@flyingrobots/graft 0.4.0 → 0.6.0

package/ARCHITECTURE.md

@@ -0,0 +1,139 @@
+# ARCHITECTURE
+
+Graft is an industrial-grade context governor converging on a strict Hexagonal (Ports and Adapters) architecture.
+
+Repo truth today is narrower than a finished strict-hex claim:
+
+- explicit ports and adapters exist
+- foundational dependency guardrails are mechanically enforced
+- primary adapters and composition roots are still mid-migration
+- WARP is still becoming a first-class port boundary rather than an ambient capability
+
+## Official Entry Points
+
+Graft now has three official product entry points:
+
+1. **API** — the direct package/library surface exported from the root
+   package entry point
+2. **CLI** — the operator and debugging surface
+3. **MCP** — the agent transport surface
+
+Repo truth today:
+
+- API is first-class, not a side door
+- CLI and MCP remain primary adapters
+- not every capability is symmetric across all three entry points yet
+- every capability should explicitly declare which entry points it is
+  available on and, for API, whether the exposure is a direct typed
+  surface or an MCP-style tool bridge
+
+The convergence target is:
+
+- one application core
+- three thin primary adapters
+- explicit surface metadata and invariants
+- capability parity where parity is intended, with narrow documented
+  exceptions where it is not
+
+## Repo Topology
+
+The source tree should make the three entry points visible:
+
+- `src/api/` is the API primary adapter home
+- `src/cli/` is the CLI primary adapter home
+- `src/mcp/` is the MCP primary adapter home
+
+The package export root is:
+
+- `src/index.ts`
+
+That root file is intentionally thinner than the adapter homes. It is
+the public package entrypoint, not the place where API behavior should
+accumulate.
+
+Supporting roles stay explicit too:
+
+- `src/hooks/` is an adjunct entrypoint for local automation and
+  governance, not one of the three official product surfaces
+- `src/operations/`, `src/policy/`, `src/session/`, `src/git/`,
+  `src/metrics/`, and `src/release/` are the current application/core
+  areas
+- `src/contracts/`, `src/ports/`, `src/guards/`, and `src/format/`
+  carry foundational contracts and helpers
+- `src/adapters/`, `src/parser/`, and `src/warp/` remain secondary
+  adapters or infrastructure bindings
+
+See [docs/repo-topology.md](./docs/repo-topology.md) for the repo-local
+topology contract.
+
+## Core Boundary
+
+The Graft core is TypeScript. Platform-specific concerns are intended to enter through explicit secondary ports:
+
+| Port | Responsibility | Official Adapter |
+| :--- | :--- | :--- |
+| **`FileSystem`** | Path resolution, file reads, directory creation | `nodeFs` |
+| **`JsonCodec`** | Canonical JSON shaping and serialization | `CanonicalJsonCodec` |
+| **`GitClient`** | Git history enumeration and status observation | `nodeGit` |
+| **`ProcessRunner`** | Shell execution and diagnostic capture | `nodeProcessRunner` |
+
+Primary adapters should sit above that core boundary:
+
+| Primary Adapter | Responsibility |
+| :--- | :--- |
+| **API** | Direct typed package surface for in-process integrations |
+| **CLI** | Human/operator command surface and scripting |
+| **MCP** | Agent-facing transport surface with receipts and schemas |
+
+The architecture rule is that none of these primary adapters own
+business flow. They validate input, call application services, and
+shape edge-specific output.
+
+## Pipeline: From File to Governance
+
+```mermaid
+flowchart TD
+    subgraph Core["Graft Core (Policy)"]
+        P1[Read Governance]
+        P2[Budget / Session Caps]
+    end
+    subgraph Parser["Parser (Meaning)"]
+        PA1[Tree-Sitter WASM]
+        PA2[Structural Outlines / Diffs]
+    end
+    subgraph Host["Host (Execution)"]
+        H1[Daemon Authority]
+        H2[Worker Execution]
+    end
+
+    PA2 --> P1
+    P1 --> P2
+    P2 --> H1
+    H1 --> H2
+```
+
+## Layered Worldline Model
+
+Graft models repository state through three distinct layers:
+
+1. **`commit_worldline`**: Durable structural history grounded in Git commits.
+2. **`ref_view`**: Branch and reference comparisons over durable history.
+3. **`workspace_overlay`**: The current dirty working tree and reactive edit signals.
+
+## WARP: Structural Worldline Memory
+
+### Write Path (Indexer)
+The write path turns Git history into structural worldline facts by extracting AST outlines and writing them into the WARP graph.
+
+### Read Path (Observers)
+The read path uses the **Observer Law**: projections are read through lenses (e.g., `graft_diff`, `code_show`) rather than traversing graph internals directly.
+
+## Execution Authority: The Daemon
+
+The Daemon is the system-wide authority for multi-repo coordination. It manages:
+- **Authorization**: Workspace and session binding.
+- **Scheduling**: Job queueing and fairness.
+- **Resources**: Shared worker pools for heavy indexing and parsing tasks.
+
+---
+**The goal is to move the repository from a collection of bytes to a provenance-aware professional bedrock.**

package/CHANGELOG.md

@@ -5,6 +5,134 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.6.0] - 2026-04-18
+
+### Added
+
+- **Runtime port guards**: `assertFileSystem()`, `assertJsonCodec()`,
+  and `assertToolContext()` validate adapter contracts at construction
+  time. Plumbing conformance test catches drift against
+  `@git-stunts/plumbing`.
+- **Secret scrubbing**: shared `scrubSecrets()` and
+  `sanitizeArgValues()` redact sensitive keys, truncate oversized
+  values, and scrub secret patterns across both `run_capture` output
+  and observability arg logging.
+- **Path escape invariants**: dedicated test suite for traversal
+  attacks, symlink escapes, and root-confinement.
+- **Worktree identity canonicalization**: `fs.realpathSync` resolves
+  path aliases (`/tmp` vs `/private/tmp`) before deriving workspace
+  IDs.
+- **Tool-call provenance footprints**: `ToolCallFootprint` records
+  paths, symbols, and line regions per tool invocation. Read-family
+  and search tools instrumented.
+- **Canonical symbol identity projection**: `graft_diff` and
+  `graft_since` enrich diff entries with `identityId` from WARP
+  `sid:*` anchors when indexed. Graceful degradation when unavailable.
+- **Dynamic project root**: `GRAFT_PROJECT_ROOT` env var overrides
+  the default `process.cwd()` binding. Git root auto-detection
+  fallback.
+- **Implicit daemon binding**: daemon-mode sessions auto-bind when
+  a repo-scoped tool is called with path evidence, removing the
+  mandatory `workspace_bind` step.
+- **Attribution fallback hardening**: transport session, environment
+  inference (CI/CD, editor detection), and session continuity
+  strategies reduce `actor:unknown` to the exception path.
+- **Anti-sludge policy**: semgrep rules and shell checks for
+  boundary discipline, banned patterns, and core-layer hygiene.
+- **`toJsonObject()` DTO bridge**: universal serialization boundary
+  between typed operation results and `ctx.respond()`.
+
+### Changed
+
+- **Explicit execution context**: `ToolHandler` now receives `ctx`
+  as an explicit parameter `(args, ctx)` instead of closing over it
+  via `createHandler(ctx)`. `AsyncLocalStorage` removed from
+  execution context threading.
+- **Session concept disambiguation**: `SessionTracker` renamed to
+  `GovernorTracker`, `RegisteredSession` to `RegisteredTransport`,
+  `WorkspaceSessionMode` to `WorkspaceMode`. Wire format preserved.
+- **MCP composition decomposition**: `server.ts` split into barrel +
+  `server-context.ts` + `server-invocation.ts`. `repo-state.ts` into
+  4 sub-modules. `daemon-control-plane.ts` into `control-plane/`.
+  `daemon-repos.ts` into `repo-overview/`. `daemon-worker-pool.ts`
+  into 3 sub-modules. `persistent-monitor-runtime.ts` into 3
+  sub-modules. `workspace-router.ts` gains capability and history
+  sub-modules.
+- **Parser decomposition**: markdown extraction split into
+  `src/parser/markdown.ts`. Parser reclassified as application module
+  (Layer 3) with enforced hex layer guardrails.
+- **Result type hardening**: `MetricsSnapshot`, `MetricsDelta`,
+  `DecisionEntry`, `StateSaveResult`, `StateLoadResult` promoted to
+  runtime classes. `[key: string]: unknown` index signatures removed
+  from all operation results. Receipt builder uses mutable draft
+  instead of `as` casts.
+- **`code_find` approximate discovery**: plain-text queries now use
+  case-insensitive exact/prefix/substring matching with deterministic
+  ranking.
+- **Claude hook governed reads**: `PreToolUse` now redirects large
+  JS/TS native `Read` calls to graft's bounded-read path.
+- **Codex bootstrap posture**: `graft init --write-codex-mcp` now
+  seeds `AGENTS.md` alongside `.codex/config.toml`.
+- **MCP runtime observability**: sessions emit metadata-only events
+  to `.graft/logs/mcp-runtime.ndjson`, receipts carry `traceId` and
+  `latencyMs`.
+- **Map tool collector extraction**: `map.ts` reduced from 328 to
+  52 lines; collection logic in `map-collector.ts`.
+- **Typed diagnostic responses**: `DoctorResponse`, `StatsResponse`,
+  `ExplainResponse`, `SetBudgetResponse`, `RunCaptureResponse`.
+
+### Fixed
+
+- **Worktree identity drift on macOS**: `/tmp` and `/private/tmp`
+  aliases no longer produce different workspace IDs.
+- **`GRAFT_PROJECT_ROOT` env var**: MCP servers no longer hardcoded
+  to their own repo path.
+- **Path resolver security**: absolute paths now confined to project
+  root. Symlink escapes detected via `fs.realpathSync` double-check.
+- **WARP symbol disambiguation**: `symNodeId` uses qualified names
+  (`Header.render` vs `Footer.render`) — same-named methods across
+  classes no longer collide.
+- **WARP indexer error propagation**: `IndexResult` is a discriminated
+  union. Git failures propagate instead of producing silently empty
+  graphs.
+- **Daemon session cleanup**: session directories removed on close
+  instead of leaking forever.
+- **Rotating log preservation**: oversized entries preserved instead
+  of erasing the entire log during rotation.
+- **`graft_map` output caps**: `MAX_MAP_FILES=100`, `MAX_MAP_BYTES=50000`
+  with automatic summary-only fallback. Budget-exhausted sessions get
+  compact `BUDGET_EXHAUSTED` response.
+- **hono vulnerability**: override to >=4.12.14 patches HTML
+  injection in `hono/jsx` SSR (Dependabot alert #10).
+
+## [0.5.0] - 2026-04-11
+
+### Added
+
+- **Between-commit activity view**: new bounded `activity_view` MCP
+  tool and `graft diag activity` CLI peer surface for inspecting
+  recent local `artifact_history` around the active causal workspace.
+- **Persisted local history substrate**: continuity, attribution,
+  staged-target, transition, and recent read/stage activity now
+  survive across local sessions as bounded artifact history.
+- **Same-repo concurrency posture**: bounded `repoConcurrency`
+  summaries and lawful same-worktree cross-session handoff semantics.
+
+### Changed
+
+- **Reactive workspace footing**: checkout-boundary footing, hook
+  posture, and forked-vs-stable lineage are now explicit product truth
+  instead of implied inference.
+- **Semantic transitions**: bounded surfaces now summarize
+  `index_update`, `conflict_resolution`, `merge_phase`,
+  `rebase_phase`, `bulk_transition`, and lawful `unknown` with
+  transition-aware guidance.
+- **Signpost docs**: README, GUIDE, BEARING, VISION, release notes,
+  and the new CLI/MCP/advanced signposts now reflect the 0.5.0
+  release cut.
+
 ## [0.4.0] - 2026-04-05
 
 ### Added

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Code of Conduct
+
+Graft is a public developer tool project. Participation in this
+repository, its issue tracker, pull requests, discussions, and other
+project spaces should be respectful, constructive, and professional.
+
+## Expected behavior
+
+Participants are expected to:
+
+- assume good intent while still being direct about technical concerns
+- give feedback that is specific, evidence-based, and useful
+- respect differences in experience level, background, and viewpoint
+- keep disagreements focused on ideas, code, design, or process
+- accept correction gracefully when impact is pointed out
+
+## Unacceptable behavior
+
+The following behavior is not acceptable in project spaces:
+
+- harassment, intimidation, threats, or sustained hostility
+- personal attacks, insults, or demeaning language
+- discrimination based on personal characteristics or identity
+- sexualized language or unwanted sexual attention
+- doxxing, sharing private information, or encouraging others to do so
+- trolling, deliberate disruption, or bad-faith escalation
+- retaliation against someone who reports a conduct concern
+
+## Scope
+
+This code of conduct applies in:
+
+- GitHub issues, pull requests, discussions, and reviews
+- project chat or coordination spaces, if any
+- any public interaction where someone is representing the Graft
+  project
+
+## Reporting
+
+If you experience or witness unacceptable behavior, report it to the
+maintainer:
+
+- `james@flyingrobots.dev`
+
+Please include as much context as you can, including links, screenshots,
+or timestamps when available.
+
+## Enforcement
+
+Reports will be reviewed promptly and handled as fairly as possible.
+Responses may include:
+
+- clarification or warning
+- moderation of comments or discussion
+- removal of content
+- temporary or permanent exclusion from project spaces
+
+The maintainer may take any action needed to protect participants and
+the project.
+
+## Project standard
+
+This document is intentionally concise. The standard is simple: be
+respectful, stay constructive, and do not make project participation
+unsafe for other people.

package/README.md

@@ -1,170 +1,144 @@
-<div align="center">
-    <img src="./docs/assets/graft.svg" />
-    <h3>Context governor for coding agents</h3>
-</div>
+# Graft
 
-Graft enforces read policy so coding agents consume the smallest
-structurally correct view of a codebase instead of dumping entire
-files into their context window. Agent-first, but the structural
-tools (outlines, diffs, symbol history) are useful to anyone.
+An industrial-grade context governor for coding agents. Graft enforces read policy so agents consume the smallest structurally correct view of a codebase instead of dumping raw files into their context window.
 
-## Why
+Graft is designed for the operator who demands precision and the architect who needs a stable foundation for agentic work. It scales from simple policy-aware reads to high-fidelity causal provenance tracking across multi-session worktrees.
 
-Empirical analysis of 1,091 real coding sessions ([Blacklight](https://github.com/flyingrobots/blacklight)) found
-that **Read accounts for 96.2 GB of context burden** — 6.6x all
-other tools combined. 58% of reads are full-file. The fattest 2.4%
-of reads produce 24% of raw bytes. Dynamic read caps + session
-management reduce this by **75.1%**.
+[![npm version](https://img.shields.io/npm/v/@flyingrobots/graft)](https://www.npmjs.com/package/@flyingrobots/graft)
+[![License](https://img.shields.io/github/license/graft)](./LICENSE)
 
-## Install
+![Graft demo](./docs/assets/graft.svg)
 
-```bash
-npm install -g @flyingrobots/graft
-```
+## Why Graft?
+
+Unlike simple file-scraping tools, Graft treats the repository as a layered worldline of code structure and causal activity.
+
+- **Policy-Enforced Reads**: Automatically degrades large files to structural outlines and jump tables. Refuses binaries, secrets, and lockfiles with machine-readable reasons.
+- **Machine-Readable Contracts**: Responses carry versioned `_schema` metadata and decision receipts so agents can reason about outcomes without scraping prose.
+- **Structural Memory**: Uses WARP (Structural Worldline Memory) to track AST evolution across Git commits. Query what changed structurally without reading a single byte of source code.
+- **Causal Provenance**: Tracks the *why* behind structural changes by logging read, stage, and transition activity into strand-scoped causal workspaces.
+- **Industrial-Grade Daemon**: A same-user local runtime that manages multi-repo authorization, background indexing, and shared-machine worker pools.
 
-Or use directly:
+## Quick Start
 
+Graft has three official entry points:
+
+- **API** for direct in-process integration
+- **CLI** for operator and debugging workflows
+- **MCP** for agent transport integration
+
+### 1. Bootstrap a Repo
+Scaffold `.graftignore`, setup git hooks, and seed agent instructions.
 ```bash
-npx @flyingrobots/graft
+npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
 ```
 
-Or run in Docker (no Node required):
+### 2. Repo-Local Stdio MCP
+This is the simplest per-repo path for most clients. The current
+checkout is the authority, and there is no separate workspace binding
+step.
+```bash
+npx @flyingrobots/graft serve
+```
 
+### 3. Standalone CLI
+Enforce policy on a single read or inspect structural history.
 ```bash
-docker run -i --rm -v "$PWD:/workspace" flyingrobots/graft
+npx @flyingrobots/graft read safe src/app.ts
+npx @flyingrobots/graft struct since HEAD~3
 ```
 
-## Quick start
+### 4. Direct Library API
+Embed Graft in-process when you want direct access without MCP transport
+or CLI process orchestration.
+```ts
+import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
 
-```bash
-npx @flyingrobots/graft init
+const graft = createRepoLocalGraft({ cwd: process.cwd() });
+const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
 ```
 
-Scaffolds `.graftignore`, adds `.graft/` to `.gitignore`, generates
-a `CLAUDE.md` snippet telling agents to prefer graft tools, and
-prints Claude Code hook config.
-
-Then add graft to your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "graft": {
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft"]
-    }
-  }
-}
+This uses the same repo-local core as the CLI and MCP server, but it
+lets host tools call Graft directly inside the same process.
+
+When you want a direct repo-local read surface instead of tool receipts,
+use the workspace API:
+```ts
+import { createRepoWorkspace } from "@flyingrobots/graft";
+
+const workspace = await createRepoWorkspace({ cwd: process.cwd() });
+const first = await workspace.safeRead({ path: "src/app.ts" });
+const second = await workspace.safeRead({ path: "src/app.ts" });
+const outline = await workspace.fileOutline({ path: "src/app.ts" });
 ```
 
-Add this to your MCP config — works with Claude Code, Cursor,
-Windsurf, Continue, Cline, and any MCP-compatible client.
-
-See **[Setup Guide](docs/GUIDE.md)** for per-editor instructions,
-Claude Code hooks, `.graftignore` configuration, troubleshooting,
-and details on what the agent experiences.
-
-## What it does
-
-When an agent asks to read a file, Graft applies policy:
-
-- **Small files** are returned as-is.
-- **Large files** are returned as a structural outline with a jump
-  table so the agent can request specific ranges.
-- **Banned files** (binaries, lockfiles, minified bundles, secrets)
-  are refused with a machine-readable reason code and suggested next
-  steps.
-- **Re-reads** of unchanged files return a cached outline (no wasted
-  context). Changed files return a structural diff (added/removed/
-  changed symbols).
-- **Ranges** are bounded — no stealth `cat` of a 10,000-line file.
-- **Session depth** tightens caps as the context window fills.
-- **Budget governor** — agent declares a byte budget, thresholds
-  tighten as it drains. No single read may consume more than 5% of
-  remaining budget.
-- **Tripwires** signal when the session is going off the rails.
-- **Receipts** on every response with compression ratio for usage
-  analysis.
-
-Every decision is logged. Every refusal is explainable. All output
-is structured JSON.
-
-## Tools
-
-| Tool | Purpose |
-|---|---|
-| `safe_read` | Policy-enforced file read (content, outline, refusal, or diff) |
-| `file_outline` | Structural skeleton with jump table |
-| `read_range` | Bounded range read (max 250 lines), policy-gated |
-| `graft_diff` | Structural diff between git refs with per-file summary lines |
-| `changed_since` | Check if a file changed since last read (peek or consume) |
-| `run_capture` | Shell output capture — tee to log, tail to agent |
-| `state_save` | Save session working state (max 8 KB) |
-| `state_load` | Restore session working state |
-| `set_budget` | Declare session byte budget — governor tightens as it drains |
-| `explain` | Human-readable help for any reason code |
-| `doctor` | Runtime health check |
-| `stats` | Decision metrics summary |
-
-## Claude Code hooks
-
-Two hooks work alongside the MCP server to govern native `Read`
-calls — a safety net for when agents bypass graft's tools:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"
-          }
-        ]
-      }
-    ]
-  }
-}
+This exposes the same governed repo-local read behavior that the MCP
+surface uses for `safe_read`, `file_outline`, `read_range`, and
+`changed_since`, but without going through MCP receipts at all.
+
+For close editor integration, use the buffer-native surface directly:
+```ts
+import { createProjectionBundle, createStructuredBuffer } from "@flyingrobots/graft";
+
+const buffer = createStructuredBuffer("src/app.tsx", liveEditorText, {
+  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
+});
+const spans = buffer.syntaxSpans({
+  viewport: {
+    start: { row: 0, column: 0 },
+    end: { row: 80, column: 0 },
+  },
+});
+const context = buffer.nodeAt({ row: 24, column: 12 });
+const rename = buffer.renamePreview({
+  position: { row: 24, column: 12 },
+  nextName: "nextValue",
+});
+
+// Every warm result now carries the basis it was derived from.
+console.log(spans.basis);
+
+const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
+  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
+  viewport: {
+    start: { row: 0, column: 0 },
+    end: { row: 80, column: 0 },
+  },
+});
+
+console.log(bundle.parseStatus.status);
 ```
 
-Add to `.claude/settings.json` in your project root.
-**PreToolUse** blocks banned files before the read.
-**PostToolUse** shows the agent what `safe_read` would have saved.
+### 5. Shared Daemon Runtime
+Start the same-user execution authority for multi-session or multi-repo
+work.
+```bash
+npx @flyingrobots/graft daemon
+```
 
-See the **[Setup Guide](docs/GUIDE.md)** for full details on hooks,
-per-editor MCP config, `.graftignore`, and troubleshooting.
+Daemon sessions start `unbound`. If your client connects through the
+daemon instead of repo-local stdio, the first repo-scoped flow is:
 
-## Reason codes
+1. `workspace_authorize` for the target repo/worktree
+2. `workspace_bind` for the active daemon session
+3. then use repository-scoped tools such as `safe_read`
 
-Every refusal or policy decision includes a machine-readable reason
-code. Use `explain(code)` to get meaning and recommended action.
+Use [docs/SETUP.md](./docs/SETUP.md) for the exact client bootstrap and
+daemon control-plane posture.
 
-| Code | Meaning |
-|------|---------|
-| `CONTENT` | File within thresholds — full content returned |
-| `OUTLINE` | File exceeds thresholds — structural outline returned |
-| `SESSION_CAP` | Session-depth byte cap triggered |
-| `BUDGET_CAP` | Budget-proportional cap triggered |
-| `BINARY` | Binary file refused |
-| `LOCKFILE` | Machine-generated lockfile refused |
-| `MINIFIED` | Minified file refused |
-| `BUILD_OUTPUT` | Build output directory refused |
-| `SECRET` | Potential secrets file refused |
-| `GRAFTIGNORE` | Matches .graftignore pattern |
+## Documentation
 
-## License
+- **[Guide](./GUIDE.md)**: Orientation, the fast path, and agent bootstrap.
+- **[Setup Guide](./docs/SETUP.md)**: Client-specific MCP setup, daemon posture, and workspace binding.
+- **[Advanced Guide](./ADVANCED_GUIDE.md)**: Deep dives into the pipeline, worldlines, and daemon mechanics.
+- **[Architecture](./ARCHITECTURE.md)**: The authoritative structural reference (Ports, Adapters, WARP).
+- **[Public API Contract](./docs/public-api.md)**: The semver-public root import surface and stability policy.
+- **[Repo Topology](./docs/repo-topology.md)**: Where API, CLI, MCP, and the core live in the source tree.
+- **[Three-Surface Capability Matrix](./docs/three-surface-capability-matrix.md)**: Current API / CLI / MCP baseline and peer posture.
+- **[Security Model](./docs/strategy/security-model.md)**: Same-user daemon trust boundaries, authz, and observability posture.
+- **[Causal Provenance](./docs/strategy/causal-provenance.md)**: Transport sessions, causal workspaces, strands, and handoff truth.
+- **[Vision](./docs/VISION.md)**: Core tenets and the provenance-aware mission.
+- **[Method](./METHOD.md)**: Repo work doctrine and the cycle loop.
 
-Apache 2.0 — see [LICENSE](LICENSE).
+---
+Built with precision by [FLYING ROBOTS](https://github.com/flyingrobots)

package/bin/graft.js

@@ -13,20 +13,12 @@ const require = createRequire(import.meta.url);
 
 // If already running under tsx, proceed directly
 if (process.env.__GRAFT_TSX_LOADED === "1") {
-  const command = process.argv[2];
-  if (command === "init") {
-    const { runInit } = await import("../src/cli/init.js");
-    runInit();
-  } else if (command === "index") {
-    const { runIndex } = await import("../src/cli/index-cmd.js");
-    await runIndex();
-  } else {
-    const { createGraftServer } = await import("../src/mcp/server.js");
-    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
-    const graft = createGraftServer();
-    const transport = new StdioServerTransport();
-    await graft.getMcpServer().connect(transport);
-  }
+  const { runCliEntrypoint } = await import("../src/cli/entrypoint.js");
+  await runCliEntrypoint({
+    argv: process.argv.slice(2),
+    stdinIsTTY: process.stdin.isTTY,
+    stdoutIsTTY: process.stdout.isTTY,
+  });
 } else {
   // Re-exec with tsx loader from our own node_modules
   const tsxPath = require.resolve("tsx/esm");

package/dist/adapters/canonical-json.d.ts

@@ -0,0 +1,6 @@
+import type { JsonCodec } from "../ports/codec.js";
+export declare class CanonicalJsonCodec implements JsonCodec {
+    encode(value: unknown): string;
+    decode(data: string): unknown;
+}
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/adapters/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/adapters/canonical-json.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAmCnD,qBAAa,kBAAmB,YAAW,SAAS;IAClD,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAI9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG9B"}