diff --git a/README.md b/README.md
index 66e87c8..9f620e4 100644
--- a/README.md
+++ b/README.md
@@ -1,479 +1,108 @@
 # sync-agents
 
-One set of agent rules to rule them all. `sync-agents` keeps your AI coding agent configurations in a single `.agents/` directory and syncs them to agent-specific directories (`.claude/`, `.windsurf/`, `.cursor/`, `.github/copilot/`) via symlinks. This ensures all agents follow the same rules, skills, workflows, subagents, plans, and specs without duplicating files.
+**One `.agents/` directory. Every AI coding assistant. Always in sync.**
 
-AGENTS.md serves as an auto-generated index of everything in `.agents/` and is symlinked to CLAUDE.md for Claude compatibility.
+`sync-agents` is a package manager and sync engine for AI-agent context — the rules, skills, workflows, subagents, plans, specs, and ADRs you feed to Claude, Cursor, Windsurf, and Copilot. Write everything once in `.agents/`, and `sync-agents` fans it out to every tool via symlinks, keeps an `AGENTS.md` index current, and lets you pull shared context from other repos as safely and reproducibly as you'd install an npm package.
 
-## Installation
+## Why you want this
 
-### npm (recommended for Node.js projects)
+If you use more than one AI coding tool — or more than one repo — you already know the pain: the same rules copy-pasted into `.claude/`, `.cursor/`, `.windsurf/`, and `.github/copilot/`, drifting apart the moment you edit one of them. Team conventions living in a wiki nobody's agent reads. A "cool skill" pasted from the internet with zero review of what it actually tells your agent to do.
 
-Ships native Go binaries via per-platform optional packages — no build step required.
+`sync-agents` fixes all three:
 
-```bash
-npm install -g @brickhouse-tech/sync-agents
-```
-
-Or as a project devDependency:
-
-```bash
-npm install --save-dev @brickhouse-tech/sync-agents
-```
-
-### go install (no Node.js required)
-
-```bash
-go install github.com/brickhouse-tech/sync-agents@latest
-```
-
-Requires Go 1.21+. The binary is placed in `$GOPATH/bin` (or `$HOME/go/bin`). Version is read from the module proxy at install time via `debug.ReadBuildInfo`.
-
-### Homebrew
-
-```bash
-brew install brickhouse-tech/tap/sync-agents
-```
-
-The tap is updated automatically on every release via GoReleaser.
-
-### GitHub Releases (pre-built binaries)
-
-Download the archive for your platform from the [Releases page](https://github.com/brickhouse-tech/sync-agents/releases), extract, and place the binary on your `PATH`:
-
-```bash
-# Example: macOS arm64
-curl -fsSL https://github.com/brickhouse-tech/sync-agents/releases/latest/download/sync-agents_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/').tar.gz | tar -xz
-sudo mv sync-agents /usr/local/bin/
-```
-
-SHA-256 checksums are published alongside each release as `checksums.txt`.
-
-## Topology
-
-`.agents/` is the source of truth. It contains all rules, skills, workflows, and state for your agents:
-
-```
-.agents/
-  ├── config              # sync targets (claude, windsurf, cursor, copilot)
-  ├── rules/
-  │   ├── rule1.md
-  │   ├── rule2.md
-  │   └── ...
-  ├── skills/
-  │   ├── skill1/
-  │   │   └── SKILL.md
-  │   ├── skill2/
-  │   │   └── SKILL.md
-  │   └── ...
-  ├── workflows/
-  │   ├── workflow1.md
-  │   ├── workflow2.md
-  │   └── ...
-  ├── agents/              # optional: Claude subagent definitions
-  │   └── reviewer.md
-  ├── plans/               # optional: per-effort implementation plans (how/when)
-  │   └── auth-effort/
-  │       └── rollout.md
-  ├── specs/               # optional: durable design/requirements docs (what/why)
-  │   └── SPEC-001.md
-  ├── adrs/                # optional: Architecture Decision Records, status = subdirectory
-  │   ├── proposed/
-  │   │   └── adopt-grpc.md
-  │   ├── accepted/
-  │   │   └── use-postgres.md
-  │   └── denied/          # kept but never indexed — prevents re-proposing rejected decisions
-  │       └── use-mongo.md
-  └── STATE.md
-```
-
-> **Note:** Skills use a directory layout (`skills/name/SKILL.md`) rather than flat files. This allows skills to include supporting files alongside their definition. The `fix` command can convert legacy flat skill files to the directory layout automatically.
-
-> **Optional buckets:** `agents/`, `plans/`, `specs/`, `hooks/`, and `adrs/` activate only when their directory exists — `init` does not create them, `add agent|plan|spec|hook|adr <name>` does. They sync to Claude only (`.claude/agents`, `.claude/plans`, `.claude/specs`); other tools consume plans/specs through the `AGENTS.md` index and have no subagent surface. `plans/` and `specs/` share plumbing but differ in lifecycle: specs are durable what/why documents, plans are per-effort how/when documents that retire when the effort lands.
-
-Running `sync-agents sync` creates symlinks from `.agents/` subdirectories into `.claude/`, `.windsurf/`, `.cursor/`, and `.github/copilot/`. Any changes to `.agents/` are automatically reflected in the target directories because they are symlinks, not copies.
-
-AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively.
-
-## STATE.md
-
-`.agents/STATE.md` tracks the current state of your project from the agent's perspective. It serves as a resumption point after failures or interruptions -- the agent can read STATE.md to determine where it left off and what tasks remain. Update it regularly to keep agents in sync with progress.
-
-## Commands
-
-| Command | Description |
-|---|---|
-| `init` | Initialize the `.agents/` directory structure with `rules/`, `skills/`, `workflows/`, `STATE.md`, and generate `AGENTS.md` |
-| `sync` | Create symlinks from `.agents/` into all target directories, and symlink `AGENTS.md` to `CLAUDE.md` |
-| `watch` | Watch `.agents/` for changes and auto-regenerate `AGENTS.md` |
-| `import <url>` | Import a rule/skill/workflow from a URL |
-| `pull [--dry-run\|--offline\|--force\|--only NAME\|--global]` | Fetch every `sources.yaml` entry, verify integrity, install into the matching buckets |
-| `update [NAME]` | Re-resolve refs and re-pull entries whose upstream moved; SHA-pinned entries are skipped |
-| `source add <entry>` | Append an entry to `sources.yaml` and pull it |
-| `source add --link[=<path>] [<entry>]` | Declare a **linked (editable)** source — symlink a live local checkout instead of a fetched snapshot (SPEC-007) |
-| `source remove <name> [--keep]` | Remove the manifest entry and delete the artifact (`--keep` converts it to manual) |
-| `source list [--json]` | Show each entry's local state: `ok` / `outdated` / `modified` / `missing` / `linked` |
-| `source bundle` | Rebuild `sources.yaml` from installed artifacts' origin metadata |
-| `source detach <name>` | Un-manage an artifact: flip its origin to manual and drop the manifest entry (for a **linked** source, freeze the live copy into a vendored snapshot) |
-| `quarantine` | List remotely-fetched artifacts awaiting review, with their scan findings |
-| `approve <name>\|--all [--force]` | Promote a quarantined artifact into `.agents/` (`--force` accepts critical findings, recorded in the lock) |
-| `reject <name>\|--all` | Delete a quarantined artifact without installing it |
-| `git-hook` | Install a pre-commit git hook for auto-sync (`hook` remains as a deprecated alias) |
-| `inherit <label> <path>` | Add an inheritance link to AGENTS.md |
-| `inherit --list` | List current inheritance links |
-| `inherit --remove <label>` | Remove an inheritance link by label |
-| `status` | Show the current sync status of all targets and symlinks |
-| `add <type> <name>` | Add a new artifact from a template (type is `rule`, `skill`, `workflow`, `agent`, `plan`, `spec`, `hook`, or `adr`) |
-| `index [--no-fix]` | Regenerate `AGENTS.md` by scanning `.agents/`. Backfills fixable skill frontmatter first (`--no-fix` skips the backfill) |
-| `adr <accept\|deny\|propose> <name>` | Move an ADR between status directories, update its `status:` frontmatter, and reindex |
-| `lint [skills] [--fix]` | Validate SKILL.md frontmatter against [Claude's skill authoring rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices); `--fix` amends fixable findings in place |
-| `clean` | Remove all synced symlinks and empty target directories (does not remove `.agents/`) |
-| `fix [type]` | Migrate legacy dirs into `.agents/`, convert flat skill files to directory layout, and repair broken symlinks. Type: any bucket dir, or `all` (default) |
-| `promote <type> <name>` | Copy an artifact from the project's `.agents/` to the user-level global store (`~/.agents/`) |
-| `global init` | Initialize the global `~/.agents/` store |
-| `global sync` | Fan the global store out to each tool's user-level config dir with semantic-aware routing |
-| `global status` | Show per-artifact sync state across global tool dirs |
-| `global clean` | Remove global symlinks/concat files owned by sync-agents |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-h`, `--help` | Show help message |
-| `-v`, `--version` | Show version |
-| `-d`, `--dir <path>` | Set project root directory (default: current directory) |
-| `--targets <list>` | Comma-separated list of sync targets (default: `claude,windsurf,cursor,copilot`) |
-| `--dry-run` | Show what would be done without making changes |
-| `--force` | Overwrite existing files and symlinks |
-| `--no-clobber` | (fix only) Skip items that already exist in `.agents/` instead of merging |
-| `--fix` | (lint only) Amend fixable frontmatter findings in place |
-| `--no-fix` | (index only) Skip the skill frontmatter backfill |
-| `--trust` | (pull/update only) Bypass the quarantine gate; the scan still runs and prints findings |
-
-## Configuration
-
-`sync-agents init` creates `.agents/config` with default sync targets:
-
-```
-# sync-agents configuration
-# Comma-separated list of sync targets (available: claude, windsurf, cursor, copilot)
-targets = claude,windsurf,cursor,copilot
-```
-
-Edit this file to limit which targets `sync` writes to by default. The `--targets` flag on any command overrides the config.
-
-## Fix
-
-The `fix` command handles three scenarios:
-
-1. **Legacy directory migration** — Moves top-level `skills/`, `rules/`, or `workflows/` directories into `.agents/` and replaces them with symlinks.
-2. **Flat skill conversion** — Converts `.agents/skills/name.md` flat files to the directory layout `.agents/skills/name/SKILL.md`.
-3. **Symlink repair** — Recreates missing or broken symlinks in target directories (`.claude/`, `.windsurf/`, etc.) and the `CLAUDE.md` symlink.
-
-```bash
-# Fix everything (all types)
-sync-agents fix
-
-# Fix only skills
-sync-agents fix skills
-
-# Preview without changing anything
-sync-agents fix --dry-run
-
-# Don't overwrite items already in .agents/
-sync-agents fix --no-clobber skills
-```
-
-A reproducible demo is available in [`examples/fix/`](examples/fix/):
-
-```bash
-bash examples/fix/run-demo.sh
-```
-
-## Skill frontmatter (lint & backfill)
-
-Claude discovers skills through their `SKILL.md` YAML frontmatter, with [published requirements](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): `name` (≤64 chars, lowercase letters/numbers/hyphens, no reserved words) and `description` (non-empty, ≤1024 chars, third person, says what the skill does *and when to use it*).
-
-`sync-agents lint` checks every skill against those rules; `lint --fix` mechanically amends what it can — injecting a missing frontmatter block, deriving `name` from the directory, deriving `description` from the first body paragraph, truncating overlong values, and stripping XML tags — while preserving all other frontmatter keys verbatim. Reserved-word names are reported but never auto-renamed.
-
-`sync-agents index` runs the same backfill by default before regenerating `AGENTS.md`, so legacy skills upgrade themselves as part of the normal index cycle (`--no-fix` opts out). Unfixable findings warn but never fail indexing.
-
-```bash
-# report compliance issues (exit non-zero on errors — CI-friendly)
-sync-agents lint
-
-# amend fixable findings in place
-sync-agents lint --fix
-```
-
-## Source manifest (pull, lockfile & provenance)
-
-Declare upstream rules, skills, workflows — or whole `.agents/` trees — in `.agents/sources.yaml` and install them reproducibly:
-
-```yaml
-version: 1
-sources:
-  - skill:anthropic/skill-pack@v1.2.0/skills/code-review
-  - rule:my-org/agent-norms@main/rules/security.md
-  - tree:my-org/team-agents@v2.0.0   # fans out to every bucket in the upstream .agents/
-```
-
-`sync-agents pull` resolves each ref to a commit SHA via the GitHub API, fetches the repo tarball (cached by SHA under `$XDG_CACHE_HOME/sync-agents/`, no `git` binary needed), verifies a deterministic sha256 content hash against `.agents/sources.lock`, and only then installs — a tampered tarball or corrupted cache aborts before anything is written. Every installed artifact carries provenance (`_origin.json` inside skill dirs, `<name>.origin.json` beside flat files) recording owner/repo/ref/SHA/hash; commit these so clones keep their provenance.
-
-Safety rules: locally-edited artifacts are never overwritten without `--force`; a destination without origin metadata is treated as a manual conflict. Private repos use your token (`SYNC_AGENTS_GITHUB_TOKEN` > `GITHUB_TOKEN` > `GH_TOKEN` > `gh auth token`). All commands accept `--global` to operate on `~/.agents/` instead of the project.
-
-```bash
-sync-agents source add skill:anthropic/skill-pack@v1.2.0/skills/code-review
-sync-agents source list          # ok / outdated / modified / missing per entry
-sync-agents update               # bump tag-tracked entries when upstream moves
-sync-agents pull --offline       # cache-only, for CI or airplanes
-```
-
-## Quarantine (remote content review)
-
-Remote installs are treated like a hostile supply chain. By default, everything `pull`/`update` fetches lands in `.agents/.quarantine/` — invisible to `sync` and the index — after a static scan for network-then-execute patterns (`curl | bash`), credential access combined with network calls, obfuscation (long base64, zero-width Unicode), and prompt-injection phrasing aimed at your agent.
-
-```bash
-sync-agents pull                  # → 1 quarantined (run `sync-agents quarantine`)
-sync-agents quarantine            # review findings per artifact
-sync-agents approve code-review   # promote into .agents/ (blocked on CRITICAL unless --force)
-sync-agents reject sketchy-rule   # delete without installing
-```
-
-Critical findings block `approve`; overriding with `--force` is recorded in `sources.lock` as `approved_with_findings` so the decision is auditable. `--trust` on `pull`/`update` skips the gate for one invocation (findings still print), and `quarantine = off` in `.agents/config` disables it for teams that review via pinned SHAs in PRs instead.
-
-## Linked (editable) sources
-
-When you're **actively developing** a skill that lives in another repo (or the upstream repo itself), a SHA-pinned snapshot forces a slow `edit → commit → push → update` loop. A **linked** source is the `npm link` / `go mod replace` for `.agents/` — it symlinks the artifact at a live local checkout, so edits flow both ways and `git pull` in the checkout reaps updates with no re-fetch (SPEC-007).
-
-```bash
-# Link a checkout you already have (path relative to cwd or absolute):
-sync-agents source add --link=../foo-skill skill:me/foo-skill
-
-# Derive the entry from the checkout's github remote + layout:
-sync-agents source add --link=../foo-skill
-
-# Managed clone: sync-agents clones the repo under .agents/.sources/ and links out of it
-# (the initial clone is scanned once through the quarantine scanner; --trust to skip):
-sync-agents source add --link skill:me/foo-skill
-```
-
-The link is recorded declaratively as a `link:` override in `sources.yaml` and echoed in `sources.lock`, so the intent is committed and reviewable:
+- **Zero drift.** `.agents/` is the single source of truth; tool directories are symlinks into it. Edit once, every tool sees it instantly.
+- **Real distribution.** Declare upstream rules/skills/whole trees in `sources.yaml`, get SHA-pinned, lockfile-verified installs — a package manager, not a copy-paste culture.
+- **Supply-chain safety by default.** Everything fetched remotely is statically scanned and quarantined until you approve it. Your agent's instructions are an attack surface; treat them like one.
 
-```yaml
-overrides:
-  - match: skill:me/foo-skill
-    link: file:../foo-skill      # relative to .agents/; mutually exclusive with pin_sha
-```
+## What is this, in simple terms?
 
-All persisted paths are **relative** (`file:` scheme) and the on-disk symlink is created relative too — an absolute path would break the instant another machine cloned the repo, so absolute `file:` paths are rejected at parse time. `pull` verifies (and self-heals) the symlink and never re-fetches a snapshot over it; a missing checkout surfaces as a warning, not a silent revert. `update` advances a **managed clone** with `git pull --ff-only` (a checkout you own is yours to drive). `source list` shows linked entries as `[linked] … link → file:../foo-skill`, and `source detach` **freezes** the live copy into an ordinary vendored snapshot (materialize the files, drop the `link` override, keep the upstream identity). Because a linked source is a local working tree you own, it is trusted by default — only the first fetch of a managed clone is scanned.
+Think of the instructions you give AI coding assistants as software. This tool is **npm for your AI's brain**.
 
-## ADRs (Architecture Decision Records)
+- Your project gets one folder (`.agents/`) that holds everything you've taught your AI: house rules, reusable how-to guides, step-by-step playbooks.
+- Every AI tool you use reads from that one folder — like several TVs all tuned to the same channel. Change the channel once, every screen updates.
+- Want a rule or skill someone else published? "Install" it like an app from an app store, pinned to an exact version so it can't silently change under you.
+- And just like you wouldn't run a random downloaded program without a virus scan, anything you install from the internet is scanned and held in a waiting room until you say it's okay.
 
-ADRs live in `.agents/adrs/` with **status encoded by subdirectory**: `proposed/`, `accepted/`, `denied/`. `add adr <name>` scaffolds into `proposed/`; `sync-agents adr accept|deny|propose <name>` moves a record between statuses (nested grouping subdirs are preserved) and regenerates the index.
+No more copy-pasting the same instructions into four different tools, and no more wondering where that one config file came from.
 
-Only **accepted and proposed** records appear in `AGENTS.md`. Denied records are kept on disk and the index carries a standing note telling agents to check `.agents/adrs/denied/` before proposing a new ADR — so already-rejected decisions don't get re-proposed.
+## Install
 
 ```bash
-sync-agents add adr use-postgres      # → .agents/adrs/proposed/use-postgres.md
-sync-agents adr accept use-postgres   # → .agents/adrs/accepted/, reindexed
-sync-agents adr deny use-postgres     # → .agents/adrs/denied/, dropped from index
-```
-
-## Inheritance
-
-Projects can inherit agent rules from parent directories (org, team, global) using a convention-based approach. This enables hierarchical rule sharing without duplicating files.
-
-### How It Works
-
-Add an `## Inherits` section to your project's `AGENTS.md` that links to parent-level agent configs:
-
-```markdown
-## Inherits
-- [global](../../AGENTS.md)
-- [team](../AGENTS.md)
-```
-
-AI agents (Claude, Codex, etc.) follow markdown links natively — when they read your project's `AGENTS.md`, they'll traverse the inheritance chain and apply rules from all levels.
+# npm — ships prebuilt native binaries, no Go toolchain needed
+npm install -g @brickhouse-tech/sync-agents
 
-### Hierarchy Example
+# Homebrew
+brew install brickhouse-tech/tap/sync-agents
 
-```
-~/code/                     # Global: security norms, universal rules
-  ├── .agents/
-  ├── AGENTS.md
-  └── org/                  # Org-level: coding standards, shared workflows
-      ├── .agents/
-      ├── AGENTS.md
-      └── team/             # Team-level: language-specific rules
-          ├── .agents/
-          ├── AGENTS.md
-          └── project/      # Project: project-specific rules + inherits
-              ├── .agents/
-              └── AGENTS.md  → ## Inherits links to team, org, global
+# go install (Go 1.21+, no Node needed)
+go install github.com/brickhouse-tech/sync-agents@latest
 ```
 
-**Inheritance is upward-only.** A project declares what it inherits from. Parent directories don't need to know about their children — when an agent works at the org level, it already has access to org-level rules.
+Pre-built archives (with SHA-256 checksums) are also on the [Releases page](https://github.com/brickhouse-tech/sync-agents/releases). More detail in [docs/install.md](docs/install.md).
 
-### Managing Inheritance
+## 60-second quickstart
 
 ```bash
-# Add an inheritance link
-sync-agents inherit global ../../AGENTS.md
-sync-agents inherit team ../AGENTS.md
-
-# List current inheritance links
-sync-agents inherit --list
-
-# Remove an inheritance link
-sync-agents inherit --remove global
-```
+cd your-project
 
-The `## Inherits` section is preserved across `sync-agents index` regenerations.
-
-### Full Example
-
-Set up a three-level hierarchy: global rules → org standards → project config.
-
-```bash
-# 1. Create global rules (e.g. ~/code/.agents/)
-cd ~/code
+# 1. Create .agents/ (rules/, skills/, workflows/, STATE.md) + AGENTS.md index
 sync-agents init
-sync-agents add rule security
-cat > .agents/rules/security.md << 'EOF'
----
-trigger: always_on
----
-# Security
-- Never commit secrets or API keys
-- Validate all external input
-- Use parameterized queries for database access
-EOF
-
-# 2. Create org-level rules (e.g. ~/code/myorg/.agents/)
-cd ~/code/myorg
-sync-agents init
-sync-agents add rule go-standards
-cat > .agents/rules/go-standards.md << 'EOF'
----
-trigger: always_on
----
-# Go Standards
-- Use `gofmt` and `golangci-lint` on all Go files
-- Prefer table-driven tests
-- Export only what consumers need
-EOF
-
-# 3. Create project with inheritance
-cd ~/code/myorg/api-service
-sync-agents init
-sync-agents add rule api-conventions
 
-# Link to parent levels
-sync-agents inherit org ../AGENTS.md
-sync-agents inherit global ../../AGENTS.md
+# 2. Add your first rule and skill
+sync-agents add rule no-secrets
+sync-agents add skill code-review
 
-# Sync to agent directories
+# 3. Fan everything out to .claude/, .windsurf/, .cursor/, .github/copilot/
 sync-agents sync
-```
-
-The project's `AGENTS.md` now looks like:
-
-```markdown
-## Inherits
-- [org](../AGENTS.md)
-- [global](../../AGENTS.md)
-
-## Rules
-- [api-conventions](.agents/rules/api-conventions.md)
-
-## Skills
-_No skills defined yet._
-
-## Workflows
-_No workflows defined yet._
-```
-
-When an AI agent reads this file, it follows the `## Inherits` links and applies rules from all three levels — project-specific API conventions, org-wide Go standards, and global security rules.
-
-### Verifying Inheritance
-
-```bash
-# Check what's inherited
-sync-agents inherit --list
-# Output:
-# - [org](../AGENTS.md)
-# - [global](../../AGENTS.md)
-
-# Remove a link if no longer needed
-sync-agents inherit --remove global
-
-# Re-add with a different path
-sync-agents inherit global ../../AGENTS.md
-```
 
-## Examples
-
-The [`examples/`](examples/) directory contains ready-to-use rules, skills, and workflows. Import them directly:
+# 4. Install a shared skill from another repo (SHA-pinned + scanned + quarantined)
+sync-agents source add skill:anthropic/skill-pack@v1.2.0/skills/code-review
+sync-agents quarantine          # review the scan findings
+sync-agents approve code-review # promote it into .agents/
 
-```bash
-sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/rules/no-secrets.md
-sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/skills/code-review.md
-sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/workflows/pr-checklist.md
+# 5. Check that everything is wired up
+sync-agents status
 ```
 
-See [examples/README.md](examples/README.md) for the full list.
+That's it — every supported tool now reads the same rules, and `AGENTS.md` (symlinked to `CLAUDE.md`) indexes it all automatically.
 
-## Usage
+## Killer features
 
-```bash
-# Initialize .agents/ structure in the current project
-sync-agents init
-
-# Add a new rule
-sync-agents add rule no-eval
-
-# Add a new skill
-sync-agents add skill debugging
+### 📦 Seven buckets, one tree
+Rules, skills, workflows, subagents, plans, specs, and ADRs each get a first-class home under `.agents/`, routed to the right place per tool (ADRs even track proposed/accepted/denied status by directory). [Topology →](docs/topology.md)
 
-# Add a new workflow
-sync-agents add workflow deploy
+### 🔒 Declarative sources with a lockfile
+`sources.yaml` + `sources.lock`: every upstream artifact resolves to a commit SHA, downloads are content-hashed, and a tampered tarball aborts before anything touches disk. `pull`, `update`, `source list` — reproducible like a real package manager. [Sources →](docs/sources.md)
 
-# Add a Claude subagent / a plan / a spec (creates the bucket on demand)
-sync-agents add agent reviewer
-sync-agents add plan q3-roadmap
-sync-agents add spec sso-login
+### 🛡️ Quarantine + static scanning, on by default
+Remote installs are treated like a hostile supply chain. Fetched artifacts are scanned for `curl | bash` patterns, credential-access-plus-network combos, obfuscation, and prompt injection — then held in `.agents/.quarantine/` until you `approve` them. [Quarantine →](docs/quarantine.md)
 
-# Validate + upgrade skill frontmatter
-sync-agents lint
-sync-agents lint --fix
+### 🔗 Linked (editable) sources — *new in 1.4.0*
+`npm link` for agent context: point a source at a live local checkout instead of a frozen snapshot. Edits flow both ways, `git pull` reaps updates, and the link is recorded declaratively so it survives clones. [Linked sources →](docs/linked-sources.md)
 
-# Sync to all targets (.claude/ and .windsurf/)
-sync-agents sync
-
-# Sync to a specific target only
-sync-agents sync --targets claude
+### 🖥️ OS-scoped routing
+Drop rules into `rules/macos/`, `rules/linux/`, or `rules/unix/` and they only sync on matching machines. One committed tree, no brew-rules noise on your Linux box. [OS routing →](docs/os-scoped-routing.md)
 
-# Preview sync without making changes
-sync-agents sync --dry-run
+### 🗂️ AGENTS.md auto-index
+Every artifact is indexed into a generated `AGENTS.md` (symlinked to `CLAUDE.md`), with descriptions pulled from frontmatter, passive rules `@`-imported for Claude, and an `## Inherits` section for org → team → project rule hierarchies. [Index →](docs/commands/index.md) · [Inheritance →](docs/inheritance.md)
 
-# Force overwrite existing symlinks
-sync-agents sync --force
+### ✅ Lint for skill compliance
+`sync-agents lint` validates every `SKILL.md` against Claude's published authoring rules (name format, description quality, reserved words) and `--fix` mechanically repairs what it can. CI-friendly exit codes. [Lint →](docs/commands/lint.md)
 
-# Check sync status
-sync-agents status
+### 🌍 Global scope too
+`promote` an artifact from a project to your user-level `~/.agents/`, then `global sync` fans it out to every tool's *user* config dir with semantic-aware routing. [Global commands →](docs/commands/global-sync.md)
 
-# Regenerate the AGENTS.md index
-sync-agents index
+## Documentation
 
-# Remove all synced symlinks
-sync-agents clean
+The full manual lives in [`docs/`](docs/README.md):
 
-# Fix legacy layouts and broken symlinks
-sync-agents fix
+- [Command reference](docs/commands/README.md) — every command and flag
+- [Topology & configuration](docs/topology.md) — the `.agents/` tree, `config`, `STATE.md`
+- [Sources, lockfile & provenance](docs/sources.md) · [Quarantine](docs/quarantine.md) · [Linked sources](docs/linked-sources.md)
+- [Inheritance](docs/inheritance.md) · [ADRs](docs/adrs.md) · [OS-scoped routing](docs/os-scoped-routing.md)
+- [Architecture](docs/README.md#architecture) — scope resolution, semantic routing, global roots
+- [Examples](examples/README.md) — ready-to-import rules, skills, and workflows
 
-# Fix only skills (migrate + convert flat files + repair symlinks)
-sync-agents fix skills
+## License
 
-# Work in a different directory
-sync-agents sync --dir /path/to/project
-```
+[MIT](LICENSE) © Brickhouse Tech
diff --git a/docs/README.md b/docs/README.md
index d2cfd13..23f8f43 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,6 +8,38 @@ form that's easier to read end-to-end than scattered code comments.
 
 ## Index
 
+### Getting started
+
+- [Installation](./install.md) — every install channel (npm, Homebrew,
+  `go install`, GitHub Releases) with the trade-offs of each.
+- [Topology & configuration](./topology.md) — the `.agents/` tree
+  layout, optional buckets (`agents/`, `plans/`, `specs/`, `hooks/`,
+  `adrs/`), `STATE.md`, and the `.agents/config` file.
+- [Command reference](./commands/README.md) — every command and flag
+  in one table, plus common usage.
+
+### Features
+
+- [Source manifest, lockfile & provenance](./sources.md) — declare
+  upstream rules/skills/trees in `sources.yaml`; `pull` installs them
+  SHA-pinned, content-hashed against `sources.lock`, with per-artifact
+  origin metadata.
+- [Quarantine (remote content review)](./quarantine.md) — remotely
+  fetched artifacts are statically scanned and held in
+  `.agents/.quarantine/` until approved; escape hatches are loud and
+  audited.
+- [Linked (editable) sources](./linked-sources.md) — `npm link` for
+  agent context: symlink a source at a live local checkout; edits flow
+  both ways; recorded declaratively in the manifest.
+- [Inheritance](./inheritance.md) — hierarchical rule sharing via
+  `## Inherits` links in `AGENTS.md` (project → team → org → global).
+- [ADRs](./adrs.md) — Architecture Decision Records with status
+  encoded by subdirectory; denied records stay on disk so they aren't
+  re-proposed.
+- [OS-scoped routing](./os-scoped-routing.md) — `macos/`, `linux/`,
+  `unix/`, `windows/` subdirectories under any bucket sync only on
+  matching hosts.
+
 ### Architecture
 
 - [Scope and target directories](./architecture/scope-and-targets.md) —
@@ -28,28 +60,28 @@ form that's easier to read end-to-end than scattered code comments.
   per-bucket defaults to route correctly into each tool's matching
   destination.
 
-### Commands
-
-- [`sync-agents promote`](./commands/promote.md) — Copy a project
-  artifact (rule, skill, or workflow) into the user-scope
-  `~/.agents/` tree. Supports both canonical
-  (`promote <type> <name>`) and path-form (`promote <path>`)
-  invocation.
-- [`sync-agents global init`](./commands/global-init.md) — Create
-  the user's global `.agents/` skeleton (`rules/`, `skills/`,
-  `workflows/`, `config`). Idempotent.
-- [`sync-agents global sync`](./commands/global-sync.md) — Fan the
-  global `~/.agents/` tree out to per-tool global directories
-  (`~/.claude/`, `~/.codeium/`, …) using semantic-aware routing.
-  Composable with `promote --sync`.
+### Command deep-dives
+
+- [`sync-agents index`](./commands/index.md) — AGENTS.md regeneration,
+  section-by-section, including the skill frontmatter backfill.
+- [`sync-agents lint`](./commands/lint.md) — SKILL.md compliance
+  checks against Claude's authoring rules, with the full finding
+  table.
+- [`sync-agents fix`](./commands/fix.md) — legacy-layout migration,
+  flat-skill conversion, and symlink repair.
+- [`sync-agents promote`](./commands/promote.md) — copy a project
+  artifact into the user-scope `~/.agents/` tree.
+- [`sync-agents global init`](./commands/global-init.md) — create the
+  user's global `.agents/` skeleton. Idempotent.
+- [`sync-agents global sync`](./commands/global-sync.md) — fan the
+  global `~/.agents/` tree out to per-tool global directories with
+  semantic-aware routing.
 - [`sync-agents global status`](./commands/global-status.md) —
-  Read-only report of every per-tool destination's state: synced,
-  drifted, missing, not-a-symlink, or per-concat ok/stale/missing/
-  foreign. Output is grep-friendly.
-- [`sync-agents global clean`](./commands/global-clean.md) — Remove
+  read-only, grep-friendly report of every per-tool destination's
+  state.
+- [`sync-agents global clean`](./commands/global-clean.md) — remove
   sync-agents-owned symlinks and concat files from per-tool global
-  dirs. Two-check safety contract: symlinks must point into
-  `~/.agents/`, files must carry the banner.
+  dirs.
 
 ### Specs
 
@@ -57,14 +89,18 @@ The authoritative source for *what we're building and why* lives in
 [`specs/`](../specs/) at the repo root. This folder may reference SPEC
 IDs but is never the source of truth for them.
 
-- [SPEC-001](../specs/SPEC-001-go-install-first-class.md) — first-class
-  `go install` and goreleaser-based release.
-- [SPEC-002](../specs/SPEC-002-promote-global-sync.md) — promote and
-  global sync with semantic-aware routing across Claude, Windsurf,
-  Cursor, Copilot, Codex.
-- [SPEC-003](../specs/SPEC-003-source-manifest-pull.md) — declarative
-  source manifest for pulling rules, skills, and workflows from
-  upstream repositories.
+Only specs with **open work** are kept in the tree; fully-shipped specs
+(SPEC-001 go-install/goreleaser, SPEC-002 promote/global sync, SPEC-003
+source manifest, SPEC-004 asset buckets, SPEC-007 linked sources) are
+retired to git history — `git log --all --oneline -- specs/` finds
+them.
+
+- [SPEC-005](../specs/SPEC-005-sandboxing-quarantine.md) — supply-chain
+  safety: Parts A+B (fetch hardening, quarantine + scan) shipped;
+  Part C (sandboxed skill exec) open.
+- [SPEC-006](../specs/SPEC-006-os-scoped-routing.md) — OS-scoped
+  routing: core shipped; AGENTS.md OS badge and concat OS headers
+  open.
 
 ## Conventions
 
@@ -73,7 +109,8 @@ IDs but is never the source of truth for them.
 - Every doc file ends with a `## See also` section linking related
   docs and the relevant SPEC IDs.
 - When a doc explains a behavior that was specified, link to the SPEC
-  at the bottom rather than restating it.
+  at the bottom rather than restating it. If the spec has been retired
+  to git history, reference the SPEC ID as plain text.
 - Prefer prose over bullet salad for conceptual material. Reserve
   bullets for enumerations and checklists.
 
diff --git a/docs/adrs.md b/docs/adrs.md
new file mode 100644
index 0000000..5dde72e
--- /dev/null
+++ b/docs/adrs.md
@@ -0,0 +1,31 @@
+# ADRs (Architecture Decision Records)
+
+How the `adrs/` bucket encodes decision status by subdirectory and keeps rejected decisions from being re-proposed.
+
+## Status by subdirectory
+
+ADRs live in `.agents/adrs/` with **status encoded by subdirectory**:
+`proposed/`, `accepted/`, `denied/`. `add adr <name>` scaffolds into
+`proposed/`; `sync-agents adr accept|deny|propose <name>` moves a
+record between statuses (nested grouping subdirs are preserved) and
+regenerates the index.
+
+## Indexing rules
+
+Only **accepted and proposed** records appear in `AGENTS.md`. Denied
+records are kept on disk and the index carries a standing note telling
+agents to check `.agents/adrs/denied/` before proposing a new ADR — so
+already-rejected decisions don't get re-proposed.
+
+## Usage
+
+```bash
+sync-agents add adr use-postgres      # → .agents/adrs/proposed/use-postgres.md
+sync-agents adr accept use-postgres   # → .agents/adrs/accepted/, reindexed
+sync-agents adr deny use-postgres     # → .agents/adrs/denied/, dropped from index
+```
+
+## See also
+
+- [Topology & configuration](./topology.md)
+- [`sync-agents index`](./commands/index.md)
diff --git a/docs/architecture/global-root-resolution.md b/docs/architecture/global-root-resolution.md
index 24bf45d..233aa5f 100644
--- a/docs/architecture/global-root-resolution.md
+++ b/docs/architecture/global-root-resolution.md
@@ -98,6 +98,6 @@ will fail with a clearer error than the resolver itself could give.
 
 - [Scope and target directories](./scope-and-targets.md) — how the
   resolved global root composes with per-tool dir names.
-- [SPEC-002 §Configurable global root](../../specs/SPEC-002-promote-global-sync.md) —
+- SPEC-002 §Configurable global root (shipped; spec retired to git history) —
   the spec that requires this resolver.
 - `internal/agent/globalroot.go` — the implementation.
diff --git a/docs/architecture/scope-and-targets.md b/docs/architecture/scope-and-targets.md
index 675f331..df86865 100644
--- a/docs/architecture/scope-and-targets.md
+++ b/docs/architecture/scope-and-targets.md
@@ -87,7 +87,7 @@ the registry.
 
 - [Global root resolution](./global-root-resolution.md) — the
   precedence chain that determines the global canonical path.
-- [SPEC-002](../../specs/SPEC-002-promote-global-sync.md) — the spec
+- SPEC-002 (shipped; spec retired to git history) — the spec
   that introduced global scope, the `Tool.DirByScope` model, and the
   semantic-aware routing layer that builds on top of it.
 - `internal/agent/scope.go`, `internal/agent/tool.go`,
diff --git a/docs/architecture/semantic-routing.md b/docs/architecture/semantic-routing.md
index 24b16f4..3b086e3 100644
--- a/docs/architecture/semantic-routing.md
+++ b/docs/architecture/semantic-routing.md
@@ -138,8 +138,8 @@ output is a derived artifact.
 
 ## See also
 
-- [SPEC-002 §Semantic categories (bucket ≠ semantic)](../../specs/SPEC-002-promote-global-sync.md)
-- [SPEC-002 §Requirement: Semantic-aware routing](../../specs/SPEC-002-promote-global-sync.md)
+- SPEC-002 §Semantic categories (bucket ≠ semantic) (shipped; spec retired to git history)
+- SPEC-002 §Requirement: Semantic-aware routing (shipped; spec retired to git history)
 - [Scope and target directories](./scope-and-targets.md)
 - `internal/agent/semantic.go` — `Semantic`, `BucketDefaultSemantic`,
   `ParseFrontmatterInvocable`, `ResolveSemantic`.
diff --git a/docs/commands/README.md b/docs/commands/README.md
new file mode 100644
index 0000000..1f9111e
--- /dev/null
+++ b/docs/commands/README.md
@@ -0,0 +1,123 @@
+# Command reference
+
+Every `sync-agents` command and global option, with links to the deep-dive doc where one exists.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `init` | Initialize the `.agents/` directory structure with `rules/`, `skills/`, `workflows/`, `STATE.md`, and generate `AGENTS.md` |
+| `sync` | Create symlinks from `.agents/` into all target directories, and symlink `AGENTS.md` to `CLAUDE.md` |
+| `watch` | Watch `.agents/` for changes and auto-regenerate `AGENTS.md` |
+| `import <url>` | Import a rule/skill/workflow from a URL |
+| `pull [--dry-run\|--offline\|--force\|--only NAME\|--global]` | Fetch every `sources.yaml` entry, verify integrity, install into the matching buckets ([sources](../sources.md)) |
+| `update [NAME]` | Re-resolve refs and re-pull entries whose upstream moved; SHA-pinned entries are skipped |
+| `source add <entry>` | Append an entry to `sources.yaml` and pull it |
+| `source add --link[=<path>] [<entry>]` | Declare a **linked (editable)** source — symlink a live local checkout instead of a fetched snapshot ([linked sources](../linked-sources.md)) |
+| `source remove <name> [--keep]` | Remove the manifest entry and delete the artifact (`--keep` converts it to manual) |
+| `source list [--json]` | Show each entry's local state: `ok` / `outdated` / `modified` / `missing` / `linked` |
+| `source bundle` | Rebuild `sources.yaml` from installed artifacts' origin metadata |
+| `source detach <name>` | Un-manage an artifact: flip its origin to manual and drop the manifest entry (for a **linked** source, freeze the live copy into a vendored snapshot) |
+| `quarantine` | List remotely-fetched artifacts awaiting review, with their scan findings ([quarantine](../quarantine.md)) |
+| `approve <name>\|--all [--force]` | Promote a quarantined artifact into `.agents/` (`--force` accepts critical findings, recorded in the lock) |
+| `reject <name>\|--all` | Delete a quarantined artifact without installing it |
+| `git-hook` | Install a pre-commit git hook for auto-sync (`hook` remains as a deprecated alias) |
+| `inherit <label> <path>` | Add an inheritance link to AGENTS.md ([inheritance](../inheritance.md)) |
+| `inherit --list` | List current inheritance links |
+| `inherit --remove <label>` | Remove an inheritance link by label |
+| `status` | Show the current sync status of all targets and symlinks |
+| `add <type> <name>` | Add a new artifact from a template (type is `rule`, `skill`, `workflow`, `agent`, `plan`, `spec`, `hook`, or `adr`) |
+| `index [--no-fix]` | Regenerate `AGENTS.md` by scanning `.agents/`. Backfills fixable skill frontmatter first (`--no-fix` skips the backfill) ([index](./index.md)) |
+| `adr <accept\|deny\|propose> <name>` | Move an ADR between status directories, update its `status:` frontmatter, and reindex ([ADRs](../adrs.md)) |
+| `lint [skills] [--fix]` | Validate SKILL.md frontmatter against [Claude's skill authoring rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices); `--fix` amends fixable findings in place ([lint](./lint.md)) |
+| `clean` | Remove all synced symlinks and empty target directories (does not remove `.agents/`) |
+| `fix [type]` | Migrate legacy dirs into `.agents/`, convert flat skill files to directory layout, and repair broken symlinks. Type: any bucket dir, or `all` (default) ([fix](./fix.md)) |
+| `promote <type> <name>` | Copy an artifact from the project's `.agents/` to the user-level global store (`~/.agents/`) ([promote](./promote.md)) |
+| `global init` | Initialize the global `~/.agents/` store ([global init](./global-init.md)) |
+| `global sync` | Fan the global store out to each tool's user-level config dir with semantic-aware routing ([global sync](./global-sync.md)) |
+| `global status` | Show per-artifact sync state across global tool dirs ([global status](./global-status.md)) |
+| `global clean` | Remove global symlinks/concat files owned by sync-agents ([global clean](./global-clean.md)) |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-h`, `--help` | Show help message |
+| `-v`, `--version` | Show version |
+| `-d`, `--dir <path>` | Set project root directory (default: current directory) |
+| `--targets <list>` | Comma-separated list of sync targets (default: `claude,windsurf,cursor,copilot`) |
+| `--dry-run` | Show what would be done without making changes |
+| `--force` | Overwrite existing files and symlinks |
+| `--no-clobber` | (fix only) Skip items that already exist in `.agents/` instead of merging |
+| `--fix` | (lint only) Amend fixable frontmatter findings in place |
+| `--no-fix` | (index only) Skip the skill frontmatter backfill |
+| `--trust` | (pull/update only) Bypass the quarantine gate; the scan still runs and prints findings |
+
+## Common usage
+
+```bash
+# Initialize .agents/ structure in the current project
+sync-agents init
+
+# Add a new rule / skill / workflow
+sync-agents add rule no-eval
+sync-agents add skill debugging
+sync-agents add workflow deploy
+
+# Add a Claude subagent / a plan / a spec (creates the bucket on demand)
+sync-agents add agent reviewer
+sync-agents add plan q3-roadmap
+sync-agents add spec sso-login
+
+# Validate + upgrade skill frontmatter
+sync-agents lint
+sync-agents lint --fix
+
+# Sync to all targets
+sync-agents sync
+
+# Sync to a specific target only
+sync-agents sync --targets claude
+
+# Preview sync without making changes
+sync-agents sync --dry-run
+
+# Force overwrite existing symlinks
+sync-agents sync --force
+
+# Check sync status
+sync-agents status
+
+# Regenerate the AGENTS.md index
+sync-agents index
+
+# Remove all synced symlinks
+sync-agents clean
+
+# Fix legacy layouts and broken symlinks
+sync-agents fix
+
+# Work in a different directory
+sync-agents sync --dir /path/to/project
+```
+
+## Importing single artifacts
+
+The [`examples/`](../../examples/) directory contains ready-to-use
+rules, skills, and workflows. Import them directly:
+
+```bash
+sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/rules/no-secrets.md
+sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/skills/code-review.md
+sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/workflows/pr-checklist.md
+```
+
+See [examples/README.md](../../examples/README.md) for the full list.
+For reproducible, SHA-pinned installs prefer the
+[source manifest](../sources.md) over one-shot `import`.
+
+## See also
+
+- [Topology & configuration](../topology.md)
+- [Sources, lockfile & provenance](../sources.md)
+- [Docs index](../README.md)
diff --git a/docs/commands/fix.md b/docs/commands/fix.md
new file mode 100644
index 0000000..acac2b1
--- /dev/null
+++ b/docs/commands/fix.md
@@ -0,0 +1,44 @@
+# `sync-agents fix [type]`
+
+Migrates legacy layouts into the canonical `.agents/` structure and repairs broken symlinks.
+
+## Scenarios
+
+The `fix` command handles three scenarios:
+
+1. **Legacy directory migration** — Moves top-level `skills/`,
+   `rules/`, or `workflows/` directories into `.agents/` and replaces
+   them with symlinks.
+2. **Flat skill conversion** — Converts `.agents/skills/name.md` flat
+   files to the directory layout `.agents/skills/name/SKILL.md`.
+3. **Symlink repair** — Recreates missing or broken symlinks in target
+   directories (`.claude/`, `.windsurf/`, etc.) and the `CLAUDE.md`
+   symlink.
+
+## Usage
+
+```bash
+# Fix everything (all types)
+sync-agents fix
+
+# Fix only skills
+sync-agents fix skills
+
+# Preview without changing anything
+sync-agents fix --dry-run
+
+# Don't overwrite items already in .agents/
+sync-agents fix --no-clobber skills
+```
+
+A reproducible demo is available in
+[`examples/fix/`](../../examples/fix/):
+
+```bash
+bash examples/fix/run-demo.sh
+```
+
+## See also
+
+- [Topology & configuration](../topology.md)
+- [Command reference](./README.md)
diff --git a/docs/commands/global-clean.md b/docs/commands/global-clean.md
index 4798a0e..1c88e73 100644
--- a/docs/commands/global-clean.md
+++ b/docs/commands/global-clean.md
@@ -108,7 +108,7 @@ permissions, say) produce warnings but don't abort the loop.
 
 ## See also
 
-- [SPEC-002 §Requirement: Global clean](../../specs/SPEC-002-promote-global-sync.md)
+- SPEC-002 §Requirement: Global clean (shipped; spec retired to git history)
 - [`sync-agents global sync`](./global-sync.md)
 - [`sync-agents global status`](./global-status.md)
 - `internal/agent/globalclean.go` — the implementation.
diff --git a/docs/commands/global-init.md b/docs/commands/global-init.md
index 8a824f5..e2a5b6b 100644
--- a/docs/commands/global-init.md
+++ b/docs/commands/global-init.md
@@ -89,7 +89,7 @@ add any missing subdirectories without disturbing existing content.
 
 ## See also
 
-- [SPEC-002 §Global agents directory](../../specs/SPEC-002-promote-global-sync.md)
+- SPEC-002 §Global agents directory (shipped; spec retired to git history)
 - [Global root resolution](../architecture/global-root-resolution.md)
 - [Scope and target directories](../architecture/scope-and-targets.md)
 - `internal/agent/globalinit.go` — the implementation.
diff --git a/docs/commands/global-status.md b/docs/commands/global-status.md
index 4ff006d..f9ec889 100644
--- a/docs/commands/global-status.md
+++ b/docs/commands/global-status.md
@@ -94,7 +94,7 @@ sync-agents global status --global-root /tmp/.agents
 
 ## See also
 
-- [SPEC-002 §Requirement: Global status](../../specs/SPEC-002-promote-global-sync.md)
+- SPEC-002 §Requirement: Global status (shipped; spec retired to git history)
 - [`sync-agents global sync`](./global-sync.md)
 - [`sync-agents global clean`](./global-clean.md)
 - `internal/agent/globalstatus.go` — the implementation.
diff --git a/docs/commands/global-sync.md b/docs/commands/global-sync.md
index d08cebb..198414e 100644
--- a/docs/commands/global-sync.md
+++ b/docs/commands/global-sync.md
@@ -141,7 +141,7 @@ preferable to all-or-nothing for fan-out operations.
 ## What `global sync` does NOT do
 
 - It does not pull artifacts from upstream repos — that's
-  [SPEC-003](../../specs/SPEC-003-source-manifest-pull.md).
+  SPEC-003 (shipped; spec retired to git history).
 - It does not regenerate per-project sync targets (the local
   `.claude/`, `.windsurf/`, etc.). Use the existing `sync-agents
   sync` command for project scope.
@@ -150,8 +150,8 @@ preferable to all-or-nothing for fan-out operations.
 
 ## See also
 
-- [SPEC-002 §Requirement: Global sync](../../specs/SPEC-002-promote-global-sync.md)
-- [SPEC-002 §Requirement: Semantic-aware routing](../../specs/SPEC-002-promote-global-sync.md)
+- SPEC-002 §Requirement: Global sync (shipped; spec retired to git history)
+- SPEC-002 §Requirement: Semantic-aware routing (shipped; spec retired to git history)
 - [Semantic routing](../architecture/semantic-routing.md)
 - [Scope and target directories](../architecture/scope-and-targets.md)
 - [`sync-agents promote`](./promote.md)
diff --git a/docs/commands/lint.md b/docs/commands/lint.md
index ec0d198..5bba1c7 100644
--- a/docs/commands/lint.md
+++ b/docs/commands/lint.md
@@ -4,6 +4,16 @@ Validates every `.agents/skills/<dir>/SKILL.md` against Claude's
 [skill authoring rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
 and, with `--fix`, mechanically amends what's fixable (SPEC-004 Part E).
 
+Claude discovers skills through their `SKILL.md` YAML frontmatter, with
+published requirements: `name` (≤64 chars, lowercase
+letters/numbers/hyphens, no reserved words) and `description`
+(non-empty, ≤1024 chars, third person, says what the skill does *and
+when to use it*). `lint --fix` amends what it can — injecting a missing
+frontmatter block, deriving `name` from the directory, deriving
+`description` from the first body paragraph, truncating overlong
+values, and stripping XML tags — while preserving all other frontmatter
+keys verbatim. Reserved-word names are reported but never auto-renamed.
+
 ## Checks
 
 | Code | Rule | `--fix` action |
diff --git a/docs/commands/promote.md b/docs/commands/promote.md
index 18683aa..2328177 100644
--- a/docs/commands/promote.md
+++ b/docs/commands/promote.md
@@ -126,7 +126,7 @@ sync-agents promote --global-root /tmp/test/.agents rule security
 
 ## See also
 
-- [SPEC-002 §Promote command](../../specs/SPEC-002-promote-global-sync.md)
+- SPEC-002 §Promote command (shipped; spec retired to git history)
 - [Global root resolution](../architecture/global-root-resolution.md)
 - [Scope and target directories](../architecture/scope-and-targets.md)
 - `internal/agent/promote.go` — the implementation.
diff --git a/docs/inheritance.md b/docs/inheritance.md
new file mode 100644
index 0000000..9679e06
--- /dev/null
+++ b/docs/inheritance.md
@@ -0,0 +1,148 @@
+# Inheritance
+
+Convention-based hierarchical rule sharing: projects link upward to team, org, and global `AGENTS.md` files instead of duplicating rules.
+
+## How it works
+
+Add an `## Inherits` section to your project's `AGENTS.md` that links
+to parent-level agent configs:
+
+```markdown
+## Inherits
+- [global](../../AGENTS.md)
+- [team](../AGENTS.md)
+```
+
+AI agents (Claude, Codex, etc.) follow markdown links natively — when
+they read your project's `AGENTS.md`, they'll traverse the inheritance
+chain and apply rules from all levels.
+
+## Hierarchy example
+
+```
+~/code/                     # Global: security norms, universal rules
+  ├── .agents/
+  ├── AGENTS.md
+  └── org/                  # Org-level: coding standards, shared workflows
+      ├── .agents/
+      ├── AGENTS.md
+      └── team/             # Team-level: language-specific rules
+          ├── .agents/
+          ├── AGENTS.md
+          └── project/      # Project: project-specific rules + inherits
+              ├── .agents/
+              └── AGENTS.md  → ## Inherits links to team, org, global
+```
+
+**Inheritance is upward-only.** A project declares what it inherits
+from. Parent directories don't need to know about their children — when
+an agent works at the org level, it already has access to org-level
+rules.
+
+## Managing inheritance
+
+```bash
+# Add an inheritance link
+sync-agents inherit global ../../AGENTS.md
+sync-agents inherit team ../AGENTS.md
+
+# List current inheritance links
+sync-agents inherit --list
+
+# Remove an inheritance link
+sync-agents inherit --remove global
+```
+
+The `## Inherits` section is preserved across `sync-agents index`
+regenerations.
+
+## Full example
+
+Set up a three-level hierarchy: global rules → org standards → project
+config.
+
+```bash
+# 1. Create global rules (e.g. ~/code/.agents/)
+cd ~/code
+sync-agents init
+sync-agents add rule security
+cat > .agents/rules/security.md << 'EOF'
+---
+trigger: always_on
+---
+# Security
+- Never commit secrets or API keys
+- Validate all external input
+- Use parameterized queries for database access
+EOF
+
+# 2. Create org-level rules (e.g. ~/code/myorg/.agents/)
+cd ~/code/myorg
+sync-agents init
+sync-agents add rule go-standards
+cat > .agents/rules/go-standards.md << 'EOF'
+---
+trigger: always_on
+---
+# Go Standards
+- Use `gofmt` and `golangci-lint` on all Go files
+- Prefer table-driven tests
+- Export only what consumers need
+EOF
+
+# 3. Create project with inheritance
+cd ~/code/myorg/api-service
+sync-agents init
+sync-agents add rule api-conventions
+
+# Link to parent levels
+sync-agents inherit org ../AGENTS.md
+sync-agents inherit global ../../AGENTS.md
+
+# Sync to agent directories
+sync-agents sync
+```
+
+The project's `AGENTS.md` now looks like:
+
+```markdown
+## Inherits
+- [org](../AGENTS.md)
+- [global](../../AGENTS.md)
+
+## Rules
+- [api-conventions](.agents/rules/api-conventions.md)
+
+## Skills
+_No skills defined yet._
+
+## Workflows
+_No workflows defined yet._
+```
+
+When an AI agent reads this file, it follows the `## Inherits` links
+and applies rules from all three levels — project-specific API
+conventions, org-wide Go standards, and global security rules.
+
+## Verifying inheritance
+
+```bash
+# Check what's inherited
+sync-agents inherit --list
+# Output:
+# - [org](../AGENTS.md)
+# - [global](../../AGENTS.md)
+
+# Remove a link if no longer needed
+sync-agents inherit --remove global
+
+# Re-add with a different path
+sync-agents inherit global ../../AGENTS.md
+```
+
+## See also
+
+- [`sync-agents index`](./commands/index.md)
+- [Global root resolution](./architecture/global-root-resolution.md)
+- [`sync-agents promote`](./commands/promote.md) — the other way to
+  share rules across projects (via the user-level `~/.agents/`)
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..4985565
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,56 @@
+# Installation
+
+Every supported install channel for the `sync-agents` binary, with the trade-offs of each.
+
+## npm (recommended for Node.js projects)
+
+Ships native Go binaries via per-platform optional packages — no build
+step, no Go toolchain required.
+
+```bash
+npm install -g @brickhouse-tech/sync-agents
+```
+
+Or as a project devDependency:
+
+```bash
+npm install --save-dev @brickhouse-tech/sync-agents
+```
+
+## go install (no Node.js required)
+
+```bash
+go install github.com/brickhouse-tech/sync-agents@latest
+```
+
+Requires Go 1.21+. The binary is placed in `$GOPATH/bin` (or
+`$HOME/go/bin`). Version is read from the module proxy at install time
+via `debug.ReadBuildInfo`.
+
+## Homebrew
+
+```bash
+brew install brickhouse-tech/tap/sync-agents
+```
+
+The tap is updated automatically on every release via GoReleaser.
+
+## GitHub Releases (pre-built binaries)
+
+Download the archive for your platform from the
+[Releases page](https://github.com/brickhouse-tech/sync-agents/releases),
+extract, and place the binary on your `PATH`:
+
+```bash
+# Example: macOS arm64
+curl -fsSL https://github.com/brickhouse-tech/sync-agents/releases/latest/download/sync-agents_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/').tar.gz | tar -xz
+sudo mv sync-agents /usr/local/bin/
+```
+
+SHA-256 checksums are published alongside each release as
+`checksums.txt`.
+
+## See also
+
+- [Command reference](./commands/README.md)
+- [Topology & configuration](./topology.md)
diff --git a/docs/linked-sources.md b/docs/linked-sources.md
new file mode 100644
index 0000000..93bf22e
--- /dev/null
+++ b/docs/linked-sources.md
@@ -0,0 +1,63 @@
+# Linked (editable) sources
+
+The `npm link` / `go mod replace` of `.agents/` — symlink an artifact at a live local checkout instead of a fetched snapshot, so edits flow both ways.
+
+## Why
+
+When you're **actively developing** a skill that lives in another repo
+(or the upstream repo itself), a SHA-pinned snapshot forces a slow
+`edit → commit → push → update` loop. A **linked** source instead
+symlinks the artifact at a live local checkout, so edits flow both ways
+and `git pull` in the checkout reaps updates with no re-fetch.
+
+## Usage
+
+```bash
+# Link a checkout you already have (path relative to cwd or absolute):
+sync-agents source add --link=../foo-skill skill:me/foo-skill
+
+# Derive the entry from the checkout's github remote + layout:
+sync-agents source add --link=../foo-skill
+
+# Managed clone: sync-agents clones the repo under .agents/.sources/ and links out of it
+# (the initial clone is scanned once through the quarantine scanner; --trust to skip):
+sync-agents source add --link skill:me/foo-skill
+```
+
+## Declarative and committed
+
+The link is recorded declaratively as a `link:` override in
+`sources.yaml` and echoed in `sources.lock`, so the intent is committed
+and reviewable:
+
+```yaml
+overrides:
+  - match: skill:me/foo-skill
+    link: file:../foo-skill      # relative to .agents/; mutually exclusive with pin_sha
+```
+
+All persisted paths are **relative** (`file:` scheme) and the on-disk
+symlink is created relative too — an absolute path would break the
+instant another machine cloned the repo, so absolute `file:` paths are
+rejected at parse time.
+
+## Behavior
+
+- `pull` verifies (and self-heals) the symlink and never re-fetches a
+  snapshot over it; a missing checkout surfaces as a warning, not a
+  silent revert.
+- `update` advances a **managed clone** with `git pull --ff-only` (a
+  checkout you own is yours to drive).
+- `source list` shows linked entries as
+  `[linked] … link → file:../foo-skill`.
+- `source detach` **freezes** the live copy into an ordinary vendored
+  snapshot (materialize the files, drop the `link` override, keep the
+  upstream identity).
+- Because a linked source is a local working tree you own, it is
+  trusted by default — only the first fetch of a managed clone is
+  scanned.
+
+## See also
+
+- [Source manifest, lockfile & provenance](./sources.md)
+- [Quarantine (remote content review)](./quarantine.md)
diff --git a/docs/os-scoped-routing.md b/docs/os-scoped-routing.md
new file mode 100644
index 0000000..86ce4e5
--- /dev/null
+++ b/docs/os-scoped-routing.md
@@ -0,0 +1,55 @@
+# OS-scoped routing
+
+Per-platform rules, skills, and workflows: OS-named subdirectories under any bucket route only on matching hosts.
+
+## Layout
+
+Any `.agents/` bucket may carry optional OS-scoped subdirectories
+(`macos/`, `linux/`, `unix/`, `windows/`) whose contents route **only**
+when the host matches:
+
+```
+.agents/
+├── rules/
+│   ├── security.md          → always
+│   ├── macos/
+│   │   └── brew.md          → Darwin only
+│   ├── linux/
+│   │   └── apt.md           → Linux only
+│   └── unix/
+│       └── posix.md         → Darwin + Linux (not Windows)
+```
+
+The OS gate is applied at **sync time** via `runtime.GOOS`. Root-level
+files are always synced (no gate), so a tree without OS subdirs behaves
+exactly as before. `init` never creates OS subdirs — they activate when
+you create them, the same opt-in model as the optional buckets.
+
+## Why
+
+- Homelab/server skill sets differ from desktop Mac workflows: `brew`
+  rules are noise on a Linux box, `apt` rules are noise on a Mac.
+- Cross-platform teams commit one `.agents/` tree; without OS gating,
+  every dev gets every rule regardless of their OS.
+- `unix/` covers the common case (POSIX conventions that apply to
+  macOS and Linux but not Windows) without duplicating files.
+
+## Routing details
+
+Destination paths mirror the source tree
+(`.agents/rules/macos/brew.md` → `.claude/rules/macos/brew.md`), so
+multiple platforms' artifacts never collide in a flat target dir. The
+managed CLAUDE.md `@`-import block includes only rules from matching OS
+subdirs. `.agents/config` accepts an `os = <goos>` override for testing
+and cross-compile CI.
+
+This is a **routing** feature — it gates which artifacts reach which
+machines. It is orthogonal to the quarantine/sandboxing work, which
+controls what a skill can *do* once loaded.
+
+## See also
+
+- [Topology & configuration](./topology.md)
+- [SPEC-006](../specs/SPEC-006-os-scoped-routing.md) — design spec,
+  including the remaining cosmetic items (AGENTS.md OS badge, concat
+  OS headers)
diff --git a/docs/quarantine.md b/docs/quarantine.md
new file mode 100644
index 0000000..44de4c4
--- /dev/null
+++ b/docs/quarantine.md
@@ -0,0 +1,42 @@
+# Quarantine (remote content review)
+
+Why remotely-fetched artifacts land in a scanned holding area by default, and how to review, approve, or reject them.
+
+## The gate
+
+Remote installs are treated like a hostile supply chain. By default,
+everything `pull`/`update` fetches lands in `.agents/.quarantine/` —
+invisible to `sync` and the index — after a static scan for:
+
+- network-then-execute patterns (`curl | bash`),
+- credential access combined with network calls,
+- obfuscation (long base64, zero-width Unicode),
+- prompt-injection phrasing aimed at your agent.
+
+## Workflow
+
+```bash
+sync-agents pull                  # → 1 quarantined (run `sync-agents quarantine`)
+sync-agents quarantine            # review findings per artifact
+sync-agents approve code-review   # promote into .agents/ (blocked on CRITICAL unless --force)
+sync-agents reject sketchy-rule   # delete without installing
+```
+
+## Escape hatches (loud by design)
+
+- Critical findings block `approve`; overriding with `--force` is
+  recorded in `sources.lock` as `approved_with_findings` so the
+  decision is auditable.
+- `--trust` on `pull`/`update` skips the gate for one invocation —
+  findings still print.
+- `quarantine = off` in `.agents/config` disables the gate for teams
+  that review via pinned SHAs in PRs instead.
+
+Local authoring (`add`, `promote`) never quarantines — the gate applies
+to remote content only.
+
+## See also
+
+- [Source manifest, lockfile & provenance](./sources.md)
+- [SPEC-005](../specs/SPEC-005-sandboxing-quarantine.md) — the design
+  spec, including the open Part C (sandboxed skill exec)
diff --git a/docs/sources.md b/docs/sources.md
new file mode 100644
index 0000000..8b8a029
--- /dev/null
+++ b/docs/sources.md
@@ -0,0 +1,58 @@
+# Source manifest, lockfile & provenance
+
+Declarative, reproducible installation of `.agents/` artifacts from upstream GitHub repositories — the package-manager layer of sync-agents.
+
+## The manifest
+
+Declare upstream rules, skills, workflows — or whole `.agents/` trees —
+in `.agents/sources.yaml` and install them reproducibly:
+
+```yaml
+version: 1
+sources:
+  - skill:anthropic/skill-pack@v1.2.0/skills/code-review
+  - rule:my-org/agent-norms@main/rules/security.md
+  - tree:my-org/team-agents@v2.0.0   # fans out to every bucket in the upstream .agents/
+```
+
+## How `pull` works
+
+`sync-agents pull` resolves each ref to a commit SHA via the GitHub
+API, fetches the repo tarball (cached by SHA under
+`$XDG_CACHE_HOME/sync-agents/`, no `git` binary needed), verifies a
+deterministic sha256 content hash against `.agents/sources.lock`, and
+only then installs — a tampered tarball or corrupted cache aborts
+before anything is written.
+
+Every installed artifact carries provenance (`_origin.json` inside
+skill dirs, `<name>.origin.json` beside flat files) recording
+owner/repo/ref/SHA/hash; commit these so clones keep their provenance.
+
+## Safety rules
+
+- Locally-edited artifacts are never overwritten without `--force`.
+- A destination without origin metadata is treated as a manual
+  conflict.
+- Private repos use your token (`SYNC_AGENTS_GITHUB_TOKEN` >
+  `GITHUB_TOKEN` > `GH_TOKEN` > `gh auth token`).
+- All commands accept `--global` to operate on `~/.agents/` instead of
+  the project.
+- Everything fetched remotely passes through the
+  [quarantine gate](./quarantine.md) before it can enter the live tree.
+
+## Day-to-day commands
+
+```bash
+sync-agents source add skill:anthropic/skill-pack@v1.2.0/skills/code-review
+sync-agents source list          # ok / outdated / modified / missing per entry
+sync-agents update               # bump tag-tracked entries when upstream moves
+sync-agents pull --offline       # cache-only, for CI or airplanes
+sync-agents source bundle        # rebuild sources.yaml from installed origin metadata
+sync-agents source detach NAME   # un-manage: flip to manual, drop the entry
+```
+
+## See also
+
+- [Quarantine (remote content review)](./quarantine.md)
+- [Linked (editable) sources](./linked-sources.md)
+- [Command reference](./commands/README.md)
diff --git a/docs/topology.md b/docs/topology.md
new file mode 100644
index 0000000..48bd4da
--- /dev/null
+++ b/docs/topology.md
@@ -0,0 +1,109 @@
+# Topology & configuration
+
+How the `.agents/` source-of-truth tree is laid out, which buckets are optional, and how `config` and `STATE.md` fit in.
+
+## The `.agents/` tree
+
+`.agents/` is the source of truth. It contains all rules, skills,
+workflows, and state for your agents:
+
+```
+.agents/
+  ├── config              # sync targets (claude, windsurf, cursor, copilot)
+  ├── rules/
+  │   ├── rule1.md
+  │   ├── rule2.md
+  │   └── ...
+  ├── skills/
+  │   ├── skill1/
+  │   │   └── SKILL.md
+  │   ├── skill2/
+  │   │   └── SKILL.md
+  │   └── ...
+  ├── workflows/
+  │   ├── workflow1.md
+  │   ├── workflow2.md
+  │   └── ...
+  ├── agents/              # optional: Claude subagent definitions
+  │   └── reviewer.md
+  ├── plans/               # optional: per-effort implementation plans (how/when)
+  │   └── auth-effort/
+  │       └── rollout.md
+  ├── specs/               # optional: durable design/requirements docs (what/why)
+  │   └── SPEC-001.md
+  ├── adrs/                # optional: Architecture Decision Records, status = subdirectory
+  │   ├── proposed/
+  │   │   └── adopt-grpc.md
+  │   ├── accepted/
+  │   │   └── use-postgres.md
+  │   └── denied/          # kept but never indexed — prevents re-proposing rejected decisions
+  │       └── use-mongo.md
+  └── STATE.md
+```
+
+Running `sync-agents sync` creates symlinks from `.agents/`
+subdirectories into `.claude/`, `.windsurf/`, `.cursor/`, and
+`.github/copilot/`. Any changes to `.agents/` are automatically
+reflected in the target directories because they are symlinks, not
+copies.
+
+`AGENTS.md` is an auto-generated index of everything in `.agents/` and
+is symlinked to `CLAUDE.md` so that Claude reads the index natively.
+
+## Skills use a directory layout
+
+Skills use a directory layout (`skills/name/SKILL.md`) rather than flat
+files. This allows skills to include supporting files alongside their
+definition. The [`fix` command](./commands/fix.md) can convert legacy
+flat skill files to the directory layout automatically.
+
+## Optional buckets
+
+`agents/`, `plans/`, `specs/`, `hooks/`, and `adrs/` activate only when
+their directory exists — `init` does not create them,
+`add agent|plan|spec|hook|adr <name>` does. They sync to Claude only
+(`.claude/agents`, `.claude/plans`, `.claude/specs`); other tools
+consume plans/specs through the `AGENTS.md` index and have no subagent
+surface.
+
+`plans/` and `specs/` share plumbing but differ in lifecycle: specs are
+durable what/why documents, plans are per-effort how/when documents
+that retire when the effort lands.
+
+Any bucket may also carry OS-scoped subdirectories (`macos/`, `linux/`,
+`unix/`, `windows/`) — see [OS-scoped routing](./os-scoped-routing.md).
+
+## STATE.md
+
+`.agents/STATE.md` tracks the current state of your project from the
+agent's perspective. It serves as a resumption point after failures or
+interruptions — the agent can read `STATE.md` to determine where it
+left off and what tasks remain. Update it regularly to keep agents in
+sync with progress.
+
+## Configuration (`.agents/config`)
+
+`sync-agents init` creates `.agents/config` with default sync targets:
+
+```
+# sync-agents configuration
+# Comma-separated list of sync targets (available: claude, windsurf, cursor, copilot)
+targets = claude,windsurf,cursor,copilot
+```
+
+Edit this file to limit which targets `sync` writes to by default. The
+`--targets` flag on any command overrides the config.
+
+Other recognized keys:
+
+- `quarantine = on|off` — disable the remote-install quarantine gate
+  (default `on`); see [Quarantine](./quarantine.md).
+- `os = <goos>` — override the detected OS for testing/cross-compile
+  CI; see [OS-scoped routing](./os-scoped-routing.md).
+
+## See also
+
+- [Command reference](./commands/README.md)
+- [Scope and target directories](./architecture/scope-and-targets.md)
+- [Semantic routing](./architecture/semantic-routing.md)
+- [ADRs](./adrs.md)
diff --git a/specs/SPEC-001-go-install-first-class.md b/specs/SPEC-001-go-install-first-class.md
deleted file mode 100644
index 0587ef7..0000000
--- a/specs/SPEC-001-go-install-first-class.md
+++ /dev/null
@@ -1,533 +0,0 @@
----
-id: SPEC-001
-title: Make `go install` a first-class install path for sync-agents
-status: Draft
-owner: nmccready
-created: 2026-05-13
-updated: 2026-05-13 (rev 3: aligned with existing CI/release infra at v0.2.4)
----
-
-# [SPEC-001] Feature: First-class `go install` + goreleaser for sync-agents
-
-## Overview
-
-Restructure the repository so that
-
-```
-go install github.com/brickhouse-tech/sync-agents@latest
-```
-
-resolves and installs the `sync-agents` binary directly, with no subpath. Adopt
-[goreleaser](https://goreleaser.com) as the canonical release tool for tagged
-binary releases (Linux, macOS, Windows × amd64/arm64). The existing
-`npm install -g @brickhouse-tech/sync-agents` flow MUST continue to work,
-fed from the same goreleaser-produced artifacts.
-
-## Pre-existing infrastructure (as of v0.2.4)
-
-The release pipeline is already substantially built out. The pieces below
-exist and SHALL NOT be reinvented:
-
-1. **Versioning via `commit-and-tag-version`** — runs as `npx commit-and-tag-version`
-   inside the brickhouse-tech org reusable workflow
-   `brickhouse-tech/.github/.github/workflows/release.yml@main`, invoked from
-   this repo's `.github/workflows/release.yml` on every push to `main`.
-   Conventional Commits drive the bump; the workflow auto-detects breaking
-   changes (`feat!:`, `fix!:`, `BREAKING CHANGE:`) and forces a major bump.
-   Skipped if HEAD commit is already `chore(release): …`.
-2. **Tag push → GitHub Release** — `.github/workflows/auto-release.yml`
-   triggers on `v*` tags and delegates to org reusable
-   `auto-release.yml@main`, which runs `gh release create "$TAG" --title "$TAG"
-   --generate-notes --verify-tag`. Empty release (no assets) today.
-3. **Tag push → npm OIDC trusted publish with provenance** —
-   `.github/workflows/publish.yml` builds all 5 platform packages
-   (darwin-{arm64,x64}, linux-{arm64,x64}, win32-x64) and publishes each
-   via OIDC + `--provenance`, then publishes the root package. Already on
-   Node 24.
-4. **optionalDependencies sync** — `scripts/sync-optional-deps.js` runs in
-   the root package's `prepack` and rewrites each `optionalDependencies`
-   entry to match the root version. The lag visible in source
-   (`0.1.18` while parent is `0.2.4`) is cosmetic — overwritten in CI
-   immediately before publish.
-
-What's still missing:
-
-- **`go install` from the network is broken** — `go.mod` sits at `go/go.mod`,
-  module path mismatches on-disk location. This spec fixes that.
-- **GitHub Releases ship no Go binary assets** — `auto-release.yml` creates a
-  text-only release. Go users can't grab a prebuilt `sync-agents` from a
-  Release page. This spec adds goreleaser as a complementary step that
-  appends archives + `checksums.txt` to the existing Release.
-
-## Motivation
-
-Current layout (as of v0.2.4):
-
-```
-sync-agents/
-├── go/
-│   ├── go.mod               ← module: github.com/brickhouse-tech/sync-agents
-│   ├── cmd/sync-agents/main.go
-│   └── internal/
-├── package.json
-├── bin/sync-agents.js
-├── npm/<triple>/
-├── src/{sh,md}/
-└── Makefile
-```
-
-Problems this causes:
-
-1. **`go install` is broken from the network.** The module path
-   `github.com/brickhouse-tech/sync-agents` does not match the on-disk
-   location of `go.mod` (which sits under `go/`). Go's module proxy joins the
-   repo URL with the directory containing `go.mod`, so the only working install
-   command today is the awkward
-   `go install github.com/brickhouse-tech/sync-agents/go/cmd/sync-agents@latest`.
-2. **Discoverability suffers.** Go-native users expect `go install <module>@latest`
-   to "just work" — the de facto first-class install path for a Go CLI.
-3. **Releases are bespoke.** Cross-compilation is hand-rolled in `Makefile` and
-   `scripts/build-platform.js`. There is no signed checksums file, no
-   GitHub Releases artifacts, no SBOM, and no Homebrew tap. Each npm publish
-   has to rebuild from source on the publishing host.
-4. **Duplication of intent.** The npm platform packages exist solely to ship a
-   prebuilt Go binary. A standard Go release pipeline produces those exact
-   binaries for free.
-
-## Goals
-
-- `go install github.com/brickhouse-tech/sync-agents@latest` installs the CLI.
-- `goreleaser` is the single source of truth for cross-compiled binaries.
-- `npm install -g @brickhouse-tech/sync-agents` still works, pulling the same
-  goreleaser binaries into the platform packages.
-- A tagged release on GitHub produces:
-  - GitHub Release with archives, checksums (`SHA256SUMS`), and changelog.
-  - A Homebrew tap formula (optional, behind a flag).
-  - Synced npm platform package binaries (manually published or via CI).
-
-## Non-Goals
-
-- Rewriting the CLI's commands or behavior. Surface stays identical.
-- Migrating off cobra or changing the dependency graph beyond what's required
-  to move files.
-- Signing releases (cosign / sigstore). Tracked separately.
-- Publishing a Homebrew formula in this spec — leave the tap stub but do not
-  cut a brew release yet.
-
-## Requirements
-
-### Requirement: Module root layout
-
-The system SHALL place `go.mod`, `go.sum`, and the `main` package at the
-repository root, so that the Go module path matches the repository URL.
-
-#### Scenario: Fresh `go install` from network
-
-- **GIVEN** a developer has Go ≥1.22 on PATH and no local clone of the repo
-- **WHEN** they run `go install github.com/brickhouse-tech/sync-agents@latest`
-- **THEN** the command exits 0
-- **AND** `$(go env GOBIN)/sync-agents` (or `$GOPATH/bin/sync-agents`) is
-  executable
-- **AND** `sync-agents --version` prints a version string matching the latest
-  tagged release
-
-#### Scenario: Pinned-version install
-
-- **GIVEN** the repo has a published tag `vX.Y.Z`
-- **WHEN** a developer runs `go install github.com/brickhouse-tech/sync-agents@vX.Y.Z`
-- **THEN** the installed binary's `--version` output matches `X.Y.Z`
-
-### Requirement: goreleaser pipeline
-
-The system SHALL include a checked-in `.goreleaser.yaml` that builds the CLI
-for darwin/linux/windows on amd64/arm64 and uploads archives + checksums as
-**assets to the GitHub Release already created by the org-level
-`auto-release.yml` reusable workflow**. goreleaser SHALL NOT create a parallel
-Release or duplicate the changelog — it appends artifacts.
-
-#### Scenario: Tag triggers asset upload
-
-- **GIVEN** a maintainer's push to `main` triggered the reusable release
-  workflow which created and pushed tag `vX.Y.Z`
-- **AND** the org `auto-release.yml@main` has created the empty GitHub
-  Release for that tag
-- **WHEN** this repo's `.github/workflows/goreleaser.yml` job runs on the
-  same tag push
-- **THEN** `goreleaser release --clean` exits 0
-- **AND** archives for {darwin,linux,windows} × {amd64,arm64} are uploaded
-  to the existing GitHub Release as assets
-- **AND** a `checksums.txt` (SHA256) is attached
-- **AND** the Release notes (from `auto-release.yml`'s `--generate-notes`)
-  remain unchanged
-
-#### Scenario: Local dry-run snapshot
-
-- **GIVEN** a contributor wants to validate the release config without tagging
-- **WHEN** they run `SYNC_AGENTS_VERSION=$(jq -r .version package.json) \
-  goreleaser release --snapshot --clean`
-- **THEN** the command exits 0
-- **AND** `dist/` contains archives for every configured platform
-
-### Requirement: npm install continuity
-
-The system SHALL preserve the existing `npm install -g @brickhouse-tech/sync-agents`
-install path, using goreleaser artifacts as the source for the per-platform
-binaries shipped in optional dependencies.
-
-#### Scenario: Existing npm consumers upgrade
-
-- **GIVEN** an existing user has `@brickhouse-tech/sync-agents@0.1.20` installed
-- **WHEN** they run `npm i -g @brickhouse-tech/sync-agents@latest` after this
-  spec ships (vX.Y.Z)
-- **THEN** install succeeds without manual intervention
-- **AND** the bin entry `sync-agents` is on PATH
-- **AND** `sync-agents --version` reports `X.Y.Z`
-
-#### Scenario: Platform package binary parity
-
-- **GIVEN** a release `vX.Y.Z` has been produced by goreleaser
-- **WHEN** the npm publish flow runs (manual or CI)
-- **THEN** each `npm/<triple>/bin/sync-agents` binary is byte-identical to its
-  counterpart inside the goreleaser `dist/` tree
-- **AND** the platform package versions in `package.json` `optionalDependencies`
-  match the parent package version
-
-### Requirement: Build/test ergonomics for contributors
-
-The system SHALL keep a working `make build && make test` flow from a fresh
-clone, with no requirement to `cd go/`.
-
-#### Scenario: Single-command local build
-
-- **GIVEN** a contributor has just cloned the repo
-- **WHEN** they run `make build`
-- **THEN** `bin/sync-agents` is produced
-- **AND** running `bin/sync-agents --version` matches the version derived from
-  `package.json`
-
-#### Scenario: bats + go tests run together
-
-- **GIVEN** a contributor wants to run all tests
-- **WHEN** they run `npm test`
-- **THEN** both the bats suite (`test/sync-agents.bats`) and Go tests under
-  `internal/...` execute
-- **AND** the command exits 0 on a clean tree
-
-### Requirement: Version single-sourcing via `package.json`
-
-The system SHALL treat `package.json`'s `version` field as the single source
-of truth. The existing brickhouse-tech reusable `release.yml` workflow already
-runs `npx commit-and-tag-version` on every push to `main` and pushes the
-resulting `vX.Y.Z` tag. goreleaser SHALL consume that version when building
-the Go binary by reading `package.json` at workflow time (not the raw tag
-string), so the `go install`, npm, and Go-release-archive paths cannot drift.
-
-#### Scenario: goreleaser inherits version from package.json
-
-- **GIVEN** a `vX.Y.Z` tag was created by `commit-and-tag-version` on the
-  prior push to `main` and has just been pushed
-- **WHEN** the goreleaser workflow runs in CI
-- **THEN** it reads `package.json` `.version` and exports it as
-  `$SYNC_AGENTS_VERSION` before invoking goreleaser
-- **AND** `internal/version.Version` is set to that value via
-  `-ldflags -X`
-- **AND** `sync-agents --version` on the resulting binary reports `X.Y.Z`
-- **AND** the value matches the pushed tag, the parent `package.json` and
-  every platform `package.json` under `npm/<triple>/`
-
-#### Scenario: Drift fails the release
-
-- **GIVEN** the pushed tag is `vA.B.C` but `package.json` says `X.Y.Z`
-  (i.e. someone tagged manually, bypassing `commit-and-tag-version`)
-- **WHEN** the goreleaser workflow runs
-- **THEN** the workflow fails fast in a version-check step with a clear
-  error
-- **AND** no Go-binary assets are uploaded to the GitHub Release
-
-#### Scenario: Local snapshot build works without a tag
-
-- **GIVEN** a contributor on `main` with no clean tag yet
-- **WHEN** they run `SYNC_AGENTS_VERSION=$(jq -r .version package.json) \
-  goreleaser release --snapshot --clean`
-- **THEN** `dist/` contains archives for every configured platform
-- **AND** the embedded `--version` string is the `package.json` value
-
-## Acceptance Criteria
-
-- **AC-1**: Given Go ≥1.22 and no local clone, when running
-  `go install github.com/brickhouse-tech/sync-agents@latest`, then the binary
-  installs and `sync-agents --version` reports the latest released version.
-- **AC-2**: Given a tag `vX.Y.Z` is pushed, when the goreleaser workflow runs,
-  then archives for darwin/linux/windows × amd64/arm64 plus `checksums.txt`
-  are attached as assets to the existing GitHub Release created by
-  `auto-release.yml`.
-- **AC-3**: Given an existing npm install at `0.2.4`, when upgrading to the
-  spec's first release, then `npm i -g @brickhouse-tech/sync-agents@latest`
-  succeeds and the bin works.
-- **AC-4**: Given a fresh clone, when running `make build && make test`, then
-  both succeed without `cd go/`.
-- **AC-5**: Given any release after this spec ships, when comparing the
-  binary inside the npm platform package to the matching goreleaser archive
-  asset on the GitHub Release, then they were both produced by the same CI
-  run and report identical `--version` output (byte-identity is a
-  non-goal — the two pipelines use different stripping flags and
-  Node/Go-stage compression).
-
-## Technical Design
-
-### Target layout
-
-```
-sync-agents/
-├── .goreleaser.yaml        ← NEW
-├── .github/workflows/
-│   ├── goreleaser.yml      ← NEW (tag-triggered goreleaser; uploads assets to existing Release)
-│   ├── release.yml         ← existing (on push to main, delegates to org reusable for commit-and-tag-version)
-│   ├── auto-release.yml    ← existing (on tag push, delegates to org reusable for `gh release create`)
-│   ├── publish.yml         ← existing, only path edit needed (go-version-file)
-│   └── tests.yml           ← existing, only path edit needed (go-version-file)
-├── go.mod                  ← MOVED from go/go.mod
-├── go.sum                  ← MOVED from go/go.sum
-├── main.go                 ← MOVED from go/cmd/sync-agents/main.go
-├── internal/
-│   ├── agent/              ← MOVED from go/internal/agent/
-│   └── version/            ← MOVED from go/internal/version/
-├── vendor/                 ← regenerated at new root
-├── bin/
-│   ├── sync-agents         ← local build output (gitignored)
-│   └── sync-agents.js      ← npm launcher (unchanged)
-├── npm/<triple>/           ← unchanged shape; binaries sourced from dist/
-├── src/{sh,md}/            ← unchanged
-├── scripts/
-│   ├── build-platform.js   ← updated to call goreleaser snapshot or copy from dist/
-│   └── sync-optional-deps.js ← unchanged
-├── examples/, test/        ← unchanged
-├── package.json            ← unchanged shape; version single-sourced
-├── Makefile                ← updated: drop `cd go/`
-└── README.md               ← updated install instructions (go install first)
-```
-
-### Module path
-
-- `module github.com/brickhouse-tech/sync-agents` stays.
-- `main` package moves to repo root → `go install <module>@latest` resolves
-  directly. No subpath required.
-
-### Internal import rewrites
-
-```
-github.com/brickhouse-tech/sync-agents/internal/agent
-github.com/brickhouse-tech/sync-agents/internal/version
-```
-
-Identical strings to today — the rewrite is purely on-disk file moves; import
-paths are stable.
-
-### Release flow (high level)
-
-```
-npm run release             # commit-and-tag-version
-  ├── bump package.json
-  ├── update CHANGELOG.md
-  ├── git commit -m "chore(release): vX.Y.Z"
-  └── git tag vX.Y.Z
-
-git push --follow-tags      # maintainer
-
-GitHub Actions: release.yml on tag push
-  ├── checkout @ tag
-  ├── verify  package.json version == tag (drop the leading "v")
-  ├── export SYNC_AGENTS_VERSION=$(jq -r .version package.json)
-  ├── goreleaser release --clean
-  │     └── ldflags: -X .../internal/version.Version=$SYNC_AGENTS_VERSION
-  └── (manual) npm sync + publish
-```
-
-### `.goreleaser.yaml` sketch
-
-```yaml
-version: 2
-project_name: sync-agents
-
-before:
-  hooks:
-    # Source of truth: package.json. Fail loudly if the tag drifted from it.
-    - sh -c 'v=$(jq -r .version package.json); if [ "v$v" != "{{ .Tag }}" ]; then echo "version drift: package.json=$v tag={{ .Tag }}" >&2; exit 1; fi'
-    - go mod tidy
-
-builds:
-  - id: sync-agents
-    main: ./
-    binary: sync-agents
-    env: [CGO_ENABLED=0]
-    goos: [linux, darwin, windows]
-    goarch: [amd64, arm64]
-    ldflags:
-      # {{ .Env.SYNC_AGENTS_VERSION }} is exported by the workflow from
-      # package.json; this keeps package.json the single source of truth.
-      - -s -w
-      - -X github.com/brickhouse-tech/sync-agents/internal/version.Version={{ .Env.SYNC_AGENTS_VERSION }}
-
-archives:
-  - id: default
-    formats: [tar.gz]
-    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
-    format_overrides:
-      - goos: windows
-        formats: [zip]
-
-checksum:
-  name_template: "checksums.txt"
-
-# auto-release.yml already creates the Release with --generate-notes;
-# goreleaser must not duplicate or replace it.
-release:
-  github:
-    owner: brickhouse-tech
-    name: sync-agents
-  draft: false
-  prerelease: auto
-  mode: append           # upload assets to the existing Release
-  use_existing: true     # do not error if the Release already exists
-```
-
-### GitHub Actions: `goreleaser.yml` sketch (NEW)
-
-```yaml
-name: goreleaser
-on:
-  push:
-    tags: ["v*.*.*"]
-
-jobs:
-  # Run after auto-release.yml has had a chance to create the GH Release.
-  # We rely on goreleaser's `mode: append` + `use_existing: true` to be
-  # idempotent if this races ahead.
-  goreleaser:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write   # upload assets to releases
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - uses: actions/setup-go@v6
-        with: { go-version-file: go.mod }
-      - name: Export version from package.json
-        run: |
-          v=$(jq -r .version package.json)
-          tag="${GITHUB_REF_NAME}"
-          if [ "v$v" != "$tag" ]; then
-            echo "::error::version drift: package.json=$v tag=$tag"
-            exit 1
-          fi
-          echo "SYNC_AGENTS_VERSION=$v" >> "$GITHUB_ENV"
-      - uses: goreleaser/goreleaser-action@v6
-        with: { version: latest, args: release --clean }
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SYNC_AGENTS_VERSION: ${{ env.SYNC_AGENTS_VERSION }}
-```
-
-### `commit-and-tag-version` — already in place
-
-The org reusable workflow at
-`brickhouse-tech/.github/.github/workflows/release.yml@main` already runs
-`npx commit-and-tag-version` on every push to `main`. This spec does NOT
-add a `commit-and-tag-version` devDependency or `npm run release` script
-to this repo — they would only create local drift from how CI actually
-versions the project.
-
-`scripts/sync-optional-deps.js` already runs in `prepack` and rewrites
-`optionalDependencies` to match root version, so the cosmetic drift visible
-in source (`0.1.18` vs root `0.2.4`) is overwritten in CI before publish
-and does not affect published artifacts.
-
-### Makefile updates
-
-Remove `cd go &&` prefixes:
-
-```make
-install:
-	go mod tidy -e && go mod vendor
-
-build:
-	go build $(LDFLAGS) -o bin/sync-agents ./
-
-build-platform: install
-	# unchanged logic, drop the cd go &&
-```
-
-### Migration steps (one PR)
-
-1. `git mv go/go.mod go.mod && git mv go/go.sum go.sum`
-2. `git mv go/cmd/sync-agents/main.go main.go`
-3. `git mv go/internal internal`
-4. `rm -rf go/vendor && go mod vendor` (at the new root)
-5. Update `Makefile` to drop `cd go/` prefixes.
-6. Update `scripts/build-platform.js` to build from repo root.
-7. Update `.github/workflows/publish.yml` and `tests.yml`:
-   `go-version-file: go/go.mod` → `go-version-file: go.mod`.
-8. Add `.goreleaser.yaml` (with `mode: append` so it never duplicates the
-   Release auto-release.yml creates).
-9. Add `.github/workflows/goreleaser.yml`.
-10. Add `dist/` to `.gitignore`.
-11. Update `README.md`: lead with `go install`, fall back to npm.
-12. Run `go build ./...`, `go vet ./...`, `make build`, `npm test`,
-    `SYNC_AGENTS_VERSION=$(jq -r .version package.json) goreleaser release --snapshot --clean`
-    locally before pushing.
-13. Merge PR. The reusable workflow will cut a `feat:` minor bump tag, which
-    triggers all three downstream workflows (`auto-release.yml`,
-    `publish.yml`, new `goreleaser.yml`). Verify on the resulting Release
-    page.
-
-## Test Plan
-
-- [ ] `go build ./...` succeeds from repo root.
-- [ ] `go vet ./...` succeeds from repo root.
-- [ ] `go test ./internal/...` succeeds (add at least one smoke test for
-      `version.Version` if none exists).
-- [ ] `make build` produces `bin/sync-agents`.
-- [ ] `make build-all` produces all five platform binaries.
-- [ ] `npm test` runs both bats and Go suites.
-- [ ] `goreleaser release --snapshot --clean` exits 0 and produces archives
-      for all targets (with `SYNC_AGENTS_VERSION` exported from `package.json`).
-- [ ] Drift guard: pushing a tag that doesn't match `package.json` fails the
-      `goreleaser.yml` workflow in the version-export step before goreleaser
-      runs.
-- [ ] `auto-release.yml` still creates the Release with notes; `goreleaser.yml`
-      appends assets to it (verified by manually tagging in a fork or by
-      running `goreleaser release --snapshot` and inspecting `dist/`).
-- [ ] Cut `vX.Y.Z-rc.1` tag in a fork; verify `go install github.com/<fork>/sync-agents@vX.Y.Z-rc.1`
-      yields a working binary on at least darwin-arm64 and linux-amd64.
-- [ ] `npm pack` on the parent package + each platform package produces tarballs
-      identical in shape to pre-migration baseline (manual diff).
-- [ ] `sync-agents --version`, `sync-agents init`, and `sync-agents sync` smoke
-      tests pass after install via both paths.
-
-## Rollout
-
-- One PR cuts the layout move + adds goreleaser + new workflow.
-- Merge to `main`. The reusable `release.yml` will auto-bump the version
-  via `commit-and-tag-version` and push the tag.
-- The new `goreleaser.yml` workflow fires on that tag push concurrently with
-  `auto-release.yml` and `publish.yml`. Verify Go binary archives + checksums
-  attach to the GitHub Release.
-- README announces `go install` as the recommended install path.
-- Keep npm install supported indefinitely; no deprecation in this spec.
-
-## Open Questions
-
-- **Q1:** Do we want a Homebrew tap (`brickhouse-tech/tap/sync-agents`) in this
-  spec, or defer? Recommend defer — adds maintainer burden.
-- **Q2:** Should `version.Version` default to `dev` when not built via
-  goreleaser (currently it falls back to `package.json`'s version via
-  `Makefile`)? Recommend **keep the Makefile fallback** — it already reads
-  `package.json`, which matches the new source-of-truth rule, so a local
-  `make build` reports the correct version without needing a tag.
-- **Q3:** Do we want SLSA provenance / cosign signing now or defer? Defer.
-
-## References
-
-- Go module layout: <https://go.dev/ref/mod#vcs>
-- goreleaser docs: <https://goreleaser.com/customization/>
-- npm bin-binary pattern (precedent: esbuild, biome, turbo).
diff --git a/specs/SPEC-002-promote-global-sync.md b/specs/SPEC-002-promote-global-sync.md
deleted file mode 100644
index c29ba8b..0000000
--- a/specs/SPEC-002-promote-global-sync.md
+++ /dev/null
@@ -1,1073 +0,0 @@
----
-id: SPEC-002
-title: "Promote to Global: sync skills, rules, and workflows to provider global dirs"
-status: Draft
-owner: nmccready
-created: 2026-05-13
-updated: 2026-05-14 (rev 4: Technical Design snippets re-synced to PR A + PR B implementation — Tool registry replaces string-switch ResolveGlobalTargetDir; method renamed GlobalRoot → ResolveGlobalRoot; CmdPromote takes ArtifactType not bare string; `--sync` flag explicitly tagged as PR-C deferred)
-prior_revisions:
-  - rev 3 (2026-05-14): added semantic-aware routing — buckets are not behavioral categories; invocable vs passive frontmatter contract; Claude skill ⇄ Windsurf workflow re-routing; passive concat for Windsurf rules
-  - rev 2 (2026-05-14): merged SPEC-002-global-scope-promotion into this doc; copy semantics confirmed; env-var root override + path-form promote + idempotency requirements folded in; demote/relocate deferred to Future Work
-  - rev 1 (2026-05-13): initial draft
-
-implementation_status:
-  - PR A landed (a84c13f): Scope + Tool types + ResolveGlobalRoot resolver. Foundation only — no behavior change to existing commands.
-  - PR B landed (f63d143): CmdPromote (both invocation forms) + CmdGlobalInit + their CLI wiring + 21 unit tests + user-facing docs.
-  - PR C pending: CmdGlobalSync with semantic-aware routing, concat regeneration, `--sync` flag on `promote`.
-  - PR D pending: CmdGlobalStatus + CmdGlobalClean.
-  - PR E pending: Makefile/npm test wiring for `go test ./...`, README updates, bats integration.
----
-
-# [SPEC-002] Feature: Promote / Global Sync for Skills, Rules, and Workflows
-
-## Overview
-
-Add a `promote` command and a `global` subcommand group so that any item in a
-project's `.agents/` directory can be elevated to a user-level global store
-(`~/.agents/`), and then synced from there to the standard global config
-directories of every supported AI coding agent.
-
-This spec also establishes the **Go test suite** (`go test ./...`) as a
-first-class requirement alongside the existing bats integration tests.
-
-## Motivation
-
-Today `sync-agents sync` links `.agents/` into per-project provider dirs
-(`.claude/`, `.windsurf/`, `.cursor/`, `.github/copilot/`). There is no path
-to make a rule, skill, or workflow available _globally_ — across every project
-on the machine — without manually copying files.
-
-Provider conventions for global config differ from local:
-
-| Provider | Local dir          | Global dir (user-level)         |
-| -------- | ------------------ | ------------------------------- |
-| Claude   | `.claude/`         | `~/.claude/`                    |
-| Windsurf | `.windsurf/`       | (local only; Codeium is global) |
-| Codeium  | `.windsurf/`       | `~/.codeium/`                   |
-| Cursor   | `.cursor/`         | `~/.cursor/`                    |
-| Copilot  | `.github/copilot/` | `~/.github/copilot/`            |
-| Codex    | `.codex/`          | `~/.codex/`                     |
-
-The `.windsurf/` directory is **local-only**; Codeium's global directory
-(`~/.codeium/`) is the correct global target for Windsurf/Codeium users.
-
-## Goals
-
-- `sync-agents promote <type> <name>` copies a local `.agents/` item into the
-  global store (`~/.agents/`) and optionally triggers a global sync.
-- `sync-agents promote <path>` is sugar for the above: detect `<type>` and
-  `<name>` from a conventional path (see "Auto-detect from path" below).
-- `sync-agents global init` creates `~/.agents/` with the standard skeleton.
-- `sync-agents global sync` links `~/.agents/` subdirectories into all
-  supported global provider dirs.
-- `sync-agents global status` reports the state of global symlinks.
-- `sync-agents global clean` removes global symlinks created by sync-agents.
-- A configurable global root (env var + flag) lets tests and shared-machine
-  setups redirect `~/.agents/` to an alternate prefix.
-- Go unit tests (`go test ./...`) cover all promote and global-sync logic;
-  bats tests cover CLI surface and integration.
-
-## Non-Goals
-
-- **`demote` / `relocate` (inverse direction)** — moving a global artifact
-  back into a project is deferred. Manual copy works today; a dedicated
-  command can ship in a follow-up spec once promote stabilizes.
-- **Merging or diffing global vs local versions** (tracked separately).
-- **Three-way merge** of divergent local/global copies. Conflict policy is
-  fail-fast with `--force` override; no automatic merge.
-- **Network / remote global stores** (e.g., git-hosted shared `.agents/`).
-  Users who want a versioned `~/.agents/` can use their own dotfiles tooling.
-- **Cross-machine sync.**
-- **Settings/hooks fragments** (`.claude/settings.json` JSON patches). These
-  are not simple file copies and need their own design; tracked as a future
-  spec.
-- **Automatic conflict resolution** — local always wins on `promote --force`,
-  global always wins on `global pull` (future spec).
-- **Homebrew or system-level install paths.**
-- **MCP server installs.**
-
-## Definitions
-
-| Term | Meaning |
-|---|---|
-| **Project scope** | The cwd's `.agents/` and per-tool dirs (`.claude/`, `.windsurf/`, `.cursor/`, `.github/copilot/`). |
-| **Global scope** | `~/.agents/` and per-tool user dirs (`~/.claude/`, `~/.codeium/`, `~/.cursor/`, `~/.github/copilot/`, `~/.codex/`). Override-able via `--global-root` or `$SYNC_AGENTS_GLOBAL_ROOT`. |
-| **Promote** | Copy a project artifact into the global store. Copy, not symlink (see "Copy semantics" below). |
-| **Global sync** | Symlink global per-tool directories into `~/.agents/`. |
-| **Artifact** | A rule, skill, or workflow. (Settings/hooks deferred.) |
-| **Semantic** | The *behavioral category* of an artifact: `invocable` (loaded on demand by name or by the model's trigger decision) or `passive` (always loaded as context). Bucket name and semantic are NOT the same thing — see below. |
-
----
-
-## Semantic categories (bucket ≠ semantic)
-
-The three `.agents/` buckets (`rules/`, `skills/`, `workflows/`) are
-**directory conventions**, not behavioral categories. Different AI tools
-treat the same bucket name as a different *semantic*:
-
-| Bucket | Claude semantic | Windsurf / Codeium semantic | Cursor semantic | Copilot / Codex semantic |
-|---|---|---|---|---|
-| `rules/` | passive (always-on) | passive (concat → `memories/global_rules.md`) | passive (`rules/`) | passive (flat `instructions.md`) |
-| `skills/` | **invocable** (Skill tool decides) | **passive** (auto-loaded as memory; no auto-run) | passive | passive |
-| `workflows/` | passive (reference doc) | **invocable** (slash-style flow) | passive | passive |
-
-The two semantics are:
-
-- **`invocable`** — the artifact is loaded only when chosen by name (user
-  slash command, or the model's tool-call decision based on the artifact's
-  trigger description). Not in baseline context.
-- **`passive`** — the artifact is part of baseline context for every
-  conversation. No trigger logic; always loaded.
-
-### Frontmatter contract
-
-Each artifact MAY declare its semantic in YAML frontmatter:
-
-```yaml
----
-invocable: true   # or false
----
-```
-
-If `invocable` is absent, the default is **inferred from the bucket**:
-
-| Bucket | Default `invocable` |
-|---|---|
-| `rules/` | `false` (passive) |
-| `skills/` | `true` (invocable) |
-| `workflows/` | `true` (invocable) |
-
-Existing artifacts that don't carry frontmatter MUST continue to work — the
-bucket-based default covers them. Authors who want non-default behavior
-(e.g., a passive skill that's really a long-form rule, or an invocable
-workflow that's really a one-pager reference) opt in by writing the
-frontmatter.
-
-### Routing rule (the point of this section)
-
-When `global sync` writes a `~/.agents/<bucket>/<name>` artifact to a target
-tool's directory, the destination subdir SHALL be chosen by **semantic**,
-not by bucket. Each tool declares two destination patterns — one for
-`invocable`, one for `passive` — and the artifact's resolved `invocable`
-value picks which one is used.
-
-Per-tool destination map:
-
-| Tool | Invocable destination | Passive destination |
-|---|---|---|
-| Claude | `~/.claude/skills/<name>/SKILL.md` (for skill dirs) or `~/.claude/commands/<name>.md` (for single-file invocables) | `~/.claude/rules/<name>.md` |
-| Windsurf / Codeium | `~/.codeium/windsurf/global_workflows/<name>.md` (single-file) — directory invocables get flattened or rejected (see scenario) | concat into `~/.codeium/windsurf/memories/global_rules.md` |
-| Cursor | `~/.cursor/rules/<name>.md` (Cursor has no separate invocable surface today — write passive) | `~/.cursor/rules/<name>.md` |
-| Copilot | `~/.github/copilot/instructions.md` (concat) | `~/.github/copilot/instructions.md` (concat) |
-| Codex | `~/.codex/instructions.md` (concat) | `~/.codex/instructions.md` (concat) |
-
-Notes on degenerate cases:
-
-- **Cursor / Copilot / Codex don't distinguish.** Both semantics land in the
-  same place. The mapping is still computed via semantic for consistency;
-  it just happens to resolve to one path. No fan-out, no duplication.
-- **Windsurf invocables must be single-file.** Windsurf workflows are
-  single `.md` files, not directories. A multi-file Claude skill cannot
-  cleanly become a Windsurf workflow — see the corresponding scenario.
-- **Concat targets** (`memories/global_rules.md`, Copilot/Codex
-  `instructions.md`) merge all passive artifacts into one file, in
-  alphabetical order of `<name>`, with `## <name>` headings and a
-  "do-not-edit, generated by sync-agents" banner at the top.
-
----
-
-## Requirements
-
-### Requirement: Global agents directory
-
-The system SHALL treat `~/.agents/` as the global source of truth, mirroring
-the same directory structure as a project-level `.agents/`.
-
-#### Scenario: Init creates global skeleton
-
-- **GIVEN** `~/.agents/` does not exist
-- **WHEN** `sync-agents global init` runs
-- **THEN** `~/.agents/rules/`, `~/.agents/skills/`, `~/.agents/workflows/`
-  are created
-- **AND** `~/.agents/config` is written with the full global target list
-  (`claude,codeium,cursor,copilot,codex`)
-- **AND** `sync-agents global status` shows all targets as `[not synced]`
-
-#### Scenario: Init is idempotent
-
-- **GIVEN** `~/.agents/` already exists with content
-- **WHEN** `sync-agents global init` runs again
-- **THEN** existing files are preserved
-- **AND** missing subdirs are created
-- **AND** the command exits 0
-
----
-
-### Requirement: Promote command
-
-The system SHALL provide a `promote` command that copies a named item from the
-project's `.agents/` directory into `~/.agents/`, making it globally available.
-
-Supported types: `rule`, `skill`, `workflow`.
-
-Invocation forms:
-
-1. **Type + name (canonical):** `sync-agents promote <type> <name>` —
-   e.g. `sync-agents promote skill my-skill`.
-2. **Path (sugar):** `sync-agents promote <path>` — detect `<type>` and
-   `<name>` from a conventional path. The detection rules are:
-   - Path ends in `SKILL.md` OR is a directory containing `SKILL.md` →
-     **skill**; name is the directory basename.
-   - Path is under `.agents/rules/` and ends in `.md` → **rule**; name is
-     the basename minus `.md`.
-   - Path is under `.agents/workflows/` and ends in `.md` → **workflow**;
-     name is the basename minus `.md`.
-   - Anything else → error with a suggestion to pass `<type> <name>`
-     explicitly.
-
-#### Scenario: Promote a rule
-
-- **GIVEN** `.agents/rules/my-rule.md` exists in the current project
-- **WHEN** `sync-agents promote rule my-rule` runs
-- **THEN** `~/.agents/rules/my-rule.md` is created (copy, not symlink)
-- **AND** `[info] Promoted rule my-rule to ~/.agents/rules/my-rule.md` is
-  printed
-
-#### Scenario: Promote a skill (directory layout)
-
-- **GIVEN** `.agents/skills/my-skill/SKILL.md` exists
-- **WHEN** `sync-agents promote skill my-skill` runs
-- **THEN** `~/.agents/skills/my-skill/SKILL.md` is created (full dir copy)
-- **AND** any supporting files within `my-skill/` are also copied
-
-#### Scenario: Promote a workflow
-
-- **GIVEN** `.agents/workflows/my-workflow.md` exists
-- **WHEN** `sync-agents promote workflow my-workflow` runs
-- **THEN** `~/.agents/workflows/my-workflow.md` is created
-
-#### Scenario: Promote via path (sugar form)
-
-- **GIVEN** `.agents/skills/cool-skill/SKILL.md` exists
-- **WHEN** `sync-agents promote .agents/skills/cool-skill` runs
-- **THEN** the artifact is detected as `skill cool-skill` and copied to
-  `~/.agents/skills/cool-skill/`
-- **AND** the outcome is identical to running
-  `sync-agents promote skill cool-skill`
-
-#### Scenario: Promote via path rejects unrecognised location
-
-- **GIVEN** `notes/random.md` exists outside any conventional `.agents/`
-  subdirectory
-- **WHEN** `sync-agents promote notes/random.md` runs
-- **THEN** the command exits non-zero
-- **AND** stderr names the unrecognised path and suggests
-  `promote <type> <name>` explicitly
-
-#### Scenario: Conflict requires --force
-
-- **GIVEN** `~/.agents/rules/my-rule.md` already exists
-- **WHEN** `sync-agents promote rule my-rule` runs **without** `--force`
-- **THEN** the command prints a warning and exits non-zero
-- **AND** the existing file is unchanged
-
-- **WHEN** `sync-agents promote rule my-rule --force` runs
-- **THEN** the existing file is overwritten with the project version
-
-#### Scenario: --dry-run shows intent without writing
-
-- **GIVEN** `.agents/skills/cool-skill/SKILL.md` exists
-- **WHEN** `sync-agents promote skill cool-skill --dry-run` runs
-- **THEN** the command prints what would be copied
-- **AND** no files are written to `~/.agents/`
-
-#### Scenario: Promote with auto global-sync
-
-- **GIVEN** a valid `~/.agents/` and global provider dirs are set up
-- **WHEN** `sync-agents promote rule my-rule --sync` runs
-- **THEN** the rule is promoted AND `sync-agents global sync` is invoked
-  automatically
-
-#### Scenario: Missing source is an error
-
-- **GIVEN** `.agents/rules/nonexistent.md` does not exist
-- **WHEN** `sync-agents promote rule nonexistent` runs
-- **THEN** `[error] rule "nonexistent" not found in .agents/rules/` is printed
-- **AND** the command exits non-zero
-
----
-
-### Requirement: Global sync
-
-The system SHALL provide `sync-agents global sync` to link `~/.agents/`
-subdirectories into each supported global provider directory.
-
-Global provider directory map:
-
-| scope     | Target token | Global directory                                  | local dir mapping (for sync) / symlink | INVOCABLE ? (/)    | Context to Sync to                                          |
-| --------- | ------------ | ------------------------------------------------- | -------------------------------------- | ------------------ | ----------------------------------------------------------- |
-| skills    | `claude`     | `~/.claude/skills/${name}/SKILL.md`               | `~/.claude/skills/${name}/SKILL.md`    | YES                | 1 to 1                                                      |
-| skills    | `windsurf`   | `~/.codeium/windsurf/skills/${name}/SKILL.md`     | `~/.windsurf/skills/${name}/SKILL.md`  | NO auto run        | 1 to 2 (workflows/skills) claudee skills picked by windsurf |
-| skills    | `github`     | `~/.github/skills/${name}/SKILL.md`               | `~/.github/skills/${name}/SKILL.md`    | YES                | 1 to 1                                                      |
-| rules     | `claude`     | `~/.claude/rules/${name}.md`                      | `~/.claude/rules/${name}.md`           | NO                 | 1 to 1                                                      |
-| rules     | `windsurf`   | `~/.codeium/windsurf/memories/global_rules.md`    | IGNORED                                | NO                 | 1 to 0 or global concat                                     |
-| workflows | `windsurf`   | `~/.codeium/windsurf/global_workflows/${name}.md` | `~/.windsurf/workflows/${name}.md`     | Yes ~ Claude Skill | 1 to 1                                                      |
-
-Note: `.windsurf/` is **local-only**. The global Windsurf target is `codeium`
-(`~/.codeium/`).
-
-#### Scenario: Global sync links all targets
-
-- **GIVEN** `~/.agents/` exists with `rules/`, `skills/`, `workflows/`
-- **WHEN** `sync-agents global sync` runs
-- **THEN** for each configured target, e.g. `claude`, the path
-  `~/.claude/rules` is a symlink pointing to `~/.agents/rules`
-- **AND** the same applies for `skills/` and `workflows/` in each target dir
-- **AND** only subdirs that exist in `~/.agents/` are linked (no empty dir creation)
-
-#### Scenario: --targets filters global sync
-
-- **GIVEN** `~/.agents/` is initialized
-- **WHEN** `sync-agents global sync --targets claude,codeium` runs
-- **THEN** only `~/.claude/` and `~/.codeium/` are touched
-- **AND** cursor, copilot, and codex dirs are not modified
-
-#### Scenario: --dry-run for global sync
-
-- **GIVEN** `~/.agents/` is initialized
-- **WHEN** `sync-agents global sync --dry-run` runs
-- **THEN** each proposed symlink is printed (`would link: …`)
-- **AND** no filesystem changes are made
-
-#### Scenario: Existing non-symlink conflicts
-
-- **GIVEN** `~/.claude/rules` exists as a real directory (not a symlink)
-- **WHEN** `sync-agents global sync` runs without `--force`
-- **THEN** a warning is printed and that entry is skipped
-- **WHEN** `sync-agents global sync --force` runs
-- **THEN** the existing directory is removed and replaced with the symlink
-
----
-
-### Requirement: Semantic-aware routing
-
-The system SHALL route each artifact to a target tool's directory by its
-**resolved semantic** (`invocable` | `passive`), not by its source bucket.
-See "Semantic categories" above for the contract and per-tool destination map.
-
-Semantic resolution order:
-
-1. Artifact YAML frontmatter `invocable: true|false`.
-2. Bucket default: `rules/` → passive, `skills/` → invocable,
-   `workflows/` → invocable.
-
-`global sync` SHALL use the resolved semantic for every destination
-calculation. Symlink vs concat is implied by the destination:
-- 1:1 paths (e.g. `~/.claude/skills/<name>/SKILL.md`) get a symlink.
-- Concat paths (e.g. `~/.codeium/windsurf/memories/global_rules.md`) get a
-  regenerated merged file each sync. Source `.agents/` files stay
-  authoritative; the concat output is a derived artifact.
-
-#### Scenario: Claude skill (invocable) lands in Windsurf global_workflows
-
-- **GIVEN** `~/.agents/skills/cool-skill/SKILL.md` exists
-- **AND** the file has no `invocable:` frontmatter (defaults to `true` per
-  bucket)
-- **AND** the skill is a single-file skill (only `SKILL.md`, no siblings)
-- **WHEN** `sync-agents global sync --targets codeium` runs
-- **THEN** `~/.codeium/windsurf/global_workflows/cool-skill.md` is a
-  symlink (or copy on filesystems without symlink support) pointing at
-  `~/.agents/skills/cool-skill/SKILL.md`
-- **AND** `~/.codeium/windsurf/skills/cool-skill/` is **not** created
-- **AND** `~/.codeium/windsurf/memories/global_rules.md` does **not**
-  include this skill
-
-#### Scenario: Claude rule (passive) concats into Windsurf memories
-
-- **GIVEN** `~/.agents/rules/security.md` and `~/.agents/rules/style.md`
-  exist
-- **AND** neither file declares `invocable:` frontmatter (default passive)
-- **WHEN** `sync-agents global sync --targets codeium` runs
-- **THEN** `~/.codeium/windsurf/memories/global_rules.md` exists as a
-  regular file
-- **AND** its contents start with a generated banner line
-- **AND** it includes `## security` and `## style` headings followed by the
-  respective file bodies, alphabetized by name
-- **AND** neither rule appears under `~/.codeium/windsurf/global_workflows/`
-
-#### Scenario: Frontmatter override flips routing
-
-- **GIVEN** `~/.agents/rules/onboarding.md` exists with frontmatter
-  `invocable: true`
-- **WHEN** `sync-agents global sync --targets codeium` runs
-- **THEN** `~/.codeium/windsurf/global_workflows/onboarding.md` is the
-  link/copy
-- **AND** `onboarding` is **not** in the concat'd `global_rules.md`
-- **AND** for Claude target, `~/.claude/commands/onboarding.md` is the
-  destination (not `~/.claude/rules/`)
-
-#### Scenario: Multi-file invocable skill cannot land in Windsurf workflow
-
-- **GIVEN** `~/.agents/skills/big-skill/` contains `SKILL.md` plus other
-  supporting files
-- **AND** the skill is invocable (default)
-- **WHEN** `sync-agents global sync --targets codeium` runs
-- **THEN** the command prints a warning naming the skill and the reason
-  ("Windsurf workflows are single-file; skill `big-skill` has supporting
-  files")
-- **AND** the skill is skipped for the codeium target (other targets still
-  process it normally)
-- **AND** the overall exit code remains 0 (warning, not error)
-
-#### Scenario: Cursor degenerate case — both semantics same dir
-
-- **GIVEN** `~/.agents/rules/security.md` (passive) and
-  `~/.agents/skills/grep-helper/SKILL.md` (invocable) exist
-- **WHEN** `sync-agents global sync --targets cursor` runs
-- **THEN** both end up under `~/.cursor/rules/` (Cursor has no separate
-  invocable surface)
-- **AND** no error or warning is printed — this is the documented
-  degenerate mapping
-
----
-
-### Requirement: Global status
-
-The system SHALL provide `sync-agents global status` to report the state of all
-global provider directories and their symlinks.
-
-#### Scenario: Status shows synced and missing targets
-
-- **GIVEN** `~/.claude/rules` → `~/.agents/rules` (symlink exists)
-- **AND** `~/.cursor/rules` does not exist
-- **WHEN** `sync-agents global status` runs
-- **THEN** output includes `[synced]  ~/.claude/rules -> ~/.agents/rules`
-- **AND** output includes `[missing] ~/.cursor/rules`
-
----
-
-### Requirement: Global clean
-
-The system SHALL provide `sync-agents global clean` to remove symlinks created
-by `global sync`.
-
-#### Scenario: Clean removes symlinks
-
-- **GIVEN** `~/.claude/rules` is a symlink to `~/.agents/rules`
-- **WHEN** `sync-agents global clean` runs
-- **THEN** `~/.claude/rules` is removed
-- **AND** `~/.agents/rules` (the source) is untouched
-- **AND** empty parent dirs created by sync-agents are removed
-
----
-
-### Requirement: Idempotency and repair
-
-Re-running `promote`, `global sync`, `global clean`, or `global init` on an
-already-applied state SHALL be a no-op: exit 0, with no filesystem writes
-beyond fixing broken or drifted symlinks if detected.
-
-#### Scenario: Re-running global sync is a no-op when state is current
-
-- **GIVEN** `sync-agents global sync` has already run successfully and all
-  expected symlinks resolve correctly
-- **WHEN** `sync-agents global sync` runs again
-- **THEN** the command exits 0
-- **AND** no filesystem writes occur (verified via stat mtimes)
-- **AND** stdout summarizes "N targets already in sync" rather than echoing
-  the full link list
-
-#### Scenario: Repair recreates a broken symlink
-
-- **GIVEN** `~/.claude/rules` is a symlink whose target no longer resolves
-  (user deleted `~/.agents/rules/` manually or it moved)
-- **WHEN** `sync-agents global sync` runs
-- **THEN** the broken symlink is replaced with a fresh one pointing at the
-  current `~/.agents/rules`
-- **AND** stdout calls out the repair (`[repair] relinked ~/.claude/rules`)
-
----
-
-### Requirement: Configurable global root
-
-The default global root is `$HOME/.agents/`. The system SHALL allow this to
-be overridden via, in order of precedence:
-
-1. `--global-root <path>` flag, on any `global *` or `promote` command.
-2. `$SYNC_AGENTS_GLOBAL_ROOT` environment variable.
-3. The Go-level `App.GlobalRoot` field (used by tests).
-4. Default: `$HOME/.agents/`.
-
-This requirement exists so the test suite can use a `t.TempDir()` root, and
-so corporate/shared machines can park the global tree somewhere other than
-`$HOME`.
-
-When `--global-root` is set, the per-tool global directories (`~/.claude/`,
-`~/.codeium/`, …) are **also** rerouted under that root. Concretely, with
-`--global-root=/tmp/x`, `~/.claude/rules` becomes `/tmp/x/.claude/rules`.
-This keeps the override fully self-contained for tests.
-
-#### Scenario: Env var redirects global root
-
-- **GIVEN** `$SYNC_AGENTS_GLOBAL_ROOT=/tmp/fake-home` is set
-- **AND** `/tmp/fake-home/` is empty
-- **WHEN** `sync-agents global init` runs
-- **THEN** `/tmp/fake-home/.agents/` is created
-- **AND** `$HOME/.agents/` is **not** touched
-
-#### Scenario: Flag overrides env var
-
-- **GIVEN** `$SYNC_AGENTS_GLOBAL_ROOT=/tmp/a` is set
-- **WHEN** `sync-agents global sync --global-root=/tmp/b` runs
-- **THEN** `/tmp/b/.agents/` is the resolved root
-- **AND** `/tmp/a/.agents/` is not touched
-
----
-
-### Requirement: Go test suite
-
-The system SHALL have a Go unit test suite covering all business logic in
-`internal/`. Tests MUST run with `go test ./...` from the repo root. The
-existing `npm test` command MUST run both bats AND Go tests concurrently.
-
-The Makefile `test-go` target SHALL run `go test ./...` (not bats).
-
-#### Scenario: go test passes on clean tree
-
-- **GIVEN** a fresh clone of the repo
-- **WHEN** `go test ./...` runs
-- **THEN** all tests pass and the command exits 0
-
-#### Scenario: promote logic is unit tested
-
-- **GIVEN** a temporary directory acting as a fake project root and `~/.agents/`
-- **WHEN** `App.CmdPromote("rule", "my-rule")` is called in a test
-- **THEN** the rule file is copied to the fake global dir
-- **AND** no filesystem side-effects outside the temp dirs occur
-
-#### Scenario: global sync logic is unit tested
-
-- **GIVEN** a populated fake `~/.agents/`
-- **WHEN** `App.CmdGlobalSync()` is called
-- **THEN** the expected symlinks are created in the fake global provider dirs
-- **AND** `App.CmdGlobalStatus()` reports all as `[synced]`
-
-#### Scenario: npm test runs go tests
-
-- **GIVEN** a clean repo with Go and Node installed
-- **WHEN** `npm test` runs
-- **THEN** `go test ./...` and `bats test/sync-agents.bats` both execute
-- **AND** the overall exit code is 0 on a green tree
-
----
-
-## Acceptance Criteria
-
-- **AC-1**: `sync-agents promote rule foo` copies `.agents/rules/foo.md` to
-  `~/.agents/rules/foo.md` and exits 0. Without `--force`, an existing
-  destination causes a warning + non-zero exit.
-- **AC-2**: `sync-agents promote skill bar` deep-copies
-  `.agents/skills/bar/` (including all files) to `~/.agents/skills/bar/`.
-- **AC-3**: `sync-agents global sync` creates symlinks from `~/.agents/`
-  subdirs into `~/.claude/`, `~/.codeium/`, `~/.cursor/`, `~/.github/copilot/`,
-  `~/.codex/` for each subdir that exists.
-- **AC-4**: `sync-agents global status` prints `[synced]` / `[missing]` /
-  `[not a symlink]` for each target×subdir combination.
-- **AC-5**: `sync-agents global clean` removes only symlinks that point into
-  `~/.agents/`; it does not remove real directories.
-- **AC-6**: `go test ./...` passes from repo root. Test coverage ≥ 70% on
-  `internal/agent` package.
-- **AC-7**: `make test-go` runs `go test ./...`, not bats.
-- **AC-8**: `npm test` runs bats AND `go test ./...` concurrently; both must
-  pass for overall success.
-- **AC-9**: `.windsurf/` is never created by `global sync`; `codeium` is the
-  only global Windsurf target.
-- **AC-10**: `sync-agents global sync` regenerates `~/.agents/AGENTS.md` after
-  linking, so Claude reads a current global index at `~/.claude/`.
-- **AC-11**: `sync-agents global init` always writes
-  `targets = claude,codeium,cursor,copilot,codex` regardless of any
-  project-level `.agents/config`.
-- **AC-12**: Given `$SYNC_AGENTS_GLOBAL_ROOT` (or `--global-root`) set to a
-  temp dir, every `global *` and `promote` operation reads/writes under that
-  temp dir and never touches `$HOME`.
-- **AC-13**: Re-running any `global *` or `promote` command in a steady state
-  is a no-op (exit 0, no filesystem writes); a broken symlink encountered
-  during re-run is repaired and logged.
-- **AC-14**: `sync-agents promote <path>` accepts a path under
-  `.agents/{rules,skills,workflows}/…` and behaves identically to the
-  `<type> <name>` form; unrecognised paths exit non-zero with guidance.
-- **AC-15**: An invocable artifact (default for `skills/` and `workflows/`,
-  or explicit frontmatter `invocable: true`) routes to each tool's
-  invocable destination per "Semantic categories"; specifically a Claude
-  skill bucket lands at `~/.codeium/windsurf/global_workflows/<name>.md`
-  for the codeium target, not at `~/.codeium/windsurf/skills/`.
-- **AC-16**: A passive artifact (default for `rules/`, or explicit
-  frontmatter `invocable: false`) routes to each tool's passive
-  destination; for codeium it is merged into
-  `~/.codeium/windsurf/memories/global_rules.md` with alphabetized
-  `## <name>` sections and a generated-by banner.
-- **AC-17**: Artifact frontmatter `invocable: true|false` overrides the
-  bucket default; the override applies uniformly across every target.
-- **AC-18**: A multi-file invocable skill targeting codeium emits a warning
-  and is skipped for codeium only; other targets still process it; exit
-  code stays 0.
-
----
-
-## Technical Design
-
-### New `App` methods
-
-```go
-// internal/agent/agent.go (additions)
-
-// CmdPromote promotes a single item from .agents/ to ~/.agents/.
-// The path-form invocation is exposed as a thin shim in main.go that
-// calls DetectArtifact() to derive (typ, name) before invoking this
-// method. The library-level signature stays typed.
-func (a *App) CmdPromote(typ ArtifactType, name string, opts PromoteOpts) error
-
-// CmdGlobalInit initializes ~/.agents/ with the standard skeleton.
-func (a *App) CmdGlobalInit() error
-
-// CmdGlobalSync links ~/.agents/ subdirs into global provider dirs.
-// (To be added in PR C.)
-func (a *App) CmdGlobalSync(opts GlobalSyncOpts) error
-
-// CmdGlobalStatus reports the state of global provider symlinks.
-// (To be added in PR D.)
-func (a *App) CmdGlobalStatus() error
-
-// CmdGlobalClean removes global symlinks created by sync-agents.
-// (To be added in PR D.)
-func (a *App) CmdGlobalClean(opts GlobalCleanOpts) error
-
-// ResolveGlobalRoot returns the resolved global agents directory.
-// Resolution order: App.GlobalRoot field > $SYNC_AGENTS_GLOBAL_ROOT > $HOME/.agents.
-// Also exposed: ResolveGlobalRootParent (returns filepath.Dir of the above)
-// and ResolveToolDir(tool, scope) for callers that want the per-tool
-// dir at either scope.
-func (a *App) ResolveGlobalRoot() string
-func (a *App) ResolveGlobalRootParent() string
-func (a *App) ResolveToolDir(tool Tool, scope Scope) string
-```
-
-### Tool registry (replaces the string-switch ResolveGlobalTargetDir
-sketch from rev 1–3)
-
-A typed `Tool` struct with a per-`Scope` directory map replaces the
-original string-keyed switch statement. The same five tools are
-supported; the registry encodes the windsurf/codeium asymmetry once,
-and any future tool gets added with one slice entry instead of patches
-to every call site.
-
-```go
-// internal/agent/tool.go (new file)
-
-type Tool struct {
-    ID         string                  // canonical, lowercase
-    Aliases    []string                // e.g. "windsurf" → codeium
-    DirByScope map[Scope]string        // {ScopeLocal: ".windsurf",
-                                       //  ScopeGlobal: ".codeium"}
-    LocalOnly  bool                    // future opt-out for tools w/o global
-}
-
-var Tools = []Tool{
-    {ID: "claude",  DirByScope: map[Scope]string{ScopeLocal: ".claude", ScopeGlobal: ".claude"}},
-    {ID: "codeium", Aliases: []string{"windsurf"},
-                    DirByScope: map[Scope]string{ScopeLocal: ".windsurf", ScopeGlobal: ".codeium"}},
-    {ID: "cursor",  DirByScope: map[Scope]string{ScopeLocal: ".cursor", ScopeGlobal: ".cursor"}},
-    {ID: "copilot", DirByScope: map[Scope]string{ScopeLocal: ".github/copilot", ScopeGlobal: ".github/copilot"}},
-    {ID: "codex",   DirByScope: map[Scope]string{ScopeLocal: ".codex", ScopeGlobal: ".codex"}},
-}
-
-func (t Tool) DirForScope(scope Scope, parentRoot string) string
-func (t Tool) HasScope(scope Scope) bool
-func (t Tool) Matches(name string) bool
-
-func ResolveTool(name string) (Tool, bool)
-func ToolIDs() []string
-func ToolIDsForScope(scope Scope) []string  // replaces the GlobalTargets constant
-```
-
-`ToolIDsForScope(ScopeGlobal)` returns the same five names the rev-3
-draft called `GlobalTargets`. There is no separate `GlobalTargets`
-constant — the registry is the single source of truth, and
-LocalOnly-tool opt-out works automatically.
-
-Note: `windsurf` is **not** a separate `Tool` in the registry. It is
-an alias on the `codeium` Tool. `ResolveTool("windsurf")` and
-`ResolveTool("codeium")` return the same value. This matches SPEC
-intent (`.windsurf/` is local-only; `~/.codeium/` is the global) and
-keeps the registry declarative.
-
-### App.GlobalRoot field
-
-```go
-type App struct {
-    // ... existing fields ...
-
-    // GlobalRoot, when non-empty, overrides $SYNC_AGENTS_GLOBAL_ROOT and
-    // $HOME/.agents. Per-tool dirs (~/.claude/, ~/.codeium/, …) are
-    // rerouted under filepath.Dir(GlobalRoot).
-    GlobalRoot string
-}
-```
-
-### Promote — copy semantics
-
-`promote` uses recursive copy, **not** symlinks, because:
-
-1. The global store should not have project-relative symlinks.
-2. The promoted copy is the global canonical version; the project copy is the
-   source of the promotion, not an ongoing reference.
-
-Skill promotion copies the entire directory tree:
-
-```
-.agents/skills/foo/ → ~/.agents/skills/foo/   (deep copy)
-```
-
-### Global sync — symlink semantics
-
-`global sync` creates **absolute symlinks** from global provider dirs into
-`~/.agents/`:
-
-```
-~/.claude/rules    → ~/.agents/rules    (absolute symlink)
-~/.claude/skills   → ~/.agents/skills
-~/.claude/workflows→ ~/.agents/workflows
-~/.codeium/rules   → ~/.agents/rules
-...
-```
-
-Unlike project-level sync (which uses relative symlinks), global sync uses
-absolute paths to ensure symlinks remain valid regardless of the working
-directory. Tests that set `--global-root` get absolute paths into the test
-tempdir.
-
-### Semantic resolution and routing
-
-```go
-// internal/agent/semantic.go (new file)
-
-type Semantic string
-const (
-    Invocable Semantic = "invocable"
-    Passive   Semantic = "passive"
-)
-
-// ResolveSemantic inspects YAML frontmatter for `invocable:` and falls
-// back to the bucket default.
-func ResolveSemantic(artifactPath, bucket string) (Semantic, error)
-
-// TargetDestination yields the per-tool path for an artifact, picking
-// the invocable vs passive destination per the routing table.
-// Returns ("", reason, nil) when the artifact cannot be routed to this
-// tool (e.g. multi-file invocable skill → codeium).
-func TargetDestination(tool, name string, sem Semantic, isDir bool, globalRoot string) (path string, skipReason string, err error)
-
-// ConcatTarget describes a tool's "merge all passive artifacts into one
-// file" destination (Windsurf memories, Copilot/Codex instructions).
-// global sync regenerates these atomically per run.
-type ConcatTarget struct {
-    Path        string  // e.g. ~/.codeium/windsurf/memories/global_rules.md
-    Banner      string  // generated-by banner prepended on each regen
-    HeadingTmpl string  // e.g. "## %s\n\n"
-}
-func ConcatTargetFor(tool string, globalRoot string) (ConcatTarget, bool)
-
-// RegenerateConcat collects every passive artifact whose semantic resolves
-// to the tool's concat target, sorts by name, and writes the merged file
-// atomically (tmp + rename) so partial writes never corrupt the output.
-func (a *App) RegenerateConcat(tool string) error
-```
-
-`CmdGlobalSync` becomes a loop that, for each `(artifact, tool)` pair,
-calls `ResolveSemantic` then `TargetDestination` (or routes to the
-concat collector). Concat regeneration runs once per tool, after the
-per-artifact pass.
-
-### Path-form promote (auto-detect)
-
-```go
-// detectArtifact maps a path under .agents/ to (type, name).
-// Returns an error when not under a known subdirectory so the CLI
-// can suggest the explicit type+name form. Shipped form is exported
-// (DetectArtifact) and returns the typed ArtifactType, not a bare
-// string.
-func DetectArtifact(rel string) (ArtifactType, string, error) {
-    rel = filepath.Clean(rel)
-    rel = strings.TrimPrefix(rel, "./")
-    slashed := filepath.ToSlash(rel)  // normalize for forward-slash prefix checks
-    switch {
-    case strings.HasPrefix(slashed, ".agents/skills/"):
-        after := strings.TrimPrefix(slashed, ".agents/skills/")
-        // first path component is the skill name; SKILL.md inside a
-        // skill dir also resolves correctly because the name comes
-        // from the segment before /SKILL.md.
-        return ArtifactSkill, strings.SplitN(after, "/", 2)[0], nil
-    case strings.HasPrefix(slashed, ".agents/rules/") && strings.HasSuffix(slashed, ".md"):
-        return ArtifactRule, strings.TrimSuffix(filepath.Base(slashed), ".md"), nil
-    case strings.HasPrefix(slashed, ".agents/workflows/") && strings.HasSuffix(slashed, ".md"):
-        return ArtifactWorkflow, strings.TrimSuffix(filepath.Base(slashed), ".md"), nil
-    }
-    return "", "", fmt.Errorf("path %q is not under .agents/{rules,skills,workflows}/", rel)
-}
-```
-
-### CLI surface
-
-New top-level commands added to `main.go` / cobra command tree:
-
-```
-sync-agents promote <type> <name>     [--force] [--dry-run] [--sync*] [--global-root P]
-sync-agents promote <path>            [--force] [--dry-run] [--sync*] [--global-root P]
-sync-agents global init               [--global-root P]
-sync-agents global sync               [--targets t1,t2] [--force] [--dry-run] [--global-root P]
-sync-agents global status             [--targets t1,t2] [--global-root P]
-sync-agents global clean              [--targets t1,t2] [--dry-run] [--global-root P]
-```
-
-`global` is a cobra command group; `init`, `sync`, `status`, `clean` are
-subcommands.
-
-### Go test infrastructure
-
-New files: `internal/agent/agent_test.go` and `global_test.go`.
-
-Test helpers use `t.TempDir()` to provide isolated fake project roots and
-global roots. Tests set `App.GlobalRoot` directly. The CLI layer is
-exercised via bats with `SYNC_AGENTS_GLOBAL_ROOT` pointing at a per-test
-tempdir.
-
-Updated `Makefile`:
-
-```make
-test-go:
-	go test ./...
-
-test: build
-	SYNC_AGENTS_BIN=bin/sync-agents npx bats test/sync-agents.bats
-```
-
-`package.json` script updates:
-
-```json
-"test": "npx concurrently --names \"sh,go\" -c \"cyan,magenta\" \"npm run test:sh\" \"npm run test:unit\"",
-"test:sh": "SYNC_AGENTS_BIN=bin/sync-agents npx bats test/sync-agents.bats",
-"test:unit": "go test ./..."
-```
-
----
-
-## Test Plan
-
-### Go unit tests (`go test ./...`)
-
-- [x] `TestCmdPromote_Rule` — copies rule from fake project root to fake global root. (PR B)
-- [x] `TestCmdPromote_Skill` — deep-copies skill dir; supporting files included. (PR B)
-- [x] `TestCmdPromote_Workflow` — copies workflow file. (PR B)
-- [x] `TestDetectArtifact_Skill` — `.agents/skills/foo` and `.../SKILL.md` both detected as `skill foo`. (PR B)
-- [x] `TestDetectArtifact_RuleAndWorkflow` — file-form paths detected. (PR B)
-- [x] `TestDetectArtifact_Unrecognised` — paths outside the buckets return error. (PR B)
-- [x] `TestCmdPromote_ConflictNoForce` — returns error when destination exists. (PR B)
-- [x] `TestCmdPromote_ConflictForce` — overwrites when `--force`. (PR B)
-- [x] `TestCmdPromote_DryRun` — no files written, `[dry-run]` printed. (PR B)
-- [x] `TestCmdPromote_MissingSource` — non-zero exit + error message names the artifact. (PR B)
-- [x] `TestCmdPromote_AutoCreatesParents` — works without prior `global init`. (PR B)
-- [x] `TestCmdGlobalInit_CreatesSkeleton` — creates skeleton dirs + canonical config. (PR B)
-- [x] `TestCmdGlobalInit_Idempotent` — second run preserves existing files. (PR B)
-- [x] `TestCmdGlobalInit_MissingSubdirRecreated` — partial-state recovery. (PR B)
-- [x] `TestCmdGlobalInit_DryRun` — no fs changes, `[dry-run]` printed. (PR B)
-- [x] `TestNormalizeArtifactType` — singular/plural/case normalization. (PR B)
-- [ ] `TestGlobalSync` — symlinks created for all configured targets; `~/.agents/AGENTS.md` is regenerated.
-- [ ] `TestGlobalSyncTargetFilter` — only specified targets touched.
-- [ ] `TestGlobalSyncConflictNoForce` — existing real dir skipped with warning.
-- [ ] `TestGlobalSyncConflictForce` — existing real dir replaced.
-- [ ] `TestGlobalSyncDryRun` — no filesystem changes.
-- [ ] `TestGlobalSyncIdempotent` — second run is no-op (no mtime changes).
-- [ ] `TestGlobalSyncRepair` — broken symlink is recreated and logged.
-- [ ] `TestResolveSemantic_BucketDefaults` — `rules/` → passive,
-      `skills/` → invocable, `workflows/` → invocable when no frontmatter.
-- [ ] `TestResolveSemantic_FrontmatterOverride` — `invocable: false` in a
-      file under `skills/` resolves to passive.
-- [ ] `TestRouteClaudeSkill_ToWindsurfWorkflow` — single-file invocable
-      skill lands at `~/.codeium/windsurf/global_workflows/<name>.md`,
-      not under `skills/`.
-- [ ] `TestRoutePassiveRule_ToWindsurfMemoriesConcat` — two rules concat
-      into `memories/global_rules.md` alphabetically with banner.
-- [ ] `TestRouteMultiFileSkill_WindsurfSkipsWithWarning` — multi-file
-      skill targeting codeium emits a warning and is skipped for codeium
-      only; claude target still gets it; exit code 0.
-- [ ] `TestRouteCursorDegenerate` — both invocable and passive land in
-      `~/.cursor/rules/`; no warning.
-- [ ] `TestRouteCopilotConcat` — Copilot/Codex concat into a single
-      `instructions.md` regardless of semantic.
-- [ ] `TestRegenerateConcat_Atomic` — concat target is written via
-      tmp-file + rename; an injected mid-write failure leaves the
-      original file intact.
-- [ ] `TestGlobalStatus` — correct `[synced]` / `[missing]` output.
-- [ ] `TestGlobalClean` — removes only sync-agents symlinks.
-- [x] `TestTool_DirForScope_Codeium` / `TestResolveToolDir_*` — correct
-      path for each tool at each scope; `windsurf` resolves to the same
-      Tool as `codeium` via the alias mechanism. (PR A)
-- [x] `TestResolveGlobalRoot_EnvBeatsHome` — `$SYNC_AGENTS_GLOBAL_ROOT` wins over `$HOME`. (PR A)
-- [x] `TestResolveGlobalRoot_FieldPrecedence` — `App.GlobalRoot` wins over env. (PR A)
-- [x] `TestResolveGlobalRoot_HomeDefault` — falls back to `$HOME/.agents`. (PR A)
-- [x] `TestResolveGlobalRoot_AbsolutePathNormalization` — relative paths get expanded. (PR A)
-- [x] `TestScope_String`, `TestParseScope_Valid`, `TestParseScope_Invalid` — Scope round-trip. (PR A)
-- [x] `TestResolveTool_AliasResolution` — windsurf alias resolves to codeium. (PR A)
-- [ ] `TestVersionSmoke` — `version.Version` is not empty string (regression
-      guard from SPEC-001).
-
-### bats integration tests (`test/sync-agents.bats`)
-
-All bats tests SHALL run with `SYNC_AGENTS_GLOBAL_ROOT=$BATS_TMPDIR/global`
-so they never touch the real `$HOME`.
-
-- [ ] `promote rule` happy path via CLI.
-- [ ] `promote skill` happy path via CLI.
-- [ ] `promote <path>` sugar form.
-- [ ] `global init` creates dirs.
-- [ ] `global sync` creates symlinks; re-running is idempotent.
-- [ ] `global status` output format.
-- [ ] `global clean` removes symlinks.
-- [ ] `promote --dry-run` prints intent, no writes.
-- [ ] `global sync --targets claude` touches only Claude dir.
-- [ ] `global sync` does **not** create `.windsurf/` anywhere under global root.
-- [ ] Semantic routing end-to-end: a `.agents/skills/foo/SKILL.md` with no
-      frontmatter lands at `~/.codeium/windsurf/global_workflows/foo.md`
-      and `~/.claude/skills/foo/SKILL.md` after a `promote skill foo &&
-      global sync`. Verify `~/.codeium/windsurf/memories/global_rules.md`
-      does not mention `foo`.
-- [ ] Concat regen end-to-end: two rules result in a `global_rules.md`
-      with both `## <name>` sections; deleting one rule and re-running
-      `global sync` removes it from the concat.
-
-### Cross-platform
-
-- [ ] macOS, Linux: same symlink behavior.
-- [ ] Windows: junctions or skip-with-fallback-to-copy; documented.
-      (Decision tracked under Open Questions.)
-
-### Manual smoke tests
-
-- [ ] On a fresh macOS ARM machine: `sync-agents global init && sync-agents promote rule foo && sync-agents global sync` — verify `~/.claude/rules/foo.md` resolves correctly through the symlink chain.
-- [ ] `sync-agents global clean` removes all global symlinks; verify `~/.agents/` is intact.
-- [ ] Verify `~/.windsurf/` is **never** created by any global command.
-
----
-
-## Rollout
-
-1. One PR: `internal/agent/global.go` (new), `internal/agent/agent_test.go`,
-   `internal/agent/global_test.go`, CLI wiring in `main.go`,
-   Makefile `test-go` fix, `package.json` script update, bats additions.
-2. README: add `promote` and `global` command table entries.
-3. CHANGELOG: `feat: promote command and global sync for skills/rules/workflows`.
-4. Merge → reusable workflow cuts `vX.Y.Z` tag → goreleaser + npm publish.
-
-### Suggested implementation order (sub-steps split across PRs A–E)
-
-The order below reflects the actual PR sequence on `feat/specs`. PR A
-and PR B are landed; PR C–E are pending.
-
-**PR A — Foundation** ✅ landed at `a84c13f`
-1. Add `ResolveGlobalRoot()` resolver + `App.GlobalRoot` field +
-   `$SYNC_AGENTS_GLOBAL_ROOT` env-var support. No behavior change to
-   existing commands.
-2. Add `Tool` struct + `Tools` registry (replaces what rev-1 sketched
-   as `GlobalTargets` + string-switch `ResolveGlobalTargetDir`).
-3. Add `Scope` type, `ParseScope`, `ResolveToolDir(tool, scope)`.
-
-**PR B — CmdPromote + CmdGlobalInit** ✅ landed at `f63d143`
-4. Add `DetectArtifact()` + unit tests.
-5. Implement `CmdPromote` (type+name form and path-form sugar). The
-   `--sync` flag is intentionally deferred to PR C because it depends
-   on `CmdGlobalSync`.
-6. Implement `CmdGlobalInit`.
-7. CLI wiring for both commands.
-
-**PR C — CmdGlobalSync with semantic-aware routing**
-8. Add `Semantic` type + `ResolveSemantic` (frontmatter + bucket
-   default).
-9. Add `TargetDestination` + `ConcatTarget` + `RegenerateConcat` with
-   tmp+rename atomicity.
-10. Implement `CmdGlobalSync` (idempotency + repair built in from the
-    start; don't bolt on later).
-11. Wire `--sync` flag on `promote` to call CmdGlobalSync after
-    CmdPromote.
-12. CLI wiring for `global sync`.
-
-**PR D — CmdGlobalStatus + CmdGlobalClean**
-13. Implement `CmdGlobalStatus` (`[synced]` / `[missing]` / `[modified]`).
-14. Implement `CmdGlobalClean`.
-15. CLI wiring for both.
-
-**PR E — Test infrastructure + release wiring**
-16. Bats tests; switch them to `$SYNC_AGENTS_GLOBAL_ROOT=$BATS_TMPDIR/...`.
-17. Makefile/package.json scripts; verify `npm test` runs both suites
-    (AC-7, AC-8).
-18. README + CHANGELOG.
-
-*Asterisk on `--sync` in the CLI surface section above means "flag is
-declared in the spec but lands in PR C, not PR B."
-
----
-
-## Open Questions
-
-- **Q1**: Should `promote` also write back a "source" header in the promoted
-  file so the global copy knows its origin? (Useful for future `global pull`.)
-  Recommend defer — adds schema coupling.
-- **Q2** ✅ **Resolved**: `global sync` SHALL regenerate `~/.agents/AGENTS.md`
-  after each sync — mirrors the project-level `AGENTS.md` pattern and gives
-  Claude a global index at `~/.claude/`.
-- **Q3** ✅ **Resolved**: `global init` SHALL always default to all five global
-  targets (`claude,codeium,cursor,copilot,codex`). Global config is independent
-  of any project's `.agents/config`.
-- **Q4** ✅ **Resolved (rev 3)**: Copilot and Codex now have an explicit
-  concat destination (`~/.github/copilot/instructions.md` and
-  `~/.codex/instructions.md`) built into the "Semantic categories"
-  routing map. Both invocable and passive artifacts merge into the same
-  file, alphabetically by name, with `## <name>` headings.
-- **Q6**: Concat ordering — alphabetical by name is the rev-3 default.
-  Worth allowing an `order:` frontmatter key (numeric) for deterministic
-  override? Defer unless we hit a real case.
-- **Q7**: When a `skills/<name>/` directory contains only `SKILL.md` and
-  no other files, is it considered "single-file" for the Windsurf
-  workflow destination? Rev 3 says yes (path is the `SKILL.md`).
-  Confirm before merge.
-- **Q5**: Windows symlinks require admin or developer mode. Fall back to
-  junctions or hard copies? Currently "junctions or skip-with-fallback-to-copy;
-  document." Needs a firm call before merge.
-
----
-
-## Future Work (out of scope, tracked here for visibility)
-
-- **`demote` / `relocate`** — inverse of promote (global → project). Symmetric
-  CLI and library design; deferred until promote ships and we see real
-  usage patterns. Original detailed proposal in the pre-merge
-  `SPEC-002-global-scope-promotion.md` (now removed) — see git history at
-  `d036c4f` for the elaborated form, including `--copy` / `--move` /
-  `--link-back` flag matrix.
-- **Settings/hooks fragments** — `.claude/settings.json` JSON-patch
-  promotion. Needs its own spec (SPEC-003 tentatively).
-- **`global pull`** — pull a globally-updated artifact back into a project
-  that has its own copy, with conflict reporting.
-- **Network/remote stores** — a `.agents/` synced from a git remote.
-
----
-
-## References
-
-- Claude global config: `~/.claude/` (Claude CLI docs)
-- Codeium/Windsurf global: `~/.codeium/` (Windsurf docs — local is `.windsurf/`)
-- Cursor global rules: `~/.cursor/rules/` (Cursor docs)
-- GitHub Copilot instructions: `~/.github/copilot/instructions.md`
-- OpenAI Codex: `~/.codex/`
-- SPEC-001: `go install` first-class + goreleaser
-- Pre-merge sibling spec (now folded into this one): see git history at
-  commit `d036c4f` for `SPEC-002-global-scope-promotion.md`.
diff --git a/specs/SPEC-003-source-manifest-pull.md b/specs/SPEC-003-source-manifest-pull.md
deleted file mode 100644
index f807c7b..0000000
--- a/specs/SPEC-003-source-manifest-pull.md
+++ /dev/null
@@ -1,668 +0,0 @@
----
-id: SPEC-003
-title: "Source manifest & pull: install rules, skills, and workflows from upstream repos"
-status: Implemented
-owner: nmccready
-created: 2026-05-14
-updated: 2026-05-14
-related: SPEC-001, SPEC-002
-inspired_by: https://github.com/knoxgraeme/skillfish
----
-
-# [SPEC-003] Feature: Source manifest & pull for upstream artifacts
-
-## Overview
-
-Add declarative, reproducible installation of `.agents/` artifacts (rules,
-skills, workflows) from upstream GitHub repositories, modeled on
-[skillfish](https://github.com/knoxgraeme/skillfish) but extended beyond
-skills.
-
-A project (or a user's global `~/.agents/`) declares its upstream sources
-in `.agents/sources.yaml`. `sync-agents pull` resolves and fetches each
-entry into the appropriate `.agents/{rules,skills,workflows}/` bucket;
-`sync-agents update` bumps refs and re-fetches; per-artifact origin
-metadata is written inline so a future operator can see exactly where each
-file came from and at what commit.
-
-## Motivation
-
-`sync-agents` today has `sync-agents import <url>` — single-artifact, no
-manifest, no version pinning, no inverse, no integrity. That works for
-one-off grabs but does not support:
-
-1. **Reproducible team setup.** A team-mate `git clone`s your project and
-   wants identical rules/skills/workflows without copy-paste. Today they
-   re-run `import` for each. With a manifest they run one command.
-2. **Pinning + drift detection.** Today there is no record of which
-   commit an imported skill came from. If upstream changes, you don't
-   know. Skillfish's `.skillfish.json` solves this for skills; we need
-   the same for the full artifact set.
-3. **Multi-artifact pulls from one repo.** `import <url>` is one URL =
-   one file. A "tap" repo that publishes 10 rules + 3 skills currently
-   requires 13 separate import commands. A `tree:owner/repo` entry pulls
-   the whole `.agents/`-shaped subtree in one go.
-4. **Rules and workflows, not just skills.** skillfish is skills-only.
-   In our model, rules and workflows are first-class artifacts with their
-   own buckets and (after SPEC-002) their own routing semantics. Anything
-   the source-manifest system does for skills, it must do for rules and
-   workflows too.
-
-## Goals
-
-- `sync-agents source add <entry>` appends an entry to
-  `.agents/sources.yaml` and pulls it.
-- `sync-agents source remove <name>` removes an entry and deletes the
-  pulled artifact (with confirmation).
-- `sync-agents pull` fetches every entry into the matching bucket.
-  Idempotent.
-- `sync-agents update [name]` bumps tracked refs to latest and re-pulls.
-- `sync-agents source list` shows declared entries + their resolved
-  commit SHAs.
-- `sync-agents source bundle` (inverse of pull) emits a `sources.yaml`
-  reflecting whatever is already installed manually (origin recovered
-  from per-artifact metadata when available, else prompts).
-- Every pulled artifact carries `_origin.json` next to it recording
-  `{owner, repo, path, ref, sha, fetched_at, source: 'manifest'|'manual'}`.
-- Pulls use sparse tarball fetch over the GitHub API, not full clones —
-  no `git` binary required.
-
-## Non-Goals
-
-- **Hosted registry / search** — skillfish has `skill.fish` and
-  `skillfish search`. We don't build a registry. Direct repo URLs only.
-- **Cross-host SCM** — GitHub only in this spec. GitLab/Bitbucket
-  deferred (the tarball fetch abstraction should leave room).
-- **Conflict-with-local merge** — if a pulled artifact would overwrite a
-  locally-modified file, fail with diff. No three-way merge.
-- **Signing / SBOM** — checksum integrity yes, signing deferred.
-- **Auto-pull on `sync-agents sync`** — pull is its own command; sync
-  doesn't fetch. Compose them in CI or hooks.
-
-## Definitions
-
-| Term | Meaning |
-|---|---|
-| **Source** | A declared upstream: a line in `sources.yaml`. |
-| **Entry** | The string form of a source: `<type>:<owner>/<repo>[@<ref>][/<path>]`. |
-| **Artifact** | A pulled file or directory under `.agents/{rules,skills,workflows}/`. |
-| **Origin metadata** | The `_origin.json` (or `_origin.yaml`) file written next to a pulled artifact, recording where it came from. |
-| **Lock** | The resolved commit SHA + content hash for each entry, written into `.agents/sources.lock`. |
-
-## Manifest schema
-
-`.agents/sources.yaml`:
-
-```yaml
-version: 1
-
-# Each entry: "<type>:<owner>/<repo>[@<ref>][/<path>]"
-# type ∈ {skill, rule, workflow, tree}
-sources:
-  - skill:anthropic/skill-pack@v1.2.0/skills/code-review
-  - rule:my-org/agent-norms@main/rules/security.md
-  - workflow:my-org/agent-norms@v0.4.1/workflows/release.md
-  - tree:my-org/team-agents@v2.0.0
-  # "tree:" pulls every subdir of an upstream .agents/ that the user has
-  # not excluded.
-
-# Optional: per-entry overrides (rare; keeps the inline form simple)
-overrides:
-  - match: "skill:anthropic/skill-pack@*/skills/code-review"
-    rename: "claude-code-review"
-    pin_sha: "abc123…"  # belt-and-suspenders pin
-    exclude_paths:
-      - "tests/"
-```
-
-The lock file `.agents/sources.lock`:
-
-```yaml
-version: 1
-entries:
-  - entry: "skill:anthropic/skill-pack@v1.2.0/skills/code-review"
-    resolved_sha: "abc1234567890abcdef…"
-    content_hash: "sha256:1f3a…"
-    fetched_at: "2026-05-14T02:31:00Z"
-  - …
-```
-
-Each installed artifact gets an `_origin.json` (next to `SKILL.md` for
-skills; next to the `.md` for rules/workflows, named `<name>.origin.json`):
-
-```json
-{
-  "schema": 1,
-  "owner": "anthropic",
-  "repo": "skill-pack",
-  "path": "skills/code-review",
-  "ref": "v1.2.0",
-  "sha": "abc1234567890abcdef…",
-  "content_hash": "sha256:1f3a…",
-  "fetched_at": "2026-05-14T02:31:00Z",
-  "source": "manifest"
-}
-```
-
-`source: "manifest"` means this artifact is governed by `sources.yaml`.
-`source: "manual"` means it was added by `sync-agents import` or hand
-copied. `bundle` flips manuals to manifest entries.
-
-## Requirements
-
-### Requirement: Source entry grammar
-
-The system SHALL accept entries of the form
-`<type>:<owner>/<repo>[@<ref>][/<path>]` where:
-
-- `<type>` ∈ {`skill`, `rule`, `workflow`, `tree`}
-- `<owner>/<repo>` is a GitHub repo
-- `<ref>` is a tag, branch, or 40-char commit SHA; defaults to the repo's
-  default branch
-- `<path>` is the path inside the repo to the artifact. Defaults differ
-  by type:
-  - `skill:` — defaults to repo root (expects `SKILL.md` at root) or
-    `skills/<name>` if `<name>` matches a top-level dir
-  - `rule:` — required for rule
-  - `workflow:` — required for workflow
-  - `tree:` — defaults to repo root; the puller walks for any subdirs
-    named `rules/`, `skills/`, `workflows/`
-
-#### Scenario: Skill with pinned tag
-
-- **GIVEN** the entry `skill:foo/bar@v1.0.0/skills/grep-helper`
-- **WHEN** `sync-agents pull` runs
-- **THEN** `.agents/skills/grep-helper/SKILL.md` exists
-- **AND** `.agents/skills/grep-helper/_origin.json` records
-  `{owner: foo, repo: bar, ref: v1.0.0, sha: <resolved>}`
-
-#### Scenario: Rule with required path
-
-- **GIVEN** the entry `rule:foo/bar@main/rules/security.md`
-- **WHEN** `sync-agents pull` runs
-- **THEN** `.agents/rules/security.md` exists with file contents
-- **AND** `.agents/rules/security.origin.json` records the source
-
-#### Scenario: Tree pull populates multiple buckets
-
-- **GIVEN** the entry `tree:foo/team-agents@v2.0.0`
-- **AND** the upstream repo has `.agents/rules/r1.md`, `.agents/skills/s1/SKILL.md`, `.agents/workflows/w1.md`
-- **WHEN** `sync-agents pull` runs
-- **THEN** `.agents/rules/r1.md`, `.agents/skills/s1/SKILL.md`, and
-  `.agents/workflows/w1.md` all exist locally
-- **AND** each has its `_origin.json` / `.origin.json`
-- **AND** files OUTSIDE the three buckets are ignored
-
-#### Scenario: Invalid entry rejected with guidance
-
-- **GIVEN** the entry `notatype:foo/bar`
-- **WHEN** `sync-agents source add notatype:foo/bar` runs
-- **THEN** the command exits non-zero
-- **AND** stderr names the valid type prefixes
-
----
-
-### Requirement: Pull command
-
-`sync-agents pull` SHALL fetch every entry in `sources.yaml`, resolve
-each `<ref>` to a commit SHA via the GitHub API, sparse-fetch the entry's
-path as a tarball, extract to the matching bucket, and write
-`_origin.json` + update `sources.lock`.
-
-Conflict handling (per artifact):
-
-- Destination does not exist → write.
-- Destination exists and the existing `_origin.json` matches the entry's
-  resolved SHA → no-op (idempotent).
-- Destination exists, `_origin.json` matches but content hash differs
-  from the recorded one → local modification detected; fail without
-  `--force`, print diff.
-- Destination exists, no `_origin.json` → manual conflict; fail without
-  `--force`.
-
-#### Scenario: Pull is idempotent
-
-- **GIVEN** `sources.yaml` lists one entry that was already pulled at
-  the resolved SHA
-- **WHEN** `sync-agents pull` runs again
-- **THEN** no filesystem writes occur (verified via mtime)
-- **AND** exit code is 0
-- **AND** stdout summarizes "1 entry already current"
-
-#### Scenario: Local modification blocks unintentional overwrite
-
-- **GIVEN** a previously-pulled `.agents/rules/security.md` has been
-  edited locally
-- **WHEN** `sync-agents pull` runs
-- **THEN** the command exits non-zero
-- **AND** stderr shows the diff between local content and upstream
-  content at the recorded SHA
-- **AND** suggests `--force` or `sync-agents source detach <name>` to
-  convert to a manual artifact
-
-#### Scenario: --dry-run plans without writing
-
-- **GIVEN** `sources.yaml` lists three entries, two unchanged and one
-  with a newer SHA available
-- **WHEN** `sync-agents pull --dry-run` runs
-- **THEN** stdout lists each entry's plan
-  (`current`/`would-update`/`would-add`) and no filesystem changes
-  occur
-
----
-
-### Requirement: Update command
-
-`sync-agents update [name]` SHALL re-resolve `<ref>` for one or all
-entries and pull any whose SHA has advanced. Pinned SHAs (entries whose
-`<ref>` is a 40-char SHA) are skipped with a note. Pinned tags resolve to
-that tag's current SHA — if a tag has been moved upstream, that's a
-detected update.
-
-#### Scenario: Update bumps a tag-pinned entry
-
-- **GIVEN** `sources.yaml` has `skill:foo/bar@v1.0.0/skills/x`
-- **AND** the previous pull recorded SHA `aaa…` for `v1.0.0`
-- **AND** upstream has retagged `v1.0.0` to point at `bbb…`
-- **WHEN** `sync-agents update` runs
-- **THEN** the artifact is re-fetched
-- **AND** `sources.lock` records `bbb…`
-- **AND** stdout calls out the moved tag
-
-#### Scenario: Update is a no-op for SHA-pinned entries
-
-- **GIVEN** `sources.yaml` has
-  `skill:foo/bar@abc1234567890abcdef0123456789abcdef012345/skills/x`
-- **WHEN** `sync-agents update` runs
-- **THEN** the entry is skipped with `[skip] SHA-pinned`
-- **AND** no network call beyond a HEAD check is made
-
----
-
-### Requirement: Source list, add, remove, bundle, detach
-
-- `sync-agents source add <entry>` — append entry to `sources.yaml`, run
-  `pull` for it.
-- `sync-agents source remove <name>` — remove from `sources.yaml`,
-  delete pulled artifact (with `--keep` to leave the artifact as
-  manual).
-- `sync-agents source list` — print each entry, its resolved SHA, and
-  whether the local artifact matches the lock (`[ok]` / `[outdated]` /
-  `[modified]` / `[missing]`).
-- `sync-agents source bundle` — scan `.agents/` for artifacts with
-  `_origin.json` and emit/refresh `sources.yaml` from them. Artifacts
-  without origin metadata prompt for a source URL or are skipped with a
-  warning.
-- `sync-agents source detach <name>` — flip an artifact's `_origin.json`
-  to `source: "manual"` and remove its entry from `sources.yaml`. The
-  artifact stays in `.agents/`.
-
-#### Scenario: Add appends to manifest and pulls
-
-- **GIVEN** `.agents/sources.yaml` has 1 entry
-- **WHEN** `sync-agents source add rule:foo/bar@main/rules/sec.md` runs
-- **THEN** `sources.yaml` has 2 entries
-- **AND** `.agents/rules/sec.md` exists and has origin metadata
-
-#### Scenario: Bundle picks up manual artifact with origin
-
-- **GIVEN** `.agents/skills/cool/SKILL.md` was added via
-  `sync-agents import` and has `_origin.json` with `source: "manual"`
-- **WHEN** `sync-agents source bundle` runs
-- **THEN** `sources.yaml` gains a corresponding entry
-- **AND** the artifact's `_origin.json` flips `source` to `"manifest"`
-
----
-
-### Requirement: Tarball fetch (no git binary required)
-
-The puller SHALL fetch upstream content via the GitHub REST API's
-tarball endpoint (`/repos/{owner}/{repo}/tarball/{ref}`), extract
-selectively, and never shell out to `git`. This keeps the tool usable on
-machines without `git`, in CI containers, and lets us cache by SHA.
-
-GitHub auth resolution (matches skillfish):
-
-1. `$SYNC_AGENTS_GITHUB_TOKEN`
-2. `$GITHUB_TOKEN`
-3. `$GH_TOKEN`
-4. `gh auth token` if `gh` is on PATH
-
-Anonymous requests are allowed; rate-limit errors hint at auth.
-
-A local cache lives at `$XDG_CACHE_HOME/sync-agents/sources/<host>/<owner>/<repo>/<sha>.tar.gz`
-(falls back to `~/.cache/sync-agents/...`). Re-pulls hit the cache by
-SHA.
-
-#### Scenario: Cache hit avoids the network
-
-- **GIVEN** `sources.yaml` has an entry resolving to SHA `abc…`
-- **AND** the cache holds `…/abc….tar.gz`
-- **WHEN** `sync-agents pull --offline` runs
-- **THEN** the artifact is extracted from cache, no network calls made
-- **AND** if a needed SHA is not in cache, the command exits non-zero
-
----
-
-### Requirement: Per-artifact origin metadata
-
-Every pulled artifact SHALL have an origin file co-located with it:
-
-- For a skill dir: `.agents/skills/<name>/_origin.json`
-- For a rule file: `.agents/rules/<name>.origin.json`
-- For a workflow file: `.agents/workflows/<name>.origin.json`
-
-The schema is fixed (see "Manifest schema" above). Tools downstream
-(SPEC-002 promote, the AGENTS.md indexer) MAY read these files but MUST
-NOT depend on them — an artifact without origin is valid and untracked.
-
-`.gitignore` is **not** updated by sync-agents. Origin files are
-intended to be committed so a `git clone` of the project still records
-provenance.
-
-#### Scenario: Skill origin file format
-
-- **GIVEN** a skill freshly pulled from `foo/bar@v1.0.0/skills/x` at
-  SHA `abc…`
-- **WHEN** `sync-agents pull` completes
-- **THEN** `.agents/skills/x/_origin.json` is a valid JSON document
-  with `schema: 1`, `owner: "foo"`, `repo: "bar"`, `ref: "v1.0.0"`,
-  `sha: "abc…"`, `source: "manifest"`, and a UTC `fetched_at` timestamp
-
----
-
-### Requirement: Integrity verification
-
-Each pulled artifact's content hash (sha256 over the artifact's file
-tree, deterministic) SHALL be recorded in both `_origin.json` and
-`sources.lock`. On every `pull`/`update`, the puller re-hashes after
-extraction and compares to `sources.lock`. Mismatch fails the operation
-with a clear error citing both hashes; nothing under the destination is
-written until the hash matches.
-
-A future signing layer can compose with this; in this spec we only
-guarantee content equivalence against what was recorded at first pull.
-
----
-
-### Requirement: Interop with SPEC-002 (global)
-
-All `source *` commands SHALL honor `--global-root` and
-`$SYNC_AGENTS_GLOBAL_ROOT` (defined in SPEC-002). When invoked with
-`--global`, they operate against `$HOME/.agents/sources.yaml` and pull
-into `$HOME/.agents/`. Combined flow:
-
-```bash
-sync-agents source add --global skill:foo/bar@v1/skills/x
-sync-agents global sync   # then fan out per SPEC-002 routing
-```
-
-#### Scenario: Pull into global root
-
-- **GIVEN** `$SYNC_AGENTS_GLOBAL_ROOT=/tmp/g`
-- **WHEN** `sync-agents pull --global` runs
-- **THEN** every artifact lands under `/tmp/g/.agents/...`
-- **AND** `$HOME/.agents/` is not touched
-
----
-
-### Requirement: Pulled rules/workflows carry semantic frontmatter (SPEC-002 compat)
-
-When pulling a rule or workflow that does not declare `invocable:` in its
-frontmatter, the puller SHALL leave it unchanged — the SPEC-002
-bucket-default resolution handles it. The puller MUST NOT inject
-`invocable:` frontmatter into pulled files; provenance metadata lives
-exclusively in `_origin.json` / `.origin.json`.
-
----
-
-## Acceptance Criteria
-
-- **AC-1**: `sync-agents source add <entry>` appends to `sources.yaml`
-  and pulls the artifact into the correct bucket.
-- **AC-2**: `sync-agents pull` is idempotent (no writes on second run
-  with no upstream movement) and writes per-artifact origin files.
-- **AC-3**: `sync-agents update` bumps tag-pinned entries when upstream
-  moves the tag; skips SHA-pinned entries.
-- **AC-4**: `sync-agents source remove <name>` removes the manifest
-  entry and deletes the artifact unless `--keep` is passed.
-- **AC-5**: `sync-agents source list` reports `[ok]` / `[outdated]` /
-  `[modified]` / `[missing]` per entry.
-- **AC-6**: `sync-agents source bundle` reconstructs `sources.yaml`
-  from `_origin.json` files and flips `source` to `"manifest"`.
-- **AC-7**: Tarball fetcher does not invoke `git`. Cache hits avoid
-  network entirely.
-- **AC-8**: Token resolution order matches skillfish:
-  `SYNC_AGENTS_GITHUB_TOKEN > GITHUB_TOKEN > GH_TOKEN > gh auth token`.
-- **AC-9**: Local modifications block `pull` without `--force`, with a
-  clear diff.
-- **AC-10**: Content-hash mismatch (tampered tarball, corrupted cache)
-  aborts the operation before any destination writes.
-- **AC-11**: `tree:` entries fan out to multiple buckets in one
-  resolved tarball fetch.
-- **AC-12**: `--global` (and `$SYNC_AGENTS_GLOBAL_ROOT`) reroute every
-  operation under the global root; `$HOME` is untouched in tests.
-- **AC-13**: `go test ./...` passes with ≥70% coverage on
-  `internal/agent/source` (the new package).
-
-## Technical Design
-
-### Module layout
-
-```
-internal/agent/source/
-  manifest.go      # parse/write sources.yaml, sources.lock
-  entry.go         # entry grammar + parser
-  origin.go        # _origin.json schema + read/write
-  fetcher.go       # GitHub tarball fetch + cache
-  hash.go          # deterministic content hash over a file tree
-  pull.go          # pull/update orchestration
-  bundle.go        # reverse: scan tree → sources.yaml
-```
-
-### Entry parser
-
-```go
-type EntryType int
-const (
-    EntrySkill EntryType = iota
-    EntryRule
-    EntryWorkflow
-    EntryTree
-)
-
-type Entry struct {
-    Type   EntryType
-    Owner  string
-    Repo   string
-    Ref    string  // "" → repo default branch
-    Path   string  // "" → root or type-specific default
-    Raw    string  // original string
-}
-
-func ParseEntry(s string) (Entry, error)
-```
-
-### Fetcher
-
-```go
-type Fetcher interface {
-    // ResolveRef returns the commit SHA for a tag/branch/SHA ref.
-    ResolveRef(ctx context.Context, owner, repo, ref string) (sha string, err error)
-    // Fetch returns a tarball reader for repo@sha, hitting the cache first.
-    Fetch(ctx context.Context, owner, repo, sha string) (io.ReadCloser, fromCache bool, err error)
-}
-
-type GitHubFetcher struct {
-    HTTPClient *http.Client
-    CacheDir   string  // resolved $XDG_CACHE_HOME/sync-agents/sources
-    TokenFn    func() (string, error)
-}
-```
-
-`TokenFn` resolution: env var chain → `gh auth token` shellout (best-
-effort; absence is non-fatal).
-
-### Pull orchestration
-
-```go
-type PullOpts struct {
-    Force    bool
-    DryRun   bool
-    Offline  bool
-    Only     []string  // empty = all
-    Global   bool
-}
-
-func (a *App) Pull(opts PullOpts) (PullReport, error)
-```
-
-`PullReport` enumerates per-entry result (`Added`, `Updated`, `Current`,
-`Skipped`, `Failed`) for both human and `--json` output.
-
-### CLI surface
-
-```
-sync-agents pull                           [--dry-run] [--offline] [--force] [--only NAME] [--global]
-sync-agents update [NAME]                  [--dry-run] [--force] [--global]
-sync-agents source add <ENTRY>             [--global]
-sync-agents source remove <NAME>           [--keep] [--global]
-sync-agents source list                    [--json] [--global]
-sync-agents source bundle                  [--global]
-sync-agents source detach <NAME>           [--global]
-```
-
-`import <url>` (existing) stays as a thin shim: parses `<url>`, calls
-`source add` under the hood. Behavior identical for users who don't
-care about the manifest.
-
-### Manifest format choice
-
-YAML for `sources.yaml` because the schema has nested overrides and
-arrays-of-objects that JSON makes painful by hand. The lock file is
-also YAML for consistency. Origin files are JSON because they're written
-by code, never hand-edited, and JSON has better Go std-lib support for
-deterministic emission.
-
-### Hash function
-
-`content_hash` = sha256 over a sorted, normalized manifest of the
-extracted file tree:
-
-```
-sha256(
-  for each file in sorted order:
-    "{relative-path}\t{size}\t{sha256(content)}\n"
-)
-```
-
-Excludes the `_origin.json` itself (would create a chicken-and-egg).
-Deterministic across platforms (LF-only, no atime/mtime).
-
-### Cache layout
-
-```
-$XDG_CACHE_HOME/sync-agents/sources/
-  github.com/
-    <owner>/
-      <repo>/
-        <sha>.tar.gz
-        <sha>.json     # cached metadata (ref → sha resolution, ttl 1h)
-```
-
-Cache eviction is out of scope; document a `sync-agents source
-cache prune` follow-up.
-
-## Test Plan
-
-### Go unit tests (`go test ./...`)
-
-- [ ] `TestParseEntry_Skill`, `_Rule`, `_Workflow`, `_Tree` — each grammar form.
-- [ ] `TestParseEntry_PinnedSHA` — 40-char ref recognised as SHA.
-- [ ] `TestParseEntry_Invalid` — bad type prefix, missing required path.
-- [ ] `TestContentHash_Deterministic` — same tree → same hash across runs.
-- [ ] `TestContentHash_LineEndings` — CRLF vs LF normalized.
-- [ ] `TestFetcher_CacheHit` — mock HTTP layer, second fetch hits cache.
-- [ ] `TestFetcher_RefResolution` — tag, branch, SHA all resolve.
-- [ ] `TestPull_Idempotent` — second pull writes nothing.
-- [ ] `TestPull_DetectsLocalModification` — diff returned, no write.
-- [ ] `TestPull_TreeFanout` — one tarball → multiple buckets populated.
-- [ ] `TestUpdate_MovedTag` — SHA changes, artifact re-fetched.
-- [ ] `TestUpdate_SHAPinnedSkipped` — no fetch.
-- [ ] `TestBundle_RoundTrip` — manual artifact with origin → manifest
-      entry; subsequent pull is a no-op.
-- [ ] `TestTokenResolution_Order` — env vars short-circuit `gh` shellout.
-- [ ] `TestGlobalRoot_Routing` — `--global` writes under global root only.
-- [ ] `TestIntegrityMismatch_Aborts` — tampered tarball → no writes.
-
-### Bats integration (with a fake GitHub via local file server)
-
-- [ ] End-to-end pull → list → modify upstream → update → list shows
-      `[outdated]` then `[ok]`.
-- [ ] `source remove` deletes artifact unless `--keep`.
-- [ ] `--offline` honors cache and errors on miss.
-
-### Manual smoke
-
-- [ ] Real GitHub pull of skillfish's own repo as a `tree:` entry,
-      verifying our fetcher matches what `git archive` would produce.
-
-## Rollout
-
-1. New package `internal/agent/source/` lands in one PR with all
-   commands + Go unit tests + bats fixtures.
-2. README gains a "Source manifest" section under Commands.
-3. CHANGELOG: `feat: declarative source manifest and pull command for
-   upstream rules, skills, and workflows`.
-4. Existing `sync-agents import <url>` becomes a thin shim around
-   `source add` — no behavior change for current users.
-
-### Suggested implementation order
-
-1. `entry.go` + parser + tests.
-2. `hash.go` + tests.
-3. `fetcher.go` with mocked HTTP + cache + tests; then real GitHub.
-4. `origin.go` + `manifest.go` parse/write + tests.
-5. `pull.go` orchestration + idempotency + local-mod detection.
-6. `update`, `bundle`, `detach`.
-7. CLI wiring in `main.go`.
-8. `--global` integration with SPEC-002 root resolver.
-9. `import` shim refactor.
-
-## Open Questions
-
-- **Q1**: `sources.yaml` vs `sources.json` vs extending existing
-  `.agents/config` (INI-ish) — picked YAML. Confirm.
-- **Q2**: Per-artifact origin filename — `_origin.json` next to
-  `SKILL.md` for skills, `<name>.origin.json` for files. Alternative:
-  always under `.agents/.origins/<rel-path>.json` (out-of-band). Picked
-  in-band for discoverability when reading a skill dir.
-- **Q3**: `tree:` entry semantics — currently walks `.agents/{rules,
-  skills,workflows}/` only. Should it also pick up `.agents/AGENTS.md`
-  inheritance pointers? Defer.
-- **Q4**: Should `pull` regenerate `AGENTS.md` automatically on success
-  (mirroring SPEC-002 behavior)? Lean yes; confirm.
-- **Q5**: Auth for private repos relies on the user's token. Should we
-  surface a `sync-agents source whoami` debug subcommand to print which
-  token source is being used? Lean yes, cheap.
-- **Q6**: Compatibility with skillfish's `skillfish.json` — should
-  `sync-agents source import-skillfish` import a `skillfish.json` into
-  our `sources.yaml`? Trivial and friendly; recommend yes as a follow-up.
-
-## Future Work
-
-- **GitLab/Bitbucket fetchers** — `Fetcher` interface leaves room.
-- **Cache prune** — `sync-agents source cache prune --older-than 30d`.
-- **Registry integration** — could point at skill.fish's registry for
-  discovery without depending on it for installation.
-- **Skillfish import** — read `skillfish.json` and emit `sources.yaml`
-  entries (with type `skill:` for each).
-- **Signed sources** — `sigstore`/cosign verification before extraction.
-
-## References
-
-- skillfish: https://github.com/knoxgraeme/skillfish
-- skillfish manifest schema (project-manifest.ts) — `skills: string[]`
-  with `owner/repo[@ref][/path]` grammar.
-- SPEC-001 — first-class `go install`.
-- SPEC-002 — promote/global sync, semantic-aware routing.
diff --git a/specs/SPEC-004-new-asset-buckets.md b/specs/SPEC-004-new-asset-buckets.md
deleted file mode 100644
index 389674e..0000000
--- a/specs/SPEC-004-new-asset-buckets.md
+++ /dev/null
@@ -1,284 +0,0 @@
----
-id: SPEC-004
-title: "New asset buckets: agents, hooks, plans, specs — .claude-first routing on a centralized bucket registry"
-status: Draft
-owner: nmccready
-created: 2026-07-02
-updated: 2026-07-03 (rev 2: Part F — adrs bucket with status subdirectories)
-related: SPEC-002, SPEC-003, SPEC-005
----
-
-# [SPEC-004] Feature: New asset buckets (agents, hooks, plans, specs)
-
-## Overview
-
-Extend the canonical `.agents/` tree beyond the current three buckets
-(`rules`, `skills`, `workflows`) with four new ones:
-
-| Bucket        | Contents                                   | Primary destination                     |
-| ------------- | ------------------------------------------ | --------------------------------------- |
-| `agents/`     | Subagent definitions (`<name>.md`)         | `.claude/agents/<name>.md`              |
-| `hooks/`      | Harness hook fragments (`<name>.json`)     | merged into `.claude/settings.json`     |
-| `plans/`      | Implementation plans / task breakdowns     | indexed reference docs (see Part D)     |
-| `specs/`      | Durable design / requirements documents    | indexed reference docs (see Part D)     |
-
-Claude Code is the first-class target for all four. Other tools skip
-buckets they have no equivalent for, using the same graceful-skip
-pattern `destination.go` already uses (e.g. Passive skill → skipped).
-
-Prerequisite: a **bucket registry refactor** (Part A) so that adding a
-bucket is one registry entry instead of edits to ~6 hardcoded
-`[]string{"rules", "skills", "workflows"}` sites in `agent.go`.
-
-## Motivation
-
-1. **Subagents are un-syncable today.** Claude Code reads
-   `.claude/agents/<name>.md` (project) and `~/.claude/agents/`
-   (global). There is no `.agents/` bucket for them, so teams
-   copy-paste subagent files per project — exactly the problem
-   sync-agents exists to solve.
-2. **Hooks are un-syncable today.** Claude Code hooks live inside
-   `.claude/settings.json`. Nothing in sync-agents can carry a hook
-   from `.agents/` into that file, and naive syncing would clobber
-   user-authored settings.
-3. **Plans and specs are first-class agent context.** Spec-driven
-   workflows (including this repo's own `specs/SPEC-00X` process)
-   produce durable documents that agents should discover. Today they
-   have no bucket, no index entry, and no routing.
-
-### plans vs specs — why both?
-
-The distinction is **lifecycle, not plumbing**:
-
-- **`specs/`** — durable design/requirements documents: _what_ to build
-  and why. Long-lived, committed, the source of truth. Survive the
-  effort that produced them.
-- **`plans/`** — implementation plans and task breakdowns: _how/when_.
-  Working documents scoped to an effort; typically archived or deleted
-  when the effort lands.
-
-Both route identically (Part D). Supporting both costs one registry
-entry each after Part A, and conflating them forces teams to choose
-between polluting durable specs with ephemeral task lists or losing
-plan history.
-
-## Goals
-
-- Part A: single bucket registry consumed by `sync`, `status`, `clean`,
-  `fix`, `init`, `add`, `index`, and the semantic router. Pure
-  refactor; zero behavior change.
-- Part B: `agents` bucket synced to `.claude/agents/` (local symlink,
-  global copy via `promote`/`global sync`).
-- Part C: `hooks` bucket merged into `.claude/settings.json` with
-  strict ownership tracking — sync-agents only ever adds/removes
-  entries it wrote; user-authored settings are never touched.
-- Part D: `plans` + `specs` buckets as indexed reference docs.
-- All changes backwards compatible (see Backwards Compatibility).
-
-## Non-Goals
-
-- New tool targets (gemini, opencode) — separate effort.
-- Executing or validating hook commands — SPEC-005 territory.
-- Remote install of the new bucket types — SPEC-003 gains them for
-  free once buckets are registry-driven.
-- Translating Claude hook fragments to other harnesses' hook systems.
-
-## Part A — Bucket registry refactor (Phase 0, standalone PR)
-
-Today the bucket list is hardcoded in at least: `CmdSync`
-(`agent.go:363`), `CmdStatus` (`:436`), `CmdClean` (`:474`), `CmdFix`
-(`:668-673`), `CmdInit` (`:245-247`), `CmdAdd` (`:295-305`), plus the
-`ArtifactType` enum in `promote.go:16-22` and routing in
-`destination.go`.
-
-Design:
-
-```go
-// internal/agent/bucket.go
-type Bucket struct {
-    Name      string       // directory name under .agents/
-    Artifact  ArtifactType // singular artifact type ("rule", "agent", …)
-    Aliases   []string     // CmdAdd aliases ("rule", "rules", …)
-    Layout    BucketLayout // FlatFiles | SkillDirs | JSONFragments
-    InInit    bool         // created by `sync-agents init`
-    Reference bool         // Part D reference-doc semantics
-}
-
-var Buckets = []Bucket{ /* rules, skills, workflows — then Part B–D append here */ }
-```
-
-All call sites iterate `Buckets` (or filter it) instead of literal
-slices. `CmdAdd`'s type switch and `CmdFix`'s validation derive from
-`Aliases`. Behavior with only the classic three registered is
-byte-for-byte identical — verified by the existing bats + go suites
-passing unmodified.
-
-## Part B — `agents` bucket (subagents)
-
-- Source: `.agents/agents/<name>.md`. Frontmatter is Claude's subagent
-  schema (`name`, `description`, `tools`, `model`) — sync-agents treats
-  it as opaque except `name` for collision checks.
-- Local sync: symlink the bucket dir, same as existing buckets:
-  `.claude/agents -> ../.agents/agents`. If a real (non-symlink)
-  `.claude/agents/` already exists, warn and skip (never merge or
-  clobber) — same conflict rule `CreateSymlink` applies today.
-- Global: `promote agent <name>` copies to `~/.agents/agents/`;
-  `global sync` routes to `~/.claude/agents/<name>.md`.
-- Semantics: always Invocable-like (Claude auto-discovers agents);
-  never included in the managed CLAUDE.md import block.
-- Other tools: skipped (no subagent equivalent in cursor / windsurf /
-  copilot / codex today).
-
-## Part C — `hooks` bucket
-
-- Source: `.agents/hooks/<name>.json`. Each file is one hook fragment
-  in Claude's settings schema:
-
-```json
-{
-  "event": "PreToolUse",
-  "matcher": "Bash",
-  "hooks": [{ "type": "command", "command": "./scripts/check.sh" }]
-}
-```
-
-- Destination: `.claude/settings.json` → `hooks.<event>[]`. JSON has no
-  comments, so marker-block ownership (the CLAUDE.md approach) doesn't
-  work. Instead, ownership is tracked in a sidecar state file
-  `.agents/.sync/claude-hooks-state.json` recording exactly which
-  entries sync-agents wrote (fragment name → event + content hash).
-  Regeneration removes precisely the recorded entries and re-adds
-  current fragments; user-authored hook entries and all other settings
-  keys pass through untouched. Writes are atomic (tmp + rename) and
-  key-order stable to keep diffs reviewable.
-- `clean` removes only recorded entries; if `hooks` becomes empty it is
-  dropped; if settings.json becomes `{}` it is deleted only when
-  sync-agents created it (recorded in the state file).
-- Idempotency: `sync` twice → identical settings.json (tested).
-- Naming collision: the existing `sync-agents hook` command (git
-  pre-commit installer) is renamed `sync-agents git-hook`; `hook`
-  remains as a hidden deprecated alias printing a pointer to the new
-  name. Docs updated.
-- Other tools: skipped in v1.
-
-## Part D — `plans` + `specs` buckets (reference docs)
-
-- Source: `.agents/plans/<name>.md`, `.agents/specs/<name>.md`. Flat
-  files; subdirectories allowed (indexed recursively) since plan/spec
-  sets are often grouped per effort.
-- Local sync: symlink bucket dirs into `.claude/` (`.claude/plans`,
-  `.claude/specs`) so they're @-mentionable and discoverable, plus an
-  **AGENTS.md index section** listing each doc with its frontmatter
-  `description` (same generator that indexes rules today).
-- NOT included in the managed CLAUDE.md import block by default —
-  reference docs are pulled on demand, not preloaded into context.
-  Frontmatter `import: true` opts a doc in.
-- Semantics: new `Reference` semantic alongside Invocable/Passive in
-  `semantic.go`; `promote`/`global sync` route them to
-  `~/.claude/{plans,specs}/` for the global scope.
-- Other tools: indexed in AGENTS.md (which codex/copilot consume via
-  concat); no per-tool dirs in v1.
-
-## Part E — Skill frontmatter compliance: `lint` + `lint --fix`
-
-Claude's published skill authoring rules
-(<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices>)
-require SKILL.md frontmatter that our current scaffold does not emit
-(`templates/skill.md` writes only `trigger: always_on` — no `name`,
-no `description`), and skills authored before the rules existed need
-a mechanical upgrade path. Two deliverables:
-
-1. **Claude-compatible scaffold.** `sync-agents add skill <name>`
-   emits frontmatter with `name: <name>` and a `description:` seeded
-   with the required what-it-does + when-to-use shape, in third
-   person. Existing keys (`invocable:`, `trigger:`) remain supported
-   and are preserved.
-
-2. **`sync-agents lint [skills] [--fix]`** — validate every
-   `.agents/skills/<dir>/SKILL.md` against the published rules and
-   mechanically amend what's fixable:
-
-   | Check | Rule | `--fix` action |
-   | ----- | ---- | -------------- |
-   | E001  | frontmatter block missing | inject one |
-   | E002  | `name` missing/empty | derive from dir name (slugified) |
-   | E003  | `name` has uppercase/invalid chars (must be `[a-z0-9-]`) | slugify (lowercase, `_`/space→`-`, strip the rest) |
-   | E004  | `name` > 64 chars | truncate at hyphen boundary |
-   | E005  | `name` contains reserved word (`anthropic`, `claude`) | report only |
-   | E006  | `name` ≠ skill directory name | set to dir slug |
-   | E007  | `description` missing/empty | derive from first body paragraph, else TODO stub + warning |
-   | E008  | `description` > 1024 chars | truncate |
-   | E009  | XML tags in `name`/`description` | strip |
-   | W101  | first-person description ("I can…", "You can use this…") | report only (third person required) |
-   | W102  | description lacks a when-to-use trigger clause | report only |
-   | W103  | SKILL.md body > 500 lines | report only |
-
-   `lint` exits non-zero on E-level findings (CI-friendly); warnings
-   don't affect the exit code. `--fix` rewrites only the frontmatter
-   block — body untouched, unknown frontmatter keys preserved, atomic
-   write, idempotent (second run reports clean).
-
-Scope note: v1 lints the skills bucket. The check set is organized
-per-bucket so rules/workflows (and Part B agents, whose subagent
-frontmatter has its own schema) can be added incrementally via the
-Part A registry. SPEC-005's install-time scanner reuses `lint` so
-remotely pulled skills are held to the same bar before approval.
-
-## Part F — `adrs` bucket (Architecture Decision Records)
-
-- Source: `.agents/adrs/<status>/<name>.md` with status ∈
-  {`proposed`, `accepted`, `denied`} encoded by subdirectory (the
-  directory is the source of truth; frontmatter `status:` mirrors it).
-  Nested grouping subdirs allowed (`adrs/accepted/db/use-postgres.md`).
-- `add adr <name>` scaffolds into `proposed/`. `sync-agents adr
-  <accept|deny|propose> <name>` moves records between statuses,
-  updates the frontmatter label, and regenerates AGENTS.md.
-  Ambiguous names (same basename under two statuses) error rather
-  than guess.
-- Index: `## ADRs` section with `### Accepted` and `### Proposed`
-  subsections. **Denied records are never indexed**; the section
-  carries a standing note directing agents to check
-  `.agents/adrs/denied/` before proposing, so rejected decisions
-  aren't re-proposed (the note ships in generated context — it can't
-  drift or be forgotten like a separate rule file).
-- Routing: Reference semantic, same as plans/specs — `.claude/adrs`
-  local symlink (Claude-only), skip elsewhere.
-
-## Backwards Compatibility
-
-- New buckets activate **only when their directory exists**. A v0.3.x
-  `.agents/` tree syncs byte-for-byte identically.
-- `sync-agents init` keeps creating only the classic three buckets;
-  new ones are created on demand by `sync-agents add
-  agent|hook|plan|spec <name>`.
-- `.agents/config` schema unchanged; `targets=` still the only key.
-- AGENTS.md index gains sections only for present buckets.
-- `hook` → `git-hook` rename ships with a working deprecated alias; no
-  script breaks.
-- Index/lock sidecar lives under `.agents/.sync/` (new, gitignored by
-  the existing `updateGitignore` mechanism).
-
-## Test Plan
-
-- Part A: full existing go + bats suites pass with zero test edits.
-- Part B/D: golden-tree tests per bucket (sync, re-sync idempotent,
-  clean restores pristine state, status output).
-- Part C: table tests for settings.json merge — empty file, missing
-  file, user-authored hooks present, ours interleaved with theirs,
-  fragment removed upstream, tampered state file (fail loud, no
-  writes), `clean` on each of the above.
-- Collision tests: pre-existing real `.claude/agents/` dir → warn+skip.
-- Part E: table tests per check (E001–E009, W101–W103), fix
-  idempotency (lint → fix → lint reports clean), unknown frontmatter
-  keys survive a fix round-trip, exit codes (errors=1, warnings
-  only=0).
-
-## Rollout
-
-1. PR 0 (Part A) — registry refactor, no behavior change.
-2. PR 1 (Part E) — skill `lint`/`lint --fix` + Claude-compatible
-   scaffold (independent of the other parts; highest immediate value).
-3. PR 2 (Part B) — `agents` bucket.
-4. PR 3 (Part D) — `plans` + `specs` (simpler than hooks; ships early).
-5. PR 4 (Part C) — `hooks` + `git-hook` rename.
-6. Docs: README bucket table, `docs/architecture/buckets.md`.
diff --git a/specs/SPEC-005-sandboxing-quarantine.md b/specs/SPEC-005-sandboxing-quarantine.md
index acdc533..942bf36 100644
--- a/specs/SPEC-005-sandboxing-quarantine.md
+++ b/specs/SPEC-005-sandboxing-quarantine.md
@@ -1,10 +1,10 @@
 ---
 id: SPEC-005
 title: "Supply-chain safety by default: fetch hardening, install quarantine + static scan, sandboxed skill exec"
-status: Parts A+B Implemented (Part C future)
+status: Parts A+B Shipped (v1.1.0–v1.2.0); Part C (sandboxed exec) open
 owner: nmccready
 created: 2026-07-02
-updated: 2026-07-02
+updated: 2026-07-09 (rev 2: Parts A+B trimmed to a shipped summary; doc now tracks only the open Part C)
 related: SPEC-003, SPEC-004
 ---
 
@@ -16,117 +16,49 @@ Make remote artifact installation safe **by default** on macOS and
 Linux. Three layers, in dependency order:
 
 1. **Fetch hardening** (Part A) — the download/extract path itself can
-   neither execute content nor escape the target directory.
+   neither execute content nor escape the target directory. **Shipped.**
 2. **Quarantine + static scan** (Part B) — remotely-fetched artifacts
    land in a holding area, get scanned, and require explicit approval
-   before entering the live `.agents/` tree.
+   before entering the live `.agents/` tree. **Shipped.**
 3. **Sandboxed exec wrapper** (Part C, stretch) — an opt-in runner that
    executes skill scripts under an OS sandbox (macOS `sandbox-exec`,
-   Linux `bwrap`/Landlock) with a default-deny profile.
+   Linux `bwrap`/Landlock) with a default-deny profile. **Open.**
 
 sync-agents does not itself execute skills — harnesses do — so the
-highest-leverage safety work is at **install time** (Parts A + B).
+highest-leverage safety work was at **install time** (Parts A + B).
 Part C covers the residual risk for skills that ship scripts.
 
-## Motivation
-
-- `CmdImport` today shells out to `curl -fsSL <url> -o <dest>` and
-  drops the result directly into the live tree: no integrity check, no
-  review gate, no record of origin. One malicious or typo'd URL and a
-  hostile rule/skill is in every synced harness on the machine.
-- SPEC-003 adds manifest + lockfile + sha256 integrity (tamper
-  detection), but integrity ≠ safety: a correctly-hashed artifact can
-  still contain `curl | bash`, credential exfiltration, or prompt
-  injection. Treat skill registries and "tap" repos as a hostile
-  supply chain, like npm.
-- Agent harnesses increasingly auto-load whatever is in their config
-  dirs. The install pipeline is the last human checkpoint.
-
-## Goals
-
-- No code path in sync-agents ever executes fetched content.
-- Remote installs (`import`, SPEC-003 `pull`/`update`) default to
-  quarantine; promotion to the live tree is an explicit, logged action.
-- `sync-agents scan` produces a human-readable findings report per
-  artifact; findings recorded in the SPEC-003 lockfile on approve.
-- Escape hatches exist (`--trust`, config default) but are loud.
-- Part C runner works on macOS and Linux; other unixes get best-effort
-  (no sandbox available → refuse unless `--unsandboxed`).
-
-## Non-Goals
-
-- Sandboxing the harnesses themselves (Claude/Cursor own their exec).
-- Signature verification / sigstore — future; sha256 pinning only
-  (SPEC-003).
-- Windows sandboxing (AppContainer) — deferred.
-- LLM-based semantic scanning — heuristics only in v1.
-
-## Part A — Fetch hardening
-
-- Replace the `curl` subprocess in `CmdImport` with native Go
-  `net/http`: TLS verification on, redirects capped (5), https-only by
-  default (`--insecure-http` to override), timeout + size cap
-  (default 10 MiB/artifact, configurable).
-- SPEC-003 tarball extraction: reject path traversal (`..`, absolute
-  paths, symlinks pointing outside the extract root), reject
-  hardlinks, strip setuid/setgid/exec bits on extract, entry-count and
-  total-size caps (zip-bomb guard).
-- Downloads land in a temp dir and move into place only after all
-  checks pass (already SPEC-003's atomic-write requirement; restated
-  here as a security invariant, not just a crash-safety one).
-
-## Part B — Quarantine + static scan
-
-### Flow
-
-```
-import/pull ──▶ .agents/.quarantine/<bucket>/<name>/   (+ _origin.json)
-                      │
-                      ▼
-              sync-agents scan [name]     # automatic after fetch
-                      │  findings report (stdout + .findings.json)
-                      ▼
-              sync-agents approve <name>  # human gate
-                      │  moves into .agents/<bucket>/, records
-                      ▼  scan verdict + content hash in lockfile
-              live tree (synced to harnesses on next sync)
-```
-
-- Quarantined artifacts are **invisible to `sync`** — nothing under
-  `.agents/.quarantine/` is ever symlinked, indexed, or imported.
-- `sync-agents approve <name> [--all]` promotes; `sync-agents reject
-  <name>` deletes with its findings.
-- `--trust` on `import`/`pull` skips the gate but still runs the scan
-  and prints findings (loud escape hatch, for CI bootstrap of
-  already-reviewed manifests). `.agents/config` gains
-  `quarantine = on|off` (default `on`) for teams that pin by sha and
-  review in PRs instead.
-- Local authoring (`add`, `promote`) is untouched — quarantine applies
-  to remote content only.
-
-### Scanner heuristics (v1)
-
-Per-file findings with severity (info / warn / critical):
-
-- Shell execution surface: shebang scripts in skill dirs, `Bash(`
-  tool grants in frontmatter, `exec`/`eval`/`system` in embedded code.
-- Network-then-execute: `curl … | sh`, `wget … | bash`, `iwr | iex`,
-  base64-decode-then-exec chains.
-- Exfiltration patterns: reads of `~/.ssh`, `~/.aws`, `.env`,
-  `*_TOKEN`/`*_API_KEY` env references combined with network calls.
-- Obfuscation: long base64/hex blobs, zero-width/bidi Unicode,
-  homoglyph command names.
-- Prompt-injection markers in markdown: "ignore previous
-  instructions", hidden HTML comments with directives, instructions
-  addressed to the agent to disable safety/review steps.
-- Frontmatter anomalies: undeclared extra files in single-file
-  buckets, `import: true` on remote reference docs (context
-  preloading from an untrusted source).
-
-Critical findings block `approve` unless `--force` (logged into the
-lockfile entry as `approved_with_findings`).
-
-## Part C — Sandboxed exec wrapper (stretch)
+## Shipped (Parts A + B)
+
+Landed in v1.1.0 (fetch hardening rode in with the SPEC-003 pull
+pipeline, PR #62) and v1.2.0 (quarantine + scanner, PR #64, issue #52).
+User-facing behavior is documented in
+[docs/quarantine.md](../docs/quarantine.md); this list is the
+requirements-level summary:
+
+- **Fetch hardening:** native Go `net/http` (no `curl` subprocess),
+  TLS verification, capped redirects, https-only by default, timeout +
+  size caps; tarball extraction rejects path traversal, absolute
+  paths, escaping symlinks, and hardlinks; strips exec/setuid bits;
+  entry-count and total-size caps (zip-bomb guard); temp-dir download
+  with atomic move-into-place.
+- **Quarantine flow:** `pull`/`update`/`import` land remote content in
+  `.agents/.quarantine/` (never synced, indexed, or imported);
+  `quarantine` lists findings; `approve <name>|--all` promotes;
+  `reject <name>|--all` deletes.
+- **Static scanner (heuristic v1):** shell-execution surface,
+  network-then-execute chains (`curl | bash` etc.), credential-read +
+  network exfiltration combos, obfuscation (long base64/hex,
+  zero-width/bidi Unicode), prompt-injection phrasing, frontmatter
+  anomalies. Severity info/warn/critical.
+- **Escape hatches, loud and audited:** critical findings block
+  `approve` unless `--force` (recorded in `sources.lock` as
+  `approved_with_findings`); `--trust` skips the gate for one
+  invocation but still scans and prints; `quarantine = off` in
+  `.agents/config` disables the gate. Local authoring (`add`,
+  `promote`) is never quarantined.
+
+## Open — Part C: Sandboxed exec wrapper (stretch)
 
 - `sync-agents run <skill> -- <cmd…>` executes a skill's script under:
   - macOS: `sandbox-exec` with a generated seatbelt profile.
@@ -147,36 +79,23 @@ permissions:
 - Harness integration is out of scope; the wrapper exists so harness
   configs *can* route skill exec through it (documented recipe for
   Claude hooks: PreToolUse hook rewriting skill-script invocations).
+- Other unixes get best-effort (no sandbox available → refuse unless
+  `--unsandboxed`). Windows sandboxing (AppContainer) remains deferred.
+
+### Part C test plan
+
+- Sandboxed process cannot read a canary file outside the allow-list.
+- Cannot open a socket when network is denied.
+- Permission frontmatter round-trips into the generated profile.
+- CI: macOS + ubuntu runners.
+
+### Part C rollout
 
-## Backwards Compatibility
-
-- `import` keeps its CLI shape; the only visible change is the
-  quarantine step. `quarantine = off` restores v0.3.x behavior
-  exactly.
-- No new runtime dependencies for Parts A/B (pure Go + stdlib;
-  scanner is regex/AST heuristics). Part C shells out to OS tools that
-  are present by default (`sandbox-exec`) or clearly diagnosed when
-  missing (`bwrap`).
-- `.agents/.quarantine/` and `.findings.json` are gitignored via the
-  existing `updateGitignore` mechanism.
-
-## Test Plan
-
-- Part A: traversal/symlink/hardlink/zip-bomb fixture tarballs → no
-  writes outside root, loud errors; http→https redirect; size cap.
-- Part B: fixture artifacts per heuristic class → expected findings;
-  approve/reject state transitions; quarantined content never synced
-  (run `sync`, assert absent); `--trust` still scans; idempotent
-  re-pull of a quarantined name.
-- Part C: sandboxed process cannot read a canary file outside the
-  allow-list, cannot open a socket when network denied; permission
-  frontmatter round-trips into the generated profile. CI: macOS +
-  ubuntu runners.
-
-## Rollout
-
-1. PR 1 (Part A) — fetch hardening; lands independently, hardens
-   existing `import` immediately.
-2. PR 2+3 (Part B) — quarantine flow, then scanner heuristics.
-   Sequenced after SPEC-003's pull pipeline (quarantine hooks into it).
-3. PR 4 (Part C) — runner, macOS first, then Linux.
+Single PR series: runner on macOS first, then Linux.
+
+## Non-Goals (unchanged)
+
+- Sandboxing the harnesses themselves (Claude/Cursor own their exec).
+- Signature verification / sigstore — future; sha256 pinning only
+  (SPEC-003, retired to git history).
+- LLM-based semantic scanning — heuristics only in v1.
diff --git a/specs/SPEC-006-os-scoped-routing.md b/specs/SPEC-006-os-scoped-routing.md
index 64f3758..2a0a5b6 100644
--- a/specs/SPEC-006-os-scoped-routing.md
+++ b/specs/SPEC-006-os-scoped-routing.md
@@ -1,10 +1,10 @@
 ---
 id: SPEC-006
 title: "OS-scoped artifact routing — per-platform rules, skills, and workflows"
-status: Core Implemented (routing + config override + @-imports; AGENTS.md badge & concat OS-headers pending)
+status: Core Shipped (v1.3.0); open — AGENTS.md OS badge + concat OS headers
 owner: nmccready
 created: 2026-07-02
-updated: 2026-07-02
+updated: 2026-07-09 (rev 2: shipped core trimmed to a summary; doc now tracks only the two cosmetic gaps)
 related: SPEC-004, SPEC-005
 ---
 
@@ -14,112 +14,43 @@ related: SPEC-004, SPEC-005
 
 Allow any `.agents/` bucket to carry optional OS-scoped subdirectories
 (`macos/`, `linux/`, `unix/`, `windows/`) whose contents route **only**
-when the host matches.
-
-```
-.agents/
-├── rules/
-│   ├── security.md          → always
-│   ├── macos/
-│   │   └── brew.md          → Darwin only
-│   ├── linux/
-│   │   └── apt.md           → Linux only
-│   └── unix/
-│       └── posix.md         → Darwin + Linux (not Windows)
-├── skills/
-│   ├── macos/
-│   │   └── screen-recording/  → Darwin only
-│   └── ...
-```
-
-The OS gate is applied at **sync time** via `runtime.GOOS`: artifacts
-in `macos/` only symlink on Darwin, `linux/` only on Linux, `unix/` on
-both, `windows/` only on Windows. The root-level files are always
-synced (no gate), preserving backward compatibility.
+when the host matches. The OS gate is applied at sync time via
+`runtime.GOOS`; root-level files are always synced, preserving backward
+compatibility.
 
 This is a **routing** feature — it gates which artifacts reach which
 machines. It is orthogonal to SPEC-005's runtime sandboxing (which
 controls what a skill can *do* once loaded).
 
-## Motivation
-
-- Homelab/server skill sets differ from desktop Mac workflows.
-  `brew` rules are noise on a Linux box; `apt` rules are noise on a
-  Mac. Today you either maintain separate repos or pollute every
-  machine with irrelevant context.
-- Cross-platform teams commit one `.agents/` tree. Without OS gating,
-  every dev gets every rule regardless of their OS.
-- The `unix/` subdir covers the common case (POSIX conventions that
-  apply to both macOS and Linux but not Windows) without duplicating
-  files.
-
-## Goals
-
-- `macos/`, `linux/`, `unix/`, `windows/` subdirectories under any
-  bucket are recognized by the artifact discovery loop.
-- Non-matching OS subdirs are silently skipped at sync time (no
-  symlink, no concat contribution, no index entry).
-- The managed CLAUDE.md @-import block only includes rules from
-  matching OS subdirs.
-- AGENTS.md index lists OS-scoped entries with a visual indicator
-  (`[macos]`, `[linux]`, `[unix]`) so readers know which artifacts
-  are gated.
-- All existing tests pass unmodified (no OS subdirs = no behavior
-  change).
-- `sync-agents init` does NOT create OS subdirs — they activate when
-  the user creates them (same opt-in model as plans/specs/agents).
-
-## Non-Goals
+## Shipped (core, v1.3.0 — PR #67, 3 of 4 rollout steps)
 
-- Windows per-seat policies, Group Policy, or registry — Windows
-  support in sync-agents is speculative; `windows/` subdirs are
-  included for spec completeness but not a v1 deliverable.
-- Runtime sandboxing (SPEC-005) — orthogonal.
-- OS-specific `.agents/config` overrides — the config file is
-  platform-agnostic.
-
-## Design
+User-facing behavior is documented in
+[docs/os-scoped-routing.md](../docs/os-scoped-routing.md); this list is
+the requirements-level summary:
 
-### Discovery
-
-`DiscoverArtifacts` (or a new wrapper) walks each bucket's directory
-tree. When it enters an OS-scoped subdirectory, it checks:
-
-```go
-var osScopes = map[string]func(string) bool{
-    "macos":   func(goos string) bool { return goos == "darwin" },
-    "linux":   func(goos string) bool { return goos == "linux" },
-    "unix":    func(goos string) bool { return goos == "darwin" || goos == "linux" },
-    "windows": func(goos string) bool { return goos == "windows" },
-}
-```
-
-If the scope matches, artifacts within are discovered normally. If it
-doesn't match, the entire subdirectory is skipped (no `WalkDir` into
-it). This is cheaper than discovering then filtering.
-
-Scoped names retain the subdirectory prefix as context: a rule at
-`rules/macos/brew.md` is named `macos/brew` internally. The destination
-path resolves to `rules/macos/brew.md` → symlinked as
-`.claude/rules/macos/brew.md` (the OS subdir is preserved so multiple
-platforms' rules don't collide in the same flat `rules/` target dir).
-
-### Routing
+- **Discovery:** `macos/`, `linux/`, `unix/`, `windows/` subdirs under
+  any bucket are recognized; non-matching OS subdirs are skipped
+  entirely (no walk-in), matching subdirs discover normally. `unix`
+  matches darwin + linux.
+- **Routing:** destination paths mirror the source tree
+  (`.agents/rules/macos/brew.md` → `.claude/rules/macos/brew.md`), so
+  platforms never collide in a flat target dir.
+- **Managed CLAUDE.md @-import block:** includes only rules from
+  matching OS subdirs.
+- **Config override:** `os = <goos>` in `.agents/config` overrides
+  `runtime.GOOS` for testing and cross-compile CI.
+- **Opt-in:** `init` never creates OS subdirs; zero behavior change
+  for trees without them. Existing tests pass unmodified.
 
-The destination path for a scoped artifact mirrors the source tree:
+## Open — cosmetic surface
 
-```
-.agents/rules/macos/brew.md → .claude/rules/macos/brew.md
-.agents/skills/macos/screen-recording/SKILL.md → .claude/skills/macos/screen-recording/SKILL.md
-```
+Two index/concat presentation items from the original design remain
+unimplemented:
 
-This means tool directories gain the same OS subdirectory structure as
-`.agents/`. Claude loads them from nested `rules/macos/` the same way
-it loads from `rules/` — no per-tool changes needed.
+### 1. AGENTS.md OS badge
 
-### Index
-
-AGENTS.md renders OS-scoped entries with a badge:
+The index should render OS-scoped entries with a visual indicator so
+readers know which artifacts are gated:
 
 ```markdown
 ## Rules
@@ -131,77 +62,31 @@ AGENTS.md renders OS-scoped entries with a badge:
 ```
 
 The badge is informational — the index is a static file checked into
-the repo. A Linux developer reading AGENTS.md knows `[macos]` rules
-won't apply to them.
+the repo, so all platforms see all entries; a Linux developer reading
+AGENTS.md knows `[macos]` rules won't apply to them.
 
-### Managed CLAUDE.md block
+### 2. Concat OS headers
 
-The @-import block only lists rules from matching OS subdirs. On macOS:
+Concat files (Windsurf `global_rules.md`, Copilot, Codex) should append
+scoped content with an OS header comment so readers know which platform
+a block targets:
 
 ```markdown
-@/Users/me/.claude/rules/security.md
-@/Users/me/.claude/rules/macos/brew.md
-@/Users/me/.claude/rules/unix/posix.md
+<!-- OS: macos -->
 ```
 
-`linux/apt.md` is excluded because `runtime.GOOS != "linux"`.
-`RegenerateClaudeImports` already receives a filtered list from the
-discovery loop; OS filtering happens at the source.
-
-### Tool support
-
-OS subdirs route to **all tools**, same as the parent bucket — no
-per-tool restrictions beyond what the bucket already has. A rule in
-`rules/macos/` routes through the same destination logic as
-`rules/`, including Windsurf concat, Cursor symlink, etc.
-
-The only difference is the extra `macos/` path segment in the
-destination.
-
-### Config override
-
-`.agents/config` gains an optional `os = <goos>` key for testing and
-cross-compile CI. When set, discovery uses the configured OS instead
-of `runtime.GOOS`. Default: absent → use `runtime.GOOS`.
-
-## Backwards Compatibility
-
-- Zero change for `.agents/` trees with no OS subdirectories.
-- OS subdirs are never created by `init` — opt-in by creating the
-  directory.
-- AGENTS.md index gains the `[os]` badge inline; existing entries are
-  unchanged.
-- Concat files (Windsurf, Copilot, Codex) append scoped content with
-  an OS header comment so readers of `global_rules.md` know which
-  platform a block targets.
-
-## Test Plan
-
-- Table-driven test: each OS subdir name → expected match on
-  darwin/linux/windows. `unix` matches darwin + linux but not
-  freebsd (out of scope for v1).
-- Discovery test: seed `rules/`, `rules/macos/`, `rules/linux/`,
-  `rules/unix/` → run discovery on each GOOS → assert correct set.
-- Sync golden-tree test per platform: seed the same tree → sync on
-  each OS → assert correct subset of symlinks.
-- Idempotency: sync twice on the same OS → no changes.
-- Index test: AGENTS.md includes `[macos]` badge on scoped entries,
-  no badge on unscoped; all platforms see all entries (index is
-  static).
+### Remaining test plan
+
+- Index test: AGENTS.md includes `[macos]` badge on scoped entries, no
+  badge on unscoped; all platforms see all entries (index is static).
 - Concat test: Windsurf `global_rules.md` includes `<!-- OS: macos -->`
   headers on scoped sections.
-- Cross-compile test: set `os = linux` → discovery returns
-  `linux/` + `unix/` artifacts but not `macos/`.
-
-## Rollout
 
-Single PR — the feature is self-contained:
-1. Extend `DiscoverArtifacts` with OS scope awareness.
-2. Extend `destination.go` path construction to preserve the OS subdir.
-3. Extend `generateAgentsMD` to badge scoped entries.
-4. Extend `RegenerateClaudeImports` (already filtered by the caller;
-   minimal change).
-5. Add `os` key to `.agents/config` parser.
-6. Tests (table + golden-tree + discovery + index + concat).
+## Non-Goals (unchanged)
 
-No dependency on SPEC-004 Part C (hooks) or SPEC-005.
\ No newline at end of file
+- Windows per-seat policies, Group Policy, or registry — Windows
+  support in sync-agents is speculative; `windows/` subdirs exist for
+  spec completeness but are not a deliverable.
+- Runtime sandboxing (SPEC-005) — orthogonal.
+- OS-specific `.agents/config` overrides beyond the `os` key — the
+  config file is platform-agnostic.
diff --git a/specs/SPEC-007-linked-sources.md b/specs/SPEC-007-linked-sources.md
deleted file mode 100644
index 7db140e..0000000
--- a/specs/SPEC-007-linked-sources.md
+++ /dev/null
@@ -1,218 +0,0 @@
----
-id: SPEC-007
-title: "Linked (editable) sources: npm-link / go-replace for .agents artifacts"
-status: Implemented
-owner: nmccready
-created: 2026-07-06
-updated: 2026-07-07
-related: SPEC-003, SPEC-005
----
-
-# [SPEC-007] Feature: Linked (editable) sources
-
-## Overview
-
-Add an **editable / linked** source mode to the SPEC-003 source system,
-modeled on `npm link` and `go mod replace`. Today a source entry resolves
-to an immutable, SHA-pinned tarball snapshot fetched over HTTP — a one-way
-copy. A **linked** source instead points a managed artifact in `.agents/`
-at a **live local git checkout** via a relative-path symlink, so:
-
-1. **Edits flow both ways.** The artifact and the upstream working copy are
-   the same inode; editing either edits both.
-2. **The local copy reaps upstream updates** by `git pull` in the checkout
-   (or a managed clone), with no re-fetch/re-stage step.
-3. **Changes can be paid forward upstream** by branching / committing / PRing
-   from that same checkout.
-
-Linking is recorded declaratively in `sources.yaml` and `sources.lock` so
-the intent is committed, reviewable, and reproducible — replacing today's
-undocumented manual `ln -s`.
-
-## Motivation
-
-The current model is snapshot-only. When you are *actively developing* a
-skill that lives in another repo (or developing the upstream repo itself and
-consuming it here), the SPEC-003 flow forces a painful loop:
-`edit upstream → commit → push → sync-agents update → test → repeat`.
-
-Developers work around this with a hand-rolled `ln -s`, which is:
-
-- **Invisible** — not in `sources.yaml`/`sources.lock`, so `pull`/`update`
-  and the AGENTS.md index don't know the artifact is a link; a later `pull`
-  may clobber it.
-- **Non-portable** — an absolute symlink or lock path (`/Users/tars/...`)
-  breaks the instant the repo is cloned on another machine or by another
-  engineer. `sources.lock` is git-tracked, so this is a correctness bug, not
-  just an annoyance.
-- **One-off** — no lifecycle: no `list` visibility, no clean `detach`, no
-  re-pin back to a remote snapshot.
-
-`npm link` and `go mod replace` exist for exactly this. We adopt the
-`replace` model: keep the upstream identity entry, redirect resolution to a
-**relative** local path.
-
-## Goals
-
-- `sync-agents source add --link <path> <entry>` declares a linked source:
-  writes the upstream `<entry>` to `sources.yaml` **and** an override
-  redirecting it to a relative `file:` path, then wires the symlink.
-- Bare `sync-agents source add --link <entry>` (no path) **manages a clone**:
-  clones the upstream repo into `.agents/.sources/<owner>-<repo>/`, then links
-  the artifact out of it. `update` runs `git pull` in that clone.
-- `sync-agents source add --link <path>` (path, no entry) derives
-  `owner/repo` (and type/in-repo path) from the checkout's git remote +
-  layout.
-- `pull` / `update` **skip the HTTP fetcher** for linked entries (nothing to
-  download); `update` optionally `git pull`s a managed clone.
-- `index` **follows the symlink** so AGENTS.md still enumerates the artifact.
-- `source list` marks linked entries (`link → ../foo-skill`).
-- `detach` converts a link into a real vendored copy (materialize the files,
-  drop the override) — the inverse of linking.
-- All persisted paths are **relative** (`file:` scheme); the on-disk symlink
-  is created **relative** too. Absolute paths are rejected at parse time.
-
-## Non-goals
-
-- **Watching / copy-on-change.** We symlink; we do not run a file watcher.
-  Symlink *is* the bidirectional link (same as `npm link`).
-- **Cross-VCS.** Managed clones are git-only in v1.
-- **Automatic pay-forward.** Committing/pushing/PRing upstream stays a manual
-  git action in the checkout — we do not wrap `git push`/`gh pr`.
-- **Re-running SPEC-005 quarantine per sync.** See Security.
-
-## Path grammar & the `file:` scheme
-
-Linked paths use npm's `file:` convention, resolved **relative to the
-`.agents/` directory** (the `sources.yaml` location):
-
-```
-file:../foo-skill          # sibling of the repo root (common: checkout in ~/code)
-file:./vendor/foo-skill    # inside the project
-```
-
-- **Absolute paths are a parse error** (`file:/Users/...`, `file:/abs`) — they
-  do not round-trip through git. Error names the fix (use a `file:../` relative
-  path).
-- The literal after `file:` is `path.Clean`ed and must stay a relative path
-  (may traverse up with `..`).
-- Portability across machines requires the same sibling layout on each — this
-  is inherent to relative links and shared with `go mod replace`. Documented,
-  not worked around.
-
-## Manifest & lock schema
-
-Linking reuses the existing `Override` mechanism (`match` glob), adding one
-field — a link is conceptually "pin to a local path instead of a SHA":
-
-`sources.yaml`
-```yaml
-version: 1
-sources:
-  - skill:nmccready/foo-skill          # upstream identity — unchanged
-overrides:
-  - match: skill:nmccready/foo-skill*
-    link: file:../foo-skill            # relative to .agents/; mutually exclusive with pin_sha
-```
-
-`sources.lock`
-```yaml
-version: 1
-entries:
-  - entry: skill:nmccready/foo-skill
-    link: file:../foo-skill            # relative, echoing the override
-    resolved_sha: 9f3a…                # HEAD of the checkout at link time — INFORMATIONAL only
-    content_hash: ""                   # empty: a live checkout has no stable content hash
-    fetched_at: 2026-07-06T23:00:00Z
-    managed_clone: false               # true when sync-agents owns the clone under .agents/.sources/
-```
-
-Schema changes:
-
-- `Override.Link string` (yaml `link,omitempty`). Mutually exclusive with
-  `PinSHA` — validated on load (a link cannot also be SHA-pinned).
-- `LockEntry.Link string`, `LockEntry.ManagedClone bool`. `ResolvedSHA` for a
-  linked entry is informational (records provenance at link time; not used for
-  drift/verification). `ContentHash` is empty for links.
-
-## Behavior
-
-### `source add --link`
-
-| invocation | behavior |
-|---|---|
-| `--link <path> <entry>` | write `<entry>` to `sources`; write override `link: file:<rel>` (path made relative to `.agents/`); create relative symlink `.agents/<bucket>/<name> → <path>/<in-repo-path>`; write lock. |
-| `--link <entry>` (no path) | clone `<owner>/<repo>` → `.agents/.sources/<owner>-<repo>/`; link artifact out; `managed_clone: true`. |
-| `--link <path>` (no entry) | read `<path>/.git` remote to derive `owner/repo`; infer type + in-repo path from layout; proceed as row 1. |
-
-`--link` refuses if an absolute path is supplied. If the target symlink
-already exists as a real dir/file, refuse unless `--force`.
-
-### `pull`
-
-For each entry: if it has a `link` override (or a `link` lock record),
-**skip the fetcher entirely**. Verify the symlink exists and resolves; if the
-target is missing (checkout moved/deleted), emit a clear warning and leave the
-dangling link (do not silently re-fetch a remote snapshot — that would mask a
-broken dev setup). Non-linked entries: unchanged SPEC-003 path.
-
-### `update`
-
-Linked, `managed_clone: true`: `git -C .agents/.sources/<owner>-<repo> pull
---ff-only`; refresh `resolved_sha` in lock (informational). Linked,
-`managed_clone: false` (user checkout): **no-op** — the user drives their own
-git; we only refresh the informational `resolved_sha` from current HEAD.
-Non-linked: unchanged.
-
-### `index`
-
-`DiscoverArtifacts` must `filepath.EvalSymlinks` / stat-through the link so a
-linked skill's `SKILL.md` is read and enumerated in AGENTS.md exactly like a
-vendored one. (Today it walks real files; confirm symlinked dirs are
-followed.)
-
-### `source list`
-
-Linked entries render with a `link → file:../foo-skill` annotation and, for
-managed clones, the clone's short SHA. Snapshot entries unchanged.
-
-### `detach`
-
-Extend existing `detach` to handle links: replace the symlink with a real
-copy of the current target contents, remove the `link` override, and record a
-normal snapshot lock entry (content-hash the materialized files). This is the
-"freeze my linked dev copy into a vendored artifact" operation.
-
-## Security (SPEC-005 interaction)
-
-A linked source is a **local checkout the operator is actively developing** —
-running the quarantine scanner and hardened-extraction gate on every `pull`
-is noise, and there is no tarball to extract. Therefore:
-
-- **Linking a local `--link <path>` is trusted by default** — no quarantine,
-  no scan on link or on subsequent `pull`.
-- **Managed-clone linking (`--link <entry>`) fetches remote code**, so the
-  **initial clone is scanned once** through the SPEC-005 scanner (same
-  heuristics as tarball pull). Findings gate the link unless `--trust`.
-  Subsequent `git pull`s during `update` are **not** re-scanned (the operator
-  now owns the checkout) — but `sync-agents check`/scan can be run on demand.
-- Rationale: matches the [ClawHub supply-chain] posture — untrusted *remote
-  first contact* is scanned; an operator's own working tree is not policed.
-
-## Test plan (bats + Go)
-
-- Parse: `file:../x` ok; `file:/abs` rejected; `file:./x` ok; empty rejected.
-- `Override.Link` + `PinSHA` together → load error.
-- `add --link <path> <entry>`: symlink created relative; manifest+lock written
-  relative; re-`pull` is a no-op and does not clobber the link.
-- `add --link <entry>`: managed clone created + scanned; `managed_clone: true`.
-- Dangling target → `pull` warns, does not re-fetch.
-- `index`: linked skill appears in AGENTS.md.
-- `detach`: link → real copy, override removed, content_hash populated.
-- Portability: lock/symlink contain no absolute paths (grep gate in test).
-
-## Rollout
-
-Additive, backwards-compatible: no `link` override ⇒ identical to today.
-Ships in 1.x (per the standing no-2.0 decision). New `.agents/.sources/`
-dot-dir is invisible to sync/index (same convention as `.quarantine`).