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

{dotai_cli-0.3.0 → dotai_cli-0.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotai-cli
-Version: 0.3.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
@@ -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
+
+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.
+
+dotai turns those corrections into durable, reusable context:
+
+- **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.
+
+The useful part is the feedback loop:
+
+```text
+agent makes a mistake → capture the correction → sync → every agent learns it
+```
+
+## See it in action
 
-- Claude Code → `CLAUDE.md`
-- Cursor → `.cursorrules`
-- Gemini CLI → `GEMINI.md`
-- Codex / Copilot → `AGENTS.md`
+```bash
+# Set up your global knowledge base
+dotai init
 
-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.
+# 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"
 
-## The Solution
+# Bring that knowledge into a project
+cd ~/my-project
+dotai sync
+```
 
-`dotai` defines a universal `~/.ai/` directory convention that any tool can consume. It ships with:
+Now the rule is available to every supported agent, alongside reusable commands such as:
 
-- **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
+```text
+/run_plan as product-manager
+/run_investigate as debugger
+/run_review as security-engineer
+/run_verify
+/run_ship
+```
 
 ## Installation
 
@@ -125,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
@@ -177,6 +212,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 +368,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 +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/
@@ -699,6 +771,9 @@ dotai prompt <skill> [--role <role>]   # Assemble skill + role prompt for any ag
 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_cli-0.3.0 → dotai_cli-0.4.0}/README.md

@@ -1,28 +1,62 @@
 # 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
+
+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.
+
+dotai turns those corrections into durable, reusable context:
+
+- **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.
+
+The useful part is the feedback loop:
+
+```text
+agent makes a mistake → capture the correction → sync → every agent learns it
+```
+
+## See it in action
 
-- Claude Code → `CLAUDE.md`
-- Cursor → `.cursorrules`
-- Gemini CLI → `GEMINI.md`
-- Codex / Copilot → `AGENTS.md`
+```bash
+# Set up your global knowledge base
+dotai init
 
-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.
+# 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"
 
-## The Solution
+# Bring that knowledge into a project
+cd ~/my-project
+dotai sync
+```
 
-`dotai` defines a universal `~/.ai/` directory convention that any tool can consume. It ships with:
+Now the rule is available to every supported agent, alongside reusable commands such as:
 
-- **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
+```text
+/run_plan as product-manager
+/run_investigate as debugger
+/run_review as security-engineer
+/run_verify
+/run_ship
+```
 
 ## Installation
 
@@ -96,6 +130,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
@@ -148,6 +183,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/`:
@@ -269,6 +339,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
@@ -293,6 +364,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/
@@ -670,6 +742,9 @@ dotai prompt <skill> [--role <role>]   # Assemble skill + role prompt for any ag
 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_cli-0.3.0 → dotai_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dotai-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Universal AI context for any coding agent. Roles, skills, and rules in ~/.ai/"
 readme = "README.md"
 license = "MIT"

{dotai_cli-0.3.0 → dotai_cli-0.4.0}/src/dotai/__init__.py

@@ -1,3 +1,3 @@
 """dotai — Universal AI context for any coding agent."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{dotai_cli-0.3.0 → dotai_cli-0.4.0}/src/dotai/cli/rules_cmd.py

@@ -10,6 +10,261 @@ from rich.table import Table
 from . import app, console
 
 
+@app.command()
+def audit(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Audit rules effective for a registered project"),
+    all: bool = typer.Option(False, "--all", "-a", help="Include disabled rules"),
+    json_output: bool = typer.Option(False, "--json", help="Emit a machine-readable report"),
+    fail_on: Optional[str] = typer.Option(None, "--fail-on", help="Exit non-zero at or above: low, medium, high"),
+):
+    """Audit rule quality, overlap, scope, and estimated context cost.
+
+    The audit is deterministic, local, and read-only. No rule content is sent
+    to an external service.
+    """
+    import json
+
+    from ..maintenance import SEVERITY_ORDER, audit_rules
+    from ..store import load_config
+
+    if fail_on and fail_on not in ("low", "medium", "high"):
+        console.print("[red]--fail-on must be one of: low, medium, high[/red]")
+        raise typer.Exit(2)
+
+    config = load_config()
+    if project and not config.get_project(project):
+        console.print(f"[red]Project '{project}' not found[/red]")
+        raise typer.Exit(1)
+    report = audit_rules(config, project_name=project, include_disabled=all)
+
+    if json_output:
+        console.print_json(json.dumps(report.to_dict()))
+    else:
+        console.print(
+            f"[bold]Rule audit[/bold] · {report.scope} · "
+            f"{report.rule_count} rules · ~{report.estimated_tokens} tokens"
+        )
+        top_metrics = report.rule_metrics[:3]
+        if len(top_metrics) >= 2 and report.estimated_tokens:
+            concentrated = sum(metric.estimated_tokens for metric in top_metrics)
+            percentage = concentrated / report.estimated_tokens * 100
+            names = ", ".join(metric.rule_id for metric in top_metrics)
+            console.print(
+                f"[bold]Context concentration:[/bold] top {len(top_metrics)} rules consume "
+                f"~{concentrated} tokens ({percentage:.0f}%): {names}"
+            )
+        recent_metrics = [metric for metric in report.rule_metrics if metric.recent_saved_tokens]
+        if recent_metrics:
+            console.print("[bold]Recent compression:[/bold]")
+            for metric in recent_metrics:
+                percentage = (
+                    metric.recent_saved_tokens / metric.recent_before_tokens * 100
+                    if metric.recent_before_tokens
+                    else 0
+                )
+                console.print(
+                    f"  {metric.rule_id}: ~{metric.recent_before_tokens} → "
+                    f"~{metric.estimated_tokens} tokens "
+                    f"([green]-{metric.recent_saved_tokens}, {percentage:.0f}%[/green])"
+                )
+        if not report.findings:
+            console.print("[green]No deterministic rule quality issues found.[/green]")
+        else:
+            console.print("\n[bold]Findings[/bold]")
+            for finding in report.findings:
+                color = {"high": "red", "medium": "yellow", "low": "blue", "info": "dim"}[finding.severity]
+                console.print(
+                    f"[{color}]{finding.severity.upper()}[/{color}] "
+                    f"[cyan]{finding.code}[/cyan] · {', '.join(finding.rule_ids)}"
+                )
+                console.print(f"  {finding.message}")
+                if finding.evidence:
+                    console.print(f"  [dim]{finding.evidence}[/dim]")
+                console.print(f"  [bold]Next:[/bold] {finding.suggestion}\n")
+
+    if fail_on:
+        threshold = SEVERITY_ORDER[fail_on]
+        if any(SEVERITY_ORDER[finding.severity] >= threshold for finding in report.findings):
+            raise typer.Exit(1)
+
+
+@app.command()
+def compress(
+    action: Optional[str] = typer.Argument(None, help="Optional action: apply"),
+    proposal: Optional[Path] = typer.Argument(None, help="Versioned JSON proposal file for the apply action"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Compress a registered project's local rules"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show candidates without applying exact duplicates"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Apply an already-approved proposal without another prompt"),
+    json_output: bool = typer.Option(False, "--json", help="Emit a machine-readable compression plan"),
+):
+    """Plan compression or safely apply an agent-generated proposal.
+
+    Run without an action to inspect candidates. Use `compress apply FILE` to
+    validate a versioned proposal, show its diffs, back up the rules, and apply
+    only approved changes.
+    """
+    import difflib
+    import json
+    import sys
+
+    from ..maintenance import (
+        apply_compression_plan,
+        build_compression_plan,
+        create_compression_backup,
+        estimate_tokens,
+        finalize_compression_backup,
+        load_compression_proposal,
+        write_reviewed_rule,
+    )
+    from ..store import load_config
+
+    config = load_config()
+    if project and not config.get_project(project):
+        console.print(f"[red]Project '{project}' not found[/red]")
+        raise typer.Exit(1)
+    plan = build_compression_plan(config, project_name=project)
+
+    if action:
+        if action != "apply" or not proposal:
+            console.print("[red]Usage: dotai compress apply <proposal.json> [--project NAME] [--yes][/red]")
+            raise typer.Exit(2)
+        try:
+            loaded = load_compression_proposal(proposal, config, project_name=project)
+        except ValueError as error:
+            console.print(f"[red]Invalid compression proposal: {error}[/red]")
+            raise typer.Exit(1)
+
+        approved = []
+        for change in loaded.changes:
+            original = change.source_path.read_text()
+            before = estimate_tokens(original)
+            after = estimate_tokens(change.content)
+            diff = "".join(difflib.unified_diff(
+                original.splitlines(keepends=True),
+                change.content.splitlines(keepends=True),
+                fromfile=str(change.source_path),
+                tofile=f"{change.source_path} (proposed)",
+            ))
+            console.print(
+                f"\n[bold]{change.rule_id}[/bold] · ~{before} → ~{after} tokens "
+                f"([green]-{max(0, before - after)}[/green])"
+            )
+            console.print(diff or "[dim]No textual change.[/dim]")
+            if change.content == original:
+                continue
+            if yes or typer.confirm("Apply this compression?", default=False):
+                approved.append(change)
+
+        if not approved:
+            console.print("\n[dim]No changes approved.[/dim]")
+            return
+        backup_path = create_compression_backup(config, plan, project_name=project)
+        console.print(f"[bold]Backup created:[/bold] {backup_path}")
+        changed = 0
+        for change in approved:
+            try:
+                write_reviewed_rule(
+                    config,
+                    project_name=project,
+                    rule_path=change.source_path,
+                    content=change.content,
+                    backup_path=backup_path,
+                    expected_sha256=change.original_sha256,
+                )
+            except (OSError, ValueError) as error:
+                console.print(f"[red]Could not apply {change.rule_id}: {error}[/red]")
+                continue
+            changed += 1
+            console.print(f"[green]Applied:[/green] {change.rule_id}")
+        manifest = finalize_compression_backup(
+            config,
+            backup_path,
+            project_name=project,
+        )
+        console.print(f"\n[green]Compression complete: {changed} rule(s) changed.[/green]")
+        for change in manifest["changes"]:
+            console.print(
+                f"  {change['rule_id']}: ~{change['before_tokens']} → "
+                f"~{change['after_tokens']} tokens "
+                f"([green]-{change['saved_tokens']}[/green])"
+            )
+        console.print(
+            f"[bold]Actual context:[/bold] ~{manifest['actual_tokens_before']} → "
+            f"~{manifest['actual_tokens_after']} tokens "
+            f"([green]-{manifest['actual_tokens_saved']}[/green])"
+        )
+        console.print(f"[bold]Backup:[/bold] {backup_path}")
+        return
+
+    if json_output:
+        console.print_json(json.dumps(plan.to_dict()))
+    else:
+        saved = plan.estimated_tokens_before - plan.estimated_tokens_after
+        manual = [action for action in plan.actions if not action.automatic]
+        manual_low = sum(action.estimated_tokens_saved_low for action in manual)
+        manual_high = sum(action.estimated_tokens_saved_high for action in manual)
+        console.print(
+            f"[bold]Compression plan[/bold] · {plan.scope} · {plan.rule_count} rules"
+        )
+        if saved:
+            console.print(
+                f"Safe automatic context: ~{plan.estimated_tokens_before} → "
+                f"~{plan.estimated_tokens_after} tokens ([green]-{saved}[/green])"
+            )
+        else:
+            console.print(
+                f"Estimated context: ~{plan.estimated_tokens_before} tokens · "
+                "no safe automatic savings"
+            )
+        if manual:
+            savings = (
+                f" · potential manual savings ~{manual_low}-{manual_high} tokens"
+                if manual_high
+                else ""
+            )
+            console.print(f"[yellow]{len(manual)} review candidate(s)[/yellow]{savings}")
+        if not plan.actions:
+            console.print("[green]No safe automatic changes or review candidates found.[/green]")
+        else:
+            console.print("\n[bold]Actions[/bold]")
+            for action in plan.actions:
+                if action.estimated_tokens_saved:
+                    savings = f"~{action.estimated_tokens_saved}"
+                elif action.estimated_tokens_saved_high:
+                    savings = (
+                        f"~{action.estimated_tokens_saved_low}-"
+                        f"{action.estimated_tokens_saved_high}"
+                    )
+                else:
+                    savings = ""
+                mode = "[green]APPLY[/green]" if action.automatic else "[yellow]REVIEW[/yellow]"
+                savings_text = f" · potential savings {savings} tokens" if savings else ""
+                console.print(
+                    f"{mode} [cyan]{action.action}[/cyan] · "
+                    f"{', '.join(action.rule_ids)}{savings_text}"
+                )
+                console.print(f"  {action.message}\n")
+
+    if json_output or dry_run or not plan.automatic_actions:
+        if plan.actions and not json_output:
+            console.print("[dim]Use `/run_compress` in a synced coding agent to draft and review semantic changes.[/dim]")
+        return
+    if not sys.stdin.isatty():
+        console.print("[dim]Exact duplicates found; run in a terminal to approve their removal.[/dim]")
+        return
+    if typer.confirm(
+        f"Apply {len(plan.automatic_actions)} exact-duplicate action(s)?",
+        default=False,
+    ):
+        try:
+            result = apply_compression_plan(config, plan, project_name=project)
+        except (OSError, ValueError) as error:
+            console.print(f"[red]Compression aborted: {error}[/red]")
+            raise typer.Exit(1)
+        console.print(f"[green]Removed {len(result.removed_paths)} exact duplicate rule(s).[/green]")
+        console.print(f"[bold]Backup:[/bold] {result.backup_path}")
+
+
 @app.command()
 def rules(
     project: Optional[str] = typer.Option(None, "--project", "-p", help="Show rules resolved for a project"),