Write and publish project documents

Writing rules

Use plain English inspired by ASD-STE100. We do not claim full compliance with that standard or its controlled vocabulary.

For example, replace “The adapter facilitates persistence of canonical content” with “The adapter saves the Markdown content.” Define “canonical” as “source of truth” when that distinction matters.

Where a document belongs

Use the documentation index. Keep one source for each fact and link to it elsewhere. Keep the current status near the top of plans and product documents. Separate current behavior, planned work, and historical decisions.

Do not rewrite code samples, test fixtures, quotations, generated regions, or append-only decision logs as a language cleanup. Historical reference files in docs/design/reference/ stay unchanged. Mark old guides as historical when their instructions no longer apply.

Maintain two editions

The original document stays at its existing path and remains the source of truth. Its reading copy lives at docs/simplified/<original-path>. For example:

docs/architecture/storage.md                  original
docs/simplified/docs/architecture/storage.md  simplified reading copy

This PR restores pre-PR wording in existing originals. New workflow and hosting notes remain as additions. Old agent guidance is retained with a notice that points to the current rules. Git retains the full change history.

Single-edition documents

Some documents have no simplified copy. Their HTML page reads the original. They are listed in SINGLE_EDITION in scripts/docs/catalog.mjs:

• generated or append-only files that tooling rewrites, such as docs/CHANGELOG.md;

• files edited in almost every session, such as docs/product/TODO.md;

• originals that are already plain, or not yet simplified (PH-85).

Edit a single-edition document once, in the original. Do not run docs:review for it. To simplify one later, remove it from SINGLE_EDITION, create its copy, and record the comparison. A new document is paired by default.

Update a paired document

1. Change facts and requirements in the original document first.

2. Update its simplified copy. For a new document, create the matching copy.

3. Compare both files. Preserve every requirement, exception, example, command, and status. A simplified edition is not a summary. If wording is already clear, it can stay the same in both files. Do not edit generated sections in the copy. Hashes ignore them, and the HTML build takes them from the original, so npm run docs:blocks never makes a pair stale.

4. Keep relative links and image paths relative to the original file location. The HTML builder resolves them there, so the two editions use the same links. Raw copies on GitHub are intended for comparison; use the HTML library to browse.

5. Record the comparison for the files you checked:

   npm run docs:review -- docs/architecture/storage.md
   npm run docs:check

docs:review records hashes of both files in docs/simplified/manifest.json. It does not rewrite text or prove equivalent meaning. It records that the author compared the pair. CI and HTML builds fail when either file changes without a new comparison, or a copy is missing. Do not refresh hashes just to bypass a failure.

For a deletion, remove the original, its simplified copy, and its manifest entry in the same change. Treat a rename as a deletion plus a new pair. To change only wording for readers, edit the simplified copy and compare it with the original.

The original files are authoritative, including agent instructions. Reading copies are not additional policies. Historical references and test fixtures remain outside the existing HTML catalog. PH-85 tracks the remaining detailed language review; a current hash does not mean every section has already been simplified.

Build the HTML library

npm run docs:html

The build reads the simplified copy of each paired document, and the original of each single-edition document. Each page states its edition and links to its Markdown on GitHub.

Open .docs-site/index.html in a browser. Choose a document or All documents for one HTML page you can search with the browser's Find command or print to PDF. The output uses relative links, so it also works without a web server.

npm run docs:watch

Leave this command running while you edit. It detects additions, edits, and removals, then rebuilds the library after the pair passes its freshness check. Update the copy and record the comparison, then refresh the browser. Build failures appear in the terminal; fix the error before using the output.

Shared product rendering

The build uses PageHare’s Markdown parser, section rules, and Svelte block components. The rule engine chooses header, items, Q&A, or prose for each section. A documentation guard keeps sections in the product’s prose block when a richer block would lose heading levels, links, inline code, or task checkboxes.

The library also uses the product’s reset, theme tokens, block styles, Literata font, and logo. Component CSS comes from the same Svelte source as the app. Only the library navigation and page layout have separate CSS. The output contains static HTML and CSS, with no browser JavaScript.

Use inline Markdown links. Reference-style links and footnotes are not supported by the product renderer yet; the docs build reports an error instead of dropping them. The all-documents page opens Q&A answers for searching and printing. Watch mode also rebuilds when shared block code or styles change. Restart the watcher after changing the generator or its pair-checking scripts.

Automatic updates and hosting

The app's build command does not build the document library, so a document problem never blocks an app deployment. CI checks the pairs and tests the generator. The next deployment publishes a separate static documentation site at docs.next.pagehare.com, built with npm run docs:html:public. Production (main) has no documentation site. Merge a document change into next to deploy it.

Search engines must not index the site. Every response has an X-Robots-Tag: noindex, nofollow, noarchive header, and every page has a noindex meta tag. robots.txt allows crawling, because a crawler must fetch a page to see its noindex.

The repository is private, but the site is public. The public build includes only the documents in PUBLIC_DOCS (scripts/docs/catalog.mjs) and their linked images. It has no GitHub links, and links to unpublished documents keep their text without a link. The build fails if a page contains an AWS ARN, a 12-digit account number, or an access key ID. Before you add a document to PUBLIC_DOCS, check that it has no account details, internal hosts, runbooks, or unreleased plans. Run npm run docs:html:public to preview the public site.

SST manages the certificate, DNS record, S3 bucket, and CloudFront distribution. It uses the existing Route 53 zone and GitHub deployment role. A successful local build does not prove that AWS permissions or the live domain work. After deployment, open the index, a nested guide, its image, and the all-documents page on the domain.

Do not edit .docs-site/ or commit generated HTML. Fix the Markdown or generator, then build again. The build is deterministic and uses no AI service or API key.

Check an edit

1. Compare the original and simplified text. Check each requirement and exception.

2. Verify commands, names, links, and current behavior against the source.

3. For a paired document, run npm run docs:review -- <original-path>. Then run npm run docs:check, npm run docs:test, and npm run docs:html.

4. Open the changed page and check its headings, tables, code, and links.

5. Record deferred work in TODO.