@theihtisham/agent-shadow-brain 7.2.0 → 7.22.1

package/docs/launch/RELEASE_CHECKLIST_v7.0.0.md

@@ -1,24 +1,24 @@
-# 7.0.0 release checklist
-
-## Build and behavior
-
-- Confirm package.json, lockfile root, CLI, update checker, MCP metadata, dashboard, README, and release notes agree on 7.0.0.
-- Run `npm ci --ignore-scripts` from a clean checkout, then `npm run verify` and `npm run lint`.
-- Verify independent-process writes survive, queued success follows persistence, failed changes remain retryable, external deletions are preserved, and invalid stores remain byte-for-byte unchanged.
-- Verify unrelated agent notes cannot boost corroboration and every score is finite and explained.
-- Run `npm audit --audit-level=high`; record counts with the validation date.
-- Run `npm run test:package`; it packs the build, installs into a fresh temporary consumer, imports the public API, tests both new CLI commands, and verifies configuration isolation.
-
-## Publish the reviewed artifact
-
-- Keep the original 6.3.0 tarball and exact source commit available for rollback comparison.
-- Review `npm pack --dry-run --json` and allowlisted contents. Exclude personal state, node_modules, tests, temporary outputs, and configuration files.
-- Commit the reviewed source and lockfile; push without rewriting existing remote history.
-- Pack once, compute SHA-512/integrity, and publish that exact tarball with `npm publish <tarball> --access public --ignore-scripts` after local npm login by its owner.
-- If npm requests browser authentication or a second factor, the user completes it directly. Never put authentication material into scripts, output, or chat.
-- Verify registry 7.0.0 and `latest`, package integrity, and a fresh downloaded tarball. Publish the matching GitHub tag/release and attach the verified package.
-- Confirm remote CI separately. Do not describe unrun OS/runtime combinations as tested.
-
-## Rollback
-
-Use the preserved pre-upgrade store backup and install the previous package version if required. Stop all writers before restoring data. Published npm versions cannot be overwritten; release a corrective patch rather than silently replacing 7.0.0. Do not unpublish or move the latest tag without an explicit rollback decision.
+# 7.0.0 release checklist
+
+## Build and behavior
+
+- Confirm package.json, lockfile root, CLI, update checker, MCP metadata, dashboard, README, and release notes agree on 7.0.0.
+- Run `npm ci --ignore-scripts` from a clean checkout, then `npm run verify` and `npm run lint`.
+- Verify independent-process writes survive, queued success follows persistence, failed changes remain retryable, external deletions are preserved, and invalid stores remain byte-for-byte unchanged.
+- Verify unrelated agent notes cannot boost corroboration and every score is finite and explained.
+- Run `npm audit --audit-level=high`; record counts with the validation date.
+- Run `npm run test:package`; it packs the build, installs into a fresh temporary consumer, imports the public API, tests both new CLI commands, and verifies configuration isolation.
+
+## Publish the reviewed artifact
+
+- Keep the original 6.3.0 tarball and exact source commit available for rollback comparison.
+- Review `npm pack --dry-run --json` and allowlisted contents. Exclude personal state, node_modules, tests, temporary outputs, and configuration files.
+- Commit the reviewed source and lockfile; push without rewriting existing remote history.
+- Pack once, compute SHA-512/integrity, and publish that exact tarball with `npm publish <tarball> --access public --ignore-scripts` after local npm login by its owner.
+- If npm requests browser authentication or a second factor, the user completes it directly. Never put authentication material into scripts, output, or chat.
+- Verify registry 7.0.0 and `latest`, package integrity, and a fresh downloaded tarball. Publish the matching GitHub tag/release and attach the verified package.
+- Confirm remote CI separately. Do not describe unrun OS/runtime combinations as tested.
+
+## Rollback
+
+Use the preserved pre-upgrade store backup and install the previous package version if required. Stop all writers before restoring data. Published npm versions cannot be overwritten; release a corrective patch rather than silently replacing 7.0.0. Do not unpublish or move the latest tag without an explicit rollback decision.

package/docs/launch/RELEASE_NOTES_v7.0.0.md

@@ -1,44 +1,44 @@
-# Agent Shadow Brain 7.0.0
-
-Release date: 2026-11-11. Development used Astra for planning/review and GPT-6.1 SoL for core implementation. These are development roles, not newly bundled AI model services.
-
-## What changed
-
-Concurrent agents now serialize memory commits and merge their pending additions, access changes, and registrations with the latest valid disk snapshot. Successful queued-write acknowledgements follow persistence. Failed changes remain pending for retry. Corrupt or future-schema stores produce explicit errors while preserving the original bytes.
-
-Scored recall ranks the full matching pool, reports matched keywords and supporting agent identities, uses creation-age recency, and handles malformed numeric values without emitting NaN. Corroboration requires matching normalized content in the same project and category. Repeated text from different agent identities is a heuristic; it does not establish independent fact checking.
-
-New CLI commands:
-
-```sh
-shadow-brain storage-health --json
-shadow-brain storage-health --db ./global.json --json
-shadow-brain recall-explain "release verification" --limit 5
-```
-
-The MCP `global_storage_health` tool exposes the active process's pending operations and latest storage error without starting or flushing a store. Existing `global_recall_scored` results include explanations. The library entry point exports GlobalBrain and associated types.
-
-Installation no longer runs automatic agent setup. CLI help, version, storage-health, and recall-explain do not load provider settings. Dashboard activity rows escape memory text. Diagnostic output no longer prints key fragments. Dependencies are updated and promotional automation is manual-only.
-
-## Compatibility and migration
-
-- Supported runtimes: Node 22.12+ within 22.x, 24.x, or 26+.
-- Back up the store and stop older writers before upgrade. The new protocol cannot coordinate with an old writer that ignores its lock.
-- Store schema remains version 1. Invalid stores must be repaired or restored explicitly; automatic reset is removed.
-- `writeSync` stages an in-memory change. Use `await sync()` for persistence. A queued `write()` resolves after synchronization. A false result means queue rejection or failed persistence; accepted failed operations remain retryable.
-- Recalls use the current process snapshot; a sync refreshes external changes. There is no instantaneous cross-process notification guarantee.
-- Lock waits are bounded (default five seconds, configurable with `lockTimeoutMs`). Locks are never removed merely because they are old. After an interrupted process, inspect the writer and store before manually removing an abandoned `.lock` file.
-- Atomic replacement protects against partial JSON visibility. This release does not claim power-loss durability on every filesystem or safe coordination on all network filesystems.
-- Scores are heuristic rankings. Revisit application-specific `minConfidence` thresholds.
-- New health timestamps refer to the current process, not a persisted lifetime history.
-- Dependency major upgrades can affect applications importing re-exported Zod APIs; consult the upstream Zod 4 and simple-git 4 migration notes.
-
-## Source provenance
-
-The original repository URL returned 404 during this upgrade. The source was recovered from public fork `shadrackohemeng/agent-shadow-brain` at commit `bec756e19647a11cad570f8ae3c363792de84856`, exactly matching npm 6.3.0's `gitHead`. The downloaded 6.3.0 tarball is retained separately as the comparison baseline. Original MIT licensing and history are preserved.
-
-## Validation
-
-The release gate requires type-check/build, full tests, cross-process storage regressions, npm audit, fresh-consumer tarball installation, CLI/library smoke checks, package-content review, and Astra review. Remote CI results and publication status are recorded separately; prepared artifacts are not evidence of publication.
-
-Upstream references: [Vitest migration](https://main.vitest.dev/guide/migration/), [simple-git changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md), [Zod migration](https://zod.dev/v4/changelog).
+# Agent Shadow Brain 7.0.0
+
+Release date: 2026-11-11. Development used Astra for planning/review and GPT-6.1 SoL for core implementation. These are development roles, not newly bundled AI model services.
+
+## What changed
+
+Concurrent agents now serialize memory commits and merge their pending additions, access changes, and registrations with the latest valid disk snapshot. Successful queued-write acknowledgements follow persistence. Failed changes remain pending for retry. Corrupt or future-schema stores produce explicit errors while preserving the original bytes.
+
+Scored recall ranks the full matching pool, reports matched keywords and supporting agent identities, uses creation-age recency, and handles malformed numeric values without emitting NaN. Corroboration requires matching normalized content in the same project and category. Repeated text from different agent identities is a heuristic; it does not establish independent fact checking.
+
+New CLI commands:
+
+```sh
+shadow-brain storage-health --json
+shadow-brain storage-health --db ./global.json --json
+shadow-brain recall-explain "release verification" --limit 5
+```
+
+The MCP `global_storage_health` tool exposes the active process's pending operations and latest storage error without starting or flushing a store. Existing `global_recall_scored` results include explanations. The library entry point exports GlobalBrain and associated types.
+
+Installation no longer runs automatic agent setup. CLI help, version, storage-health, and recall-explain do not load provider settings. Dashboard activity rows escape memory text. Diagnostic output no longer prints key fragments. Dependencies are updated and promotional automation is manual-only.
+
+## Compatibility and migration
+
+- Supported runtimes: Node 22.12+ within 22.x, 24.x, or 26+.
+- Back up the store and stop older writers before upgrade. The new protocol cannot coordinate with an old writer that ignores its lock.
+- Store schema remains version 1. Invalid stores must be repaired or restored explicitly; automatic reset is removed.
+- `writeSync` stages an in-memory change. Use `await sync()` for persistence. A queued `write()` resolves after synchronization. A false result means queue rejection or failed persistence; accepted failed operations remain retryable.
+- Recalls use the current process snapshot; a sync refreshes external changes. There is no instantaneous cross-process notification guarantee.
+- Lock waits are bounded (default five seconds, configurable with `lockTimeoutMs`). Locks are never removed merely because they are old. After an interrupted process, inspect the writer and store before manually removing an abandoned `.lock` file.
+- Atomic replacement protects against partial JSON visibility. This release does not claim power-loss durability on every filesystem or safe coordination on all network filesystems.
+- Scores are heuristic rankings. Revisit application-specific `minConfidence` thresholds.
+- New health timestamps refer to the current process, not a persisted lifetime history.
+- Dependency major upgrades can affect applications importing re-exported Zod APIs; consult the upstream Zod 4 and simple-git 4 migration notes.
+
+## Source provenance
+
+The original repository URL returned 404 during this upgrade. The source was recovered from public fork `shadrackohemeng/agent-shadow-brain` at commit `bec756e19647a11cad570f8ae3c363792de84856`, exactly matching npm 6.3.0's `gitHead`. The downloaded 6.3.0 tarball is retained separately as the comparison baseline. Original MIT licensing and history are preserved.
+
+## Validation
+
+The release gate requires type-check/build, full tests, cross-process storage regressions, npm audit, fresh-consumer tarball installation, CLI/library smoke checks, package-content review, and Astra review. Remote CI results and publication status are recorded separately; prepared artifacts are not evidence of publication.
+
+Upstream references: [Vitest migration](https://main.vitest.dev/guide/migration/), [simple-git changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md), [Zod migration](https://zod.dev/v4/changelog).

package/docs/launch/RELEASE_NOTES_v7.1.0.md

@@ -1,32 +1,32 @@
-# Agent Shadow Brain 7.1.0
-
-This release adds focused task guidance and project skill installation on top of 7.0.0's durable memory and explained recall.
-
-## Changes
-
-- Six bundled skills: workflow selection, implementation, debugging, review, research, and release.
-- Project skill layouts for Codex, Claude Code, OpenCode, and DeepSeek Harness; portable files for other compatible clients.
-- Preview-first installation that preserves project instruction text, detects local edits, validates destinations and stale plans, records ownership, and backs up managed updates.
-- CLI skill catalog/install commands and advisory request analysis with explicit overrides.
-- Read-only MCP guidance tools and public library functions/types.
-
-The intended workflow is understand, plan when useful, execute authorized work, and verify. A small question stays a small answer. Plan-only, diagnosis-only, and review-only instructions keep their scope. No provider/model setup, credentials, new runtime dependencies, or global configuration changes are required.
-
-## Start
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@7.1.0
-# Run in the project root:
-shadow-brain skills install . --target codex
-shadow-brain skills install . --target codex --apply
-```
-
-Choose `claude-code`, `opencode`, `deepseek-harness`, `portable`, or `all` instead as appropriate. See the [integration guide](../WORKFLOW_INTEGRATION.md) for host requirements, updates, conflicts, and examples.
-
-## Verification and limits
-
-The release gate covers TypeScript, regression tests, installer preservation/failure scenarios, representative task-routing scenarios, skill frontmatter validation, and an installed npm tarball in a clean consumer project. CI runs on Windows and Linux with Node 22, 24, and 26. Final run counts and publication evidence are recorded in the release report.
-
-The router is a deterministic English-language heuristic; host interpretation and explicit options handle ambiguity. The package provides guidance, not autonomous task execution or authorization. Documented host layouts and automated installation tests do not prove that a running host discovered or followed a skill. DeepSeek Harness needs its skill/context plugins enabled.
-
-This is an additive 7.x release. No memory-store schema migration is introduced; retain the 7.0.0 upgrade guidance when coming from 6.x.
+# Agent Shadow Brain 7.1.0
+
+This release adds focused task guidance and project skill installation on top of 7.0.0's durable memory and explained recall.
+
+## Changes
+
+- Six bundled skills: workflow selection, implementation, debugging, review, research, and release.
+- Project skill layouts for Codex, Claude Code, OpenCode, and DeepSeek Harness; portable files for other compatible clients.
+- Preview-first installation that preserves project instruction text, detects local edits, validates destinations and stale plans, records ownership, and backs up managed updates.
+- CLI skill catalog/install commands and advisory request analysis with explicit overrides.
+- Read-only MCP guidance tools and public library functions/types.
+
+The intended workflow is understand, plan when useful, execute authorized work, and verify. A small question stays a small answer. Plan-only, diagnosis-only, and review-only instructions keep their scope. No provider/model setup, credentials, new runtime dependencies, or global configuration changes are required.
+
+## Start
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.1.0
+# Run in the project root:
+shadow-brain skills install . --target codex
+shadow-brain skills install . --target codex --apply
+```
+
+Choose `claude-code`, `opencode`, `deepseek-harness`, `portable`, or `all` instead as appropriate. See the [integration guide](../WORKFLOW_INTEGRATION.md) for host requirements, updates, conflicts, and examples.
+
+## Verification and limits
+
+The release gate covers TypeScript, regression tests, installer preservation/failure scenarios, representative task-routing scenarios, skill frontmatter validation, and an installed npm tarball in a clean consumer project. CI runs on Windows and Linux with Node 22, 24, and 26. Final run counts and publication evidence are recorded in the release report.
+
+The router is a deterministic English-language heuristic; host interpretation and explicit options handle ambiguity. The package provides guidance, not autonomous task execution or authorization. Documented host layouts and automated installation tests do not prove that a running host discovered or followed a skill. DeepSeek Harness needs its skill/context plugins enabled.
+
+This is an additive 7.x release. No memory-store schema migration is introduced; retain the 7.0.0 upgrade guidance when coming from 6.x.

package/docs/launch/RELEASE_NOTES_v7.1.3.md

@@ -0,0 +1,40 @@
+# Agent Shadow Brain 7.1.3
+
+Version 7.1.3 connects memory review, the workspace graph, and the context handed to an agent. The new live operations portal shows recorded agent activity and tool timing.
+
+## Live operations
+
+Open `/live` on the dashboard address for the session list, activity network, charts, and event timeline. Measured activity comes from the local MCP service. Hosts can explicitly report task phases and tool spans. The portal labels the two sources and uses matched, measured calls for timing metrics.
+
+The shared local journal keeps the latest 500 metadata events. It tracks sequence and journal identity so readers can continue from a cursor and detect gaps or a restarted journal. `activityRecording` controls new records and `liveActivity` controls visibility. Both are enabled by default and can be changed with the other three runtime controls. Use `activity report` to send a host report and `activity tail` to inspect the journal.
+
+## Memory review and relations
+
+Open a memory in the workspace to see its content, recorded references, current review, and history. Set its state to active, archived, or contested. Record a same-project link of type related, supports, contradicts, or supersedes. Supersession links point from the replacement to the older memory.
+
+Context assembly filters inactive memories before ranking, preserves relevant relation and source provenance when collapsing duplicates, and labels recorded contradictions. If a replacement disappears, its older memory stays superseded until you remove the relation. Manual reviews and links record decisions to inspect against the underlying evidence.
+
+The `curate show`, `curate review`, `curate link`, and `curate unlink` commands use the same annotation store as the workspace. The store validates project identities, revisions, duplicate relations, and supersession cycles. It keeps an audit trail alongside the existing memory store.
+
+## Connect a client
+
+The workspace's Integrations view shows project skill-file presence, supported client capabilities, and local runtime and storage checks. Codex, Claude Code, OpenCode, and DeepSeek Harness can use their documented project skill layouts. Host-side discovery depends on client configuration.
+
+The standalone MCP service now runs over standard input and output.
+
+```bash
+shadow-brain mcp --stdio
+```
+
+Configure this command as the executable and arguments in a compatible client. The service exposes nine read-only memory, context, and workflow tools plus the explicit `activity_report` write tool. Activity recording uses a separate journal from the memory store. DeepSeek Harness needs its MCP client and filesystem skill plugins enabled. See the [workspace guide](../WORKSPACE.md) and [skill integration guide](../WORKFLOW_INTEGRATION.md).
+
+## Upgrade
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.1.3
+shadow-brain dash . --no-analysis
+```
+
+Existing memories retain schema version 1. Keep `global.json` and the separate `memory-annotations.json` when backing up your memory and review state. Follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md) if you are upgrading from 6.x.
+
+This upgrade uses the maintainer-requested version **7.1.3**, published after 7.2.0. It is assigned the npm `latest` tag, but semver update tools may still prefer 7.2.0. Use the exact install command above.

package/docs/launch/RELEASE_NOTES_v7.1.4.md

@@ -0,0 +1,30 @@
+# Agent Shadow Brain 7.1.4
+
+The local Brain Hub brings actual saved memory, project documents, collaboration, and the activity journal into one control room. Node.js 22.13+ in the 22.x line, 24.x, or 26+ is required.
+
+## Install and open
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@latest
+shadow-brain --version
+shadow-brain project workspace . --port 62595
+```
+
+Check for `7.1.4`, then open [the project Brain Hub](http://127.0.0.1:62595/hub). Keep the local process running. Reuse the project directory and port after a restart. The classic workspace is still at `/workspace`; detailed activity is at `/live`. [Quickstart](../QUICKSTART.md)
+
+## What changed
+
+- **Control room.** The graph loads actual project, agent, and memory relationships, with a keyboard-accessible node list and record inspector. The local process reports its own health. The page retries when it loses the server, and it reopens the scope when the process instance changes.
+- **PDF intake.** Project PDFs have bounded extraction, stored fingerprints, and page-level review. Approved pages become cited project memory. Image-only pages surface the need for OCR.
+- **Collaboration.** Project rooms contain proposals, replies, leased task claims, artifacts with recorded digests, acknowledgements, and outcomes. The browser and configured project-local MCP clients share these records.
+- **Context and skills.** Build and compare scoped packs, copy the rendered Markdown, save project knowledge, and preview and apply host-specific project skills. The classic Context Lab retains detailed retrieval explanations and memory curation.
+- **Learning.** A recorded outcome can become a candidate. The operator records evaluation and explicitly promotes an eligible lesson. Rollback archives the promoted memory’s retrieval influence.
+- **Setup and usage.** Persist feature changes and copy native client recipes. The Hub separates measured tool activity from explicit reports. Provider usage receipts, model identity, and cost are unavailable without host evidence. Context pack tokens are estimates.
+
+![The running control room with an isolated checkout fixture](../assets/7.1.4-hub-control-room.png)
+
+## Verification scope
+
+Browser checks used isolated fixture data with actual local stores and MCP calls. They exercised graph selection, context copy, PDF review, feature changes, shared work, durable retry, learning rollback, and same-port reconnect. Host file detection and local tool exchange are separate from native host confirmation. The release does not include autonomous model execution or model training.
+
+[Visual guide](../VISUAL_GUIDE_v7.1.4.md) · [Workflow integration](../WORKFLOW_INTEGRATION.md) · [Changelog](../../CHANGELOG.md)

package/docs/launch/RELEASE_NOTES_v7.2.0.md

@@ -1,24 +1,24 @@
-# Agent Shadow Brain 7.2.0
-
-Version 7.2 makes it easier to see what agents have saved and choose what to hand to a new session. The default local workspace has five views for overview, memory search, the project and agent graph, context assembly, and feature controls. The previous dashboard remains available at `/advanced`.
-
-## What changed
-
-- Context packs rank memories for the selected project and task, collapse exact duplicates, retain recorded source provenance, and explain what fits the rendered budget. Cross-project context requires both a setting and explicit opt-in.
-- Session briefings use the same assembler. Cached briefings follow the current task and feature settings. Disabling automatic briefings suppresses both new and cached output.
-- Four persistent switches control context packs, cross-project access within context packs, automatic briefings, and dashboard activity. The settings store validates updates, detects revision conflicts, and replaces saved settings atomically.
-- The CLI adds `context-pack` and `features list|set`. MCP clients can call `context_pack` and `feature_flags`. Library consumers can import the assembler and settings store directly.
-- The README includes a conceptual memory-flow illustration and screenshots from the running workspace with synthetic data.
-
-## Start the workspace
-
-```bash
-npm install -g @theihtisham/agent-shadow-brain@7.2.0
-shadow-brain dash . --no-analysis
-```
-
-From a second terminal, run `shadow-brain context-pack "import retry behavior" --project . --token-budget 1200` to inspect what an agent would receive for that task.
-
-Memory storage keeps schema version 1. The six bundled skills and the existing skill install workflow remain available. If you are coming from 6.x, follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md).
-
-[Workspace guide](../WORKSPACE.md) · [Skill integration guide](../WORKFLOW_INTEGRATION.md)
+# Agent Shadow Brain 7.2.0
+
+Version 7.2 makes it easier to see what agents have saved and choose what to hand to a new session. The default local workspace has five views for overview, memory search, the project and agent graph, context assembly, and feature controls. The previous dashboard remains available at `/advanced`.
+
+## What changed
+
+- Context packs rank memories for the selected project and task, collapse exact duplicates, retain recorded source provenance, and explain what fits the rendered budget. Cross-project context requires both a setting and explicit opt-in.
+- Session briefings use the same assembler. Cached briefings follow the current task and feature settings. Disabling automatic briefings suppresses both new and cached output.
+- Four persistent switches control context packs, cross-project access within context packs, automatic briefings, and dashboard activity. The settings store validates updates, detects revision conflicts, and replaces saved settings atomically.
+- The CLI adds `context-pack` and `features list|set`. MCP clients can call `context_pack` and `feature_flags`. Library consumers can import the assembler and settings store directly.
+- The README includes a conceptual memory-flow illustration and screenshots from the running workspace with synthetic data.
+
+## Start the workspace
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.2.0
+shadow-brain dash . --no-analysis
+```
+
+From a second terminal, run `shadow-brain context-pack "import retry behavior" --project . --token-budget 1200` to inspect what an agent would receive for that task.
+
+Memory storage keeps schema version 1. The six bundled skills and the existing skill install workflow remain available. If you are coming from 6.x, follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md).
+
+[Workspace guide](../WORKSPACE.md) · [Skill integration guide](../WORKFLOW_INTEGRATION.md)

package/docs/launch/RELEASE_NOTES_v7.22.0.md

@@ -0,0 +1,53 @@
+# Agent Shadow Brain 7.22.0
+
+Release date: 2026-11-14. See the [verification record](RELEASE_ACCEPTANCE_v7.22.0.md) for tested behavior and integration boundaries.
+
+This release makes project knowledge easier to add, trace, share and correct. Save ordinary notes directly with **Add to memory**, or review longer notes and optional document imports before sharing them. Pending and rejected review items remain outside shared retrieval.
+
+## Knowledge and learning
+
+- Paste a short fact or paragraph and save it with one click, retaining its original evidence and retry identity. Longer notes offer section review, correction and selective approval.
+- Import text PDFs, knowledge JSON and simple transcript JSON. The source review keeps speaker attribution, original text, exact page or item locator, fingerprint and approved corrections.
+- Inspect source evidence through the portal or the read-only `memory_evidence` MCP tool.
+- Rate a retrieved memory for a task. Bounded feedback affects matching future queries; users can pause or remove this influence.
+- Follow a lesson back to its recorded outcome and reported comparison. Promotion and rollback remain explicit.
+
+## Shared memory and handoffs
+
+- Already-running independent project MCP servers refresh their read view before ordinary recall.
+- Archived, contested and superseded records are excluded before project recall ranking. Audit views retain the historical record.
+- `hub_artifact_read` retrieves the saved immutable UTF-8 artifact by room, artifact ID and SHA-256. It does not reread a changed workspace file.
+- Duplicate collapse preserves conservative feedback attribution, and a supplied query without searchable terms no longer falls back to unrelated recent memories.
+
+## Portal and usage
+
+- A tool activity panel uses locally bundled integration icons and accessible detail controls for reported sessions, models, coordination roles and latest observed actions. Fresh event indicators respect pause and reduced-motion settings.
+- Initialized project MCP transports report bounded presence leases, with ten-second renewals, thirty-second expiry and clean-disconnect removal. Presence refreshes independently of the graph and never substitutes for evidence of model execution.
+- Optional usage receipts accept a bounded `reasoningEffort` label. It remains host-reported, with unknown effort omitted; existing receipts keep their retry identity.
+- The brain-shaped graph lays out actual stored records, with depth cues, quieter membership links, recorded relationship filters, search, pan, zoom and reduced motion.
+- Observed client exchanges remain visible even when the memory graph is empty. Replay does not silently switch to a newer event after the selected record expires.
+- Context shows candidates, selection reasons, exclusions, source navigation and the actual added/removed/shared records in a comparison.
+- Cooperating hosts can send optional `usage_report` receipts. Input and output totals remain distinct from cached and reasoning subsets. Missing counts remain unknown and receipts stay labelled host-reported.
+- Legacy model routes no longer discover host configuration files automatically, expose saved credential fields in JSON, or claim a successful provider test without testing it.
+
+## Compatibility and limits
+
+Existing project memory and ActivityJournal v1 remain compatible. New source and usage records live in separate project-local SQLite stores. No external database service or model download is required. Feature data is bounded and project scoped.
+
+Text organization is deterministic; it is not a separate model interpreting every paragraph. The connected agent reasons over the reviewed context it requests. Learning adapts stored memory and retrieval; it does not train model weights. Scanned PDFs need OCR, which is not included. Model reports do not establish billing or independently prove a proxy's upstream model. Native application connectivity requires that application's configuration and active use of the tools.
+
+## Conversation continuity
+
+Connected tools can register project sessions, report progress, save immutable checkpoints and continue another tool's checkpoint in a new agent-owned session. History is paged and bounded; old checkpoints keep their exact digest. Imported conversation snapshots preserve original IDs, available titles, workspace identity and source locators. A changed export becomes a linked snapshot rather than overwriting the original.
+
+The optional Codex history connection starts only after **Connect**. It uses the installed app-server's read interface, scopes the list to the current project, supports archived conversations and reads selected history in pages. Other supported tools use selected native exports. These interfaces do not reopen another application's native tab or transfer hidden model state.
+
+## Live updates and control
+
+The portal receives bounded pushed invalidations from local stores, with reconnect and polling fallback. Optional file activity reports safe project-relative file metadata; a filesystem event alone cannot identify the editing agent. Graph motion follows observed activity and can be paused.
+
+Project controls set tool participation, conversation sharing, coordination roles and context ceilings. Excluded conversations and their explicitly linked evidence are withheld from subsequent agent delivery, including inherited handoffs. Client labels are cooperative controls, not authenticated enterprise access control. Information already received by another process cannot be recalled.
+
+Project Kit skills with intact ownership receipts can be disabled, restored or removed through an exact preview. Edited and unmanaged files remain protected. Disabling a skill changes future file discovery; a host may need to reload to discard instructions already in its context.
+
+See the [research and acceptance plan](RESEARCH_AND_PLAN_v7.22.0.md), [source intake guide](../SOURCE_INTAKE.md), [sessions guide](../SESSIONS.md), and [visual guide](../VISUAL_GUIDE_v7.22.0.md).

package/docs/launch/RELEASE_NOTES_v7.22.1.md

@@ -0,0 +1,11 @@
+# Agent Shadow Brain 7.22.1
+
+This patch adds creator and repository links to the Brain Hub footer and public README, plus a live total-download badge. npm author metadata links to [Ihtisham on GitHub](https://github.com/theihtishaam).
+
+[View the source and star Agent Shadow Brain](https://github.com/theihtishaam/agents-brain).
+
+Memory, context, and agent behavior are unchanged. Install or update with:
+
+```sh
+npm install -g @theihtisham/agent-shadow-brain@latest
+```