diff --git a/AGENTS.md b/AGENTS.md
index 8601e63..c935c08 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -375,6 +375,20 @@ git add packages/my-tool README.md
 bd close <id>         # Mark task as complete
 ```
 
+## Agent skills
+
+### Issue tracker
+
+Issues live in the beads database (`.beads/`, driven by the `bd` CLI), synced through `git push`. The Gitea remote is not the issue tracker. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical triage roles keep their default names, applied as `bd` labels. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout: `CONTEXT.md` plus `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
 <!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
 ## Beads Issue Tracker
 
diff --git a/docs/agents/domain.md b/docs/agents/domain.md
new file mode 100644
index 0000000..c53864c
--- /dev/null
+++ b/docs/agents/domain.md
@@ -0,0 +1,55 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-two-overlay-strategies.md
+│   └── 0002-package-discovery-via-git-index.md
+├── packages/
+├── overlays/
+└── modules/
+```
+
+This repo uses the single-context layout. There is no `CONTEXT-MAP.md` and no per-directory `CONTEXT.md` files; the whole overlay is one domain.
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
new file mode 100644
index 0000000..32c8a4b
--- /dev/null
+++ b/docs/agents/issue-tracker.md
@@ -0,0 +1,63 @@
+# Issue tracker: bd (beads)
+
+Issues and specs for this repo live in the beads database at `.beads/`. The source of truth is `.beads/issues.jsonl`, managed through the `bd` CLI (v1.3.0). beads state is versioned in the repo and synced with `git push`; there is no separate Dolt remote.
+
+The forge remote (`git.millerson.name`, self-hosted Gitea) is not the issue tracker. Do not open Gitea, GitHub, or GitLab issues for work in this repo.
+
+## Core commands
+
+```bash
+bd ready                 # open issues with no active blockers
+bd show <id>             # full issue detail
+bd list                  # list issues
+bd search "<text>"       # text search
+bd create "title" -d "description" -p 2 -l label1,label2
+bd q "quick capture"     # create and print only the id
+bd update <id> --claim   # claim before starting work
+bd close <id> --reason "..."
+bd reopen <id>
+bd comment <id> "..."    # conversation history
+bd note <id> "..."       # append a note
+bd tag <id> <label>      # shorthand for: bd update <id> --add-label <label>
+bd label add <id> <label>
+bd label remove <id> <label>
+bd status                # database overview
+```
+
+Issue ids look like `nix-overlay-4g1`. New work must be claimed with `bd update <id> --claim` before it starts.
+
+## When a skill says "publish to the issue tracker"
+
+Run `bd create`. Use one issue per ticket. Put the full body in `--description` (markdown is fine). Add labels per `triage-labels.md`. For a multi-part spec, create a parent issue and link children with `--deps`.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `bd show <id>` and read the description plus comments (`bd show <id> --include-comments --json` when full comment bodies are needed). The user normally passes the issue id directly.
+
+## Dependencies
+
+`bd create --deps 'blocked-by:nix-overlay-4g1,discovered-from:nix-overlay-2a3'`
+
+Bare ids, `depends-on:` and `blocked-by:` all make the new issue depend on the target. `blocks:` reverses the direction. `bd link`, `bd dep`, and `bd children` manage the graph after creation. `bd ready` already excludes anything with an unresolved blocker, so a ticket is unblocked when every issue that blocks it is closed.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The map is a parent bead; the children are its sub-issues.
+
+- **Map**: a bead created for the effort. Its description holds the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: a bead linked to the map with `--deps depends-on:<map-id>`. The question goes in the description. Record the ticket type as a label (`research`, `prototype`, `grilling`, `task`).
+- **Blocking**: a `blocked-by:<id>` dependency on the blocking bead.
+- **Frontier**: `bd ready` output, restricted to children of the map (`bd children <map-id> --ready` or filter `bd ready` by parent). Lowest priority number, then oldest, wins.
+- **Claim**: `bd update <id> --claim` before any work starts.
+- **Resolve**: append the answer with `bd note <id> "..."` or `bd comment`, then `bd close <id> --reason "<answer gist>"`, then add a context pointer (gist plus issue id) to the map's Decisions-so-far with `bd note <map-id> "..."`.
+
+## Session end
+
+Work is not complete until pushed. The project workflow requires:
+
+```bash
+git pull --rebase
+bd dolt push    # prints "No remote is configured - skipping." here; expected, not a failure
+git push
+git status      # must show up to date with origin
+```
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
new file mode 100644
index 0000000..927024a
--- /dev/null
+++ b/docs/agents/triage-labels.md
@@ -0,0 +1,30 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (for example "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.
+
+## Applying labels with bd
+
+Labels are bd labels, not forge labels:
+
+```bash
+bd tag <issue-id> ready-for-agent
+bd label add <issue-id> needs-triage
+bd label remove <issue-id> needs-triage
+bd label list <issue-id>
+```
+
+On creation: `bd create "title" -l ready-for-agent`.
+
+A ticket has at most one triage role label. When a ticket moves to a new role, remove the old label and add the new one in the same step rather than stacking role labels.