fastrmemory 0.3.0 → 0.4.0

package/skills/fastr-memory/SKILL.md

@@ -1,51 +1,51 @@
----
-name: fastr-memory
-description: Use at the start of any coding task and before reading-to-edit, creating, or modifying project files. Checks FastrMemory for [TRAP] warnings on the target files, then recalls relevant rules and decisions so you do not repeat known mistakes or contradict project conventions.
----
-
-# FastrMemory: Recall Before You Code
-
-## When to use
-- A new task or sub-task begins (feature, bug fix, refactor, review).
-- You are about to edit or create a file you have not checked this session.
-- You hit unfamiliar architecture or a convention you are unsure about.
-
-## Steps
-
-1. **Check traps on the files you will touch** (always, before the first edit):
-   ```js
-   fastr_trap_recall({ files: ["src/auth/jwt.ts", "src/auth/guard.ts"] })
-   ```
-   For each `[TRAP]` returned, state in your plan how the change avoids it.
-
-2. **Recall rules and decisions for the task**:
-   ```js
-   fastr_recall({
-     query: "JWT expiry handling in auth guard",
-     files: ["src/auth/jwt.ts"],
-     module: "auth",
-     budgetTokens: 1500
-   })
-   ```
-   Set `includeHistory: true` only when you need superseded rules (for example, to learn why something changed).
-
-   Or get one token-budgeted context block (rules + traps + ready tasks + last handoff):
-   ```js
-   fastr_assemble({
-     taskDescription: "Add refresh-token rotation to the auth guard",
-     targetFiles: ["src/auth/guard.ts"],
-     module: "auth",
-     budgetTokens: 2000
-   })
-   ```
-
-3. **Drill down only when needed**:
-   - Everything linked to one file: `fastr_file_history({ filePath: "src/auth/jwt.ts" })`
-   - Neighbouring files and memories: `fastr_graph_query({ filePath: "src/auth/jwt.ts", depth: 2 })`
-   - Verbatim stack trace or diff behind a memory: `fastr_drill({ memoryId: "mem_8f2a1c" })`
-   - Where the last session stopped: `fastr_handoff({ action: "latest" })`
-
-## Ground rules
-- If recall returns nothing, say so. Do not invent project conventions.
-- Note the IDs of memories you relied on; rate them at the end with the `fastr-session-commit` skill.
-- When a failure is diagnosed mid-task, switch to the `fastr-trap-log` skill immediately.
+---
+name: fastr-memory
+description: Use at the start of any coding task and before reading-to-edit, creating, or modifying project files. Checks FastrMemory for [TRAP] warnings on the target files, then recalls relevant rules and decisions so you do not repeat known mistakes or contradict project conventions.
+---
+
+# FastrMemory: Recall Before You Code
+
+## When to use
+- A new task or sub-task begins (feature, bug fix, refactor, review).
+- You are about to edit or create a file you have not checked this session.
+- You hit unfamiliar architecture or a convention you are unsure about.
+
+## Steps
+
+1. **Check traps on the files you will touch** (always, before the first edit):
+   ```js
+   fastr_trap_recall({ files: ["src/auth/jwt.ts", "src/auth/guard.ts"] })
+   ```
+   For each `[TRAP]` returned, state in your plan how the change avoids it.
+
+2. **Recall rules and decisions for the task**:
+   ```js
+   fastr_recall({
+     query: "JWT expiry handling in auth guard",
+     files: ["src/auth/jwt.ts"],
+     module: "auth",
+     budgetTokens: 1500
+   })
+   ```
+   Set `includeHistory: true` only when you need superseded rules (for example, to learn why something changed).
+
+   Or get one token-budgeted context block (rules + traps + ready tasks + last handoff):
+   ```js
+   fastr_assemble({
+     taskDescription: "Add refresh-token rotation to the auth guard",
+     targetFiles: ["src/auth/guard.ts"],
+     module: "auth",
+     budgetTokens: 2000
+   })
+   ```
+
+3. **Drill down only when needed**:
+   - Everything linked to one file: `fastr_file_history({ filePath: "src/auth/jwt.ts" })`
+   - Neighbouring files and memories: `fastr_graph_query({ filePath: "src/auth/jwt.ts", depth: 2 })`
+   - Verbatim stack trace or diff behind a memory: `fastr_drill({ memoryId: "mem_8f2a1c" })`
+   - Where the last session stopped: `fastr_handoff({ action: "latest" })`
+
+## Ground rules
+- If recall returns nothing, say so. Do not invent project conventions.
+- Note the IDs of memories you relied on; rate them at the end with the `fastr-session-commit` skill.
+- When a failure is diagnosed mid-task, switch to the `fastr-trap-log` skill immediately.

package/skills/fastr-plan-estimate/SKILL.md

@@ -1,45 +1,45 @@
----
-name: fastr-plan-estimate
-description: Use when the user asks how long or how risky a change will be, before committing to an estimate or plan for a migration, refactor, or bug fix, and again when that work finishes so the estimate can be closed with the actual result. Calibrates estimates against the project's own track record.
----
-
-# FastrMemory: Calibrated Estimates and Risk
-
-## When to use
-- You are asked for an effort or time estimate.
-- You are planning edits to files with a history of breakage.
-- A previously estimated task is complete (close the prediction).
-
-## 1. Check the base rate for this kind of work
-```js
-fastr_predict_baserate({ classTag: "migration" })
-```
-If history exists, multiply your inside-view estimate by the reported median ratio. Pick a stable `classTag` (for example `migration`, `refactor`, `bugfix`, `feature`) and reuse it.
-
-## 2. Check pre-edit risk for the target files
-```js
-fastr_risk_predict({ targetFiles: ["src/db/schema.ts", "src/db/repository.ts"], module: "db" })
-```
-High risk means: read the traps (`fastr-memory` skill), plan smaller steps, and add tests first.
-
-## 3. Record the estimate
-```js
-fastr_predict({
-  action: "create",
-  classTag: "migration",
-  claimText: "Add bi-temporal columns to the actions table",
-  estimateValue: 3,
-  estimateUnit: "hours"
-})
-```
-Note the returned prediction ID.
-
-## 4. Close it when the work is done
-```js
-fastr_predict({ action: "close", predictionId: 12, actualValue: 5 })
-```
-List open predictions with `fastr_predict({ action: "list", classTag: "migration" })`.
-
-## Rules
-- Report the calibrated number, and say what the raw estimate was.
-- Always close predictions; unclosed ones never improve future calibration.
+---
+name: fastr-plan-estimate
+description: Use when the user asks how long or how risky a change will be, before committing to an estimate or plan for a migration, refactor, or bug fix, and again when that work finishes so the estimate can be closed with the actual result. Calibrates estimates against the project's own track record.
+---
+
+# FastrMemory: Calibrated Estimates and Risk
+
+## When to use
+- You are asked for an effort or time estimate.
+- You are planning edits to files with a history of breakage.
+- A previously estimated task is complete (close the prediction).
+
+## 1. Check the base rate for this kind of work
+```js
+fastr_predict_baserate({ classTag: "migration" })
+```
+If history exists, multiply your inside-view estimate by the reported median ratio. Pick a stable `classTag` (for example `migration`, `refactor`, `bugfix`, `feature`) and reuse it.
+
+## 2. Check pre-edit risk for the target files
+```js
+fastr_risk_predict({ targetFiles: ["src/db/schema.ts", "src/db/repository.ts"], module: "db" })
+```
+High risk means: read the traps (`fastr-memory` skill), plan smaller steps, and add tests first.
+
+## 3. Record the estimate
+```js
+fastr_predict({
+  action: "create",
+  classTag: "migration",
+  claimText: "Add bi-temporal columns to the actions table",
+  estimateValue: 3,
+  estimateUnit: "hours"
+})
+```
+Note the returned prediction ID.
+
+## 4. Close it when the work is done
+```js
+fastr_predict({ action: "close", predictionId: 12, actualValue: 5 })
+```
+List open predictions with `fastr_predict({ action: "list", classTag: "migration" })`.
+
+## Rules
+- Report the calibrated number, and say what the raw estimate was.
+- Always close predictions; unclosed ones never improve future calibration.

package/skills/fastr-session-commit/SKILL.md

@@ -1,49 +1,49 @@
----
-name: fastr-session-commit
-description: Use when a task or milestone is finished and tests pass, before handing control back to the user, or when you are about to run out of context. Rates the memories you used, supersedes rules your work invalidated, and saves a handoff that promotes this session's staging memories to verified.
----
-
-# FastrMemory: Commit the Session
-
-## When to use
-- The task is done and the test suite passes.
-- You are yielding to the user or another agent, or context is about to be compacted.
-- You are resuming work and need to know where the last session stopped.
-
-## Steps
-
-1. **Supersede rules your change made obsolete** (keeps history, redirects future recall):
-   ```js
-   fastr_supersede({
-     oldMemoryId: "mem_8f2a1c",
-     newTitle: "Use Vitest for all unit tests",
-     newContent: "The project migrated from Jest to Vitest for native ESM. Do not add Jest config.",
-     reason: "Test runner migration",
-     files: ["vitest.config.ts"]
-   })
-   ```
-
-2. **Rate each memory you actually relied on** (per ID, never the whole batch):
-   ```js
-   fastr_feedback({ memoryId: "mem_3c9d0e", outcome: "good" })
-   fastr_feedback({ memoryId: "mem_77ab12", outcome: "bad", note: "Described the old config loader" })
-   ```
-
-3. **Save the handoff and verify staging**:
-   ```js
-   fastr_handoff({
-     action: "save",
-     taskTitle: "Refresh-token rotation in auth guard",
-     summary: "Added rotation and revocation list; all auth tests pass.",
-     nextStep: "Wire revocation list cleanup into the nightly job.",
-     activeFiles: ["src/auth/guard.ts", "src/auth/jwt.ts"],
-     verifyStaging: true
-   })
-   ```
-   Only pass `verifyStaging: true` when tests pass; it promotes every staging memory from this project to verified.
-
-## Resuming a session
-```js
-fastr_handoff({ action: "latest" })
-```
-Read the summary and next step before planning, then follow the `fastr-memory` skill.
+---
+name: fastr-session-commit
+description: Use when a task or milestone is finished and tests pass, before handing control back to the user, or when you are about to run out of context. Rates the memories you used, supersedes rules your work invalidated, and saves a handoff that promotes this session's staging memories to verified.
+---
+
+# FastrMemory: Commit the Session
+
+## When to use
+- The task is done and the test suite passes.
+- You are yielding to the user or another agent, or context is about to be compacted.
+- You are resuming work and need to know where the last session stopped.
+
+## Steps
+
+1. **Supersede rules your change made obsolete** (keeps history, redirects future recall):
+   ```js
+   fastr_supersede({
+     oldMemoryId: "mem_8f2a1c",
+     newTitle: "Use Vitest for all unit tests",
+     newContent: "The project migrated from Jest to Vitest for native ESM. Do not add Jest config.",
+     reason: "Test runner migration",
+     files: ["vitest.config.ts"]
+   })
+   ```
+
+2. **Rate each memory you actually relied on** (per ID, never the whole batch):
+   ```js
+   fastr_feedback({ memoryId: "mem_3c9d0e", outcome: "good" })
+   fastr_feedback({ memoryId: "mem_77ab12", outcome: "bad", note: "Described the old config loader" })
+   ```
+
+3. **Save the handoff and verify staging**:
+   ```js
+   fastr_handoff({
+     action: "save",
+     taskTitle: "Refresh-token rotation in auth guard",
+     summary: "Added rotation and revocation list; all auth tests pass.",
+     nextStep: "Wire revocation list cleanup into the nightly job.",
+     activeFiles: ["src/auth/guard.ts", "src/auth/jwt.ts"],
+     verifyStaging: true
+   })
+   ```
+   Only pass `verifyStaging: true` when tests pass; it promotes every staging memory from this project to verified.
+
+## Resuming a session
+```js
+fastr_handoff({ action: "latest" })
+```
+Read the summary and next step before planning, then follow the `fastr-memory` skill.

package/skills/fastr-setup/SKILL.md

@@ -1,45 +1,45 @@
----
-name: fastr-setup
-description: Use when FastrMemory tools are missing or not responding in Claude Code, when the user asks to install or wire up FastrMemory in a project, or when hooks (session start, pre-edit trap warnings) are not firing. Covers project install, manual MCP registration, and verification.
-allowed-tools: Bash(fastr *), Bash(fastrmemory *), Bash(npx -y fastrmemory*)
----
-
-# FastrMemory: Wire Up Claude Code
-
-## When to use
-- `fastr_*` tools are not available in the session.
-- The user asks to set up FastrMemory for this repository.
-- Pre-edit trap warnings or session-start context stopped appearing.
-
-## 1. Project install (recommended)
-Run from the project root:
-```bash
-npx -y fastrmemory@0.3.0 hook install
-```
-This is idempotent and backs up files it changes. It writes:
-- `.mcp.json`: a project-scoped `fastrmemory` MCP server.
-- `.claude/settings.json`: hooks for `SessionStart`, `PreToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`), `PreCompact`, and `SessionEnd`, each running the FastrMemory CLI as `... hook run <event>`.
-- `.cursor/mcp.json` and an `AGENTS.md` discipline block for other agents.
-
-Commit `.mcp.json` and `.claude/settings.json` so the team shares the setup. Restart Claude Code and approve the project MCP server when prompted.
-
-## 2. Manual MCP registration (alternative)
-```bash
-claude mcp add fastrmemory -- npx -y fastrmemory@0.3.0 mcp
-```
-On native Windows use `-- cmd /c npx -y fastrmemory@0.3.0 mcp`. Pass `--scope project` (before the name) to write `.mcp.json`. This adds tools only, not hooks.
-
-## 3. Verify
-```bash
-npx -y fastrmemory@0.3.0 status
-claude mcp list
-```
-`status` prints the project ID, memory counts, and database path (`.fastr/` under the project). Inside a session, call:
-```js
-fastr_status({})
-```
-
-## Troubleshooting
-- Tools missing after install: run `/mcp` in Claude Code and check the server started; requires Node >= 22.16.
-- Searches miss new memories or the DB looks inconsistent: follow the `fastr-doctor` skill.
-- Do not edit `~/.claude` files by hand; prefer the commands above.
+---
+name: fastr-setup
+description: Use when FastrMemory tools are missing or not responding in Claude Code, when the user asks to install or wire up FastrMemory in a project, or when hooks (session start, pre-edit trap warnings) are not firing. Covers project install, manual MCP registration, and verification.
+allowed-tools: Bash(fastr *), Bash(fastrmemory *), Bash(npx -y fastrmemory*)
+---
+
+# FastrMemory: Wire Up Claude Code
+
+## When to use
+- `fastr_*` tools are not available in the session.
+- The user asks to set up FastrMemory for this repository.
+- Pre-edit trap warnings or session-start context stopped appearing.
+
+## 1. Project install (recommended)
+Run from the project root:
+```bash
+npx -y fastrmemory@0.3.1 hook install
+```
+This is idempotent and backs up files it changes. It writes:
+- `.mcp.json`: a project-scoped `fastrmemory` MCP server.
+- `.claude/settings.json`: hooks for `SessionStart`, `PreToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`), `PreCompact`, and `SessionEnd`, each running the FastrMemory CLI as `... hook run <event>`.
+- `.cursor/mcp.json` and an `AGENTS.md` discipline block for other agents.
+
+Commit `.mcp.json` and `.claude/settings.json` so the team shares the setup. Restart Claude Code and approve the project MCP server when prompted.
+
+## 2. Manual MCP registration (alternative)
+```bash
+claude mcp add fastrmemory -- npx -y fastrmemory@0.3.1 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.
+
+## 3. Verify
+```bash
+npx -y fastrmemory@0.3.1 status
+claude mcp list
+```
+`status` prints the project ID, memory counts, and database path (`.fastr/` under the project). Inside a session, call:
+```js
+fastr_status({})
+```
+
+## Troubleshooting
+- Tools missing after install: run `/mcp` in Claude Code and check the server started; requires Node >= 22.16.
+- Searches miss new memories or the DB looks inconsistent: follow the `fastr-doctor` skill.
+- Do not edit `~/.claude` files by hand; prefer the commands above.

package/skills/fastr-trap-log/SKILL.md

@@ -1,39 +1,39 @@
----
-name: fastr-trap-log
-description: Use the moment you diagnose the root cause of a build error, failing test, runtime exception, or platform/library gotcha. Records it as an error trap so future agents are warned before editing the same files. Do not wait until the end of the session.
----
-
-# FastrMemory: Log Error Traps Immediately
-
-## When to use
-- A test, type check, or build failed and you now know why.
-- A runtime crash or wrong behaviour was traced to a specific cause.
-- You hit a subtle environment trap (Windows paths, SQLite locking, ESM/CJS interop, timezone, rounding).
-
-Skip it for typos or one-off mistakes that teach nothing reusable.
-
-## Steps
-
-1. **Check it is not already recorded**:
-   ```js
-   fastr_trap_recall({ files: ["src/db/schema.ts"] })
-   ```
-   If the same trap exists, do not duplicate it; rate it instead with
-   `fastr_feedback({ memoryId: "mem_xxxx", outcome: "good", note: "Trap matched this failure" })`.
-
-2. **Log the trap** (stored as a verified `error_trap` with a 2.0x recall boost):
-   ```js
-   fastr_trap_log({
-     title: "Never open two write connections to the SQLite DB",
-     content: "Symptom: SQLITE_BUSY in tests. Cause: a second DatabaseSync writer outside the shared repo. Fix: reuse the server context's db handle.",
-     files: ["src/db/schema.ts", "src/mcp/server.ts"],
-     module: "db"
-   })
-   ```
-
-## Writing a good trap
-- `title`: imperative rule, not a description of the bug ("Always X" / "Never Y").
-- `content`: symptom, root cause, and the concrete fix or workaround, in a few sentences.
-- `files`: every file where the trap applies; this is what pre-edit checks match on.
-- Never paste secrets, tokens, or private URLs. Content is scrubbed, but do not rely on it.
-- If the fix changes an existing rule, also follow the `fastr-curate` skill to supersede it.
+---
+name: fastr-trap-log
+description: Use the moment you diagnose the root cause of a build error, failing test, runtime exception, or platform/library gotcha. Records it as an error trap so future agents are warned before editing the same files. Do not wait until the end of the session.
+---
+
+# FastrMemory: Log Error Traps Immediately
+
+## When to use
+- A test, type check, or build failed and you now know why.
+- A runtime crash or wrong behaviour was traced to a specific cause.
+- You hit a subtle environment trap (Windows paths, SQLite locking, ESM/CJS interop, timezone, rounding).
+
+Skip it for typos or one-off mistakes that teach nothing reusable.
+
+## Steps
+
+1. **Check it is not already recorded**:
+   ```js
+   fastr_trap_recall({ files: ["src/db/schema.ts"] })
+   ```
+   If the same trap exists, do not duplicate it; rate it instead with
+   `fastr_feedback({ memoryId: "mem_xxxx", outcome: "good", note: "Trap matched this failure" })`.
+
+2. **Log the trap** (stored as a verified `error_trap` with a 2.0x recall boost):
+   ```js
+   fastr_trap_log({
+     title: "Never open two write connections to the SQLite DB",
+     content: "Symptom: SQLITE_BUSY in tests. Cause: a second DatabaseSync writer outside the shared repo. Fix: reuse the server context's db handle.",
+     files: ["src/db/schema.ts", "src/mcp/server.ts"],
+     module: "db"
+   })
+   ```
+
+## Writing a good trap
+- `title`: imperative rule, not a description of the bug ("Always X" / "Never Y").
+- `content`: symptom, root cause, and the concrete fix or workaround, in a few sentences.
+- `files`: every file where the trap applies; this is what pre-edit checks match on.
+- Never paste secrets, tokens, or private URLs. Content is scrubbed, but do not rely on it.
+- If the fix changes an existing rule, also follow the `fastr-curate` skill to supersede it.

package/skills/fastr-vision/SKILL.md

@@ -1,35 +1,35 @@
----
-name: fastr-vision
-description: Use when a screenshot, UI mockup, architecture diagram, or error screen should be remembered for later, or before fixing a visual bug or redesigning UI to find related images stored earlier. Tags images with descriptions and OCR text and searches them.
----
-
-# FastrMemory: Visual Memory
-
-## When to use
-- The user shares a screenshot or diagram that explains a bug, design, or architecture.
-- A test or tool produced an image worth keeping (visual regression, error dialog).
-- You are about to change UI and want earlier screenshots or design references.
-
-## 1. Tag an image
-```js
-fastr_vision_tag({
-  filePath: "screenshots/checkout-401.png",
-  description: "Checkout modal showing a red HTTP 401 banner above the pay button",
-  ocrText: "HTTP 401 Unauthorized. Access token expired.",
-  memoryId: "mem_009e4a7d",
-  taskId: "act_checkout_fix"
-})
-```
-- `description`: components, layout, colours, and what is wrong or notable.
-- `ocrText`: exact visible text (error messages, codes, labels) to make keyword search work.
-- `memoryId` / `taskId` (optional): link the governing trap or rule, and the related action.
-
-## 2. Search images
-```js
-fastr_vision_search({ query: "checkout modal 401 error", limit: 5 })
-```
-Filter to images linked to one memory with `memoryId: "mem_009e4a7d"`.
-
-## Rules
-- Describe what is in the image; do not guess at content you cannot see.
-- Do not tag images containing secrets or personal data.
+---
+name: fastr-vision
+description: Use when a screenshot, UI mockup, architecture diagram, or error screen should be remembered for later, or before fixing a visual bug or redesigning UI to find related images stored earlier. Tags images with descriptions and OCR text and searches them.
+---
+
+# FastrMemory: Visual Memory
+
+## When to use
+- The user shares a screenshot or diagram that explains a bug, design, or architecture.
+- A test or tool produced an image worth keeping (visual regression, error dialog).
+- You are about to change UI and want earlier screenshots or design references.
+
+## 1. Tag an image
+```js
+fastr_vision_tag({
+  filePath: "screenshots/checkout-401.png",
+  description: "Checkout modal showing a red HTTP 401 banner above the pay button",
+  ocrText: "HTTP 401 Unauthorized. Access token expired.",
+  memoryId: "mem_009e4a7d",
+  taskId: "act_checkout_fix"
+})
+```
+- `description`: components, layout, colours, and what is wrong or notable.
+- `ocrText`: exact visible text (error messages, codes, labels) to make keyword search work.
+- `memoryId` / `taskId` (optional): link the governing trap or rule, and the related action.
+
+## 2. Search images
+```js
+fastr_vision_search({ query: "checkout modal 401 error", limit: 5 })
+```
+Filter to images linked to one memory with `memoryId: "mem_009e4a7d"`.
+
+## Rules
+- Describe what is in the image; do not guess at content you cannot see.
+- Do not tag images containing secrets or personal data.