@driftless-sh/cli 0.1.22 → 0.1.23

package/README.md

@@ -1,8 +1,8 @@
 # Driftless CLI
 
-**Context integrity for AI engineering teams.**
+**Living repo context for humans and coding agents.**
 
-Driftless is the shared codebase memory layer for engineering teams. The CLI lets you scan your repo, enforce architectural rules, and manage context watchers — the team's durable knowledge about how the codebase works.
+Driftless scans your codebase, builds durable context about how it works, and delivers the right knowledge to the right person at the right time — before changes are made.
 
 ```
 npm install -g @driftless-sh/cli
@@ -12,9 +12,10 @@ npm install -g @driftless-sh/cli
 
 ```bash
 driftless login --key <api-key>       # Generate one at driftless.icu → Settings → API keys
-driftless init                         # Scan repo, upload baseline, suggest rules
-driftless scan --diff                  # Check uncommitted changes against rules
-driftless context get <name>           # Load team context before coding
+driftless init                         # Scan repo, bootstrap context, suggest rules
+driftless session start                # See relevant context before editing
+driftless scan --diff                  # Check changes against rules before pushing
+driftless session finish               # Scan + context report + stale detection
 driftless install-skill                # Write AGENTS.md for Claude Code / Cursor
 ```
 
@@ -58,7 +59,23 @@ cd my-nestjs-repo
 driftless init
 ```
 
-After init, Driftless suggests architectural rules based on detected patterns.
+After init, Driftless suggests architectural rules based on detected patterns and creates context topics for each module.
+
+---
+
+### `driftless session`
+
+The agent loop — start with context, finish with a report.
+
+```bash
+driftless session start                # Show context for local changes
+driftless session start --files "src/auth/**"  # Show context for specific files
+driftless session finish               # Scan changes, check violations, suggest updates
+```
+
+**Before editing:** `session start` tells you which context topics, docs, and gotchas apply to the files you're about to touch.
+
+**Before pushing:** `session finish` runs `scan --diff`, reports violations, and flags stale context that needs updating.
 
 ---
 
@@ -71,13 +88,21 @@ driftless scan           # Scan staged + uncommitted changes
 driftless scan --diff    # Scan uncommitted changes only
 ```
 
-Returns:
-```json
-{ "status": "clean", "violations": [] }
+Output:
+```
+Scanning uncommitted changes...
+  Files: src/sso/sso.controller.ts
+
+Clean — 4 rule(s) evaluated, no violations.
 ```
-or
-```json
-{ "status": "violated", "violations": [{ "rule_id": "...", "explanation": "..." }] }
+
+Or:
+```
+1 violation(s) found (4 rule(s) evaluated):
+
+  [HIGH] Controllers must be thin
+    Business logic detected in controller: "console.log('debug')" — move to a service
+    File: src/sso/sso.controller.ts:13
 ```
 
 Run this before every push. Agents should run it automatically before completing tasks.
@@ -86,31 +111,45 @@ Run this before every push. Agents should run it automatically before completing
 
 ### `driftless context`
 
-Manage **context watchers** — the team's shared codebase memory. Each watcher captures what a piece of the system is, how it works, where it lives, and why decisions were made.
+Manage **context topics** — the team's shared codebase memory. Each topic captures what a piece of the system is, how it works, where it lives, and why decisions were made.
 
 #### Output format
 
-All commands output **JSON by default** for agent consumption. Use `--human` for readable text.
+All commands output **human-readable text by default**. Use `--json` for machine output (agents, CI).
 
 ```bash
-driftless context get sdk          # JSON (for Claude Code, Codex, etc.)
-driftless context get sdk --human  # Readable text
+driftless context list                   # Human-readable
+driftless context list --json            # For agents
+driftless context get auth-boundaries    # Full topic view
+driftless context get auth-boundaries --json
 ```
 
 #### Subcommands
 
 | Command | Description |
 |---------|-------------|
-| `context list` | List all watchers |
-| `context get <slug>` | Get watcher with resolved components + history |
-| `context add <slug>` | Create new watcher |
-| `context update <slug>` | Update watcher fields |
-| `context delete <slug>` | Delete watcher |
-| `context search <query>` | Full-text search across watchers |
+| `context list` | List all context topics |
+| `context get <slug>` | Get topic with resolved components + history |
+| `context add <slug>` | Create new topic |
+| `context update <slug>` | Update topic fields |
+| `context delete <slug>` | Delete a topic |
+| `context search <query>` | Full-text search across topics |
+| `context anchor <slug>` | Anchor a doc to a topic |
+| `context push --files` | Match topics for given file paths |
+
+#### Dry run
 
-#### Creating watchers
+All write commands support `--dry-run` to preview changes without writing to Cloud:
 
-A watcher can track components in two ways:
+```bash
+driftless context push --files "src/auth/**" --dry-run
+driftless context update auth --what "..." --dry-run
+driftless context anchor auth --doc docs/auth.md --dry-run
+```
+
+#### Creating topics
+
+A topic can track components in two ways:
 
 - **`--pattern`** — glob pattern that resolves dynamically (e.g. `src/sdk/**`)
 - **`--where`** — explicit file path
@@ -147,23 +186,26 @@ driftless context add "b2b-guard" \
 #### Examples
 
 ```bash
-# List all watchers
+# List all topics
 driftless context list
 
-# Get watcher with resolved components (JSON)
+# Get topic with resolved components
 driftless context get sdk
 
-# Get watcher with human-readable output
-driftless context get sdk --human
-
-# Search watchers
+# Search topics
 driftless context search "auth"
 driftless context search "business guard"
 
-# Update a watcher
+# Update a topic
 driftless context update sdk --what "SDK v2 with streaming"
 
-# Delete a watcher
+# Append a gotcha
+driftless context update sdk --gotchas "Reset token on org switch"
+
+# Anchor a doc
+driftless context anchor auth --doc docs/auth.md --files "src/auth/**"
+
+# Delete a topic
 driftless context delete old-feature
 ```
 
@@ -184,6 +226,18 @@ driftless install-skill
 
 ---
 
+### `driftless doctor`
+
+Check environment health before using Driftless.
+
+```bash
+driftless doctor
+```
+
+Verifies: API key, API reachable, git remote, workspace, repo link, baseline, AGENTS.md, GitHub App.
+
+---
+
 ### `driftless help`
 
 Show help for all commands or a specific command.
@@ -222,16 +276,16 @@ This creates `AGENTS.md` with instructions for Claude Code to use Driftless befo
 
 ```bash
 # Before starting work
-driftless context get <feature>
+driftless session start --files "src/auth/**"
 
 # Before finishing work
-driftless scan --diff
+driftless session finish
 
 # After discovering new context
 driftless context add "name" --what "..." --how "..." --where "..."
 ```
 
-All output is JSON by default, making it easy for agents to parse and use as context.
+Use `--json` flag for machine-readable output that agents can parse.
 
 ## Architecture
 
@@ -252,7 +306,7 @@ driftless scan
   └── Return violations
 
 driftless context
-  ├── CRUD watchers via REST API
+  ├── CRUD topics via REST API
   ├── Full-text search (Postgres tsvector)
   └── Pattern resolution (glob → resolved files)
 ```