@theihtisham/agent-shadow-brain 7.1.0 → 7.1.4

package/docs/PROJECT_KIT.md

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

package/docs/QUICKSTART.md

@@ -0,0 +1,44 @@
+# 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)

package/docs/README.md

@@ -0,0 +1,33 @@
+# 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)

package/docs/ROADMAP-v7.md

@@ -0,0 +1,147 @@
+# Shadow Brain — Roadmap to v7.0 and Beyond
+
+> **Status:** Living document
+> **Last updated:** 2026-05-12
+> **Author:** @theihtisham
+> **Companion docs:** `RELEASE_NOTES_v6.0.2.md`, `VIRAL-PLAYBOOK.md`
+
+This is the strategic plan. v6.0.2 ("Singularity") shipped the substrate. v7.0 is where Shadow Brain becomes the default infrastructure for every AI coding agent on Earth.
+
+---
+
+## North Star
+
+> **"Every line of code an AI agent writes anywhere should be able to draw on every relevant lesson your team has ever learned — instantly, locally, privately."**
+
+That's it. The roadmap exists to compound toward that.
+
+---
+
+## v7.0 — "Multiplayer" (target: Q3 2026)
+
+The theme is *plurality*. v6 made the brain smart; v7 makes it social.
+
+### 🟥 Tier-S (no v7 without these)
+
+#### S1. CRDT real-time team sync (Yjs)
+Replace `team-sync` JSON-stomp protocol with **Yjs**. Two engineers on the same brain, concurrent edits, conflict-free. Figma-for-knowledge.
+- Yjs Y.Doc per project
+- WebSocket relay (default: free, self-hosted) + optional Cloudflare relay
+- Encrypted-at-rest via existing `brain-encryption.ts`
+- Backwards-compat shim for v6 team-sync clients
+
+#### S2. VS Code Marketplace launch
+The repo has `vscode-extension/` — it's not on the marketplace yet.
+- Inline memory highlights ("Agent X learned this from file Y")
+- Hover for entity provenance ("learned 2 weeks ago by Cursor, confirmed 3× by Claude")
+- One-click "ask brain about this function"
+- Codelens for files: "12 brain memories · 3 ADRs · 1 collision pending"
+- Status bar: brain health · forgetting curve · last sync
+- Publisher account: needs theihtisham@ Microsoft Partner Center setup
+
+#### S3. SWE-Bench-Verified public leaderboard
+v6.0.2 shipped the harness. v7 runs it for real.
+- 50-problem SWE-Bench-Verified subset
+- Brain off vs brain on for: Claude 4.7, GPT-5, DeepSeek V3, Llama 4
+- Published dashboard at `brain.dev/leaderboard` (domain TBD)
+- Numbers become the marketing — if brain delivers +20pp resolution, that's the headline
+
+#### S4. Brain Exchange seeded with 10 canonical packs
+The marketplace exists; the content doesn't. Pre-build and curate:
+- React 19 · Next.js 16 · Vue 4 · Svelte 6
+- Django 5 · Rails 8 · FastAPI · NestJS
+- Rust async (Tokio/axum) · Solidity · Unity 6
+- K8s ops · Postgres ops · Solana programs
+Each pack: 200-500 high-signal entities, signed, MIT-licensed.
+
+### 🟧 Tier-A (high impact)
+
+#### A1. Mobile companion (React Native + Expo)
+"Brain in your pocket."
+- Voice capture: hold-to-talk → transcribe → ingest as memory
+- Photo capture: snap a whiteboard → llava → memory entity
+- Dashboard read-only view
+- Notifications: "Your brain forgot X yesterday — restore?"
+- Syncs via team-sync (Yjs)
+
+#### A2. Multimodal v2 — real OCR + diagrams
+v6.0.2 stubs OCR. v7 wires tesseract-wasm (zero install) for clean text extraction. Plus diagram parsing (Mermaid/PlantUML detection).
+
+#### A3. Project-LoRA — actually trained
+v6.0.2 ships the pipeline. v7 actually trains + publishes:
+- 5 reference adapters on Hugging Face (one per canonical brain pack)
+- Per-user trained adapters via paid tier (compute pass-through, no margin)
+- Ollama Modelfile auto-generation
+- A/B vs base model in eval harness
+
+#### A4. Constitution v2 — auto-evolution
+v6.0.2 reads `constitution.md` statically. v7 lets the brain **propose new rules** when it sees repeated violations of patterns. User approves → rule added. Living constitution.
+
+#### A5. Time-travel UI in dashboard
+Brain Replay is currently CLI/SVG. v7 ships an interactive React panel: drag-scrub, play, slow-motion, jump-to-milestone, full-screen.
+
+### 🟨 Tier-B (high-leverage smaller bets)
+
+- **B1.** Brain Exchange CLI commands: `shadow-brain exchange install react@latest` → ready in 5 seconds
+- **B2.** Pricing tier signal: free → pro ($10/mo for team sync relay + LoRA training compute)
+- **B3.** Public homepage: `brain.dev` (or `shadow-brain.dev`) with live demos
+- **B4.** SDK in 3 langs: TypeScript (have it), Python, Rust — for embedding brain in any tool
+- **B5.** "Ask the Hive" public demo — drop in a code snippet on the homepage, see the brain answer live (with rate limit)
+- **B6.** Cursor / Cline / Aider plugins-on-their-marketplace (where they have one)
+- **B7.** GitHub Action: `shadow-brain/learn-from-pr@v1` — every merged PR ingests its lessons
+- **B8.** Brain garden v2 — actual knowledge-graph editor, not just a viz
+
+### 🟩 Quality of life (do anytime)
+
+- 30-second `demo` enhancements: add 3 themed sample projects (React, Django, Rust) the user can pick
+- Per-platform installers: Homebrew tap, scoop, winget
+- One-click migration from Cursor/Cline-stored prompts (if those tools expose any local memory)
+- Brain "health report" weekly email (opt-in)
+- "What did my brain learn today?" daily digest
+
+---
+
+## v7.5 — "Distributed" (target: Q4 2026)
+
+### Big swings
+
+- **Federated brains** — multiple teams' brains can selectively share concepts without merging fully. Cross-org learning without leaks.
+- **Constitution federation** — share rules across projects with diff-and-approve flow
+- **Real-time co-debugging** — two engineers + their brains + shared cursor on a bug, with hive-voice for decisions
+- **Brain forking** — `shadow-brain fork --from theihtisham/react-pack` like GitHub for brains
+- **Brain pull requests** — propose a change to a public brain, peer-reviewed
+
+---
+
+## v8.0 — "Self-Aware" (target: 2027)
+
+The brain becomes meta-cognitive.
+
+- **Self-tuning forgetting curve** — brain decides what to keep based on observed agent behavior, not heuristics
+- **Brain self-debugging** — brain detects its own degraded recall and proposes interventions
+- **Cross-brain federated learning** — multi-team adapters fine-tuned across consenting brains, privacy-preserving (DP-SGD or LoRA federation)
+- **Predictive memory** — brain pre-fetches likely-needed memories *before* the agent asks, based on session trajectory
+- **Brain handoff to humans** — handoff briefing generator: when a human takes over from an agent, get a one-page "what the agent thinks it knows + what it's uncertain about"
+
+---
+
+## What we will NOT build
+
+Explicit anti-list. Saves time arguing.
+
+- **Hosted-only SaaS shell** — defeats the local-first thesis. Always local-first; cloud is a relay, not a brain.
+- **Closed core, open shell** — the brain stays MIT. Always.
+- **LLM provider lock-in** — must work with Ollama / vLLM / any OpenAI-compat / Anthropic API equally.
+- **Replacing the agent** — Shadow Brain is *for* agents, not a competing agent. Hermes-Devin-AutoGen territory is theirs.
+- **Surveillance features** — no telemetry. No "anonymous usage data." Ever.
+
+---
+
+## How to push back on this roadmap
+
+This document changes. File an issue at `github.com/theihtisham/agent-shadow-brain/issues` with:
+- The item you disagree with
+- What you'd do instead
+- Why (with evidence — your team's experience, paper citation, etc.)
+
+Strongest arguments win. The author reserves the right to be wrong publicly.

package/docs/SHARING.md

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

package/docs/SHOWCASE.md

@@ -0,0 +1,87 @@
+# Workspace showcase
+
+The images show the 7.1.4 workspace with synthetic projects, memory records, reviews, and links. The Project Kit images use a separate persistent synthetic project. The live views use scripted local MCP calls. Displayed phases come from explicit reports, and durations come from measured calls in that demo.
+
+```bash
+shadow-brain demo workspace --port 0
+```
+
+Open the printed **Workspace** or **Live view** address. Use `--no-activity` for a fixed initial journal snapshot.
+
+## Project Kit
+
+In a project-local workspace, inspect observed stack markers and declared checks. Save a knowledge record and use it when drafting a skill for the selected client.
+
+![Project Kit showing observed stack evidence and local knowledge controls](assets/7.1.4-project-kit.png)
+
+Review the generated `SKILL.md` and its destination before applying it. The preview includes the user-supplied requirement and available checks.
+
+![Generated project skill preview with the target path and Markdown](assets/7.1.4-project-skill-preview.png)
+
+### Reported memory outcomes
+
+Record an observed result with a task, rating, reason, and optional references. The saved card shows the reporter and gives the user a way to remove the report. The switch controls whether later adaptive retrieval can use the reports.
+
+![Project Kit with a user-reported useful outcome and an influence toggle](assets/7.1.4-learning.png)
+
+The next matching task shows the report's signed contribution alongside the other ranking signals.
+
+![Context Lab showing a positive Project task feedback contribution and user attribution](assets/7.1.4-outcome-ranking.png)
+
+## Overview and attention queue
+
+Choose the project scope, review source coverage, and open a record from the attention queue. The queue flags conditions that merit inspection, including contested records and missing references.
+
+![Overview and the project memory attention queue](assets/7.1.4-overview.png)
+
+## Context Lab
+
+Assemble a brief, check its estimated tokens and rendered characters, then expand a candidate to see matched fields, ranking contributions, or a recorded link path.
+
+![Context Lab with task settings, brief metrics, and retrieval stages](assets/7.1.4-context-lab.png)
+
+### Compare profiles
+
+Compare the same task and scope with Adaptive and Legacy. The result lists which memories each profile adds and shows their estimated usage.
+
+![Adaptive and legacy comparison for the same task](assets/7.1.4-comparison.png)
+
+## Memory review and graph
+
+Inspect a saved record, its recorded references, and manual review controls. A review change is recorded in revision history.
+
+![Memory inspector with saved content, references, and review controls](assets/7.1.4-memory-review.png)
+
+Select an edge or focus the recorded relationships around one memory. The workspace distinguishes these relations from project membership and recording-agent links.
+
+![Focused graph showing recorded memory links and the inspector](assets/7.1.4-graph.png)
+
+## Integrations and features
+
+Read the documented capabilities and generate a setup example for the client. A project skill-file check and a live client handshake provide different evidence.
+
+![Integration cards and local diagnostics](assets/7.1.4-integrations.png)
+
+Choose when context, session briefings, and activity are available. The workspace keeps activity visibility and journal recording as separate controls.
+
+![The five runtime feature controls](assets/7.1.4-features.png)
+
+## Live operations and recorded replay
+
+Select a session or event to inspect the available history. The session network, timeline, and charts distinguish measured tool activity from explicit host reports.
+
+![Live operations with the session network and measured timing](assets/7.1.4-live.png)
+
+Replay navigates the loaded journal slice. Move to an event with the slider or step controls and return to the live stream when finished.
+
+![Journal replay controls over recorded events](assets/7.1.4-replay.png)
+
+![Animated capture of scripted local MCP activity and replay](assets/live-v7.1.4.gif)
+
+## Mobile layout
+
+Use the workspace on a narrow viewport to inspect the same saved records and context.
+
+![Workspace at a mobile viewport](assets/7.1.4-mobile.png)
+
+[Project Kit guide](PROJECT_KIT.md) · [Context Lab guide](CONTEXT_LAB.md) · [Workspace guide](WORKSPACE.md) · [Client integrations](INTEGRATIONS.md)

package/docs/STATS.md

@@ -0,0 +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/docs/TROUBLESHOOTING.md

@@ -0,0 +1,42 @@
+# Troubleshooting
+
+## The Hub says Workspace unavailable
+
+Keep the launcher running and open the current URL. If an older tab points to a stopped server, start the same project on the same port and refresh. A port of `0` can change each time.
+
+```bash
+cd your-project
+shadow-brain project workspace . --port 62595
+```
+
+Open `http://127.0.0.1:62595/hub`. The status endpoint at `/api/workspace/status` reports the process instance, workspace mode, project scope, and storage health. A reachable server can report a storage error separately. Resolve the storage error before making changes and retain the existing project files. If the port is already in use, check the existing launcher or start on a free port and use the new address.
+
+## The installed version differs from this guide
+
+This guide describes the 7.1.4 build. It requires Node.js 22.13+ in the 22.x line, 24.x, or 26+.
+
+```bash
+node --version
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+```
+
+If the command still reports the previous version, locate it with `Get-Command shadow-brain -All` in PowerShell or `command -v shadow-brain` in your shell. Restart the launcher after changing versions. A browser refresh alone continues using the old process.
+
+## The graph or journal is empty
+
+Check the selected project. Save a knowledge record or approve a PDF page to create a graph record. Connect a host using the recipe generated from the same project directory. In **Setup**, enable **Live dashboard activity** and **Record agent activity**. Ask the host to call `project_inspect` or `context_pack`, then look for the event. A reachable workspace and installed skill files are independent of host tool activity.
+
+## A feature setting or claim changed elsewhere
+
+Refresh to read the current revision before retrying. For a task claim, check its owner and lease. After a network failure, retry the same input to reuse the operation key. The work room and journal use different stores and can be inspected independently.
+
+## A PDF page has no text
+
+Image-only pages require OCR. The current Hub extracts a text layer and labels missing text. Upload a text-searchable PDF or save a verified excerpt as explicit project knowledge with its reference.
+
+## A context pack is empty or shorter than expected
+
+Check that the selected project contains relevant active memories, the context feature is enabled, and the token budget allows an excerpt. Try specific project terms. Context estimates describe the rendered pack. Model usage stays unavailable when the host supplies no usage receipts.
+
+[Quickstart](QUICKSTART.md) · [Workspace guide](WORKSPACE.md) · [Integrations](INTEGRATIONS.md)