diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9389755..5f7a5b1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -43,12 +43,6 @@ jobs:
 
   build-and-lint:
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        module:
-          - .
-          - memory/tools/knowledge-sync
     steps:
       - uses: actions/checkout@v4
 
@@ -58,22 +52,38 @@ jobs:
           cache: false
 
       - name: Test
-        working-directory: ${{ matrix.module }}
         run: go test ./...
 
       - name: Build
-        working-directory: ${{ matrix.module }}
         run: go build ./...
 
       - name: Vet
-        working-directory: ${{ matrix.module }}
         run: go vet ./...
 
       - name: Lint
         uses: golangci/golangci-lint-action@v7
         with:
           version: v2.12.2
-          working-directory: ${{ matrix.module }}
+
+  memory-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Test memory hooks and lib
+        run: python3 -m unittest discover -s memory/tests
+
+  release-script:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Test release script validation
+        run: sh scripts/release_test.sh
 
   npm-wrapper:
     runs-on: ubuntu-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7a92637..bcb83fb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,36 +1,82 @@
 name: Release
 
+# Publishing happens from a v* tag, but only after the tag has been verified
+# against main and a green ci.yml run, and after the protected `release`
+# environment approves. Configure that environment in repository settings with
+# required reviewers, and keep HOMEBREW_TAP_TOKEN scoped to it.
+
 on:
   push:
     tags:
       - "v*"
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
+  verify:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag, ancestry, and CI
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -eu
+          tag="${GITHUB_REF_NAME}"
+          if ! printf '%s' "$tag" | grep -Eq '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'; then
+            echo "::error::not a stable semver tag: $tag"
+            exit 1
+          fi
+          git fetch --no-tags --quiet origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_SHA is not on origin/main; releases are cut from main only"
+            exit 1
+          fi
+          successes=$(gh run list --workflow=ci.yml --commit "$GITHUB_SHA" --status completed --limit 20 \
+            --json headSha,conclusion \
+            --jq "[.[] | select(.headSha == \"$GITHUB_SHA\" and .conclusion == \"success\")] | length")
+          if [ "$successes" -lt 1 ]; then
+            echo "::error::no successful ci.yml run found for $GITHUB_SHA"
+            exit 1
+          fi
+          echo "verified $tag at $GITHUB_SHA (on main, ci.yml green)"
+
+      - name: Release script checks
+        run: sh scripts/release_test.sh
+
   goreleaser:
+    needs: verify
     runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
         with:
           go-version: "1.24"
 
-      - uses: goreleaser/goreleaser-action@v6
+      - uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
         with:
           distribution: goreleaser
-          version: "~> v2"
+          version: "v2.18.2"
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
 
   npm-publish:
-    needs: goreleaser
+    needs: [verify, goreleaser]
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -39,9 +85,9 @@ jobs:
       run:
         working-directory: npm
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org
diff --git a/AGENTS.md b/AGENTS.md
index a0fb1cc..8ce2580 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,7 +38,7 @@ New starter content requires an explicit product decision and an inventory test
 
 # Development
 
-- Go version and module layout are declared by `go.mod` and `go.work`.
+- Go version and module layout are declared by `go.mod`. The memory tools under `memory/tools/` are packages of that root module; `setup` scaffolds a standalone `go.mod` beside each copied tool so a user-owned config root can build them without the source checkout.
 - Install the development CLI with `go install ./cmd/dotagents`.
 - Use focused package tests while iterating; run `go test ./...` before submission.
 - Use Python 3's standard library for the dependency-free basic memory tier.
diff --git a/README.md b/README.md
index 7e1936c..c152f26 100644
--- a/README.md
+++ b/README.md
@@ -173,18 +173,24 @@ tailscale serve --bg --set-path /dotagents http://127.0.0.1:8765
 
 ## Releases
 
+Releases are cut from `main` after the release PR is reviewed and merged, and only with explicit approval:
+
 ```bash
-scripts/release.sh v0.7.0    # verify + tag; CI publishes binaries, brew tap, npm
+scripts/release.sh vX.Y.Z    # verify + tag; CI publishes binaries, brew tap, npm
 ```
 
+The script refuses to run unless the tree is clean, `HEAD` matches `origin/main`, the tag is strict `vMAJOR.MINOR.PATCH`, and every check passes. Pushing the tag starts `.github/workflows/release.yml`, which re-verifies the tag against `main` and a green `ci.yml` run, waits on the protected `release` environment, then publishes binaries, the Homebrew tap, and the npm wrapper.
+
 ## Documentation
 
+- [Overview & comparison](https://yourconscience.github.io/dotagents/) — landing page, sync matrix, positioning
 - [docs/setup.md](docs/setup.md) — first-run walkthrough, review screen, multi-machine setup
 - [docs/skills.md](docs/skills.md) — authoring skills, external pins and audits
 - [docs/roles.md](docs/roles.md) — role format, model tiers, per-harness overrides
 - [docs/memory.md](docs/memory.md) — memory tiers, rem workflow, vault layout
 - [docs/comparison.md](docs/comparison.md) — how dotagents differs from rulesync, ruler, openskills
 - [Troubleshooting](docs/troubleshooting.md)
+- [memory/README.md](memory/README.md) — memory layer layout, hooks, and tools
 
 Project-level generators (rulesync, ruler) win on tool breadth; dotagents is user-level — one private repo, nine targets deep, pinned externals, review-first memory. Full table in [docs/comparison.md](docs/comparison.md).
 
diff --git a/SPEC.md b/SPEC.md
deleted file mode 100644
index e58ca23..0000000
--- a/SPEC.md
+++ /dev/null
@@ -1,305 +0,0 @@
-# SPEC
-
-## Goal
-
-Add a local-first authoring surface for dotagents that works as:
-
-1. a responsive web UI on desktop and mobile;
-2. a Bubble Tea TUI in the terminal;
-3. the existing editable YAML file.
-
-All three are projections of the same canonical `dotagents.yaml` document. The web UI and TUI must never create a second configuration store or write native harness configuration directly. `dotagents sync` remains the only renderer from canonical config into harness-specific files.
-
-The web UI ships inside the existing `dotagents` binary and runs as a standalone local process. It must not require HarnessKit, Node, or a separate daemon at runtime.
-
-## Non-goals
-
-- Moving skill bodies, role Markdown, plugin source, memory, or lock data into `dotagents.yaml`. These remain canonical repo files; YAML owns configuration and references to those files.
-- Editing arbitrary files outside the resolved dotagents config root.
-- Installing a LaunchAgent, daemon, Tailscale Serve rule, or public tunnel automatically.
-- Managing active agent sessions, terminals, prompts, or usage dashboards.
-- Writing directly to `~/.claude`, `~/.codex`, `~/.omp`, `~/.hermes`, or other materialized harness directories from the UI.
-
-## Commands
-
-The canonical configuration experience is reached two ways: `dotagents config` for the terminal TUI (plus `validate`/`print`) and `dotagents view` for the browser web UI. Both are projections of the same document. `view` takes over the `dotagents view` name from the former HarnessKit launcher, which is renamed to `dotagents inspect` (a separate read-mostly cross-harness inspector, not an authoring surface).
-
-```text
-dotagents config                         # interactive TUI
-dotagents view                           # web UI, loopback only, opens browser
-dotagents view --no-open
-dotagents view --addr 127.0.0.1:8765
-dotagents config validate                # validate canonical YAML without writing
-dotagents config print                   # print resolved paths and effective config
-```
-
-If no canonical config exists, `dotagents config` and `dotagents view` direct the user to `dotagents setup`; they do not implement a second first-run flow.
-
-## Canonical configuration model
-
-### Files and layers
-
-- Resolution remains: `--config` → `$DOTAGENTS_HOME/dotagents.yaml` → `~/.agents/dotagents.yaml`.
-- `dotagents.yaml` is the canonical shared layer.
-- `dotagents.local.yaml` is the optional machine-local canonical overlay.
-- The UI exposes three explicit modes: **shared**, **local**, and **effective**.
-- Shared and local are editable. Effective is a read-only merged projection. The UI never flattens the overlay back into the shared file.
-- `dotagents.lock` stays sync-owned and read-only in this feature.
-
-### Shared config service
-
-Add one concrete `configDocument` service used directly by CLI, TUI, and HTTP handlers. Do not add an interface until a second implementation exists.
-
-Responsibilities:
-
-1. Resolve the canonical paths with the existing resolver and reject linked worktree roots with `refuseWorktreeRoot`.
-2. Read YAML into a `yaml.Node` document and decode the same document into the existing typed `config` struct.
-3. Apply the local overlay through the existing merge semantics, extended so a non-nil local `ui` block replaces the shared `ui` block wholesale, matching the overlay's current whole-entry behavior.
-4. Validate editable bytes with `validateConfig(..., expand=false)` so portable `~` paths remain unchanged. Use `expand=true` only on a separate typed copy for effective views and sync planning.
-5. Address list entries by stable keys:
-   - agents: normalized `name`;
-   - MCP servers: `name`;
-   - hooks: `name`;
-   - external skills: repository identity derived from `url`.
-6. Mutate only the selected YAML nodes. Structured edits must preserve unknown fields, comments, ordering, quoting, and untouched subtrees.
-7. Allow raw YAML replacement only after parsing and validation succeeds.
-8. Compute a SHA-256 revision from the exact bytes read. Reject stale writes instead of overwriting a file changed by another process.
-9. Write atomically in the same directory: temporary file, preserved file mode, flush/close, rename. A failed validation or write leaves the original bytes unchanged.
-10. Return the exact before/after unified diff for every proposed save.
-
-Do not use `yaml.Marshal(config)` for interactive edits: the current setup/MCP writers reserialize the whole struct and can drop comments or unknown future fields. The config UI needs node-level mutation so it remains forward-compatible.
-
-Before `ui` ships, add typed `UI`/`Links` fields to `config`, extend `mergeConfig`, and route every canonical whole-document writer, including `writeSetupConfig` and `writeEditableMCPConfig`, through `configDocument`. Otherwise an existing `setup` or `mcp` command could silently remove `ui`, comments, or unknown fields.
-
-### Editable fields
-
-The structured editor covers every field currently represented by `config`:
-
-- version;
-- agents: name, enabled, detect command, skill root, agent root, role model;
-- external skills: URL, branch, skill directory/directories, selected skills, materialize, MCP enablement and target agents;
-- MCP servers: name, enabled, command, arguments, environment, and target agents;
-- hooks: name, enabled, event, command, timeout, target agents;
-- context note token threshold;
-- UI navigation links: name and absolute HTTPS URL or origin-relative path.
-
-### Linked surfaces
-
-Add an optional UI-only section to the canonical schema:
-
-```yaml
-ui:
-  links:
-    - name: Usage
-      url: /usage
-```
-
-- Links are navigation metadata, not a sixth synced harness surface.
-- `url` accepts an absolute `https://` URL or an origin-relative path beginning with `/`.
-- The personal usage dashboard remains an external application. A machine-local overlay may link to its HTTPS URL or same-origin `/usage` route without adding a usage page to dotagents.
-- The web UI renders configured links as read-only top-level navigation. Link values remain YAML-authored and are never proxied or embedded.
-- TUI shows the same links in its UI section and can copy/open the selected URL where the platform supports it.
-
-Raw YAML editing remains available in the TUI and through the canonical file. The web UI deliberately exposes only browser-native selection controls for finite choices such as enablement; unknown fields remain untouched.
-
-## Mutation flow
-
-Every write follows the same review-first state machine:
-
-```text
-Select option → Validate → Preview YAML diff → Save canonical YAML
-                                            ↓ optional, separate action
-                                     Preview sync plan → Confirm → Sync
-```
-
-- Saving YAML does not implicitly run `sync`.
-- Sync preview reuses the existing inspection/report pipeline.
-- Sync apply requires the preview digest and current config revision. If either changed, preview again.
-- Destructive removals and role overwrites retain the existing per-harness confirmation semantics.
-- API errors use stable codes (`invalid_yaml`, `invalid_config`, `stale_revision`, `sync_plan_changed`) plus actionable text.
-
-## Web API
-
-Minimum JSON API:
-
-```text
-GET  /api/state                 paths, active layer, typed config, raw YAML, revision
-POST /api/config/validate       candidate raw YAML or structured patch; returns errors + diff
-PUT  /api/config/raw            expected revision + complete YAML; validates and writes
-PATCH /api/config               expected revision + keyed operations; validates and writes
-POST /api/sync/preview          returns per-harness plan + digest
-POST /api/sync/apply            expected revision + plan digest + confirmed destructive items
-GET  /api/status                current per-harness sync state
-```
-
-No generic filesystem, shell, command, or path endpoint. Responses must not expose environment values marked as secrets; environment keys may be displayed, values are masked by default and only sent when editing the selected canonical YAML field.
-
-## Web security and mobile access
-
-- Bind only to loopback. Reject wildcard and non-loopback addresses.
-- Generate a random startup token. Bootstrap it into an `HttpOnly`, `SameSite=Strict` session cookie and remove the token from the visible URL. `dotagents view --secure-cookie` additionally marks it `Secure` and is required when the browser reaches the loopback server through Tailscale HTTPS; plain local HTTP omits that flag.
-- Require the session for every API request, validate `Origin`, and require a CSRF header for mutations.
-- Send `Cache-Control: no-store`, a restrictive CSP, `X-Content-Type-Options: nosniff`, and `frame-ancestors 'none'`.
-- Keep configuration and secrets in memory only for the request lifecycle; never log request bodies or tokens.
-- Tailscale access is an explicit operator step, for example:
-
-```bash
-dotagents view --no-open --secure-cookie --addr 127.0.0.1:8765
-tailscale serve --bg --set-path /dotagents http://127.0.0.1:8765
-```
-
-The Tailscale syntax above was verified against the installed client on 2026-09-12. The application does not install or persist this route itself.
-
-## Web UX
-
-### Information architecture
-
-Desktop uses a compact settings ledger rather than a card dashboard:
-
-```text
-┌ Sources ──────┬ Configuration ───────────────────┬ Change rail ─────┐
-│ Shared        │ Agents / MCP / Hooks             │ validation       │
-│ Local         │ selection controls + metadata    │ diff + save      │
-│ Effective     │ read-only merged state           │ sync preview     │
-└───────────────┴──────────────────────────────────┴───────────────────┘
-```
-
-Mobile collapses the same controls into one vertical page with horizontally scrollable source tabs. A sticky bottom bar contains only context-valid actions: **Validate**, **Review**, and **Save**. **Preview sync** and **Sync** remain separate below the change rail.
-
-### Visual direction
-
-Treat the product as an instrument panel for configuration provenance, not a generic SaaS dashboard.
-
-- Memorable element: the **change rail**, which shows the canonical YAML diff for selected settings.
-- Layout: dense left-aligned ledger rows, clear nesting, no grid of rounded cards.
-- Palette: Catppuccin Mocha base `#1E1E2E`, surface `#181825`, accent `#B4BEFE`, with accessible semantic colors.
-- Type: native UI sans for controls; native monospace only for paths, revisions, and diffs. No network fonts.
-- Motion: only state transitions for opening an item and revealing validation/diff results; respect reduced motion.
-- Accessibility: semantic controls, visible focus, keyboard navigation, 44px mobile targets, safe-area padding, WCAG AA contrast, and no horizontal page overflow at 320px.
-
-The distinguishing choice is provenance visibility: every value says whether it comes from shared YAML, local overlay, a default, or the effective merge. Remove decoration that does not communicate that state.
-
-### Frontend delivery
-
-Use separate `index.html`, CSS, and JavaScript modules embedded with `go:embed`. Start with browser-native HTML controls and ES modules; no frontend framework or build-time Node dependency. Add a framework or editor package only after measured complexity proves native controls insufficient.
-
-## TUI UX
-
-Reuse Bubble Tea and Lip Gloss already in the module. The TUI and web UI share the config service and mutation state machine, not rendering code.
-
-```text
-shared | local | effective
-agents  mcp  hooks  external skills  advanced  yaml
-
-> claude-code   enabled   ~/.claude/skills
-  codex         enabled   ~/.codex/skills
-
-[e] edit  [/] search  [y] yaml  [v] validate  [r] review  [s] save  [q] quit
-```
-
-- Wide terminals show section list, detail form, and change rail.
-- Narrow terminals show one pane at a time.
-- The YAML tab is a real editable text area, not a shell-out to `$EDITOR` in the first version.
-- Save always opens the same validation + diff confirmation view used by structured edits.
-- External file changes surface as a stale-revision screen with **reload** or **copy unsaved YAML**; never overwrite.
-
-## Implementation plan
-
-### Slice 1: canonical document editing
-
-- Introduce `config_document.go` with YAML node loading, typed decoding, stable-key lookup, validation, revisions, diff generation, and atomic write.
-- Add typed `UI`/`Links` fields and explicit local-overlay semantics, then route every canonical whole-document writer, including `writeSetupConfig` and `writeEditableMCPConfig`, through `configDocument` before linked surfaces ship. Existing commands must not strip `ui`, comments, or unknown fields.
-- Add `dotagents config validate` and `dotagents config print` as non-interactive proof of the shared service.
-- Focused tests: comment/unknown-field preservation, overlay isolation, invalid-write rollback, stale revision, and file-mode preservation.
-- Fresh canonical files use mode `0o644`; replacement preserves the existing file mode.
-
-### Slice 2: TUI authoring
-
-- Add `dotagents config` using the existing Bubble Tea dependency.
-- Implement section navigation, complete field editing, raw YAML, validation, diff review, and save.
-- Reuse existing setup review styles where useful, but keep setup import review and config editing as separate models.
-- Exercise it against a temporary config root in a real PTY; tests never touch live harness configuration.
-
-### Slice 3: web server and desktop UI
-
-- Add `dotagents view` (the web UI) with loopback validation, token bootstrap, security headers, revision-aware APIs, and embedded separate assets.
-- Implement selection-only structured controls, diff/save, status, and sync preview. Raw YAML stays out of the web UI.
-- Keep sync apply behind a separate explicit confirmation screen.
-- Exercise the actual page in a browser against a temporary config root: select setting → diff → save → reload.
-
-### Slice 4: mobile and Tailscale proof
-
-- Verify the 320px and current iPhone viewport flows with the real browser surface: navigation, YAML editing, validation errors, diff review, stale-write recovery, and sync confirmation.
-- Run the server on loopback and expose it through a temporary Tailscale Serve path; verify HTTPS access from a tailnet client without changing existing routes.
-- Document the operator-owned Tailscale command only after the live proof. Do not install persistent automation.
-
-### Slice 5: safe sync completion and documentation
-
-- Complete preview-digest guarded sync apply in web and TUI.
-- Update README, CLI help, `skills/dotagents/SKILL.md`, setup docs, and release-site copy together.
-- Document `dotagents config` (TUI) and `dotagents view` (web UI) as the two projections of canonical authoring; the former HarnessKit launcher is renamed to `dotagents inspect`.
-- Remove throwaway smoke scripts and update this spec with Outcome / Deviations.
-
-## Acceptance tests
-
-1. A selection change in web updates the selected YAML node, survives reload, and appears immediately in TUI and raw YAML.
-2. A TUI edit appears in web after reload and changes no native harness file until explicit sync.
-3. The web UI contains no free-text editing widget; finite YAML choices use native checkboxes, toggles, or selects.
-4. Structured editing preserves comments, unknown keys, ordering, quoting, and unrelated bytes where possible.
-5. Editing `dotagents.local.yaml` changes only the local layer; the effective view reflects the merge and shared YAML remains byte-identical.
-6. Invalid YAML or invalid typed config cannot replace the canonical file.
-7. Concurrent external modification produces `stale_revision`; neither web nor TUI overwrites it.
-8. Save shows the exact YAML diff. Sync shows a separate per-harness plan and rejects a changed digest.
-9. Web server rejects non-loopback binds, unauthenticated API calls, invalid origins, CSRF-less mutations, and arbitrary path requests.
-10. Desktop and 320px mobile browser smoke complete select → validate → review → save without horizontal page overflow.
-11. Temporary Tailscale HTTPS access works while the server remains loopback-bound; removing the temporary route removes remote access.
-12. Focused tests and `go test ./...` pass without mutating live harness configuration.
-13. A machine-local `ui.links` entry renders as external top-level navigation on desktop and mobile; dotagents does not implement or proxy the linked usage page.
-
-## Risks / open questions
-
-- `yaml.v3` preserves node metadata but can still normalize formatting around modified nodes. The Slice 1 preservation tests define the acceptable boundary before UI work starts.
-- Environment values may contain secrets. The UI needs masking and log redaction; deciding whether to reveal existing values at all should be made during Slice 1 threat modeling.
-- `dotagents.local.yaml` replacement semantics are whole-entry, not field-level. The UI presents only safe finite choices; changing overlay semantics is out of scope.
-- Mobile uses native controls and a single vertical page, avoiding a code editor dependency and iOS text-editing problems.
-- Existing experimental dashboard work from May 2026 was a read-only catalog and session launcher on an obsolete repo layout. Reuse its proven loopback guardrails and separate-asset lesson, not its API or information architecture.
-
-## Codebase notes
-
-- Existing typed schema: `cmd/dotagents/main.go`, `mcp.go`, and `hooks.go`.
-- Existing resolution, overlay, validation, and worktree safety: `cmd/dotagents/config.go`.
-- Existing TUI foundation: `cmd/dotagents/review.go` and `review_apply.go`.
-- Config web UI launcher: `cmd/dotagents/view.go` (serves the loopback web UI in `config_web.go`).
-- Existing whole-document writers: `writeSetupConfig` and `writeEditableMCPConfig`; these are insufficient for comment/unknown-field-preserving interactive edits.
-
-## Outcome / Deviations
-
-Implemented in the current checkout:
-
-- `configDocument` now owns YAML node loading, typed validation, stable-key
-  mutations, SHA-256 revisions, atomic mode-preserving writes, and unified
-  diffs. Shared and local overlays remain isolated; a non-nil local `ui`
-  block replaces shared UI links.
-- Setup and MCP canonical whole-document writes route through the document
-  service, preserving unknown fields and comments instead of flattening the
-  typed struct.
-- `dotagents config`, `config validate`, and `config print` are wired. The
-  Bubble Tea editor has shared/local/effective tabs, raw YAML editing,
-  validation, diff review, save, and stale-revision protection.
-- `dotagents view` embeds separate HTML/CSS/ES-module assets and exposes the
-  revision-aware state, validation, raw/structured mutation, sync preview,
-  guarded sync apply, and status APIs. Loopback binding, startup-token
-  bootstrap, strict session cookies, origin/CSRF checks, security headers,
-  secret masking, and `--secure-cookie` are implemented.
-- Public help, README, skill documentation, setup documentation, and release
-  site copy describe canonical authoring through `dotagents config` (TUI) and `dotagents view` (web UI).
-
-Known deviations:
-
-- The TUI uses a native minimal textarea rather than a full structured form;
-  every schema field remains editable through its YAML tab. The web UI exposes
-  only finite enablement choices and renders paths, commands, events, and links
-  as read-only context.
-- Browser and temporary Tailscale HTTPS proof require a desktop browser and
-  tailnet route outside this checkout. Focused HTTP/API and asset checks are
-  included; no persistent route or automation is installed.
diff --git a/cmd/dotagents/agents.go b/cmd/dotagents/agents.go
deleted file mode 100644
index 357642e..0000000
--- a/cmd/dotagents/agents.go
+++ /dev/null
@@ -1,720 +0,0 @@
-package main
-
-import (
-	"bytes"
-	"errors"
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"sort"
-	"strconv"
-	"strings"
-
-	"gopkg.in/yaml.v3"
-)
-
-const (
-	generatedAgentMarker    = "Generated by dotagents"
-	readmeSkillsBeginMarker = "<!-- BEGIN GENERATED SKILLS -->"
-	readmeSkillsEndMarker   = "<!-- END GENERATED SKILLS -->"
-)
-
-// agentRoleMarkdownExt is the editable starter role source format under
-// agents/<name>.md. The YAML frontmatter holds metadata; the Markdown body is
-// the role prompt.
-const agentRoleMarkdownExt = ".md"
-
-type agentRole struct {
-	Name         string              `yaml:"name"`
-	Description  string              `yaml:"description"`
-	Model        string              `yaml:"model"`
-	Effort       string              `yaml:"effort"`
-	Tools        []string            `yaml:"tools"`
-	Color        string              `yaml:"color"`
-	Instructions string              `yaml:"-"`
-	Source       string              `yaml:"-"`
-	Claude       claudeRoleOptions   `yaml:"claude"`
-	Codex        codexRoleOptions    `yaml:"codex"`
-	OMP          ompRoleOptions      `yaml:"omp"`
-	Pi           piRoleOptions       `yaml:"pi"`
-	Droid        droidRoleOptions    `yaml:"droid"`
-	Opencode     opencodeRoleOptions `yaml:"opencode"`
-	Qwen         qwenRoleOptions     `yaml:"qwen"`
-}
-
-func (role *agentRole) UnmarshalYAML(value *yaml.Node) error {
-	if value.Kind != yaml.MappingNode {
-		return fmt.Errorf("agent role must be a mapping")
-	}
-	for i := 0; i+1 < len(value.Content); i += 2 {
-		key := value.Content[i].Value
-		node := value.Content[i+1]
-		switch key {
-		case "name":
-			if err := node.Decode(&role.Name); err != nil {
-				return err
-			}
-		case "description":
-			if err := node.Decode(&role.Description); err != nil {
-				return err
-			}
-		case "model":
-			if err := node.Decode(&role.Model); err != nil {
-				return err
-			}
-		case "effort":
-			if err := node.Decode(&role.Effort); err != nil {
-				return err
-			}
-		case "color":
-			if err := node.Decode(&role.Color); err != nil {
-				return err
-			}
-		case "claude":
-			if err := node.Decode(&role.Claude); err != nil {
-				return err
-			}
-		case "codex":
-			if err := node.Decode(&role.Codex); err != nil {
-				return err
-			}
-		case "omp":
-			if err := node.Decode(&role.OMP); err != nil {
-				return err
-			}
-		case "pi":
-			if err := node.Decode(&role.Pi); err != nil {
-				return err
-			}
-		case "droid":
-			if err := node.Decode(&role.Droid); err != nil {
-				return err
-			}
-		case "opencode":
-			if err := node.Decode(&role.Opencode); err != nil {
-				return err
-			}
-		case "qwen":
-			if err := node.Decode(&role.Qwen); err != nil {
-				return err
-			}
-		case "tools":
-			tools, err := decodeRoleTools(node)
-			if err != nil {
-				return err
-			}
-			role.Tools = tools
-		}
-	}
-	return nil
-}
-
-func decodeRoleTools(node *yaml.Node) ([]string, error) {
-	switch node.Kind {
-	case yaml.SequenceNode:
-		var tools []string
-		if err := node.Decode(&tools); err != nil {
-			return nil, err
-		}
-		return tools, nil
-	case yaml.ScalarNode:
-		var tools []string
-		for _, part := range strings.Split(node.Value, ",") {
-			if tool := strings.TrimSpace(part); tool != "" {
-				tools = append(tools, tool)
-			}
-		}
-		return tools, nil
-	default:
-		return nil, fmt.Errorf("tools must be a YAML sequence or comma-separated string")
-	}
-}
-
-type claudeRoleOptions struct {
-	Model string `yaml:"model"`
-}
-
-type codexRoleOptions struct {
-	Model                string `yaml:"model"`
-	ModelReasoningEffort string `yaml:"model_reasoning_effort"`
-}
-
-type ompRoleOptions struct {
-	Model         string `yaml:"model"`
-	ThinkingLevel string `yaml:"thinking-level"`
-}
-
-type piRoleOptions struct {
-	Model    string `yaml:"model"`
-	Thinking string `yaml:"thinking"`
-}
-
-type droidRoleOptions struct {
-	Model           string   `yaml:"model"`
-	ReasoningEffort string   `yaml:"reasoning_effort"`
-	Tools           []string `yaml:"tools"`
-}
-
-type opencodeRoleOptions struct {
-	Model       string `yaml:"model"`
-	Temperature string `yaml:"temperature"`
-	Mode        string `yaml:"mode"`
-}
-
-type qwenRoleOptions struct {
-	Model        string   `yaml:"model"`
-	ApprovalMode string   `yaml:"approval_mode"`
-	Tools        []string `yaml:"tools"`
-}
-
-var droidToolMapping = map[string][]string{
-	"bash":      {"Execute"},
-	"edit":      {"Edit"},
-	"glob":      {"Glob"},
-	"grep":      {"Grep"},
-	"read":      {"Read"},
-	"webfetch":  {"FetchUrl"},
-	"websearch": {"WebSearch"},
-	"write":     {"Create", "Edit"},
-}
-
-var droidFallbackTools = []string{"Read", "LS", "Grep", "Glob"}
-
-type renderedAgentRole struct {
-	Name    string
-	Source  string
-	Target  string
-	Content string
-}
-
-func expectedAgentRoles(repoRoot string, agent agentConfig) (map[string]renderedAgentRole, error) {
-	if agent.AgentRoot == "" {
-		return map[string]renderedAgentRole{}, nil
-	}
-
-	roles, err := loadAgentRoles(repoRoot)
-	if err != nil {
-		return nil, err
-	}
-
-	rendered := make(map[string]renderedAgentRole)
-	for _, role := range roles {
-		target, content, ok := renderAgentRole(role, agent)
-		if !ok {
-			continue
-		}
-		rendered[role.Name] = renderedAgentRole{
-			Name:    role.Name,
-			Source:  role.Source,
-			Target:  target,
-			Content: content,
-		}
-	}
-	return rendered, nil
-}
-
-func loadAgentRoles(repoRoot string) ([]agentRole, error) {
-	agentsDir := filepath.Join(repoRoot, "agents")
-	entries, err := os.ReadDir(agentsDir)
-	if errors.Is(err, fs.ErrNotExist) {
-		return nil, nil
-	}
-	if err != nil {
-		return nil, fmt.Errorf("read %s: %w", agentsDir, err)
-	}
-
-	var paths []string
-	for _, entry := range entries {
-		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || filepath.Ext(entry.Name()) != agentRoleMarkdownExt {
-			continue
-		}
-		paths = append(paths, filepath.Join(agentsDir, entry.Name()))
-	}
-	sort.Strings(paths)
-	return loadMarkdownAgentRoles(paths)
-}
-
-func loadMarkdownAgentRoles(paths []string) ([]agentRole, error) {
-	roles := make([]agentRole, 0, len(paths))
-	seen := make(map[string]struct{}, len(paths))
-	for _, path := range paths {
-		role, err := loadMarkdownAgentRole(path)
-		if err != nil {
-			return nil, err
-		}
-		if _, ok := seen[role.Name]; ok {
-			return nil, fmt.Errorf("agent role %s is duplicated", role.Name)
-		}
-		seen[role.Name] = struct{}{}
-		roles = append(roles, role)
-	}
-	sort.Slice(roles, func(i, j int) bool {
-		return roles[i].Name < roles[j].Name
-	})
-	return roles, nil
-}
-
-func loadMarkdownAgentRole(path string) (agentRole, error) {
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return agentRole{}, fmt.Errorf("read %s: %w", path, err)
-	}
-	role, err := parseAgentRoleMarkdown(path, data)
-	if err != nil {
-		return agentRole{}, err
-	}
-	if err := finalizeAgentRole(&role, path); err != nil {
-		return agentRole{}, err
-	}
-	return role, nil
-}
-
-func parseAgentRoleMarkdown(path string, data []byte) (agentRole, error) {
-	if !bytes.HasPrefix(data, []byte("---\n")) {
-		return agentRole{}, fmt.Errorf("%s: missing YAML frontmatter", path)
-	}
-	rest := data[len("---\n"):]
-	end := bytes.Index(rest, []byte("\n---"))
-	if end < 0 {
-		return agentRole{}, fmt.Errorf("%s: unterminated YAML frontmatter", path)
-	}
-	frontmatter := rest[:end]
-	body := rest[end+len("\n---"):]
-	if len(body) > 0 && body[0] == '\r' {
-		body = body[1:]
-	}
-	if len(body) > 0 && body[0] == '\n' {
-		body = body[1:]
-	}
-	var role agentRole
-	if err := yaml.Unmarshal(frontmatter, &role); err != nil {
-		return agentRole{}, fmt.Errorf("parse %s frontmatter: %w", path, err)
-	}
-	role.Instructions = strings.TrimSpace(string(body))
-	role.Source = path
-	return role, nil
-}
-
-func finalizeAgentRole(role *agentRole, source string) error {
-	role.Name = normalizeAgentName(role.Name)
-	role.Model = strings.TrimSpace(role.Model)
-	role.Effort = strings.TrimSpace(role.Effort)
-	role.Description = strings.TrimSpace(role.Description)
-	role.Instructions = strings.TrimSpace(role.Instructions)
-	if role.Name == "" {
-		return fmt.Errorf("%s is missing name", source)
-	}
-	if role.Description == "" {
-		return fmt.Errorf("%s: role %s is missing description", source, role.Name)
-	}
-	if role.Instructions == "" {
-		return fmt.Errorf("%s: role %s is missing instructions", source, role.Name)
-	}
-	return nil
-}
-
-func expectedREADMESkillsBlock(repoRoot string) (string, int, error) {
-	entries, err := os.ReadDir(filepath.Join(repoRoot, "skills"))
-	if errors.Is(err, fs.ErrNotExist) {
-		entries = nil
-	} else if err != nil {
-		return "", 0, fmt.Errorf("read skills/: %w", err)
-	}
-
-	names := make([]string, 0, len(entries))
-	for _, entry := range entries {
-		if !entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
-			continue
-		}
-		if !hasFile(filepath.Join(repoRoot, "skills", entry.Name(), "SKILL.md")) {
-			continue
-		}
-		// grill-me is a packaged command alias for grilling, not a standalone
-		// model-invocable skill in the public inventory.
-		if entry.Name() == "grill-me" {
-			continue
-		}
-		names = append(names, entry.Name())
-	}
-	sort.Strings(names)
-
-	var b strings.Builder
-	b.WriteString(readmeSkillsBeginMarker)
-	b.WriteString("\n")
-	fmt.Fprintf(&b, "%d skills ship with this repo:\n\n", len(names))
-	b.WriteString("`")
-	b.WriteString(strings.Join(names, "` `"))
-	b.WriteString("`\n")
-	b.WriteString(readmeSkillsEndMarker)
-	return b.String(), len(names), nil
-}
-
-func locateREADMESkillsBlock(content string) (int, int, error) {
-	if strings.Count(content, readmeSkillsBeginMarker) != 1 || strings.Count(content, readmeSkillsEndMarker) != 1 {
-		return 0, 0, errors.New("README skills markers must each appear exactly once")
-	}
-	start := strings.Index(content, readmeSkillsBeginMarker)
-	end := strings.Index(content, readmeSkillsEndMarker)
-	if end < start {
-		return 0, 0, errors.New("README skills end marker precedes begin marker")
-	}
-	return start, end + len(readmeSkillsEndMarker), nil
-}
-
-func renderREADMESkills(repoRoot string) error {
-	path := filepath.Join(repoRoot, "README.md")
-	data, err := os.ReadFile(path)
-	if errors.Is(err, fs.ErrNotExist) {
-		return nil
-	}
-	if err != nil {
-		return fmt.Errorf("read README.md: %w", err)
-	}
-	expected, count, err := expectedREADMESkillsBlock(repoRoot)
-	if err != nil {
-		return err
-	}
-	content := string(data)
-	if !strings.Contains(content, readmeSkillsBeginMarker) && !strings.Contains(content, readmeSkillsEndMarker) {
-		return nil
-	}
-	start, end, err := locateREADMESkillsBlock(content)
-	if err != nil {
-		return err
-	}
-	updated := content[:start] + expected + content[end:]
-	if updated == content {
-		fmt.Printf("rendered README skills: %d unchanged\n", count)
-		return nil
-	}
-	if err := os.WriteFile(path, []byte(updated), 0o644); err != nil {
-		return fmt.Errorf("write README.md: %w", err)
-	}
-	fmt.Printf("rendered README skills: %d written\n", count)
-	return nil
-}
-
-func runRender(opts runOptions) error {
-	repoRoot, _, _, _, err := loadContext(opts)
-	if err != nil {
-		return err
-	}
-	return renderCommittedArtifacts(repoRoot)
-}
-
-func renderCommittedArtifacts(repoRoot string) error {
-	return renderREADMESkills(repoRoot)
-}
-
-func renderAgentRole(role agentRole, agent agentConfig) (string, string, bool) {
-	h := harnessFor(agent.Name)
-	if h == nil || h.Roles == nil {
-		return "", "", false
-	}
-	if role.Model == "" && agent.RoleModel != "" {
-		role.Model = agent.RoleModel
-	}
-	target := filepath.Join(agent.AgentRoot, role.Name+h.Roles.Extension)
-	content := h.Roles.Render(role)
-	return target, content, true
-}
-
-func renderClaudeAgentRole(role agentRole) string {
-	model := strings.TrimSpace(role.Claude.Model)
-	if model == "" {
-		model = strings.TrimSpace(role.Model)
-	}
-
-	var b strings.Builder
-	b.WriteString("---\n")
-	writeYAMLScalar(&b, "name", role.Name)
-	writeYAMLScalar(&b, "description", role.Description)
-	writeYAMLScalar(&b, "model", model)
-	writeYAMLScalar(&b, "effort", role.Effort)
-	if len(role.Tools) > 0 {
-		b.WriteString("tools: ")
-		b.WriteString(strings.Join(role.Tools, ", "))
-		b.WriteString("\n")
-	}
-	writeYAMLScalar(&b, "color", role.Color)
-	b.WriteString("---\n\n")
-	b.WriteString("<!-- ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly. -->\n\n")
-	b.WriteString(role.Instructions)
-	b.WriteString("\n")
-	return b.String()
-}
-
-func renderCodexAgentRole(role agentRole) string {
-	model := strings.TrimSpace(role.Codex.Model)
-	if model == "" {
-		model = codexModelFor(role.Model)
-	}
-	effort := strings.TrimSpace(role.Codex.ModelReasoningEffort)
-	if effort == "" {
-		effort = strings.TrimSpace(role.Effort)
-	}
-
-	var b strings.Builder
-	b.WriteString("# ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly.\n")
-	writeTOMLString(&b, "name", role.Name)
-	writeTOMLString(&b, "description", role.Description)
-	writeTOMLString(&b, "model", model)
-	writeTOMLString(&b, "model_reasoning_effort", effort)
-	writeTOMLMultiline(&b, "developer_instructions", role.Instructions)
-	return b.String()
-}
-
-// codexModelFor resolves legacy canonical model aliases. Claude-family names
-// (opus/sonnet/haiku) are not valid Codex identifiers, so they render without a
-// model and Codex uses its own default; anything else passes through verbatim.
-func codexModelFor(model string) string {
-	switch strings.ToLower(strings.TrimSpace(model)) {
-	case "", "haiku", "sonnet", "opus":
-		return ""
-	default:
-		return strings.TrimSpace(model)
-	}
-}
-
-func renderDroidAgentRole(role agentRole) string {
-	model := strings.TrimSpace(role.Droid.Model)
-	if model == "" {
-		model = droidModelFor(role.Model)
-	}
-	effort := strings.TrimSpace(role.Droid.ReasoningEffort)
-	if effort == "" {
-		effort = strings.TrimSpace(role.Effort)
-	}
-	tools := role.Droid.Tools
-	if len(tools) == 0 {
-		tools = droidToolsFor(role.Tools)
-	}
-
-	var b strings.Builder
-	b.WriteString("---\n")
-	writeYAMLScalar(&b, "name", role.Name)
-	writeYAMLScalar(&b, "description", role.Description)
-	writeYAMLScalar(&b, "model", model)
-	writeYAMLScalar(&b, "reasoningEffort", effort)
-	if len(tools) > 0 {
-		b.WriteString("tools:\n")
-		for _, tool := range tools {
-			writeYAMLListItem(&b, tool)
-		}
-	}
-	b.WriteString("---\n\n")
-	b.WriteString("<!-- ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly. -->\n\n")
-	b.WriteString(role.Instructions)
-	b.WriteString("\n")
-	return b.String()
-}
-
-// canonicalModelTier reports whether the value is a legacy tier alias rather
-// than an exact model identifier. Harnesses without a tier concept must not
-// emit these values verbatim.
-func canonicalModelTier(model string) bool {
-	switch strings.ToLower(strings.TrimSpace(model)) {
-	case "haiku", "sonnet", "opus":
-		return true
-	}
-	return false
-}
-
-func agentRoleSourceLabel(role agentRole) string {
-	if role.Source == "" {
-		return "agents/" + role.Name + agentRoleMarkdownExt
-	}
-	return "agents/" + filepath.Base(role.Source)
-}
-
-func writeYAMLScalar(b *strings.Builder, key string, value string) {
-	value = strings.TrimSpace(value)
-	if value == "" {
-		return
-	}
-	b.WriteString(key)
-	b.WriteString(": ")
-	b.WriteString(strconv.Quote(value))
-	b.WriteString("\n")
-}
-
-func writeYAMLListItem(b *strings.Builder, value string) {
-	value = strings.TrimSpace(value)
-	if value == "" {
-		return
-	}
-	b.WriteString("  - ")
-	b.WriteString(strconv.Quote(value))
-	b.WriteString("\n")
-}
-
-func writeTOMLString(b *strings.Builder, key string, value string) {
-	value = strings.TrimSpace(value)
-	if value == "" {
-		return
-	}
-	b.WriteString(key)
-	b.WriteString(" = ")
-	b.WriteString(strconv.Quote(value))
-	b.WriteString("\n")
-}
-
-func writeTOMLMultiline(b *strings.Builder, key string, value string) {
-	b.WriteString(key)
-	b.WriteString(" = ")
-	b.WriteString(strconv.Quote(value))
-	b.WriteString("\n")
-}
-
-func droidModelFor(model string) string {
-	model = strings.TrimSpace(model)
-	switch strings.ToLower(model) {
-	case "haiku":
-		return "custom:gpt-5.5(low)"
-	case "sonnet":
-		return "custom:gpt-5.5(medium)"
-	case "opus":
-		return "custom:gpt-5.5(high)"
-	default:
-		if model == "" {
-			return "inherit"
-		}
-		return model
-	}
-}
-
-func droidToolsFor(tools []string) []string {
-	var out []string
-	seen := make(map[string]struct{})
-	for _, tool := range tools {
-		for _, mapped := range droidToolMapping[strings.ToLower(strings.TrimSpace(tool))] {
-			if _, ok := seen[mapped]; ok {
-				continue
-			}
-			seen[mapped] = struct{}{}
-			out = append(out, mapped)
-		}
-	}
-	if len(tools) > 0 && len(out) == 0 {
-		return append([]string(nil), droidFallbackTools...)
-	}
-	return out
-}
-
-func inspectAgentRoles(report *agentReport, repoRoot string, agent agentConfig) error {
-	expected, err := expectedAgentRoles(repoRoot, agent)
-	if err != nil {
-		return err
-	}
-	if len(expected) == 0 {
-		return nil
-	}
-
-	names := sortedAgentRoleNames(expected)
-	for _, name := range names {
-		rendered := expected[name]
-		data, err := os.ReadFile(rendered.Target)
-		if errors.Is(err, fs.ErrNotExist) {
-			report.MissingAgent = append(report.MissingAgent, name)
-			report.AddsAgent = append(report.AddsAgent, name)
-			continue
-		}
-		if err != nil {
-			return fmt.Errorf("read %s: %w", rendered.Target, err)
-		}
-
-		if string(data) == rendered.Content {
-			report.ManagedAgent = append(report.ManagedAgent, name)
-			continue
-		}
-		if isManagedAgentFile(rendered.Target, data, repoRoot) {
-			report.DriftedAgent = append(report.DriftedAgent, name)
-			report.UpdatesAgent = append(report.UpdatesAgent, name)
-			continue
-		}
-		report.Conflicts = append(report.Conflicts, fmt.Sprintf("agent %s exists but is not dotagents-managed", rendered.Target))
-	}
-	return nil
-}
-
-func isManagedAgentFile(path string, data []byte, repoRoot string) bool {
-	if strings.Contains(string(data), generatedAgentMarker) {
-		return true
-	}
-
-	info, err := os.Lstat(path)
-	if err != nil || info.Mode()&os.ModeSymlink == 0 {
-		return false
-	}
-	rawTarget, err := os.Readlink(path)
-	if err != nil {
-		return false
-	}
-	targetAbs := absoluteTarget(path, rawTarget)
-	repoAgentsRoot := filepath.Join(repoRoot, "agents")
-	return targetAbs == repoAgentsRoot || strings.HasPrefix(targetAbs, repoAgentsRoot+string(os.PathSeparator))
-}
-
-func applyAgentRoleSync(reports []agentReport, selected []agentConfig, repoRoot string) error {
-	agentIndex := make(map[string]agentConfig, len(selected))
-	for _, agent := range selected {
-		agentIndex[agent.Name] = agent
-	}
-	for _, report := range reports {
-		if !report.Detected {
-			continue
-		}
-		agent, ok := agentIndex[report.Name]
-		if !ok || agent.AgentRoot == "" {
-			continue
-		}
-		if len(report.Conflicts) > 0 {
-			return fmt.Errorf("%s has conflicts", report.Name)
-		}
-		expected, err := expectedAgentRoles(repoRoot, agent)
-		if err != nil {
-			return err
-		}
-		if len(report.AddsAgent)+len(report.UpdatesAgent) == 0 {
-			continue
-		}
-		if err := os.MkdirAll(agent.AgentRoot, 0o755); err != nil {
-			return fmt.Errorf("create %s: %w", agent.AgentRoot, err)
-		}
-		for _, name := range append(append([]string{}, report.AddsAgent...), report.UpdatesAgent...) {
-			rendered, ok := expected[name]
-			if !ok {
-				continue
-			}
-			if err := os.Remove(rendered.Target); err != nil && !errors.Is(err, fs.ErrNotExist) {
-				return fmt.Errorf("remove %s before rewrite: %w", rendered.Target, err)
-			}
-			if err := os.WriteFile(rendered.Target, []byte(rendered.Content), 0o644); err != nil {
-				return fmt.Errorf("write %s: %w", rendered.Target, err)
-			}
-		}
-	}
-	return nil
-}
-
-func sortedAgentRoleNames(roles map[string]renderedAgentRole) []string {
-	names := make([]string, 0, len(roles))
-	for name := range roles {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-	return names
-}
diff --git a/cmd/dotagents/agents_test.go b/cmd/dotagents/agents_test.go
deleted file mode 100644
index 63608d2..0000000
--- a/cmd/dotagents/agents_test.go
+++ /dev/null
@@ -1,436 +0,0 @@
-package main
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-func TestRenderClaudeAgentRoleQuotesFrontmatter(t *testing.T) {
-	role := agentRole{
-		Name:         "reviewer",
-		Description:  "Reviews code: safely",
-		Model:        "sonnet",
-		Effort:       "high",
-		Tools:        []string{"Read", "Grep"},
-		Color:        "purple",
-		Instructions: "Review the change.",
-	}
-
-	got := renderClaudeAgentRole(role)
-	for _, want := range []string{
-		`name: "reviewer"`,
-		`description: "Reviews code: safely"`,
-		`model: "sonnet"`,
-		`effort: "high"`,
-		`color: "purple"`,
-		generatedAgentMarker,
-		"Review the change.",
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("rendered Claude role missing %q:\n%s", want, got)
-		}
-	}
-}
-
-func TestRenderClaudeAgentRoleAllowsArbitraryOverride(t *testing.T) {
-	role := agentRole{
-		Name:         "builder",
-		Description:  "Builds features",
-		Model:        "opus",
-		Claude:       claudeRoleOptions{Model: "claude-custom-model"},
-		Instructions: "Implement the change.",
-	}
-
-	got := renderClaudeAgentRole(role)
-	if !strings.Contains(got, `model: "claude-custom-model"`) {
-		t.Fatalf("rendered Claude role did not use explicit model override:\n%s", got)
-	}
-	if strings.Contains(got, `model: "opus"`) {
-		t.Fatalf("rendered Claude role retained family default after override:\n%s", got)
-	}
-}
-
-func TestParseAgentRoleMarkdownPreservesHarnessModelOverrides(t *testing.T) {
-	role, err := parseAgentRoleMarkdown("agents/builder.md", []byte(`---
-name: builder
-description: Builds features
-model: opus
-claude:
-  model: claude-custom-model
-omp:
-  model: gpt-custom-model
----
-
-Implement the change.
-`))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if role.Claude.Model != "claude-custom-model" {
-		t.Fatalf("Claude override = %q", role.Claude.Model)
-	}
-	if role.OMP.Model != "gpt-custom-model" {
-		t.Fatalf("OMP override = %q", role.OMP.Model)
-	}
-}
-
-func TestRenderCodexAgentRoleEscapesControlCharacters(t *testing.T) {
-	role := agentRole{
-		Name:         "researcher",
-		Description:  `Find "facts"`,
-		Model:        "sonnet",
-		Effort:       "high",
-		Instructions: "Line one\nLine two\tTabbed\rReturn",
-		Codex: codexRoleOptions{
-			Model:                "test-model-mini",
-			ModelReasoningEffort: "medium",
-		},
-	}
-
-	got := renderCodexAgentRole(role)
-	for _, want := range []string{
-		`name = "researcher"`,
-		`model = "test-model-mini"`,
-		`model_reasoning_effort = "medium"`,
-		`developer_instructions = "Line one\nLine two\tTabbed\rReturn"`,
-		generatedAgentMarker,
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("rendered Codex role missing %q:\n%s", want, got)
-		}
-	}
-}
-
-func TestRenderOMPAgentRoleHonorsOverride(t *testing.T) {
-	role := agentRole{
-		Name:         "researcher",
-		Description:  "Find reliable evidence",
-		Model:        "opus",
-		Effort:       "high",
-		Instructions: "Compare the sources.",
-		OMP: ompRoleOptions{
-			Model:         "gpt-5.6-luna",
-			ThinkingLevel: "xhigh",
-		},
-	}
-
-	got := renderOMPAgentRole(role)
-	for _, want := range []string{
-		`name: "researcher"`,
-		"model:\n",
-		`- "gpt-5.6-luna"`,
-		`thinking-level: "xhigh"`,
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("rendered OMP role missing %q:\n%s", want, got)
-		}
-	}
-	if strings.Contains(got, `- "opus"`) || strings.Contains(got, "effort:") {
-		t.Fatalf("OMP role leaked Claude defaults into override:\n%s", got)
-	}
-}
-
-func TestRenderOMPAgentRoleFallsBackToCanonicalModel(t *testing.T) {
-	role := agentRole{
-		Name:         "reviewer",
-		Description:  "Reviews code",
-		Model:        "opus",
-		Effort:       "high",
-		Instructions: "Review carefully.",
-	}
-
-	got := renderOMPAgentRole(role)
-	if !strings.Contains(got, "model:\n") || !strings.Contains(got, `- "opus"`) {
-		t.Fatalf("OMP role did not fall back to canonical model:\n%s", got)
-	}
-	if strings.Contains(got, "thinking-level:") {
-		t.Fatalf("OMP role invented a thinking-level without an override:\n%s", got)
-	}
-}
-
-func TestRenderDroidAgentRoleMapsModelAndTools(t *testing.T) {
-	role := agentRole{
-		Name:         "builder",
-		Description:  "Builds features",
-		Model:        "sonnet",
-		Effort:       "high",
-		Tools:        []string{"Read", "Glob", "Grep", "Bash", "Write", "Edit", "WebFetch", "WebSearch"},
-		Instructions: "Implement the change.",
-	}
-
-	got := renderDroidAgentRole(role)
-	for _, want := range []string{
-		`name: "builder"`,
-		`description: "Builds features"`,
-		`model: "custom:gpt-5.5(medium)"`,
-		`reasoningEffort: "high"`,
-		`- "Read"`,
-		`- "Glob"`,
-		`- "Grep"`,
-		`- "Execute"`,
-		`- "Create"`,
-		`- "Edit"`,
-		`- "FetchUrl"`,
-		`- "WebSearch"`,
-		generatedAgentMarker,
-		"Implement the change.",
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("rendered Droid role missing %q:\n%s", want, got)
-		}
-	}
-}
-
-func TestRenderCodexAgentRoleOmitsMissingModel(t *testing.T) {
-	role := agentRole{
-		Name:         "builder",
-		Description:  "Builds features",
-		Instructions: "Implement the change.",
-	}
-
-	got := renderCodexAgentRole(role)
-	for _, absent := range []string{"model =", "model_reasoning_effort ="} {
-		if strings.Contains(got, absent) {
-			t.Fatalf("model-neutral codex role should omit %q:\n%s", absent, got)
-		}
-	}
-}
-func TestCodexModelForNeutralizesAliases(t *testing.T) {
-	tests := map[string]string{
-		"":           "",
-		"sonnet":     "",
-		"opus":       "",
-		"haiku":      "",
-		"gpt-custom": "gpt-custom",
-	}
-
-	for input, want := range tests {
-		if got := codexModelFor(input); got != want {
-			t.Fatalf("codexModelFor(%q) = %q, want %q", input, got, want)
-		}
-	}
-}
-
-func TestRenderAgentRolePrefillsConfiguredModel(t *testing.T) {
-	role := agentRole{Name: "builder", Description: "Builds features", Instructions: "Implement."}
-	path, content, ok := renderAgentRole(role, agentConfig{Name: agentClaudeCode, AgentRoot: t.TempDir(), RoleModel: "configured-model"})
-	if !ok {
-		t.Fatal("claude role was not rendered")
-	}
-	if !strings.Contains(content, `model: "configured-model"`) {
-		t.Fatalf("role missing configured role_model:\n%s", content)
-	}
-	if path == "" {
-		t.Fatal("empty target path")
-	}
-}
-
-func TestDroidModelFor(t *testing.T) {
-	tests := map[string]string{
-		"":           "inherit",
-		"sonnet":     "custom:gpt-5.5(medium)",
-		"opus":       "custom:gpt-5.5(high)",
-		"haiku":      "custom:gpt-5.5(low)",
-		"gpt-custom": "gpt-custom",
-	}
-
-	for input, want := range tests {
-		if got := droidModelFor(input); got != want {
-			t.Fatalf("droidModelFor(%q) = %q, want %q", input, got, want)
-		}
-	}
-}
-
-func TestDroidToolsForMapsWriteToCreateAndEdit(t *testing.T) {
-	got := droidToolsFor([]string{"Write"})
-	want := []string{"Create", "Edit"}
-	if len(got) != len(want) {
-		t.Fatalf("droidToolsFor(Write) = %#v, want %#v", got, want)
-	}
-	for i := range want {
-		if got[i] != want[i] {
-			t.Fatalf("droidToolsFor(Write) = %#v, want %#v", got, want)
-		}
-	}
-}
-
-func TestDroidToolsForFallsBackToReadOnlyWhenNoToolsMap(t *testing.T) {
-	got := droidToolsFor([]string{"NotebookEdit"})
-	want := []string{"Read", "LS", "Grep", "Glob"}
-	if len(got) != len(want) {
-		t.Fatalf("droidToolsFor(unmapped) = %#v, want %#v", got, want)
-	}
-	for i := range want {
-		if got[i] != want[i] {
-			t.Fatalf("droidToolsFor(unmapped) = %#v, want %#v", got, want)
-		}
-	}
-}
-
-func writeAgentsFixture(t *testing.T, repoRoot string, name string, data string) {
-	t.Helper()
-	agentsDir := filepath.Join(repoRoot, "agents")
-	if err := os.MkdirAll(agentsDir, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(agentsDir, name), []byte(data), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func TestLoadAgentRolesMarkdown(t *testing.T) {
-	repoRoot := t.TempDir()
-	writeAgentsFixture(t, repoRoot, "reviewer.md", `---
-name: reviewer
-description: Reviews changes
-model: sonnet
-effort: high
-tools: [Read, Grep]
-color: purple
-omp:
-  model: gpt-5.6-luna
-  thinking-level: xhigh
----
-
-Review the change.
-`)
-	writeAgentsFixture(t, repoRoot, "builder.md", `---
-name: builder
-description: Builds features
-model: sonnet
-tools: Read, Grep
----
-
-Implement the change.
-`)
-
-	roles, err := loadAgentRoles(repoRoot)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(roles) != 2 {
-		t.Fatalf("loaded %d roles, want 2", len(roles))
-	}
-	if roles[0].Name != "builder" || roles[1].Name != "reviewer" {
-		t.Fatalf("roles not sorted by name: %#v", roles)
-	}
-	if len(roles[0].Tools) != 2 || roles[0].Tools[0] != "Read" || roles[0].Tools[1] != "Grep" {
-		t.Fatalf("unexpected scalar tools: %#v", roles[0].Tools)
-	}
-	role := roles[1]
-	if role.Description != "Reviews changes" || role.Instructions != "Review the change." {
-		t.Fatalf("unexpected role: %#v", role)
-	}
-	if len(role.Tools) != 2 || role.Tools[0] != "Read" || role.Tools[1] != "Grep" {
-		t.Fatalf("unexpected tools: %#v", role.Tools)
-	}
-	if role.OMP.Model != "gpt-5.6-luna" || role.OMP.ThinkingLevel != "xhigh" {
-		t.Fatalf("unexpected OMP options: %#v", role.OMP)
-	}
-	if filepath.Base(role.Source) != "reviewer.md" {
-		t.Fatalf("unexpected source: %q", role.Source)
-	}
-}
-
-func TestCanonicalResearcherRendersCodexAtMax(t *testing.T) {
-	repoRoot, err := filepath.Abs(filepath.Join("..", ".."))
-	if err != nil {
-		t.Fatal(err)
-	}
-	role, err := loadMarkdownAgentRole(filepath.Join(repoRoot, "agents", "researcher.md"))
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	got := renderCodexAgentRole(role)
-	for _, want := range []string{
-		`name = "researcher"`,
-		`model = "gpt-5.6-luna"`,
-		`model_reasoning_effort = "max"`,
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("canonical researcher Codex role missing %q:\n%s", want, got)
-		}
-	}
-}
-
-func TestCanonicalResearcherRendersOMPAtMaximum(t *testing.T) {
-	repoRoot, err := filepath.Abs(filepath.Join("..", ".."))
-	if err != nil {
-		t.Fatal(err)
-	}
-	role, err := loadMarkdownAgentRole(filepath.Join(repoRoot, "agents", "researcher.md"))
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	got := renderOMPAgentRole(role)
-	for _, want := range []string{
-		`name: "researcher"`,
-		`- "gpt-5.6-luna"`,
-		`thinking-level: "max"`,
-	} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("canonical researcher OMP role missing %q:\n%s", want, got)
-		}
-	}
-}
-
-func TestLoadAgentRolesMarkdownRejectsMappingTools(t *testing.T) {
-	repoRoot := t.TempDir()
-	writeAgentsFixture(t, repoRoot, "invalid.md", `---
-name: invalid
-description: Invalid tools
-tools: {name: Read}
----
-
-Do work.
-`)
-	_, err := loadAgentRoles(repoRoot)
-	if err == nil || !strings.Contains(err.Error(), "tools must be a YAML sequence or comma-separated string") {
-		t.Fatalf("mapping tools error = %v", err)
-	}
-}
-
-func TestLoadAgentRolesMarkdownRejectsMissingFrontmatter(t *testing.T) {
-	repoRoot := t.TempDir()
-	writeAgentsFixture(t, repoRoot, "reviewer.md", "Review the change.\n")
-
-	if _, err := loadAgentRoles(repoRoot); err == nil || !strings.Contains(err.Error(), "missing YAML frontmatter") {
-		t.Fatalf("want missing frontmatter error, got %v", err)
-	}
-}
-
-func TestLoadAgentRolesMarkdownRejectsMissingInstructions(t *testing.T) {
-	repoRoot := t.TempDir()
-	writeAgentsFixture(t, repoRoot, "reviewer.md", `---
-name: reviewer
-description: Reviews changes
----
-`)
-
-	if _, err := loadAgentRoles(repoRoot); err == nil || !strings.Contains(err.Error(), "missing instructions") {
-		t.Fatalf("want missing instructions error, got %v", err)
-	}
-}
-
-func TestIsManagedAgentFile(t *testing.T) {
-	repoRoot := t.TempDir()
-	managed := filepath.Join(repoRoot, "managed.toml")
-	if err := os.WriteFile(managed, []byte("# "+generatedAgentMarker+"\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if !isManagedAgentFile(managed, []byte("# "+generatedAgentMarker+"\n"), repoRoot) {
-		t.Fatal("generated marker should be managed")
-	}
-
-	unmanaged := filepath.Join(repoRoot, "unmanaged.toml")
-	if err := os.WriteFile(unmanaged, []byte("name = \"local\"\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if isManagedAgentFile(unmanaged, []byte("name = \"local\"\n"), repoRoot) {
-		t.Fatal("unmarked real file should not be managed")
-	}
-}
diff --git a/cmd/dotagents/main.go b/cmd/dotagents/main.go
index 82175c4..eee1241 100644
--- a/cmd/dotagents/main.go
+++ b/cmd/dotagents/main.go
@@ -1,604 +1,15 @@
 package main
 
 import (
-	"errors"
-	"flag"
 	"fmt"
-	"io"
 	"os"
-	"os/exec"
-)
-
-type config struct {
-	Version        int                   `yaml:"version"`
-	Agents         []agentConfig         `yaml:"agents"`
-	MCPServers     []mcpServerConfig     `yaml:"mcp_servers"`
-	ExternalSkills []externalSkillSource `yaml:"external_skills"`
-	PublishTargets []publishTarget       `yaml:"publish_targets,omitempty"`
-	Hooks          []hookConfig          `yaml:"hooks,omitempty"`
-	UI             *uiConfig             `yaml:"ui,omitempty"`
-	// ContextNoteTokens is the estimated skill-listing token threshold above
-	// which `dotagents doctor` prints a soft context advisory note. Absent
-	// (nil) uses contextNoteTokensDefault; 0 (or negative) disables the note.
-	ContextNoteTokens *int `yaml:"context_note_tokens,omitempty"`
-}
-
-type uiConfig struct {
-	Links []uiLink `yaml:"links,omitempty"`
-}
-
-type uiLink struct {
-	Name string `yaml:"name"`
-	URL  string `yaml:"url"`
-}
-
-type externalSkillSource struct {
-	URL         string   `yaml:"url"`
-	SkillDir    string   `yaml:"skill_dir,omitempty"`
-	SkillDirs   []string `yaml:"skill_dirs,omitempty"`
-	Branch      string   `yaml:"branch"`
-	Skills      []string `yaml:"skills,omitempty"`
-	Materialize bool     `yaml:"materialize,omitempty"`
-	MCP         bool     `yaml:"mcp,omitempty"`
-	MCPAgents   []string `yaml:"mcp_agents,omitempty"`
-}
-
-type agentConfig struct {
-	Name      string    `yaml:"name"`
-	Enabled   bool      `yaml:"enabled"`
-	SkillRoot string    `yaml:"skill_root"`
-	AgentRoot string    `yaml:"agent_root,omitempty"`
-	Detect    string    `yaml:"detect,omitempty"`
-	RoleModel string    `yaml:"role_model,omitempty"`
-	Packages  *[]string `yaml:"packages,omitempty"`
-}
-
-// publishTarget declares a remote skill registry to push canonical skills to.
-// It is a publish verb, not a sync entity: unlike agentConfig it has no local
-// skill_root to reconcile and no detect key. Skills is an explicit allowlist —
-// only named skills are ever uploaded, so a private or experimental skill is
-// never shipped by accident.
-type publishTarget struct {
-	Name            string   `yaml:"name"`
-	Kind            string   `yaml:"kind"`                       // registry kind; only "openai-skills" for now
-	Enabled         bool     `yaml:"enabled"`                    // default off; opt in per target
-	Skills          []string `yaml:"skills"`                     // allowlist of local skill dir names to publish
-	VersionStrategy string   `yaml:"version_strategy,omitempty"` // new-version (default) | set-default
-	APIKeyEnv       string   `yaml:"api_key_env,omitempty"`      // env var holding the key; default OPENAI_API_KEY
-}
 
-const (
-	publishKindOpenAISkills   = "openai-skills"
-	publishDefaultAPIKeyEnv   = "OPENAI_API_KEY"
-	publishStrategyNewVersion = "new-version"
-	publishStrategySetDefault = "set-default"
+	"github.com/yourconscience/dotagents/internal/app"
 )
 
-type repoLinkReport struct {
-	Path           string
-	ExpectedTarget string
-	ActualTarget   string
-	State          string
-}
-
-type agentReport struct {
-	Name            string
-	SkillRoot       string
-	AgentRoot       string
-	ExpectedSkills  map[string]string
-	Detected        bool
-	RootPath        string
-	RootExpected    string
-	RootActual      string
-	RootState       string
-	Managed         []string
-	ManagedAgent    []string
-	ManagedMCP      []string
-	ManagedHook     []string
-	ManagedPackage  []string
-	Drifted         []string
-	DriftedAgent    []string
-	DriftedMCP      []string
-	DriftedHook     []string
-	DriftedPackage  []string
-	Missing         []string
-	MissingAgent    []string
-	MissingMCP      []string
-	MissingHook     []string
-	UnsupportedHook []string
-	Conflicts       []string
-	StaleManaged    []string
-	External        []string
-	Adds            []string
-	AddsAgent       []string
-	AddsMCP         []string
-	AddsHook        []string
-	Updates         []string
-	UpdatesAgent    []string
-	UpdatesMCP      []string
-	UpdatesHook     []string
-	UpdatesPackage  []string
-	Removes         []string
-	RemovesAgent    []string
-	RemovesPackage  []string
-	Synced          bool
-}
-
-func isDetected(agent agentConfig) bool {
-	if agent.Detect == "" {
-		return true
-	}
-	executable, err := exec.LookPath(agent.Detect)
-	if err != nil {
-		return false
-	}
-	if harness := harnessFor(agent.Name); harness != nil && harness.Detect != nil {
-		return harness.Detect(executable)
-	}
-	return true
-}
-
-type runOptions struct {
-	ConfigPath     string
-	ConfigOverride *config
-	Agents         string
-	Pull           bool
-	E2E            bool
-	SkipPackageAge bool
-	MemoryTier     string
-	JSONOutput     bool
-	DryRun         bool
-	AssumeYes      bool
-	Stdin          io.Reader
-	Stdout         io.Writer
-	// ConfirmRemovals makes sync preview per-harness removals and role
-	// overwrites and ask before applying them. Set by setup-driven syncs.
-	ConfirmRemovals bool
-	// Verbose expands `status` back to the full per-surface managed and
-	// external skill lists and native root paths instead of the concise view.
-	Verbose bool
-}
-
 func main() {
-	if err := run(os.Args[1:]); err != nil {
+	if err := app.Run(os.Args[1:]); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(1)
 	}
 }
-
-func run(args []string) error {
-	if len(args) == 0 {
-		printUsage()
-		return errors.New("missing subcommand")
-	}
-
-	switch args[0] {
-	case "setup":
-		return runSetupCommand(args[1:])
-	case "status":
-		return runStatusCommand(args[1:])
-	case "sync":
-		return runSyncCommand(args[1:])
-	case "doctor":
-		return runDoctorCommand(args[1:])
-	case "config":
-		return runConfigCommand(args[1:])
-	case "view":
-		return runView(args[1:])
-	case "inspect":
-		return runInspect(args[1:])
-	case "sessions":
-		return runSessions(args[1:])
-	case "skill":
-		return runSkillCommand(args[1:])
-	case "publish":
-		return runPublishCommand(args[1:])
-	case "mcp":
-		return runMCP(args[1:])
-	case "hook":
-		return runHookCommand(args[1:])
-	case "cron":
-		opts, err := parseCronFlags(args[1:])
-		if err != nil {
-			return err
-		}
-		return runCron(opts)
-	case "pull":
-		printRenameNotice("pull", "sync --pull")
-		opts, err := parseSubcommandFlags("pull", args[1:])
-		if err != nil {
-			return err
-		}
-		return runPull(opts)
-	case "deps":
-		return runDeprecatedDeps(args[1:])
-	case "memsearch":
-		return runDeprecatedMemsearch(args[1:])
-	case "skillify":
-		printRenameNotice("skillify", "skill new")
-		return runSkillCommand(append([]string{"new"}, args[1:]...))
-	case "render":
-		printRenameNotice("render", "sync")
-		opts, err := parseSubcommandFlags("render", args[1:])
-		if err != nil {
-			return err
-		}
-		return runRender(opts)
-	case "audit":
-		printRenameNotice("audit", "doctor")
-		opts, err := parseSubcommandFlags("audit", args[1:])
-		if err != nil {
-			return err
-		}
-		return runAudit(opts)
-	case "external":
-		if len(args) > 1 && args[1] == "list" {
-			printRenameNotice("external list", "status")
-		} else if len(args) > 1 && args[1] == "update" {
-			printRenameNotice("external update", "skill update")
-		} else {
-			printRenameNotice("external", "status or skill update")
-		}
-		return runExternal(args[1:])
-	case "promote":
-		printRenameNotice("promote", "skill promote")
-		return runSkillCommand(append([]string{"promote"}, args[1:]...))
-	case "dogfood":
-		printRenameNotice("dogfood", "doctor --e2e")
-		opts, err := parseSubcommandFlags("dogfood", args[1:])
-		if err != nil {
-			return err
-		}
-		return runDogfood(opts)
-	case "help":
-		if len(args) == 1 {
-			printUsage()
-			return nil
-		}
-		if len(args) == 2 && args[1] == "--all" {
-			printAllUsage()
-			return nil
-		}
-		return errors.New("usage: dotagents help [--all]")
-	case "-h", "--help":
-		if len(args) != 1 {
-			return errors.New("usage: dotagents help [--all]")
-		}
-		printUsage()
-		return nil
-	default:
-		printUsage()
-		return fmt.Errorf("unknown subcommand %q", args[0])
-	}
-}
-
-func runSetupCommand(args []string) error {
-	if len(args) > 0 {
-		switch args[0] {
-		case "memsearch":
-			return runMemsearch(append([]string{"setup"}, args[1:]...))
-		}
-	}
-	opts, err := parseSetupFlags(args)
-	if err != nil {
-		return err
-	}
-	return runSetup(opts)
-}
-
-func runStatusCommand(args []string) error {
-	if len(args) > 0 {
-		switch args[0] {
-		case "memsearch":
-			printRenameNotice("status memsearch", "status")
-			return runMemsearch(append([]string{"status"}, args[1:]...))
-		}
-	}
-	opts, err := parseStatusFlags(args)
-	if err != nil {
-		return err
-	}
-	return runStatus(opts)
-}
-
-func parseStatusFlags(args []string) (runOptions, error) {
-	fs := flag.NewFlagSet("status", flag.ContinueOnError)
-	fs.SetOutput(os.Stderr)
-
-	var opts runOptions
-	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
-	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
-	fs.BoolVar(&opts.SkipPackageAge, "skip-package-age", false, "Skip external package publish-age checks")
-	fs.BoolVar(&opts.Verbose, "verbose", false, "Show full managed/external skill lists and native root paths")
-	fs.BoolVar(&opts.Verbose, "v", false, "Show full managed/external skill lists and native root paths")
-
-	if err := fs.Parse(args); err != nil {
-		return runOptions{}, err
-	}
-	if fs.NArg() != 0 {
-		return runOptions{}, errors.New("status does not accept positional arguments")
-	}
-	return opts, nil
-}
-
-func runSyncCommand(args []string) error {
-	if len(args) > 0 {
-		switch args[0] {
-		case "pull":
-			printRenameNotice("sync pull", "sync --pull")
-			opts, err := parseSubcommandFlags("sync pull", args[1:])
-			if err != nil {
-				return err
-			}
-			return runPull(opts)
-		case "deps":
-			opts, err := parseDepsFlags("sync deps", args[1:])
-			if err != nil {
-				return err
-			}
-			return runDepsUpdate(opts)
-		case "render":
-			printRenameNotice("sync render", "sync")
-			opts, err := parseSubcommandFlags("sync render", args[1:])
-			if err != nil {
-				return err
-			}
-			return runRender(opts)
-		}
-	}
-	opts, err := parseSyncFlags(args)
-	if err != nil {
-		return err
-	}
-	if opts.Pull {
-		opts.Pull = false
-		return runPull(opts)
-	}
-	return runSync(opts)
-}
-
-func runDoctorCommand(args []string) error {
-	if len(args) > 0 {
-		switch args[0] {
-		case "audit":
-			opts, err := parseSubcommandFlags("doctor audit", args[1:])
-			if err != nil {
-				return err
-			}
-			return runAudit(opts)
-		case "deps":
-			opts, err := parseDepsFlags("doctor deps", args[1:])
-			if err != nil {
-				return err
-			}
-			return runDepsCheck(opts)
-		case "dogfood":
-			printRenameNotice("doctor dogfood", "doctor --e2e")
-			opts, err := parseSubcommandFlags("doctor dogfood", args[1:])
-			if err != nil {
-				return err
-			}
-			return runDogfood(opts)
-		}
-	}
-	opts, err := parseDoctorFlags(args)
-	if err != nil {
-		return err
-	}
-	if opts.E2E {
-		opts.E2E = false
-		return runDogfood(opts)
-	}
-	return runDoctor(opts)
-}
-
-func runSkillCommand(args []string) error {
-	if len(args) == 0 {
-		return errors.New("skill requires subcommand: new, list, info, update, promote")
-	}
-	switch args[0] {
-	case "new":
-		return runSkillify(args[1:])
-	case "update":
-		return runExternalUpdate(args[1:])
-	case "list":
-		return runSkillList(args[1:])
-	case "info":
-		return runSkillInfo(args[1:])
-	case "promote":
-		return runPromote(args[1:])
-	case "external":
-		if len(args) > 1 && args[1] == "list" {
-			printRenameNotice("skill external list", "status")
-		} else if len(args) > 1 && args[1] == "update" {
-			printRenameNotice("skill external update", "skill update")
-		} else {
-			printRenameNotice("skill external", "status or skill update")
-		}
-		return runExternal(args[1:])
-	default:
-		return fmt.Errorf("unknown skill subcommand %q", args[0])
-	}
-}
-
-func runDeprecatedDeps(args []string) error {
-	if len(args) > 0 {
-		switch args[0] {
-		case "check":
-			printRenameNotice("deps check", "doctor deps")
-			return runDoctorCommand(append([]string{"deps"}, args[1:]...))
-		case "update":
-			printRenameNotice("deps update", "sync deps")
-			return runSyncCommand(append([]string{"deps"}, args[1:]...))
-		}
-	}
-	printRenameNotice("deps", "doctor deps or sync deps")
-	return runDeps(args)
-}
-
-func runDeprecatedMemsearch(args []string) error {
-	if len(args) > 0 {
-		switch args[0] {
-		case "setup":
-			printRenameNotice("memsearch setup", "setup memsearch")
-			return runSetupCommand(append([]string{"memsearch"}, args[1:]...))
-		case "status":
-			printRenameNotice("memsearch status", "status memsearch")
-			return runStatusCommand(append([]string{"memsearch"}, args[1:]...))
-		}
-	}
-	printRenameNotice("memsearch", "setup memsearch or status memsearch")
-	return runMemsearch(args)
-}
-
-func printRenameNotice(oldCommand string, newCommand string) {
-	fmt.Fprintf(os.Stderr, "dotagents: %q was renamed to %q\n", oldCommand, newCommand)
-}
-
-func parseSubcommandFlags(name string, args []string) (runOptions, error) {
-	fs := flag.NewFlagSet(name, flag.ContinueOnError)
-	fs.SetOutput(os.Stderr)
-
-	var opts runOptions
-	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
-	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
-	fs.BoolVar(&opts.SkipPackageAge, "skip-package-age", false, "Skip external package publish-age checks")
-
-	if err := fs.Parse(args); err != nil {
-		return runOptions{}, err
-	}
-	if fs.NArg() != 0 {
-		return runOptions{}, fmt.Errorf("%s does not accept positional arguments", name)
-	}
-
-	return opts, nil
-}
-
-func parseSetupFlags(args []string) (runOptions, error) {
-	fs := flag.NewFlagSet("setup", flag.ContinueOnError)
-	fs.SetOutput(os.Stderr)
-	var opts runOptions
-	opts.MemoryTier = memoryTierBasic
-	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
-	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
-	fs.StringVar(&opts.MemoryTier, "memory", memoryTierBasic, "Memory tier: off, basic, or memsearch")
-	fs.BoolVar(&opts.JSONOutput, "json", false, "Emit detection result as JSON and exit")
-	fs.BoolVar(&opts.DryRun, "dry-run", false, "Show detected import candidates and exit without changes (overrides --yes)")
-	fs.BoolVar(&opts.AssumeYes, "yes", false, "Import all detected items without prompting")
-	if err := fs.Parse(args); err != nil {
-		return runOptions{}, err
-	}
-	if fs.NArg() != 0 {
-		return runOptions{}, errors.New("setup does not accept positional arguments")
-	}
-	return opts, nil
-}
-
-func parseSyncFlags(args []string) (runOptions, error) {
-	fs := flag.NewFlagSet("sync", flag.ContinueOnError)
-	fs.SetOutput(os.Stderr)
-	var opts runOptions
-	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
-	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
-	fs.BoolVar(&opts.Pull, "pull", false, "Pull the repo before syncing")
-	if err := fs.Parse(args); err != nil {
-		return runOptions{}, err
-	}
-	if fs.NArg() != 0 {
-		return runOptions{}, errors.New("sync does not accept positional arguments")
-	}
-	return opts, nil
-}
-
-func parseDoctorFlags(args []string) (runOptions, error) {
-	fs := flag.NewFlagSet("doctor", flag.ContinueOnError)
-	fs.SetOutput(os.Stderr)
-	var opts runOptions
-	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
-	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
-	fs.BoolVar(&opts.E2E, "e2e", false, "Run sync, status, and doctor end to end")
-	fs.BoolVar(&opts.SkipPackageAge, "skip-package-age", false, "Skip external package publish-age checks")
-	if err := fs.Parse(args); err != nil {
-		return runOptions{}, err
-	}
-	if fs.NArg() != 0 {
-		return runOptions{}, errors.New("doctor does not accept positional arguments")
-	}
-	return opts, nil
-}
-
-func parseCronFlags(args []string) (cronOptions, error) {
-	fs := flag.NewFlagSet("cron", flag.ContinueOnError)
-	fs.SetOutput(os.Stderr)
-
-	var opts cronOptions
-	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
-	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names")
-	fs.BoolVar(&opts.Remove, "remove", false, "Remove the cron entry instead of installing")
-	fs.BoolVar(&opts.Deps, "deps", false, "Install dependency maintenance cron instead of auto-pull")
-	fs.StringVar(&opts.Interval, "interval", cronIntervalDefault, "Pull interval: 5m, 15m, 30m, 1h, 6h, 12h, daily, weekly")
-
-	if err := fs.Parse(args); err != nil {
-		return cronOptions{}, err
-	}
-	return opts, nil
-}
-
-func printUsage() {
-	fmt.Println("dotagents - manage shared skills, MCP, and canonical config")
-	fmt.Println()
-	fmt.Println("Commands:")
-	fmt.Println("  setup    Set up this machine and sync configured harnesses")
-	fmt.Println("  status   Show harness, external lock, and memsearch state")
-	fmt.Println("  sync     Regenerate committed artifacts and reconcile harnesses")
-	fmt.Println("  doctor   Check pins, dependencies, and local health")
-	fmt.Println("  config   Author the canonical YAML in an interactive TUI")
-	fmt.Println("  view     Author the canonical YAML in a loopback web UI (browser)")
-	fmt.Println()
-	fmt.Println("Supported integrations:")
-	fmt.Println("  inspect  Launch HarnessKit for cross-harness configuration inspection")
-	fmt.Println("  sessions Launch AgentsView for session search, telemetry, and usage")
-	fmt.Println()
-	fmt.Println("Command groups:")
-	fmt.Println("  skill    Inspect, create, update, and promote skills")
-	fmt.Println("  publish  Push canonical skills to a remote skill registry")
-	fmt.Println("  mcp      Manage MCP servers")
-	fmt.Println("  hook     Review and remove native hook registrations")
-	fmt.Println()
-	fmt.Println("Run \"dotagents help --all\" for flags, maintenance commands, and compatibility aliases.")
-}
-
-func printAllUsage() {
-	printUsage()
-	fmt.Println()
-	fmt.Println("Canonical forms:")
-	fmt.Println("  dotagents setup [--memory off|basic|memsearch] [--agents ...] [--yes] [--dry-run] [--json]")
-	fmt.Println("  dotagents status [--verbose] [--agents ...]")
-	fmt.Println("  dotagents sync [--pull] [--agents ...]")
-	fmt.Println("  dotagents doctor [--e2e] [--agents ...]")
-	fmt.Println("  dotagents config [validate|print] [--config PATH]")
-	fmt.Println("  dotagents view [--addr 127.0.0.1:8765] [--no-open] [--secure-cookie] [--ssh-host user@host] [--token-file PATH]")
-	fmt.Println("  dotagents inspect [--no-open] [--ssh-host user@host] [hk serve flags: --port N, --host ADDR, --no-token]")
-	fmt.Println("  dotagents sessions [--no-open] [--ssh-host user@host] [agentsview serve flags: --port N, --host ADDR, --no-sync]")
-	fmt.Println("  dotagents skill new <name> [--description ...]")
-	fmt.Println("  dotagents skill list [--agents ...]")
-	fmt.Println("  dotagents skill info <name>")
-	fmt.Println("  dotagents skill update [name ...]")
-	fmt.Println("  dotagents skill promote <name-or-path> [--dry-run]")
-	fmt.Println("  dotagents publish [--target NAME] [--skills a,b] [--dry-run] [--json] [--yes]")
-	fmt.Println("  dotagents mcp <list|add|import|remove> [options]")
-	fmt.Println("  dotagents hook list [--agents ...] [query]")
-	fmt.Println("  dotagents hook remove [--dry-run] [--agents ...] <query>")
-	fmt.Println()
-	fmt.Println("Maintenance and compatibility aliases:")
-	fmt.Println("  dotagents cron [--interval 30m|--deps|--remove]")
-	fmt.Println("  dotagents deps <check|update> [options]")
-	fmt.Println("  dotagents memsearch <setup|status> [options]")
-	fmt.Println("  dotagents pull [options]")
-	fmt.Println("  dotagents render [options]")
-	fmt.Println("  dotagents audit [options]")
-	fmt.Println("  dotagents external <list|update> [name ...]")
-	fmt.Println("  dotagents skillify <name> [options]")
-	fmt.Println("  dotagents promote <name-or-path> [--dry-run]")
-	fmt.Println("  dotagents dogfood [options]")
-}
diff --git a/cmd/dotagents/omp_agent.go b/cmd/dotagents/omp_agent.go
deleted file mode 100644
index 5bc343c..0000000
--- a/cmd/dotagents/omp_agent.go
+++ /dev/null
@@ -1,63 +0,0 @@
-package main
-
-import "strings"
-
-var ompToolMapping = map[string]string{
-	"bash":      "bash",
-	"edit":      "edit",
-	"glob":      "glob",
-	"grep":      "grep",
-	"read":      "read",
-	"webfetch":  "read",
-	"websearch": "web_search",
-	"write":     "write",
-}
-
-func renderOMPAgentRole(role agentRole) string {
-	model := strings.TrimSpace(role.OMP.Model)
-	if model == "" {
-		model = strings.TrimSpace(role.Model)
-	}
-
-	var b strings.Builder
-	b.WriteString("---\n")
-	writeYAMLScalar(&b, "name", role.Name)
-	writeYAMLScalar(&b, "description", role.Description)
-	if model != "" {
-		b.WriteString("model:\n")
-		writeYAMLListItem(&b, model)
-	}
-	writeYAMLScalar(&b, "thinking-level", role.OMP.ThinkingLevel)
-	if tools := ompToolsFor(role.Tools); len(tools) > 0 {
-		b.WriteString("tools:\n")
-		for _, tool := range tools {
-			writeYAMLListItem(&b, tool)
-		}
-	}
-	b.WriteString("---\n\n")
-	b.WriteString("<!-- ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly. -->\n\n")
-	b.WriteString(role.Instructions)
-	b.WriteString("\n")
-	return b.String()
-}
-
-func ompToolsFor(tools []string) []string {
-	out := make([]string, 0, len(tools))
-	seen := make(map[string]struct{}, len(tools))
-	for _, tool := range tools {
-		mapped := ompToolMapping[strings.ToLower(strings.TrimSpace(tool))]
-		if mapped == "" {
-			continue
-		}
-		if _, ok := seen[mapped]; ok {
-			continue
-		}
-		seen[mapped] = struct{}{}
-		out = append(out, mapped)
-	}
-	return out
-}
diff --git a/cmd/dotagents/pi_agent.go b/cmd/dotagents/pi_agent.go
deleted file mode 100644
index 70bf3ad..0000000
--- a/cmd/dotagents/pi_agent.go
+++ /dev/null
@@ -1,66 +0,0 @@
-package main
-
-import "strings"
-
-var piToolMapping = map[string]string{
-	"bash":      "bash",
-	"edit":      "edit",
-	"glob":      "find",
-	"grep":      "grep",
-	"read":      "read",
-	"webfetch":  "fetch_content",
-	"websearch": "web_search",
-	"write":     "write",
-}
-
-// renderPiAgentRole emits the user-agent format consumed by pi-subagents.
-// Vanilla Pi itself ignores this directory when the extension is absent.
-func renderPiAgentRole(role agentRole) string {
-	model := strings.TrimSpace(role.Pi.Model)
-	if model == "" && !canonicalModelTier(role.Model) {
-		model = strings.TrimSpace(role.Model)
-	}
-	thinking := strings.TrimSpace(role.Pi.Thinking)
-	if thinking == "" {
-		thinking = strings.TrimSpace(role.Effort)
-	}
-
-	var b strings.Builder
-	b.WriteString("---\n")
-	writeYAMLScalar(&b, "name", role.Name)
-	writeYAMLScalar(&b, "description", role.Description)
-	writeYAMLScalar(&b, "model", model)
-	writeYAMLScalar(&b, "thinking", thinking)
-	if tools := piToolsFor(role.Tools); len(tools) > 0 {
-		b.WriteString("tools:\n")
-		for _, tool := range tools {
-			writeYAMLListItem(&b, tool)
-		}
-	}
-	b.WriteString("---\n\n")
-	b.WriteString("<!-- ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly. -->\n\n")
-	b.WriteString(role.Instructions)
-	b.WriteString("\n")
-	return b.String()
-}
-
-func piToolsFor(tools []string) []string {
-	out := make([]string, 0, len(tools))
-	seen := make(map[string]struct{}, len(tools))
-	for _, tool := range tools {
-		mapped := piToolMapping[strings.ToLower(strings.TrimSpace(tool))]
-		if mapped == "" {
-			continue
-		}
-		if _, ok := seen[mapped]; ok {
-			continue
-		}
-		seen[mapped] = struct{}{}
-		out = append(out, mapped)
-	}
-	return out
-}
diff --git a/docs/harnesskit-integration.md b/docs/harnesskit-integration.md
deleted file mode 100644
index 372ebc1..0000000
--- a/docs/harnesskit-integration.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# HarnessKit integration — design notes
-
-Status: L0 + L2 shipped. The launcher is `dotagents inspect` (it was `dotagents inspect` until v0.9.0, when `view` became the config web UI). L1 (opt-in install) and L3 (write-through) remain future work. Original design date 2026-09-06.
-
-## Finding
-
-[HarnessKit](https://github.com/RealZST/HarnessKit) (RealZST/HarnessKit, Rust, Apache-2.0, ~420★, active) is a web UI (also desktop/CLI) that inspects and manages agent extensions, configs, memory, and rules across 13 harnesses. Verified live against a full stack install on 2026-09-06: it detects and reads the **full dotagents stack** — Claude Code, Codex, **Oh My Pi** (`~/.omp/agent/`), **Hermes** (`~/.hermes/`), plus Gemini CLI, Copilot, OpenCode, Grok Build. This is exactly the coverage (Pi/OMP + Hermes) that CCO and ai-config-sync-manager lack.
-
-Consequence: dotagents does **not** need to build its own config viewer. HarnessKit already does the read/inspect/audit surface better than we would from scratch, and on every harness we care about.
-
-## Why integrate, and the one boundary rule
-
-HarnessKit and dotagents are complementary, not competing:
-
-- **HarnessKit** = read/inspect/audit dashboard + marketplace. Reads *materialized native dirs*. Its write model is **convergence** ("deploy this extension to every agent").
-- **dotagents** = sync engine + source of truth. Manages the 5 surfaces (skills, MCP, hooks, roles, plugins) via symlinks + `dotagents.lock` + intentional per-harness divergence.
-
-**Boundary invariant for this integration:** dotagents stays the only writer. HarnessKit is consumed read-mostly. We never route dotagents' managed surfaces *through* HarnessKit's convergence writer, and we never let HK's "deploy to all" become the mechanism that mutates a dotagents-owned symlink. Divergence is a feature here, not drift — HK's model treats it as drift, so its write path is off-limits for managed surfaces.
-
-## Integration levels
-
-### L0 — Recommend (docs only, zero coupling)
-
-Name HarnessKit in `README.md`, `docs/comparison.md`, and the `dotagents` skill as the inspection dashboard: "dotagents owns sync; use HarnessKit to see/audit the result across harnesses." No code. Ships today.
-
-### L1 — Optional dependency (`deps` / `setup`)
-
-Register HarnessKit as an **optional, opt-in** external tool:
-
-- `dotagents setup` offers (never forces) HK install after the first sync, gated behind a prompt.
-- `dotagents deps check` reports whether HK is present + version; `deps update` bumps it.
-- Honor the existing publish-age gate (`checkExternalPackageAge`, `package_age.go`) — HK is a fast-moving Rust binary; do not auto-pull a release younger than the configured window.
-
-Install method is still open (release binary vs `cargo install` vs `brew` tap) — do not hardcode one until verified.
-
-### L2 — Launch command (`dotagents inspect`)
-
-`dotagents inspect` starts `hk serve`, prints the tokenized URL on its own line, and (locally) opens it in the default browser; `--no-open` skips the launch and `--ssh-host user@host` prints an `ssh -L` tunnel command instead.
-
-- HarnessKit does its own harness discovery over the native homes (`~/.claude`, `~/.omp`, `~/.hermes`, …), so `inspect` does not load or pass the dotagents config root; a nonstandard `--config`/`$DOTAGENTS_HOME` only relocates dotagents' YAML, not the harness homes HK reads.
-- Spawns the HK local server (127.0.0.1, token in URL) and opens it locally (suppressible with `--no-open`). Mirrors the external-CLI launch path (`external_cli.go`, `cli_launch_test.go`).
-- Inspection intent, not enforced: `hk serve` has no read-only mode, so HarnessKit's own enable/disable/deploy actions can still write native dirs and bypass dotagents. The launch banner warns against using them on managed surfaces; reconcile drift with `dotagents sync`.
-
-L0–L2 are the concrete near-term scope. dotagents itself writes no managed surfaces on these paths, but `dotagents inspect` launches HarnessKit, whose own enable/disable/deploy actions can still write native dirs (including managed surfaces) and bypass dotagents; the launch banner cautions against this and drift is reconciled with `dotagents sync`.
-
-## Recommended first slice
-
-**L0 + L2, now unblocked** (open questions #1–#3 resolved in HK's favor):
-
-1. L0 docs pointer — README + `dotagents` SKILL + CLI help. Pointer only, no duplicated harness-compat table.
-2. `dotagents inspect` — thin launcher: `exec.LookPath("hk")`, forward args to `hk serve`, inspection framing (writes not enforced — banner cautions), install hint when absent. Implemented in `cmd/dotagents/harnesskit.go` and `inspect_test.go`.
-3. L1 opt-in install — deferred until the install method and publish-age window are settled.
-4. L3 write-through — separate research spike, no code; keep dotagents the only writer until a go/no-go is decided.
diff --git a/docs/openai-skill-registry-publish.md b/docs/openai-skill-registry-publish.md
deleted file mode 100644
index 069e587..0000000
--- a/docs/openai-skill-registry-publish.md
+++ /dev/null
@@ -1,171 +0,0 @@
-# Design: `dotagents publish` — OpenAI skill registry target
-
-Status: **core implemented on branch `feat/publish-openai-skills` (2026-09-12).** Config schema, lock schema, bundler, upload, and the `dotagents publish` command with dry-run/json/confirmation are built and unit-tested (`publish_test.go`, full suite green). Still inert by default: no targets are configured and every target is opt-in via `enabled: true`. Deferred pending live-API verification: `--prune`, server-side `status` reconcile, and any dependence on list/delete endpoints (undocumented — see §10). No live upload has run yet.
-Date: 2026-09-12
-Author trigger: OpenAI Agents API public beta (Codex harness). Background research lives in the maintainer's private knowledge vault under `research/` (not distributed with this repo).
-
-## 1. Summary
-
-OpenAI's Agents API loads the same open Agent-Skills `SKILL.md` that dotagents already treats as canonical, and it exposes a **persistent skill registry**: `POST https://api.openai.com/v1/skills` uploads a skill bundle, stores it server-side, returns a `skill_id`, and manages versioned bundles. The Responses API references skills by `skill_id` + `version`.
-
-This is a **publish verb**, not a sync entity. It does not belong in the `agents:` list. It maps cleanly onto the existing `external_skills` + `dotagents.lock` machinery, but in the opposite direction: `external_skills` materializes remote skills *inward* and pins their upstream commit; `publish` pushes canonical skills *outward* to a remote registry and pins the returned id/version.
-
-## 2. Why not an `agents:` entity (the decision)
-
-Every `agentConfig` in `dotagents.yaml` is a locally-installed harness with:
-- a `skill_root` (an on-disk directory dotagents reconciles by placing skills), and
-- a `detect` key (checks whether the harness is installed on this machine).
-
-The Agents API has neither. It is a cloud API, not a local install; there is no directory to reconcile and nothing to detect. And it runs the **Codex harness** — the `codex` entity already produces the canonical `SKILL.md` the Agents API consumes. Adding an `openai-agents` row would:
-- duplicate the `codex` skill output,
-- break the "reconcile a local directory" invariant every current entity satisfies, and
-- misfile a per-session runtime concern (`capability_directories`) as a local sync target.
-
-So the format side needs **zero** work — it is already handled by the `codex` entity. The only genuinely new surface is the registry transport, and that is a publish action.
-
-### Scope boundary: registry, not sandbox
-Two OpenAI skill-loading mechanisms exist:
-- **`capability_directories`** — ephemeral, per-session, from sandbox filesystem paths supplied at session-create time by the *application* calling the Agents API. Out of scope for dotagents.
-- **`/v1/skills` registry** — persistent, upload-once, reference-by-id. **This is the only surface dotagents targets.**
-
-## 3. Config schema (`publish_targets:`)
-
-New top-level section in `dotagents.yaml`, sibling to `agents:`, `external_skills:`, etc. Struct mirrors `externalSkillSource` in style.
-
-```yaml
-publish_targets:
-    - name: openai            # unique target name
-      kind: openai-skills     # registry kind (only value for now)
-      enabled: false          # default off; opt-in per user privacy/cost stance
-      skills:                 # explicit allowlist of skill dir names to publish
-        - jobs
-        - tech-search
-      # optional: bump strategy when content changed. default: new-version
-      version_strategy: new-version   # new-version | set-default | dry-run-only
-      # auth: env var name holding the API key. never inline the key.
-      api_key_env: OPENAI_API_KEY
-```
-
-Proposed Go struct (in `main.go`, alongside `externalSkillSource`):
-
-```go
-type publishTarget struct {
-    Name            string   `yaml:"name"`
-    Kind            string   `yaml:"kind"`              // "openai-skills"
-    Enabled         bool     `yaml:"enabled"`
-    Skills          []string `yaml:"skills"`            // allowlist of local skill dir names
-    VersionStrategy string   `yaml:"version_strategy,omitempty"` // default "new-version"
-    APIKeyEnv       string   `yaml:"api_key_env,omitempty"`      // default "OPENAI_API_KEY"
-}
-```
-
-Add `PublishTargets []publishTarget `yaml:"publish_targets,omitempty"`` to `config`.
-
-Design choices:
-- **Explicit allowlist, no "publish everything".** Prevents accidentally shipping private/experimental skills to a US-only, no-ZDR service. A skill is published only if named here.
-- `enabled: false` by default; the command is a no-op until the user opts a target in.
-- No `skill_root`/`detect` — this is a push, not a reconcile.
-
-## 4. Lock schema additions
-
-Extend `dotagents.lock` to pin published state, mirroring `externalLockEntry`.
-
-```yaml
-version: 1
-external_skills:
-    - name: skills
-      ...
-published_skills:
-    - target: openai
-      skill: jobs
-      skill_id: skill_abc123
-      version: "4"   # string: the registry may return non-numeric pointers (e.g. "latest")
-      content_hash: sha256:...   # hash of the bundled skill tree
-      published_at: 2026-09-12T10:00:00Z
-```
-
-Proposed Go structs (in `lock.go`):
-
-```go
-type lockFile struct {
-    Version         int                  `yaml:"version"`
-    ExternalSkills  []externalLockEntry  `yaml:"external_skills"`
-    PublishedSkills []publishedLockEntry `yaml:"published_skills,omitempty"`
-}
-
-type publishedLockEntry struct {
-    Target      string `yaml:"target"`
-    Skill       string `yaml:"skill"`
-    SkillID     string `yaml:"skill_id"`
-    Version     string `yaml:"version"`
-    ContentHash string `yaml:"content_hash"`
-    PublishedAt string `yaml:"published_at"`
-}
-```
-
-The `content_hash` is the idempotency key: if a skill's bundled tree hashes to the same value already in the lock, publish is skipped. This is the outward analogue of `externalLockEntry.Commit`.
-
-## 5. CLI
-
-New top-level command, flag style matching `sync`:
-
-```bash
-dotagents publish                       # publish all enabled targets' allowlisted skills that changed
-dotagents publish --target openai       # limit to one target
-dotagents publish --skills jobs,tech-search   # limit to named skills
-dotagents publish --dry-run             # show what would upload; no network writes
-dotagents publish --json                # machine-readable result
-dotagents publish -y                    # skip the confirmation prompt (CI)
-```
-
-Default behavior (no flags): for each `enabled` target, diff each allowlisted skill's `content_hash` against the lock; upload only changed/new skills; update the lock with returned `skill_id`+`version`. Unchanged skills print "up to date" and are skipped.
-
-Placement: new `cmd/dotagents/publish.go` (flat, matching `sync.go`, `mcp.go`, `promote.go`). Register in the command dispatcher next to `sync`/`mcp`.
-
-## 6. Bundling & validation (enforce API limits before upload)
-
-Before any network call, build the bundle and validate against documented limits:
-- zip ≤ 50 MB, ≤ 500 files, ≤ 25 MB uncompressed;
-- exactly one top-level folder in the zip;
-- exactly one `SKILL.md` with valid front matter (`name`, `description`).
-
-Reuse the existing skill-discovery / skillspec validation (`skill_discovery.go`, `skillspec.go`) for the front-matter and structure checks so the same parser gates both local sync and publish. A skill that fails local validation must fail publish with the same error — no divergent validators.
-
-Bundling: stdlib only — `archive/zip` + `mime/multipart` + `net/http`. **No OpenAI SDK dependency** (a multipart POST does not warrant one; keeps the tree dependency-free and avoids a new external package to age-check).
-
-## 7. Auth, privacy, cost gates
-
-- API key read **only** from the env var named by `api_key_env` (default `OPENAI_API_KEY`). Never inline in `dotagents.yaml`, never write it to the lock, never log it.
-- Publish is destructive-adjacent (sends skill content to a third party). It therefore:
-  - requires `enabled: true` per target,
-  - requires an explicit skill allowlist,
-  - prompts for confirmation unless `-y`, showing the exact skill names and target,
-  - refuses if `OPENAI_API_KEY` is unset rather than falling back to any other credential.
-- Print a one-line privacy reminder on every real (non-dry-run) publish: skills are uploaded to a US-only, no-ZDR service; do not publish vault- or secret-bearing skills.
-
-## 8. `status` integration
-
-`dotagents status` gains a compact "published" section per enabled target: which allowlisted skills are up to date (hash matches lock), drifted (local hash differs → would re-publish), or never published. Mirrors how `status` already reports managed/drifted/missing for local skill roots. Verbose mode lists `skill_id`+`version`.
-
-## 9. Verification plan (when built)
-
-- Unit: bundle builder respects file/size/single-folder limits; content_hash is stable and order-independent; validator rejects missing/duplicate `SKILL.md`.
-- Idempotency: second `publish` with no local change performs zero network writes and leaves the lock byte-identical.
-- Dry-run: `--dry-run` performs no network writes and prints the planned uploads.
-- Live smoke (opt-in, one throwaway skill, real key): upload → assert returned `skill_id`+`version` land in the lock → re-run → assert skip. Delete the test skill from the registry afterward.
-- No live test touches allowlisted real skills or the private vault.
-
-## 10. Open questions
-
-- Does `/v1/skills` support **delete** and **list**? Needed for a `dotagents publish --prune` (remove registry skills no longer in any allowlist) and for `status` to reconcile against the server rather than only the lock. Verify against the current API before building either.
-- Version semantics: does uploading identical content create a new version or dedupe server-side? If the server dedupes, the local `content_hash` skip is an optimization, not a correctness requirement.
-- `agents/openai.yaml` sidecar (display_name/icons/brand_color/default_prompt): include in the bundle when present, but never hand-maintain — generate on demand via the upstream `generate_openai_yaml.py`. Out of scope for v1; base `SKILL.md` publishes fine without it.
-- Should Codex's own `client.beta.agents.sessions` / `capability_directories` path ever be dotagents' concern? Current answer: no — that is the calling application's runtime, not a config-store sync surface.
-
-## 11. Non-goals / gate
-
-- Not building this now. It ships only when there is a concrete long-running cloud-agent workload that justifies metered API billing (tokens + tools + container time), separate from the ChatGPT/Codex subscription.
-- Not an `agents:` entity (see §2). Do not add `openai-agents` to the harness list.
-- Not touching `capability_directories`, sandboxes, or `codex exec-server`.
-- Not a new skill; no new runtime dependency; no automation/cron.
-```
diff --git a/docs/site/index.html b/docs/site/index.html
index 1fac26b..9d543e1 100644
--- a/docs/site/index.html
+++ b/docs/site/index.html
@@ -396,7 +396,7 @@ <h3>How it compares</h3>
           <tr><th scope="row">Agent roles</th><td class="y">rendered native</td><td class="y">yes</td><td style="color:var(--gold)">experimental</td><td class="n">no</td></tr>
           <tr><th scope="row">Pinned + audited externals</th><td class="y">lock file + audit</td><td class="n">no pinning</td><td class="n">no pinning</td><td style="color:var(--gold)">tracks source, no pin</td></tr>
           <tr><th scope="row">Harness coverage</th><td class="y">9 deep</td><td style="color:var(--gold)">broad</td><td style="color:var(--gold)">broad</td><td style="color:var(--gold)">narrow</td></tr>
-          <tr><th scope="row">Install</th><td style="color:var(--gold)">curl / mise / go</td><td style="color:var(--gold)">npm / brew</td><td style="color:var(--gold)">npm</td><td style="color:var(--gold)">npm</td></tr>
+          <tr><th scope="row">Install</th><td style="color:var(--gold)">brew / npm / curl / go</td><td style="color:var(--gold)">npm / brew</td><td style="color:var(--gold)">npm</td><td style="color:var(--gold)">npm</td></tr>
         </tbody>
       </table>
       </div>
@@ -404,6 +404,29 @@ <h3>How it compares</h3>
     </div>
   </section>
 
+  <!-- Docs -->
+  <section>
+    <h2>Documentation</h2>
+    <p class="section-sub">Operational detail lives in the repository, next to the code it describes.</p>
+
+    <div class="panel">
+      <h3>Guides</h3>
+      <div class="table-wrap">
+      <table>
+        <tbody>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents#readme">README</a></th><td>Install channels, the five synced surfaces, and the command index</td></tr>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents/blob/main/docs/setup.md">Setup</a></th><td>First-run walkthrough, review screen, multi-machine setup</td></tr>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents/blob/main/docs/skills.md">Skills</a></th><td>Authoring skills, external pins, plugin discovery</td></tr>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents/blob/main/docs/roles.md">Roles</a></th><td>Role format, model tiers, per-harness overrides</td></tr>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents/blob/main/docs/memory.md">Memory</a></th><td>Tiers, the <code>rem</code> workflow, vault layout</td></tr>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents/blob/main/docs/comparison.md">Comparison</a></th><td>How dotagents differs from rulesync, ruler, and openskills</td></tr>
+          <tr><th scope="row"><a href="https://github.com/yourconscience/dotagents/blob/main/docs/troubleshooting.md">Troubleshooting</a></th><td>Doctor first, plus the common failure modes</td></tr>
+        </tbody>
+      </table>
+      </div>
+    </div>
+  </section>
+
   <footer>
     <a href="https://github.com/yourconscience/dotagents">github.com/yourconscience/dotagents</a>
     <a href="https://yourconscience.github.io/mushroom/" title="agent-built in one evening">built by agents, verified by humans</a>
diff --git a/docs/status-preview.html b/docs/status-preview.html
deleted file mode 100644
index 844e4e8..0000000
--- a/docs/status-preview.html
+++ /dev/null
@@ -1,120 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>dotagents status preview</title>
-<style>
-  body {
-    margin: 0;
-    padding: 0;
-    background: #0d1117;
-    display: flex;
-    justify-content: center;
-    align-items: flex-start;
-    min-height: 100vh;
-    padding: 32px;
-  }
-  .terminal {
-    background: #161b22;
-    border: 1px solid #30363d;
-    border-radius: 12px;
-    max-width: 780px;
-    width: 100%;
-    box-shadow: 0 16px 48px rgba(0,0,0,.4);
-    overflow: hidden;
-    font-family: 'SF Mono', 'Menlo', 'Monaco', 'Cascadia Code', 'Consolas', monospace;
-  }
-  .titlebar {
-    background: #1c2128;
-    border-bottom: 1px solid #30363d;
-    padding: 12px 16px;
-    display: flex;
-    align-items: center;
-    gap: 8px;
-  }
-  .dot { width: 12px; height: 12px; border-radius: 50%; }
-  .dot-red { background: #ff5f57; }
-  .dot-yellow { background: #febc2e; }
-  .dot-green { background: #28c840; }
-  .titlebar-text {
-    flex: 1;
-    text-align: center;
-    color: #8b949e;
-    font-size: 12px;
-    margin-right: 52px;
-  }
-  .content {
-    padding: 20px 24px 24px;
-    font-size: 13px;
-    line-height: 1.55;
-    color: #c9d1d9;
-    white-space: pre;
-    overflow-x: auto;
-  }
-  .prompt { color: #7ee787; }
-  .cmd { color: #f0f6fc; font-weight: 600; }
-  .dim { color: #6e7681; }
-  .heading { color: #f0f6fc; font-weight: 600; }
-  .label { color: #8b949e; }
-  .ok { color: #7ee787; }
-  .val { color: #c9d1d9; }
-  .skill { color: #d2a8ff; }
-  .mcp { color: #79c0ff; }
-  .hook { color: #ffa657; }
-  .agent { color: #7ee787; }
-  .ext { color: #6e7681; }
-  .pass { color: #7ee787; font-weight: 600; }
-  .warn { color: #d29922; }
-</style>
-</head>
-<body>
-<div class="terminal">
-  <div class="titlebar">
-    <div class="dot dot-red"></div>
-    <div class="dot dot-yellow"></div>
-    <div class="dot dot-green"></div>
-    <div class="titlebar-text">dotagents status</div>
-  </div>
-  <div class="content"><span class="prompt">$</span> <span class="cmd">dotagents status</span>
-
-<span class="heading">dotagents status</span>
-<span class="label">repo:</span> <span class="val">~/.agents</span>
-
-<span class="label">external sources:</span>
-  <span class="label">skills</span>  github.com/mattpocock/skills  <span class="ok">synced</span> <span class="dim">(d574778)</span>
-
-<span class="heading">claude-code</span>
-  <span class="label">sync:</span> <span class="ok">synced</span>
-  <span class="label">managed</span> <span class="dim">(16):</span> <span class="skill">dotagents, grill-me, grilling, gws, humanizer,
-              jobs, pr-triage, remote-access, repo-eval, spawn,
-              spec, tech-search, tg, tmux, x-cli, x-sim</span>
-  <span class="label">agent managed</span> <span class="dim">(4):</span> <span class="agent">architect, builder, researcher, reviewer</span>
-  <span class="label">mcp managed</span> <span class="dim">(2):</span> <span class="mcp">linkedin, tavily</span>
-  <span class="label">hook managed</span> <span class="dim">(4):</span> <span class="hook">memory-session-end, memory-session-start,
-                       memory-stop, pr-triage-stop</span>
-
-<span class="heading">codex</span>
-  <span class="label">sync:</span> <span class="ok">synced</span>
-  <span class="label">managed</span> <span class="dim">(16):</span> <span class="skill">dotagents, grill-me, grilling, gws, humanizer,
-              jobs, pr-triage, remote-access, repo-eval, spawn,
-              spec, tech-search, tg, tmux, x-cli, x-sim</span>
-  <span class="label">agent managed</span> <span class="dim">(4):</span> <span class="agent">architect, builder, researcher, reviewer</span>
-  <span class="label">mcp managed</span> <span class="dim">(2):</span> <span class="mcp">linkedin, tavily</span>
-
-<span class="heading">hermes</span>
-  <span class="label">sync:</span> <span class="ok">synced</span>
-  <span class="label">managed</span> <span class="dim">(16):</span> <span class="skill">dotagents, grill-me, grilling, gws, humanizer, ...</span>
-  <span class="label">mcp managed</span> <span class="dim">(2):</span> <span class="mcp">linkedin, tavily</span>
-  <span class="label">hook managed</span> <span class="dim">(1):</span> <span class="hook">memory-session-end</span>
-
-<span class="heading">droid</span>
-  <span class="label">sync:</span> <span class="ok">synced</span>
-  <span class="label">managed</span> <span class="dim">(16):</span> <span class="skill">dotagents, grill-me, grilling, gws, humanizer, ...</span>
-  <span class="label">agent managed</span> <span class="dim">(4):</span> <span class="agent">architect, builder, researcher, reviewer</span>
-  <span class="label">mcp managed</span> <span class="dim">(2):</span> <span class="mcp">linkedin, tavily</span>
-
-<span class="pass">external lock:</span> pass <span class="dim">(1 source pinned and in sync)</span>
-<span class="pass">memsearch:</span>     pass <span class="dim">(collection ai has 3224 chunks)</span></div>
-</div>
-</body>
-</html>
\ No newline at end of file
diff --git a/docs/status-preview.png b/docs/status-preview.png
deleted file mode 100644
index 37210ec..0000000
Binary files a/docs/status-preview.png and /dev/null differ
diff --git a/go.work b/go.work
deleted file mode 100644
index c3f8031..0000000
--- a/go.work
+++ /dev/null
@@ -1,6 +0,0 @@
-go 1.24.2
-
-use (
-	.
-	./memory/tools/knowledge-sync
-)
diff --git a/internal/agentrole/claude.go b/internal/agentrole/claude.go
new file mode 100644
index 0000000..20cef40
--- /dev/null
+++ b/internal/agentrole/claude.go
@@ -0,0 +1,24 @@
+package agentrole
+
+import "strings"
+
+func renderClaude(role Role) string {
+	model := strings.TrimSpace(role.Claude.Model)
+	if model == "" {
+		model = strings.TrimSpace(role.Model)
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	writeYAMLScalar(&b, "name", role.Name)
+	writeYAMLScalar(&b, "description", role.Description)
+	writeYAMLScalar(&b, "model", model)
+	writeYAMLScalar(&b, "effort", role.Effort)
+	if len(role.Tools) > 0 {
+		b.WriteString("tools: ")
+		b.WriteString(strings.Join(role.Tools, ", "))
+		b.WriteString("\n")
+	}
+	writeYAMLScalar(&b, "color", role.Color)
+	writeGeneratedMarkdownBody(&b, role)
+	return b.String()
+}
diff --git a/internal/agentrole/codex.go b/internal/agentrole/codex.go
new file mode 100644
index 0000000..59e84fa
--- /dev/null
+++ b/internal/agentrole/codex.go
@@ -0,0 +1,40 @@
+package agentrole
+
+import (
+	"strconv"
+	"strings"
+)
+
+func renderCodex(role Role) string {
+	model := strings.TrimSpace(role.Codex.Model)
+	if model == "" {
+		model = codexModelFor(role.Model)
+	}
+	effort := strings.TrimSpace(role.Codex.ModelReasoningEffort)
+	if effort == "" {
+		effort = strings.TrimSpace(role.Effort)
+	}
+	var b strings.Builder
+	b.WriteString("# ")
+	b.WriteString(GeneratedMarker)
+	b.WriteString(" from ")
+	b.WriteString(sourceLabel(role))
+	b.WriteString("; do not edit directly.\n")
+	writeTOMLString(&b, "name", role.Name)
+	writeTOMLString(&b, "description", role.Description)
+	writeTOMLString(&b, "model", model)
+	writeTOMLString(&b, "model_reasoning_effort", effort)
+	b.WriteString("developer_instructions = ")
+	b.WriteString(strconv.Quote(role.Instructions))
+	b.WriteString("\n")
+	return b.String()
+}
+
+func codexModelFor(model string) string {
+	switch strings.ToLower(strings.TrimSpace(model)) {
+	case "", "haiku", "sonnet", "opus":
+		return ""
+	default:
+		return strings.TrimSpace(model)
+	}
+}
diff --git a/internal/agentrole/droid.go b/internal/agentrole/droid.go
new file mode 100644
index 0000000..c850bad
--- /dev/null
+++ b/internal/agentrole/droid.go
@@ -0,0 +1,73 @@
+package agentrole
+
+import "strings"
+
+var droidToolMapping = map[string][]string{
+	"bash": {"Execute"}, "edit": {"Edit"}, "glob": {"Glob"}, "grep": {"Grep"},
+	"read": {"Read"}, "webfetch": {"FetchUrl"}, "websearch": {"WebSearch"}, "write": {"Create", "Edit"},
+}
+var droidFallbackTools = []string{"Read", "LS", "Grep", "Glob"}
+
+func renderDroid(role Role) string {
+	model := strings.TrimSpace(role.Droid.Model)
+	if model == "" {
+		model = droidModelFor(role.Model)
+	}
+	effort := strings.TrimSpace(role.Droid.ReasoningEffort)
+	if effort == "" {
+		effort = strings.TrimSpace(role.Effort)
+	}
+	tools := role.Droid.Tools
+	if len(tools) == 0 {
+		tools = droidToolsFor(role.Tools)
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	writeYAMLScalar(&b, "name", role.Name)
+	writeYAMLScalar(&b, "description", role.Description)
+	writeYAMLScalar(&b, "model", model)
+	writeYAMLScalar(&b, "reasoningEffort", effort)
+	if len(tools) > 0 {
+		b.WriteString("tools:\n")
+		for _, tool := range tools {
+			writeYAMLListItem(&b, tool)
+		}
+	}
+	writeGeneratedMarkdownBody(&b, role)
+	return b.String()
+}
+
+func droidModelFor(model string) string {
+	model = strings.TrimSpace(model)
+	switch strings.ToLower(model) {
+	case "haiku":
+		return "custom:gpt-5.5(low)"
+	case "sonnet":
+		return "custom:gpt-5.5(medium)"
+	case "opus":
+		return "custom:gpt-5.5(high)"
+	default:
+		if model == "" {
+			return "inherit"
+		}
+		return model
+	}
+}
+
+func droidToolsFor(tools []string) []string {
+	var out []string
+	seen := make(map[string]struct{})
+	for _, tool := range tools {
+		for _, mapped := range droidToolMapping[strings.ToLower(strings.TrimSpace(tool))] {
+			if _, ok := seen[mapped]; ok {
+				continue
+			}
+			seen[mapped] = struct{}{}
+			out = append(out, mapped)
+		}
+	}
+	if len(tools) > 0 && len(out) == 0 {
+		return append([]string(nil), droidFallbackTools...)
+	}
+	return out
+}
diff --git a/internal/agentrole/omp.go b/internal/agentrole/omp.go
new file mode 100644
index 0000000..dfe0371
--- /dev/null
+++ b/internal/agentrole/omp.go
@@ -0,0 +1,32 @@
+package agentrole
+
+import "strings"
+
+var ompToolMapping = map[string]string{
+	"bash": "bash", "edit": "edit", "glob": "glob", "grep": "grep", "read": "read",
+	"webfetch": "read", "websearch": "web_search", "write": "write",
+}
+
+func renderOMP(role Role) string {
+	model := strings.TrimSpace(role.OMP.Model)
+	if model == "" {
+		model = strings.TrimSpace(role.Model)
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	writeYAMLScalar(&b, "name", role.Name)
+	writeYAMLScalar(&b, "description", role.Description)
+	if model != "" {
+		b.WriteString("model:\n")
+		writeYAMLListItem(&b, model)
+	}
+	writeYAMLScalar(&b, "thinking-level", role.OMP.ThinkingLevel)
+	if tools := mappedTools(role.Tools, ompToolMapping); len(tools) > 0 {
+		b.WriteString("tools:\n")
+		for _, tool := range tools {
+			writeYAMLListItem(&b, tool)
+		}
+	}
+	writeGeneratedMarkdownBody(&b, role)
+	return b.String()
+}
diff --git a/internal/agentrole/opencode.go b/internal/agentrole/opencode.go
new file mode 100644
index 0000000..79bb714
--- /dev/null
+++ b/internal/agentrole/opencode.go
@@ -0,0 +1,28 @@
+package agentrole
+
+import "strings"
+
+func renderOpenCode(role Role) string {
+	mode := strings.TrimSpace(role.Opencode.Mode)
+	if mode == "" {
+		mode = "subagent"
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	writeYAMLScalar(&b, "description", role.Description)
+	b.WriteString("mode: ")
+	b.WriteString(mode)
+	b.WriteString("\n")
+	if model := strings.TrimSpace(role.Opencode.Model); model != "" {
+		writeYAMLScalar(&b, "model", model)
+	} else if model := strings.TrimSpace(role.Model); model != "" && !canonicalModelTier(model) {
+		writeYAMLScalar(&b, "model", model)
+	}
+	if temperature := strings.TrimSpace(role.Opencode.Temperature); temperature != "" {
+		b.WriteString("temperature: ")
+		b.WriteString(temperature)
+		b.WriteString("\n")
+	}
+	writeGeneratedMarkdownBody(&b, role)
+	return b.String()
+}
diff --git a/internal/agentrole/parser.go b/internal/agentrole/parser.go
new file mode 100644
index 0000000..e71bd88
--- /dev/null
+++ b/internal/agentrole/parser.go
@@ -0,0 +1,213 @@
+package agentrole
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+func (role *Role) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind != yaml.MappingNode {
+		return fmt.Errorf("agent role must be a mapping")
+	}
+	type plainRole Role
+	var decoded plainRole
+	for i := 0; i+1 < len(value.Content); i += 2 {
+		key, node := value.Content[i].Value, value.Content[i+1]
+		if key == "tools" {
+			tools, err := decodeTools(node)
+			if err != nil {
+				return err
+			}
+			decoded.Tools = tools
+			continue
+		}
+		var err error
+		// Decode fields individually so tools can retain scalar compatibility.
+		switch key {
+		case "name":
+			err = node.Decode(&decoded.Name)
+		case "description":
+			err = node.Decode(&decoded.Description)
+		case "model":
+			err = node.Decode(&decoded.Model)
+		case "effort":
+			err = node.Decode(&decoded.Effort)
+		case "color":
+			err = node.Decode(&decoded.Color)
+		case "claude":
+			err = node.Decode(&decoded.Claude)
+		case "codex":
+			err = node.Decode(&decoded.Codex)
+		case "omp":
+			err = node.Decode(&decoded.OMP)
+		case "pi":
+			err = node.Decode(&decoded.Pi)
+		case "droid":
+			err = node.Decode(&decoded.Droid)
+		case "opencode":
+			err = node.Decode(&decoded.Opencode)
+		case "qwen":
+			err = node.Decode(&decoded.Qwen)
+		}
+		if err != nil {
+			return err
+		}
+	}
+	*role = Role(decoded)
+	return nil
+}
+
+func decodeTools(node *yaml.Node) ([]string, error) {
+	switch node.Kind {
+	case yaml.SequenceNode:
+		var tools []string
+		if err := node.Decode(&tools); err != nil {
+			return nil, err
+		}
+		return tools, nil
+	case yaml.ScalarNode:
+		var tools []string
+		for _, part := range strings.Split(node.Value, ",") {
+			if tool := strings.TrimSpace(part); tool != "" {
+				tools = append(tools, tool)
+			}
+		}
+		return tools, nil
+	default:
+		return nil, fmt.Errorf("tools must be a YAML sequence or comma-separated string")
+	}
+}
+
+// ParseMarkdown parses canonical YAML-frontmatter Markdown role bytes.
+func ParseMarkdown(path string, data []byte) (Role, error) {
+	if !bytes.HasPrefix(data, []byte("---\n")) {
+		return Role{}, fmt.Errorf("%s: missing YAML frontmatter", path)
+	}
+	rest := data[len("---\n"):]
+	end := bytes.Index(rest, []byte("\n---"))
+	if end < 0 {
+		return Role{}, fmt.Errorf("%s: unterminated YAML frontmatter", path)
+	}
+	frontmatter := rest[:end]
+	body := rest[end+len("\n---"):]
+	if len(body) > 0 && body[0] == '\r' {
+		body = body[1:]
+	}
+	if len(body) > 0 && body[0] == '\n' {
+		body = body[1:]
+	}
+	var role Role
+	if err := yaml.Unmarshal(frontmatter, &role); err != nil {
+		return Role{}, fmt.Errorf("parse %s frontmatter: %w", path, err)
+	}
+	role.Instructions = strings.TrimSpace(string(body))
+	role.Source = path
+	return role, nil
+}
+
+// LoadFile loads and validates one canonical role.
+func LoadFile(path string) (Role, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Role{}, fmt.Errorf("read %s: %w", path, err)
+	}
+	role, err := ParseMarkdown(path, data)
+	if err != nil {
+		return Role{}, err
+	}
+	if err := validate(&role, path); err != nil {
+		return Role{}, err
+	}
+	return role, nil
+}
+
+func validate(role *Role, source string) error {
+	role.Name = strings.ToLower(strings.TrimSpace(role.Name))
+	role.Model = strings.TrimSpace(role.Model)
+	role.Effort = strings.TrimSpace(role.Effort)
+	role.Description = strings.TrimSpace(role.Description)
+	role.Instructions = strings.TrimSpace(role.Instructions)
+	if role.Name == "" {
+		return fmt.Errorf("%s is missing name", source)
+	}
+	if role.Description == "" {
+		return fmt.Errorf("%s: role %s is missing description", source, role.Name)
+	}
+	if role.Instructions == "" {
+		return fmt.Errorf("%s: role %s is missing instructions", source, role.Name)
+	}
+	return nil
+}
+
+// RenderCanonical serializes a role in the editable canonical Markdown format.
+func RenderCanonical(role Role) ([]byte, error) {
+	if err := validate(&role, "imported role"); err != nil {
+		return nil, err
+	}
+	front := struct {
+		Name        string          `yaml:"name"`
+		Description string          `yaml:"description"`
+		Model       string          `yaml:"model,omitempty"`
+		Effort      string          `yaml:"effort,omitempty"`
+		Tools       []string        `yaml:"tools,omitempty"`
+		Color       string          `yaml:"color,omitempty"`
+		Claude      ClaudeOptions   `yaml:"claude,omitempty"`
+		Codex       CodexOptions    `yaml:"codex,omitempty"`
+		Droid       DroidOptions    `yaml:"droid,omitempty"`
+		OpenCode    OpenCodeOptions `yaml:"opencode,omitempty"`
+		OMP         OMPOptions      `yaml:"omp,omitempty"`
+		Pi          PiOptions       `yaml:"pi,omitempty"`
+	}{
+		Name: role.Name, Description: role.Description, Model: role.Model, Effort: role.Effort,
+		Tools: role.Tools, Color: role.Color, Claude: role.Claude, Codex: role.Codex,
+		Droid: role.Droid, OpenCode: role.Opencode, OMP: role.OMP, Pi: role.Pi,
+	}
+	meta, err := yaml.Marshal(front)
+	if err != nil {
+		return nil, err
+	}
+	return []byte("---\n" + string(meta) + "---\n\n" + strings.TrimSpace(role.Instructions) + "\n"), nil
+}
+
+// Load reads and validates canonical roles from <root>/agents.
+func Load(root string) ([]Role, error) {
+	dir := filepath.Join(root, "agents")
+	entries, err := os.ReadDir(dir)
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("read %s: %w", dir, err)
+	}
+	var paths []string
+	for _, entry := range entries {
+		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || filepath.Ext(entry.Name()) != MarkdownExtension {
+			continue
+		}
+		paths = append(paths, filepath.Join(dir, entry.Name()))
+	}
+	sort.Strings(paths)
+	roles := make([]Role, 0, len(paths))
+	seen := make(map[string]struct{}, len(paths))
+	for _, path := range paths {
+		role, err := LoadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		if _, ok := seen[role.Name]; ok {
+			return nil, fmt.Errorf("agent role %s is duplicated", role.Name)
+		}
+		seen[role.Name] = struct{}{}
+		roles = append(roles, role)
+	}
+	sort.Slice(roles, func(i, j int) bool { return roles[i].Name < roles[j].Name })
+	return roles, nil
+}
diff --git a/internal/agentrole/pi.go b/internal/agentrole/pi.go
new file mode 100644
index 0000000..1672992
--- /dev/null
+++ b/internal/agentrole/pi.go
@@ -0,0 +1,35 @@
+package agentrole
+
+import "strings"
+
+var piToolMapping = map[string]string{
+	"bash": "bash", "edit": "edit", "glob": "find", "grep": "grep", "read": "read",
+	"webfetch": "fetch_content", "websearch": "web_search", "write": "write",
+}
+
+// renderPi emits the user-agent format consumed by pi-subagents. Vanilla Pi
+// ignores this directory when the extension is absent.
+func renderPi(role Role) string {
+	model := strings.TrimSpace(role.Pi.Model)
+	if model == "" && !canonicalModelTier(role.Model) {
+		model = strings.TrimSpace(role.Model)
+	}
+	thinking := strings.TrimSpace(role.Pi.Thinking)
+	if thinking == "" {
+		thinking = strings.TrimSpace(role.Effort)
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	writeYAMLScalar(&b, "name", role.Name)
+	writeYAMLScalar(&b, "description", role.Description)
+	writeYAMLScalar(&b, "model", model)
+	writeYAMLScalar(&b, "thinking", thinking)
+	if tools := mappedTools(role.Tools, piToolMapping); len(tools) > 0 {
+		b.WriteString("tools:\n")
+		for _, tool := range tools {
+			writeYAMLListItem(&b, tool)
+		}
+	}
+	writeGeneratedMarkdownBody(&b, role)
+	return b.String()
+}
diff --git a/internal/agentrole/qwen.go b/internal/agentrole/qwen.go
new file mode 100644
index 0000000..c3d8c3b
--- /dev/null
+++ b/internal/agentrole/qwen.go
@@ -0,0 +1,37 @@
+package agentrole
+
+import "strings"
+
+var qwenToolMapping = map[string]string{
+	"bash": "run_shell_command", "edit": "replace", "glob": "glob", "grep": "grep_search",
+	"read": "read_file", "webfetch": "web_fetch", "websearch": "web_search", "write": "write_file",
+}
+
+func renderQwen(role Role) string {
+	model := strings.TrimSpace(role.Qwen.Model)
+	if model == "" {
+		if generic := strings.TrimSpace(role.Model); generic != "" && !canonicalModelTier(generic) {
+			model = generic
+		} else {
+			model = "inherit"
+		}
+	}
+	tools := role.Qwen.Tools
+	if len(tools) == 0 {
+		tools = mappedTools(role.Tools, qwenToolMapping)
+	}
+	var b strings.Builder
+	b.WriteString("---\n")
+	writeYAMLScalar(&b, "name", role.Name)
+	writeYAMLScalar(&b, "description", role.Description)
+	writeYAMLScalar(&b, "model", model)
+	writeYAMLScalar(&b, "approvalMode", role.Qwen.ApprovalMode)
+	if len(tools) > 0 {
+		b.WriteString("tools:\n")
+		for _, tool := range tools {
+			writeYAMLListItem(&b, tool)
+		}
+	}
+	writeGeneratedMarkdownBody(&b, role)
+	return b.String()
+}
diff --git a/internal/agentrole/role.go b/internal/agentrole/role.go
new file mode 100644
index 0000000..f9146d1
--- /dev/null
+++ b/internal/agentrole/role.go
@@ -0,0 +1,176 @@
+// Package agentrole parses canonical dotagents roles and projects them into
+// harness-native role formats.
+package agentrole
+
+import (
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+const (
+	// MarkdownExtension is the canonical editable role source extension.
+	MarkdownExtension = ".md"
+	// GeneratedMarker identifies role projections owned by dotagents.
+	GeneratedMarker = "Generated by dotagents"
+)
+
+// Role is the canonical representation shared by every harness renderer.
+type Role struct {
+	Name         string          `yaml:"name"`
+	Description  string          `yaml:"description"`
+	Model        string          `yaml:"model"`
+	Effort       string          `yaml:"effort"`
+	Tools        []string        `yaml:"tools"`
+	Color        string          `yaml:"color"`
+	Instructions string          `yaml:"-"`
+	Source       string          `yaml:"-"`
+	Claude       ClaudeOptions   `yaml:"claude"`
+	Codex        CodexOptions    `yaml:"codex"`
+	OMP          OMPOptions      `yaml:"omp"`
+	Pi           PiOptions       `yaml:"pi"`
+	Droid        DroidOptions    `yaml:"droid"`
+	Opencode     OpenCodeOptions `yaml:"opencode"`
+	Qwen         QwenOptions     `yaml:"qwen"`
+}
+
+type ClaudeOptions struct {
+	Model string `yaml:"model"`
+}
+
+type CodexOptions struct {
+	Model                string `yaml:"model"`
+	ModelReasoningEffort string `yaml:"model_reasoning_effort"`
+}
+
+type OMPOptions struct {
+	Model         string `yaml:"model"`
+	ThinkingLevel string `yaml:"thinking-level"`
+}
+
+type PiOptions struct {
+	Model    string `yaml:"model"`
+	Thinking string `yaml:"thinking"`
+}
+
+type DroidOptions struct {
+	Model           string   `yaml:"model"`
+	ReasoningEffort string   `yaml:"reasoning_effort"`
+	Tools           []string `yaml:"tools"`
+}
+
+type OpenCodeOptions struct {
+	Model       string `yaml:"model"`
+	Temperature string `yaml:"temperature"`
+	Mode        string `yaml:"mode"`
+}
+
+type QwenOptions struct {
+	Model        string   `yaml:"model"`
+	ApprovalMode string   `yaml:"approval_mode"`
+	Tools        []string `yaml:"tools"`
+}
+
+// Renderer is a harness projection of a canonical role.
+type Renderer interface {
+	Extension() string
+	Render(Role) string
+}
+
+type renderer struct {
+	extension string
+	render    func(Role) string
+}
+
+func (r renderer) Extension() string       { return r.extension }
+func (r renderer) Render(role Role) string { return r.render(role) }
+
+var renderers = map[string]Renderer{
+	"claude-code": renderer{extension: ".md", render: renderClaude},
+	"codex":       renderer{extension: ".toml", render: renderCodex},
+	"droid":       renderer{extension: ".md", render: renderDroid},
+	"opencode":    renderer{extension: ".md", render: renderOpenCode},
+	"pi":          renderer{extension: ".md", render: renderPi},
+	"omp":         renderer{extension: ".md", render: renderOMP},
+	"qwen-code":   renderer{extension: ".md", render: renderQwen},
+}
+
+// Lookup returns the registered renderer for a harness name.
+func Lookup(harness string) (Renderer, bool) {
+	renderer, ok := renderers[strings.ToLower(strings.TrimSpace(harness))]
+	return renderer, ok
+}
+
+func sourceLabel(role Role) string {
+	if role.Source == "" {
+		return "agents/" + role.Name + MarkdownExtension
+	}
+	return "agents/" + filepath.Base(role.Source)
+}
+
+func writeYAMLScalar(b *strings.Builder, key, value string) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return
+	}
+	b.WriteString(key)
+	b.WriteString(": ")
+	b.WriteString(strconv.Quote(value))
+	b.WriteString("\n")
+}
+
+func writeYAMLListItem(b *strings.Builder, value string) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return
+	}
+	b.WriteString("  - ")
+	b.WriteString(strconv.Quote(value))
+	b.WriteString("\n")
+}
+
+func writeTOMLString(b *strings.Builder, key, value string) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return
+	}
+	b.WriteString(key)
+	b.WriteString(" = ")
+	b.WriteString(strconv.Quote(value))
+	b.WriteString("\n")
+}
+
+func writeGeneratedMarkdownBody(b *strings.Builder, role Role) {
+	b.WriteString("---\n\n<!-- ")
+	b.WriteString(GeneratedMarker)
+	b.WriteString(" from ")
+	b.WriteString(sourceLabel(role))
+	b.WriteString("; do not edit directly. -->\n\n")
+	b.WriteString(role.Instructions)
+	b.WriteString("\n")
+}
+
+func canonicalModelTier(model string) bool {
+	switch strings.ToLower(strings.TrimSpace(model)) {
+	case "haiku", "sonnet", "opus":
+		return true
+	}
+	return false
+}
+
+func mappedTools(tools []string, mapping map[string]string) []string {
+	out := make([]string, 0, len(tools))
+	seen := make(map[string]struct{}, len(tools))
+	for _, tool := range tools {
+		mapped := mapping[strings.ToLower(strings.TrimSpace(tool))]
+		if mapped == "" {
+			continue
+		}
+		if _, ok := seen[mapped]; ok {
+			continue
+		}
+		seen[mapped] = struct{}{}
+		out = append(out, mapped)
+	}
+	return out
+}
diff --git a/internal/agentrole/role_test.go b/internal/agentrole/role_test.go
new file mode 100644
index 0000000..29d8466
--- /dev/null
+++ b/internal/agentrole/role_test.go
@@ -0,0 +1,127 @@
+package agentrole
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestRendererRegistryByteStableOutputs(t *testing.T) {
+	role := Role{
+		Name:         "reviewer",
+		Description:  "Review: safely",
+		Model:        "opus",
+		Effort:       "high",
+		Tools:        []string{"Read", "WebSearch", "Write"},
+		Color:        "purple",
+		Instructions: "Review carefully.",
+		Source:       filepath.Join("somewhere", "reviewer.md"),
+		Claude:       ClaudeOptions{Model: "claude-custom"},
+		Codex:        CodexOptions{Model: "gpt-custom", ModelReasoningEffort: "max"},
+		Droid:        DroidOptions{},
+		Opencode:     OpenCodeOptions{Model: "anthropic/claude", Temperature: "0.1", Mode: "primary"},
+		OMP:          OMPOptions{Model: "gpt-omp", ThinkingLevel: "max"},
+		Qwen:         QwenOptions{ApprovalMode: "plan"},
+	}
+	tests := map[string]struct {
+		extension string
+		want      string
+	}{
+		"claude-code": {".md", "---\nname: \"reviewer\"\ndescription: \"Review: safely\"\nmodel: \"claude-custom\"\neffort: \"high\"\ntools: Read, WebSearch, Write\ncolor: \"purple\"\n---\n\n<!-- Generated by dotagents from agents/reviewer.md; do not edit directly. -->\n\nReview carefully.\n"},
+		"codex":       {".toml", "# Generated by dotagents from agents/reviewer.md; do not edit directly.\nname = \"reviewer\"\ndescription = \"Review: safely\"\nmodel = \"gpt-custom\"\nmodel_reasoning_effort = \"max\"\ndeveloper_instructions = \"Review carefully.\"\n"},
+		"droid":       {".md", "---\nname: \"reviewer\"\ndescription: \"Review: safely\"\nmodel: \"custom:gpt-5.5(high)\"\nreasoningEffort: \"high\"\ntools:\n  - \"Read\"\n  - \"WebSearch\"\n  - \"Create\"\n  - \"Edit\"\n---\n\n<!-- Generated by dotagents from agents/reviewer.md; do not edit directly. -->\n\nReview carefully.\n"},
+		"opencode":    {".md", "---\ndescription: \"Review: safely\"\nmode: primary\nmodel: \"anthropic/claude\"\ntemperature: 0.1\n---\n\n<!-- Generated by dotagents from agents/reviewer.md; do not edit directly. -->\n\nReview carefully.\n"},
+		"pi":          {".md", "---\nname: \"reviewer\"\ndescription: \"Review: safely\"\nthinking: \"high\"\ntools:\n  - \"read\"\n  - \"web_search\"\n  - \"write\"\n---\n\n<!-- Generated by dotagents from agents/reviewer.md; do not edit directly. -->\n\nReview carefully.\n"},
+		"omp":         {".md", "---\nname: \"reviewer\"\ndescription: \"Review: safely\"\nmodel:\n  - \"gpt-omp\"\nthinking-level: \"max\"\ntools:\n  - \"read\"\n  - \"web_search\"\n  - \"write\"\n---\n\n<!-- Generated by dotagents from agents/reviewer.md; do not edit directly. -->\n\nReview carefully.\n"},
+		"qwen-code":   {".md", "---\nname: \"reviewer\"\ndescription: \"Review: safely\"\nmodel: \"inherit\"\napprovalMode: \"plan\"\ntools:\n  - \"read_file\"\n  - \"web_search\"\n  - \"write_file\"\n---\n\n<!-- Generated by dotagents from agents/reviewer.md; do not edit directly. -->\n\nReview carefully.\n"},
+	}
+	for harness, test := range tests {
+		t.Run(harness, func(t *testing.T) {
+			renderer, ok := Lookup(harness)
+			if !ok {
+				t.Fatalf("renderer %q not registered", harness)
+			}
+			if got := renderer.Extension(); got != test.extension {
+				t.Fatalf("extension = %q, want %q", got, test.extension)
+			}
+			if got := renderer.Render(role); got != test.want {
+				t.Fatalf("rendered bytes differ\n--- got ---\n%s--- want ---\n%s", got, test.want)
+			}
+		})
+	}
+	if _, ok := Lookup("unknown"); ok {
+		t.Fatal("unknown harness unexpectedly has a role renderer")
+	}
+}
+
+func TestParseMarkdownSupportsToolShapesAndHarnessOverrides(t *testing.T) {
+	for name, tools := range map[string]string{
+		"list":   "tools: [Read, Grep]",
+		"scalar": "tools: Read, Grep",
+	} {
+		t.Run(name, func(t *testing.T) {
+			role, err := ParseMarkdown("agents/builder.md", []byte("---\nname: builder\ndescription: Builds features\nmodel: opus\n"+tools+"\nqwen:\n  model: qwen-custom\n  approval_mode: plan\n---\n\nBuild carefully.\n"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(role.Tools) != 2 || role.Tools[0] != "Read" || role.Tools[1] != "Grep" {
+				t.Fatalf("tools = %#v", role.Tools)
+			}
+			if role.Qwen.Model != "qwen-custom" || role.Qwen.ApprovalMode != "plan" {
+				t.Fatalf("Qwen options = %#v", role.Qwen)
+			}
+		})
+	}
+}
+
+func TestParseMarkdownRejectsMappingTools(t *testing.T) {
+	_, err := ParseMarkdown("agents/invalid.md", []byte("---\nname: invalid\ndescription: Invalid\ntools: {name: Read}\n---\n\nDo work.\n"))
+	if err == nil || err.Error() != "parse agents/invalid.md frontmatter: tools must be a YAML sequence or comma-separated string" {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+func TestRendererModelFallbackRules(t *testing.T) {
+	base := Role{Name: "builder", Description: "Builds", Model: "opus", Instructions: "Build."}
+	tests := map[string][]string{
+		"claude-code": {`model: "opus"`},
+		"codex":       {`!model =`},
+		"droid":       {`model: "custom:gpt-5.5(high)"`},
+		"opencode":    {`!model:`},
+		"pi":          {`!model:`},
+		"omp":         {"model:\n  - \"opus\""},
+		"qwen-code":   {`model: "inherit"`},
+	}
+	for harness, assertions := range tests {
+		t.Run(harness, func(t *testing.T) {
+			renderer, _ := Lookup(harness)
+			got := renderer.Render(base)
+			for _, assertion := range assertions {
+				if strings.HasPrefix(assertion, "!") {
+					if strings.Contains(got, strings.TrimPrefix(assertion, "!")) {
+						t.Fatalf("unexpected %q in:\n%s", assertion[1:], got)
+					}
+					continue
+				}
+				if !strings.Contains(got, assertion) {
+					t.Fatalf("missing %q in:\n%s", assertion, got)
+				}
+			}
+		})
+	}
+}
+
+func TestLoadValidatesCanonicalRoles(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "agents")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "invalid.md"), []byte("---\nname: invalid\ndescription: Missing body\n---\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := Load(root); err == nil || !strings.Contains(err.Error(), "missing instructions") {
+		t.Fatalf("Load error = %v", err)
+	}
+}
diff --git a/internal/app/agents.go b/internal/app/agents.go
new file mode 100644
index 0000000..f328439
--- /dev/null
+++ b/internal/app/agents.go
@@ -0,0 +1,162 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/yourconscience/dotagents/internal/agentrole"
+)
+
+type renderedAgentRole struct {
+	Name    string
+	Source  string
+	Target  string
+	Content string
+}
+
+func expectedAgentRoles(repoRoot string, agent agentConfig) (map[string]renderedAgentRole, error) {
+	if agent.AgentRoot == "" {
+		return map[string]renderedAgentRole{}, nil
+	}
+
+	roles, err := agentrole.Load(repoRoot)
+	if err != nil {
+		return nil, err
+	}
+
+	rendered := make(map[string]renderedAgentRole)
+	for _, role := range roles {
+		target, content, ok := renderAgentRole(role, agent)
+		if !ok {
+			continue
+		}
+		rendered[role.Name] = renderedAgentRole{
+			Name:    role.Name,
+			Source:  role.Source,
+			Target:  target,
+			Content: content,
+		}
+	}
+	return rendered, nil
+}
+
+func renderAgentRole(role agentrole.Role, agent agentConfig) (string, string, bool) {
+	h := harnessFor(agent.Name)
+	if h == nil || h.roles == nil {
+		return "", "", false
+	}
+	if role.Model == "" && agent.RoleModel != "" {
+		role.Model = agent.RoleModel
+	}
+	target := filepath.Join(agent.AgentRoot, role.Name+h.roles.Extension())
+	return target, h.roles.Render(role), true
+}
+
+func inspectAgentRoles(report *agentReport, repoRoot string, agent agentConfig) error {
+	expected, err := expectedAgentRoles(repoRoot, agent)
+	if err != nil {
+		return err
+	}
+	if len(expected) == 0 {
+		return nil
+	}
+
+	for _, name := range sortedAgentRoleNames(expected) {
+		rendered := expected[name]
+		data, err := os.ReadFile(rendered.Target)
+		if errors.Is(err, fs.ErrNotExist) {
+			report.MissingAgent = append(report.MissingAgent, name)
+			report.AddsAgent = append(report.AddsAgent, name)
+			continue
+		}
+		if err != nil {
+			return fmt.Errorf("read %s: %w", rendered.Target, err)
+		}
+
+		if string(data) == rendered.Content {
+			report.ManagedAgent = append(report.ManagedAgent, name)
+			continue
+		}
+		if isManagedAgentFile(rendered.Target, data, repoRoot) {
+			report.DriftedAgent = append(report.DriftedAgent, name)
+			report.UpdatesAgent = append(report.UpdatesAgent, name)
+			continue
+		}
+		report.Conflicts = append(report.Conflicts, fmt.Sprintf("agent %s exists but is not dotagents-managed", rendered.Target))
+	}
+	return nil
+}
+
+func isManagedAgentFile(path string, data []byte, repoRoot string) bool {
+	if strings.Contains(string(data), agentrole.GeneratedMarker) {
+		return true
+	}
+
+	info, err := os.Lstat(path)
+	if err != nil || info.Mode()&os.ModeSymlink == 0 {
+		return false
+	}
+	rawTarget, err := os.Readlink(path)
+	if err != nil {
+		return false
+	}
+	targetAbs := absoluteTarget(path, rawTarget)
+	repoAgentsRoot := filepath.Join(repoRoot, "agents")
+	return targetAbs == repoAgentsRoot || strings.HasPrefix(targetAbs, repoAgentsRoot+string(os.PathSeparator))
+}
+
+func applyAgentRoleSync(reports []agentReport, selected []agentConfig, repoRoot string) error {
+	agentIndex := make(map[string]agentConfig, len(selected))
+	for _, agent := range selected {
+		agentIndex[agent.Name] = agent
+	}
+	for _, report := range reports {
+		if !report.Detected {
+			continue
+		}
+		agent, ok := agentIndex[report.Name]
+		if !ok || agent.AgentRoot == "" {
+			continue
+		}
+		if len(report.Conflicts) > 0 {
+			return fmt.Errorf("%s has conflicts", report.Name)
+		}
+		expected, err := expectedAgentRoles(repoRoot, agent)
+		if err != nil {
+			return err
+		}
+		if len(report.AddsAgent)+len(report.UpdatesAgent) == 0 {
+			continue
+		}
+		if err := os.MkdirAll(agent.AgentRoot, 0o755); err != nil {
+			return fmt.Errorf("create %s: %w", agent.AgentRoot, err)
+		}
+		for _, name := range append(append([]string{}, report.AddsAgent...), report.UpdatesAgent...) {
+			rendered, ok := expected[name]
+			if !ok {
+				continue
+			}
+			if err := os.Remove(rendered.Target); err != nil && !errors.Is(err, fs.ErrNotExist) {
+				return fmt.Errorf("remove %s before rewrite: %w", rendered.Target, err)
+			}
+			if err := os.WriteFile(rendered.Target, []byte(rendered.Content), 0o644); err != nil {
+				return fmt.Errorf("write %s: %w", rendered.Target, err)
+			}
+		}
+	}
+	return nil
+}
+
+func sortedAgentRoleNames(roles map[string]renderedAgentRole) []string {
+	names := make([]string, 0, len(roles))
+	for name := range roles {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
diff --git a/internal/app/agents_test.go b/internal/app/agents_test.go
new file mode 100644
index 0000000..56802b5
--- /dev/null
+++ b/internal/app/agents_test.go
@@ -0,0 +1,78 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/yourconscience/dotagents/internal/agentrole"
+)
+
+func writeAgentsFixture(t *testing.T, repoRoot, name, data string) {
+	t.Helper()
+	agentsDir := filepath.Join(repoRoot, "agents")
+	if err := os.MkdirAll(agentsDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(agentsDir, name), []byte(data), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRenderAgentRolePrefillsConfiguredModel(t *testing.T) {
+	role := agentrole.Role{Name: "builder", Description: "Builds features", Instructions: "Implement."}
+	path, content, ok := renderAgentRole(role, agentConfig{Name: agentClaudeCode, AgentRoot: t.TempDir(), RoleModel: "configured-model"})
+	if !ok {
+		t.Fatal("claude role was not rendered")
+	}
+	if !strings.Contains(content, `model: "configured-model"`) {
+		t.Fatalf("role missing configured role_model:\n%s", content)
+	}
+	if path == "" {
+		t.Fatal("empty target path")
+	}
+}
+
+func TestExpectedAgentRolesLoadsCanonicalMarkdown(t *testing.T) {
+	repoRoot := t.TempDir()
+	writeAgentsFixture(t, repoRoot, "builder.md", `---
+name: builder
+description: Builds features
+model: sonnet
+tools: Read, Grep
+---
+
+Implement the change.
+`)
+	roles, err := expectedAgentRoles(repoRoot, agentConfig{Name: agentClaudeCode, AgentRoot: t.TempDir()})
+	if err != nil {
+		t.Fatal(err)
+	}
+	role, ok := roles["builder"]
+	if !ok {
+		t.Fatalf("rendered roles = %#v", roles)
+	}
+	if !strings.Contains(role.Content, "tools: Read, Grep\n") {
+		t.Fatalf("canonical scalar tools not preserved in projection:\n%s", role.Content)
+	}
+}
+
+func TestIsManagedAgentFile(t *testing.T) {
+	repoRoot := t.TempDir()
+	managed := filepath.Join(repoRoot, "managed.toml")
+	if err := os.WriteFile(managed, []byte("# "+agentrole.GeneratedMarker+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if !isManagedAgentFile(managed, []byte("# "+agentrole.GeneratedMarker+"\n"), repoRoot) {
+		t.Fatal("generated marker should be managed")
+	}
+
+	unmanaged := filepath.Join(repoRoot, "unmanaged.toml")
+	if err := os.WriteFile(unmanaged, []byte("name = \"local\"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if isManagedAgentFile(unmanaged, []byte("name = \"local\"\n"), repoRoot) {
+		t.Fatal("unmarked real file should not be managed")
+	}
+}
diff --git a/cmd/dotagents/agentsview.go b/internal/app/agentsview.go
similarity index 99%
rename from cmd/dotagents/agentsview.go
rename to internal/app/agentsview.go
index a281c78..b3c3c03 100644
--- a/cmd/dotagents/agentsview.go
+++ b/internal/app/agentsview.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/amp_e2e_test.go b/internal/app/amp_e2e_test.go
similarity index 94%
rename from cmd/dotagents/amp_e2e_test.go
rename to internal/app/amp_e2e_test.go
index 89ad160..5460a90 100644
--- a/cmd/dotagents/amp_e2e_test.go
+++ b/internal/app/amp_e2e_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
@@ -55,7 +55,7 @@ func TestAmpSetupE2EConfiguresSkillsAndMCP(t *testing.T) {
 	configPath := filepath.Join(repoRoot, "dotagents.yaml")
 	writeAmpE2EConfig(t, configPath)
 
-	if err := run([]string{"setup", "--agents=amp", "--config", configPath}); err != nil {
+	if err := Run([]string{"setup", "--agents=amp", "--config", configPath}); err != nil {
 		t.Fatal(err)
 	}
 
@@ -83,7 +83,7 @@ func TestAmpSetupE2EConfiguresSkillsAndMCP(t *testing.T) {
 		t.Fatalf("local MCP = %#v", local)
 	}
 
-	if err := run([]string{"status", "--agents=amp", "--config", configPath}); err != nil {
+	if err := Run([]string{"status", "--agents=amp", "--config", configPath}); err != nil {
 		t.Fatal(err)
 	}
 }
@@ -104,7 +104,7 @@ func TestAmpSetupE2EPreservesExistingSettings(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	if err := run([]string{"setup", "--agents=amp", "--config", configPath}); err != nil {
+	if err := Run([]string{"setup", "--agents=amp", "--config", configPath}); err != nil {
 		t.Fatal(err)
 	}
 
diff --git a/cmd/dotagents/amp_memory_e2e_test.go b/internal/app/amp_memory_e2e_test.go
similarity index 77%
rename from cmd/dotagents/amp_memory_e2e_test.go
rename to internal/app/amp_memory_e2e_test.go
index 86ef4b6..cc94cea 100644
--- a/cmd/dotagents/amp_memory_e2e_test.go
+++ b/internal/app/amp_memory_e2e_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
@@ -10,7 +10,7 @@ import (
 	"testing"
 )
 
-func TestAmpMemoryHookE2EWritesSessionDigest(t *testing.T) {
+func TestAmpMemoryHookE2ERecognizesLegacyReplayMarker(t *testing.T) {
 	_, sourceFile, _, ok := runtime.Caller(0)
 	if !ok {
 		t.Fatal("resolve test source path")
@@ -64,30 +64,21 @@ func TestAmpMemoryHookE2EWritesSessionDigest(t *testing.T) {
 	}
 
 	out := stdout.String()
-	if !strings.Contains(out, "memsearch updated from Amp session T-amp-e2e") {
+	if !strings.Contains(out, "memory skipped replayed Amp session T-amp-e2e") {
 		t.Fatalf("unexpected hook output: %s", out)
 	}
 	digest, err := os.ReadFile(digestPath)
 	if err != nil {
 		t.Fatal(err)
 	}
-	text := string(digest)
-	for _, want := range []string{
-		existingSession,
-		"<!-- amp-session:T-amp-e2e:start -->",
-		"## Amp session 2026-05-17 01:02 - T-amp-e2e",
-		"first request: wire Amp memory",
-		"final assistant output: done",
-	} {
-		if !strings.Contains(text, want) {
-			t.Fatalf("digest missing %q:\n%s", want, text)
-		}
+	if string(digest) != existingSession {
+		t.Fatalf("replayed payload changed target digest:\n%s", digest)
 	}
 	previousDigest, err := os.ReadFile(previousDigestPath)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if strings.Contains(string(previousDigest), "amp-session:T-amp-e2e") {
-		t.Fatalf("stale same-session digest was not removed:\n%s", string(previousDigest))
+	if !strings.Contains(string(previousDigest), "amp-session:T-amp-e2e") {
+		t.Fatalf("legacy replay marker was unexpectedly removed:\n%s", previousDigest)
 	}
 }
diff --git a/internal/app/app.go b/internal/app/app.go
new file mode 100644
index 0000000..1a9d58c
--- /dev/null
+++ b/internal/app/app.go
@@ -0,0 +1,597 @@
+package app
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+)
+
+type config struct {
+	Version        int                   `yaml:"version"`
+	Agents         []agentConfig         `yaml:"agents"`
+	MCPServers     []mcpServerConfig     `yaml:"mcp_servers"`
+	ExternalSkills []externalSkillSource `yaml:"external_skills"`
+	PublishTargets []publishTarget       `yaml:"publish_targets,omitempty"`
+	Hooks          []hookConfig          `yaml:"hooks,omitempty"`
+	UI             *uiConfig             `yaml:"ui,omitempty"`
+	// ContextNoteTokens is the estimated skill-listing token threshold above
+	// which `dotagents doctor` prints a soft context advisory note. Absent
+	// (nil) uses contextNoteTokensDefault; 0 (or negative) disables the note.
+	ContextNoteTokens *int `yaml:"context_note_tokens,omitempty"`
+}
+
+type uiConfig struct {
+	Links []uiLink `yaml:"links,omitempty"`
+}
+
+type uiLink struct {
+	Name string `yaml:"name"`
+	URL  string `yaml:"url"`
+}
+
+type externalSkillSource struct {
+	URL         string   `yaml:"url"`
+	SkillDir    string   `yaml:"skill_dir,omitempty"`
+	SkillDirs   []string `yaml:"skill_dirs,omitempty"`
+	Branch      string   `yaml:"branch"`
+	Skills      []string `yaml:"skills,omitempty"`
+	Materialize bool     `yaml:"materialize,omitempty"`
+	MCP         bool     `yaml:"mcp,omitempty"`
+	MCPAgents   []string `yaml:"mcp_agents,omitempty"`
+}
+
+type agentConfig struct {
+	Name      string    `yaml:"name"`
+	Enabled   bool      `yaml:"enabled"`
+	SkillRoot string    `yaml:"skill_root"`
+	AgentRoot string    `yaml:"agent_root,omitempty"`
+	Detect    string    `yaml:"detect,omitempty"`
+	RoleModel string    `yaml:"role_model,omitempty"`
+	Packages  *[]string `yaml:"packages,omitempty"`
+}
+
+// publishTarget declares a remote skill registry to push canonical skills to.
+// It is a publish verb, not a sync entity: unlike agentConfig it has no local
+// skill_root to reconcile and no detect key. Skills is an explicit allowlist —
+// only named skills are ever uploaded, so a private or experimental skill is
+// never shipped by accident.
+type publishTarget struct {
+	Name            string   `yaml:"name"`
+	Kind            string   `yaml:"kind"`                       // registry kind; only "openai-skills" for now
+	Enabled         bool     `yaml:"enabled"`                    // default off; opt in per target
+	Skills          []string `yaml:"skills"`                     // allowlist of local skill dir names to publish
+	VersionStrategy string   `yaml:"version_strategy,omitempty"` // new-version (default) | set-default
+	APIKeyEnv       string   `yaml:"api_key_env,omitempty"`      // env var holding the key; default OPENAI_API_KEY
+}
+
+const (
+	publishKindOpenAISkills   = "openai-skills"
+	publishDefaultAPIKeyEnv   = "OPENAI_API_KEY"
+	publishStrategyNewVersion = "new-version"
+	publishStrategySetDefault = "set-default"
+)
+
+type repoLinkReport struct {
+	Path           string
+	ExpectedTarget string
+	ActualTarget   string
+	State          string
+}
+
+type agentReport struct {
+	Name            string
+	SkillRoot       string
+	AgentRoot       string
+	ExpectedSkills  map[string]string
+	Detected        bool
+	RootPath        string
+	RootExpected    string
+	RootActual      string
+	RootState       string
+	Managed         []string
+	ManagedAgent    []string
+	ManagedMCP      []string
+	ManagedHook     []string
+	ManagedPackage  []string
+	Drifted         []string
+	DriftedAgent    []string
+	DriftedMCP      []string
+	DriftedHook     []string
+	DriftedPackage  []string
+	Missing         []string
+	MissingAgent    []string
+	MissingMCP      []string
+	MissingHook     []string
+	UnsupportedHook []string
+	Conflicts       []string
+	StaleManaged    []string
+	External        []string
+	Adds            []string
+	AddsAgent       []string
+	AddsMCP         []string
+	AddsHook        []string
+	Updates         []string
+	UpdatesAgent    []string
+	UpdatesMCP      []string
+	UpdatesHook     []string
+	UpdatesPackage  []string
+	Removes         []string
+	RemovesAgent    []string
+	RemovesPackage  []string
+	Synced          bool
+}
+
+func isDetected(agent agentConfig) bool {
+	if agent.Detect == "" {
+		return true
+	}
+	executable, err := exec.LookPath(agent.Detect)
+	if err != nil {
+		return false
+	}
+	if harness := harnessFor(agent.Name); harness != nil && harness.Detect != nil {
+		return harness.Detect(executable)
+	}
+	return true
+}
+
+type runOptions struct {
+	ConfigPath     string
+	ConfigOverride *config
+	Agents         string
+	Pull           bool
+	E2E            bool
+	SkipPackageAge bool
+	MemoryTier     string
+	JSONOutput     bool
+	DryRun         bool
+	AssumeYes      bool
+	Stdin          io.Reader
+	Stdout         io.Writer
+	// ConfirmRemovals makes sync preview per-harness removals and role
+	// overwrites and ask before applying them. Set by setup-driven syncs.
+	ConfirmRemovals bool
+	// Verbose expands `status` back to the full per-surface managed and
+	// external skill lists and native root paths instead of the concise view.
+	Verbose bool
+}
+
+func Run(args []string) error {
+	if len(args) == 0 {
+		printUsage()
+		return errors.New("missing subcommand")
+	}
+
+	switch args[0] {
+	case "setup":
+		return runSetupCommand(args[1:])
+	case "status":
+		return runStatusCommand(args[1:])
+	case "sync":
+		return runSyncCommand(args[1:])
+	case "doctor":
+		return runDoctorCommand(args[1:])
+	case "config":
+		return runConfigCommand(args[1:])
+	case "view":
+		return runView(args[1:])
+	case "inspect":
+		return runInspect(args[1:])
+	case "sessions":
+		return runSessions(args[1:])
+	case "skill":
+		return runSkillCommand(args[1:])
+	case "publish":
+		return runPublishCommand(args[1:])
+	case "mcp":
+		return runMCP(args[1:])
+	case "hook":
+		return runHookCommand(args[1:])
+	case "cron":
+		opts, err := parseCronFlags(args[1:])
+		if err != nil {
+			return err
+		}
+		return runCron(opts)
+	case "pull":
+		printRenameNotice("pull", "sync --pull")
+		opts, err := parseSubcommandFlags("pull", args[1:])
+		if err != nil {
+			return err
+		}
+		return runPull(opts)
+	case "deps":
+		return runDeprecatedDeps(args[1:])
+	case "memsearch":
+		return runDeprecatedMemsearch(args[1:])
+	case "skillify":
+		printRenameNotice("skillify", "skill new")
+		return runSkillCommand(append([]string{"new"}, args[1:]...))
+	case "render":
+		printRenameNotice("render", "sync")
+		opts, err := parseSubcommandFlags("render", args[1:])
+		if err != nil {
+			return err
+		}
+		return runRender(opts)
+	case "audit":
+		printRenameNotice("audit", "doctor")
+		opts, err := parseSubcommandFlags("audit", args[1:])
+		if err != nil {
+			return err
+		}
+		return runAudit(opts)
+	case "external":
+		if len(args) > 1 && args[1] == "list" {
+			printRenameNotice("external list", "status")
+		} else if len(args) > 1 && args[1] == "update" {
+			printRenameNotice("external update", "skill update")
+		} else {
+			printRenameNotice("external", "status or skill update")
+		}
+		return runExternal(args[1:])
+	case "promote":
+		printRenameNotice("promote", "skill promote")
+		return runSkillCommand(append([]string{"promote"}, args[1:]...))
+	case "dogfood":
+		printRenameNotice("dogfood", "doctor --e2e")
+		opts, err := parseSubcommandFlags("dogfood", args[1:])
+		if err != nil {
+			return err
+		}
+		return runDogfood(opts)
+	case "help":
+		if len(args) == 1 {
+			printUsage()
+			return nil
+		}
+		if len(args) == 2 && args[1] == "--all" {
+			printAllUsage()
+			return nil
+		}
+		return errors.New("usage: dotagents help [--all]")
+	case "-h", "--help":
+		if len(args) != 1 {
+			return errors.New("usage: dotagents help [--all]")
+		}
+		printUsage()
+		return nil
+	default:
+		printUsage()
+		return fmt.Errorf("unknown subcommand %q", args[0])
+	}
+}
+
+func runSetupCommand(args []string) error {
+	if len(args) > 0 {
+		switch args[0] {
+		case "memsearch":
+			return runMemsearch(append([]string{"setup"}, args[1:]...))
+		}
+	}
+	opts, err := parseSetupFlags(args)
+	if err != nil {
+		return err
+	}
+	return runSetup(opts)
+}
+
+func runStatusCommand(args []string) error {
+	if len(args) > 0 {
+		switch args[0] {
+		case "memsearch":
+			printRenameNotice("status memsearch", "status")
+			return runMemsearch(append([]string{"status"}, args[1:]...))
+		}
+	}
+	opts, err := parseStatusFlags(args)
+	if err != nil {
+		return err
+	}
+	return runStatus(opts)
+}
+
+func parseStatusFlags(args []string) (runOptions, error) {
+	fs := flag.NewFlagSet("status", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+
+	var opts runOptions
+	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
+	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
+	fs.BoolVar(&opts.SkipPackageAge, "skip-package-age", false, "Skip external package publish-age checks")
+	fs.BoolVar(&opts.Verbose, "verbose", false, "Show full managed/external skill lists and native root paths")
+	fs.BoolVar(&opts.Verbose, "v", false, "Show full managed/external skill lists and native root paths")
+
+	if err := fs.Parse(args); err != nil {
+		return runOptions{}, err
+	}
+	if fs.NArg() != 0 {
+		return runOptions{}, errors.New("status does not accept positional arguments")
+	}
+	return opts, nil
+}
+
+func runSyncCommand(args []string) error {
+	if len(args) > 0 {
+		switch args[0] {
+		case "pull":
+			printRenameNotice("sync pull", "sync --pull")
+			opts, err := parseSubcommandFlags("sync pull", args[1:])
+			if err != nil {
+				return err
+			}
+			return runPull(opts)
+		case "deps":
+			opts, err := parseDepsFlags("sync deps", args[1:])
+			if err != nil {
+				return err
+			}
+			return runDepsUpdate(opts)
+		case "render":
+			printRenameNotice("sync render", "sync")
+			opts, err := parseSubcommandFlags("sync render", args[1:])
+			if err != nil {
+				return err
+			}
+			return runRender(opts)
+		}
+	}
+	opts, err := parseSyncFlags(args)
+	if err != nil {
+		return err
+	}
+	if opts.Pull {
+		opts.Pull = false
+		return runPull(opts)
+	}
+	return runSync(opts)
+}
+
+func runDoctorCommand(args []string) error {
+	if len(args) > 0 {
+		switch args[0] {
+		case "audit":
+			opts, err := parseSubcommandFlags("doctor audit", args[1:])
+			if err != nil {
+				return err
+			}
+			return runAudit(opts)
+		case "deps":
+			opts, err := parseDepsFlags("doctor deps", args[1:])
+			if err != nil {
+				return err
+			}
+			return runDepsCheck(opts)
+		case "dogfood":
+			printRenameNotice("doctor dogfood", "doctor --e2e")
+			opts, err := parseSubcommandFlags("doctor dogfood", args[1:])
+			if err != nil {
+				return err
+			}
+			return runDogfood(opts)
+		}
+	}
+	opts, err := parseDoctorFlags(args)
+	if err != nil {
+		return err
+	}
+	if opts.E2E {
+		opts.E2E = false
+		return runDogfood(opts)
+	}
+	return runDoctor(opts)
+}
+
+func runSkillCommand(args []string) error {
+	if len(args) == 0 {
+		return errors.New("skill requires subcommand: new, list, info, update, promote")
+	}
+	switch args[0] {
+	case "new":
+		return runSkillify(args[1:])
+	case "update":
+		return runExternalUpdate(args[1:])
+	case "list":
+		return runSkillList(args[1:])
+	case "info":
+		return runSkillInfo(args[1:])
+	case "promote":
+		return runPromote(args[1:])
+	case "external":
+		if len(args) > 1 && args[1] == "list" {
+			printRenameNotice("skill external list", "status")
+		} else if len(args) > 1 && args[1] == "update" {
+			printRenameNotice("skill external update", "skill update")
+		} else {
+			printRenameNotice("skill external", "status or skill update")
+		}
+		return runExternal(args[1:])
+	default:
+		return fmt.Errorf("unknown skill subcommand %q", args[0])
+	}
+}
+
+func runDeprecatedDeps(args []string) error {
+	if len(args) > 0 {
+		switch args[0] {
+		case "check":
+			printRenameNotice("deps check", "doctor deps")
+			return runDoctorCommand(append([]string{"deps"}, args[1:]...))
+		case "update":
+			printRenameNotice("deps update", "sync deps")
+			return runSyncCommand(append([]string{"deps"}, args[1:]...))
+		}
+	}
+	printRenameNotice("deps", "doctor deps or sync deps")
+	return runDeps(args)
+}
+
+func runDeprecatedMemsearch(args []string) error {
+	if len(args) > 0 {
+		switch args[0] {
+		case "setup":
+			printRenameNotice("memsearch setup", "setup memsearch")
+			return runSetupCommand(append([]string{"memsearch"}, args[1:]...))
+		case "status":
+			printRenameNotice("memsearch status", "status memsearch")
+			return runStatusCommand(append([]string{"memsearch"}, args[1:]...))
+		}
+	}
+	printRenameNotice("memsearch", "setup memsearch or status memsearch")
+	return runMemsearch(args)
+}
+
+func printRenameNotice(oldCommand string, newCommand string) {
+	fmt.Fprintf(os.Stderr, "dotagents: %q was renamed to %q\n", oldCommand, newCommand)
+}
+
+func parseSubcommandFlags(name string, args []string) (runOptions, error) {
+	fs := flag.NewFlagSet(name, flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+
+	var opts runOptions
+	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
+	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
+	fs.BoolVar(&opts.SkipPackageAge, "skip-package-age", false, "Skip external package publish-age checks")
+
+	if err := fs.Parse(args); err != nil {
+		return runOptions{}, err
+	}
+	if fs.NArg() != 0 {
+		return runOptions{}, fmt.Errorf("%s does not accept positional arguments", name)
+	}
+
+	return opts, nil
+}
+
+func parseSetupFlags(args []string) (runOptions, error) {
+	fs := flag.NewFlagSet("setup", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+	var opts runOptions
+	opts.MemoryTier = memoryTierBasic
+	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
+	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
+	fs.StringVar(&opts.MemoryTier, "memory", memoryTierBasic, "Memory tier: off, basic, or memsearch")
+	fs.BoolVar(&opts.JSONOutput, "json", false, "Emit detection result as JSON and exit")
+	fs.BoolVar(&opts.DryRun, "dry-run", false, "Show detected import candidates and exit without changes (overrides --yes)")
+	fs.BoolVar(&opts.AssumeYes, "yes", false, "Import all detected items without prompting")
+	if err := fs.Parse(args); err != nil {
+		return runOptions{}, err
+	}
+	if fs.NArg() != 0 {
+		return runOptions{}, errors.New("setup does not accept positional arguments")
+	}
+	return opts, nil
+}
+
+func parseSyncFlags(args []string) (runOptions, error) {
+	fs := flag.NewFlagSet("sync", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+	var opts runOptions
+	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
+	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
+	fs.BoolVar(&opts.Pull, "pull", false, "Pull the repo before syncing")
+	if err := fs.Parse(args); err != nil {
+		return runOptions{}, err
+	}
+	if fs.NArg() != 0 {
+		return runOptions{}, errors.New("sync does not accept positional arguments")
+	}
+	return opts, nil
+}
+
+func parseDoctorFlags(args []string) (runOptions, error) {
+	fs := flag.NewFlagSet("doctor", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+	var opts runOptions
+	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
+	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names to use for this run")
+	fs.BoolVar(&opts.E2E, "e2e", false, "Run sync, status, and doctor end to end")
+	fs.BoolVar(&opts.SkipPackageAge, "skip-package-age", false, "Skip external package publish-age checks")
+	if err := fs.Parse(args); err != nil {
+		return runOptions{}, err
+	}
+	if fs.NArg() != 0 {
+		return runOptions{}, errors.New("doctor does not accept positional arguments")
+	}
+	return opts, nil
+}
+
+func parseCronFlags(args []string) (cronOptions, error) {
+	fs := flag.NewFlagSet("cron", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+
+	var opts cronOptions
+	fs.StringVar(&opts.ConfigPath, "config", "", "Path to dotagents YAML config")
+	fs.StringVar(&opts.Agents, "agents", "", "Comma-separated agent names")
+	fs.BoolVar(&opts.Remove, "remove", false, "Remove the cron entry instead of installing")
+	fs.BoolVar(&opts.Deps, "deps", false, "Install dependency maintenance cron instead of auto-pull")
+	fs.StringVar(&opts.Interval, "interval", cronIntervalDefault, "Pull interval: 5m, 15m, 30m, 1h, 6h, 12h, daily, weekly")
+
+	if err := fs.Parse(args); err != nil {
+		return cronOptions{}, err
+	}
+	return opts, nil
+}
+
+func printUsage() {
+	fmt.Println("dotagents - manage shared skills, MCP, and canonical config")
+	fmt.Println()
+	fmt.Println("Commands:")
+	fmt.Println("  setup    Set up this machine and sync configured harnesses")
+	fmt.Println("  status   Show harness, external lock, and memsearch state")
+	fmt.Println("  sync     Regenerate committed artifacts and reconcile harnesses")
+	fmt.Println("  doctor   Check pins, dependencies, and local health")
+	fmt.Println("  config   Author the canonical YAML in an interactive TUI")
+	fmt.Println("  view     Author the canonical YAML in a loopback web UI (browser)")
+	fmt.Println()
+	fmt.Println("Supported integrations:")
+	fmt.Println("  inspect  Launch HarnessKit for cross-harness configuration inspection")
+	fmt.Println("  sessions Launch AgentsView for session search, telemetry, and usage")
+	fmt.Println()
+	fmt.Println("Command groups:")
+	fmt.Println("  skill    Inspect, create, update, and promote skills")
+	fmt.Println("  publish  Push canonical skills to a remote skill registry")
+	fmt.Println("  mcp      Manage MCP servers")
+	fmt.Println("  hook     Review and remove native hook registrations")
+	fmt.Println()
+	fmt.Println("Run \"dotagents help --all\" for flags, maintenance commands, and compatibility aliases.")
+}
+
+func printAllUsage() {
+	printUsage()
+	fmt.Println()
+	fmt.Println("Canonical forms:")
+	fmt.Println("  dotagents setup [--memory off|basic|memsearch] [--agents ...] [--yes] [--dry-run] [--json]")
+	fmt.Println("  dotagents status [--verbose] [--agents ...]")
+	fmt.Println("  dotagents sync [--pull] [--agents ...]")
+	fmt.Println("  dotagents doctor [--e2e] [--agents ...]")
+	fmt.Println("  dotagents config [validate|print] [--config PATH]")
+	fmt.Println("  dotagents view [--addr 127.0.0.1:8765] [--no-open] [--secure-cookie] [--ssh-host user@host] [--token-file PATH]")
+	fmt.Println("  dotagents inspect [--no-open] [--ssh-host user@host] [hk serve flags: --port N, --host ADDR, --no-token]")
+	fmt.Println("  dotagents sessions [--no-open] [--ssh-host user@host] [agentsview serve flags: --port N, --host ADDR, --no-sync]")
+	fmt.Println("  dotagents skill new <name> [--description ...]")
+	fmt.Println("  dotagents skill list [--agents ...]")
+	fmt.Println("  dotagents skill info <name>")
+	fmt.Println("  dotagents skill update [name ...]")
+	fmt.Println("  dotagents skill promote <name-or-path> [--dry-run]")
+	fmt.Println("  dotagents publish [--target NAME] [--skills a,b] [--dry-run] [--json] [--yes]")
+	fmt.Println("  dotagents mcp <list|add|import|remove> [options]")
+	fmt.Println("  dotagents hook list [--agents ...] [query]")
+	fmt.Println("  dotagents hook remove [--dry-run] [--agents ...] <query>")
+	fmt.Println()
+	fmt.Println("Maintenance and compatibility aliases:")
+	fmt.Println("  dotagents cron [--interval 30m|--deps|--remove]")
+	fmt.Println("  dotagents deps <check|update> [options]")
+	fmt.Println("  dotagents memsearch <setup|status> [options]")
+	fmt.Println("  dotagents pull [options]")
+	fmt.Println("  dotagents render [options]")
+	fmt.Println("  dotagents audit [options]")
+	fmt.Println("  dotagents external <list|update> [name ...]")
+	fmt.Println("  dotagents skillify <name> [options]")
+	fmt.Println("  dotagents promote <name-or-path> [--dry-run]")
+	fmt.Println("  dotagents dogfood [options]")
+}
diff --git a/cmd/dotagents/audit.go b/internal/app/audit.go
similarity index 99%
rename from cmd/dotagents/audit.go
rename to internal/app/audit.go
index ce41250..eef9f84 100644
--- a/cmd/dotagents/audit.go
+++ b/internal/app/audit.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/audit_cmd.go b/internal/app/audit_cmd.go
similarity index 99%
rename from cmd/dotagents/audit_cmd.go
rename to internal/app/audit_cmd.go
index 0edd186..9553050 100644
--- a/cmd/dotagents/audit_cmd.go
+++ b/internal/app/audit_cmd.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
diff --git a/cmd/dotagents/audit_test.go b/internal/app/audit_test.go
similarity index 99%
rename from cmd/dotagents/audit_test.go
rename to internal/app/audit_test.go
index 868c02e..563217c 100644
--- a/cmd/dotagents/audit_test.go
+++ b/internal/app/audit_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/cli_launch_test.go b/internal/app/cli_launch_test.go
similarity index 91%
rename from cmd/dotagents/cli_launch_test.go
rename to internal/app/cli_launch_test.go
index 47a6ab5..89aff4e 100644
--- a/cmd/dotagents/cli_launch_test.go
+++ b/internal/app/cli_launch_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
@@ -60,9 +60,9 @@ func TestCanonicalCLIRoutesToCommandFamilies(t *testing.T) {
 
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			_, _, err := captureCLIOutput(t, func() error { return run(tc.args) })
+			_, _, err := captureCLIOutput(t, func() error { return Run(tc.args) })
 			if err == nil || err.Error() != tc.wantErr {
-				t.Fatalf("run(%q) error = %v, want %q", tc.args, err, tc.wantErr)
+				t.Fatalf("Run(%q) error = %v, want %q", tc.args, err, tc.wantErr)
 			}
 		})
 	}
@@ -89,18 +89,18 @@ func TestHiddenAliasesRouteWithOneRenameNotice(t *testing.T) {
 
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			_, stderr, err := captureCLIOutput(t, func() error { return run(tc.args) })
+			_, stderr, err := captureCLIOutput(t, func() error { return Run(tc.args) })
 			if err == nil {
-				t.Fatalf("run(%q) unexpectedly succeeded", tc.args)
+				t.Fatalf("Run(%q) unexpectedly succeeded", tc.args)
 			}
 			if tc.wantErr != "" && err.Error() != tc.wantErr {
-				t.Fatalf("run(%q) error = %q, want %q", tc.args, err, tc.wantErr)
+				t.Fatalf("Run(%q) error = %q, want %q", tc.args, err, tc.wantErr)
 			}
 			if tc.containsErr != "" && !strings.Contains(err.Error(), tc.containsErr) {
-				t.Fatalf("run(%q) error = %q, want substring %q", tc.args, err, tc.containsErr)
+				t.Fatalf("Run(%q) error = %q, want substring %q", tc.args, err, tc.containsErr)
 			}
 			if strings.Count(stderr, "dotagents: ") != 1 || !strings.Contains(stderr, tc.notice+"\n") {
-				t.Fatalf("run(%q) rename output = %q, want exactly one %q notice", tc.args, stderr, tc.notice)
+				t.Fatalf("Run(%q) rename output = %q, want exactly one %q notice", tc.args, stderr, tc.notice)
 			}
 		})
 	}
@@ -123,7 +123,7 @@ external_skills:
 `))
 
 	_, canonicalStderr, canonicalErr := captureCLIOutput(t, func() error {
-		return run([]string{"skill", "update", "missing"})
+		return Run([]string{"skill", "update", "missing"})
 	})
 	const wantErr = `unknown external source "missing"; configured: catalog`
 	if canonicalErr == nil || canonicalErr.Error() != wantErr {
@@ -134,7 +134,7 @@ external_skills:
 	}
 
 	_, legacyStderr, legacyErr := captureCLIOutput(t, func() error {
-		return run([]string{"external", "update", "missing"})
+		return Run([]string{"external", "update", "missing"})
 	})
 	if legacyErr == nil || legacyErr.Error() != wantErr {
 		t.Fatalf("external update error = %v, want routed error %q", legacyErr, wantErr)
@@ -147,7 +147,7 @@ external_skills:
 
 func TestRootHelpAdvertisesCanonicalDescriptiveFamilies(t *testing.T) {
 	stdout, stderr, err := captureCLIOutput(t, func() error {
-		return run([]string{"--help"})
+		return Run([]string{"--help"})
 	})
 	if err != nil {
 		t.Fatal(err)
diff --git a/cmd/dotagents/codex_layout_test.go b/internal/app/codex_layout_test.go
similarity index 95%
rename from cmd/dotagents/codex_layout_test.go
rename to internal/app/codex_layout_test.go
index 05b8590..387658a 100644
--- a/cmd/dotagents/codex_layout_test.go
+++ b/internal/app/codex_layout_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
@@ -31,7 +31,7 @@ Review the change.
 	writeSyncTestFile(t, filepath.Join(repoRoot, "skills", "sample", "SKILL.md"), []byte("---\nname: sample\n---\n"))
 	writeSyncTestFile(t, filepath.Join(repoRoot, "README.md"), []byte("# Skills\n\n"+readmeSkillsBeginMarker+"\n0 skills ship with this repo:\n\n``\n"+readmeSkillsEndMarker+"\n"))
 
-	if err := run([]string{"sync", "render"}); err != nil {
+	if err := Run([]string{"sync", "render"}); err != nil {
 		t.Fatal(err)
 	}
 	data, err := os.ReadFile(filepath.Join(repoRoot, "README.md"))
diff --git a/cmd/dotagents/config.go b/internal/app/config.go
similarity index 99%
rename from cmd/dotagents/config.go
rename to internal/app/config.go
index 868ddb6..c5fdc45 100644
--- a/cmd/dotagents/config.go
+++ b/internal/app/config.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/config_document.go b/internal/app/config_document.go
similarity index 99%
rename from cmd/dotagents/config_document.go
rename to internal/app/config_document.go
index 6164227..1a42c0b 100644
--- a/cmd/dotagents/config_document.go
+++ b/internal/app/config_document.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
diff --git a/cmd/dotagents/config_document_test.go b/internal/app/config_document_test.go
similarity index 99%
rename from cmd/dotagents/config_document_test.go
rename to internal/app/config_document_test.go
index 42ca69a..5c0cb4f 100644
--- a/cmd/dotagents/config_document_test.go
+++ b/internal/app/config_document_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
diff --git a/cmd/dotagents/config_tui.go b/internal/app/config_tui.go
similarity index 99%
rename from cmd/dotagents/config_tui.go
rename to internal/app/config_tui.go
index d8ab8ee..36f295c 100644
--- a/cmd/dotagents/config_tui.go
+++ b/internal/app/config_tui.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/config_web.go b/internal/app/config_web.go
similarity index 99%
rename from cmd/dotagents/config_web.go
rename to internal/app/config_web.go
index 17ca3e3..7398c9e 100644
--- a/cmd/dotagents/config_web.go
+++ b/internal/app/config_web.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"crypto/rand"
diff --git a/cmd/dotagents/config_web_token_test.go b/internal/app/config_web_token_test.go
similarity index 99%
rename from cmd/dotagents/config_web_token_test.go
rename to internal/app/config_web_token_test.go
index b6e079b..e84befd 100644
--- a/cmd/dotagents/config_web_token_test.go
+++ b/internal/app/config_web_token_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/config_worktree_test.go b/internal/app/config_worktree_test.go
similarity index 99%
rename from cmd/dotagents/config_worktree_test.go
rename to internal/app/config_worktree_test.go
index 2b1376a..af46933 100644
--- a/cmd/dotagents/config_worktree_test.go
+++ b/internal/app/config_worktree_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/context_cost.go b/internal/app/context_cost.go
similarity index 99%
rename from cmd/dotagents/context_cost.go
rename to internal/app/context_cost.go
index 5b786ef..8043bbf 100644
--- a/cmd/dotagents/context_cost.go
+++ b/internal/app/context_cost.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/context_cost_test.go b/internal/app/context_cost_test.go
similarity index 99%
rename from cmd/dotagents/context_cost_test.go
rename to internal/app/context_cost_test.go
index 8c02f6d..6527fad 100644
--- a/cmd/dotagents/context_cost_test.go
+++ b/internal/app/context_cost_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/deps.go b/internal/app/deps.go
similarity index 99%
rename from cmd/dotagents/deps.go
rename to internal/app/deps.go
index fdf719a..c337442 100644
--- a/cmd/dotagents/deps.go
+++ b/internal/app/deps.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/detect.go b/internal/app/detect.go
similarity index 87%
rename from cmd/dotagents/detect.go
rename to internal/app/detect.go
index d113377..1cfa002 100644
--- a/cmd/dotagents/detect.go
+++ b/internal/app/detect.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"crypto/sha256"
@@ -12,48 +12,48 @@ import (
 	"strings"
 )
 
-// DetectedSource records where an item was found.
-type DetectedSource struct {
+// detectedSource records where an item was found.
+type detectedSource struct {
 	Harness string `json:"harness"`
 	Path    string `json:"path"`
 	Hash    string `json:"hash"`
 }
 
-// DetectedItem is a unified representation of a skill, role, or MCP server
+// detectedItem is a unified representation of a skill, role, or MCP server
 // found in one or more harness configs that is NOT already managed by
 // dotagents. Managed items (symlinks, owned roles, configured MCP) are
 // pre-filtered during detection. Hooks are excluded: they flow FROM
 // dotagents.yaml INTO harnesses, not the other direction.
-type DetectedItem struct {
+type detectedItem struct {
 	Surface   string           `json:"surface"`
 	Name      string           `json:"name"`
-	Sources   []DetectedSource `json:"sources"`
+	Sources   []detectedSource `json:"sources"`
 	Identical bool             `json:"identical"`
 }
 
-// DetectionResult is the output of runDetection, suitable for JSON serialization.
+// detectionResult is the output of runDetection, suitable for JSON serialization.
 // Resolved holds items identical across all sources; they are auto-promoted to
 // shared without review. AutoResolved is len(Resolved), kept for JSON consumers.
-type DetectionResult struct {
+type detectionResult struct {
 	Harnesses    []string       `json:"harnesses"`
-	Items        []DetectedItem `json:"items"`
-	Resolved     []DetectedItem `json:"resolved,omitempty"`
+	Items        []detectedItem `json:"items"`
+	Resolved     []detectedItem `json:"resolved,omitempty"`
 	AutoResolved int            `json:"auto_resolved"`
 }
 
 // runDetection scans all detected harnesses for non-managed skills, roles, and
 // MCP servers. Items already in the canonical config root or identical across
 // all sources are counted as auto-resolved and excluded from Items.
-func runDetection(cfg config, detected []agentConfig, repoRoot string, home string) (*DetectionResult, error) {
+func runDetection(cfg config, detected []agentConfig, repoRoot string, home string) (*detectionResult, error) {
 	canonicalSkills := filepath.Join(repoRoot, "skills")
 	canonicalAgents := filepath.Join(repoRoot, "agents")
 
-	result := &DetectionResult{}
+	result := &detectionResult{}
 	for _, agent := range detected {
 		result.Harnesses = append(result.Harnesses, agent.Name)
 	}
 
-	itemIndex := make(map[string]*DetectedItem)
+	itemIndex := make(map[string]*detectedItem)
 	key := func(surface, name string) string { return surface + ":" + name }
 
 	for _, agent := range detected {
@@ -68,10 +68,10 @@ func runDetection(cfg config, detected []agentConfig, repoRoot string, home stri
 			k := key("skill", s.Name)
 			item, ok := itemIndex[k]
 			if !ok {
-				item = &DetectedItem{Surface: "skill", Name: s.Name}
+				item = &detectedItem{Surface: "skill", Name: s.Name}
 				itemIndex[k] = item
 			}
-			item.Sources = append(item.Sources, DetectedSource{
+			item.Sources = append(item.Sources, detectedSource{
 				Harness: agent.Name,
 				Path:    s.Path,
 				Hash:    s.Hash,
@@ -86,10 +86,10 @@ func runDetection(cfg config, detected []agentConfig, repoRoot string, home stri
 			k := key("role", r.Name)
 			item, ok := itemIndex[k]
 			if !ok {
-				item = &DetectedItem{Surface: "role", Name: r.Name}
+				item = &detectedItem{Surface: "role", Name: r.Name}
 				itemIndex[k] = item
 			}
-			item.Sources = append(item.Sources, DetectedSource{
+			item.Sources = append(item.Sources, detectedSource{
 				Harness: agent.Name,
 				Path:    r.Path,
 				Hash:    r.Hash,
@@ -104,10 +104,10 @@ func runDetection(cfg config, detected []agentConfig, repoRoot string, home stri
 			k := key("mcp", m.Name)
 			item, ok := itemIndex[k]
 			if !ok {
-				item = &DetectedItem{Surface: "mcp", Name: m.Name}
+				item = &detectedItem{Surface: "mcp", Name: m.Name}
 				itemIndex[k] = item
 			}
-			item.Sources = append(item.Sources, DetectedSource{
+			item.Sources = append(item.Sources, detectedSource{
 				Harness: agent.Name,
 				Path:    m.Path,
 				Hash:    m.Hash,
@@ -183,7 +183,7 @@ func detectNativeSkills(agent agentConfig, skillRoot string, canonicalSkills str
 
 func detectNativeRoles(agent agentConfig, agentRoot string, canonicalAgents string) ([]detectedEntry, error) {
 	h := harnessFor(agent.Name)
-	if h == nil || h.Roles == nil || agentRoot == "" {
+	if h == nil || h.roles == nil || agentRoot == "" {
 		return nil, nil
 	}
 	entries, err := os.ReadDir(agentRoot)
@@ -195,7 +195,7 @@ func detectNativeRoles(agent agentConfig, agentRoot string, canonicalAgents stri
 	}
 	var out []detectedEntry
 	for _, entry := range entries {
-		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || filepath.Ext(entry.Name()) != h.Roles.Extension {
+		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || filepath.Ext(entry.Name()) != h.roles.Extension() {
 			continue
 		}
 		path := filepath.Join(agentRoot, entry.Name())
@@ -206,7 +206,7 @@ func detectNativeRoles(agent agentConfig, agentRoot string, canonicalAgents stri
 		if isManagedAgentFile(path, data, filepath.Dir(filepath.Dir(canonicalAgents))) {
 			continue
 		}
-		name := normalizeAgentName(strings.TrimSuffix(entry.Name(), h.Roles.Extension))
+		name := normalizeAgentName(strings.TrimSuffix(entry.Name(), h.roles.Extension()))
 		hash := hashBytes(data)
 		out = append(out, detectedEntry{Name: name, Path: path, Hash: hash})
 	}
@@ -240,7 +240,7 @@ func detectNativeMCPServers(agent agentConfig, cfg config, home string) ([]detec
 	return out, nil
 }
 
-func markIdentical(item *DetectedItem) {
+func markIdentical(item *detectedItem) {
 	if len(item.Sources) < 2 {
 		item.Identical = false
 		return
diff --git a/cmd/dotagents/detect_test.go b/internal/app/detect_test.go
similarity index 96%
rename from cmd/dotagents/detect_test.go
rename to internal/app/detect_test.go
index 5482410..0a2f3e4 100644
--- a/cmd/dotagents/detect_test.go
+++ b/internal/app/detect_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
@@ -56,8 +56,8 @@ func TestHashDirDiffersOnContent(t *testing.T) {
 }
 
 func TestMarkIdenticalSingleSource(t *testing.T) {
-	item := &DetectedItem{
-		Sources: []DetectedSource{{Hash: "abc123"}},
+	item := &detectedItem{
+		Sources: []detectedSource{{Hash: "abc123"}},
 	}
 	markIdentical(item)
 	if item.Identical {
@@ -66,8 +66,8 @@ func TestMarkIdenticalSingleSource(t *testing.T) {
 }
 
 func TestMarkIdenticalMatching(t *testing.T) {
-	item := &DetectedItem{
-		Sources: []DetectedSource{
+	item := &detectedItem{
+		Sources: []detectedSource{
 			{Harness: "claude-code", Hash: "abc123"},
 			{Harness: "codex", Hash: "abc123"},
 		},
@@ -79,8 +79,8 @@ func TestMarkIdenticalMatching(t *testing.T) {
 }
 
 func TestMarkIdenticalDiffering(t *testing.T) {
-	item := &DetectedItem{
-		Sources: []DetectedSource{
+	item := &detectedItem{
+		Sources: []detectedSource{
 			{Harness: "claude-code", Hash: "abc123"},
 			{Harness: "codex", Hash: "def456"},
 		},
diff --git a/cmd/dotagents/doctor.go b/internal/app/doctor.go
similarity index 99%
rename from cmd/dotagents/doctor.go
rename to internal/app/doctor.go
index 6d53cc5..26a2ec7 100644
--- a/cmd/dotagents/doctor.go
+++ b/internal/app/doctor.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bufio"
@@ -12,6 +12,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/yourconscience/dotagents/internal/agentrole"
 	"gopkg.in/yaml.v3"
 )
 
@@ -55,7 +56,7 @@ func runDoctor(opts runOptions) error {
 	results = append(results, checkSkillSpec(repoRoot))
 	results = append(results, checkAgentRoles(repoRoot))
 	for _, name := range sortedHarnessNames() {
-		for _, check := range getHarnesses()[name].DoctorChecks {
+		for _, check := range getHarnesses()[name].doctorChecks {
 			results = append(results, check.Run(repoRoot, home, cfg))
 		}
 	}
@@ -162,7 +163,7 @@ func printContextNotes(cfg config, repoRoot string, home string, selected []agen
 }
 
 func checkAgentRoles(repoRoot string) checkResult {
-	roles, err := loadAgentRoles(repoRoot)
+	roles, err := agentrole.Load(repoRoot)
 	if err != nil {
 		return checkResult{"agent roles", checkStatusFail, err.Error()}
 	}
diff --git a/cmd/dotagents/doctor_test.go b/internal/app/doctor_test.go
similarity index 99%
rename from cmd/dotagents/doctor_test.go
rename to internal/app/doctor_test.go
index 9c85279..d9e34e5 100644
--- a/cmd/dotagents/doctor_test.go
+++ b/internal/app/doctor_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/dogfood.go b/internal/app/dogfood.go
similarity index 97%
rename from cmd/dotagents/dogfood.go
rename to internal/app/dogfood.go
index f844d3a..3230cfd 100644
--- a/cmd/dotagents/dogfood.go
+++ b/internal/app/dogfood.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/external.go b/internal/app/external.go
similarity index 99%
rename from cmd/dotagents/external.go
rename to internal/app/external.go
index f3a3fd6..2516ea6 100644
--- a/cmd/dotagents/external.go
+++ b/internal/app/external.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"crypto/sha256"
diff --git a/cmd/dotagents/external_cli.go b/internal/app/external_cli.go
similarity index 99%
rename from cmd/dotagents/external_cli.go
rename to internal/app/external_cli.go
index 4e671a3..85d39e4 100644
--- a/cmd/dotagents/external_cli.go
+++ b/internal/app/external_cli.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/external_test.go b/internal/app/external_test.go
similarity index 99%
rename from cmd/dotagents/external_test.go
rename to internal/app/external_test.go
index bfdb9ba..4fda3c2 100644
--- a/cmd/dotagents/external_test.go
+++ b/internal/app/external_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
diff --git a/cmd/dotagents/harness.go b/internal/app/harness.go
similarity index 79%
rename from cmd/dotagents/harness.go
rename to internal/app/harness.go
index f157eac..73e8dda 100644
--- a/cmd/dotagents/harness.go
+++ b/internal/app/harness.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
@@ -7,82 +7,78 @@ import (
 	"path/filepath"
 	"sort"
 	"sync"
+
+	"github.com/yourconscience/dotagents/internal/agentrole"
 )
 
-// SkillsKind describes how an agent discovers skills from dotagents.
-type SkillsKind int
+// skillsKind describes how an agent discovers skills from dotagents.
+type skillsKind int
 
 const (
-	// SkillsSymlink means dotagents creates symlinks in the agent's skill root.
-	SkillsSymlink SkillsKind = iota
-	// SkillsConfigDriven means the agent reads skills from a config-driven
+	// skillsSymlink means dotagents creates symlinks in the agent's skill root.
+	skillsSymlink skillsKind = iota
+	// skillsConfigDriven means the agent reads skills from a config-driven
 	// shared path (e.g. Amp's amp.skills.path or Hermes' skills.external_dirs).
 	// Inspect and setup are handled by custom functions on the harness.
-	SkillsConfigDriven
+	skillsConfigDriven
 )
 
-// RolesCapability describes how agent roles are rendered for this harness.
-type RolesCapability struct {
-	Extension string                      // file extension including dot: ".md", ".toml"
-	Render    func(role agentRole) string // render role to file content
-}
-
-// RootInstructionsCapability describes a root instructions symlink the agent needs.
-type RootInstructionsCapability struct {
+// rootInstructionsCapability describes a root instructions symlink the agent needs.
+type rootInstructionsCapability struct {
 	Path     func(home string) string     // symlink path, e.g. ~/.factory/AGENTS.md
 	Expected func(repoRoot string) string // target path, e.g. <config-root>/AGENTS.md
 }
 
-// DoctorCheck is a named health check contributed by a harness.
-type DoctorCheck struct {
+// doctorCheck is a named health check contributed by a harness.
+type doctorCheck struct {
 	Name string
 	Run  func(repoRoot, home string, cfg config) checkResult
 }
 
-// InspectSkillsFunc is the signature for config-driven skill inspection.
-// Only used when Skills == SkillsConfigDriven.
-type InspectSkillsFunc func(agent agentConfig, expected map[string]string, agentsSkillRoot string, cfg config, home string) (agentReport, error)
+// inspectSkillsFunc is the signature for config-driven skill inspection.
+// Only used when Skills == skillsConfigDriven.
+type inspectSkillsFunc func(agent agentConfig, expected map[string]string, agentsSkillRoot string, cfg config, home string) (agentReport, error)
 
-// SetupFunc is the signature for agent-specific config patching during setup.
-type SetupFunc func(home string, repoRoot string, cfg config) (bool, error)
+// setupFunc is the signature for agent-specific config patching during setup.
+type setupFunc func(home string, repoRoot string, cfg config) (bool, error)
 
-// Harness is the central descriptor for a coding agent integration.
+// harness is the central descriptor for a coding agent integration.
 // All feature dispatch reads capability fields instead of switching on agent names.
-type Harness struct {
+type harness struct {
 	// Detect validates an executable after the generic PATH lookup.
 	// nil means the executable's presence is sufficient.
 	Detect func(executable string) bool
 
 	// Skills integration mode.
-	Skills SkillsKind
+	Skills skillsKind
 	// InspectSkills is called instead of the generic symlink inspector
-	// when Skills == SkillsConfigDriven.
-	InspectSkills InspectSkillsFunc
+	// when Skills == skillsConfigDriven.
+	InspectSkills inspectSkillsFunc
 	// SkillsNativeRoot, when non-nil and returning true, marks that this
 	// harness reads dotagents skills directly from the config root, so no
-	// per-harness skill mirror is created. Only consulted for SkillsSymlink
+	// per-harness skill mirror is created. Only consulted for skillsSymlink
 	// harnesses.
 	SkillsNativeRoot func(repoRoot string, home string) bool
 	// Setup patches the agent's config during `dotagents setup`.
 	// nil means no patching needed.
-	Setup SetupFunc
+	Setup setupFunc
 
 	// MCP holds the MCP config target. nil = no MCP support.
 	MCP *mcpTarget
-	// Roles holds the agent role rendering capability. nil = no role support.
-	Roles *RolesCapability
+	// roles holds the agent role rendering capability. nil = no role support.
+	roles agentrole.Renderer
 	// Hooks holds the hook config target. nil = no hook support.
 	Hooks *hookTarget
 
 	// RootInstructions describes a root instructions symlink. nil = none.
-	RootInstructions *RootInstructionsCapability
+	RootInstructions *rootInstructionsCapability
 
 	// IntegrationNote is printed in status/sync reports for this agent.
 	// Empty string = no note.
 	IntegrationNote string
 
-	// DoctorChecks are agent-specific health checks appended to `dotagents doctor`.
-	DoctorChecks []DoctorCheck
+	// doctorChecks are agent-specific health checks appended to `dotagents doctor`.
+	doctorChecks []doctorCheck
 
 	// TrailerExample is the Co-authored-by trailer this agent's bot produces.
 	// Used by commit-msg hook tests to validate coverage.
@@ -91,13 +87,13 @@ type Harness struct {
 
 // harnesses maps agent name to its harness descriptor.
 // Built at init time with current behavior encoded declaratively.
-var harnesses map[string]*Harness
+var harnesses map[string]*harness
 var harnessesOnce sync.Once
 
 func initHarnesses() {
-	harnesses = map[string]*Harness{
+	harnesses = map[string]*harness{
 		"amp": {
-			Skills: SkillsConfigDriven,
+			Skills: skillsConfigDriven,
 			InspectSkills: func(agent agentConfig, expected map[string]string, agentsSkillRoot string, cfg config, home string) (agentReport, error) {
 				return inspectAmpAgent(agent, expected, agentsSkillRoot, cfg, home)
 			},
@@ -112,7 +108,7 @@ func initHarnesses() {
 				read:       readJSONMCPServer,
 				rootKey:    "amp.mcpServers",
 			}),
-			RootInstructions: &RootInstructionsCapability{
+			RootInstructions: &rootInstructionsCapability{
 				Path:     func(home string) string { return filepath.Join(home, ".config", "amp", "AGENTS.md") },
 				Expected: func(repoRoot string) string { return filepath.Join(repoRoot, "AGENTS.md") },
 			},
@@ -121,7 +117,7 @@ func initHarnesses() {
 		},
 
 		"claude-code": {
-			Skills: SkillsSymlink,
+			Skills: skillsSymlink,
 			MCP: mcpTargetPtr(mcpTarget{
 				agentName:  "claude-code",
 				configPath: func(home string) string { return filepath.Join(home, ".claude.json") },
@@ -131,13 +127,13 @@ func initHarnesses() {
 				rootKey:    "mcpServers",
 				defaults:   map[string]interface{}{"type": "stdio"},
 			}),
-			Roles: &RolesCapability{Extension: ".md", Render: renderClaudeAgentRole},
+			roles: roleRenderer("claude-code"),
 			Hooks: &hookTarget{
 				agentName: "claude-code",
 				inspect:   inspectClaudeHook,
 				patch:     patchClaudeHook,
 			},
-			RootInstructions: &RootInstructionsCapability{
+			RootInstructions: &rootInstructionsCapability{
 				Path:     func(home string) string { return filepath.Join(home, ".claude", "CLAUDE.md") },
 				Expected: func(repoRoot string) string { return filepath.Join(repoRoot, "AGENTS.md") },
 			},
@@ -145,7 +141,7 @@ func initHarnesses() {
 		},
 
 		"codex": {
-			Skills: SkillsSymlink,
+			Skills: skillsSymlink,
 			MCP: mcpTargetPtr(mcpTarget{
 				agentName:  "codex",
 				configPath: func(home string) string { return filepath.Join(home, ".codex", "config.toml") },
@@ -153,13 +149,13 @@ func initHarnesses() {
 				patch:      patchCodexMCPServer,
 				read:       readCodexMCPServer,
 			}),
-			Roles: &RolesCapability{Extension: ".toml", Render: renderCodexAgentRole},
+			roles: roleRenderer("codex"),
 			Hooks: &hookTarget{
 				agentName: "codex",
 				inspect:   inspectCodexHook,
 				patch:     patchCodexHook,
 			},
-			RootInstructions: &RootInstructionsCapability{
+			RootInstructions: &rootInstructionsCapability{
 				Path:     func(home string) string { return filepath.Join(home, ".codex", "AGENTS.md") },
 				Expected: func(repoRoot string) string { return filepath.Join(repoRoot, "AGENTS.md") },
 			},
@@ -167,7 +163,7 @@ func initHarnesses() {
 		},
 
 		"droid": {
-			Skills: SkillsSymlink,
+			Skills: skillsSymlink,
 			MCP: mcpTargetPtr(mcpTarget{
 				agentName:  "droid",
 				configPath: func(home string) string { return filepath.Join(home, ".factory", "mcp.json") },
@@ -177,13 +173,13 @@ func initHarnesses() {
 				rootKey:    "mcpServers",
 				defaults:   map[string]interface{}{"type": "stdio", "disabled": false},
 			}),
-			Roles: &RolesCapability{Extension: ".md", Render: renderDroidAgentRole},
+			roles: roleRenderer("droid"),
 			Hooks: &hookTarget{
 				agentName: "droid",
 				inspect:   inspectDroidHook,
 				patch:     patchDroidHook,
 			},
-			RootInstructions: &RootInstructionsCapability{
+			RootInstructions: &rootInstructionsCapability{
 				Path:     func(home string) string { return filepath.Join(home, ".factory", "AGENTS.md") },
 				Expected: func(repoRoot string) string { return filepath.Join(repoRoot, "AGENTS.md") },
 			},
@@ -191,7 +187,7 @@ func initHarnesses() {
 		},
 
 		"hermes": {
-			Skills: SkillsConfigDriven,
+			Skills: skillsConfigDriven,
 			InspectSkills: func(agent agentConfig, expected map[string]string, agentsSkillRoot string, cfg config, home string) (agentReport, error) {
 				return inspectHermesAgent(agent, expected, agentsSkillRoot, cfg, home)
 			},
@@ -212,7 +208,7 @@ func initHarnesses() {
 				patch:     patchHermesHook,
 			},
 			IntegrationNote: "config-driven via ~/.hermes/config.yaml -> skills.external_dirs",
-			DoctorChecks: []DoctorCheck{
+			doctorChecks: []doctorCheck{
 				{Name: "hermes direct mirrors", Run: checkHermesDirectMirrors},
 				{Name: "hermes hooks", Run: func(_, home string, cfg config) checkResult {
 					return checkHermesHooks(home, cfg)
@@ -222,7 +218,7 @@ func initHarnesses() {
 		},
 
 		agentOpenCode: {
-			Skills:           SkillsSymlink,
+			Skills:           skillsSymlink,
 			SkillsNativeRoot: openCodeReadsAgentsSkills,
 			MCP: mcpTargetPtr(mcpTarget{
 				agentName:  agentOpenCode,
@@ -232,16 +228,16 @@ func initHarnesses() {
 				read:       readOpenCodeMCPServer,
 				rootKey:    "mcp",
 			}),
-			Roles:           &RolesCapability{Extension: ".md", Render: renderOpenCodeAgentRole},
+			roles:           roleRenderer(agentOpenCode),
 			IntegrationNote: "skills read natively from ~/.agents/skills (mirrored into the skill root only when the config root differs)",
-			DoctorChecks: []DoctorCheck{
+			doctorChecks: []doctorCheck{
 				{Name: "opencode duplicate skills", Run: checkOpenCodeDuplicateSkills},
 			},
 		},
 
 		agentPi: {
 			Detect: detectVanillaPi,
-			Skills: SkillsSymlink,
+			Skills: skillsSymlink,
 			MCP: mcpTargetPtr(mcpTarget{
 				agentName:  agentPi,
 				configPath: func(home string) string { return filepath.Join(home, ".pi", "agent", "mcp.json") },
@@ -250,8 +246,8 @@ func initHarnesses() {
 				read:       readJSONMCPServer,
 				rootKey:    "mcpServers",
 			}),
-			Roles: &RolesCapability{Extension: ".md", Render: renderPiAgentRole},
-			RootInstructions: &RootInstructionsCapability{
+			roles: roleRenderer(agentPi),
+			RootInstructions: &rootInstructionsCapability{
 				Path:     func(home string) string { return filepath.Join(home, ".pi", "agent", "AGENTS.md") },
 				Expected: func(repoRoot string) string { return filepath.Join(repoRoot, "AGENTS.md") },
 			},
@@ -260,7 +256,7 @@ func initHarnesses() {
 		},
 
 		agentOMP: {
-			Skills: SkillsSymlink,
+			Skills: skillsSymlink,
 			MCP: mcpTargetPtr(mcpTarget{
 				agentName:  agentOMP,
 				configPath: func(home string) string { return filepath.Join(home, ".omp", "agent", "mcp.json") },
@@ -269,11 +265,11 @@ func initHarnesses() {
 				read:       readJSONMCPServer,
 				rootKey:    "mcpServers",
 			}),
-			Roles: &RolesCapability{Extension: ".md", Render: renderOMPAgentRole},
+			roles: roleRenderer(agentOMP),
 		},
 
 		agentQwenCode: {
-			Skills: SkillsConfigDriven,
+			Skills: skillsConfigDriven,
 			InspectSkills: func(agent agentConfig, expected map[string]string, agentsSkillRoot string, cfg config, home string) (agentReport, error) {
 				return inspectQwenAgent(agent, expected, agentsSkillRoot, cfg, home)
 			},
@@ -286,13 +282,13 @@ func initHarnesses() {
 				read:       readJSONMCPServer,
 				rootKey:    "mcpServers",
 			}),
-			Roles: &RolesCapability{Extension: ".md", Render: renderQwenAgentRole},
+			roles: roleRenderer(agentQwenCode),
 			Hooks: &hookTarget{
 				agentName: agentQwenCode,
 				inspect:   inspectQwenHook,
 				patch:     patchQwenHook,
 			},
-			RootInstructions: &RootInstructionsCapability{
+			RootInstructions: &rootInstructionsCapability{
 				Path:     func(home string) string { return filepath.Join(home, ".qwen", "QWEN.md") },
 				Expected: func(repoRoot string) string { return filepath.Join(repoRoot, "AGENTS.md") },
 			},
@@ -301,7 +297,15 @@ func initHarnesses() {
 	}
 }
 
-func getHarnesses() map[string]*Harness {
+func roleRenderer(name string) agentrole.Renderer {
+	renderer, ok := agentrole.Lookup(name)
+	if !ok {
+		panic("missing role renderer for " + name)
+	}
+	return renderer
+}
+
+func getHarnesses() map[string]*harness {
 	harnessesOnce.Do(initHarnesses)
 	return harnesses
 }
@@ -312,7 +316,7 @@ func mcpTargetPtr(t mcpTarget) *mcpTarget {
 
 // harnessFor returns the harness for the given agent name.
 // Returns nil if no harness is registered (unknown agent).
-func harnessFor(name string) *Harness {
+func harnessFor(name string) *harness {
 	return getHarnesses()[normalizeAgentName(name)]
 }
 
diff --git a/cmd/dotagents/harness_test.go b/internal/app/harness_test.go
similarity index 94%
rename from cmd/dotagents/harness_test.go
rename to internal/app/harness_test.go
index f16b581..e3124a2 100644
--- a/cmd/dotagents/harness_test.go
+++ b/internal/app/harness_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
@@ -7,6 +7,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/yourconscience/dotagents/internal/agentrole"
 	"gopkg.in/yaml.v3"
 )
 
@@ -15,14 +16,14 @@ func TestPiAndOMPHarnessCapabilities(t *testing.T) {
 	if pi == nil {
 		t.Fatal("Pi harness is not registered")
 	}
-	if pi.Skills != SkillsSymlink {
+	if pi.Skills != skillsSymlink {
 		t.Fatalf("Pi skills capability = %v, want symlink", pi.Skills)
 	}
 	if pi.MCP == nil {
 		t.Fatal("Pi does not expose MCP adapter support")
 	}
-	if pi.Roles == nil || pi.Roles.Extension != ".md" {
-		t.Fatalf("Pi roles capability = %#v, want pi-subagents Markdown roles", pi.Roles)
+	if pi.roles == nil || pi.roles.Extension() != ".md" {
+		t.Fatalf("Pi roles capability = %#v, want pi-subagents Markdown roles", pi.roles)
 	}
 	if pi.RootInstructions == nil {
 		t.Fatal("Pi does not expose root-instruction support")
@@ -32,14 +33,14 @@ func TestPiAndOMPHarnessCapabilities(t *testing.T) {
 	if omp == nil {
 		t.Fatal("OMP harness is not registered")
 	}
-	if omp.Skills != SkillsSymlink {
+	if omp.Skills != skillsSymlink {
 		t.Fatalf("OMP skills capability = %v, want symlink", omp.Skills)
 	}
 	if omp.MCP == nil {
 		t.Fatal("OMP does not expose MCP support")
 	}
-	if omp.Roles == nil || omp.Roles.Extension != ".md" {
-		t.Fatalf("OMP roles capability = %#v, want Markdown roles", omp.Roles)
+	if omp.roles == nil || omp.roles.Extension() != ".md" {
+		t.Fatalf("OMP roles capability = %#v, want Markdown roles", omp.roles)
 	}
 }
 
@@ -131,12 +132,12 @@ func TestPiAndOMPMCPPatchesUseSeparateConfigs(t *testing.T) {
 }
 
 func TestPiAndOMPRenderersProduceNativeRoles(t *testing.T) {
-	role := agentRole{
+	role := agentrole.Role{
 		Name:         "researcher",
 		Description:  "Find reliable evidence",
 		Model:        "opus",
 		Effort:       "high",
-		OMP:          ompRoleOptions{Model: "gpt-5.6-luna-high"},
+		OMP:          agentrole.OMPOptions{Model: "gpt-5.6-luna-high"},
 		Tools:        []string{"Read", "WebSearch", "Write", "NotebookEdit", "read"},
 		Instructions: "Compare the sources.",
 	}
diff --git a/cmd/dotagents/harnesskit.go b/internal/app/harnesskit.go
similarity index 99%
rename from cmd/dotagents/harnesskit.go
rename to internal/app/harnesskit.go
index 5eaa0bf..e9a7c63 100644
--- a/cmd/dotagents/harnesskit.go
+++ b/internal/app/harnesskit.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bufio"
diff --git a/cmd/dotagents/hook_cli.go b/internal/app/hook_cli.go
similarity index 99%
rename from cmd/dotagents/hook_cli.go
rename to internal/app/hook_cli.go
index 1d7d389..0c7815d 100644
--- a/cmd/dotagents/hook_cli.go
+++ b/internal/app/hook_cli.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/hook_cli_test.go b/internal/app/hook_cli_test.go
similarity index 99%
rename from cmd/dotagents/hook_cli_test.go
rename to internal/app/hook_cli_test.go
index da014aa..ac3f02c 100644
--- a/cmd/dotagents/hook_cli_test.go
+++ b/internal/app/hook_cli_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/hooks.go b/internal/app/hooks.go
similarity index 99%
rename from cmd/dotagents/hooks.go
rename to internal/app/hooks.go
index c9b9b27..5fb3b64 100644
--- a/cmd/dotagents/hooks.go
+++ b/internal/app/hooks.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/hooks_test.go b/internal/app/hooks_test.go
similarity index 99%
rename from cmd/dotagents/hooks_test.go
rename to internal/app/hooks_test.go
index 45639b0..f255233 100644
--- a/cmd/dotagents/hooks_test.go
+++ b/internal/app/hooks_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/inspect.go b/internal/app/inspect.go
similarity index 99%
rename from cmd/dotagents/inspect.go
rename to internal/app/inspect.go
index 7791fc4..b564e60 100644
--- a/cmd/dotagents/inspect.go
+++ b/internal/app/inspect.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
@@ -192,7 +192,7 @@ func inspectAgent(agent agentConfig, expected map[string]string, repoRoot string
 		return report, nil
 	}
 	h := harnessFor(agent.Name)
-	if h != nil && h.Skills == SkillsConfigDriven && h.InspectSkills != nil {
+	if h != nil && h.Skills == skillsConfigDriven && h.InspectSkills != nil {
 		return h.InspectSkills(agent, expected, agentsSkillRoot, cfg, home)
 	}
 
@@ -398,7 +398,7 @@ func isReportSynced(report agentReport) bool {
 	return report.RootState == "" || report.RootState == stateSynced
 }
 
-func inspectRootInstructions(report *agentReport, ri *RootInstructionsCapability, repoRoot string, home string) error {
+func inspectRootInstructions(report *agentReport, ri *rootInstructionsCapability, repoRoot string, home string) error {
 	linkPath := ri.Path(home)
 	expectedTarget := ri.Expected(repoRoot)
 	report.RootPath = linkPath
diff --git a/cmd/dotagents/inspect_test.go b/internal/app/inspect_test.go
similarity index 99%
rename from cmd/dotagents/inspect_test.go
rename to internal/app/inspect_test.go
index 0181eaf..a45e06b 100644
--- a/cmd/dotagents/inspect_test.go
+++ b/internal/app/inspect_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/local_overlay_test.go b/internal/app/local_overlay_test.go
similarity index 99%
rename from cmd/dotagents/local_overlay_test.go
rename to internal/app/local_overlay_test.go
index 5527d26..7566cee 100644
--- a/cmd/dotagents/local_overlay_test.go
+++ b/internal/app/local_overlay_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/lock.go b/internal/app/lock.go
similarity index 99%
rename from cmd/dotagents/lock.go
rename to internal/app/lock.go
index 994bdc9..da3c11a 100644
--- a/cmd/dotagents/lock.go
+++ b/internal/app/lock.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/lock_test.go b/internal/app/lock_test.go
similarity index 99%
rename from cmd/dotagents/lock_test.go
rename to internal/app/lock_test.go
index 903c21e..b4a0294 100644
--- a/cmd/dotagents/lock_test.go
+++ b/internal/app/lock_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/mcp.go b/internal/app/mcp.go
similarity index 99%
rename from cmd/dotagents/mcp.go
rename to internal/app/mcp.go
index 9b47a2f..9eb2b2c 100644
--- a/cmd/dotagents/mcp.go
+++ b/internal/app/mcp.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/mcp_cli.go b/internal/app/mcp_cli.go
similarity index 99%
rename from cmd/dotagents/mcp_cli.go
rename to internal/app/mcp_cli.go
index 0217811..1e205a2 100644
--- a/cmd/dotagents/mcp_cli.go
+++ b/internal/app/mcp_cli.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/mcp_cli_test.go b/internal/app/mcp_cli_test.go
similarity index 99%
rename from cmd/dotagents/mcp_cli_test.go
rename to internal/app/mcp_cli_test.go
index 13f7337..0f0acec 100644
--- a/cmd/dotagents/mcp_cli_test.go
+++ b/internal/app/mcp_cli_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
diff --git a/cmd/dotagents/mcp_test.go b/internal/app/mcp_test.go
similarity index 99%
rename from cmd/dotagents/mcp_test.go
rename to internal/app/mcp_test.go
index 4acc7c8..8c82e14 100644
--- a/cmd/dotagents/mcp_test.go
+++ b/internal/app/mcp_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/memory_tools.go b/internal/app/memory_tools.go
similarity index 77%
rename from cmd/dotagents/memory_tools.go
rename to internal/app/memory_tools.go
index c1c7d87..52c6f0b 100644
--- a/cmd/dotagents/memory_tools.go
+++ b/internal/app/memory_tools.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
@@ -10,9 +10,10 @@ import (
 	"time"
 )
 
-// installMemoryTools builds every Go tool under <repoRoot>/memory/tools/<name>
-// (a directory with a go.mod) and installs the binary into the user's bin
-// directory. This is how the default memory system (rem, knowledge-sync)
+// installMemoryTools builds every Go package under <repoRoot>/memory/tools/<name>
+// and installs the binary into the user's bin directory. Source checkouts use
+// the root module; setup scaffolds a module file beside each copied tool. This
+// is how the default memory system (rem, knowledge-sync)
 // follows a machine: dotagents sync provisions it after reconciling files.
 //
 // installed binary, so frequent syncs stay cheap. GOBIN overrides the
@@ -46,9 +47,17 @@ func installMemoryTools(repoRoot string) ([]string, error) {
 
 	var names []string
 	for _, entry := range entries {
-		if entry.IsDir() {
-			if _, err := os.Stat(filepath.Join(toolsDir, entry.Name(), "go.mod")); err == nil {
+		if !entry.IsDir() {
+			continue
+		}
+		matches, err := filepath.Glob(filepath.Join(toolsDir, entry.Name(), "*.go"))
+		if err != nil {
+			return nil, fmt.Errorf("find Go source for %s: %w", entry.Name(), err)
+		}
+		for _, match := range matches {
+			if !strings.HasSuffix(match, "_test.go") {
 				names = append(names, entry.Name())
+				break
 			}
 		}
 	}
@@ -74,7 +83,7 @@ func buildMemoryTool(srcDir, dest string) (bool, error) {
 		return false, err
 	}
 	for _, entry := range entries {
-		if entry.IsDir() || (!strings.HasSuffix(entry.Name(), ".go") && entry.Name() != "go.mod") {
+		if entry.IsDir() || (!strings.HasSuffix(entry.Name(), ".go") && entry.Name() != "go.mod") || strings.HasSuffix(entry.Name(), "_test.go") {
 			continue
 		}
 		info, err := entry.Info()
diff --git a/cmd/dotagents/memory_tools_test.go b/internal/app/memory_tools_test.go
similarity index 56%
rename from cmd/dotagents/memory_tools_test.go
rename to internal/app/memory_tools_test.go
index 4c43fad..7ba90b4 100644
--- a/cmd/dotagents/memory_tools_test.go
+++ b/internal/app/memory_tools_test.go
@@ -1,8 +1,9 @@
-package main
+package app
 
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 )
@@ -13,8 +14,10 @@ func TestInstallMemoryToolsBuildsAndSkipsFresh(t *testing.T) {
 	if err := os.MkdirAll(toolDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	writeFile(t, filepath.Join(toolDir, "go.mod"), "module hello\n\ngo 1.24\n")
-	writeFile(t, filepath.Join(toolDir, "main.go"), "package main\n\nfunc main() {}\n")
+	writeFile(t, filepath.Join(toolDir, "go.mod"), "module hello\n\ngo 1.24.2\n")
+	writeFile(t, filepath.Join(toolDir, "main.go"), "package main\n\nfunc main() { helper() }\n")
+	writeFile(t, filepath.Join(toolDir, "helper.go"), "package main\n\nfunc helper() {}\n")
+	writeFile(t, filepath.Join(toolDir, "main_test.go"), "package main\n")
 
 	binDir := filepath.Join(t.TempDir(), "bin")
 	t.Setenv("GOBIN", binDir)
@@ -53,6 +56,38 @@ func TestInstallMemoryToolsBuildsAndSkipsFresh(t *testing.T) {
 	}
 }
 
+func TestFreshScaffoldBuildsBothMemoryTools(t *testing.T) {
+	root := t.TempDir()
+	configPath := filepath.Join(root, "dotagents.yaml")
+	if err := ensureStarterAssets(root, configPath); err != nil {
+		t.Fatalf("scaffold starter assets: %v", err)
+	}
+	for _, tool := range []string{"knowledge-sync", "rem"} {
+		toolDir := filepath.Join(root, "memory", "tools", tool)
+		if _, err := os.Stat(filepath.Join(toolDir, "go.mod")); err != nil {
+			t.Fatalf("scaffolded %s go.mod missing: %v", tool, err)
+		}
+		if _, err := os.Stat(filepath.Join(toolDir, "go.mod.template")); !os.IsNotExist(err) {
+			t.Fatalf("scaffolded %s retained template name: %v", tool, err)
+		}
+	}
+
+	binDir := filepath.Join(t.TempDir(), "bin")
+	t.Setenv("GOBIN", binDir)
+	installed, err := installMemoryTools(root)
+	if err != nil {
+		t.Fatalf("install freshly scaffolded memory tools: %v", err)
+	}
+	if got := strings.Join(installed, ","); got != "knowledge-sync,rem" {
+		t.Fatalf("installed = %q, want knowledge-sync,rem", got)
+	}
+	for _, tool := range installed {
+		if info, err := os.Stat(filepath.Join(binDir, tool)); err != nil || info.Mode()&0o111 == 0 {
+			t.Fatalf("installed binary %s is not executable: info=%v err=%v", tool, info, err)
+		}
+	}
+}
+
 func TestInstallMemoryToolsMissingDirIsNoop(t *testing.T) {
 	t.Setenv("GOBIN", filepath.Join(t.TempDir(), "bin"))
 	installed, err := installMemoryTools(t.TempDir())
diff --git a/cmd/dotagents/memsearch.go b/internal/app/memsearch.go
similarity index 96%
rename from cmd/dotagents/memsearch.go
rename to internal/app/memsearch.go
index d4c1636..08c8f3a 100644
--- a/cmd/dotagents/memsearch.go
+++ b/internal/app/memsearch.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"flag"
@@ -56,6 +56,10 @@ func runMemsearch(args []string) error {
 	}
 }
 
+func shellQuote(value string) string {
+	return "'" + strings.ReplaceAll(value, "'", "'\"'\"'") + "'"
+}
+
 func memsearchConfigContent(vaultDir, home string) string {
 	sessionsDir := filepath.Join(vaultDir, "sessions")
 	notesDir := filepath.Join(vaultDir, "notes")
@@ -63,13 +67,13 @@ func memsearchConfigContent(vaultDir, home string) string {
 	stateDir := filepath.Join(home, ".memsearch", "state")
 	return fmt.Sprintf(`# memsearch configuration (written by dotagents memsearch setup)
 # Source this file from memory hooks to get portable paths.
-KNOWLEDGE_DIR="%s"
-SESSIONS_DIR="%s"
-NOTES_DIR="%s"
-PROFILE_DIR="%s"
-MEMSEARCH_STATE_DIR="%s"
-MEMSEARCH_COLLECTION="ai"
-`, vaultDir, sessionsDir, notesDir, profileDir, stateDir)
+KNOWLEDGE_DIR=%s
+SESSIONS_DIR=%s
+NOTES_DIR=%s
+PROFILE_DIR=%s
+MEMSEARCH_STATE_DIR=%s
+MEMSEARCH_COLLECTION='ai'
+`, shellQuote(vaultDir), shellQuote(sessionsDir), shellQuote(notesDir), shellQuote(profileDir), shellQuote(stateDir))
 }
 func ensureMemsearchConfig(root string, home string) error {
 	vaultDir := os.Getenv("KNOWLEDGE_DIR")
diff --git a/cmd/dotagents/memsearch_test.go b/internal/app/memsearch_test.go
similarity index 81%
rename from cmd/dotagents/memsearch_test.go
rename to internal/app/memsearch_test.go
index a47d316..93959b7 100644
--- a/cmd/dotagents/memsearch_test.go
+++ b/internal/app/memsearch_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
@@ -41,6 +41,38 @@ func TestParseMemsearchFlagsDefaultsToDocumentedKnowledgeDir(t *testing.T) {
 	}
 }
 
+func TestMemsearchConfigPOSIXShellQuotesArbitraryPaths(t *testing.T) {
+	home := filepath.Join(t.TempDir(), "home with $dollar `tick` \"double\" and 'single'")
+	vault := filepath.Join(home, "vault with shell chars")
+	confPath := filepath.Join(t.TempDir(), "memsearch.conf")
+	if err := os.WriteFile(confPath, []byte(memsearchConfigContent(vault, home)), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	script := `. "$CONF"; printf '%s\n' "$KNOWLEDGE_DIR" "$SESSIONS_DIR" "$NOTES_DIR" "$PROFILE_DIR" "$MEMSEARCH_STATE_DIR" "$MEMSEARCH_COLLECTION"`
+	cmd := exec.Command("/bin/sh", "-c", script)
+	cmd.Env = []string{"CONF=" + confPath, "PATH=" + os.Getenv("PATH")}
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("source generated config: %v: %s", err, output)
+	}
+	got := strings.Split(strings.TrimSuffix(string(output), "\n"), "\n")
+	want := []string{
+		vault,
+		filepath.Join(vault, "sessions"),
+		filepath.Join(vault, "notes"),
+		filepath.Join(vault, "profile"),
+		filepath.Join(home, ".memsearch", "state"),
+		"ai",
+	}
+	if strings.Join(got, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("sourced config values = %#v, want %#v\nconfig:\n%s", got, want, memsearchConfigContent(vault, home))
+	}
+	if strings.Contains(memsearchConfigContent(vault, home), "$dollar") && !strings.Contains(memsearchConfigContent(vault, home), `KNOWLEDGE_DIR='`) {
+		t.Fatal("generated path is not single-quoted")
+	}
+}
+
 func TestMemsearchConfigFieldsDriveCommonShToSelectedVault(t *testing.T) {
 	home := t.TempDir()
 	vault := filepath.Join(home, "selected-vault")
@@ -127,7 +159,7 @@ func TestEnsureMemsearchConfigWritesCustomRoot(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(data), `KNOWLEDGE_DIR="`+vault+`"`) {
+	if !strings.Contains(string(data), "KNOWLEDGE_DIR="+shellQuote(vault)) {
 		t.Fatalf("custom-root memsearch config = %s", data)
 	}
 	if _, err := os.Stat(filepath.Join(home, ".agents", "memsearch.conf")); !os.IsNotExist(err) {
diff --git a/cmd/dotagents/opencode.go b/internal/app/opencode.go
similarity index 88%
rename from cmd/dotagents/opencode.go
rename to internal/app/opencode.go
index 9736ea3..34c0e97 100644
--- a/cmd/dotagents/opencode.go
+++ b/internal/app/opencode.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
@@ -38,39 +38,6 @@ func openCodeReadsAgentsSkills(repoRoot string, home string) bool {
 	return sameResolvedPath(repoRoot, agentsRoot)
 }
 
-func renderOpenCodeAgentRole(role agentRole) string {
-	mode := strings.TrimSpace(role.Opencode.Mode)
-	if mode == "" {
-		mode = "subagent"
-	}
-
-	var b strings.Builder
-	b.WriteString("---\n")
-	writeYAMLScalar(&b, "description", role.Description)
-	b.WriteString("mode: ")
-	b.WriteString(mode)
-	b.WriteString("\n")
-	if model := strings.TrimSpace(role.Opencode.Model); model != "" {
-		writeYAMLScalar(&b, "model", model)
-	} else if model := strings.TrimSpace(role.Model); model != "" && !canonicalModelTier(model) {
-		writeYAMLScalar(&b, "model", model)
-	}
-	if temperature := strings.TrimSpace(role.Opencode.Temperature); temperature != "" {
-		b.WriteString("temperature: ")
-		b.WriteString(temperature)
-		b.WriteString("\n")
-	}
-	b.WriteString("---\n\n")
-	b.WriteString("<!-- ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly. -->\n\n")
-	b.WriteString(role.Instructions)
-	b.WriteString("\n")
-	return b.String()
-}
-
 // openCodeCommandArray folds the canonical command + args into the single
 // command array OpenCode expects for a local (stdio) MCP server.
 func openCodeCommandArray(server mcpServerConfig) []string {
diff --git a/cmd/dotagents/opencode_test.go b/internal/app/opencode_test.go
similarity index 95%
rename from cmd/dotagents/opencode_test.go
rename to internal/app/opencode_test.go
index fec9d67..6991473 100644
--- a/cmd/dotagents/opencode_test.go
+++ b/internal/app/opencode_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
@@ -7,6 +7,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/yourconscience/dotagents/internal/agentrole"
 	"gopkg.in/yaml.v3"
 )
 
@@ -15,7 +16,7 @@ func TestOpenCodeHarnessCapabilitiesAndDefaults(t *testing.T) {
 	if h == nil {
 		t.Fatal("OpenCode harness is not registered")
 	}
-	if h.Skills != SkillsSymlink {
+	if h.Skills != skillsSymlink {
 		t.Fatalf("OpenCode skills capability = %v, want symlink", h.Skills)
 	}
 	if h.SkillsNativeRoot == nil {
@@ -24,8 +25,8 @@ func TestOpenCodeHarnessCapabilitiesAndDefaults(t *testing.T) {
 	if h.MCP == nil {
 		t.Fatal("OpenCode does not expose MCP support")
 	}
-	if h.Roles == nil || h.Roles.Extension != ".md" {
-		t.Fatalf("OpenCode roles capability = %#v, want Markdown roles", h.Roles)
+	if h.roles == nil || h.roles.Extension() != ".md" {
+		t.Fatalf("OpenCode roles capability = %#v, want Markdown roles", h.roles)
 	}
 	if h.Hooks != nil {
 		t.Fatal("OpenCode must not declare hook support (JS plugin surface only)")
@@ -62,7 +63,7 @@ func TestOpenCodeDetectionFromPATH(t *testing.T) {
 }
 
 func TestOpenCodeRoleRenderDefaultMode(t *testing.T) {
-	role := agentRole{
+	role := agentrole.Role{
 		Name:         "researcher",
 		Description:  "Find reliable evidence",
 		Model:        "opus",
@@ -70,7 +71,7 @@ func TestOpenCodeRoleRenderDefaultMode(t *testing.T) {
 		Instructions: "Compare the sources.",
 		Source:       "agents/researcher.md",
 	}
-	content := renderOpenCodeAgentRole(role)
+	content := roleRenderer(agentOpenCode).Render(role)
 
 	if strings.Contains(content, "name:") {
 		t.Fatalf("opencode role should not emit a name field (filename is the name):\n%s", content)
@@ -84,7 +85,7 @@ func TestOpenCodeRoleRenderDefaultMode(t *testing.T) {
 	if strings.Contains(content, "model:") || strings.Contains(content, "temperature:") {
 		t.Fatalf("opencode role should omit model/temperature without an override:\n%s", content)
 	}
-	if !strings.Contains(content, generatedAgentMarker) {
+	if !strings.Contains(content, agentrole.GeneratedMarker) {
 		t.Fatalf("opencode role missing managed marker:\n%s", content)
 	}
 	if !strings.Contains(content, "Compare the sources.") {
@@ -93,13 +94,13 @@ func TestOpenCodeRoleRenderDefaultMode(t *testing.T) {
 }
 
 func TestOpenCodeRoleRenderHonorsOverride(t *testing.T) {
-	role := agentRole{
+	role := agentrole.Role{
 		Name:         "reviewer",
 		Description:  "Reviews code",
 		Instructions: "Review carefully.",
-		Opencode:     opencodeRoleOptions{Model: "anthropic/claude-sonnet-4", Temperature: "0.1", Mode: "primary"},
+		Opencode:     agentrole.OpenCodeOptions{Model: "anthropic/claude-sonnet-4", Temperature: "0.1", Mode: "primary"},
 	}
-	content := renderOpenCodeAgentRole(role)
+	content := roleRenderer(agentOpenCode).Render(role)
 	if !strings.Contains(content, "mode: primary") {
 		t.Fatalf("opencode override mode not applied:\n%s", content)
 	}
@@ -389,13 +390,13 @@ Be helpful.
 }
 
 func TestOpenCodeRoleRenderUsesConfiguredModel(t *testing.T) {
-	role := agentRole{
+	role := agentrole.Role{
 		Name:         "builder",
 		Description:  "Builds features",
 		Model:        "openai/gpt-5.6",
 		Instructions: "Implement.",
 	}
-	content := renderOpenCodeAgentRole(role)
+	content := roleRenderer(agentOpenCode).Render(role)
 	if !strings.Contains(content, "model: \"openai/gpt-5.6\"") {
 		t.Fatalf("configured role_model not applied to OpenCode role:\n%s", content)
 	}
diff --git a/cmd/dotagents/package_age.go b/internal/app/package_age.go
similarity index 99%
rename from cmd/dotagents/package_age.go
rename to internal/app/package_age.go
index d6b9c37..db0f224 100644
--- a/cmd/dotagents/package_age.go
+++ b/internal/app/package_age.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/package_age_test.go b/internal/app/package_age_test.go
similarity index 99%
rename from cmd/dotagents/package_age_test.go
rename to internal/app/package_age_test.go
index 025e758..e08f996 100644
--- a/cmd/dotagents/package_age_test.go
+++ b/internal/app/package_age_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/pi_packages.go b/internal/app/pi_packages.go
similarity index 99%
rename from cmd/dotagents/pi_packages.go
rename to internal/app/pi_packages.go
index e80c161..134a050 100644
--- a/cmd/dotagents/pi_packages.go
+++ b/internal/app/pi_packages.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/pi_packages_test.go b/internal/app/pi_packages_test.go
similarity index 99%
rename from cmd/dotagents/pi_packages_test.go
rename to internal/app/pi_packages_test.go
index 6dbf4b3..19f1b1d 100644
--- a/cmd/dotagents/pi_packages_test.go
+++ b/internal/app/pi_packages_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/pluginmcp.go b/internal/app/pluginmcp.go
similarity index 99%
rename from cmd/dotagents/pluginmcp.go
rename to internal/app/pluginmcp.go
index fb6a8eb..cca9fdb 100644
--- a/cmd/dotagents/pluginmcp.go
+++ b/internal/app/pluginmcp.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/pluginmcp_test.go b/internal/app/pluginmcp_test.go
similarity index 99%
rename from cmd/dotagents/pluginmcp_test.go
rename to internal/app/pluginmcp_test.go
index 57e6c1a..a144afb 100644
--- a/cmd/dotagents/pluginmcp_test.go
+++ b/internal/app/pluginmcp_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/pluginspec.go b/internal/app/pluginspec.go
similarity index 99%
rename from cmd/dotagents/pluginspec.go
rename to internal/app/pluginspec.go
index a5c6846..1ac8c0d 100644
--- a/cmd/dotagents/pluginspec.go
+++ b/internal/app/pluginspec.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/pluginspec_test.go b/internal/app/pluginspec_test.go
similarity index 99%
rename from cmd/dotagents/pluginspec_test.go
rename to internal/app/pluginspec_test.go
index 56782b1..32fbca3 100644
--- a/cmd/dotagents/pluginspec_test.go
+++ b/internal/app/pluginspec_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/promote.go b/internal/app/promote.go
similarity index 99%
rename from cmd/dotagents/promote.go
rename to internal/app/promote.go
index 00db751..acb6736 100644
--- a/cmd/dotagents/promote.go
+++ b/internal/app/promote.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"flag"
diff --git a/cmd/dotagents/publish.go b/internal/app/publish.go
similarity index 99%
rename from cmd/dotagents/publish.go
rename to internal/app/publish.go
index 2563394..8b95081 100644
--- a/cmd/dotagents/publish.go
+++ b/internal/app/publish.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"archive/zip"
diff --git a/cmd/dotagents/publish_test.go b/internal/app/publish_test.go
similarity index 99%
rename from cmd/dotagents/publish_test.go
rename to internal/app/publish_test.go
index e4e072e..518ae8e 100644
--- a/cmd/dotagents/publish_test.go
+++ b/internal/app/publish_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
diff --git a/cmd/dotagents/qwen.go b/internal/app/qwen.go
similarity index 72%
rename from cmd/dotagents/qwen.go
rename to internal/app/qwen.go
index 63de12a..db5ce0b 100644
--- a/cmd/dotagents/qwen.go
+++ b/internal/app/qwen.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
@@ -139,68 +139,3 @@ func inspectQwenAgent(agent agentConfig, expected map[string]string, agentsSkill
 	report.Synced = isReportSynced(report)
 	return report, nil
 }
-
-var qwenToolMapping = map[string]string{
-	"bash":      "run_shell_command",
-	"edit":      "replace",
-	"glob":      "glob",
-	"grep":      "grep_search",
-	"read":      "read_file",
-	"webfetch":  "web_fetch",
-	"websearch": "web_search",
-	"write":     "write_file",
-}
-
-func renderQwenAgentRole(role agentRole) string {
-	model := strings.TrimSpace(role.Qwen.Model)
-	if model == "" {
-		if generic := strings.TrimSpace(role.Model); generic != "" && !canonicalModelTier(generic) {
-			model = generic
-		} else {
-			model = "inherit"
-		}
-	}
-	tools := role.Qwen.Tools
-	if len(tools) == 0 {
-		tools = qwenToolsFor(role.Tools)
-	}
-
-	var b strings.Builder
-	b.WriteString("---\n")
-	writeYAMLScalar(&b, "name", role.Name)
-	writeYAMLScalar(&b, "description", role.Description)
-	writeYAMLScalar(&b, "model", model)
-	writeYAMLScalar(&b, "approvalMode", role.Qwen.ApprovalMode)
-	if len(tools) > 0 {
-		b.WriteString("tools:\n")
-		for _, tool := range tools {
-			writeYAMLListItem(&b, tool)
-		}
-	}
-	b.WriteString("---\n\n")
-	b.WriteString("<!-- ")
-	b.WriteString(generatedAgentMarker)
-	b.WriteString(" from ")
-	b.WriteString(agentRoleSourceLabel(role))
-	b.WriteString("; do not edit directly. -->\n\n")
-	b.WriteString(role.Instructions)
-	b.WriteString("\n")
-	return b.String()
-}
-
-func qwenToolsFor(tools []string) []string {
-	out := make([]string, 0, len(tools))
-	seen := make(map[string]struct{}, len(tools))
-	for _, tool := range tools {
-		mapped := qwenToolMapping[strings.ToLower(strings.TrimSpace(tool))]
-		if mapped == "" {
-			continue
-		}
-		if _, ok := seen[mapped]; ok {
-			continue
-		}
-		seen[mapped] = struct{}{}
-		out = append(out, mapped)
-	}
-	return out
-}
diff --git a/cmd/dotagents/qwen_test.go b/internal/app/qwen_test.go
similarity index 91%
rename from cmd/dotagents/qwen_test.go
rename to internal/app/qwen_test.go
index f11ab00..0091457 100644
--- a/cmd/dotagents/qwen_test.go
+++ b/internal/app/qwen_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
@@ -8,6 +8,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/yourconscience/dotagents/internal/agentrole"
 	"gopkg.in/yaml.v3"
 )
 
@@ -16,10 +17,10 @@ func TestQwenHarnessCapabilitiesAndDefaultDetection(t *testing.T) {
 	if h == nil {
 		t.Fatal("Qwen Code harness is not registered")
 	}
-	if h.Skills != SkillsConfigDriven || h.Setup == nil || h.InspectSkills == nil {
+	if h.Skills != skillsConfigDriven || h.Setup == nil || h.InspectSkills == nil {
 		t.Fatalf("Qwen skills capability = %#v, want config-driven setup and inspection", h)
 	}
-	if h.MCP == nil || h.Hooks == nil || h.Roles == nil || h.RootInstructions == nil {
+	if h.MCP == nil || h.Hooks == nil || h.roles == nil || h.RootInstructions == nil {
 		t.Fatalf("Qwen capabilities incomplete: %#v", h)
 	}
 
@@ -166,15 +167,15 @@ func TestQwenHookPatchUsesMillisecondsAndPreservesSettings(t *testing.T) {
 }
 
 func TestRenderQwenAgentRoleUsesNativeFrontmatter(t *testing.T) {
-	role := agentRole{
+	role := agentrole.Role{
 		Name:         "reviewer",
 		Description:  "Review changes",
 		Model:        "opus",
 		Tools:        []string{"Read", "Glob", "Grep", "Bash", "Read"},
-		Qwen:         qwenRoleOptions{ApprovalMode: "plan"},
+		Qwen:         agentrole.QwenOptions{ApprovalMode: "plan"},
 		Instructions: "Review without editing.",
 	}
-	content := renderQwenAgentRole(role)
+	content := roleRenderer(agentQwenCode).Render(role)
 	parts := strings.SplitN(content, "---\n", 3)
 	if len(parts) != 3 {
 		t.Fatalf("Qwen role lacks frontmatter:\n%s", content)
@@ -196,7 +197,7 @@ func TestRenderQwenAgentRoleUsesNativeFrontmatter(t *testing.T) {
 	if !reflect.DeepEqual(frontmatter.Tools, wantTools) {
 		t.Fatalf("Qwen tools = %#v, want %#v", frontmatter.Tools, wantTools)
 	}
-	if !strings.Contains(parts[2], generatedAgentMarker) || !strings.Contains(parts[2], role.Instructions) {
+	if !strings.Contains(parts[2], agentrole.GeneratedMarker) || !strings.Contains(parts[2], role.Instructions) {
 		t.Fatalf("Qwen role body = %q", parts[2])
 	}
 }
@@ -249,14 +250,14 @@ hooks:
 }
 
 func TestQwenRoleRenderUsesConfiguredModel(t *testing.T) {
-	role := agentRole{Name: "builder", Description: "Builds features", Model: "qwen3-coder-plus", Instructions: "Implement."}
-	content := renderQwenAgentRole(role)
+	role := agentrole.Role{Name: "builder", Description: "Builds features", Model: "qwen3-coder-plus", Instructions: "Implement."}
+	content := roleRenderer(agentQwenCode).Render(role)
 	if !strings.Contains(content, "model: \"qwen3-coder-plus\"") {
 		t.Fatalf("configured role_model not applied to Qwen role:\n%s", content)
 	}
 
-	alias := agentRole{Name: "reviewer", Description: "Reviews code", Model: "opus", Instructions: "Review."}
-	content = renderQwenAgentRole(alias)
+	alias := agentrole.Role{Name: "reviewer", Description: "Reviews code", Model: "opus", Instructions: "Review."}
+	content = roleRenderer(agentQwenCode).Render(alias)
 	if strings.Contains(content, "model: opus") {
 		t.Fatalf("tier alias leaked into Qwen role:\n%s", content)
 	}
diff --git a/internal/app/readme.go b/internal/app/readme.go
new file mode 100644
index 0000000..1a2f291
--- /dev/null
+++ b/internal/app/readme.go
@@ -0,0 +1,109 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+const (
+	readmeSkillsBeginMarker = "<!-- BEGIN GENERATED SKILLS -->"
+	readmeSkillsEndMarker   = "<!-- END GENERATED SKILLS -->"
+)
+
+func expectedREADMESkillsBlock(repoRoot string) (string, int, error) {
+	entries, err := os.ReadDir(filepath.Join(repoRoot, "skills"))
+	if errors.Is(err, fs.ErrNotExist) {
+		entries = nil
+	} else if err != nil {
+		return "", 0, fmt.Errorf("read skills/: %w", err)
+	}
+
+	names := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		if !hasFile(filepath.Join(repoRoot, "skills", entry.Name(), "SKILL.md")) {
+			continue
+		}
+		// grill-me is a packaged command alias for grilling, not a standalone
+		// model-invocable skill in the public inventory.
+		if entry.Name() == "grill-me" {
+			continue
+		}
+		names = append(names, entry.Name())
+	}
+	sort.Strings(names)
+
+	var b strings.Builder
+	b.WriteString(readmeSkillsBeginMarker)
+	b.WriteString("\n")
+	fmt.Fprintf(&b, "%d skills ship with this repo:\n\n", len(names))
+	b.WriteString("`")
+	b.WriteString(strings.Join(names, "` `"))
+	b.WriteString("`\n")
+	b.WriteString(readmeSkillsEndMarker)
+	return b.String(), len(names), nil
+}
+
+func locateREADMESkillsBlock(content string) (int, int, error) {
+	if strings.Count(content, readmeSkillsBeginMarker) != 1 || strings.Count(content, readmeSkillsEndMarker) != 1 {
+		return 0, 0, errors.New("README skills markers must each appear exactly once")
+	}
+	start := strings.Index(content, readmeSkillsBeginMarker)
+	end := strings.Index(content, readmeSkillsEndMarker)
+	if end < start {
+		return 0, 0, errors.New("README skills end marker precedes begin marker")
+	}
+	return start, end + len(readmeSkillsEndMarker), nil
+}
+
+func renderREADMESkills(repoRoot string) error {
+	path := filepath.Join(repoRoot, "README.md")
+	data, err := os.ReadFile(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("read README.md: %w", err)
+	}
+	expected, count, err := expectedREADMESkillsBlock(repoRoot)
+	if err != nil {
+		return err
+	}
+	content := string(data)
+	if !strings.Contains(content, readmeSkillsBeginMarker) && !strings.Contains(content, readmeSkillsEndMarker) {
+		return nil
+	}
+	start, end, err := locateREADMESkillsBlock(content)
+	if err != nil {
+		return err
+	}
+	updated := content[:start] + expected + content[end:]
+	if updated == content {
+		fmt.Printf("rendered README skills: %d unchanged\n", count)
+		return nil
+	}
+	if err := os.WriteFile(path, []byte(updated), 0o644); err != nil {
+		return fmt.Errorf("write README.md: %w", err)
+	}
+	fmt.Printf("rendered README skills: %d written\n", count)
+	return nil
+}
+
+func runRender(opts runOptions) error {
+	repoRoot, _, _, _, err := loadContext(opts)
+	if err != nil {
+		return err
+	}
+	return renderCommittedArtifacts(repoRoot)
+}
+
+func renderCommittedArtifacts(repoRoot string) error {
+	return renderREADMESkills(repoRoot)
+}
diff --git a/cmd/dotagents/readme_inventory_test.go b/internal/app/readme_inventory_test.go
similarity index 99%
rename from cmd/dotagents/readme_inventory_test.go
rename to internal/app/readme_inventory_test.go
index 7fbb445..7d0de74 100644
--- a/cmd/dotagents/readme_inventory_test.go
+++ b/internal/app/readme_inventory_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/repo_link_test.go b/internal/app/repo_link_test.go
similarity index 99%
rename from cmd/dotagents/repo_link_test.go
rename to internal/app/repo_link_test.go
index 4406344..6481c89 100644
--- a/cmd/dotagents/repo_link_test.go
+++ b/internal/app/repo_link_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/report.go b/internal/app/report.go
similarity index 99%
rename from cmd/dotagents/report.go
rename to internal/app/report.go
index 1c2828a..8ed40da 100644
--- a/cmd/dotagents/report.go
+++ b/internal/app/report.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/review.go b/internal/app/review.go
similarity index 97%
rename from cmd/dotagents/review.go
rename to internal/app/review.go
index 1b1f881..e9cecc3 100644
--- a/cmd/dotagents/review.go
+++ b/internal/app/review.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
@@ -34,7 +34,7 @@ func (a reviewAction) String() string {
 // sourceIdx selects which harness copy becomes canonical when sharing an
 // item whose content differs between sources.
 type reviewRow struct {
-	item      DetectedItem
+	item      detectedItem
 	action    reviewAction
 	sourceIdx int
 }
@@ -44,7 +44,7 @@ type reviewDecision struct {
 	Surface string
 	Name    string
 	Action  reviewAction
-	Source  DetectedSource
+	Source  detectedSource
 }
 
 type reviewModel struct {
@@ -65,7 +65,7 @@ var (
 	reviewSkipStyle   = lipgloss.NewStyle().Foreground(lipgloss.Color("3"))
 )
 
-func newReviewModel(detection *DetectionResult) reviewModel {
+func newReviewModel(detection *detectionResult) reviewModel {
 	rows := make([]reviewRow, 0, len(detection.Items))
 	for _, item := range detection.Items {
 		rows = append(rows, reviewRow{item: item, action: actionShare})
@@ -234,7 +234,7 @@ func (m reviewModel) actionCell(row reviewRow) string {
 
 // decisions returns the review outcome. Auto-resolved items are appended as
 // share decisions using their first source; nil is returned on abort.
-func (m reviewModel) decisions(detection *DetectionResult) []reviewDecision {
+func (m reviewModel) decisions(detection *detectionResult) []reviewDecision {
 	if m.aborted {
 		return nil
 	}
diff --git a/cmd/dotagents/review_apply.go b/internal/app/review_apply.go
similarity index 91%
rename from cmd/dotagents/review_apply.go
rename to internal/app/review_apply.go
index 2781901..997c940 100644
--- a/cmd/dotagents/review_apply.go
+++ b/internal/app/review_apply.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
@@ -10,6 +10,7 @@ import (
 
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/mattn/go-isatty"
+	"github.com/yourconscience/dotagents/internal/agentrole"
 )
 
 // reviewTTYAvailable reports whether the review TUI can run: setup must be
@@ -25,7 +26,7 @@ func reviewTTYAvailable(streams setupIO) bool {
 // Returns errReviewAborted when the user quits without applying.
 var errReviewAborted = errors.New("review aborted")
 
-func runReviewImport(root string, cfg *config, detection *DetectionResult, skills []nativeSkillCandidate, roles []nativeRoleCandidate, mcps []nativeMCPCandidate, streams setupIO) error {
+func runReviewImport(root string, cfg *config, detection *detectionResult, skills []nativeSkillCandidate, roles []nativeRoleCandidate, mcps []nativeMCPCandidate, streams setupIO) error {
 	if len(detection.Items) == 0 && len(detection.Resolved) == 0 {
 		return nil
 	}
@@ -101,7 +102,7 @@ func applyReviewDecisions(root string, cfg *config, decisions []reviewDecision,
 }
 
 // renderDetectionSummary is the plain-text detection view used by --dry-run.
-func renderDetectionSummary(detection *DetectionResult) string {
+func renderDetectionSummary(detection *detectionResult) string {
 	var b strings.Builder
 	if len(detection.Items) == 0 && len(detection.Resolved) == 0 {
 		b.WriteString("no import candidates detected\n")
@@ -122,7 +123,7 @@ func renderDetectionSummary(detection *DetectionResult) string {
 	return b.String()
 }
 
-func formatDetectedItem(item DetectedItem) string {
+func formatDetectedItem(item detectedItem) string {
 	harnesses := make([]string, 0, len(item.Sources))
 	for _, src := range item.Sources {
 		harnesses = append(harnesses, src.Harness)
@@ -136,9 +137,9 @@ func formatDetectedItem(item DetectedItem) string {
 
 // shareAllDecisions marks every detected item for sharing, picking the first
 // source when content differs. Used by --yes non-interactive imports.
-func shareAllDecisions(detection *DetectionResult) []reviewDecision {
+func shareAllDecisions(detection *detectionResult) []reviewDecision {
 	out := make([]reviewDecision, 0, len(detection.Items)+len(detection.Resolved))
-	for _, item := range append(append([]DetectedItem(nil), detection.Items...), detection.Resolved...) {
+	for _, item := range append(append([]detectedItem(nil), detection.Items...), detection.Resolved...) {
 		out = append(out, reviewDecision{
 			Surface: item.Surface,
 			Name:    item.Name,
@@ -172,7 +173,7 @@ func importRoleCandidate(root string, role nativeRoleCandidate) error {
 	if err != nil {
 		return err
 	}
-	path := filepath.Join(root, "agents", role.TargetName+agentRoleMarkdownExt)
+	path := filepath.Join(root, "agents", role.TargetName+agentrole.MarkdownExtension)
 	if _, err := os.Lstat(path); err == nil {
 		return nil
 	} else if !errors.Is(err, fs.ErrNotExist) {
diff --git a/cmd/dotagents/review_test.go b/internal/app/review_test.go
similarity index 91%
rename from cmd/dotagents/review_test.go
rename to internal/app/review_test.go
index 746507f..9c2811d 100644
--- a/cmd/dotagents/review_test.go
+++ b/internal/app/review_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
@@ -7,16 +7,17 @@ import (
 	"testing"
 
 	tea "github.com/charmbracelet/bubbletea"
+	"github.com/yourconscience/dotagents/internal/agentrole"
 )
 
-func testDetection() *DetectionResult {
-	return &DetectionResult{
+func testDetection() *detectionResult {
+	return &detectionResult{
 		Harnesses: []string{"claude-code", "codex"},
-		Items: []DetectedItem{
+		Items: []detectedItem{
 			{
 				Surface: "skill",
 				Name:    "linter",
-				Sources: []DetectedSource{
+				Sources: []detectedSource{
 					{Harness: "claude-code", Path: "/tmp/a", Hash: "h1"},
 					{Harness: "codex", Path: "/tmp/b", Hash: "h2"},
 				},
@@ -24,15 +25,15 @@ func testDetection() *DetectionResult {
 			{
 				Surface: "mcp",
 				Name:    "tavily",
-				Sources: []DetectedSource{{Harness: "codex", Path: "tavily", Hash: "h3"}},
+				Sources: []detectedSource{{Harness: "codex", Path: "tavily", Hash: "h3"}},
 			},
 		},
-		Resolved: []DetectedItem{
+		Resolved: []detectedItem{
 			{
 				Surface:   "skill",
 				Name:      "shared",
 				Identical: true,
-				Sources: []DetectedSource{
+				Sources: []detectedSource{
 					{Harness: "claude-code", Path: "/tmp/s", Hash: "h4"},
 					{Harness: "codex", Path: "/tmp/s2", Hash: "h4"},
 				},
@@ -201,7 +202,7 @@ func TestRenderDetectionSummary(t *testing.T) {
 			t.Fatalf("summary missing %q:\n%s", want, out)
 		}
 	}
-	empty := renderDetectionSummary(&DetectionResult{})
+	empty := renderDetectionSummary(&detectionResult{})
 	if !strings.Contains(empty, "no import candidates") {
 		t.Fatalf("empty summary unexpected: %s", empty)
 	}
@@ -220,8 +221,8 @@ func TestApplyReviewDecisionsSkill(t *testing.T) {
 
 	cfg := config{Version: 1}
 	decisions := []reviewDecision{
-		{Surface: "skill", Name: "linter", Action: actionShare, Source: DetectedSource{Harness: "claude-code", Path: srcSkill}},
-		{Surface: "skill", Name: "other", Action: actionSkip, Source: DetectedSource{Harness: "codex", Path: filepath.Join(srcRoot, "missing")}},
+		{Surface: "skill", Name: "linter", Action: actionShare, Source: detectedSource{Harness: "claude-code", Path: srcSkill}},
+		{Surface: "skill", Name: "other", Action: actionSkip, Source: detectedSource{Harness: "codex", Path: filepath.Join(srcRoot, "missing")}},
 	}
 	shared, err := applyReviewDecisions(root, &cfg, decisions, nil, nil, nil)
 	if err != nil {
@@ -255,8 +256,8 @@ func TestApplyReviewDecisionsRoleAndMCP(t *testing.T) {
 		},
 	}
 	decisions := []reviewDecision{
-		{Surface: "role", Name: "reviewer", Action: actionShare, Source: DetectedSource{Harness: "codex"}},
-		{Surface: "mcp", Name: "tavily", Action: actionShare, Source: DetectedSource{Harness: "codex"}},
+		{Surface: "role", Name: "reviewer", Action: actionShare, Source: detectedSource{Harness: "codex"}},
+		{Surface: "mcp", Name: "tavily", Action: actionShare, Source: detectedSource{Harness: "codex"}},
 	}
 	shared, err := applyReviewDecisions(root, &cfg, decisions, nil, roles, mcps)
 	if err != nil {
@@ -265,7 +266,7 @@ func TestApplyReviewDecisionsRoleAndMCP(t *testing.T) {
 	if shared != 2 {
 		t.Fatalf("expected 2 shared, got %d", shared)
 	}
-	if !hasFile(filepath.Join(root, "agents", "reviewer"+agentRoleMarkdownExt)) {
+	if !hasFile(filepath.Join(root, "agents", "reviewer"+agentrole.MarkdownExtension)) {
 		t.Fatal("role file should be written")
 	}
 	if len(cfg.MCPServers) != 1 || cfg.MCPServers[0].Name != "tavily" {
diff --git a/cmd/dotagents/root_instructions_test.go b/internal/app/root_instructions_test.go
similarity index 95%
rename from cmd/dotagents/root_instructions_test.go
rename to internal/app/root_instructions_test.go
index 96145d6..fbc1cd7 100644
--- a/cmd/dotagents/root_instructions_test.go
+++ b/internal/app/root_instructions_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
@@ -6,9 +6,9 @@ import (
 	"testing"
 )
 
-// droidRootInstructions returns the RootInstructionsCapability for the droid harness.
+// droidRootInstructions returns the rootInstructionsCapability for the droid harness.
 // Used by tests to exercise inspectRootInstructions with droid-specific paths.
-func droidRootInstructions() *RootInstructionsCapability {
+func droidRootInstructions() *rootInstructionsCapability {
 	h := harnessFor(agentDroid)
 	if h == nil || h.RootInstructions == nil {
 		panic("droid harness missing RootInstructions")
@@ -111,7 +111,7 @@ func TestApplyAgentRootInstructionSyncCreatesMissingLink(t *testing.T) {
 	}
 }
 
-func claudeCodeRootInstructions() *RootInstructionsCapability {
+func claudeCodeRootInstructions() *rootInstructionsCapability {
 	h := harnessFor(agentClaudeCode)
 	if h == nil || h.RootInstructions == nil {
 		panic("claude-code harness missing RootInstructions")
@@ -119,7 +119,7 @@ func claudeCodeRootInstructions() *RootInstructionsCapability {
 	return h.RootInstructions
 }
 
-func codexRootInstructions() *RootInstructionsCapability {
+func codexRootInstructions() *rootInstructionsCapability {
 	h := harnessFor(agentCodex)
 	if h == nil || h.RootInstructions == nil {
 		panic("codex harness missing RootInstructions")
@@ -127,7 +127,7 @@ func codexRootInstructions() *RootInstructionsCapability {
 	return h.RootInstructions
 }
 
-func ampRootInstructions() *RootInstructionsCapability {
+func ampRootInstructions() *rootInstructionsCapability {
 	h := harnessFor("amp")
 	if h == nil || h.RootInstructions == nil {
 		panic("amp harness missing RootInstructions")
@@ -140,7 +140,7 @@ func TestRootInstructionsNativePaths(t *testing.T) {
 	repoRoot := filepath.Join(home, ".agents")
 	for _, tc := range []struct {
 		agent    string
-		cap      *RootInstructionsCapability
+		cap      *rootInstructionsCapability
 		wantLink string
 	}{
 		{"amp", ampRootInstructions(), filepath.Join(home, ".config", "amp", "AGENTS.md")},
@@ -159,7 +159,7 @@ func TestRootInstructionsNativePaths(t *testing.T) {
 func TestInspectClaudeAndCodexRootInstructions(t *testing.T) {
 	for _, tc := range []struct {
 		agent string
-		cap   func() *RootInstructionsCapability
+		cap   func() *rootInstructionsCapability
 		dir   string
 		file  string
 	}{
diff --git a/cmd/dotagents/sessions_test.go b/internal/app/sessions_test.go
similarity index 99%
rename from cmd/dotagents/sessions_test.go
rename to internal/app/sessions_test.go
index 77f4c74..16fd91e 100644
--- a/cmd/dotagents/sessions_test.go
+++ b/internal/app/sessions_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/setup.go b/internal/app/setup.go
similarity index 99%
rename from cmd/dotagents/setup.go
rename to internal/app/setup.go
index e43322b..f3eec31 100644
--- a/cmd/dotagents/setup.go
+++ b/internal/app/setup.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/setup_scaffold.go b/internal/app/setup_scaffold.go
similarity index 93%
rename from cmd/dotagents/setup_scaffold.go
rename to internal/app/setup_scaffold.go
index 37f513c..d7c30ef 100644
--- a/cmd/dotagents/setup_scaffold.go
+++ b/internal/app/setup_scaffold.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
@@ -13,6 +13,7 @@ import (
 	"strings"
 
 	starter "github.com/yourconscience/dotagents"
+	"github.com/yourconscience/dotagents/internal/agentrole"
 	"gopkg.in/yaml.v3"
 )
 
@@ -79,7 +80,11 @@ func ensureStarterAssets(root string, configPath string) error {
 		if path == "." {
 			return nil
 		}
-		target := filepath.Join(root, filepath.FromSlash(path))
+		targetPath := path
+		if strings.HasSuffix(targetPath, "/go.mod.template") {
+			targetPath = strings.TrimSuffix(targetPath, ".template")
+		}
+		target := filepath.Join(root, filepath.FromSlash(targetPath))
 		if path == "dotagents.yaml" {
 			target = configPath
 		}
@@ -415,7 +420,7 @@ func scanNativeSkills(agent agentConfig, canonicalSkills string) ([]nativeSkillC
 
 func scanNativeRoles(agent agentConfig, canonicalAgents string) ([]nativeRoleCandidate, error) {
 	h := harnessFor(agent.Name)
-	if h == nil || h.Roles == nil {
+	if h == nil || h.roles == nil {
 		return nil, nil
 	}
 	entries, err := os.ReadDir(agent.AgentRoot)
@@ -427,7 +432,7 @@ func scanNativeRoles(agent agentConfig, canonicalAgents string) ([]nativeRoleCan
 	}
 	var out []nativeRoleCandidate
 	for _, entry := range entries {
-		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || filepath.Ext(entry.Name()) != h.Roles.Extension {
+		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || filepath.Ext(entry.Name()) != h.roles.Extension() {
 			continue
 		}
 		path := filepath.Join(agent.AgentRoot, entry.Name())
@@ -435,7 +440,7 @@ func scanNativeRoles(agent agentConfig, canonicalAgents string) ([]nativeRoleCan
 		if err != nil {
 			return nil, fmt.Errorf("stat %s: %w", path, err)
 		}
-		if info.Mode()&os.ModeSymlink != 0 || sameResolvedPath(path, filepath.Join(canonicalAgents, strings.TrimSuffix(entry.Name(), h.Roles.Extension)+agentRoleMarkdownExt)) {
+		if info.Mode()&os.ModeSymlink != 0 || sameResolvedPath(path, filepath.Join(canonicalAgents, strings.TrimSuffix(entry.Name(), h.roles.Extension())+agentrole.MarkdownExtension)) {
 			continue
 		}
 		data, err := os.ReadFile(path)
@@ -445,7 +450,7 @@ func scanNativeRoles(agent agentConfig, canonicalAgents string) ([]nativeRoleCan
 		if isManagedAgentFile(path, data, filepath.Dir(filepath.Dir(canonicalAgents))) {
 			continue
 		}
-		name := normalizeAgentName(strings.TrimSuffix(entry.Name(), h.Roles.Extension))
+		name := normalizeAgentName(strings.TrimSuffix(entry.Name(), h.roles.Extension()))
 		candidate := nativeRoleCandidate{nativeImportCandidate: nativeImportCandidate{Name: name, Origin: agent.Name, Path: path}, TargetName: name, Data: append([]byte(nil), data...)}
 		switch agent.Name {
 		case agentCodex:
@@ -631,12 +636,12 @@ func codexMCPServerNames(content string) []string {
 
 func convertNativeRoleMarkdown(path string, data []byte, fallbackName string) ([]byte, error) {
 	if bytes.HasPrefix(data, []byte("---\n")) {
-		if _, err := parseAgentRoleMarkdown(path, data); err == nil {
+		if _, err := agentrole.ParseMarkdown(path, data); err == nil {
 			return data, nil
 		}
 	}
-	role := agentRole{Name: fallbackName, Description: "Imported from " + path, Model: "opus", Effort: "high", Instructions: strings.TrimSpace(string(data))}
-	return renderCanonicalRoleMarkdown(role)
+	role := agentrole.Role{Name: fallbackName, Description: "Imported from " + path, Model: "opus", Effort: "high", Instructions: strings.TrimSpace(string(data))}
+	return agentrole.RenderCanonical(role)
 }
 
 func convertCodexRoleTOMLToMarkdown(path string, data []byte) ([]byte, error) {
@@ -668,37 +673,8 @@ func convertCodexRoleTOMLToMarkdown(path string, data []byte) ([]byte, error) {
 	if strings.TrimSpace(instructions) == "" {
 		instructions = strings.TrimSpace(string(data))
 	}
-	role := agentRole{Name: name, Description: description, Effort: effort, Instructions: instructions, Codex: codexRoleOptions{Model: model, ModelReasoningEffort: effort}}
-	return renderCanonicalRoleMarkdown(role)
-}
-
-func renderCanonicalRoleMarkdown(role agentRole) ([]byte, error) {
-	if err := finalizeAgentRole(&role, "imported role"); err != nil {
-		return nil, err
-	}
-	front := struct {
-		Name        string              `yaml:"name"`
-		Description string              `yaml:"description"`
-		Model       string              `yaml:"model,omitempty"`
-		Effort      string              `yaml:"effort,omitempty"`
-		Tools       []string            `yaml:"tools,omitempty"`
-		Color       string              `yaml:"color,omitempty"`
-		Claude      claudeRoleOptions   `yaml:"claude,omitempty"`
-		Codex       codexRoleOptions    `yaml:"codex,omitempty"`
-		Droid       droidRoleOptions    `yaml:"droid,omitempty"`
-		Opencode    opencodeRoleOptions `yaml:"opencode,omitempty"`
-		OMP         ompRoleOptions      `yaml:"omp,omitempty"`
-		Pi          piRoleOptions       `yaml:"pi,omitempty"`
-	}{
-		Name: role.Name, Description: role.Description, Model: role.Model, Effort: role.Effort,
-		Tools: role.Tools, Color: role.Color, Claude: role.Claude, Codex: role.Codex,
-		Droid: role.Droid, Opencode: role.Opencode, OMP: role.OMP, Pi: role.Pi,
-	}
-	meta, err := yaml.Marshal(front)
-	if err != nil {
-		return nil, err
-	}
-	return []byte("---\n" + string(meta) + "---\n\n" + strings.TrimSpace(role.Instructions) + "\n"), nil
+	role := agentrole.Role{Name: name, Description: description, Effort: effort, Instructions: instructions, Codex: agentrole.CodexOptions{Model: model, ModelReasoningEffort: effort}}
+	return agentrole.RenderCanonical(role)
 }
 
 // confirmDestructiveSyncActions previews per-harness removals and role
@@ -811,7 +787,7 @@ func importNativeContent(root string, cfg *config, skills []nativeSkillCandidate
 			if err != nil {
 				return err
 			}
-			path := filepath.Join(root, "agents", role.TargetName+agentRoleMarkdownExt)
+			path := filepath.Join(root, "agents", role.TargetName+agentrole.MarkdownExtension)
 			if _, err := os.Lstat(path); err == nil {
 				continue
 			} else if !errors.Is(err, fs.ErrNotExist) {
diff --git a/cmd/dotagents/setup_separation_test.go b/internal/app/setup_separation_test.go
similarity index 99%
rename from cmd/dotagents/setup_separation_test.go
rename to internal/app/setup_separation_test.go
index 68e6e8d..ee58a5a 100644
--- a/cmd/dotagents/setup_separation_test.go
+++ b/internal/app/setup_separation_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"bytes"
@@ -117,6 +117,8 @@ func TestEnsureStarterAssetsCreatesMissingOnlyAndExecutableHooks(t *testing.T) {
 		filepath.Join(root, "agents", "architect.md"),
 		filepath.Join(root, "agents", "tester.md"),
 		filepath.Join(root, "memory", "lib", "basic_memory.py"),
+		filepath.Join(root, "memory", "tools", "rem", "main.go"),
+		filepath.Join(root, "memory", "tools", "knowledge-sync", "main.go"),
 	} {
 		if _, err := os.Stat(path); err != nil {
 			t.Fatalf("starter asset %s missing: %v", path, err)
diff --git a/cmd/dotagents/setup_test.go b/internal/app/setup_test.go
similarity index 99%
rename from cmd/dotagents/setup_test.go
rename to internal/app/setup_test.go
index 3f7841b..f4b77c7 100644
--- a/cmd/dotagents/setup_test.go
+++ b/internal/app/setup_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/skill_collision_test.go b/internal/app/skill_collision_test.go
similarity index 99%
rename from cmd/dotagents/skill_collision_test.go
rename to internal/app/skill_collision_test.go
index 93dec00..71c0454 100644
--- a/cmd/dotagents/skill_collision_test.go
+++ b/internal/app/skill_collision_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/skill_discovery.go b/internal/app/skill_discovery.go
similarity index 99%
rename from cmd/dotagents/skill_discovery.go
rename to internal/app/skill_discovery.go
index 7e2c806..b1f911e 100644
--- a/cmd/dotagents/skill_discovery.go
+++ b/internal/app/skill_discovery.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"fmt"
diff --git a/cmd/dotagents/skill_list.go b/internal/app/skill_list.go
similarity index 99%
rename from cmd/dotagents/skill_list.go
rename to internal/app/skill_list.go
index 77c5aa1..8453248 100644
--- a/cmd/dotagents/skill_list.go
+++ b/internal/app/skill_list.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
@@ -211,7 +211,7 @@ func runSkillList(args []string) error {
 			continue
 		}
 		h := harnessFor(report.Name)
-		if h != nil && h.Skills == SkillsConfigDriven {
+		if h != nil && h.Skills == skillsConfigDriven {
 			if missing := integrationMissing(report); len(missing) > 0 {
 				fmt.Printf("  integration missing: %s\n", displayList(missing))
 			}
diff --git a/cmd/dotagents/skill_list_test.go b/internal/app/skill_list_test.go
similarity index 99%
rename from cmd/dotagents/skill_list_test.go
rename to internal/app/skill_list_test.go
index 518c38c..04857ee 100644
--- a/cmd/dotagents/skill_list_test.go
+++ b/internal/app/skill_list_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/skillify.go b/internal/app/skillify.go
similarity index 99%
rename from cmd/dotagents/skillify.go
rename to internal/app/skillify.go
index d0d3732..d20ad1a 100644
--- a/cmd/dotagents/skillify.go
+++ b/internal/app/skillify.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"flag"
diff --git a/cmd/dotagents/skillspec.go b/internal/app/skillspec.go
similarity index 99%
rename from cmd/dotagents/skillspec.go
rename to internal/app/skillspec.go
index edbd752..753df99 100644
--- a/cmd/dotagents/skillspec.go
+++ b/internal/app/skillspec.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 // Validates skills/*/SKILL.md against the Agent Skills standard
 // (https://agentskills.io/specification).
diff --git a/cmd/dotagents/skillspec_test.go b/internal/app/skillspec_test.go
similarity index 99%
rename from cmd/dotagents/skillspec_test.go
rename to internal/app/skillspec_test.go
index 93ea9fd..30d26db 100644
--- a/cmd/dotagents/skillspec_test.go
+++ b/internal/app/skillspec_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"os"
diff --git a/cmd/dotagents/sync.go b/internal/app/sync.go
similarity index 98%
rename from cmd/dotagents/sync.go
rename to internal/app/sync.go
index 33c91ee..b6eb44c 100644
--- a/cmd/dotagents/sync.go
+++ b/internal/app/sync.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
@@ -189,7 +189,7 @@ func applyAgentSync(reports []agentReport, cfg config, repoRoot string, home str
 			return fmt.Errorf("%s has conflicts", report.Name)
 		}
 		h := harnessFor(report.Name)
-		if h != nil && h.Skills == SkillsConfigDriven {
+		if h != nil && h.Skills == skillsConfigDriven {
 			if err := applyConfigDrivenSkillDrift(report, h, cfg, repoRoot, home); err != nil {
 				return err
 			}
@@ -245,7 +245,7 @@ func linkExpectedSkills(report agentReport) error {
 	return nil
 }
 
-func applyConfigDrivenSkillDrift(report agentReport, h *Harness, cfg config, repoRoot string, home string) error {
+func applyConfigDrivenSkillDrift(report agentReport, h *harness, cfg config, repoRoot string, home string) error {
 	if h.Setup == nil || (len(report.Adds) == 0 && len(report.Updates) == 0 && len(report.Removes) == 0) {
 		return nil
 	}
diff --git a/cmd/dotagents/sync_test.go b/internal/app/sync_test.go
similarity index 99%
rename from cmd/dotagents/sync_test.go
rename to internal/app/sync_test.go
index 200db3f..0cdb27f 100644
--- a/cmd/dotagents/sync_test.go
+++ b/internal/app/sync_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"encoding/json"
diff --git a/cmd/dotagents/view.go b/internal/app/view.go
similarity index 99%
rename from cmd/dotagents/view.go
rename to internal/app/view.go
index 9c8b6d6..14d8ca9 100644
--- a/cmd/dotagents/view.go
+++ b/internal/app/view.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"errors"
diff --git a/cmd/dotagents/view_test.go b/internal/app/view_test.go
similarity index 99%
rename from cmd/dotagents/view_test.go
rename to internal/app/view_test.go
index c7953b0..de81b62 100644
--- a/cmd/dotagents/view_test.go
+++ b/internal/app/view_test.go
@@ -1,4 +1,4 @@
-package main
+package app
 
 import (
 	"strings"
diff --git a/cmd/dotagents/web/app.js b/internal/app/web/app.js
similarity index 100%
rename from cmd/dotagents/web/app.js
rename to internal/app/web/app.js
diff --git a/cmd/dotagents/web/index.html b/internal/app/web/index.html
similarity index 100%
rename from cmd/dotagents/web/index.html
rename to internal/app/web/index.html
diff --git a/cmd/dotagents/web/style.css b/internal/app/web/style.css
similarity index 100%
rename from cmd/dotagents/web/style.css
rename to internal/app/web/style.css
diff --git a/memory/README.md b/memory/README.md
index 61d1de2..5132558 100644
--- a/memory/README.md
+++ b/memory/README.md
@@ -1,63 +1,72 @@
 # memory
 
-Agent-agnostic session memory and private data sync for dotagents.
+Agent-agnostic session memory and private Hermes-vault synchronization for
+dotagents. Session capture writes bounded, redacted digests; it never promotes
+facts into durable profile or agent instructions automatically.
 
-This directory is the **canonical upstream** of the memory layer: hook
-entrypoints capture compact session digests, `rem` captures explicit facts,
-consolidation is report-first, and `knowledge-sync` keeps the knowledge vault
-git-synced. User repos deployed via `dotagents setup` carry their own copy of
-`memory/lib`, `memory/hooks`, and `memory/tools`; `dotagents sync` builds the
-tools and this repo carries the tested reference implementations.
-
-## The rem workflow
+## Setup and shipped tools
 
 ```bash
-rem add -src claude "prefers pnpm for Node work"   # capture a candidate fact anywhere
-rem dream                                          # consolidation report (report-only)
-rem dream --apply                                  # collapse exact-duplicate records
-rem search "quota preferences"                     # semantic search via memsearch
-rem sync                                           # flush the vault via knowledge-sync
+dotagents setup --memory basic      # default; Python 3 only
+dotagents setup --memory off        # no managed memory hooks
+dotagents setup --memory memsearch  # derived search index; requires memsearch
 ```
 
-Candidates are inert until promoted into durable instructions — consolidation
-is report-first by design. See [tools/rem/README.md](tools/rem/README.md).
+A fresh setup scaffolds `memory/hooks`, `memory/lib`, and the Go sources for
+`memory/tools/rem` and `memory/tools/knowledge-sync`. `dotagents sync` builds
+those source packages and installs `rem` and `knowledge-sync` into `$GOBIN` or
+`~/.local/bin`; no prebuilt binaries are shipped. The repository tests both
+packages in its root module, while setup materializes each embedded
+`go.mod.template` as `go.mod` so a user-owned config root builds independently.
+
+| Tier | Behavior | Dependency |
+|---|---|---|
+| `off` | no managed memory hooks | none |
+| `basic` | session start context plus bounded session-end digests | Python 3 |
+| `memsearch` | the same canonical vault plus a disposable search index | Python 3, `memsearch` |
+
+## One capture and consolidation pipeline
 
-## Setup
+All locally captured Amp, Droid/Factory, Hermes, Codex, OMP-compatible, and
+Claude fallback payloads are normalized by `lib/basic_memory.py` and written as
+the same digest format under `$KNOWLEDGE_DIR/sessions`. Provider-specific code
+only classifies payloads or loads a provider-owned session file. The shared
+shell helper performs the one bounded, non-overlapping refresh after a new
+digest or a successful Hermes bridge sync.
 
-Choose a tier through the CLI:
+`rem dream` is the only supported consolidation workflow:
 
 ```bash
-dotagents setup --memory basic      # default; Python 3 only
-dotagents setup --memory off        # no managed memory hooks
-dotagents setup --memory memsearch  # indexed search; requires memsearch on PATH
+rem add -src claude "prefers pnpm for Node work"
+rem dream                  # report-only candidate consolidation
+rem dream --apply          # guarded exact-duplicate cleanup
+rem search "preferences"  # memsearch collection ai
+rem sync                   # guarded knowledge-sync
 ```
 
-| Tier | Behavior | Dependency |
-|---|---|---|
-| `off` | no managed memory hooks | none |
-| `basic` | bounded session digests into the knowledge vault | Python 3 |
-| `memsearch` | adds a derived search index over the vault | `memsearch` |
+Captured candidates and digests remain inert until a person reviews and
+promotes them.
 
-For the `memsearch` tier, bring any machine to full parity (install, config,
-index, verify) with `tools/memsearch/install-parity.sh`. The per-machine index
-is derived and disposable; only the vault markdown is canonical. Freshness is
-kept by two idempotent triggers (reindex-after-sync in `knowledge-sync`,
-reindex-after-capture in the capture path), not a cron -- see
-[tools/memsearch/README.md](tools/memsearch/README.md) for the parity steps and
-the shared reindex contract.
+## Managed hook boundary
 
-## Layout
+The CLI only manages hooks exposed by the harness registry:
 
-- `hooks/` — lifecycle entrypoints (session start/end/stop) registered per harness
-- `lib/` — Python implementation: `basic_memory.py` (digests, dream-pass parsing),
-  `sync.py` (Hermes memory ↔ vault), `safety.py`
-- `tools/` — `rem` and `knowledge-sync` (Go binaries built by `dotagents sync`),
-  and `memsearch/` (parity installer + reindex contract)
-- `tests/` — reference test suite
+- Claude Code, Codex, and Droid/Factory: verified start/stop/end events as
+  available for the selected tier.
+- Hermes: verified native session events, including the existing Hermes vault
+  bridge wrappers.
+- Amp, OMP, and Pi: no managed hook installation. The dispatcher retains cheap
+  compatibility for legacy Amp/OMP payloads, but users should not treat that as
+  a managed native integration.
 
-## Relationship to user repos
+`hooks/sync.sh` remains solely for legacy path migration.
+
+## Layout
 
-`dotagents` (this repo) is upstream: changes land here first, with tests. Your
-`~/.agents` repository (created by `setup`) carries the deployed copy; `sync`
-rebuilds the binaries whenever the sources change. Keep the two in sync by
-porting changes here, then pulling in the user repo.
+- `hooks/` — managed lifecycle wrappers and the shared refresh helper
+- `lib/basic_memory.py` — payload normalization, digest capture, and start context
+- `lib/sync.py` — Hermes memory ↔ vault bridge (no index implementation)
+- `lib/safety.py` — locking, redaction, and safe filesystem helpers
+- `tools/rem/`, `tools/knowledge-sync/` — shipped Go package sources
+- `tools/memsearch/` — optional memsearch parity guidance
+- `tests/` — dependency-free Python behavior tests
diff --git a/memory/hooks/README-codex-omp.md b/memory/hooks/README-codex-omp.md
deleted file mode 100644
index 3a94719..0000000
--- a/memory/hooks/README-codex-omp.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Codex and OMP/Pi memory capture
-
-Claude Code capture is wired automatically by `dotagents setup`. Codex and
-OMP/Pi have no session-end hook that dotagents installs for them, so their
-automatic capture is opt-in and wired manually. Both route through the same
-`session-end.sh` dispatcher, which classifies a Codex/OMP payload and writes the
-local `basic_memory` digest — the same digest Claude produces.
-
-Reminder for both harnesses: automatic digests are a safety net, not a
-substitute for deliberate capture. Record durable cross-harness facts explicitly
-with `rem add -src codex "<fact>"` / `rem add -src omp "<fact>"`.
-
-## Codex
-
-Codex emits Claude-compatible Stop/SessionEnd payloads (with `transcript_path`
-and `model`). Add a hook to `~/.codex/hooks.json` on `SessionEnd` (preferred) or
-`Stop`, setting `DOTAGENTS_MEMORY_SOURCE=codex` so the digest is labelled and so
-the `Stop`-wired path captures rather than passing through:
-
-```json
-{
-  "type": "command",
-  "command": "DOTAGENTS_MEMORY_SOURCE=codex ~/.agents/memory/hooks/session-end.sh",
-  "timeout": 30
-}
-```
-
-Reminder: also `rem add -src codex "<fact>"` for facts worth promoting.
-
-## OMP / Pi
-
-OMP/Pi has no session-end hook but supports extensions that fire on
-`agent_end`. Install the shipped extension:
-
-```sh
-cp ~/.agents/memory/hooks/omp-memory.ts ~/.omp/agent/extensions/
-```
-
-It pipes an `agent: "omp"` payload into `session-end.sh` on every `agent_end`.
-Set `DOTAGENTS_MEMORY_HOOKS` if your dotagents checkout is not at `~/.agents`.
-
-Reminder: also `rem add -src omp "<fact>"` for facts worth promoting.
diff --git a/memory/hooks/common.sh b/memory/hooks/common.sh
index 8ca2623..7e07067 100755
--- a/memory/hooks/common.sh
+++ b/memory/hooks/common.sh
@@ -132,14 +132,14 @@ else:
 PY
 }
 
-# Write a local basic_memory digest for the payload, then fire a bounded,
-# non-overlapping reindex only when a new digest was actually appended. Used by
-# the Claude fallback and by Codex/OMP capture so the logic lives in one place.
+# Write a digest through the shared basic_memory implementation, then fire a
+# bounded, non-overlapping reindex only when a new digest was actually appended.
 dispatch_basic_digest() {
-  if digest_output="$(python3 "$MEMORY_DIR/hooks/basic-session-end.py" <"$1")"; then
+  digest_source="${2:-}"
+  if digest_output="$(DOTAGENTS_MEMORY_SOURCE="$digest_source" python3 "$MEMORY_DIR/hooks/basic-session-end.py" <"$1")"; then
     printf '%s\n' "$digest_output"
     case "$digest_output" in
-      *'"systemMessage":"basic memory appended'*) refresh_index_async ;;
+      *'"systemMessage":"basic memory appended'*|*'"message": "memsearch updated from'*|*'"systemMessage":"memsearch updated from'*) refresh_index_async ;;
     esac
   else
     printf '{"continue":true,"suppressOutput":true}\n'
diff --git a/memory/hooks/omp-memory.ts b/memory/hooks/omp-memory.ts
deleted file mode 100644
index 038b017..0000000
--- a/memory/hooks/omp-memory.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-// dotagents OMP/Pi memory extension.
-//
-// OMP/Pi exposes no session-end hook of its own, so this extension captures a
-// basic_memory digest on `agent_end` by piping an OMP-tagged payload into the
-// shared session-end dispatch (memory/hooks/session-end.sh), which classifies
-// `agent: "omp"` and writes the same local digest Claude and Codex use.
-//
-// Manual wiring (dotagents does not install OMP extensions automatically):
-//   cp ~/.agents/memory/hooks/omp-memory.ts ~/.omp/agent/extensions/
-// Override the hook location with DOTAGENTS_MEMORY_HOOKS if your dotagents
-// checkout is not at ~/.agents.
-//
-// Reminder: automatic digests are a net, not a replacement. Capture deliberate
-// cross-harness facts explicitly with:  rem add -src omp "<fact>"
-import { spawn } from "node:child_process";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { AgentEndEvent, ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
-
-function hooksDir(): string {
-  return process.env.DOTAGENTS_MEMORY_HOOKS || path.join(os.homedir(), ".agents", "memory", "hooks");
-}
-
-function digestMessages(event: AgentEndEvent): Array<{ role: string; content: unknown }> {
-  const messages: Array<{ role: string; content: unknown }> = [];
-  for (const message of event.messages || []) {
-    if (!message || typeof message !== "object") continue;
-    const typed = message as { role?: unknown; content?: unknown };
-    if (typeof typed.role !== "string" || typed.content == null) continue;
-    messages.push({ role: typed.role, content: typed.content });
-  }
-  return messages;
-}
-
-function captureDigest(ctx: ExtensionContext, event: AgentEndEvent): void {
-  const sessionId = ctx.sessionManager.getSessionId();
-  if (!sessionId) return;
-  const cwd = ctx.cwd || process.cwd();
-  const payload = JSON.stringify({
-    agent: "omp",
-    hook_event_name: "SessionEnd",
-    session_id: sessionId,
-    cwd,
-    messages: digestMessages(event),
-  });
-  try {
-    const child = spawn(path.join(hooksDir(), "session-end.sh"), [], {
-      env: { ...process.env, DOTAGENTS_MEMORY_SOURCE: "omp" },
-      stdio: ["pipe", "ignore", "ignore"],
-      detached: true,
-    });
-    child.on("error", () => {});
-    child.unref();
-    child.stdin.on("error", () => {});
-    child.stdin.end(payload);
-  } catch (_) {
-    // Best-effort: never let memory capture break the session.
-  }
-}
-
-export default function dotagentsOmpMemoryExtension(api: ExtensionAPI) {
-  api.on("agent_end", async (event, ctx) => {
-    captureDigest(ctx, event);
-  });
-}
diff --git a/memory/hooks/session-end.sh b/memory/hooks/session-end.sh
index 7631594..3e9b31f 100755
--- a/memory/hooks/session-end.sh
+++ b/memory/hooks/session-end.sh
@@ -19,17 +19,16 @@ kind="$(classify_payload "$payload")"
 
 case "$kind" in
   amp-json)
-    python3 "$MEMORY_DIR/lib/amp_digest.py" <"$payload"
+    dispatch_basic_digest "$payload" amp
     ;;
   factory-jsonl)
-    python3 "$MEMORY_DIR/lib/factory_digest.py" <"$payload"
+    dispatch_basic_digest "$payload" droid
     ;;
   hermes-json)
-    python3 "$MEMORY_DIR/lib/hermes_digest.py" <"$payload"
+    dispatch_basic_digest "$payload" hermes
     ;;
   codex|omp)
-    # Codex/OMP capture always uses the local basic_memory digest.
-    dispatch_basic_digest "$payload"
+    dispatch_basic_digest "$payload" "$kind"
     ;;
   *)
     plugin_dir="$(resolve_claude_memory_plugin || true)"
diff --git a/memory/hooks/stop.sh b/memory/hooks/stop.sh
index 3a86ce2..6e78827 100755
--- a/memory/hooks/stop.sh
+++ b/memory/hooks/stop.sh
@@ -21,7 +21,7 @@ cat >"$payload"
 kind="$(classify_payload "$payload")"
 case "$kind" in
   codex|omp)
-    dispatch_basic_digest "$payload"
+    dispatch_basic_digest "$payload" "$kind"
     exit 0
     ;;
 esac
diff --git a/memory/hooks/sync-memory-to-vault.sh b/memory/hooks/sync-memory-to-vault.sh
index 6d7824e..20c78e0 100755
--- a/memory/hooks/sync-memory-to-vault.sh
+++ b/memory/hooks/sync-memory-to-vault.sh
@@ -13,6 +13,9 @@ rm -f "$TMP"
 if [ -n "$OUTPUT" ]; then
   printf '%s\n' "$OUTPUT" >&2
 fi
+if [ "$STATUS" -eq 0 ]; then
+  refresh_index_async
+fi
 
 python3 - "$STATUS" "$OUTPUT" <<'PY'
 import json
diff --git a/memory/hooks/sync-vault-to-memory.sh b/memory/hooks/sync-vault-to-memory.sh
index 1340dd4..23d58c3 100755
--- a/memory/hooks/sync-vault-to-memory.sh
+++ b/memory/hooks/sync-vault-to-memory.sh
@@ -13,6 +13,9 @@ rm -f "$TMP"
 if [ -n "$OUTPUT" ]; then
   printf '%s\n' "$OUTPUT" >&2
 fi
+if [ "$STATUS" -eq 0 ]; then
+  refresh_index_async
+fi
 
 python3 - "$STATUS" "$OUTPUT" <<'PY'
 import json
diff --git a/memory/lib/amp_digest.py b/memory/lib/amp_digest.py
deleted file mode 100644
index 90bc571..0000000
--- a/memory/lib/amp_digest.py
+++ /dev/null
@@ -1,199 +0,0 @@
-#!/usr/bin/env python3
-"""Append an Amp session digest to the shared knowledge vault."""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-import subprocess
-import sys
-from datetime import datetime
-from datetime import timezone
-from pathlib import Path
-from typing import Any
-
-from safety import atomic_write_text, locked_directory, redact_text, safe_identifier, truncate_redacted
-
-
-PATH_RE = re.compile(r"(?:~?/[^\s`'\"\\]+|/Users/[^\s`'\"\\]+|\./[^\s`'\"\\]+)")
-
-
-def truncate(text: str, limit: int = 220) -> str:
-    return truncate_redacted(text, limit)
-
-
-def parse_start(value: Any) -> datetime:
-    if isinstance(value, str) and value.strip():
-        normalized = value.strip().replace("Z", "+00:00")
-        try:
-            return datetime.fromisoformat(normalized)
-        except ValueError:
-            pass
-    return datetime.now(timezone.utc)
-
-
-def content_text(content: Any) -> str:
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        parts: list[str] = []
-        for item in content:
-            if isinstance(item, dict):
-                text = item.get("text") or item.get("content")
-                if isinstance(text, str):
-                    parts.append(text)
-        return "\n".join(parts)
-    return ""
-
-
-def collect_user_turns(messages: list[dict[str, Any]]) -> list[str]:
-    turns: list[str] = []
-    for msg in messages:
-        if msg.get("role") != "user":
-            continue
-        text = content_text(msg.get("content")).strip()
-        if text:
-            turns.append(text)
-    return turns
-
-
-def nonempty_assistant_text(messages: list[dict[str, Any]]) -> str:
-    for msg in reversed(messages):
-        if msg.get("role") != "assistant":
-            continue
-        text = content_text(msg.get("content")).strip()
-        if text:
-            return text
-    return ""
-
-
-def extract_paths(messages: list[dict[str, Any]]) -> list[str]:
-    found: list[str] = []
-    seen: set[str] = set()
-    for msg in messages:
-        text = content_text(msg.get("content"))
-        for match in PATH_RE.findall(text):
-            cleaned = redact_text(match.rstrip(".,;:)"))
-            if cleaned.startswith("/Users/") or cleaned.startswith("~/") or cleaned.startswith("./"):
-                if cleaned not in seen:
-                    seen.add(cleaned)
-                    found.append(cleaned)
-        if len(found) >= 8:
-            break
-    return found[:8]
-
-
-def build_block(data: dict[str, Any]) -> str:
-    session_id = safe_identifier(data.get("session_id") or data.get("amp_thread_id") or "unknown")
-    started = parse_start(data.get("session_start"))
-    started_human = started.strftime("%Y-%m-%d %H:%M")
-    messages = data.get("messages") if isinstance(data.get("messages"), list) else []
-    users = collect_user_turns(messages)
-    final_assistant = nonempty_assistant_text(messages)
-    paths = extract_paths(messages)
-    model = truncate(str(data.get("model") or ""), 120)
-
-    lines = [
-        f"<!-- amp-session:{session_id}:start -->",
-        f"## Amp session {started_human} - {session_id}",
-        "",
-    ]
-    meta = ["platform: amp"]
-    if model:
-        meta.append(f"model: {model}")
-    lines.append(f"- {'; '.join(meta)}")
-    if users:
-        lines.append(f"- first request: {truncate(users[0], 260)}")
-    if len(users) > 1:
-        lines.append("- user follow-ups:")
-        for text in users[1:6]:
-            lines.append(f"  - {truncate(text, 220)}")
-    if final_assistant:
-        lines.append(f"- final assistant output: {truncate(final_assistant, 420)}")
-    if paths:
-        lines.append("- paths mentioned:")
-        for path in paths:
-            lines.append(f"  - `{truncate(path, 180)}`")
-    lines.extend(
-        [
-            "",
-            f"<!-- amp-session:{session_id}:end -->",
-            "",
-        ]
-    )
-    return "\n".join(lines)
-
-
-def update_daily_file(sessions_dir: Path, data: dict[str, Any]) -> Path:
-    started = parse_start(data.get("session_start"))
-    target = sessions_dir / f"{started.strftime('%Y-%m-%d')}.md"
-    session_id = safe_identifier(data.get("session_id") or data.get("amp_thread_id") or "unknown")
-    session_marker_re = re.compile(
-        rf"<!-- amp-session:{re.escape(session_id)}:start -->.*?<!-- amp-session:{re.escape(session_id)}:end -->\n?",
-        re.DOTALL,
-    )
-
-    with locked_directory(sessions_dir):
-        existing = ""
-        session_files = sorted({*sessions_dir.glob("*.md"), *sessions_dir.glob("*.markdown")})
-        for path in session_files:
-            text = path.read_text(encoding="utf-8")
-            cleaned = session_marker_re.sub("", text).rstrip()
-            if path == target:
-                existing = cleaned
-            elif cleaned != text.rstrip():
-                atomic_write_text(path, cleaned + "\n" if cleaned else "")
-        if not existing and target.exists() and target not in session_files:
-            existing = session_marker_re.sub("", target.read_text(encoding="utf-8")).rstrip()
-
-        block = build_block(data).rstrip() + "\n"
-        atomic_write_text(target, (existing + "\n\n" + block).lstrip() if existing else block)
-    return target
-
-
-def reindex(notes_dir: str, profile_dir: str, sessions_dir: Path, collection: str) -> None:
-    paths: list[str] = []
-    for pattern in ("*.md", "*.markdown"):
-        paths.extend(str(path) for path in sorted(sessions_dir.glob(pattern)) if path.is_file())
-    try:
-        subprocess.run(
-            ["memsearch", "index", notes_dir, profile_dir, *paths, "--collection", collection],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-    except OSError:
-        pass
-
-
-def main() -> None:
-    payload = json.load(sys.stdin)
-    session_id = payload.get("session_id") or payload.get("amp_thread_id")
-    if not session_id:
-        print(json.dumps({"action": "continue"}))
-        return
-
-    knowledge_dir = Path(os.path.expanduser(os.environ.get("KNOWLEDGE_DIR", "~/Workspace/knowledge")))
-    sessions_dir = Path(os.path.expanduser(os.environ.get("SESSIONS_DIR", str(knowledge_dir / "sessions"))))
-    notes_dir = os.path.expanduser(os.environ.get("NOTES_DIR", str(knowledge_dir / "notes")))
-    profile_dir = os.path.expanduser(os.environ.get("PROFILE_DIR", str(knowledge_dir / "profile")))
-    collection = os.environ.get("MEMSEARCH_COLLECTION", "ai")
-
-    sessions_dir.mkdir(parents=True, exist_ok=True)
-    target = update_daily_file(sessions_dir, payload)
-    reindex(notes_dir, profile_dir, sessions_dir, collection)
-
-    print(
-        json.dumps(
-            {
-                "action": "continue",
-                "message": f"memsearch updated from Amp session {safe_identifier(session_id)}",
-                "output_file": str(target),
-            }
-        )
-    )
-
-
-if __name__ == "__main__":
-    main()
diff --git a/memory/lib/basic_memory.py b/memory/lib/basic_memory.py
index 0bdc469..93c3fa5 100755
--- a/memory/lib/basic_memory.py
+++ b/memory/lib/basic_memory.py
@@ -8,15 +8,11 @@
 
 from __future__ import annotations
 
-import argparse
-import hashlib
 import json
 import os
 import re
 import sys
 import tempfile
-import unicodedata
-from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, TextIO
@@ -157,6 +153,8 @@ def message_from_record(record: dict[str, Any]) -> dict[str, Any] | None:
 
     nested = record.get("message")
     if isinstance(nested, dict):
+        if nested.get("visibility") == "llm_only":
+            return None
         role = nested.get("role") or role
         content = nested.get("content") if "content" in nested else content
         timestamp = nested.get("timestamp") or timestamp
@@ -184,7 +182,13 @@ def inline_messages(payload: dict[str, Any]) -> list[dict[str, Any]]:
     return parsed
 
 
-def read_transcript(path: Path) -> tuple[list[dict[str, Any]], datetime | None, str | None]:
+def read_transcript(path: Path, tolerant: bool = False) -> tuple[list[dict[str, Any]], datetime | None, str | None]:
+    """Read a JSONL transcript.
+
+    tolerant skips undecodable lines instead of failing. Factory/Droid writes its
+    transcript while the hook may read it, so a partially written trailing record
+    must not discard the whole session.
+    """
     if not path.exists():
         return [], None, None
     if not path.is_file():
@@ -202,6 +206,8 @@ def read_transcript(path: Path) -> tuple[list[dict[str, Any]], datetime | None,
                 try:
                     record = json.loads(raw)
                 except json.JSONDecodeError as exc:
+                    if tolerant:
+                        continue
                     raise HookError(f"invalid JSONL transcript at {path}:{line_number}: {exc.msg}") from exc
                 if not isinstance(record, dict):
                     continue
@@ -219,6 +225,61 @@ def read_transcript(path: Path) -> tuple[list[dict[str, Any]], datetime | None,
     return messages, started, transcript_session_id
 
 
+def provider_source(payload: dict[str, Any]) -> str:
+    hint = os.environ.get("DOTAGENTS_MEMORY_SOURCE", "").strip().lower()
+    if hint:
+        return hint
+    marker = str(payload.get("platform") or payload.get("agent") or "").strip().lower()
+    if marker in {"amp", "codex", "omp", "droid", "factory", "hermes"}:
+        return "droid" if marker == "factory" else marker
+    if payload.get("amp_thread_id"):
+        return "amp"
+    transcript = str(payload.get("transcript_path") or "")
+    if "/.factory/" in os.path.expanduser(transcript) and Path(transcript).suffix == ".jsonl":
+        return "droid"
+    session_id = payload.get("session_id") or payload.get("sessionId")
+    if session_id and not transcript and not payload.get("messages"):
+        hermes_home = Path(os.path.expanduser(os.environ.get("HERMES_HOME", "~/.hermes")))
+        if (hermes_home / "sessions" / f"session_{session_id}.json").is_file():
+            return "hermes"
+    return "basic"
+
+
+def normalize_provider_payload(payload: dict[str, Any]) -> tuple[dict[str, Any], str, bool]:
+    """Load provider-owned session data while keeping digest rendering shared.
+
+    The third value reports whether capture may proceed. Hermes content lives in
+    a provider-owned session file that can lag the hook, and recording a stub
+    digest for that session id would make the real transcript look like a replay
+    later, so capture is skipped until the file is readable.
+    """
+    source = provider_source(payload)
+    if source != "hermes":
+        return payload, source, True
+
+    session_id = payload.get("session_id") or payload.get("sessionId")
+    if not session_id:
+        return payload, source, True
+    raw_id = str(session_id)
+    if raw_id != Path(raw_id).name:
+        raise HookError("Hermes session_id must not contain path separators")
+    hermes_home = Path(os.path.expanduser(os.environ.get("HERMES_HOME", "~/.hermes")))
+    session_path = hermes_home / "sessions" / f"session_{raw_id}.json"
+    if not session_path.is_file():
+        return payload, source, False
+    try:
+        session_data = json.loads(session_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HookError(f"cannot read Hermes session file {session_path}: {exc}") from exc
+    if not isinstance(session_data, dict):
+        raise HookError(f"Hermes session file must contain a JSON object: {session_path}")
+    normalized = dict(payload)
+    normalized.update(session_data)
+    normalized.setdefault("session_id", raw_id)
+    normalized["source_transcript"] = str(session_path)
+    return normalized, source, True
+
+
 def collect_messages(payload: dict[str, Any]) -> tuple[list[dict[str, Any]], datetime | None, str | None]:
     messages = inline_messages(payload)
     transcript_started = None
@@ -226,7 +287,8 @@ def collect_messages(payload: dict[str, Any]) -> tuple[list[dict[str, Any]], dat
     transcript = payload.get("transcript_path")
     if isinstance(transcript, str) and transcript.strip():
         transcript_path = Path(os.path.expanduser(transcript)).resolve()
-        transcript_messages, transcript_started, transcript_session_id = read_transcript(transcript_path)
+        tolerant = payload.get("dotagents_memory_source") == "droid"
+        transcript_messages, transcript_started, transcript_session_id = read_transcript(transcript_path, tolerant=tolerant)
         if transcript_messages:
             messages = transcript_messages
     return messages, transcript_started, transcript_session_id
@@ -306,7 +368,8 @@ def build_digest(payload: dict[str, Any], messages: list[dict[str, Any]], starte
     # An explicit source hint wins over payload markers so a conflicting
     # platform/agent field in the payload cannot mislabel the digest.
     platform = (
-        os.environ.get("DOTAGENTS_MEMORY_SOURCE")
+        payload.get("dotagents_memory_source")
+        or os.environ.get("DOTAGENTS_MEMORY_SOURCE")
         or payload.get("platform")
         or payload.get("agent")
         or payload.get("hook_event_name")
@@ -336,6 +399,9 @@ def build_digest(payload: dict[str, Any], messages: list[dict[str, Any]], starte
         lines.append("- paths mentioned:")
         for path in paths:
             lines.append(f"  - `{truncate(path, 180)}`")
+    source_transcript = payload.get("source_transcript") or payload.get("transcript_path")
+    if isinstance(source_transcript, str) and source_transcript.strip():
+        lines.append(f"- source transcript: `{truncate(source_transcript, 220)}`")
     if not users and not assistant:
         lines.append("- summary: Session ended without supported transcript messages in the hook payload.")
 
@@ -355,14 +421,20 @@ def build_digest(payload: dict[str, Any], messages: list[dict[str, Any]], starte
 
 
 def marker_exists(sessions_dir: Path, session_id: str) -> bool:
-    marker = f"<!-- basic-memory-session:{session_id}:start -->"
+    markers = [
+        f"<!-- basic-memory-session:{session_id}:start -->",
+        f"<!-- amp-session:{session_id}:start -->",
+        f"<!-- droid-session:{session_id}:start -->",
+        f"<!-- hermes-session:{session_id}:start -->",
+    ]
     try:
         paths = sorted({*sessions_dir.glob("*.md"), *sessions_dir.glob("*.markdown")})
     except OSError as exc:
         raise HookError(f"cannot list sessions directory {sessions_dir}: {exc}") from exc
     for path in paths:
         try:
-            if marker in path.read_text(encoding="utf-8"):
+            text = path.read_text(encoding="utf-8")
+            if any(marker in text for marker in markers):
                 return True
         except OSError as exc:
             raise HookError(f"cannot read existing session file {path}: {exc}") from exc
@@ -408,7 +480,16 @@ def context_json(context: str) -> str:
 
 def session_end(stdin: TextIO = sys.stdin, stdout: TextIO = sys.stdout) -> int:
     try:
-        payload = parse_payload(stdin)
+        payload, source, provider_ready = normalize_provider_payload(parse_payload(stdin))
+        if not provider_ready:
+            session_id = payload.get("session_id") or payload.get("sessionId")
+            print(
+                json.dumps({"action": "continue", "message": f"Hermes session log not found for {session_id}; capture skipped"}),
+                file=stdout,
+            )
+            return 0
+        if source != "basic":
+            payload["dotagents_memory_source"] = source
         knowledge_dir = knowledge_dir_from_env()
         sessions_dir = ensure_sessions_dir(knowledge_dir)
         messages, transcript_started, transcript_session_id = collect_messages(payload)
@@ -420,10 +501,22 @@ def session_end(stdin: TextIO = sys.stdin, stdout: TextIO = sys.stdout) -> int:
         return _error(str(exc))
 
     if appended:
-        message = f"basic memory appended session digest to {target}"
+        basic_message = f"basic memory appended session digest to {target}"
+    else:
+        basic_message = f"basic memory skipped replayed session {session_id}"
+
+    display_source = {"amp": "Amp", "droid": "Droid", "hermes": "Hermes"}.get(source)
+    if display_source:
+        if appended:
+            message = f"memsearch updated from {display_source} session {session_id}"
+        else:
+            message = f"memory skipped replayed {display_source} session {session_id}"
+        if source in {"amp", "hermes"}:
+            print(json.dumps({"action": "continue", "message": message, "output_file": str(target)}), file=stdout)
+        else:
+            print(continuation_json(output_file=str(target), systemMessage=message), file=stdout)
     else:
-        message = f"basic memory skipped replayed session {session_id}"
-    print(continuation_json(output_file=str(target), systemMessage=message), file=stdout)
+        print(continuation_json(output_file=str(target), systemMessage=basic_message), file=stdout)
     return 0
 
 
@@ -482,412 +575,3 @@ def session_start(stdin: TextIO = sys.stdin, stdout: TextIO = sys.stdout) -> int
         return _error(str(exc))
     print(context_json(context), file=stdout)
     return 0
-
-
-DREAM_START_RE = re.compile(r"^<!-- basic-memory-session:(?P<id>[^:]+):start -->$")
-DREAM_END_TEMPLATE = "<!-- basic-memory-session:{session_id}:end -->"
-DREAM_HEADER_RE = re.compile(
-    r"^## Session (?P<captured>\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC) - (?P<id>.+)$"
-)
-DREAM_PREFERENCE_RE = re.compile(
-    r"^(?:i prefer|i want|please always|always|never|do not|don't)\b",
-    re.IGNORECASE,
-)
-DREAM_CORRECTION_RE = re.compile(
-    r"^(?:correction:|actually,|i was wrong\b|i no longer\b|instead,)",
-    re.IGNORECASE,
-)
-LEGACY_SYNC_RE = re.compile(
-    r"^## Sync (?P<captured>\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC)$"
-)
-
-
-@dataclass(frozen=True)
-class DreamEvidence:
-    path: str
-    line_start: int
-    line_end: int
-    session_id: str
-    captured_at: str
-    quote: str
-
-
-@dataclass(frozen=True)
-class DreamRecord:
-    path: str
-    line_start: int
-    line_end: int
-    session_id: str
-    captured_at: str
-    block: str
-    statements: tuple[DreamEvidence, ...]
-
-
-def dream_normalize(text: str) -> str:
-    normalized = unicodedata.normalize("NFKC", text).casefold()
-    normalized = re.sub(r"\s+", " ", normalized).strip()
-    return normalized.strip(" \t\r\n.,;:!?\"'()[]{}")
-
-
-def dream_statement(text: str) -> str | None:
-    cleaned = redact_text(text).strip()
-    if not cleaned or cleaned.endswith("…"):
-        return None
-    return cleaned
-
-
-def parse_dream_record(path: Path, relative_path: str, lines: list[str], start: int, end: int, session_id: str) -> DreamRecord | None:
-    header_index = start + 1
-    if header_index >= end:
-        return None
-    header = DREAM_HEADER_RE.match(lines[header_index])
-    if not header or header.group("id") != session_id:
-        return None
-    try:
-        captured = datetime.strptime(header.group("captured"), "%Y-%m-%d %H:%M UTC").replace(tzinfo=timezone.utc)
-    except ValueError:
-        return None
-
-    statements: list[DreamEvidence] = []
-    in_followups = False
-    for index in range(header_index + 1, end):
-        line = lines[index]
-        if line.startswith("- first request: "):
-            text = dream_statement(line.removeprefix("- first request: "))
-            in_followups = False
-        elif line == "- user follow-ups:":
-            in_followups = True
-            continue
-        elif in_followups and line.startswith("  - "):
-            text = dream_statement(line.removeprefix("  - "))
-        else:
-            if line.startswith("- "):
-                in_followups = False
-            continue
-        if text is None:
-            continue
-        statements.append(
-            DreamEvidence(
-                path=relative_path,
-                line_start=index + 1,
-                line_end=index + 1,
-                session_id=session_id,
-                captured_at=captured.isoformat().replace("+00:00", "Z"),
-                quote=text,
-            )
-        )
-
-    block = "\n".join(line.rstrip() for line in lines[start : end + 1])
-    return DreamRecord(
-        path=relative_path,
-        line_start=start + 1,
-        line_end=end + 1,
-        session_id=session_id,
-        captured_at=captured.isoformat().replace("+00:00", "Z"),
-        block=block,
-        statements=tuple(statements),
-    )
-
-
-def parse_dream_records(path: Path, knowledge_dir: Path) -> list[DreamRecord]:
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError as exc:
-        raise HookError(f"cannot read session file {path}: {exc}") from exc
-    relative_path = str(path.relative_to(knowledge_dir))
-    records: list[DreamRecord] = []
-    index = 0
-    while index < len(lines):
-        start_match = DREAM_START_RE.match(lines[index])
-        if not start_match:
-            index += 1
-            continue
-        session_id = start_match.group("id")
-        end_marker = DREAM_END_TEMPLATE.format(session_id=session_id)
-        end = index + 1
-        while end < len(lines) and lines[end] != end_marker:
-            end += 1
-        if end >= len(lines):
-            index += 1
-            continue
-        record = parse_dream_record(path, relative_path, lines, index, end, session_id)
-        if record is not None:
-            records.append(record)
-        index = end + 1
-    return records
-
-
-def dream_evidence_dict(evidence: DreamEvidence) -> dict[str, Any]:
-    return {
-        "path": evidence.path,
-        "line_start": evidence.line_start,
-        "line_end": evidence.line_end,
-        "session_id": evidence.session_id,
-        "captured_at": evidence.captured_at,
-        "quote": redact_text(evidence.quote),
-    }
-
-
-def dream_candidate_id(kind: str, normalized_text: str, evidence: list[dict[str, Any]]) -> str:
-    coordinates = [
-        [item["path"], item["line_start"], item["line_end"], item["session_id"]]
-        for item in evidence
-    ]
-    payload = json.dumps([kind, normalized_text, coordinates], ensure_ascii=False, separators=(",", ":"))
-    return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
-
-
-def repeated_dream_candidates(records: list[DreamRecord]) -> list[dict[str, Any]]:
-    grouped: dict[tuple[str, str], list[DreamEvidence]] = {}
-    for record in records:
-        for statement in record.statements:
-            if DREAM_PREFERENCE_RE.match(statement.quote):
-                kind = "repeated_preference"
-            elif DREAM_CORRECTION_RE.match(statement.quote):
-                kind = "repeated_correction"
-            else:
-                continue
-            normalized = dream_normalize(statement.quote)
-            grouped.setdefault((kind, normalized), []).append(statement)
-
-    candidates: list[dict[str, Any]] = []
-    for (kind, normalized), occurrences in sorted(grouped.items()):
-        by_session: dict[str, DreamEvidence] = {}
-        for occurrence in sorted(
-            occurrences,
-            key=lambda item: (item.path, item.line_start, item.session_id),
-        ):
-            by_session.setdefault(occurrence.session_id, occurrence)
-        if len(by_session) < 2:
-            continue
-        evidence = [dream_evidence_dict(item) for item in by_session.values()]
-        action = "promote_for_review"
-        candidates.append(
-            {
-                "id": dream_candidate_id(kind, normalized, evidence),
-                "kind": kind,
-                "status": "proposed",
-                "normalized_text": normalized,
-                "reason": f"Exact explicit statement appears in {len(evidence)} distinct sessions.",
-                "proposed_action": action,
-                "evidence": evidence,
-            }
-        )
-    return candidates
-
-
-def record_evidence(record: DreamRecord) -> dict[str, Any]:
-    return {
-        "path": record.path,
-        "line_start": record.line_start,
-        "line_end": record.line_end,
-        "session_id": record.session_id,
-        "captured_at": record.captured_at,
-        "quote": redact_text(record.block),
-    }
-
-
-def stale_dream_candidates(records: list[DreamRecord]) -> list[dict[str, Any]]:
-    grouped: dict[str, list[DreamRecord]] = {}
-    for record in records:
-        grouped.setdefault(record.session_id, []).append(record)
-
-    candidates: list[dict[str, Any]] = []
-    for session_id, occurrences in sorted(grouped.items()):
-        if len(occurrences) < 2:
-            continue
-        ordered = sorted(occurrences, key=lambda item: (item.path, item.line_start))
-        evidence = [record_evidence(item) for item in ordered]
-        blocks = {item.block for item in ordered}
-        expected_date = ordered[0].captured_at[:10]
-        canonical = [item for item in ordered if Path(item.path).name == f"{expected_date}.md"]
-        if len(blocks) == 1 and len(canonical) == 1:
-            kind = "stale_duplicate_record"
-            # `block` is line-rstripped when parsed, so equal blocks match apart
-            # from trailing whitespace / CRLF, not necessarily byte-for-byte.
-            reason = "Session block is identical apart from trailing whitespace and exists outside its unique UTC-dated canonical file."
-            action = "consolidate_for_review"
-            normalized = session_id
-        else:
-            kind = "record_conflict"
-            reason = "Repeated session ID has differing content or no unique UTC-dated canonical file."
-            action = "resolve_conflict"
-            normalized = session_id
-        candidates.append(
-            {
-                "id": dream_candidate_id(kind, normalized, evidence),
-                "kind": kind,
-                "status": "proposed",
-                "normalized_text": normalized,
-                "reason": reason,
-                "proposed_action": action,
-                "evidence": evidence,
-            }
-        )
-    return candidates
-
-
-def legacy_dream_candidates(path: Path, knowledge_dir: Path) -> tuple[list[dict[str, Any]], int]:
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError as exc:
-        raise HookError(f"cannot read legacy memory file {path}: {exc}") from exc
-    relative_path = str(path.relative_to(knowledge_dir))
-    grouped: dict[str, list[DreamEvidence]] = {}
-    section_line = 0
-    section_id = ""
-    captured_at = ""
-    section_count = 0
-    for index, line in enumerate(lines):
-        heading = LEGACY_SYNC_RE.match(line)
-        if heading:
-            section_line = index + 1
-            section_id = f"legacy:{relative_path}:{section_line}"
-            captured = datetime.strptime(heading.group("captured"), "%Y-%m-%d %H:%M UTC").replace(tzinfo=timezone.utc)
-            captured_at = captured.isoformat().replace("+00:00", "Z")
-            section_count += 1
-            continue
-        if not section_id or not line.startswith("- "):
-            continue
-        quote = dream_statement(line.removeprefix("- "))
-        if quote is None:
-            continue
-        normalized = dream_normalize(quote)
-        if not normalized:
-            continue
-        grouped.setdefault(normalized, []).append(
-            DreamEvidence(
-                path=relative_path,
-                line_start=index + 1,
-                line_end=index + 1,
-                session_id=section_id,
-                captured_at=captured_at,
-                quote=quote,
-            )
-        )
-
-    candidates: list[dict[str, Any]] = []
-    for normalized, occurrences in sorted(grouped.items()):
-        by_section: dict[str, DreamEvidence] = {}
-        for occurrence in occurrences:
-            by_section.setdefault(occurrence.session_id, occurrence)
-        if len(by_section) < 2:
-            continue
-        all_evidence = [dream_evidence_dict(item) for item in by_section.values()]
-        shown_evidence = all_evidence[:20]
-        candidates.append(
-            {
-                "id": dream_candidate_id("stale_duplicate_record", normalized, all_evidence),
-                "kind": "stale_duplicate_record",
-                "status": "proposed",
-                "normalized_text": normalized,
-                "reason": f"Exact legacy fact appears in {len(all_evidence)} distinct sync records.",
-                "proposed_action": "consolidate_for_review",
-                "occurrence_count": len(all_evidence),
-                "evidence": shown_evidence,
-                "evidence_omitted": len(all_evidence) - len(shown_evidence),
-            }
-        )
-    return candidates, section_count
-
-
-def build_dream_report(knowledge_dir: Path) -> dict[str, Any]:
-    sessions_dir = require_readable_sessions_dir(knowledge_dir)
-    files = session_markdown_files(sessions_dir) if sessions_dir is not None else []
-    records: list[DreamRecord] = []
-    for path in sorted(files, key=lambda item: item.name):
-        records.extend(parse_dream_records(path, knowledge_dir))
-    records.sort(key=lambda item: (item.path, item.line_start, item.session_id))
-
-    legacy_candidates: list[dict[str, Any]] = []
-    legacy_records = 0
-    if sessions_dir is not None:
-        legacy_path = sessions_dir / "knowledge.md"
-        if legacy_path.is_file():
-            legacy_candidates, legacy_records = legacy_dream_candidates(legacy_path, knowledge_dir)
-    candidates = repeated_dream_candidates(records) + stale_dream_candidates(records) + legacy_candidates
-    candidates.sort(key=lambda item: (item["kind"], item["id"]))
-    counts = {
-        "repeated_preferences": sum(item["kind"] == "repeated_preference" for item in candidates),
-        "repeated_corrections": sum(item["kind"] == "repeated_correction" for item in candidates),
-        "stale_records": sum(item["kind"] == "stale_duplicate_record" for item in candidates),
-        "conflicts": sum(item["kind"] == "record_conflict" for item in candidates),
-    }
-    return {
-        "schema_version": 1,
-        "mode": "review-only",
-        "source": {
-            "root": "$KNOWLEDGE_DIR",
-            "patterns": ["sessions/*.md", "sessions/*.markdown"],
-            "files_scanned": len(files),
-            "records_scanned": len(records) + legacy_records,
-        },
-        "summary": counts,
-        "candidates": candidates,
-    }
-
-
-def write_dream_report(knowledge_dir: Path, output: Path, report: dict[str, Any]) -> None:
-    reviews_dir = (knowledge_dir / "reviews").resolve()
-    resolved = output.expanduser().resolve()
-    if not resolved.is_relative_to(reviews_dir):
-        raise HookError(f"dream output must be under {reviews_dir}")
-    if resolved.exists():
-        raise HookError(f"dream output already exists: {resolved}")
-    resolved.parent.mkdir(parents=True, exist_ok=True)
-    content = json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
-    fd, tmp_name = tempfile.mkstemp(prefix=f".{resolved.name}.", suffix=".tmp", dir=str(resolved.parent))
-    tmp_path = Path(tmp_name)
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            handle.write(content)
-            handle.flush()
-            os.fsync(handle.fileno())
-        os.link(tmp_path, resolved)
-    except FileExistsError as exc:
-        raise HookError(f"dream output already exists: {resolved}") from exc
-    except OSError as exc:
-        raise HookError(f"cannot write dream report {resolved}: {exc}") from exc
-    finally:
-        try:
-            tmp_path.unlink()
-        except OSError:
-            pass
-
-
-def dream_command(argv: list[str], stdout: TextIO = sys.stdout) -> int:
-    parser = argparse.ArgumentParser(prog="basic_memory.py dream")
-    parser.add_argument("--output", required=True, type=Path)
-    args = parser.parse_args(argv)
-    try:
-        knowledge_dir = knowledge_dir_from_env()
-        report = build_dream_report(knowledge_dir)
-        write_dream_report(knowledge_dir, args.output, report)
-    except HookError as exc:
-        return _error(str(exc))
-    counts = report["summary"]
-    print(
-        json.dumps(
-            {
-                "output_file": str(args.output.expanduser().resolve()),
-                "mode": "review-only",
-                "summary": counts,
-            },
-            sort_keys=True,
-            separators=(",", ":"),
-        ),
-        file=stdout,
-    )
-    return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = sys.argv[1:] if argv is None else argv
-    if not args or args[0] != "dream":
-        print("usage: basic_memory.py dream --output $KNOWLEDGE_DIR/reviews/<name>.json", file=sys.stderr)
-        return 2
-    return dream_command(args[1:])
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
diff --git a/memory/lib/factory_digest.py b/memory/lib/factory_digest.py
deleted file mode 100755
index e5caf5d..0000000
--- a/memory/lib/factory_digest.py
+++ /dev/null
@@ -1,239 +0,0 @@
-#!/usr/bin/env python3
-import json
-import os
-import re
-import subprocess
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Optional
-
-from safety import atomic_write_text, locked_directory, redact_text, safe_identifier, truncate_redacted
-
-PATH_RE = re.compile(r"(?:~?/[^\s`'\"\\]+|/Users/[^\s`'\"\\]+|\./[^\s`'\"\\]+)")
-
-
-
-def truncate(text: str, limit: int = 220) -> str:
-    return truncate_redacted(text, limit)
-
-
-def parse_timestamp(value: Optional[str]) -> datetime:
-    if value:
-        try:
-            return datetime.fromisoformat(value.replace("Z", "+00:00"))
-        except ValueError:
-            pass
-    return datetime.now(timezone.utc)
-
-
-def content_to_text(content) -> str:
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        parts = []
-        for item in content:
-            if isinstance(item, dict):
-                text = item.get("text") or item.get("content")
-                if isinstance(text, str):
-                    parts.append(text)
-            elif isinstance(item, str):
-                parts.append(item)
-        return "\n".join(parts)
-    return ""
-
-
-def read_transcript(path: Path):
-    session = {}
-    messages = []
-    session_end = None
-    with path.open(encoding="utf-8") as f:
-        for line in f:
-            if not line.strip():
-                continue
-            try:
-                event = json.loads(line)
-            except json.JSONDecodeError:
-                continue
-            event_type = event.get("type")
-            if event_type == "session_start":
-                session = event
-            elif event_type == "session_end":
-                session_end = event
-            elif event_type == "message":
-                message = event.get("message")
-                if isinstance(message, dict):
-                    if message.get("visibility") == "llm_only":
-                        continue
-                    messages.append(
-                        {
-                            "role": message.get("role"),
-                            "content": content_to_text(message.get("content")),
-                            "timestamp": event.get("timestamp"),
-                        }
-                    )
-    return session, messages, session_end
-
-
-def collect_user_turns(messages):
-    return [
-        msg["content"].strip()
-        for msg in messages
-        if msg.get("role") == "user" and isinstance(msg.get("content"), str) and msg["content"].strip()
-    ]
-
-
-def nonempty_assistant_text(messages):
-    for msg in reversed(messages):
-        if msg.get("role") == "assistant" and isinstance(msg.get("content"), str) and msg["content"].strip():
-            return msg["content"].strip()
-    return ""
-
-
-def extract_paths(messages):
-    found = []
-    seen = set()
-    for msg in messages:
-        content = msg.get("content")
-        if not isinstance(content, str):
-            continue
-        for match in PATH_RE.findall(content):
-            cleaned = redact_text(match.rstrip(".,;:)"))
-            if cleaned.startswith(("/Users/", "~/", "./")) and cleaned not in seen:
-                seen.add(cleaned)
-                found.append(cleaned)
-        if len(found) >= 8:
-            break
-    return found[:8]
-
-
-def build_block(payload, transcript_path: Path, session, messages):
-    session_id = safe_identifier(payload.get("session_id") or session.get("id") or transcript_path.stem)
-    started = parse_timestamp(session.get("timestamp") or (messages[0].get("timestamp") if messages else None))
-    started_human = started.strftime("%Y-%m-%d %H:%M")
-    users = collect_user_turns(messages)
-    final_assistant = nonempty_assistant_text(messages)
-    paths = extract_paths(messages)
-    cwd = truncate(payload.get("cwd") or session.get("cwd") or "", 180)
-    title = truncate(session.get("sessionTitle") or session.get("title") or "", 180)
-
-    lines = [
-        f"<!-- droid-session:{session_id}:start -->",
-        f"## Droid session {started_human} - {session_id}",
-        "",
-    ]
-    meta = []
-    if title:
-        meta.append(f"title: {title}")
-    if cwd:
-        meta.append(f"cwd: `{cwd}`")
-    if meta:
-        lines.append(f"- {'; '.join(meta)}")
-    if users:
-        lines.append(f"- first request: {truncate(users[0], 260)}")
-    if len(users) > 1:
-        lines.append("- user follow-ups:")
-        for text in users[1:6]:
-            lines.append(f"  - {truncate(text, 220)}")
-    if final_assistant:
-        lines.append(f"- final assistant output: {truncate(final_assistant, 420)}")
-    if paths:
-        lines.append("- paths mentioned:")
-        for p in paths:
-            lines.append(f"  - `{truncate(p, 180)}`")
-    lines.extend(
-        [
-            f"- source transcript: `{truncate(str(transcript_path), 220)}`",
-            "",
-            f"<!-- droid-session:{session_id}:end -->",
-            "",
-        ]
-    )
-    return "\n".join(lines), started
-
-
-def update_daily_file(ai_dir: Path, payload, transcript_path: Path, session, messages):
-    block, started = build_block(payload, transcript_path, session, messages)
-    session_id = safe_identifier(payload.get("session_id") or session.get("id") or transcript_path.stem)
-    target = ai_dir / f"{started.strftime('%Y-%m-%d')}.md"
-    marker_re = re.compile(
-        rf"<!-- droid-session:{re.escape(session_id)}:start -->.*?<!-- droid-session:{re.escape(session_id)}:end -->\n?",
-        re.DOTALL,
-    )
-    with locked_directory(ai_dir):
-        existing = target.read_text(encoding="utf-8") if target.exists() else ""
-        existing = marker_re.sub("", existing).rstrip()
-        block = block.rstrip() + "\n"
-        atomic_write_text(target, existing + "\n\n" + block if existing else block)
-    return target
-
-
-def ai_index_paths(ai_dir: Path):
-    paths = []
-    for pattern in ("*.md", "*.markdown"):
-        paths.extend(str(p) for p in sorted(ai_dir.glob(pattern)) if p.is_file())
-    return paths
-
-
-def reindex(notes_dir: str, profile_dir: str, ai_dir: Path, collection: str):
-    paths = [notes_dir, profile_dir, *ai_index_paths(ai_dir)]
-    try:
-        result = subprocess.run(
-            ["memsearch", "index", *paths, "--collection", collection],
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-    except OSError as exc:
-        print(f"memsearch reindex warning: {exc}", file=sys.stderr)
-        return
-    if result.returncode != 0:
-        print(f"memsearch reindex warning: {result.stderr.strip()}", file=sys.stderr)
-
-
-def main():
-    try:
-        payload = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        print(json.dumps({"continue": True, "suppressOutput": True}))
-        return
-
-    transcript = payload.get("transcript_path")
-    if not transcript:
-        print(json.dumps({"continue": True, "suppressOutput": True}))
-        return
-
-    transcript_path = Path(os.path.expanduser(transcript))
-    if not transcript_path.exists():
-        print(json.dumps({"continue": True, "suppressOutput": True}))
-        return
-
-    session, messages, _ = read_transcript(transcript_path)
-    if not messages:
-        print(json.dumps({"continue": True, "suppressOutput": True}))
-        return
-
-    knowledge_dir = Path(os.path.expanduser(os.environ.get("KNOWLEDGE_DIR", "~/Workspace/knowledge")))
-    sessions_dir = Path(os.path.expanduser(os.environ.get("SESSIONS_DIR", str(knowledge_dir / "sessions"))))
-    sessions_dir.mkdir(parents=True, exist_ok=True)
-    target = update_daily_file(sessions_dir, payload, transcript_path, session, messages)
-
-    notes_dir = os.path.expanduser(os.environ.get("NOTES_DIR", str(knowledge_dir / "notes")))
-    profile_dir = os.path.expanduser(os.environ.get("PROFILE_DIR", str(knowledge_dir / "profile")))
-    collection = os.environ.get("MEMSEARCH_COLLECTION", "ai")
-    reindex(notes_dir, profile_dir, sessions_dir, collection)
-
-    print(
-        json.dumps(
-            {
-                "continue": True,
-                "suppressOutput": True,
-                "systemMessage": f"memsearch updated from Droid session {safe_identifier(payload.get('session_id') or session.get('id'))}",
-                "output_file": str(target),
-            }
-        )
-    )
-
-
-if __name__ == "__main__":
-    main()
diff --git a/memory/lib/hermes_digest.py b/memory/lib/hermes_digest.py
deleted file mode 100755
index a19de44..0000000
--- a/memory/lib/hermes_digest.py
+++ /dev/null
@@ -1,189 +0,0 @@
-#!/usr/bin/env python3
-import json
-import os
-import re
-import subprocess
-import sys
-from datetime import datetime
-from pathlib import Path
-
-from safety import atomic_write_text, locked_directory, redact_text, safe_identifier, truncate_redacted
-
-SESSION_MARKER_RE = re.compile(
-    r"<!-- hermes-session:(?P<sid>[^:]+):start -->.*?<!-- hermes-session:(?P=sid):end -->\n?",
-    re.DOTALL,
-)
-PATH_RE = re.compile(r"(?:~?/[^\s`'\"\\]+|/Users/[^\s`'\"\\]+|\./[^\s`'\"\\]+)")
-
-
-def truncate(text: str, limit: int = 220) -> str:
-    return truncate_redacted(text, limit)
-
-
-def nonempty_assistant_text(messages):
-    for msg in reversed(messages):
-        if msg.get("role") != "assistant":
-            continue
-        content = msg.get("content")
-        if isinstance(content, str) and content.strip():
-            return content.strip()
-    return ""
-
-
-def collect_user_turns(messages):
-    turns = []
-    for msg in messages:
-        if msg.get("role") != "user":
-            continue
-        content = msg.get("content")
-        if not isinstance(content, str):
-            continue
-        text = content.strip()
-        if not text:
-            continue
-        turns.append(text)
-    return turns
-
-
-def extract_paths(messages):
-    found = []
-    seen = set()
-    for msg in messages:
-        content = msg.get("content")
-        if not isinstance(content, str):
-            continue
-        for match in PATH_RE.findall(content):
-            cleaned = redact_text(match.rstrip(".,;:)"))
-            if cleaned.startswith('/Users/') or cleaned.startswith('~/') or cleaned.startswith('./'):
-                if cleaned not in seen:
-                    seen.add(cleaned)
-                    found.append(cleaned)
-        if len(found) >= 8:
-            break
-    return found[:8]
-
-
-def build_block(data):
-    session_id = safe_identifier(data["session_id"])
-    started = data.get("session_start") or datetime.utcnow().isoformat()
-    started_dt = datetime.fromisoformat(started)
-    started_human = started_dt.strftime("%Y-%m-%d %H:%M")
-    messages = data.get("messages") or []
-    users = collect_user_turns(messages)
-    final_assistant = nonempty_assistant_text(messages)
-    paths = extract_paths(messages)
-    model = truncate(data.get("model") or "", 120)
-    platform = truncate(data.get("platform") or "", 120)
-
-    lines = [
-        f"<!-- hermes-session:{session_id}:start -->",
-        f"## Hermes session {started_human} - {session_id}",
-        "",
-    ]
-    meta = []
-    if platform:
-        meta.append(f"platform: {platform}")
-    if model:
-        meta.append(f"model: {model}")
-    if meta:
-        lines.append(f"- {'; '.join(meta)}")
-    if users:
-        lines.append(f"- first request: {truncate(users[0], 260)}")
-    if len(users) > 1:
-        lines.append("- user follow-ups:")
-        for text in users[1:6]:
-            lines.append(f"  - {truncate(text, 220)}")
-    if final_assistant:
-        lines.append(f"- final assistant output: {truncate(final_assistant, 420)}")
-    if paths:
-        lines.append("- paths mentioned:")
-        for p in paths:
-            lines.append(f"  - `{truncate(p, 180)}`")
-    lines.extend([
-        f"- source transcript: `~/.hermes/sessions/session_{session_id}.json`",
-        "",
-        f"<!-- hermes-session:{session_id}:end -->",
-        "",
-    ])
-    return "\n".join(lines)
-
-
-def update_daily_file(ai_dir: Path, data):
-    started = data.get("session_start") or datetime.utcnow().isoformat()
-    day = datetime.fromisoformat(started).strftime("%Y-%m-%d")
-    target = ai_dir / f"{day}.md"
-    session_id = safe_identifier(data.get("session_id") or "unknown")
-    marker_re = re.compile(
-        rf"<!-- hermes-session:{re.escape(session_id)}:start -->.*?<!-- hermes-session:{re.escape(session_id)}:end -->\n?",
-        re.DOTALL,
-    )
-    with locked_directory(ai_dir):
-        existing = target.read_text(encoding="utf-8") if target.exists() else ""
-        existing = marker_re.sub("", existing).rstrip()
-        block = build_block(data).rstrip() + "\n"
-        atomic_write_text(target, existing + "\n\n" + block if existing else block)
-    return target
-
-
-def ai_index_paths(ai_dir: Path):
-    paths = []
-    for pattern in ("*.md", "*.markdown"):
-        paths.extend(str(p) for p in sorted(ai_dir.glob(pattern)) if p.is_file())
-    return paths
-
-
-def reindex(notes_dir: str, profile_dir: str, ai_dir: Path, collection: str):
-    try:
-        subprocess.run(
-            [
-                "memsearch",
-                "index",
-                notes_dir,
-                profile_dir,
-                *ai_index_paths(ai_dir),
-                "--collection",
-                collection,
-            ],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-    except OSError as exc:
-        print(f"memsearch reindex warning: {exc}", file=sys.stderr)
-
-
-def main():
-    payload = json.load(sys.stdin)
-    session_id = payload.get("session_id")
-    if not session_id:
-        print(json.dumps({"action": "continue"}))
-        return
-
-    hermes_home = Path(os.path.expanduser(os.environ.get("HERMES_HOME", "~/.hermes")))
-    session_path = hermes_home / "sessions" / f"session_{session_id}.json"
-    if not session_path.exists():
-        print(json.dumps({"action": "continue", "message": f"session log not found: {session_path}"}))
-        return
-
-    with session_path.open(encoding="utf-8") as f:
-        data = json.load(f)
-
-    knowledge_dir = Path(os.path.expanduser(os.environ.get("KNOWLEDGE_DIR", "~/Workspace/knowledge")))
-    sessions_dir = Path(os.path.expanduser(os.environ.get("SESSIONS_DIR", str(knowledge_dir / "sessions"))))
-    sessions_dir.mkdir(parents=True, exist_ok=True)
-    target = update_daily_file(sessions_dir, data)
-
-    notes_dir = os.path.expanduser(os.environ.get("NOTES_DIR", str(knowledge_dir / "notes")))
-    profile_dir = os.path.expanduser(os.environ.get("PROFILE_DIR", str(knowledge_dir / "profile")))
-    collection = os.environ.get("MEMSEARCH_COLLECTION", "ai")
-    reindex(notes_dir, profile_dir, sessions_dir, collection)
-
-    print(json.dumps({
-        "action": "continue",
-        "message": f"memsearch updated from Hermes session {safe_identifier(session_id)}",
-        "output_file": str(target),
-    }))
-
-
-if __name__ == "__main__":
-    main()
diff --git a/memory/lib/sync.py b/memory/lib/sync.py
index 97cb23c..3e10144 100755
--- a/memory/lib/sync.py
+++ b/memory/lib/sync.py
@@ -9,8 +9,6 @@
   - vault profile/USER.md -> Hermes USER.md (compact, deduplicated)
   - vault recent sessions/ facts -> Hermes MEMORY.md (compact, deduplicated)
 
-After either direction, reindexes memsearch.
-
 Usage:
   python sync.py memory-to-vault   # export Hermes -> vault
   python sync.py vault-to-memory   # import vault -> Hermes
@@ -37,12 +35,6 @@ def resolve():
         "hermes_user": home / ".hermes" / "memories" / "USER.md",
         "vault_profile": profile_dir / "USER.md",
         "vault_knowledge": sessions_dir / "knowledge.md",
-        "vault_dir": vault_dir,
-        "vault_sessions_dir": sessions_dir,
-        "vault_notes_dir": notes_dir,
-        "vault_profile_dir": profile_dir,
-        "memsearch_home": Path(os.path.expanduser(os.environ.get("MEMSEARCH_HOME", "~/.memsearch"))),
-        "collection": os.environ.get("MEMSEARCH_COLLECTION", "ai"),
     }
 
 
@@ -239,54 +231,6 @@ def rendered_size(entries: list[str]) -> int:
     return changed
 
 
-# -- Reindex ---------------------------------------------------------------
-def reindex_memsearch(paths: dict):
-    """Refresh the derived memsearch index over the canonical vault.
-
-    Indexes the whole vault into collection ``ai`` -- the same scope the
-    knowledge-sync reindex-after-sync trigger uses -- so markdown stays the
-    single source of truth and the index is a disposable per-machine derivative.
-    Best-effort and guarded by the shared reindex lock so it never overlaps a
-    concurrent refresh (reindex-after-sync / reindex-after-capture).
-    """
-    import fcntl
-    import shutil
-    import subprocess
-
-    if not shutil.which("memsearch"):
-        print("memsearch reindex: memsearch not installed, skipped")
-        return
-
-    state_dir = paths["memsearch_home"]
-    # Best-effort: a failure to create the state dir or open the lock must never
-    # raise out of a reindex trigger, only skip and warn.
-    try:
-        state_dir.mkdir(parents=True, exist_ok=True)
-        lock = open(state_dir / "reindex.lock", "w")
-    except OSError as exc:
-        print(f"memsearch reindex: cannot open lock dir ({exc}), skipped")
-        return
-    try:
-        fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
-    except OSError:
-        print("memsearch reindex: another reindex running, skipped")
-        lock.close()
-        return
-
-    try:
-        # Always refresh the canonical "ai" collection; ignore MEMSEARCH_COLLECTION
-        # drift so the canonical collection cannot go silently stale.
-        cmd = ["memsearch", "index", str(paths["vault_dir"]), "--collection", "ai"]
-        result = subprocess.run(cmd, capture_output=True, text=True)
-        if result.returncode == 0:
-            print("memsearch reindex: done")
-        else:
-            print(f"memsearch reindex: warning - {result.stderr.strip()}")
-    finally:
-        fcntl.flock(lock, fcntl.LOCK_UN)
-        lock.close()
-
-
 # -- Main ------------------------------------------------------------------
 def main():
     if len(sys.argv) < 2:
@@ -295,16 +239,11 @@ def main():
 
     paths = resolve()
     direction = sys.argv[1]
-    any_change = False
-
     if direction in ("memory-to-vault", "both"):
-        any_change |= memory_to_vault(paths)
+        memory_to_vault(paths)
 
     if direction in ("vault-to-memory", "both"):
-        any_change |= vault_to_memory(paths)
-
-    if any_change:
-        reindex_memsearch(paths)
+        vault_to_memory(paths)
 
 
 if __name__ == "__main__":
diff --git a/memory/tests/test_basic_memory_hooks.py b/memory/tests/test_basic_memory_hooks.py
index d4c2d65..837581b 100644
--- a/memory/tests/test_basic_memory_hooks.py
+++ b/memory/tests/test_basic_memory_hooks.py
@@ -14,10 +14,6 @@
 MEMORY_DIR = Path(__file__).resolve().parents[1]
 END_HOOK = MEMORY_DIR / "hooks" / "basic-session-end.py"
 START_HOOK = MEMORY_DIR / "hooks" / "basic-session-start.py"
-DREAM_SCRIPT = MEMORY_DIR / "lib" / "basic_memory.py"
-AMP_DIGEST = MEMORY_DIR / "lib" / "amp_digest.py"
-FACTORY_DIGEST = MEMORY_DIR / "lib" / "factory_digest.py"
-HERMES_DIGEST = MEMORY_DIR / "lib" / "hermes_digest.py"
 SESSION_END_HOOK = MEMORY_DIR / "hooks" / "session-end.sh"
 SESSION_START_HOOK = MEMORY_DIR / "hooks" / "session-start.sh"
 STOP_HOOK = MEMORY_DIR / "hooks" / "stop.sh"
@@ -182,57 +178,50 @@ def test_malformed_input_fails_actionably(self):
             self.assertEqual(malformed.stdout, "")
             self.assertIn("invalid hook JSON", malformed.stderr)
 
-    def test_amp_and_hermes_digests_redact_secrets_before_persisting(self):
+    def test_amp_and_hermes_payloads_use_shared_digest_and_redact(self):
         with tempfile.TemporaryDirectory() as tmp:
             tmp_path = Path(tmp)
             knowledge = tmp_path / "knowledge"
-            fake_bin = tmp_path / "bin"
-            fake_bin.mkdir()
-            fake_memsearch = fake_bin / "memsearch"
-            fake_memsearch.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
-            fake_memsearch.chmod(fake_memsearch.stat().st_mode | stat.S_IXUSR)
-            env = self.env_with_knowledge(knowledge, {"PATH": str(fake_bin)})
+            env = self.env_with_knowledge(knowledge, {"MEMSEARCH_PLUGIN_DIR": str(tmp_path / "missing")})
+            secret = "providersecret123456789"
 
-            amp_secret = "ampsecret123456789"
-            path_secret = "pathsecret123456789"
             amp_payload = {
+                "platform": "amp",
                 "session_id": "amp-redact",
                 "session_start": "2026-07-16T03:04:05Z",
-                "model": f"model token={amp_secret}",
                 "messages": [
-                    {"role": "user", "content": f"Use api_key={amp_secret} in /Users/example/project?token={path_secret}"},
-                    {"role": "assistant", "content": f"Done with Authorization: Bearer {amp_secret}"},
+                    {"role": "user", "content": f"Use api_key={secret} in ./amp"},
+                    {"role": "assistant", "content": f"Authorization: Bearer {secret}"},
                 ],
             }
-            amp = self.run_hook(AMP_DIGEST, amp_payload, env=env)
+            amp = subprocess.run(
+                ["/bin/bash", str(SESSION_END_HOOK)], input=json.dumps(amp_payload), text=True,
+                capture_output=True, env=env, check=False,
+            )
             self.assertEqual(amp.returncode, 0, amp.stderr)
+            self.assertEqual(json.loads(amp.stdout)["action"], "continue")
 
             hermes_home = tmp_path / "hermes"
             hermes_sessions = hermes_home / "sessions"
             hermes_sessions.mkdir(parents=True)
-            hermes_secret = "hermessecret123456789"
             hermes_data = {
                 "session_id": "hermes-redact",
-                "session_start": "2026-07-16T04:05:06",
-                "platform": f"hermes token={hermes_secret}",
-                "model": f"model password={hermes_secret}",
-                "messages": [
-                    {"role": "user", "content": f"Open /Users/example/hermes?secret={hermes_secret}"},
-                    {"role": "assistant", "content": f"Used Authorization: Bearer {hermes_secret}"},
-                ],
+                "session_start": "2026-07-16T04:05:06Z",
+                "model": f"model password={secret}",
+                "messages": [{"role": "user", "content": f"Open ./hermes?secret={secret}"}],
             }
             (hermes_sessions / "session_hermes-redact.json").write_text(json.dumps(hermes_data), encoding="utf-8")
-            hermes = self.run_hook(
-                HERMES_DIGEST,
-                {"session_id": "hermes-redact"},
-                env={**env, "HERMES_HOME": str(hermes_home)},
+            hermes = subprocess.run(
+                ["/bin/bash", str(SESSION_END_HOOK)], input=json.dumps({"session_id": "hermes-redact"}),
+                text=True, capture_output=True, env={**env, "HERMES_HOME": str(hermes_home)}, check=False,
             )
             self.assertEqual(hermes.returncode, 0, hermes.stderr)
+            self.assertEqual(json.loads(hermes.stdout)["action"], "continue")
 
             content = (knowledge / "sessions" / "2026-07-16.md").read_text(encoding="utf-8")
-            self.assertNotIn(amp_secret, content)
-            self.assertNotIn(path_secret, content)
-            self.assertNotIn(hermes_secret, content)
+            self.assertIn("- source: amp", content)
+            self.assertIn("- source: hermes", content)
+            self.assertNotIn(secret, content)
             self.assertIn("[REDACTED]", content)
 
     def test_basic_digest_redacts_unlabelled_provider_tokens(self):
@@ -259,57 +248,100 @@ def test_basic_digest_redacts_unlabelled_provider_tokens(self):
                 self.assertNotIn(secret, content)
             self.assertIn("[REDACTED]", content)
 
-    def test_provider_digests_persist_when_memsearch_binary_disappears(self):
+    def test_droid_factory_jsonl_uses_shared_digest_without_memsearch(self):
         with tempfile.TemporaryDirectory() as tmp:
             tmp_path = Path(tmp)
             knowledge = tmp_path / "knowledge"
-            env = self.env_with_knowledge(knowledge, {"PATH": ""})
+            transcript = tmp_path / ".factory" / "sessions" / "factory-session.jsonl"
+            transcript.parent.mkdir(parents=True)
+            transcript.write_text(
+                "\n".join([
+                    json.dumps({"type": "session_start", "id": "factory-no-memsearch", "timestamp": "2026-07-16T05:06:07Z", "cwd": "./factory"}),
+                    json.dumps({"type": "message", "timestamp": "2026-07-16T05:07:08Z", "message": {"role": "user", "content": "Persist the Factory digest."}}),
+                    json.dumps({"type": "message", "message": {"role": "assistant", "content": "hidden", "visibility": "llm_only"}}),
+                ]) + "\n",
+                encoding="utf-8",
+            )
+            payload = {"session_id": "factory-no-memsearch", "transcript_path": str(transcript)}
+            result = subprocess.run(
+                ["/bin/bash", str(SESSION_END_HOOK)], input=json.dumps(payload), text=True,
+                capture_output=True,
+                env=self.env_with_knowledge(knowledge, {"PATH": "/usr/bin:/bin", "MEMSEARCH_PLUGIN_DIR": str(tmp_path / "missing")}),
+                check=False,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertTrue(json.loads(result.stdout)["continue"])
+            content = (knowledge / "sessions" / "2026-07-16.md").read_text(encoding="utf-8")
+            self.assertIn("- source: droid", content)
+            self.assertIn("Persist the Factory digest.", content)
+            self.assertNotIn("hidden", content)
+            self.assertIn("source transcript", content)
 
-            factory_transcript = tmp_path / "factory-session.jsonl"
-            factory_transcript.write_text(
-                "\n".join(
-                    [
-                        json.dumps({"type": "session_start", "id": "factory-no-memsearch", "timestamp": "2026-07-16T05:06:07Z"}),
-                        json.dumps(
-                            {
-                                "type": "message",
-                                "timestamp": "2026-07-16T05:07:08Z",
-                                "message": {"role": "user", "content": "Persist the Factory digest."},
-                            }
-                        ),
-                    ]
-                )
-                + "\n",
+    def test_droid_factory_jsonl_tolerates_partially_written_trailing_record(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            knowledge = tmp_path / "knowledge"
+            transcript = tmp_path / ".factory" / "sessions" / "factory-partial.jsonl"
+            transcript.parent.mkdir(parents=True)
+            transcript.write_text(
+                "\n".join([
+                    json.dumps({"type": "session_start", "id": "factory-partial", "timestamp": "2026-07-16T06:07:08Z", "cwd": "./factory"}),
+                    json.dumps({"type": "message", "timestamp": "2026-07-16T06:08:09Z", "message": {"role": "user", "content": "Keep the partial Factory session."}}),
+                    '{"type": "message", "message": {"role": "assist',
+                ]) + "\n",
                 encoding="utf-8",
             )
-            factory = self.run_hook(
-                FACTORY_DIGEST,
-                {"session_id": "factory-no-memsearch", "transcript_path": str(factory_transcript)},
-                env=env,
+            payload = {"session_id": "factory-partial", "transcript_path": str(transcript)}
+            result = subprocess.run(
+                ["/bin/bash", str(SESSION_END_HOOK)], input=json.dumps(payload), text=True,
+                capture_output=True,
+                env=self.env_with_knowledge(knowledge, {"PATH": "/usr/bin:/bin", "MEMSEARCH_PLUGIN_DIR": str(tmp_path / "missing")}),
+                check=False,
             )
-            self.assertEqual(factory.returncode, 0, factory.stderr)
-            self.assertTrue(json.loads(factory.stdout)["continue"])
+            self.assertEqual(result.returncode, 0, result.stderr)
+            content = (knowledge / "sessions" / "2026-07-16.md").read_text(encoding="utf-8")
+            self.assertIn("Keep the partial Factory session.", content)
 
+    def test_hermes_missing_session_log_defers_capture_instead_of_recording_a_stub(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            knowledge = tmp_path / "knowledge"
             hermes_home = tmp_path / "hermes"
-            hermes_sessions = hermes_home / "sessions"
-            hermes_sessions.mkdir(parents=True)
-            hermes_data = {
-                "session_id": "hermes-no-memsearch",
-                "session_start": "2026-07-16T06:07:08",
-                "messages": [{"role": "user", "content": "Persist the Hermes digest."}],
-            }
-            (hermes_sessions / "session_hermes-no-memsearch.json").write_text(json.dumps(hermes_data), encoding="utf-8")
-            hermes = self.run_hook(
-                HERMES_DIGEST,
-                {"session_id": "hermes-no-memsearch"},
-                env={**env, "HERMES_HOME": str(hermes_home)},
+            (hermes_home / "sessions").mkdir(parents=True)
+            env = self.env_with_knowledge(
+                knowledge,
+                {"HERMES_HOME": str(hermes_home), "PATH": "/usr/bin:/bin", "MEMSEARCH_PLUGIN_DIR": str(tmp_path / "missing")},
             )
-            self.assertEqual(hermes.returncode, 0, hermes.stderr)
-            self.assertEqual(json.loads(hermes.stdout)["action"], "continue")
+            payload = {"session_id": "hermes-deferred", "session_start": "2026-07-16T07:08:09Z"}
 
+            first = subprocess.run(
+                ["/bin/bash", str(SESSION_END_HOOK)], input=json.dumps(payload), text=True,
+                capture_output=True, env=env, check=False,
+            )
+            self.assertEqual(first.returncode, 0, first.stderr)
+            self.assertIn("session log not found", first.stdout)
+            self.assertFalse((knowledge / "sessions" / "2026-07-16.md").exists())
+
+            # The provider file appears later: the real transcript must still capture.
+            (hermes_home / "sessions" / "session_hermes-deferred.json").write_text(
+                json.dumps({
+                    "session_id": "hermes-deferred",
+                    "session_start": "2026-07-16T07:08:09Z",
+                    "messages": [
+                        {"role": "user", "content": "Capture the deferred Hermes session."},
+                        {"role": "assistant", "content": "Captured."},
+                    ],
+                }),
+                encoding="utf-8",
+            )
+            second = subprocess.run(
+                ["/bin/bash", str(SESSION_END_HOOK)], input=json.dumps(payload), text=True,
+                capture_output=True, env=env, check=False,
+            )
+            self.assertEqual(second.returncode, 0, second.stderr)
             content = (knowledge / "sessions" / "2026-07-16.md").read_text(encoding="utf-8")
-            self.assertIn("Persist the Factory digest.", content)
-            self.assertIn("Persist the Hermes digest.", content)
+            self.assertIn("Capture the deferred Hermes session.", content)
+            self.assertIn("- source: hermes", content)
 
     def test_session_end_dispatch_cleans_temporary_payload(self):
         with tempfile.TemporaryDirectory() as tmp:
@@ -418,181 +450,6 @@ def test_basic_hooks_do_not_invoke_or_require_memsearch(self):
             self.assertFalse(marker.exists(), "basic hooks invoked memsearch")
 
 
-class DreamMemoryReviewTests(unittest.TestCase):
-    def env_with_knowledge(self, knowledge_dir: Path) -> dict[str, str]:
-        env = os.environ.copy()
-        env["KNOWLEDGE_DIR"] = str(knowledge_dir)
-        return env
-
-    def digest(self, session_id: str, captured: str, request: str, *, assistant: str = "Done.") -> str:
-        return "\n".join(
-            [
-                f"<!-- basic-memory-session:{session_id}:start -->",
-                f"## Session {captured} UTC - {session_id}",
-                "",
-                "- source: claude-code",
-                f"- first request: {request}",
-                f"- final assistant output: {assistant}",
-                "",
-                f"<!-- basic-memory-session:{session_id}:end -->",
-                "",
-            ]
-        )
-
-    def run_dream(self, knowledge: Path, output: Path) -> subprocess.CompletedProcess[str]:
-        return subprocess.run(
-            [sys.executable, str(DREAM_SCRIPT), "dream", "--output", str(output)],
-            text=True,
-            capture_output=True,
-            env=self.env_with_knowledge(knowledge),
-            check=False,
-        )
-
-    def test_dream_reports_exact_repeated_preferences_deterministically(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            knowledge = Path(tmp) / "knowledge"
-            sessions = knowledge / "sessions"
-            reviews = knowledge / "reviews"
-            sessions.mkdir(parents=True)
-            (sessions / "2026-07-01.md").write_text(
-                self.digest("one", "2026-07-01 10:00", "I prefer concise reports."),
-                encoding="utf-8",
-            )
-            (sessions / "2026-07-02.md").write_text(
-                self.digest("two", "2026-07-02 10:00", "I prefer concise reports!"),
-                encoding="utf-8",
-            )
-
-            first_path = reviews / "first.json"
-            second_path = reviews / "second.json"
-            first = self.run_dream(knowledge, first_path)
-            second = self.run_dream(knowledge, second_path)
-            self.assertEqual(first.returncode, 0, first.stderr)
-            self.assertEqual(second.returncode, 0, second.stderr)
-            self.assertEqual(first_path.read_bytes(), second_path.read_bytes())
-
-            report = json.loads(first_path.read_text(encoding="utf-8"))
-            self.assertEqual(report["mode"], "review-only")
-            self.assertEqual(report["summary"]["repeated_preferences"], 1)
-            candidate = report["candidates"][0]
-            self.assertEqual(candidate["kind"], "repeated_preference")
-            self.assertEqual([item["session_id"] for item in candidate["evidence"]], ["one", "two"])
-
-    def test_dream_ignores_non_user_incomplete_and_non_exact_evidence(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            knowledge = Path(tmp) / "knowledge"
-            sessions = knowledge / "sessions"
-            sessions.mkdir(parents=True)
-            (sessions / "2026-07-01.md").write_text(
-                "\n".join(
-                    [
-                        self.digest("one", "2026-07-01 10:00", "I prefer concise replies."),
-                        self.digest("two", "2026-07-01 11:00", "I prefer short replies."),
-                        self.digest("three", "2026-07-01 12:00", "I prefer concise replies…"),
-                        "- first request: I prefer concise replies.",
-                        "<!-- basic-memory-session:incomplete:start -->",
-                        "## Session 2026-07-01 13:00 UTC - incomplete",
-                        "- first request: I prefer concise replies.",
-                    ]
-                ),
-                encoding="utf-8",
-            )
-
-            output = knowledge / "reviews" / "review.json"
-            result = self.run_dream(knowledge, output)
-            self.assertEqual(result.returncode, 0, result.stderr)
-            report = json.loads(output.read_text(encoding="utf-8"))
-            self.assertEqual(report["summary"]["repeated_preferences"], 0)
-            self.assertEqual(report["candidates"], [])
-
-    def test_dream_finds_objective_duplicates_and_never_mutates_canonical_files(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            knowledge = Path(tmp) / "knowledge"
-            sessions = knowledge / "sessions"
-            profile = knowledge / "profile"
-            sessions.mkdir(parents=True)
-            profile.mkdir()
-            block = self.digest("duplicate", "2026-07-01 10:00", "Keep this record.")
-            canonical = sessions / "2026-07-01.md"
-            stale = sessions / "2026-07-02.md"
-            canonical.write_text(block, encoding="utf-8")
-            stale.write_text(block, encoding="utf-8")
-            user = profile / "USER.md"
-            user.write_text("- I prefer profile text to remain untouched.\n", encoding="utf-8")
-            before = {path: path.read_bytes() for path in (canonical, stale, user)}
-
-            output = knowledge / "reviews" / "review.json"
-            result = self.run_dream(knowledge, output)
-            self.assertEqual(result.returncode, 0, result.stderr)
-            report = json.loads(output.read_text(encoding="utf-8"))
-            self.assertEqual(report["summary"]["stale_records"], 1)
-            self.assertEqual(report["candidates"][0]["kind"], "stale_duplicate_record")
-            self.assertEqual({path: path.read_bytes() for path in before}, before)
-
-            replay = self.run_dream(knowledge, output)
-            self.assertNotEqual(replay.returncode, 0)
-            self.assertIn("already exists", replay.stderr)
-            outside = self.run_dream(knowledge, Path(tmp) / "outside.json")
-            self.assertNotEqual(outside.returncode, 0)
-            self.assertIn("must be under", outside.stderr)
-
-
-    def test_dream_reports_exact_legacy_sync_duplicates_without_guessing(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            knowledge = Path(tmp) / "knowledge"
-            sessions = knowledge / "sessions"
-            sessions.mkdir(parents=True)
-            (sessions / "knowledge.md").write_text(
-                "\n".join(
-                    [
-                        "# Legacy export",
-                        "",
-                        "## Sync 2026-05-01 10:00 UTC",
-                        "",
-                        "- User prefers pnpm for Node work.",
-                        "- Similar but distinct fact.",
-                        "",
-                        "## Sync 2026-05-02 10:00 UTC",
-                        "",
-                        "- User prefers pnpm for Node work.",
-                        "- Similar but different fact.",
-                        "",
-                    ]
-                ),
-                encoding="utf-8",
-            )
-
-            output = knowledge / "reviews" / "review.json"
-            result = self.run_dream(knowledge, output)
-            self.assertEqual(result.returncode, 0, result.stderr)
-            report = json.loads(output.read_text(encoding="utf-8"))
-            self.assertEqual(report["summary"]["stale_records"], 1)
-            candidate = report["candidates"][0]
-            self.assertEqual(candidate["kind"], "stale_duplicate_record")
-            self.assertEqual(candidate["occurrence_count"], 2)
-            self.assertEqual(len(candidate["evidence"]), 2)
-
-    def test_dream_truncates_legacy_evidence_beyond_twenty_occurrences(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            knowledge = Path(tmp) / "knowledge"
-            sessions = knowledge / "sessions"
-            sessions.mkdir(parents=True)
-            fact = "- User prefers pnpm for Node work."
-            body = []
-            for day in range(1, 22):  # 21 distinct sync sections repeat the same fact
-                body += [f"## Sync 2026-05-{day:02d} 10:00 UTC", "", fact, ""]
-            (sessions / "knowledge.md").write_text("\n".join(body) + "\n", encoding="utf-8")
-
-            output = knowledge / "reviews" / "review.json"
-            result = self.run_dream(knowledge, output)
-            self.assertEqual(result.returncode, 0, result.stderr)
-            report = json.loads(output.read_text(encoding="utf-8"))
-            candidate = report["candidates"][0]
-            self.assertEqual(candidate["kind"], "stale_duplicate_record")
-            self.assertEqual(candidate["occurrence_count"], 21)
-            self.assertEqual(len(candidate["evidence"]), 20)
-            self.assertEqual(candidate["evidence_omitted"], 1)
-
 class ClaudeFallbackAndDispatchTests(unittest.TestCase):
     """R1 fallback, R7 Codex/OMP capture, and R2 bounded reindex."""
 
diff --git a/memory/tests/test_sync.py b/memory/tests/test_sync.py
index 7637a4d..d83fb8f 100644
--- a/memory/tests/test_sync.py
+++ b/memory/tests/test_sync.py
@@ -1,12 +1,17 @@
-import importlib.util
+import json
 import os
 import stat
+import subprocess
+import sys
 import tempfile
+import time
 import unittest
+import importlib.util
 from pathlib import Path
 
 
-SYNC_PATH = Path(__file__).parents[1] / "lib" / "sync.py"
+MEMORY_DIR = Path(__file__).parents[1]
+SYNC_PATH = MEMORY_DIR / "lib" / "sync.py"
 SPEC = importlib.util.spec_from_file_location("dotagents_memory_sync", SYNC_PATH)
 assert SPEC is not None
 SYNC = importlib.util.module_from_spec(SPEC)
@@ -40,103 +45,64 @@ def test_full_user_memory_is_not_rewritten_or_reported_changed(self):
             self.assertEqual(hermes_user.stat().st_mtime_ns, before_mtime)
 
 
-class ReindexTests(unittest.TestCase):
-    def _paths(self, root: Path) -> dict:
-        return {
-            "vault_dir": root / "vault",
-            "memsearch_home": root / "memsearch_home",
-            "collection": "ai",
-        }
+class HermesSyncHookTests(unittest.TestCase):
+    def wait_for(self, predicate, timeout: float = 5.0) -> bool:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if predicate():
+                return True
+            time.sleep(0.05)
+        return predicate()
 
-    def test_reindex_skips_cleanly_without_memsearch(self):
+    def test_both_successful_wrappers_use_shared_refresh_helper(self):
         with tempfile.TemporaryDirectory() as tmp:
             root = Path(tmp)
-            empty_bin = root / "emptybin"
-            empty_bin.mkdir()
-            old_path = os.environ.get("PATH", "")
-            os.environ["PATH"] = str(empty_bin)
-            try:
-                SYNC.reindex_memsearch(self._paths(root))  # must not raise
-            finally:
-                os.environ["PATH"] = old_path
+            home = root / "home"
+            knowledge = root / "knowledge"
+            (home / ".hermes" / "memories").mkdir(parents=True)
+            (knowledge / "profile").mkdir(parents=True)
+            (knowledge / "sessions").mkdir(parents=True)
+            (knowledge / "notes").mkdir(parents=True)
+            (knowledge / "profile" / "USER.md").write_text("# Profile\n", encoding="utf-8")
 
-    def test_reindex_indexes_whole_vault_into_collection_ai(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
             fake_bin = root / "bin"
             fake_bin.mkdir()
-            argv_log = root / "argv.txt"
+            log = root / "memsearch.log"
             fake = fake_bin / "memsearch"
-            fake.write_text(
-                "#!/usr/bin/env bash\n"
-                f'printf "%s\\n" "$@" > "{argv_log}"\n'
-                "exit 0\n",
-                encoding="utf-8",
-            )
-            fake.chmod(fake.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
-
-            paths = self._paths(root)
-            old_path = os.environ.get("PATH", "")
-            os.environ["PATH"] = str(fake_bin) + os.pathsep + old_path
-            try:
-                SYNC.reindex_memsearch(paths)
-            finally:
-                os.environ["PATH"] = old_path
-
-            argv = argv_log.read_text(encoding="utf-8").splitlines()
-            self.assertEqual(argv[0], "index")
-            self.assertEqual(argv[1], str(paths["vault_dir"]))
-            self.assertIn("--collection", argv)
-            self.assertEqual(argv[argv.index("--collection") + 1], "ai")
-            # shared reindex lock was created under the engine home
-            self.assertTrue((paths["memsearch_home"] / "reindex.lock").exists())
-
-    def _fake_memsearch(self, root: Path) -> tuple[Path, Path]:
-        fake_bin = root / "bin"
-        fake_bin.mkdir()
-        argv_log = root / "argv.txt"
-        fake = fake_bin / "memsearch"
-        fake.write_text(
-            "#!/usr/bin/env bash\n"
-            f'printf "%s\\n" "$@" > "{argv_log}"\n'
-            "exit 0\n",
-            encoding="utf-8",
-        )
-        fake.chmod(fake.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
-        return fake_bin, argv_log
+            fake.write_text(f'#!/bin/sh\nprintf "%s\\n" "$*" >> "{log}"\n', encoding="utf-8")
+            fake.chmod(fake.stat().st_mode | stat.S_IXUSR)
 
-    def test_reindex_ignores_collection_drift_and_pins_ai(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            fake_bin, argv_log = self._fake_memsearch(root)
-            paths = self._paths(root)
-            paths["collection"] = "some-other-collection"  # drift must be ignored
-            old_path = os.environ.get("PATH", "")
-            os.environ["PATH"] = str(fake_bin) + os.pathsep + old_path
-            try:
-                SYNC.reindex_memsearch(paths)
-            finally:
-                os.environ["PATH"] = old_path
-            argv = argv_log.read_text(encoding="utf-8").splitlines()
-            self.assertEqual(argv[argv.index("--collection") + 1], "ai")
-
-    def test_reindex_stays_best_effort_when_state_dir_unusable(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            root = Path(tmp)
-            fake_bin, argv_log = self._fake_memsearch(root)
-            # A regular file where a directory is expected makes mkdir raise.
-            blocker = root / "blocker"
-            blocker.write_text("not a dir\n", encoding="utf-8")
-            paths = self._paths(root)
-            paths["memsearch_home"] = blocker / "nested"
-            old_path = os.environ.get("PATH", "")
-            os.environ["PATH"] = str(fake_bin) + os.pathsep + old_path
-            try:
-                SYNC.reindex_memsearch(paths)  # must not raise
-            finally:
-                os.environ["PATH"] = old_path
-            # skipped before running memsearch
-            self.assertFalse(argv_log.exists())
+            env = os.environ.copy()
+            env.update(
+                {
+                    "HOME": str(home),
+                    "KNOWLEDGE_DIR": str(knowledge),
+                    "MEMSEARCH_STATE_DIR": str(root / "state"),
+                    "PATH": str(fake_bin) + os.pathsep + env.get("PATH", ""),
+                }
+            )
+            for index, name in enumerate(("sync-memory-to-vault.sh", "sync-vault-to-memory.sh"), start=1):
+                result = subprocess.run(
+                    ["/bin/bash", str(MEMORY_DIR / "hooks" / name)],
+                    text=True,
+                    capture_output=True,
+                    env=env,
+                    check=False,
+                )
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertEqual(json.loads(result.stdout)["action"], "continue")
+                self.assertTrue(
+                    self.wait_for(lambda: log.exists() and len(log.read_text(encoding="utf-8").splitlines()) >= index),
+                    f"{name} did not trigger the shared refresh helper",
+                )
+                self.assertTrue(
+                    self.wait_for(lambda: not (root / "state" / "reindex.lock").exists()),
+                    f"{name} refresh did not release its lock",
+                )
+
+            for line in log.read_text(encoding="utf-8").splitlines():
+                self.assertIn("index", line)
+                self.assertIn("--collection ai", line)
 
 
 if __name__ == "__main__":
diff --git a/memory/tools/knowledge-sync/go.mod b/memory/tools/knowledge-sync/go.mod.template
similarity index 69%
rename from memory/tools/knowledge-sync/go.mod
rename to memory/tools/knowledge-sync/go.mod.template
index 73edea8..5a8b7a2 100644
--- a/memory/tools/knowledge-sync/go.mod
+++ b/memory/tools/knowledge-sync/go.mod.template
@@ -1,3 +1,3 @@
 module knowledge-sync
 
-go 1.24
+go 1.24.2
diff --git a/memory/tools/rem/README.md b/memory/tools/rem/README.md
index 299d93a..9389290 100644
--- a/memory/tools/rem/README.md
+++ b/memory/tools/rem/README.md
@@ -1,40 +1,29 @@
 # rem
 
-Memory workflow CLI for the knowledge vault. Shipped as a dotagents memory tool:
-`dotagents sync` builds it and installs it to `$GOBIN` or `~/.local/bin`.
-
-```
-rem add [-src harness] "<fact>"   capture a candidate fact to $KNOWLEDGE_DIR/ai/YYYY-MM-DD.md
+The sole supported capture/consolidation CLI for the knowledge vault. A fresh
+`dotagents setup` copies this Go package source, materializes the embedded
+`go.mod.template` as `go.mod`, and `dotagents sync` builds and installs it to
+`$GOBIN` or `~/.local/bin`. In this repository the package remains part of the
+root module, so `go test ./...` covers it without a nested module boundary.
+
+```text
+rem add [-src harness] "<fact>"   capture an inert candidate in ai/YYYY-MM-DD.md
 rem search "<query>"              semantic search via memsearch (collection ai)
-rem dream [--apply]               consolidation report; --apply collapses exact-duplicate
-                                  sync sections in sessions/knowledge.md (backup + commit)
-rem sync                          commit+merge+push the vault via knowledge-sync
+rem dream [--apply]               report candidates; optionally collapse exact
+                                  duplicate sync sections with backup + commit
+rem sync                          run the guarded knowledge-sync binary
 ```
 
-`rem search` targets collection `ai` (the canonical vault collection) unless you
-pass your own `-c`/`--collection`.
+`rem dream` is the only consolidation command. Its normal mode writes a review
+report and does not promote facts. `--apply` performs only its documented,
+unattended-safe exact-duplicate cleanup; it does not infer or promote facts.
+Session digests written by memory hooks remain context records, not durable
+profile claims.
 
 Environment:
 
-- `KNOWLEDGE_DIR` - vault root (default `~/Workspace/knowledge`)
-- `REM_SYNC_BIN` - alternate knowledge-sync binary for `rem sync` (default `~/.local/bin/knowledge-sync`)
-- `REM_COLLECTION` - collection for `rem search` (default `ai`)
-
-## Consolidation: one owner per input (R4)
-
-There are two `dream` passes; they consume **different inputs** and neither
-feeds the other, so ownership is split deliberately to avoid duplication:
-
-| Pass | Owner | Input | Output |
-|---|---|---|---|
-| `rem dream` (this tool) | Go | `ai/` candidate captures | promotion report in `reviews/`; `--apply` collapses exact-duplicate sync sections in `sessions/knowledge.md` |
-| `basic_memory dream` | Python (`lib/basic_memory.py`) | `sessions/` session digests | review-only JSON in `reviews/` |
-
-`rem dream` owns the explicit `rem add` candidate loop (promotion into
-`profile/USER.md` or `AGENTS.md`); `basic_memory dream` owns automatic session
-digests. Keep them on separate inputs -- do not point either at the other's
-source.
-
-Design and rationale: `plans/rem-plan-2026-08.md` in the knowledge vault.
+- `KNOWLEDGE_DIR` — vault root (default `~/Workspace/knowledge`)
+- `REM_SYNC_BIN` — alternate `knowledge-sync` binary
+- `REM_COLLECTION` — collection for `rem search` (default `ai`)
 
-Tests: `go test ./...`
+Tests are included in the root module and run with `go test ./...`.
diff --git a/memory/tools/rem/dream_test.go b/memory/tools/rem/dream_test.go
index 6635366..9026c6a 100644
--- a/memory/tools/rem/dream_test.go
+++ b/memory/tools/rem/dream_test.go
@@ -91,26 +91,32 @@ func TestDreamApplyCollapsesWithBackupAndGuards(t *testing.T) {
 		out, err := c.CombinedOutput()
 		return string(out), err
 	}
+	mustRun := func(args ...string) string {
+		t.Helper()
+		out, err := run(args...)
+		if err != nil {
+			t.Fatalf("git %v: %v %s", args, err, out)
+		}
+		return out
+	}
 	if out, err := run("init"); err != nil {
 		t.Fatalf("git init: %v %s", err, out)
 	}
-	run("config", "user.email", "t@t")
-	run("config", "user.name", "t")
+	mustRun("config", "user.email", "t@t")
+	mustRun("config", "user.name", "t")
 	write(t, filepath.Join(root, "sessions", "other.md"), "- clean\n")
 	kb := "# H\n\n## Sync 2026-05-01 00:00 UTC\n\n- fact A\n\n## Sync 2026-05-02 00:00 UTC\n\n- fact A\n"
 	write(t, filepath.Join(root, "sessions", "knowledge.md"), kb)
-	run("add", "-A")
-	run("commit", "-m", "init")
-	if _, err := run("branch", "-M", "main"); err != nil {
-		t.Fatalf("branch: %v", err)
-	}
+	mustRun("add", "-A")
+	mustRun("commit", "-m", "init")
+	mustRun("branch", "-M", "main")
 
 	// Guard: uncommitted change blocks apply.
 	appendLine(t, filepath.Join(root, "sessions", "other.md"), "- dirty\n")
 	if err := dreamApply(nil); err == nil {
 		t.Error("apply should refuse on dirty tree")
 	}
-	run("reset", "--hard")
+	mustRun("reset", "--hard")
 
 	if err := dreamApply(nil); err != nil {
 		t.Fatalf("apply: %v", err)
@@ -123,7 +129,7 @@ func TestDreamApplyCollapsesWithBackupAndGuards(t *testing.T) {
 	if len(matches) != 1 {
 		t.Errorf("expected one backup, got %v", matches)
 	}
-	out, _ := run("log", "--oneline")
+	out := mustRun("log", "--oneline")
 	if !strings.Contains(out, "rem dream: collapse 1 duplicate") {
 		t.Errorf("commit message missing: %s", out)
 	}
@@ -139,6 +145,11 @@ func appendLine(t *testing.T, path, line string) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	f.WriteString(line + "\n")
-	f.Close()
+	if _, err := f.WriteString(line + "\n"); err != nil {
+		f.Close()
+		t.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
 }
diff --git a/memory/tools/rem/go.mod b/memory/tools/rem/go.mod.template
similarity index 54%
rename from memory/tools/rem/go.mod
rename to memory/tools/rem/go.mod.template
index b7632c5..a598589 100644
--- a/memory/tools/rem/go.mod
+++ b/memory/tools/rem/go.mod.template
@@ -1,3 +1,3 @@
 module rem
 
-go 1.26.1
+go 1.24.2
diff --git a/scripts/release.sh b/scripts/release.sh
index 71f7e09..bb6c494 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -1,41 +1,158 @@
 #!/usr/bin/env sh
 # Cut a dotagents release: verify, tag, push. CI does the rest.
 #
-# Usage: scripts/release.sh v0.7.0
+# Usage: scripts/release.sh vX.Y.Z [--yes|-y]
 #
-# Pushing a v* tag triggers .github/workflows/release.yml, which:
-#   1. runs goreleaser  -> binaries + checksums + GitHub release + homebrew tap bump
-#   2. publishes the npm wrapper (dotagents) with provenance
-TAG="${1:-}"
-YES="${2:-}"
-
-[ -f .goreleaser.yaml ] || { echo "run from the dotagents repo root"; exit 1; }
-case "$TAG" in v[0-9]*.[0-9]*.[0-9]*) ;; *) echo "usage: scripts/release.sh v0.7.0 [--yes]"; exit 1 ;; esac
+# Pushing a v* tag triggers .github/workflows/release.yml, which re-verifies the
+# tag against main and a green ci.yml run, waits on the protected `release`
+# environment, then publishes binaries, the Homebrew tap, and the npm wrapper.
+# Tagging only happens after the release PR is reviewed and merged, and after
+# explicit approval -- this script is the approval step, so it must be run on
+# purpose, from a clean up-to-date main.
+#
+# Set DOTAGENTS_RELEASE_LIB=1 to source the helpers (used by release_test.sh)
+# without running a release.
+
+set -eu
+
+SEMVER_RE='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+NPM_PACKAGE='@your_conscience/dotagents'
+HOMEBREW_FORMULA='dotagents'
+
+usage() {
+	cat <<'EOF'
+usage: scripts/release.sh vX.Y.Z [--yes|-y]
+
+Runs the release checks, then creates and pushes the annotated tag. CI publishes
+the GitHub release, the Homebrew tap bump, and the npm wrapper from that tag.
+EOF
+}
+
+die() {
+	echo "error: $*" >&2
+	exit 1
+}
+
+note() {
+	echo ">> $*"
+}
+
+# valid_tag reports whether the argument is a strict stable semver tag.
+valid_tag() {
+	printf '%s' "${1:-}" | grep -Eq "$SEMVER_RE"
+}
+
+# version_gt reports whether $1 is a greater stable version than $2.
+version_gt() {
+	newer=${1#v}
+	older=${2#v}
+	newer_major=${newer%%.*}
+	newer_rest=${newer#*.}
+	newer_minor=${newer_rest%%.*}
+	newer_patch=${newer_rest#*.}
+	older_major=${older%%.*}
+	older_rest=${older#*.}
+	older_minor=${older_rest%%.*}
+	older_patch=${older_rest#*.}
+	[ "$newer_major" -gt "$older_major" ] && return 0
+	[ "$newer_major" -lt "$older_major" ] && return 1
+	[ "$newer_minor" -gt "$older_minor" ] && return 0
+	[ "$newer_minor" -lt "$older_minor" ] && return 1
+	[ "$newer_patch" -gt "$older_patch" ] && return 0
+	return 1
+}
+
+# check_clean_tree refuses to tag anything but an exactly committed tree.
+# Untracked files are refused too: they usually mean uncommitted work, and a
+# release should be reproducible from the tagged commit alone.
+check_clean_tree() {
+	git diff --quiet || die "working tree has unstaged changes"
+	git diff --cached --quiet || die "index has staged changes"
+	[ -z "$(git ls-files -u)" ] || die "working tree has unmerged files"
+	untracked=$(git ls-files --others --exclude-standard)
+	[ -z "$untracked" ] || die "untracked files present: $(printf '%s' "$untracked" | tr '\n' ' ')"
+}
+
+run_checks() {
+	note "go test ./..."
+	go test ./...
+
+	note "go build ./..."
+	go build ./...
+
+	note "go vet ./..."
+	go vet ./...
+
+	if command -v python3 >/dev/null 2>&1; then
+		note "python3 memory tests"
+		python3 -m unittest discover -s memory/tests
+	else
+		note "python3 not found: skipped memory tests"
+	fi
+
+	if command -v node >/dev/null 2>&1; then
+		note "node --test npm/install.test.js"
+		node --test npm/install.test.js
+	else
+		note "node not found: skipped npm wrapper tests"
+	fi
+
+	note "scripts/release_test.sh"
+	sh "$(dirname -- "$0")/release_test.sh"
+
+	if command -v goreleaser >/dev/null 2>&1; then
+		note "goreleaser check"
+		goreleaser check
+	else
+		note "goreleaser not found: skipped config check (CI runs goreleaser)"
+	fi
+}
+
 confirm() {
-	[ "$YES" = "--yes" ] && return 0
+	if [ "$YES" = "--yes" ] || [ "$YES" = "-y" ]; then
+		return 0
+	fi
 	printf '%s [y/N] ' "$1"
 	read -r answer
-	[ "$answer" = y ]
+	[ "$answer" = y ] || [ "$answer" = Y ]
 }
-case "$TAG" in v[0-9]*.[0-9]*.[0-9]*) ;; *) echo "tag must look like v0.7.0"; exit 1 ;; esac
 
-branch=$(git rev-parse --abbrev-ref HEAD)
-[ "$branch" = "main" ] || { echo "must be on main (on $branch)"; exit 1; }
-[ -z "$(git status --porcelain | grep '^[ MARC]')" ] || { echo "working tree has uncommitted changes"; exit 1; }
-git fetch origin --tags -q
-[ "$(git rev-parse main)" = "$(git rev-parse origin/main)" ] || { echo "main not in sync with origin/main"; exit 1; }
-git rev-parse -q --verify "refs/tags/$TAG" >/dev/null && { echo "$TAG already exists"; exit 1; }
+main() {
+	TAG="${1:-}"
+	YES="${2:-}"
+
+	[ -n "$TAG" ] || { usage >&2; exit 1; }
+	valid_tag "$TAG" || { usage >&2; die "tag must look like v0.9.0"; }
+	[ -f .goreleaser.yaml ] || die "run from the dotagents repo root"
+
+	branch=$(git rev-parse --abbrev-ref HEAD)
+	[ "$branch" = "main" ] || die "must be on main (on $branch)"
+	check_clean_tree
+
+	git fetch origin --tags -q
+	[ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ] || die "HEAD is not in sync with origin/main"
 
-echo ">> go test ./..."
-go test ./...
+	previous=$(git describe --tags --abbrev=0 --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null || true)
+	if [ -n "$previous" ]; then
+		version_gt "$TAG" "$previous" || die "$TAG is not newer than $previous"
+	fi
+	git rev-parse -q --verify "refs/tags/$TAG" >/dev/null && die "$TAG already exists"
 
-prev=$(git describe --tags --abbrev=0)
-echo ">> changes since $prev:"
-git log --oneline "$prev"..main | sed 's/^/   /'
+	run_checks
 
-confirm "release $TAG? [y/N] " || { echo "aborted"; exit 1; }
-git tag -a "$TAG" -m "$TAG"
-git push origin "$TAG"
+	if [ -n "$previous" ]; then
+		note "changes since $previous:"
+		git log --oneline "$previous"..HEAD | sed 's/^/   /'
+	fi
+
+	confirm "release $TAG?" || die "aborted"
+
+	git tag -a "$TAG" -m "$TAG" || die "failed to create $TAG"
+	git push origin "$TAG" || die "failed to push $TAG (the local tag is still present; delete it with 'git tag -d $TAG' before retrying)"
+
+	echo ">> tag $TAG pushed. CI publishes binaries, brew tap, and npm."
+	echo ">> watch: gh run watch --interval 30 \$(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')"
+	echo ">> after CI: brew info $HOMEBREW_FORMULA && npm view $NPM_PACKAGE version"
+}
 
-echo ">> tag pushed. watch: gh run watch --interval 30 \$(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')"
-echo ">> after CI: brew info dotagents && npm view dotagents version"
+[ "${DOTAGENTS_RELEASE_LIB:-}" = "1" ] || main "$@"
diff --git a/scripts/release_test.sh b/scripts/release_test.sh
new file mode 100755
index 0000000..8229a4a
--- /dev/null
+++ b/scripts/release_test.sh
@@ -0,0 +1,108 @@
+#!/usr/bin/env sh
+# Tests for the validation helpers in scripts/release.sh.
+#
+# Sourcing the script with DOTAGENTS_RELEASE_LIB=1 exposes valid_tag,
+# version_gt, and check_clean_tree without running a release.
+
+set -eu
+
+here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+DOTAGENTS_RELEASE_LIB=1 . "$here/release.sh"
+
+failures=0
+
+fail() {
+	echo "FAIL: $*" >&2
+	failures=$((failures + 1))
+}
+
+accept_tag() {
+	valid_tag "$1" || fail "expected tag '$1' to be accepted"
+}
+
+reject_tag() {
+	if valid_tag "$1"; then
+		fail "expected tag '$1' to be rejected"
+	fi
+}
+
+accept_newer() {
+	version_gt "$1" "$2" || fail "expected $1 to be newer than $2"
+}
+
+reject_newer() {
+	if version_gt "$1" "$2"; then
+		fail "expected $1 to not be newer than $2"
+	fi
+}
+
+# Strict stable semver only.
+accept_tag v0.1.0
+accept_tag v0.9.0
+accept_tag v1.0.0
+accept_tag v10.20.30
+reject_tag ""
+reject_tag 1.2.3
+reject_tag v1.2
+reject_tag v1.2.3.4
+reject_tag v1.2.3-rc.1
+reject_tag v1.2.3+build
+reject_tag v01.2.3
+reject_tag v1.02.3
+reject_tag v1x.2y.3z
+reject_tag V1.2.3
+reject_tag v1.2.x
+
+# Version ordering.
+accept_newer v0.9.0 v0.8.0
+accept_newer v0.10.0 v0.9.9
+accept_newer v1.0.0 v0.99.99
+accept_newer v0.2.1 v0.2.0
+reject_newer v0.8.0 v0.9.0
+reject_newer v0.9.0 v0.9.0
+reject_newer v1.0.0 v1.0.0
+
+# Clean-tree detection in a throwaway repository.
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+(
+	cd "$tmp"
+	git init -q .
+	git config user.email release-test@example.com
+	git config user.name "release test"
+	printf 'tracked\n' > tracked.txt
+	git add tracked.txt
+	git commit -qm "initial"
+
+	check_clean_tree || fail "expected a freshly committed tree to be clean"
+
+	printf 'changed\n' >> tracked.txt
+	if (check_clean_tree) 2>/dev/null; then
+		fail "expected unstaged changes to be refused"
+	fi
+	git checkout -q -- tracked.txt
+
+	printf 'staged\n' > staged.txt
+	git add staged.txt
+	if (check_clean_tree) 2>/dev/null; then
+		fail "expected staged changes to be refused"
+	fi
+	git rm -q --cached staged.txt
+	rm -f staged.txt
+
+	printf 'untracked\n' > untracked.txt
+	if (check_clean_tree) 2>/dev/null; then
+		fail "expected untracked files to be refused"
+	fi
+	rm -f untracked.txt
+
+	check_clean_tree || fail "expected the tree to be clean again"
+) || failures=$((failures + 1))
+
+if [ "$failures" -ne 0 ]; then
+	echo "release_test.sh: $failures failure(s)" >&2
+	exit 1
+fi
+
+echo "release_test.sh: ok"
diff --git a/starter_assets.go b/starter_assets.go
index 2f3e7b9..70cb808 100644
--- a/starter_assets.go
+++ b/starter_assets.go
@@ -6,5 +6,9 @@ import "embed"
 // user-owned canonical configuration root. The CLI must not read these paths
 // from the source checkout at runtime; release binaries carry them here.
 //
-//go:embed .gitignore AGENTS.md dotagents.yaml dotagents.lock plugin.json agents/*.md skills/dotagents skills/grilling memory/hooks memory/lib
+// This file lives at the repository root on purpose: go:embed can only reach
+// files at or below its own directory, so the manifest cannot move into
+// internal/. Keep the embed list in sync with the public starter inventory.
+//
+//go:embed .gitignore AGENTS.md dotagents.yaml dotagents.lock plugin.json agents/*.md skills/dotagents skills/grilling memory/hooks memory/lib memory/tools
 var StarterAssets embed.FS