@theihtisham/agent-shadow-brain 7.1.4 → 7.22.0

package/docs/INTEGRATIONS.md

@@ -7,7 +7,7 @@ Agent Shadow Brain provides six reusable workflow skills, project-specific skill
 Run these commands from the project root:
 
 ```bash
-npm install -g @theihtisham/agent-shadow-brain@7.1.4
+npm install -g @theihtisham/agent-shadow-brain@7.22.0
 shadow-brain project workspace .
 shadow-brain project config . --target codex
 ```
@@ -34,6 +34,8 @@ 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
@@ -50,7 +52,7 @@ The first command previews the reusable skill bundle. The second applies it. Loc
 
 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 regular memory profile offers twelve tools, two static resources, a scoped memory resource template, and two task/handoff prompt templates. A project-local MCP launch additionally exposes Project Kit inspection, explicit knowledge storage, skill preview, and guarded apply. Use the current `tools/list` response for available tools. Resource references are saved labels; the service does not open their targets.
+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.
 

package/docs/LEARNING.md

@@ -32,7 +32,7 @@ The task matcher drops generic action words and compares substantive terms. A re
 
 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. Repeated praise therefore does not accumulate. When a user and an agent report on the same normalized task, the user report takes precedence. 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.
+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
 

package/docs/PROJECT_KIT.md

@@ -14,10 +14,11 @@ Open the printed address and choose **Project Kit**. This mode needs no model pr
 | --- | --- |
 | `.shadow-brain/project-memory.json` | Explicit project knowledge |
 | `.shadow-brain/memory-annotations.json` | Reviews and recorded memory relationships |
-| `.shadow-brain/feature-settings.json` | The five runtime controls |
+| `.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.
@@ -64,6 +65,10 @@ The output includes `planHash`. Repeat the same inputs with `--apply --expected-
 
 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

package/docs/QUICKSTART.md

@@ -1,44 +1,62 @@
-# Quickstart
-
-This guide covers the 7.1.4 Brain Hub. Use Node.js 22.13 or later in the 22.x line, 24.x, or 26 and later.
-
-## Install and open a project
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@latest
-shadow-brain --version
-cd your-project
-shadow-brain project workspace . --port 62595
-```
-
-Check that the CLI prints `7.1.4` for these steps. Keep the command running and open [the Brain Hub](http://127.0.0.1:62595/hub). The process writes project data inside the selected project’s `.shadow-brain` directory. On restart, run the same command from the same project directory. If you use `--port 0`, open the URL printed by the current process.
-
-From a source checkout, use `npm ci` and `npm run build`, then replace `shadow-brain` with `node dist/cli.js` from the checkout. Pass the intended project directory as the workspace argument.
-
-![Running Brain Hub control room](assets/7.1.4-hub-control-room.png)
-
-## Add your first evidence
-
-1. In **Knowledge**, save explicit project knowledge or upload a PDF.
-2. For a PDF, open an extracted page, read its citation, and approve the page you want to retrieve later. Scanned pages show that OCR is needed.
-3. Open **Brain overview** and select a record. The node list offers the same selection with a keyboard.
-4. In **Context**, describe the task and set a token budget. Build a pack or compare profiles, review selected sources, then copy the pack.
-
-![Approved source page and extracted citation](assets/7.1.4-hub-knowledge.png)
-
-## Connect a host
-
-```bash
-shadow-brain project config . --target codex
-shadow-brain skills install . --target codex
-```
-
-Merge the recipe into the selected host’s configuration. Preview the skill-file changes, then use `--apply` if you want them. Reconnect the host and confirm it can call a tool such as `project_inspect` or `context_pack`. Host file presence, recorded activity, and model evidence are shown separately. [Supported client recipes](INTEGRATIONS.md)
-
-## Explore shared work
-
-Create a room in **Collaboration**, add a task, and record a proposal or critique. A participant can claim the task, attach a project-relative artifact, and record a result. **Learning** turns recorded outcomes into candidates with explicit evaluation and promotion. [Workspace guide](WORKSPACE.md)
-
-The classic workspace at `/workspace` provides detailed memory review, context selection, and retrieval feedback. `/live` opens the detailed journal. `shadow-brain demo workspace --port 0` runs a separate synthetic tour.
-
-[Visual guide](VISUAL_GUIDE_v7.1.4.md) · [Troubleshooting](TROUBLESHOOTING.md)
+# Quickstart
+
+This guide covers the 7.22.0 Brain Hub. Use Node.js 22.13 or later in the 22.x line, 24.x, or 26 and later.
+
+## Install and open a project
+
+From the project directory, you can start with one command:
+
+```bash
+npx --yes --package @theihtisham/agent-shadow-brain@7.22.0 shadow-brain project workspace . --port 62595
+```
+
+Or install the reusable CLI:
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+cd your-project
+shadow-brain project workspace . --port 62595
+```
+
+Check that the CLI prints `7.22.0` for these steps. Keep the command running and open [the Brain Hub](http://127.0.0.1:62595/hub). The process writes project data inside the selected project’s `.shadow-brain` directory. On restart, run the same command from the same project directory. If you use `--port 0`, open the URL printed by the current process.
+
+From a source checkout, use `npm ci` and `npm run build`, then replace `shadow-brain` with `node dist/cli.js` from the checkout. Pass the intended project directory as the workspace argument.
+
+![Running Brain Hub control room](assets/7.22.0-hub-graph.png)
+
+## Save a fact in ordinary words
+
+1. Open **Knowledge** and type “The cupboard is black. Keep its brass handles.”
+2. Click **Add to memory**. No title, JSON or upload is required.
+3. Open **Context** and ask “What colour is the cupboard?” The returned reference includes your note and a link to its original text.
+4. Connect your chosen host through **Setup** so it can retrieve the same memory through MCP.
+
+For longer notes, choose **Review first** and save the useful parts. Optional PDF and JSON imports stay available below the plain-text form. Image-only PDFs need OCR, which is not included.
+
+![Approved source page and extracted citation](assets/7.1.4-hub-knowledge.png)
+
+## Connect a host
+
+```bash
+shadow-brain project config . --target codex
+shadow-brain skills install . --target codex
+```
+
+Merge the recipe into the selected host’s configuration. Preview the skill-file changes, then use `--apply` if you want them. Reconnect the host and confirm it can call a tool such as `project_inspect` or `context_pack`. Host file presence, recorded activity, and model evidence are shown separately. [Supported client recipes](INTEGRATIONS.md)
+
+## Explore shared work
+
+Create a room in **Collaboration**, add a task, and record a proposal or critique. A participant can claim the task, attach a project-relative artifact, and record a result. **Learning** turns recorded outcomes into candidates with explicit evaluation and promotion. [Workspace guide](WORKSPACE.md)
+
+The classic workspace at `/workspace` provides detailed memory review, context selection, and retrieval feedback. `/live` opens the detailed journal. `shadow-brain demo workspace --port 0` runs a separate synthetic tour.
+
+[Visual guide](VISUAL_GUIDE_v7.22.0.md) · [Troubleshooting](TROUBLESHOOTING.md)
+
+## Plain-language notes, sessions, and live files
+
+In **Knowledge**, paste ordinary notes or a plan and choose **Add to memory**. Direct saving accepts 6,000 characters and 20 paragraphs; **Review first** handles longer notes. **Context** lets you try a task, inspect original evidence, and compare a focused context pack with a bounded reference under the same project controls. **Learning** records usefulness feedback.
+
+Open **Sessions** for explicitly reported conversation history and saved handoffs. A connected host can call `session_open`, record meaningful progress, and create a checkpoint; another host calls `session_resume` with that checkpoint to continue. Imported transcripts are deliberate snapshots, not automatic access to native private chat history. [Sessions guide](SESSIONS.md).
+
+In **Setup**, choose sharing preferences, context ceilings and optional **project file activity**. A filesystem event does not identify its author. Pushed updates need the local server to remain running. Tool participation applies to cooperating client labels; it does not configure or control another application globally.

package/docs/README.md

@@ -1,33 +1,36 @@
-# Agent Shadow Brain documentation
-
-Agent Shadow Brain 7.1.4 provides a local workspace, CLI, and standalone MCP service for project memory, task context, and generated project skills.
-
-## Start and use the workspace
-
-| Guide | Use it to |
-| --- | --- |
-| [Quickstart](QUICKSTART.md) | Install the exact version, launch the synthetic demo, and open your project workspace. |
-| [Project Kit](PROJECT_KIT.md) | Inspect one project, save local knowledge, and preview and apply a tailored skill. |
-| [Context Lab](CONTEXT_LAB.md) | Assemble, inspect, compare, and copy a task brief. |
-| [Reported outcomes](LEARNING.md) | Record an observed result and inspect, pause, or remove its bounded influence on later retrieval. |
-| [Workspace guide](WORKSPACE.md) | Review memory, work with typed links, check project health, and follow recorded activity. |
-| [Features and limits](FEATURES_AND_LIMITS.md) | Distinguish implemented behavior from host prerequisites, estimates and unavailable metrics. |
-| [Client integrations](INTEGRATIONS.md) | Configure MCP stdio, inspect project skill files, and understand which surfaces the client exposes. |
-| [Workflow skills](WORKFLOW_INTEGRATION.md) | Preview or install the six focused project skills. |
-| [Showcase](SHOWCASE.md) | See Project Kit, Context Lab, memory review, outcome feedback, and Live replay with synthetic data. |
-
-## Architecture and evidence
-
-- [Component guide](COMPONENTS.md) maps the shared paths and retained modules.
-- [Agent memory approaches](COMPARISON.md) compares the documented architectures and tradeoffs of related systems.
-- [Paired retrieval evaluation](evaluation/CONTEXT_EVALUATION_v7.1.4.md) reports 14 author-generated diagnostic cases against both profiles. [Raw results](evaluation/CONTEXT_EVALUATION_v7.1.4.json)
-- [Research and acceptance plan](launch/RESEARCH_AND_PLAN_v7.1.4.md) records the research, implementation scope, and verification gates.
-
-## Release and support
-
-- [7.1.4 release notes](launch/RELEASE_NOTES_v7.1.4.md) cover compatibility, the demo, commands, and MCP access.
-- [Changelog](../CHANGELOG.md) · [Historical versions](versions/README.md) · [7.0 migration notes](launch/RELEASE_NOTES_v7.0.0.md)
-- [Troubleshooting](TROUBLESHOOTING.md) covers installation, storage, context, and local activity checks.
-- [Open an issue](https://github.com/theihtishaam/agents-brain/issues) with the version, reproduction steps, and relevant diagnostics.
-
-[Project README](../README.md)
+# Agent Shadow Brain documentation
+
+Agent Shadow Brain 7.22.0 provides a local workspace, CLI, and standalone MCP service for project memory, task context, and generated project skills.
+
+## Start and use the workspace
+
+| Guide | Use it to |
+| --- | --- |
+| [Source intake](SOURCE_INTAKE.md) | Paste notes, review corrections, import simple conversations and inspect original evidence. |
+| [Visual guide](VISUAL_GUIDE_v7.22.0.md) | See actual browser captures and their fixture provenance. |
+| [Quickstart](QUICKSTART.md) | Install the exact version, launch the synthetic demo, and open your project workspace. |
+| [Project Kit](PROJECT_KIT.md) | Inspect one project, save local knowledge, and preview and apply a tailored skill. |
+| [Context Lab](CONTEXT_LAB.md) | Assemble, inspect, compare, and copy a task brief. |
+| [Reported outcomes](LEARNING.md) | Record an observed result and inspect, pause, or remove its bounded influence on later retrieval. |
+| [Workspace guide](WORKSPACE.md) | Review memory, work with typed links, check project health, and follow recorded activity. |
+| [Features and limits](FEATURES_AND_LIMITS.md) | Distinguish implemented behavior from host prerequisites, estimates and unavailable metrics. |
+| [Client integrations](INTEGRATIONS.md) | Configure MCP stdio, inspect project skill files, and understand which surfaces the client exposes. |
+| [Workflow skills](WORKFLOW_INTEGRATION.md) | Preview or install the six focused project skills. |
+| [Showcase](SHOWCASE.md) | See Project Kit, Context Lab, memory review, outcome feedback, and Live replay with synthetic data. |
+
+## Architecture and evidence
+
+- [Component guide](COMPONENTS.md) maps the shared paths and retained modules.
+- [Agent memory approaches](COMPARISON.md) compares the documented architectures and tradeoffs of related systems.
+- [Paired retrieval evaluation](evaluation/CONTEXT_EVALUATION_v7.1.4.md) reports 14 author-generated diagnostic cases against both profiles. [Raw results](evaluation/CONTEXT_EVALUATION_v7.1.4.json)
+- [Research and acceptance plan](launch/RESEARCH_AND_PLAN_v7.22.0.md) records the research, implementation scope, and verification gates.
+
+## Release and support
+
+- [7.22.0 release notes](launch/RELEASE_NOTES_v7.22.0.md) cover shared sessions, native history, project controls and compatibility.
+- [Verification record](launch/RELEASE_ACCEPTANCE_v7.22.0.md) separates tested behavior, local measurements and native-client coverage.
+- [Changelog](../CHANGELOG.md) · [Historical versions](versions/README.md) · [7.0 migration notes](launch/RELEASE_NOTES_v7.0.0.md)
+- [Troubleshooting](TROUBLESHOOTING.md) covers installation, storage, context, and local activity checks.
+- [Open an issue](https://github.com/theihtishaam/agents-brain/issues) with the version, reproduction steps, and relevant diagnostics.
+
+[Project README](../README.md)

package/docs/SESSIONS.md

@@ -0,0 +1,77 @@
+# Shared project sessions
+
+Run the local Hub from your project and generate a recipe for each coding agent you use.
+
+```bash
+shadow-brain project workspace . --port 62595
+shadow-brain project config . --target codex
+```
+
+Use `claude-code`, `opencode`, or `deepseek-harness` for the other native recipes. Configure each host to use its recipe from the same project directory, then confirm `session_list`, `session_read`, `session_checkpoint_read`, `session_open`, `session_record`, and `session_resume` appear in its MCP tool list. Open **Sessions** in the project Hub to review work reported by those clients. [Client setup](INTEGRATIONS.md)
+
+## Track work and continue with another agent
+
+1. At the start of shared work, call `session_open` with a title, the project goal, and an operation key. Supply `hostSessionId` when the host already has a safe conversation label to share. A child worker can set `parentSessionId` to the UUID of an existing project session.
+2. Use `session_record` at meaningful milestones. Record a brief note, a `working` or `waiting` status, or a checkpoint. Save verified progress, decisions, next steps and evidence labels before a handoff. Use `completed` when the session is finished.
+3. In **Sessions**, open the saved checkpoint and copy the agent resume request. Give it to the next connected agent in the same project. Its `session_resume` call opens a new session owned by that connection and returns the exact saved handoff. The source session and earlier checkpoint stay available. Continuing in the portal creates an operator-owned session.
+
+Each write uses a stable operation key for retries in the same connection. Each record includes a revision. Pass `expectedRevision` when making a change based on a specific observed version. If the current connection ends, a new agent connection continues via a checkpoint. The original session is still readable.
+
+For example, after opening a session, an agent can call `session_record` with these arguments. Replace the UUID with the `session_open` result and use a new operation key for the checkpoint.
+
+```json
+{
+  "sessionId": "1b7766ed-34cb-4108-985d-b172a86ebd85",
+  "command": {
+    "kind": "checkpoint",
+    "key": "checkout-handoff-20261114",
+    "summary": "Verified the retry check with a fixture.",
+    "completed": ["Ran the existing retry regression check"],
+    "nextSteps": ["Check behavior after a process restart"],
+    "evidence": ["tests/checkout-retry.test.ts"]
+  }
+}
+```
+
+## Read the status and history
+
+The workspace shows the reporting tool label, session title, parent, and last report time. A report stays **recent** for five minutes. Older working or waiting reports are **stale**. Completion and the latest status reporter are stored. A recent report establishes that a cooperating host sent an update. Reported sessions do not themselves inspect open chats or determine whether a model is still generating. The separate Codex connector described below requires an explicit connection. Model information appears when a host explicitly reports usage with the matching agent label and `hostSessionId` as its usage `sessionId`.
+
+Messages come from intentional reports by hosts or the operator. You can also import an approved transcript in **Sessions** as a historical snapshot. The snapshot includes the items approved at import time, their original role, and source locators. Imported system, developer, and tool text appears as quoted notes. Only an explicit operator checkpoint turns historical work into a resumable handoff. Treat all recorded text as project evidence and follow current user instructions.
+
+The local store retains up to 150 sessions, 200 messages and 40 checkpoints per session. It rejects new records at the relevant limit and preserves existing history. `session_read` returns up to 25 messages and 32 KiB of serialized message data per page. Pass its `nextBefore` value as `before` to read older messages. Use `session_checkpoint_read` to see a checkpoint's contents. Resuming requires its recorded SHA-256. Checkpoint evidence labels are stored as text. Project sessions do not open source paths, start agents, reopen native chat tabs, or capture conversations on their own.
+
+## Understand the tool activity panel
+
+The **Brain overview** and **Sessions** views identify Codex, Claude Code, DeepSeek Harness and OpenCode with locally bundled icons. Hover or focus a tool for details, or select it to keep the details open. Select a conversation or connection to inspect its workspace, exact available title and ID, coordination role, latest recorded action and optional model receipt.
+
+**Reporting MCP connections** counts initialized project MCP transports with a recent heartbeat. Each transport renews every ten seconds; its lease expires after thirty seconds without renewal. A clean disconnect removes it. An abruptly stopped process expires even if it cannot write a final event. The store retains at most 128 current leases. Recording off or unreadable presence data is unavailable, not evidence of zero connections. Tool participation is a separate control: turning it off restricts project operations but does not close the host's transport, so its connection can still report a heartbeat.
+
+A current heartbeat shows that the memory transport is reporting. It does not establish that a model is generating or that a native application tab is open. Registered work sessions, observed tool calls and host-reported model receipts remain separate. If one connection serves several chats, a connection-level action is not attributed to a chat without explicit evidence. A usage receipt shared by several registered sessions is shown at the conversation level rather than assigned to a worker by guessing.
+
+Model, provider, effort and token counts appear only when explicitly reported. These receipts do not prove a proxy's underlying model. Fresh journal events can briefly animate the activity indicator; heartbeat renewals do not animate work or reload the graph. Pause motion and reduced-motion preferences keep the interface still.
+
+## Connect to Codex project history
+
+In **Sessions**, select **Connect installed Codex**. This starts a separate, read-only local Codex app-server connection for the project open in the Hub. Nothing is connected or read until you select this control. The connector uses the installed CLI; it does not start a model, create a native conversation, read browser data, or request authentication information. Select **Disconnect Codex** to close the connection. It expires automatically after 15 minutes.
+
+The connector asks Codex for its indexed current conversations whose recorded working directory matches this project. Use **Show archived chats** for a separate archived list and use the page controls to browse further. The index-only query avoids asking Codex to scan and repair rollout files, so the list can omit conversations that have not appeared in its state index. It is not a guarantee of complete native history. The exact title is shown when Codex provides one; otherwise the Hub says the original title is unavailable. The native conversation ID and its separate session-group ID are not interchangeable.
+
+Select a conversation to read a bounded page of visible user and assistant text, then use **Earlier history** for older pages. The page shows how many non-text or unsupported items were omitted. Tool output, reasoning, and attachments are not imported as messages. To keep the displayed page in shared project sessions, select **Save this history page**. The Hub verifies the page fingerprint before saving; if the source changed, review the new page first. A saved page is an immutable, possibly partial snapshot. It is not automatically added as project knowledge and does not resume the original native chat.
+
+While **Sessions** is open and connected, the Hub checks the current list every ten seconds and reloads the selected page when its reported update timestamp changes. This does not automatically save new snapshots. The timestamp is supplied by the separate app-server and can have limited resolution; its runtime state does not prove whether a desktop chat is active. The connector requires a compatible app-server with bounded history paging. On Windows it looks for the official npm package's local vendor executable; custom installation locations may not be detected. See the [Codex app-server protocol](https://learn.chatgpt.com/docs/app-server).
+
+## Import a native conversation export
+
+In **Sessions**, choose the originating tool and one exported conversation. The Hub keeps the exact title when the export provides one. When the original workspace is recorded, it must match the open project. Selected exports are saved as separate historical snapshots, with their original conversation ID and source fingerprint. The same export reopens the original snapshot. A changed export links a new snapshot to the previous one. Imports do not create memories or run instructions in the conversation.
+
+| Tool | Accepted export | Title source |
+| --- | --- | --- |
+| Codex | Selected rollout JSONL or a `codex-rollout-v1` JSON wrapper | The matching `thread_name` in the supplied session index entry. A rollout by itself may have no name. |
+| Claude Code | Selected main conversation JSONL or a `claude-agent-sdk-v1` JSON wrapper | Latest custom title for that conversation. SDK summaries are separate from custom titles. |
+| OpenCode | V1 or V2 session JSON from `opencode session export <id> --sanitize` | The exported session's `info.title`. |
+| DeepSeek Harness | Canonical V4 JSONL or the selected ZIP containing one root session log | Latest title event in the exported conversation. Child logs and attachments stay outside this import. |
+
+Codex wrappers include `format`, the selected `rollout` as a JSONL string, and `sessionIndex` with the matching name record. Claude SDK wrappers include `format`, a `session` from `listSessions`, and `messages` from `getSessionMessages` for that session. Choose the one workspace and conversation you intend to share. [Codex session index source](https://github.com/openai/codex/blob/main/codex-rs/rollout/src/session_index.rs) · [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/typescript) · [OpenCode commands](https://opencode.ai/docs/cli/commands/) · [DeepSeek archive source](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/session-query/session-log-export/src/archive.ts)
+
+Imports accept up to 2 MiB and retain visible user and assistant text with its source locators. Tool arguments, reasoning blocks, system messages, and attachments are excluded. Select only exports you intend to share with this project. An imported session can be continued after the operator saves a handoff checkpoint.

package/docs/SOURCE_INTAKE.md

@@ -0,0 +1,33 @@
+# Teach the project from your own notes
+
+Open **Knowledge**, write ordinary text and click **Add to memory**. For example: “The cupboard is black. Keep its brass handles.” The project is fixed by the workspace you opened. In **Context**, ask “What colour is the cupboard?” to inspect the retrieved fact and its original source. Connected agents can request the same project context through MCP.
+
+Direct saving supports up to 6,000 characters and 20 paragraphs. It preserves the original text and saves each paragraph as reference knowledge. Retrying the same note reuses the same records; earlier approved corrections remain intact. Previously skipped parts are not silently approved. No title, file or special format is needed, and no model is trained by saving a note.
+
+For longer notes or a correction before saving, choose **Review first**. Optional uploads support `.txt`, `.md`, `.json` and the separate PDF workflow. Ordinary text is the main path; files and JSON are optional.
+
+A preview splits plain text into paragraphs and displays their original lines. The title comes from the first nonblank line; a simple keyword rule suggests a category such as requirement, plan, or knowledge. These are suggestions, not an AI interpretation. Read each item, change its title, text, or category if needed, and approve or reject it. Approved text becomes project memory and may be used in later context. Pending and rejected items are not added as memories. Corrections take effect when you approve the corrected wording; this changes recorded context and does not train model weights.
+
+Previewing a valid source saves its original bytes, digest, filename, and review items in the project-owned source store even before approval. A second upload of identical bytes reopens the same review. The evidence view shows the original text and location alongside your approved wording; it verifies the stored relationship, not whether the claim is true. Do not include information you do not want saved in the project. The app does not read a browser's history, session data, or private client configuration to perform an import. Structured credential-shaped fields are rejected, but free-text secret detection is not comprehensive.
+
+Text and Markdown must be UTF-8 and are limited to 1 MiB, 500 sections, 6,000 characters per section, and 180,000 extracted characters in total. Break long paragraphs into smaller ones before importing. Text PDFs use the separate PDF page-review workflow and its limits; scanned/image-only PDFs require OCR, which this workflow does not provide.
+
+JSON accepts the following three versioned or simple interchange formats, plus an array of messages. Each content value must be a string. Unsupported nested exports, attachments, multimodal content, and unknown fields are rejected instead of silently omitted. System and developer roles in an imported transcript are quoted source evidence only; they do not become instructions to the app or an agent.
+
+```json
+{"schemaVersion":1,"kind":"knowledge","title":"Project notes","records":[{"title":"Build command","content":"Run the build before release.","source":"README.md"}]}
+```
+
+```json
+{"schemaVersion":1,"kind":"transcript","title":"Review discussion","messages":[{"role":"user","content":"Preserve Unicode."},{"role":"assistant","content":"The proposed constraint is to preserve Unicode."}]}
+```
+
+```json
+{"messages":[{"role":"user","content":"Preserve Unicode."}]}
+```
+
+Source labels such as `README.md` are citations only and are not opened. No import makes claims in a note true or independently verifies them. Review and correct the text before approving it.
+
+## Save a reviewed transcript as session history
+
+After reviewing a transcript, select **Open reviewed history in Sessions**. This creates a completed session containing only the messages approved at that time, preserving their original speaker labels and source locations. Messages labelled system, developer, or tool remain untrusted quoted notes. Repeating the import opens the existing snapshot; review all desired messages before the first import. No summary is generated automatically. You may write a checkpoint yourself and share its resume request with another connected project host. A portal continuation creates a portal-owned record, not a running model or a native host conversation.

package/docs/STATS.md

@@ -1,21 +1,21 @@
-# Package and repository statistics
-
-Last successful refresh: **2026-11-13T10:46:49.286Z**. Counts are snapshots from public npm and GitHub APIs.
-
-| Metric | Count | Coverage |
-| --- | ---: | --- |
-| npm total downloads | **6,030** | 2026-04-10 through 2026-11-12, inclusive |
-| npm latest day | 79 | 2026-11-12 through 2026-11-12 |
-| npm last 7 days | 725 | 2026-11-06 through 2026-11-12 |
-| npm last 30 days | 819 | 2026-10-14 through 2026-11-12 |
-| GitHub stars | 0 | At refresh |
-| GitHub forks | 0 | At refresh |
-| GitHub watchers | 0 | At refresh |
-
-The package was created on 2026-04-10. The total sums non-overlapping ranges of at most 365 days from creation through the latest complete day returned by npm. This handles the API's 18-month request limit without silently truncating lifetime counts. npm counts downloads, including automated installs; these are not unique people or active users.
-
-The dedicated **README metrics** workflow refreshes this page and the total-download badge daily. A failed request preserves the last successful snapshot. Weekly and monthly README badges use Shields' live npm endpoints and may refresh at different times.
-
-[Raw snapshot and coverage](npm-metrics.json) · [npm download API documentation](https://github.com/npm/registry/blob/main/docs/download-counts.md) · [Package](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain) · [Repository](https://github.com/theihtishaam/agents-brain)
-
-Historical snapshots in [stats-history.json](stats-history.json) come from the previous monitoring implementation and are not used to calculate this total.
+# Package and repository statistics
+
+Last successful refresh: **2026-11-14T11:49:13.195Z**. Counts are snapshots from public npm and GitHub APIs.
+
+| Metric | Count | Coverage |
+| --- | ---: | --- |
+| npm total downloads | **6,229** | 2026-04-10 through 2026-11-13, inclusive |
+| npm latest day | 199 | 2026-11-13 through 2026-11-13 |
+| npm last 7 days | 923 | 2026-11-07 through 2026-11-13 |
+| npm last 30 days | 1,018 | 2026-10-15 through 2026-11-13 |
+| GitHub stars | 0 | At refresh |
+| GitHub forks | 0 | At refresh |
+| GitHub watchers | 0 | At refresh |
+
+The package was created on 2026-04-10. The total sums non-overlapping ranges of at most 365 days from creation through the latest complete day returned by npm. This handles the API's 18-month request limit without silently truncating lifetime counts. npm counts downloads, including automated installs; these are not unique people or active users.
+
+The dedicated **README metrics** workflow refreshes this page and the plain-text README total every two days. The npm README is a snapshot from the published release. A failed request preserves the last successful snapshot.
+
+[Raw snapshot and coverage](npm-metrics.json) · [npm download API documentation](https://github.com/npm/registry/blob/main/docs/download-counts.md) · [Package](https://www.npmjs.com/package/@theihtisham/agent-shadow-brain) · [Repository](https://github.com/theihtishaam/agents-brain)
+
+Historical snapshots in [stats-history.json](stats-history.json) come from the previous monitoring implementation and are not used to calculate this total.

package/docs/VISUAL_GUIDE_v7.22.0.md

@@ -0,0 +1,73 @@
+# Brain Hub 7.22.0 visual guide
+
+These captures are from the running local Hub with an isolated synthetic fixture. The dense fixture contains 580 stored memories and explicit recorded links. Scripted MCP clients produce the observed tool activity. The graph can display up to 500 memories, with project and author nodes in addition to that sample. The animation shows actual measured `context_pack` tool calls against the fixture.
+
+![Hub graph showing recorded memory links and animated MCP requests and results](assets/7.22.0-hub-exchanges.gif)
+
+## Inspect tools and reported workers
+
+The tool activity panel shows recognizable local icons and a separate count of reporting MCP connections. Hover or focus a tool to inspect it; select it to keep its details open. Individual session chips retain different workers and models. A shared conversation receipt is not assigned to one worker by guessing. **Escape** closes the details and returns focus to its tool.
+
+![Running tool panel with a selected Codex session and its explicitly reported model and effort](assets/7.22.0-agent-dock.png)
+
+This additional capture uses four initialized scripted MCP clients, five registered sessions and two synthetic model receipts in an isolated project. The icon identifies the client tool; the provider, model and effort fields retain their host-reported labels. It does not show native application or model execution.
+
+![Brief indicator response to a measured tool event in the test workspace](assets/7.22.0-agent-dock.gif)
+
+Heartbeats renew every ten seconds and expire after thirty seconds. They update only the presence readout and never animate tool work. Missing metadata stays unavailable. Motion stops when paused, hidden or reduced-motion is requested.
+
+<img src="assets/7.22.0-agent-dock-mobile.png" width="390" alt="Tool activity panel and readable session details on a narrow viewport">
+
+## Explore the memory graph
+
+**Find node** lists visible records and searches stored memories in the selected scope. Pick a result to inspect its content, sources, and relations. **+**, **−**, and **Fit** control the graph view. Drag to pan after zooming. Use the relationship buttons to filter the visible edges by project membership, author, or recorded memory relation.
+
+![Dense memory graph and exchanges from three measured fixture sessions](assets/7.22.0-hub-graph.png)
+
+## Follow a measured exchange
+
+**MCP exchanges** shows recent measured tool activity by client session. The incoming arrow marks a request the workspace observed. The outgoing arrow marks a result ready at the tool boundary. Select an exchange to inspect its timing, status, and matching request or result when both are in the loaded history. **Latest** returns to incoming activity. **Pause motion** keeps the view still.
+
+![Replay inspector showing the selected request and its paired result](assets/7.22.0-hub-exchange.png)
+
+An empty memory store can still have real MCP activity. The graph count stays at zero and the exchange lanes show the measured calls.
+
+<img src="assets/7.22.0-hub-mobile-empty.png" width="370" alt="Empty project memory graph with three measured MCP client sessions on mobile">
+
+## Teach the project from ordinary notes
+
+In **Knowledge**, write “The cupboard is black” and select **Add to memory**. This directly saves a short note with its original source. For longer notes or changes before saving, choose **Review first**. Review each part, edit the wording if necessary, and select **Save to this project** or **Skip this part**.
+
+![Knowledge screen showing a plain-text fact saved with Add to memory](assets/7.22.0-teach-brain.png)
+
+Open **Context**, describe your next task, and select **Find useful context**. The result shows the saved wording, why it matched, and an **Original source** button. The source view shows the original text and your approved correction together. Select **Review usefulness** to report whether a memory helped; rebuilding the same context can show a bounded feedback adjustment. These changes affect stored memory and retrieval, not model weights. The text and clicks above were verified with an isolated synthetic project; no external model response is implied.
+
+![Context source inspection showing the original saved cupboard fact](assets/7.22.0-plain-evidence.png)
+
+Optional upload sections accept UTF-8 text, Markdown, or the supported JSON examples. The separate PDF workflow reviews extracted pages and cannot perform OCR. See [source intake](SOURCE_INTAKE.md) for formats, limits, privacy, and provenance details.
+
+## Keep and hand off a project session
+
+**Sessions** lists project records and their reported status. Recent activity indicates a recent report, not proof that a native client is still running. A portal session is a manual record and does not start an AI model. Write a note, add your own handoff summary and next steps, then save the checkpoint. **Copy agent resume request** prepares the request for a connected host; **Continue in portal** creates a separate portal-owned session with the saved handoff. The original remains available.
+
+![Sessions page showing an approved transcript imported as a completed snapshot](assets/7.22.0-sessions.png)
+
+The screenshot is from an isolated synthetic project. The imported transcript was explicitly selected and reviewed: the visible system label describes quoted source material, not an instruction with elevated authority. Only approved messages present at the first import are included; later imports reopen that snapshot. The portal flow and checkpoint continuation were checked in the browser; independent MCP host handoff was tested separately.
+
+## Set what the project shares
+
+In **Setup → Project sharing**, set maximum estimated context tokens and entries. Choose a conversation to control sharing or assign its coordination role. **Tool participation** controls whether a client label can use this project’s Shadow Brain operations.
+
+![Project sharing controls with saved context limits, a private conversation, and one disabled tool in an isolated synthetic project](assets/7.22.0-project-controls.png)
+
+**Context** previews the current delivery rules. **Sessions** retains local audit access and identifies conversations whose contents are withheld from connected agents.
+
+## Manage a generated project skill
+
+Apply a project skill in **Knowledge** to create its local ownership receipt. In **Setup → Managed project skills**, review the exact paths before disabling, enabling, or removing the skill.
+
+![Managed project skill disable preview showing its original and disabled paths](assets/7.22.0-managed-skills.png)
+
+The isolated browser fixture exercised creation, disable, enable, and removal. A separate skill that lacked a Project Kit ownership receipt retained its original bytes.
+
+[Workspace guide](WORKSPACE.md)

package/docs/WORKFLOW_INTEGRATION.md

@@ -6,7 +6,9 @@ Agent Shadow Brain 7.1.0 bundles practical guidance for coding agents. It helps
 
 From the project directory, launch `shadow-brain project workspace . --port 62595` and open `/hub`. Generate the client’s project-local recipe with `shadow-brain project config . --target codex` or the appropriate target. This routes the browser and host to the same project store.
 
-Compatible project-local MCP clients can use `hub_overview`, `hub_room_read`, `hub_room_create`, `hub_room_action`, and `hub_lesson_propose`. Approved PDF passages are available through normal memory and context tools. Confirm the tools the host actually exposes with its tool list. Room actions record the author and accept an operation key for safe retries. Host claims and artifact proposals carry revisions. The operator reviews evidence and controls lesson promotion and rollback. The service handles local state and tool responses. The host decides when to invoke a tool.
+Compatible project-local MCP clients can read and create rooms, exchange recorded evidence, and propose lessons. Use `hub_artifact_read` with the room ID, artifact ID and recorded SHA-256 from `hub_room_read` to retrieve up to 32 KiB of immutable UTF-8 text. Larger or binary artifacts are available through the project workspace. Room actions record the author and accept an operation key for safe retries. Host claims and artifact proposals carry revisions. The operator reviews evidence and controls lesson promotion and rollback.
+
+Project-local recall refreshes committed memory before each call and excludes archived, contested, and superseded records. The timeline and memory inspection retain those records for review. Approved PDF passages can be selected by project memory and context tools.
 
 ```mermaid
 flowchart LR