threadnote 0.1.0

package/docs/agent-instructions.md

@@ -0,0 +1,58 @@
+# Agent Instructions
+
+Threadnote installs this as user-level agent guidance for Codex and Claude.
+
+## Shared Context
+
+Use OpenViking through Threadnote as a shared local context and memory layer. Repo files remain authoritative: always
+follow the nearest `AGENTS.md`, `CLAUDE.md`, or other checked-in instruction file first.
+
+When OpenViking MCP tools are available, use them directly. If MCP is unavailable, use the `threadnote` CLI fallback.
+
+## Recall
+
+At the start of a non-trivial task, recall relevant context before making changes. Search for:
+
+- the current repo and branch;
+- recent handoffs;
+- task-specific skills or workflow guidance;
+- user or team preferences that may affect the work.
+
+Skip proactive recall for tiny one-shot questions where context would add noise.
+
+Search results are not the final payload. Treat returned `viking://` URIs as pointers: read the relevant URI, or list a
+directory when the result is an abstract/overview node.
+
+## Remember
+
+When the user asks you to remember something, store it unless it contains secrets, credentials, customer data, production
+logs, or other sensitive data.
+
+Also remember durable workflow facts you discover during work when they would help future agents and are not already in
+canonical docs. Prefer updating checked-in docs for canonical repo rules.
+
+## Handoff
+
+Before pausing, switching agents, or ending meaningful work with local changes, store a concise handoff. Include:
+
+- repo and branch;
+- files touched;
+- current status;
+- tests or checks run;
+- blockers;
+- next suggested step.
+
+Do not store long diffs, secrets, raw logs, or customer data in handoffs.
+
+## CLI Fallback
+
+Use these only when MCP tools are not available:
+
+```bash
+threadnote start
+threadnote recall --query "last handoff for this branch"
+threadnote read viking://agent/threadnote/memories/.abstract.md
+threadnote list viking://agent/threadnote/memories --all --recursive
+threadnote remember --text "Durable engineering note..."
+threadnote handoff --task "short task summary" --tests "checks run" --next-step "what to do next"
+```

package/docs/demo.md

@@ -0,0 +1,279 @@
+# Demo: Cross-Agent Development Context
+
+This demo shows `threadnote` as a shared local memory layer for engineering work. The story is intentionally simple:
+one agent starts a task in a worktree, stores a handoff, and another agent or worktree recalls it without the
+developer copy-pasting chat history, PR notes, or terminal output.
+
+## Demo Goal
+
+Show engineers that:
+
+- repo instructions still live in `AGENTS.md`, `CLAUDE.md`, and checked-in docs;
+- OpenViking adds durable, searchable context across agent sessions, worktrees, and repos;
+- agents should use MCP directly, while `threadnote` is the human-readable fallback and diagnostic path;
+- memories survive branch merges and worktree deletion because they live under the developer's OpenViking home, not in
+  the git worktree;
+- `repair` fixes the common stale-worktree and MCP launcher problems that show up during real local development.
+
+## Use Case
+
+Use "continue a PR after switching agents" as the live scenario.
+
+The engineer has a PR that updates a local tool. Codex has already done some work and creates a handoff. The engineer
+opens Claude, or a fresh Codex session from another repo/worktree, and asks it to continue. The new agent
+recalls the handoff, reads the relevant `viking://` memory, discovers repo guidance, and stores an updated handoff when
+it finishes.
+
+This is the highest-signal demo because it exercises the behavior engineers actually feel every day: context transfer,
+stale local setup, and "what did the previous agent already learn?"
+
+## Prep Checklist
+
+Run these before the meeting from this checkout:
+
+```bash
+npm install
+npm run doctor -- --dry-run
+npm run threadnote -- install
+threadnote start
+threadnote doctor --dry-run
+threadnote init-manifest --repo "$(pwd)"
+threadnote seed --dry-run
+threadnote seed
+threadnote seed-skills --dry-run
+threadnote seed-skills
+threadnote mcp-install codex --apply
+threadnote mcp-install claude --apply
+```
+
+Open a fresh Codex or Claude session after installing MCP. Existing sessions may not pick up newly registered MCP
+servers.
+
+Optional: create a deterministic demo handoff so the search result is easy to find.
+
+```bash
+threadnote handoff \
+  --task "Demo PR: continue the threadnote rollout after adding repair and docs" \
+  --tests "doctor --dry-run, mcp-install dry runs, local TypeScript checks" \
+  --next-step "Recall this handoff, read the most relevant viking URI, then summarize what changed and what to do next"
+```
+
+## Live Script
+
+### 1. Open With The Problem
+
+Say:
+
+```text
+When we switch from one agent session to another, we usually lose the useful middle: what was tried, what failed, what
+the branch is about, and what the next agent should avoid re-discovering. This tool gives agents a shared local context
+layer without replacing repo instructions or indexing entire repos.
+```
+
+Show that the repo still has normal instructions:
+
+```bash
+ls AGENTS.md CLAUDE.md
+```
+
+### 2. Show Local Health
+
+Run:
+
+```bash
+threadnote doctor --dry-run
+threadnote start
+```
+
+Say:
+
+```text
+The server is local. The default is 127.0.0.1:1933, so it does not conflict with apps running on localhost:80 or
+localhost:443. If the exact port is taken, we can set THREADNOTE_PORT.
+```
+
+### 3. Show MCP Is Installed
+
+Run the client-specific check you want to demo:
+
+```bash
+codex mcp list
+claude mcp list
+```
+
+Say:
+
+```text
+MCP is the expected agent path. The CLI exists so humans can inspect, repair, and reproduce what the agent is doing.
+Claude installs at user scope by default, so it works from other repos and worktrees.
+```
+
+If the MCP server does not appear in an already-open agent session, restart that session after `mcp-install --apply`.
+
+### 4. Recall The Previous Handoff
+
+In the agent UI, ask:
+
+```text
+Before touching code, recall recent OpenViking context for this branch and read the most relevant handoff.
+```
+
+For a terminal fallback, run:
+
+```bash
+threadnote recall --query "last handoff for threadnote rollout"
+```
+
+Point out that recall returns candidate `viking://` URIs and abstracts. Then read the best match:
+
+```bash
+threadnote read "<paste the most relevant viking:// URI>"
+```
+
+Say:
+
+```text
+Search is intentionally a pointer step. The agent should read or list the selected URI before treating it as context.
+That keeps recall cheap and makes the result auditable.
+```
+
+### 5. Discover Repo Guidance
+
+Ask the agent:
+
+```text
+Find any repo guidance or skills that matter for this task before you continue.
+```
+
+Terminal fallback:
+
+```bash
+threadnote recall --query "repo agent instructions testing guidance"
+threadnote recall --query "skills for this repo"
+```
+
+Say:
+
+```text
+This is not source navigation. It is a curated catalog of instructions, skills, and durable notes that helps the agent
+start in the right neighborhood.
+```
+
+### 6. Show Cross-Repo Or Cross-Worktree Continuity
+
+Switch to another repo or worktree and run the same recall:
+
+```bash
+cd ~/work/another-repo
+threadnote recall --query "last handoff for threadnote rollout"
+```
+
+Or ask a fresh Claude session from another repo:
+
+```text
+Use OpenViking to recall the latest handoff for the threadnote rollout and summarize the next step.
+```
+
+Say:
+
+```text
+The repo list is developer-local and manifest-driven. Nothing assumes a fixed source path. Memories are stored in the
+local OpenViking home, so deleting a worktree removes launcher paths, not the remembered handoff.
+```
+
+### 7. Remember A Durable Fact
+
+Ask the agent:
+
+```text
+Remember this workflow fact: threadnote MCP for Claude should be installed at user scope so it works from any repo or
+worktree.
+```
+
+Terminal fallback:
+
+```bash
+threadnote remember \
+  --text "Workflow fact: install Claude OpenViking MCP at user scope so it works from any repo or worktree."
+```
+
+Say:
+
+```text
+The rule is: remember durable workflow facts, not secrets, customer data, raw logs, or long diffs. Canonical repo rules
+should still be checked in.
+```
+
+### 8. Create The Next Handoff
+
+Ask the agent:
+
+```text
+Create a handoff for the next agent with the current status, tests run, blockers, and next step.
+```
+
+Terminal fallback:
+
+```bash
+threadnote handoff \
+  --task "Demo: verified cross-agent recall for the threadnote rollout" \
+  --tests "doctor --dry-run, recall, read, remember, handoff" \
+  --next-step "Open a fresh agent session and ask it to recall this handoff before continuing"
+```
+
+Say:
+
+```text
+This is the part we want agents to do automatically before pausing or finishing meaningful code changes.
+```
+
+### 9. Show Repair
+
+Run:
+
+```bash
+threadnote repair --dry-run
+```
+
+Say:
+
+```text
+This catches the ugly local cases: stale command shims, MCP launchers pointing at deleted worktrees, missing manifests,
+and a stopped local server. Repair rewrites paths from the current checkout.
+```
+
+### 10. Close
+
+Say:
+
+```text
+The important design choice is that this does not replace the repo. It makes the useful working memory around the repo
+available to whichever agent session picks up the task next.
+```
+
+## Expected Signals
+
+- `doctor --dry-run` reports no failures or prints concrete repair steps.
+- `recall` returns `memory`, `resource`, or `skill` rows with `viking://` URIs.
+- `read` turns a selected URI into actual handoff or memory content.
+- A fresh agent session can use the OpenViking MCP tools after MCP install.
+- `repair --dry-run` explains what it would fix without mutating anything.
+
+## Recovery Branches
+
+- MCP is installed but the current agent says no OpenViking tools are registered: open a fresh agent session.
+- `claude mcp list` does not show OpenViking: run `threadnote mcp-install claude --apply`; the default scope is
+  `user`.
+- `/health` is OK but `/mcp` fails: this is expected for OpenViking `0.3.12`; use the default stdio adapter instead of
+  `--native-http`.
+- The old checkout or worktree was deleted: run
+  `npm run threadnote -- repair` from any fresh checkout.
+- Recall returns only overview nodes: read the URI, or list the directory with
+  `threadnote list <uri> --all --recursive`.
+
+## What Not To Demo
+
+- Do not seed an entire repo.
+- Do not store secrets, tokens, customer data, raw production logs, or long diffs.
+- Do not present CLI commands as the ideal daily workflow. For normal work, the developer should ask the agent in
+  natural language and the agent should use MCP directly.

package/docs/migration.md

@@ -0,0 +1,218 @@
+# Migration
+
+This guide explains how to switch a developer workflow to `threadnote` without losing the repo-local instruction
+model that current agents rely on.
+
+## Short Answer
+
+Do not remove `AGENTS.md`, `CLAUDE.md`, `.claude/`, or `.agents/` as part of the migration.
+
+Those files remain the versioned source of truth for repo-local behavior. OpenViking becomes a shared, searchable
+context and memory layer on top of them. It helps agents recall handoffs, skills, and curated guidance across tools,
+but it should not replace the files that fresh agents read directly from the working tree.
+
+## Authority Model
+
+- `AGENTS.md` and `CLAUDE.md`: canonical repo instructions. Keep these small, current, and checked in.
+- Nested `AGENTS.md` and `CLAUDE.md`: canonical module-specific overrides. Keep them next to the code they govern.
+- `.claude/commands` and `.claude/skills`: executable or tool-specific workflows. Keep them where Claude and other
+  local tools can discover them.
+- `.agents/`: agent/plugin metadata or repo-local automation config. Keep it unless the owning tool no longer uses it.
+- OpenViking: durable memory, cross-agent handoffs, searchable snapshots of curated guidance, and seeded skill
+  catalogs.
+
+When these sources disagree, the checked-in repo instruction file wins. Update the source file first, then refresh the
+OpenViking context.
+
+## DX Model
+
+Developers should not need to run `recall`, `remember`, or `handoff` as a normal habit.
+
+The intended workflow has three layers:
+
+- Agent-first: Codex, Claude, or another MCP-enabled agent calls OpenViking tools when the task calls for shared
+  context.
+- Short CLI fallback: humans and scripts can run `threadnote recall`, `threadnote remember`, or
+  `threadnote handoff` from any repo.
+- Checkout-local command: `npm run threadnote -- ...` is the bootstrap and debugging path before the short command shim
+  is installed.
+
+After MCP install, developers can use natural language:
+
+```text
+Recall the last handoff for this branch.
+Remember that this repo uses <durable workflow fact>.
+Create a handoff for the next agent before you stop.
+```
+
+For better continuity, run `threadnote install` so it can add the agent-side guidance from `docs/agent-instructions.md`
+to the user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` files. That guidance tells agents to recall context at
+task start, store durable memories when explicitly asked or when a reusable workflow fact is learned, and create
+handoffs automatically before stopping meaningful work.
+
+## Migration Steps
+
+Run install commands from any working directory. Run manifest commands from a repo root, or pass explicit `--repo`
+paths.
+
+1. Check prerequisites:
+
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | sh
+   threadnote doctor --dry-run
+   ```
+
+   To force Bun or Deno:
+
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | THREADNOTE_RUNTIME=bun sh
+   curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/install.sh | THREADNOTE_RUNTIME=deno sh
+   ```
+
+2. Install or repair local OpenViking. This also installs the short `threadnote` command shim to `~/.local/bin` and
+   upserts user-level agent instructions by default. The one-line installer already runs `threadnote install`; run these
+   only when doing the manual install flow or previewing changes:
+
+   ```bash
+   threadnote install --dry-run
+   threadnote install
+   ```
+
+   If `threadnote` is not found after install, add `~/.local/bin` to `PATH` or rerun install with
+   `THREADNOTE_BIN_DIR=<dir-on-path>`.
+
+3. Create the developer-local manifest for the repos this machine actually uses:
+
+   ```bash
+   threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
+   ```
+
+   `--repo` can be repeated. Paths may be anywhere on the machine. If no `--repo` is provided, the current git repo is
+   used. The manifest is written to `~/.openviking/seed-manifest.yaml` by default and is intentionally not checked in.
+
+4. Start the local service:
+
+   ```bash
+   threadnote start
+   threadnote doctor --dry-run
+   ```
+
+5. Inspect curated repo imports:
+
+   ```bash
+   threadnote seed --dry-run
+   ```
+
+6. Seed curated repo guidance after reviewing the dry-run output:
+
+   ```bash
+   threadnote seed
+   ```
+
+7. Inspect and seed shared skills:
+
+   ```bash
+   threadnote seed-skills --dry-run
+   threadnote seed-skills
+   ```
+
+8. Wire one agent at a time:
+
+   ```bash
+   threadnote mcp-install codex
+   threadnote mcp-install codex --apply
+   ```
+
+   Then repeat for Claude:
+
+   ```bash
+   threadnote mcp-install claude
+   threadnote mcp-install claude --apply
+   ```
+
+   Claude installs at user scope by default so it works from every repo/worktree. Use `--scope local` only when a
+   repo-specific Claude MCP entry is intentional.
+
+   Later, if the checkout that installed the MCP adapter is deleted or moved, repair it from any fresh checkout:
+
+   ```bash
+   threadnote repair
+   ```
+
+9. Validate recall:
+
+   ```bash
+   threadnote recall --query "repo testing guidance"
+   ```
+
+## Daily Workflow
+
+At the start of a task, agents should still read the nearest `AGENTS.md` or `CLAUDE.md` files from the repo. OpenViking
+is the cross-session layer.
+
+Preferred developer behavior is conversational:
+
+```text
+Recall anything relevant for this branch before you start.
+Remember this workflow note for future agents: ...
+Create a handoff now.
+```
+
+Preferred agent behavior is automatic after `threadnote install` has updated the user-level Codex and Claude instruction
+files:
+
+- On non-trivial task start, search OpenViking for recent handoffs and relevant repo guidance.
+- When the user says "remember", store the memory after checking that it contains no secret or customer data.
+- Before pausing, switching agents, or finishing meaningful code changes, store a concise handoff with status, tests,
+  blockers, and next steps.
+
+Manual CLI remains available for scripts and emergencies:
+
+```bash
+threadnote recall --query "last handoff for this branch"
+threadnote remember --text "Durable engineering note..."
+threadnote handoff --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
+```
+
+## Repo Paths
+
+The workflow is not tied to any fixed repo list. Repo discovery is manifest-driven:
+
+- `~/.openviking/seed-manifest.yaml`: developer-local default manifest, created by `threadnote init-manifest`.
+- `THREADNOTE_MANIFEST`: override for custom teams, experiments, or CI.
+- `--manifest <path>`: one-off override for `seed` and `seed-skills`.
+- `config/seed-manifest.example.yaml`: checked-in example only.
+
+Use `threadnote init-manifest --repo <path>` whenever a developer adds a new repo they want included. The command
+derives a stable `viking://resources/repos/<repo-name>` URI and keeps the seed patterns conservative.
+
+## Refreshing Context
+
+OpenViking stores imported context as durable resources. For v1, treat `seed` as a first-ingest operation. When a
+seeded instruction file changes, update the checked-in source first, then refresh the relevant `viking://` resource.
+
+Current practical options:
+
+- Remove the old resource with `forget`, then re-run a scoped seed manifest.
+- Use `remember` for short corrections that should be available immediately.
+- Export/import packs only for moving a known-good local context between machines.
+
+Do not edit OpenViking directly and leave the repo instruction file stale.
+
+## What To Remove
+
+Remove nothing during the initial migration.
+
+After the workflow is proven, teams may delete or consolidate only content that has a clear owner-approved replacement.
+Good candidates are stale handoff notes, obsolete duplicate docs, or abandoned per-agent experiments. Bad candidates are
+canonical instructions, active commands, active skills, MCP config, or anything required by existing tools.
+
+## Cutover Checklist
+
+- `doctor --dry-run` reports a healthy OpenViking server.
+- `threadnote` works from a different repo or subdirectory.
+- `mcp-install` has been applied for the agent the developer actually uses.
+- `recall` returns seeded guidance.
+- A test `handoff` can be stored and recalled by another agent.
+- `AGENTS.md` and `CLAUDE.md` still describe the source-of-truth repo rules.
+- The team has agreed on which seeded paths are allowed and which sensitive paths stay excluded.

package/docs/rollout.md

@@ -0,0 +1,24 @@
+# Rollout
+
+Start with a local-only pilot.
+
+## Pilot Steps
+
+1. Run `doctor --dry-run`.
+2. Run `install --dry-run`, review paths, then run `install`.
+3. For a solo pilot, use the default local embedding backend; for broader rollout, configure a company-approved
+   embedding and summary provider in `~/.openviking/ov.conf`.
+4. Run `start` and confirm `doctor` reports a healthy server.
+5. Run `seed --dry-run` and inspect every planned import.
+6. Run `seed`.
+7. Run `seed-skills --dry-run`, then `seed-skills`.
+8. Install MCP for one agent, validate recall, then install the second.
+
+## Acceptance Criteria
+
+- Install completes in under 10 minutes after prerequisites.
+- `doctor` reports clear actionable checks.
+- Codex and Claude can both store and recall a shared handoff.
+- Seeding curated guidance does not import known secret patterns.
+- Fresh agents can recall repo testing guidance and discover relevant skills.
+- Removing OpenViking leaves agent configs in a known state.

package/docs/security.md

@@ -0,0 +1,30 @@
+# Security
+
+`threadnote` treats OpenViking as durable local memory, so the default workflow is conservative.
+
+## Do Not Ingest
+
+- Credentials, access tokens, API keys, certificates, private keys, or shell history.
+- Customer data, production data, HIPAA data, or production logs without explicit approval and scrubbing.
+- Local auth files such as `~/.codex/auth.json` or `~/.claude/.credentials.json`.
+- Local settings files that may contain secrets unless they go through redaction.
+
+## Built-In Controls
+
+- `.threadnoteignore` excludes common secret and build-output paths.
+- `.mcp.json`, `config.toml`, and settings JSON are redacted before import.
+- Files are skipped if common secret patterns remain after redaction.
+- `mcp-install` requires `--apply` before it changes Codex or Claude config.
+- `install` updates user-level Codex and Claude instruction files through a managed Markdown block. Existing personal
+  instructions outside that block are preserved.
+- Config files created under `THREADNOTE_HOME` are written with user-only permissions.
+
+## Rollout Requirements
+
+Before team-wide use, get explicit legal and security review for:
+
+- OpenViking licensing and operational use.
+- Approved embedding and summary model providers.
+- At-rest encryption settings.
+- Local API key requirements.
+- Forget/removal expectations for stale or sensitive context.