Refocus fingerprints around covers and foundations

.changeset/concrete-tiers-recipe.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+Add the concrete-tiers skill recipe: choosing which concrete code tiers (tokens, skeletons, components, exemplars) a fingerprint carries, and justifying absences.

.changeset/cover-context-guidance.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+Treat the manifest cover as inlined context instead of asking agents to select an `index` node.

.changeset/cover-node-designer-skeleton.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": minor
+---
+
+Adds a manifest `cover` field — gather inlines the named node above the menu, validate enforces it — and re-authors the skeleton starter in designer-native vocabulary: a brand cover, foundation chapters with open questions, context nodes, and a cliche floor paired with checks.

.changeset/docs-cleanup-pass.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+Document bound/open pattern authoring and `concept.*` nodes in the capture skill recipe; deduplicate the package README against the root README.

.changeset/docs-code-drift-fixes.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+Make `GHOST_PACKAGE_DIR` honored by every command, not just `init` and `validate`; support `goose` in the `install.sh` curl installer; and drop detection of the pre-flat legacy checks directory entirely.

.changeset/remove-glossary-posture.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": major
+---
+
+Removes the glossary posture system. Glossary kinds no longer accept a posture key; `ghost gather` drops the `--wild` flag and lists every node; `ghost pull` orders packets as index, concrete nodes, then prose; `ghost review` reports matched material-backed nodes without a separate review-critical section and renames the `unguarded-material` coverage gap to `unchecked-material`; `ghost pulse` drops the wild usage section. Existing fingerprints keep working: an ignored `posture` key in `glossary.md` frontmatter is tolerated, and anti-goal nodes still gather, pull, and match in review through their materials like any node.

.changeset/validate-warns-undescribed-nodes.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": minor
+---
+
+`ghost validate` warns on nodes without a `description` (rule `node-description-missing`), and the `ghost gather` coverage line reports how many nodes lack descriptions, since an undescribed node is invisible to agent selection.

.changeset/vessel-light-closure.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": patch
+---
+
+Reconciles the vessel-light starter body: every token and primitive class is now demonstrated in a reference or removed, display type has one answer, and a closure check keeps the materials contract enforced.

CLAUDE.md

@@ -91,7 +91,7 @@ edits and checks.
 | `packages/ghost` | yes: `@design-intelligence/ghost` | The public package. Ships the `ghost` CLI, node authoring, corpus validation, gather/pull/pulse, review packet assembly, and the unified skill bundle. Shared runtime lives in `packages/ghost/src/ghost-core`. |
 | `packages/vessel-react` | no | A standalone shadcn component registry plus `vessel-mcp` MCP server: the opinionated default reference body. Design-system-agnostic; nothing in Ghost requires it. |
 | `packages/vessel-light` | no | Vessel's design language as a portable `.ghost/` fingerprint package for agents writing raw HTML/CSS. No build, no dependencies. |
-| `packages/steering-eval` | no | Before/after evaluation harness: measures what handing an agent a `.ghost` fingerprint buys, as a deterministic `report.html`. |
+| `packages/steering-control` | no | Before/after evaluation harness: measures what handing an agent a `.ghost` fingerprint buys, as a deterministic `report.html`. |
 | `apps/docs` | no | Docs site. |
 
 ## CLI Commands
@@ -100,7 +100,7 @@ Core workflow:
 
 | Command | Description |
 | --- | --- |
-| `ghost init` | Scaffold `.ghost/` with the skeleton starter: manifest, glossary, `index.md`, grammar nodes, and unanswered signature dials. `--template minimal` writes only the manifest/glossary/index starter; `--body vessel-light` installs a full inhabited fingerprint instead. `--with checks` also adds the checks directory. |
+| `ghost init` | Scaffold `.ghost/` with the skeleton starter: manifest, glossary, a `brand.md` cover, foundation chapters, context nodes, and the cliche floor. `--template minimal` writes a smaller cover-led starter; `--body vessel-light` installs a full inhabited fingerprint instead. `--with checks` also adds the checks directory. |
 | `ghost checks init` | Scaffold `.ghost/checks/` with an example review assertion. |
 | `ghost validate` | Validate the package: manifest shape, node validity, material locators, check references, and glossary kind prefixes. |
 | `ghost gather [ask…]` | Emit the fingerprint menu for the agent to select from. |

README.md

@@ -87,17 +87,19 @@ writes, and decides.
 
 ```text
 .ghost/
-  manifest.yml          # schema + package id (the anchor)
+  manifest.yml          # schema + package id + optional cover id
   glossary.md           # your kind vocabulary + what each kind means
-  index.md              # the curated front door
+  brand.md              # example cover inlined by gather
   principle.trust.md    # a brand truth of kind `principle`
   asset.logo.md         # a truth that may point at concrete materials
   checks/               # optional review assertions; never nodes
 ```
 
-The fingerprint is a **flat set of nodes**. A node is one markdown file: a
-`description` in frontmatter, optional `materials`, and a brand truth in the
-prose body.
+The fingerprint 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 truth in the prose body.
 
 ```markdown
 ---
@@ -175,7 +177,7 @@ point at things that moved.
 | [`packages/ghost`](./packages/ghost) | The public `ghost` CLI, node authoring, fingerprint validation, gather/pull, review packet assembly, and the skill bundle. | yes: `@design-intelligence/ghost` |
 | [`packages/vessel-react`](./packages/vessel-react) | A standalone shadcn component registry plus `vessel-mcp` MCP server. | no |
 | [`packages/vessel-light`](./packages/vessel-light) | Vessel's design language as a portable `.ghost/` fingerprint for agents writing raw HTML/CSS. | no |
-| [`packages/steering-eval`](./packages/steering-eval) | Before/after evaluation harness: measures what a `.ghost` fingerprint buys as a self-contained `report.html`. | no |
+| [`packages/steering-control`](./packages/steering-control) | Before/after evaluation harness: measures what a `.ghost` fingerprint buys as a self-contained `report.html`. | no |
 | [`apps/docs`](./apps/docs) | Docs site. | no |
 
 ## Development

apps/docs/.ghost/voice.docs-language.md

@@ -17,9 +17,9 @@ Voice rules:
 - Prefer short declarative sentences around the model: "The CLI does the
   deterministic work; your agent does the interpretation." Do not bury the
   boundary in hedging.
-- Use concrete artifact names: `.ghost/`, `manifest.yml`, `glossary.md`,
-  `index.md`, `checks/`, `ghost gather`, `ghost pull`. The docs earn trust by
-  naming the files and commands agents actually touch.
+- Use concrete artifact names: `.ghost/`, `manifest.yml`, `glossary.md`, the
+  manifest-declared cover, `checks/`, `ghost gather`, `ghost pull`. The docs earn
+  trust by naming the files and commands agents actually touch.
 - Say **brand truth**, **fingerprint**, **node**, **kind**, **materials**,
   **feed-forward**, **feed-back**, and **advisory review packet**
   consistently. Do not introduce synonyms such as brand DNA, style cache,

apps/docs/src/content/docs/cli-reference.mdx

@@ -43,15 +43,16 @@ Every command follows one contract, so an agent can branch on the exit code:
 | `3` | A command-specific refusal, currently only `skill install` when a skill is already present (pass `--force`). |
 
 A missing package is reported, not treated as a crash: `validate` records it as
-a finding (exit `1`).
+a finding (exit `1`). Getting a code you don't understand, or a command that
+refuses to run at all? See [Troubleshooting](/docs/troubleshooting).
 
 </DocSection>
 
 <DocSection title="Create And Inspect">
 
 ### Initialize: `init`
 
-Scaffold a `.ghost/` package. Every template and body includes `anti-goal.median`; the skeleton starter also includes a manifest, a `glossary.md` declaring the grammar/signature/register/anti-goal kinds, a core `index.md`, six grammar nodes of value-free decision logic, and four signature nodes as unanswered dials awaiting your brand's values. The median node is Ghost's measured knowledge of unsteered model behavior — model truth, not brand truth — stamped at init and owned (pruned, adapted) by you thereafter. Nothing in the skeleton is fiction: grammar and the median floor are safe to consume verbatim; the dials tell the agent to ask or flag, never freehand. Use `--template minimal` when you only want the small manifest/glossary/index starter. Add truths by adding files (`principle.density.md`). Use
+Scaffold a `.ghost/` package. The skeleton starter includes a manifest, a glossary, a `brand.md` cover, foundation chapters with open questions, a conversation context, and the model cliche floor. The cover and foundations tell the agent to ask rather than invent brand values. Use `--template minimal` for a smaller cover-led starter. Add truths by adding files (`principle.density.md`). Use
 `--package <dir>` for an exact directory, or set `GHOST_PACKAGE_DIR` when a host
 wrapper stores Ghost files outside the default `.ghost`. Core `init` scaffolds
 the fingerprint only; pass `--with checks` to also add the checks directory in

apps/docs/src/content/docs/fingerprint-authoring.mdx

@@ -84,9 +84,9 @@ filename's first dotted segment (`principle.trust.md` → kind `principle`), and
 must be a kind declared in `glossary.md`; a bare name (`voice.md`) has
 no kind. Folders are a human-browsing convenience only.
 
-Reserved at the package root are `manifest.yml`, `glossary.md`, and the
-`checks/` directory; every other `*.md` is a node. Moving or renaming a node
-changes its id.
+Reserved at the package root are `manifest.yml`, `glossary.md`, `materials/`,
+and the `checks/` directory; every other `*.md` is a node. Moving or renaming
+a node changes its id.
 
 Node frontmatter carries only descriptive properties:
 

apps/docs/src/content/docs/getting-started.mdx

@@ -80,12 +80,11 @@ by decision. One high-confidence truth beats an empty catalog.
 
 The CLI scaffolds; your agent authors: interviewing you, working with the
 material you show it, drafting node prose, and asking you to curate the claims.
-`ghost init` writes a starter you adapt: a glossary, an index, truths that hold
-for any brand, and a few files left as unanswered **dials** that
-tell the agent to ask you rather than invent a value. Answering the dials is how
-the starter becomes your brand. Prefer a bare start? `ghost init --template
-minimal` writes only the manifest, glossary, and index. The full starter
-anatomy is in the [CLI reference](/docs/cli).
+`ghost init` writes a starter you adapt: a glossary, a `brand.md` cover,
+foundation chapters with open questions, and the model cliche floor. Answering
+the questions is how the starter becomes your brand. Prefer a bare start?
+`ghost init --template minimal` writes a smaller cover-led starter. The full
+starter anatomy is in the [CLI reference](/docs/cli).
 
 ```bash
 ghost init
@@ -170,6 +169,10 @@ An undeclared kind prefix is a warning with a "did you mean" suggestion, not a
 failure. Treat fingerprint edits as ordinary Git-reviewed changes: uncommitted
 edits are drafts; checked-in nodes are canonical.
 
+Hit something the loop above doesn't explain — an empty `gather`, a `review`
+that refuses to run, a stale example? See
+[Troubleshooting](/docs/troubleshooting).
+
 </DocSection>
 
 <DocSection title="How It Works (the model underneath)">
@@ -181,27 +184,30 @@ The fingerprint is a **flat set of prose nodes**:
 
 ```text
 .ghost/
-  manifest.yml          # schema + package id
+  manifest.yml          # schema + package id + optional cover id
   glossary.md           # the kind vocabulary + what each kind means
-  index.md              # the curated front door node
+  brand.md              # example cover inlined by gather
   principle.trust.md    # a brand truth of kind `principle`
   condition.density.md  # a brand truth of kind `condition`
   asset.logo.md         # a truth that may point at concrete materials
   voice.md              # a brand truth without a kind
   checks/               # optional review assertions; never a node
 ```
 
-There is no hierarchy, no inheritance, and no edges between nodes. A node's
-identity is its file path with `.md` dropped (`marketing.email.md` is the node
-`marketing.email`). Its **kind** is the filename's first dotted segment, and must
+There is no hierarchy, no inheritance, and no edges between 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's identity is its file path with `.md` dropped
+(`marketing.email.md` is the node `marketing.email`). Its **kind** is the
+filename's first dotted segment, and must
 be a kind declared in `glossary.md`; a bare name (`voice.md`) has
 no kind. Folders are a human-browsing convenience only; the model reads a
 flat menu.
 
 Altitude lives in the prose: a universal truth is stated plainly; a narrower
 truth names the *situation* it applies in. The agent reads the condition and
 decides when the truth applies. Reserved at the package root: `manifest.yml`,
-`glossary.md`, and `checks/`; every other `*.md` is a node.
+`glossary.md`, `materials/`, and `checks/`; every other `*.md` is a node.
 
 A node may carry `materials`: repo-relative paths/globs or HTTPS
 URLs for the concrete materials the prose governs. `ghost gather` emits the menu;

apps/docs/src/content/docs/troubleshooting.mdx

@@ -0,0 +1,174 @@
+---
+title: Troubleshooting
+description: What to do when gather comes back empty, validate warns about a kind, review refuses to run, or a pull misses an id.
+kicker: Docs
+section: guide
+order: 35
+slug: troubleshooting
+---
+
+<DocSection title="Start Here">
+
+Every Ghost command follows one exit-code contract, so start by reading the
+code before reading the message:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | The command ran but the result is unhappy: `validate` found issues, or an unexpected error was thrown. |
+| `2` | The command was called wrong: a bad flag or argument, a missing package for a command that needs one, a `pull` with no known ids, or `review` without a checks directory. |
+| `3` | A command-specific refusal, currently only `skill install` when a skill is already present (pass `--force`). |
+
+The sections below are the specific failures behind those codes, and what to
+do about each.
+
+</DocSection>
+
+<DocSection title="`ghost gather` returns nothing relevant">
+
+`gather` does no filtering or ranking; it always emits the whole menu. If your
+agent reads the menu and pulls nothing useful, the problem is retrieval, not
+missing coverage.
+
+- **Check the description, not the body.** An agent selects against a node's
+  `description` alone. A vague description (`Our trust principles.`) is
+  invisible at selection time no matter how good the prose underneath is.
+  Rewrite it as a task-shaped phrase: what moment, surface, or question should
+  make an agent realize this node applies.
+- **Check `ghost pulse`.** It shows whether a node appeared on the menu, got
+  pulled, was missed by an id the agent tried and failed, or stayed cold
+  every time. A cold node with real content is a description problem, not a
+  content problem.
+- **Don't add more nodes to fix a retrieval miss.** A weak description with a
+  strong body is worse than a strong description with a thin body; the agent
+  never reaches the body.
+
+```bash
+ghost gather "checkout settings" --format json
+ghost pulse
+```
+
+</DocSection>
+
+<DocSection title="`ghost validate` warns about an undeclared kind">
+
+A node's kind is the filename prefix before the first dot
+(`principle.trust.md` → kind `principle`), and it must be declared in
+`glossary.md`. An undeclared kind is a warning with a "did you mean"
+suggestion, not a failure — `validate` still exits `0` unless something else
+is wrong.
+
+- If the suggestion is right, it's usually a typo in the filename
+  (`pinciple.trust.md`) or a stale glossary that never picked up a kind you
+  started using.
+- If you meant to introduce a new kind, add it to `glossary.md`'s `kinds`
+  list along with a `#` section explaining its meaning and normative weight.
+  Declaring a kind with one user is fine; Ghost ships no fixed vocabulary.
+- If the file was never meant to carry a kind, drop the dotted prefix; a bare
+  name (`voice.md`) has no kind and needs no glossary entry.
+
+```bash
+ghost validate --format json
+```
+
+</DocSection>
+
+<DocSection title="`ghost review` exits 2 immediately">
+
+`review` requires a checks directory. Without one, it refuses rather than
+silently emitting an empty packet:
+
+```bash
+ghost checks init
+```
+
+If checks already exist and `review` still exits oddly, check that you're
+running it against a real diff — with no base and no staged/unstaged changes,
+there's nothing to match against materials. Point it explicitly:
+
+```bash
+ghost review --base main
+git diff main | ghost review --diff=-
+```
+
+</DocSection>
+
+<DocSection title="`ghost pull` warns about an unknown id">
+
+`pull` partially succeeds: known ids are emitted, unknown ids warn with
+closest-id hints, and the miss is recorded for `ghost pulse`. A pull with
+**no** known ids exits `2`.
+
+- Run `ghost gather` first and copy ids from the menu rather than guessing
+  them; a node's id is its file path with `.md` dropped, so a nested or
+  renamed file changes its id.
+- A repeated miss on the same guessed id is retrieval signal: the id or the
+  glossary vocabulary isn't what agents expect. Consider renaming the node or
+  sharpening its description so the menu surfaces it before an id is needed.
+
+</DocSection>
+
+<DocSection title="A node points at a file that moved">
+
+`materials` locators are repo-relative paths/globs or absolute HTTPS URLs.
+When a path moves or a component gets deleted, the node still validates (path
+resolution is checked, but drift after a refactor can slip through between
+validate runs) and `ghost review` will simply stop matching that node to the
+files that touch it.
+
+- Run `ghost export --strict` periodically; it audits every `materials` entry
+  and fails on any repo-relative path that resolves outside the package or
+  doesn't exist, which is exactly the "stranded" case a refactor produces.
+- If `ghost review`'s coverage gaps list a touched file no node claims, that's
+  the same signal at review time: either the file needs a `materials` owner,
+  or it's genuinely out of scope.
+
+```bash
+ghost export --strict
+```
+
+</DocSection>
+
+<DocSection title="CLI docs or examples look stale">
+
+The CLI reference and its `--help` output are generated from the CLI source,
+not hand-maintained. If you changed a command or flag and the docs didn't
+follow:
+
+```bash
+pnpm dump:cli-help
+```
+
+Commit the regenerated `apps/docs/src/generated/cli-manifest.json`. CI's
+drift check declines a PR that changes a command surface without this step.
+
+</DocSection>
+
+<DocSection title="Fingerprint edits aren't taking effect">
+
+Uncommitted or unmerged fingerprint edits are drafts; Ghost's tooling reads
+whatever is on disk in your working tree, so a draft node does show up in
+`gather` immediately. What it means for edits to "take effect" is usually one
+of:
+
+- **The agent already had a stale menu in context.** Re-run `ghost gather`
+  after any edit; nothing caches the menu between calls.
+- **The team disagrees on what's canonical.** Ordinary Git review is the
+  approval boundary for fingerprint edits, same as any other code change.
+  Treat an unmerged branch's nodes as provisional until they land.
+
+</DocSection>
+
+<DocSection title="Still stuck?">
+
+If none of the above matches what you're seeing, the fastest path is usually
+to ask your agent directly, since it already has the skill bundle installed:
+
+```text
+Run ghost validate and ghost pulse, and tell me what's wrong with this fingerprint.
+```
+
+If that doesn't resolve it, open an issue with the exact command, its exit
+code, and `--format json` output attached.
+
+</DocSection>