Find accessibility fixes for a shop

# Assemble the Decosa storefront accessibility pass on this machine

You are setting up a self-hosted accessibility pass for an online shop on this Linux machine, for the shop's team or
the agency that builds it. For up to five pages of a shop it:
- runs axe-core's automated WCAG 2.2 A and AA rules in a private headless Chromium;
- tries add-to-cart and the checkout with the keyboard alone (reachable, answers Enter or Space, focus visible, no trap)
  and submits empty forms to read their error messages (never a real order: non-GET requests are blocked);
- asks Qwen3.8-27B with vision what a rule engine cannot: is the alt text right for this image, are link and button
  names clear in context, does each error message say how to fix the field, is an offer only inside an image;
- returns a fix list ranked by what blocks a purchase, each finding with its WCAG success criterion and a code fix, and a
  signed record of what was checked.

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:**
- This is an audit aid, not a certification and not a statement that the site conforms to WCAG, the ADA or the European
  Accessibility Act. Automated rules and model judgements miss things; a person reviews every finding. Not legal advice.
- Staging sites and pages behind a login stay on this machine: the model route stays local (`direct`).
- Only audit sites I own or have permission to test.

Repeat these 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/storefront-accessibility-pass.zip (58 KB, 8 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 storefront-accessibility-pass` (the api image carries the same bundle under /app/rehearsal/storefront-accessibility-pass/;
   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 storefront-accessibility-pass --bundle storefront-accessibility-pass.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: "Add to cart, a div the keyboard cannot reach, is found and ranked first (P1)", "the quantity field without a label is found by the rule engine", "the packshot's alt text, which calls the orange can purple, is flagged by the model"). 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, **with its vision tower** | internal 8000 |
| `api` | `${DECOSA_REGISTRY}/decosa-api:0.1.0` built **with `WITH_BROWSER=1`** (headless Chromium, BSD-3-Clause; Playwright, Apache-2.0; axe-core 4.13.0, MPL-2.0, vendored in the package) | none | `127.0.0.1:8445` |

The browser, axe-core, the keyboard and form passes, the fix list and the record run on CPU. Without the model you can
still run the rules, keyboard and form passes (`"judge": false`).

## 1. Check the GPU, driver and Docker

1. Run `nvidia-smi`. You need one NVIDIA GPU with at least 64 GB (the measured setup is an RTX PRO 6000 96 GB) and driver
   580 or newer.
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 repositories
   (`sudo nvidia-ctk runtime configure --runtime=docker`, then restart Docker).
3. Confirm about 70 GB of free disk.

## 2. Get the images

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.
1. Try `docker pull ${DECOSA_REGISTRY}/decosa-llm:0.1.0`.
2. Build the api image with the browser from the `decosa-api` source (once published):
   `docker build -f docker/api/Dockerfile --build-arg WITH_BROWSER=1 -t ${DECOSA_REGISTRY}/decosa-api:0.1.0 .`
   (`WITH_BROWSER=1` is required: without it `GET /a11y/info` reports `browser_available: false` and audits return 503).
3. If none of this works, stop and tell me.

## 3. Write the compose file

Create `~/decosa-a11y/.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.80
DECOSA_SIGNER_NAME="<who signs these records, e.g. Example Shop web team>"
DECOSA_ADMIN_SECRET=<a long random string; keep this file mode 0600>
# hosts this box may audit without DNS verification, e.g. staging.example-shop.com,localhost
AUDIT_HOSTS=
```

Create `~/decosa-a11y/docker-compose.yml`:

```yaml
name: decosa-a11y
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]
    # no --language-model-only: the pass sends one image per alt-text call
    command: ["${LLM_MODEL}", "--revision", "${LLM_REVISION}", "--served-model-name", "qwen3.8-27b",
              "--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}',
              "--limit-mm-per-prompt", '{"image":4,"video":0}', "--seed", "0", "--enable-force-include-usage", "--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 }
  api:
    image: ${DECOSA_REGISTRY}/decosa-api:${DECOSA_TAG}
    restart: unless-stopped
    depends_on: { llm: { condition: service_healthy } }
    shm_size: 1gb                               # Chromium needs more than Docker's 64 MB default
    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"
      DECOSA_SIGNER_NAME: ${DECOSA_SIGNER_NAME}
      DECOSA_ADMIN_SECRET: ${DECOSA_ADMIN_SECRET}
      DECOSA_TESTRUNS_TARGETS: ${AUDIT_HOSTS}   # shared with test runs: hosts audited without domain verification
      DECOSA_TESTRUNS_ALLOW_PRIVATE: "1"        # lets those hosts resolve to private addresses (staging on your LAN)
      DECOSA_A11Y_MAX_CONCURRENT: "2"
      DECOSA_SESSIONS_PER_IP_HOUR: "1000"
      DECOSA_BUDGET_LLM_TOKENS: "200000"
      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: {} }
```

Use the named volumes as written: a host bind mount owned by root makes the API fail on `/data/keys.sqlite` (the api image
owns `/data`).

## 4. Start it

1. `docker compose up -d`, then poll `docker compose ps` until both are healthy (the LLM takes 5-10 minutes the first time).
2. `curl -s localhost:8445/a11y/info | jq '{browser_available, axe_core, route: .models.route}'`: `browser_available: true`,
   axe-core `4.13.0` with licence `MPL-2.0`, route `direct`.

## 5. Smoke test

```bash
cd ~/decosa-a11y && docker compose exec api python scripts/rehearse.py storefront-accessibility-pass --base-url http://127.0.0.1:8445
```

Then run the two sample shops by hand:

```bash
API=localhost:8445
TOKEN=$(curl -s $API/demo/session -H 'content-type: application/json' -d '{"vertical":"storefront-accessibility-pass"}' | jq -r .token)
for s in shop-with-issues clean-shop; do
  curl -s $API/a11y/audit -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
    -d "{\"sample_id\":\"$s\",\"stream\":false}" | jq -c '{s: .summary, calls: .model_calls}'
done
```

Pass if `shop-with-issues` has P1 findings (Add to cart is a `<div>` the keyboard never reaches; the newsletter dialog
traps focus) plus alt-text, name and error-message findings from the model; `clean-shop` has no findings; the record in
each result verifies at `POST /record/verify`; every model receipt is `attested`.

## 6. Audit your own shop

- Mint a key: `KEY=$(curl -s -XPOST $API/v1/keys -H "authorization: Bearer $DECOSA_ADMIN_SECRET" -H 'content-type: application/json' -d '{"label":"a11y","verticals":["storefront-accessibility-pass"]}' | jq -r .key)`.
- Put the host in `AUDIT_HOSTS` (step 3; `http://` is allowed for a listed host) and restart the api. Then:
  `curl -s $API/a11y/audit -H "authorization: Bearer $KEY" -H 'content-type: application/json' -d '{"urls":["https://staging.example-shop.com/","https://staging.example-shop.com/products/one","https://staging.example-shop.com/cart"],"stream":false}'`
  Up to five pages on one origin. Add `"mobile": true` for a 390 px viewport.
- Without `AUDIT_HOSTS`, prove the domain first: `POST /a11y/domains {domain}` returns a token to publish as a DNS TXT
  record at `_decosa-challenge.<domain>` or at `/.well-known/decosa-verify.txt`, then `POST /a11y/domains/check`.
- A page you can't reach from this box can be pasted: `{"html": "...", "synthetic": true}` (the browser has no network
  then, so inline the images as `data:` URLs if you want them judged).

## 7. Point your tools at it

- The console on the Decosa site talks to `NEXT_PUBLIC_DECOSA_API`; set it to `http://127.0.0.1:8445` for a local build.
- In CI, run the pass on every theme release and fail the build on new P1 findings; keep each signed record with the
  release.