@codified/cli 0.4.6 → 0.5.0

package/README.md

@@ -1,26 +1,15 @@
 # Codify
 
-**Living context graph for AI-native teams.**
+**Living Context Graph for AI-Native Teams**
 
-Codify mines your project history into a structured graph that captures decisions, features, customer signals, code artifacts, and their relationships. It then gives Claude Code ambient access to that context via MCP, so your AI assistant understands not just what your code does but *why* it was built that way.
+Codify mines your project history into a structured context graph -- decisions, features, customer signals, code artifacts, and their relationships. Claude Code gets ambient access to that context via MCP, so your AI assistant understands not just what your code does but *why* it was built that way.
 
-A built-in Gap Engine proactively detects missing context, stale assumptions, and untested decisions. Gaps get addressed automatically through graph mining and evidence collection.
+A built-in Gap Engine proactively detects missing context, stale assumptions, and untested decisions. An Autonomous Collection service fills those gaps by mining existing data and reaching out to team members. A Metabolism service continuously maintains graph health through freshness decay, semantic dedup, contradiction resolution, and structural evolution.
 
-## Prerequisites
-
-- Node.js 22+
-- Docker (for PostgreSQL, NATS, Redis)
-- `ANTHROPIC_API_KEY` environment variable (for bootstrap, explain, and collect commands)
-
-## Install
+## Quick Start
 
 ```bash
 npm install -g @codified/cli
-```
-
-## Quickstart
-
-```bash
 cd your-project
 codify up
 ```
@@ -31,80 +20,165 @@ codify up
 2. **bootstrap** -- Mines your git history with Claude, extracting decisions, features, and relationships into the context graph.
 3. **start** -- Launches the MCP server on stdio. Claude Code connects automatically.
 
-After this, open Claude Code in your project. It now has full context about your codebase.
+After this, open Claude Code in your project. It now has full context about your codebase -- 23 tools and 4 resources at its disposal.
+
+## What Claude Code Gets
+
+Codify auto-installs its MCP server config during `codify init`. Claude Code connects automatically -- no manual configuration required.
+
+### MCP Tools (23)
+
+#### Search and Navigate
+
+| Tool | Description |
+|------|-------------|
+| `codify_get_context` | Get the full context surrounding a topic -- decisions, signals, gaps, relationships |
+| `codify_search` | Search the graph using natural language (hybrid keyword + semantic) |
+| `codify_traverse` | Walk the graph from any node following typed edges |
+| `codify_get_decision_trail` | Trace the reasoning chain behind a decision |
+| `codify_explain` | Claude-powered narrative synthesis from graph data |
+| `codify_get_context_package` | Get a synthesized context briefing for a topic |
+
+#### Gap Engine
+
+| Tool | Description |
+|------|-------------|
+| `codify_get_gaps` | List detected context gaps with priority sorting |
+| `codify_resolve_gap` | Mark a gap as resolved with evidence |
+
+#### Collection
+
+| Tool | Description |
+|------|-------------|
+| `codify_collect` | Mine evidence for open gaps from the existing graph |
+| `codify_get_collection_plans` | View active collection plans and their status |
+| `codify_get_collection_metrics` | Collection pipeline analytics -- response rates, fill time |
+
+#### Metabolism and Evolution
+
+| Tool | Description |
+|------|-------------|
+| `codify_get_metabolism_audit` | View the metabolism audit trail -- decay, prune, promote events |
+| `codify_get_evolution_proposals` | View pending structural evolution proposals (type splits) |
+| `codify_execute_evolution` | Execute an approved evolution proposal |
+
+#### Context and Decision Support
+
+| Tool | Description |
+|------|-------------|
+| `codify_decision_context` | Assemble a decision brief -- prior decisions, evidence, contradictions, risks |
+| `codify_add_context` | Add new context nodes to the graph |
+| `codify_status` | Graph health and statistics |
+| `codify_bootstrap` | Trigger a bootstrap from within Claude Code |
+| `codify_get_digest` | Daily context digest -- graph growth, gaps, metabolism activity |
+| `codify_subscribe_events` | Configure proactive context push notification filters |
 
-## Commands
+#### Branch Management
 
-### Getting Started
+| Tool | Description |
+|------|-------------|
+| `codify_create_branch` | Create an exploration branch of the graph |
+| `codify_merge_branch` | Merge a branch back into the main graph |
+| `codify_list_branches` | List active graph branches |
+
+### MCP Resources (4)
+
+| Resource | Description |
+|----------|-------------|
+| `codify://schema` | The context graph schema -- node types, edge types, relationships |
+| `codify://quickstart` | Quick start guide for using Codify tools |
+| `codify://context/{topic}` | Dynamic context package for any topic (resource template) |
+| `codify://gaps/active` | Current active gap summary -- count, top 5, clusters |
+
+## CLI Commands (30)
+
+### Setup
 
 | Command | Description |
 |---------|-------------|
 | `codify up` | One-command setup and start (init + bootstrap + start) |
-| `codify init` | Set up infrastructure and configure project |
+| `codify init` | Set up Docker services, run migrations, install MCP config |
 | `codify bootstrap` | Mine git history into the context graph |
 | `codify start` | Start the MCP server for Claude Code |
+| `codify project` | Manage multiple projects (create, list, switch) |
 
-### Working with Context
+### Graph Operations
 
 | Command | Description |
 |---------|-------------|
+| `codify search <query>` | Search the context graph (keyword + semantic) |
 | `codify explain <question>` | Ask Claude a question about your project |
-| `codify search <query>` | Search the context graph by keyword |
+| `codify briefing <topic>` | Get a synthesized context briefing on a topic |
+| `codify decide <question>` | Assemble decision-point context (evidence, gaps, risks) |
 | `codify add` | Record a decision, signal, or other context |
 | `codify graph` | Visualize the context graph (Mermaid diagram) |
-| `codify status` | Show project health dashboard |
 
-### Gaps and Quality
+### Gap Management
 
 | Command | Description |
 |---------|-------------|
+| `codify status` | Show project health dashboard |
 | `codify gaps` | Show gaps detected by the Gap Engine |
-| `codify triage` | Interactively resolve gaps |
+| `codify triage` | Interactively resolve gaps (with [c]ollect) |
 | `codify collect` | Mine the graph for evidence to fill gaps |
-| `codify check <file>` | Check files for related context (CI-ready) |
+| `codify check <file>` | Check files for related context (CI-ready, exit code 1 on critical gaps) |
+| `codify evolve` | Manage structural evolution proposals |
+
+### Connectors
+
+| Command | Description |
+|---------|-------------|
+| `codify connect` | Connect external data sources (Slack, GitHub, Linear, Notion, docs) |
+| `codify connectors` | List all connectors with health status |
 
-### Projects and Maintenance
+### Analytics
 
 | Command | Description |
 |---------|-------------|
-| `codify project create/list/switch` | Manage multiple projects |
+| `codify digest` | Daily context digest -- graph growth, gaps, metabolism |
+| `codify metrics` | Collection pipeline analytics (response rates, fill time) |
+
+### Maintenance
+
+| Command | Description |
+|---------|-------------|
+| `codify audit` | Show metabolism audit trail (decay, prune, promote events) |
+| `codify refresh-freshness` | Recalculate freshness scores for all nodes |
 | `codify timeline` | Show what changed in the graph over time |
-| `codify export` | Backup the graph to JSON |
+| `codify cleanup` | Fix legacy data quality issues (gap descriptions, node titles) |
+| `codify export` | Backup the graph to a JSON file |
 | `codify import` | Restore the graph from a JSON backup |
-| `codify watch` | Start continuous ingest polling |
-| `codify connect` | Connect external data sources |
+| `codify watch` | Start continuous ingest polling with heartbeat |
+| `codify embed` | Backfill embeddings for semantic search |
 | `codify reset` | Reset the context graph (drop all data) |
 
 Run `codify <command> --help` for detailed options on any command.
 
-## MCP Integration
+## Architecture
 
-Codify auto-installs its MCP server config during `codify init`. Claude Code connects automatically -- no manual configuration required.
+Codify uses PostgreSQL as its single storage engine:
 
-The MCP server exposes tools that Claude can call directly:
+- **Apache AGE** for graph traversal (nodes, edges, typed relationships)
+- **pgvector** for semantic search (Voyage AI embeddings, hybrid keyword + vector ranking)
+- **NATS JetStream** for event-driven gap detection, collection, and metabolism
+- **Redis** for caching
 
-- **codify_get_context** -- Retrieve context nodes by type or ID
-- **codify_search** -- Search the graph by keyword
-- **codify_explain** -- Claude-powered narrative synthesis from graph data
-- **codify_get_gaps** -- List detected context gaps
-- **codify_resolve_gap** -- Mark a gap as resolved with evidence
-- **codify_add_context** -- Add new context nodes to the graph
-- **codify_get_decision_trail** -- Trace the reasoning chain behind a decision
-- **codify_traverse** -- Walk the graph from any node
-- **codify_status** -- Graph health and statistics
-- **codify_collect** -- Mine evidence for open gaps
-- **codify_get_context_package** -- Get a bundled context snapshot for a topic
+The context graph stores nodes (Decision, Feature, CustomerSignal, CodeArtifact, Gap, Metric, Discussion, Person, Study) and typed edges representing their relationships. Five subsystems run continuously:
 
-## How It Works
+1. **Gap Engine** -- 7 proactive scan patterns detect missing context, stale assumptions, weak evidence, contradictions, orphan nodes, cross-functional blind spots, and assumption drift. Gaps auto-resolve when sufficient evidence arrives.
+2. **Autonomous Collection** -- Mines the existing graph and connected data sources for evidence that addresses detected gaps. Sends Slack DMs to team members for tribal knowledge. Structures collected data into typed graph nodes via Claude.
+3. **Metabolism** -- Freshness decay, semantic dedup gating, pruning of stale nodes, contradiction resolution, hot layer TTL, and structural evolution (automatic type splitting when embedding clusters diverge).
+4. **Connector Health** -- Monitors all connected data sources, auto-reconnects with exponential backoff on transient failures, escalates to critical gaps when connectors stay dead.
+5. **Context Push** -- Subscribes to significant graph events (critical gaps, connector failures, evolution) and pushes MCP notifications to Claude Code in real time.
 
-Codify uses PostgreSQL as its single storage engine:
+TypeScript monorepo with 8 packages, built with pnpm workspaces and esbuild.
 
-- **Apache AGE** for graph traversal (nodes, edges, relationships)
-- **pgvector** for semantic search (embedding-based similarity)
-- **NATS JetStream** for event-driven gap detection and metabolism
-- **Redis** for caching
+## Requirements
 
-The context graph stores nodes (Decision, Feature, CustomerSignal, CodeArtifact, Gap, etc.) and typed edges representing their relationships. A Metabolism service continuously maintains graph health through freshness decay, contradiction detection, and deduplication.
+- **Node.js 22+**
+- **Docker** (for PostgreSQL 16 + AGE 1.6 + pgvector, NATS 2.11, Redis 7)
+- **ANTHROPIC_API_KEY** environment variable (for bootstrap, explain, briefing, decide, digest, collect)
+- **VOYAGE_API_KEY** environment variable (optional, for semantic search embeddings)
 
 ## Links
 

package/assets/migrations/006_multi_project.sql

@@ -0,0 +1,24 @@
+-- 006: Multi-project support
+-- Add project_id to nodes and edges, create projects table
+
+-- Projects table
+CREATE TABLE IF NOT EXISTS projects (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT UNIQUE NOT NULL,
+  description TEXT,
+  created_at TIMESTAMPTZ DEFAULT now(),
+  updated_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- Insert default project
+INSERT INTO projects (id, name, description)
+VALUES ('00000000-0000-0000-0000-000000000000', 'default', 'Default project')
+ON CONFLICT (id) DO NOTHING;
+
+-- Add project_id to nodes
+ALTER TABLE nodes ADD COLUMN IF NOT EXISTS project_id UUID DEFAULT '00000000-0000-0000-0000-000000000000' REFERENCES projects(id);
+CREATE INDEX IF NOT EXISTS idx_nodes_project_id ON nodes (project_id);
+
+-- Add project_id to edges
+ALTER TABLE edges ADD COLUMN IF NOT EXISTS project_id UUID DEFAULT '00000000-0000-0000-0000-000000000000' REFERENCES projects(id);
+CREATE INDEX IF NOT EXISTS idx_edges_project_id ON edges (project_id);

package/assets/migrations/007_collection_metrics.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS collection_metrics (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  computed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  period_start TIMESTAMPTZ NOT NULL,
+  period_end TIMESTAMPTZ NOT NULL,
+  total_plans_created INTEGER NOT NULL DEFAULT 0,
+  total_plans_completed INTEGER NOT NULL DEFAULT 0,
+  total_plans_failed INTEGER NOT NULL DEFAULT 0,
+  avg_time_to_fill_ms BIGINT,
+  median_time_to_fill_ms BIGINT,
+  response_rate NUMERIC(5,4),
+  channel_stats JSONB DEFAULT '{}',
+  gap_type_stats JSONB DEFAULT '{}',
+  metadata JSONB DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_collection_metrics_computed ON collection_metrics(computed_at DESC);