fastrmemory 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "fastrmemory",
       "source": "./",
       "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
-      "version": "0.4.0"
+      "version": "0.5.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fastrmemory",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local-first agent memory for Claude Code: MCP server plus Agent Skills for pre-edit trap checks, recall, trap logging, curation, and session handoffs.",
   "author": {
     "name": "Fastrsoft"
@@ -12,7 +12,7 @@
   "mcpServers": {
     "fastrmemory": {
       "command": "npx",
-      "args": ["-y", "fastrmemory@0.4.0", "mcp"]
+      "args": ["-y", "fastrmemory@0.5.0", "mcp"]
     }
   }
 }

package/.cursor/mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "fastrmemory@0.3.1",
+        "fastrmemory@0.5.0",
         "mcp"
       ]
     }

package/.cursor/skills/fastr-setup/SKILL.md

@@ -14,7 +14,7 @@ allowed-tools: Bash(fastr *), Bash(fastrmemory *), Bash(npx -y fastrmemory*)
 ## 1. Project install (recommended)
 Run from the project root:
 ```bash
-npx -y fastrmemory@0.3.1 hook install
+npx -y fastrmemory@0.5.0 hook install
 ```
 This is idempotent and backs up files it changes. It writes:
 - `.mcp.json`: a project-scoped `fastrmemory` MCP server.
@@ -25,13 +25,13 @@ Commit `.mcp.json` and `.claude/settings.json` so the team shares the setup. Res
 
 ## 2. Manual MCP registration (alternative)
 ```bash
-claude mcp add fastrmemory -- npx -y fastrmemory@0.3.1 mcp
+claude mcp add fastrmemory -- npx -y fastrmemory@0.5.0 mcp
 ```
-On native Windows use `-- cmd /c npx -y fastrmemory@0.3.1 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. For a user-scoped registration (the default when `--scope project` is omitted), append `--project <absolute-project-path>` so the server does not use the client's launch directory; `fastr setup` writes that path automatically. This adds tools only, not hooks.
+On native Windows use `-- cmd /c npx -y fastrmemory@0.5.0 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. For a user-scoped registration (the default when `--scope project` is omitted), append `--project <absolute-project-path>` so the server does not use the client's launch directory; `fastr setup` writes that path automatically. This adds tools only, not hooks.
 
 ## 3. Verify
 ```bash
-npx -y fastrmemory@0.3.1 status
+npx -y fastrmemory@0.5.0 status
 claude mcp list
 ```
 `status` prints the project ID, memory counts, and database path (`.fastr/` under the project). Inside a session, call:

package/.cursor/skills/skills.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://skills.sh/schema/v1.json",
   "name": "fastrmemory-skills",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent Skills that teach coding agents when to recall, log traps, curate, and commit FastrMemory.",
   "author": "Fastrsoft",
   "license": "Apache-2.0",

package/README.md

@@ -10,11 +10,11 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/Node-%3E%3D22.16.0-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![Protocol](https://img.shields.io/badge/Protocol-MCP%20v2-7C3AED?style=flat-square)](https://modelcontextprotocol.io)
-[![Tests](https://img.shields.io/badge/Tests-293%20Passed-brightgreen?style=flat-square)](tests/)
+[![Tests](https://img.shields.io/badge/Tests-297%20Passed-brightgreen?style=flat-square)](tests/)
 [![MCP Setup](https://img.shields.io/badge/MCP%20Setup-fastr%20mcp%20init-7C3AED?style=flat-square)](#-one-click-agent-mcp-configuration)
 [![Architecture](https://img.shields.io/badge/Architecture-Zero--Daemon%20WAL-orange?style=flat-square)](#-architecture)
 
-> **Status (2026-10-23):** **`fastrmemory@0.3.1` is published and is `latest`; `0.4.0` is prepared on `main` and is not tagged or published.** Evidence for 0.3.1: `npm view fastrmemory version` -> `0.3.1`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.3.1"}`; tag `v0.3.1` (`3a3cac6`); published 2026-10-22 23:02 UTC via GitHub Actions OIDC with npm provenance; GitHub Release tarball SHA-256 `747f61791dcb7c5694f3cf5cc8705152892a5b16cb33bec51a356fc22112a7b8`; `npm install -g fastrmemory@0.3.1` + `fastr --version` -> `0.3.1`. Caveat: Node.js >=22.16.0; the npm README for 0.3.1 was rendered at the release tag and still labels 0.3.1 the release target; this post-release docs commit is not part of that render; `0.3.0` remains published historical. This release replaces the stale `0.3.0` npm README, fixes Windows MCP commands, pins user-scoped clients to the project root, and adds the Node runtime guard. The old scoped npm entries (`@atifjubaer/fastrmemory` and `fastrmemory@0.0.0-stage`) were removed on 2026-10-23; the GitHub `v0.2.1` tag and release remain as history. This README tracks current `main`; published release evidence remains **0.3.1**. Use the exact `0.3.1` version for reproducibility. `0.4.0` adds `fastr mcp init` and LF checkout enforcement; those changes are not in the published `0.3.1` tarball. Until `0.4.0` is published, `npx fastrmemory@latest mcp init` still resolves to `0.3.1` and does not include the command; use the source-checkout path in the MCP setup section. CI run `39879595191` at `098100e` (the 0.4.0 preparation commit) passed all six matrix jobs on 2026-10-23, including Windows Node `22.x` and `24.x`. The release post for 0.2.1 remains at [docs/blog/2026-10-21-fastrmemory-0.2.1.md](docs/blog/2026-10-21-fastrmemory-0.2.1.md). The exact release surface is in [CHANGELOG.md](CHANGELOG.md). The headline benchmark uses **240 deterministic synthetic cases with a 20% holdout**, not SWE-bench or LongMemEval. Public LongMemEval, LoCoMo, and self-repository retrieval-only results plus pinned external baselines are in [BENCHMARKS.md](BENCHMARKS.md); no QA-leaderboard parity is claimed. Performance, packaging, and retrieval claims are tracked in [CLAIMS.md](CLAIMS.md); every README section is mapped to claim IDs in the README claim trace at the end of that ledger. Methodology, caveats, and raw JSON are in [BENCHMARKS.md](BENCHMARKS.md).
+> **Status (2026-10-23):** **`fastrmemory@0.4.0` is published and is `latest`.** Evidence: `npm view fastrmemory version` -> `0.4.0`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.4.0"}`; tag `v0.4.0` (`bb365c2`); published 2026-10-23 07:32 UTC via GitHub Actions OIDC with npm provenance; release workflow run `39918288792` passed the full gate, clean tarball install, registry verification, and GitHub Release upload; GitHub Release tarball SHA-256 `b784e3e12b8a50deaee3b38dbc1f45c756bc37462f2d40433fdda5288cf554ad`; `npm install -g fastrmemory@0.4.0` + `fastr --version` -> `0.4.0`; `npm audit signatures` reports 5 verified registry signatures and 4 verified attestations. Caveat: Node.js >=22.16.0; `0.3.1` remains published historical and `0.3.0` remains historical. This release adds `fastr mcp init` and LF checkout enforcement, with no schema migration. The old scoped npm entries (`@atifjubaer/fastrmemory` and `fastrmemory@0.0.0-stage`) were removed on 2026-10-23; the GitHub `v0.2.1` tag and release remain as history. This README tracks current `main`. Current `main` is **`0.5.0`** and adds `fastr mcp init --source local`; it has **297 tests / 53 files**. `0.5.0` is prepared but not yet published, so `--source local` remains unavailable from npm `latest` until the `v0.5.0` release workflow completes. Until then, use the exact `0.4.0` version for reproducibility. CI run `39935705994` at `6c2a53a` passed all six matrix jobs on 2026-10-23, including Windows Node `22.x` and `24.x`; the `0.4.0` release commit `bb365c2` passed run `39879913968`. The release post for 0.2.1 remains at [docs/blog/2026-10-21-fastrmemory-0.2.1.md](docs/blog/2026-10-21-fastrmemory-0.2.1.md). The exact release surface is in [CHANGELOG.md](CHANGELOG.md). The headline benchmark uses **240 deterministic synthetic cases with a 20% holdout**, not SWE-bench or LongMemEval. Public LongMemEval, LoCoMo, and self-repository retrieval-only results plus pinned external baselines are in [BENCHMARKS.md](BENCHMARKS.md); no QA-leaderboard parity is claimed. Performance, packaging, and retrieval claims are tracked in [CLAIMS.md](CLAIMS.md); every README section is mapped to claim IDs in the README claim trace at the end of that ledger. Methodology, caveats, and raw JSON are in [BENCHMARKS.md](BENCHMARKS.md).
 
 <p align="center">
   <a href="#-overview">Overview</a> &bull;
@@ -39,15 +39,15 @@
 
 | Claim | Current result | Evidence |
 |---|---|---|
-| Install path | Published `fastrmemory@0.3.1`; `0.4.0` prepared on `main`, not published | `npm view fastrmemory version` -> `0.3.1`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.3.1"}`; `npm install -g fastrmemory@0.3.1`; `fastr --version` -> `0.3.1`; GitHub Release tarball SHA-256 `747f6179...`; old scoped npm entries removed |
-| Synthetic retrieval | Holdout `95.8%` Hit@1, `100%` Hit@5, MRR `0.969` | `npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json` |
-| Test suite | `293` tests across `53` files on current HEAD; published `0.3.1` is `282` / `52`; v0.2.1 is `235` / `43` | `npm test` |
-| MCP setup (0.4.0 prepared) | `fastr mcp init` merges portable configs for 9 JSON clients and prints a Codex TOML snippet | `npm test -- tests/mcp-init.test.ts` -> `11 passed`; `fastr mcp init --client claude --dry-run` |
+| Install path | Published `fastrmemory@0.4.0` | `npm view fastrmemory version` -> `0.4.0`; `npm view fastrmemory dist-tags --json` -> `{"latest":"0.4.0"}`; `npm install -g fastrmemory@0.4.0`; `fastr --version` -> `0.4.0`; GitHub Release tarball SHA-256 `b784e3e1...`; old scoped npm entries removed |
+| Synthetic retrieval (optional MiniLM) | Holdout `95.8%` Hit@1, `100%` Hit@5, MRR `0.969` | `npx tsx scripts/eval-bench.ts --split all --embeddings minilm --out bench/results/minilm.json` |
+| Test suite | `297` tests across `53` files on current `main` (`0.5.0`); published `0.4.0` is `293` / `53`; `0.3.1` is `282` / `52`; v0.2.1 is `235` / `43` | `npm test`; `npm run check:ci` |
+| MCP setup | `fastr mcp init` merges portable registry configs or active-CLI local configs for 9 JSON clients and prints a Codex TOML snippet; `--source local` ships in `0.5.0` (prepared; `0.4.0` remains published until `v0.5.0`) | `npm test -- tests/mcp-init.test.ts` -> `15 passed`; `fastr mcp init --client claude --source local --dry-run --json` -> `node .../dist/bin/fastr.js mcp --project ...` |
 | Crash safety | 10/10 runs, 0 lost, 0 duplicate ids/titles | `npm run test:crash`; `bench/results/crash-test.json` |
 | Public retrieval (0.3.0) | LongMemEval `+10.4pp` / `+11.0pp` Hit@5; LoCoMo `+4.4pp` / `+2.3pp` (target missed) | [docs/EXTERNAL_BASELINE.md](docs/EXTERNAL_BASELINE.md) |
 | Release score | Provisional `9.4 / 10`; `9.2` target met; Retrieval remains Partial | [SCORECARD.md](SCORECARD.md) |
 
-The synthetic table is not SWE-bench or LongMemEval. Public numbers are retrieval-only and are not QA-leaderboard results. Full provenance is in [CLAIMS.md](CLAIMS.md).
+The synthetic table is not SWE-bench or LongMemEval. Public numbers are retrieval-only and are not QA-leaderboard results. The `95.8%` row uses optional MiniLM; the default offline hash path scores `77.1%` Hit@1 / `93.8%` Hit@5 on the same holdout. Full provenance is in [CLAIMS.md](CLAIMS.md).
 
 ---
 
@@ -110,42 +110,68 @@ Clients commonly used with FastrMemory include Codex CLI, Gemini CLI, OpenCode,
 
 ### ⚡ Run Without a Global Install
 
-The canonical package target is unscoped `fastrmemory@0.3.1`. `0.4.0` is prepared on `main` but is not published; keep using `0.3.1` for installs until the release workflow completes. The old scoped npm entries were removed on 2026-10-23.
+The canonical package target is unscoped `fastrmemory@0.4.0`. `0.3.1` remains published historical. The old scoped npm entries were removed on 2026-10-23.
 
 ```bash
 # Canonical one-shot (pins the exact release):
-npx -y fastrmemory@0.3.1 setup
+npx -y fastrmemory@0.4.0 setup
 
 # Or launch the local Web UI:
-npx -y fastrmemory@0.3.1 ui
+npx -y fastrmemory@0.4.0 ui
 ```
 
-The GitHub source path remains available for development only: `npx github:atifjubaer/fastrmemory setup`. For a reproducible source install, pin the tag: `npx github:atifjubaer/fastrmemory#v0.3.1 setup`. The current `main` contains the unpublished `0.4.0` source. Do not use either GitHub form in generated MCP or hook configs; those must use the npm package. The default `latest` channel tracks new releases, and `--channel pinned` records the exact version for reproducibility.
+The GitHub source path remains available for development only: `npx github:atifjubaer/fastrmemory setup`. For a reproducible source install, pin the tag: `npx github:atifjubaer/fastrmemory#v0.4.0 setup`. Do not use either GitHub form in generated MCP or hook configs; those must use the npm package. The default `latest` channel tracks new releases, and `--channel pinned` records the exact version for reproducibility.
 
 ---
 
 ### Install from npm
 
 ```bash
-# Canonical install (latest is 0.3.1):
+# Canonical install (latest is 0.4.0):
 npm install -g fastrmemory
 fastr --version
 
 # Exact release:
-npm install -g fastrmemory@0.3.1
+npm install -g fastrmemory@0.4.0
 ```
 
 For a one-shot run without a global install:
 
 ```bash
-npx -y fastrmemory@0.3.1 --version
+npx -y fastrmemory@0.4.0 --version
 ```
 
-`0.3.1` is built from tag `v0.3.1` by `.github/workflows/release.yml`, which runs the full gate, publishes with npm provenance, and attaches the same tarball to the GitHub Release. Verify the registry result with `npm view fastrmemory@0.3.1 version` and `npm view fastrmemory dist-tags --json`; a first E404 for a few minutes is registry propagation, not a failed publish. The old scoped npm entries remain removed. Do not republish `0.3.0`. `0.4.0` is prepared on `main`; no tag `v0.4.0` and no npm publication exist as of 2026-10-23.
+`0.4.0` is built from tag `v0.4.0` by `.github/workflows/release.yml`, which runs the full gate, publishes with npm provenance, and attaches the same tarball to the GitHub Release. Verify the registry result with `npm view fastrmemory@0.4.0 version` and `npm view fastrmemory dist-tags --json`; a first E404 for a few minutes is registry propagation, not a failed publish. The old scoped npm entries remain removed. Do not republish `0.3.0`. `0.3.1` remains published historical.
+
+### Update an Existing Install
+
+Stop every agent, hook, `fastr ui`, and `fastr daemon` before changing versions. Run this from the project root:
+
+```bash
+# 1. Back up memory before changing versions
+fastr backup fastr-backup.jsonl
+fastr backup --verify fastr-backup.jsonl
+
+# 2. Update the global CLI
+npm install -g fastrmemory@latest
+fastr --version
+
+# 3. Refresh project integration (choose what you use)
+fastr mcp init --client all --scope project   # portable npx configs only
+fastr mcp init --client all --scope user --source local --profile core  # installed CLI
+fastr setup                                   # MCP configs, AGENTS.md, and skills
+fastr hook install                            # lifecycle hooks plus MCP for hook clients
+
+# 4. Verify
+fastr status
+fastr hygiene
+```
+
+`0.5.0` has no schema migration. If you use `--channel pinned`, rerun `fastr mcp init` after each update; with the default `latest` channel, restart the client to pick up the new release. If you use `--source local`, the config points at the installed CLI, so updating the global package updates the server without rewriting the config. `fastr setup` refreshes copied skills, overwrites same-named skill files, removes retired skills, and leaves user-owned directories. `fastr hook install` does not copy skills. See [MIGRATION.md](MIGRATION.md) for rollback.
 
 ### One-Command MCP Setup
 
-`fastr mcp init` is the shadcn-style setup path. It is config-only: it merges the `fastrmemory` MCP entry into an existing client config, preserves unrelated keys, writes a one-time `.fastr.bak` backup, and is idempotent. It does not install lifecycle hooks, skills, or the OpenCode plugin; use `fastr hook install` for those.
+`fastr mcp init` is the shadcn-style setup path. It is config-only: it merges the `fastrmemory` MCP entry into an existing client config, preserves unrelated keys, writes a one-time `.fastr.bak` backup, and is idempotent. It does not install lifecycle hooks, skills, or the OpenCode plugin; use `fastr hook install` for hooks and the OpenCode plugin, and `fastr setup` for skills.
 
 ```bash
 # Claude Code (project-scoped .mcp.json)
@@ -175,31 +201,41 @@ yarn dlx fastrmemory@latest mcp init --client claude
 bunx fastrmemory@latest mcp init --client claude
 ```
 
-The default `--channel latest` writes `fastrmemory@latest`, so a client restart picks up the newest npm release. Use `--channel pinned` for a reproducible config containing the exact version that ran the command; on current `main` that writes `fastrmemory@0.4.0`, which is not installable from npm until the release publishes. `--runner pnpm|yarn|bunx` changes the generated runner, `--profile core` selects the 12-tool surface, `--dry-run` prints targets without writing, and `--scope user` writes user-level configs with an explicit `--project /absolute/path` so the server always opens the intended database. Codex prints a `[mcp_servers.fastrmemory]` TOML block for `~/.codex/config.toml` instead of rewriting a user-owned TOML file.
+The default `--channel latest` writes `fastrmemory@latest`, so a client restart picks up the newest npm release. Use `--channel pinned` for a reproducible config containing the exact version that ran the command; on current `main` that writes `fastrmemory@0.5.0` (pending publication). `--runner pnpm|yarn|bunx` changes the generated runner, `--profile core` selects the 12-tool surface, `--dry-run` prints targets without writing, and `--scope user` writes user-level configs with an explicit `--project /absolute/path` so the server always opens the intended database. Codex prints a `[mcp_servers.fastrmemory]` TOML block for `~/.codex/config.toml` instead of rewriting a user-owned TOML file.
 
-> `mcp init` is prepared in `0.4.0` on `main`; `0.4.0` is not tagged or published as of 2026-10-23, and `npx fastrmemory@latest mcp init` still resolves to published `0.3.1`. Until `0.4.0` publishes, run the same commands from a source checkout (`npx --yes github:atifjubaer/fastrmemory#main mcp init ...`) or after `npm run build:core` with `node bin/fastr-guard.mjs mcp init ...`.
+For a globally installed CLI, use `--source local` to write the active CLI path instead of an npx command. It always appends an absolute `--project`, so the config is machine-specific but starts without an npx cold start:
+
+```bash
+fastr mcp init --client all --scope user --source local --profile core
+```
+
+Updating the global package updates the server; rerun the command only if the CLI path changes. Use the default `--source registry` for portable project configs that are committed and shared across machines.
+
+> `--source local` ships in `0.5.0`. Until the `v0.5.0` release workflow completes, published `0.4.0` remains the install target; use `fastr setup` on `0.4.0` for an installed-CLI config.
+
+> `mcp init` ships in `0.4.0`; `npx fastrmemory@latest mcp init ...` now resolves to published `0.4.0`. If you need the previous release, use `fastr setup` or pin `fastrmemory@0.3.1`.
 
 ### Install from GitHub
 
 For a one-shot source run, pin the release tag:
 
 ```bash
-npx --yes github:atifjubaer/fastrmemory#v0.3.1 --version
-npx --yes github:atifjubaer/fastrmemory#v0.3.1 setup
+npx --yes github:atifjubaer/fastrmemory#v0.4.0 --version
+npx --yes github:atifjubaer/fastrmemory#v0.4.0 setup
 ```
 
 For a global CLI without npm's Git resolver, download the release tarball:
 
 ```bash
-curl -L -o fastrmemory-0.3.1.tgz \
-  https://github.com/atifjubaer/fastrmemory/releases/download/v0.3.1/fastrmemory-0.3.1.tgz
-npm install -g ./fastrmemory-0.3.1.tgz
+curl -L -o fastrmemory-0.4.0.tgz \
+  https://github.com/atifjubaer/fastrmemory/releases/download/v0.4.0/fastrmemory-0.4.0.tgz
+npm install -g ./fastrmemory-0.4.0.tgz
 fastr --version
 ```
 
-On Windows, download the same URL with `Invoke-WebRequest` or a browser, then run `npm install -g .\fastrmemory-0.3.1.tgz`. For a local project install, use `npm install --no-save ./fastrmemory-0.3.1.tgz` instead of the global flag.
+On Windows, download the same URL with `Invoke-WebRequest` or a browser, then run `npm install -g .\fastrmemory-0.4.0.tgz`. For a local project install, use `npm install --no-save ./fastrmemory-0.4.0.tgz` instead of the global flag.
 
-> Git installs build from source and are slower than the npm tarball; for a global CLI, prefer the npm package or the release tarball above. `npm install -g git+https://...` is not recommended with npm 11 because the `prepare` build does not receive dev dependencies. Both `fastrmemory` and `fastr` (short alias) are executable after installation. The canonical package is unscoped `fastrmemory@0.3.1`; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.
+> Git installs build from source and are slower than the npm tarball; for a global CLI, prefer the npm package or the release tarball above. `npm install -g git+https://...` is not recommended with npm 11 because the `prepare` build does not receive dev dependencies. Both `fastrmemory` and `fastr` (short alias) are executable after installation. The canonical package is unscoped `fastrmemory@0.4.0`; the old scoped npm entries are gone. Use npm for generated MCP and hook configs so installs stay reproducible.
 
 ### 2. Verify Database Health
 
@@ -299,9 +335,10 @@ fastrmemory daemon start
 fastrmemory daemon status
 fastrmemory daemon stop
 
-# Auto-wire MCP configs, lifecycle hooks, and Planetary Skills into Claude Code, Cursor,
-# Gemini CLI, GitHub Copilot CLI, and OpenCode; setup also wires Antigravity, Claude Desktop, and Windsurf:
+# Auto-wire MCP + lifecycle hooks for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode:
 fastrmemory hook install
+
+# Auto-wire MCP + AGENTS.md + Planetary Skills; setup also wires Antigravity, Claude Desktop, and Windsurf:
 fastrmemory setup
 
 # Mine past Git bug fixes directly into staging error traps:
@@ -344,7 +381,7 @@ fastrmemory guard --strict
 
 ## 🔌 One-Click Agent MCP Configuration
 
-`fastr mcp init` is the one-command path for MCP-only wiring. It writes the platform-correct runner (`npx`, `pnpm dlx`, `yarn dlx`, or `bunx`; `cmd /c ...` on native Windows), preserves unrelated config keys, and is idempotent. `fastr setup` remains the full installer for `.fastr/`, `AGENTS.md`, skills, and lifecycle hooks; `fastr hook install` remains the hook-only path.
+`fastr mcp init` is the one-command path for MCP-only wiring. By default it uses `--source registry` and writes the platform-correct portable runner (`npx`, `pnpm dlx`, `yarn dlx`, or `bunx`; `cmd /c ...` on native Windows). Pass `--source local` to write the active CLI path plus an absolute `--project`, which is useful for a globally installed CLI but makes the config machine-specific. It preserves unrelated config keys and is idempotent. `fastr setup` remains the full installer for `.fastr/`, `AGENTS.md`, MCP configs, and skills; `fastr hook install` adds lifecycle hooks plus MCP configs for Claude Code, Cursor, Gemini CLI, Copilot CLI, and OpenCode.
 
 `fastr hook install` merges lifecycle hooks for Claude Code, Cursor, Gemini CLI, GitHub Copilot CLI, and OpenCode, and writes the OpenCode context/compaction plugin. Gemini CLI requires strict JSON on hook stdout; Copilot returns `permissionDecision: "ask"` for an active trap because it has no model-facing advisory field for `preToolUse`.
 
@@ -376,13 +413,15 @@ Example POSIX project config generated by `fastr mcp init --client cursor` (Wind
 
 VS Code uses `servers` instead of `mcpServers`; OpenCode uses `mcp.servers` with a command array and `"type": "local"`. Existing `opencode.json(c)` settings are preserved, but a JSONC config is reported for manual wiring rather than rewritten. Codex is always printed as a `[mcp_servers.fastrmemory]` TOML block because rewriting a user-owned TOML file safely requires a dedicated parser.
 
-For user-scoped clients, the generated entry includes `--project /absolute/path/to/repo`; this prevents the client's launch directory from selecting the wrong database. `fastr setup` also writes the absolute `node` path and is the recommended path when the client cannot launch package-runner shims. On native Windows, `fastr mcp init` automatically emits `"command": "cmd"` with `"/c"` and the runner, so manual `npx.cmd` fixes are not needed.
+For user-scoped clients, the generated entry includes `--project /absolute/path/to/repo`; this prevents the client's launch directory from selecting the wrong database. `fastr setup` also writes the absolute `node` path and is the recommended path when the client cannot launch package-runner shims. `--source local` is the `mcp init` equivalent for an installed CLI: it writes the active CLI path and an absolute `--project`; use `--source registry` (the default) when the config will be committed or shared. `--source local` ships in `0.5.0`; on published `0.4.0`, use `fastr setup` for an installed-CLI config. On native Windows, `fastr mcp init` automatically emits `"command": "cmd"` with `"/c"` and the runner, so manual `npx.cmd` fixes are not needed.
+
+`--client all --scope project` covers the six project-scoped clients in the table. `--client all --scope user` covers the eight user-scoped clients; OpenCode and Copilot CLI are project-only, while Codex prints a TOML block for manual insertion. User-scoped entries pin one `--project` database, so use project scope when each developer may open a different checkout.
 
 ---
 
 ## 🛠️ MCP Server: Tools & Resources
 
-Built using the official **v2 `@modelcontextprotocol/server`** SDK. The tool list below describes **0.4.0** (prepared; unchanged from 0.3.1); the v0.2.1 release has 4 resources.
+Built using the official **v2 `@modelcontextprotocol/server`** SDK. The tool list below describes **0.5.0** (tool surface unchanged from 0.4.0); the v0.2.1 release has 4 resources.
 
 ### 41 MCP Tools
 
@@ -516,6 +555,8 @@ FastrMemory ships 10 Agent Skills (in `skills/`, mirrored to `.cursor/skills/`)
 
 Run `npm run check:skills` to validate every tool call in the skills against `src/mcp/server.ts`.
 
+After updating the CLI, re-run `fastr setup` to refresh the copied skills. The installer overwrites same-named skill files, removes retired skills, and leaves unrelated user-owned directories. `fastr hook install` does not copy skills. Restart the client after setup. If you install the Claude Code plugin instead, update the plugin rather than maintaining a second copied skill set.
+
 ---
 
 ## 🏗️ Architecture
@@ -560,7 +601,7 @@ Run the comprehensive unit test suite:
 npm test
 ```
 
-All **293 tests pass** across **53 test files** on current HEAD (`0.4.0` prepared); published `0.3.1` has **282 tests / 52 files**, and v0.2.1 has **235 tests / 43 files**. Coverage includes database schema, WAL locking, offline spooling, bi-temporal supersession, secret scrubbing, two-zone rendering, automated benchmarks, snapshots/rollback, branch merge conflict reports, replay/diff, memory envelopes, confidence tiers and 3-bad dormancy, memory hygiene checks, Memory CI, conflict-aware recall, portable backup manifests and verified restore, local rule import, OpenCode V2, Gemini CLI, and Copilot CLI wiring, git-learner, cognitive blame, commit synthesis, hybrid background daemon, token compression, self-healing doctor, multimodal vision, web dashboard server, pre-merge trap guardian, UI loopback security boundaries, atomic installer configuration safety, and shadcn-style `mcp init` client config merges.
+All **297 tests pass** across **53 test files** on current `main` (`0.5.0`); published `0.4.0` has **293 tests / 53 files**, `0.3.1` has **282 / 52**, and v0.2.1 has **235 / 43**. Coverage includes database schema, WAL locking, offline spooling, bi-temporal supersession, secret scrubbing, two-zone rendering, automated benchmarks, snapshots/rollback, branch merge conflict reports, replay/diff, memory envelopes, confidence tiers and 3-bad dormancy, memory hygiene checks, Memory CI, conflict-aware recall, portable backup manifests and verified restore, local rule import, OpenCode V2, Gemini CLI, and Copilot CLI wiring, git-learner, cognitive blame, commit synthesis, hybrid background daemon, token compression, self-healing doctor, multimodal vision, web dashboard server, pre-merge trap guardian, UI loopback security boundaries, atomic installer configuration safety, and shadcn-style `mcp init` client config merges, including local-source entries.
 
 **CI performance gates:** `check:query-plans`, `check:recall-latency`, and `check:install-size` run inside `check:ci`. CI executes them on the canonical Ubuntu/Node 24 job; other matrix jobs set `FASTR_PERF_GATE=0` because timing is runner-sensitive, while functional tests still run on every matrix entry.
 

package/dist/bin/fastr.js

@@ -10,7 +10,7 @@ import { runInteractiveSetup } from '../src/installer/setup.js';
 import { formatBenchmarkMarkdown } from '../src/bench/benchmark.js';
 import { startUiServer } from '../src/ui/server.js';
 import { installAgentHooks } from '../src/installer/hooks.js';
-import { formatMcpInitResult, initMcpClients, parseMcpChannel, parseMcpClients, parseMcpProfile, parseMcpRunner, parseMcpScope, } from '../src/installer/mcp-init.js';
+import { formatMcpInitResult, initMcpClients, parseMcpChannel, parseMcpClients, parseMcpProfile, parseMcpRunner, parseMcpScope, parseMcpSource, } from '../src/installer/mcp-init.js';
 import { learnFromGitHistory } from '../src/learn/git-learner.js';
 import { exportToObsidianVault } from '../src/export/obsidian.js';
 import { runLifecycleHook, toClaudeHookStdout, toGeminiHookStdout, toCopilotHookStdout } from '../src/hooks/runner.js';
@@ -87,6 +87,7 @@ mcpCmd
     .option('--channel <channel>', 'latest (auto-update) or pinned (exact version)', 'latest')
     .option('--runner <runner>', 'npx, pnpm, yarn, or bunx', 'npx')
     .option('--profile <profile>', 'Tool surface: full or core', 'full')
+    .option('--source <source>', 'registry (portable npx) or local (active CLI)', 'registry')
     .option('--project <path>', 'Project root for user-scoped configs', process.cwd())
     .option('--dry-run', 'Print the target files without writing', false)
     .option('--json', 'Print a machine-readable result', false)
@@ -96,7 +97,10 @@ Examples:
   $ fastrmemory mcp init --client cursor,vscode --channel pinned
   $ fastrmemory mcp init --client opencode --runner pnpm
   $ fastrmemory mcp init --client all --scope project
-  $ fastrmemory mcp init --client codex --scope user`)
+  $ fastrmemory mcp init --client all --scope user --source local --profile core
+  $ fastrmemory mcp init --client codex --scope user
+
+--source local writes the active CLI and an absolute --project; project configs are machine-specific.`)
     .action((options) => {
     try {
         const scope = parseMcpScope(options.scope);
@@ -104,6 +108,7 @@ Examples:
         const channel = parseMcpChannel(options.channel);
         const runner = parseMcpRunner(options.runner);
         const profile = parseMcpProfile(options.profile);
+        const source = parseMcpSource(options.source);
         const results = initMcpClients({
             clients,
             scope,
@@ -111,10 +116,11 @@ Examples:
             channel,
             runner,
             profile,
+            source,
             dryRun: options.dryRun,
         });
         if (options.json) {
-            console.log(JSON.stringify({ scope, channel, runner, profile, results }, null, 2));
+            console.log(JSON.stringify({ scope, channel, runner, profile, source, results }, null, 2));
             return;
         }
         for (const result of results) {