# Repository Guidance

## Sources and Scope

- Use the [project source map](reference/project-knowledge.md) to locate authoritative information and the [tutorial specification register](spec/tutorial/README.md) for design intent and dated decisions. Follow links relevant to the task; these files do not grant permissions or imply automatic context loading.

- Read `CONTRIBUTING.md` before editing tutorial content. Write project documentation in English.
- Before rewriting prose, read the editorial rules in [CONTRIBUTING.md](CONTRIBUTING.md), the [shared vocabulary](GLOSSARY.md), and the approved narrative direction in the tutorial specification. Present representative before/after passages for owner approval before a major site-wide style change; preserve chapter objectives, source identifiers, and meaningful distinctions.
- Keep `docs/` as the chapter source of truth. Astro in `site/` reads these files; do not duplicate or move them into the site.
- Preserve stable chapter IDs. Filename prefixes and `chapter_number` determine reading order.
- Keep existing user changes. Commit, push, or change GitHub settings only when requested.

## Keep Related Information Consistent

For a capability, publication, or workflow change, inspect the following files and update those affected. Do not edit every file mechanically.

- `README.md`: current status, available outputs, links, next milestone, and licensing.
- `site/README.md`: reproducible local commands, deployment, base path, and widget behavior.
- `docs/03-project-growth.md`: the history and traceability chapter with a dashboard link. `data/features.json`: capability milestones and verification evidence. Mark complete only after its criterion is verified.
- `docs/10-publishing.md` and `docs/11-beyond-github.md`: actual workflow behavior, hosted status, lab architecture, and remaining output pipelines.
- `ROADMAP.md`: remaining work and decisions; do not leave completed choices described as undecided.
- `CONTRIBUTING.md` and `LICENSE.md`: conventions, license scope, and attribution when relevant.
- Supporting assets, tables, captions, links, and source lists when their inputs change.

Distinguish chapter draft status, approval, capability completion, and successful deployment. A passing build does not establish all four.

## Website and History

- Preserve the GitHub Pages base path `/document-as-code-lab/` in navigation, Markdown links, images, and scripts. Check both local and hosted paths.
- The chapter widget uses front matter and chapter-specific Git history collected at build time. Preserve full-history checkout in workflows; it is not a live API feed.
- Fixed charts under `assets/figures/` are historical teaching snapshots. Do not silently refresh their values or source revisions.
- Growth workflow artifacts do not automatically update chapter charts. Label working-tree previews separately from committed measurements.
- The Project Control Center's growth widget uses a separate JSON report regenerated by `site/`'s `predev` and `prebuild` hooks. Keep its measurement rules shared with the Python script, preserve Python setup in the website workflows, and restart the local server after new commits to refresh the report.
- Keep `site/dist/`, `site/node_modules/`, `.astro/`, and working reports under `build/` out of commits.
- When linking a new supporting source, check its material route and the explicit source-file selection in `site/src/lib/repository.ts`.

## Verification and Publication

- From `site/`, run `npm run check` and `npm run build`. Use `ASTRO_TELEMETRY_DISABLED=1` when sandboxed execution requires it.
- Run `.venv/bin/python -m unittest discover -s tests` from the root when changing measurement or processing behavior.
- Run `node scripts/test-budget.mjs` from `site/` when validating the website. For the optional PDF proof, follow `publishing/pdf/README.md`, run its focused tests, and inspect rendered pages. Record whether Mermaid CLI or a prepared SVG was used; do not claim the full PDF pipeline is verified from the prepared-SVG path alone.
- For milestone changes, regenerate `scripts/measure_growth.py` reports with the appropriate Python environment; use `--include-working-tree` before committing.
- Check `git diff --check`, changed-file scope, internal links, and representative images and diagrams. Verify one title and one widget per chapter when changing their rendering.
- If Markdown rendering configuration changes but old HTML persists locally, use `npm exec astro sync -- --force` for development. `npm run build` already uses `astro build --force` so cached Markdown does not hide renderer changes in production.
- Before an authorized push, synchronize with the remote without discarding changes. After publication, verify the deployment run and affected live pages. Report the exact commit and distinguish local checks from hosted verification.
- Search affected documentation for stale claims such as "deployment not configured", "pending publication", or "no license selected". Preserve genuinely historical explanations.