canopy-cli 3.1.0__py3-none-any.whl

canopy/workspace/discovery.py

@@ -0,0 +1,197 @@
+"""
+Auto-detect Git repositories in a directory and generate canopy.toml.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+from .config import RepoConfig
+from ..git import repo as git
+
+
+# Extension → language mapping (by frequency)
+_LANG_MAP: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript",
+    ".ts": "typescript", ".tsx": "typescript",
+    ".java": "java",
+    ".kt": "kotlin", ".kts": "kotlin",
+    ".go": "go",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".swift": "swift",
+    ".dart": "dart",
+    ".c": "c", ".h": "c",
+    ".cpp": "cpp", ".cc": "cpp", ".cxx": "cpp", ".hpp": "cpp",
+    ".cs": "csharp",
+    ".scala": "scala",
+    ".php": "php",
+    ".lua": "lua",
+    ".ex": "elixir", ".exs": "elixir",
+}
+
+_SKIP_DIRS = {
+    ".git", "node_modules", "__pycache__", "vendor", "dist",
+    "build", ".venv", "venv", ".tox", "target",
+}
+
+
+def discover_repos(root: Path) -> list[RepoConfig]:
+    """Walk immediate children of root and find Git repositories.
+
+    For each repo found, detect primary language and default branch.
+    """
+    root = root.resolve()
+    repos = []
+
+    for child in sorted(root.iterdir()):
+        if not child.is_dir():
+            continue
+        if child.name.startswith("."):
+            continue
+
+        # Check if it's a git repo — .git can be a directory (normal)
+        # or a file (linked worktree)
+        git_dir = child / ".git"
+        if not git_dir.exists():
+            continue
+
+        lang = _detect_language(child)
+        default_branch = _detect_default_branch(child)
+        role = _guess_role(child.name, lang)
+
+        # Detect worktree status
+        is_linked_worktree = git_dir.is_file()
+        worktree_main = None
+        if is_linked_worktree:
+            main_path = git.worktree_main_path(child)
+            if main_path:
+                worktree_main = str(main_path)
+
+        repos.append(RepoConfig(
+            name=child.name,
+            path=f"./{child.name}",
+            role=role,
+            lang=lang,
+            default_branch=default_branch,
+            is_worktree=is_linked_worktree,
+            worktree_main=worktree_main,
+        ))
+
+    return repos
+
+
+def generate_toml(root: Path, workspace_name: str | None = None) -> str:
+    """Generate a canopy.toml string for the given root directory."""
+    repos = discover_repos(root)
+    name = workspace_name or root.name
+
+    lines = [
+        "[workspace]",
+        f'name = "{name}"',
+        "",
+    ]
+
+    for repo in repos:
+        lines.append("[[repos]]")
+        lines.append(f'name = "{repo.name}"')
+        lines.append(f'path = "{repo.path}"')
+        if repo.role:
+            lines.append(f'role = "{repo.role}"')
+        if repo.lang:
+            lines.append(f'lang = "{repo.lang}"')
+        if repo.default_branch != "main":
+            lines.append(f'default_branch = "{repo.default_branch}"')
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _detect_language(repo_path: Path) -> str:
+    """Detect primary language by file extension frequency."""
+    counts: Counter[str] = Counter()
+
+    for item in repo_path.rglob("*"):
+        if any(skip in item.parts for skip in _SKIP_DIRS):
+            continue
+        if item.is_file() and item.suffix in _LANG_MAP:
+            counts[_LANG_MAP[item.suffix]] += 1
+
+    if not counts:
+        return ""
+    return counts.most_common(1)[0][0]
+
+
+def _detect_default_branch(repo_path: Path) -> str:
+    """Detect the default branch from local refs.
+
+    Works for both normal repos (.git is a directory) and linked
+    worktrees (.git is a file pointing to the main repo).
+    """
+    git_path = repo_path / ".git"
+
+    # For linked worktrees, use the git command directly since
+    # the .git directory structure is different
+    if git_path.is_file():
+        return git.default_branch(repo_path)
+
+    # Normal repo: check remote HEAD
+    head_ref = git_path / "refs" / "remotes" / "origin" / "HEAD"
+    if head_ref.exists():
+        try:
+            content = head_ref.read_text().strip()
+            # "ref: refs/remotes/origin/main"
+            if content.startswith("ref:"):
+                return content.split("/")[-1]
+        except (OSError, IndexError):
+            pass
+
+    # Check local refs for common default branch names
+    for candidate in ("main", "master"):
+        ref_path = git_path / "refs" / "heads" / candidate
+        if ref_path.exists():
+            return candidate
+
+    # Fallback: parse HEAD for current branch
+    head_file = git_path / "HEAD"
+    if head_file.exists():
+        try:
+            content = head_file.read_text().strip()
+            if content.startswith("ref: refs/heads/"):
+                return content.replace("ref: refs/heads/", "")
+        except OSError:
+            pass
+
+    return "main"
+
+
+def _guess_role(name: str, lang: str) -> str:
+    """Guess repo role from name and language."""
+    name_lower = name.lower()
+
+    backend_hints = {"api", "backend", "server", "service", "core"}
+    frontend_hints = {"ui", "frontend", "web", "client", "app"}
+    shared_hints = {"shared", "common", "types", "proto", "lib"}
+    infra_hints = {"infra", "infrastructure", "deploy", "ops", "terraform"}
+
+    for hint in backend_hints:
+        if hint in name_lower:
+            return "backend"
+    for hint in frontend_hints:
+        if hint in name_lower:
+            return "frontend"
+    for hint in shared_hints:
+        if hint in name_lower:
+            return "shared"
+    for hint in infra_hints:
+        if hint in name_lower:
+            return "infra"
+
+    # Language-based guess
+    if lang in ("python", "java", "go", "rust"):
+        return "backend"
+    if lang in ("javascript", "typescript"):
+        return "frontend"
+
+    return ""

canopy/workspace/workspace.py

@@ -0,0 +1,173 @@
+"""
+Workspace — the central orchestration object.
+
+Holds the workspace config and provides access to per-repo Git state.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import WorkspaceConfig, RepoConfig
+from ..git import repo as git
+
+
+@dataclass
+class RepoState:
+    """Live Git state for a single repository."""
+    config: RepoConfig
+    abs_path: Path
+    current_branch: str = ""
+    head_sha: str = ""
+    is_dirty: bool = False
+    dirty_count: int = 0
+    remote_url: str = ""
+
+    # Populated by enrich()
+    ahead_of_default: int = 0
+    behind_default: int = 0
+    changed_files: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d = {
+            "name": self.config.name,
+            "path": str(self.abs_path),
+            "role": self.config.role,
+            "lang": self.config.lang,
+            "current_branch": self.current_branch,
+            "head_sha": self.head_sha,
+            "is_dirty": self.is_dirty,
+            "dirty_count": self.dirty_count,
+            "remote_url": self.remote_url,
+            "default_branch": self.config.default_branch,
+            "ahead_of_default": self.ahead_of_default,
+            "behind_default": self.behind_default,
+            "changed_files": self.changed_files,
+            "changed_file_count": len(self.changed_files),
+        }
+        if self.config.is_worktree:
+            d["is_worktree"] = True
+            d["worktree_main"] = self.config.worktree_main
+        return d
+
+
+class Workspace:
+    """Central workspace object.
+
+    Reads workspace config, discovers Git state for all repos,
+    and provides cross-repo queries.
+    """
+
+    def __init__(self, config: WorkspaceConfig):
+        self.config = config
+        self.repos: list[RepoState] = []
+        self._refresh_basic()
+
+    def _refresh_basic(self) -> None:
+        """Read basic Git state for all repos."""
+        self.repos = []
+        for rc in self.config.repos:
+            abs_path = (self.config.root / rc.path).resolve()
+            state = RepoState(
+                config=rc,
+                abs_path=abs_path,
+            )
+            if abs_path.exists():
+                try:
+                    state.current_branch = git.current_branch(abs_path)
+                    state.head_sha = git.short_sha(abs_path)
+                    state.is_dirty = git.is_dirty(abs_path)
+                    state.dirty_count = git.dirty_file_count(abs_path)
+                    state.remote_url = git.remote_url(abs_path)
+                except git.GitError:
+                    pass  # repo exists but git commands failed
+            self.repos.append(state)
+
+    def refresh(self) -> None:
+        """Re-read Git state for all repos, including divergence."""
+        self._refresh_basic()
+        self.enrich()
+
+    def enrich(self) -> None:
+        """Enrich repo states with divergence and changed file data."""
+        for state in self.repos:
+            if not state.abs_path.exists():
+                continue
+            branch = state.current_branch
+            base = state.config.default_branch
+            if branch and branch != base and branch != "(detached)":
+                try:
+                    ahead, behind = git.divergence(state.abs_path, branch, base)
+                    state.ahead_of_default = ahead
+                    state.behind_default = behind
+                    state.changed_files = git.changed_files(
+                        state.abs_path, branch, base
+                    )
+                except git.GitError:
+                    pass
+
+    def get_repo(self, name: str) -> RepoState:
+        """Get a repo state by name. Raises KeyError if not found."""
+        for state in self.repos:
+            if state.config.name == name:
+                return state
+        raise KeyError(f"No repo named '{name}' in workspace")
+
+    def active_features(self) -> list[str]:
+        """Find branch names that exist in 2+ repos.
+
+        These are candidate feature lanes — branches that were probably
+        created together across repos for coordinated work.
+        """
+        from collections import Counter
+        branch_counts: Counter[str] = Counter()
+        default_branches = {rc.default_branch for rc in self.config.repos}
+
+        for state in self.repos:
+            branch = state.current_branch
+            if branch and branch not in default_branches and branch != "(detached)":
+                branch_counts[branch] += 1
+
+        # Also check all local branches in each repo
+        for state in self.repos:
+            if not state.abs_path.exists():
+                continue
+            try:
+                for branch in git.branches(state.abs_path):
+                    if branch not in default_branches:
+                        branch_counts[branch] += 1
+            except git.GitError:
+                pass
+
+        # Branches in 2+ repos are candidate features
+        # Deduplicate: we may have counted a branch twice (once from current_branch,
+        # once from branches list) — use set-based counting
+        branch_repos: dict[str, set[str]] = {}
+        for state in self.repos:
+            if not state.abs_path.exists():
+                continue
+            try:
+                repo_branches = set(git.branches(state.abs_path))
+            except git.GitError:
+                repo_branches = set()
+            if state.current_branch:
+                repo_branches.add(state.current_branch)
+
+            for branch in repo_branches:
+                if branch not in default_branches and branch != "(detached)":
+                    branch_repos.setdefault(branch, set()).add(state.config.name)
+
+        return sorted(
+            branch
+            for branch, repos in branch_repos.items()
+            if len(repos) >= 2
+        )
+
+    def to_dict(self) -> dict:
+        """Serialize workspace state to a dict (for --json output)."""
+        return {
+            "name": self.config.name,
+            "root": str(self.config.root),
+            "repos": [r.to_dict() for r in self.repos],
+            "active_features": self.active_features(),
+        }

canopy_cli-3.1.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: canopy-cli
+Version: 3.1.0
+Summary: Workspace-first development orchestrator for AI coding agents
+Project-URL: Homepage, https://github.com/ashmitb95/canopy
+Project-URL: Source, https://github.com/ashmitb95/canopy
+Project-URL: Issues, https://github.com/ashmitb95/canopy/issues
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == 'graph'
+Requires-Dist: tree-sitter>=0.21; extra == 'graph'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/canopy-banner.svg" alt="canopy — typed multi-repo work for AI coding agents" width="600">
+</p>
+
+<p align="center">
+  <em>The typed multi-repo MCP server your AI coding agent needs.</em>
+</p>
+
+<p align="center">
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square&logo=python&logoColor=white">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-857%20passing-brightgreen?style=flat-square">
+  <img alt="MCP Tools" src="https://img.shields.io/badge/MCP%20tools-67-purple?style=flat-square">
+  <a href="https://marketplace.visualstudio.com/items?itemName=SingularityInc.canopy"><img alt="VSCode Extension" src="https://img.shields.io/badge/VSCode-extension-blue?style=flat-square&logo=visualstudiocode"></a>
+  <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-gray?style=flat-square">
+</p>
+
+---
+
+Canopy is built for workspaces with **multiple repos that share a feature lifecycle** — backend + frontend, api + mobile, a monolith plus its services. That setting breaks coding agents in specific, fixable ways: shell state doesn't survive between tool calls, paths get constructed wrong, drift accumulates silently between repos, and PR review work pulls the agent across repo boundaries faster than its context can keep up.
+
+Canopy gives the agent a typed contract for that setting — `feature` / `repo` / alias inputs, structured outputs, recoverable errors — so it can drive multi-repo feature work end-to-end without ever shelling `cd /wrong/repo`.
+
+```python
+# Without canopy: brittle paths, parsed stderr, no shared state across repos.
+bash("cd /Users/.../web/api && git status")
+bash("cd /Users/.../web/ui && git status")
+bash("gh pr list --author @me --json number,title")
+# ... then per-thread "is this still actionable?" logic in the agent's head
+
+# With canopy: one typed call, structured multi-repo response, recoverable error.
+mcp__canopy__feature_state(feature="auth-flow")
+# → { "state": "needs_work",
+#     "next_actions": ["address_review_comments"],
+#     "summary": {
+#       "ci_aggregate": "passing",
+#       "actionable_human_count": 2,
+#       "repos": {
+#         "api": { "dirty_file_count": 3, "ahead": 2, "behind": 0, "pr": {...} },
+#         "ui":  { "dirty_file_count": 0, "ahead": 0, "behind": 0, "pr": {...} }
+#       }
+#     }
+#   }
+```
+
+The CLI is the surface humans use to drive the same primitives. Same JSON, two consumers.
+
+## Why multi-repo work breaks coding agents
+
+Each `mcp__canopy__*` tool closes one failure mode that agents reliably hit when the workspace has more than one repo:
+
+| Failure mode | Canopy's fix |
+|---|---|
+| **Shell state evaporates between tool calls.** `cd /repo-a && command` doesn't persist; the next call lands somewhere else. Multi-repo makes this worse because there's more than one "right" place to land. | Every canopy tool takes `feature` / `repo` / alias as parameters; path resolution lives inside canopy. The agent has no surface area to type the path. |
+| **Cross-repo state is invisible.** `git status` in one repo doesn't tell you what's happening in the other. The agent has to query each repo separately and stitch the picture. | `mcp__canopy__feature_state(feature)` returns the full multi-repo picture in one call: per-repo dirty/ahead/behind, PRs, CI, computed state, prioritized next actions. |
+| **Drift between tool calls.** The agent `git checkout`'d X in one repo, the next call assumes the OTHER repo is also on X; things go sideways. | Per-repo post-checkout hooks write `.canopy/state/heads.json` (fcntl-locked, atomic-renamed). `mcp__canopy__drift` reads cached state in <50ms. The agent sees misalignments that happened between calls, even when it didn't cause them. |
+| **Session re-derivation.** Each new chat re-walks `gh pr list`, `git status` per repo, comment threads, CI status — burning context on bookkeeping the previous chat already did. | `mcp__canopy__feature_resume(alias)` is one call: alias → switch focus if needed → refresh GH+Linear → return structured brief of what changed since last visit. Cross-session state via `.canopy/state/visits.json` + per-feature memory at `.canopy/memory/<feature>.md`. |
+| **PR review churn across repos.** A feature with two PRs (one per repo) accumulates threads on both; the agent re-classifies "is this still actionable?" every turn. | `mcp__canopy__github_get_pr_comments(alias)` returns threads pre-bucketed as `actionable` / `likely_resolved` via temporal filtering (comment timestamp vs commits-on-file-since). Resolved threads carry `by_canopy: true` attribution when canopy itself closed them. |
+| **Closing GH threads needs raw GraphQL.** REST has no thread IDs; agents fumble with `gh api graphql` query strings. | `mcp__canopy__resolve_thread(thread_id)`, `mcp__canopy__reply_to_thread(thread_id, body, resolve_after=True)`, and `mcp__canopy__commit(address=<id>, resolve_thread=True)` handle the wire format and log resolutions locally for attribution. |
+| **Juggling 2–3 features in parallel** loses in-progress work to forgotten stashes or breaks when one repo gets `git checkout`'d alone. | The slot model (Wave 3.0): each feature lives in `canonical` / `warm` / `cold`. `mcp__canopy__switch(feature)` rotates focus atomically across every repo in the feature's lane, evacuating the previous canonical into a warm slot with `stash → checkout → pop`. |
+| **Errors come back as stderr text.** Agents have to parse English failure messages to decide recovery. | Structured `BlockerError(code, what, expected, actual, fix_actions)`, each fix carrying `safe: bool` so the agent knows what's auto-runnable vs needs human confirmation. |
+
+## Install
+
+Requires Python 3.10+.
+
+```bash
+pipx install git+https://github.com/ashmitb95/canopy.git
+cd ~/your-multi-repo-workspace
+canopy init
+```
+
+If you don't have pipx: `brew install pipx && pipx ensurepath`.
+
+`canopy init` does four things:
+1. Discovers your git repos and writes `canopy.toml`.
+2. Installs the drift-detection post-checkout git hook in every repo.
+3. **Wires the canopy MCP server into Claude Code** by writing a `.mcp.json` entry — this is what makes the agent surface live.
+4. Installs the `using-canopy` skill at `~/.claude/skills/using-canopy/SKILL.md` so the agent knows when to reach for canopy tools.
+
+Skip the agent bits with `--no-agent` if you're just using the CLI.
+
+<p align="center">
+  <img src="docs/cli-init.svg" alt="canopy init" width="720">
+</p>
+
+## The 67-tool surface
+
+Every CLI command has an `mcp__canopy__*` MCP equivalent returning the same JSON. The MCP server is the load-bearing surface for agents; the CLI is the side benefit for humans. Tools by topic:
+
+### Session-start + state
+
+| Tool | What it does |
+|---|---|
+| `feature_resume(alias)` | The headline primitive. Resolves alias → switches canonical if needed → refreshes GitHub + Linear → returns the structured brief (`since_last_visit`, `current_state`, `intent_hints`). Call this first when a chat opens on a feature. |
+| `feature_state(feature)` | 9-state machine (`drifted`, `needs_work`, `awaiting_bot_resolution`, `in_progress`, `ready_to_commit`, `ready_to_push`, `awaiting_review`, `approved`, `no_prs`) + `next_actions` array. Drives the agent's decision tree. |
+| `triage` | Cross-feature priority view. Returns features ordered by review-state urgency. |
+| `slots(rich=True)` | Dashboard data — canonical + every warm slot with per-repo branch, dirty, ahead/behind, PR, CI, bot threads, Linear, computed `feature_state`. |
+
+### Focus management (the slot model)
+
+| Tool | What it does |
+|---|---|
+| `switch(feature)` | Promote a feature into the canonical slot. Previous canonical evacuates into a warm slot (active rotation, default) or goes cold with feature-tagged stash (`release_current=True`). Atomic across every repo in the feature's lane. |
+| `slot_load(feature, slot_id?)` | Warm a cold feature into a slot **without** changing canonical. Use for pre-warming or inspecting a feature you're not ready to focus on. |
+| `slot_clear(slot_id)` | Vacate a slot to cold (feature-tagged stash if dirty). The slot remains, just empty. |
+| `slot_swap(slot_a, slot_b)` | Exchange the occupants of two warm slots. |
+| `migrate_slots()` | One-shot migration from pre-3.0 layouts. |
+
+### PR review work
+
+| Tool | What it does |
+|---|---|
+| `github_get_pr_comments(alias)` | Returns `actionable_threads` + `likely_resolved_threads` per repo. Temporal filter has already classified what's worth the agent's attention. |
+| `resolve_thread(thread_id, feature?)` | Close a GH review thread via GraphQL + log to `.canopy/state/thread_resolutions.json` for attribution. |
+| `reply_to_thread(thread_id, body, feature?, resolve_after=False)` | Post a reply; optionally close after. |
+| `commit(message, feature?, address=<id>, resolve_thread=False)` | Commit across the feature's repos. With `address=<comment_id>`, auto-suffixes the message + logs to `bot_resolutions.json`. With `resolve_thread=True`, closes the corresponding GH thread. |
+| `bot_comments_status(feature)` | Per-PR bot-comment rollup: total / resolved / unresolved. |
+| `draft_replies(feature)` | File-history-based addressed-comment detector + reply templates. |
+
+### Operate across repos without `cd`
+
+| Tool | What it does |
+|---|---|
+| `preflight(feature?)` | Run each repo's preflight hooks (or `[augments] preflight_cmd` override). Records result for the state machine. |
+| `push(feature?)` | Push across every repo in the feature's lane. `set_upstream=True` on first push. |
+| `run(repo, command)` | Path-safe shell exec. Canopy resolves the cwd to the right repo dir; the agent never types a path. |
+
+### Read + alias resolution
+
+| Tool | What it does |
+|---|---|
+| `linear_get_issue(alias)`, `linear_my_issues` | Linear issue data via the issue-provider abstraction. |
+| `github_get_pr(alias)`, `github_get_branch(alias)` | PR + branch data. |
+| `issue_get(alias)` | Provider-agnostic issue read (Linear or GitHub Issues). |
+
+Every read tool accepts the same alias forms:
+- Feature name: `auth-flow`
+- Linear issue ID: `TEAM-101` (resolves via lane's `linear_issue`)
+- Specific PR: `<repo>#<n>` like `api#142`
+- PR URL: `https://github.com/owner/repo/pull/142`
+- Specific branch: `<repo>:<branch>`
+- Slot id: `worktree-1`, `worktree-2`, ... (resolves to the slot's current occupant)
+
+### Recovery
+
+| Tool | What it does |
+|---|---|
+| `doctor` | 21 diagnostic codes across 12 categories of state-file drift + install staleness. Each issue carries `severity`, `expected` / `actual`, and an `auto_fixable` flag. `doctor(fix=True)` runs the safe auto-fixes. First call when something feels off. |
+| `version` | `{cli_version, mcp_version, schema_version}` handshake. Doctor reports `cli_stale` / `mcp_stale` when these drift. |
+
+### Cross-session memory
+
+`feature_memory(feature)`, `historian_decide(feature, decisions)`, `historian_pause(feature, reason)`, `historian_defer_comment(feature, comment_id, reason)`, `historian_compact(feature, keep_sessions)` — persistent per-feature memory at `.canopy/memory/<feature>.md`. Auto-captured by `commit --address` and `github_get_pr_comments`. Read on `switch` to recover prior session context without re-deriving.
+
+Full reference: [docs/mcp.md](docs/mcp.md).
+
+## The slot model
+
+Every feature lives in one of three states:
+
+- **canonical** — checked out in the main repo dirs. Exactly one canonical feature at a time across all repos. **This is the only place to run code.** Worktrees are passive branch storage; never `cd` into them to launch the app.
+- **warm** — sits in a numbered slot at `.canopy/worktrees/worktree-N/<repo>/`. Slot identity (`worktree-1`, `worktree-2`, ...) is stable across feature swaps; feature occupancy is transient. Capped by `[workspace] slots = N` in canopy.toml (default 2).
+- **cold** — branch only, no checkout. Cheap and unlimited.
+
+`switch(Y)` is the single primitive that moves features between these states:
+
+- **Active rotation (default):** previous canonical evacuates into a warm slot via `stash → checkout → pop`. Instant to switch back.
+- **Wind-down (`release_current=True`):** previous goes cold with a feature-tagged stash.
+
+When the cap fires, `switch` returns `BlockerError(code='worktree_cap_reached')` with explicit `fix_actions` (evict a specific slot, wind down the current focus, raise the cap). **No silent eviction.**
+
+Full design: [docs/concepts.md §4](docs/concepts.md#4-the-slot-model).
+
+## Structured errors
+
+Every error is a typed payload — agents don't parse stderr.
+
+```json
+{
+  "status": "blocked",
+  "code": "drift_detected",
+  "what": "branches don't match feature lane 'auth-flow'",
+  "expected": {"branches": {"api": "auth-flow", "ui": "auth-flow"}},
+  "actual":   {"branches": {"api": "auth-flow", "ui": "main"}},
+  "fix_actions": [
+    {"action": "switch", "args": {"feature": "auth-flow"}, "safe": true,
+     "preview": "promote auth-flow to canonical across all repos"}
+  ]
+}
+```
+
+The agent reads `fix_actions[0]`, checks `safe: true`, calls `mcp__canopy__switch(feature="auth-flow")`. The CLI renders the same payload as colored multi-line output via [`cli/render.py`](src/canopy/cli/render.py). Single source of truth, two surfaces.
+
+## Agent integration
+
+`canopy init` installs the `using-canopy` skill at `~/.claude/skills/using-canopy/SKILL.md` (per-user) and writes `.mcp.json` so Claude Code spawns the canopy MCP server in this workspace. The skill teaches the agent when to reach for canopy:
+
+- See a feature alias or issue ID as the first non-trivial token? Call `feature_resume(alias)` before doing anything else.
+- About to `cd <repo> && command`? Use `mcp__canopy__run(repo, command)` or the feature-aware verb.
+- About to `gh api graphql` for thread mutations? Use `resolve_thread` / `reply_to_thread` / `commit --address --resolve-thread`.
+- See an unfamiliar error? Call `doctor` first.
+
+Opt-in extra skills via `canopy setup-agent --skill <name>`:
+- [`augment-canopy`](src/canopy/agent_setup/skills/augment-canopy/SKILL.md) — teaches the agent the `canopy.toml [augments]` schema so it can configure `preflight_cmd`, `review_bots`, `auto_resolve_threads_on_address`, etc. on the user's behalf.
+
+GitHub access works via the `gh` CLI fallback when no `github` MCP server is configured. Linear works via OAuth (browser flow once, no API key).
+
+## For humans
+
+The same primitives are available as a CLI. Daily commands:
+
+```bash
+canopy resume <feature>     # session start — print the brief
+canopy switch <feature>     # focus — promote to canonical
+canopy status               # workspace-wide rollup
+canopy state <feature>      # 9-state + next_actions
+canopy triage               # cross-feature priority
+canopy preflight            # run hooks across the feature's repos
+canopy commit -m "..."      # commit across repos at once
+canopy push                 # push across repos at once
+canopy slots --rich         # dashboard data
+canopy doctor               # diagnose drift / staleness
+```
+
+<p align="center">
+  <img src="docs/cli-state.svg" alt="canopy state" width="720">
+</p>
+
+The CLI and MCP server are thin wrappers over the same actions — `canopy state X` and `mcp__canopy__feature_state(feature='X')` return identical bytes. There's also a [VSCode extension](https://marketplace.visualstudio.com/items?itemName=SingularityInc.canopy) reading the same state the agent reads.
+
+Full CLI reference: [docs/commands.md](docs/commands.md).
+
+## Docs
+
+- [Concepts](docs/concepts.md) — the action framework, agent context contract, 9-state machine, slot model, resume brief
+- [Agents](docs/agents.md) — skill install, integration recipes, the agent tool loop
+- [Commands](docs/commands.md) — full CLI reference
+- [MCP](docs/mcp.md) — server tool list, client transports (stdio + HTTP/OAuth), gh fallback
+- [Workspace](docs/workspace.md) — `canopy.toml`, `features.json`, state files
+- [Architecture](docs/architecture.md) — module boundaries, runtime pathways, state files
+- [Providers](docs/architecture/providers.md) — issue-provider abstraction (Linear, GitHub Issues)
+
+## Develop
+
+```bash
+git clone https://github.com/ashmitb95/canopy.git ~/projects/canopy
+cd ~/projects/canopy
+pip install -e ".[dev]"
+pytest tests/ -v             # 857 tests, ~225s, all use real temporary Git repos
+```
+
+## License
+
+MIT