PageHare docs
Start here to find a guide, plan, or technical rule. Keep each fact in one document.
When a feature ships, keep its plan in plans/ as history. Put its current behavior
in the relevant guide or specification.
Read the writing and HTML guide before editing.
Run npm run docs:html and open .docs-site/index.html to browse the HTML library.
Run npm run docs:watch to rebuild it as documents change.
Layout
| Folder | Read it for |
|---|---|
product/ | MVP1 scope and launch checklist, roadmap, bugs, and open tasks |
plans/ | Work planned or completed. Keep completed plans as history and state their status. The reader-social plan has a handoff and test checklist. |
architecture/ | Storage and records, social counts and backlinks, bundle-size checks, OAuth scopes (which permission each sign-in and feature asks for), and diagrams. Link to diagrams here instead of copying them. |
design/ | Brand assets and motion. Use /styleguide for current components. Keep reference/ unchanged as history. |
operations/ | Deploy with SST, find AWS resources, and set deploy permissions |
guides/ | Use each app page, run browser tests, test the reader-social features by hand, and write and publish documents. Carbon and Storybook guides are historical. |
archive/ | Old ECS and Fargate deployment guides. Do not use them for current deployment. |
CHANGELOG.md | Release history, updated with npm run changelog |
Pinned at docs/ root (path-coupled — do not move)
-
PAGEHARE_BLOCKS.md— block spec; its rules/fence tables are generated bynpm run docs:blocksand drift-checked in CI (scripts/generate-blocks-doc.tswrites this exact path). -
ENGINE_INVARIANTS.md— engine invariants; referenced by path fromclaude.md, plans, and code comments.
Also path-pinned at the repo root: PAGEHARE_DS.md (design-system rules — read before any UI work) and claude.md (agent instructions; note git tracks it lowercase).
Conventions
-
Put status first. Plans and product docs state their status (
not started / in progress / done / superseded) in the first lines. -
Link to the source. Keep each fact in one doc and link to it elsewhere. Values live in code (CSS tokens, Zod schemas, lexicon JSON); docs hold rules and intent.
-
Generated regions are never hand-edited (
PAGEHARE_BLOCKS.mdtables,CHANGELOG.mdreconciled section). -
Changelog: run
npm run changelogto append commits since the last reconcile point; hand-written release notes go above the generated history.
Original and simplified editions
Documents at the paths above retain their original wording. Most have a reading
copy under docs/simplified/<original-path>, and the HTML library uses those copies.
Single-edition documents (generated, append-only, or already plain) have no copy;
the HTML library uses the original.
For example, docs/architecture/storage.md pairs with
docs/simplified/docs/architecture/storage.md.
Follow the document workflow to update both editions and record a comparison. Simplified editions are not separate specifications.