Write a due-diligence red-flag memo

# Assemble Decosa M&A due-diligence red flags on this machine

You are setting up a self-hosted due-diligence red-flag review on this Linux machine for a deal team or law firm. It
reads a data room as text (contracts, board minutes, the disclosure schedule, revenue by customer, financial summaries)
and returns:
- a red-flag memo for counsel: for ten categories (change of control, anti-assignment, exclusivity and non-compete, MFN
  pricing, uncapped liability, debt covenants, IP assignment gaps, litigation missing from the disclosure schedule,
  customer concentration, key person), each flag with the exact words quoted, the document, chunk and byte span, why it
  matters and what to ask the seller;
- a signed, hash-chained record of hashes: every document, the retrieval index hash, every search receipt id, every
  flag's byte span and quote hash, and every model receipt id.

Work step by step, show me each command before running anything that needs sudo, and stop if a check fails.

**Before anything else, remind me:**
- Data rooms are under NDA. On this box nothing leaves the machine: the language model, the retrieval models and the
  checks all run here. Never point it at a hosted gateway while it holds a real room.
- This is a triage aid for counsel, not legal advice. "No flag found" means nothing turned up in the passages searched,
  not that the room is clean.

Repeat both points in your final summary.

## 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/ma-dd-redflags.zip (16 KB, 13 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 ma-dd-redflags` (the api image carries the same bundle under /app/rehearsal/ma-dd-redflags/;
   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 ma-dd-redflags --bundle ma-dd-redflags.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 customer MSA's change-of-control termination right is flagged", "the demand letter in the March minutes, missing from the disclosure schedule, is flagged", "the covenant breach is flagged with the figure"). 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.

## What you are building

| service | image | model | port |
|---|---|---|---|
| `llm` | `${DECOSA_REGISTRY}/decosa-llm:0.1.0` (vLLM 0.29.0, `vllm/vllm-openai@sha256:c2914767605584b6d8f45686b82de173ecc99e781897aa3d0a66dacd72c51ae1`) | `nvidia/Qwen3.8-27B-NVFP4` @ `482ca0f3832238542f8f5295dde86b5f22711d80`, Apache-2.0 | internal 8000 |
| `retrieval` | built from `decosa-api/services/retrieval` | `Qwen/Qwen3-Embedding-0.6B` @ `97b0c614be4d77ee51c0cef4e5f07c00f9eb65b3` + `Qwen/Qwen3-Reranker-4B` @ `22e683669bc0f0bd69640a1354a6d0aebcfeede5`, Apache-2.0 | internal 8499 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` (no GPU) | none | `127.0.0.1:8445` |

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. I need one NVIDIA GPU with at least 48 GB (the model about 20 GB plus KV cache, the retrieval
   models about 10 GB) and driver 580 or newer.
   - Blackwell (RTX PRO 6000, B200): use the defaults below (NVFP4). This is the measured setup.
   - Hopper (H100/H200) or 48 GB Ada/L40S: set `LLM_MODEL=Qwen/Qwen3.8-27B-FP8`, `LLM_REVISION=main` and
     `LLM_GPU_UTIL=0.70`; on 48 GB also `LLM_MAX_LEN=32768`. Not measured.
   - Under 48 GB: tell me, and use the BM25 option in step 3 (no `retrieval` service).
2. Check `docker --version`, `docker compose version` and `docker run --rm --gpus all ubuntu nvidia-smi`. If Docker or the
   NVIDIA Container Toolkit is missing, install them from the official Docker and NVIDIA repositories, run
   `sudo nvidia-ctk runtime configure --runtime=docker` and restart Docker.
3. Confirm about 80 GB of free disk.

## 2. Get the images and the source

The images are **on request** while self-host is in early access: ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry (set it as `DECOSA_REGISTRY`), pull access and the compose file. Try `docker pull ${DECOSA_REGISTRY}/decosa-{llm,api}:0.1.0`. If a pull
fails, build from source once `decosa-api` is published: clone it into `~/decosa-dd/decosa-api`, run
`docker build -f docker/api/Dockerfile -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`, and `docker compose build llm` from
its compose file. If neither works, stop and tell me. The `retrieval` service is always built from the clone
(`services/retrieval`), so clone it either way.

## 3. Write the compose file

Create `~/decosa-dd/.env`:

```bash
DECOSA_TAG=0.1.0
DECOSA_GPU=0
LLM_MODEL=nvidia/Qwen3.8-27B-NVFP4
LLM_REVISION=482ca0f3832238542f8f5295dde86b5f22711d80
LLM_MAX_LEN=65536
LLM_GPU_UTIL=0.72
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example LLP deal team>"
```

Create `~/decosa-dd/docker-compose.yml` with exactly these services:

```yaml
name: decosa-dd
x-health: &health
  interval: 15s
  timeout: 5s
  retries: 5
services:
  llm:
    image: ${DECOSA_REGISTRY}/decosa-llm:${DECOSA_TAG}
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    ipc: host
    restart: unless-stopped
    volumes: [hf-cache:/root/.cache/huggingface]
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b",
              "--language-model-only", "--max-model-len", "${LLM_MAX_LEN}", "--gpu-memory-utilization", "${LLM_GPU_UTIL}",
              "--max-num-seqs", "16", "--kv-cache-dtype", "fp8_e4m3", "--speculative-config", '{"method":"mtp","num_speculative_tokens":3}',
              "--seed", "0", "--enable-force-include-usage", "--disable-uvicorn-access-log", "--host", "0.0.0.0", "--port", "8000"]
    healthcheck: { <<: *health, test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=4)"], start_period: 900s }
  retrieval:
    build:
      context: ./decosa-api/services/retrieval
      dockerfile_inline: |
        FROM python:3.12-slim
        WORKDIR /app
        COPY requirements.txt .
        RUN pip install --no-cache-dir -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cu130
        COPY *.py .
        CMD ["python", "server.py"]
    deploy: { resources: { reservations: { devices: [ { driver: nvidia, device_ids: ["${DECOSA_GPU:-0}"], capabilities: [gpu] } ] } } }
    restart: unless-stopped
    environment:
      RETRIEVAL_HOST: 0.0.0.0
      RETRIEVAL_PORT: "8499"
      RETRIEVAL_EMBED: qwen3-emb-0.6b
      RETRIEVAL_RERANK: qwen3-rr-4b
      HF_HOME: /root/.cache/huggingface
    volumes: [hf-cache:/root/.cache/huggingface]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8499/health', timeout=4)"], start_period: 600s }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy }, retrieval: { condition: service_healthy } }
    environment:
      DECOSA_LLM_ROUTE: direct                  # local model only; receipts are signed by this box's key ("attested")
      DECOSA_LLM_URL: http://llm:8000/v1
      DECOSA_LLM_MODEL: qwen3.8-27b
      DECOSA_LOCAL_SIGNING: "on"                # Ed25519 key created at /data/attest/ed25519.pem on first start
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_RETRIEVAL_URL: http://retrieval:8499
      DECOSA_MADD_SYNTHETIC_ONLY: "0"           # this box accepts real data rooms
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "400000"        # per session; a full review uses about 7,500 generated tokens
      DECOSA_SESSION_TTL_S: "28800"
      DECOSA_CORS_ORIGIN_REGEX: '^https?://(localhost|127\.0\.0\.1)(:\d+)?$$'
    ports: ["127.0.0.1:8445:8445"]
    volumes: [decosa-data:/data]
    healthcheck: { <<: *health, test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8445/healthz', timeout=4)"], start_period: 20s }
volumes: { hf-cache: {}, decosa-data: {} }
```

The retrieval service downloads its two models (about 9 GB) into the shared `hf-cache` volume on first start. It uses
the pinned revisions in `services/retrieval/models.py`.

**No room for the retrieval models?** Delete the `retrieval` service and its `depends_on` entry, drop
`DECOSA_RETRIEVAL_URL`, and add `DECOSA_MADD_RETRIEVAL: bm25` to the api. Passages are then picked by keyword search
only; the quote gate, grounding and record are unchanged.

Use the named volume `decosa-data` exactly as written: a root-owned host bind mount makes the API fail on
`/data/keys.sqlite`.

Run `docker compose up -d --build`, then poll `docker compose ps` until every service is healthy (the LLM takes 5-10
minutes the first time). `curl -s localhost:8445/madd/info | jq '{synthetic_only, retrieval}'` should show
`synthetic_only: false` and `service_reachable: true`.

## 4. Smoke test on the bundled invented rooms

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"ma-dd-redflags"}' | jq -r .token)
curl -s $API/madd/review -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"kestrel"}' > /tmp/dd.json
jq -r '.flags[] | "\(.severity)\t\(.category)\t\(.doc)\t\(.quote[0:70])"' /tmp/dd.json
jq '{record}' /tmp/dd.json | curl -s $API/record/verify -H 'content-type: application/json' -d @- | jq '{ok, summary}'
curl -s $API/madd/review -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"sample":"linnet"}' | jq '.counts'
```

Pass if Kestrel gives at least ten flags, including a change-of-control flag in `MSA-BRI`, an undisclosed-litigation
flag in `MIN-2026Q1`, a debt-covenant flag quoting `3.42x` and a customer-concentration flag in `REV-FY2025`, none in
`NDA-BRI`; every receipt is `attested`; the record verifies; and the clean Linnet room gives at most one flag.

## 5. Review a real room

Put each document in a text file (convert PDFs first; scanned ones through the document reader), then:

```bash
python3 - <<'PY' > room.json
import json, pathlib
docs = [{"id": p.stem[:60], "title": p.name, "text": p.read_text()} for p in sorted(pathlib.Path("room").glob("*.txt"))]
print(json.dumps({"room": {"target": "Example Widgets, Inc.", "buyer": "Example Holdings", "documents": docs}}))
PY
curl -s $API/madd/review -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d @room.json > review.json
jq -r .markdown review.json > red-flag-memo.md
jq .record review.json > red-flag-record.json
```

Limits per run: 40 documents, 60,000 characters each, 400,000 in all. Split a bigger room by folder (contracts, corporate,
finance) and run each.

## 6. Point tools at the local API

- Base URL `http://localhost:8445`; for a web app set `NEXT_PUBLIC_DECOSA_API=http://localhost:8445`.
- `POST /madd/review` returns JSON, or Server-Sent Events with `Accept: text/event-stream`. `GET /madd/info` lists the
  categories with their definitions and near-miss rules.
- Keep the memo and the record with the deal file. Anyone can re-check the record with `POST /record/verify` against the
  key at `GET /attest/signing-key`.
- Keep the API on 127.0.0.1; for other users, put a TLS reverse proxy with authentication in front.

## 7. Keep the direct route

`DECOSA_LLM_ROUTE=gateway` would send the room's passages to the hosted Decosa
API. Leave it off for real data rooms.

Finish with a summary: what is running, the health output, the smoke-test results, and the reminders above.