Check a brief before filing

# Decosa Filing pre-flight: use the hosted API

You are wiring Decosa's filing pre-flight into this project. It takes a brief and the record excerpts it cites and runs
five checks: every cited case, statute and rule exists; the cited opinion supports what the brief says; record cites
resolve to the excerpts; quotations are verbatim; and no full SSN, birth date, financial-account number or minor's name
is left in (Fed. R. Civ. P. 5.2). Each proposition check is one model call with its own signed receipt, and the run ends
with a signed record. Use only what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- The hosted API is for public filings. A draft brief is confidential and may be privileged: for drafts, use the
  self-host prompt instead. The hosted service sends only citations to public case-law sources, never the text.
- It is a check, not legal advice: "ok" means found and matching, not that the argument is right. Say so wherever you
  show results.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "filing-preflight"}` returns `{"token", "expires_at", "budget"}`.
   The session's token allowance is its `budget`; how many sessions one network may start an hour is `demo_sessions` in
   `GET https://api.decosa.ai/healthz`. Over a limit: HTTP 429 with `Retry-After`.
3. One run at a time per demo token (409 otherwise).

## Endpoints
- `POST /preflight/parse?name=brief.pdf` (token): the raw file as the body (`application/pdf`, a .docx, or `text/plain`;
  up to 15 MB) → `{upload_id, kind, chars, text, redaction: {ran, pages: [{page, boxes, hidden_chars}]}}`. `hidden_chars`
  counts text still selectable under black boxes. The text is kept for one hour under `upload_id`.
- `POST /preflight/check` (token). Body:
  `{"text" | "upload_id" | "sample_id": "...", "record"?: [{"label": "App.", "text" | "upload_id": "...", "first_page"?: 1}], "authorities"?: [{"cite": "469 U.S. 325", "name"?: "...", "text": "..."}], "title"?: "...", "stream"?: true}`
  - Limits: brief up to 80,000 characters; up to 8 record excerpts (600,000 characters in all). Record labels are what
    the brief cites (`App.`, `J.A.`, `ECF No. 45`, `Ex. 7`, `Tr.`). Mark pages in pasted excerpts with lines like `[[212]]`;
    PDFs sent by `upload_id` keep their pages.
  - With `"stream": true` (or `Accept: text/event-stream`) it streams `ready` (every citation, quotation, proposition and
    record cite with its offsets in the brief), `stage`, `item` events (replace by `id`), a `receipt` after each model call,
    then `report`, `done` and `budget`. With `"stream": false`: one JSON object `{run_id, decision, totals, items, report, budget}`.
  - Each item: `{id, check: authority|proposition|record|quote|privacy, status: problem|review|unverified|ok|skipped, title, detail, start, end, ...}`.
    `problem` means positive evidence of an error; `review` needs a lawyer's eye; `unverified` means the free sources do
    not cover it (never treat it as ok).
- `GET /preflight/runs/{run_id}/export?format=md` → a Markdown review for the partner; `format=record` → the signed record.
- `POST /record/verify` (no token) `{"record": {...}}` → `{ok, summary, bad}`.
- `GET /preflight/info`, `GET /preflight/samples`, `GET /preflight/samples/{id}`, `GET /attest/signing-key` (no token).

Offsets are Python string indices (Unicode code points) into the brief as sent.

## Example: stop a filing with problems (Python, `pip install httpx`)
```python
import httpx, os, pathlib
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
up = httpx.post(f"{API}/preflight/parse?name=brief.pdf", content=pathlib.Path("brief.pdf").read_bytes(),
                headers={**H, "Content-Type": "application/pdf"}, timeout=120).json()
app = httpx.post(f"{API}/preflight/parse?name=appendix.pdf", content=pathlib.Path("appendix.pdf").read_bytes(),
                 headers={**H, "Content-Type": "application/pdf"}, timeout=120).json()
r = httpx.post(f"{API}/preflight/check", headers=H, timeout=900,
               json={"upload_id": up["upload_id"], "record": [{"label": "App.", "upload_id": app["upload_id"]}], "stream": False})
r.raise_for_status()
run = r.json()
for it in run["items"]:
    if it["status"] in ("problem", "review"):
        print(it["status"].upper(), it["check"], it["title"], "--", it.get("detail"))
pathlib.Path("preflight-review.md").write_text(httpx.get(f"{API}{run['export']['md']}", headers=H).text)
if run["decision"] == "problems":
    raise SystemExit("do not file: fix the problems first")
```

## Honest limits
- It does not check whether a case is still good law (no citator), and free sources miss Westlaw/Lexis-only decisions,
  many unpublished orders, agency decisions and state codes: those come back `unverified`.
- Proposition verdicts come from an open model and are a triage list; see the measured rates on the Stack tab.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa Filing pre-flight: run it yourself (containers)

You are setting up the Decosa filing pre-flight on this machine, so draft briefs never leave it. It checks a brief's
citations, quotations, record cites and Rule 5.2 identifiers and signs a record. Nothing is sent to Decosa's hosted API.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/filing-preflight.zip (6 KB, 12 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py filing-preflight` (the api image carries the same bundle under /app/rehearsal/filing-preflight/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py filing-preflight --bundle filing-preflight.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the Word file is read as a brief", "the appendix PDF is read and its redaction check runs", "the pre-flight decision is: problems"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
   instructions for this distribution (docs.docker.com/engine/install). For the GPU judge, also install the NVIDIA
   container toolkit and check `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
   `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
   Read it. Keep the `llm` service (Qwen3.8-27B on vLLM) and the `api` service. For the `api` service set
   `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b` and bind every port to
   127.0.0.1. Ask me whether citation lookups may go out (only the citations are sent, to static.case.law,
   courtlistener.com, uscode.house.gov, ecfr.gov and law.cornell.edu). If not, set `DECOSA_PREFLIGHT_OFFLINE=1`: cases are
   then checked only against opinion texts I send in `authorities`, or a local mirror of the Caselaw Access Project
   (`DECOSA_PREFLIGHT_CAP_BASE`). Without a GPU, set `DECOSA_PREFLIGHT_JUDGE=off` (no proposition check).
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
   downloads about 20 GB of weights).
4. Check: `curl -fsS http://127.0.0.1:<PORT>/preflight/info` lists the five checks, `offline` and `judge`;
   `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify my records.
5. Smoke test: get a token with `POST /demo/session {"vertical":"filing-preflight"}` and run
   `POST /preflight/check {"sample_id": "demo-planted", "stream": false}`. With lookups on, expect `decision: "problems"`
   with the invented Varghese cite, the one-word T.L.O. misquote, the Redding holding, App. 4 and App. 9, and the SSN,
   birth date, account number and minor's name. Then `POST /record/verify` with `report.record`: `ok` must be true.
6. Report back: the public key and key id, the smoke-test decision and totals, and how long the run took.

Off by default. Joining as a provider serves other people's requests on this GPU; never do it on a box that holds
client drafts. If I ask for it later, follow the Provide page instead of improvising.

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 48 GB of unified memory or more): use https://decosa.ai/prompts/filing-preflight-mac.md instead.