pi-weave 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eran Yonai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# pi-weave
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/logo-high-res.jpg" alt="pi-weave — an agent-native knowledge workspace" width="220"/>
+</p>
+
+**An agent-native knowledge workspace for your life and your code.**
+
+pi-weave is a [pi](https://github.com/earendil-works/pi)
+extension with two faces that are secretly one:
+
+1. **A smart notepad with AI skills.** A persistent vault of knowledge —
+   decisions, ideas, people, meetings — stored as plain Markdown notes with
+   front matter under `~/.okf/notes/`. Your agent reads and writes it *with*
+   you; everything is editable by hand in any editor.
+
+2. **A repository exploration engine.** A derived, git-aware knowledge index
+   of the repo you're in, living at `<repo>/.okf/` — structure, languages,
+   packages, modules, entry points, and staleness state. Rebuildable,
+   disposable, never the source of truth.
+
+And one rule across both: **everything is equally usable by humans and
+agents.** No opaque databases. No lock-in formats.
+
+```
+🧵 vault:12 · my-project:ok      ← pi's status line when weave is active
+```
+
+## Install
+
+```bash
+pi install npm:pi-weave             # from npm
+pi install git:github.com/EranYonai/pi-weave   # from git
+pi install /path/to/pi-weave       # local path
+```
+
+Or for development: `pi -e ./src/pi/index.ts`.
+
+## What you get
+
+| Surface | Name | Purpose |
+|---|---|---|
+| Tool | `weave_note` | list / get / add / append / search vault notes |
+| Tool | `weave_repo` | status / scan / overview of the `.okf` repo index |
+| Command | `/weave` | workspace dashboard (vault + repository) |
+| Command | `/weave-scan` | build/refresh the repository index (light) |
+| Command | `/weave-scan deep` | light index + model-summarized sidecars (opt-in, incremental) |
+| Command | `/weave-view` | open the local graph viewer in your browser |
+| Command | `/weave-view tui` | explore the same graph in-terminal (keyboard) |
+| Skill | `weave-notepad` | how the agent should take good notes |
+| Skill | `weave-explore` | how the agent should explore repositories |
+
+**`/weave-view`** starts a loopback-only server (`127.0.0.1`, random port)
+and opens an interactive graph of your knowledge space: vault notes with
+trust provenance (solid = human, dashed = agent, dimmed = generated),
+wiki-link edges between notes, and the repository's structure anchored to
+git state. It reads disk live on every refresh — never a stale cache.
+Zoom/scroll, drag to pan, click nodes to expand; notes open in a rendered
+markdown side panel.
+
+**`/weave-view tui`** explores the same knowledge graph in the terminal:
+an expandable containment tree (Explore), a 1-hop neighborhood (Focus), a
+selected-node detail view with note/`.okf` bodies, and a staleness + link
+health surface — all keyboard-driven and read-only. Same data as the
+browser viewer (the `GraphModel` assembled from vault + repo index); a
+pure, harness-free view-model (`src/pi/viewer/tui/model.ts`) backs the
+`WeaveExplorer` component. See `docs/weave-view-tui-design.md`.
+
+On session start, pi-weave detects the repository you're in, checks whether
+`.okf` exists and is fresh, and says so in the status line.
+
+**`/weave-scan deep`** is the opt-in, incremental deep pass: it refreshes the
+light index and then writes a short model summary per file to
+`.okf/repository/summaries/`, skipping files whose content hash is unchanged
+since their last summary. It costs tokens, so it never runs implicitly.
+
+## The formats (why everything is portable)
+
+Vault note (`~/.okf/notes/auth-boundary.md`):
+
+```markdown
+---
+title: Auth boundary decision
+created: 2026-08-22T09:00:00.000Z
+updated: 2026-08-22T09:30:00.000Z
+tags: [auth, security]
+source: human
+---
+
+JWT validation happens at the gateway because…
+```
+
+Repository index (`<repo>/.okf/`):
+
+```text
+.okf/
+├── okf.json            # format version + generator + source: generated
+└── repository/
+    ├── identity.json   # name, remotes, default branch
+    ├── git.json        # HEAD sha + branch + changed-file content hashes (staleness anchor)
+    └── structure.json  # languages, packages, modules, entry points
+```
+
+The `.okf` index is **derived**: delete it, rescan, lose nothing. By default
+it's excluded from git locally (`.git/info/exclude`); committing it for team
+sharing is a deliberate opt-in.
+
+## For other agent harnesses
+
+The on-disk artifacts and `src/core` are harness-agnostic by design — Claude
+Code and opencode adapters are on the roadmap (docs/design.md §21), and the
+skills follow the [Agent Skills standard](https://agentskills.io/specification).
+
+## Development
+
+```bash
+npm install
+npm run check     # typecheck + tests with coverage gate (≥95%)
+```
+
+See [AGENTS.md](AGENTS.md) for contributor/agent rules and
+[docs/design.md](docs/design.md) for the full design.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "pi-weave",
+  "version": "0.1.1",
+  "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "knowledge-graph",
+    "agent",
+    "notepad",
+    "repository-index"
+  ],
+  "license": "MIT",
+  "author": "Eran Yonai <yonai.eran@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EranYonai/pi-weave.git"
+  },
+  "homepage": "https://github.com/EranYonai/pi-weave#readme",
+  "bugs": "https://github.com/EranYonai/pi-weave/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./core": "./src/core/index.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/pi/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/logo-high-res.jpg"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run coverage",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typebox": "1.3.7",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/weave-explore/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: weave-explore
+description: Explore a git repository through its pi-weave knowledge index (.okf). Use when starting work in an unfamiliar repo, when asked to "explore this repository", or before broad structural questions about modules, packages, or architecture.
+---
+
+# Weave Explore
+
+pi-weave keeps a **derived** knowledge index of the repository at
+`<repo>/.okf/`. Source code is the truth; the index is a rebuildable cache.
+Deleting `.okf` loses nothing — rescan to regenerate it.
+
+## Tools
+
+In pi, use the `weave_repo` tool (or the `/weave-scan` command). To see
+the assembled graph in the terminal, run `/weave-view tui` (Explore tree,
+Focus neighborhood, Health surface); `/weave-view` opens the browser viewer.
+In other harnesses, read the JSON documents under `.okf/` directly.
+
+## Workflow
+
+1. **Check for an index**: `weave_repo` action=status.
+   - `missing` → offer to scan (`weave_repo` action=scan), or scan directly
+     when the user asked to explore.
+   - `stale` → scan again; the repository moved on.
+   - `fresh` → read it: action=overview.
+2. **Start from the overview**: file counts, languages, packages, module
+   groupings, and likely entry points. This replaces dozens of `ls`/`find`
+   calls.
+3. **Descend progressively** (design §9): only open files in modules relevant
+   to the user's question. The index gives you the map; the code gives you
+   the terrain.
+4. **Read summaries before full files**: if the repo has been deep-scanned
+   (`.okf/repository/summaries/` exists), read the relevant sidecars first —
+   they tell you what a file does and its outward surface in 1–3 sentences,
+   so you can decide whether to open the full file at all.
+5. **Answer with structure**: name modules and packages by their indexed
+   paths so the user can jump straight to them.
+
+## Deep summaries
+
+`/weave-scan deep` creates or refreshes `.okf/repository/summaries/` — one
+sidecar per file, written by the session model. It is **opt-in and
+incremental**: it never runs implicitly, and it only re-summarizes files
+whose content hash changed since their last summary. If summaries are
+missing or stale, offer `/weave-scan deep` to create or refresh them before
+diving into full files.
+
+## On-disk layout
+
+```text
+.okf/
+├── okf.json               # format version + generator
+└── repository/
+    ├── identity.json      # name, remotes, default branch
+    ├── git.json           # HEAD sha + branch + changed files (staleness anchor)
+    ├── structure.json     # languages, packages, modules, entry points
+    └── summaries/         # deep-scan sidecars (one per file, when present)
+```
+
+## Trust model
+
+Everything in `.okf` is machine-generated (`source: generated`). If the user
+corrects an interpretation, that correction belongs in the vault (see the
+`weave-notepad` skill) as human knowledge, not in the derived index.

package/skills/weave-notepad/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: weave-notepad
+description: Take and retrieve durable notes in the pi-weave vault. Use when the user asks to remember something or to start/add to a note (aliases: notes, ai note, note-taking, note-taker), or when answering questions about past decisions, people, or projects. Also handles interview note-taking where raw dictations are appended AND expanded.
+---
+
+# Weave Notepad
+
+The pi-weave vault is the user's long-term memory: plain Markdown notes with
+front matter under `~/.okf/notes/`. It is shared with the human — anything
+you write here, they can read and edit, and vice versa.
+
+## Tools
+
+In pi, use the `weave_note` tool. In other harnesses (or when the tool is not
+available), operate on the files directly:
+
+- **Notes** live at `~/.okf/notes/<slug>.md` (vault root overridable via `PI_WEAVE_VAULT`).
+- Each note has YAML front matter: `title`, `created`, `updated` (ISO-8601),
+  `tags: [..]`, and `source: human | agent | generated`.
+- `weave_note` actions: `list`, `get`, `add`, `append`, `finalize`, `search`.
+  `finalize` restructures the body *above* the `## Raw notes` tail and preserves
+  the tail verbatim.
+
+## Dictation mode ("I will write, you expand")
+
+When the user is dictating (e.g. "I am in an interview", "I will write, you
+expand on my draft"), behave as notepad + expander:
+
+1. **Every raw line the user adds MUST be captured.** Append their words
+   verbatim to the active note (`weave_note` action=append).
+2. **Then expand it immediately.** Add `## Raw: "<user's line>"` followed by
+   `**Expand:** <polished, interview-ready passage>` (STAR-style when
+   applicable). Never append without expanding.
+3. **Terse replies.** Acknowledge briefly and show what was written. Do NOT
+   dump long prose in chat — the expansion lives in the note, not the reply.
+4. **Small talk / questions → ask the user.** If you want to chat, clarify,
+   or ask something, pose it to the user directly and briefly, and wait.
+
+## When to take a note
+
+Create a note **only when the user explicitly asks** for one to exist:
+"start a note on X", "add to the X note", "remember this", "jot that down".
+Never promote conversation into a note on your own initiative — capture is
+explicit by design.
+
+## When NOT to take a note
+
+- Anything derivable from the repository itself (that knowledge belongs to
+  the `.okf` index, not the vault).
+- Session-scratch information (in-progress task state).
+- Secrets, credentials, or anything the user hasn't confirmed is safe to persist.
+
+## How to write a good note
+
+1. **Search first** (`weave_note` action=search): if a note exists, `append`
+   to it rather than creating a duplicate.
+2. Title: short noun phrase ("Auth boundary decision", not "Notes").
+3. **Scribble in, verbatim.** When the user is dictating, append their words
+   to the note as rough, verbatim scribbles — no silent rewording. Keep them
+   under a `## Raw notes` tail at the end of the note.
+4. **Finalize on request.** When the user says "finalize this" / "clean this
+   up", restructure the body *above* the raw tail: front-loaded summary,
+   sections, entities, links. Use `weave_note` action=finalize (or edit the
+   file directly in other harnesses). Move nothing out of `## Raw notes` — it
+   is append-only and never rewritten.
+5. Tags: 1–4 lowercase tags; reuse existing tags when possible.
+6. Provenance: notes the user scribbled stay `source: human` (finalization is
+   editorial, not authorship) — pass `source: "human"` to `add` for
+   user-scribbled notes. Notes you draft from scratch are `source: agent`
+   (the default). Never overwrite a `source: human` note's meaning; append
+   with a dated "Agent addendum" section instead.
+
+## Retrieving knowledge
+
+Use `weave_note` action=search with the user's key terms, then `get` the best
+hits. When a note and the repository index disagree, trust the repository for
+facts about code and flag the discrepancy — the note may be stale intent.

package/src/core/frontmatter.ts

@@ -0,0 +1,119 @@
+import type { NoteMeta, NoteSource } from "./types";
+import { NOTE_SOURCES } from "./types";
+
+/**
+ * Minimal YAML-front-matter handling for vault notes.
+ *
+ * Deliberately a *subset*: notes are meant to be human-editable plain text,
+ * so we write only `key: value` scalars and `[a, b]` inline arrays, and we
+ * parse exactly that. Anything richer belongs in the Markdown body.
+ */
+
+export interface ParsedNoteFile {
+  meta: NoteMeta;
+  body: string;
+}
+
+/** Generic, tolerant front-matter parse (any fields) — for non-note OKF files. */
+export interface ParsedFrontMatter {
+  fields: Map<string, string>;
+  body: string;
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+export function quoteField(value: string): string {
+  // Only quote when the value could confuse our subset parser.
+  if (/[:#[\]]|^\s|\s$|^$/.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+export function unquoteField(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+  return trimmed;
+}
+
+function parseTags(value: string): string[] {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) {
+    return trimmed.length > 0 ? [unquoteField(trimmed)] : [];
+  }
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner.length === 0) return [];
+  return inner
+    .split(",")
+    .map((t) => unquoteField(t))
+    .filter((t) => t.length > 0);
+}
+
+function parseSource(value: string): NoteSource {
+  const raw = value.trim();
+  return (NOTE_SOURCES as readonly string[]).includes(raw)
+    ? (raw as NoteSource)
+    : "human";
+}
+
+/** Serialize note metadata + body to the on-disk Markdown form. */
+export function serializeNote(meta: NoteMeta, body: string): string {
+  const lines = [
+    "---",
+    `title: ${quoteField(meta.title)}`,
+    `created: ${meta.created}`,
+    `updated: ${meta.updated}`,
+    `tags: [${meta.tags.map(quoteField).join(", ")}]`,
+    `source: ${meta.source}`,
+    "---",
+    "",
+    body.replace(/\s+$/, ""),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Parse any OKF front-matter block generically. Returns null when there is
+ * no leading `---` block; field parsing is best-effort (junk lines skipped).
+ * The body is stripped of the serializer's blank separator and trailing
+ * whitespace so round-trips are stable.
+ */
+export function parseFrontMatter(text: string): ParsedFrontMatter | null {
+  const match = FRONTMATTER_RE.exec(text);
+  if (!match || match[1] === undefined) return null;
+  const body = text.slice(match[0].length).replace(/^\n/, "").replace(/\s+$/, "");
+  const fields = new Map<string, string>();
+  for (const line of match[1].split("\n")) {
+    if (line.trim().length === 0) continue;
+    const idx = line.indexOf(":");
+    if (idx <= 0) continue; // tolerate blank/junk lines, front matter is best-effort
+    fields.set(line.slice(0, idx).trim(), line.slice(idx + 1).trim());
+  }
+  return { fields, body };
+}
+
+/**
+ * Parse a note file. Throws on missing/invalid front matter so callers can
+ * treat the file as malformed rather than guessing.
+ */
+export function parseNoteFile(text: string): ParsedNoteFile {
+  const parsed = parseFrontMatter(text);
+  if (!parsed) {
+    throw new Error("Missing front matter block (expected leading --- block)");
+  }
+  const title = parsed.fields.get("title");
+  if (!title) {
+    throw new Error("Front matter is missing required field: title");
+  }
+  const meta: NoteMeta = {
+    title: unquoteField(title),
+    created: parsed.fields.get("created") ?? "",
+    updated: parsed.fields.get("updated") ?? "",
+    tags: parseTags(parsed.fields.get("tags") ?? "[]"),
+    source: parseSource(parsed.fields.get("source") ?? "human"),
+  };
+  return { meta, body: parsed.body };
+}

package/src/core/git.ts

@@ -0,0 +1,194 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import type { GitState } from "./types";
+
+/**
+ * Minimal git layer for repository knowledge.
+ *
+ * Every function degrades to `null`/empty instead of throwing: callers are
+ * usually answering "is there repo knowledge here?" and must survive
+ * detached worktrees, missing git binaries, and non-repo directories.
+ */
+
+export interface GitExecOptions {
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+async function git(args: string[], cwd: string, timeoutMs: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => {
+      if (err) resolve(null);
+      else resolve(stdout);
+    });
+  });
+}
+
+/** Absolute path of the enclosing git worktree root, or null. */
+export async function findGitRoot(cwd: string, options: GitExecOptions = {}): Promise<string | null> {
+  const out = await git(["rev-parse", "--show-toplevel"], cwd, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const root = out?.trim();
+  if (!root || root.length === 0) return null;
+  // Normalize symlinks (macOS /var -> /private/var) so callers always get a
+  // canonical, comparable path.
+  try {
+    return await fs.realpath(root);
+  } catch {
+    return root;
+  }
+}
+
+/** Current HEAD sha, or null (unborn branch, not a repo, ...). */
+export async function headSha(cwd: string, options: GitExecOptions = {}): Promise<string | null> {
+  const out = await git(["rev-parse", "HEAD"], cwd, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const sha = out?.trim();
+  return sha && sha.length > 0 ? sha : null;
+}
+
+/** Current branch name; null when detached or not a repo. */
+export async function currentBranch(cwd: string, options: GitExecOptions = {}): Promise<string | null> {
+  const out = await git(["symbolic-ref", "--short", "HEAD"], cwd, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const branch = out?.trim();
+  return branch && branch.length > 0 ? branch : null;
+}
+
+/** Paths changed in the worktree relative to HEAD (porcelain v1). */
+export async function changedFiles(cwd: string, options: GitExecOptions = {}): Promise<string[]> {
+  const out = await git(["status", "--porcelain"], cwd, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  if (out === null) return [];
+  return out
+    .split("\n")
+    .map((line) => line.slice(3).trim()) // drop the 2 status columns + space
+    .map((path) => {
+      // Renames appear as "old -> new"; the new path is what matters.
+      const arrow = path.indexOf(" -> ");
+      return arrow >= 0 ? path.slice(arrow + 4) : path;
+    })
+    .filter((path) => path.length > 0)
+    .sort();
+}
+
+/** Files git knows about: tracked plus untracked-but-not-ignored. */
+export async function listFiles(cwd: string, options: GitExecOptions = {}): Promise<string[] | null> {
+  const out = await git(
+    ["ls-files", "--cached", "--others", "--exclude-standard"],
+    cwd,
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  );
+  if (out === null) return null;
+  return out
+    .split("\n")
+    .filter((f) => f.length > 0)
+    .sort();
+}
+
+/** Configured remotes, deduplicated URLs. */
+export async function remotes(cwd: string, options: GitExecOptions = {}): Promise<string[]> {
+  const out = await git(["remote", "-v"], cwd, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  if (out === null) return [];
+  const urls = new Set<string>();
+  for (const line of out.split("\n")) {
+    const parts = line.split(/\s+/);
+    const url = parts[1];
+    if (url) urls.add(url);
+  }
+  return [...urls].sort();
+}
+
+/** Remote default branch (origin/HEAD), null when unknown. */
+export async function defaultBranch(cwd: string, options: GitExecOptions = {}): Promise<string | null> {
+  const out = await git(
+    ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+    cwd,
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  );
+  const ref = out?.trim();
+  if (!ref) return null;
+  const prefix = "origin/";
+  return ref.startsWith(prefix) ? ref.slice(prefix.length) : ref;
+}
+
+/**
+ * Resolve a path inside the repo's *real* git dir via `git rev-parse
+ * --git-path`. In linked worktrees and submodules `.git` is a file pointing
+ * at the real git dir, so naive `<root>/.git/...` joins fail with ENOTDIR.
+ * Returns null when no git metadata is available.
+ */
+async function resolveGitPath(repoRoot: string, relPath: string, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<string | null> {
+  const out = await git(["rev-parse", "--git-path", relPath], repoRoot, timeoutMs);
+  const resolved = out?.trim();
+  if (!resolved || resolved.length === 0) return null;
+  // Normal repos print a root-relative path (".git/info/exclude"); linked
+  // worktrees and submodules print the real, absolute location.
+  return isAbsolute(resolved) ? resolved : join(repoRoot, resolved);
+}
+
+/**
+ * Add `.okf/` to the repo's local exclude file (info/exclude in the real
+ * git dir) so the derived index stays a local cache by default (design §15,
+ * Model A) without touching tracked files. Idempotent; no-op when the repo
+ * has no git metadata (not a repo, no git binary).
+ */
+export async function excludeOkfLocally(repoRoot: string): Promise<void> {
+  const excludePath = await resolveGitPath(repoRoot, "info/exclude");
+  if (!excludePath) return;
+  let current = "";
+  try {
+    current = await fs.readFile(excludePath, "utf8");
+  } catch {
+    // no exclude file yet — we will create it
+  }
+  const already = current
+    .split("\n")
+    .map((line) => line.trim())
+    .some((line) => line === ".okf/" || line === ".okf");
+  if (already) return;
+  await fs.mkdir(dirname(excludePath), { recursive: true });
+  const prefix = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
+  await fs.writeFile(excludePath, `${current}${prefix}.okf/\n`, "utf8");
+}
+
+/**
+ * sha1 the worktree content of each repo-relative path. Paths without file
+ * content (deletions, untracked directories, unreadable entries) map to
+ * null — their porcelain membership still anchors them.
+ */
+export async function hashWorktreeFiles(
+  repoRoot: string,
+  paths: string[],
+): Promise<Record<string, string | null>> {
+  const entries = await Promise.all(
+    paths.map(async (path): Promise<[string, string | null]> => {
+      try {
+        const full = join(repoRoot, path);
+        if (!(await fs.stat(full)).isFile()) return [path, null];
+        return [path, createHash("sha1").update(await fs.readFile(full)).digest("hex")];
+      } catch {
+        return [path, null];
+      }
+    }),
+  );
+  return Object.fromEntries(entries);
+}
+
+/** Snapshot the current git state. Returns null when HEAD does not exist. */
+export async function snapshotGitState(cwd: string, options: GitExecOptions = {}): Promise<GitState | null> {
+  const sha = await headSha(cwd, options);
+  if (!sha) return null;
+  const [branch, changed, root] = await Promise.all([
+    currentBranch(cwd, options),
+    changedFiles(cwd, options),
+    findGitRoot(cwd, options),
+  ]);
+  return {
+    headSha: sha,
+    branch: branch ?? "(detached)",
+    changedFiles: changed,
+    // Hash against the repo root: `cwd` may be a subdirectory.
+    changedHashes: await hashWorktreeFiles(root ?? cwd, changed),
+    capturedAt: new Date().toISOString(),
+  };
+}