docs(stream-plugin): land operator handbook pack

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.

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.

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