dotai-cli 0.5.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.5.0 → dotai_cli-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dotai-cli
-Version: 0.5.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"
 
 # 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
@@ -126,9 +146,9 @@ cd ~/my-project
 dotai sync
 ```
 
-Inside a Git repository, `dotai sync` defaults to **local mode**. It 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.
+`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 context for pasting or piping into your agent. Use `dotai sync --shared` only when your team has intentionally chosen to maintain dotai sections in repository files.
+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:
 
@@ -192,22 +212,40 @@ memory under `~/.config/dotai/backups/agents/claude/`.
 adapter invokes the resolver. It reports selection metadata and reasons, but
 never stores source contents, expanded prompts, credentials, or telemetry.
 
-### Moving an existing repository to local mode
+### Understanding what dotai delivered
 
-If an older dotai version wrote generated context into repository files, use the
-one-off detach command. It previews by default:
+`dotai insights` aggregates local resolution receipts so you can see whether
+your engineering judgment is actually being selected:
 
 ```bash
-dotai detach
-dotai detach --apply
+dotai insights
+dotai insights --agent claude
+dotai insights --project my-app
+dotai insights --json
 ```
 
-Detach removes only complete `<!-- dotai:start -->` blocks and Claude skill
-directories whose `SKILL.md` contains dotai's generated marker. Loader files
-containing team content are preserved and updated in place; files containing
-only generated dotai content are removed. Before applying changes, dotai copies
-every affected artifact to `~/.config/dotai/backups/detach/`. Detach is not part
-of routine sync and does not need to be run again after migration.
+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
 
@@ -218,16 +256,18 @@ of routine sync and does not need to be run again after migration.
 cd ~/my-project
 dotai sync
 
-# Or leave it running — auto-resyncs when you edit ~/.ai/ files
-dotai watch
-
 # 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 an explicit shared Claude sync (`dotai sync --shared --agents claude`), skills appear as native slash commands:
+Natural-language routing is recommended with the personal adapter:
 
 ```
 > /run_plan                            # Plan before coding
@@ -245,31 +285,32 @@ After an explicit shared Claude sync (`dotai sync --shared --agents claude`), sk
 
 ### 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" \
@@ -278,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
@@ -291,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
 
@@ -315,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.
 
@@ -369,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
@@ -524,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
 
@@ -615,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
@@ -627,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
 
@@ -682,60 +712,36 @@ dotai toggle no-useeffect --off --project my-legacy-app
 dotai toggle no-useeffect --on
 ```
 
-Synced agent files contain a compact bootstrap by default: universal rule summaries plus preference, role, and skill catalogs. Use `dotai context` to expand relevant material on demand, or pass `dotai sync --full` for the legacy complete inline context.
+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` prepares tool-specific context with:
+`dotai sync` prepares repository-safe local context with:
 
 - **Universal structured rule summaries** (always visible)
 - **Pointers to freeform `rules.md` conventions**
 - **Role and skill catalogs** (names, triggers, categories — not full workflows)
-- **Claude Code**: compact pointers + native `.claude/skills/` slash commands
-
-Use `--full` only when you need every role persona and skill definition dumped inline (larger context).
-
-In a Git repository, local mode is the default and writes 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.
+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
-# Safe default in Git: generate outside the repository
+# Generate outside the repository
 dotai sync
 
 # Preview the resolved mode and target without writing
 dotai sync --check
 
-# Explicit team-owned mode: update marked sections in repository files
-dotai sync --shared
-
-# Generate for specific agents
-dotai sync --agents claude,cursor
-dotai sync --agents gemini
-
-# Legacy-style full dump (roles + skill definitions inline)
-dotai sync --full
-
 # Print primer to stdout (for piping)
 dotai primer
 dotai primer --path .
-dotai primer --full
 
 # Resolve task-specific context on demand
 dotai context --path . --files src/app.tsx --context security
 dotai context --path . --skill run_review
 ```
 
-### Supported Agents
-
-| Agent | Output File | Sync Command | Notes |
-|-------|-------------|--------------|-------|
-| Claude Code | Local cache; shared: `CLAUDE.md` + `.claude/skills/` | `dotai sync --agents claude` | Team file is authoritative; shared mode uses marker-based merging |
-| Cursor | `.cursorrules` | `dotai sync --agents cursor` | Compact bootstrap by default; full context with `--full` |
-| Gemini CLI | `GEMINI.md` | `dotai sync --agents gemini` | Compact bootstrap; shared files are auto-discovered by Gemini CLI |
-| Generic | `AGENTS.md` | `dotai sync --agents generic` | Compact bootstrap for agents that read `AGENTS.md` |
-
-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.
-
-> **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
 
@@ -755,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):
 
@@ -766,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
-
-# 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.
+### Installing other skill formats
 
-### 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:
@@ -816,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
 
@@ -856,38 +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] [--local|--shared] [--check] [--agents ...] [--full]
-dotai detach [path] [--apply]            # One-off removal of old shared-sync artifacts
+dotai sync [path] [--check]            # Refresh safe local context
 dotai agent setup|status|last|remove claude [--apply]  # User-level Claude delivery
-dotai primer [--project <name>|--path <path>] [--full]
+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

dotai_cli-0.6.0/PRODUCT.md

@@ -0,0 +1,93 @@
+# Product direction
+
+## Purpose
+
+dotai carries a developer's engineering judgment across coding agents.
+
+Engineering judgment includes standards, architectural choices, personal taste,
+safety and compliance guardrails, repeatable workflows, and lessons deliberately
+retained from prior work.
+
+> Teach it once. Apply it when relevant. Know what influenced the agent.
+
+## User
+
+The initial user is an individual developer who uses more than one coding agent,
+works across multiple repositories, or cares enough about their development style
+to make it explicit. They should not need a platform, team rollout, or hosted
+memory service to get value.
+
+## Product loop
+
+1. **Capture** a standard, preference, workflow, or correction.
+2. **Approve** what becomes durable developer knowledge.
+3. **Resolve** the minimum relevant knowledge for a task and its affected files.
+4. **Deliver** it through an adapter or explicit context command.
+5. **Explain** what was selected and why.
+6. **Audit** knowledge that is stale, conflicting, oversized, or ineffective.
+7. **Retire** knowledge without losing control of its source or history.
+
+## Product principles
+
+1. **Developer-approved, never silently learned.** Agents may propose knowledge;
+   only the developer promotes it into durable context.
+2. **Selective, not exhaustive.** Always-on context is a cost. Load the smallest
+   relevant set while keeping mandatory guardrails dependable.
+3. **Explicit before inferred.** File scopes, tags, task aliases, and precedence
+   remain inspectable. Opaque semantic retrieval cannot be the only path for
+   security or compliance rules.
+4. **Team instructions remain authoritative.** Personal judgment supplements a
+   repository; it does not silently take ownership of shared agent files.
+5. **Portable and local first.** Knowledge remains readable, versionable files.
+   Core behavior does not require a server, account, or network request.
+6. **Observable.** A developer can determine which knowledge was selected, why it
+   was selected, and whether resolution was provisional.
+7. **One canonical path.** `context` resolves judgment, adapters deliver it, and
+   `sync` only prepares a safe local cache. Avoid parallel prompt, index, watcher,
+   and repository-mutation workflows.
+
+## Near-term roadmap
+
+### Now: make judgment first-class
+
+- Let developers capture proactive directives as well as corrections.
+- Describe rules as codified judgment rather than only mistake prevention.
+- Preserve the hard-rule versus soft-preference distinction.
+- Keep adapters automatic and resolution explainable.
+- Derive local usage counts, last-selected timestamps, and unused knowledge from
+  bounded metadata-only receipt history.
+
+### Next: propose improvements
+
+- Let agents draft proposed lessons from explicit developer corrections, with a
+  mandatory preview and approval step.
+- Add another adapter only where it removes repeated setup for real users.
+
+### Later, only with evidence
+
+- Effectiveness signals beyond selection counts.
+- More expressive conflict reporting between personal and team instructions.
+- Optional semantic discovery as a convenience layer, never as the sole path for
+  mandatory rules.
+
+## Explicit non-goals
+
+dotai is not currently a transcript store, general-purpose agent memory, goal
+manager, agent orchestrator, autonomous self-editing instruction system, hosted
+vector database, production-agent observability platform, or replacement for
+repository and organization policy.
+
+## Decision test
+
+A feature belongs in dotai when it makes developer judgment easier to capture,
+selectively apply, verify, maintain, or carry across agents. It should also reduce
+repeated correction or setup without making every interaction heavier. Features
+that merely accumulate history or orchestrate agents need separate evidence.
+
+## Success signals
+
+- A developer teaches a rule once and sees it applied by another agent.
+- Relevant context stays small as the knowledge base grows.
+- Users can explain why a rule, preference, role, or skill was selected.
+- Audit and usage information causes users to improve or retire knowledge.
+- dotai saves more repeated correction time than it adds in maintenance.