S9 — Release (design note)

Status: Done (D-116) · Date: 2026-10-03 · Roadmap: S9 · Decisions: D-056, D-058, D-063, D-064, D-111, D-115, D-116

Run as D-111 sets out: two builds in parallel worktrees (R needs Rhino, W does not), each reviewed by a second agent before it is merged; scripts/verify.ps1 and mkdocs build --strict before each merge; the rhino-smoke specs once on the merge candidate; a fresh clone of the tag; one decision-log entry. Version 1.0.0, tag v1.0.0; pushing waits for the owner.

Layout (shared contract of the two builds)

Path	Owner	Content
mkdocs.yml	W	Site config and the whole navigation; theme Material for MkDocs
docs-site/index.md	W	Landing page: what BEMGen is, the two parts of the site
docs-site/user/	W	getting-started.md (install, the Yak package, first run), concepts.md (definitions: plan, zone, program preset, space type, envelope, simplifier, floor aggregator, multiplier, building, validation, provenance, levels of detail), workflow.md (the workflow guide), example-end-to-end.md (one full example), typologies.md (the 18 families with their generator, defaults, and example definition)
docs-site/user/components/	R	Generated: index.md and one page per panel, every component with icon, nickname, GUID, description, inputs and outputs (name, nickname, type, access, optional, default, description), and its screenshot
docs-site/assets/icons/, docs-site/assets/screenshots/	R	Copied icons (by script from src/Lod.Grasshopper/Icons/), captured screenshots
docs-site/developer/index.md	W	Developer landing page; the other developer pages are assembled at build time from docs/ (architecture, ADRs, decision log, plans) into a staging folder, never committed as copies
scripts/docs-site/	R and W	R: component_reference.py (renders the generated pages from a metadata dump), the Rhino spec that dumps the metadata and captures screenshots; W: build.ps1 and serve.ps1 (assemble, mkdocs build --strict, mkdocs serve on localhost), requirements.txt (pinned MkDocs packages), README
examples/	R	One .gh per typology and end-to-end.gh, built and saved by the harness, plus a README
.claude/skills/sync-docs/SKILL.md	W	The sync-docs skill
scripts/package-yak.ps1, packaging/yak/	W	Local Yak build (manifest from Directory.Build.props), never published
LICENSE	W	MIT, Environmental Systems Lab

Generated output (site/, staging folders, the metadata dump) is git-ignored. Screenshots and icons are committed (small PNGs).

Build R — reference, examples, screenshots (needs Rhino)

1. A rhino-smoke spec that dumps every BEMGen component's metadata (panel, name, nickname, GUID, description, exposure, inputs and outputs with their types, access, optional flag, defaults, descriptions) to JSON outside the repository; component_reference.py renders the component pages from it and copies the icons. Re-running both is how the reference is updated (used by sync-docs).
2. The example definitions: for each typology a definition presets → generator → simplifier → aggregator → Convert2BEM (and Convert2IDF with Write off), laid out readably with groups and short scribbles, saved as .gh; end-to-end.gh for the walkthrough of example-end-to-end.md. Each is reopened headless and must solve without errors.
3. Screenshots, captured by script: the viewport previews of each typology's plan and building, and the canvas of each example. If the canvas cannot be captured headless, report it; the controller then asks the owner for screen control.

Build W — site, skill, package, license

1. MkDocs site (Material theme, pinned requirements), the user part (the pages above, written for a new user; the workflow guide covers presets → generator → simplifier → aggregator → validation → Convert2BEM / Convert2IDF, Preview Location, Transform Plan, storeys, the any-program preset, the heat-transfer options), the end-to-end example (the linear plan through Perimeter Core and Stack to Convert2BEM and Convert2IDF, with every input value and the expected outputs), the developer part assembled at build time, and clear separation of the two (navigation, landing pages, styling).
2. sync-docs skill: compares the generated component reference with the current plugin (via the metadata spec, or by reading the component sources when Rhino is not available), checks user pages against component names, inputs, and defaults, checks the developer docs against the decision log and ADR statuses, and writes a plan of the edits needed; it never edits on its own unless asked.
3. Yak package script and manifest, LICENSE, version 1.0.0 in Directory.Build.props at close-out.

Acceptance criteria

• mkdocs build --strict passes; serve.ps1 serves the site on localhost; every component appears in the reference with its icon; the workflow guide and the end-to-end example match the examples and the code.
• Every example opens and solves headless without errors; the rhino-smoke specs pass.
• The Yak package builds locally with version 1.0.0; nothing is published.
• sync-docs run on the final tree reports the docs up to date.
• scripts/verify.ps1 passes; a fresh clone of v1.0.0 passes it.