Sync _project docs to deployed reality

- ARCHITECTURE: root route, parse() signature change, response shape, bucket
mount, 5-min sleep, public-Space sharp edge.
- CURRENT_STATE: deployed Space verified live; remaining task is
ANTHROPIC_API_KEY + first real PDF.
- CHANGELOG: dated v0 deploy entry; consolidated Unreleased into shipped.
- RUNBOOK: secret-setting recipe via huggingface_hub; dev-mode debug step;
hf spaces info command.
- INFRASTRUCTURE: public visibility, dev-mode off, deploy date.
- ENVIRONMENT: marks API_TOKEN as set, ANTHROPIC_API_KEY as pending.
- DECISIONS: new entry for public-Space + bearer-token auth model.
- ROADMAP: filled in (was placeholder).
- TODO: deploy items moved to Done; ANTHROPIC_API_KEY surfaced as next.
- SPEC: bucket replaces persistent-storage tier; sleep 15→5 min.

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

_project/ARCHITECTURE.md

@@ -17,25 +17,30 @@
 - **Frontend:** none. JSON API only.
 - **Build / package manager:** `uv` for dependency resolution; `pip` inside the
   Docker image (smaller layer than installing `uv` into the runtime).
-- **Hosting:** Hugging Face Space, **Docker SDK**, A10 small GPU, persistent
-  storage mounted at `/data`.
+- **Hosting:** Hugging Face Space (`hirokamitai/trenchlesspm`, **public**),
+  Docker SDK, A10 small GPU, HF Bucket `hirokamitai/trenchlesspm-cache`
+  mounted at `/data` for the model cache.
 
 ## Components
 
-- **`app/main.py`** — FastAPI app. Exposes `GET /health` and `POST /parse`.
-  Bearer-token auth via `Authorization: Bearer <secret>` header, secret read from
-  the `API_TOKEN` Space secret.
-- **`app/parser.py`** — wraps marker-pdf. Loads the marker model converter once at
-  startup (module-level singleton) so subsequent requests reuse weights on GPU.
-  Exposes `parse(pdf_bytes, mode) -> str`. `mode="quality"` flips marker's
-  LLM-enhancement flag on; `mode="fast"` leaves it off.
-- **`Dockerfile`** — CUDA-enabled base image, installs system deps marker needs,
-  `pip install marker-pdf` + FastAPI stack, sets `HF_HOME=/data/hf` and
-  `TORCH_HOME=/data/torch` so model weights persist across cold starts. Exposes
-  port 7860 (HF Space convention).
-- **`README.md`** (Space root) — HF Space frontmatter (`sdk: docker`, `app_port:
-  7860`, `sleep_time: 900`, `suggested_hardware: a10g-small`), plus a short usage
-  blurb.
+- **`app/main.py`** — FastAPI app. Exposes `GET /` (endpoint blurb, public),
+  `GET /health` (liveness + gpu/cpu, public), and `POST /parse` (bearer-gated).
+  Bearer-token auth via `Authorization: Bearer <secret>`; secret comes from the
+  `API_TOKEN` Space secret. Streams uploads to a temp file (no RAM buffering).
+- **`app/parser.py`** — wraps marker-pdf. Loads the marker model dict once at
+  import time (module-level singleton) so subsequent requests reuse weights on
+  GPU. Exposes `parse(pdf_path, mode) -> tuple[str, int]` returning
+  `(markdown, page_count)`. `mode="quality"` flips marker's LLM-enhancement
+  flag on and routes through `marker.services.claude.ClaudeService`
+  (defaults to `claude-sonnet-4-6`).
+- **`Dockerfile`** — CUDA-enabled base image, installs system deps marker
+  needs, `pip install` of marker-pdf + FastAPI stack, sets `HF_HOME=/data/hf`
+  and `TORCH_HOME=/data/torch` so model weights persist on the bucket. CMD
+  runs Uvicorn with `--timeout-keep-alive 1800` so long parses don't drop
+  the connection. Exposes port 7860 (HF Space convention).
+- **`README.md`** (Space root) — HF Space frontmatter (`sdk: docker`,
+  `app_port: 7860`, `sleep_time: 300`, `suggested_hardware: a10g-small`,
+  `suggested_storage: small`), plus a short usage blurb.
 
 ## Data flow
 
@@ -45,18 +50,26 @@
      file:       the PDF
      parse_mode: "fast" (default) | "quality"
 
-2. FastAPI handler validates the bearer token + form fields.
+2. FastAPI handler validates the bearer token + form fields. Upload streams
+   in 1 MiB chunks to a NamedTemporaryFile so 100+ MB PDFs don't OOM.
 
-3. Handler reads the PDF bytes into memory and calls parser.parse(bytes, mode).
+3. Handler times parser.parse(tmp_path, mode) with time.perf_counter().
 
 4. parser.parse runs marker-pdf on the GPU. On "quality" mode it also calls out
    to Claude (Sonnet 4.6 by default) via marker's `ClaudeService` for layout,
    table, and equation cleanup. See _project/ENVIRONMENT.md for env vars.
 
-5. Handler returns JSON: { "markdown": "<string>", "mode": "fast|quality" }.
-
-6. Space autosleeps after 15 min of no requests. Next request triggers a cold
-   start; model weights load from /data instead of re-downloading.
+5. Handler returns JSON:
+   {
+     "markdown": "...",
+     "mode": "fast"|"quality",
+     "page_count": <int>,
+     "duration_ms": <int>
+   }
+   page_count comes from marker's rendered.metadata, falling back to pypdf.
+
+6. Space autosleeps after 5 min of no requests. Next request triggers a cold
+   start; model weights load from /data (HF Bucket) instead of re-downloading.
 ```
 
 ## Key directories
@@ -64,12 +77,13 @@
 | Path | Purpose |
 |---|---|
 | `app/` | FastAPI app code (`main.py`, `parser.py`). |
-| `/data/` (runtime, on the Space) | HF persistent storage. Holds `hf/` (HF model cache) and `torch/` (Torch hub cache). Not in this repo. |
+| `/data/` (runtime, on the Space) | Mount point for HF Bucket `hirokamitai/trenchlesspm-cache`. Holds `hf/` (HF Hub cache) and `torch/` (Torch hub cache). Not in this repo. |
 
 ## External touchpoints
 
-- **Hugging Face Hub** — marker pulls its layout / OCR models from the Hub on first
-  cold start; cached to `/data/hf` thereafter. No auth needed for public models.
+- **Hugging Face Hub** — marker pulls its layout / OCR models from the Hub on
+  first cold start; cached to `/data/hf` (HF Bucket mount) thereafter. No auth
+  needed for public models.
 - **Anthropic API (Claude)** — only called when `parse_mode=quality`. Marker
   uses its built-in `ClaudeService`; we pin `claude-sonnet-4-6`. API key
   stored as a Space secret. See [DEPENDENCIES.md](DEPENDENCIES.md).
@@ -79,10 +93,14 @@
 - **Cold start is slow.** First request after sleep waits on container boot +
   model load from `/data` (~30–60s). This is by design for cost; don't try to
   paper over it with a keepalive.
-- **Model cache MUST land on `/data`.** Without persistent storage, every cold
-  start re-downloads ~5 GB of weights, which both slows cold starts and burns
-  bandwidth. The Dockerfile sets `HF_HOME=/data/hf` and `TORCH_HOME=/data/torch`
-  for this reason.
+- **Model cache MUST land on `/data`.** If the bucket isn't mounted, every
+  cold start re-downloads ~5 GB of weights into ephemeral container disk
+  (lost on the next sleep). The Dockerfile sets `HF_HOME=/data/hf` and
+  `TORCH_HOME=/data/torch` so marker writes through the bucket.
+- **Public Space, bearer auth.** The Space URL is reachable without HF auth.
+  Real access control is the bearer-token check in `app/main.py` — `/parse`
+  401s without `Authorization: Bearer <API_TOKEN>`. `/` and `/health` are
+  intentionally open and leak nothing.
 - **Package name vs import name.** `pip install marker-pdf`, but `import marker`.
   Easy to get wrong.
 - **Single-process, GPU-bound.** Don't run multiple Uvicorn workers — they'd each

_project/CHANGELOG.md

@@ -8,12 +8,19 @@ Newest first. Format: `## YYYY-MM-DD — short title`, then bullets.
 
 ## Unreleased
 
-- Persistence switched from the older per-Space "Persistent Storage" tier to an HF Bucket (`hirokamitai/trenchlesspm-cache`, private, mounted at `/data`) for the marker model cache. No code changes — Dockerfile already pins `HF_HOME`/`TORCH_HOME` under `/data`. See DECISIONS for the cost rationale.
-- `/parse` response shape extended with `page_count` and `duration_ms`; uploads stream to a temp file (no longer buffered in RAM) so 100+ MB construction PDFs don't OOM the A10 small. Uvicorn keep-alive bumped to 30 min for long parses. Space autosleep lowered from 15 min → 5 min to halve idle billing. Added `pypdf` as a fallback page-count source when marker's metadata key shifts between versions. Caller for these changes: TrenchlessPM, replacing LlamaParse.
-- Initial FastAPI app: `GET /health`, `POST /parse` (multipart upload, bearer-token auth, `parse_mode` toggle for marker's LLM-enhancement flag).
-- `quality` mode wired to Claude (Sonnet 4.6 via marker's `ClaudeService`); reads `ANTHROPIC_API_KEY`, optional `CLAUDE_MODEL` override.
-- Dockerfile: CUDA-enabled base, marker-pdf installed, `HF_HOME` and `TORCH_HOME` pinned to `/data` so model cache survives cold starts.
-- Root `README.md` carries the HF Space frontmatter (Docker SDK, A10 small, 15-min autosleep, persistent storage).
-- Project docs filled in (SPEC, ARCHITECTURE, DECISIONS, ENVIRONMENT, DEPENDENCIES, INFRASTRUCTURE, RUNBOOK).
+- (nothing yet)
 
 ---
+
+## 2026-04-28 — v0 deploy to HF Space
+
+- First deploy of marker to `hirokamitai/trenchlesspm` (public, Docker SDK, A10 small, dev-mode off, autosleep 5 min). Push via `git push origin master:main`.
+- HF Bucket `hirokamitai/trenchlesspm-cache` (private, RW) mounted at `/data` for marker's ~5 GB model cache. Replaces the older fixed-fee Persistent Storage tier with pay-per-byte billing. No code change — `HF_HOME`/`TORCH_HOME` already point at `/data`. See DECISIONS for rationale.
+- `API_TOKEN` set as a Space secret (via `huggingface_hub.add_space_secret`). `ANTHROPIC_API_KEY` still pending — `parse_mode=quality` will 400 until set.
+- Verified live: `GET /` 200 (endpoint blurb), `GET /health` 200 with `mode: "gpu"`, `POST /parse` without auth 401.
+- FastAPI app shipped: `GET /` (blurb, public), `GET /health` (liveness, public), `POST /parse` (bearer-gated, multipart, `parse_mode` toggle).
+- `parse_mode=quality` routes through Claude Sonnet 4.6 via marker's `ClaudeService`; reads `ANTHROPIC_API_KEY`, optional `CLAUDE_MODEL` override.
+- `/parse` response shape: `{markdown, mode, page_count, duration_ms}`. Uploads stream to a temp file (no RAM buffering) so 100+ MB construction PDFs don't OOM the A10 small. Uvicorn `--timeout-keep-alive 1800` so long parses don't drop. Added `pypdf` as a fallback page-count source when marker's metadata key shifts between versions. Caller these changes were sized for: TrenchlessPM, replacing LlamaParse.
+- Dockerfile: CUDA 12.4 base, Python 3.11, marker-pdf installed, `HF_HOME=/data/hf` and `TORCH_HOME=/data/torch` so the bucket holds the model cache across cold starts.
+- Root `README.md` carries the HF Space frontmatter (Docker SDK, A10 small, 5-min autosleep, persistent storage suggested).
+- Project docs filled in (SPEC, ARCHITECTURE, DECISIONS, ENVIRONMENT, DEPENDENCIES, INFRASTRUCTURE, RUNBOOK, CURRENT_STATE, TODO, ROADMAP, CHANGELOG).

_project/CURRENT_STATE.md

@@ -8,25 +8,37 @@
 
 ## What's built and working
 
-- Project docs filled in: SPEC, ARCHITECTURE, DECISIONS, ENVIRONMENT, DEPENDENCIES, INFRASTRUCTURE, RUNBOOK.
-- FastAPI app skeleton: `GET /health`, `POST /parse` with bearer-token auth and `parse_mode` (`fast` | `quality`).
-- Dockerfile targeting CUDA + marker-pdf, with `HF_HOME` / `TORCH_HOME` pinned to `/data` for persistent model cache.
-- HF Space frontmatter in root `README.md` (Docker SDK, A10 small, 15-min autosleep, persistent storage).
+- FastAPI app with three routes:
+  - `GET /` — endpoint blurb (public, no auth).
+  - `GET /health` — liveness + reports `gpu`/`cpu` (public, no auth).
+  - `POST /parse` — multipart upload → `{markdown, mode, page_count, duration_ms}` (bearer-gated).
+- Bearer-token auth via `Authorization: Bearer <API_TOKEN>`; constant-time compare.
+- Streamed uploads to a temp file (1 MiB chunks) — handles 100+ MB PDFs without OOM.
+- `parse_mode=fast` runs marker-pdf alone; `parse_mode=quality` adds Claude Sonnet 4.6 LLM-enhancement via marker's `ClaudeService`.
+- Page count from marker's rendered metadata, falling back to `pypdf`; duration timed with `time.perf_counter()`.
+- Dockerfile (CUDA 12.4 base, Python 3.11) with `HF_HOME` and `TORCH_HOME` pinned to `/data` so marker's ~5 GB of model weights persist via the HF Bucket mount.
+- Uvicorn `--timeout-keep-alive 1800` so long parses don't drop.
 
 ## What's deployed
 
-- **Environment:** Hugging Face Space `hirokamitai/trenchlesspm` (Docker SDK, A10 small, persistent `/data`).
-- **Version / commit:** see latest push to `origin master:main`.
-- **Deployed at:** 2026-04-28 (first deploy).
+- **Environment:** Hugging Face Space `hirokamitai/trenchlesspm` — public, Docker SDK, A10 small, dev-mode off, autosleep 5 min.
+- **Persistence:** HF Bucket `hirokamitai/trenchlesspm-cache` (private, RW) mounted at `/data`.
+- **Secrets set:** `API_TOKEN` ✓. `ANTHROPIC_API_KEY` is **not yet set** — so `parse_mode=quality` will 400 until it is.
+- **Verified live (2026-04-28):**
+  - `GET /` → 200, returns endpoint blurb.
+  - `GET /health` → 200, `{"status":"ok","mode":"gpu"}` (GPU detected).
+  - `POST /parse` without auth → 401 (auth enforced).
+- **Version / commit:** see latest `origin/main`. End-to-end PDF smoke test still pending (next item below).
 
 ## What's in progress
 
-- First push to the Space; verifying cold-start + model cache behavior on real GPU.
-- Setting `API_TOKEN` and `ANTHROPIC_API_KEY` as Space secrets.
+- Set `ANTHROPIC_API_KEY` on the Space (only blocks `parse_mode=quality`).
+- End-to-end smoke test: upload a real contract PDF, verify both modes return sensible markdown and that cold start after autosleep loads weights from the bucket (no 5 GB re-download).
+- Wire TrenchlessPM (`/Users/michael/Documents/apps/web/TrenchlessPM`) to call `/parse`, replacing LlamaParse.
 
 ## What's known broken / flaky
 
-- Nothing observed yet — nothing has been deployed.
+- Nothing observed yet at runtime.
 
 ## Half-finished or abandoned
 

_project/DECISIONS.md

@@ -27,6 +27,30 @@ Write decisions where someone smart would reasonably pick differently.
 
 ## Entries
 
+## 2026-04-28 — Public Space, bearer-token auth (not HF private + HF token)
+
+**Decision:** the Space is **public**; access control to `/parse` is the
+single shared bearer token in `app/main.py` (`API_TOKEN`, set as a Space
+secret). `/` and `/health` are intentionally open and leak nothing.
+**Context:** TrenchlessPM and any other internal caller needs to invoke
+`/parse` from non-interactive code. HF Spaces gate private Spaces behind
+the caller's HF user token, on top of any app-level auth.
+**Alternatives considered:** keep the Space private and require callers
+to send `Authorization: Bearer <HF_USER_TOKEN>` *plus* our app-level
+`API_TOKEN`. Workable, but doubles the number of secrets each integrator
+manages, and HF user tokens are coarse-grained (they grant access to the
+whole HF account, not just this Space) — leaking one is a much bigger
+incident than leaking the marker bearer.
+**Tradeoffs:** the Space URL is publicly discoverable. Anyone can hit it,
+and unauthenticated `/parse` calls will burn a tiny bit of edge bandwidth
+returning 401. Acceptable — a 256-bit shared secret is the actual
+enforcement boundary, and HF's edge handles abuse.
+**Revisit if:** (a) we need fine-grained per-caller revocation (right now
+rotating the single token forces every caller to update), (b) compliance
+ever requires that the URL itself not be discoverable, or (c) we add
+endpoints that are unsafe to expose at all (in which case route-level
+auth is the answer, not Space-level).
+
 ## 2026-04-28 — Claude Sonnet 4.6 for marker's LLM-enhancement pass
 
 **Decision:** point marker's `quality` mode at `marker.services.claude.ClaudeService`

_project/ENVIRONMENT.md

@@ -12,7 +12,7 @@ do **not** live in this file — only pointers to them.
 
 | Name | Purpose | Where the real value lives | Used by |
 |---|---|---|---|
-| `API_TOKEN` | Bearer token clients send in `Authorization: Bearer …` to call `/parse`. Single shared secret, no per-user tokens. | 1Password > marker > API_TOKEN | `app/main.py` |
+| `API_TOKEN` | Bearer token clients send in `Authorization: Bearer …` to call `/parse`. Single shared secret, no per-user tokens. **Set on the Space as of 2026-04-28.** | 1Password > marker > API_TOKEN | `app/main.py` |
 
 ## Optional
 
@@ -20,7 +20,7 @@ do **not** live in this file — only pointers to them.
 |---|---|---|---|
 | `HF_HOME` | Where the Hugging Face client caches model weights. Pinned to persistent storage so cold starts don't re-download ~5 GB. | `/data/hf` (set in Dockerfile) | n/a — set in image |
 | `TORCH_HOME` | Where Torch hub caches checkpoints. Same reason as `HF_HOME`. | `/data/torch` (set in Dockerfile) | n/a — set in image |
-| `ANTHROPIC_API_KEY` | Used by marker's LLM-enhancement path (Claude) when `parse_mode=quality`. Not needed if you never call quality mode. | 1Password > marker > ANTHROPIC_API_KEY | `app/parser.py` |
+| `ANTHROPIC_API_KEY` | Used by marker's LLM-enhancement path (Claude) when `parse_mode=quality`. Not needed if you never call quality mode. **Not yet set on the Space as of 2026-04-28** — `parse_mode=quality` will 400 until it is. | 1Password > marker > ANTHROPIC_API_KEY | `app/parser.py` |
 | `CLAUDE_MODEL` | Claude model ID used for quality mode. Override only if you want a different speed/cost/quality tradeoff. | `claude-sonnet-4-6` | n/a |
 | `LOG_LEVEL` | Uvicorn log level. | `info` | n/a |
 | `PORT` | Port FastAPI binds to. HF Spaces convention is 7860. | `7860` | n/a |
@@ -28,7 +28,7 @@ do **not** live in this file — only pointers to them.
 ## Where env vars are loaded
 
 - **Local:** `.env` file at project root, loaded by `python-dotenv` from `app/main.py` on startup. Only used for development; production reads from the Space's secret store directly.
-- **Production (HF Space):** set in the Space's **Settings → Variables and secrets** panel. `API_TOKEN` and `ANTHROPIC_API_KEY` go in **Secrets**; `HF_HOME` / `TORCH_HOME` are baked into the Dockerfile and don't need to be set here.
+- **Production (HF Space):** set in the Space's **Settings → Variables and secrets** panel, or programmatically via `huggingface_hub.HfApi().add_space_secret(...)`. `API_TOKEN` and `ANTHROPIC_API_KEY` go in **Secrets**; `HF_HOME` / `TORCH_HOME` are baked into the Dockerfile and don't need to be set here. See [RUNBOOK.md](RUNBOOK.md) for the API-based recipe (avoids putting the secret on the bash command line / in shell history).
 
 ## Rotation notes
 

_project/INFRASTRUCTURE.md

@@ -19,14 +19,16 @@ and the `hf` CLI / git push to the Space repo.
 - **Provider:** Hugging Face Spaces
 - **Host name / label:** `hirokamitai/trenchlesspm`
 - **URL:** `https://hirokamitai-trenchlesspm.hf.space`
+- **Visibility:** **public** (real access control is the bearer-token check in `app/main.py`; see [DECISIONS.md](DECISIONS.md))
 - **Region:** US (HF default for GPU Spaces)
 - **Size / tier:** A10 small (1× NVIDIA A10G, 24 GB VRAM)
 - **SDK:** Docker
+- **Dev mode:** off (must stay off — when on, HF routes the public URL to a dev IDE and every endpoint 404s)
 - **Persistent storage:** HF Bucket `hirokamitai/trenchlesspm-cache` (private, read+write) mounted at `/data`. Holds the marker model cache (`/data/hf`, `/data/torch`) so cold starts skip the ~5 GB model download.
 - **Sleep behavior:** autosleep after 5 min idle (`sleep_time: 300` in README frontmatter)
 - **Monthly cost:** A10 small billed by the second when awake (~$1.05/hr) + bucket storage (pay-per-byte, ~5 GB of marker weights). Target total <$5–10/mo at expected usage.
 - **Paid with:** card on file at huggingface.co/settings/billing
-- **Provisioned on:** pre-existing (Space was scaffolded from the sappcode template)
+- **First deploy:** 2026-04-28
 
 ## How to access
 

_project/ROADMAP.md

@@ -13,23 +13,23 @@ For why specific choices were made, see [DECISIONS.md](DECISIONS.md).
 
 ## Now (this month)
 
-- **<!-- FILL IN: theme -->** — <!-- one-line description. Success looks like: ... -->
-- 
+- **Cut TrenchlessPM over from LlamaParse to marker** — finish the integration on the TrenchlessPM side and run the first real contract through `/parse`. Success: parses match or beat LlamaParse Premium quality at <$5/mo bill.
+- **Verify cold-start cache hit** — confirm that after autosleep, the first wake reads weights from the bucket (no 5 GB redownload in the Logs tab). Success: cold-start latency settles around 30–60 s.
+- **Set `ANTHROPIC_API_KEY`** so `parse_mode=quality` is usable. Success: a real contract round-trips through Sonnet 4.6 cleanup.
 
 ## Next (1–3 months)
 
-- **<!-- FILL IN: theme -->** — <!-- one-line description -->
-- 
+- **Hash-keyed result caching** — skip the GPU when TrenchlessPM retries the same PDF. Probably an in-memory LRU or a small SQLite at `/data/cache.db`.
+- **Operability** — wire the Space into the sapplab monitor dashboard via `.monitor.yml`; add a `429`-aware retry on the TrenchlessPM client side.
 
 ## Later (3–6+ months)
 
-- **<!-- FILL IN: theme -->** — <!-- one-line description -->
-- 
+- **Multi-PDF batch endpoint** — only if a real workflow asks for it; sync request model is fine for v1.
+- **Audit / replay** — externalize input+output to an R2/S3 bucket if a downstream consumer ever needs to dispute "what did marker return for this PDF?"
 
 ## Considered, not doing
 
-Things actively evaluated and rejected. Saves you (and Claude) from
-re-litigating them. One-line reason each.
-
-- <!-- FILL IN: e.g., "Custom code-reviewer subagent — Claude Code's /review already covers it." -->
-- 
+- **Mounting an external S3/R2/GCS bucket for inputs/outputs** — see [DECISIONS.md](DECISIONS.md) "No external bucket"; speculative for v1.
+- **Gradio UI on top of `/parse`** — JSON API only is a goal, not a v1 omission; see [SPEC.md](SPEC.md).
+- **Multiple Uvicorn workers** — would OOM the GPU; concurrency comes from Space scaling, not in-process workers.
+- **Local LLM for `quality` mode** — A10's VRAM is for marker; the LLM call stays external.

_project/RUNBOOK.md

@@ -34,13 +34,16 @@ uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload
 Smoke test:
 
 ```bash
+curl -s http://localhost:7860/
+# => {"service":"marker","endpoints":{...}}
+
 curl -s http://localhost:7860/health
 # => {"status":"ok","mode":"cpu"}
 
 curl -s -X POST http://localhost:7860/parse \
   -H "Authorization: Bearer $API_TOKEN" \
   -F "file=@sample.pdf" \
-  -F "parse_mode=fast" | jq -r '.markdown' | head
+  -F "parse_mode=fast" | jq '{mode, page_count, duration_ms, head: (.markdown[:200])}'
 ```
 
 ### Run tests
@@ -61,12 +64,28 @@ The Space repo is wired up as this repo's `origin` remote — local branch is
 `master`, the Space's default branch is `main`, so all pushes are
 `master:main`.
 
-### Set Space secrets (one-time, via web UI)
+### Set Space secrets
+
+Either via the web UI (https://huggingface.co/spaces/hirokamitai/trenchlesspm/settings → Variables and secrets) or via the `huggingface_hub` Python API. **Never paste a secret on the bash command line directly** — pass it via env var so it doesn't land in shell history. Example:
 
-Go to https://huggingface.co/spaces/hirokamitai/trenchlesspm/settings and set:
+```bash
+HF_PY=/opt/homebrew/Cellar/hf/*/libexec/bin/python  # bundled with `brew install hf`
+SECRET_VALUE='<paste here>' $HF_PY -c '
+import os
+from huggingface_hub import HfApi
+HfApi().add_space_secret(
+    repo_id="hirokamitai/trenchlesspm",
+    key="ANTHROPIC_API_KEY",   # or API_TOKEN
+    value=os.environ["SECRET_VALUE"],
+)
+'
+unset SECRET_VALUE
+```
 
-- `API_TOKEN` — bearer token callers must send.
-- `ANTHROPIC_API_KEY` — only needed for `parse_mode=quality`.
+Required:
+
+- `API_TOKEN` — bearer token callers must send. **Already set** as of 2026-04-28.
+- `ANTHROPIC_API_KEY` — only needed for `parse_mode=quality`. **Pending** as of 2026-04-28.
 
 ### Deploy a change
 
@@ -103,10 +122,26 @@ curl -fsS https://hirokamitai-trenchlesspm.hf.space/health
 If it's been idle >5 min the first request triggers a cold start (~30–60 s
 wait). That's by design.
 
-### Restart
+### Check Space metadata (stage, dev mode, hardware, sha)
+
+```bash
+hf spaces info hirokamitai/trenchlesspm
+```
+
+Look at `runtime.stage` (`RUNNING` / `BUILDING` / `STOPPED` / `SLEEPING`) and
+`runtime.raw.devMode`. **Dev mode must be `false` for the public URL to route
+to FastAPI** — when it's `true`, HF routes the URL to a dev IDE and every
+endpoint 404s (you'll see HF's HTML 404 page, not our JSON).
+
+### Restart / rebuild
+
+```bash
+# Toggle dev mode off (also forces a restart):
+hf spaces dev-mode hirokamitai/trenchlesspm --stop
+```
 
-The Space web UI: **Settings → Factory rebuild** (rebuilds image) or
-**Restart this Space** (just restarts the container). No CLI equivalent.
+Web UI alternatives: **Settings → Factory rebuild** (rebuilds image) or
+**Restart this Space** (just restarts the container).
 
 ### Tail logs
 
@@ -124,9 +159,10 @@ container boots and marker loads model weights from `/data`.
 
 When something's broken, try these in order:
 
-1. **Health check.** `curl https://hirokamitai-trenchlesspm.hf.space/health`. If this fails, the container is down or sleeping — check the Space's status badge on the web UI.
-2. **Tail the Space logs** in the web UI's Logs tab. Look for Python tracebacks, OOMs ("CUDA out of memory"), or marker model-load errors.
-3. **401 from `/parse`?** Verify the caller is sending `Authorization: Bearer <API_TOKEN>` and that the token matches the `API_TOKEN` Space secret. Re-set the secret if in doubt.
-4. **Quality mode failing but fast mode works?** Almost certainly `ANTHROPIC_API_KEY` is missing/expired or you're rate-limited. Check the Space secrets and the Anthropic console for usage/quota.
-5. **Cold starts re-download 5 GB every time?** The HF Bucket (`hirokamitai/trenchlesspm-cache`) isn't mounted, or `HF_HOME`/`TORCH_HOME` aren't pointing at `/data`. Verify the bucket is attached at `/data` in the Space's Storage Buckets settings and the Dockerfile's `ENV` lines are intact.
-6. **Cross-reference [DEPENDENCIES.md](DEPENDENCIES.md)** for status pages of HF and Anthropic if multiple things are broken at once.
+1. **Health check.** `curl https://hirokamitai-trenchlesspm.hf.space/health`. If this fails, the container is down, sleeping, or dev-mode is on.
+2. **HTML 404 (not our JSON 404) on every endpoint?** `hf spaces info hirokamitai/trenchlesspm` — check `runtime.raw.devMode`. If `true`, run `hf spaces dev-mode hirokamitai/trenchlesspm --stop` (or toggle in the UI). Same symptom can also mean the Space is private and the caller has no HF auth — the Space should be public.
+3. **Tail the Space logs** in the web UI's Logs tab. Look for Python tracebacks, OOMs ("CUDA out of memory"), or marker model-load errors.
+4. **401 from `/parse`?** Verify the caller is sending `Authorization: Bearer <API_TOKEN>` and that the token matches the `API_TOKEN` Space secret. Re-set the secret if in doubt.
+5. **Quality mode failing but fast mode works?** Almost certainly `ANTHROPIC_API_KEY` is missing/expired or you're rate-limited. Check the Space secrets and the Anthropic console for usage/quota.
+6. **Cold starts re-download 5 GB every time?** The HF Bucket (`hirokamitai/trenchlesspm-cache`) isn't mounted, or `HF_HOME`/`TORCH_HOME` aren't pointing at `/data`. Verify the bucket is attached at `/data` in the Space's Storage Buckets settings and the Dockerfile's `ENV` lines are intact.
+7. **Cross-reference [DEPENDENCIES.md](DEPENDENCIES.md)** for status pages of HF and Anthropic if multiple things are broken at once.

_project/SPEC.md

@@ -56,7 +56,7 @@ Not public, not multi-tenant.
 
 - Budget: pay-per-second GPU billing on A10 small. Target <$5/mo at expected volume.
 - Time: weekend build. Don't over-engineer.
-- Platform: Hugging Face Space, Docker SDK, A10 small GPU, persistent storage enabled
-  and mounted at `/data`.
-- Other: model cache must live on `/data` (HF persistent storage), not the ephemeral
-  container FS. Space configured to sleep after 15 min idle.
+- Platform: Hugging Face Space, Docker SDK, A10 small GPU, HF Bucket
+  (`hirokamitai/trenchlesspm-cache`) mounted at `/data`.
+- Other: model cache must live on `/data` (the HF Bucket mount), not the
+  ephemeral container FS. Space configured to sleep after 5 min idle.

_project/TODO.md

@@ -9,10 +9,10 @@ For "what's broken," also see CURRENT_STATE.md's known-issues section.
 
 ## Next up (doing soon, in order)
 
-1. Set `API_TOKEN` and `ANTHROPIC_API_KEY` as secrets on the `hirokamitai/trenchlesspm` Space (https://huggingface.co/spaces/hirokamitai/trenchlesspm/settings).
-2. Watch the Logs tab on the Space for the first Docker build (~5–10 min on first push).
-3. Hit `/health`, then run an end-to-end `/parse` on a sample contract in both `fast` and `quality` modes.
-4. Confirm cold starts after autosleep load weights from `/data` (no 5 GB re-download).
+1. Set `ANTHROPIC_API_KEY` on the Space (https://huggingface.co/spaces/hirokamitai/trenchlesspm/settings → Secrets). Required for `parse_mode=quality`.
+2. End-to-end smoke test: upload a real contract PDF and verify `{markdown, mode, page_count, duration_ms}` for both `fast` and `quality`.
+3. After the first parse, sleep the Space (or wait 5 min) and confirm cold start loads weights from the bucket — no 5 GB re-download in the Logs tab.
+4. Wire TrenchlessPM to call `/parse`, replacing LlamaParse. Document the integration on the TrenchlessPM side.
 
 ## Backlog (not prioritized)
 
@@ -23,9 +23,9 @@ For "what's broken," also see CURRENT_STATE.md's known-issues section.
 
 ## Ideas / maybe
 
-- Audit-trail bucket (deferred — see [DECISIONS.md](DECISIONS.md) 2026-04-28 entry). Revisit if a downstream caller ever needs replay.
+- External audit-trail bucket (deferred — see [DECISIONS.md](DECISIONS.md) "No external bucket"). Revisit if a downstream caller ever needs replay.
 - Multi-PDF batch endpoint, if a real workflow shows up that wants it.
-- Swap the LLM model used for `quality` mode (e.g. bump to Opus 4.7, or try Haiku 4.5 for cheaper) if Sonnet 4.6 output disappoints on contracts. Set via `CLAUDE_MODEL` env var, no code change.
+- Swap the Claude model used for `quality` mode (e.g. bump to Opus 4.7, or try Haiku 4.5 for cheaper) if Sonnet 4.6 output disappoints on contracts. Set via `CLAUDE_MODEL` env var, no code change.
 
 ---
 
@@ -33,6 +33,12 @@ For "what's broken," also see CURRENT_STATE.md's known-issues section.
 
 Keep the last ~10. Older items belong in [CHANGELOG.md](CHANGELOG.md).
 
+- 2026-04-28 — Deployed to `hirokamitai/trenchlesspm`. Public, dev-mode off, A10 small running. `/`, `/health`, `/parse`-401 verified live.
+- 2026-04-28 — Switched persistence to HF Bucket `hirokamitai/trenchlesspm-cache` mounted at `/data`. Cheaper than the older Persistent Storage tier.
+- 2026-04-28 — Set `API_TOKEN` as a Space secret via `huggingface_hub.add_space_secret`.
+- 2026-04-28 — Added `GET /` route so the Space URL doesn't 404 in a browser.
+- 2026-04-28 — Wired `parse_mode=quality` to Claude Sonnet 4.6 via marker's `ClaudeService` (was Gemini default).
+- 2026-04-28 — Streamed uploads to disk, added `page_count` + `duration_ms` to the `/parse` response, raised Uvicorn keep-alive to 30 min, lowered autosleep to 5 min.
 - 2026-04-28 — Filled in `_project/` docs (SPEC, ARCHITECTURE, DECISIONS, ENVIRONMENT, DEPENDENCIES, INFRASTRUCTURE, RUNBOOK).
 - 2026-04-28 — Installed `hf` CLI + the `hf-cli` skill globally for Claude Code.
 - 2026-04-28 — Scaffolded FastAPI app, Dockerfile, and HF Space README frontmatter.