docs: add AGENTS.md + CLAUDE.md agent-contributor guidance

AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md — familiar-contract
+
+Guidance for **AI agents** (Codex, Claude Code, and any Coven familiar) opening
+pull requests against this repo. This is the agent-specific layer; read
+[`README.md`](README.md) for the full specification.
+
+> **What this repo is:** the **Familiar Contract** — an open specification for
+> what an agent is *allowed to be*: not just what it can do, but what it cannot
+> change about itself. The normative artifacts are the JSON Schemas under
+> [`schemas/`](schemas/) (`identity`, `role`, `soul`, `ward`) and the prose
+> spec in the Markdown pages.
+
+## Branch & PR workflow
+
+- **Never push to `main`.** Every change lands via a PR. 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/famcontract-<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.
+
+## This is a specification — change it deliberately
+
+- **Schemas are normative; prose explains them.** When you change a schema under
+  `schemas/`, update the corresponding prose page in the **same PR**, and vice
+  versa. They must not drift.
+- **Validate before you submit.** Every JSON Schema must be valid, and every
+  example/fixture in the repo must validate against its schema:
+  ```sh
+  # example — use whatever validator the repo scripts provide
+  find schemas -name '*.schema.json' -print0 | xargs -0 -n1 <json-schema-validate>
+  ```
+- **Backward compatibility matters.** The contract is consumed by real agents.
+  Prefer additive changes; a breaking change to identity/role/soul/ward needs an
+  explicit rationale and a version note in the PR body.
+- **Ward semantics are load-bearing.** The `ward` schema encodes what an agent
+  may *not* change about itself — treat edits there as security-sensitive and
+  spell out the reasoning.
+
+## 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 and on their
+profile:
+
+```
+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 (e.g. `name@Someones-Mac.local`) 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, tokens, or private emails. Use `*.noreply.github.com`
+  for attribution.
+- Don't loosen a ward or safety constraint in the spec to make an example pass;
+  fix the example instead.
+
+## Claude Code
+
+`CLAUDE.md` points here — this file is the source of truth for both.

CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md — familiar-contract
+
+**Read [`AGENTS.md`](AGENTS.md).** It is the canonical guide for AI agents
+(including Claude Code) contributing to this repo — the branch/PR workflow, the
+spec-change discipline (schemas are normative, keep prose + schema in sync,
+prefer additive changes, ward semantics are load-bearing), 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`.