@magic-spells/constellation 0.2.2 → 0.4.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/decision/DECISION-FEATURE-RELEASE-TYPES.md

@@ -0,0 +1,50 @@
+---
+name: FEATURE and RELEASE are native card types
+status: built
+connections:
+  - DOC-CARD-TYPES
+  - FILE-TYPES
+  - DECISION-NATIVE-DECISION-TYPE
+---
+
+# FEATURE and RELEASE are native card types
+
+## Context
+
+Constellation modeled the *initial* build well — PLAN cards and phases, work
+marked `status: planned` — but had no primitive for how projects actually grow
+afterwards: feature branches that ship in release versions. `planned` marks
+individual cards, yet nothing groups a coherent slice of work; and a version's
+intent (theme, upgrade notes) had no home that isn't a changelog.
+
+## Decision
+
+Add two types (the 19th and 20th). **FEATURE** — a coherent unit of future
+work, connected to every card it adds or touches; fields `release` (handle of
+the RELEASE it targets — structured ref, auto-connects) and `branch`
+(informational). **RELEASE** — a version milestone; field `version`. Status
+carries each card's arc: a FEATURE goes `planned → building → built` as its
+branch merges; a RELEASE goes `planned → built` as it ships.
+
+Two guardrails hold the philosophy:
+
+- **FEATURE is not a ticket tracker.** Work that is one card's status flip
+  needs no FEATURE card; the backlog stays a `status` query.
+- **RELEASE is not a changelog.** What shipped is git's job ([[DOC-CHANGE-TRACKING]]);
+  the card holds only what git can't say — theme, intent, migration notes.
+
+## Alternatives
+
+- **Scoped PLAN cards per feature** — rejected: plans are living summaries, not
+  units of work with an arc; and retrieval by type ("show open features") needs
+  a prefix.
+- **External trackers only (issues/boards)** — rejected: the plan is the
+  agent-facing memory; work the graph can't see can't be traversed, assembled,
+  or drift-checked.
+
+## Consequences
+
+- The iteration loop is now first-class: feature branch ↔ FEATURE card,
+  release version ↔ RELEASE card, wired by `release:`.
+- A shipped FEATURE card stays, like a DECISION card
+  ([[DECISION-NATIVE-DECISION-TYPE]]) — provenance of why the system grew.

package/constellation/decision/DECISION-NATIVE-DECISION-TYPE.md

@@ -0,0 +1,58 @@
+---
+name: DECISION is a native card type
+status: built
+connections:
+  - DOC-CARD-TYPES
+  - DOC-MCP-UPGRADES
+  - FILE-TYPES
+---
+
+# DECISION is a native card type
+
+Reverses the earlier call in [[DOC-MCP-UPGRADES]] ("decided AGAINST a dedicated
+`DECISION` card type"). This card is itself the first native decision card — the
+new type records the *why*; [[DOC-CARD-TYPES]] records the *what*.
+
+## Context
+
+The original reasoning was that co-location beats a separate filing system:
+decisions live as `append_note(kind: decision)` on the cards they concern, or as
+a DOC card (`kind: decision`) when bigger. Field use broke that model two ways:
+
+- **Volume.** Real projects accumulated 30+ `DOC-…` decision cards, burying the
+  actual documentation (guides, rules) in `doc/` and making "every decision" a
+  kind-filter query instead of a folder and a type.
+- **Fan-out.** A decision routinely shapes *several* cards, so there is no single
+  card to co-locate a note on. The graph already had the right primitive —
+  connections — but no node type for the decision itself.
+
+The skill also already mandated one-file-per-decision ("Decisions (ADRs) get one
+DOC card each"), so the "separate filing system" existed either way; it was just
+typed as documentation.
+
+## Decision
+
+Add `DECISION-` / `decision/` as the 18th type. A DECISION card is an ADR — the
+choice, the why, the alternatives rejected — **connected to every card it
+shaped**. One structured field, `supersedes` (an earlier DECISION handle; must
+resolve, and connects the two). Superseded decisions are kept, never deleted.
+
+`append_note(kind: decision)` stays: it remains the right home for a choice local
+to a single card. Promote a note to a DECISION card when the choice touches more
+than one card or the rejected alternatives are worth recording.
+
+## Alternatives
+
+- **Status quo (DOC `kind: decision`)** — rejected: pollutes `doc/`, invisible in
+  the type system, and retrieval (viewer nav, `list_cards`, `describe_type`)
+  can't treat decisions as first-class.
+- **Notes only, no decision cards** — rejected: cross-cutting decisions have no
+  co-location target; splitting one rationale across N notes drifts.
+
+## Consequences
+
+- `doc/` is documentation again: suggested DOC kinds shrink to guide / rule / meta.
+- Adding the type touched the usual four places ([[DOC-CARD-TYPES]]) plus the
+  three agent-guidance copies and the viewer palette.
+- Existing plans with `DOC-…` decision cards can migrate one card at a time with
+  `rename_card` (e.g. `DOC-DECISION-X` → `DECISION-X`); nothing forces it.

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,39 @@
+---
+name: The 20 card types
+kind: reference
+status: built
+---
+
+# The 20 card types
+
+The prefix before the first dash determines a card's type and must be one of these 20. 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 |
+| DECISION | `DECISION-` | `decision/` | Architecture decision records — the why + rejected alternatives |
+| 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) |
+| FEATURE | `FEATURE-` | `feature/` | Future work units — the iteration primitive |
+| RELEASE | `RELEASE-` | `release/` | Version milestones — theme + upgrade notes, never a changelog |
+
+**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 20 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 20 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,57 @@
+---
+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** — *superseded by
+  [[DECISION-NATIVE-DECISION-TYPE]]*: real projects accumulated dozens of DOC decision cards,
+  and cross-cutting decisions have no single card to co-locate a note on. Card-local choices
+  still live as `append_note(kind: decision)` on the card they concern.
+- **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.