Writing docs

The bar for this site is minimalist but important info. A person or an agent should be able to scan a page in under a minute and come away with the real thing, not filler.

The one rule

Document only what is implemented. Two ground truths:

• Shipped → Status + task-plan/MASTER-TASK-LIST.md upstream.
• Planned → the live GitHub issues in conclavehq/{Conclave,Capture,VFTEE,Mobile}. These belong on the Roadmap, clearly labelled not yet built — never in a feature page as if they exist.

If you can't confirm a capability is built, it doesn't go in a feature page.

Status badges

Every feature gets one, stated plainly in prose or a table cell:

• Live in prod — deployed and running on the Phala CVMs.
• Built · merged local — merged to a local main, not yet pushed/deployed. Say built, not shipped.
• Built · not merged — exists on a feature branch, not merged.

Surface known open bugs where they matter (e.g. the web login loop) rather than hiding them.

Voice

• Dense and concrete. Prefer a table or a tight list to a paragraph.
• Cite the source. Link the canonical upstream doc (FEATURE-SPEC.md, DEPLOYMENT-GUIDE.md, a TASK-*.md) so a reader can verify and go deeper.
• Machine identifiers — CVM ids, env vars, endpoints, file paths — in monospace.
• No marketing adjectives in engineering pages. No invented numbers. Flag assumptions as assumptions (the GTM pages label pricing/market sizing as the model, not validated).
• No emoji in headings, no decorative gradients, no stock imagery.

Mechanics

• Pages are MDX under content/docs/. Frontmatter needs title and description.
• Sidebar order and tabs live in each folder's meta.json ("root": true makes a tab).
• The trust-accent green is reserved for trust/attestation cues — use the trust-note block sparingly, not as general emphasis.
• Run npm run build before you commit; it must stay green.