@theihtisham/agent-shadow-brain 7.2.0 → 7.22.0

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

@@ -2,9 +2,29 @@
 
 Agent Shadow Brain 7.1.0 bundles practical guidance for coding agents. It helps the host select an appropriate workflow, avoid unnecessary extra work, and check the requested result. It does not call a model or run the task on its own. Your host agent supplies the reasoning, tools, permissions, and execution.
 
+## Share project work through the Hub
+
+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 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
+  Operator[Browser operator] --> Store[Project-local Hub store]
+  Host[Configured MCP host] --> Store
+  Store --> Work[Rooms, claims, and artifacts]
+  Store --> Records[PDF citations and lessons]
+  Host --> Journal[Local activity journal]
+  Journal --> Operator
+```
+
+[Workspace guide](WORKSPACE.md) · [Client recipes](INTEGRATIONS.md)
+
 ## Choose a client and install
 
-Use Node 22.12+ within 22.x, Node 24.x, or Node 26+. Install the package, move to the project root, and preview the files:
+Use Node 22.13+ within 22.x, Node 24.x, or Node 26+. Install the package, move to the project root, and preview the files:
 
 ```bash
 npm install -g @theihtisham/agent-shadow-brain

package/docs/WORKSPACE.md

@@ -1,70 +1,63 @@
-# Workspace guide
-
-Start the local workspace from your project directory.
-
-```bash
-shadow-brain dash . --no-analysis
-```
-
-The CLI binds to `127.0.0.1:7341` by default and opens the workspace. Use `--no-open` to open the printed address yourself, or `--port` to choose another port. `--no-analysis` starts the UI and API without background project analysis.
-
-**Overview** shows the memory count, projects and agents represented in the inventory, and recent activity. **Memories** supports project, category, agent, and text filters. **Graph** connects each memory to its project and recording agent. Select a node to inspect its detail. **Context** builds a pack for the task at hand. **Features** changes the runtime controls.
-
-The workspace uses up to 2,500 recent memories for its inventory and filter lists. Text search ranks matching records in the selected scope and returns up to 2,500 results. The graph displays up to 180 memories plus their project and agent nodes. The workspace indicates when it is showing a partial view.
-
-Visit `/advanced` for the previous dashboard and its existing tools. Its Features page links to the current controls.
-
-## Build context for the task
-
-Choose a project and enter a task or a few search terms. Review the selected memories, their recorded references, and the reasons entries were skipped before copying the pack.
-
-```bash
-shadow-brain context-pack "trace retry behavior in the importer" --project . --token-budget 1200 --json
-```
-
-The assembler considers up to 200 ranked candidates and selects up to 12 entries by default. The library supports a maximum of 30 entries. It groups exact content matches within a project after normalizing case and whitespace, keeps the highest-ranked representative, and carries forward bounded source references with their originating memory IDs. Distinct statements remain separate.
-
-The size limit applies to the complete Markdown, including labels and references. Long text can appear as a labeled excerpt. The assembler skips oversized entries and checks the remaining candidates. The token estimate is the rendered JavaScript string length divided by four, rounded up. It is a rough sizing guide because model tokenizers count text differently.
-
-Context stays within the selected project unless you enable `crossProjectContext` and explicitly request other projects using the workspace option, `--cross-project`, or the MCP/library option. Broader packs label each memory's project. Recorded references come from saved memory metadata. Check them against current sources before relying on a claim.
-
-Session-start briefings use the same assembler and budget. They respect the current task, project, allowed agents, and runtime controls. A task can still recall an older relevant lesson.
-
-## Change the runtime controls
-
-Set features in the workspace or through the CLI.
-
-```bash
-shadow-brain features list
-shadow-brain features set automaticBriefing off
-shadow-brain features set automaticBriefing on
-```
-
-| ID | Default | What it controls |
-| --- | --- | --- |
-| `contextAssembly` | On | Builds context packs, including the memory context used by session briefings. |
-| `crossProjectContext` | Off | Permits a context request to include other projects when the caller explicitly selects it. |
-| `automaticBriefing` | On | Generates session-start briefings for eligible agents. Turning it off also suppresses previously cached briefings. |
-| `liveActivity` | On | Serves the dashboard activity feed and delivers WebSocket activity events and backlog. Memory storage and other internal events continue operating. |
-
-Settings persist in `~/.shadow-brain/feature-settings.json` and take effect on the next relevant operation. The workspace writes validated changes and checks the settings revision before saving. If another client changes the settings first, review the refreshed values and try again. CLI commands accept `--settings <path>` for an explicitly selected file.
-
-## Integrate with a client
-
-The read-only MCP tools `context_pack` and `feature_flags` provide context assembly and current feature states. `context_pack` accepts `projectId`, optional `query`, `tokenBudget`, and `includeCrossProject`.
-
-The library exports `assembleContext`, `FeatureSettingsStore`, and their types. Pass a recall source and current feature settings to `assembleContext`. Context assembly uses stored memories and recorded references without making model calls.
-
-The local dashboard uses these HTTP endpoints.
-
-| Method and route | Purpose |
-| --- | --- |
-| `GET /api/workspace/overview` | Workspace totals, projects, recent memories, and current activity state. |
-| `GET /api/workspace/memories` | Filter and page through saved memories. |
-| `GET /api/workspace/graph` | Get project, agent, and memory nodes and their relationships. |
-| `POST /api/workspace/context` | Send a project ID, query, budget, and cross-project choice. |
-| `GET /api/workspace/activity` | Read the activity feed when enabled. |
-| `GET /api/workspace/features` | Read feature settings and their revision. |
-| `POST /api/workspace/features` | Send a boolean `patch` and optional `expectedRevision`. |
-
-Install the [bundled workflow skills](WORKFLOW_INTEGRATION.md) separately to give compatible clients task guidance.
+# Workspace guide
+
+Start a project-local Brain Hub from your project directory.
+
+```bash
+shadow-brain project workspace . --port 62595
+```
+
+Open [the project Hub](http://127.0.0.1:62595/hub). Keep the process running and reuse the same directory and port after restarting. `/workspace` opens the classic memory workspace; `/live` opens detailed activity diagnostics. The shared-store `shadow-brain dash . --no-analysis` opens an all-project view. Project-local PDF review, rooms, skills, and lesson promotion require the project workspace.
+
+![Running Brain Hub with stored memories and observed tool exchanges](assets/7.22.0-hub-graph.png)
+
+## Inspect records and activity
+
+Select a project, agent, or memory node. **Find node** lists the displayed graph records and searches stored memories in the selected scope. Selecting a search result brings the exact record into the graph even when it falls outside the current sample. Use **+**, **−**, and **Fit** to adjust the view, or drag the zoomed canvas with a pointer. The relationship filters show project membership, recorded authors, or explicit memory links. The inspector shows the record, its recorded sources, and its links.
+
+**MCP exchanges** shows recent measured client sessions even in a project with no stored memories. The request arrow points from client to workspace. The result arrow points from workspace to client when a handler completes, with the outcome shown on the receipt. A result-ready event records tool completion. Model consumption is unobserved. Select a lane, or open **Trace** and choose a journal record. The inspector links an exact matching request or result when both are retained in the loaded history. **Latest** returns to incoming activity. **Pause motion** and reduced-motion settings keep the display still.
+
+## Review and use knowledge
+
+Use **Knowledge** to write an ordinary fact, paragraph or plan and click **Add to memory**. For longer notes or corrections, choose **Review first**. Optional PDFs provide extracted pages with source citations; image-only pages require OCR. You can also inspect project markers or preview and apply a project skill. [Plain-text guide](SOURCE_INTAKE.md) · [Project Kit](PROJECT_KIT.md)
+
+Use **Context** to enter a task, set a budget, compare profiles, and copy a pack. Review selected passages, reasons, and citations. The pack size is estimated. Tool timings and model token receipts are separate, and unavailable receipts stay visibly unavailable. [Context Lab](CONTEXT_LAB.md)
+
+## Report optional model usage
+
+A cooperating host can call `usage_report` with counters and metadata it already knows. For example, replace the project and session identifiers with the host's actual labels:
+
+```json
+{
+  "operationId": "example-operation-1",
+  "projectId": "0123456789abcdef",
+  "sessionId": "example-host-session",
+  "agent": "codex",
+  "requestModel": "example-model",
+  "reasoningEffort": "high",
+  "inputTokens": 1200
+}
+```
+
+`reasoningEffort` is an optional short plain label reported by the host, not a value inferred from a model name. Omit it and any unknown counters when they are unavailable; zero means a reported zero. Receipts remain labelled **host-reported**, do not include prompts or credentials, and are not billing records. A receipt can be associated with a project session only when project ID, the host session ID and the agent label match exactly. Reuse the same operation ID for an identical retry.
+
+## Share a task and its evidence
+
+Create or open a **Collaboration** room. Post a proposal, critique, question, decision, or handoff. Add a task and claim it before attaching a project-relative file. The task’s lease and revision control ownership. Accept the current submitted artifact and record the result with its check and evidence. A participant can acknowledge another participant’s message or artifact. These operations are shared with project-local MCP clients. [Workflow integration](WORKFLOW_INTEGRATION.md)
+
+In **Learning**, propose a lesson from a recorded outcome. Record the baseline, candidate, controls, and evidence. Promotion is an explicit operator action. Rollback archives the promoted memory so it no longer influences normal retrieval. Use the classic workspace to manage separate task-scoped retrieval feedback. [Learning guide](LEARNING.md)
+
+## Change runtime controls
+
+In **Setup**, manage context packs, activity display, and activity recording. The project portal stays pinned to its project, so cross-project context is unavailable here. Automatic briefing requires a legacy analysis session. Feature changes are revisioned and persist when the local process restarts. Disabling the activity display hides journal records in the Hub. Disabling recording stops new optional telemetry. Work-room records remain available.
+
+**Project sharing** lets you set context ceilings, control tool participation, and turn off delivery for a conversation. An unshared chat and its inherited handoffs remain available for operator audit. Memories with explicit provenance linking them to that conversation are removed before retrieval ranks or merges candidates. Older memories without that linkage cannot be associated automatically. Tool limits follow the MCP client label; roles are coordination labels. **Context** previews the same limits, including its reference comparison.
+
+Setup can print native client recipes and diagnostic text. Recipes point to the selected local installation and store. To confirm the host actually uses the same project, call one of its project tools and inspect the journal. [Integrations](INTEGRATIONS.md)
+
+The project Hub uses a local event stream for store changes while the tab is visible. **Polling fallback** appears if the stream disconnects. A reconnect can replay retained notices or refresh the current snapshot when the replay window has expired. Earlier records do not start fresh activity animations.
+
+Turn on **Project file activity** in Setup to see eligible relative paths and grouped filesystem notifications in **Sessions**. Watching runs while there is an open live subscription and both live display and recording are enabled. The watcher skips hidden, private, configuration, dependency, and build paths, and does not open file contents. It caps directory watches at 64 and shows at most 180 project paths and the 24 latest groups in the panel. File changes have an unknown actor. A grouped notification only establishes that the filesystem reported a change.
+
+A local Windows fixture measured 30 writes through to the visible Chrome page. Ten independent MCP memory writes, ten session API writes, and ten allowed file creates delivered in 241 ms median and 386 ms p95, with an 888 ms maximum. Over 60 seconds idle on the same fixture and Node 24.15.0, workspace RSS moved from 82.33 to 82.21 MiB, average server CPU was 0.365% of one core, and the open Sessions page made no workspace API refetches.
+
+[Visual guide](VISUAL_GUIDE_v7.22.0.md) · [Troubleshooting](TROUBLESHOOTING.md)