chore: add crabbox config + workflow + agent skill

.agents/skills/crabbox/SKILL.md

@@ -0,0 +1,13 @@
+# Crabbox
+
+Use Crabbox for remote Linux verification.
+
+Workflow:
+- Warm early: crabbox warmup
+- Reuse the returned slug for interactive checks and keep the cbx_ id in scripts/logs.
+- Run checks with crabbox run --id <slug> -- <command>.
+- Use crabbox status --id <slug> --wait before broad gates if needed.
+- Use crabbox ssh --id <slug> to inspect the runner when a failure needs live context.
+- Stop with crabbox stop <slug> when finished.
+
+Do not debug product failures on a reused box that fails sync sanity. Stop it, warm a fresh box, and rerun.

.crabbox.yaml

@@ -0,0 +1,38 @@
+profile: stream-plugin-check
+class: beast
+capacity:
+  market: spot
+  strategy: most-available
+  fallback: on-demand-after-120s
+actions:
+  workflow: .github/workflows/crabbox.yml
+  job: hydrate
+  runnerLabels:
+    - crabbox
+  runnerVersion: latest
+  ephemeral: true
+sync:
+  delete: true
+  checksum: false
+  gitSeed: true
+  fingerprint: true
+  timeout: 15m
+  warnFiles: 50000
+  warnBytes: 5368709120
+  failFiles: 150000
+  failBytes: 21474836480
+  exclude:
+    - .cache
+    - .turbo
+    - dist
+    - node_modules
+env:
+  allow:
+    - CI
+    - NODE_OPTIONS
+ssh:
+  user: crabbox
+  port: "2222"
+  # Ordered fallback ports tried after ssh.port; use [] to disable fallback.
+  fallbackPorts:
+    - "22"

.github/workflows/crabbox.yml

@@ -0,0 +1,96 @@
+name: crabbox
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref to hydrate"
+        required: false
+        type: string
+      crabbox_id:
+        description: "Crabbox lease ID"
+        required: true
+        type: string
+      crabbox_runner_label:
+        description: "Dynamic Crabbox runner label"
+        required: true
+        type: string
+      crabbox_job:
+        description: "Hydration job identifier expected by Crabbox"
+        required: false
+        default: "hydrate"
+        type: string
+      crabbox_keep_alive_minutes:
+        description: "Minutes to keep the hydrated job alive"
+        required: false
+        default: "90"
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  hydrate:
+    runs-on: [self-hosted, "${{ inputs.crabbox_runner_label }}"]
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - name: Hydrate
+        run: |
+          if [ -f package-lock.json ]; then npm ci; fi
+          if [ -f pnpm-lock.yaml ]; then corepack enable && pnpm install --frozen-lockfile; fi
+          if [ -f go.mod ]; then go mod download; fi
+      - name: Mark Crabbox ready
+        shell: bash
+        run: |
+          job="${{ inputs.crabbox_job }}"
+          if [ -z "$job" ]; then job=hydrate; fi
+          mkdir -p "$HOME/.crabbox/actions"
+          state="$HOME/.crabbox/actions/${{ inputs.crabbox_id }}.env"
+          env_file="$HOME/.crabbox/actions/${{ inputs.crabbox_id }}.env.sh"
+          services_file="$HOME/.crabbox/actions/${{ inputs.crabbox_id }}.services"
+          write_export() {
+            key="$1"
+            value="${!key-}"
+            if [ -n "$value" ]; then
+              printf 'export %s=%q\n' "$key" "$value"
+            fi
+          }
+          {
+            for key in CI GITHUB_ACTIONS GITHUB_WORKSPACE GITHUB_REPOSITORY GITHUB_RUN_ID GITHUB_RUN_NUMBER GITHUB_RUN_ATTEMPT GITHUB_REF GITHUB_REF_NAME GITHUB_SHA GITHUB_EVENT_NAME GITHUB_ACTOR GITHUB_JOB RUNNER_OS RUNNER_ARCH RUNNER_TEMP RUNNER_TOOL_CACHE; do
+              write_export "$key"
+            done
+          } > "${env_file}.tmp"
+          mv "${env_file}.tmp" "$env_file"
+          {
+            echo "# Docker containers visible from the hydrated runner"
+            docker ps --format '{{.Names}}\t{{.Image}}\t{{.Ports}}' 2>/dev/null || true
+          } > "${services_file}.tmp"
+          mv "${services_file}.tmp" "$services_file"
+          tmp="${state}.tmp"
+          {
+            echo "WORKSPACE=${GITHUB_WORKSPACE}"
+            echo "RUN_ID=${GITHUB_RUN_ID}"
+            echo "JOB=${job}"
+            echo "ENV_FILE=${env_file}"
+            echo "SERVICES_FILE=${services_file}"
+            echo "READY_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          } > "$tmp"
+          mv "$tmp" "$state"
+      - name: Keep Crabbox job alive
+        shell: bash
+        run: |
+          minutes="${{ inputs.crabbox_keep_alive_minutes }}"
+          case "$minutes" in
+            ''|*[!0-9]*) minutes=90 ;;
+          esac
+          stop="$HOME/.crabbox/actions/${{ inputs.crabbox_id }}.stop"
+          deadline=$(( $(date +%s) + minutes * 60 ))
+          while [ "$(date +%s)" -lt "$deadline" ]; do
+            if [ -f "$stop" ]; then
+              exit 0
+            fi
+            sleep 15
+          done

docs/GET_STARTED.md

@@ -132,6 +132,10 @@ If approvals are enabled:
 
 ## Next docs
 
+- `OPERATOR_HANDBOOK_INDEX.md`
+- `OPERATOR_JOURNEY.md`
 - `INSTALL_AND_AUTH.md`
 - `ACTIONS_REFERENCE.md`
 - `EDGE_CASES_AND_RECOVERY.md`
+- `RUNBOOK_PACK.md`
+- `STREAM_MASTERY_LANE.md`

docs/OPERATOR_HANDBOOK_INDEX.md

@@ -0,0 +1,55 @@
+# 555 Stream Operator Handbook Index
+
+This is the canonical entrypoint for the stream operator surface.
+
+Use this file when you need one reading path from install through live operation,
+recovery, and release review.
+
+## Reading path
+
+1. `GET_STARTED.md`
+   shortest correct path to a working stream setup
+2. `INSTALL_AND_AUTH.md`
+   auth model, setup, and session prerequisites
+3. `OPERATOR_SETUP_MATRIX.md`
+   configuration by runtime and deployment context
+4. `ACTIONS_REFERENCE.md`
+   operator action surface and expected arguments
+5. `COMPLEX_FLOWS.md`
+   multi-step flows and orchestration patterns
+6. `OPERATOR_JOURNEY.md`
+   default, advanced, and recovery-oriented operator paths
+7. `EDGE_CASES_AND_RECOVERY.md`
+   recovery guidance and failure handling
+8. `RUNBOOK_PACK.md`
+   canonical setup, go-live, incident, and release-review runbook set
+9. `STREAM_MASTERY_LANE.md`
+   operator maturity model and proof expectations
+10. `STREAM_RELEASE_READINESS_MEMO.md`
+   current release-readiness decision and required evidence
+
+## Approval-bound operations
+
+Use these docs whenever a stop, fallback, delete, or other sensitive action is
+involved:
+
+- `approval-api.md`
+- `approval-ui.md`
+
+## State and release docs
+
+- `STATES_AND_TRANSITIONS.md`
+- `state-diagrams.md`
+- `PLUGIN_RELEASE_P0_CHECKLIST.md`
+- `PUBLIC_RELEASE_CHECKLIST.md`
+
+## Evidence sources
+
+The operator handbook is canonical for the interface. Runtime proof and release
+evidence live in the stream repo:
+
+- `../555stream/ECOSYSTEM_EVIDENCE_INDEX.md`
+- `../555stream/MANUAL_TESTING_INDEX.md`
+- `../555stream/STREAM_RELEASE_READINESS_MEMO_2026-03-25.md`
+
+If these disagree, fix the disagreement rather than creating a third source.

docs/OPERATOR_JOURNEY.md

@@ -0,0 +1,69 @@
+# 555 Stream Operator Journey
+
+Use this document when you need the full operator path, not just the shortest
+bootstrap checklist.
+
+## Default operator path
+
+This is the expected path for a serious first-time operator.
+
+1. Install and enable the plugin.
+2. Verify auth and bootstrap a session.
+3. Save and enable the intended output channels.
+4. Choose the go-live surface:
+   - direct studio start
+   - app/website capture path
+5. Confirm live state.
+6. Operate the stream:
+   - ads
+   - chat
+   - overlays and scene transitions
+7. Stop safely and confirm the session returns to ready state.
+
+## Advanced operator paths
+
+### Recovery path
+
+Use this when the operator is already installed but the stream is degraded.
+
+1. Check `STREAM555_STREAM_STATUS`.
+2. Identify whether the fault is:
+   - auth/token
+   - channel config
+   - realtime/session
+   - approval gating
+3. Recover using `EDGE_CASES_AND_RECOVERY.md`.
+4. Reconfirm status before any new mutating action.
+
+### App / website go-live path
+
+Use this when the source is not the default studio composition.
+
+1. Inspect available sources with `STREAM555_APP_LIST`.
+2. Pick the correct viewer/site target.
+3. Invoke `STREAM555_GO_LIVE_APP`.
+4. Verify active state and downstream channels.
+
+### Alice/internal runtime path
+
+Use this when the operator is Alice or another allow-listed internal runtime.
+
+1. Confirm public vs internal base URL routing.
+2. Confirm fixed/default session assumptions.
+3. Keep approvals on.
+4. Use the same status-before-mutation rule as the public path.
+
+## Decision rules
+
+- If the operator is new, teach the default path first.
+- If the operator is debugging, use the recovery path instead of repeating the
+  install flow.
+- If the operator is using non-default capture, treat app/website go-live as a
+  separate workflow, not a footnote.
+
+## Related docs
+
+- `GET_STARTED.md`
+- `INSTALL_AND_AUTH.md`
+- `EDGE_CASES_AND_RECOVERY.md`
+- `STREAM_RELEASE_READINESS_MEMO.md`

docs/RUNBOOK_PACK.md

@@ -0,0 +1,42 @@
+# 555 Stream Runbook Pack
+
+This file defines the canonical runbook set for setup, go-live, incident, and
+recovery.
+
+## Setup runbook
+
+- `GET_STARTED.md`
+- `INSTALL_AND_AUTH.md`
+- `OPERATOR_SETUP_MATRIX.md`
+
+Use when bringing up a new operator environment.
+
+## Go-live runbook
+
+- `GET_STARTED.md`
+- `OPERATOR_JOURNEY.md`
+- `ACTIONS_REFERENCE.md`
+
+Use when preparing a normal live launch.
+
+## Incident runbook
+
+- `EDGE_CASES_AND_RECOVERY.md`
+- `approval-api.md`
+- `approval-ui.md`
+
+Use when the stream is degraded, approvals are blocking, or auth/session state
+is inconsistent.
+
+## Release review runbook
+
+- `STREAM_RELEASE_READINESS_MEMO.md`
+- `PLUGIN_RELEASE_P0_CHECKLIST.md`
+- `PUBLIC_RELEASE_CHECKLIST.md`
+
+Use when deciding whether the stream surface is operator-ready to promote.
+
+## Rule
+
+If a new stream doc is written and it affects setup, go-live, incident, or
+release review, this pack must be updated in the same change.