docs: production proxy path + capability-URL guidance

Two small documentation gaps the second-pass audit flagged:

- CLAUDE.md described only the Vite dev proxy ("Vite dev-proxies to
  the backend"), which left the production path opaque. Now lists
  both: the Vite proxy for `npm run dev` and
  `frontend/src/hooks.server.ts` for adapter-node. Same-origin cookie
  story called out explicitly.

- `/api/v1/files/{key}` is an unauthenticated capability URL by
  design — reads stay public, keys are unguessable v4 UUIDs, leaked
  URL leaks one file. Documented both in `backend/src/api/files.rs`'s
  module doc (with a pointer at the seam a future
  feat/private-libraries branch would use) and in a new "Capability
  URLs" section in README so a casual reader doesn't mistake the lack
  of auth for an oversight.

No code or behaviour change.

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

CLAUDE.md

@@ -102,7 +102,9 @@ Do not call `tokio::fs` or any filesystem API from handlers. Go through `state.s
 
 ## Frontend layout
 
-- [frontend/src/lib/api/](frontend/src/lib/api/) — typed API client. **All backend calls go through here**, not raw `fetch` in components. The base URL is `import.meta.env.VITE_API_BASE`, defaulting to `/api` (which Vite dev-proxies to the backend).
+- [frontend/src/lib/api/](frontend/src/lib/api/) — typed API client. **All backend calls go through here**, not raw `fetch` in components. The base URL is `import.meta.env.VITE_API_BASE`, defaulting to `/api`. Two layers route `/api/*` to axum depending on environment:
+  - **`npm run dev`** uses the Vite proxy in [vite.config.ts](frontend/vite.config.ts) to forward `/api` to `http://localhost:8080`.
+  - **Production / adapter-node** uses [frontend/src/hooks.server.ts](frontend/src/hooks.server.ts) to reverse-proxy `/api/*` to `BACKEND_URL` (compose wires `http://backend:8080`). The browser only ever talks to the SvelteKit container on `:3000`, so cookies stay same-origin and `CORS_ALLOWED_ORIGINS` can stay empty.
 - [frontend/src/routes/](frontend/src/routes/) — SvelteKit routes.
 - Use Svelte 5 runes (`$state`, `$derived`, `$effect`, `$props`). Do not use the legacy `let`-reactive syntax or `on:event=` directive form — prefer `onevent={...}`.
 - The Node adapter is configured for production; `npm run build && node build` is what the Dockerfile runs.

README.md

@@ -86,7 +86,7 @@ Everything is namespaced under `/api/v1/`. `/api/*` outside the version prefix i
 | GET    | `/api/v1/mangas/{id}/chapters`                          | Paginated chapter list, ordered by number. |
 | GET    | `/api/v1/mangas/{id}/chapters/{n}`                      | Single chapter.                            |
 | GET    | `/api/v1/mangas/{id}/chapters/{n}/pages`                | Page metadata (storage keys + MIME).       |
-| GET    | `/api/v1/files/{key}`                                   | Streams a blob (cover or page).            |
+| GET    | `/api/v1/files/{key}`                                   | Streams a blob (cover or page). See [Capability URLs](#capability-urls) below. |
 
 ### Write endpoints (require authentication)
 
@@ -144,6 +144,10 @@ Everything is namespaced under `/api/v1/`. `/api/*` outside the version prefix i
 
 The frontend handles this for you: register → cookie set → writes work. Cookies are `HttpOnly; SameSite=Lax; Secure` (configurable via `COOKIE_SECURE`).
 
+### Capability URLs
+
+`GET /api/v1/files/{key}` is unauthenticated by design: reads stay public so embedded `<img>` tags and external readers work without round-tripping a cookie or token. The keys themselves are unguessable — they're scoped under v4 UUIDs (`mangas/{manga-uuid}/cover.png`, `mangas/{manga-uuid}/chapters/{chapter-uuid}/pages/0001.png`) — so a leaked URL leaks at most the one file. Treat the URLs as bearer tokens for the bytes they reference and don't paste them into public chat. A future private-libraries feature would gate this endpoint behind a per-key ownership check; the architectural seam is documented in `backend/src/api/files.rs`.
+
 ### Bots / scripts (bearer tokens)
 
 The frontend on `:3000` proxies `/api/*` through to the backend, so any URL below works against `http://localhost:3000` in the default compose deploy. If you publish the backend port directly, swap in `http://localhost:8080`.

backend/src/api/files.rs

@@ -4,6 +4,17 @@
 //!
 //! The handler uses `Storage::get_stream` so a multi-MB page is piped to
 //! the client a chunk at a time instead of buffered server-side.
+//!
+//! **Auth model — capability URLs by design.** This endpoint is
+//! deliberately unauthenticated: reads stay public per the project
+//! brief, and per-page authorisation would require either a per-request
+//! ownership lookup (covers + pages are scoped by manga, not user) or a
+//! signed-URL scheme. Mangalord instead relies on the keys being
+//! unguessable — `mangas/{uuid}/...` and
+//! `mangas/{uuid}/chapters/{uuid}/...` — so a leaked URL leaks at most
+//! the one referenced file. A future feat/private-libraries branch
+//! would gate this endpoint behind a `Storage::owner_of(key)` check;
+//! the seam is intentional.
 
 use axum::body::Body;
 use axum::extract::{Path, State};