diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..23b237a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,75 @@
+# AGENTS.md — open-sesame
+
+Guidance for **AI agents** (Codex, Claude Code, and any Coven familiar) opening
+pull requests against this repo.
+
+> **Read first:** [`README.md`](README.md) for what this repo is and how to
+> build it.
+
+---
+
+## What this repo is (one line)
+
+OpenSesame is a **SwiftUI macOS application shell template** for OpenCoven
+projects — a generic shell that pins web apps into a native window.
+
+## Branch & PR workflow (all agents)
+
+- **Never push to `main`.** Every change lands via a PR with green CI. Branch
+  from current `origin/main`.
+- **Fresh branch per task**; use a worktree if multiple sessions may touch this
+  repo:
+  ```sh
+  git fetch origin main
+  git worktree add -b <branch> /tmp/sesame-<branch> origin/main
+  ```
+- Keep the diff scoped to one concern; conventional-commit subjects (`feat:`,
+  `fix:`, `docs:`, `chore:`, `refactor:`).
+- After merge: delete the remote branch, remove your local worktree/branch.
+
+## Checks — run locally before opening the PR
+
+CI (`.github/workflows/ci.yml`) runs the Swift build and tests. Run them first:
+
+```sh
+swift package resolve
+swift build
+swift test --parallel
+```
+
+Fix failures rather than skipping them.
+
+## Repo-specific invariants (don't break these)
+
+- This is a **template/shell**, not an app-specific fork. Keep it generic and
+  reusable; don't bake one project's branding or behavior into the shell.
+- Keep the macOS app entitlements and web-pinning surface minimal and
+  intentional; don't broaden capabilities without a clear reason.
+
+## Attribution — credit contributors correctly
+
+When you re-land or build on someone else's work (a fork PR, an issue author's
+proposal, a co-author), **credit the human contributor with a working
+GitHub-linked trailer** so they appear in the contributors graph:
+
+```
+Co-authored-by: Full Name <ID+username@users.noreply.github.com>
+```
+
+- Use the **numeric-id no-reply form**. Get the id with `gh api users/<login> --jq .id`.
+- **Never** use a machine or `.local` email in a co-author trailer — it links to
+  no account and gives **zero** credit.
+- When a squash-merge folds a contributor's PR into an internal branch, preserve
+  their `Co-authored-by:` line in the squash commit message.
+- Credit **people**, not AI tools.
+
+## Secrets & safety
+
+- Never commit secrets, signing certs, or private emails. Use
+  `*.noreply.github.com` for attribution.
+- Don't disable CI gates or branch protection to land a change; surface the
+  blocker instead.
+
+## Claude Code
+
+`CLAUDE.md` points here — this file is the source of truth for both.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2dc4508
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,10 @@
+# CLAUDE.md — open-sesame
+
+**Read [`AGENTS.md`](AGENTS.md).** It is the canonical guide for AI agents
+(including Claude Code) contributing to this repo — the branch/PR workflow,
+local checks (`swift build`, `swift test --parallel`), the template-shell
+invariants, and contributor attribution.
+
+Claude Code auto-loads this file; everything you need lives in `AGENTS.md` plus
+[`README.md`](README.md). There is no separate Claude-only workflow — follow
+`AGENTS.md`.