Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/docs-entrance-accuracy-pass.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@design-intelligence/ghost": patch
---

Refresh the entrance docs: accurate skeleton/body init descriptions, a documented `ghost export`, and plainer language on the welcome path.
2 changes: 0 additions & 2 deletions .ghost/.gitignore

This file was deleted.

19 changes: 0 additions & 19 deletions .ghost/anti-goal.surface-sprawl.md

This file was deleted.

19 changes: 0 additions & 19 deletions .ghost/decision.flat-corpus.md

This file was deleted.

24 changes: 0 additions & 24 deletions .ghost/glossary.md

This file was deleted.

29 changes: 0 additions & 29 deletions .ghost/index.md

This file was deleted.

2 changes: 0 additions & 2 deletions .ghost/manifest.yml

This file was deleted.

28 changes: 0 additions & 28 deletions .ghost/principle.byoa-boundary.md

This file was deleted.

25 changes: 0 additions & 25 deletions .ghost/principle.voice.md

This file was deleted.

12 changes: 11 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +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`. |
| `apps/docs` | no | Docs site. |

## CLI Commands
Expand All @@ -99,13 +100,14 @@ Core workflow:

| Command | Description |
| --- | --- |
| `ghost init` | Scaffold `.ghost/` with a manifest, starter glossary, and a starter `index.md`. `--with checks` also adds the checks directory. |
| `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 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. |
| `ghost pull <id> [<id>…]` | Emit selected nodes' bodies and materials; append the selection to the local `.ghost/.events` tape. |
| `ghost review` | Emit an advisory review packet for a diff using material-backed nodes and checks (requires `.ghost/checks/`). |
| `ghost pulse` | Summarize local gather/pull events from `.ghost/.events`. |
| `ghost export` | Package the fingerprint as a portable tarball with a materials audit (`--strict` fails on stranded locators). |
| `ghost skill install` | Install the unified `ghost` skill bundle. |

Advanced/maintenance:
Expand Down Expand Up @@ -151,6 +153,14 @@ Use `patch` for fixes and docs, `minor` for new commands/flags/exports, and

## Conventions

- Shipped prose is plain, precise, restrained, and product-minded. When
completeness and compactness compete, compactness wins; link out for depth.
Concrete over aspirational: name the decision a truth forces, not the value
it serves. Teach terms by worked example before defining them. No em dashes,
no brand-deck filler, no exclamation points. `scripts/check-terminology.mjs`
enforces the retired-vocabulary list; run `pnpm check:terminology` before
pushing, and when renaming a concept, retire the old word everywhere in the
same change and add it to the forbidden list.
- Keep publishable runtime code self-contained in `packages/ghost`; no
`workspace:*` runtime dependencies in the packed public artifact.
- The canonical on-disk form is a flat `.ghost/` package: `manifest.yml` plus
Expand Down
22 changes: 12 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
# Contributing to Ghost

Ghost is pre-1.0 and moving fast. This doc is organized around what gets a
PR declined, because that's the information you actually need. Everything
below is enforced — by review, by CI, or both.
Contributions are welcome: fixes, docs, dogfooding reports, and friction you
hit as a user are all valuable. Ghost is pre-1.0 and moving fast, so this doc
is organized around what gets a PR declined, because that's the information
you need. Everything below is enforced by review, by CI, or both.

## Invariants

These are project-defining. A PR that violates one gets declined regardless
of quality elsewhere.

1. **The CLI computes; it never decides.** No LLM calls in the CLI, ever.
Ghost is BYOA: the host agent does all interpretive work. The CLI's value
is determinism — same input, same output, no key required.
Ghost is BYOA (bring your own agent): the host agent does all interpretive
work. The CLI's value is determinism: same input, same output, no key
required.
2. **The fingerprint corpus stays flat.** No hierarchy, no inheritance, no
edges between nodes. A node's identity is its filename; its kind is a
glossary-declared prefix. Altitude lives in prose, not structure.
Expand All @@ -26,12 +28,12 @@ of quality elsewhere.
`scripts/check-terminology.mjs` fails CI on banned phrasings. The script is
the source of truth; these are the clusters and their reasons:

- **The "memory" compounds.** Ghost holds nothing an agent holds nothing it
- **The "memory" compounds.** Ghost holds nothing; an agent holds nothing it
isn't handed. The fingerprint is a steering packet, not recall.
- **The "judg-" words.** The CLI computes; the host agent decides. Review
output is advisory.
- **Product-UI-centric framing.** Ghost is brand through every medium
screens, emails, empty states, sentences so phrases that anchor it to
- **Product-UI-centric framing.** Ghost is brand through every medium
(screens, emails, empty states, sentences), so phrases that anchor it to
product UI alone are banned.
- **Bare next-major version markers.** No speculative roadmap language in
the tree.
Expand All @@ -48,7 +50,7 @@ the list.
- Added, removed, or renamed a CLI command or flag? Run `pnpm dump:cli-help`
and commit the regenerated manifest, or the drift check declines for you.
- **Changesets:** `@design-intelligence/ghost` is the only public
package. Write the changeset file yourself `patch` for fixes and docs,
package. Write the changeset file yourself: `patch` for fixes and docs,
`minor` for new commands/flags/exports, `major` for removed or renamed
public behavior. One sentence, user-facing, present tense.

Expand All @@ -57,7 +59,7 @@ the list.
Surfaces in this repo carry their own fingerprints: `apps/docs/.ghost` and
`packages/vessel-react/.ghost`. If you touch a surface, `ghost gather` from its
fingerprint before you build, and expect review against it. This is where
you experience Ghost as a user treat friction you hit here as a bug worth
you experience Ghost as a user; treat friction you hit here as a bug worth
reporting.

## Governance
Expand Down
Loading
Loading