@accelerationguy/accel 1.0.0

package/modules/momentum/README.md

@@ -0,0 +1,678 @@
+<div align="center">
+  <img src="terminal.svg" alt="Momentum terminal" width="740"/>
+</div>
+
+<div align="center">
+
+[![npm](https://img.shields.io/npm/v/@accel/momentum?color=00d8ff&label=npm&style=flat-square)](https://www.npmjs.com/package/@accel/momentum)
+[![Node](https://img.shields.io/badge/node-%3E%3D16.7.0-brightgreen?style=flat-square)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-8b5cf6?style=flat-square)](https://claude.ai/code)
+
+**Your AI builder operating system.**<br/>
+Turn Claude Code from a per-session tool into a workspace that remembers, maintains itself, and never goes stale.
+
+
+</div>
+
+---
+
+## Contents
+
+- [The Problem Every Claude Code User Hits](#the-problem-every-claude-code-user-hits)
+- [What Momentum Actually Does](#what-momentum-actually-does)
+- [How It Works](#how-it-works)
+- [Install](#install)
+- [Upgrading from v2](#upgrading-from-v2)
+- [What Gets Installed](#what-gets-installed)
+- [The Maintenance Cycle](#the-maintenance-cycle)
+- [Config Alignment](#config-alignment--claude-directory-audit)
+- [MCP Server](#mcp-server--claude-operates-on-your-data)
+- [Operator Profile](#operator-profile--who-you-are-always-in-context)
+- [PSMM — Session Intelligence](#per-session-meta-memory-psmm--session-intelligence)
+- [Mission Control Insights](#mission-control-insights--workspace-analytics)
+- [Multi-Project Workspaces — Momentum + Drive](#multi-project-workspaces--momentum--drive)
+- [Creating Custom Surfaces](#creating-custom-surfaces)
+- [How the Ecosystem Fits Together](#how-the-ecosystem-fits-together)
+- [Design Principles](#design-principles)
+- [Quick Start](#quick-start)
+
+---
+
+## Ecosystem
+
+Momentum is part of a broader Claude Code extension ecosystem:
+
+| System | What It Does | Link |
+|--------|-------------|------|
+| **Radar** | Multi-agent codebase auditing — diagnosis + controlled evolution | [GitHub](https://github.com/accelerationguy/radar) |
+| **Momentum** | Builder's Automated State Engine — workspace lifecycle, health tracking, drift prevention | You are here |
+| **Vector** | Context Augmentation & Reinforcement Layer — dynamic rules loaded JIT by intent | [GitHub](https://github.com/accelerationguy/vector) |
+| **Drive** | Project orchestration — Plan, Apply, Unify Loop | [GitHub](https://github.com/accelerationguy/drive) |
+| **Ignition** | Typed project incubator — guided ideation through graduation into buildable projects | [GitHub](https://github.com/accelerationguy/ignition) |
+| **Forge** | Skill builder — standardized syntax specs + guided workflows for Claude Code skills | [GitHub](https://github.com/accelerationguy/forge) |
+| **CC Strategic AI** | Skool community — courses, community, live support | [Skool](https://accelerationguy.com) |
+
+---
+
+## The Problem Every Claude Code User Hits
+
+You start a Claude Code session. Claude doesn't know:
+
+- What you're working on
+- What's blocked
+- What you worked on yesterday
+- What's overdue
+- Which projects need attention
+
+So you repeat yourself. Every. Single. Session.
+
+Maybe you've tried fixing this with a massive `CLAUDE.md` file, `@`-mentions pointing at markdown docs, or manual context dumps at session start. It works... until it doesn't. Files go stale. Your CLAUDE.md becomes a junk drawer. You forget to update things. Claude starts making decisions based on outdated information. And the bigger your workspace gets, the worse it breaks.
+
+**This is the duct tape phase.** Everyone goes through it. Momentum is what comes after.
+
+---
+
+## What Momentum Actually Does
+
+Momentum turns your Claude Code workspace into a managed operating system. Instead of scattered markdown files and manual context loading, you get:
+
+**Structured data that Claude reads automatically.** Your active projects, backlog items, client lists — anything you want Claude to passively know about — lives in structured JSON files. Lightweight hooks inject compact summaries into every session automatically. You never type "here's what I'm working on" again.
+
+**Health monitoring that catches drift before it hurts.** A drift score tracks how far your workspace state has drifted from reality. When things go stale, Momentum tells you. When grooming is overdue, Momentum tells you. You fix it with a guided maintenance cycle, not a weekend of cleanup.
+
+**A manifest that drives everything.** One config file (`workspace.json`) declares what your workspace contains, how each area should be maintained, and what projects are in play. Every command reads from it. Your workspace is self-describing.
+
+### What This Looks Like in Practice
+
+You open Claude Code. Before you type anything, Claude already knows:
+
+```xml
+<active-awareness items="5">
+[URGENT]
+- [ACT-001] Client Portal Launch (Blocked: API auth)
+  DUE: 2026-03-20
+[HIGH]
+- [ACT-002] Course Module 3 (In Progress)
+- [ACT-003] MCP Server Refactor (In Review)
+
+BEHAVIOR: PASSIVE AWARENESS ONLY.
+Do NOT proactively mention unless user asks or deadline < 24h.
+</active-awareness>
+```
+
+Claude doesn't nag. It doesn't start the session with "here are your tasks." But the moment you ask "what should I work on?" — the answer is instant and accurate. No file reading. No context window wasted. No stale data.
+
+---
+
+## How It Works
+
+### Data Surfaces — The Core Concept
+
+A "data surface" is just a structured JSON file paired with a hook that injects it into Claude's context. That's it.
+
+```
+JSON file (your data)  →  Hook (reads + summarizes)  →  Claude knows it
+```
+
+Momentum ships with five built-in surfaces:
+
+| Surface | What It Tracks |
+|---------|---------------|
+| **Active** | Current projects, tasks, blockers, deadlines, status |
+| **Backlog** | Future work, ideas, deferred items with review deadlines |
+| **Projects** | Unified project tracking with Drive integration, categories, revenue |
+| **Entities** | People and organizations — contacts, stakeholders, collaborators |
+| **State** | Workspace health — drift score, area statuses, groom tracking |
+
+But you can create surfaces for anything — clients, contacts, content pipelines, API keys, whatever persistent data you want Claude to passively know about. The `/momentum:surface create` command walks you through it: define a schema, pick an injection format, and Momentum generates the JSON file, the hook, and the wiring automatically.
+
+### The Manifest — One File Rules Everything
+
+`workspace.json` is the brain. It registers:
+
+- Every data surface and its schema
+- Every tracked area in your workspace (projects, tools, content, clients...)
+- Grooming schedules per area
+- Audit strategies per area type
+- Connected projects and their health status
+
+Every Momentum command reads from this manifest. You configure it once during setup, and the system maintains itself from there.
+
+### Hooks — The Glue
+
+Momentum uses Claude Code's [hook system](https://docs.anthropic.com/en/docs/claude-code/hooks) to inject context automatically. There are two types:
+
+**Every prompt** (`UserPromptSubmit`) — Fire on every message you send, keeping Claude's awareness current throughout the session:
+
+| Hook | What It Does |
+|------|-------------|
+| **Pulse check** | Calculates workspace drift score, warns if grooming is overdue |
+| **PSMM injector** | Re-injects important session moments (decisions, corrections, insights) into Claude's context so they don't get buried in a long session. [Details below.](#per-session-meta-memory-psmm--session-intelligence) |
+| **Operator** | Injects a compact identity summary from your operator profile — north star, values, vision — so Claude stays aligned with who you are and what you're building toward |
+| **Surface hooks** | One per data surface (active, backlog, or custom). Reads the JSON, outputs a compact summary so Claude passively knows the current state |
+
+**Session start** (`SessionStart`) — Runs once when a Claude Code session begins:
+
+| Hook | What It Does |
+|------|-------------|
+| **Drive project detection** | Scans your workspace for [Drive](https://github.com/accelerationguy/drive) project files (`.drive/drive.json`) and auto-registers new ones into `workspace.json`. Only needs to run once — your project list doesn't change mid-session. (More on Drive below.) |
+
+**On demand** — Invoked by specific commands, not auto-fired:
+
+| Hook | What It Does |
+|------|-------------|
+| **Apex insights** | Workspace analytics engine — velocity tracking, stall detection, blocking analysis, revenue exposure, dependency chains. Invoked by `/accel:insights`. |
+
+All hooks are lightweight Python — they read JSON files and output compact XML summaries. No network calls, no heavy dependencies, no noticeable latency. A hook that has nothing to report outputs nothing and exits silently.
+
+---
+
+## Install
+
+```bash
+npx @accel/momentum --global --workspace
+```
+
+One command. Two layers:
+
+- `--global` installs commands and the framework to `~/.claude` (shared across all your workspaces)
+- `--workspace` installs the data layer to `.accel/momentum/` in your current directory
+
+Then open Claude Code and run `/momentum:scaffold` to configure your workspace with a guided setup.
+
+```bash
+# Full install — most users start here
+npx @accel/momentum --global --workspace
+
+# Already installed globally? Wire up a new workspace
+npx @accel/momentum --workspace
+
+# Global only — set up workspaces later with /momentum:scaffold
+npx @accel/momentum --global
+```
+
+| Flag | What It Does |
+|------|-------------|
+| `--global` | Commands + framework to `~/.claude` (shared) |
+| `--workspace` | Data layer to `.accel/momentum/` in current directory |
+| `--local` | Commands to `./.claude` instead of global |
+| `--config-dir <path>` | Custom Claude config directory |
+| `--workspace-dir <path>` | Target a specific workspace path |
+
+### Upgrading from v2
+
+If you're upgrading from Momentum v2.x, the installer detects old artifacts and offers to archive them before proceeding. Nothing is deleted — everything moves to `.accel/momentum/_archive/upgrade-v3/` where you can recover it if needed.
+
+| What Gets Archived | Why |
+|-------------------|-----|
+| `.accel/momentum/vector-mcp/` | Vector MCP is no longer bundled with Momentum. Install [vector-core](https://github.com/accelerationguy/vector) separately for Vector MCP tools. |
+| `.claude/hooks/momentum-pulse-check.py`, `psmm-injector.py`, `satellite-detection.py` | Session hooks moved to `.accel/momentum/hooks/`. Old copies in `.claude/hooks/` cause double-fire. |
+| `.mcp.json` vector-mcp entry | Removed to prevent startup errors from missing server. |
+| `momentum-framework/templates/active-md.md`, `backlog-md.md`, `state-md.md` | Replaced by JSON templates. Scaffold no longer references these. |
+
+The upgrade prompt looks like this:
+```
+=== UPGRADE DETECTED ===
+Found 8 artifact(s) from a previous Momentum version:
+
+! .accel/momentum/vector-mcp/
+  Vector MCP no longer ships with Momentum — install vector-core separately
+! .claude/hooks/momentum-pulse-check.py
+  Hooks now live in .accel/momentum/hooks/ — duplicate here causes double-fire
+...
+
+These will be archived to: .accel/momentum/_archive/upgrade-v3/
+Nothing is deleted — you can recover from the archive.
+
+Archive these artifacts? [Y/n]:
+```
+
+Answering `n` skips cleanup and installs v3 alongside existing artifacts. You can clean up manually later.
+
+---
+
+## What Gets Installed
+
+```
+~/.claude/                              Shared across all workspaces
+├── commands/momentum/                      Slash commands (/momentum:pulse, /momentum:groom, etc.)
+├── skills/momentum/                        Skill entry point + package sources
+└── momentum-framework/
+    ├── tasks/                          How each command works (pulse, groom, audit...)
+    ├── templates/                      Schemas for workspace.json, surfaces
+    ├── context/                        Core principles
+    ├── frameworks/                     Audit strategies, config alignment, project registration
+    ├── utils/                          Scanner utilities (scan-claude-dirs.py)
+    └── hooks/                          All hook sources (for scaffold reference)
+
+.accel/momentum/                                  Per-workspace
+├── workspace.json                      The manifest — everything is registered here
+├── operator.json                       Operator profile — north star, values, vision, pitch
+├── data/
+│   ├── active.json                     Active work surface
+│   ├── backlog.json                    Backlog surface
+│   ├── projects.json                   Unified project tracking
+│   ├── entities.json                   People and organizations
+│   └── state.json                      Workspace health state
+├── hooks/
+│   ├── _template.py                    Hook template for creating new surfaces
+│   ├── active-hook.py                  Injects active work into Claude's context
+│   ├── backlog-hook.py                 Injects backlog into Claude's context
+│   ├── momentum-pulse-check.py             Drift score + groom reminders
+│   ├── psmm-injector.py                Session meta memory
+│   ├── satellite-detection.py          Drive project auto-discovery
+│   ├── operator.py                     Operator identity context
+│   └── mission-control-insights.py                Workspace analytics (on-demand)
+└── momentum-mcp/                           MCP server for surface + project operations
+```
+
+---
+
+## The Maintenance Cycle
+
+Most workspace management tools are set-and-forget. Momentum is designed around the reality that workspaces are living things that drift.
+
+### Pulse — Session Start Health Check
+
+`/momentum:pulse` runs automatically via hook. It reads your manifest, checks filesystem timestamps, and calculates a drift score:
+
+| Drift Score | What It Means | What to Do |
+|-------------|--------------|------------|
+| **0** | Everything is current | Work normally |
+| **1-7** | Minor drift | Fix at next groom |
+| **8-14** | Moderate — Claude may be acting on stale info | Groom soon |
+| **15+** | Critical — workspace context is unreliable | Groom now |
+
+No stop hooks. No unreliable session-end tracking. Pulse always starts from filesystem ground truth.
+
+### Groom — Weekly Maintenance
+
+`/momentum:groom` is a guided, voice-friendly walkthrough of your entire workspace. It reviews one area at a time, oldest-first:
+
+1. **Active work** — "Still active? Status changed? Anything done?" — walks through each project and task
+2. **Backlog** — Enforces time-based rules:
+   - High priority items get 7 days before they demand a decision
+   - Medium gets 14 days. Low gets 30 days.
+   - Items that sit past 2x their review window get auto-archived.
+   - "Decide or kill" — nothing sits in limbo forever.
+3. **Graduation** — "Ready to work on any backlog items?" Items move to active work. Always explicit, never automatic.
+4. **Directories** — Scans tracked directories (projects, clients, tools) for orphaned or new items
+5. **Connected projects** — Checks project health across your workspace (more on this below)
+6. **System layer** — Quick scan for dead hooks, unused commands, stale rules
+
+Result: drift score resets to 0, summary gets logged, next groom date is set.
+
+### Audit — Deep Optimization
+
+`/momentum:audit` goes deeper than grooming. Each tracked area maps to a configurable audit strategy:
+
+| Strategy | Applies To | What It Does |
+|----------|-----------|-------------|
+| `staleness` | Working memory files | Checks file age against thresholds |
+| `classify` | Directories (projects/, clients/) | Lists items for triage: active, archive, or delete |
+| `cross-reference` | Tools with config files | Finds orphaned tools and broken config references |
+| `dead-code` | System directories | Finds unused hooks, commands, skills |
+| `pipeline-status` | Content or task workflows | Flags stuck items and bottlenecks |
+
+The number of audit phases is dynamic — generated from your manifest, not hardcoded. A small workspace gets 3 phases. A large one gets 12. Same command, adapted to your reality.
+
+### Config Alignment — `.claude/` Directory Audit
+
+`/momentum:audit-claude` solves a problem that grows silently: `.claude/` directory sprawl.
+
+As you work across multiple projects, each one accumulates its own `.claude/` directory — hooks copied from another project, skills installed locally before you went global, settings files with MCP server lists from three months ago. Over time you end up with duplicated hooks running twice, stale config referencing tools that don't exist, and skills taking up space in five project directories when they should live in one global location.
+
+#### How it works
+
+The audit runs in two stages:
+
+**Stage 1: Scanner** — A Python utility (`scan-claude-dirs.py`) runs first and produces a complete JSON dataset of your workspace. It recursively discovers every `.claude/` directory, catalogs every file inside them, and generates an MD5 fingerprint for each one. It also builds baselines of your global `~/.claude/` and workspace root `.claude/` — same treatment, every file fingerprinted. The result is a structured JSON file saved to `.accel/momentum/audits/data-sets/`.
+
+An MD5 fingerprint is a unique identifier generated from a file's contents. If two files produce the same fingerprint, they are byte-for-byte identical — not "similar," not "probably the same," but provably exact. If the fingerprints differ, the files are different. This means every classification in the audit is based on evidence, not assumption.
+
+**Stage 2: Classification + Report** — Claude reads the scanner's JSON dataset and classifies every item against both baselines:
+
+| Classification | What It Means |
+|---------------|---------------|
+| **DUPLICATE** | Fingerprint matches a baseline file — provably identical, safe to remove |
+| **DIVERGED** | Same name exists in a baseline but different fingerprint — needs a decision |
+| **GLOBAL_CANDIDATE** | Verified not to exist in any baseline — suggest promotion |
+| **PROJECT_SPECIFIC** | Legitimately belongs in this project — leave it alone |
+| **STALE** | References things that no longer exist — clean up |
+| **ACCIDENTAL** | Nested `.claude/.claude/` dirs, empty dirs — delete |
+| **TEMPLATE** | Lives in a `_template/` directory — intentional, skip |
+
+The scanner produces the data. Claude produces the judgment. Separating these means the data is deterministic and complete — Claude can't accidentally skip a file or forget to check a baseline.
+
+#### Remediation
+
+Findings are grouped by risk level (lowest first) and every change requires explicit approval. The workflow never batch-deletes, never assumes a messy config is wrong, and never modifies your global `~/.claude/` without asking. After changes, it verifies no broken references were created and recommends which projects to test.
+
+The full audit report is written to `.accel/momentum/audits/` as a structured markdown file — readable in any markdown viewer, not buried in terminal output. The scanner's raw JSON dataset is preserved in `.accel/momentum/audits/data-sets/` for reference.
+
+The strategy is defined in a standalone framework file (`claude-config-alignment.md`) that any audit workflow can compose in at runtime — it doesn't modify existing audit strategies.
+
+---
+
+## MCP Server — Claude Operates on Your Data
+
+Momentum ships one MCP server so Claude can read and write your workspace data through structured tool calls instead of raw file edits.
+
+### Momentum MCP — Surfaces, Projects, Entities, Operator, State
+
+A unified interface for all workspace data. Claude can manage surfaces, track projects, maintain entities, read operator context, and check workspace state:
+
+| Tool | What It Does |
+|------|-------------|
+| `momentum_list_surfaces` | List all surfaces with item counts |
+| `momentum_get_surface` | Read all items from a surface |
+| `momentum_get_item` | Get one item by ID |
+| `momentum_add_item` | Add item (auto-generates ID, validates against schema) |
+| `momentum_update_item` | Update specific fields (preserves everything else) |
+| `momentum_archive_item` | Move item to archive with timestamp |
+| `momentum_search` | Search across one or all surfaces by keyword |
+
+Additional tool modules for first-class data:
+
+| Module | Tools | What They Do |
+|--------|-------|-------------|
+| **Projects** | `momentum_get_projects`, `momentum_update_project` | Unified project tracking with Drive integration |
+| **Entities** | `momentum_get_entities`, `momentum_add_entity`, `momentum_update_entity` | People and organization management |
+| **Operator** | `momentum_get_operator` | Read operator profile (north star, values, vision) |
+| **State** | `momentum_get_state`, `momentum_update_state` | Workspace health and drift tracking |
+| **PSMM** | `momentum_psmm_log`, `momentum_psmm_get`, `momentum_psmm_list`, `momentum_psmm_clean` | Per-session meta memory — log and manage session moments |
+
+When you create a new surface, the MCP server auto-discovers it from `workspace.json`. No code changes needed.
+
+### Vector Integration
+
+[Vector](https://github.com/accelerationguy/vector) (Context Augmentation & Reinforcement Layer) is a dynamic rules engine for Claude Code. It stores behavioral rules in domain files — groups of rules that load automatically based on what you're doing. Say "check Skool" and Vector loads your Skool community rules. Start coding and it loads your development standards. The rules are just config files in `.vector/`.
+
+**Vector is fully independent — it works without Momentum, and Momentum works without Vector.** Vector ships its own MCP server (`vector-mcp`) as part of the [vector-core](https://github.com/accelerationguy/vector) package. Install it separately if you want Vector's tools. If you use both, they complement each other — Vector handles rules and decisions, Momentum handles workspace data and project tracking.
+
+When Vector is installed alongside Momentum, Claude gets programmatic access to three powerful systems (all provided by Vector's MCP, not Momentum's):
+
+#### Dynamic Rules
+
+Claude can read, search, and manage your rule domains through tool calls instead of file edits:
+
+| Tool | What It Does |
+|------|-------------|
+| `vector_list_domains` | List all rule domains and their status |
+| `vector_get_domain_rules` | Read rules for a specific domain |
+| `vector_stage_proposal` | Stage a new rule proposal for review (more on this below) |
+
+#### Decision Logger
+
+Decisions get lost. You make a call in one session — "we're using OAuth, not API keys" — and three sessions later Claude asks you the same question. Or worse, it makes the opposite choice because it has no memory of what you decided.
+
+Vector's decision logger fixes this. Decisions are stored per domain (e.g., `decisions/development.json`, `decisions/global.json`) and **load automatically alongside domain rules**. When Vector loads the "development" domain because you're coding, every decision you've ever logged in that domain loads with it as lightweight metadata. Claude reads your decisions before acting on the prompt itself. It never misses a key decision again — not because it searches for it, but because the decision is already in context the moment the domain is relevant.
+
+| Tool | What It Does |
+|------|-------------|
+| `vector_log_decision` | Record a decision with domain, rationale, and recall keywords |
+| `vector_search_decisions` | Search across all domains when you need to find something specific |
+
+#### The Rule Staging Pipeline
+
+This is where Vector connects to Momentum's [PSMM](#per-session-meta-memory-psmm--session-intelligence) system. Session moments logged via PSMM can graduate into permanent Vector rules:
+
+1. **During a session** — Claude notices a pattern worth codifying (a correction you gave, a decision that should become policy, an insight about how you work)
+2. **Stage it** — `vector_stage_proposal` creates a draft rule in staging, not in your live rules
+3. **Review during hygiene** — Momentum's `/momentum:vector-hygiene` command walks you through staged proposals: approve, edit, or kill each one
+4. **Approved rules go live** — They become part of your Vector domains, loaded automatically in future sessions
+
+This means your AI assistant gets smarter over time — not by accumulating a massive prompt, but by distilling session learnings into clean, targeted rules. And because staging exists, nothing goes live without your review. The hygiene cycle (part of Momentum's groom flow) prevents staged proposals from going stale — they get reviewed or they get killed.
+
+---
+
+## Operator Profile — Who You Are, Always in Context
+
+`operator.json` is a structured identity document that gives Claude persistent alignment with your goals, values, and vision. Instead of re-explaining who you are and what you're building toward each session, your operator profile loads automatically.
+
+The profile is built through a guided questionnaire (via `/momentum:scaffold`) that walks through five layers:
+
+| Section | What It Captures |
+|---------|-----------------|
+| **Deep Why** | Five increasingly deep questions about your motivation — not a mission statement, but the real reason you do what you do |
+| **North Star** | One measurable metric with a timeframe — the thing you're optimizing for right now |
+| **Key Values** | Rank-ordered values with concrete meanings — not platitudes, but actionable principles |
+| **Elevator Pitch** | A layered pitch (1-4 floors) that describes what you do at increasing depth |
+| **Surface Vision** | Concrete scenes of what success looks like — not abstract goals, but vivid snapshots |
+
+The operator hook injects a compact summary into every session. Claude doesn't quote it back to you — it just stays aligned. When you're making decisions, Claude's suggestions naturally reflect your north star and values without being asked.
+
+---
+
+## Per-Session Meta Memory (PSMM) — Session Intelligence
+
+Here's the problem with long Claude Code sessions: Claude's context window is huge (up to 1M tokens), but important moments — a design decision you made at minute 5, a correction at minute 20, a key insight at minute 45 — get buried under thousands of lines of tool output and code. By the time you're deep into the session, Claude has technically "seen" these moments but they've drifted so far back in context that they stop influencing behavior.
+
+PSMM fixes this. Both logging and injection are built into Momentum:
+
+**Logging** — When something significant happens, Claude logs it via the Momentum MCP:
+
+| Tool | What It Does |
+|------|-------------|
+| `momentum_psmm_log` | Log a session meta-memory entry (type: DECISION, CORRECTION, SHIFT, INSIGHT, COMMITMENT) |
+| `momentum_psmm_get` | Retrieve entries for a specific session |
+| `momentum_psmm_list` | List all sessions with entry counts |
+| `momentum_psmm_clean` | Remove stale session data |
+
+**Injection** — The PSMM hook re-injects the current session's entries into Claude's context on every prompt. Important moments stay hot for the entire session, no matter how long it runs.
+
+**Graduation** — When a session insight should become a permanent rule, it can be staged as a [Vector](https://github.com/accelerationguy/vector) rule proposal via `vector_stage_proposal`. This is the only point where PSMM connects to Vector — everything else is self-contained in Momentum.
+
+No Vector required. PSMM works standalone as session memory. Vector adds the optional path from "session insight" to "permanent behavioral rule."
+
+---
+
+## Mission Control Insights — Workspace Analytics
+
+`/accel:insights` is your portfolio dashboard. It reads `projects.json` and `workspace.json` to compute:
+
+| Analysis | What It Shows |
+|----------|--------------|
+| **Velocity** | Projects sorted by plan age, phase progress, and loop position |
+| **Stall detection** | Projects with plan age > 14 days that aren't completed or deferred |
+| **Blocking analysis** | Groups blocked projects by blocker, flags revenue at risk |
+| **Cross-project dependencies** | Visualizes dependency chains between projects |
+| **Workload by category** | Active project count per category |
+| **Revenue exposure** | All revenue-tied projects with blocked flags |
+| **Pending handoffs** | Drive satellites awaiting handoff processing |
+
+Use it during weekly groom cycles, when deciding what to work on next, before stakeholder updates, or whenever a project feels stalled.
+
+---
+
+## Multi-Project Workspaces — Momentum + Drive
+
+Here's where Momentum really separates from "just another CLAUDE.md helper."
+
+Most Claude Code users work on one project at a time. But real workspaces have multiple projects — apps, client work, tools, content pipelines — each in their own directory, sometimes their own git repo. Without something managing the workspace level, you lose track. Projects stall silently. Work gets abandoned. Nobody notices until it's a problem.
+
+### What Is Drive?
+
+[Drive](https://github.com/accelerationguy/drive) is a project orchestration framework for Claude Code. It manages individual project builds through a structured **Plan → Apply → Unify** loop:
+
+- **Plan** — Define what you're building, break it into phases, get alignment before writing code
+- **Apply** — Execute the plan phase by phase with built-in progress tracking
+- **Unify** — Reconcile what was planned vs what was built, close the loop, start the next milestone
+
+Each Drive project lives in its own directory with a `.drive/` config folder that tracks the project's state, milestones, and phase history. Drive is excellent at managing a single project's lifecycle. But it doesn't know about your other projects, your backlog, or your workspace health.
+
+### Where Momentum Comes In
+
+Momentum is designed to work alongside Drive as the workspace layer that ties everything together. Think of it as the difference between **project management** and **portfolio management:**
+
+- **Drive** manages each project: "What phase am I in? What's the plan? What's left to build?"
+- **Momentum** manages your workspace: "Which of my 6 projects needs attention? Which ones are stalling? What should I work on today?"
+
+### How They Connect
+
+Momentum automatically detects and registers Drive projects across your workspace:
+
+- On session start, a hook scans your workspace for `.drive/drive.json` files and registers any new Drive projects in `workspace.json` automatically
+- If you started using Drive before Momentum, update Drive to the latest version and run `/drive:register` in any Drive project directory to generate the `drive.json` manifest. The next time you start a session in your Momentum workspace, it picks it up automatically.
+- Activity timestamps from each project flow into the workspace manifest so Momentum always knows when each project was last touched
+- During weekly groom, Momentum checks each registered project's health:
+  - **Stuck?** — Planning done but implementation stalled for 7+ days
+  - **Abandoned?** — No activity for 14+ days with work still incomplete
+  - **Drifting?** — Milestone marked complete but no new work started
+- You can configure health checks per project — enable or disable them in the manifest
+
+Momentum never modifies your projects. It only reads and reports. Each project manages itself through Drive. Momentum manages the workspace those projects live in.
+
+```json
+{
+  "satellites": {
+    "my-saas-app": {
+      "path": "apps/my-saas-app",
+      "engine": "drive",
+      "state": "apps/my-saas-app/.drive/STATE.md",
+      "registered": "2026-03-15",
+      "groom_check": true,
+      "last_activity": "2026-03-17T14:30:00-05:00",
+      "phase_name": "Auth System",
+      "phase_number": 3,
+      "phase_status": "in_progress",
+      "loop_position": "APPLY",
+      "handoff": false,
+      "last_plan_completed_at": "2026-03-15T10:00:00-05:00"
+    }
+  }
+}
+```
+
+### Without Drive
+
+Don't use Drive? Momentum still works as a standalone workspace framework. You still get:
+
+- Data surfaces for tracking any structured information
+- Drift detection and grooming for all workspace areas
+- Audit strategies for directories, tools, and system files
+- The full MCP server for surface CRUD
+- Custom surface creation for anything you need
+
+The project detection hook simply has nothing to find. Everything else operates independently.
+
+---
+
+## Creating Custom Surfaces
+
+The five built-in surfaces cover common workspace needs. The real power is creating surfaces for your specific needs.
+
+### `/momentum:surface create`
+
+A guided workflow that generates everything:
+
+```
+> /momentum:surface create
+
+What does this surface track? → "Client projects and their current phase"
+
+What fields does each item need?
+  - name (string, required)
+  - company (string, required)
+  - phase (enum: discovery, proposal, active, maintenance)
+  - monthly_value (number)
+  - next_action (string)
+
+How should this appear in Claude's context?
+  - Group by: phase
+  - Summary format: "[ID] name — company (phase)"
+  - Behavior: passive (silent unless asked)
+
+Generating...
+  + .accel/momentum/data/clients.json
+  + .accel/momentum/hooks/clients-hook.py
+  + workspace.json updated
+  + Hook registered in settings.json
+```
+
+Next session, Claude passively knows your client roster without you doing anything.
+
+### `/momentum:surface convert`
+
+Already have a markdown file with structured data? This command reads it, detects the structure, proposes a JSON schema, migrates the content, and generates everything. Your old `@CLIENTS.md` file becomes a proper data surface with full MCP support.
+
+---
+
+## How the Ecosystem Fits Together
+
+```
+┌─────────────────────────────────┐
+│  Drive   (per-project lifecycle) │  Plan → Apply → Unify
+├─────────────────────────────────┤
+│  Vector   (per-session rules)     │  Load rules based on intent
+├─────────────────────────────────┤
+│  Momentum   (workspace layer)       │  Surfaces, projects, analytics, health
+│         + Operator profile      │  Identity alignment across sessions
+└─────────────────────────────────┘
+```
+
+**All tools are fully independent.** No dependencies between them. Use one, some, or all. References to uninstalled tools are silent — no errors, no noise. If you only install Momentum, you'll never see a Drive or Vector warning.
+
+Together, they turn Claude Code from a per-session coding tool into a managed operating system for AI builders.
+
+<details>
+<summary><strong>How they enhance each other when combined</strong></summary>
+
+- **Momentum + Drive** — Drive projects auto-register with Momentum on session start, giving you workspace-level visibility across all your builds. Momentum groom checks project health. Drive handles the project. Momentum handles the portfolio.
+- **Momentum + Vector** — Vector brings dynamic rules and decision memory. Momentum brings workspace data and project tracking. Together, Claude has both behavioral guidance (Vector) and situational awareness (Momentum). Momentum groom can optionally check Vector rule health and surface staged proposals for review.
+- **Vector + Drive** — Independent. Each operates in its own scope (session rules vs project builds).
+
+</details>
+
+**See also:** [Radar](https://github.com/accelerationguy/radar) — an optional companion for deep codebase auditing (security, architecture, scalability, compliance). 12 AI agent personas across 14 audit domains. Works standalone or pairs with Drive for structured remediation.
+
+---
+
+## Design Principles
+
+1. **If it's not current, it's harmful.** Stale context feeds Claude bad information. Maintenance isn't optional — it's the whole point.
+2. **Every file earns its place.** Can't explain why it's here in 5 seconds? It moves or dies.
+3. **Archive over delete.** When in doubt, archive. You can always delete later. You can't un-delete.
+4. **The workspace is the product.** Treat it like production code, not a scratch pad.
+5. **One manifest drives everything.** `workspace.json` is the single source of truth. No manual bookkeeping.
+6. **Tools register themselves.** Projects auto-register. Surfaces auto-discover. Zero human memory required.
+7. **Passive by default.** Claude has awareness. Claude does not nag.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install globally + wire current workspace
+npx @accel/momentum --global --workspace
+
+# 2. Open Claude Code
+claude
+
+# 3. Run guided workspace setup
+/momentum:scaffold
+
+# 4. Check workspace health anytime
+/momentum:pulse
+
+# 5. Weekly maintenance
+/momentum:groom
+
+# 6. Create a custom surface for anything you want Claude to know about
+/momentum:surface create
+```
+
+---
+
+## Requirements
+
+- **Node.js** >= 16.7.0
+- **Python 3** (for hooks)
+- **[Claude Code](https://claude.ai/code)**
+
+---
+
+## License
+
+MIT — [Acceleration Guy](https://github.com/accelerationguy)