@theihtisham/agent-shadow-brain 7.22.0 → 7.22.1

package/docs/INTEGRATIONS.md

@@ -1,70 +1,70 @@
-# Connect a coding client
-
-Agent Shadow Brain provides six reusable workflow skills, project-specific skill generation, and a local MCP service. Skills guide the host's work; MCP exposes saved memory and context. A client must load the skill or call the tool for it to take effect.
-
-## Start with a local project
-
-Run these commands from the project root:
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@7.22.0
-shadow-brain project workspace .
-shadow-brain project config . --target codex
-```
-
-The portal stores knowledge in `.shadow-brain/project-memory.json`. The generated recipe pins MCP to that same project and file, so a saved note can be recalled by the agent and its tool calls appear in the matching portal's **Live** view. The recipe is printed, not installed. Merge the entry with your existing host settings, then reconnect the client.
-
-![Native configuration recipes](assets/7.1.4-integrations.png)
-
-## Choose a client
-
-| Target | Native recipe | Project skill location |
-| --- | --- | --- |
-| `codex` | TOML entry for `.codex/config.toml` | `.agents/skills` |
-| `claude-code` | JSON entry for `.mcp.json` | `.claude/skills` |
-| `opencode` | JSON entry for `opencode.json` | `.opencode/skills` |
-| `deepseek-harness` | MCP client plugin YAML entry | `.dsh/skills` |
-| `portable` | Common `mcpServers` JSON wrapper | `.agents/skills`, if supported by the host |
-
-```bash
-shadow-brain project config . --target claude-code
-shadow-brain project config . --target opencode
-shadow-brain project config . --target deepseek-harness
-```
-
-Recipes contain an absolute Node executable and installed CLI path. Regenerate them after moving the installation. OpenCode V2 uses `mcp.servers`; consult the documentation for an older host. DeepSeek Harness requires the MCP client plugin and, for skill discovery, the filesystem skill provider. Its documented MCP bridge supports tools and resources; prompt templates are unsupported. A generic wrapper is not universal configuration for every client.
-
-The legacy Models panel uses provider settings configured for Shadow Brain. It returns model labels and enabled status to the browser. Coding-agent settings stay with their hosts. The old custom-agent configuration endpoint is retired.
-
-[Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) · [Claude Code MCP](https://code.claude.com/docs/en/mcp) · [OpenCode MCP](https://opencode.ai/docs/mcp-servers/) · [Harness MCP client](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) · [Harness filesystem skills](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/skill/skill-filesystem/README.md)
-
-## Add workflow skills
-
-```bash
-shadow-brain skills install . --target codex
-shadow-brain skills install . --target codex --apply
-shadow-brain clients inspect .
-```
-
-The first command previews the reusable skill bundle. The second applies it. Local inspection checks only the selected project skill paths; it does not read client profiles or verify that a host loaded a skill. The **Project Kit** view separately generates a tailored skill from observed project evidence and your requirement. [Project Kit guide](PROJECT_KIT.md) · [Bundle installation and safe updates](WORKFLOW_INTEGRATION.md)
-
-## Verify a connection
-
-Ask the connected host to call `workflow_skills`, then `context_pack` with the selected project ID, your current task, and `profile: "adaptive"`. Check the returned memory IDs and sources. A successful host call verifies the connection. With recording enabled, its measured boundaries appear in the matching portal's Live view.
-
-The memory profile offers scoped tools, resources and task/handoff prompt templates. A project-local MCP launch additionally exposes Project Kit, reviewed source evidence, collaboration, sessions and optional host-reported usage. Use the current `tools/list` response for available tools. Resource references are saved labels; the service does not open their targets. Project tool participation and conversation sharing apply to agent delivery through tools, resources and prompts.
-
-`activity_report` records explicitly reported phases or spans. Reported activity is labelled separately from measured MCP calls. Neither exposes a model's hidden reasoning.
-
-## Keep an existing shared store
-
-Existing global-store workflows remain available:
-
-```bash
-shadow-brain dash . --no-analysis
-shadow-brain clients config --target codex --project .
-```
-
-For any other explicit store, add `--db PATH` to `clients config`. This prints a recipe for that file; it does not migrate or merge memory. The default dashboard cannot display a different store's activity journal. Use the project portal and its matching recipe for the simplest isolated setup.
-
+# Connect a coding client
+
+Agent Shadow Brain provides six reusable workflow skills, project-specific skill generation, and a local MCP service. Skills guide the host's work; MCP exposes saved memory and context. A client must load the skill or call the tool for it to take effect.
+
+## Start with a local project
+
+Run these commands from the project root:
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.22.0
+shadow-brain project workspace .
+shadow-brain project config . --target codex
+```
+
+The portal stores knowledge in `.shadow-brain/project-memory.json`. The generated recipe pins MCP to that same project and file, so a saved note can be recalled by the agent and its tool calls appear in the matching portal's **Live** view. The recipe is printed, not installed. Merge the entry with your existing host settings, then reconnect the client.
+
+![Native configuration recipes](assets/7.1.4-integrations.png)
+
+## Choose a client
+
+| Target | Native recipe | Project skill location |
+| --- | --- | --- |
+| `codex` | TOML entry for `.codex/config.toml` | `.agents/skills` |
+| `claude-code` | JSON entry for `.mcp.json` | `.claude/skills` |
+| `opencode` | JSON entry for `opencode.json` | `.opencode/skills` |
+| `deepseek-harness` | MCP client plugin YAML entry | `.dsh/skills` |
+| `portable` | Common `mcpServers` JSON wrapper | `.agents/skills`, if supported by the host |
+
+```bash
+shadow-brain project config . --target claude-code
+shadow-brain project config . --target opencode
+shadow-brain project config . --target deepseek-harness
+```
+
+Recipes contain an absolute Node executable and installed CLI path. Regenerate them after moving the installation. OpenCode V2 uses `mcp.servers`; consult the documentation for an older host. DeepSeek Harness requires the MCP client plugin and, for skill discovery, the filesystem skill provider. Its documented MCP bridge supports tools and resources; prompt templates are unsupported. A generic wrapper is not universal configuration for every client.
+
+The legacy Models panel uses provider settings configured for Shadow Brain. It returns model labels and enabled status to the browser. Coding-agent settings stay with their hosts. The old custom-agent configuration endpoint is retired.
+
+[Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) · [Claude Code MCP](https://code.claude.com/docs/en/mcp) · [OpenCode MCP](https://opencode.ai/docs/mcp-servers/) · [Harness MCP client](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) · [Harness filesystem skills](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/skill/skill-filesystem/README.md)
+
+## Add workflow skills
+
+```bash
+shadow-brain skills install . --target codex
+shadow-brain skills install . --target codex --apply
+shadow-brain clients inspect .
+```
+
+The first command previews the reusable skill bundle. The second applies it. Local inspection checks only the selected project skill paths; it does not read client profiles or verify that a host loaded a skill. The **Project Kit** view separately generates a tailored skill from observed project evidence and your requirement. [Project Kit guide](PROJECT_KIT.md) · [Bundle installation and safe updates](WORKFLOW_INTEGRATION.md)
+
+## Verify a connection
+
+Ask the connected host to call `workflow_skills`, then `context_pack` with the selected project ID, your current task, and `profile: "adaptive"`. Check the returned memory IDs and sources. A successful host call verifies the connection. With recording enabled, its measured boundaries appear in the matching portal's Live view.
+
+The memory profile offers scoped tools, resources and task/handoff prompt templates. A project-local MCP launch additionally exposes Project Kit, reviewed source evidence, collaboration, sessions and optional host-reported usage. Use the current `tools/list` response for available tools. Resource references are saved labels; the service does not open their targets. Project tool participation and conversation sharing apply to agent delivery through tools, resources and prompts.
+
+`activity_report` records explicitly reported phases or spans. Reported activity is labelled separately from measured MCP calls. Neither exposes a model's hidden reasoning.
+
+## Keep an existing shared store
+
+Existing global-store workflows remain available:
+
+```bash
+shadow-brain dash . --no-analysis
+shadow-brain clients config --target codex --project .
+```
+
+For any other explicit store, add `--db PATH` to `clients config`. This prints a recipe for that file; it does not migrate or merge memory. The default dashboard cannot display a different store's activity journal. Use the project portal and its matching recipe for the simplest isolated setup.
+
 [Workspace guide](WORKSPACE.md) · [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) · [Troubleshooting](TROUBLESHOOTING.md)

package/docs/LEARNING.md

@@ -1,46 +1,46 @@
-# Learning from work
-
-Shadow Brain 7.1.4 can reuse project-specific feedback when assembling adaptive context. The loop is explicit: select relevant memory, do the task in the host, observe the result, report what helped or failed, and inspect the effect on later retrieval.
-
-```mermaid
-flowchart LR
-    A[Current task] --> B[Scoped adaptive context]
-    B --> C[Host performs authorized work]
-    C --> D[Observed outcome]
-    D --> E[Reported memory feedback]
-    E --> F[Bounded task-relevant adjustment]
-    F --> B
-    E --> G[User review / remove / disable]
-```
-
-The MCP tool assigns `reporter: agent`; portal and CLI feedback assign `reporter: user`. Neither reporter can claim its result is machine-verified by this system. Source and evidence references are not fetched. A tool call succeeding is not evidence that the task succeeded.
-
-## What changes in retrieval
-
-Feedback operates only on direct lexical candidates that passed normal project and curation filters. It cannot create a match, boost a graph-only neighbor, revive archived/contested/superseded memory, add source provenance, or alter stored memory content.
-
-The task matcher drops generic action words and compares substantive terms. A report needs at least one substantive overlap and a Jaccard similarity of at least 0.34 with the current query. Up to three recent matching distinct tasks contribute. The adjustment is the mean of each rating value multiplied by task similarity and reporter weight.
-
-| Input | Value |
-| --- | ---: |
-| Useful | +0.08 |
-| Not useful | -0.04 |
-| Incorrect | -0.12 |
-| User reporter weight | 1 |
-| Agent reporter weight | 0.5 |
-| Final adjustment bounds | -0.12 to +0.08 |
-
-The final score cannot go below zero. The candidate report exposes the signed **Project task feedback** signal, contributing record IDs, and reporter kinds. This is a ranking heuristic, not a confidence or truth score.
-
-An identical memory/task/reporter combination updates its prior record. When eligible exact-text duplicates are grouped, the newest report from each normalized task can contribute once, with user reports taking precedence over agent reports. Candidate details retain the contributing report IDs. The sidecar is limited to 500 records and 2 MiB, with bounded task, reason and evidence fields. At capacity, a new distinct record is rejected. Existing records can still be updated or removed. Changes use revision checks and atomic file replacement. No age expiry is silently imposed.
-
-## Keep control
-
-- Turn local learning influence off to retain records while restoring baseline adaptive scoring.
-- Remove a report to withdraw its influence.
-- Use normal memory curation to mark a claim contested or archive an outdated record. An `incorrect` report does not secretly change curation state.
-- Review agent reports against actual checks. A plausible explanation can still be wrong.
-
-This feature is limited to the explicit project workspace and matching local MCP/CLI store. Library callers opt in by passing a `ProjectFeedbackSnapshot` to `assembleContext`. Existing global-store retrieval and legacy profiles do not automatically adopt feedback.
-
+# Learning from work
+
+Shadow Brain 7.1.4 can reuse project-specific feedback when assembling adaptive context. The loop is explicit: select relevant memory, do the task in the host, observe the result, report what helped or failed, and inspect the effect on later retrieval.
+
+```mermaid
+flowchart LR
+    A[Current task] --> B[Scoped adaptive context]
+    B --> C[Host performs authorized work]
+    C --> D[Observed outcome]
+    D --> E[Reported memory feedback]
+    E --> F[Bounded task-relevant adjustment]
+    F --> B
+    E --> G[User review / remove / disable]
+```
+
+The MCP tool assigns `reporter: agent`; portal and CLI feedback assign `reporter: user`. Neither reporter can claim its result is machine-verified by this system. Source and evidence references are not fetched. A tool call succeeding is not evidence that the task succeeded.
+
+## What changes in retrieval
+
+Feedback operates only on direct lexical candidates that passed normal project and curation filters. It cannot create a match, boost a graph-only neighbor, revive archived/contested/superseded memory, add source provenance, or alter stored memory content.
+
+The task matcher drops generic action words and compares substantive terms. A report needs at least one substantive overlap and a Jaccard similarity of at least 0.34 with the current query. Up to three recent matching distinct tasks contribute. The adjustment is the mean of each rating value multiplied by task similarity and reporter weight.
+
+| Input | Value |
+| --- | ---: |
+| Useful | +0.08 |
+| Not useful | -0.04 |
+| Incorrect | -0.12 |
+| User reporter weight | 1 |
+| Agent reporter weight | 0.5 |
+| Final adjustment bounds | -0.12 to +0.08 |
+
+The final score cannot go below zero. The candidate report exposes the signed **Project task feedback** signal, contributing record IDs, and reporter kinds. This is a ranking heuristic, not a confidence or truth score.
+
+An identical memory/task/reporter combination updates its prior record. When eligible exact-text duplicates are grouped, the newest report from each normalized task can contribute once, with user reports taking precedence over agent reports. Candidate details retain the contributing report IDs. The sidecar is limited to 500 records and 2 MiB, with bounded task, reason and evidence fields. At capacity, a new distinct record is rejected. Existing records can still be updated or removed. Changes use revision checks and atomic file replacement. No age expiry is silently imposed.
+
+## Keep control
+
+- Turn local learning influence off to retain records while restoring baseline adaptive scoring.
+- Remove a report to withdraw its influence.
+- Use normal memory curation to mark a claim contested or archive an outdated record. An `incorrect` report does not secretly change curation state.
+- Review agent reports against actual checks. A plausible explanation can still be wrong.
+
+This feature is limited to the explicit project workspace and matching local MCP/CLI store. Library callers opt in by passing a `ProjectFeedbackSnapshot` to `assembleContext`. Existing global-store retrieval and legacy profiles do not automatically adopt feedback.
+
 [Project Kit walkthrough](PROJECT_KIT.md) · [Retrieval evaluation](evaluation/CONTEXT_EVALUATION_v7.1.4.md)

package/docs/PROJECT_KIT.md

@@ -1,98 +1,98 @@
-# Project Kit: knowledge and skills for one workspace
-
-Project Kit combines a local knowledge store, bounded project inspection, task-specific skill generation, and feedback from actual work. Everything belongs to the selected project. Opening another project does not import these memories or install the skill globally.
-
-## 1. Open your project
-
-```bash
-shadow-brain project workspace .
-```
-
-Open the printed address and choose **Project Kit**. This mode needs no model provider and does not read coding-client profiles. Closing the portal keeps your saved files. The older `dash` command still opens the shared-store dashboard; it does not silently switch or merge stores.
-
-| File or folder | Purpose |
-| --- | --- |
-| `.shadow-brain/project-memory.json` | Explicit project knowledge |
-| `.shadow-brain/memory-annotations.json` | Reviews and recorded memory relationships |
-| `.shadow-brain/feature-settings.json` | Workspace runtime controls |
-| `.shadow-brain/activity-journal.json` | Bounded measured/reported activity metadata |
-| `.shadow-brain/memory-feedback.json` | Reported outcomes and local learning control |
-| `.shadow-brain/project-kit-skills` | Ownership receipts for generated skills |
-| `.shadow-brain/disabled-project-skills` | Verified disabled copies outside client discovery paths |
-| Selected host's project skill folder | Generated `SKILL.md` files |
-
-Files are created when their feature needs to save data. Treat knowledge and skill content as project files: decide what belongs in version control before sharing the repository. Moving a project changes its path-derived project ID; this release does not automatically reassign earlier memory IDs to the new location.
-
-## 2. Inspect what the project actually declares
-
-```bash
-shadow-brain project inspect .
-```
-
-Inspection reports observed stack markers, package-manager markers, and known check names. It scans at most 500 directory entries through depth three, with bounded allowlisted manifest reads. A script named `test` yields a suggested command; its body is not returned or executed. Lockfiles and configuration markers can identify a tool without reading their contents. The scanner skips linked paths, dependency/build trees and private configuration locations.
-
-These are observations, not complete semantic understanding. Missing manifests, a large monorepo, custom scripts, or an unfamiliar stack can leave gaps. The profile shows coverage and warnings. Check the suggested command before running it.
-
-## 3. Add knowledge you want the agent to retain
-
-Use the knowledge form for a project constraint, decision, rule, or known lesson. An optional reference records where you found it; the service does not fetch that reference or certify the statement.
-
-```bash
-shadow-brain project knowledge . --title "Checkout retry contract" --content "Preserve the original idempotency key across retries." --source "docs/checkout.md"
-```
-
-The command returns the committed memory ID and project ID. The original text is stored with explicit user provenance. A reference is recorded only when you supply one, so adding a note without a source does not inflate source coverage.
-
-Open **Context Lab**, select the project, and ask about checkout retries. The saved note is immediately available to scoped retrieval. You can inspect, contest, archive, or connect it through the existing memory tools.
-
-## 4. Turn a requirement into a local skill
-
-Describe the task, choose a client, and optionally supply knowledge. **Use in skill** reuses the knowledge you just added. Preview shows the exact destination and Markdown before Apply.
-
-```bash
-shadow-brain project skill . --target codex --name checkout-retries --requirement "Fix checkout retries and verify that each request commits once."
-```
-
-The output includes `planHash`. Repeat the same inputs with `--apply --expected-plan-hash HASH_FROM_PREVIEW` to write the reviewed plan. The generated skill includes your requirement, supplied knowledge, observed project evidence, and relevant declared checks. It is deterministic; no model or install script runs during generation.
-
-| Client target | Generated path |
-| --- | --- |
-| `codex` | `.agents/skills/NAME/SKILL.md` |
-| `claude-code` | `.claude/skills/NAME/SKILL.md` |
-| `opencode` | `.opencode/skills/NAME/SKILL.md` |
-| `deepseek-harness` | `.dsh/skills/NAME/SKILL.md` |
-| `portable` | `.agents/skills/NAME/SKILL.md` |
-
-Apply recomputes the preview, checks path safety and ownership, and refuses stale plans or files that were edited outside Project Kit. An unowned file is not overwritten, even if its name matches. Generated skills do not edit `AGENTS.md`, provider settings, or global skill directories. Host support and skill discovery still need to be checked in the client.
-
-In **Setup → Managed project skills**, preview Disable, Enable, or Remove to see the affected paths. Disabling moves the verified `SKILL.md` bytes into the workspace’s disabled-skill folder. Enabling restores them only when the discovery path is free. Removal deletes the verified file and its Project Kit receipt. Supporting files and other skill installations stay in place.
-
-The panel reports edited files, destination conflicts, and pending operations. For a pending operation, review the same action to complete it. Reload the coding client to refresh its skill discovery. An existing chat can still contain instructions it loaded earlier.
-
-## 5. Connect the same local knowledge to your agent
-
-```bash
-shadow-brain project config . --target codex
-```
-
-Merge the printed recipe into the selected host's configuration. It includes the explicit project directory, project ID and local `--db` path. The connected MCP process then reads the same knowledge shown by the portal.
-
-The local launch adds `project_inspect`, `project_knowledge`, `project_skill_preview`, `project_skill_apply`, and `project_feedback` to the regular memory tools. Preview/apply is a two-step operation. Saved text and observations remain reference material; they do not override current user instructions or the host's permissions.
-
-## 6. Learn from reported outcomes
-
-After a real task, record whether a selected memory helped. The **Memory outcomes** panel keeps the task, outcome, reason, optional evidence labels and reporter visible. A user report and an agent report remain distinguishable. Agents can call `project_feedback` after observing a concrete result; retrieval alone never creates positive feedback.
-
-```bash
-shadow-brain project feedback list .
-shadow-brain project feedback record . --memory MEMORY_ID --task "Fix checkout retries" --rating useful --reason "The existing idempotency contract matched the passing retry regression check." --evidence "tests/checkout-retry.test.ts"
-shadow-brain project feedback set off --project .
-```
-
-Use `useful`, `not-useful`, or `incorrect`. Record only an outcome you observed; the example reason is not a claim that your tests passed. Feedback is reported evidence, not an automatic truth verdict. The portal lets you remove a record or disable its influence while keeping the history available.
-
-Adaptive retrieval applies a small signed adjustment only when the memory already matches the current task and the feedback task is relevant. Repeated identical reports are updated instead of counted again. User reports carry more weight than agent reports. Context Lab shows the applied signal and links to reported outcomes; diagnostic JSON retains record IDs. Legacy retrieval, unrelated projects, inactive memories, and empty-query browsing do not gain feedback influence.
-
-This improves local reuse through outcome feedback. It does not train model weights, verify external sources, execute self-modifying code, or guarantee that an agent's next answer will be correct. [Learning rules and limits](LEARNING.md)
-
+# Project Kit: knowledge and skills for one workspace
+
+Project Kit combines a local knowledge store, bounded project inspection, task-specific skill generation, and feedback from actual work. Everything belongs to the selected project. Opening another project does not import these memories or install the skill globally.
+
+## 1. Open your project
+
+```bash
+shadow-brain project workspace .
+```
+
+Open the printed address and choose **Project Kit**. This mode needs no model provider and does not read coding-client profiles. Closing the portal keeps your saved files. The older `dash` command still opens the shared-store dashboard; it does not silently switch or merge stores.
+
+| File or folder | Purpose |
+| --- | --- |
+| `.shadow-brain/project-memory.json` | Explicit project knowledge |
+| `.shadow-brain/memory-annotations.json` | Reviews and recorded memory relationships |
+| `.shadow-brain/feature-settings.json` | Workspace runtime controls |
+| `.shadow-brain/activity-journal.json` | Bounded measured/reported activity metadata |
+| `.shadow-brain/memory-feedback.json` | Reported outcomes and local learning control |
+| `.shadow-brain/project-kit-skills` | Ownership receipts for generated skills |
+| `.shadow-brain/disabled-project-skills` | Verified disabled copies outside client discovery paths |
+| Selected host's project skill folder | Generated `SKILL.md` files |
+
+Files are created when their feature needs to save data. Treat knowledge and skill content as project files: decide what belongs in version control before sharing the repository. Moving a project changes its path-derived project ID; this release does not automatically reassign earlier memory IDs to the new location.
+
+## 2. Inspect what the project actually declares
+
+```bash
+shadow-brain project inspect .
+```
+
+Inspection reports observed stack markers, package-manager markers, and known check names. It scans at most 500 directory entries through depth three, with bounded allowlisted manifest reads. A script named `test` yields a suggested command; its body is not returned or executed. Lockfiles and configuration markers can identify a tool without reading their contents. The scanner skips linked paths, dependency/build trees and private configuration locations.
+
+These are observations, not complete semantic understanding. Missing manifests, a large monorepo, custom scripts, or an unfamiliar stack can leave gaps. The profile shows coverage and warnings. Check the suggested command before running it.
+
+## 3. Add knowledge you want the agent to retain
+
+Use the knowledge form for a project constraint, decision, rule, or known lesson. An optional reference records where you found it; the service does not fetch that reference or certify the statement.
+
+```bash
+shadow-brain project knowledge . --title "Checkout retry contract" --content "Preserve the original idempotency key across retries." --source "docs/checkout.md"
+```
+
+The command returns the committed memory ID and project ID. The original text is stored with explicit user provenance. A reference is recorded only when you supply one, so adding a note without a source does not inflate source coverage.
+
+Open **Context Lab**, select the project, and ask about checkout retries. The saved note is immediately available to scoped retrieval. You can inspect, contest, archive, or connect it through the existing memory tools.
+
+## 4. Turn a requirement into a local skill
+
+Describe the task, choose a client, and optionally supply knowledge. **Use in skill** reuses the knowledge you just added. Preview shows the exact destination and Markdown before Apply.
+
+```bash
+shadow-brain project skill . --target codex --name checkout-retries --requirement "Fix checkout retries and verify that each request commits once."
+```
+
+The output includes `planHash`. Repeat the same inputs with `--apply --expected-plan-hash HASH_FROM_PREVIEW` to write the reviewed plan. The generated skill includes your requirement, supplied knowledge, observed project evidence, and relevant declared checks. It is deterministic; no model or install script runs during generation.
+
+| Client target | Generated path |
+| --- | --- |
+| `codex` | `.agents/skills/NAME/SKILL.md` |
+| `claude-code` | `.claude/skills/NAME/SKILL.md` |
+| `opencode` | `.opencode/skills/NAME/SKILL.md` |
+| `deepseek-harness` | `.dsh/skills/NAME/SKILL.md` |
+| `portable` | `.agents/skills/NAME/SKILL.md` |
+
+Apply recomputes the preview, checks path safety and ownership, and refuses stale plans or files that were edited outside Project Kit. An unowned file is not overwritten, even if its name matches. Generated skills do not edit `AGENTS.md`, provider settings, or global skill directories. Host support and skill discovery still need to be checked in the client.
+
+In **Setup → Managed project skills**, preview Disable, Enable, or Remove to see the affected paths. Disabling moves the verified `SKILL.md` bytes into the workspace’s disabled-skill folder. Enabling restores them only when the discovery path is free. Removal deletes the verified file and its Project Kit receipt. Supporting files and other skill installations stay in place.
+
+The panel reports edited files, destination conflicts, and pending operations. For a pending operation, review the same action to complete it. Reload the coding client to refresh its skill discovery. An existing chat can still contain instructions it loaded earlier.
+
+## 5. Connect the same local knowledge to your agent
+
+```bash
+shadow-brain project config . --target codex
+```
+
+Merge the printed recipe into the selected host's configuration. It includes the explicit project directory, project ID and local `--db` path. The connected MCP process then reads the same knowledge shown by the portal.
+
+The local launch adds `project_inspect`, `project_knowledge`, `project_skill_preview`, `project_skill_apply`, and `project_feedback` to the regular memory tools. Preview/apply is a two-step operation. Saved text and observations remain reference material; they do not override current user instructions or the host's permissions.
+
+## 6. Learn from reported outcomes
+
+After a real task, record whether a selected memory helped. The **Memory outcomes** panel keeps the task, outcome, reason, optional evidence labels and reporter visible. A user report and an agent report remain distinguishable. Agents can call `project_feedback` after observing a concrete result; retrieval alone never creates positive feedback.
+
+```bash
+shadow-brain project feedback list .
+shadow-brain project feedback record . --memory MEMORY_ID --task "Fix checkout retries" --rating useful --reason "The existing idempotency contract matched the passing retry regression check." --evidence "tests/checkout-retry.test.ts"
+shadow-brain project feedback set off --project .
+```
+
+Use `useful`, `not-useful`, or `incorrect`. Record only an outcome you observed; the example reason is not a claim that your tests passed. Feedback is reported evidence, not an automatic truth verdict. The portal lets you remove a record or disable its influence while keeping the history available.
+
+Adaptive retrieval applies a small signed adjustment only when the memory already matches the current task and the feedback task is relevant. Repeated identical reports are updated instead of counted again. User reports carry more weight than agent reports. Context Lab shows the applied signal and links to reported outcomes; diagnostic JSON retains record IDs. Legacy retrieval, unrelated projects, inactive memories, and empty-query browsing do not gain feedback influence.
+
+This improves local reuse through outcome feedback. It does not train model weights, verify external sources, execute self-modifying code, or guarantee that an agent's next answer will be correct. [Learning rules and limits](LEARNING.md)
+
 [Client integration](INTEGRATIONS.md) · [Context Lab](CONTEXT_LAB.md) · [Workspace guide](WORKSPACE.md)

package/docs/SHARING.md

@@ -1,13 +1,13 @@
-# Share Agent Shadow Brain
-
-## Short announcement
-
-> Agent Shadow Brain 7.1.3 gives coding clients a shared local store for project decisions and lessons. Build a scoped context pack, review the memories behind it, and follow measured MCP calls in the live portal. Project skills and local MCP setup are available for Codex, Claude Code, OpenCode, and DeepSeek Harness.
-
-[GitHub repository](https://github.com/ihtishaam-dev/agent-shadow-brain) · [7.1.3 release and recording](https://github.com/ihtishaam-dev/agent-shadow-brain/releases/tag/v7.1.3) · [npm package](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain/v/7.1.3) · [Client setup](INTEGRATIONS.md)
-
-## Demo caption
-
-> Scripted local clients run real MCP calls against synthetic project memories. The live portal shows measured tool timing and marks explicitly reported task phases.
-
-[Live screenshot](assets/live-v7.1.3.png) · [Workspace showcase](SHOWCASE.md)
+# Share Agent Shadow Brain
+
+## Short announcement
+
+> Agent Shadow Brain 7.1.3 gives coding clients a shared local store for project decisions and lessons. Build a scoped context pack, review the memories behind it, and follow measured MCP calls in the live portal. Project skills and local MCP setup are available for Codex, Claude Code, OpenCode, and DeepSeek Harness.
+
+[GitHub repository](https://github.com/ihtishaam-dev/agent-shadow-brain) · [7.1.3 release and recording](https://github.com/ihtishaam-dev/agent-shadow-brain/releases/tag/v7.1.3) · [npm package](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain/v/7.1.3) · [Client setup](INTEGRATIONS.md)
+
+## Demo caption
+
+> Scripted local clients run real MCP calls against synthetic project memories. The live portal shows measured tool timing and marks explicitly reported task phases.
+
+[Live screenshot](assets/live-v7.1.3.png) · [Workspace showcase](SHOWCASE.md)