dotai-cli 0.4.0__tar.gz → 0.6.0__tar.gz

dotai_cli-0.6.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.6.0 — 2026-07-17
+
+### Added
+
+- `dotai learn --directive` for proactive engineering standards, taste, and
+  guardrails without requiring a prior mistake.
+- `dotai insights` for deterministic local delivery evidence: resolution health,
+  selection counts, last use, rule-summary exposure, and unused knowledge.
+- Bounded metadata-only receipt history, retaining the latest 500 resolutions
+  per agent.
+- `PRODUCT.md` defining dotai as portable engineering judgment for coding agents.
+
+### Changed
+
+- Repositioned the CLI and documentation around developer-controlled engineering
+  judgment rather than universal context.
+- `dotai sync` now has one repository-safe behavior: local context outside the
+  worktree.
+- `dotai primer` now always emits the compact bootstrap.
+- `dotai search` reads live knowledge instead of a cached index.
+- `dotai install` is the single entry point for supported external skill formats.
+
+### Removed
+
+- Commands: `watch`, `detach`, `index`, `tree`, `prompt`, `role`, `convert`, and
+  `import-plugin`.
+- Shared/full/agent-specific sync controls and primer session overlays.
+- Freeform `dotai learn --append-md` capture.
+- The cached knowledge-tree model and `watchdog` dependency.
+
+This release intentionally breaks pre-1.0 CLI compatibility to keep one clear,
+local-first product path.

{dotai_cli-0.4.0 → dotai_cli-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dotai-cli
-Version: 0.4.0
-Summary: Universal AI context for any coding agent. Roles, skills, and rules in ~/.ai/
+Version: 0.6.0
+Summary: Portable engineering judgment for coding agents
 Project-URL: Homepage, https://github.com/dawalama/dotai
 Project-URL: Repository, https://github.com/dawalama/dotai
 Project-URL: Issues, https://github.com/dawalama/dotai/issues
@@ -22,69 +22,89 @@ Requires-Dist: ai-skill-audit>=0.5.1
 Requires-Dist: pydantic>=2.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.9
-Requires-Dist: watchdog>=4.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # dotai
 
-**Your coding agents should remember what you taught them.**
+**Portable engineering judgment for coding agents.**
 
-dotai gives Claude, Cursor, Gemini, Codex, and other coding agents one shared memory for how you build software. Keep your rules, workflows, and engineering taste in `~/.ai/`; sync them into any project with one command.
+dotai teaches Claude, Cursor, Gemini, Codex, and other coding agents how you build software. Keep your standards, workflows, guardrails, and engineering taste in `~/.ai/`; dotai applies only the judgment each task needs without taking ownership of team files.
 
 ```text
-                         ┌─ CLAUDE.md + native slash commands
-~/.ai/ ── dotai sync ───┼─ .cursorrules
-                         ├─ GEMINI.md
-                         └─ AGENTS.md
+~/.ai/ ── dotai context ── relevant rules + skill + role + preferences
+   │
+   └──── dotai sync ────── local context cache (outside Git repositories)
 ```
 
-No server. No account. No proprietary memory layer. Just portable Markdown that you own.
+Teach it once. Apply it when relevant. Know what influenced the agent. No server, account, or proprietary memory layer—just portable Markdown that you own.
 
-## Stop reteaching every agent
+## The short version
 
-You tell one agent “never call `useEffect` directly.” Next week, a different agent does exactly that. Your review checklist lives in one tool, your deployment workflow in another, and the correction you made yesterday disappears with the chat.
+| You want to… | Use |
+|---|---|
+| Teach agents a standard, taste, or guardrail | `dotai learn --directive` |
+| Use dotai automatically in Claude Code | `dotai agent setup claude --apply` |
+| See what Claude actually loaded | `dotai agent last claude` |
+| Resolve context manually or from automation | `dotai context` |
+| Prepare a safe per-repository cache | `dotai sync` |
 
-dotai turns those corrections into durable, reusable context:
+The default is personal and repository-safe. Team instructions stay authoritative.
 
-- **Rules are hard constraints.** Capture coding standards and scope them by project or file pattern.
+## Make every agent work like yours
+
+You prefer derived state over synchronization effects. You reproduce bugs before fixing them. You never allow credentials in logs. These are different kinds of judgment, but they all shape how you build software—and they should not disappear when you change agents.
+
+dotai turns that judgment into durable, reusable instructions:
+
+- **Rules codify decisions.** Capture standards, architectural taste, safety boundaries, and compliance requirements; scope them by project or file pattern.
 - **Skills are repeatable workflows.** Plan, investigate, review, verify, and ship the same way every time.
 - **Roles change how the agent thinks.** Review as a security engineer; plan as a product manager.
 - **Preference packs carry your taste.** Share softer choices without weakening hard rules.
-- **Sync speaks each agent's language.** Generate the bootstrap file that Claude, Cursor, Gemini, or Codex already understands.
+- **Adapters fit normal workflows.** Configure an agent once, then ask naturally while dotai resolves context behind the scenes.
 
-The useful part is the feedback loop:
+Rules can be proactive or learned from a correction:
 
 ```text
-agent makes a mistake → capture the correction → sync → every agent learns it
+teach a standard ───────────────┐
+                               ├─→ approve → resolve when relevant → verify what loaded
+correct an agent → keep lesson ┘
 ```
 
+dotai is deliberately not an autonomous history of every conversation. It is the small, developer-approved part of memory important enough to be explicit, portable, scoped, and auditable.
+
 ## See it in action
 
 ```bash
 # Set up your global knowledge base
 dotai init
 
-# Teach every agent a correction you never want to repeat
-dotai learn "no-print-debugging" \
-  --issue "Debug output was left in production code" \
-  --correction "Use structured logging and remove temporary debug output" \
-  --globs "*.py"
+# Teach every agent an engineering preference
+dotai learn "no-useeffect" \
+  --directive "Never call useEffect directly; prefer declarative alternatives" \
+  --globs "*.tsx,*.ts" \
+  --tags "react,taste"
 
-# Bring that knowledge into a project
+# Prepare that knowledge for the current project
 cd ~/my-project
 dotai sync
 ```
 
-Now the rule is available to every supported agent, alongside reusable commands such as:
+For automatic delivery in Claude Code, configure the user-level adapter once:
+
+```bash
+dotai agent setup claude
+dotai agent setup claude --apply
+```
+
+Then ask naturally. dotai routes unambiguous workflows and expands matching file-scoped rules:
 
 ```text
-/run_plan as product-manager
-/run_investigate as debugger
-/run_review as security-engineer
-/run_verify
-/run_ship
+Plan this feature as a product manager.
+Investigate this failure.
+Review the authentication changes.
+Verify the pending changes.
 ```
 
 ## Installation
@@ -121,32 +141,133 @@ dotai roles
 dotai skills
 dotai rules
 
-# Sync agent bootstrap files into a project
+# Prepare agent context for a project
 cd ~/my-project
 dotai sync
 ```
 
-This generates agent config files in your project root — `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, and `AGENTS.md`. Structured rules and freeform conventions are included in full; roles and skills are included as a compact catalog by default. For Claude Code, sync also generates `.claude/skills/` entries so skills appear as native slash commands. Use `dotai sync --full` when an agent needs every role and skill definition inline.
+`dotai sync` always writes personal context under `~/.config/dotai/contexts/` and leaves team-owned files such as `CLAUDE.md`, `AGENTS.md`, and `.claude/skills/` untouched. Existing repository instructions are copied into the local context as the authoritative layer; personal dotai rules and preferences are explicitly supplemental.
+
+Local context storage does not, by itself, make an agent load the context. Until an agent adapter is configured, use `dotai primer --path .` to print a compact bootstrap for pasting or piping into your agent.
+
+dotai uses progressive disclosure to keep prompts small. Synced context contains rule summaries and role/skill catalogs. Expand only what a task needs:
+
+```bash
+# Expand rules matching the affected files
+dotai context --path . --files src/api.py,tests/test_api.py
+
+# Expand security-tagged rules and an active CLI preference pack
+dotai context --path . --context security --domain cli
+
+# Load one complete skill and its declared role
+dotai context --path . --skill run_review
+```
+
+Selection is deterministic: file globs, explicit context tags, active preference domains, and named skills or roles. dotai does not guess from semantic similarity. Every expanded item includes the reason it was selected.
+
+### Automatic delivery with Claude Code
+
+The resolver is infrastructure; you should not have to type `dotai context`
+during normal work. Install dotai's user-level Claude adapter once:
+
+```bash
+# Preview the user-memory change
+dotai agent setup claude
+
+# Back up existing memory and install it
+dotai agent setup claude --apply
+
+# Confirm activation
+dotai agent status claude
+
+# See the most recent context Claude actually resolved
+dotai agent last claude
+```
+
+The adapter adds a small marker-managed block to `~/.claude/CLAUDE.md`, which
+Claude Code loads as user memory across projects. It tells Claude to resolve
+dotai context for substantial development work, after affected files are known,
+and to avoid repeated calls when the task has not changed. Repository and
+organization instructions remain authoritative.
+
+For file-sensitive workflows such as review, debugging, verification, scaffolding,
+maintenance, and release work, a resolution without `--files` is explicitly
+marked provisional. Claude must resolve again after discovering the affected
+files. `dotai agent last claude` reports whether the latest resolution is
+`provisional` or `complete`.
+
+The adapter does not modify repositories, install a persistent process, or use
+MCP. Existing personal Claude instructions are preserved. To remove only
+dotai's block:
+
+```bash
+dotai agent remove claude
+dotai agent remove claude --apply
+```
+
+Setup and removal preview by default. Applied changes back up the prior Claude
+memory under `~/.config/dotai/backups/agents/claude/`.
+
+`dotai agent last claude` reads a local receipt written only when the Claude
+adapter invokes the resolver. It reports selection metadata and reasons, but
+never stores source contents, expanded prompts, credentials, or telemetry.
+
+### Understanding what dotai delivered
+
+`dotai insights` aggregates local resolution receipts so you can see whether
+your engineering judgment is actually being selected:
+
+```bash
+dotai insights
+dotai insights --agent claude
+dotai insights --project my-app
+dotai insights --json
+```
+
+The report shows complete versus provisional resolutions, selection counts,
+last-selected timestamps, universal rule-summary exposure, and enabled items
+that have never been selected in the current window. Selection proves delivery,
+not compliance: dotai cannot claim that an agent followed an instruction merely
+because it received it.
+
+History contains metadata only and is stored under
+`~/.config/dotai/receipts/history/`. It never includes expanded bodies, prompts,
+source contents, or credentials. History is bounded to the latest 500 receipts
+per agent and never leaves the machine.
+
+If no receipt appears, refresh the adapter and start a new Claude Code session:
+
+```bash
+dotai agent setup claude --apply
+dotai agent status claude
+```
+
+Setup pins the dotai executable used to install the adapter, avoiding an older
+`dotai` elsewhere on `PATH`. Receipt persistence is best-effort: if its local
+directory is unavailable, Claude still receives resolved context and dotai emits
+a warning instead of blocking the task.
 
 ## Usage
 
 ### Daily workflow
 
 ```bash
-# Start of day: sync your knowledge into the project you're working on
+# Start of day: refresh local context for the project you're working on
 cd ~/my-project
 dotai sync
 
-# Or leave it running — auto-resyncs when you edit ~/.ai/ files
-dotai watch
-
-# Now open your editor — Claude Code, Cursor, Gemini, etc.
-# Your roles, skills, and rules are already loaded.
+# Print the context for an agent that does not yet have a dotai adapter
+dotai primer --path .
 ```
 
+With the Claude adapter installed, daily use is simpler: open Claude Code and
+ask for the work normally. Claude invokes the pinned dotai executable, resolves
+the workflow, and resolves again with affected files when file-scoped rules may
+apply. Use `dotai agent last claude` whenever you want to verify delivery.
+
 ### Using skills in Claude Code
 
-After `dotai sync`, skills appear as native slash commands:
+Natural-language routing is recommended with the personal adapter:
 
 ```
 > /run_plan                            # Plan before coding
@@ -164,31 +285,32 @@ After `dotai sync`, skills appear as native slash commands:
 
 ### Using skills outside Claude Code
 
-Assemble a skill prompt and pipe it into any tool:
+Resolve a skill and its role through the same context engine used by adapters:
 
 ```bash
-# Copy a skill prompt to clipboard
-dotai prompt review --role paranoid-reviewer | pbcopy
-
-# Save to a file
-dotai prompt ship > /tmp/ship-prompt.md
+dotai context --path . --skill run_review --role paranoid-reviewer
 
 # List skills filtered by category
 dotai skills --category deployment
 ```
 
-### Recording what you learn
+### Teaching your engineering judgment
 
-`dotai learn` creates a **structured rule file** in `~/.ai/rules/` by default (not a freeform journal scrap).
+`dotai learn` creates a **structured rule file** in `~/.ai/rules/` by default. Use a directive for a standard you already hold; use an issue and correction when an agent interaction teaches you something new.
 
 ```bash
+# Proactively encode engineering taste or a guardrail
+dotai learn "no-useeffect" \
+  --directive "Never call useEffect directly; prefer declarative alternatives" \
+  --globs "*.tsx,*.ts"
+
 # Preview the rule without writing
 dotai learn "auth-header" \
   --issue "Forgot Bearer prefix on API token" \
   --correction "Always prepend 'Bearer ' to auth tokens" \
   --dry-run
 
-# Save structured rule + resync agent configs
+# Save a structured rule and refresh local context
 dotai learn "auth-header" \
   -i "Forgot Bearer prefix on API token" \
   -c "Always prepend 'Bearer ' to auth tokens" \
@@ -197,11 +319,8 @@ dotai learn "auth-header" \
 # Import a detailed rule from a file
 dotai learn "no-useEffect" --from-file react-rules.md --globs "*.tsx,*.ts"
 
-# Freeform journal entry in rules.md (opt-in)
-dotai learn "note" -i "..." -c "..." --append-md
-
-# Or let the agent do it — /run_learn reviews the session and proposes a rule
-> /run_learn
+# Or ask an adapted agent naturally
+> Capture what we learned as a rule.
 
 # Disable a rule for one legacy project
 dotai toggle no-useeffect --off --project legacy-app
@@ -210,7 +329,7 @@ dotai toggle no-useeffect --off --project legacy-app
 dotai rules --check
 ```
 
-The feedback loop: **vibe-code → agent makes mistake → `/run_learn` → structured rule → `dotai sync` → agent never repeats it.**
+The loop: **teach or correct → review the structured rule → dotai resolves it for the next matching task → inspect what loaded.**
 
 ### Keeping rules healthy
 
@@ -234,14 +353,14 @@ The report includes stable finding codes, evidence, suggested actions, an estima
 # Inspect candidates
 dotai compress
 
-# Ask the current coding agent to draft, diff, and review changes
-> /run_compress
+# Ask an adapted coding agent to use the compression workflow
+> Compress and audit my dotai rules.
 
 # Low-level application boundary for an approved versioned proposal
 dotai compress apply proposal.json
 ```
 
-`/run_compress` reads the JSON plan, drafts shorter complete rules, explains what it preserved and consolidated, shows the full diff in conversation, and asks `Apply this compression? [y/N]`. It then passes only approved changes to dotai. Near-duplicates, generic guidance, and rules that may belong in a preference pack remain suggestions unless the developer explicitly approves a concrete proposal.
+The compression skill reads the JSON plan, drafts shorter complete rules, explains what it preserved and consolidated, shows the full diff in conversation, and asks `Apply this compression? [y/N]`. It then passes only approved changes to dotai. Near-duplicates, generic guidance, and rules that may belong in a preference pack remain suggestions unless the developer explicitly approves a concrete proposal.
 
 When no exact duplicates exist, compression says there are no **safe automatic** savings while still listing semantic review candidates and their estimated savings. These estimates are directional—they help prioritize review. The CLI never invents a semantic rewrite or calls an external provider.
 
@@ -288,10 +407,6 @@ dotai prefs pull ./design-eng-taste.md --name design-eng --domain design
 dotai prefs pull https://github.com/org/taste-packs -n cli
 dotai prefs use design-eng
 
-# Session overlay without changing active list
-dotai sync --with-prefs design-eng,cli
-dotai primer --with-prefs design-eng
-
 # List / show / deactivate
 dotai prefs
 dotai prefs show cli-conventions
@@ -443,7 +558,7 @@ All skill triggers use the `run_` prefix to avoid collisions with built-in agent
 | Scaffold | `/run_scaffold` | Generate boilerplate from patterns |
 | Verify | `/run_verify` | Run tests, types, lint, build |
 | Plan | `/run_plan` | Structured planning before coding |
-| Learn | `/run_learn` | Capture mistakes as permanent rules |
+| Learn | `/run_learn` | Capture engineering judgment as structured rules |
 
 ### Skill Format
 
@@ -534,7 +649,8 @@ Skills reference roles by ID — when a skill runs, the role's full persona is i
 
 ### Composing Skills with Roles
 
-Skills and roles can be composed inline. Pass `as <role>` to run any skill with a specific persona:
+Ask for a perspective naturally through an adapter, or resolve it explicitly
+with `dotai context --skill <skill> --role <role>`.
 
 ```
 /run_plan as product-manager         # Scope a feature with acceptance criteria
@@ -546,12 +662,7 @@ Skills and roles can be composed inline. Pass `as <role>` to run any skill with
 /run_review                         # Uses the skill's default role, or none
 ```
 
-From the CLI:
-
-```bash
-dotai prompt review --role paranoid-reviewer | pbcopy
-dotai prompt review --role qa > /tmp/prompt.md
-```
+The resolver expands the role and skill together and records why each was selected.
 
 ## Rules
 
@@ -601,50 +712,36 @@ dotai toggle no-useeffect --off --project my-legacy-app
 dotai toggle no-useeffect --on
 ```
 
-Structured rules are included **inline** in every synced agent file. Freeform `rules.md` is included too. Skills/roles stay as catalogs unless you pass `dotai sync --full`.
+Synced local context contains a compact bootstrap: universal rule summaries plus preference, role, and skill catalogs. Use `dotai context` to expand relevant material on demand.
 
 ## Agent Sync
 
-`dotai sync` generates tool-specific bootstrap files with:
-
-- **Full structured rule bodies** (high-value constraints)
-- **Freeform `rules.md` conventions** (previously referenced but not inlined)
-- **Role and skill catalogs** (names, triggers, descriptions — not every skill novel)
-- **Claude Code**: compact pointers + native `.claude/skills/` slash commands
+`dotai sync` prepares repository-safe local context with:
 
-Use `--full` only when you need every role persona and skill definition dumped inline (larger context).
-
-These files contain machine-specific context and may include absolute paths. Treat them as generated per-user artifacts unless your team intentionally commits shared agent instructions. dotai-managed sections are marker-delimited, so syncing preserves user-authored content outside those markers.
+- **Universal structured rule summaries** (always visible)
+- **Pointers to freeform `rules.md` conventions**
+- **Role and skill catalogs** (names, triggers, categories — not full workflows)
+Context is always written outside the worktree. Team instructions take precedence over personal dotai rules and preferences. dotai does not attempt unreliable keyword-based conflict resolution; the generated context tells the agent to ignore conflicting personal guidance and ask when a disagreement is ambiguous.
 
 ```bash
-# Generate all (CLAUDE.md + .cursorrules + GEMINI.md + AGENTS.md)
+# Generate outside the repository
 dotai sync
 
-# Generate for specific agents
-dotai sync --agents claude,cursor
-dotai sync --agents gemini
-
-# Legacy-style full dump (roles + skill definitions inline)
-dotai sync --full
+# Preview the resolved mode and target without writing
+dotai sync --check
 
 # Print primer to stdout (for piping)
 dotai primer
-dotai primer --compact
-dotai primer --full
-```
-
-### Supported Agents
-
-| Agent | Output File | Sync Command | Notes |
-|-------|-------------|--------------|-------|
-| Claude Code | `CLAUDE.md` + `.claude/skills/` | `dotai sync --agents claude` | Marker-based merging + native slash commands |
-| Cursor | `.cursorrules` | `dotai sync --agents cursor` | Full rules and preferences; role/skill catalog by default |
-| Gemini CLI | `GEMINI.md` | `dotai sync --agents gemini` | Auto-discovered in project root and `~/.gemini/GEMINI.md` |
-| Generic | `AGENTS.md` | `dotai sync --agents generic` | Works with Codex, Copilot, and any agent that reads it |
+dotai primer --path .
 
-For Claude Code, `dotai sync` also generates `.claude/skills/<trigger>/SKILL.md` files. These register as native slash commands — they appear in autocomplete and work as real `/run_*` commands with role composition support built in.
+# Resolve task-specific context on demand
+dotai context --path . --files src/app.tsx --context security
+dotai context --path . --skill run_review
+```
 
-> **Tip:** Run `dotai primer --full | pbcopy` to copy the complete context to your clipboard for pasting into an agent's system prompt.
+Use an agent adapter for automatic delivery. For an agent without an adapter,
+paste or pipe `dotai primer --path .`, then use `dotai context` for task-specific
+expansion.
 
 ## Installing Skills
 
@@ -664,7 +761,8 @@ dotai install ~/my-skills/review
 dotai install https://github.com/team/skills -p my-project
 ```
 
-After install, run `dotai sync` to make them available as slash commands in Claude Code, Gemini, etc.
+Installed skills are immediately available to `dotai context` and configured
+agent adapters.
 
 Refresh skills that were installed from a tracked source (team conventions repo):
 
@@ -675,49 +773,17 @@ dotai install --update -s mvp
 
 Updates are staged and security-vetted before installation. A blocked or declined update leaves the existing skill unchanged. Multi-skill repositories refresh each recorded skill independently. `--skip-vet` is an explicit trust override and should only be used for a source you have reviewed.
 
-### Converting Claude-native skills
-
-If you have a Claude-native `SKILL.md` and want to convert it manually:
-
-```bash
-# Preview what would be converted
-dotai convert /path/to/SKILL.md --dry-run
-
-# Convert to global skills
-dotai convert /path/to/SKILL.md
-
-# Convert to a specific project
-dotai convert /path/to/SKILL.md -p my-project
+### Installing other skill formats
 
-# Convert to a custom directory
-dotai convert /path/to/skill-dir/ -o ~/my-skills/
-```
-
-The converter maps Claude-native fields (`compatibility`, `license`) to dotai format, auto-generates a `/run_*` trigger, and infers a category from the skill's name and description.
-
-### Importing from plugin ecosystems
-
-dotai can import skills from **Claude plugins**, **Cursor plugins**, and **Gemini extensions** — converting them into universal dotai format so they work across all tools.
+`dotai install` detects dotai skills, Claude-native `SKILL.md` files, Claude
+plugins, Cursor plugins, and Gemini extensions. Supported skills and commands
+are converted automatically:
 
 ```bash
-# Import from a Claude Code plugin
-dotai import-plugin /path/to/claude-plugin/
-dotai import-plugin https://github.com/user/claude-plugin
-
-# Import from a Cursor plugin
-dotai import-plugin /path/to/cursor-plugin/
-
-# Import from a Gemini CLI extension
-dotai import-plugin /path/to/gemini-extension/
-
-# Import only a specific skill from a plugin
-dotai import-plugin /path/to/plugin/ -s review-code
-
-# Also convert agents to dotai roles
-dotai import-plugin /path/to/plugin/ --include-agents
-
-# Also convert Cursor .mdc rules to dotai rules
-dotai import-plugin /path/to/cursor-plugin/ --include-rules
+dotai install /path/to/SKILL.md
+dotai install /path/to/claude-plugin/
+dotai install /path/to/cursor-plugin/
+dotai install /path/to/gemini-extension/
 ```
 
 Supported plugin formats:
@@ -725,7 +791,7 @@ Supported plugin formats:
 - **Cursor plugins** — directories with `.cursor-plugin/plugin.json`
 - **Gemini extensions** — directories with `gemini-extension.json`
 
-The importer discovers skills, commands, agents, and rules within the plugin and converts each to dotai format. Hooks and MCP server configs are noted but not converted (they're tool-specific).
+Hooks and MCP server configurations remain tool-specific and are not installed.
 
 ### Removing skills
 
@@ -765,35 +831,31 @@ dotai new-skill "Deploy" -t /run_deploy -c deployment --folder
 ```bash
 dotai init [project-path]              # Initialize ~/.ai/ or project .ai/
 dotai roles                            # List available roles
-dotai role <name>                      # Output a role's full prompt to stdout
 dotai skills [-c category]             # List skills (optionally filter by category)
-dotai prompt <skill> [--role <role>]   # Assemble skill + role prompt for any agent
-dotai sync [path] [--agents ...] [--full]  # Sync ~/.ai/ into agent config files
-dotai primer [--project <name>] [--full|--compact]  # Print agent context to stdout
+dotai sync [path] [--check]            # Refresh safe local context
+dotai agent setup|status|last|remove claude [--apply]  # User-level Claude delivery
+dotai insights [--agent name] [-p project] [--json]  # Local delivery evidence
+dotai primer [--project <name>|--path <path>]  # Compact generic bootstrap
+dotai context --path <path> [--task ...] [--files ...] [--context ...] [--domain ...] [--skill ...]
 dotai rules [-p project] [-a] [--check]    # List rules (or audit quality)
 dotai audit [-p project] [--json] [--fail-on severity]  # Read-only rule audit
 dotai compress [-p project] [--json]       # Plan compression candidates
 dotai compress apply <proposal.json> [--yes]  # Validate, back up, and apply proposals
 dotai toggle <rule-id> --on/--off      # Enable/disable rules globally or per-project
-dotai learn "title" -i "..." -c "..."  # Create structured rule (default)
-dotai learn "title" -i "..." -c "..." --dry-run|--sync|--force|--append-md
+dotai learn "title" --directive "..."    # Teach a standard, taste, or guardrail
+dotai learn "title" -i "..." -c "..."  # Preserve a correction as a rule
+dotai learn "title" -i "..." -c "..." --dry-run|--sync|--force
 dotai learn "title" --from-file <f>    # Import structured rule from a file
 dotai import-agent <path> [-m mode] [--dry-run]  # Non-destructive agent-file migration
 dotai prefs [list|show|new|pull|use|unuse|remove]  # Preference / taste packs
 dotai prefs new "CLI" --domain cli     # Create a soft style pack
 dotai prefs pull <path|url> [-n id]    # Borrow / install a pack
 dotai prefs use <id> [-p project|--global]  # Activate pack in an explicit scope
-dotai sync --with-prefs a,b            # Session overlay of preference packs
 dotai install <source> [-s skill]      # Install skills from git repo or local path
 dotai install --update [-s skill] [--skip-vet]  # Vetted refresh from recorded sources
-dotai import-plugin <source>          # Import from Claude/Cursor/Gemini plugin
 dotai remove <skill> [-p project]     # Remove an installed skill
-dotai convert <path> [--dry-run]      # Convert Claude-native SKILL.md to dotai format
 dotai new-skill <name> [-t trigger]    # Create a new skill from template
-dotai watch [path] [--agents ...]       # Auto-resync on ~/.ai/ changes
-dotai search "query" [--type t] [--tag] # Search knowledge index
-dotai index [--refresh]                # Build/show knowledge index
-dotai tree                             # Show knowledge tree
+dotai search "query" [--type t] [--tag] # Search live knowledge
 ```
 
 ## Philosophy