docs: initial planning artifacts for fjmcp-broker

Establish project scope, architecture, and phased implementation plan
for an OAuth 2.1 broker that fronts forgejo-mcp, delegating user
authentication to Forgejo and spawning a per-session stdio
forgejo-mcp subprocess scoped to each authenticated user's token.

No code yet — planning only.

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

README.md

@@ -0,0 +1,34 @@
+# forgejo-mcp-broker
+
+OAuth 2.1 authorization server and MCP session broker for [forgejo-mcp](https://codeberg.org/goern/forgejo-mcp).
+
+Lets MCP clients such as **Claude.ai** connect to a Forgejo instance through a single public HTTPS endpoint, with per-user authentication delegated to Forgejo's own OAuth2 provider. The broker handles the OAuth dance, then spawns a dedicated `forgejo-mcp --transport stdio` subprocess for each authenticated session, scoped to the authenticated user's Forgejo access token.
+
+**Status:** Planning. No code yet. See [`docs/design.md`](docs/design.md) for the architecture and [`docs/plan.md`](docs/plan.md) for the phased implementation plan.
+
+## How it fits
+
+```
+Claude.ai ──HTTPS──▶ Caddy ──▶ fjmcp-broker ──stdio──▶ forgejo-mcp  ──▶ Forgejo API
+                                  (this)              (one per user     (per-user
+                                                       session)          token)
+```
+
+- **`fjmcp-broker`** (this project): one long-running process. Handles OAuth discovery, dynamic client registration, the authorization-code flow against Forgejo, session lifecycle, and stdio-to-streamable-HTTP bridging.
+- **`forgejo-mcp`** (existing project): used as-is. Spawned per-session with the authenticated user's `FORGEJO_ACCESS_TOKEN` in the environment.
+- **Caddy**: terminates TLS for the public hostname and reverse-proxies to the broker.
+
+## Why a broker instead of adding OAuth to forgejo-mcp?
+
+Process-level isolation. Each user's Forgejo token lives in exactly one subprocess — the broker never needs to demultiplex tokens inside a single shared client. This keeps forgejo-mcp's `sync.Once` singleton-client pattern valid and avoids a refactor of every tool handler. Full trade-off in [`docs/design.md`](docs/design.md).
+
+## Quick map
+
+| File | What |
+|---|---|
+| [`docs/design.md`](docs/design.md) | Architecture, components, token flow, deployment, security |
+| [`docs/plan.md`](docs/plan.md) | Seven-phase implementation plan with acceptance criteria |
+
+## License
+
+TBD — pick one before the first public release. Likely MIT or Apache-2.0 to match the Forgejo ecosystem.