brickhouse-tech · nmccready · Jul 10, 2026 · Jul 9, 2026 · Jul 9, 2026
diff --git a/README.md b/README.md
diff --git 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,43 +60,47 @@ 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
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.