threadnote 0.3.7 → 0.4.0

package/docs/agent-instructions.md

@@ -1,6 +1,6 @@
 # Agent Instructions
 
-Threadnote installs this as user-level agent guidance for Codex, Claude, and Cursor.
+Threadnote installs this as user-level agent guidance for Codex, Claude, Cursor, and Copilot.
 
 ## Shared Context
 
@@ -8,9 +8,9 @@ Use OpenViking through Threadnote as a shared local context and memory layer. Re
 follow the nearest `AGENTS.md`, `CLAUDE.md`, or other checked-in instruction file first.
 
 When OpenViking MCP tools are available, use them directly. Prefer Threadnote-named MCP tools when present:
-`recall_context`, `read_context`, `list_context`, and `remember_context`. Always pass JSON arguments to MCP tools, for
-example `recall_context({"query":"current repo latest handoff"})`. Older Threadnote MCP adapters may expose
-`search`, `read`, `list`, and `store` instead.
+`recall_context`, `read_context`, `list_context`, `remember_context`, and `share_publish`. Always pass JSON arguments to
+MCP tools, for example `recall_context({"query":"current repo latest handoff"})`. Older Threadnote MCP adapters may
+expose `search`, `read`, `list`, and `store` instead.
 
 If MCP is unavailable, use the `threadnote` CLI fallback.
 
@@ -20,9 +20,14 @@ At the start of a non-trivial task, recall relevant context before making change
 
 - the current repo and branch;
 - recent handoffs;
+- durable feature memories for the branch, feature name, project/topic, or issue;
 - task-specific skills or workflow guidance;
 - user or team preferences that may affect the work.
 
+When a recalled handoff describes an active branch or feature, do a second recall for durable memories about that
+feature before coding. The handoff tells you the current work state; durable feature memories tell you the design,
+decisions, invariants, interfaces, and gotchas that should survive beyond one session.
+
 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
@@ -36,6 +41,12 @@ 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.
 
+During feature work on a branch, maintain durable feature knowledge in addition to handoffs. Store or update a durable
+memory when you learn something future agents should know about the feature itself: the intended behavior, design
+decisions, API contracts, data flow, migration semantics, edge cases, known limitations, or why an implementation choice
+was made. Do not wait until the end of the branch; update the feature memory whenever a valuable change lands or a
+decision becomes clear.
+
 Use lifecycle metadata when storing memories:
 
 - `kind: durable` for facts future agents should use by default.
@@ -46,6 +57,14 @@ Use lifecycle metadata when storing memories:
 Archived handoffs are provenance, not default working context. Read them only when current durable memories or active
 handoffs are insufficient.
 
+For branch feature work, prefer two stable memories with the same project and topic:
+
+- `kind: durable` for the feature knowledge that should remain useful after the current agent session.
+- `kind: handoff` for current status, files touched, tests, blockers, and next step.
+
+If a durable feature memory already exists, update it in place with the same project/topic or with `--replace <uri>` /
+`replaceUri`. Avoid creating a new timestamped durable memory for every small progress note.
+
 ## Memory Compaction
 
 When working on the same active issue, prefer keeping one current-state memory updated instead of creating many small
@@ -56,7 +75,8 @@ progress memories. If an existing memory is clearly the current state for the is
 When the issue has a stable name, prefer project/topic storage over timestamped memories:
 
 ```bash
-threadnote remember --kind durable --project my-repo --topic test-workflow --text "..."
+threadnote recall --query "my-repo active-bug durable feature knowledge"
+threadnote remember --kind durable --project my-repo --topic active-bug --text "Feature knowledge: ..."
 threadnote handoff --project my-repo --topic active-bug --task "..." --tests "..."
 ```
 
@@ -73,11 +93,40 @@ them when it is safe:
 
 Never compact secrets, credentials, customer data, raw production logs, or checked-in canonical docs into memory.
 
+## Sharing memories with teammates
+
+Threadnote can publish a curated subset of durable memories into a team git repo so other engineers' agents can pull them.
+The mechanism lives under the `viking://user/<you>/memories/shared/<team>/...` subtree; only memories that are explicitly
+published leave the machine. Personal handoffs, preferences, and unpublished durable notes always stay local.
+
+Publish a durable memory when its content is useful to other engineers working on the same project (intended behavior,
+design decisions, API contracts, gotchas) and is safe to share. Do NOT publish:
+
+- handoffs or anything carrying machine-local paths, branch state, or in-flight task context;
+- memories under `memories/preferences/`;
+- anything mentioning secrets, customer data, raw logs, or material a teammate's git history shouldn't carry.
+
+The MCP tool `share_publish` runs the same scrubber as the CLI and refuses to publish memories containing common secret
+patterns (PEM private keys, `sk-...`, `gh[pousr]_...`, `Bearer ...`, `AKIA...`, `xox[abprs]-...`). It is a destructive
+operation: it removes the personal copy after the shared copy is committed.
+
+When a teammate's memory needs to come into your own working set, run `threadnote share sync` (no MCP equivalent yet) to
+pull and reindex.
+
+```
+# MCP call shape
+share_publish({"uri":"viking://user/you/memories/durable/projects/foo/bar.md"})
+share_publish({"uri":"viking://user/you/memories/durable/projects/foo/bar.md","team":"friends","push":false})
+```
+
+Before publishing, confirm with the user unless they have already instructed you to share durable memories autonomously.
+
 ## Handoff
 
 Before pausing, switching agents, or ending meaningful work with local changes, store a concise handoff. Include:
 
 - repo and branch;
+- related durable feature memory URI or topic, when known;
 - files touched;
 - current status;
 - tests or checks run;
@@ -93,11 +142,16 @@ Use these only when MCP tools are not available:
 ```bash
 threadnote start
 threadnote recall --query "last handoff for this branch"
+threadnote recall --query "durable feature knowledge for this branch"
 threadnote read viking://agent/threadnote/memories/.abstract.md
 threadnote list viking://agent/threadnote/memories --all --recursive
 threadnote remember --kind durable --project example --topic workflow --text "Durable engineering note..."
+threadnote remember --kind durable --project example --topic active-issue --text "Feature knowledge..."
 threadnote remember --replace viking://user/example/memories/durable/projects/example/workflow.md --text "Updated durable engineering note..."
 threadnote archive viking://user/example/memories/handoffs/active/example/old-issue.md
 threadnote forget viking://user/example/memories/events/duplicate.md
 threadnote handoff --project example --topic active-issue --task "short task summary" --tests "checks run" --next-step "what to do next"
+threadnote share init git@github.com:org/team-memories.git
+threadnote share publish viking://user/example/memories/durable/projects/foo/bar.md
+threadnote share sync
 ```

package/docs/migration.md

@@ -30,8 +30,8 @@ Developers should not need to run `recall`, `remember`, or `handoff` as a normal
 
 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.
+- Agent-first: Codex, Claude, Copilot, 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
@@ -46,8 +46,8 @@ 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 user-level Codex, Claude, and Cursor instruction 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
+to user-level Codex, Claude, Cursor, and Copilot instruction 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
@@ -141,6 +141,16 @@ paths.
 
    Cursor installs by updating the global `~/.cursor/mcp.json` file.
 
+   For GitHub Copilot in VS Code:
+
+   ```bash
+   threadnote mcp-install copilot
+   threadnote mcp-install copilot --apply
+   ```
+
+   Copilot installs by updating the VS Code user-profile `mcp.json` file. If VS Code uses a custom profile path, set
+   `THREADNOTE_COPILOT_MCP_CONFIG` to that `mcp.json` path before running `mcp-install copilot`.
+
    Later, if the checkout that installed the MCP adapter is deleted or moved, repair it from any fresh checkout:
 
    ```bash
@@ -162,16 +172,21 @@ Preferred developer behavior is conversational:
 
 ```text
 Recall anything relevant for this branch before you start.
-Remember this workflow note for future agents: ...
+Remember this feature decision for future agents: ...
 Create a handoff now.
 ```
 
 Preferred agent behavior is automatic after `threadnote install` has updated the user-level instruction files:
 
-- On non-trivial task start, search OpenViking for recent handoffs and relevant repo guidance.
+- On non-trivial task start, search OpenViking for recent handoffs, durable feature memories for the branch/topic, and
+  relevant repo guidance.
 - When the user says "remember", store the memory after checking that it contains no secret or customer data.
-- When continuing the same active issue, update the current-state memory with `remember --replace <uri>` or
-  `handoff --replace <uri>` instead of creating another near-duplicate progress memory.
+- When continuing the same active issue, keep two current-state records when useful: a durable feature memory for design,
+  decisions, interfaces, and gotchas, plus a handoff for status, tests, blockers, and next steps.
+- When valuable feature knowledge changes, update the durable feature memory with the same project/topic or
+  `remember --replace <uri>` instead of burying that knowledge only in a handoff.
+- When current status changes, update the active handoff with the same project/topic or `handoff --replace <uri>` instead
+  of creating another near-duplicate progress memory.
 - When recall surfaces clearly duplicate or stale memories, store one concise replacement memory and forget only the
   redundant originals.
 - Before pausing, switching agents, or finishing meaningful code changes, store a concise handoff with status, tests,
@@ -181,9 +196,10 @@ Manual CLI remains available for scripts and emergencies:
 
 ```bash
 threadnote recall --query "last handoff for this branch"
-threadnote remember --text "Durable engineering note..."
+threadnote recall --query "durable feature knowledge for this branch"
+threadnote remember --kind durable --project example --topic active-feature --text "Feature knowledge..."
 threadnote remember --replace viking://user/example/memories/events/current.md --text "Updated durable engineering note..."
-threadnote handoff --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
+threadnote handoff --project example --topic active-feature --task "short task summary" --tests "checks run" --next-step "what the next agent should do"
 ```
 
 ## Repo Paths

package/docs/rollout.md

@@ -18,7 +18,7 @@ Start with a local-only pilot.
 
 - Install completes in under 10 minutes after prerequisites.
 - `doctor` reports clear actionable checks.
-- Codex, Claude, or Cursor can store and recall a shared handoff after MCP setup.
+- Codex, Claude, Cursor, or Copilot can store and recall a shared handoff after MCP setup.
 - Seeding curated guidance does not import known secret patterns.
 - Fresh agents can recall repo testing guidance and discover relevant skills.
 - `uninstall --dry-run` previews removal, and `uninstall` leaves memories intact unless `--erase-memories` is explicit.

package/docs/security.md

@@ -6,7 +6,8 @@
 
 - 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`, `~/.claude/.credentials.json`, or Cursor account/session files.
+- Local auth files such as `~/.codex/auth.json`, `~/.claude/.credentials.json`, Cursor account/session files, or VS Code
+  Copilot account/session files.
 - Local settings files that may contain secrets unless they go through redaction.
 
 ## Built-In Controls
@@ -14,9 +15,9 @@
 - `.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, Claude, or Cursor config.
-- `install` updates user-level Codex, Claude, and Cursor instruction files through a managed Markdown block. Existing
-  personal instructions outside that block are preserved.
+- `mcp-install` requires `--apply` before it changes Codex, Claude, Cursor, or Copilot config.
+- `install` updates user-level Codex, Claude, Cursor, and Copilot instruction files through managed Threadnote content.
+  Existing personal instructions outside managed blocks are preserved.
 - `uninstall` preserves local memories by default. `--erase-memories` is required before deleting `THREADNOTE_HOME`.
 - Config files created under `THREADNOTE_HOME` are written with user-only permissions.
 

package/docs/share.md

@@ -0,0 +1,151 @@
+# Sharing memories with teammates
+
+`threadnote share` lets a small team keep a curated set of durable memories in a
+git repository so every member's local agent can recall them. Personal handoffs,
+preferences, and unpublished durable notes stay local; only memories you
+explicitly publish leave your machine.
+
+## Model in one screen
+
+- A **team** is a configured shared repo. Each team has a name (default:
+  `default`), a git remote, a local working tree, and a separate gitdir.
+- The working tree lives inside the OpenViking data tree at
+  `~/.openviking/data/viking/<account>/user/<you>/memories/shared/<team>/`. That
+  means files appearing in the worktree are also addressable as
+  `viking://user/<you>/memories/shared/<team>/...` and show up in normal
+  `recall`.
+- The gitdir lives outside the OV data tree at
+  `~/.openviking/share/teams/<team>.gitdir/` so OpenViking never sees git
+  internals.
+- Team configuration is recorded in `~/.openviking/share/teams.json` (mode
+  `0600`).
+
+## Workflow
+
+### One-time setup
+
+```bash
+# Create the repo first on GitHub/GitLab/etc. and copy its SSH URL.
+threadnote share init git@github.com:org/team-memories.git
+# Optional: add a second team
+threadnote share init --team friends git@github.com:you/friends-memories.git
+# Switch the default with init --set-default <name> or by running publish/sync
+# with an explicit --team.
+```
+
+`share init` clones the remote into your local memory tree and ingests any
+existing markdown memories into OpenViking.
+
+### See what's configured
+
+```bash
+threadnote share list
+threadnote share status                # default team
+threadnote share status --team friends
+```
+
+### Share a memory
+
+```bash
+# 1. Identify the personal URI you want to publish (use recall/list as usual).
+# 2. Publish:
+threadnote share publish viking://user/you/memories/durable/projects/foo/bar.md
+# Optional flags: --team <name>, --message "...", --no-push, --dry-run.
+```
+
+`share publish` moves the memory from your personal namespace into the team's
+shared subtree, commits with the message
+`share: publish <relative-path>`, and pushes. The memory's recall path becomes
+`viking://user/you/memories/shared/<team>/durable/projects/foo/bar.md`.
+
+### Pull teammates' updates
+
+```bash
+threadnote share sync                  # default team
+threadnote share sync --team friends   # other team
+threadnote share sync --no-push        # pull only
+```
+
+`share sync` will auto-commit any uncommitted edits in the worktree, fetch and
+rebase from the remote, reindex pulled markdown files into OpenViking (so
+`recall` finds them immediately), and push. Pass `--no-auto-commit` to refuse
+syncing when the worktree is dirty.
+
+### Take a memory back
+
+```bash
+threadnote share unpublish viking://user/you/memories/shared/default/durable/projects/foo/bar.md
+```
+
+The memory is rewritten back into your personal namespace and removed from the
+shared repo.
+
+### Stop sharing for a team
+
+```bash
+threadnote share remove --team friends             # deletes worktree + gitdir
+threadnote share remove --team friends --keep-files
+```
+
+`share remove` without `--keep-files` deletes the local checkout. Push any
+unpushed commits first (`threadnote share sync` or `git -C <worktree> push`),
+otherwise unpublished work is lost.
+
+## Privacy & safety rules
+
+- Only memories you actively publish leave your machine. `share init` will
+  refuse to clone over a non-empty worktree.
+- `share publish` runs a best-effort scrubber over the memory text. It refuses
+  to publish if it matches any of:
+  - PEM private key headers (`-----BEGIN ... PRIVATE KEY-----`)
+  - OpenAI / Anthropic-style `sk-...` keys (16+ chars). Note: this also matches
+    any URL slug or random string starting with `sk-`; if you hit a false
+    positive on legitimate content, edit the memory to break the pattern.
+  - GitHub classic tokens (`gh[pousr]_...`)
+  - GitHub fine-grained PATs (`github_pat_...`)
+  - GitLab PATs (`glpat-...`)
+  - HTTP `Bearer ...` tokens (20+ chars)
+  - Bare JWTs (three base64url segments starting `eyJ...`) — catches a leaked
+    token even when the surrounding `Authorization: Bearer ` prefix has been
+    stripped. JWE tokens in legitimate documentation can collide; edit the
+    memory if the false positive is unavoidable.
+  - AWS access keys (`AKIA...`)
+  - Slack tokens (`xoxa`, `xoxb`, `xoxc`, `xoxd`, `xoxe`, `xoxp`, `xoxr`,
+    `xoxs`, with optional `-N-` segment markers — covers bot, user,
+    configuration, legacy cookie, refresh, app, and similar shapes)
+- The scrubber complements but does not replace human review. Strip the value,
+  then retry.
+- Only the `durable/` kind is shareable. `handoffs/`, `preferences/`,
+  `incidents/`, and other lifecycle kinds stay local by construction — both
+  the initial ingest (`share init`) and the sync-pull reindex (`share sync`)
+  skip any file outside `durable/`.
+- `share publish` deletes the personal copy after publishing. If you want to
+  keep both, copy the memory to a new URI first (`ov read` then
+  `threadnote remember`).
+- `share publish` refuses to overwrite an existing shared memory at the same
+  URI; forget the existing shared copy first or pick a different topic name.
+
+## Conflict resolution
+
+`share sync` uses `git pull --rebase` against the remote. When git can't merge
+cleanly:
+
+1. The pull command reports the conflict and leaves the worktree in a
+   rebase-in-progress state.
+2. Resolve the conflicts manually in the worktree (it's a normal git checkout).
+3. Run `git rebase --continue` (or `--abort`) yourself.
+4. Re-run `threadnote share sync` to finish the reindex and push.
+
+Two publishes touching the same `<topic>.md` from different machines will
+collide; coordinate ownership per-topic, or use distinct topics.
+
+## Cross-machine identity notes
+
+Each user clones into their own user-namespaced path. A memory authored on
+machine A as `viking://user/alice/memories/shared/team/durable/projects/foo/bar.md`
+shows up on machine B as
+`viking://user/bob/memories/shared/team/durable/projects/foo/bar.md`. The file
+content (including any `supersedes:` URIs that reference the original author) is
+identical, but explicit URI cross-references will point at the author's
+namespace. For now, prefer narrative references ("see the foo memory under
+shared/team") over URI links in shared content.

package/docs/troubleshooting.md

@@ -147,7 +147,7 @@ threadnote repair
 ```
 
 `repair` reinstalls the `threadnote` shim, repairs generated config files, starts OpenViking if needed, and rewrites
-Codex/Claude/Cursor MCP configs to point at the current checkout.
+Codex/Claude/Cursor/Copilot MCP configs to point at the current checkout.
 
 ## MCP Install Is Only Printing Commands
 
@@ -166,6 +166,16 @@ threadnote mcp-install cursor --apply
 This updates the global `~/.cursor/mcp.json` file. Restart Cursor or open a fresh agent session after changing MCP
 config.
 
+For GitHub Copilot in VS Code:
+
+```bash
+threadnote mcp-install copilot --apply
+```
+
+This updates the VS Code user-profile `mcp.json` file. Restart VS Code or run `MCP: List Servers` from the Command
+Palette after changing MCP config. If VS Code uses a custom profile path, set `THREADNOTE_COPILOT_MCP_CONFIG` to that
+`mcp.json` path before running the command.
+
 ## Cursor MCP Tool Says Query Is Missing
 
 If Cursor shows an error like `expected string, received undefined` for Threadnote `search`, the MCP server started but

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",