---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-web-choices-runbook"
title: "Web Choices server and submission runbook"
---

# Web Choices server and submission runbook

Use this for agent-generated option lists that the user should review in a clean, polished, interactive browser experience or on a phone.

The durable implementation lives in this skill directory:

```text
~/.agents/skills/web-choices
```

Agents must launch the skill-local CLI from any project and must store runtime state in a caller-selected `HITL_OUT_DIR`, usually `$PWD/.hitl-choice`.

## Non-Negotiables

- The browser UI must be compiled from Svelte and mdsvex sources in this skill.
- At least one `.svx` route or template must be part of the served choice experience.
- A plain generated HTML form, static DOM script, or one-off Markdown page is not an acceptable implementation.
- Oracle-generated choices remain strict JSON data. Do not compile Oracle/user option strings as Svelte or mdsvex source.
- `current-job.json`, drafts, and submissions remain the durable source of truth.
- The app must run from any project. Do not hardcode `script-kit-gpui`.
- Do not overwrite an active current job without inspecting status and requiring explicit replacement.
- Keep the HITL server alive in `tmux`; do not stop it after sending the URL.
- Wait for the saved submission before continuing. The local wait defaults to no timeout.

## Generate Choices With Oracle

For repo-aware lists, use `$oracle-packx` and include process docs plus relevant source/tests. For large context, use Oracle browser attachments rather than inline-only prompts.

Oracle generation is blocking. After starting the Oracle choice-list request, do not draft choices locally, publish a partial job, or continue until Oracle has completed and the local Oracle response has been read.

Ask Oracle for a strict JSON job:

```json
{
  "jobId": "short-stable-id",
  "title": "Human-readable title",
  "description": "What the user is choosing",
  "createdAt": "ISO timestamp",
  "options": [
    {
      "id": "stable-option-id",
      "title": "Short option title",
      "description": "Concrete choice text",
      "tags": ["optional"],
      "surface": "optional area",
      "goal": "optional goal",
      "risk": "optional risk",
      "suggestedProofCommands": ["optional command"],
      "expectedEvidence": {
        "pass": "optional pass signal",
        "fail": "optional fail signal"
      }
    }
  ]
}
```

If a selected option later fails verification, ask Oracle again with a Prior-State Ledger and Forward Progress Gate describing the failure, selected option, logs, and what has already been tried.

## Build And Serve The mdsvex Choice Experience

The skill-local app is a Bun + Vite + Svelte + mdsvex app. mdsvex owns the page/template shell; Svelte components own filters, cards, selection state, feedback fields, save status, and submission controls. Runtime data remains JSON-driven.

From any project:

```bash
export WEB_CHOICES_SKILL_DIR="$HOME/.agents/skills/web-choices"
export HITL_OUT_DIR="$PWD/.hitl-choice"
export HITL_HOST="127.0.0.1"
export HITL_PORT="8877"

bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" server \
  --out-dir "$HITL_OUT_DIR" \
  --host "$HITL_HOST" \
  --port "$HITL_PORT" \
  --tmux
```

The server writes or reuses `$HITL_OUT_DIR/.token`. Read the token from that file or from the server status.

Confirm the server is alive:

```bash
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" status \
  --out-dir "$HITL_OUT_DIR" \
  --url "http://127.0.0.1:$HITL_PORT" \
  --token-file "$HITL_OUT_DIR/.token"
```

Push the Oracle-generated job:

```bash
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" push /path/to/job.json \
  --url "http://127.0.0.1:$HITL_PORT" \
  --token-file "$HITL_OUT_DIR/.token"
```

Use `--replace` only after inspecting active job status and confirming replacement is safe.

Start and verify Tailscale Funnel by default:

```bash
tailscale funnel --bg --yes "$HITL_PORT"
tailscale funnel status
curl -s "https://<your-tailnet-host>.ts.net/api/jobs/current?token=$(cat "$HITL_OUT_DIR/.token")"
```

Give the user the public URL only after the public API returns the expected `jobId` and option count:

```text
https://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>
```

Tell the user the server is staying open, drafts are saved server-side, and you are waiting for their submission.

## Wait And Resume

Wait locally without a timeout unless the user asks otherwise:

```bash
bun "$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts" wait \
  --job "<jobId>" \
  --out-dir "$HITL_OUT_DIR"
```

Persisted sources of truth:

- `$HITL_OUT_DIR/current-job.json`
- `$HITL_OUT_DIR/drafts/`
- `$HITL_OUT_DIR/submissions.jsonl`
- `$HITL_OUT_DIR/submissions/<submissionId>.json`

After submission, report the `submissionId`, selected count, selected option IDs/titles, per-option feedback, overall feedback, and saved file path. Continue from saved JSON, not memory.

## Verification

Before giving the user the URL, verify:

- `bun run build` succeeds in `~/.agents/skills/web-choices`.
- The current page is served from compiled Svelte/mdsvex output.
- The public or local API returns the expected `jobId` and option count.
- Desktop and phone-width rendering are usable.
- Draft saving and final submit persist JSON under `HITL_OUT_DIR`.

## Failure Prevention

- If the tunnel fails, keep the same server/job/token when possible and restart Funnel; do not regenerate choices unless asked.
- If the server dies, inspect `HITL_OUT_DIR` first, restart with the same token, and verify drafts/submissions still exist.
- If the user says they submitted but wait has not returned, check `submissions.jsonl`, per-submission files, server logs, and `/api/jobs/<jobId>/submissions/status?token=<token>`.
- If laptop sleep or network loss is possible, say the server is durable while the machine and Tailscale are online; leave the `tmux` session running.
- Do not expose sensitive choices over a public Funnel URL without user approval. The token gates access but is not full authentication.

## Operational boundaries

- The bundle includes the skill instructions, not the complete runnable Svelte/mdsvex app. Install or locate the implementation before using its CLI paths. Funnel exposes the service publicly; token-bearing links are not full authentication.

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
