diff --git a/.context/CONTEXT.md b/.context/CONTEXT.md
index ccf21f9..a3ddde7 100644
--- a/.context/CONTEXT.md
+++ b/.context/CONTEXT.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-**dotcontext** is an AI context toolkit for Claude Code. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.
+**dotcontext** is an AI context toolkit for coding agents — Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.
 
 **Users:** Developers and teams who use AI coding assistants and want to provide them with project context.
 
@@ -14,12 +14,13 @@
 
 | Entity | Responsibility |
 |--------|----------------|
-| `CLAUDE.md` | Root-level project context: stack, commands, critical rules, architecture overview |
+| `AGENTS.md` | **Canonical** root-level project instructions: stack, commands, critical rules, architecture, workflows. Read natively by Codex/opencode/Copilot/Cursor |
+| `CLAUDE.md` / `GEMINI.md` | Thin `@AGENTS.md` import stubs for Claude Code / Gemini CLI (emitted per selected harness) |
 | `.context/CONTEXT.md` | Domain knowledge: entities, flows, integrations, glossary |
 | `ADR (Architectural Decision Record)` | Documents a significant architectural decision with context, alternatives, and consequences |
 | `Skill` | Step-by-step guide for a recurring pattern or task in the codebase |
 | `PRP (Product Requirements Prompt)` | Structured feature specification with implementation plan and phases |
-| `Command` | Custom Claude Code slash command (markdown file in `.claude/commands/`) |
+| `Command` | A workflow prompt, emitted per harness (`.claude/commands/`, `.opencode/command/`, `.github/prompts/`, or the `## Workflows` section of `AGENTS.md`) |
 | `Discovery` | Output document from deep context analysis with business rules and cross-repo validation |
 | `Bug Report` | Structured report from `/fix-bug` with root cause, reproduction test, and fix details |
 
diff --git a/.context/decisions/003-safe-update-behavior.md b/.context/decisions/003-safe-update-behavior.md
index ac07cc6..e5d2bf3 100644
--- a/.context/decisions/003-safe-update-behavior.md
+++ b/.context/decisions/003-safe-update-behavior.md
@@ -43,19 +43,19 @@ There is **no `--force` flag** — it was removed (it had degenerated into a pla
 ## Consequences
 
 ### Positive
-- User customizations are preserved by default
-- Explicit `--force` prevents accidental data loss
-- Simple mental model: default is safe
+- User customizations (seeds) are preserved by default — never force-overwritten
+- Managed files stay current via a diff-and-prompt update (no blunt overwrite needed)
+- Simple mental model: seeds are create-only, managed files prompt
 - New templates from updates are still available
 
 ### Negative
-- Users with outdated templates may not get improvements
-- Must document that `--force` is needed for full reset
-- No way to selectively update one template
+- Users with outdated seed files may not get improvements (by design — seeds are user-owned)
+- To reset a seed, the user must delete it and re-run update
+- No destructive `--force` flag (removed in v2.0); `--yes` only auto-confirms managed updates
 
 ### Risks
 - Users may not realize their templates are outdated
-- Mitigation: Add `dotcontext status` command to check for template drift (future)
+- Mitigation: `dotcontext doctor` reports when a newer version is available (ADR-015)
 
 ## History
 
diff --git a/.context/decisions/004-claude-code-integration.md b/.context/decisions/004-claude-code-integration.md
index 48a9177..186b451 100644
--- a/.context/decisions/004-claude-code-integration.md
+++ b/.context/decisions/004-claude-code-integration.md
@@ -1,10 +1,15 @@
 # ADR-004: Claude Code Integration via Slash Commands
 
-**Status:** Accepted
+**Status:** Accepted (extended beyond Claude by ADR-016/017/018)
 **Date:** 2025-01-31
 **Version:** 1.0
 **Deciders:** Gocase Team
 
+> **Note (2026-06):** the "tightly coupled to Claude Code (won't work with other AI tools)" tradeoff below
+> has been lifted — dotcontext now serves six harnesses. Instructions go through a canonical `AGENTS.md`
+> (ADR-016), skills/hooks port per agent (ADR-017), and workflows reach each agent's command primitive or
+> the `AGENTS.md` Workflows section (ADR-018). This ADR is kept as the original Claude-first record.
+
 ## Context
 
 dotcontext creates documentation structure, but the real value comes from AI assistants using that documentation. We needed to decide how to integrate with Claude Code (Anthropic's CLI for Claude).
@@ -52,3 +57,6 @@ Commands created:
 
 ## Related
 - ADR-005: AskUserQuestion requirement
+- ADR-016: Multi-agent harness (extends this beyond Claude)
+- ADR-017: Skills & hooks portability + harness selection
+- ADR-018: Command portability & invocation modes
diff --git a/.context/decisions/005-askuserquestion-requirement.md b/.context/decisions/005-askuserquestion-requirement.md
index db7244f..fff68a7 100644
--- a/.context/decisions/005-askuserquestion-requirement.md
+++ b/.context/decisions/005-askuserquestion-requirement.md
@@ -63,6 +63,12 @@ The root `CLAUDE.md` also includes this as Critical Rule #1:
 | 1.0 | 2025-02-02 | Initial decision |
 | 2.0 | 2026-05-21 | Replaced fixed "10 questions" quota in `/generate-prp` with clarity-assessment policy (0..N questions). Selectively absorbed ideas from spec-driven-build skill without adopting its full ceremony. |
 
+> **Cross-agent note (2026-06):** `AskUserQuestion` is Claude's tool name. Every supported agent ships an
+> equivalent structured-question tool (`request_user_input`, `question`, `ask_user`, `cursor/ask_question`),
+> so this requirement holds on all of them. ADR-018 makes it portable via a neutral `{{ASK}}` convention
+> that renders to each agent's native tool — it does not degrade to free text.
+
 ## Related
 - ADR-004: Claude Code integration
 - ADR-011: Test-Driven Bug Fixing Pattern (partial exception — `/fix-bug` skips initial questions)
+- ADR-018: Command portability — generalizes this requirement across agents via `{{ASK}}`
diff --git a/.context/decisions/014-automated-release-pipeline.md b/.context/decisions/014-automated-release-pipeline.md
index 47e55ec..e81af50 100644
--- a/.context/decisions/014-automated-release-pipeline.md
+++ b/.context/decisions/014-automated-release-pipeline.md
@@ -28,7 +28,8 @@ Inspired by github/spec-kit's tag-triggered release workflow, which generates no
    `v*` tag. The workflow:
    - runs `make build` and fails if the committed `dotcontext` is out of sync with `src/`,
    - fails if the tag does not match the binary's `VERSION`,
-   - generates release notes from `git log --no-merges` since the previous tag,
+   - takes release notes from the matching `CHANGELOG.md` section (falling back to `git log --no-merges`
+     since the previous tag when no section exists), since squash-merges make the git log too sparse,
    - runs `gh release create`. Humans must not call `gh release create` by hand.
 
 3. **A CI workflow (`.github/workflows/ci.yml`)** runs on PRs and pushes to `main`:
@@ -44,8 +45,8 @@ Inspired by github/spec-kit's tag-triggered release workflow, which generates no
 
 ### Negative
 - Contributors must remember to `make build` and commit the binary (now enforced by CI).
-- Release notes from `git log` are only as good as commit hygiene; the curated `CHANGELOG.md`
-  entry remains the human-readable record.
+- Release notes are only as good as the `CHANGELOG.md` entry for that version, so each release needs a
+  written changelog section (the `git log` fallback is sparse under squash-merge).
 
 ## Alternatives Considered
 
diff --git a/.context/decisions/015-capability-discovery-and-update-awareness.md b/.context/decisions/015-capability-discovery-and-update-awareness.md
index d17704b..cb3652c 100644
--- a/.context/decisions/015-capability-discovery-and-update-awareness.md
+++ b/.context/decisions/015-capability-discovery-and-update-awareness.md
@@ -13,7 +13,7 @@ Two gaps surfaced while comparing dotcontext to github/spec-kit:
    ran `dotcontext update`. spec-kit's `specify self check` surfaces "update available" passively.
 2. **No machine-readable capability handshake.** spec-kit exposes `specify version --features --json`
    so a harness can discover what the tool supports before invoking it. This becomes important for
-   the planned multi-agent work (ADR-016, forthcoming), where a harness must know whether features
+   the multi-agent work (ADR-016), where a harness must know whether features
    like `AskUserQuestion`, statusline, or multi-agent output are available.
 
 A standing project constraint is to keep the CLI surface minimal — new flows belong inside existing
@@ -29,8 +29,9 @@ commands, not as new top-level subcommands (see ADR-007).
 
 2. **`--version` gains `--features` and `--json`.** Plain `--version` is unchanged. `--features` prints
    a human-readable capability list; `--json` emits a machine-readable handshake (name, version, repo,
-   commands, and a `capabilities` object) with **no jq dependency** (hand-built JSON). The current
-   `capabilities.multiagent` is `false` and `agents` is `["claude"]`; these flip when ADR-016 lands.
+   commands, and a `capabilities` object) with **no jq dependency** (hand-built JSON). Since ADR-016/017/018
+   landed, `capabilities.multiagent` is `true`, `skills`/`hooks`/`commands` are `true`, and `agents` lists
+   the full adapter registry (`claude codex opencode gemini copilot cursor`).
 
 ## Consequences
 
@@ -59,4 +60,4 @@ commands, not as new top-level subcommands (see ADR-007).
 ## Related
 - ADR-007: CLI simplification
 - ADR-005: Mandatory AskUserQuestion (a capability that does not port to other agents)
-- ADR-016: Multi-agent harness support (forthcoming) — will consume the capability handshake
+- ADR-016: Multi-agent harness support — consumes the capability handshake
diff --git a/.context/decisions/016-multi-agent-harness.md b/.context/decisions/016-multi-agent-harness.md
index c671cb3..2bb9a2b 100644
--- a/.context/decisions/016-multi-agent-harness.md
+++ b/.context/decisions/016-multi-agent-harness.md
@@ -106,6 +106,7 @@ This ADR covers the **instructions file** only. Skills and hooks portability is
 
 ## Related
 - ADR-004: Claude Code integration (this extends it beyond Claude)
-- ADR-005: Mandatory AskUserQuestion (will get a v2.0 for command portability in phase 2b)
-- ADR-007: CLI simplification (interactive detection, no new flags)
+- ADR-005: Mandatory AskUserQuestion (ADR-018 renders `{{ASK}}` to each agent's native question tool)
+- ADR-007: CLI simplification (interactive detection; the `--agents` flag is a scoped exception, see ADR-017)
 - ADR-015: Capability discovery & update awareness (the handshake this populates)
+- ADR-017 / ADR-018: skills & hooks portability, command portability
diff --git a/.context/decisions/018-command-portability-and-invocation-modes.md b/.context/decisions/018-command-portability-and-invocation-modes.md
index a03ea16..3dd17c3 100644
--- a/.context/decisions/018-command-portability-and-invocation-modes.md
+++ b/.context/decisions/018-command-portability-and-invocation-modes.md
@@ -1,7 +1,8 @@
 # ADR-018: Command Portability & Invocation Modes (phase 2b plan)
 
-**Status:** Proposed
+**Status:** Accepted
 **Date:** 2026-06-03
+**Version:** 1.0
 **Deciders:** Nicholas (Gocase)
 
 ## Context
@@ -39,19 +40,41 @@ Rationale for the promotions: `code-review` and `deep-context` are read-mostly,
 / "help me understand X" are natural auto-triggers — discovery adds value with no side-effect risk, and
 the explicit `/name` still works.
 
-### 2. Emit per agent by mode
+### 2. Emit per agent by mode — **hybrid** (chosen)
 
 - `skill` mode → `SKILL.md` (already ports to all six — ADR-017).
-- `command` mode → each agent's **explicit** primitive: Claude command, opencode command, Copilot
-  prompt file, Gemini custom command (TOML), Cursor skill + `disable-model-invocation`, Codex prompt
-  (global `~/.codex/prompts/`, namespaced). Where an agent only offers auto-skills, use its explicit
-  flag if honored, otherwise fall back to documenting the workflow in `AGENTS.md`.
+- `command` mode → **native command/prompt files where the format is markdown-compatible and safe**,
+  and **`AGENTS.md` documentation everywhere else**:
+  - **Claude** → `.claude/commands/<name>.md` (slash command)
+  - **opencode** → `.opencode/command/<name>.md`
+  - **Copilot** → `.github/prompts/<name>.prompt.md`
+  - **Gemini, Cursor, Codex** → a **`## Workflows`** section in `AGENTS.md` (lists each workflow + when
+    to use). Rejected per-agent transforms (Gemini TOML, Cursor skill+flag, Codex global prompts) as
+    high-effort, format-divergent, and not runtime-verifiable here — the `AGENTS.md` section makes the
+    workflows usable on those agents without fragile generation.
+
+The canonical bodies are the existing `templates/.claude/commands/*.md`; opencode/Copilot receive copies
+(create-only). The `AGENTS.md` Workflows section also instructs every agent to use its **native
+structured-question tool** for clarification.
+
+> **Note:** the `code-review`/`deep-context` skill-mode promotion (item 1) is recorded but **not yet
+> applied** — they currently ship as commands. Converting them to discoverable `SKILL.md` is a small
+> follow-up within phase 2b.
 
 ### 3. Portable `{{ASK}}` directive
 
 Command/skill bodies express requirement-gathering with a portable `{{ASK: question | optA | optB }}`
-directive. At emit time it renders to each agent's **native** structured-question tool — it does **not**
-degrade to free text. This satisfies ADR-005's clarity-assessed questioning on every agent.
+directive. Because **every** agent ships a native structured-question tool (Context fact 2), this is an
+**authoring convention**, not a runtime transformer: bodies say "ask the user via your structured-question
+tool: …", and each agent's model uses its own (`AskUserQuestion` / `ask_user` / `question` / …). It does
+**not** degrade to free text, and satisfies ADR-005's clarity-assessed questioning on every agent.
+
+### 4. Skill frontmatter (`name` + `description`) — DONE
+
+Every `SKILL.md` now opens with YAML frontmatter (`name` matching the directory, a keyword-front-loaded
+`description`). Without it the model can't auto-discover a skill — only explicit `/name` works — which
+would defeat the description-driven discovery ADR-016/017 rely on. Applied to all four current skills
+(`bug-reproduction`, `batch-operations`, `git-platform`, `update-api-documentation`).
 
 ## Consequences
 
@@ -71,7 +94,7 @@ degrade to free text. This satisfies ADR-005's clarity-assessed questioning on e
 
 | Version | Date | Changes |
 |---------|------|---------|
-| 1.0 (proposed) | 2026-06-03 | Initial plan for phase 2b |
+| 1.0 | 2026-06-03 | Accepted — skill frontmatter + hybrid command portability (opencode/Copilot native; AGENTS.md Workflows for Gemini/Cursor/Codex) |
 
 ## Related
 - ADR-005: Mandatory AskUserQuestion (clarity assessment) — `{{ASK}}` is how it's satisfied cross-agent
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..a087313
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[bug] "
+labels: bug
+---
+
+**What you ran** (the exact `dotcontext` command, and which agent/harness — Claude, Codex, opencode, Gemini, Copilot, Cursor):
+
+```
+```
+
+**`dotcontext --version`:**
+
+**OS / shell:**
+
+**Expected:**
+
+**Actual** (paste the output):
+
+```
+```
+
+**Steps to reproduce:**
+1.
+2.
+
+**`dotcontext doctor` output** (optional, often helpful):
+
+```
+```
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..33fce06
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: How to contribute (add a skill, etc.)
+    url: https://github.com/goca-se/dotcontext/blob/main/CONTRIBUTING.md
+    about: Read the contributing guide before opening a PR.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..2a9e9eb
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea — a new skill, harness, command, or improvement
+title: "[feat] "
+labels: enhancement
+---
+
+**Use case** — what are you trying to do, and why? ("I'm trying to … so that …")
+
+**Proposed solution:**
+
+**If this is a new skill or harness, which agent(s) does it target?**
+(Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, Cursor)
+
+**Alternatives considered:**
+
+**Additional context:**
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..4fe1f11
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,28 @@
+<!-- Thanks for contributing! Keep the summary tight. See CONTRIBUTING.md. -->
+
+## Summary
+
+<!-- What does this change and why? -->
+
+## Changes
+
+-
+
+## Type
+
+- [ ] Skill / template (no `src/` change)
+- [ ] CLI behavior (`src/` change — rebuilt the `dotcontext` binary)
+- [ ] Docs / ADR
+- [ ] Other
+
+## Checklist
+
+- [ ] Ran `make build` and committed the rebuilt `dotcontext` (CI fails if it's out of sync with `src/`)
+- [ ] `bash -n` passes and I tested locally (`./dotcontext …`)
+- [ ] New skills include `name`/`description` frontmatter and are wired into `init.sh` + `update.sh`
+- [ ] Checked `.context/decisions/` — no ADR conflict (or I noted/added one)
+- [ ] Conventional-commit style on commits (`feat:` / `fix:` / `docs:` / `chore:`)
+
+## Test plan
+
+-
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 6660750..3bc24e5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,7 +1,8 @@
 name: Release
 
 # Tag-triggered release: push a vX.Y.Z tag and this builds, verifies, and
-# publishes a GitHub release with notes generated from the git log.
+# publishes a GitHub release. Notes come from the matching CHANGELOG.md section
+# (falling back to the git log when no section exists).
 on:
   push:
     tags:
@@ -39,16 +40,33 @@ jobs:
 
       - name: Generate release notes
         run: |
+          ver="${GITHUB_REF_NAME#v}"
           prev="$(git describe --tags --abbrev=0 "${GITHUB_REF_NAME}^" 2>/dev/null || echo "")"
+
+          # Prefer the curated CHANGELOG.md section for this version (everything
+          # between its "## [ver]" header and the next "## [" header).
+          notes="$(awk -v ver="$ver" '
+            index($0, "## [" ver "]") == 1 { capture=1; next }
+            capture && index($0, "## [") == 1 { exit }
+            capture { print }
+          ' CHANGELOG.md)"
+
           {
-            echo "## What's Changed"
-            echo ""
+            if [ -n "$(printf '%s' "$notes" | tr -d '[:space:]')" ]; then
+              printf '%s\n' "$notes"
+            else
+              # Fallback: build from the git log since the previous tag.
+              echo "## What's Changed"
+              echo ""
+              if [ -n "$prev" ]; then
+                git log --no-merges --pretty='* %s (%h)' "${prev}..${GITHUB_REF_NAME}"
+              else
+                git log --no-merges --pretty='* %s (%h)' "${GITHUB_REF_NAME}"
+              fi
+            fi
             if [ -n "$prev" ]; then
-              git log --no-merges --pretty='* %s (%h)' "${prev}..${GITHUB_REF_NAME}"
               echo ""
               echo "**Full Changelog**: https://github.com/${GITHUB_REPOSITORY}/compare/${prev}...${GITHUB_REF_NAME}"
-            else
-              git log --no-merges --pretty='* %s (%h)' "${GITHUB_REF_NAME}"
             fi
           } > RELEASE_NOTES.md
           cat RELEASE_NOTES.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc5feda..7e492fa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.17.0](https://github.com/goca-se/dotcontext/compare/v0.16.0...v0.17.0) (2026-06-03)
+
+### Features
+
+* **multi-agent commands & skill discovery (phase 2b)** — completes the multi-agent story for skills and workflows (ADR-018):
+  * **skill frontmatter** — every `SKILL.md` now carries YAML `name` + `description`, so the model can **auto-discover** skills by description on every agent (not just via explicit `/name`). Applied to `bug-reproduction`, `batch-operations`, `git-platform`, `update-api-documentation`
+  * **commands across harnesses (hybrid)** — the 12 workflow prompts now reach non-Claude agents: **opencode** gets `.opencode/command/*.md` and **Copilot** gets `.github/prompts/*.prompt.md` (native copies); **Gemini/Cursor/Codex** get a new **`## Workflows`** section in `AGENTS.md` that lists each workflow and tells the agent to use its native structured-question tool for clarification. Claude keeps `.claude/commands/`
+  * **`--version --json`** now reports `commands: true`
+  * **`/add-skill` updated** — it now generates the new skill format (YAML `name`/`description` frontmatter, description front-loaded for discovery) instead of the old `# Skill:`-only format, and notes the `.agents/skills` mirror for non-Claude agents
+  * emission is per **selected** harness and create-only (no junk, no clobber)
+* **new `update-api-documentation` skill** (#10, @anachronicsofa) — keeps external API/webhook contracts documented from a single OpenAPI source of truth (`docs/openapi.yml`), with generated Redoc HTML, `docs:validate`/`docs:build` tasks, and a CI step. Stack-agnostic (Rails/Node/Python examples). Merged after v0.16.0, so it ships in this release.
+* **release notes from `CHANGELOG.md`** — `release.yml` now uses the matching `CHANGELOG.md` section as the GitHub release body (squash-merges made the old git-log notes one line); falls back to the git log when no section exists.
+
+### Fixes
+
+* **commands now read/write `AGENTS.md`, not the `CLAUDE.md` stub** — `setup-context` writes project instructions to `AGENTS.md`; `fix-bug`, `execute-prp`, `deep-context`, and `code-review` read `AGENTS.md`. Previously they targeted `CLAUDE.md`, which is now just an `@AGENTS.md` import stub (so they were getting near-empty content).
+* **`doctor` no longer fails on valid non-Claude projects** — a missing Claude CLI is a warning, and the commands check recognizes `.opencode/command`, `.github/prompts`, and the `AGENTS.md` Workflows section.
+* consistency sweep across docs and ADRs (README, root `CLAUDE.md`, `CONTEXT.md`, ADR-003/004/005/015/016): removed stale "Claude-only" framing, the removed `--force` flag, and dangling/`forthcoming` ADR references.
+
+### Docs
+
+* added **`CONTRIBUTING.md`** (skill-first, with the full deploy/release flow), GitHub **issue templates** + a **pull request template**.
+* humanized `CONTRIBUTING.md` and the README multi-agent section.
+
+### Notes
+
+* Per-agent command files are emitted in markdown-compatible form (opencode/Copilot) — Gemini TOML / Cursor skill / Codex global-prompt transforms were intentionally **not** generated (format-divergent, not runtime-verifiable); those agents use the `AGENTS.md` Workflows section instead. The `code-review`/`deep-context` → skill-mode promotion (ADR-018 item 1) is recorded but deferred — they still ship as commands.
+
 ## [0.16.0](https://github.com/goca-se/dotcontext/compare/v0.15.0...v0.16.0) (2026-06-03)
 
 ### Features
diff --git a/CLAUDE.md b/CLAUDE.md
index 5761d75..d878505 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # dotcontext
 
-> AI context toolkit for Claude Code — commands, decisions, skills, and feature planning for your codebase.
+> AI context toolkit for coding agents (Claude Code, Codex, opencode, Gemini, Copilot, Cursor) — commands, decisions, skills, and feature planning for your codebase.
 
 ## Decision Compliance
 
@@ -29,8 +29,8 @@ If a requested change conflicts with an existing decision:
 ### CLI
 
 ```bash
-# Initialize context structure in a project (auto-runs /setup-context)
-dotcontext init [--name "Project Name"] [--yes] [--no-setup]
+# Initialize context structure in a project (harness-selective; auto-runs /setup-context when Claude is selected)
+dotcontext init [--name "Project Name"] [--agents claude,codex,...] [--yes] [--no-setup]
 
 # Update CLI + templates
 dotcontext update                     # Update CLI + templates (if in project)
@@ -43,9 +43,9 @@ dotcontext doctor
 # Shell tab completion
 dotcontext completion [bash|zsh]
 
-# Help
+# Help / version (--features and --json expose the capability handshake)
 dotcontext --help
-dotcontext --version
+dotcontext --version [--features|--json]
 ```
 
 ### Claude Code (interactive with questions)
@@ -82,13 +82,15 @@ The CLI is distributed as a single `dotcontext` bash script. Source code lives i
 
 ### Template-Based Init
 
-Templates live in `templates/` directory on GitHub and are downloaded during `dotcontext init`. The structure mirrors what gets created in user projects:
-- `templates/CLAUDE.md` → project root `CLAUDE.md`
+Templates live in `templates/` directory on GitHub and are downloaded during `dotcontext init`. `init` is **harness-selective** — only the chosen agents' files are emitted:
+- `templates/AGENTS.md` → project `AGENTS.md` (the **canonical** instructions, always emitted)
+- `templates/CLAUDE.md` / `templates/GEMINI.md` → thin `@AGENTS.md` import stubs (emitted only for Claude / Gemini)
 - `templates/.context/` → project `.context/` directory
+- `.claude/` (commands, agents, statusline, hooks) is emitted **only when Claude is selected**
 
-### Claude Code Integration
+### Multi-Agent Integration
 
-Slash commands in `.claude/commands/` provide interactive workflows that integrate with Claude Code's tool system (AskUserQuestion, file operations, etc.).
+Six harnesses are supported (Claude Code, Codex, opencode, Gemini CLI, Copilot, Cursor) via an adapter registry (`src/setup/agents.sh`). Workflows reach each harness in its native form: Claude `.claude/commands/`, opencode `.opencode/command/`, Copilot `.github/prompts/`, and a `## Workflows` section in `AGENTS.md` for Gemini/Cursor/Codex. Skills (`SKILL.md` with `name`/`description` frontmatter) go to `.claude/skills/` and/or `.agents/skills/`. See ADR-016/017/018.
 
 ---
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c36cf8a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,223 @@
+# Contributing to dotcontext
+
+Thanks for contributing. dotcontext is an AI context toolkit for coding agents (Claude Code, OpenAI
+Codex, opencode, Gemini CLI, GitHub Copilot, Cursor). Most people contribute by adding a skill, so that's
+where this guide starts. Build, PR, and release come after.
+
+## Table of contents
+
+- [Reporting bugs & requesting features](#reporting-bugs--requesting-features)
+- [How the project is built](#how-the-project-is-built)
+- [Add a skill (start here)](#add-a-skill-start-here)
+- [Other contributions](#other-contributions)
+- [Local development](#local-development)
+- [Pull request workflow](#pull-request-workflow)
+- [Decision compliance (ADRs)](#decision-compliance-adrs)
+- [How deploy / release works](#how-deploy--release-works)
+- [Community expectations](#community-expectations)
+
+---
+
+## Reporting bugs & requesting features
+
+Issues are welcome. Before opening one, search the existing issues so you don't file a duplicate.
+
+**Bug reports.** Open an issue and include:
+- what you ran (the exact `dotcontext` command, and which agent/harness),
+- `dotcontext --version`, plus your OS and shell,
+- what you expected, and what happened instead (paste the output),
+- the steps to reproduce it.
+
+Pasting `dotcontext doctor` output usually helps too.
+
+**Feature requests.** Describe the use case ("I'm trying to X so that Y"), not just the solution you have
+in mind. If it's a new skill or harness, say which agent(s) it targets. For anything large, open an issue
+to talk it through before you write a big PR.
+
+---
+
+## How the project is built
+
+- The CLI ships as a single bash executable, `dotcontext`, built by concatenating the modules in `src/`
+  (`core/`, `setup/`, `commands/`, `main.sh`) with `make build` (see the `Makefile`).
+- You edit `src/` and `templates/`. Don't hand-edit the bundled `dotcontext` file; run `make build`
+  instead. `src/header.sh` is the single source of truth for `VERSION`.
+- The `templates/` directory is what users receive. `dotcontext init` and `dotcontext update` fetch
+  templates from the `main` branch at runtime, so a merged template change is live right away. The CLI
+  binary itself comes from the latest release tag (see [release flow](#how-deploy--release-works)).
+
+There's no compiled language and no test framework, just bash. CI runs `bash -n` for syntax and checks
+that the committed `dotcontext` matches the `make build` output.
+
+---
+
+## Add a skill (start here)
+
+A skill is a reusable `SKILL.md` guide the agent discovers and pulls in when it's relevant (for example
+`bug-reproduction`, `git-platform`, `update-api-documentation`). Skills are seed files: created once per
+project and never overwritten, so they're safe to customize downstream.
+
+### 1. Create the skill file
+
+```
+templates/.claude/skills/<your-skill-slug>/SKILL.md
+```
+
+`<your-skill-slug>` must be kebab-case. Start the file with YAML frontmatter. The `description` is what
+every agent reads to decide whether to use the skill, so put the keywords and filenames a user is likely
+to say up front:
+
+```markdown
+---
+name: your-skill-slug          # kebab-case, MUST match the directory name
+description: >-
+  One or two sentences, keywords up front: what the skill does and when to use it.
+  This is what drives discovery on Claude, Codex, opencode, Gemini, Copilot, and Cursor.
+---
+# Skill: Your Skill Name
+
+## When to Use
+
+- [Concrete situation 1]
+- [Concrete situation 2]
+
+## Step by Step
+
+### 1. [Step]
+[Explanation + a real code example]
+
+## Anti-Patterns
+
+**Don't:** ...
+**Do:** ...
+```
+
+Follow the structure of the existing skills in `templates/.claude/skills/`. Keep it stack-agnostic when
+you can: show one stack as an example rather than hard-coding it.
+
+> Without `name`/`description`, agents can't discover the skill on their own; it only works if the user
+> types `/name`. The `description` is the discovery surface. (ADR-016/017/018)
+
+### 2. Wire it into the CLI
+
+Skills are emitted per selected harness: into `.claude/skills/` for Claude, and/or `.agents/skills/` for
+the others (Codex, opencode, Gemini, Copilot, Cursor), via a mirror. Add your skill in two places:
+
+1. `src/commands/init.sh`: in the skills block, add the slug to the `mkdir -p "$skills_dir/…"` line and
+   add a matching `download_if_missing` line.
+2. `src/commands/update.sh`: add a line to the `seed_templates` array so existing projects pick it up on
+   `dotcontext update --templates`:
+   ```
+   "templates/.claude/skills/<your-skill-slug>/SKILL.md:.claude/skills/<your-skill-slug>/SKILL.md"
+   ```
+
+### 3. Reference it in AGENTS.md
+
+Add a line under Additional Context in `templates/AGENTS.md` so the canonical instructions point at it:
+
+```markdown
+- Your skill topic → `.claude/skills/<your-skill-slug>/SKILL.md`
+```
+
+### 4. Build and verify
+
+```bash
+make build                 # regenerate the dotcontext binary
+bash -n dotcontext         # syntax check
+git diff --quiet dotcontext && echo "in sync"   # CI fails if it isn't
+```
+
+Commit your `src/`/`templates/` changes together with the rebuilt `dotcontext`.
+
+---
+
+## Other contributions
+
+- **A workflow command** (a new `/something`): add `templates/.claude/commands/<name>.md`, then add the
+  name to `DOTCONTEXT_COMMANDS` in `src/setup/agents.sh` and to the Claude command loop in
+  `src/commands/init.sh`. For clarifications, say "ask the user with your structured-question tool" rather
+  than naming Claude's tool, so it works on every agent. List it in the Workflows table in
+  `templates/AGENTS.md`.
+- **A new agent/harness**: add one entry to the registry in `src/setup/agents.sh` (`AGENT_IDS`,
+  `agent_name`, `agent_detect`, `agent_instructions_file`, `agent_emit_mode`), plus its hook and command
+  emission. ADR-016/017/018 describe the model.
+- **An architectural decision**: add an ADR under `.context/decisions/` in the house format (look at the
+  existing ADRs and `.context/decisions/README.md`).
+
+---
+
+## Local development
+
+```bash
+make build            # bundle src/ → ./dotcontext
+./dotcontext --help   # run your local build
+./dotcontext doctor   # exercise a command
+bash -n dotcontext    # syntax check (same as CI)
+```
+
+Keep it POSIX / Bash 3.2 compatible. macOS still ships 3.2, so no associative arrays and similar newer
+features. Test on macOS and Linux where you can.
+
+---
+
+## Pull request workflow
+
+1. Branch from `main` (`feat/…`, `fix/…`, `docs/…`, `chore/…`).
+2. Use conventional-commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`); they shape the release notes.
+   Commit the rebuilt `dotcontext` whenever you change `src/`.
+3. Open the PR against `main`. CI (`.github/workflows/ci.yml`) runs `bash -n` on every module and the
+   binary, and fails if `dotcontext` is out of sync with `src/`. CodeRabbit posts an automated review.
+4. Address the review and keep the branch green.
+
+---
+
+## Decision compliance (ADRs)
+
+Before you change how something behaves, check `.context/decisions/` for a related ADR. If your change
+conflicts with one, say so in the PR, then either comply with it or supersede it with a new version that
+references the old one. New significant decisions get their own ADR.
+
+---
+
+## How deploy / release works
+
+This trips people up, so it's worth being precise.
+
+Merging a PR does not create a release. Merging to `main` does two things:
+
+- Template changes go live immediately. `dotcontext init` and `dotcontext update --templates` read
+  templates from `main`, so a merged skill is available to anyone who re-runs them.
+- The CLI binary users download does not change. That comes from the latest release tag, so a change to
+  `src/` (init/update wiring, doctor, and so on) only reaches users after a release.
+
+A release is a separate step, automated by `.github/workflows/release.yml` (ADR-014):
+
+1. Bump `VERSION` in `src/header.sh` (not the built binary), then `make build`.
+2. Update `CHANGELOG.md`.
+3. Commit (`chore(release): vX.Y.Z`) and tag `vX.Y.Z`.
+4. `git push && git push --tags`.
+5. Pushing the `v*` tag triggers `release.yml`. It checks the binary is in sync and the tag matches
+   `VERSION`, takes the release notes from the matching `CHANGELOG.md` section (so write a good one),
+   and publishes the GitHub release. Don't run `gh release create` yourself.
+
+Maintainers can run `/release [patch|minor|major]` in Claude Code for steps 1 through 4.
+
+So for a skill, or any change that touches `src/`, to fully reach users: merge, then cut a release. A
+template-only addition is live on merge, but it's still worth releasing so the CLI's seed list, which now
+references the new file, ships in the binary too.
+
+---
+
+## Community expectations
+
+Be respectful and patient, and assume good intent. Keep feedback actionable and about the work. Everyone's
+first PR has a learning curve, so help newcomers out. Harassment or disrespectful behavior isn't tolerated.
+If the project later adds a `CODE_OF_CONDUCT.md`, it governs all project spaces; until then, this applies.
+
+### Resources
+
+- **README**: overview, install, and command reference.
+- **`.context/CONTEXT.md`**: domain and architecture.
+- **`.context/decisions/`**: the ADRs, including the multi-agent design in 016 through 018.
+
+Questions? Open an issue.
diff --git a/README.md b/README.md
index d8ceda3..54ab6e0 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 <h1 align="center">dotcontext</h1>
 
 <p align="center">
-  <em>AI context toolkit for Claude Code</em>
+  <em>AI context toolkit for coding agents — Claude Code, Codex, opencode, Gemini, Copilot & Cursor</em>
 </p>
 
 <p align="center">
@@ -13,7 +13,7 @@
   <a href="https://github.com/goca-se/dotcontext/blob/main/LICENSE"><img src="https://img.shields.io/github/license/goca-se/dotcontext" alt="License"></a>
 </p>
 
-`dotcontext` is an AI context toolkit for Claude Code. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.
+`dotcontext` is an AI context toolkit for coding agents — Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor. It provides commands, decisions, skills, and feature planning workflows that help AI assistants understand and work with your codebase.
 
 <details>
 <summary>See it in action</summary>
@@ -46,7 +46,7 @@ cd your-project
 dotcontext init
 ```
 
-This creates the context structure, downloads templates, and **automatically opens Claude Code running `/setup-context`** to analyze and populate your project's context files.
+This creates the context structure and downloads templates for the harness(es) you select. When **Claude Code** is among them, it **automatically opens Claude running `/setup-context`** to analyze and populate your project's context files; otherwise, edit `AGENTS.md` and `.context/CONTEXT.md` to describe your project.
 
 **Options:**
 
@@ -108,7 +108,7 @@ claude
 
 ## Decision Compliance
 
-The generated `CLAUDE.md` includes instructions for AI assistants to **respect architectural decisions**.
+The generated `AGENTS.md` (the canonical instructions file) includes instructions for AI assistants to **respect architectural decisions**.
 
 When you ask Claude Code to make a change that conflicts with an existing ADR, it will:
 
@@ -155,8 +155,11 @@ your-project/
     │   ├── code-review/              # 3 review agents
     │   ├── deep-context/             # 4 exploration agents
     │   └── fix-bug/                  # 5 bug-fix agents
-    ├── skills/                       # Step-by-step guides
-    │   └── bug-reproduction/         # Bug reproduction patterns
+    ├── skills/                       # Step-by-step guides (SKILL.md w/ name+description frontmatter)
+    │   ├── bug-reproduction/         # Reproduce-before-fixing patterns
+    │   ├── batch-operations/         # Safe multi-file changes
+    │   ├── git-platform/             # Detect GitHub/GitLab/… before git CLI
+    │   └── update-api-documentation/ # OpenAPI SSOT docs
     └── scripts/
         └── statusline.sh            # StatusLine: model, dir, git, ctx-usage bar, cost/time/lines
 ```
@@ -180,7 +183,7 @@ Additionally, `dotcontext init` configures:
 
 ## Multi-Agent Support
 
-dotcontext targets six harnesses — **Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor** (IDE + `cursor-agent`). `init` only writes files for the harnesses you choose, so you never get junk (no `.claude/` in a Codex-only project):
+dotcontext works with six harnesses: **Claude Code, OpenAI Codex, opencode, Gemini CLI, GitHub Copilot, and Cursor** (IDE and `cursor-agent`). `init` only writes files for the harnesses you pick, so a Codex-only project never ends up with a stray `.claude/`:
 
 ```bash
 dotcontext init                       # interactive: confirm each detected agent
@@ -192,10 +195,10 @@ What's shared vs per-harness (ADR-016, ADR-017):
 
 | Layer | Coverage |
 | --- | --- |
-| **Instructions** — canonical `AGENTS.md` | Codex/opencode/Copilot/Cursor read it natively; Claude (`CLAUDE.md`) and Gemini (`GEMINI.md`) via `@AGENTS.md` import |
-| **Skills** — shared `SKILL.md` | `.agents/skills/` (Codex/opencode/Gemini/Copilot/Cursor) mirrored to `.claude/skills/` (Claude) |
-| **Hooks** — notification on finish | native config per harness (`.codex/`, `.gemini/`, `.github/hooks/`, `.cursor/`, opencode plugin); Claude also gets the tool-failure guard |
-| **Commands** (`.claude/commands/`) | Claude-only for now — per-agent ports are planned |
+| Instructions (`AGENTS.md`) | Codex, opencode, Copilot, and Cursor read it natively; Claude (`CLAUDE.md`) and Gemini (`GEMINI.md`) import it with `@AGENTS.md` |
+| Skills (`SKILL.md`) | `.agents/skills/` for Codex/opencode/Gemini/Copilot/Cursor, mirrored to `.claude/skills/` for Claude |
+| Hooks (finish notification) | native config per harness (`.codex/`, `.gemini/`, `.github/hooks/`, `.cursor/`, opencode plugin); Claude also gets the tool-failure guard |
+| Commands / workflows | Claude `.claude/commands/`, opencode `.opencode/command/`, Copilot `.github/prompts/`; Gemini, Cursor, and Codex use the `## Workflows` section of `AGENTS.md` |
 
 `dotcontext update` migrates an existing single-file `CLAUDE.md` into the shared `AGENTS.md` (Claude keeps working via the import). Check `dotcontext --version --json` for the live capability/agent list.
 
@@ -476,7 +479,7 @@ Create a custom Claude Code slash command:
 
 ## Notifications
 
-`dotcontext init` automatically configures native OS notifications for Claude Code in the project's `.claude/settings.json`:
+`dotcontext init` automatically configures native OS notifications for each selected harness in its own hook config (`.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, `.github/hooks/`, `.cursor/hooks.json`, or an opencode plugin). For Claude:
 
 | Event | When | Sound (macOS) |
 |-------|------|---------------|
diff --git a/dotcontext b/dotcontext
index 1508e4d..dbeedd0 100755
--- a/dotcontext
+++ b/dotcontext
@@ -1,7 +1,7 @@
 #!/bin/bash
 set -e
 
-VERSION="0.16.0"
+VERSION="0.17.0"
 REPO="goca-se/dotcontext"
 BRANCH="main"
 BASE_URL="https://raw.githubusercontent.com/${REPO}/${BRANCH}"
@@ -650,6 +650,37 @@ JS
   done
   [ "$done_any" = true ] || true
 }
+
+# ── Per-agent commands (hybrid, ADR-018) ──────────────────────────────────────
+# The canonical workflow prompts ship in templates/.claude/commands/. Claude gets
+# them in .claude/commands/ (handled in init). opencode and Copilot get native
+# command/prompt files here; Gemini/Cursor/Codex rely on the "## Workflows"
+# section emitted into AGENTS.md. Create-only — never clobbers existing files.
+DOTCONTEXT_COMMANDS="setup-context generate-prp execute-prp code-review commit create-pr pr-comment deep-context fix-bug add-decision add-skill add-command"
+
+emit_agent_commands() {
+  local selected="$1" id name
+  for id in $selected; do
+    case "$id" in
+      opencode)
+        mkdir -p ".opencode/command"
+        for name in $DOTCONTEXT_COMMANDS; do
+          [ -f ".opencode/command/${name}.md" ] || \
+            download "${BASE_URL}/templates/.claude/commands/${name}.md" ".opencode/command/${name}.md"
+        done
+        print_gray "  commands: .opencode/command/ (opencode)"
+        ;;
+      copilot)
+        mkdir -p ".github/prompts"
+        for name in $DOTCONTEXT_COMMANDS; do
+          [ -f ".github/prompts/${name}.prompt.md" ] || \
+            download "${BASE_URL}/templates/.claude/commands/${name}.md" ".github/prompts/${name}.prompt.md"
+        done
+        print_gray "  commands: .github/prompts/ (copilot)"
+        ;;
+    esac
+  done
+}
 # ── Command: init ─────────────────────────────────────────────────────────────
 
 cmd_init() {
@@ -788,6 +819,9 @@ cmd_init() {
 
   touch ".context/prp/generated/.keep" ".context/discoveries/.keep" ".context/bugs/.keep"
 
+  # ── Commands per selected harness (opencode/Copilot native; others via AGENTS.md Workflows) ──
+  emit_agent_commands "$selected" 2>/dev/null || true
+
   # ── Hooks per selected harness (notifications; Claude also gets the failure guard) ──
   setup_agent_hooks "$selected" 2>/dev/null || true
 
@@ -1311,7 +1345,7 @@ cmd_update_templates() {
     else
       echo ""
       print_blue "MCP Servers"
-      print_gray "Configure Model Context Protocol servers for Claude Code"
+      print_gray "Configure Model Context Protocol servers for your agents"
       echo ""
 
       if confirm_yes "  Add Context7? (up-to-date library docs for LLMs)"; then
@@ -1358,13 +1392,14 @@ cmd_doctor() {
     check_fail "Git repository — not a git repo"
   fi
 
-  # Check: Claude CLI installed
+  # Check: Claude CLI installed (informational — dotcontext is multi-agent, so a
+  # missing Claude CLI is not a failure for Codex/opencode/Gemini/etc. projects)
   if command -v claude &>/dev/null; then
     local claude_ver
     claude_ver=$(claude --version 2>/dev/null || echo "unknown")
     check_pass "Claude CLI installed ($claude_ver)"
   else
-    check_fail "Claude CLI — not installed"
+    check_warn "Claude CLI — not installed (fine if you use another agent)"
   fi
 
   # Check: .context/ directory
@@ -1410,15 +1445,21 @@ cmd_doctor() {
     check_warn ".context/decisions/ — no ADRs found"
   fi
 
-  # Check: .claude/commands/ present
+  # Check: workflow commands present (per-harness — a non-Claude project has no
+  # .claude/, getting its workflows from .opencode/command, .github/prompts, or
+  # the AGENTS.md "Workflows" section instead)
   local cmd_count=0
   if [ -d ".claude/commands" ]; then
     cmd_count=$(find .claude/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
   fi
   if [ "$cmd_count" -gt 0 ]; then
     check_pass ".claude/commands/ — $cmd_count command(s)"
+  elif [ -d ".opencode/command" ] || [ -d ".github/prompts" ]; then
+    check_pass "Commands present (non-Claude harness)"
+  elif grep -q "## Workflows" "AGENTS.md" 2>/dev/null; then
+    check_pass "Workflows documented in AGENTS.md"
   else
-    check_fail ".claude/commands/ — no commands found"
+    check_fail "No commands found (run dotcontext init)"
   fi
 
   # Check: .claude/agents/ present
@@ -1526,7 +1567,7 @@ cmd_help() {
   fi
 
   echo ""
-  printf "  ${BOLD}dotcontext${NC} ${GRAY}— AI context toolkit for Claude Code${NC}\n"
+  printf "  ${BOLD}dotcontext${NC} ${GRAY}— AI context toolkit for coding agents${NC}\n"
   echo ""
 
   # Usage
@@ -1536,7 +1577,7 @@ cmd_help() {
 
   # Commands
   printf "  ${BLUE}${BOLD}Commands${NC}\n"
-  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "init"       "Initialize .context structure + open Claude Code"
+  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "init"       "Initialize context for your agent(s)"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "update"     "Update CLI and/or templates"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "doctor"     "Check project setup health"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "completion" "Generate shell tab completions"
@@ -1565,7 +1606,7 @@ cmd_help() {
   echo ""
 
   # Claude Code Commands
-  printf "  ${BLUE}${BOLD}Claude Code Commands${NC} ${GRAY}(after init)${NC}\n"
+  printf "  ${BLUE}${BOLD}Workflows${NC} ${GRAY}(after init — slash commands on Claude/opencode/Copilot; AGENTS.md elsewhere)${NC}\n"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/setup-context"  "Analyze codebase and populate context"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/generate-prp"   "Plan a new feature"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/execute-prp"    "Implement a planned feature"
@@ -1632,6 +1673,7 @@ cmd_version() {
     "statusline": true,
     "hooks": true,
     "skills": true,
+    "commands": true,
     "multiagent": true,
     "agents": $agents_json
   }
@@ -1649,6 +1691,7 @@ JSON
     printf "  %-16s %s\n" "statusline"      "yes"
     printf "  %-16s %s\n" "hooks"           "yes"
     printf "  %-16s %s\n" "skills"          "yes"
+    printf "  %-16s %s\n" "commands"        "yes"
     printf "  %-16s %s\n" "multiagent"      "yes"
     printf "  %-16s %s\n" "agents"          "$agents_list"
   fi
diff --git a/src/commands/doctor.sh b/src/commands/doctor.sh
index af2f1e4..ca56344 100644
--- a/src/commands/doctor.sh
+++ b/src/commands/doctor.sh
@@ -30,13 +30,14 @@ cmd_doctor() {
     check_fail "Git repository — not a git repo"
   fi
 
-  # Check: Claude CLI installed
+  # Check: Claude CLI installed (informational — dotcontext is multi-agent, so a
+  # missing Claude CLI is not a failure for Codex/opencode/Gemini/etc. projects)
   if command -v claude &>/dev/null; then
     local claude_ver
     claude_ver=$(claude --version 2>/dev/null || echo "unknown")
     check_pass "Claude CLI installed ($claude_ver)"
   else
-    check_fail "Claude CLI — not installed"
+    check_warn "Claude CLI — not installed (fine if you use another agent)"
   fi
 
   # Check: .context/ directory
@@ -82,15 +83,21 @@ cmd_doctor() {
     check_warn ".context/decisions/ — no ADRs found"
   fi
 
-  # Check: .claude/commands/ present
+  # Check: workflow commands present (per-harness — a non-Claude project has no
+  # .claude/, getting its workflows from .opencode/command, .github/prompts, or
+  # the AGENTS.md "Workflows" section instead)
   local cmd_count=0
   if [ -d ".claude/commands" ]; then
     cmd_count=$(find .claude/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
   fi
   if [ "$cmd_count" -gt 0 ]; then
     check_pass ".claude/commands/ — $cmd_count command(s)"
+  elif [ -d ".opencode/command" ] || [ -d ".github/prompts" ]; then
+    check_pass "Commands present (non-Claude harness)"
+  elif grep -q "## Workflows" "AGENTS.md" 2>/dev/null; then
+    check_pass "Workflows documented in AGENTS.md"
   else
-    check_fail ".claude/commands/ — no commands found"
+    check_fail "No commands found (run dotcontext init)"
   fi
 
   # Check: .claude/agents/ present
diff --git a/src/commands/help.sh b/src/commands/help.sh
index ef0eef6..9353a8b 100644
--- a/src/commands/help.sh
+++ b/src/commands/help.sh
@@ -13,7 +13,7 @@ cmd_help() {
   fi
 
   echo ""
-  printf "  ${BOLD}dotcontext${NC} ${GRAY}— AI context toolkit for Claude Code${NC}\n"
+  printf "  ${BOLD}dotcontext${NC} ${GRAY}— AI context toolkit for coding agents${NC}\n"
   echo ""
 
   # Usage
@@ -23,7 +23,7 @@ cmd_help() {
 
   # Commands
   printf "  ${BLUE}${BOLD}Commands${NC}\n"
-  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "init"       "Initialize .context structure + open Claude Code"
+  printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "init"       "Initialize context for your agent(s)"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "update"     "Update CLI and/or templates"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "doctor"     "Check project setup health"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "completion" "Generate shell tab completions"
@@ -52,7 +52,7 @@ cmd_help() {
   echo ""
 
   # Claude Code Commands
-  printf "  ${BLUE}${BOLD}Claude Code Commands${NC} ${GRAY}(after init)${NC}\n"
+  printf "  ${BLUE}${BOLD}Workflows${NC} ${GRAY}(after init — slash commands on Claude/opencode/Copilot; AGENTS.md elsewhere)${NC}\n"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/setup-context"  "Analyze codebase and populate context"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/generate-prp"   "Plan a new feature"
   printf "    ${CYAN}%-${cmd_col}s${NC}%s\n" "/execute-prp"    "Implement a planned feature"
@@ -119,6 +119,7 @@ cmd_version() {
     "statusline": true,
     "hooks": true,
     "skills": true,
+    "commands": true,
     "multiagent": true,
     "agents": $agents_json
   }
@@ -136,6 +137,7 @@ JSON
     printf "  %-16s %s\n" "statusline"      "yes"
     printf "  %-16s %s\n" "hooks"           "yes"
     printf "  %-16s %s\n" "skills"          "yes"
+    printf "  %-16s %s\n" "commands"        "yes"
     printf "  %-16s %s\n" "multiagent"      "yes"
     printf "  %-16s %s\n" "agents"          "$agents_list"
   fi
diff --git a/src/commands/init.sh b/src/commands/init.sh
index a3c43c5..f3f12e3 100644
--- a/src/commands/init.sh
+++ b/src/commands/init.sh
@@ -136,6 +136,9 @@ cmd_init() {
 
   touch ".context/prp/generated/.keep" ".context/discoveries/.keep" ".context/bugs/.keep"
 
+  # ── Commands per selected harness (opencode/Copilot native; others via AGENTS.md Workflows) ──
+  emit_agent_commands "$selected" 2>/dev/null || true
+
   # ── Hooks per selected harness (notifications; Claude also gets the failure guard) ──
   setup_agent_hooks "$selected" 2>/dev/null || true
 
diff --git a/src/commands/update.sh b/src/commands/update.sh
index 3d88d9b..55497fe 100644
--- a/src/commands/update.sh
+++ b/src/commands/update.sh
@@ -455,7 +455,7 @@ cmd_update_templates() {
     else
       echo ""
       print_blue "MCP Servers"
-      print_gray "Configure Model Context Protocol servers for Claude Code"
+      print_gray "Configure Model Context Protocol servers for your agents"
       echo ""
 
       if confirm_yes "  Add Context7? (up-to-date library docs for LLMs)"; then
diff --git a/src/header.sh b/src/header.sh
index f8fcfc0..a14a616 100644
--- a/src/header.sh
+++ b/src/header.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 set -e
 
-VERSION="0.16.0"
+VERSION="0.17.0"
 REPO="goca-se/dotcontext"
 BRANCH="main"
 BASE_URL="https://raw.githubusercontent.com/${REPO}/${BRANCH}"
diff --git a/src/setup/agents.sh b/src/setup/agents.sh
index 25a76b7..dc09c72 100644
--- a/src/setup/agents.sh
+++ b/src/setup/agents.sh
@@ -263,3 +263,34 @@ JS
   done
   [ "$done_any" = true ] || true
 }
+
+# ── Per-agent commands (hybrid, ADR-018) ──────────────────────────────────────
+# The canonical workflow prompts ship in templates/.claude/commands/. Claude gets
+# them in .claude/commands/ (handled in init). opencode and Copilot get native
+# command/prompt files here; Gemini/Cursor/Codex rely on the "## Workflows"
+# section emitted into AGENTS.md. Create-only — never clobbers existing files.
+DOTCONTEXT_COMMANDS="setup-context generate-prp execute-prp code-review commit create-pr pr-comment deep-context fix-bug add-decision add-skill add-command"
+
+emit_agent_commands() {
+  local selected="$1" id name
+  for id in $selected; do
+    case "$id" in
+      opencode)
+        mkdir -p ".opencode/command"
+        for name in $DOTCONTEXT_COMMANDS; do
+          [ -f ".opencode/command/${name}.md" ] || \
+            download "${BASE_URL}/templates/.claude/commands/${name}.md" ".opencode/command/${name}.md"
+        done
+        print_gray "  commands: .opencode/command/ (opencode)"
+        ;;
+      copilot)
+        mkdir -p ".github/prompts"
+        for name in $DOTCONTEXT_COMMANDS; do
+          [ -f ".github/prompts/${name}.prompt.md" ] || \
+            download "${BASE_URL}/templates/.claude/commands/${name}.md" ".github/prompts/${name}.prompt.md"
+        done
+        print_gray "  commands: .github/prompts/ (copilot)"
+        ;;
+    esac
+  done
+}
diff --git a/templates/.claude/commands/add-skill.md b/templates/.claude/commands/add-skill.md
index eff7eb8..2d58936 100644
--- a/templates/.claude/commands/add-skill.md
+++ b/templates/.claude/commands/add-skill.md
@@ -31,11 +31,25 @@ Search the codebase to find:
 mkdir -p .claude/skills/[skill-slug]
 ```
 
+**Multi-agent note:** if `.agents/skills/` exists as a real directory (not a symlink to
+`.claude/skills/`), create the skill in **both** so non-Claude agents (Codex, Gemini, …) discover it
+too. If `.agents/skills/` is a symlink to `.claude/skills/`, writing to `.claude/skills/` already
+covers both.
+
 ### 5. Populate SKILL.md
 
-Create `.claude/skills/[skill-slug]/SKILL.md`:
+Create `.claude/skills/[skill-slug]/SKILL.md`. **Start with YAML frontmatter** — the `description` is
+what agents (Claude, Codex, opencode, Gemini, Copilot, Cursor) use to **auto-discover** the skill, so
+front-load the literal keywords/filenames the user is likely to say. `name` must be the kebab-case slug
+and match the directory name.
 
 ```markdown
+---
+name: [skill-slug]
+description: >-
+  [One or two sentences, keyword-front-loaded: what the skill does and when to use it —
+  the situations from "When to Use". This drives auto-discovery.]
+---
 # Skill: [Name]
 
 ## When to Use
diff --git a/templates/.claude/commands/code-review.md b/templates/.claude/commands/code-review.md
index 15016db..b36822b 100644
--- a/templates/.claude/commands/code-review.md
+++ b/templates/.claude/commands/code-review.md
@@ -42,12 +42,12 @@ Collect all relevant context before launching agents:
 
 1. **Get the PR/MR diff** using the detected platform CLI (e.g., `gh pr diff`, `glab mr diff`)
 
-2. **Find all CLAUDE.md files** (project guidelines):
+2. **Find all AGENTS.md files** (project guidelines):
 ```bash
-find . -name "CLAUDE.md" -o -name "*.claude.md" | head -20
+find . -name "AGENTS.md" -o -name "*.claude.md" | head -20
 ```
 
-3. **Read CLAUDE.md files** found above to understand project rules
+3. **Read AGENTS.md files** found above to understand project rules
 
 4. **Get PR/MR metadata** using the detected platform CLI (e.g., `gh pr view --json title,body,files`, `glab mr view`)
 
@@ -55,22 +55,22 @@ find . -name "CLAUDE.md" -o -name "*.claude.md" | head -20
 
 Use the **Task tool** to launch 4 agents in parallel. Each agent receives:
 - The full PR diff
-- All CLAUDE.md content found
+- All AGENTS.md content found
 - Their specific mission
 
 **IMPORTANT:** Launch all 4 agents in a SINGLE message with multiple Task tool calls.
 
-**Agent prompt files** — Read these files and use as agent prompts, substituting `{diff}` with the PR diff and `{claude_md_content}` with the CLAUDE.md content:
+**Agent prompt files** — Read these files and use as agent prompts, substituting `{diff}` with the PR diff and `{claude_md_content}` with the AGENTS.md content:
 
 ---
 
-#### Agent 1: CLAUDE.md Compliance (Primary)
+#### Agent 1: AGENTS.md Compliance (Primary)
 
 Read `.claude/agents/code-review/compliance-checker.md` for the agent prompt.
 
 ---
 
-#### Agent 2: CLAUDE.md Compliance (Secondary)
+#### Agent 2: AGENTS.md Compliance (Secondary)
 
 Same prompt as Agent 1 (read `.claude/agents/code-review/compliance-checker.md`). Redundancy ensures we catch compliance issues.
 
@@ -99,7 +99,7 @@ After all agents complete, collect their findings and score each issue for confi
 **Scoring questions to ask yourself:**
 1. Is there concrete evidence this is a real issue?
 2. Could this be intentional or handled elsewhere?
-3. Does the CLAUDE.md explicitly mention this rule?
+3. Does the AGENTS.md explicitly mention this rule?
 4. Is this introduced by the PR or pre-existing?
 
 ### Step 5: Filter and Deduplicate
@@ -212,7 +212,7 @@ Do NOT report these (they inflate noise):
 - Pre-existing issues not introduced by this PR
 - Issues that linters/formatters will catch
 - Code that "looks wrong" but is intentional (check git blame)
-- General style preferences not in CLAUDE.md
+- General style preferences not in AGENTS.md
 - Hypothetical future issues
 - Lines with `// eslint-disable` or similar ignore comments
 - Auto-generated code
diff --git a/templates/.claude/commands/deep-context.md b/templates/.claude/commands/deep-context.md
index ed341bc..df7365e 100644
--- a/templates/.claude/commands/deep-context.md
+++ b/templates/.claude/commands/deep-context.md
@@ -69,7 +69,7 @@ If `--cache` flag is present:
 
 Read the following files to build context for agents:
 - `.context/CONTEXT.md` (full file)
-- `CLAUDE.md` (full file)
+- `AGENTS.md` (full file — canonical project instructions)
 - All files in `.context/decisions/` (read each ADR)
 
 ### Step 6: Launch Exploration Agents
diff --git a/templates/.claude/commands/execute-prp.md b/templates/.claude/commands/execute-prp.md
index 3d423df..5dd5b20 100644
--- a/templates/.claude/commands/execute-prp.md
+++ b/templates/.claude/commands/execute-prp.md
@@ -18,7 +18,7 @@ Execute the PRP specified in $ARGUMENTS.
 
 - Follow patterns in `.claude/skills/`
 - Respect decisions in `.context/decisions/`
-- Check `CLAUDE.md` for critical rules
+- Check `AGENTS.md` for critical rules
 
 ## Parallel Phase Dispatch
 
@@ -188,7 +188,7 @@ Change `**Status:** Draft` to `**Status:** In Progress` when starting, and `**St
 
 ## When Finished
 
-Run the project's test/lint commands as defined in `CLAUDE.md`.
+Run the project's test/lint commands as defined in `AGENTS.md`.
 
 ## If Something Fails
 
diff --git a/templates/.claude/commands/fix-bug.md b/templates/.claude/commands/fix-bug.md
index 1969014..a251ef6 100644
--- a/templates/.claude/commands/fix-bug.md
+++ b/templates/.claude/commands/fix-bug.md
@@ -37,18 +37,18 @@ Combine all sources into a single `BUG_CONTEXT` block. Focus on **root causes, n
 ### Step 3: Read Project Context
 
 Read these files to understand the project:
-- `CLAUDE.md` — project rules, stack, test commands
+- `AGENTS.md` — project rules, stack, test commands
 - `.context/CONTEXT.md` — domain context
 - `.claude/skills/bug-reproduction/SKILL.md` — bug reproduction patterns (if exists)
 - `.context/bugs/` — check for previous similar bugs (patterns may repeat)
 
-From `CLAUDE.md`, identify:
+From `AGENTS.md`, identify:
 - **Test framework** and **test command** (e.g., `npm test`, `pytest`, `go test`)
 - **Lint command** if available
 - **Stack** information (language, framework)
 
 If no test framework can be identified, warn the user:
-> "No test framework detected in CLAUDE.md. The /fix-bug command requires a test framework to validate fixes. Please update CLAUDE.md with your test commands, or provide the test command now."
+> "No test framework detected in AGENTS.md. The /fix-bug command requires a test framework to validate fixes. Please update AGENTS.md with your test commands, or provide the test command now."
 
 Then **use AskUserQuestion** to get the test command, or allow the user to proceed without tests.
 
diff --git a/templates/.claude/commands/setup-context.md b/templates/.claude/commands/setup-context.md
index b92e658..ce30cd3 100644
--- a/templates/.claude/commands/setup-context.md
+++ b/templates/.claude/commands/setup-context.md
@@ -24,9 +24,9 @@ First, understand:
 - What are the main entry points?
 - **Does it use Docker?** Check for `docker-compose.yml`, `Dockerfile`, or similar. If yes, commands should be run via Docker (e.g., `docker compose exec <service> <command>`).
 
-### 2. Fill CLAUDE.md
+### 2. Fill AGENTS.md
 
-Update the root `CLAUDE.md` with:
+`AGENTS.md` is the **canonical** project-instructions file (read by Codex, opencode, Copilot, Cursor; Claude and Gemini import it via `CLAUDE.md`/`GEMINI.md` stubs). Edit `AGENTS.md` — **never** the import stubs. Update it with:
 
 - **Project name and description**: Clear one-liner explaining what this is
 - **Stack**: Language version, framework, database, key dependencies
@@ -119,7 +119,7 @@ For each, create a skill folder with SKILL.md following the template.
 If `.claude/skills/bug-reproduction/SKILL.md` exists (created by `dotcontext init`), fill in the project-specific sections:
 
 - **Test Framework**: Detect from `package.json` (jest, vitest, mocha), `Gemfile` (rspec, minitest), `pyproject.toml`/`setup.py` (pytest, unittest), `go.mod` (go test), etc.
-- **Run command**: The actual command to run tests (from `CLAUDE.md` or project config)
+- **Run command**: The actual command to run tests (from `AGENTS.md` or project config)
 - **Test directory**: Where tests live in this project
 - **E2E Framework**: Detect Cypress, Playwright, Selenium if present
 - **Examples**: Find 1-2 real test examples from the codebase that demonstrate the project's test patterns
@@ -206,7 +206,7 @@ After completing each file, summarize what you created:
 ✅ Context setup complete!
 
 Created/Updated:
-- CLAUDE.md - [brief description of what was added]
+- AGENTS.md - [brief description of what was added]
 - .context/CONTEXT.md - [brief description]
 - .context/decisions/001-xxx.md - [title]
 - .context/decisions/002-xxx.md - [title]
diff --git a/templates/.claude/skills/batch-operations/SKILL.md b/templates/.claude/skills/batch-operations/SKILL.md
index f9842d0..7116dcc 100644
--- a/templates/.claude/skills/batch-operations/SKILL.md
+++ b/templates/.claude/skills/batch-operations/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: batch-operations
+description: >-
+  Apply a change safely across many files — refactors touching more than 5 files,
+  library or API migrations, project-wide renames of symbols/imports/paths, or
+  adding boilerplate to many files. Use when "do it all at once" risks context
+  overflow or silent failures.
+---
 # Skill: Batch Operations
 
 ## When to Use
diff --git a/templates/.claude/skills/bug-reproduction/SKILL.md b/templates/.claude/skills/bug-reproduction/SKILL.md
index b100b06..1be0782 100644
--- a/templates/.claude/skills/bug-reproduction/SKILL.md
+++ b/templates/.claude/skills/bug-reproduction/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: bug-reproduction
+description: >-
+  Reproduce a bug with a failing test before fixing it. Use when investigating a
+  bug, working a bug report or issue, or before attempting any fix — always
+  reproduce first. Pairs with the /fix-bug workflow.
+---
 # Skill: Bug Reproduction
 
 ## When to Use
diff --git a/templates/.claude/skills/git-platform/SKILL.md b/templates/.claude/skills/git-platform/SKILL.md
index b226998..4520a43 100644
--- a/templates/.claude/skills/git-platform/SKILL.md
+++ b/templates/.claude/skills/git-platform/SKILL.md
@@ -1,3 +1,9 @@
+---
+name: git-platform
+description: >-
+  Detect the git hosting platform (GitHub, GitLab, Bitbucket, …) before running any
+  hosting CLI — creating PRs, viewing issues, commenting on PRs. Never assume GitHub.
+---
 # Skill: Git Platform Detection
 
 ## When to Use
diff --git a/templates/.claude/skills/update-api-documentation/SKILL.md b/templates/.claude/skills/update-api-documentation/SKILL.md
index 0ff8072..0eb683d 100644
--- a/templates/.claude/skills/update-api-documentation/SKILL.md
+++ b/templates/.claude/skills/update-api-documentation/SKILL.md
@@ -1,3 +1,11 @@
+---
+name: update-api-documentation
+description: >-
+  Keep external REST API and webhook contracts documented from a single OpenAPI
+  source of truth (docs/openapi.yml), with generated Redoc HTML, validate/build
+  tasks, and a CI step. Use on any change to a public route, request/response
+  shape, auth scheme, or error contract.
+---
 # Skill: Update API Documentation (OpenAPI SSOT)
 
 Keep external API contracts documented from a **single source of truth** (`docs/openapi.yml`),
diff --git a/templates/AGENTS.md b/templates/AGENTS.md
index a225b98..c65e400 100644
--- a/templates/AGENTS.md
+++ b/templates/AGENTS.md
@@ -90,6 +90,33 @@ Remove:
 
 ---
 
+## Workflows
+
+These are explicit, user-invoked workflows. On **Claude Code** they are slash commands in
+`.claude/commands/`; on **opencode** they are commands in `.opencode/commands/`; on **GitHub Copilot**
+they are prompt files in `.github/prompts/`. On agents without per-repo command files (Gemini, Cursor,
+Codex), the user describes the task and you execute the matching workflow below. Run them only when the
+user asks — never auto-fire a workflow that commits, opens a PR, or writes files.
+
+| Workflow | Purpose |
+| --- | --- |
+| `setup-context` | Analyze the codebase and populate `.context/` |
+| `generate-prp` | Plan a feature (clarity assessment + clarifying questions) |
+| `execute-prp` | Implement a planned feature (PRP) |
+| `code-review` | Multi-agent review of the current changes |
+| `commit` | Smart, style-aware commit message |
+| `create-pr` | Create a PR with an auto-generated description |
+| `pr-comment` | Add a comment to an existing PR |
+| `deep-context` | Structured 4-step codebase exploration |
+| `fix-bug` | Test-driven bug fixing (reproduce → fix → verify) |
+| `add-decision` | Add an architectural decision record (ADR) |
+| `add-skill` | Add a skill guide |
+| `add-command` | Create a custom command |
+
+When a workflow needs to clarify requirements, **ask the user with your structured-question tool**
+(`AskUserQuestion` / `ask_user` / `question` / `cursor/ask_question` / `request_user_input`) rather than
+assuming — present concrete options. Do not degrade to silent assumptions.
+
 ## Additional Context
 
 - Domain and architecture → `.context/CONTEXT.md`