@design-intelligence/ghost 0.20.0

package/dist/scan/tarball.js

@@ -0,0 +1,145 @@
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { gzipSync } from "node:zlib";
+const BLOCK_SIZE = 512;
+/**
+ * Write a dependency-free `.tgz` archive for a Ghost package directory.
+ *
+ * This intentionally implements only the portable subset Ghost needs: ustar
+ * regular-file entries, deterministic path ordering, no symlink traversal.
+ */
+export async function writeDirectoryTarball(options) {
+    const files = await listRegularFiles(options.rootDir, options.exclude);
+    const fileEntries = await Promise.all(files.map(async (file) => ({
+        path: file.path,
+        data: await readFile(file.absolutePath),
+        mtime: file.mtime,
+        mode: file.mode,
+    })));
+    const archive = createTarArchive([
+        ...(options.extraEntries ?? []),
+        ...fileEntries,
+    ]);
+    await writeFile(options.outFile, gzipSync(archive));
+}
+export function createTarArchive(entries) {
+    const sorted = entries
+        .map(normalizeEntry)
+        .sort((a, b) => a.path.localeCompare(b.path));
+    const chunks = [];
+    for (const entry of sorted) {
+        const data = Buffer.isBuffer(entry.data)
+            ? entry.data
+            : Buffer.from(entry.data, "utf-8");
+        chunks.push(createHeader({
+            path: entry.path,
+            size: data.byteLength,
+            mode: entry.mode ?? 0o644,
+            mtime: entry.mtime ?? new Date(0),
+        }));
+        chunks.push(data);
+        const remainder = data.byteLength % BLOCK_SIZE;
+        if (remainder !== 0)
+            chunks.push(Buffer.alloc(BLOCK_SIZE - remainder));
+    }
+    chunks.push(Buffer.alloc(BLOCK_SIZE * 2));
+    return Buffer.concat(chunks);
+}
+async function listRegularFiles(rootDir, exclude) {
+    const files = [];
+    await walk(rootDir, rootDir, exclude, files);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return files;
+}
+async function walk(rootDir, dir, exclude, files) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const absolutePath = join(dir, entry.name);
+        const relPath = normalizeTarPath(relative(rootDir, absolutePath));
+        if (exclude?.(relPath))
+            continue;
+        if (entry.isDirectory()) {
+            await walk(rootDir, absolutePath, exclude, files);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const s = await stat(absolutePath);
+        if (!s.isFile())
+            continue;
+        files.push({
+            path: relPath,
+            absolutePath,
+            size: s.size,
+            mode: s.mode & 0o777,
+            mtime: s.mtime,
+        });
+    }
+}
+function normalizeEntry(entry) {
+    const path = normalizeTarPath(entry.path);
+    if (path === "" || path.startsWith("../") || path.includes("/../")) {
+        throw new Error(`Invalid tar entry path: ${entry.path}`);
+    }
+    return { ...entry, path };
+}
+function createHeader(entry) {
+    const header = Buffer.alloc(BLOCK_SIZE, 0);
+    const path = splitUstarPath(entry.path);
+    writeString(header, path.name, 0, 100);
+    writeOctal(header, entry.mode, 100, 8);
+    writeOctal(header, 0, 108, 8);
+    writeOctal(header, 0, 116, 8);
+    writeOctal(header, entry.size, 124, 12);
+    writeOctal(header, Math.floor(entry.mtime.getTime() / 1000), 136, 12);
+    header.fill(0x20, 148, 156);
+    writeString(header, "0", 156, 1);
+    writeString(header, "ustar", 257, 6);
+    writeString(header, "00", 263, 2);
+    if (path.prefix !== undefined)
+        writeString(header, path.prefix, 345, 155);
+    const checksum = header.reduce((sum, byte) => sum + byte, 0);
+    writeChecksum(header, checksum);
+    return header;
+}
+function splitUstarPath(path) {
+    const byteLength = Buffer.byteLength(path);
+    if (byteLength <= 100)
+        return { name: path };
+    const parts = path.split("/");
+    for (let index = 1; index < parts.length; index++) {
+        const prefix = parts.slice(0, index).join("/");
+        const name = parts.slice(index).join("/");
+        if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) {
+            return { prefix, name };
+        }
+    }
+    throw new Error(`Tar entry path is too long for ustar: ${path}`);
+}
+function writeString(buffer, value, offset, length) {
+    const bytes = Buffer.from(value, "utf-8");
+    if (bytes.byteLength > length) {
+        throw new Error(`Tar header value is too long: ${value}`);
+    }
+    bytes.copy(buffer, offset);
+}
+function writeOctal(buffer, value, offset, length) {
+    const text = value.toString(8).padStart(length - 1, "0");
+    if (text.length > length - 1) {
+        throw new Error(`Tar numeric value is too large: ${value}`);
+    }
+    buffer.write(text, offset, length - 1, "ascii");
+}
+function writeChecksum(buffer, checksum) {
+    const text = checksum.toString(8).padStart(6, "0");
+    buffer.write(text, 148, 6, "ascii");
+    buffer[154] = 0;
+    buffer[155] = 0x20;
+}
+function normalizeTarPath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+export function defaultArchiveName(id) {
+    return `${id}-fingerprint.tgz`;
+}
+//# sourceMappingURL=tarball.js.map

package/dist/scan/tarball.js.map

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

package/dist/scan/templates.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A single seed file an `init` template writes, relative to the package dir.
+ */
+export interface TemplateFile {
+    /** Path relative to the package directory (e.g. "principle.voice.md"). */
+    relativePath: string;
+    content: string;
+}
+/**
+ * An `init` template: a pure description of the seed files a fresh node package
+ * starts with. Templates are the extension seam — adding a `marketing` / `voice`
+ * / `dashboard` starter later is just registering another entry here; `init`
+ * needs no change.
+ */
+export interface GhostInitTemplate {
+    name: string;
+    description: string;
+    files(): TemplateFile[];
+}
+export declare const DEFAULT_TEMPLATE_NAME: string;
+/** Look up a registered init template by name. */
+export declare function getInitTemplate(name: string): GhostInitTemplate | undefined;
+export declare function listInitTemplates(): string[];
+//# sourceMappingURL=templates.d.ts.map

package/dist/scan/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/scan/templates.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AACD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,IAAI,YAAY,EAAE,CAAC;CACzB;AAkSD,eAAO,MAAM,qBAAqB,QAAyB,CAAC;AAE5D,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAG3E;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C"}

package/dist/scan/templates.js

@@ -0,0 +1,295 @@
+import { GHOST_FINGERPRINT_PACKAGE_SCHEMA } from "#ghost-core";
+import { GHOST_EVENTS_FILENAME, LEGACY_PULL_HISTORY_FILENAME, } from "./constants.js";
+import { createSteeringTemplate } from "./steering-template.js";
+function manifestFile() {
+    return {
+        relativePath: "manifest.yml",
+        content: `schema: ${GHOST_FINGERPRINT_PACKAGE_SCHEMA}\nid: local\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` node. 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 index node.",
+    files() {
+        return [
+            manifestFile(),
+            gitignoreFile(),
+            {
+                relativePath: "glossary.md",
+                content: `---
+kinds:
+  - name: principle
+  - name: condition
+  - name: exemplar
+  - name: anti-goal
+  - name: asset
+  - name: pattern
+#  - { name: provocation, posture: wild, purpose: a deliberate provocation past the fingerprint — surfaced only on request }
+---
+
+# 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.
+
+# 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. This node is the only one an agent is told to always pull,
+so 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 an ordinary node in every mechanical sense — everything below the
+\`---\` is its body; the frontmatter above is the retrieval description. Its
+privilege is pure convention: the recipes tell agents to pull it first.
+
+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.
+`,
+            },
+        ];
+    },
+};
+/**
+ * The composition starter: everything in `minimal`, plus a worked composition
+ * ladder — an invariants floor (`principle.composition`), one bound/open
+ * pattern, and an index 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.",
+    files() {
+        return [
+            manifestFile(),
+            gitignoreFile(),
+            {
+                relativePath: "glossary.md",
+                content: `---
+kinds:
+  - name: principle
+  - name: condition
+  - name: exemplar
+  - name: anti-goal
+  - name: asset
+  - name: pattern
+#  - { name: provocation, posture: wild, purpose: a deliberate provocation past the fingerprint — surfaced only on request }
+---
+
+# 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.
+
+# 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.
+`,
+            },
+        ];
+    },
+};
+const STEERING_TEMPLATE = createSteeringTemplate({
+    manifestFile,
+    gitignoreFile,
+});
+const TEMPLATES = new Map([
+    [MINIMAL_TEMPLATE.name, MINIMAL_TEMPLATE],
+    [COMPOSITION_TEMPLATE.name, COMPOSITION_TEMPLATE],
+    [STEERING_TEMPLATE.name, STEERING_TEMPLATE],
+]);
+export const DEFAULT_TEMPLATE_NAME = STEERING_TEMPLATE.name;
+/** Look up a registered init template by name. */
+export function getInitTemplate(name) {
+    if (name === "default")
+        return STEERING_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":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAoBhE,SAAS,YAAY;IACnB,OAAO;QACL,YAAY,EAAE,cAAc;QAC5B,OAAO,EAAE,WAAW,gCAAgC,eAAe;KACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa;IACpB,OAAO;QACL,YAAY,EAAE,YAAY;QAC1B,OAAO,EAAE,GAAG,qBAAqB,KAAK,4BAA4B,IAAI;KACvE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,gBAAgB,GAAsB;IAC1C,IAAI,EAAE,SAAS;IACf,WAAW,EACT,mEAAmE;IACrE,KAAK;QACH,OAAO;YACL,YAAY,EAAE;YACd,aAAa,EAAE;YACf;gBACE,YAAY,EAAE,aAAa;gBAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqChB;aACM;YACD;gBACE,YAAY,EAAE,UAAU;gBACxB,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BhB;aACM;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,oBAAoB,GAAsB;IAC9C,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,2FAA2F;IAC7F,KAAK;QACH,OAAO;YACL,YAAY,EAAE;YACd,aAAa,EAAE;YACf;gBACE,YAAY,EAAE,aAAa;gBAC3B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+ChB;aACM;YACD;gBACE,YAAY,EAAE,UAAU;gBACxB,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BhB;aACM;YACD;gBACE,YAAY,EAAE,0BAA0B;gBACxC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BhB;aACM;YACD;gBACE,YAAY,EAAE,kCAAkC;gBAChD,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BhB;aACM;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;IAC/C,YAAY;IACZ,aAAa;CACd,CAAC,CAAC;AAEH,MAAM,SAAS,GAAG,IAAI,GAAG,CAA4B;IACnD,CAAC,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC;IACzC,CAAC,oBAAoB,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACjD,CAAC,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,CAAC;CAC5C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC,IAAI,CAAC;AAE5D,kDAAkD;AAClD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,iBAAiB,CAAC;IACjD,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/B,CAAC"}

package/dist/skill-bundle/SKILL.md

@@ -0,0 +1,140 @@
+---
+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, what each kind means, and optional consumption posture: `steady` by default, `posture: wild` for truths that require explicit request, or `posture: guard` for review-critical anti-goals with positive replacement.
+- The starter `index.md` node (id `index`) is the human-curated front door:
+  by convention it carries the non-negotiables and reading posture, and agents
+  pull it first.
+- 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 the fingerprint menu for this task
+ghost pull <ids>    # read 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 menu and you read the ask against it,
+then pull the truths you judge relevant. Its header includes a coverage line —
+total nodes, nodes carrying concrete material, and guards — so an all-prose or
+unrouted 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 (`index`, concrete nodes,
+prose rules, guards), 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, matched guard 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 steering starter: manifest, glossary, `index.md`, and demo nodes for stance, composition, anti-goals, patterns, exemplars, materials, and decisions. `--template minimal` writes only the small manifest/glossary/index 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…] [--wild] [--format json]` | Emit the node menu for selection plus coverage line; log exposed ids. Default gather excludes wild kinds unless `--wild` is explicit. |
+| `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 the right human-agent authoring workflow: follow [references/authoring-scenarios.md](references/authoring-scenarios.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).
+- Explore deliberate provocations with wild nodes: follow [references/wild.md](references/wild.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 `index` node), 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.