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

{dotai_cli-0.2.0 → dotai_cli-0.4.0}/.gitignore

@@ -9,6 +9,8 @@ build/
 
 # dotai sync outputs (generated per-user, run `dotai sync` to regenerate)
 .claude/skills/
+CLAUDE.md
 .cursorrules
 AGENTS.md
 GEMINI.md
+.dotai-compression-proposal.json

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotai-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Universal AI context for any coding agent. Roles, skills, and rules in ~/.ai/
 Project-URL: Homepage, https://github.com/dawalama/dotai
 Project-URL: Repository, https://github.com/dawalama/dotai
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.11
-Requires-Dist: ai-skill-audit>=0.4.0
+Requires-Dist: ai-skill-audit>=0.5.1
 Requires-Dist: pydantic>=2.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.9
@@ -29,28 +29,63 @@ Description-Content-Type: text/markdown
 
 # dotai
 
-Universal AI context for any coding agent. Roles, skills, and rules in `~/.ai/`.
+**Your coding agents should remember what you taught them.**
 
-## The Problem
+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.
 
-Every AI coding tool has its own way to store context:
+```text
+                         ┌─ CLAUDE.md + native slash commands
+~/.ai/ ── dotai sync ───┼─ .cursorrules
+                         ├─ GEMINI.md
+                         └─ AGENTS.md
+```
+
+No server. No account. No proprietary memory layer. Just portable Markdown that you own.
+
+## Stop reteaching every agent
 
-- Claude Code → `CLAUDE.md`
-- Cursor → `.cursorrules`
-- Gemini CLI → `GEMINI.md`
-- Codex / Copilot → `AGENTS.md`
+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.
 
-Your knowledge about how to write code, review it, ship it, and debug it gets scattered across tool-specific formats — or worse, stays in your head.
+dotai turns those corrections into durable, reusable context:
 
-## The Solution
+- **Rules are hard constraints.** Capture coding standards and 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.
 
-`dotai` defines a universal `~/.ai/` directory convention that any tool can consume. It ships with:
+The useful part is the feedback loop:
 
-- **Roles** — Cognitive modes that shift how the AI thinks (reviewer, architect, founder, QA, etc.)
-- **Skills** — Reusable workflows with steps, inputs, gotchas, and role references
-- **Rules** — Structured coding standards with per-project toggles and file-pattern scoping
-- **Agent sync** — Generate `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, or `AGENTS.md` from your `~/.ai/`
-- **Native slash commands** — For Claude Code, skills become real `/run_*` commands automatically
+```text
+agent makes a mistake → capture the correction → sync → every agent learns it
+```
+
+## 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"
+
+# Bring that knowledge into a project
+cd ~/my-project
+dotai sync
+```
+
+Now the rule is available to every supported agent, alongside reusable commands such as:
+
+```text
+/run_plan as product-manager
+/run_investigate as debugger
+/run_review as security-engineer
+/run_verify
+/run_ship
+```
 
 ## Installation
 
@@ -91,7 +126,7 @@ cd ~/my-project
 dotai sync
 ```
 
-This generates agent config files in your project root — `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, and `AGENTS.md` — each with your complete knowledge context inline. For Claude Code, it also generates `.claude/skills/` entries so your skills appear as native slash commands.
+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.
 
 ## Usage
 
@@ -124,6 +159,7 @@ After `dotai sync`, skills appear as native slash commands:
 > /run_careful                         # Enter production-safety mode
 > /run_verify                          # Run tests, types, lint, build
 > /run_learn                           # Capture a mistake as a permanent rule
+> /run_compress                        # Draft and review smaller rule definitions
 ```
 
 ### Using skills outside Claude Code
@@ -143,23 +179,157 @@ dotai skills --category deployment
 
 ### Recording what you learn
 
+`dotai learn` creates a **structured rule file** in `~/.ai/rules/` by default (not a freeform journal scrap).
+
 ```bash
-# Something went wrong — record it so the AI never repeats it
+# Preview the rule without writing
 dotai learn "auth-header" \
   --issue "Forgot Bearer prefix on API token" \
-  --correction "Always prepend 'Bearer ' to auth tokens"
+  --correction "Always prepend 'Bearer ' to auth tokens" \
+  --dry-run
 
-# Or let the agent do it — /run_learn reviews the session and proposes a rule
-> /run_learn
+# Save structured rule + resync agent configs
+dotai learn "auth-header" \
+  -i "Forgot Bearer prefix on API token" \
+  -c "Always prepend 'Bearer ' to auth tokens" \
+  --sync
 
 # 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
+
 # Disable a rule for one legacy project
 dotai toggle no-useeffect --off --project legacy-app
+
+# Audit rule quality (duplicates, empty bodies)
+dotai rules --check
+```
+
+The feedback loop: **vibe-code → agent makes mistake → `/run_learn` → structured rule → `dotai sync` → agent never repeats it.**
+
+### Keeping rules healthy
+
+Knowledge gets noisy as it grows. `dotai audit` reviews the effective ruleset locally and deterministically—nothing is sent to an external model.
+
+```bash
+# Find weak, generic, preference-like, oversized, or overlapping rules
+dotai audit
+dotai audit --project my-app
+
+# Machine-readable output or a CI quality gate
+dotai audit --json
+dotai audit --fail-on high
+```
+
+The report includes stable finding codes, evidence, suggested actions, an estimated prompt-token cost, and a context-concentration summary showing which rules dominate the budget. Large-rule findings show the rule's share of total context, change risk, reviewable sections, and a conservative manual-savings range. Security and other high-consequence rules receive preservation-first guidance and are deliberately protected from “the model probably knows this” recommendations.
+
+`dotai compress` turns high-confidence findings into a conservative plan. Semantic rewriting is handled by the active coding agent, not a hidden provider inside the CLI:
+
+```bash
+# Inspect candidates
+dotai compress
+
+# Ask the current coding agent to draft, diff, and review changes
+> /run_compress
+
+# 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.
+
+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.
+
+Proposal files are versioned and bound to the original rule with a SHA-256 hash, so stale or renamed rules are rejected. Before applying approved changes, dotai validates every proposed rule and creates a complete timestamped snapshot under the applicable `.ai/backups/<timestamp>-compress/`. After writing, the manifest is finalized with actual before/after hashes, per-rule token savings, total savings, and completion status. Subsequent audits show recently compressed rules and clearly note when a successful reduction remains above the large-rule threshold. Backups are ordinary local files and are never deleted automatically.
+
+### Migrating existing agent files
+
+Already have a `CLAUDE.md`, `.cursorrules`, or `AGENTS.md`? Import user-authored content into `~/.ai/`:
+
+```bash
+# Preview
+dotai import-agent CLAUDE.md --dry-run
+
+# Append into project .ai/rules.md (default)
+dotai import-agent CLAUDE.md
+
+# One structured rule
+dotai import-agent .cursorrules --mode rule --name project-conventions
+
+# One rule per ## section
+dotai import-agent AGENTS.md --mode sections --dry-run
+
+# Scan a project directory for known agent files
+dotai import-agent . --mode rules_md
+```
+
+dotai strips its own managed marker sections so you don't re-import generated primers. Directory imports combine all discovered agent files into one update, and structured-rule imports choose a new suffixed filename rather than overwrite an existing rule. Preview unfamiliar files with `--dry-run` before importing.
+
+### Preference packs (taste) — borrowable soft style
+
+Hard rules are law. **Preference packs** are soft taste: CLI stack, design micro-details, export style — things that are too granular or fluid for hard rules. You can author them, pull someone else's, and activate them per project.
+
+**Precedence:** hard rules → freeform `rules.md` → active preference packs → model default.
+
+```bash
+# Create a pack
+dotai prefs new "CLI Conventions" --domain cli
+# Edit ~/.ai/preferences/cli-conventions.md, then activate:
+dotai prefs use cli-conventions
+dotai sync
+
+# Borrow / pull someone else's taste (local file or git repo)
+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
+dotai prefs unuse design-eng
+
+# Project operations stay inside that project; global removal is explicit
+dotai prefs use cli-conventions --project my-app
+dotai prefs remove cli-conventions --global
 ```
 
-The feedback loop: **vibe-code → agent makes mistake → `/run_learn` → rule created → next sync → agent never repeats it.** Your agent gets smarter every session.
+Preference lookup and removal are scope-safe: a project command cannot mutate a pack owned by another registered project. Removing a pack also removes it from the activation list for the pack's owning scope.
+
+Example pack (`~/.ai/preferences/cli.md`):
+
+```markdown
+---
+name: CLI Conventions
+id: cli
+description: How I build CLIs
+domain: cli
+tags: typescript, commander
+---
+
+## Soft preferences
+
+Hard rules always take precedence if they conflict.
+
+### Stack
+- TypeScript + tsup
+- Commander.js
+- Vitest
+- pnpm (npm link for local bins)
+
+### Style
+- Lowercase `-v` for version
+- Start version at `0.0.1`
+- Commands live under `commands/`
+```
 
 ### Searching your knowledge
 
@@ -193,8 +363,12 @@ dotai init ~/other-project
 ```
 ~/.ai/                          # Global (cross-project)
 ├── rules.md                    # Inline rules, conventions, and lessons learned
-├── rules/                      # Structured rules (individual files)
+├── rules/                      # Structured rules (hard constraints)
 │   └── no-useeffect.md         # Example: ban useEffect in React
+├── preferences/                # Soft taste packs (borrowable style priors)
+│   └── cli.md                  # Example: CLI stack / micro-style
+├── preferences-active.json     # Which preference packs are active
+├── backups/                    # Local snapshots created before compression writes
 ├── roles/                      # Cognitive modes
 │   ├── reviewer.md             # Paranoid staff engineer
 │   ├── architect.md            # Systems thinker
@@ -219,6 +393,7 @@ dotai init ~/other-project
 │   ├── verify.md               # Run tests, types, lint (/run_verify)
 │   ├── plan.md                 # Structured planning workflow (/run_plan)
 │   ├── learn.md                # Capture learnings as rules (/run_learn)
+│   ├── compress.md             # Review semantic rule compression (/run_compress)
 │   └── deploy/                 # Folder-based skill (with scripts & assets)
 │       ├── main.md
 │       ├── scripts/
@@ -404,12 +579,18 @@ All useEffect usage must be replaced with declarative patterns...
 # List active rules
 dotai rules
 
+# Audit duplicates / empty bodies
+dotai rules --check
+
 # Import a rule from an external file
 dotai learn "no-useEffect" --from-file react-rule.md --globs "*.tsx,*.ts"
 
-# Record an inline learning
+# Record a learning as a structured rule (default)
 dotai learn "auth-header" --issue "Forgot Bearer prefix" --correction "Always prepend Bearer to tokens"
 
+# Preview first
+dotai learn "auth-header" -i "..." -c "..." --dry-run
+
 # Disable a rule globally
 dotai toggle no-useeffect --off
 
@@ -420,11 +601,20 @@ dotai toggle no-useeffect --off --project my-legacy-app
 dotai toggle no-useeffect --on
 ```
 
-Rules are included inline in every synced agent file, so agents that can't read external files still get the full rule content.
+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`.
 
 ## Agent Sync
 
-`dotai sync` generates tool-specific bootstrap files with **full inline content** — every rule body, role persona, skill definition, and gotcha is embedded so agents that can't read external files still get everything.
+`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
+
+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.
 
 ```bash
 # Generate all (CLAUDE.md + .cursorrules + GEMINI.md + AGENTS.md)
@@ -434,8 +624,13 @@ dotai sync
 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 --compact
+dotai primer --full
 ```
 
 ### Supported Agents
@@ -443,17 +638,17 @@ dotai primer
 | 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 context inline |
+| 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 |
 
 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 | pbcopy` to copy the full context to your clipboard for pasting into any agent's system prompt.
+> **Tip:** Run `dotai primer --full | pbcopy` to copy the complete context to your clipboard for pasting into an agent's system prompt.
 
 ## Installing Skills
 
-Install skills from git repos or local directories. Claude-native `SKILL.md` files are auto-detected and converted to dotai format with triggers and categories inferred from the content.
+Install skills from git repos or local directories. Claude-native `SKILL.md` files are auto-detected and converted to dotai format with triggers and categories inferred from the content. New installs are security-vetted before use.
 
 ```bash
 # Install from a GitHub repo — auto-detects and converts Claude-native skills
@@ -471,6 +666,15 @@ 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.
 
+Refresh skills that were installed from a tracked source (team conventions repo):
+
+```bash
+dotai install --update
+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:
@@ -564,13 +768,24 @@ 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 ...]       # Sync ~/.ai/ into agent config files
-dotai primer [--project <name>]        # Print full agent context to stdout
-dotai rules [-p project] [-a]          # List rules (resolved or all)
+dotai sync [path] [--agents ...] [--full]  # Sync ~/.ai/ into agent config files
+dotai primer [--project <name>] [--full|--compact]  # Print agent context to stdout
+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" --from-file <f>    # Import structured rule from a file
-dotai learn "title" -i "..." -c "..."  # Record an inline learning
+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