dotai-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{dotai_cli-0.3.0 → dotai_cli-0.5.0}/.gitignore

@@ -13,3 +13,4 @@ CLAUDE.md
 .cursorrules
 AGENTS.md
 GEMINI.md
+.dotai-compression-proposal.json

{dotai_cli-0.3.0 → dotai_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotai-cli
-Version: 0.3.0
+Version: 0.5.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
@@ -29,29 +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:
+
+```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
 
-- **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 (hard constraints)
-- **Preference packs** — Soft, borrowable taste (CLI stack, design micro-style); never override hard rules
-- **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
+# 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"
+
+# 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:
+
+```text
+/run_plan as product-manager
+/run_investigate as debugger
+/run_review as security-engineer
+/run_verify
+/run_ship
+```
 
 ## Installation
 
@@ -87,32 +121,113 @@ 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.
+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.
+
+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.
+
+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.
+
+### Moving an existing repository to local mode
+
+If an older dotai version wrote generated context into repository files, use the
+one-off detach command. It previews by default:
+
+```bash
+dotai detach
+dotai detach --apply
+```
+
+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.
 
 ## 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 .
 ```
 
 ### Using skills in Claude Code
 
-After `dotai sync`, skills appear as native slash commands:
+After an explicit shared Claude sync (`dotai sync --shared --agents claude`), skills appear as native slash commands:
 
 ```
 > /run_plan                            # Plan before coding
@@ -125,6 +240,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
@@ -177,6 +293,41 @@ 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/`:
@@ -298,6 +449,7 @@ dotai init ~/other-project
 ├── 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
@@ -322,6 +474,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/
@@ -529,25 +682,31 @@ 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 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.
 
 ## Agent Sync
 
-`dotai sync` generates tool-specific bootstrap files with:
+`dotai sync` prepares tool-specific context 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)
+- **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).
 
-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.
+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.
 
 ```bash
-# Generate all (CLAUDE.md + .cursorrules + GEMINI.md + AGENTS.md)
+# Safe default in Git: 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
@@ -557,18 +716,22 @@ dotai sync --full
 
 # Print primer to stdout (for piping)
 dotai primer
-dotai primer --compact
+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 | `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 |
+| 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.
 
@@ -696,9 +859,15 @@ 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] [--local|--shared] [--check] [--agents ...] [--full]
+dotai detach [path] [--apply]            # One-off removal of old shared-sync artifacts
+dotai agent setup|status|last|remove claude [--apply]  # User-level Claude delivery
+dotai primer [--project <name>|--path <path>] [--full]
+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