byoa-link

# BYOA link > **env defaults to `prod` when omitted.** `live` is accepted as a user-facing synonym for `prod` (e.g. `/byoa-link live` is equivalent to `/byoa-link prod` and to `/byoa-link` with no arg). `local` is the only other valid value. Walks an operator through everything they need to run `uv run byoa` against a Gradient Bang corp ship. End state: a populated `.env.byoa` at the **main repo root** (mode 0600), a ship claimed as BYOA in `private` mode with a wake secret registered server-side, and clear next-step instructions for the operator. **Always write the env file to the main repo root**, never to the current directory. The skill is often invoked from a git worktree (`.claude/worktrees/<name>/`), and a file dropped there is invisible from the operator's normal checkout. Resolve the destination via `git rev-parse --path-format=absolute --git-common-dir` (its parent is always the main worktree root, even when invoked from a linked worktree). Only honor `--out` when explicitly passed. ## Parameters ``` /byoa-link [env] [--force] [--ship-id <uuid>] [--out <path>] ``` - **env**: `prod` (default, also accepts `live` as a synonym) or `local`. Picks the game server endpoint: - `prod` / `live` → `https://api.gradient-bang.com/functions/v1` (operator-facing; no env file needed). If the operator types nothing, this is what they get. - `local` → sources `SUPABASE_URL` from `.env.supabase` (`http://127.0.0.1:54321` when `npx supabase start` is running) - **--force**: overwrite an existing `.env.byoa` without prompting - **--ship-id**: skip the ship picker; use this corp ship directly - **--out**: write the env file somewhere other than `<repo-root>/.env.byoa`. Without this flag, the file always lands at the main repo root regardless of cwd. The `dev` env was dropped — it required internal-only env files (`.env.cloud.dev`, `EDGE_API_TOKEN`) that operators don't have. Internal team members testing against dev should run `local` with their dev Supabase URL exported in shell. ## Pre-flight Refuse to proceed if any of these is true. Surface a clean error and stop: - For `local`: `${SUPABASE_URL}` is unset in `.env.supabase` (or the file is missing entirely). - The resolved destination already has a `.env.byoa` and `--force` was not passed. Check the resolved repo-root path (or `--out`), not cwd. - `SUBAGENT_BUS_DATABASE_URL` is **only** required for the local-dev wake daemon (`byoa --serve`); not for setup. Don't pre-flight it here. ## Auth header cheat-sheet `/ship_byoa_configure` uses `getAuthenticatedUser()` — same pattern as `verify_token`, `user_character_create`, `reset-password`. JWT-only; no admin token. All BYOA actions (list, claim, clear, set) go through it. | Endpoint | Scheme | Headers required | |---|---|---| | `/login` | public | `Content-Type` only | | `/ship_byoa_configure` | `getAuthenticatedUser()` | `Authorization: Bearer <user_jwt>` | ## Steps ### 1. Resolve the game server URL For `prod` or `live` (the default — if the operator types nothing, treat as `prod`; `live` is a user-facing synonym): ```bash SUPABASE_URL=https://api.gradient-bang.com ``` Hardcoded — operator never types it. (If the CNAME proxy isn't live, fall back to the direct Supabase project URL; this URL is public.) Anything other than `prod`, `live`, or `local` should error out with `unknown env: <value>; expected prod | live | local` before any network call. For `local`: ```bash set -a && source .env.supabase && set +a # SUPABASE_URL now points at http://127.0.0.1:54321 (or whatever the file has). ``` All curls in steps 2–6 append `/functions/v1/<endpoint>` to `SUPABASE_URL`, so the resolved value must NOT include `/functions/v1`. `BYOA_WAKE_SECRET` is the **per-ship** bearer that authenticates `wake_agent` → wake-receiver (local daemon or operator's Vercel Function). Generate a fresh random hex string (`openssl rand -hex 32`) **per ship** — never share across ships. The skill writes the value into `.env.byoa` AND sends the same value to us via `ship_byoa_configure { action: 'set', wake_secret }`. We encrypt at rest and never return it to clients. The bus **channel** is allocated server-side per voice session and injected into the harness env by `wake_agent`. Operators never see or set a channel. The local-dev wake daemon (`uv run byoa --serve`) loads `.env.byoa` first, then falls back to `.env.bot` for `SUBAGENT_BUS_DATABASE_URL` when running from a bot checkout. Standalone operators set it in shell env or add it to `.env.byoa` by hand. ### 2. Log the operator in Prompt for email + password (unless supplied as positional args): ```bash curl -s -X POST "${SUPABASE_URL}/functions/v1/login" \ -H "Content-Type: application/json" \ -d '{"email": "<email>", "password": "<password>"}' ``` Extract `session.access_token` and the character list (`characters`). On any non-success response (4xx, `success: false`), surface the error and stop. ### 3. Pick the operator's character If exactly one character → use it. If multiple → list by `name + character_id` (short prefix) and ask the operator to pick. ### 4. List corp ships ```bash curl -s -X POST "${SUPABASE_URL}/functions/v1/ship_byoa_configure" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <access_token>" \ -d '{"character_id": "<character_id>", "action": "list"}' ``` Response shape: `{ success, action: "list", ships: [{ ship_id, name, sector, byoa_owner_character_id_prefix, claimable_by_me }, ...] }`. Filter to `claimable_by_me === true`. If `--ship-id` was passed, validate it appears in this filtered list. Otherwise present (`name` + 8-char `ship_id` prefix + `sector`) and ask the operator to pick. If the chosen ship is already claimed by the same operator (`byoa_owner_character_id_prefix` matches the operator's character prefix), the claim in step 5 is idempotent — proceed anyway. ### 5. Claim the ship as BYOA ```bash curl -s -X POST "${SUPABASE_URL}/functions/v1/ship_byoa_configure" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <access_token>" \ -d '{ "character_id": "<character_id>", "ship_id": "<ship_id>", "action": "claim", "mode": "private" }' ``` Confirm the response has `byoa_owner_character_id` matching the operator's character_id. A `409 ship_busy` means the ship has an active task — ask the operator to wait or stop it; do not auto-retry. ### 6. Generate + register the per-ship wake secret Generate a fresh random hex bearer (`openssl rand -hex 32`). The wake secret is a per-ship, operator-side credential. Capture the freshly-generated hex in memory; write it to `.env.byoa` in step 7 AND send the same value to us so wake_agent can sign outbound POSTs to the operator's wake receiver: ```bash curl -s -X POST "${SUPABASE_URL}/functions/v1/ship_byoa_configure" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <access_token>" \ -d '{ "character_id": "<character_id>", "ship_id": "<ship_id>", "action": "set", "wake_secret": "<generated hex>" }' ``` Ask the operator whether they want a custom **wake URL** (the URL wake_agent POSTs to): - **Leave unset** (recommended for local dev): `wake_agent` falls back to `http://host.docker.internal:8765/wake` — the default port for `uv run byoa --serve` running on the host. No further config needed. - **Set explicitly**: pass `source_url` on the same `set` call (or a follow-up). Required for Vercel/prod deploys (`https://<your-project>.vercel.app/api/wake`) and for local daemons listening on a non-default port. For production also set `BYOA_WAKE_SECRET=<same hex>` as project env on the operator's Vercel project (where their wake receiver runs). ### 7. Write `.env.byoa` Path: `--out` value, or `<main-repo-root>/.env.byoa` if not provided. **Never write to cwd** — the skill is regularly invoked from a worktree, and writing there hides the file from the operator's normal checkout. File mode **0600**. Resolve the main repo root with `git rev-parse --path-format=absolute --git-common-dir` — its parent is the main worktree root whether the caller is in the main checkout or a linked worktree. The `env.byoa.example` template also lives at that root. ```bash PROJECT_ROOT="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")" OUT_PATH="${OUT_OVERRIDE:-$PROJECT_ROOT/.env.byoa}" umask 077 cp "$PROJECT_ROOT/env.byoa.example" "$OUT_PATH" python3 - "$OUT_PATH" "<character_id>" "<ship_id>" "<wake_secret_hex>" <<'PY' import sys, pathlib path, char_id, ship_id, secret = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4] text = pathlib.Path(path).read_text() text = text.replace("BYOA_CHARACTER_ID=\n", f"BYOA_CHARACTER_ID={char_id}\n", 1) text = text.replace("BYOA_SHIP_ID=\n", f"BYOA_SHIP_ID={ship_id}\n", 1) text = text.replace("BYOA_WAKE_SECRET=\n", f"BYOA_WAKE_SECRET={secret}\n", 1) pathlib.Path(path).write_text(text) PY chmod 600 "$OUT_PATH" ``` Only the three required values are filled in; every other option (`BYOA_PROMPT_FILE`, `TASK_LLM_*`, `BYOA_TOOL_CALL_TIMEOUT_SECONDS`, …) stays commented out at its default. `SUBAGENT_BUS_DATABASE_URL` is not in the template — `uv run byoa --serve` picks it up from `.env.bot` via fallback when running from the bot checkout. Standalone operator deploys without a bot checkout need to set it in the shell env or add it to `.env.byoa` by hand. Verify the file is `0600`, sits at the resolved repo root (not a worktree), and all three values are populated after writing; surface a warning if not. ### 8. Print next steps Echo a copy-pasteable summary the operator can act on: - Where the env file was written. - Author `./prompt.md` (≤ 8 KB, appended to the base task-agent prompt) and set `BYOA_PROMPT_FILE=./prompt.md` (or inline `BYOA_PROMPT=...`) in `.env.byoa`. - **Local dev** (env != `prod`): start the local wake daemon (separate terminal): ```bash uv run byoa --serve ``` The daemon reads `.env.byoa` and waits for wakes from `wake_agent`. As long as the ship has no per-ship `source_url` set, `wake_agent` defaults to `http://host.docker.internal:8765/wake` and routes to the daemon automatically using the per-ship `BYOA_WAKE_SECRET`. Only set `DEFAULT_BYOA_SOURCE_URL` on the edge env to override the default for *all* unconfigured ships. - **Production** (env = `prod`): run `/byoa-deploy-vercel prod` next. It deploys the template at [deployment/vercel/](../../../deployment/vercel/) to the operator's Vercel project (production by default — preview is SSO-gated), pushes `BYOA_WAKE_SECRET` / `TASK_LLM_*` / the matching `*_API_KEY` from `.env.byoa`, health-checks, then logs the operator in again to auto-register `source_url` via `ship_byoa_configure`. Pass `--access-token <jwt>` to reuse the JWT you just minted here and skip the second login prompt. - Point at `docs/byoa.md` for full env / config reference. - Rotate the wake secret by re-running `/byoa-link <env> --force --ship-id <ship>` — this writes a fresh value and updates `ship_byoa_configure` in one shot. ## Failure modes - **401 from /login**: bad credentials. Don't retry. - **No characters**: direct to `/character-create` first. - **No corp ships**: operator isn't in a corp or their corp has no ships. - **409 ship_busy on claim**: ship is mid-task. Don't auto-retry. - **403 on claim or set**: caller's JWT is for a different operator (not the ship owner). Stop and re-check which account was logged in. - **401 "No authorization token provided" / "Invalid or expired token" from /ship_byoa_configure**: the `Authorization: Bearer <jwt>` header is missing or the JWT is expired. Re-run `/login` to mint a fresh one. ## What this skill does NOT do - Write the operator's custom prompt — their authored content, out of scope. - Deploy the operator's BYOA agent. - Modify the bot or edge env files — only reads them.