From c2523bccc4bbf92c2336a2e46812e91307f8c06b Mon Sep 17 00:00:00 2001 From: rndrntwrk <180591682+rndrntwrk@users.noreply.github.com> Date: Thu, 26 Mar 2026 00:35:48 -0500 Subject: [PATCH 1/2] docs(stream-plugin): add operator handbook pack --- docs/GET_STARTED.md | 4 ++ docs/OPERATOR_HANDBOOK_INDEX.md | 55 +++++++++++++++ docs/OPERATOR_JOURNEY.md | 69 +++++++++++++++++++ docs/RUNBOOK_PACK.md | 42 ++++++++++++ docs/STREAM_MASTERY_LANE.md | 98 +++++++++++++++++++++++++++ docs/STREAM_RELEASE_READINESS_MEMO.md | 39 +++++++++++ 6 files changed, 307 insertions(+) create mode 100644 docs/OPERATOR_HANDBOOK_INDEX.md create mode 100644 docs/OPERATOR_JOURNEY.md create mode 100644 docs/RUNBOOK_PACK.md create mode 100644 docs/STREAM_MASTERY_LANE.md create mode 100644 docs/STREAM_RELEASE_READINESS_MEMO.md diff --git a/docs/GET_STARTED.md b/docs/GET_STARTED.md index f4e2c9a..a0af16e 100644 --- a/docs/GET_STARTED.md +++ b/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` diff --git a/docs/OPERATOR_HANDBOOK_INDEX.md b/docs/OPERATOR_HANDBOOK_INDEX.md new file mode 100644 index 0000000..65b9123 --- /dev/null +++ b/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. diff --git a/docs/OPERATOR_JOURNEY.md b/docs/OPERATOR_JOURNEY.md new file mode 100644 index 0000000..9642fc0 --- /dev/null +++ b/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` diff --git a/docs/RUNBOOK_PACK.md b/docs/RUNBOOK_PACK.md new file mode 100644 index 0000000..af2f3d5 --- /dev/null +++ b/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. diff --git a/docs/STREAM_MASTERY_LANE.md b/docs/STREAM_MASTERY_LANE.md new file mode 100644 index 0000000..00fcc77 --- /dev/null +++ b/docs/STREAM_MASTERY_LANE.md @@ -0,0 +1,98 @@ +# 555 Stream Mastery Lane + +This document defines what "mastery" means for a 555 Stream operator. + +Mastery is not feature knowledge alone. It is the ability to bring a stream +from zero to live, operate it safely, monetize it, recover from bounded failure, +and explain the resulting evidence. + +## Mastery stages + +### Stage 1 — Bootstrap + +Required outcomes: + +- install the plugin +- authenticate successfully +- bind or resume a session +- read concrete status + +Evidence: + +- status output with a valid session +- operator notes on auth path used + +### Stage 2 — Channel readiness + +Required outcomes: + +- save channel configuration +- enable intended channels +- verify readiness before going live + +Evidence: + +- configured channel list +- readiness proof before launch + +### Stage 3 — Go-live execution + +Required outcomes: + +- run the standard studio path +- run the app/website capture path +- verify live state after launch + +Evidence: + +- one successful `STREAM_START` path +- one successful `GO_LIVE_APP` path +- post-launch status proof + +### Stage 4 — Live operation + +Required outcomes: + +- perform one monetization action safely +- perform one communication/control action safely +- explain the current stream state and operator assumptions + +Evidence: + +- ad, chat, or alert proof +- operator state read before and after mutation + +### Stage 5 — Recovery + +Required outcomes: + +- stop safely +- resolve an approval-bound action correctly +- recover from one bounded failure without improvising + +Evidence: + +- recovery notes linked to `EDGE_CASES_AND_RECOVERY.md` +- approval trace if applicable + +### Stage 6 — Release review + +Required outcomes: + +- review operator docs for drift +- confirm evidence links still match runtime truth +- make a go / hold call with stated exceptions + +Evidence: + +- current readiness memo +- linked runtime evidence from `555stream` + +## Current gaps + +- mastery is now defined, but not every stage has one current artifact in this + repo +- final release evidence still depends on the stream repo packets and manual + evidence indices + +Use this lane to close those gaps instead of starting new ad hoc checklists. diff --git a/docs/STREAM_RELEASE_READINESS_MEMO.md b/docs/STREAM_RELEASE_READINESS_MEMO.md new file mode 100644 index 0000000..208cbb8 --- /dev/null +++ b/docs/STREAM_RELEASE_READINESS_MEMO.md @@ -0,0 +1,39 @@ +# 555 Stream Release Readiness Memo + +## Decision + +**Go with bounded exceptions for operator-doc readiness.** + +**Hold for final release-signoff until live runtime evidence is refreshed and +linked against the current operator handbook.** + +## What is ready + +- operator install/auth/bootstrap docs +- action and state reference docs +- approval and recovery docs +- release checklist surfaces +- explicit mastery lane for operator proficiency + +## What still blocks final release-signoff + +- current release evidence is still split across this repo and `555stream` +- the current operator handbook needs a fully refreshed evidence pass against: + - `../555stream/ECOSYSTEM_EVIDENCE_INDEX.md` + - `../555stream/MANUAL_TESTING_INDEX.md` + - `../555stream/PHASE7_UNIFIED_ACCEPTANCE_CLOSURE_2026-02-19_POST_REMEDIATION.md` +- the mastery lane has been defined, but not every stage has a fresh, + current-cycle proof artifact + +## Required closeout for a final go + +- one linked evidence set for bootstrap, channel readiness, standard go-live, + app go-live, live operation, and recovery +- one explicit drift review showing the handbook still matches the runtime +- one release sign-off note referencing the current evidence set + +## Canonical relationship + +- this file owns the operator-doc decision +- the `555stream` repo owns runtime proof packets +- if they drift, update both in the same change window From 5987d3261f9b25ee2ee892de325a4c321adb5379 Mon Sep 17 00:00:00 2001 From: rndrntwrk Date: Wed, 27 May 2026 04:32:29 -0500 Subject: [PATCH 2/2] chore: add crabbox config + workflow + agent skill Initializes the openclaw/crabbox CLI for this repo (workspace control plane for leasing remote boxes + syncing checkout + running commands remotely). Files added: - .crabbox.yaml: repo-local profile - .github/workflows/crabbox.yml: CI workflow lane - .agents/skills/crabbox/SKILL.md: agent skill Generated by `crabbox init` 0.21.0. --- .agents/skills/crabbox/SKILL.md | 13 +++++ .crabbox.yaml | 38 +++++++++++++ .github/workflows/crabbox.yml | 96 +++++++++++++++++++++++++++++++++ 3 files changed, 147 insertions(+) create mode 100644 .agents/skills/crabbox/SKILL.md create mode 100644 .crabbox.yaml create mode 100644 .github/workflows/crabbox.yml diff --git a/.agents/skills/crabbox/SKILL.md b/.agents/skills/crabbox/SKILL.md new file mode 100644 index 0000000..3591e02 --- /dev/null +++ b/.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 -- . +- Use crabbox status --id --wait before broad gates if needed. +- Use crabbox ssh --id to inspect the runner when a failure needs live context. +- Stop with crabbox stop when finished. + +Do not debug product failures on a reused box that fails sync sanity. Stop it, warm a fresh box, and rerun. diff --git a/.crabbox.yaml b/.crabbox.yaml new file mode 100644 index 0000000..7c9a3bb --- /dev/null +++ b/.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" diff --git a/.github/workflows/crabbox.yml b/.github/workflows/crabbox.yml new file mode 100644 index 0000000..300e970 --- /dev/null +++ b/.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