docs: Requirements for the project.

.claude/adr/0009-setup-command-over-postinstall.md

@@ -0,0 +1,30 @@
+# Install the Agent Skill via an explicit `setup` command, not npm postinstall
+
+gitea-axi fulfills AXI Principle 7 (Ambient context) through a `setup` subcommand that copies the bundled Agent Skill markdown into `~/.claude/skills/`.
+There is no postinstall script.
+
+## Considered Options
+
+**npm postinstall script** (rejected) — The original spec draft had `postinstall` drop the skill file automatically.
+pnpm blocks lifecycle scripts by default and npm users increasingly install with `--ignore-scripts`, so the skill would silently fail to install for those users with no signal.
+A package install silently writing into `~/.claude/` is also the exact pattern security tooling flags.
+Finally, the canonical principle text asks for installation "from an explicit setup command" — postinstall is implicit.
+
+**`setup` command** (chosen) — Matches gh-axi's command surface (its `cli.ts` registers `setup`), matches the canonical principle wording, works under pnpm and `--ignore-scripts`, and makes the `~/.claude/` write an explicit user action.
+Discoverable via dashboard help suggestions.
+
+**Both** (rejected) — Two install paths to test, and the postinstall path retains all its failure modes.
+
+## Consequences
+
+- `npm install -g gitea-axi` delivers the CLI only; the skill requires a one-time `gitea-axi setup`.
+- `setup` is idempotent: re-running reports already-installed/updated rather than failing.
+- The dashboard suggestion table hints at `setup` so agents and operators discover it.
+
+## Addendum (2026-07-10): opt-in `setup hooks`
+
+Canonical Principle 7 makes SessionStart hooks the primary ambient-context mechanism, and gh-axi ships `setup hooks` via axi-sdk-js's `installSessionStartHooks()` (Claude Code, Codex, OpenCode).
+gitea-axi adds the same opt-in `setup hooks`; the skill remains the default `setup` action.
+
+Hooks are not the default because the hook runs the dashboard in every session in every directory, and outside a Gitea repo the dashboard errors with `REPO_NOT_FOUND` — a graceful exit-0 degradation was considered and rejected in favor of keeping the error explicit, so hook noise in non-Gitea sessions is an accepted consequence for users who opt in.
+The SDK registers the bare binary as the hook command, so the hook always runs the short dashboard tier (see ADR 0012).