diff --git a/tools/coreci-executor/ONBOARDING.md b/tools/coreci-executor/ONBOARDING.md
new file mode 100644
index 0000000..5455c5e
--- /dev/null
+++ b/tools/coreci-executor/ONBOARDING.md
@@ -0,0 +1,50 @@
+# coreci-executor — Agent Onboarding Checklist
+
+> Use this checklist when adding a new agent (`coreci-<role>`) or when
+> an existing agent loses its tool binding mid-session.
+
+## Pre-flight (one-time, per agent)
+
+- [ ] Gitea user `coreci-<role>` exists (admin creates via the `coreci` org).
+- [ ] KB file set in the agent's credential KB:
+  - `git.coreci.dev.txt` → username `coreci-<role>`
+  - `executor.coreci.dev.txt` → `EXECUTOR_API_KEY=<shared key from .env>`
+  - one `<cap>.txt` per scoped capability (e.g. `proxmox.txt`, `openwebui.txt`)
+- [ ] Allowlist entry exists in `allowlist.yaml` with
+  `auto_run_targets: [coreci-<role>/home]` (PR to `executor-config`,
+  CEO approval).
+- [ ] Home repo `coreci-<role>/home` exists and is initialized
+  (`README.md`, `.gitkeep`).
+
+## Per-bind (every re-bind, including recovery from tool loss)
+
+- [ ] Fetch `coreci/executor-config/tools/coreci-executor/SPEC.md` and
+      note version.
+- [ ] Instantiate the `coreci-executor` tool locally bound to the SPEC.
+- [ ] Handshake: `GET /health` → `200`.
+- [ ] Smoke-test pack: 1-line `echo HELLO_FROM_<role>_<utc_ts>` →
+      receive `request_id` → record in `ONBOARDING.md`.
+- [ ] Append row to `ONBOARDING.md`:
+
+      | utc_ts | SPEC version | request_id | result |
+      |---|---|---|---|
+
+## Failure recovery
+
+- Tool missing in palette → re-fetch SPEC, re-instantiate, re-handshake.
+- `/submit_request` returns `NEEDS_APPROVAL` for a target that should
+  be `AUTO_RUN` → check `allowlist.yaml`; entry may be missing or
+  agent name may not match (see SPEC §4 naming convention).
+- All smoke-test failures → escalate to CEO; do not run real work
+  before `coreci-executor` is verified bound.
+
+## References
+
+- `coreci/executor-config/tools/coreci-executor/SPEC.md` (canonical
+  tool definition; v0.1 as of 2026-09-26)
+- `coreci/company/standards/communications.md` §"Mailbox" (mailbox
+  convention; per-home outbox + inbox)
+- `coreci/executor-config/allowlist.yaml` (AUTO_RUN classification
+  per agent; v2 naming convention; v4 will add `read_targets` once
+  the executor parser change lands — see D6 in CAIRO's task brief)
+