Rename node retrieval frontmatter field to for

[nahiyankhan]

Category: improvement
User Impact: Ghost package nodes declare their retrieval payload with a for: frontmatter field: the situation or activity the guidance is for. Near-miss keys (context, description) are rejected with a pointer to for.
Problem: #252 renamed the node retrieval field from description to context, but context reads as the mechanism (what ends up in the model's context) rather than the payload itself, and it collides with the everyday "context" vocabulary used throughout ghost's own prose. description was semantically loose in the other direction: the field's content never describes the node, it names when the node applies. The team converged on for.
Solution: A forward rename to for rather than a revert. Every value in the corpora already completes the sentence "this guidance is for ___" (for: Choosing or applying color., for: Any view containing text or actions.), so the field teaches itself from its own values. for is canonical across the schema, catalog, embed API, CLI output, lint rules, corpora, and docs. Authoring context: or description: fails validation with a pointer to the right key ("description is not a node key; use for"), mirroring the existing relates rejection pattern; without the explicit rejection, the passthrough schema would let an old key ride along silently and leave the node invisible to gather. Check frontmatter keeps its own description field: that is the established .agents/checks format, not the node schema. The skill prose adds the one guardrail for needs: it names a situation or activity, never an audience.

Validation:

• pnpm build: pass
• pnpm test: 211/211 pass (adds rejection tests for both near-miss keys)
• pnpm check: pass (biome, typecheck, terminology, package checks)
• Smoke tests: fresh ghost init (skeleton and vessel-light bodies) validates clean and emits for:; nodes authored with context: or description: fail validation with the pointer to for; all three in-repo corpora (apps/docs, vessel-light, vessel-react) validate with no new findings.

Changeset: added (minor) — public CLI/embed output shape and validation behavior change.

ghost Review:

• ghost review: not run — no root .ghost/checks/ directory in this repo.

File changes

.changeset/rename-retrieval-field-to-for.md
New minor changeset describing the field and the rejection behavior.

packages/ghost/src/ghost-core/node/schema.ts, types.ts, serialize.ts
for is the canonical frontmatter field. context and description are rejected keys that point to for. Key order is for, materials.

packages/ghost/src/ghost-core/catalog/types.ts, menu.ts, assemble.ts, closest.ts
Catalog nodes and menu entries carry for.

packages/ghost/src/embed/types.ts, gather.ts, pull.ts
Embed API emits for; coverage field is withoutFor; gather selection instruction updated.

packages/ghost/src/commands/gather-command.ts, pull-command.ts
CLI markdown/JSON output uses for; coverage line says "N lack for payloads".

packages/ghost/src/review/baseline.ts, review-packet.ts
Review packet and baseline prose carry for.

packages/ghost/src/scan/fingerprint-package-lint.ts
Lint rule is node-for-missing.

packages/ghost/src/skill-bundle/ (SKILL.md, references/schema.md, nodes.md, making.md, ground.md, steering-audit.md)
Skill prose teaches for as the retrieval payload: the situation or activity the guidance is for, never an audience.

packages/ghost/src/init-payloads/ (median, skeleton)
Scaffolded nodes author for:. The median-tells check keeps its check-format description field.

packages/ghost/test/ (cli.test.ts, cli-exit.test.ts, embed.test.ts, fingerprint-package.test.ts, ghost-core/node-schema.test.ts)
Node fixtures author for:; rejection tests cover both near-miss keys. Check fixtures keep description (check format).

apps/docs/.ghost/ (9 nodes), packages/vessel-light/.ghost/ (18 nodes), packages/vessel-react/.ghost/ + fingerprint/ (25 nodes)
Mechanical frontmatter rename to for:.

apps/docs/src/components/docs/gather-demo.tsx, apps/docs/src/pages/index.astro
Demo menu data and landing-page examples use for.

packages/context-control/README.md, lib/model.mjs, ui/index.html
Bench consumes the renamed menu field; coverage line reads withoutFor.

README.md, CLAUDE.md, docs/purposes.md
Docs describe for as the retrieval payload.

Screenshots/Demos: N/A