@theihtisham/agent-shadow-brain 7.1.0 → 7.1.4

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [7.1.4] - 2026-11-13 - Brain Hub, shared work, and reviewed learning
+
+- Made the dense Brain Hub the default portal, with an interactive memory graph, recorded-event animation, context comparison, knowledge intake, collaboration rooms, learning controls, and setup. The memory workspace and advanced interfaces remain available.
+- Added bounded PDF text extraction with page citations, explicit approval into local memory, and a needs-OCR state for scanned pages.
+- Added transactional project rooms with scoped MCP participation, task leases, typed messages, versioned artifact handoffs, acknowledgement, and recorded outcomes.
+- Added evidence-linked lesson candidates with operator-reported evaluation, explicit promotion, idempotent memory commits and rollback. These controls do not train model weights or autonomously execute agents.
+- Added independent server health and storage diagnostics, same-port reconnect, and stale-project mutation protection. Fixed local search/graph scope and Windows canonical-path and file-identity compatibility.
+- Raised the Node 22 minimum to 22.13 for PDF.js and built-in SQLite. Node 24.x and 26+ remain supported.
+
+- Added a provider-free project portal with persistent local knowledge, bounded project inspection, and task-specific skill previews. Generated skills remain inside the selected project and preserve edited or unowned files.
+- Added a revisioned project feedback store and local learning controls. User and agent reports remain distinguishable; small task-relevant adjustments affect existing adaptive matches only and can be removed or disabled.
+- Added optional adaptive retrieval with technical identifier/path matching, query-centered excerpts, duplicate grouping before the candidate cap, and bounded recorded-link expansion. Legacy remains the SDK/CLI/MCP default.
+- Added Context Lab pipeline and candidate explanations, profile comparison, source/review attention queues, directional graph inspection, and live journal replay with transport filters and reduced motion.
+- Added memory inspection/health tools, MCP resources and prompt templates, native client recipes, and five additional project-local tools. Local MCP launches enforce project scope across reads, prompts, resources and activity.
+- Fixed automatic briefing invalidation after external writes and staged local changes, scoped inventory selection before its cap, and the isolated demo's explicit port parsing.
+- Added an isolated synthetic demo, ten core workspace screenshots plus Project Kit and learning views, a GIF/MP4 walkthrough, a component catalog, and source-backed research/comparison documentation.
+- Added paired retrieval diagnostics, local persistence/feedback/scope regressions and fresh-package checks. Diagnostic results describe author-generated cases, not superiority over competing tools or model answer quality.
+
+Install `@7.1.4` explicitly when upgrading from the earlier publication named 7.2.0. Existing global memory workflows and advanced modules remain available; Project Kit does not migrate or merge them.
+
+## [7.1.3] - 2026-11-11 - Live activity and curated memory
+
+This release follows 7.2.0 using the version number requested by the maintainer. Install `@7.1.3` explicitly when upgrading from 7.2.0.
+
+- Added a live portal with an event-driven session network, measured tool charts, host-reported phases, timeline, pause, and reduced motion.
+- Added a bounded cross-process activity journal, cursor and reset detection, metadata-only MCP instrumentation, host reporting, and separate recording and visibility controls.
+- Added memory review, typed relations, audit history, and project-scoped curation through the workspace and CLI.
+- Excluded archived, contested, and superseded memories before context ranking; briefings refresh when reviews change.
+- Added standard MCP stdio, client capability checks, project skill diagnostics, and generated launch configuration.
+- Improved workspace navigation, source coverage, graph filtering, context explanations, dark mode, and mobile layouts.
+- Fixed empty-project graph scope, preservation of pending writes during read refresh, and per-client attach/detach targeting.
+
+
+## [7.2.0] - 2026-11-11 - Context Packs and Workspace
+
+- Make the local workspace the default dashboard with overview, searchable memories, graph, context, and feature controls. Keep the previous dashboard at `/advanced`.
+- Build size-bounded, project-scoped context packs with ranked memory selection, duplicate handling, recorded source provenance, and selection explanations.
+- Use context packs for session briefings. Key cached results to the task and current settings, and check enablement before reading or returning a briefing.
+- Persist four validated feature settings for context assembly, explicit cross-project context, automatic briefings, and dashboard activity delivery.
+- Add `context-pack` and `features list|set` commands, read-only `context_pack` and `feature_flags` MCP tools, and public context and settings APIs.
+- Refresh the README and workspace guide with a concept illustration and dashboard screenshots.
+
 ## [7.1.0] - 2026-11-11 - Focused Workflows and Portable Skills
 
 - Bundle six reusable skills for proportionate planning, implementation, diagnosis, review, research, and release work.

package/README.md

@@ -1,450 +1,125 @@
-# Agent Shadow Brain
-
-Local-first memory, focused task workflows, and portable skills for AI coding agents.
-
-Version: 7.1.0
-
-
-Agent Shadow Brain gives tools like Codex, Claude Code, Cursor, Cline, OpenCode, Aider, and related MCP clients a shared local memory layer. It stores compact, source-backed lessons about projects, recalls them later, generates fresh-session briefings, audits memory quality, and exports JSONL training/eval packs.
-
-It does not change model weights by itself. It helps agents work better by giving them relevant, current, source-linked context before and during complex work.
-
-## What's New in 7.1.0
-
-Six built-in skills help an agent understand the request, plan in proportion to the work, carry out authorized changes, and verify the result. Simple answers stay simple. Planning-only, diagnosis-only, and review-only requests keep their boundaries; existing authorization carries forward.
-
-- **Focused skills:** `shadow-workflow`, `shadow-implement`, `shadow-debug`, `shadow-review`, `shadow-research`, and `shadow-release`.
-- **Project integrations:** Codex, Claude Code, OpenCode, and DeepSeek Harness skill directories, plus a portable option. Preview installation first; preserve existing project instructions and locally edited skills.
-- **Workflow guidance:** CLI, library, and MCP interfaces suggest steps and relevant skills. Routing is a local English-language heuristic with explicit overrides. The host agent interprets the request and performs the work.
-- **No provider setup required:** skills and workflow analysis run locally without model calls, credentials, background agents, or global configuration changes.
-
-Run these commands **from your project root**:
-
-```bash
-shadow-brain skills list
-shadow-brain skills install . --target codex
-shadow-brain skills install . --target codex --apply
-shadow-brain workflow analyze "Investigate and fix the failing export" --json
-```
-
-Replace `codex` with `claude-code`, `opencode`, `deepseek-harness`, or `portable`. Use `--target all` to install the four native layouts. The preview writes nothing; `--apply` writes the listed files after validation. Clients must support and enable skill discovery. DeepSeek Harness requires its filesystem skills, registry/tool support, and project-instruction context to be enabled. Installing files alone does not prove a running client loaded them.
-
-See the [integration guide](docs/WORKFLOW_INTEGRATION.md) for selection, preservation behavior, library/MCP examples, and compatibility sources; [7.1 release notes](docs/launch/RELEASE_NOTES_v7.1.0.md) describe the scope.
-
-## Memory improvements in 7.0.0
-
-- **Durable multi-agent memory.** Saves lock, reload, and merge the latest store so independent agents cannot replace each other's new memories. Queued writes acknowledge success after persistence. Failed operations remain retryable and visible in storage health.
-- **Explainable recall.** Results include matched keywords, score components, and identities reporting the same normalized content within the same project and category. Unrelated notes no longer inflate scores. Scores are ranking heuristics, not probabilities of truth or proof of independent verification.
-- **Storage diagnostics.** Use `shadow-brain storage-health --json` or MCP `global_storage_health` to inspect errors and pending operations. Invalid or unsupported stores fail explicitly and remain unchanged.
-- **Safer setup and packaging.** Installation no longer edits agent settings. Help, version, and memory diagnostics do not load provider configuration. Dependencies are refreshed, activity-log text is escaped, and package tests install a real tarball into a fresh consumer project.
-
-### Upgrade from 6.x
-
-Use Node.js 22.12+ within 22.x, Node 24.x, or Node 26+. Back up your existing `global.json` before upgrading and stop older Shadow Brain writers; older versions do not participate in the new lock protocol. The schema remains version 1. Start integrations explicitly using the existing setup/attach commands after installation.
-
-`writeSync()` remains an in-memory operation; call `await brain.sync()` for durable persistence. `await brain.write()` resolves after the background sync or an explicit sync; a false result means persistence failed or the queue was full. Failed accepted operations remain pending for retry. Recall reads the process snapshot, refreshed by sync; it is not an instantaneous cross-process read.
-
-### New commands
-
-```bash
-shadow-brain storage-health --json
-shadow-brain storage-health --db ./global.json --json
-shadow-brain recall-explain "deployment rollback" --limit 5
-shadow-brain recall-explain "database migration" --project . --min-confidence 0.4
-```
-
-`storage-health` validates readability and schema, reports JSON even on failure, and exits with code 1 for an invalid store. It does not repair or rewrite an existing store; when checking a missing store it may create its parent directory. `lastSuccessfulSync` describes the current process only. The MCP health tool inspects existing process state without initializing or flushing it.
-
-The library exports `GlobalBrain`, `getGlobalBrain`, and their public types:
-
-```js
-import { getGlobalBrain } from '@theihtisham/agent-shadow-brain';
-const brain = getGlobalBrain({ dbPath: './global.json' });
-await brain.init();
-console.log(brain.recallScored({ keywords: ['deployment'], limit: 5 }));
-console.log(brain.getStorageHealth());
-await brain.shutdown();
-```
-
-Details: [release notes](docs/launch/RELEASE_NOTES_v7.0.0.md).
-
-## Earlier dashboard features
-
-- **Simple by default, Advanced on demand.** The dashboard opens with eight plain-English tabs (Home, Brain Map, Memories, Ask the Brain, Activity, Connected Tools, Brain Health, Settings). Flip to Advanced to reveal every feature — nothing was removed, just tidied.
-- **Brain Map.** An interactive graph of everything the brain remembers — memories, projects, tools, and tags — sized by importance (PageRank) and linked by shared context. Zoom, pan, click a node for details, and watch it grow live as new memories arrive.
-- **Realtime activity.** Memory writes, reflections, and tool events stream live over WebSocket instead of polling, with a live pulse on Home.
-- **Live Network.** A refreshed animation of your tools talking to the brain, with flowing signal pulses.
-- **Two-way knowledge seeding.** Quick-Save captures knowledge in one click; "Hand to Agent" generates a ready briefing to pass context back to any tool.
-- **Plain-language everywhere.** Cryptic feature names rewritten (e.g. Calibration → Accuracy, Pre-Mortem → Risk Check, Tokens → Cost & Usage), each with a hover description.
-
-
-## What It Actually Does
-
-- Stores cross-project and cross-agent memories in a local JSON brain at `~/.shadow-brain/global.json`.
-- Recalls memories by project, agent, category, and keywords.
-- Generates source-backed resume packs for fresh sessions, account switches, context compaction, and handoffs.
-- Audits memory quality: source coverage, stale entries, duplicates, low-quality notes, recall health.
-- Creates verified memory seed drafts from dashboard/API, then requires user, agent, or dual approval before writing to durable memory.
-- Exports JSONL rows for evals, distillation, or local fine-tuning pipelines.
-- Provides CLI, dashboard API, and MCP tool surfaces.
-- Includes safety helpers such as hook audit, detach, and action firewall checks.
-- Works without telemetry and without an API key for local memory features.
-
-## What It Does Not Claim
-
-- It does not secretly train GPT, Claude, Gemini, or any remote model.
-- It does not guarantee perfect recall.
-- It does not replace project docs, tests, source control, or human review.
-- It does not make every listed agent automatically available. Agent support depends on local installation and hook/config compatibility.
-- It does not publish or sync data unless you explicitly use export, sync, or other sharing commands.
-
-## Install
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain
-```
-
-CLI binaries:
-
-```bash
-shadow-brain --help
-asb --help
-```
-
-You can also run without global install:
-
-```bash
-npx @theihtisham/agent-shadow-brain@latest --help
-```
-
-## Safe First Run
-
-Start by auditing before attaching hooks:
-
-```bash
-shadow-brain audit-hooks .
-shadow-brain live-brain status .
-```
-
-Only attach after you review what will be changed:
-
-```bash
-shadow-brain attach-all .
-```
-
-Detach later if needed:
-
-```bash
-shadow-brain detach-all .
-```
-
-## v6.0.3: Live Brain
-
-The 6.0.3 release focuses on practical long-memory improvement for agents.
-
-### Live Brain Status
-
-```bash
-shadow-brain live-brain status .
-```
-
-Shows:
-
-- memory count
-- average memory quality
-- source coverage
-- stale memories
-- duplicate clusters
-- recall eval score
-- recommended cleanup actions
-
-JSON output:
-
-```bash
-shadow-brain live-brain status . --json
-```
-
-### Agent Briefing
-
-Generate a markdown briefing for a fresh agent session:
-
-```bash
-shadow-brain live-brain brief . -o SHADOW_BRAIN_AGENT_BRIEF.md
-```
-
-The briefing includes:
-
-- rules for agents
-- top source-backed memories
-- memory warnings
-- recall health
-- commands agents should run next
-
-### Recall Eval
-
-Check whether the brain can retrieve useful memories for common agent tasks:
-
-```bash
-shadow-brain live-brain eval .
-```
-
-Custom eval queries use pipe separators:
-
-```bash
-shadow-brain live-brain eval . --queries "current blocker|do not repeat|verified command"
-```
-
-### Memory Hygiene
-
-List concrete cleanup and learning actions:
-
-```bash
-shadow-brain live-brain hygiene .
-```
-
-This highlights missing sources, stale memories, duplicates, weak recall, and missing project-scoped memories.
-
-### Training/Eval Export
-
-Export source-backed memories as JSONL:
-
-```bash
-shadow-brain live-brain train-pack . --out shadow-brain-training.jsonl
-```
-
-This is useful for:
-
-- retrieval evals
-- local distillation experiments
-- supervised fine-tuning datasets
-- memory regression tests
-
-The export is only data preparation. You choose the downstream training/eval tool.
-
-## Core Memory Commands
-
-Recall from the global brain:
-
-```bash
-shadow-brain global recall --query "current blocker next step" --json --limit 8
-```
-
-Show global stats:
-
-```bash
-shadow-brain global stats
-```
-
-Create a source-backed resume seed:
-
-```bash
-shadow-brain resume-seed . -o SHADOW_BRAIN_RESUME_SEED.md
-```
-
-Show what a project has learned:
-
-```bash
-shadow-brain timeline . --limit 30
-```
-
-Create a cross-agent handoff packet:
-
-```bash
-shadow-brain handoff codex claude-code . --task "continue release verification"
-```
-
-Record a durable memory from a script:
-
-```bash
-node tools/record-global-memory.mjs ^
-  --project-dir "." ^
-  --project-name "my-project" ^
-  --agent codex ^
-  --category "project.lesson" ^
-  --importance 0.8 ^
-  --tags "memory,release" ^
-  --sources "README.md,CHANGELOG.md" ^
-  --content "Keep release notes source-backed and verify npm metadata before publish."
-```
-
-## Dashboard
-
-Start the local dashboard:
-
-```bash
-shadow-brain dash . --no-open --port 7341
-```
-
-For a fast UI/API-only launch on a large repo:
-
-```bash
-shadow-brain dash . --no-open --no-analysis --host 127.0.0.1 --port 7341
-```
-
-Open:
-
-```text
-http://127.0.0.1:7341
-```
-
-The v6 dashboard includes a **Live Brain** tab for memory health, source coverage, recall evals, hygiene actions, top memories, and the generated agent briefing.
-
-It also includes:
-
-- **Memory Browser intelligence cards** for total memories, source coverage, fresh learning, seed queue, top categories, agent coverage, and top tags.
-- **Memory Seeder** for controlled research-to-memory workflows. Drafts stay out of the global brain until approval is complete.
-- **Token Economy accuracy split**: current runtime agent is shown separately from historical model spend, so old Claude/Cursor spend records do not imply the dashboard is running that agent.
-
-### Realtime Activity (new in 6.1.0)
-
-The dashboard now streams brain activity live over its WebSocket instead of polling. Memory writes, dreams, seed drafts/commits, collisions, sub-agent spawns, and consolidation cycles appear the instant they happen.
-
-- **Live Pulse** card on the Overview with a streaming mini-feed and an events/min rate.
-- **Activity Log** tab with filter chips, a pulsing LIVE badge, pause/resume, clear, search, and an events/min sparkline.
-- **Connection indicator** in the header — green when the realtime socket is live, amber while reconnecting.
-- **Cross-process aware**: a memory written by an agent in a *different* terminal is picked up by watching `~/.shadow-brain/global.json`, so the feed reflects the whole machine, not just this process.
-
-Polling remains as a 15-second reconciliation fallback; live events arrive in well under a second.
-
-### Intelligence Hub — Memory Constellation (new in 6.2.0)
-
-A new **Intelligence** tab turns the brain into an interactive graph. Every memory, project, agent, and tag is a node in a force-directed **Memory Constellation**, sized by importance (PageRank blended with each memory's own score) and linked by project, author, tags, and shared-tag relatedness.
-
-- **Interactive**: scroll to zoom, drag to pan, click a node to focus its neighborhood and open a detail drawer; hover for a tooltip.
-- **Filters + search** by node type (memory / project / agent / tag).
-- **Live**: new memories pulse into the graph over the realtime stream.
-- **Analytics strip**: source-coverage gauge, agent-contribution and category charts, tag cloud, and a recent-memory feed.
-- Works instantly on your existing `~/.shadow-brain/global.json` — no project analysis or setup step.
-
-Several previously sparse tabs were also rebuilt with real visualizations: **Pre-Mortem** (risk matrix + failure cards), **Attention** (weighted heat bars), **Calibration** (Brier/trust chart), **Reputation** (trust rings), **Causal Chains** (node-link DAG), and **Branch Brains** (stat cards).
-
-Constellation API:
-
-```text
-GET /api/v6/memory-graph
-```
-
-
-Memory seeding API:
-
-```text
-GET  /api/v6/seed-drafts
-POST /api/v6/seed-draft
-POST /api/v6/seed-approve
-POST /api/v6/seed-reject
-POST /api/v6/seed-commit
-GET  /api/v6/memory-intelligence
-```
-
-Useful API endpoints:
-
-```text
-GET/POST /api/v6/live-brain
-GET/POST /api/v6/resume-pack
-GET/POST /api/v6/ww2br-recall
-GET/POST /api/v6/memory-browser
-```
-
-Example:
-
-```bash
-curl "http://127.0.0.1:7341/api/v6/live-brain?projectDir=C:/path/to/project"
-```
-
-## MCP Tools
-
-The MCP server exposes memory and agent-control tools for compatible clients.
-
-New in 6.3.0:
-
-- `global_recall_scored` — recall with a per-memory confidence score (recency, author importance, cross-agent corroboration, prior usage, keyword relevance). Results are ranked by confidence so agents can weight memories instead of trusting every hit equally. Supports `minConfidence` to drop low-trust hits.
-
-New in 6.0.3:
-
-- `live_brain_status`
-- `live_brain_brief`
-- `live_brain_train_pack`
-
-Existing useful tools include:
-
-- `global_recall`
-- `global_recall_scored`
-- `global_stats`
-- `global_timeline`
-- `subconscious_inject`
-- `agent_handoff`
-- `firewall_check`
-
-Start MCP from the dashboard API or existing CLI/server integration, depending on your setup.
-
-## How Agents Should Use It
-
-Recommended workflow for complex work:
-
-1. Run `shadow-brain live-brain status <project>`.
-2. Generate or read a live briefing.
-3. Verify current project docs and source files.
-4. Work normally.
-5. Record only durable, source-backed lessons after proof.
-6. Run recall evals when memory quality starts to drift.
-
-Good memories are short, action-oriented, and source-backed:
-
-```text
-[lesson:release-readme-v1] Before publishing, verify package.json version, package-lock root version, README install commands, build output, and npm pack contents.
-Sources: package.json; package-lock.json; README.md
-Tags: release,npm,verification
-```
-
-Bad memories are vague:
-
-```text
-Make project better.
-```
-
-## Local Data
-
-Default global brain:
-
-```text
-~/.shadow-brain/global.json
-```
-
-Project-local generated files may include:
-
-```text
-SHADOW_BRAIN_AGENT_BRIEF.md
-SHADOW_BRAIN_RESUME_SEED.md
-shadow-brain-training.jsonl
-```
-
-Do not store secrets, API keys, passwords, private keys, or raw credentials in memory content, metadata, tags, prompts, reports, or exported training data.
-
-## Development
-
-```bash
-npm ci --ignore-scripts
-npm run verify
-npm run test:package
-```
-
-Focused tests:
-
-```bash
-npx vitest run tests/brain/live-brain.test.ts tests/brain/context-continuity.test.ts
-```
-
-On Windows PowerShell, if execution policy blocks `npm.ps1`, use:
-
-```powershell
-npm.cmd run build
-npx.cmd vitest run tests\brain\live-brain.test.ts
-```
-
-## Release Checklist
-
-Run `npm run verify`, `npm audit --audit-level=high`, and `npm run test:package`. Inspect the package allowlist, then publish the verified tarball. Confirm the npm version, integrity, and GitHub tag before announcing a release. See [the complete release checklist](docs/launch/RELEASE_CHECKLIST_v7.0.0.md).
-
-## License
-
-MIT
+<h1 align="center">Agent Shadow Brain</h1>
+
+[![Follow Ihtisham on GitHub](https://img.shields.io/badge/Follow-Ihtisham%20on%20GitHub-181717?logo=github&logoColor=white)](https://github.com/theihtishaam)
+<p align="center"><strong>A shared brain for the tools you build with.</strong></p>
+<p align="center">Keep project knowledge, understand context, and follow the work between your AI tools.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@theihtisham/agent-shadow-brain"><img alt="npm latest version" src="https://img.shields.io/npm/v/@theihtisham/agent-shadow-brain/latest?label=npm&amp;color=0f766e"></a>
+  <a href="https://www.npmjs.com/package/@theihtisham/agent-shadow-brain"><img alt="npm downloads per month" src="https://img.shields.io/npm/dm/@theihtisham/agent-shadow-brain?label=downloads%20%2F%20month&amp;color=0f766e"></a>
+  <a href="docs/STATS.md"><img alt="Cumulative npm downloads" src="https://raw.githubusercontent.com/theihtishaam/agents-brain/main/docs/assets/npm-total-downloads.svg"></a>
+  <a href="https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/theihtishaam/agents-brain/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/theihtishaam/agents-brain?color=475569"></a>
+  <a href="https://github.com/theihtishaam/agents-brain/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/theihtishaam/agents-brain?style=flat&amp;logo=github&amp;color=475569"></a>
+</p>
+
+<p align="center"><a href="#try-it">Try it</a> · <a href="#inside-the-brain-hub">Visual tour</a> · <a href="#connect-your-agent">Connect your agent</a> · <a href="docs/README.md">Documentation</a></p>
+
+![Running Brain Hub with imported public documentation, measured MCP tool calls, and source inspection](docs/assets/7.1.4-hub-public-docs.gif)
+
+[What works and its limits](docs/FEATURES_AND_LIMITS.md)
+
+The Brain Hub brings project memory, cited PDF pages, shared work, and recorded tool activity into one local workspace. The animation shows 74 excerpts from 18 public Agent Brain documents loaded into an isolated store. The activity journal records three actual local MCP calls from a scripted client. [Public documentation snapshot](https://github.com/theihtishaam/agents-brain/tree/2e26e7b349db4dd75bf0277b28caff8044190d16) · [Visual guide](docs/VISUAL_GUIDE_v7.1.4.md)
+
+## Try it
+
+Use **Node.js 22.13+ in the 22.x line, 24.x, or 26+**. This guide describes the 7.1.4 build. Check the installed version before using the Hub steps.
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+cd your-project
+shadow-brain project workspace . --port 62595
+```
+
+Keep the launcher running and open [the project Brain Hub](http://127.0.0.1:62595/hub). Use the same project directory and port when restarting. Port `0` lets the OS assign a free port, so open the URL printed by that launch. The classic workspace remains at `/workspace`; detailed activity diagnostics remain at `/live`.
+
+To build from this checkout while preparing a release, use `npm ci`, `npm run build`, then `node dist/cli.js project workspace . --port 62595`. The command’s directory argument selects which project store to open. [Quickstart](docs/QUICKSTART.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)
+
+## Inside the Brain Hub
+
+![Brain Hub with stored public documentation, linked references, context estimates, and a measured MCP receipt](docs/assets/7.1.4-hub-public-docs.png)
+
+| View | What you can do |
+| --- | --- |
+| **Brain overview** | Follow stored memory relationships, open a node or its keyboard-accessible list entry, and seek through recorded activity. An empty store has zero graph nodes and edges. |
+| **Knowledge** | Upload a PDF, review extracted text page by page, approve a cited page into project memory, or save supplied knowledge. Preview and apply a host-specific project skill. |
+| **Collaboration** | Open a project room, post a proposal or critique, claim a task, attach a project file, accept evidence, and record the outcome. |
+| **Context** | Assemble a scoped pack, inspect selected passages and sources, compare retrieval profiles, and copy the rendered Markdown. |
+| **Models and Usage** | Inspect host file presence, retained tool activity, and estimated pack tokens. Missing model identities, token receipts, and costs display as unavailable. |
+| **Learning** | Create a lesson from a recorded outcome. Record a paired evaluation, promote an eligible lesson, or roll back its retrieval influence. |
+| **Setup** | Copy client configuration recipes and manage persisted runtime controls. |
+
+### Follow evidence from a PDF to a context pack
+
+![Working PDF intake with extracted text, a page locator, and approved project memory](docs/assets/7.1.4-hub-knowledge.png)
+
+```mermaid
+flowchart LR
+  PDF[Local PDF] --> Parse[Extract page text]
+  Parse --> Review[Review cited page]
+  Review -->|Approve| Memory[Project memory]
+  Memory --> Pack[Scoped context pack]
+  Pack --> Host[Copy or retrieve through MCP]
+```
+
+The project store records the document fingerprint and the approved page citation. An image-only page shows that OCR is needed. Context budget figures estimate rendered pack tokens, and profile comparisons use the same scoped request. Provider billing and model-token receipts remain unavailable. [Context guide](docs/CONTEXT_LAB.md)
+
+### Coordinate work and record a lesson
+
+```mermaid
+flowchart LR
+  Goal[Project room] --> Msg[Proposal or critique]
+  Msg --> Claim[Task claim and lease]
+  Claim --> Artifact[Versioned file and digest]
+  Artifact --> Outcome[Recorded outcome]
+  Outcome --> Candidate[Lesson candidate]
+  Candidate --> Evaluate[Operator records evaluation]
+  Evaluate --> Promote[Explicit promotion]
+  Promote --> Rollback[Rollback archives retrieval influence]
+```
+
+Browser and compatible project-local MCP clients share the same room records. Task claims carry revisions and expire. A recipient acknowledgement references the specific message or artifact. Learning changes project memory and retrieval. The workspace does not run models, train them, or assign work to hosts by itself. [Workspace guide](docs/WORKSPACE.md) · [Workflow integration](docs/WORKFLOW_INTEGRATION.md)
+
+![Actual learning view with a recorded comparison and rolled-back lesson](docs/assets/7.1.4-hub-learning.png)
+
+### Browse the original evidence tools
+
+The classic workspace offers memory curation, typed relationships, retrieval feedback, and the full Context Lab. The detailed activity view adds filters and playback controls for the loaded journal.
+
+![Classic Context Lab with selected and excluded evidence](docs/assets/7.1.4-context-lab.png)
+
+![Memory review with recorded sources and typed links](docs/assets/7.1.4-memory-review.png)
+
+![Activity diagnostics showing a recorded tool timeline](docs/assets/7.1.4-live.png)
+
+## Connect your agent
+
+Generate a recipe from the same directory used to start the project workspace. The recipe identifies the project store and launches the local stdio service.
+
+```bash
+shadow-brain project config . --target codex
+shadow-brain skills install . --target codex
+```
+
+Preview the skill installation before adding `--apply`. Merge the printed recipe in the selected host, reconnect, and confirm it can list and call a tool such as `project_inspect` or `context_pack`. A recorded exchange will appear when activity recording and display are enabled. [Integration guide](docs/INTEGRATIONS.md)
+
+| Target | Recipe |
+| --- | --- |
+| Codex | `shadow-brain project config . --target codex` |
+| Claude Code | `shadow-brain project config . --target claude-code` |
+| OpenCode | `shadow-brain project config . --target opencode` |
+| DeepSeek Harness | `shadow-brain project config . --target deepseek-harness` |
+| Other compatible host | `shadow-brain project config . --target portable` |
+
+The Setup page distinguishes installed skill files and generated configuration from recorded activity. The public documentation capture used a scripted MCP client. Native host connectivity, model identity, and provider usage remain unavailable in that capture.
+
+![Actual Setup view with persisted feature switches and client recipes](docs/assets/7.1.4-hub-setup.png)
+
+## Documentation
+
+- [Quickstart](docs/QUICKSTART.md) · [Workspace guide](docs/WORKSPACE.md) · [Visual guide](docs/VISUAL_GUIDE_v7.1.4.md) · [Features and limits](docs/FEATURES_AND_LIMITS.md)
+- [Project Kit](docs/PROJECT_KIT.md) · [Context Lab](docs/CONTEXT_LAB.md) · [Workflow skills](docs/WORKFLOW_INTEGRATION.md)
+- [Integrations](docs/INTEGRATIONS.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Release notes](docs/launch/RELEASE_NOTES_v7.1.4.md)
+
+MIT license. [Changelog](CHANGELOG.md)

package/dist/activity-cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerActivityCommands(program: Command): void;
+//# sourceMappingURL=activity-cli.d.ts.map

package/dist/activity-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-cli.d.ts","sourceRoot":"","sources":["../src/activity-cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyDpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2C/D"}