recenter the docs site on gather

.changeset/agent-first-docs-framing.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+Center the public documentation on how agents find and apply brand guidance, with the CLI in a supporting role.

README.md

@@ -1,9 +1,9 @@
 # ghost
 
-**ghost is your brand, packed for agents.** A `.ghost/` folder of plain-prose
-guidance (your stance, your voice, your trust moves) checked into the repo and
-read by any agent before it makes anything: a screen, an email, an empty
-state, a sentence.
+Use ghost to give agents applicable brand guidance before they start work. A
+`.ghost/` package stores your stance, voice, trust moves, and concrete materials
+in the repo. Agents select and read that guidance while working on a screen,
+email, empty state, or sentence.
 
 ```text
 .ghost/
@@ -13,12 +13,10 @@ state, a sentence.
   asset.logo.md         # points at the actual SVGs
 ```
 
-Today those decisions live in reviewers' heads: "that's not our voice," again,
-on every surface. The agent that built the thing never saw them. ghost writes
-them down once, where the agent looks first.
+Reviewers repeat the same feedback on every surface: "that's not our voice."
+Write the decision in `.ghost/` so the next agent has it before starting work.
 
-One portable packet; Claude Code, Codex, Cursor, and Goose all read the same
-one. One package, `@design-intelligence/ghost`. One CLI, `ghost`.
+Claude Code, Codex, Cursor, and Goose can all use the same guidance.
 
 [Documentation](https://block.github.io/ghost/) · [npm](https://www.npmjs.com/package/@design-intelligence/ghost)
 
@@ -42,48 +40,55 @@ Brief this work from the ghost package.
 Review this diff against the ghost checks.
 ```
 
-ghost never calls an LLM itself; your agent does the thinking. No API key,
-no lock-in.
+Your agent selects, interprets, and applies the guidance. The CLI handles the
+repeatable work without calling an LLM, so ghost needs no API key and does not
+lock you into one agent.
 
-## The Loop
+## Use Guidance While Making
+
+Your agent works with the package through a small set of commands:
 
 ```bash
 ghost init          # scaffold .ghost/ with the skeleton starter
 ghost checks init   # opt in to review assertions
 ghost validate      # make sure the package is well-formed
-ghost gather <ask>  # before building: list all available guidance
+ghost gather [ask]  # before building: show the complete guidance menu
 ghost pull <ids>    # read the picked nodes' full bodies
 ghost review        # during review: match a diff to guidance and checks
 ghost export        # bundle the guidance as a portable artifact
 ghost pulse         # while tuning: see what agents reached for
 ```
 
-ghost keeps a private local log of what agents reached for; `ghost pulse`
-reads it so you can tune descriptions. It stays on your machine and never
-enters version control.
+For a task-specific gather, your agent reads the complete, unfiltered menu and
+pulls every node whose stated situation applies. Bare `ghost gather` inspects
+the catalog without grounding a task. Because only selected nodes enter the
+working context, the agent can see the shape of the brand without loading the
+whole package.
+
+`gather` and `pull` write a Git-ignored local log. Use `ghost pulse` to inspect
+it and tune node descriptions.
 
 Run `ghost --help` for the core workflow and `ghost <command> --help` for
 flags; the [CLI reference](https://block.github.io/ghost/docs/cli) covers
 every command.
 
 ## Thesis
 
-Agents changed the unit of design work. When they make the screens, the
-emails, and the sentences, polishing any one of them moves nothing; the next
-generation starts from the model's average again. The work that compounds is
-architectural: decide where that average serves, decide where the brand must
-win, and put those decisions where the agent reads before it makes.
+Agents now make screens, emails, and sentences. Polishing one output does not
+help the next generation. Record where the model's default is good enough and
+where the brand must differ, then give those decisions to the agent before it
+starts.
 
-ghost is that artifact: a `.ghost/` package checked into the repo, carrying the
-guidance, the materials they point at, and the conditions they hold under.
-Buttons stay buttons. The moments that carry your brand get your stance
-instead of the default. The few author it once. Every agent it travels to
-builds from it.
+A `.ghost/` package keeps that guidance in the repo with the materials it
+points at and the conditions where it applies. Buttons stay buttons. The
+moments that carry your brand get your stance instead of the default. Write the
+decision once, and each agent can use it when the same situation returns.
 
 ## How It Works
 
-A ghost package is a small folder of prose. The CLI computes; your agent reads,
-writes, and decides.
+A ghost package is a small folder of prose. Your agent finds the guidance that
+applies, reads it, and uses it while making. The CLI supports that work with
+repeatable commands for scaffolding, validation, retrieval, and review.
 
 ```text
 .ghost/
@@ -99,7 +104,7 @@ The package is a **flat set of nodes**. The optional `cover:` in
 `manifest.yml` may name any node; `ghost gather` inlines it before the menu.
 The default skeleton calls that node `brand`, but the filename is not reserved.
 A node is one markdown file: a `description` in frontmatter, optional
-`materials`, and a brand guidance in the prose body.
+`materials`, and brand guidance in the prose body.
 
 ```markdown
 ---
@@ -140,28 +145,22 @@ references:
 Grade whether the change preserves the logo guidance in `asset.logo`.
 ```
 
-`gather` and `pull` run before your agent builds. `review` runs after: it
-reads a diff, matches touched files to node `materials`, offers relevant
-checks, and emits an advisory packet for the host agent to weigh. Review
-output never enters generation context.
-
-The packet is the product; the CLI is the courier. Everything above
-(gather, pull, review, checks, the local log) is machinery around the
-brand guidance, and the guidance outlives all of it.
+`gather` and `pull` give your agent applicable guidance before it builds.
+`review` supports the same agent after a change exists: the CLI reads a diff,
+matches touched files to node `materials`, and offers relevant checks for the
+agent to weigh. Review output never enters generation context.
 
-## Portable by Design
+## The Package Travels
 
-The package travels. It is agent-agnostic (every host agent reads the same
-packet), medium-agnostic (the same guidance steers a screen, a page, an email, a
-sentence), and repo-native (it moves with a clone, a fork, a new hire's first
-checkout). When you need it as a standalone artifact:
+Different agents can read the same guidance and apply it to a screen, page,
+email, or sentence. The package moves with the repo when someone clones or
+forks it. To move the package on its own:
 
 ```bash
 ghost export
 ```
 
-The export audits every `materials` entry so the packet doesn't silently
-point at things that moved.
+The export audits `materials` entries and reports paths that moved.
 
 ## Project Status: Beta
 

apps/docs/.ghost/anti-goal.generated-docs-site.md

@@ -6,7 +6,7 @@ materials:
   - apps/docs/src/components/docs/doc-prose.tsx
 ---
 
-Ghost is not the generated AI SaaS docs site.
+ghost is not the generated AI SaaS docs site.
 
 Reject these defaults even when they are easy to build:
 
@@ -16,13 +16,13 @@ Reject these defaults even when they are easy to build:
   dashboard screenshot.
 - Mascots, emoji headings, playful empty-state illustrations, or robot metaphors.
 - Overpromising copy: "ship on-brand every time," "brand autopilot," "AI that
-  understands your design system," or any claim that makes Ghost sound like it
+  understands your design system," or any claim that makes ghost sound like it
   replaces taste, review, or human curation.
 - Decorative motion that exists only because the page felt static.
 - Dense nav chrome, sidebars on landing pages, or tool-index pages that feel like
   enterprise documentation portals.
 
 A technically correct output can still be off-brand if it looks like any AI tool
-could ship it. Ghost's docs win by being severe, specific, and a little haunted:
+could ship it. ghost's docs win by being severe, specific, and a little haunted:
 black-and-white, exact language, spectral geometry, and enough restraint that the
 one strange gesture actually lands.

apps/docs/.ghost/asset.docs-materials.md

@@ -3,7 +3,8 @@ description: Concrete docs-site materials — inspect before inventing tokens, c
 materials:
   - apps/docs/src/App.tsx
   - apps/docs/src/main.tsx
-  - apps/docs/src/styles/dev-fonts.css
+  - apps/docs/src/styles/docs.css
+  - apps/docs/src/styles/marked-doc.css
   - apps/docs/src/components/docs/**
   - apps/docs/src/app/**/*.tsx
   - apps/docs/src/content/docs/*.mdx
@@ -23,21 +24,19 @@ Material contract:
   `bg-card`) and the named docs typography variables (`--heading-*`,
   `--label-*`). Avoid raw palette utilities unless they are already part of a
   documented semantic exception.
-- **Fonts** are overridden for the docs dev surface in
-  `apps/docs/src/styles/dev-fonts.css`; `font-display` and `font-sans` resolve to
-  Cash Sans locally. Preserve the uppercase label and black display-type rhythm.
+- **Typography** uses the docs styles and Vessel's semantic type roles. Preserve
+  the compact monospace labels, lowercase headings, and restrained body rhythm.
 - **Navigation** is the bottom floating `Dock`. New top nav, side nav, or
   secondary persistent chrome should be treated as a product decision, not a
   routine addition.
-- **Page structure** lives in `AnimatedPageHeader`, `SectionWrapper`,
-  `DocsPageLayout`, `DocSection`, and `DocProse`. Use these before making a new
-  layout primitive.
+- **Page structure** lives in `PageHeader`, `SectionWrapper`, `DocsPageLayout`,
+  `DocSection`, and `DocProse`. Use these before making a new layout primitive.
 - **Docs content** is MDX under `apps/docs/src/content/docs/` with frontmatter
   wired through the docs manifest and routes. Do not hard-code a one-off article
   route unless the content model cannot express it.
 - **CLI examples** should be checked against `apps/docs/src/generated/cli-manifest.json`
   or regenerated with `pnpm dump:cli-help` after CLI command/flag changes.
 
 The materials locate facts; this node does not make every existing choice a
-brand truth. If a component repeats a weak or legacy pattern, fix the pattern
+brand guidance. If a component repeats a weak or legacy pattern, fix the pattern
 instead of canonizing it here.

apps/docs/.ghost/checks/cli-examples-match-manifest.md

@@ -1,6 +1,6 @@
 ---
 name: cli-examples-match-manifest
-description: CLI examples and generated docs stay synchronized with the real Ghost command surface.
+description: CLI examples and generated docs stay synchronized with the real ghost command surface.
 severity: high
 references:
   - condition.cli-reference-exactness

apps/docs/.ghost/checks/no-generic-ai-ornament.md

@@ -1,6 +1,6 @@
 ---
 name: no-generic-ai-ornament
-description: Docs UI avoids generic AI SaaS ornament and preserves Ghost's restrained monochrome visual stance.
+description: Docs UI avoids generic AI SaaS ornament and preserves ghost's restrained monochrome visual stance.
 severity: medium
 references:
   - anti-goal.generated-docs-site
@@ -15,4 +15,4 @@ state.
 
 This check should not block legitimate semantic color in docs prose or existing
 Vessel component behavior. The issue is generic ornament that weakens the severe,
-monochrome, typographic Ghost stance.
+monochrome, typographic ghost stance.

apps/docs/.ghost/checks/review-stays-advisory.md

@@ -1,16 +1,16 @@
 ---
 name: review-stays-advisory
-description: Docs keep checks and review positioned as feed-back advisory context, never deterministic brand verdict or generation input.
+description: Docs keep checks and review advisory and after generation, never a brand verdict or generation input.
 severity: high
 references:
   - principle.product-model
   - decision.feed-forward-over-review
 ---
 
-Review docs copy for claims that Ghost review grades, approves, blocks, judges,
+Review docs copy for claims that ghost review grades, approves, blocks, judges,
 or guarantees brand fit. Flag wording that treats checks as generation input or
 turns advisory review packets into CI gates.
 
-Accept wording that says checks are optional deterministic assertions, review
-assembles packets, host agents judge, and teams may choose to enforce separate
-CI around their own deterministic checks.
+Accept wording that says checks are optional review assertions, `ghost review`
+supplies evidence, agents judge, and teams may enforce separate CI around
+their own automated checks.

apps/docs/.ghost/decision.feed-forward-over-review.md

@@ -3,29 +3,28 @@ description: Tradeoff behind leading with gather/pull before review — gather w
 materials:
   - apps/docs/src/content/docs/getting-started.mdx
   - apps/docs/src/content/docs/checks-and-review.mdx
-  - apps/docs/src/app/tools/scan/page.tsx
-  - apps/docs/src/app/tools/drift/page.tsx
+  - apps/docs/src/content/docs/cli-reference.mdx
 ---
 
-Decision trace: Ghost could have led with review because drift detection is easy
-to understand. We choose feed-forward authoring and recall as the center because
-that is the product's real leverage: the agent should receive the decision before
-it builds.
+Decision trace: ghost could have led with review because drift detection is easy
+to understand. We lead with authoring, gather, and pull because the agent should
+receive the decision before it builds.
 
 What review is good for:
 
 - It makes drift visible after a diff.
 - It routes changed files to material-backed nodes and checks.
-- It gives a host agent an advisory packet for critique.
+- It gives the agent grounded evidence for critique.
 
 Why review does not lead:
 
-- If the right truth was never gathered, review catches the failure late.
-- Calling review a gate makes Ghost sound like it judges brand fit
+- If the right guidance was never gathered, review catches the failure late.
+- Calling review a gate makes ghost sound like it judges brand fit
   deterministically, which it does not.
 - Teams adopt faster when the first win is one repeated decision written down and
   reused before generation.
 
 The decision reverses only for a page whose explicit job is `ghost review`, the
-checks directory, or CI-style integration. Even there, repeat the boundary: review is
-feed-back and advisory; checks do not leak into generation context.
+checks directory, or CI-style integration. Even there, repeat the boundary:
+review happens after a change exists and remains advisory; checks do not enter
+generation context.

apps/docs/.ghost/exemplar.home-thesis.md

@@ -1,5 +1,5 @@
 ---
-description: Annotated home-page thesis exemplar — match this form when writing high-level Ghost narrative or landing copy.
+description: Annotated home-page thesis exemplar — match this form when writing high-level ghost narrative or landing copy.
 materials:
   - apps/docs/src/app/page.tsx
   - apps/docs/src/components/docs/hero.tsx
@@ -11,17 +11,17 @@ pace.
 What to match:
 
 - **Tiny hero, huge word.** The hero does not explain the whole product. It says
-  "Ghost" at wordmark scale and gives one sentence of context. That restraint is
+  "ghost" at wordmark scale and gives one sentence of context. That restraint is
   the brand move.
 - **Editorial thesis cadence.** The thesis unfolds in paragraphs, not a grid of
   benefits. It trusts the reader to follow a serious idea.
-- **Mechanics over adjectives.** The copy names concrete mechanics — flat corpus,
-  `gather`, `pull`, `review`, Git approval — instead of claiming the product is
-  simple, powerful, or magical.
+- **Interaction over architecture.** The copy shows the agent finding and using
+  applicable guidance. Name commands when they clarify that interaction, not to
+  make the CLI the protagonist.
 - **Selective emphasis.** Foreground text highlights only the load-bearing model
   phrase. Do not bold every important sentence.
 - **Haunted restraint.** The concentric circles are spectral and low-opacity;
-  they make the page feel like Ghost without becoming decoration the prose must
+  they make the page feel like ghost without becoming decoration the prose must
   fight.
 
 Do not copy incidentals: the exact paragraph count, current CLI ordering, and the

apps/docs/.ghost/glossary.md

@@ -18,7 +18,7 @@ loosen them.
 
 # condition
 
-Situational truth. Use only when the stated situation holds, and do not treat the
+Situational guidance. Use only when the stated situation holds, and do not treat the
 condition as a destination bucket.
 
 # pattern
@@ -39,7 +39,7 @@ from.
 
 # asset
 
-Material truth about concrete tokens, components, type, motion, canvases, docs,
+Material guidance about concrete tokens, components, type, motion, canvases, docs,
 copy, code, or files. `materials` locates; prose explains what the files mean.
 
 # decision
@@ -49,5 +49,5 @@ choice would reverse.
 
 # voice
 
-Language and naming truth: the product vocabulary, cadence, metaphor, and copy
-boundaries that make the docs sound like Ghost rather than generic SaaS docs.
+Language and naming guidance: the product vocabulary, cadence, metaphor, and copy
+boundaries that make the docs sound like ghost rather than generic SaaS docs.