feat(standards): integrate auth-server via pinned spec (docs://spec) + auth recipe and template slice

- serve the pinned auth-server OpenAPI contract as the standards MCP resource docs://spec (no auth-server MCP bundle)
- add Auth Integration recipe (14) and wire it into the registry, prompts, index, and nav
- un-defer Auth Server in the library registry (spec/recipe pointers)
- ship the opt-in template auth slice: interfaces/auth/ (placeholder + mergeable bearerAuth security.yaml) and AUTH_SERVER/JWT_SERVER env
- rebuild bundle (13 modules, 44 components); template stays authless by default

standards/mcp/modules/auth_integration.json

@@ -0,0 +1,8 @@
+{
+  "module": "auth_integration",
+  "content": {
+    "path": "auth_integration",
+    "docstring": "# Auth Integration\n\n## Summary\n\nAuthentication is a **service**, not a library. Every Aetos application shares a\nsingle identity service — the **auth-server** — and consumes it through its HTTP\ncontract. An app never implements registration, login, password hashing, or\ntoken issuance itself.\n\nThe agent does **not** need an MCP bundle for the auth-server. It reads the\npinned OpenAPI contract (below) and declares a bearer security scheme in its own\nspec; `openapi_first` then generates the verifying dependency. **No auth code is\nwritten.**\n\n---\n\n## Read the contract\n\nThe auth-server OpenAPI document is pinned in the standards bundle and served as\nan MCP resource:\n\n```\ndocs://spec\n```\n\nIt is the authoritative client contract (OpenAPI 3.1). Read it to learn the\nendpoints and the request/response schemas:\n\n| Endpoint | Purpose |\n|---|---|\n| `POST /register` | Create a user (201, returns `PublicUser`) |\n| `POST /login` | Authenticate and issue a JWT (`LoginResponse`) |\n| `GET /me` | Current user's `PublicUser` (bearer required) |\n| `POST /logout` | Stateless logout (`LogoutResponse`) |\n| `POST /introspect` | Internal token introspection (`active`, `user`) |\n\nThe pinned snapshot is versioned (currently `0.0.5`). If the caller has a live\nauth-server and needs the *current* contract, they can pass the full endpoint\n(`{AUTH_SERVER}/openapi.json`) and read it directly instead of the pin.\n\n---\n\n## Wire it up: declare, don't code\n\nAuthentication is added by editing the app's **own** `openapi.yaml` — nothing\nelse. Declare a global bearer requirement and point the scheme at the auth\nserver (values come from the environment):\n\n```yaml\nsecurity:\n  - bearerAuth: []\npaths:\n  # ...\ncomponents:\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n      x-server-url: \"{AUTH_SERVER}\"\n      x-introspect-path: \"/introspect\"\n      x-login-path: \"/login\"\n      x-register-path: \"/register\"\n      x-logout-path: \"/logout\"\n      x-me-path: \"/me\"\n```\n\n`openapi_first` reads `securitySchemes` + `security` and generates a FastAPI\ndependency that extracts the bearer token, POSTs `{\"token\": <jwt>}` to\n`{AUTH_SERVER}/introspect`, and returns the user when `active == true`. It\nraises `401` on an invalid or inactive token and `503` when the auth server is\nunreachable. The generated handlers receive the authenticated user — you author\n**no** authentication code.\n\n### Public operations\n\nA route that must stay open opts out by overriding `security` with an empty\nlist:\n\n```yaml\npaths:\n  /health:\n    get:\n      operationId: health\n      security: []        # overrides the global requirement\n      responses:\n        \"200\":\n          description: OK\n```\n\n### Environment\n\n```bash\nAUTH_SERVER=http://localhost:8000     # auth-server base URL\nJWT_SERVER=http://localhost:8000      # jwtlib client base URL (seeding/CLI)\n```\n\n---\n\n## Path 1: `jwtlib` client (no generator)\n\nApps that do not use a generated dependency verify requests with the `py-jwt`\nclient:\n\n```python\nfrom jwtlib.introspection import authenticate_request\n\nauthorized = await authenticate_request(\n    should_skip_authentication,  # allow public paths\n    method,\n    path,\n    authorization_token,         # \"Bearer <jwt>\" or None\n)\n```\n\n`authenticate_request` POSTs to `{JWT_SERVER}/introspect` (3 second timeout) and\ntreats `{\"active\": true, \"user\": {...}}` as valid. Use this for seeding scripts\nand tests (`jwtlib.register_user`, `jwtlib.login_user`).\n\n---\n\n## Golden rules\n\n1. **Never trust an unverified token.** Decode through the generated dependency\n   or `jwtlib` before handling the request.\n2. **Treat `active: false` as unauthenticated**, even if the JWT decodes.\n3. **Do not implement your own JWT parsing.** Revocation and issuer changes must\n   stay centralized in the auth-server.\n4. **Do not add auth until the app's outcome is validated.** Ship the app\n   authless first; layer the security scheme once the core behaviour works.\n\n---\n\n## Notes\n\n- The default template is **authless** on purpose. Add the `securitySchemes`\n  block above only when auth is required. Pull the shared slice with\n  `get_app_component(\"auth\")`.\n- The auth-server is deployed as a service (no importable package); the client\n  surface is the spec, plus `jwtlib` for the low-level path.\n",
+    "objects": {}
+  }
+}

standards/mcp/modules/index.json

@@ -2,7 +2,7 @@
   "module": "index",
   "content": {
     "path": "index",
-    "docstring": "# Standards Reference\n\nThe reference half of the Standards description: the enforceable rules,\npatterns, and the internal library catalog that agents consult while coding.\n\n- **Build Recipe** — the ordered, agentic checklist for a new app.\n- **Layering Rules** — the strict request → domain → repository layering and\n  the rules that enforce it.\n- **Composition Root** — a single composition point wiring the whole app.\n- **Spec-First Routing** — the OpenAPI contract as the routing source of truth.\n- **CRUD Template** — the standardized generic resource endpoint scaffold.\n- **Pipeline Scaffold** — the deterministic pipeline skeleton for multi-stage\n  jobs.\n- **Worker & Progress** — queued work, progress reporting, and visibility.\n- **Human-in-the-Loop** — guardrails and approvals inside automations.\n- **Infra Adapters** — how infrastructure connects without leaking into domain.\n- **Genericity Matrix** — what is library-backed, template-provided, or authored.\n- **Library Registry** — the catalog of internal libraries behind all of it.\n\nRead the **Wiki** for the philosophy and rationale; these pages are the\nreference that mirrors the `standards` MCP bundle.\n",
+    "docstring": "# Standards Reference\n\nThe reference half of the Standards description: the enforceable rules,\npatterns, and the internal library catalog that agents consult while coding.\n\n- **Build Recipe** — the ordered, agentic checklist for a new app.\n- **Layering Rules** — the strict request → domain → repository layering and\n  the rules that enforce it.\n- **Composition Root** — a single composition point wiring the whole app.\n- **Spec-First Routing** — the OpenAPI contract as the routing source of truth.\n- **CRUD Template** — the standardized generic resource endpoint scaffold.\n- **Pipeline Scaffold** — the deterministic pipeline skeleton for multi-stage\n  jobs.\n- **Worker & Progress** — queued work, progress reporting, and visibility.\n- **Human-in-the-Loop** — guardrails and approvals inside automations.\n- **Infra Adapters** — how infrastructure connects without leaking into domain.\n- **Genericity Matrix** — what is library-backed, template-provided, or authored.\n- **Auth Integration** — consuming the shared auth-server service (spec-driven,\n  no auth code).\n- **Library Registry** — the catalog of internal libraries behind all of it.\n\nRead the **Wiki** for the philosophy and rationale; these pages are the\nreference that mirrors the `standards` MCP bundle.\n",
     "objects": {}
   }
 }

standards/mcp/modules/library_registry.json

@@ -2,7 +2,7 @@
   "module": "library_registry",
   "content": {
     "path": "library_registry",
-    "docstring": "# Library Registry\n\n## Summary\n\nThe Aetos ecosystem provides internal libraries for the shared concerns of\nevery application. **Use them.** Writing a private copy of any capability below\nis a defect.\n\nEach library also exposes its own documentation as an MCP server. An AI agent\ncan read a library's full API by connecting to its MCP and reading\n`docs://index`, `docs://nav`, and `docs://modules/{module}`.\n\n---\n\n## Catalog\n\n| Library | Import | Purpose | Use instead of | MCP |\n|---|---|---|---|---|\n| DAG Pipe | `dagpipe` | Deterministic state-transformation DAG engine | hand-rolled orchestration/topological ordering | `:8006` |\n| Hexa | `hexa` | Declarative DI / composition-root tooling | manual wiring, hand-written factories | `:8008` |\n| Mongo Ops | `mongo_ops` | Async MongoDB repositories, cache, populate, transactions | raw Motor CRUD and connection lifecycle | `:8007` |\n| Omniread | `omniread` | Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) | custom scrapers/parsers | `:8003` |\n| OpenAPI First | `openapi_first` | Spec-first FastAPI bootstrap, client, codegen | decorator routers and hand-written clients | `:8004` |\n| Mail Intake | `mail_intake` | Provider-agnostic read-only email ingestion | Gmail OAuth + MIME parsing | `:8002` |\n| Py JWT | `jwtlib` | JWT auth primitives (register/login/introspect) | password hashing + token code | `:8005` |\n| Doc Forge | `docforge` | Docstring compiler → MkDocs + MCP docs | custom doc generators | `:8001` |\n| Auth Server | *(service)* | Central identity service (register/login/me/introspect) | building auth endpoints yourself | *(deferred)* |\n\n## How to choose\n\n| You need to… | Use |\n|---|---|\n| persist and query documents | Mongo Ops |\n| compose dependencies | Hexa |\n| run a multi-step transformation | DAG Pipe |\n| read/parse an arbitrary input format | Omniread |\n| expose a contract-first HTTP API | OpenAPI First |\n| ingest email | Mail Intake |\n| authenticate users / verify tokens | Py JWT (+ Auth Server) |\n| generate documentation | Doc Forge |\n\n## Discovery\n\nA single **standards MCP** exposes `find_library(capability)`, which returns the\nmatching library, its import name, its \"use instead of\" guidance, and its MCP\nendpoint. Query it before writing any infrastructure.\n\n## Notes\n\n- **Hexa** is a full library with its own MCP server on `:8008`: read\n  `docs://index`, `docs://nav`, and `docs://modules/{module}` (e.g.\n  `docs://modules/hexa.container`) to discover the DI surface — `build(cls, *,\n  instances, config)` and the `PortNode` model.\n- **Auth Server** is deferred: it has no `pyproject.toml`/importable package and\n  no MCP bundle. Do not reach for it yet; `py-jwt` covers token primitives.\n- Library MCP servers expose **documentation resources** (not executable tools):\n  they tell an agent the available API surface so it does not invent code.\n",
+    "docstring": "# Library Registry\n\n## Summary\n\nThe Aetos ecosystem provides internal libraries for the shared concerns of\nevery application. **Use them.** Writing a private copy of any capability below\nis a defect.\n\nEach library also exposes its own documentation as an MCP server. An AI agent\ncan read a library's full API by connecting to its MCP and reading\n`docs://index`, `docs://nav`, and `docs://modules/{module}`.\n\n---\n\n## Catalog\n\n| Library | Import | Purpose | Use instead of | MCP |\n|---|---|---|---|---|\n| DAG Pipe | `dagpipe` | Deterministic state-transformation DAG engine | hand-rolled orchestration/topological ordering | `:8006` |\n| Hexa | `hexa` | Declarative DI / composition-root tooling | manual wiring, hand-written factories | `:8008` |\n| Mongo Ops | `mongo_ops` | Async MongoDB repositories, cache, populate, transactions | raw Motor CRUD and connection lifecycle | `:8007` |\n| Omniread | `omniread` | Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) | custom scrapers/parsers | `:8003` |\n| OpenAPI First | `openapi_first` | Spec-first FastAPI bootstrap, client, codegen | decorator routers and hand-written clients | `:8004` |\n| Mail Intake | `mail_intake` | Provider-agnostic read-only email ingestion | Gmail OAuth + MIME parsing | `:8002` |\n| Py JWT | `jwtlib` | JWT auth primitives (register/login/introspect) | password hashing + token code | `:8005` |\n| Doc Forge | `docforge` | Docstring compiler → MkDocs + MCP docs | custom doc generators | `:8001` |\n| Auth Server | *(service)* | Central identity service (register/login/me/logout/introspect) | building auth endpoints yourself | spec: `docs://spec` |\n\n## How to choose\n\n| You need to… | Use |\n|---|---|\n| persist and query documents | Mongo Ops |\n| compose dependencies | Hexa |\n| run a multi-step transformation | DAG Pipe |\n| read/parse an arbitrary input format | Omniread |\n| expose a contract-first HTTP API | OpenAPI First |\n| ingest email | Mail Intake |\n| authenticate users / verify tokens | Py JWT (+ Auth Server) |\n| generate documentation | Doc Forge |\n\n## Discovery\n\nA single **standards MCP** exposes `find_library(capability)`, which returns the\nmatching library, its import name, its \"use instead of\" guidance, and its MCP\nendpoint (or, for the auth-server service, a spec pointer). It also serves the\npinned auth-server OpenAPI contract at `docs://spec`. Query it before writing\nany infrastructure.\n\n## Notes\n\n- **Hexa** is a full library with its own MCP server on `:8008`: read\n  `docs://index`, `docs://nav`, and `docs://modules/{module}` (e.g.\n  `docs://modules/hexa.container`) to discover the DI surface — `build(cls, *,\n  instances, config)` and the `PortNode` model.\n- **Auth Server** is a **service**, not an importable library: it has no MCP\n  bundle by design. Read its client contract from the pinned OpenAPI document\n  via `docs://spec` and wire it by declaring a `bearerAuth` security scheme in\n  the app's own spec (see **Auth Integration**); `py-jwt` covers the\n  low-level token path.\n- Library MCP servers expose **documentation resources** (not executable tools):\n  they tell an agent the available API surface so it does not invent code.\n",
     "objects": {}
   }
 }