Documentation policy and decisions

This repository owns public learning and usage documentation for Assembly Engine. It follows Diátaxis: tutorials, how-to guides, reference, and explanation. Audience pages route readers to those sections rather than creating a fifth content type.

Canonical sources

Material	Owner and authoring source
Public articles, navigation, worked examples	assembly-docs, this repository
Internal architecture and settled requirements	Engine architecture
Product architecture decisions	Engine ADRs
Exact schemas, grammar, protocol, finding codes	Engine contracts
Executable contract examples	Engine conformance fixtures
Internal engineering standards and workflow	Engine engineering docs
Studio behavior and internal documentation	Assembly Studio

The engine and Studio repositories currently require organization access. These source links are contributor entry points and may be unavailable to public readers. Completed public reference articles must explain the behavior users need and link public release artifacts when available, while keeping the canonical specification in its owning repository.

These branch links are authoring entry points, not release citations. Completed articles must name their engine version and cite a tag or immutable commit for exact behavior. The initial inventory was checked against engine commit 3192020b, but its examples have not been exercised as public tutorials. No release is certified by this scaffold.

Public prose MUST NOT redefine a normative engine contract. When code, contracts, and an article disagree, the discrepancy MUST be reported and resolved in the owning repository. Public docs MAY explain or summarize contracts and MUST link their canonical version. Internal specifications are not relocated or copied wholesale into this repository.

Stub policy

Label	Meaning
Draft stub	Article unfinished; feature availability has not been verified for a release
Proposed	A concrete maintained extension, library, or integration is needed for the topic
Future	The capability is explicitly deferred or unresolved in the architecture

Every stub MUST state its scope or intended outcome and the evidence required to complete it. Proposed and future pages MUST identify what is missing. An article becoming complete MUST be reviewed for its examples, version applicability, source agreement, and visible limitations. No stub implies a release date, product commitment, or approval to apply to a live world.

Site and publishing

The site uses Astro Starlight. Content lives in src/content/docs/, with sidebar groups configured in astro.config.mjs. The public website is docs.assemblyengine.org. The source repository is public in Gitea. Infrastructure and the publishing procedure belong to the infrastructure repository; building the site or pushing source does not deploy it.

Decision ledger

Date	Decision	Reason and canonical record
2026-10-28	Put public documentation in assembly/assembly-docs; keep engine specifications beside the engine	Public reader needs differ from internal contract and architecture maintenance. ADR 0015 records the repository boundary.
2026-10-28	Use Diátaxis and keep unfinished topics visible as labeled stubs	Separate learning, tasks, lookup, and understanding while making missing coverage explicit.
2026-10-28	Build the site with Starlight	Provide documentation navigation, search, and static output with Markdown content.
2026-10-28	Publish at docs.assemblyengine.org	Serve Starlight’s static output through the existing edge Caddy service. Keep deployment configuration in the infrastructure repository.
2026-10-28	Adopt Fieldnotes and the approved seven-example Mermaid treatment	Share Paper and Charcoal tokens and local fonts. Use square ink geometry, hatched extensions, inverse kernel blocks, rust focus, and annotation rails. Keep the shared renderer and diagram conventions in this repository; retain the Diátaxis inventory and explicit stub labels.