[avsolatorio]

This pull request adds a Training section to the docs site at /training/. The section is generated from the training/ folder at every site build, and the folder stays the source. It also adds an authoring guide for later sessions, and the generator checks a session folder against that guide.

What the section contains

• Index. The series README is the index page, without the folder layout, review, and contributor sections. Its table lists session 01 and the five planned sessions by title, without dates.
• Session 01. The session appears in the sidebar as "01 · Building AI applications for research and data", with these pages:
  • The session README as the overview, without the Roles and Definition of ready sections.
  • A preface, "How AI chatbots work". It explains the problem that the session addresses and the readers for whom it matters. It then sets out the three ideas of the session (grounding, tracing failures to components, and separating writing from checking), notes on running the notebooks, and a short description of each notebook.
  • A Slides page with the deck in Canva's embedded viewer and an Open in Canva button. The link is in slides/canva.json.
  • The seven notebooks as pages with their committed outputs. Each page has an Open in Colab button and a link to the notebook on GitHub.
  • Participant resources: the participant guide, glossary, testing on fixed questions, and next steps. The next steps page names the planned sessions that continue topics of session 01.
  • A Document collection page with the eight worked-example documents, their roles, metadata, and chunks, each chunk labelled with its citation. A document can be linked to by its id in the URL hash.
  • The worked-example data page.

How it is built

• scripts/docs/build_training_site.py writes the pages into website/generated/training/, which is gitignored. npm run convert-notebooks runs it, so the GitHub Pages workflow picks it up without changes.
• A training docs instance serves the folder with an autogenerated sidebar. The navbar has a Training item, and site search covers the section.
• Every Markdown file in a session's resources/ becomes a page. The pages follow the order of the links in resources/README.md, and a file's name is its page's URL.
• The Document collection page is built for any session whose assets/documents/ has a roles.json. The page uses a DocumentViewer React component that follows the site theme.
• Relative links resolve to the generated pages when the target is on the site and to GitHub otherwise. Colab section links (#scrollTo=section-N) become heading anchors, including links between notebooks.
• Inline scripts are removed from notebook outputs. A client module fills the detail panel of verified chat answers on hover, as the script does in Jupyter.
• Output styles are collected into one generated stylesheet. The site's HTML minifier rewrites inline style text, and the mismatch broke React hydration on notebook 06.

Authoring guide and checks

• training/AUTHORING.md describes the folder layout, file names, and title formats of a session and the page that each file becomes. It also covers the formats of canva.json and roles.json, the writing rules for prefaces and notebooks, and a checklist before a pull request. The "Adding a session" section of the series README links to it.
• The generator prints a warning for each convention that a session folder breaks: README and notebook titles, notebook file names, section cells without a heading, #scrollTo links to missing cells, Colab links to missing files, pages without a title, a Canva link that is not a public view link, and documents missing from roles.json or missing required front matter. --strict turns the warnings into an error. Session 01 passes with no warnings, and a test folder with fifteen planted problems produced fifteen warnings.

Redirects and published routes

• website/published-routes.txt lists every page route the site has published. It was seeded from a build of main, which is the live site, and extended with the routes of this branch.
• website/redirects.json maps old routes to new ones. A plugin, website/plugins/published-routes.mjs, writes a redirect page at each old route after the build. The redirect keeps the query string and the #anchor.
• The same plugin fails the build when a published route has neither a page nor a redirect, or when a redirect points to a route that is not a page. A new route that is missing from published-routes.txt is a warning locally and an error in CI. npm run routes:update adds the routes of the last build.
• The "Publish to GitHub Pages" workflow now also runs on pull requests, where it builds the site without deploying, so a missing redirect fails the pull request before it reaches main.
• The process is described in website/README.md, under "Changing or removing a page", and the training authoring guide refers to it.
• Tested: without the redirect entry, the build fails and names /training/session-01/documents.html. With it, the old address opens the Document collection page on a static server, and the #coffee anchor selects the same document.

Source changes

• The notebook titles in the README tables of the series and of session 01 link to the notebook files. GitHub renders those files, and the site rewrites the links to the notebook pages.
• resources/evaluation-examples.md is renamed testing-on-fixed-questions.md to match its title and page URL.
• The document roles of session 01 moved from build_training_pages.py to assets/documents/roles.json.
• The standalone documents.html page is removed. The Document collection page replaces it, and the old address redirects there.

Checks

• npm run build passes with no broken links and no broken anchors in the section. The only anchor warnings are the existing ones for the Hub items in the navbar.
• The pages were checked in a browser in light and dark themes. The chat answers, tables, and animated explainers render, notebook 06 hydrates without errors, the verification detail panel fills on hover, the Canva viewer loads, and the Document collection page has no horizontal scroll at phone width.
• scripts/docs/check_cookbooks.py reports no errors.