# Authoring system documentation

## Start with the topic register

Follow the repository's AGENTS.md and docs/MAP.md. Read COVERAGE.yaml and NEXT.md,
then the published editorial references:

- src/content/docs/editorial/structure.md: page boundaries, article types and links.
- src/content/docs/editorial/style.md: factual language based on Microsoft Learn.
- src/content/docs/editorial/review-status.md: source authority and review status.

COVERAGE.yaml owns the area and topic register. Each topic has a stable ID, reader
question, article type, current page/anchor, related topics and detailed-work status.
Topic summaries live in the published Markdown, not in a second prose catalogue.
The topic-map page and navigation are generated from the register.

## Work within a declared scope

Check current main, issues/PRs and worktrees. Use the task's existing branch while
its PR remains open; never continue a merged branch. Select the topic IDs named
in NEXT.md. Inspect their owning contracts, relevant code, active migrations and
tests before making implementation claims. Documentation work alone does not
require live accounts, provider calls or application test data.

For the user-authorized four-pass completion, use the complete pass in NEXT.md
and editorial/roadmap.md. Every assigned topic needs its own reviewed answer; do
not substitute summary relabeling or stop after the first article. The verifier
checks the preserved 16/19/14/16 partition. All four passes are now complete;
NEXT.md defines maintenance rather than a fifth writing pass. Preserve all 85
reviewed owners and update affected answers when implementation or authority changes.

Otherwise write one coherent article or a small related set. Complete the scope, update the
register and replace NEXT.md with another self-contained assignment. Include its
reader questions, starting sources, risks, acceptance criteria and verification
commands. Preserve unrelated areas and their source references.

## Structure articles for the reader

Use the template for the article type: overview, concept, procedure, reference or
troubleshooting. templates/section.md is a completeness checklist for a whole area,
not a required heading list for every article. Use Markdown; use MDX when a local
component is necessary. Explain actual behaviour before discussing evidence or
remaining work. Keep review metadata in the page's source details.

Use Diagram.astro with its chart and caption properties. Static verification
rejects an empty diagram source, caption or accessible name; browser checks must
also establish that Mermaid rendered real diagram nodes.

Each page requires documentation.kind, readerQuestion, status, scope, codeReference
and sources in its frontmatter. Use a full reviewed commit and existing repository-
relative file paths. The site links sources at that revision and verification
checks that those files exist in Git. Set a coverage area's reviewed_source when
its starting sources differ from the initial register baseline.

Overview-reviewed means the declared overview or summary has been source-reviewed.
It does not mark the detailed topic complete. Use topic detailStatus planned,
draft or reviewed to track that separate work. Section-reviewed articles must
meet their specific detailed acceptance criteria. Implemented, merged, deployed
and scenario-verified product states remain separate from all writing statuses.

## Preserve topic ownership and addresses

Add pages to their area's pages list; navigation derives from that list. New
editorial pages belong in editorialPages. Each page needs a content link from a
parent or another relevant page, not only a sidebar entry. Keep one owning
explanation per subject and link at the first relevant mention.

A topic's canonical address currently identifies a real page and section. Preserve
old summary anchors when moving detail into a new article. Update the canonical
page/anchor and cross-links in the register. An empty anchor identifies the page
itself. Related-topic IDs must resolve to actual registered topics. Do not publish
links to unwritten routes. Use meaningful labels and avoid repetitive linking.

Existing topic contracts and CONTEXT.md retain their authority. Explain them and
link their sources rather than copying operational rules into competing documents.
Resolve clear contradictions in the owning source; record uncertain ones as gaps.
Inspecting test code is not executing it. Cite existing receipts only within their
named scenario and version.

## Build selection and distribution

Only src/content/docs/ is loaded as pages. The fixed resourceFiles list in
scripts/common.mjs selects authoring files and templates copied into the bundle.
Do not import archives, evidence folders, environment files, fixtures or screenshots.
Keep credentials, personal data and live payloads out of examples and artifacts.
The site uses local assets, bundled Mermaid and static search without analytics or
remote rendering services.

The owner authorized public hosting at https://docs.toolora.se/. HOSTING.md
owns its static publication and rollback procedure. New destinations or audiences
need their own agreement. Delivery includes a PR and static archive. GitHub source links require
separate network and repository access. The extracted archive itself needs only
a local HTTP server; its README.txt gives Python 3 commands. Individual pages can
be printed. A combined PDF edition is a separate deliverable.

## Verify the result

Use Node.js 24. From this directory run:

```bash
npm ci
npm run verify
npx playwright install chromium
npm run test:browser
```

Verification checks source references, types, page/anchor addresses, topic
relationships, content reachability, internal links and local assets. The browser
check follows search and cross-links, tests diagrams, themes, mobile navigation
and print, and rejects external runtime requests.

From the repository root run make ci-plan BASE=origin/main and its selected shared
targets. Current CI treats docs/ as documentation and runs security/result checks;
record the local handbook checks in the PR rather than claiming CI built it.

Commit a clean candidate, then run npm run verify, npm run test:browser and npm run
package. Packaging checks the build revision and clean state, performs an archive
round-trip and writes a versioned ZIP with build metadata and SHA-256 manifests.
Extract and browser-check the archive when distribution behaviour changes. Keep
builds, ZIPs and browser artifacts ignored. Record the checked SHA, actual results
and concrete limits in the PR.
