{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-web-choices-runbook",
  "slug": "web-choices-runbook",
  "title": "Web Choices server and submission runbook",
  "summary": "Oracle-generated strict JSON choices served through a skill-local Svelte/mdsvex app, with Tailscale Funnel, persistent drafts/submissions, blocking wait-and-resume, verification, and recovery safeguards.",
  "category": "Tools",
  "tags": [
    "web-choices",
    "persistence",
    "runbook"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Non-Negotiables",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Generate Choices With Oracle",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Build And Serve The mdsvex Choice Experience",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Wait And Resume",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Verification",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Failure Prevention",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 827,
  "url": "/topics/codex-web-choices-runbook/",
  "markdownUrl": "/markdown/codex-web-choices-runbook.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-web-choices-runbook.json",
  "headings": [
    {
      "id": "non-negotiables",
      "text": "Non-Negotiables",
      "level": 2
    },
    {
      "id": "generate-choices-with-oracle",
      "text": "Generate Choices With Oracle",
      "level": 2
    },
    {
      "id": "build-and-serve-the-mdsvex-choice-experience",
      "text": "Build And Serve The mdsvex Choice Experience",
      "level": 2
    },
    {
      "id": "wait-and-resume",
      "text": "Wait And Resume",
      "level": 2
    },
    {
      "id": "verification",
      "text": "Verification",
      "level": 2
    },
    {
      "id": "failure-prevention",
      "text": "Failure Prevention",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Web Choices server and submission runbook\n\nUse this for agent-generated option lists that the user should review in a clean, polished, interactive browser experience or on a phone.\n\nThe durable implementation lives in this skill directory:\n\n```text\n~/.agents/skills/web-choices\n```\n\nAgents 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`.\n\n## Non-Negotiables\n\n- The browser UI must be compiled from Svelte and mdsvex sources in this skill.\n- At least one `.svx` route or template must be part of the served choice experience.\n- A plain generated HTML form, static DOM script, or one-off Markdown page is not an acceptable implementation.\n- Oracle-generated choices remain strict JSON data. Do not compile Oracle/user option strings as Svelte or mdsvex source.\n- `current-job.json`, drafts, and submissions remain the durable source of truth.\n- The app must run from any project. Do not hardcode `script-kit-gpui`.\n- Do not overwrite an active current job without inspecting status and requiring explicit replacement.\n- Keep the HITL server alive in `tmux`; do not stop it after sending the URL.\n- Wait for the saved submission before continuing. The local wait defaults to no timeout.\n\n## Generate Choices With Oracle\n\nFor 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.\n\nOracle 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.\n\nAsk Oracle for a strict JSON job:\n\n```json\n{\n  \"jobId\": \"short-stable-id\",\n  \"title\": \"Human-readable title\",\n  \"description\": \"What the user is choosing\",\n  \"createdAt\": \"ISO timestamp\",\n  \"options\": [\n    {\n      \"id\": \"stable-option-id\",\n      \"title\": \"Short option title\",\n      \"description\": \"Concrete choice text\",\n      \"tags\": [\"optional\"],\n      \"surface\": \"optional area\",\n      \"goal\": \"optional goal\",\n      \"risk\": \"optional risk\",\n      \"suggestedProofCommands\": [\"optional command\"],\n      \"expectedEvidence\": {\n        \"pass\": \"optional pass signal\",\n        \"fail\": \"optional fail signal\"\n      }\n    }\n  ]\n}\n```\n\nIf 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.\n\n## Build And Serve The mdsvex Choice Experience\n\nThe 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.\n\nFrom any project:\n\n```bash\nexport WEB_CHOICES_SKILL_DIR=\"$HOME/.agents/skills/web-choices\"\nexport HITL_OUT_DIR=\"$PWD/.hitl-choice\"\nexport HITL_HOST=\"127.0.0.1\"\nexport HITL_PORT=\"8877\"\n\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" server \\\n  --out-dir \"$HITL_OUT_DIR\" \\\n  --host \"$HITL_HOST\" \\\n  --port \"$HITL_PORT\" \\\n  --tmux\n```\n\nThe server writes or reuses `$HITL_OUT_DIR/.token`. Read the token from that file or from the server status.\n\nConfirm the server is alive:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" status \\\n  --out-dir \"$HITL_OUT_DIR\" \\\n  --url \"http://127.0.0.1:$HITL_PORT\" \\\n  --token-file \"$HITL_OUT_DIR/.token\"\n```\n\nPush the Oracle-generated job:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" push /path/to/job.json \\\n  --url \"http://127.0.0.1:$HITL_PORT\" \\\n  --token-file \"$HITL_OUT_DIR/.token\"\n```\n\nUse `--replace` only after inspecting active job status and confirming replacement is safe.\n\nStart and verify Tailscale Funnel by default:\n\n```bash\ntailscale funnel --bg --yes \"$HITL_PORT\"\ntailscale funnel status\ncurl -s \"https://<your-tailnet-host>.ts.net/api/jobs/current?token=$(cat \"$HITL_OUT_DIR/.token\")\"\n```\n\nGive the user the public URL only after the public API returns the expected `jobId` and option count:\n\n```text\nhttps://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>\n```\n\nTell the user the server is staying open, drafts are saved server-side, and you are waiting for their submission.\n\n## Wait And Resume\n\nWait locally without a timeout unless the user asks otherwise:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" wait \\\n  --job \"<jobId>\" \\\n  --out-dir \"$HITL_OUT_DIR\"\n```\n\nPersisted sources of truth:\n\n- `$HITL_OUT_DIR/current-job.json`\n- `$HITL_OUT_DIR/drafts/`\n- `$HITL_OUT_DIR/submissions.jsonl`\n- `$HITL_OUT_DIR/submissions/<submissionId>.json`\n\nAfter 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.\n\n## Verification\n\nBefore giving the user the URL, verify:\n\n- `bun run build` succeeds in `~/.agents/skills/web-choices`.\n- The current page is served from compiled Svelte/mdsvex output.\n- The public or local API returns the expected `jobId` and option count.\n- Desktop and phone-width rendering are usable.\n- Draft saving and final submit persist JSON under `HITL_OUT_DIR`.\n\n## Failure Prevention\n\n- If the tunnel fails, keep the same server/job/token when possible and restart Funnel; do not regenerate choices unless asked.\n- If the server dies, inspect `HITL_OUT_DIR` first, restart with the same token, and verify drafts/submissions still exist.\n- 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>`.\n- 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.\n- Do not expose sensitive choices over a public Funnel URL without user approval. The token gates access but is not full authentication.\n\n## Operational boundaries\n\n- 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.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
