@driftless-sh/cli 0.1.33 → 0.1.35

package/README.md

@@ -12,10 +12,11 @@ npm install -g @driftless-sh/cli
 
 ```bash
 driftless login --key <api-key>       # Generate one at driftless.icu → Settings → API keys
-driftless init                         # Scan repo, bootstrap context, suggest rules
-driftless session start                # See relevant context before editing
+driftless init                         # Scan repo, upload baseline, install skill
+driftless init --suggest               # Also auto-generate rules + context topics
+driftless sync                         # Pull stale topics, violations, and suggested topics
+driftless context get <slug>           # Load context before editing
 driftless scan --diff                  # Check changes against rules before pushing
-driftless session end                  # Scan + context report + stale detection
 driftless install-skill                # Write AGENTS.md for Claude Code / Cursor
 ```
 
@@ -48,34 +49,38 @@ Auth is stored in `~/.driftless/config.json`. You can also set `DRIFTLESS_API_KE
 
 ### `driftless init`
 
-Full repo initialization. Runs a 3-pass scan:
+Smart repo initialization:
 
-1. **Identity** — detects framework, system type, auth patterns (zero tokens)
-2. **AST extraction** — extracts endpoints, guards, services, modules, DTOs with fields + validations, and their relations (zero tokens)
+1. **Identity** — detects framework, system type, auth patterns (local, zero tokens)
+2. **AST extraction** — extracts endpoints, guards, services, modules, relations (local, zero tokens)
 3. **Upload** — sends baseline + components + relations to Cloud
+4. **Skill install** — writes `AGENTS.md` and `.driftless/skill.md`
 
 ```bash
 cd my-nestjs-repo
 driftless init
 ```
 
-After init, Driftless suggests architectural rules based on detected patterns and creates context topics for each module.
+#### Flags
 
----
-
-### `driftless session`
-
-The agent loop — start with context, finish with a report.
+| Flag | Description |
+|------|-------------|
+| `--suggest` | Also auto-generate rules and context topics from detected patterns. Off by default. |
+| `--src <path>` | **Monorepo support** — scan from a subpath while git root stays at cwd. Example: `--src apps/api/src` |
 
 ```bash
-driftless session start                # Show context for local changes
-driftless session start --files "src/auth/**"  # Show context for specific files
-driftless session end                  # Scan changes, check violations, suggest updates
-```
+# Standard repo
+driftless init
+
+# Standard repo with auto-generated topics + rules
+driftless init --suggest
 
-**Before editing:** `session start` tells you which context topics, docs, and gotchas apply to the files you're about to touch.
+# Monorepo: NestJS app lives at apps/api/src
+driftless init --src apps/api/src
 
-**Before pushing:** `session end` runs `scan --diff`, reports violations, and flags stale context that needs updating.
+# Monorepo with auto-generated topics + rules
+driftless init --src apps/api/src --suggest
+```
 
 ---
 
@@ -153,7 +158,7 @@ driftless context sync auth --doc docs/auth.md --dry-run
 
 A topic can track components in two ways:
 
-- **`--pattern`** — glob pattern that resolves dynamically (e.g. `src/sdk/**`)
+- **`--pattern`** — glob pattern that resolves dynamically (e.g. `src/sdk/**`). One glob per topic — commas are not supported.
 - **`--where`** — explicit file path
 
 ```bash
@@ -173,6 +178,17 @@ driftless context add "b2b-guard" \
   --how "Verifies org_id in the token"
 ```
 
+#### Appending multiple gotchas at once
+
+`--gotcha` can be passed multiple times in one call — all values are appended:
+
+```bash
+driftless context update auth \
+  --gotcha "Reset token on org switch" \
+  --gotcha "Test tokens never include production claims" \
+  --gotcha "Clerk JWTs expire after 1h"
+```
+
 #### Fields
 
 | Field | Description |
@@ -254,6 +270,11 @@ Show help for all commands or a specific command.
 driftless help              # All commands
 driftless help context      # Context subcommands
 driftless help scan         # Scan details
+
+# --help also works on any command without hitting the API
+driftless init --help
+driftless scan --help
+driftless context --help
 ```
 
 ---
@@ -283,14 +304,15 @@ This creates `AGENTS.md` with instructions for Claude Code to use Driftless befo
 ### Custom Agents
 
 ```bash
-# Before starting work
-driftless session start --files "src/auth/**"
+# Load context for the files you're about to touch
+driftless context get <slug>
+driftless context load --files "src/auth/**"
 
-# Before finishing work
-driftless session end
+# Before pushing
+driftless scan --diff
 
 # After discovering new context
-driftless context add "name" --what "..." --how "..." --where "..."
+driftless context update <slug> --gotcha "..." --decisions "..."
 ```
 
 Use `--json` flag for machine-readable output that agents can parse.