docs: add project design doc and agent guidance

Tracks the two files that were sitting untracked in the working tree: the
original Agentic Bridle MCP design doc, and CLAUDE.md carrying the repo's
git/Gitea, SonarQube, and contribution conventions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m

CLAUDE.md

@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Subagents
+
+Use subagents (the Agent tool) when a task genuinely benefits from one — and match the model to the
+work:
+
+- **Reach for a subagent** for broad, read-heavy fan-out that would otherwise flood the main context:
+  sweeping many files across services, tracing a change through multiple components, or researching
+  where/how something is wired. Prefer `Explore` (read-only search) or `general-purpose` for these.
+  Use `Plan` to design a multi-step implementation before editing. Keep narrow, single-file edits and
+  quick lookups on the main thread — spawning a cold agent for those costs more than it saves.
+- **Assign the model to the task.** Route heavy reasoning — architecture decisions, contract/protocol
+  changes, security-sensitive work (auth, secrets, credential handling) — to a stronger model (Opus).
+  Route routine, well-scoped mechanical work — bulk search, boilerplate, simple refactors,
+  running/reporting tests — to a faster, cheaper model (Sonnet or Haiku). State the model explicitly
+  when spawning rather than defaulting.
+
+## Git & Gitea access
+
+- **All commits and pushes use the `wtclaude` bot identity, authenticated with the token at
+  `C:\Users\colby\.gitea_token_claude`.** Do not use the human user's git credentials. Configure the
+  remote (or a one-off push) to carry the token and set the author/committer to `wtclaude`, e.g.:
+
+  ```bash
+  TOKEN=$(cat /c/Users/colby/.gitea_token_claude)
+  git -c http.extraHeader="Authorization: token $TOKEN" \
+      -c user.name=wtclaude -c user.email=claude@whitlocktech.net \
+      push origin <branch>
+  ```
+
+  Keep the token out of committed files, remote URLs, and command output/logs (pass it via
+  `http.extraHeader` or a credential helper, never inline in the `origin` URL).
+- **Use the Gitea MCP tools (`mcp__gitea__*`) for all server-side Gitea operations** — opening and
+  reviewing pull requests, issues, releases, branches, labels, and reading repo contents. Prefer the
+  MCP over shelling out to `git`/`gh`/`tea` or the raw REST API for these. Reserve local `git` for
+  working-tree operations (commit, push, branch checkout) using the token above.
+- **Sync `main` before you start coding.** Before creating any new branch, switch to `main` and pull
+  so the local copy matches the remote (branches are always cut from an up-to-date `main`, never a
+  stale one):
+
+  ```bash
+  TOKEN=$(cat /c/Users/colby/.gitea_token_claude)
+  git checkout main
+  git -c http.extraHeader="Authorization: token $TOKEN" pull --ff-only origin main
+  git checkout -b <type>/<branch>
+  ```
+
+  If the working tree has uncommitted changes that block the checkout/pull, stop and surface it
+  rather than discarding them.
+
+## SonarQube (code quality / security scanning)
+
+- **SonarQube is at `https://sonar.whitlocktech.com`.** The API token lives in a local file in
+  `SONAR_TOKEN=squ_…` (KEY=value) format — extract the value after `=`. Read it at call time, and
+  keep it out of committed files, remote URLs, and command output/logs. **Authenticate with HTTP
+  Basic auth (token as username, empty password) — `-u "$TOKEN:"`; the `Authorization: Bearer` header
+  returns 401 on this instance.** Example:
+
+  ```bash
+  TOKEN=$(grep -oP '(?<=SONAR_TOKEN=).*' /path/to/sonar_token.txt)
+  curl -s -u "$TOKEN:" \
+    "https://sonar.whitlocktech.com/api/issues/search?componentKeys=<projectKey>&types=VULNERABILITY"
+  ```
+
+- **Project key(s):** _fill in once the Sonar project(s) for this repo are created._
+
+## Conventions
+
+- **Conventional Commits** (`type(scope): summary`, e.g. `feat(gateway): add token vault`).
+- **AI-assisted contributions must be disclosed** (org policy): tick the PR-template box naming the
+  tool, and mark AI-authored commits with a trailer such as `Co-Authored-By: Claude <noreply@anthropic.com>`.
+  Undisclosed AI-generated contributions may be closed. See `CONTRIBUTING.md`.
+- Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`).
+- **All architectural and design decisions must be asked and approved by the org lead (Colby
+  Whitlock) before implementation. You must ask before writing code.**