docs: local vs server quickstart, authz model, packaging

Reframe the README around two transports and add a local stdio quickstart with
uvx/pip and Claude Desktop / Claude Code wiring. New docs: local-quickstart.md
and packaging.md (uv build/publish). Document resource-type-aware authorization
and classified gitea_request in security.md; stdio env vars + audit-log
fallback in configuration.md; local install in deployment.md; core+adapters in
architecture.md. Add the missing root AGENTS.md contract, update CLAUDE.md with
the core/adapter layout, fail-closed invariants, and the branching flow
(HEAD -> feature -> dev -> main). Update roadmap/todo and .env.example.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -1,10 +1,61 @@
 # AegisGitea-MCP
 
-Security-first MCP server for self-hosted Gitea with per-user OAuth2/OIDC authentication for Claude, Claude Code, and Cowork.
+Security-first MCP server for self-hosted Gitea, available as **two transports built on one shared core**:
 
-AegisGitea-MCP exposes MCP tools over Streamable HTTP and a legacy SSE alias. Each user authenticates with Gitea through OAuth2/OIDC; repository authorization is checked per user before any service PAT call is allowed.
+- **Local (stdio)** — `uvx aegis-gitea-mcp`. A single-user server for your own machine that authenticates with your Gitea Personal Access Token. No OAuth, no web stack. Ideal for Claude Desktop / Claude Code on your laptop.
+- **Server (HTTP/OAuth)** — `aegis-gitea-mcp[server]` / Docker. The public, multi-user deployment with per-user OAuth2/OIDC, dynamic client registration, rate limiting, and per-user repository authorization. Exposes MCP over Streamable HTTP and a legacy SSE alias.
 
-## Securing MCP with Gitea OAuth
+Both transports share the same tools, policy engine, secret sanitization, tamper-evident audit log, and — new in 0.2.0 — **safe full-API coverage** via the policy-gated `gitea_request` escape hatch plus **resource-type-aware authorization** for the admin/user/org surface.
+
+> Branching / contribution flow: `HEAD -> feature branch -> dev -> main`. All pull requests target `dev`; `dev` is merged to `main` for releases. Never commit or push directly to `dev` or `main`.
+
+## Run locally (stdio, single user)
+
+Install nothing and run it with [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+GITEA_URL=https://git.hiddenden.cafe \
+GITEA_TOKEN=<your-gitea-personal-access-token> \
+uvx aegis-gitea-mcp
+```
+
+Or install it:
+
+```bash
+pip install aegis-gitea-mcp        # core only (local stdio)
+aegis-gitea-mcp                    # reads GITEA_URL + GITEA_TOKEN (or a .env file)
+```
+
+Wire it into Claude Code:
+
+```bash
+claude mcp add aegis-gitea -- uvx aegis-gitea-mcp
+# with env values:
+claude mcp add aegis-gitea -e GITEA_URL=https://git.hiddenden.cafe -e GITEA_TOKEN=<pat> -- uvx aegis-gitea-mcp
+```
+
+Or Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "aegis-gitea": {
+      "command": "uvx",
+      "args": ["aegis-gitea-mcp"],
+      "env": {
+        "GITEA_URL": "https://git.hiddenden.cafe",
+        "GITEA_TOKEN": "<your-gitea-personal-access-token>"
+      }
+    }
+  }
+}
+```
+
+The local server resolves your PAT's Gitea user at startup and pins every call to that identity. The policy engine and `WRITE_MODE` gate still apply (writes are off by default), and the audit log is written to a per-user path (e.g. `%LOCALAPPDATA%\aegis-gitea-mcp\audit.log` on Windows, `~/.local/state/aegis-gitea-mcp/audit.log` on Linux). See [docs/local-quickstart.md](docs/local-quickstart.md).
+
+## Securing MCP with Gitea OAuth (public server)
+
+> The HTTP/OAuth server needs the web stack: install with `pip install 'aegis-gitea-mcp[server]'` (or use Docker) and run `aegis-gitea-mcp-server`.
 
 This guide uses the live deployment values as the running example:
 
@@ -217,8 +268,11 @@ Gitea workflows were added under `.gitea/workflows/`:
 
 ## Documentation
 
+- `docs/local-quickstart.md` — local stdio install and client wiring
+- `docs/packaging.md` — build & publish with `uv`
 - `docs/api-reference.md`
-- `docs/security.md`
+- `docs/security.md` — incl. resource-type-aware authorization
 - `docs/configuration.md`
 - `docs/deployment.md`
 - `docs/write-mode.md`
+- `docs/raw-api.md` — the `gitea_request` escape hatch