npm - @chrisai/base - Versions diffs - 2.3.0 → 2.3.1 - Mend

@chrisai/base 2.3.0 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +418 -75
package/package.json +1 -1
package/src/framework/tasks/scaffold.md +12 -5
package/src/hooks/satellite-detection.py +3 -3

package/README.md CHANGED Viewed

@@ -9,15 +9,113 @@
 [![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>
 ---
-## What is BASE?
+## 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. BASE is what comes after.
+---
+## What BASE Actually Does
-BASE keeps your Claude Code workspace from becoming a mess. It scaffolds structure, tracks workspace health, surfaces the right context automatically, and tells you when things go stale — so you spend time building, not maintaining.
+BASE turns your Claude Code workspace into a managed operating system. Instead of scattered markdown files and manual context loading, you get:
-**The core pattern:** structured JSON files (data surfaces) + lightweight Python hooks that inject them into Claude's context every session. Claude always knows what's active, what's queued, and where satellites stand — without you having to say it.
+**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, BASE tells you. When grooming is overdue, BASE 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
+```
+BASE ships with two built-in surfaces:
+| Surface | What It Tracks |
+|---------|---------------|
+| **Active** | Current projects, tasks, blockers, deadlines, status |
+| **Backlog** | Future work, ideas, deferred items with review deadlines |
+But you can create surfaces for anything — clients, contacts, content pipelines, API keys, whatever persistent data you want Claude to passively know about. The `/base:surface create` command walks you through it: define a schema, pick an injection format, and BASE 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 BASE command reads from this manifest. You configure it once during setup, and the system maintains itself from there.
+### Hooks — The Glue
+BASE 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) |
+| **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 |
+|------|-------------|
+| **PAUL project detection** | Scans your workspace for [PAUL](https://github.com/ChristopherKahler/paul) project files (`.paul/paul.json`) and auto-registers new ones into `workspace.json`. Only needs to run once — your project list doesn't change mid-session. (More on PAUL below.) |
+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.
 ---
@@ -27,128 +125,373 @@ BASE keeps your Claude Code workspace from becoming a mess. It scaffolds structu
 npx @chrisai/base --global --workspace
 ```
-| Flag | What it does |
-|------|-------------|
-| `--global` | Install commands + framework to `~/.claude` |
-| `--workspace` | Install workspace layer (`.base/`) in current directory |
-| `--local` | Install commands to `./.claude` instead of global |
-| `--config-dir <path>` | Custom Claude config directory |
-| `--workspace-dir <path>` | Target a specific workspace path |
+One command. Two layers:
-**Common flows:**
+- `--global` installs commands and the framework to `~/.claude` (shared across all your workspaces)
+- `--workspace` installs the data layer to `.base/` in your current directory
+Then open Claude Code and run `/base:scaffold` to configure your workspace with a guided setup.
 ```bash
-# Full install — global commands + current workspace
+# Full install — most users start here
 npx @chrisai/base --global --workspace
-# Already have global? Just wire a new workspace
+# Already installed globally? Wire up a new workspace
 npx @chrisai/base --workspace
-# Global only — set up each workspace later with /base:scaffold
+# Global only — set up workspaces later with /base:scaffold
 npx @chrisai/base --global
 ```
+| Flag | What It Does |
+|------|-------------|
+| `--global` | Commands + framework to `~/.claude` (shared) |
+| `--workspace` | Data layer to `.base/` 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 |
 ---
 ## What Gets Installed
 ```
-~/.claude/                          ← --global
-├── commands/base/                  11 slash commands
-├── skills/base/                    Entry point (base.md)
+~/.claude/                              Shared across all workspaces
+├── commands/base/                      11 slash commands
+├── skills/base/                        Skill entry point + package sources
 └── base-framework/
-    ├── tasks/                      pulse, groom, audit, scaffold...
-    ├── templates/                  workspace.json, STATE.md, surfaces
-    ├── context/                    base-principles.md
-    ├── frameworks/                 audit-strategies.md
-    └── hooks/                      Session hooks (scaffold source)
-./.base/                            ← --workspace
-├── workspace.json                  Manifest: surfaces, satellites, groom config
+    ├── tasks/                          How each command works (pulse, groom, audit...)
+    ├── templates/                      Schemas for workspace.json, STATE.md, surfaces
+    ├── context/                        Core principles
+    ├── frameworks/                     Audit strategies, project registration
+    └── hooks/                          Session hook sources
+.base/                                  Per-workspace
+├── workspace.json                      The manifest — everything is registered here
 ├── data/
-│   ├── active.json                 Active projects surface
-│   └── backlog.json                Backlog surface
-├── hooks/                          Surface injection hooks
-├── base-mcp/                       BASE MCP server
-└── carl-mcp/                       CARL MCP server
-./.claude/
+│   ├── active.json                     Active work surface
+│   └── backlog.json                    Backlog surface
 ├── hooks/
-│   ├── base-pulse-check.py         Drift detection (every session)
-│   ├── psmm-injector.py            Per-session meta memory
-│   └── satellite-detection.py      PAUL project auto-registration
-└── settings.json                   Hook registrations (merged)
+│   ├── _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
+├── base-mcp/                           MCP server for surface operations (CRUD)
+└── carl-mcp/                           MCP server for rules engine operations
+.claude/hooks/                          Registered in settings.json
+├── base-pulse-check.py                 [UserPromptSubmit] Drift + groom reminders
+├── psmm-injector.py                    [UserPromptSubmit] Session meta memory
+└── satellite-detection.py              [SessionStart] PAUL project discovery
 ```
 ---
-## Commands
+## The Maintenance Cycle
+Most workspace management tools are set-and-forget. BASE is designed around the reality that workspaces are living things that drift.
+### Pulse — Session Start Health Check
-After install, open Claude Code and run `/base:scaffold` to complete setup.
+`/base:pulse` runs automatically via hook. It reads your manifest, checks filesystem timestamps, and calculates a drift score:
-| Command | Description |
-|---------|------------|
-| `/base:scaffold` | Set up BASE in a new or existing workspace |
-| `/base:pulse` | Daily workspace health briefing |
-| `/base:groom` | Weekly maintenance cycle |
-| `/base:audit` | Deep workspace optimization |
-| `/base:status` | Quick health check |
-| `/base:history` | Workspace evolution timeline |
-| `/base:audit-claude-md` | Audit CLAUDE.md, generate recommended version |
-| `/base:carl-hygiene` | CARL domain maintenance |
-| `/base:surface create` | Create a new data surface (guided) |
-| `/base:surface convert` | Convert a markdown file to a data surface |
-| `/base:surface list` | Show all registered data surfaces |
+| 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
+`/base: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
+`/base: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.
 ---
-## Data Surfaces
+## MCP Servers — Claude Operates on Your Data
-The core primitive. A data surface is a structured JSON file + a Python hook that injects it into Claude's context every session. Any persistent data you want Claude to passively know about becomes a surface.
+BASE ships two MCP servers so Claude can read and write your workspace data through structured tool calls instead of raw file edits.
+### BASE MCP — Works With Any Surface
+A generic CRUD interface for all registered surfaces. Claude can add items, update status, archive old work, and search across everything:
+| Tool | What It Does |
+|------|-------------|
+| `base_list_surfaces` | List all surfaces with item counts |
+| `base_get_surface` | Read all items from a surface |
+| `base_get_item` | Get one item by ID |
+| `base_add_item` | Add item (auto-generates ID, validates against schema) |
+| `base_update_item` | Update specific fields (preserves everything else) |
+| `base_archive_item` | Move item to archive with timestamp |
+| `base_search` | Search across one or all surfaces by keyword |
+When you create a new surface, the MCP server auto-discovers it from `workspace.json`. No code changes needed.
+### CARL MCP — Rules Engine + Decision Memory + Session Intelligence
+[CARL](https://github.com/ChristopherKahler/carl) (Context Augmentation & Reinforcement Layer) is a dynamic rules engine for Claude Code. On its own, CARL stores behavioral rules in domain files — groups of rules that load automatically based on what you're doing. Say "check Skool" and CARL loads your Skool community rules. Start coding and it loads your development standards. The rules are just config files in `.carl/`.
+**CARL is fully independent — it works without BASE, and BASE works without CARL.** But BASE bundles CARL's MCP server as an optional capability. If you use CARL, BASE gives it MCP superpowers (programmatic rule management, decision logging, session memory). If you don't use CARL, this MCP server sits idle and everything else in BASE works normally.
+When both are active, Claude gets programmatic access to three powerful systems:
+#### Dynamic Rules
+Claude can read, search, and manage your rule domains through tool calls instead of file edits:
+| Tool | What It Does |
+|------|-------------|
+| `carl_list_domains` | List all rule domains and their status |
+| `carl_get_domain_rules` | Read rules for a specific domain |
+| `carl_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.
+CARL'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 CARL 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 |
+|------|-------------|
+| `carl_log_decision` | Record a decision with domain, rationale, and recall keywords |
+| `carl_search_decisions` | Search across all domains when you need to find something specific |
+#### Per-Session Meta Memory (PSMM)
+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. When something significant happens during a session — a decision, a correction, a context shift, a key insight — Claude logs it:
+| Tool | What It Does |
+|------|-------------|
+| `carl_psmm_log` | Log a session meta-memory entry (type: DECISION, CORRECTION, SHIFT, INSIGHT, COMMITMENT) |
+The PSMM hook re-injects these entries into Claude's context on every prompt. Important moments stay hot for the entire session, no matter how long it runs.
+#### The Rule Staging Pipeline
+This is where PSMM, decisions, and rules connect into a learning loop:
+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** — `carl_stage_proposal` creates a draft rule in staging, not in your live rules
+3. **Review during hygiene** — BASE's `/base:carl-hygiene` command walks you through staged proposals: approve, edit, or kill each one
+4. **Approved rules go live** — They become part of your CARL 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 BASE's groom flow) prevents staged proposals from going stale — they get reviewed or they get killed.
+---
+## Multi-Project Workspaces — BASE + PAUL
+Here's where BASE 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 PAUL?
+[PAUL](https://github.com/ChristopherKahler/paul) 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 PAUL project lives in its own directory with a `.paul/` config folder that tracks the project's state, milestones, and phase history. PAUL 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 BASE Comes In
+BASE is designed to work alongside PAUL as the workspace layer that ties everything together. Think of it as the difference between **project management** and **portfolio management:**
+- **PAUL** manages each project: "What phase am I in? What's the plan? What's left to build?"
+- **BASE** manages your workspace: "Which of my 6 projects needs attention? Which ones are stalling? What should I work on today?"
+### How They Connect
+BASE automatically detects and registers PAUL projects across your workspace:
+- On session start, a hook scans your workspace for `.paul/paul.json` files and registers any new PAUL projects in `workspace.json` automatically
+- If you started using PAUL before BASE, update PAUL to the latest version and run `/paul:register` in any PAUL project directory to generate the `paul.json` manifest. The next time you start a session in your BASE workspace, it picks it up automatically.
+- Activity timestamps from each project flow into the workspace manifest so BASE always knows when each project was last touched
+- During weekly groom, BASE 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
+BASE never modifies your projects. It only reads and reports. Each project manages itself through PAUL. BASE manages the workspace those projects live in.
+```json
+{
+  "satellites": {
+    "my-saas-app": {
+      "path": "apps/my-saas-app",
+      "engine": "paul",
+      "state": "apps/my-saas-app/.paul/STATE.md",
+      "registered": "2026-03-15",
+      "groom_check": true,
+      "last_activity": "2026-03-17T14:30:00-05:00"
+    }
+  }
+}
 ```
-workspace.json registers it → hook reads it → Claude knows it
-```
-**Built-in surfaces:**
-- `active.json` — Current projects, status, blockers, deadlines
-- `backlog.json` — Future work queue, ideas, deferred items
+### Without PAUL
+Don't use PAUL? BASE 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 built-in `active` and `backlog` surfaces are starting points. The real power is creating surfaces for your specific needs.
+### `/base:surface create`
+A guided workflow that generates everything:
-**Create your own:**
 ```
-/base:surface create
+> /base: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...
+  + .base/data/clients.json
+  + .base/hooks/clients-hook.py
+  + workspace.json updated
+  + Hook registered in settings.json
 ```
-Guided schema builder. Point it at any data you want surfaced — contacts, clients, API keys, anything. BASE generates the JSON schema, the hook, and wires it automatically.
+Next session, Claude passively knows your client roster without you doing anything.
+### `/base: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.
 ---
-## PAUL Satellite Integration
+## The Ecosystem
+BASE is one layer of a three-part system. Each tool is fully independent — use one, some, or all.
-BASE auto-detects [PAUL](https://github.com/ChristopherKahler/paul) projects in your workspace. Every session, `satellite-detection.py` scans for `.paul/paul.json` files and registers any new projects in `workspace.json`. Weekly groom cycles check satellite health: stale loops, abandoned phases, overdue milestones.
+| Tool | What It Manages | Core Question It Answers |
+|------|----------------|------------------------|
+| **BASE** | Your workspace as a whole | "What am I working on? What's stale? What needs attention?" |
+| **[CARL](https://github.com/ChristopherKahler/carl)** | Session-level behavioral rules | "What rules and context should Claude load for what I'm doing right now?" |
+| **[PAUL](https://github.com/ChristopherKahler/paul)** | Individual project builds | "What's the plan? What phase am I in? What's left?" |
-No manual registration. It just works.
+**All three are fully independent.** No dependencies between them. Use one, two, or all three.
+**How they enhance each other when combined:**
+- **BASE + PAUL** — PAUL projects auto-register with BASE on session start, giving you workspace-level visibility across all your builds. BASE groom checks project health. PAUL handles the project. BASE handles the portfolio.
+- **BASE + CARL** — BASE bundles CARL's MCP server, upgrading CARL from config files to programmatic rule management, decision logging, and session memory. BASE groom can optionally check CARL rule health and surface staged proposals for review.
+- **CARL + PAUL** — Independent. Each operates in its own scope (session rules vs project builds).
+- **All three** — The full stack. BASE manages the workspace, CARL manages session behavior, PAUL manages project builds. Each layer does its job without stepping on the others.
+Think of it as layers:
+```
+┌─────────────────────────────────┐
+│  PAUL   (per-project lifecycle) │  Plan → Apply → Unify
+├─────────────────────────────────┤
+│  CARL   (per-session rules)     │  Load rules based on intent
+├─────────────────────────────────┤
+│  BASE   (workspace layer)       │  Surfaces, health, grooming
+└─────────────────────────────────┘
+```
+BASE works alone. CARL works alone. PAUL works alone. But together, they turn Claude Code from a per-session coding tool into a managed operating system for AI builders.
 ---
-## Ecosystem
+## 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.
-BASE is part of a three-layer workspace system:
+---
-| System | Role |
-|--------|------|
-| **BASE** | Workspace lifecycle — surfaces, grooming, drift detection |
-| **CARL** | Dynamic rules engine — just-in-time rule injection |
-| **PAUL** | Project orchestration — Plan → Apply → Unify loop |
+## Quick Start
-Each is independent. Use one, some, or all.
+```bash
+# 1. Install globally + wire current workspace
+npx @chrisai/base --global --workspace
+# 2. Open Claude Code
+claude
+# 3. Run guided workspace setup
+/base:scaffold
+# 4. Check workspace health anytime
+/base:pulse
+# 5. Weekly maintenance
+/base:groom
+# 6. Create a custom surface for anything you want Claude to know about
+/base:surface create
+```
 ---
 ## Requirements
-- Node.js ≥ 16.7.0
-- [Claude Code](https://claude.ai/code)
-- Python 3 (for hooks)
+- **Node.js** >= 16.7.0
+- **Python 3** (for hooks)
+- **[Claude Code](https://claude.ai/code)**
 ---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@chrisai/base",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Builder's Automated State Engine — workspace orchestration framework for Claude Code",
   "bin": {
     "base-framework": "bin/install.js"

package/src/framework/tasks/scaffold.md CHANGED Viewed

@@ -125,17 +125,24 @@ Symlinks are ONLY offered when scaffold detects existing files at workspace root
 <step name="install_hooks">
 Install and register BASE session hooks.
-Session hooks: base-pulse-check.py, psmm-injector.py, satellite-detection.py
+**UserPromptSubmit hooks** (fire every prompt):
+- base-pulse-check.py — drift detection + groom reminders
+- psmm-injector.py — per-session meta memory injection
-For each session hook:
+**SessionStart hooks** (fire once when session begins):
+- satellite-detection.py — PAUL project auto-registration
+For each hook:
 1. Check if `.claude/hooks/{hook}` exists in workspace
 2. If not: copy from `~/.claude/base-framework/hooks/{hook}` (global install source)
    - If `~/.claude/base-framework/hooks/{hook}` doesn't exist either, warn:
      "BASE framework not globally installed. Run `npx base-framework --global` first, then re-run scaffold."
-3. Check project `.claude/settings.json` for hook registration in UserPromptSubmit array
-4. If not registered: add the hook path to settings.json UserPromptSubmit array
+3. Check project `.claude/settings.json` for hook registration:
+   - base-pulse-check.py and psmm-injector.py → register in `UserPromptSubmit` array
+   - satellite-detection.py → register in `SessionStart` array
+4. If not registered: add the hook path to the correct event array in settings.json
-Report: "Session hooks installed (pulse, PSMM injector, satellite detection). Workspace health will be monitored every session."
+Report: "Hooks installed (pulse + PSMM on every prompt, satellite detection on session start)."
 </step>
 <step name="first_groom">

package/src/hooks/satellite-detection.py CHANGED Viewed

@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 """
 Hook: satellite-detection.py
-Purpose: Session-start hook that scans the workspace recursively for .paul/paul.json
-         files, cross-references registered satellites in workspace.json, and
+Purpose: Scans the workspace recursively for .paul/paul.json files,
+         cross-references registered satellites in workspace.json, and
          auto-registers any unregistered projects it finds.
-Triggers: UserPromptSubmit (session context)
+Triggers: SessionStart — runs once when Claude Code starts a session.
 Output: <base-satellites> block if new satellites registered, silent otherwise.
 """