@design-intelligence/ghost 0.0.0-next-20260715121453

package/dist/scan/templates.js

@@ -0,0 +1,375 @@
+import { GHOST_FINGERPRINT_PACKAGE_SCHEMA } from "#ghost-core";
+import { GHOST_EVENTS_FILENAME, LEGACY_PULL_HISTORY_FILENAME, } from "./constants.js";
+import { loadPackedPayload, loadPayloadFile } from "./packed-payloads.js";
+function manifestFile(cover) {
+    return {
+        relativePath: "manifest.yml",
+        content: `schema: ${GHOST_FINGERPRINT_PACKAGE_SCHEMA}\nid: local\n${cover ? `cover: ${cover}\n` : ""}`,
+    };
+}
+/**
+ * Keep events tapes out of version control: they are disposable
+ * per-machine signals for authors iterating on the fingerprint, never canonical
+ * state.
+ */
+function gitignoreFile() {
+    return {
+        relativePath: ".gitignore",
+        content: `${GHOST_EVENTS_FILENAME}\n${LEGACY_PULL_HISTORY_FILENAME}\n`,
+    };
+}
+/**
+ * The minimal starter: a manifest, a package-level glossary declaring the
+ * starter kind vocabulary, and a package-root `index.md` cover. Additional
+ * truths are plain markdown nodes; optional material locators live on the node
+ * that explains them. Checks are opt-in via `ghost checks init`.
+ */
+const MINIMAL_TEMPLATE = {
+    name: "minimal",
+    description: "Minimal node package: manifest + glossary + a starter cover node.",
+    async files() {
+        const medianFile = await medianTemplateFile();
+        return [
+            manifestFile("index"),
+            gitignoreFile(),
+            {
+                relativePath: "glossary.md",
+                content: `---
+kinds:
+  - name: principle
+  - name: condition
+  - name: exemplar
+  - name: anti-goal
+  - name: cliche
+  - name: asset
+  - name: pattern
+---
+
+# principle
+
+Durable stance: true across media unless a narrower condition explicitly limits it.
+
+# condition
+
+Situational truth: fires only when the stated situation holds.
+
+# exemplar
+
+Illustrative reference. Match its form and quality; treat its specifics as
+evidence unless the node says the sample itself is normative.
+
+# anti-goal
+
+What this brand must never look, sound, or feel like — named generic patterns
+and rejected neighbors. Always-on, like a principle, but stated as the thing
+to steer away from.
+
+# cliche
+
+The defaults a generative model falls back on when no brand is steering it.
+These are nobody's brand. Each entry pairs the tired move with the honest
+replacement. Gather before styling anything greenfield; enforced by paired
+checks at review.
+
+# asset
+
+Material truth about concrete brand assets such as logos, illustrations, motion, imagery, or files.
+
+# pattern
+
+Reusable composition or product pattern whose purpose is distinguishable from neighboring patterns.
+`,
+            },
+            {
+                relativePath: "index.md",
+                content: `---
+description: Always read first — the non-negotiables and how to read this fingerprint.
+---
+
+Replace this placeholder prose with two things:
+
+**The non-negotiables.** The handful of truths that apply to every task, every
+medium, no matter what else is gathered — hard invariants, the anti-goals, the
+one-sentence stance. Anything that must never be missed belongs here, stated
+briefly; link out to the full node by id for depth.
+
+**How to read the rest.** What this fingerprint covers, how its kinds organize
+the corpus, and where the fingerprint deliberately stays silent — including, if
+you want one, a stricter silence posture ("when this fingerprint is silent on X,
+ask a human") that overrides the default proceed-provisionally behavior.
+
+\`index\` is this package's manifest-declared cover: \`ghost gather\` inlines its
+body before the menu and excludes it from selection. Its privilege comes from
+\`cover: index\` in \`manifest.yml\`, not from the filename. You may rename it;
+update the manifest's \`cover\` id at the same time.
+
+The glossary declares the kind vocabulary. A node's kind comes from its
+filename prefix: \`principle.density.md\` has kind \`principle\` and slug
+\`density\`. A bare filename like \`voice.md\` has no kind, which is fine.
+When a truth is narrower, state the condition in the prose — the situation where
+it applies — never a filing destination.
+`,
+            },
+            medianFile,
+        ];
+    },
+};
+/**
+ * The composition starter: everything in `minimal`, plus a worked composition
+ * ladder — an invariants floor (`principle.composition`), one bound/open
+ * pattern, and a cover that teaches the convention. For teams whose
+ * fingerprint must steer *what agents build*, not only what they say.
+ *
+ * The ladder is an authoring convention, not a schema: patterns state what is
+ * bound (do not redecide) and what is open (the generator's call), and every
+ * pattern names the principles it refines. Nothing here adds frontmatter,
+ * edges, or routing — the corpus stays flat.
+ */
+const COMPOSITION_TEMPLATE = {
+    name: "composition",
+    description: "Composition starter: minimal files + an invariants floor and a worked bound/open pattern.",
+    async files() {
+        const medianFile = await medianTemplateFile();
+        return [
+            manifestFile("index"),
+            gitignoreFile(),
+            {
+                relativePath: "glossary.md",
+                content: `---
+kinds:
+  - name: principle
+  - name: condition
+  - name: exemplar
+  - name: anti-goal
+  - name: cliche
+  - name: asset
+  - name: pattern
+---
+
+# principle
+
+Durable stance: true across media unless a narrower condition explicitly limits it.
+Composition principles are the floor — when no pattern matches an ask, they are
+what the agent composes against.
+
+# condition
+
+Situational truth: fires only when the stated situation holds.
+
+# exemplar
+
+Illustrative reference. Match its form and quality; treat its specifics as
+evidence unless the node says the sample itself is normative. Pair an
+exemplar with a screenshot or implementation path in \`materials\` so the blessed
+render travels with the prose.
+
+# anti-goal
+
+What this brand must never look, sound, or feel like — named generic patterns
+and rejected neighbors. Always-on, like a principle, but stated as the thing
+to steer away from.
+
+# cliche
+
+The defaults a generative model falls back on when no brand is steering it.
+These are nobody's brand. Each entry pairs the tired move with the honest
+replacement. Gather before styling anything greenfield; enforced by paired
+checks at review.
+
+# asset
+
+Material truth about concrete brand assets such as logos, illustrations, motion,
+imagery, or files. For components, state the slot contract in prose: what the
+asset admits, how many, and where.
+
+# pattern
+
+Reusable composition whose purpose is distinguishable from neighboring patterns.
+A pattern states what is **bound** (decided — do not redecide) and what is
+**open** (the generator's call, within named limits), and names the principles
+it refines. A pattern may only narrow what its principles allow — never loosen
+them.
+`,
+            },
+            {
+                relativePath: "index.md",
+                content: `---
+description: Start here — how this fingerprint steers composition, from patterns down to principles.
+---
+
+This fingerprint steers what gets built, not only what gets said. It is
+organized as a ladder of binding depth:
+
+1. **Patterns** (\`pattern.*\`) are mostly-decided compositions. When an ask
+   matches a pattern's stated purpose, use it: apply what it binds, decide only
+   what it leaves open.
+2. **Principles** (\`principle.*\`) are the floor. When no pattern matches, do
+   not fall back to your own taste — compose freely *inside* the invariants in
+   \`principle.composition\` and its siblings.
+3. **Exemplars and assets** carry the concrete vocabulary: blessed renders,
+   real components, real tokens, located via \`materials\`.
+
+Two laws keep the ladder honest:
+
+- **Narrowing only.** A pattern may bind or narrow what a principle leaves
+  open; it may never contradict one. If a pattern conflicts with a principle,
+  the principle wins and the pattern file is wrong.
+- **Every "never" casts a shadow.** Each refusal-grade line in a principle
+  should be mirrored by a review check (\`ghost checks init\`) that
+  references the node it enforces, so the same opinion steers before building
+  and grades after.
+
+Replace this prose with your own front door once the corpus has shape. The
+starter nodes below are teaching placeholders — edit them into your real
+opinions before trusting them.
+`,
+            },
+            {
+                relativePath: "principle.composition.md",
+                content: `---
+description: The composition floor — hard layout invariants that hold for every screen, whether or not a pattern matches the ask.
+---
+
+These invariants apply to everything built against this fingerprint. Patterns
+narrow them; nothing loosens them. Each is written as a refusal or a limit with
+a number, because a stance an agent can check is a stance that steers.
+
+**The starter opinions below are placeholders. Keep the voice — refusals and
+numbers, not vibes — and replace the values with yours.**
+
+- **One focal point.** Every screen has exactly one element at the largest
+  scale. If two elements compete for primacy, the second one is wrong — demote
+  or delete it. Never resolve the tie by making both big.
+- **Hierarchy descends.** Type scale strictly decreases with nesting depth.
+  Never give a child element a larger scale than its parent context.
+- **Density has a budget.** State the budget per surface (for example: at most
+  N data points per viewport on consumer surfaces; a higher N on operational
+  ones). When content exceeds the budget, cut or collapse — never shrink type
+  below the ramp to make room.
+- **Actions land last.** Calls to action render at the end of reading order.
+  At most one primary action per screen; never two.
+- **Separation escalates.** To separate content, reach for whitespace first,
+  then a divider, then a container — in that order, never skipping a step.
+
+Mirror each refusal here with a check under \`checks/\` that lists this
+node in its \`references\`, so review enforces the same floor this prose sets.
+`,
+            },
+            {
+                relativePath: "pattern.status-with-next-step.md",
+                content: `---
+description: Status of an ongoing thing plus the single next step — reach for this when the ask is "where is X / how is X going."
+---
+
+**This is a worked example of the pattern convention — bound, open, refines.
+Replace its content with a real pattern from your product, keep the structure.**
+
+**When this applies:** the ask is about the state of something in flight — an
+order, a transfer, a build, a goal.
+
+**Bound (decided — do not redecide):**
+
+- The current status renders first and largest; it is the focal point.
+- A short line of meaning follows the status: why it matters or what changed,
+  never a restatement of it.
+- Exactly one primary action, rendered last: the single next step.
+
+**Open (your call, within these limits):**
+
+- Supporting evidence may be a timeline or a compact stat list — whichever
+  fits the data. Never a full chart in this pattern.
+- Density may flex one step tighter on operational surfaces.
+
+**Refines:** \`principle.composition\`. If anything above conflicts with the
+floor, the floor wins and this file is wrong.
+
+When a blessed render of this pattern exists, add an \`exemplar.*\` node with
+\`materials\` pointing at the screenshot and the implementation path.
+`,
+            },
+            medianFile,
+        ];
+    },
+};
+const SKELETON_FILE_ORDER = new Map([
+    "glossary.md",
+    "brand.md",
+    "cliche.median.md",
+    "foundation.composition.md",
+    "foundation.color.md",
+    "foundation.type.md",
+    "foundation.controls.md",
+    "foundation.layout.md",
+    "foundation.motion.md",
+    "foundation.voice.md",
+    "context.conversation.md",
+].map((path, index) => [path, index]));
+const SKELETON_TEMPLATE = {
+    name: "skeleton",
+    description: "Naked skeleton: a brand cover, foundation chapters with open questions, and the cliche floor.",
+    async files() {
+        const skeletonFiles = [
+            ...(await loadPackedPayload("skeleton")),
+            await medianTemplateFile(),
+        ];
+        skeletonFiles.sort((a, b) => (SKELETON_FILE_ORDER.get(a.relativePath) ?? Number.MAX_SAFE_INTEGER) -
+            (SKELETON_FILE_ORDER.get(b.relativePath) ??
+                Number.MAX_SAFE_INTEGER) ||
+            a.relativePath.localeCompare(b.relativePath));
+        return [manifestFile("brand"), gitignoreFile(), ...skeletonFiles];
+    },
+};
+async function medianTemplateFile() {
+    return {
+        relativePath: "cliche.median.md",
+        content: await loadPayloadFile("median", "cliche.median.md"),
+    };
+}
+const TEMPLATES = new Map([
+    [MINIMAL_TEMPLATE.name, MINIMAL_TEMPLATE],
+    [COMPOSITION_TEMPLATE.name, COMPOSITION_TEMPLATE],
+    [SKELETON_TEMPLATE.name, SKELETON_TEMPLATE],
+]);
+const VESSEL_LIGHT_BODY = {
+    name: "vessel-light",
+    description: "Vessel's design language at full strength: corpus, tokens, fonts, refs, and checks.",
+    includesChecks: true,
+    async files() {
+        const payload = await loadPackedPayload("vessel-light");
+        payload.sort((a, b) => {
+            const ao = BODY_FILE_ORDER.get(a.relativePath);
+            const bo = BODY_FILE_ORDER.get(b.relativePath);
+            return ((ao ?? Number.MAX_SAFE_INTEGER) - (bo ?? Number.MAX_SAFE_INTEGER) ||
+                a.relativePath.localeCompare(b.relativePath));
+        });
+        // The payload carries its own manifest.yml (id stays `vessel-light`);
+        // only the gitignore is generated locally.
+        return [gitignoreFile(), ...payload];
+    },
+};
+/** Listing order for the body scaffold output: anchors first, then the rest. */
+const BODY_FILE_ORDER = new Map(["manifest.yml", "glossary.md", "index.md"].map((path, i) => [path, i]));
+const BODIES = new Map([
+    [VESSEL_LIGHT_BODY.name, VESSEL_LIGHT_BODY],
+]);
+/** Look up a registered init body by name. */
+export function getInitBody(name) {
+    return BODIES.get(name);
+}
+export function listInitBodies() {
+    return [...BODIES.keys()];
+}
+export const DEFAULT_TEMPLATE_NAME = SKELETON_TEMPLATE.name;
+/** Look up a registered init template by name. */
+export function getInitTemplate(name) {
+    // `default` and `steering` are silent aliases for the skeleton starter:
+    // `default` for callers that never named a template, `steering` for
+    // callers pinned to the pre-skeleton default's name.
+    if (name === "default" || name === "steering")
+        return SKELETON_TEMPLATE;
+    return TEMPLATES.get(name);
+}
+export function listInitTemplates() {
+    return [...TEMPLATES.keys()];
+}
+//# sourceMappingURL=templates.js.map

package/dist/scan/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/scan/templates.ts"],"names":[],"mappings":"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"}

package/dist/skill-bundle/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ghost
+description: Author, validate, consume, and review against a repo-local Ghost fingerprint — the medium-agnostic articulation of a product's brand. Use when the user wants to set up a .ghost fingerprint, write or update brand-truth nodes, gather brand context before generation, or assemble a review packet from Ghost checks.
+license: Apache-2.0
+metadata:
+  homepage: https://github.com/block/ghost
+  cli: ghost
+---
+
+# Ghost — Brand Fingerprints
+
+A Ghost fingerprint is the medium-agnostic articulation of a brand: its truths,
+its stance, its conditions, and optional pointers to the concrete materials those
+truths govern. One brand truth is stated once, at the altitude it is actually
+true, and an agent reads the relevant truths before building.
+
+```text
+.ghost/
+  manifest.yml        # schema + id (the package anchor)
+  glossary.md         # the author's kind vocabulary
+  materials/          # bundled materials; reserved, never nodes
+  <kind>.<slug>.md    # a brand truth of a declared kind
+  <slug>.md           # a brand truth without a kind
+  checks/             # optional review assertions; never nodes
+```
+
+## The model in one breath
+
+- A **node** is a markdown file: `description`, optional `materials`, and a prose
+  brand truth.
+- `materials` is one list of locators for the concrete stuff the truth is about:
+  repo-relative paths/globs or absolute HTTPS URLs. `materials/` is reserved for
+  bundled materials; reference living implementations where they already live.
+  Guidance stays in prose.
+- A node's **kind** comes from its filename prefix (`principle.density.md` →
+  kind `principle`). A bare name (`voice.md`) has no kind.
+- The **glossary** declares the kind vocabulary and what each kind means.
+- The manifest's `cover` names the node `gather` inlines above the menu every
+  time. It carries essence, temperature, and brand-only refusals. Admission
+  test: a violation visible in one element belongs in that element's chapter;
+  visible in one view, in the composition chapter; visible only across the
+  whole body of work, on the cover.
+- There is **no hierarchy, no inheritance, no edges**. Directories are for browsing
+  only; the model reads a flat menu.
+- **Checks** are optional review assertions in a flat `.ghost/checks/*.md`
+  directory. Checks are feed-back only; they never leak into generation
+  context. Each check declares `references` to node ids and is used by
+  `ghost review`. A check may
+  include `probe: <command>`; review runs it as evidence unless `--no-probes` is
+  set. Checks are never emitted by `ghost gather` or `ghost pull`.
+
+## The loop
+
+```bash
+ghost init          # scaffold .ghost/ with the steering starter
+ghost checks init   # opt in to review assertions
+ghost validate      # artifact shape + node/material/check validation
+ghost gather <ask>  # emit Available guidance for this task
+ghost pull <ids>    # pull selected node bodies and materials
+ghost review        # assemble diff + matched material-backed nodes + checks
+ghost export        # package .ghost/ as a portable brand artifact
+ghost pulse         # summarize local gather/pull events while tuning
+```
+
+`gather` does no selection. It emits the complete, unfiltered, unranked menu
+from the Ghost brand fingerprint. You read the ask against descriptions, then
+pull every applicable truth and skip inapplicable nodes. Topic overlap alone is
+not applicability. Its header includes a coverage line: total nodes and nodes
+carrying concrete material. `gather` labels materials, substantial fenced
+examples, and Skeletons separately, so an all-prose fingerprint is visible
+before generation.
+
+Prefer `ghost pull` over reading files directly: it emits the same prose,
+inlines small local materials by default, turns binary materials into
+inspect-pointers, orders the packet for steering (cover when selected,
+concrete nodes, prose rules), extracts Skeletons dead last, and appends
+structured events to `.ghost/.events` for local tuning.
+
+`review` does no grading. It assembles an advisory packet: touched files,
+matched material-backed nodes, offered checks, probe
+evidence, coverage gaps, and the diff. The host agent renders findings.
+
+## CLI verbs
+
+| Verb | Purpose |
+|---|---|
+| `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. `--with checks` also adds the checks directory. |
+| `ghost checks init` | Scaffold `.ghost/checks/` with an example review assertion. |
+| `ghost validate [file-or-dir]` | Validate manifest, nodes, material locators, check references, and glossary kind prefixes. |
+| `ghost gather [ask…] [--format json]` | Emit the complete guidance menu plus coverage line; log exposed ids. |
+| `ghost pull <id> [<id>…]` | Emit selected nodes' full bodies and materials in steering order; log selected/missed ids. |
+| `ghost review [--diff <path|->] [--base <ref>] [--format json] [--no-probes]` | Emit an advisory review packet for a diff (requires `.ghost/checks/`). |
+| `ghost export [--out <path>] [--no-checks] [--strict] [--format json]` | Package `.ghost/` as a portable brand artifact and report which material locators will not travel. |
+| `ghost pulse [--format json]` | Summarize local `.ghost/.events`. |
+| `ghost skill install` | Install this skill bundle. |
+| `ghost manifest [--format json]` | Emit a self-describing JSON manifest of every command and flag. |
+
+## Skeleton convention
+
+A `## Skeleton` section in a node contains the literal opening structure for a
+surface, usually on a `pattern.*` node. `ghost validate` warns unless each
+Skeleton section has exactly one fenced block. `ghost pull` removes Skeletons
+from the node body and emits the fences at the end under a begin-from-this banner.
+If a pulled Skeleton matches the task, start the artifact from it verbatim, then
+fill with task facts.
+
+## Receiving a fingerprint
+
+Unpack the exported archive, run `ghost validate --package <dir>`, then run
+`ghost skill install` in the receiving workspace. From there, gather and pull
+against the unpacked package with `--package <dir>`.
+
+## Workflows
+
+- Author or update the fingerprint: follow [references/capture.md](references/capture.md).
+- Author material-backed nodes: follow [references/blocks.md](references/blocks.md).
+- Choose which concrete code tiers the package carries: follow [references/concrete-tiers.md](references/concrete-tiers.md).
+- Choose the right human-agent authoring workflow: follow [references/authoring-scenarios.md](references/authoring-scenarios.md).
+- Adapt a starter (a body or the skeleton) to your brand: follow [references/adapting-a-starter.md](references/adapting-a-starter.md).
+- Gather applicable truths for a task: follow [references/recall.md](references/recall.md).
+- Shape a pre-generation brief: follow [references/brief.md](references/brief.md).
+- Probe readiness before generating: follow [references/self-check.md](references/self-check.md).
+- Audit steering coverage: follow [references/steering-audit.md](references/steering-audit.md).
+- Understand the package shape: see [references/schema.md](references/schema.md).
+
+Fingerprint authoring is **elicitation, not scanning**. The raw material is what
+the human brings and points at: words, images, links, exemplar products, brand
+docs, copy they love or hate. Repo code can supply material locators and local
+conventions, but durable brand truth should be curated by the human.
+
+## When the fingerprint is silent
+
+A silent fingerprint does not require stopping. Proceed from nearby product
+surfaces, local conventions, and ordinary reasoning when safe, and label that
+reasoning as provisional and non-Ghost-backed unless the fingerprint itself
+declares a stricter silence posture (check the cover), which overrides
+this default. Ask a human before high-risk, irreversible, privacy, security,
+legal, or brand-defining choices.
+
+## Never
+
+- Never invent hierarchy, inheritance, or cross-node edges.
+- Never file a truth by destination (`for-emails.md`); state its condition in prose.
+- Never put guidance in `materials`; it belongs in the node body.
+- Never gather checks as generation context.
+- Never claim provisional or local-convention reasoning as Ghost-backed.

package/dist/skill-bundle/references/adapting-a-starter.md

@@ -0,0 +1,104 @@
+---
+name: adapting-a-starter
+description: Transplant a starter fingerprint — a body like vessel-light or the naked skeleton — into your own brand, one procedure from manifest id to regenerated refs.
+handoffs:
+  - label: Validate the adapted package
+    command: ghost validate --format json
+    prompt: Does the adapted fingerprint validate, and did any pruned rule orphan a check reference?
+---
+
+# Recipe: Adapt A Starter Fingerprint
+
+**Goal:** turn an installed starter — a full body (`ghost init --body
+vessel-light`) or the naked skeleton (`ghost init`) — into *your* brand's
+fingerprint without shipping a self-contradicting package.
+
+The naked skeleton is factored by what must happen during adaptation:
+
+| Stratum | Files | On adaptation |
+| --- | --- | --- |
+| Cover | `brand.md` | Write it — essence in one paragraph, temperature, and brand-only refusals. Apply the admission test to every line: a violation visible in one element belongs in that element's chapter; visible in one view, in the composition chapter; visible only across the whole body of work, here. Keep a one-screen budget and delete every scaffolding sentence when real. |
+| Foundation | `foundation.*` | Answer each chapter's open section (`Palette`, `Typeface`, `Radius`, `Character`, `Warmth`), restate it as the brand's current answer, and edit misuse lists to the brand's real failure modes. |
+| Context | `context.*` | Add or re-tune after the open questions are answered; context nodes state only what inverts in a matching situation. |
+| Cliche floor | `cliche.*` | Prune — delete entries a foundation misuse list absorbs, delete the paired check flag with it, and replace generic entries with refusals only this brand makes. If a refusal passes the cover admission test, graduate it to `brand.md`. |
+| Materials and refs | `materials/*`, referenced implementations, refs | Add or regenerate so the prose has concrete material to inspect. |
+| Checks | `checks/*` | Keep paired with the nodes they enforce; delete or rewrite flags when their source rule changes. |
+
+Do the steps **in order and in one sitting** where possible. A half-adapted
+package is worse than an unadapted one: stale refs steer harder than any prose
+you rewrote, so stopping before refs and checks are current ships a fingerprint
+that contradicts itself.
+
+## The procedure
+
+1. **Change the manifest id.** Edit `id:` in `manifest.yml` to your brand's
+   name. This is deliberately first: it is the explicit act that marks the
+   adaptation as begun. Until it changes, the package honestly claims to be the
+   starter, and every consuming agent cites it as a starter default.
+2. **Write the cover.** Replace `brand.md` with the brand's essence in one
+   paragraph, the shared temperature of words and motion, and the refusals only
+   this brand makes. Test every line: a violation visible in one element moves
+   to that element's chapter; visible in one view, to the composition chapter;
+   only what shows solely across the whole body of work stays. Keep the cover
+   to one screen and delete every scaffolding sentence when it is real.
+3. **Answer the foundation chapters.** Walk each `foundation.*` node. Keep the
+   usage rules that describe the closed vocabulary; answer the open section as
+   the brand's current answer. Ask the human for undecided values; never
+   freehand a value and present it as brand-backed. Edit each misuse list to the
+   failures this brand actually needs to avoid.
+4. **Add or edit materials.** Record literal values where the implementation or
+   asset materials live, then add `materials` locators to the nodes that explain
+   them. Role names can stay stable while values change. The point is that a
+   realizing agent can inspect the same concrete source the prose governs.
+5. **Re-tune contexts.** Revisit each `context.*` node after the foundation
+   answers exist. Keep only inversions that apply in that situation; delete
+   generic foundation rules repeated there, and add new contexts only when a
+   task situation truly bends the defaults.
+6. **Prune `cliche.median`.** Each rule is a `###` heading section; delete the
+   whole section for every rule a foundation misuse list now absorbs or your
+   brand legitimately violates. Do not rewrite surviving measured defaults into
+   taste. Then run `ghost validate`: every check reference orphaned by a pruned
+   heading surfaces as its own warning — delete the paired flag and its
+   reference from the check.
+7. **Regenerate refs.** Exemplars dominate prose: a prose rule contradicted by a
+   stale ref loses. Rebuild each ref against the new values and chapter answers,
+   keep any annotation headers current, and make each ref demonstrate its closed
+   sets completely. If the starter shipped no refs, generate them now — a
+   fingerprint with no exemplars steers at half strength.
+8. **Rewrite checks and near-miss nodes.** For each answered foundation chapter,
+   name the failure mode one step away from the answer and its replacement. Put
+   pre-generation guidance in nodes and review assertions in `checks/`; never
+   leave a check that asserts an obligation no node states.
+9. **Re-run the checks, including against refs.** `ghost validate` for package
+   shape, then review the regenerated refs against the median and value checks
+   (stage the ref changes and run `ghost review`). The floor only holds if the
+   refs hold it too: a ref that trips a median flag will teach every future
+   generation the violation.
+
+## Consuming an unadapted starter
+
+Work does not block on adaptation. Before the procedure runs (or midway through
+it), cite starter content honestly:
+
+- Cover scaffolding and unanswered foundation sections: **provisional** — never
+  plain brand truth.
+- Foundation usage rules: **Ghost-backed starter structure** until the human
+  answers the open sections and edits the misuse lists.
+- Surviving median rules: **owner-backed after init** — Ghost stamps this
+  measured model truth into every initialized package; you own the pruning and
+  any adaptation thereafter.
+- Context nodes: **conditional** — read only when their situation matches, and
+  revisit them after the foundation answers change.
+- The manifest id tells you which state you are in: a starter id means
+  unadapted.
+
+## Never
+
+- Never leave cover scaffolding in a real fingerprint.
+- Never present your provisional value as the brand's answer.
+- Never leave stale refs alongside new values — regenerate or delete; a stale
+  exemplar outweighs rewritten prose.
+- Never prune a median rule without deleting its paired check flag, or keep a
+  check that asserts an obligation no node states.
+- Never pre-write the manifest id change into automation — it is the human's
+  act of ownership, the one step an agent should not take alone.