# Documentation Site Astro reading site for the tutorial, with strict TypeScript configuration and npm. The content collection reads chapters directly from `../docs/` and sorts them by `chapter_number`. Edit the original Markdown files to update the site. Routes use the chapter filenames, while existing stable content IDs remain unchanged in the sources. The home page introduces the information-focused approach, groups all chapters into four learning paths, and links to working demonstrations and three complementary presentation packs. Chapter numbers, titles, goals, and URLs come from the existing content collection; only group descriptions and ranges are homepage configuration. It reuses `Documentation.astro` with an optional wide layout; chapter layouts are unchanged. Homepage styling is in `src/styles/home.css`. Its local editorial illustration has provenance in `assets/illustrations/README.md`; it is not a technical diagram. Chapter pages include previous/next links, rendered images, and Mermaid diagrams. Linked Markdown examples, reference notes, and the glossary have reading pages under `/materials/`. Supporting files and original sources are available under `/files/` from an explicit selection of project folders. The Project Control Center is available at `/document-as-code-lab/dashboard/`, linked from the chapter menu. By default it reads `public/data/project-operations.json`, an ignored, versioned snapshot of public GitHub issues, pull requests, main commits, and the latest run of each workflow. Configuration is in `src/lib/dashboard/config.ts`; presentation styles are in `src/styles/dashboard.css`. Collection follows pagination links (with a 20-page safety budget); exceeding that budget reports unavailable data rather than an incomplete total. Lists show up to ten matches, while the workflow list shows every retrieved workflow. Activity is a limited feed of the retrieved items. The Pages workflow generates the snapshot using its read-only `GITHUB_TOKEN` during the build, then publishes the JSON with the site. Deployments run after pushes to main, manually, and hourly at minute 17. Scheduled runs and CDN updates may be delayed. Snapshot generation time, source revision, and per-source retrieval times are visible. Workflow states describe collection time, so the deploying workflow itself may still be running. There are no data commits or updates to chapter Markdown. GitHub may disable scheduled workflows in inactive public repositories; check Actions if updates stop. Opening the dashboard, Refresh snapshot, and five-minute visible-tab refreshes read only the published JSON. Fetch live data explicitly calls the anonymous GitHub API once; it does not start API polling. Each source retains its last successful in-memory result on failure. The browser never receives a token. Refresh snapshot also reloads growth measurements. Without `GITHUB_TOKEN`, local builds reuse an existing snapshot or create an explicitly unavailable placeholder without contacting GitHub. To reproduce collection locally, provide a suitably scoped token through the environment and run `node scripts/operational-snapshot.mjs`; never put credentials into source files or public assets. The growth hook also generates ignored `public/data/project-metrics.json`, schema version 1, using the existing Python measurement rules. It includes generation time, the measured source revision and its commit time, and committed history. The browser fetches this file with `cache: no-store`, labels it Measured snapshot, and compares it with the retrieved main commit. New measurements become available after a site deployment; they do not update from live API calls. A future independent dataset publisher would need to serve JSON at a public URL with the same schema. Actions artifacts alone are not that public endpoint. Chapter 3 discusses history and provenance and links to the standalone dashboard instead of embedding a second growth widget. Dashboard verification: `npm run test:dashboard` checks API normalization, pagination, failures, workflow states, generated schema, provenance, and subpath fetching. It also runs in the Astro pull-request workflow. For browser failure testing of the production build, `node scripts/dashboard-test-server.mjs` serves an isolated test harness on port 4327 with network fault controls; those controls are never included in the deployed build. HTML slide decks are listed under `/presentations/`. YAML in `../presentations/` selects messages and links to the maintained chapters. Four Astro slide components render that content; Reveal.js provides presentation behavior within the same build and deployment. The concept/mechanics and benefits/adoption packs each contain ten slides. Their optional `notes` fields generate static `/presentations//notes/` pages linked from the toolbar, index, and homepage; no new slide framework or presenter-window dependency is introduced. See the [presentation authoring notes](../presentations/README.md) for the format and verification steps. The dedicated theme is `src/styles/presentations.css`. After a build, run `npm run test:homepage` for learning-group coverage, pack/notes structure, and retained navigation, alongside the existing content and lesson tests. The dashboard reference guide's `` marker mounts `BudgetTable.astro`. It bundles the official `@rhpaiva/cssv` 0.5.0 renderer (MIT) and reads `examples/dashboards/department-budget.cssv` at build time. The file supplies data and table CSS; `src/styles/budget-table.css` styles the surrounding controls. Our component adds sorting, filtering, and totals, not cell editing or formula evaluation. Only reviewed repository content is loaded. The Markdown table remains as a no-JavaScript/error fallback; keep its values synchronized with the example file. No third-party CDN is required. Chapters 5, 6, and 8 add optional in-context scenario checks from `examples/learning/scenario-checks.json`, validated against its JSON Schema at build time. `ScenarioCheck.astro` shares quiz configuration checks but has no score, tracking, persistence, or network calls. Answers appear after Check answer, with a hint and retry; without JavaScript, a collapsed explanation remains readable. Explicit `scenario-check-metadata`, `scenario-check-traceability`, and `scenario-check-agent-knowledge` markers place the checks near their concepts. Style these, source notes, and reference invitations through `src/styles/chapter-learning.css`. Run `npm run test:scenarios` after building. Chapter 9 adds an **Explore change impact** action that selects the existing amendment and impact tab, with the same records and traversal as free exploration. No separate guided dataset is maintained. The [tutorial specification register](../spec/tutorial/README.md) describes the four curriculum groups (1–4, 5–7, 8–9, 10–11) and owner-review gates. It is available under `/materials/spec/tutorial/README/`, outside chapter numbering. The [project source map](../reference/project-knowledge.md) links authoritative information homes rather than duplicating their rules. All 11 chapters add quizzes from `../examples/learning/questions.json`, mapped to the existing Quiz API. Chapter 4 adds its Markdown playground at the chapter's practice marker. These are website-only enhancements: the chapter stays in `docs/04-markdown.md`, with no MDX conversion or duplicated chapter. `src/components/learning/ChapterLearning.astro` selects the practice content and positions the tools; reusable components are in the same folder. Style them through `src/styles/learning.css`. The initial components were adapted from the supplied `document-as-code-learning.zip`. The chapter rewrite package supplies the current quiz questions. Marker names (`onboarding-lab`, `markdown-playground`, `metadata-lab`, `processing-lab`, `chapter-quiz`) mount components without MDX; the renderer creates hosts and `ChapterLearning.astro` moves the corresponding components into them. The playground uses bundled `markdown-it` with raw HTML and images disabled, and rejects unsafe link schemes. It does not send input to a server, load learner-entered images, or save edits. Chapter 5 reuses this editor with a practice copy of Contacts and `examples/learning/procedure.schema.json`. The bundled `yaml` parser reads the frontmatter; Ajv validates it against that JSON Schema only when Validate metadata is selected. Editing marks the previous check as out of date. The prose preview excludes frontmatter, and malformed or duplicate YAML fields produce errors. The check covers required fields, types, identifier format, allowed statuses, and extra fields, not human approval, prose accuracy, relationships, or cross-file ID uniqueness. Reset restores and checks the initial example. The source, preview, schema, and initial check remain readable without JavaScript. Quiz questions are rendered as accessible fieldsets; single-choice, multiple-choice, and true/false types are supported. Answers are included in the public page, so this is a practice aid, not a secure examination. Responses are not persisted or tracked. `Quiz.astro` requires a unique `id` per instance. Run `npm run test:learning` after building to check scoring, configuration validation, Markdown safety, YAML parsing, schema validation, and lesson mounting; also inspect editing, reset, feedback, and mobile layout in a browser. From the repository root: The growth widget also needs Python and the repository's measurement dependencies. Set up `.venv` and install `requirements.txt` as described in the [measurement reference](../reference/growth-measurement.md#prepare-a-local-environment). The npm pre-dev and pre-build hooks use that environment when available, otherwise `python3`; set `PYTHON` to override the executable. Full Git history is required. ```bash cd site npm ci npm run dev ``` Check and build: ```bash npm run check npm run build npm run test:learning npm run test:content npm run test:homepage node scripts/test-budget.mjs ``` Astro requires Node 22.12 or newer. This project includes Node 22 as a local development dependency, so npm scripts use a compatible runtime even when the system Node version is older. No global Node installation is changed. Pull requests against `main` run `.github/workflows/astro-pr-check.yml`, which installs dependencies with `npm ci`, checks types, and builds the site. Pushes to `main` run `.github/workflows/deploy-pages.yml`, which builds and publishes to [GitHub Pages](https://and-gu.github.io/document-as-code-lab/). Required review and build checks must be configured separately in GitHub's branch rules. The configured base path is `/document-as-code-lab/`, including for local development. Build output is written to `dist/` and is not committed. The chapter information widget reads metadata from the sources and chapter-specific history from Git at build time; CI checks out full history for this purpose. Its appearance is controlled by `src/styles/chapter-information.css`. The standalone dashboard provides the interactive growth view; chapter 3 links to it. The earlier `` component remains available for reuse but is no longer mounted in chapter 3. `scripts/growth-report.mjs` runs the existing Python measurement with `--json-only` before development and production builds. The report stays under ignored `build/site-growth/`; only committed revisions are included. Restart the dev server after a new commit to regenerate it. `ProjectGrowth.astro` renders the Chart.js view, with CSS in `src/styles/project-growth.css`. Saved historical charts remain under `assets/figures/` and are not rewritten by this change. Example passages can be enclosed by standalone `` and `` comments, with blank lines around each marker. Use a matching descriptive identifier for each pair; nesting is not supported. These comments are invisible in GitHub's Markdown preview. Astro wraps the content in `.tutorial-example[data-example="onboarding"]`, styled by `src/styles/tutorial-examples.css`. Set `--example-accent` and `--example-background` there to change the colors, or use the data attribute to target one example. Keep a visible example heading in the Markdown so its meaning does not depend on color. Renumbered chapter URLs have static redirects configured in `astro.config.mjs`. These preserve existing website links while Markdown filenames and navigation follow the new reading order. Chapters 5–7 separate metadata, information architecture, and processing; optional processing experiments are in `reference/record-processing.md`. `OnboardingLab.astro` reads the fixed procedure sources at build time. For chapter 1 it delegates to `ProcedureSelectionLab.astro`: readers compare approved-only selection with including drafts for review. Sources stay fixed. Excluding draft Contacts leaves the intended three-part handbook incomplete; allowing Contacts permits only a review copy. This is an inclusion preview, not handbook generation or approval. Chapter 5 uses the schema-enabled Markdown editor described above instead of this component. Chapter 7's `ProcessingPlayground.astro` reuses that editor for Contacts, while Access and Equipment remain fixed. Its explicit build validates against the procedure schema, checks unique IDs and nonempty text, and generates a rendered handbook review copy and a draft-procedure review queue. The handbook combines all three procedures, including drafts; the queue selects only drafts. Editing or resetting the source leaves outputs unchanged until a successful build. A failed build preserves the last successful result; the previous successful output is retained separately. Chapter 7 focuses on procedure information and does not mount the employee-readiness simulation. All simulations are browser-only, without persistence or API calls. They do not invoke Python, edit repository files, approve procedures, or publish a handbook. Sources and initial results remain readable without JavaScript. Run `npm run test:learning` after a build to check validation, processing, inclusion rules, and lesson mounts. The record-processing reference retains the runnable requirement examples used by later AI and diagram exercises. The 11-chapter reading order covers information architecture at chapter 6 and workflow automation at chapter 10 and lab architecture at chapter 11. Old chapter URLs redirect directly to their current chapter or the relevant reference guide. The CSSV widget is mounted by the materials route, not a chapter-specific filename. Detailed AI, visual, review, dashboard, publishing, portability, and automation exercises remain under `reference/`. New conceptual exercises use worked text, diagrams, and quizzes where there is no implemented interactive simulator; they do not expose inactive controls or pretend to call live AI or external systems. Run `npm run test:content` after a build to verify chapter IDs, diagram sources, routes, links, and assets. ### Architecture Explorer Workflow source links open the maintained files on GitHub. The Pages artifact upload excludes `.github`, so links under `/files/.github/` would return 404 even when the local build contains those files. The content tests reject these unavailable Pages paths. The production build uses `astro build --force` to regenerate cached Markdown as well as components. A change to a rendering plugin must reach every chapter even when its Markdown source is unchanged; restoring an older content cache must not preserve obsolete URLs. Chapter 11 adds a read-only Architecture Explorer through the `architecture-explorer` marker. Its five curated paths in `src/lib/architecture.ts` are checked at build time against existing files and the public source-file selection in `repositoryFiles()`. Only selected implementation files are exposed, not the entire site directory. `ArchitectureExplorer.astro` supplies a static table; `architecture-controller.ts` adds tabs with arrow, Home, and End navigation. Style it in `src/styles/architecture-explorer.css`. The architecture component never requests APIs, saves data, or starts workflows. Its PDF path leads to workflow artifacts, not a public book. Its dashboard path distinguishes published snapshots from optional live retrieval. The nine-slide `lab-architecture` deck and notes use the existing presentation pipeline and Pages deployment. Chapters 10 and 11 remain in review. Content, learning, and homepage tests cover source links, quiz mapping, the explorer, and deck structure. ### Contract Explorer Chapter 9 uses the `contract-explorer` marker and `ContractExplorer.astro`, registered through the existing chapter learning mechanism. Nine Markdown records under `examples/contract-explorer/records/` are authoritative. `contract-loader.ts` reads them at build time, validates them against `schema.json` with Ajv, and checks IDs, relation endpoints, references, dates, and cycles. Invalid inputs stop the build. No copied UI dataset or hand-authored graph edges are maintained. `contract-model.ts` derives immediate links, delivery coverage via projects, and traversal-based review candidates. `contract-controller.ts` progressively enhances the static tables and source list with three keyboard-operable views. The graph shows recorded links only; the impact list separately labels derived candidates and their recorded paths. On narrow screens the relationship table replaces the graph. Without JavaScript the record list, source links, commitments, and initial impact paths stay readable. Styles are in `src/styles/contract-explorer.css`. Each source link serves the original maintained Markdown bytes through the existing `/files/` mechanism, not the transformed snapshot. Details also provide the GitHub repository path, source commit when available, SHA-256 digest, and an explicit uncommitted label for new or edited sources. New GitHub paths become available only after publication. The snapshot is embedded during the Astro build; no API, backend, browser persistence, or AI service is used. Run `npm run build` then `npm run test:contracts` to verify transformations, validation failures, source-edit effects, source byte identity, static fallback, and URL prefixes.