Documentation and gates¶

The public site uses MkDocs Material and the Diátaxis page types: tutorial, how-to, reference, and explanation. Each curated page declares its type, audience, lifecycle, authorities, source dependencies, media IDs, and verification date in YAML front matter.

Choose the owning audience before writing¶

docs/user-guide/ explains how a person installs, operates, understands, and evaluates the product.
docs/developer-guide/ is for developers reading the code. It owns architecture, code tracing, debugging rationale, implementation workflows, and technical reference.
docs/agent-guide/ is for coding agents. It owns imperative repository protocol, scope control, platform/skill routing, evidence rules, and handoff.

Do not publish the same technical explanation in both the developer and agent guides. Put it in the developer guide; link to it from the agent page and add only the operational instruction the agent needs. Likewise, branch and checkpoint protocol does not belong in the codebase tour. The docs gate checks folder/audience ownership; review still checks that the prose actually serves its declared reader.

Install the pinned toolchain¶

uv venv .docs-venv
uv pip install --python .docs-venv/bin/python -r docs/requirements.txt

Author and preview¶

scripts/docs-serve

Use Mermaid for source-controlled diagrams and provide a text equivalent immediately after each diagram. Screenshot slots are listed in docs/assets/screenshots/manifest.yaml; regenerate deterministic stubs with tools/docs-placeholders and replace them in place with the same final dimensions.

Bind documentation to release features¶

docs/feature-catalog.yaml declares the active release profile, stable feature IDs, planned runtime flag keys, and the NOW Extension capability inventory. Add feature_ids to bind a curated page to that authority. Included alpha features are the default and render no availability banner; optional or excluded features render a notice. Use | Product area | Alpha state | Runtime binding | Notes | |---|---|---|---| | PowerPC Carbon guest | **Included** | intrinsic | Primary classic guest and the supported alpha path. | | NOW Extension | **Optional** | capability-negotiated | Bundled with the alpha; install it only for the resident-backed features listed below. | | Pre-Carbon support (NOW-68K) | **Excluded** | Plannedclassic.pre-carbonflag; not implemented | The current NOW-68K build is stale and excluded from the alpha. | or `### Application features

Feature	Without the Extension	Extension required?	Current status
Set up a PowerPC Mac from the host	Available; the Extension is an optional package selection.	No	Tested locally and mounted in Mac OS 9.1 QEMU; classic-browser download and first hardware connection remain unverified.
Capture or stream the classic Mac screen	Available.	No	Current; streaming and large transfers have documented limits.
Browse, transfer, and manage files	Available.	No	Current; resume and large transfers have documented limits.
Use iCloud Drive, Photos, and Contacts	Available.	No	Experimental; each macOS service requires an explicit grant.
Inspect and manage running applications	Available.	No	Current; state-changing requests settle through typed results.
Open Mirror and inspect its application-level shell	Basic shell only.	No	Experimental; interactive requests take priority over queued background refreshes, but the hardware latency target is not yet verified.
Run classic-side console commands	Available.	No	Current; the connected guest advertises its own command set.
Chat through a model configured on the modern Mac	Available.	No	Experimental; provider credentials remain on the modern Mac.
Translate modern web pages for classic browsers	Available from the host Direct listener.	No	Experimental; deterministic rendering is tested, while classic-browser metal verification and guest-local relay remain open.
Build and run classic software with a guest-owned toolchain	Available on the PowerPC guest.	No	Experimental; the host-home MPW build/run loop is metal-verified and typed tests, retry settlement, and guarded guest-home promotion are emulator-verified. CodeKitten acceptance and the new hardening receipts on metal remain open.
Inspect classic Mac hardware	Available.	No	Current; unsupported and unavailable probes remain explicit.
Run bounded diagnostics	Available.	No	Experimental; each diagnostic states its cost before it runs.
Inspect classic network and link state	Available.	No	Current; listener configuration remains in Connections.
Inventory classic applications and system software	Available.	No	Current; availability depends on what the connected guest serves.
Control MCP transports and inspect agent activity	Available.	No	Experimental; running a transport is not itself a guest access grant.
Review bounded host and guest logs	Available.	No	Current; entries retain machine, operation, time, and reason where known.
Manage connections and preferences	Available.	No	Current; the listener is plaintext and intended for trusted networks.

Extension-backed Mirror features¶

Feature	Without the Extension	Extension required?	Current status
See whether the Extension is active and compatible	Reports that the Extension is not installed.	No	Current diagnostic for an optional component.
See live windows and menus from other applications	Not available.	Yes	Experimental; absence and stale observations remain visible.
Recognize standard controls, list items, and menu items	Not available.	Yes	Experimental; custom and unsupported controls remain explicit.
Reconstruct application interiors from drawing activity	Not available.	Yes	Experimental and high risk; off by default and armed for an exact target only.
Interact with windows, menus, controls, text, and selections	Not available through process-local Mirror actions.	Yes	Experimental; success requires application-owned confirmation.
Follow short-lived interface changes	Changes between scene reads may be missed.	Yes	Experimental; changes prompt a coalesced refresh, while periodic refresh remains the fallback.
Stay reachable while an application is in a modal or tracking loop	The normal guest connection may pause until the loop exits.	Yes	Experimental and emulator-verified; not a blanket hardware claim.
Carry a drag through classic tracking loops	Not available as a held remote drag session.	Yes	Experimental; builds and native tests pass, but it is not machine-verified.
Show a classic cursor following remote actions	The action can still occur, but the remote cursor is not drawn.	Yes	Experimental and emulator-verified; physical mouse movement takes priority.
renders them from the catalog.

The catalog is documentation authority until runtime feature flags exist. A future flag implementation must consume the same keys or replace the catalog as authority; it must not create a second availability matrix. The docs gate rejects unknown page feature IDs, incomplete profiles, missing primary pages, and an extension capability list that differs from contract/peek_table.h.

Update derived pages¶

scripts/docs-contract
tools/derived-doc-gate rederive docs/user-guide/reference/modules/index.md

Use the rederive command for every page carrying a derived-doc block. Do not hand-edit its answers or hashes.

The official AsyncAPI Generator remains a compatibility probe, not a required dependency. On 2026-08-09, its current CLI successfully parsed this contract after the missing file.progress channel registration was fixed, but installing it brought 1,732 packages and reported 33 dependency vulnerabilities, including seven critical. NOW's bounded projector reads the same AsyncAPI authority, includes the custom x-commands registry the stock Markdown template omitted, and keeps the landing gate small enough to run on every change.

Run the landing gate¶

scripts/test-docs

It checks metadata, navigation, audience-folder ownership, public links, image alt text and dimensions, module/source parity, AsyncAPI references, generated output, a strict site build, representative accessibility structure, and all declared derived documents. NOW_DOCS_RELEASE=1 additionally refuses publication until the canonical origin, website repository, security contact, and RFC 9116 expiry are configured in docs/site-integration.yaml. A release build then writes security.txt and robots.txt; ordinary local builds never publish placeholder contact data.