@magic-spells/constellation 0.2.2 → 0.3.0

package/README.md

@@ -38,6 +38,7 @@ Requires Node ≥ 22.
 ```sh
 constellation init          # scaffold constellation/ with a starter plan.md
 constellation lint          # validate handles, references, folders, schemas
+constellation rename A-X A-Y  # rename a card + rewrite every reference to it
 constellation mcp           # run the MCP server (stdio) for AI agents
 constellation serve         # open the local viewer (editable; --readonly to disable)
 constellation repos         # list sibling repos declared in connected_repos
@@ -53,12 +54,11 @@ unknown fields, dangling prose links) don't block.
 
 | Path | What |
 |---|---|
-| `docs/001-file-format.md` | The normative format spec |
-| `docs/002-mcp.md` | MCP design: tool surface, hydration, write semantics, git layer |
+| `constellation/` | Constellation's own plan — the format spec, MCP design, and architecture as connected cards (formerly `docs/`); also a flagship real-world plan |
 | `schemas/` | JSON Schemas: `card.json` (reserved keys) + one per type |
 | `skill/` | AI authoring skill: `SKILL.md` + per-type references with golden examples |
 | `src/core/` | Parser, reference extraction, indexer, schema validation, lint |
-| `src/cli/` | The `constellation` binary (`init`, `lint`, `mcp`, `serve`, `repos`) |
+| `src/cli/` | The `constellation` binary (`init`, `lint`, `rename`, `mcp`, `serve`, `repos`) |
 | `src/mcp/` | MCP server: hydrated retrieval, validated writes, git tools |
 | `examples/constellation/` | Golden sample plan — one card of every type, lints clean, doubles as the test fixture |
 
@@ -77,11 +77,18 @@ npm run build            # tsc → dist/
 
 - **Hydrated retrieval**: `get_card`, `search`, and `traverse` can return
   connected cards with their complete frontmatter and body in one call.
-- **Validated writes**: `create_card`, `update_card`, `delete_card`,
-  `add_connection`, `remove_connection` — every write lints and returns issues.
+  `list_cards` and `traverse` filter by status — `["planned", "building", "none"]`
+  is the backlog view (everything not yet built).
+- **Validated writes**: `create_card` / `create_cards`, `update_card`,
+  `append_note` / `edit_section` (byte-cheap memory writes), `set_verified`,
+  `rename_card` (rewrites every reference plan-wide), `delete_card`,
+  `add_connection(s)`, `remove_connection` — every write lints and returns issues.
   Body-only updates never reformat frontmatter.
+- **Queryable memory**: `search` matches appended note text; `list_notes` lists
+  notes across cards by kind (every gotcha / decision in one call).
 - **Git-powered change tracking**: `diff_plan` (per-card changes since the sync
-  marker), `plan_log`, `set_sync_point`, `check_integrity`.
+  marker), `plan_log`, `set_sync_point`, `stale_report` / `check_sync`
+  (bound-code drift since a card was verified), `check_integrity`.
 - **Connected repos (multi-repo)**: a plan can declare sibling repos
   (`add_connected_repo` / `list_connected_repos` / `remove_connected_repo`); every
   tool takes an optional `repo` selector to read or write a sibling's plan. Omit it

package/constellation/agent/AGENT-GUIDANCE.md

@@ -0,0 +1,22 @@
+---
+name: Agent guidance (three copies)
+kind: policy
+status: built
+code_refs:
+  - skill/SKILL.md
+  - skill/methodology.md
+---
+
+# Agent guidance
+
+How AI agents are taught to use Constellation. The guidance lives in **three unshared copies
+that must stay consistent**: the MCP `INSTRUCTIONS` string ([[FILE-MCP-SERVER]]) and the skill
+(`skill/SKILL.md` + `skill/methodology.md`). None imports another, so any change to how an
+agent should use the plan must land in all three.
+
+Core stance: treat the plan as **durable, cross-session memory** (read the neighborhood before
+changing code; update cards as part of "done"); be **plan-first** when changing behavior
+(express the end state as cards, get sign-off on the plan diff, then bring code up to match —
+[[FLOW-SYNC-PLAN]]); act as an **orchestrator** for large work (partition into file-disjoint
+neighborhoods, one card per agent, then verify). `skill/methodology.md` also backs the MCP
+`bootstrap_plan` / `audit_plan` prompts. See [[DOC-MCP-UPGRADES]] for the why.

package/constellation/component/COMPONENT-EDITABLE.md

@@ -0,0 +1,9 @@
+---
+name: Editable
+kind: ui
+status: built
+code_refs:
+  - viewer/src/components/Editable.svelte
+---
+
+Inline-edit wrapper: click to edit a field or the body, saves through the serve PATCH endpoint with an `if_mtime` stale-write guard ([[FILE-SERVE]]).

package/constellation/component/COMPONENT-STATUS-PILL.md

@@ -0,0 +1,9 @@
+---
+name: StatusPill
+kind: ui
+status: built
+code_refs:
+  - viewer/src/components/StatusPill.svelte
+---
+
+Card status picker (`planned` → `building` → `built` → `verified`); PATCHes through the write API ([[FILE-SERVE]]).

package/constellation/component/COMPONENT-SYNC-PILL.md

@@ -0,0 +1,9 @@
+---
+name: SyncPill
+kind: ui
+status: built
+code_refs:
+  - viewer/src/components/SyncPill.svelte
+---
+
+Glanceable freshness pill — renders `computeSyncStatus` ([[FILE-SYNC]]) state (in-sync / drifted / dirty / never-synced), including the marker-unreachable case.

package/constellation/diagram/DIAGRAM-ARCHITECTURE.md

@@ -0,0 +1,28 @@
+---
+name: Architecture pipeline
+kind: flowchart
+status: built
+---
+
+# Architecture
+
+One direction: **files → index → (lint | serve | mcp)**. Every consumer reloads the index from
+disk per operation, so it's always correct under parallel edits.
+
+```mermaid
+flowchart TD
+  files["constellation/ files"] --> FILE-INDEXER
+  FILE-PARSE --> FILE-INDEXER
+  FILE-EXTRACT --> FILE-INDEXER
+  FILE-HANDLES --> FILE-INDEXER
+  FILE-VALIDATE --> FILE-LINT
+  FILE-INDEXER --> FILE-LINT
+  FILE-INDEXER --> FILE-MCP-SERVER
+  FILE-INDEXER --> FILE-SERVE
+  FILE-LINT --> FILE-CLI
+  FILE-MCP-SERVER --> FILE-CODE
+  FILE-MCP-SERVER --> FILE-GIT
+  FILE-MCP-SERVER --> FILE-WRITER
+  FILE-SERVE --> FILE-WRITER
+  FILE-SERVE --> PAGE-VIEWER-HOME
+```

package/constellation/doc/DOC-CARD-TYPES.md

@@ -0,0 +1,36 @@
+---
+name: The 17 card types
+kind: reference
+status: built
+---
+
+# The 17 card types
+
+The prefix before the first dash determines a card's type and must be one of these 17. Folder
+placement matches the type (a misfiled card warns W001, not errors — the prefix is
+authoritative). Defined in [[FILE-TYPES]] (`TYPE_NAMES`) and [[FILE-HANDLES]] (`TYPE_FOLDERS`).
+
+| Type | Prefix | Folder | What it is |
+|---|---|---|---|
+| API | `API-` | `api/` | HTTP/RPC endpoints |
+| DB | `DB-` | `db/` | Database tables / collections |
+| DATATYPE | `DATATYPE-` | `datatype/` | Data type schemas (interfaces, Zod, etc.) |
+| ROLE | `ROLE-` | `role/` | User roles / permission groups |
+| DOC | `DOC-` | `doc/` | Documentation cards |
+| FILE | `FILE-` | `file/` | Source file references (require `path`) |
+| TEST | `TEST-` | `test/` | Test specs |
+| EXTERNAL | `EXTERNAL-` | `external/` | External services / integrations |
+| EVENT | `EVENT-` | `event/` | Domain events / signals |
+| COMPONENT | `COMPONENT-` | `component/` | Reusable UI components |
+| PAGE | `PAGE-` | `page/` | Frontend routes / screens |
+| JOB | `JOB-` | `job/` | Background / scheduled / queued work |
+| FLOW | `FLOW-` | `flow/` | Multi-step sequenced processes |
+| STATE | `STATE-` | `state/` | State machines |
+| DIAGRAM | `DIAGRAM-` | `diagram/` | Architecture diagrams |
+| AGENT | `AGENT-` | `agent/` | AI agent instructions / policies |
+| PLAN | `PLAN-` | `plan/` | Plan documents (`plan.md` = PLAN-PROJECT) |
+
+**Adding or renaming a type touches four places that must agree:** `TYPE_NAMES`
+([[FILE-TYPES]]) + `TYPE_FOLDERS` ([[FILE-HANDLES]]); `schemas/<folder>.json`;
+`skill/types/<folder>.md`; and a sample card in `examples/` + this table. Each type's
+frontmatter schema + golden example is served live by the MCP `describe_type` tool.

package/constellation/doc/DOC-CHANGE-TRACKING.md

@@ -0,0 +1,26 @@
+---
+name: Change tracking & sync
+kind: spec
+status: built
+---
+
+# Change tracking & sync
+
+**What changed is git's job**, never stamped into cards: `git diff <ref> -- constellation/`
+*is* the plan diff. [[FILE-GIT]] exposes it as `diff_plan` / `plan_log`; plan changes ride
+branches and PRs, and reviewing a plan PR is the human approval gate before an AI syncs code.
+
+**Sync marker** — a reconciling agent records the last plan commit it synced code against in
+`constellation/.sync.json` (plan-global, via `set_sync_point`). [[FILE-SYNC]]'s
+`computeSyncStatus` reports `drifted` when the plan moved past the marker or code commits land
+after it, and `marker_error` → `drifted` when the marker sha is unreachable (rebase / shallow
+clone / hand-edited marker).
+
+**Lifecycle** — `status` (`planned`→`building`→`built`→`verified`) is a card property,
+orthogonal to history. Verify only against real code.
+
+**Verification provenance vs. change tracking** — the one recorded per-card baseline is
+`verified_sha` / `verified_at`: `set_verified` stamps the sha a card was checked at. That's the
+basis of a *claim*, not a change flag — and the drift *verdict* ("has the bound code moved
+since?") is recomputed live by `stale_report` / `check_sync` ([[FILE-CODE]]), never stored.
+This reconciles the "no per-card stamping" rule rather than breaking it. See [[DOC-MCP-UPGRADES]].

package/constellation/doc/DOC-CONNECTED-REPOS.md

@@ -0,0 +1,25 @@
+---
+name: Connected repos (multi-repo)
+kind: spec
+status: built
+---
+
+# Connected repos (multi-repo)
+
+A project spanning several repos declares its siblings on PLAN-PROJECT — the one cross-repo
+concept in the format, deliberately minimal. Each repo's `constellation/` is a standalone plan,
+references only its own cards, and lints clean alone; **connections never cross repos.**
+
+```yaml
+# plan.md frontmatter
+connected_repos:
+  - name: pyramid-server     # the `repo` selector (lowercase id)
+    path: ../pyramid-server  # relative to this repo's root (or absolute)
+    description: Back-end API for Pyramid.
+```
+
+Paths are local topology and are **never linted** — reachability is computed at call time.
+[[FILE-REPOS]] resolves the `repo` selector; every MCP read/write tool accepts it to target a
+sibling. **Plan resolution still never crosses a repo boundary** on its own ([[FILE-RESOLVE]])
+— a sibling is reached only when explicitly named. Management tools: `list_connected_repos`,
+`add_connected_repo` (`reciprocate` writes the reverse link too), `remove_connected_repo`.

package/constellation/doc/DOC-DIAGRAMS.md

@@ -0,0 +1,22 @@
+---
+name: Diagrams and flows
+kind: reference
+status: built
+---
+
+# Diagrams and flows
+
+Three tiers, cheapest first:
+
+1. **Derived subgraphs** — the viewer/MCP render any card's neighborhood from the real
+   connection graph on demand. Never stored, never stale. The default for "what does this area
+   look like."
+2. **Authored Mermaid** — a DIAGRAM card whose body is a mermaid block; use handles as node IDs
+   so the diagram joins the graph ([[FILE-EXTRACT]] reads them). Sequence diagrams and
+   `stateDiagram-v2` work the same way in FLOW and STATE cards.
+3. **Pinned layouts** — structured `nodes`/`edges`/`phases` with explicit positions in DIAGRAM
+   frontmatter (`schemas/diagram.json`). Only when layout carries meaning; positions make noisy
+   diffs.
+
+**FLOW cards are linear** — steps are a numbered markdown list, nested items for error/edge
+cases. Real branching belongs in a mermaid flowchart or a STATE card.

package/constellation/doc/DOC-FILE-FORMAT.md

@@ -0,0 +1,54 @@
+---
+name: File format
+kind: spec
+status: built
+---
+
+# File format
+
+Constellation stores a project's architecture plan as markdown files under a `constellation/`
+folder. Each file is one **card** — one typed piece of the plan, linked to others by
+**connections**. ("Node" is reserved for diagram elements inside DIAGRAM cards.) This is the
+normative format; the JSON Schemas in `schemas/` define per-type frontmatter and
+[[FILE-INDEXER]] is the reference implementation.
+
+## Files are handles
+
+The filename IS the handle: `api/API-TICKETS.md` defines the card `API-TICKETS`. There is no
+`handle:` or `type:` field — the path already says it. Handle grammar:
+`^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$` (3–135 chars; uppercase, digits, dashes). The prefix
+before the first dash is the type and must be one of the 17 canonical prefixes (see
+[[DOC-CARD-TYPES]]). `plan.md` at the root is the one special file — the card `PLAN-PROJECT`.
+
+## Frontmatter
+
+YAML frontmatter is optional; a card with none is valid. Four keys are **reserved**
+(`schemas/card.json`): `name`, `kind` (lowercase-slug subtype), `status`
+(`planned`→`building`→`built`→`verified`), `connections` (list of handles). Beyond those,
+card.json also defines **cross-type metadata** valid on any card, tool-managed rather than
+hand-authored: `code_refs` (code binding, `path` or `path:symbol`), `verified_sha` /
+`verified_at` (the drift baseline — see [[DOC-CHANGE-TRACKING]]), and `notes` (append-only
+typed memory `{kind,text,sha?}`). Everything else is a type-specific field. Schemas are
+permissive: almost nothing is required; unknown fields warn (W003) rather than fail.
+
+## The graph (four connection sources)
+
+[[FILE-INDEXER]] derives the connection set, in all cards, from: (1) the `connections:` list;
+(2) any handle-shaped string elsewhere in frontmatter (so `response_schema: DATATYPE-TICKET`
+connects automatically); (3) `[[HANDLE]]` wiki-links in the body; (4) handle-shaped IDs inside
+mermaid blocks. Connections are **undirected** and deduped by pair — declare on whichever card
+you're editing; the reverse view is the indexer's job, never written to disk. Extraction lives
+in [[FILE-EXTRACT]].
+
+## Body conventions
+
+Markdown narrative. DATATYPE: the type as a fenced code block. FLOW: a numbered list of steps
+(linear — branch via mermaid or a STATE card). STATE: a mermaid `stateDiagram-v2`. DIAGRAM: a
+mermaid flowchart with handles as node IDs. See [[DOC-DIAGRAMS]]. Lint codes: [[DOC-LINT-CODES]].
+
+## Deliberately not in the format
+
+No IDs but handles. No cross-repo card references (siblings link at the project level — see
+[[DOC-CONNECTED-REPOS]]). No connection kinds / directions / metadata — put nuance in prose. No
+revision/diff machinery — git does that. No required fields beyond the filename, except FILE
+cards require `path`.

package/constellation/doc/DOC-LINT-CODES.md

@@ -0,0 +1,35 @@
+---
+name: Lint codes
+kind: reference
+status: built
+---
+
+# Lint codes
+
+Errors break the graph (CLI exit 1; CI should block). Warnings are quality signals (exit 0).
+Structural codes come from [[FILE-INDEXER]]; schema codes (W002/W003) from [[FILE-VALIDATE]];
+[[FILE-LINT]] composes and sorts them.
+
+**Errors**
+
+| Code | Rule |
+|---|---|
+| E001 | Filename is not a valid handle |
+| E002 | Handle prefix is not one of the 17 canonical prefixes |
+| E003 | Duplicate handle (two files resolve to the same handle) |
+| E004 | `connections` entry is not a handle-shaped string |
+| E005 | `connections` or frontmatter-field target resolves to no card |
+| E006 | Frontmatter is not valid YAML |
+
+**Warnings**
+
+| Code | Rule |
+|---|---|
+| W001 | Card is not in the folder matching its type |
+| W002 | Frontmatter violates the type's JSON Schema |
+| W003 | Unknown frontmatter field (not a reserved/cross-type key from card.json, not in the type schema) |
+| W004 | Body `[[link]]` or mermaid reference resolves to no card |
+
+The E005/W004 split is deliberate: **structured references are contracts** (a frontmatter
+target must resolve → error); **prose references are aspirational** (a body `[[link]]` may
+point at a card not yet written → warning).

package/constellation/doc/DOC-MCP-SERVER.md

@@ -0,0 +1,59 @@
+---
+name: MCP server design
+kind: reference
+status: built
+---
+
+# MCP server
+
+`constellation mcp` (stdio) gives AI agents graph queries, hydrated retrieval, validated
+writes, and git-powered change tracking over a plan folder. It is a thin layer over
+[[FILE-MCP-SERVER]] + `src/core/`: every tool call reloads the index from disk (tens of ms at
+realistic sizes), so it is always correct while files are edited in parallel — no watcher, no
+cache invalidation. Bootstrap is folder discovery, bounded by the repo root ([[FILE-RESOLVE]]);
+a repo with no plan returns `NO_PLAN_FOUND`. The agent-facing INSTRUCTIONS string is embedded
+in the server — one of three guidance copies, see [[AGENT-GUIDANCE]].
+
+## Hydrated retrieval
+
+Any read tool can return connected cards with full data in one call — `connected: none |
+summary | full`. The acceptance test: one `get_card` returns an API card plus the complete
+content of every card connected to it (its datatypes, table, tests, docs).
+
+## Tool surface
+
+- **Read** — `get_card` (+ `code: none|paths|direct`, notes filters), `list_cards`,
+  `list_notes` (cross-card notes query by kind/handles), `search` (bodies **and** notes),
+  `traverse`, `assemble`, `describe_type` (the type reference, plan-independent).
+  `list_cards`/`traverse` filter by status (value or list; `"none"` = unset), so
+  `["planned","building","none"]` is the backlog view. On `traverse` status is a
+  *post-filter* — the walk passes through non-matching cards so a built hub never hides
+  planned work — while `types` prunes the walk itself.
+- **Write** — `create_card`, `create_cards` (batched, lints once), `update_card` (+ `if_mtime`
+  stale-write guard), `append_note`, `edit_section`, `set_verified`, `rename_card` (rename a
+  handle and rewrite every reference plan-wide, whole-token; the file moves with the prefix —
+  shared engine with the CLI `constellation rename`, [[FILE-RENAME]]),
+  `delete_card`, `add_connection`, `add_connections`, `remove_connection`. Every write reloads
+  + lints and returns the issues for the file it touched; **a card is created even when issues
+  come back** (issues are lint state, not failure). Writes are serialized per file behind an
+  in-process lock and land atomically (temp + rename); the cheap writes apply their change to
+  the file's *current* content, so concurrent small updates compose instead of clobbering.
+- **Git** — `diff_plan`, `plan_log`, `set_sync_point`, `stale_report`, `check_sync`,
+  `check_integrity` (see [[DOC-CHANGE-TRACKING]]).
+- **Viewer** — `start_viewer` / `stop_viewer` ([[PAGE-VIEWER-HOME]]).
+- **Connected repos** — `list` / `add` / `remove_connected_repo`; every tool takes a `repo`
+  selector (see [[DOC-CONNECTED-REPOS]]).
+
+## Code binding, drift & assembly
+
+A card binds to code via a connected FILE `path:` or its own `code_refs`, resolved by
+[[FILE-CODE]]. `get_card(code:"paths"|"direct")` attaches it (capped, repo-contained);
+`stale_report` / `check_sync` flag reverse drift; `assemble` builds file-disjoint work packages.
+Byte-preserving cheap writes ([[FILE-WRITER]]) make a correction cost less than a full rewrite.
+
+## What v1 tools deliberately died
+
+`expand_handles` (handles ARE the identifiers); `init_project` / `link_project` /
+`check_health` (bootstrap is finding a folder — `init_plan` just creates it);
+`read_plan` / `update_plan` (use `get_card("PLAN-PROJECT")` / `update_card`). Bulk variants were
+kept: `create_cards` / `add_connections` batch and lint once so intra-batch references resolve.

package/constellation/doc/DOC-MCP-UPGRADES.md

@@ -0,0 +1,56 @@
+---
+name: MCP upgrades & memory model
+kind: decision
+status: built
+---
+
+# MCP upgrades & memory model (decisions)
+
+The rationale behind Constellation's role as **durable, cross-session, cross-agent memory**
+for AI agents — the "003" upgrade plan, shipped in v0.2.2 (phases 0–6). This card replaces the
+former `docs/003`; it is the ADR for the memory/durability design.
+
+## Why this matters
+
+Every session an agent pays a "discovery tax" — rebuilding a mental model of the code before it
+can act. Without a place to bank that understanding it evaporates at session end and the next
+agent re-pays it. Constellation's value is that understanding **compounds**. Two failure modes
+erode it: **drift** (a card's claim silently diverges from code — a card you can't trust is
+worse than none) and **friction** (updating a card is expensive, so agents skip it, which
+*causes* drift).
+
+## Principles
+
+- **`built` is a claim that outlives its author** — claims must be re-verifiable, not taken on
+  faith. Durability, not distrust (the same reason you keep tests).
+- **Card what code can't say** — intent, decisions, current state, gotchas, cross-cutting rules.
+  Don't duplicate DDL / signatures / code; link to it (copies drift).
+- **Make the honest path the cheap path** — most drift is skipped updates; lower the cost of a
+  small correction (`append_note`, `edit_section`) and cards stay true.
+- **Purpose belongs in the intro** — the MCP instructions load every session, so framing changes
+  agent defaults more than any tool. See [[AGENT-GUIDANCE]].
+
+## Two headline capabilities
+
+**Hand me the delta** — what changed since I last looked: plan-side (`diff_plan`) and code-side
+reverse drift (`stale_report`, the core new capability). **Hand me the code behind a card** —
+attach the bound file ([[FILE-CODE]]), so an agent starts from intent + current reality in one
+call. `assemble` fuses both into a fan-out-ready work package.
+
+## Decisions on record
+
+- **Binding granularity** — FILE-`path:` is the default (zero authoring tax); optional
+  `code_refs` add precision (`path` or `path:symbol`) only where drift precision earns its keep.
+  Drift is detected at file granularity; the symbol is an informational hint.
+- **No-per-card-stamping, reconciled** — `verified_sha` is verification *provenance*, not a
+  change flag; the drift verdict stays live and unstored ([[DOC-CHANGE-TRACKING]], [[FILE-SYNC]]).
+- **Code attach is same-repo** — cards never bind across repos; reach a sibling's code via the
+  `repo` selector ([[DOC-CONNECTED-REPOS]]).
+- **Decided AGAINST a dedicated `DECISION` card type** — decisions live as data on the cards
+  they concern: an `append_note(kind: decision)`, a DOC card (`kind: decision`, like this one),
+  or a DIAGRAM. Co-location beats a separate filing system you have to remember to open.
+- **Memory must be retrievable to be memory** — `search` indexes note text alongside bodies,
+  and `list_notes` gives the cross-card view (every gotcha / every decision in one call). A
+  note that full-text search can't find would silently defeat the point of appending it.
+- **Deferred** — a structured partial-status model (`{built, pending}`); typed `notes` cover most
+  of that need for now.

package/constellation/external/EXTERNAL-AJV.md

@@ -0,0 +1,7 @@
+---
+name: ajv
+kind: library
+status: built
+---
+
+JSON Schema validation (2020 dialect) behind [[FILE-VALIDATE]] (W002/W003). Ships CJS, loaded via createRequire.

package/constellation/external/EXTERNAL-GIT.md

@@ -0,0 +1,7 @@
+---
+name: git
+kind: cli
+status: built
+---
+
+The change-tracking backbone; [[FILE-GIT]] shells out to it for diff / log / rev-list (revisions guarded by safeRev + --end-of-options).

package/constellation/external/EXTERNAL-GRAY-MATTER.md

@@ -0,0 +1,7 @@
+---
+name: gray-matter
+kind: library
+status: built
+---
+
+Frontmatter parsing in [[FILE-PARSE]].

package/constellation/external/EXTERNAL-MCP-SDK.md

@@ -0,0 +1,7 @@
+---
+name: '@modelcontextprotocol/sdk'
+kind: library
+status: built
+---
+
+The MCP protocol — stdio transport, tool/prompt registration — used by [[FILE-MCP-SERVER]].

package/constellation/external/EXTERNAL-ZOD.md

@@ -0,0 +1,7 @@
+---
+name: zod
+kind: library
+status: built
+---
+
+MCP tool input schemas in [[FILE-MCP-SERVER]].

package/constellation/file/FILE-CLI.md

@@ -0,0 +1,9 @@
+---
+name: cli/index.ts
+status: built
+path: src/cli/index.ts
+language: typescript
+summary: The constellation binary (commander)
+---
+
+Commands: `init`, `lint`, `rename`, `mcp`, `serve`, `repos`, `version`/`v`, `upgrade`. `lint` exits 1 on errors, 0 otherwise (warnings never fail), 2 when no plan is found. `rename OLD NEW` is the human-facing wrapper over [[FILE-RENAME]] — it prints the rewritten references and a lint-error count.

package/constellation/file/FILE-CODE.md

@@ -0,0 +1,9 @@
+---
+name: code.ts
+status: built
+path: src/core/code.ts
+language: typescript
+summary: Code binding + attach (same-repo, contained, capped)
+---
+
+Resolves a card's bound files — connected FILE `path:` + own `code_refs` — and attaches their contents under per-file (64 KB) and total (256 KB) caps, skipping binaries / lockfiles / generated and rejecting paths (incl. symlinks) that escape the repo root. A file over the per-file cap attaches its head with `truncated: true` rather than being skipped. Shared by `get_card` code mode, stale_report, and assemble.

package/constellation/file/FILE-EXTRACT.md

@@ -0,0 +1,9 @@
+---
+name: extract.ts
+status: built
+path: src/core/extract.ts
+language: typescript
+summary: Pull references out of a card body and frontmatter
+---
+
+Extracts the four connection sources: `[[HANDLE]]` wiki-links, handle-shaped frontmatter values, and mermaid node IDs. Only handle-shaped tokens count.

package/constellation/file/FILE-GIT.md

@@ -0,0 +1,9 @@
+---
+name: git.ts
+status: built
+path: src/core/git.ts
+language: typescript
+summary: Git plumbing for change tracking + drift
+---
+
+`diffPlan` (per-card delta), `planLog`, sync-marker read/write, `headSha`, `changedFilesSince`, `countCodeCommitsSince`, `recentPlanActivity`. Every caller-supplied revision is guarded by `safeRev` + `--end-of-options` so a dash-leading value can't be parsed as a git option.

package/constellation/file/FILE-HANDLES.md

@@ -0,0 +1,9 @@
+---
+name: handles.ts
+status: built
+path: src/core/handles.ts
+language: typescript
+summary: Handle grammar, the 17 canonical prefixes, and the type↔folder map
+---
+
+Defines the handle regex (`^[A-Z][A-Z0-9]*-[A-Z0-9][A-Z0-9-]*$`), `isHandleShaped` / `isKnownHandle` / `typeForHandle`, and `TYPE_FOLDERS` — the authority for which prefix is which type and where its cards live.

package/constellation/file/FILE-INDEXER.md

@@ -0,0 +1,11 @@
+---
+name: indexer.ts
+status: built
+path: src/core/indexer.ts
+language: typescript
+summary: 'loadPlan(root): the heart of the system'
+connections:
+  - FILE-TYPES
+---
+
+Reads every card, dedupes handles, resolves references, builds the undirected connection set, and collects structural issues (E001–E006, W001, W004). The single source of the derived graph — recomputed on every load, never stored.

package/constellation/file/FILE-LINT.md

@@ -0,0 +1,9 @@
+---
+name: lint.ts
+status: built
+path: src/core/lint.ts
+language: typescript
+summary: 'lintPlan: loadPlan + schema validation, sorted'
+---
+
+Composes the indexer's structural issues with schema validation, sorted by file then code. Errors break the graph (CLI exit 1); warnings never fail.

package/constellation/file/FILE-MCP-SEARCH.md

@@ -0,0 +1,12 @@
+---
+name: mcp/search.ts
+status: built
+path: src/mcp/search.ts
+language: typescript
+summary: Scored full-text search
+connections:
+  - FILE-MCP-SERVER
+  - DOC-MCP-SERVER
+---
+
+Ranks matches: handle ≫ name > kind/type > body-and-note occurrences; appended notes are indexed as `note(kind): text` lines so recorded memory stays findable, and the excerpt is the first matching body or note line.

package/constellation/file/FILE-MCP-SERVER.md

@@ -0,0 +1,9 @@
+---
+name: mcp/server.ts
+status: built
+path: src/mcp/server.ts
+language: typescript
+summary: 'The MCP server: tools + INSTRUCTIONS'
+---
+
+`constellation mcp` (stdio). Registers every tool, embeds the agent-facing `INSTRUCTIONS` string (one of the three guidance copies), and resolves the target plan — the home plan or, when `repo` is passed, a connected sibling.

package/constellation/file/FILE-PARSE.md

@@ -0,0 +1,9 @@
+---
+name: parse.ts
+status: built
+path: src/core/parse.ts
+language: typescript
+summary: Split a card file into YAML frontmatter + markdown body
+---
+
+Frontmatter/body splitter built on gray-matter. Surfaces malformed YAML so the indexer can raise E006.

package/constellation/file/FILE-RENAME.md

@@ -0,0 +1,18 @@
+---
+name: rename.ts
+status: built
+path: src/core/rename.ts
+language: typescript
+summary: Plan-wide handle rename shared by MCP rename_card and CLI rename
+connections:
+  - FILE-WRITER
+  - FILE-INDEXER
+  - FILE-MCP-SERVER
+  - FILE-CLI
+---
+
+Moves the card file to the new handle's path (folder follows the prefix) with its bytes
+preserved, then rewrites every card that mentions the old handle — connections lists,
+handle-shaped frontmatter values, `[[links]]`, mermaid node IDs, prose — as whole tokens
+only (`API-USER` never touches `API-USERS`). Throws typed `RenameCardError`s
+(NOT_FOUND / INVALID_HANDLE / CARD_EXISTS); callers map them to tool errors or exit codes.

package/constellation/file/FILE-REPOS.md

@@ -0,0 +1,9 @@
+---
+name: repos.ts
+status: built
+path: src/core/repos.ts
+language: typescript
+summary: Connected-repo declarations + repo selector resolution
+---
+
+Reads/writes `connected_repos` on PLAN-PROJECT and resolves the `repo` selector (name or path) to a sibling plan root. Repo-level links only — cards never connect across repos.

package/constellation/file/FILE-RESOLVE.md

@@ -0,0 +1,9 @@
+---
+name: resolve.ts
+status: built
+path: src/core/resolve.ts
+language: typescript
+summary: Find the plan folder, bounded by the repo root
+---
+
+Walks up from cwd to find `constellation/`, stopping at the first ancestor with `.git` and returning null rather than adopting a sibling repo's plan. Plan resolution never crosses a repo boundary.