Log human edits and editor sign-off

# Decosa editorial-control ledger: use the hosted API

You are wiring Decosa's editorial-control ledger into our publishing workflow. For each article it keeps the AI first
draft (written by an open model with a signed receipt, or by our own AI tool), every human save as a diff with edit
metrics, the claims each edit added or removed, and a named editor's sign-off, in one signed, hash-chained record. Each
published piece gets a public page that checks the record in the reader's browser. 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`.
- What it proves: which text the model wrote, each saved change, who says they reviewed which exact version and when, and
  that none of it changed after signing. It does not prove the editor's identity or that the review was careful.

## Auth
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page, in the 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": "editorial-ledger"}` returns `{"token", "expires_at", "budget"}`
   (a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz), 20,000 generated tokens each). A piece is visible only to the key or token that made it.

## The flow (one article)
1. `POST /editorial/pieces` `{"title", "assignment"?, "desk"?, "responsibility": "The publication that holds editorial responsibility", "sources": [{"title", "text", "url"?}], "external_id"?}`
   → `{piece_id, ...}`. Up to 6 sources, 20,000 characters each.
2. The AI draft, either:
   - `POST /editorial/pieces/{id}/draft` `{}` → the model writes it from the sources: `{text, receipt, usage, ...}`. With
     `"stream": true` or `Accept: text/event-stream`: `ready`, `receipt`, `draft`, `budget`, `done`. Or
   - `POST /editorial/pieces/{id}/draft` `{"text" | "html", "model": "our-tool"}` for a draft our own AI tool wrote. It is
     recorded as `unreceipted`: the ledger then shows what we said the model wrote.
3. Every save: `POST /editorial/pieces/{id}/revisions` `{"text" | "html", "editor": {"name", "role"?}, "base_sha256"?, "active_ms"?}`
   → `{rev, text_sha256, metrics_draft, metrics_prev}`. Send the full text each time. `base_sha256` (the previous version's
   hash) makes a concurrent save fail with 409 instead of silently branching.
4. Optional: `POST /editorial/pieces/{id}/claims` `{}` → `{items: [{removed: [...], added: [...], old, new}], removed, added, receipts}`:
   the claims the latest version dropped from or added to the AI draft (one receipted model call).
5. Sign-off: `POST /editorial/pieces/{id}/signoff` `{"editor": {"name", "role"?}, "decision": "approve" | "label", "final_sha256"}`.
   `final_sha256` must be the latest version's hash; after sign-off no more revisions are accepted.
6. Publish: `POST /editorial/pieces/{id}/publish` `{"url"?, "public_draft": false}` → `{record, check, public_id, label, label_text, reason, verify_url, credential}`.
   The piece is labelled as AI-generated when nobody signed off or the editor chose `label`. Put `label_text` on the
   article when `label` is true, and link `verify_url` from the article.

## One webhook for a CMS
`POST /editorial/hooks/cms` with `{"event": "create" | "draft" | "revision" | "signoff" | "publish", "external_id": "<our article id>", ...}`
and the same fields as the routes above. Call `revision` on every save (text or HTML).

## Example (Python, `pip install httpx`)
```python
import hashlib, httpx, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
c = httpx.Client(base_url=API, headers=H, timeout=120)
p = c.post("/editorial/pieces", json={"title": "Council approves ferry terminal upgrade", "responsibility": "Our Paper",
           "sources": [{"title": "Council release", "text": open("release.txt").read()}]}).raise_for_status().json()
d = c.post(f"/editorial/pieces/{p['piece_id']}/draft", json={}).raise_for_status().json()
edited = d["text"].replace("has approved", "approved")          # the editor's change, from our CMS
r = c.post(f"/editorial/pieces/{p['piece_id']}/revisions", json={"text": edited, "editor": {"name": "Dana Okafor", "role": "Editor"}}).raise_for_status().json()
print(r["metrics_draft"]["changed_share"], r["metrics_draft"]["depth"])
c.post(f"/editorial/pieces/{p['piece_id']}/signoff", json={"editor": {"name": "Dana Okafor"}, "decision": "approve",
       "final_sha256": hashlib.sha256(edited.encode()).hexdigest()}).raise_for_status()
out = c.post(f"/editorial/pieces/{p['piece_id']}/publish", json={"url": "https://example.org/ferry"}).raise_for_status().json()
print(out["label"], out["verify_url"])
```

## Verify
- `GET https://api.decosa.ai/editorial/p/{public_id}` (no token) → the published record and its check.
- `POST https://api.decosa.ai/editorial/verify` `{"public_id" | "record", "text"?}` (no token) checks the chain, the draft's receipt,
  the signature and the ledger rules, recomputes the metrics, and says whether `text` is the signed final version.
- `GET https://api.decosa.ai/editorial/p/{public_id}/credential.docx`: the published text as a DOCX with a C2PA credential
  (development certificate: validators show the issuer as untrusted).

## Honest limits
- The claim list is a model's reading; it can miss or over-count. The metrics measure how much changed, not how well.
- Hosted retention: open pieces 7 days, published ledgers 30 days. Keep the record JSON yourself.
- Whether a review meets the EU AI Act Art. 50(4) exception is our call, not the API's.

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 editorial-control ledger: run it yourself (containers)

You are setting up Decosa's editorial-control ledger on this machine, so unpublished drafts, embargoed copy and our
edit history stay here. The ledger (decosa-api) needs no GPU. Qwen3.8-27B is only needed if the model should write the
AI draft here (receipted) and list the claims each edit changed; if our CMS's own AI tool writes drafts, run the ledger
alone. 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.

Hardware: any Linux x86_64 machine for the ledger; 1x RTX 5090 32 GB or larger for Qwen3.8-27B (NVFP4). 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/editorial-ledger.zip (4 KB, 9 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 editorial-ledger` (the api image carries the same bundle under /app/rehearsal/editorial-ledger/;
   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 editorial-ledger --bundle editorial-ledger.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 model writes a first draft from the sources", "the edit is recorded as a substantial rewrite (over 20% of words changed)", "the claim check answered every item"). 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.

## Rules you must keep
- Bind every port to 127.0.0.1. Only the public ledger page and `GET /editorial/p/*` may be exposed, and only through a
  proxy I approve.
- The signing key is created on first start in the data volume (`attest/ed25519.pem`, 0600). Back it up; never print it.
  Publish its public key (`GET /attest/signing-key`) so readers can pin it.
- Retention: `DECOSA_EDITORIAL_TTL_S` (open pieces, default 7 days) and `DECOSA_EDITORIAL_PUBLIC_TTL_S` (published
  ledgers, default 30 days). Set them to our policy and archive sealed records ourselves; they verify offline.

## Steps
1. Docker (and the NVIDIA Container Toolkit if you run the model): if `docker compose version` fails, install it from
   the official Docker instructions.
2. Fetch the compose file: `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`. Read it.
   Keep the `api` service; keep `llm` only if the model should draft and check claims. The api's data goes in a named
   volume, not a host folder.
3. In `.env`: `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b` (with `llm`),
   `DECOSA_ADMIN_SECRET` (a long random string, file mode 0600), `DECOSA_SITE_URL` (where our public ledger page lives).
4. Start: `docker compose pull && docker compose up -d`. Wait for `curl -fsS http://localhost:<PORT>/healthz`.
5. Mint a key for the CMS: `POST /v1/keys` with the admin secret and `{"label": "cms", "verticals": ["editorial-ledger"]}`.
6. Smoke test with a token from `POST /demo/session {"vertical": "editorial-ledger"}`: take the `ferry-terminal` sample
   from `GET /editorial/samples`, create a piece, draft it (`POST .../draft {}`; without `llm`, send `{"text": ...}`
   instead), save one revision, check claims (with `llm`), sign off, publish. Expect `check.ok: true`; the draft entry's
   receipt status is `attested` (signed by this box's key: an attestation by me, not a gateway receipt).
7. `POST /editorial/verify {"public_id": ...}` must say `ok: true`. Download the record, change one word of the draft,
   and verify it again: it must fail at "AI draft".
8. Report back: health, the signing key id, the smoke-test summary and the time each step took.

## C2PA credential (optional)
`GET /editorial/p/<id>/credential.docx` needs the `provenance` extra (c2pa-python) in the image and a signing
certificate in `DECOSA_PROVENANCE_DIR`. Without them it answers 503 and everything else works. A certificate from your
own CA shows as "untrusted" in public validators.

Off by default. Leave it off unless I ask.

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