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>

docs/architecture.md

@@ -2,7 +2,38 @@
 
 ## Overview
 
-AegisGitea MCP is a Python 3.10+ application built on **FastAPI**. It acts as a bridge between an AI client (such as Claude, Claude Code, or Cowork) and a self-hosted Gitea instance, implementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
+AegisGitea MCP is a Python 3.10+ application split into a **transport-agnostic core** and **two thin transport adapters** that consume it. It bridges an AI client (Claude, Claude Code, Cowork) and a self-hosted Gitea instance, implementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
+
+```
+                ┌──────────────────────── shared core ────────────────────────┐
+                │  registry.py   (name -> handler; single source of truth)     │
+                │  tools/*       (async handlers: gitea, arguments, raw)       │
+                │  policy.py     (allow/deny, WRITE_MODE gate)                  │
+                │  authz.py      (resource-type-aware authorization)           │
+                │  gitea_client  · audit · security · response_limits · config │
+                │  errors.ToolError (transport-agnostic error type)            │
+                │  NO fastapi / uvicorn imports (locked by a boundary test)    │
+                └───────▲───────────────────────────────────────▲─────────────┘
+                        │                                       │
+       ┌────────────────┴───────────┐            ┌──────────────┴──────────────┐
+       │  HTTP / OAuth adapter       │            │  Local stdio adapter         │
+       │  server.py (FastAPI)        │            │  stdio_app.py (mcp SDK)      │
+       │  per-user OAuth2/OIDC, DCR, │            │  single PAT owner, no OAuth, │
+       │  rate limit, per-user repo  │            │  policy + WRITE_MODE + audit │
+       │  authz + resource-type gate │            │  over stdio                  │
+       │  [server] extra             │            │  core install                │
+       └─────────────────────────────┘            └──────────────────────────────┘
+```
+
+Where the security layers sit on a dispatched call: **scope check → policy
+(`policy.py`) → resource-type authorization (`authz.py`) → handler → response
+limits + secret sanitization → audit**. For `gitea_request`, the handler adds a
+deterministic write classifier, a known-path gate, and the admin/credential
+denylist. The HTTP adapter runs the per-user repository-permission probe and the
+resource-type gate; the stdio adapter trusts the PAT owner and skips the
+per-user probe while keeping policy, `WRITE_MODE`, and audit.
+
+The legacy single-process view below still describes the HTTP adapter:
 
 ```
 AI Client (Claude / Claude Code / Cowork)