Site Index Source Policy

site/index.md is generated output from checked-in site owner inputs.

Generated Output Policy

  • Generated output: site/index.md
  • Generator action: npm run objc3c -- build-site
  • Drift-check action: npm run objc3c -- check-site
  • Manual edits are unsupported.
  • CI must fail when generated output drifts from canonical inputs.

Canonical Inputs

Generation input ownership is deterministic and ordered:

  1. site/src/index.contract.json defines the generator contract (site/src/index.body.md, output path, and front matter).
  2. site/src/index.body.md is the public-facing owner input for the generated site.
  3. The site is a curated overview of the specification and current implementation status; it is not a stitched mirror of spec/*.md.
  4. README.md inputs are excluded from generated output.
  5. Site source files may mark machine-facing appendices with <!-- SITE:EXCLUDE-START --> / <!-- SITE:EXCLUDE-END -->; those blocks are omitted from generated output.

Ownership

  • Public site content owner: site/src/index.body.md.
  • Render behavior and policy-check owners: site/src/index.contract.json plus the site builder implementation.
  • Generated bytes owner path: re-run generator and commit updated site/index.md.
  • Command support boundary: the package.json objc3c script plus scripts/objc3c_workflow/action_catalog.py; public examples use npm run objc3c -- <action>.
  • Capability support boundary: docs/support/capability_matrix.md, docs/support/capability_matrix.json, docs/support/evidence_map.md, and docs/support/capability_claim_responsibility.md, with registry-owned schemas from scripts/objc3c_shared/schema_registry.py and artifact publication records from native/objc3c/src/artifacts/json/capability_support_schema_records.cpp.

Tone and Accessibility Rules

Public site content must optimize for first-read comprehension:

  • lead with current status before implementation direction,
  • use plain language before implementation jargon,
  • define specialist terms by context instead of assuming prior repo knowledge,
  • prefer short lists and comparison tables over dense paragraphs,
  • give readers a direct next link when a section names a deeper path,
  • keep generated artifact paths and evidence inventories out of the public overview unless they are the point of the section.

Non-goals for the public site:

  • historical closeout narration,
  • machine-facing packet inventories,
  • unexplained abbreviations or internal shorthand,
  • treating the site as a mirror of the archived spec/ corpus.
  • advertising retired package-script names or implementation helper commands as public workflows.

Drift Policy

If site/index.md changes without matching owner-input changes, treat it as drift:

  1. Re-run npm run objc3c -- build-site.
  2. Review resulting diff against intended source edits under site/src/.
  3. Commit generated output after owner inputs are correct.