@codified/cli 0.5.0 → 0.5.1

package/README.md

@@ -1,94 +1,26 @@
-# Codify
+# @codified/cli
 
 **Living Context Graph for AI-Native Teams**
 
-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. 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.
+Codify mines your project history into a structured context graph -- decisions, features, customer signals, code artifacts, and their relationships. Claude Code gets ambient access via MCP, so your AI assistant understands not just *what* your code does but *why* it was built that way.
 
 ## Quick Start
 
 ```bash
 npm install -g @codified/cli
 cd your-project
+export ANTHROPIC_API_KEY=sk-ant-...
 codify up
 ```
 
-`codify up` runs three steps in sequence:
-
-1. **init** -- Starts Docker services (PostgreSQL + AGE + pgvector, NATS, Redis), runs database migrations, and installs the MCP server config into Claude Code.
-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 -- 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
+`codify up` runs three steps in sequence -- infrastructure setup, git history mining, and MCP server launch. After it completes, open Claude Code. Codify connects automatically and Claude gains access to 23 MCP tools and 4 MCP resources covering your project's full context.
 
-| 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 |
+## Prerequisites
 
-#### 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 |
-
-#### Branch Management
-
-| 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 |
+- Node.js 22+
+- Docker Desktop
+- `ANTHROPIC_API_KEY` environment variable
+- `VOYAGE_API_KEY` (optional, enables semantic search via Voyage AI embeddings)
 
 ## CLI Commands (30)
 
@@ -102,16 +34,17 @@ Codify auto-installs its MCP server config during `codify init`. Claude Code con
 | `codify start` | Start the MCP server for Claude Code |
 | `codify project` | Manage multiple projects (create, list, switch) |
 
-### Graph Operations
+### Context and Search
 
 | Command | Description |
 |---------|-------------|
-| `codify search <query>` | Search the context graph (keyword + semantic) |
-| `codify explain <question>` | Ask Claude a question about your project |
-| `codify briefing <topic>` | Get a synthesized context briefing on a topic |
+| `codify search <query>` | Search the context graph |
+| `codify explain <question>` | Claude-powered narrative answer about your project |
+| `codify briefing <topic>` | 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 check <file>` | Check files for related context (CI-ready, exit 0/1) |
 
 ### Gap Management
 
@@ -119,9 +52,8 @@ Codify auto-installs its MCP server config during `codify init`. Claude Code con
 |---------|-------------|
 | `codify status` | Show project health dashboard |
 | `codify gaps` | Show gaps detected by the Gap Engine |
-| `codify triage` | Interactively resolve gaps (with [c]ollect) |
+| `codify triage` | Interactively resolve gaps |
 | `codify collect` | Mine the graph for evidence to fill gaps |
-| `codify check <file>` | Check files for related context (CI-ready, exit code 1 on critical gaps) |
 | `codify evolve` | Manage structural evolution proposals |
 
 ### Connectors
@@ -130,59 +62,53 @@ Codify auto-installs its MCP server config during `codify init`. Claude Code con
 |---------|-------------|
 | `codify connect` | Connect external data sources (Slack, GitHub, Linear, Notion, docs) |
 | `codify connectors` | List all connectors with health status |
+| `codify watch` | Start continuous ingest polling with heartbeat |
 
 ### Analytics
 
 | Command | Description |
 |---------|-------------|
 | `codify digest` | Daily context digest -- graph growth, gaps, metabolism |
-| `codify metrics` | Collection pipeline analytics (response rates, fill time) |
+| `codify metrics` | Collection pipeline analytics |
+| `codify audit` | Metabolism audit trail (decay, prune, promote events) |
 
 ### 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 cleanup` | Fix legacy data quality issues (gap descriptions, node titles) |
+| `codify cleanup` | Fix legacy data quality issues |
+| `codify embed` | Backfill embeddings for semantic search |
 | `codify export` | Backup the graph to a JSON file |
 | `codify import` | Restore the graph from a JSON backup |
-| `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.
 
-## Architecture
-
-Codify uses PostgreSQL as its single storage engine:
-
-- **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
+## MCP Tools (23)
 
-The context graph stores nodes (Decision, Feature, CustomerSignal, CodeArtifact, Gap, Metric, Discussion, Person, Study) and typed edges representing their relationships. Five subsystems run continuously:
+When the MCP server is running, Claude Code gets access to 23 tools:
 
-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.
+| Category | Tools |
+|----------|-------|
+| Search and Navigate | `codify_get_context`, `codify_search`, `codify_traverse`, `codify_get_decision_trail`, `codify_explain`, `codify_get_context_package`, `codify_decision_context`, `codify_get_digest` |
+| Gap Engine | `codify_get_gaps`, `codify_resolve_gap`, `codify_collect` |
+| Collection | `codify_get_collection_plans`, `codify_get_collection_metrics` |
+| Metabolism | `codify_get_metabolism_audit`, `codify_get_evolution_proposals`, `codify_execute_evolution` |
+| Graph Mutation | `codify_add_context`, `codify_bootstrap`, `codify_status`, `codify_subscribe_events` |
+| Branching | `codify_create_branch`, `codify_merge_branch`, `codify_list_branches` |
 
-TypeScript monorepo with 8 packages, built with pnpm workspaces and esbuild.
+Plus 4 MCP resources: `codify://schema`, `codify://quickstart`, `codify://context/{topic}`, `codify://gaps/active`.
 
-## Requirements
+## Architecture
 
-- **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)
+PostgreSQL as a single storage engine with Apache AGE (graph), pgvector (semantic search), NATS JetStream (events), and Redis (caching). TypeScript monorepo with 8 packages.
 
 ## Links
 
 - GitHub: [github.com/kurtxu88/codify](https://github.com/kurtxu88/codify)
+- [Full documentation](https://github.com/kurtxu88/codify/blob/main/docs/getting-started.md)
 
 ## License