docs: map complete operator workflows

[Nickfost]

Summary

• adds an outcome- and role-based operator workflow map that distinguishes current, prototype-only, in-review, planned, and not-production-ready paths
• makes execution surface, mutation scope, prerequisites, stopping conditions, role boundaries, lifecycle commands, verification, and final-report fields explicit
• adds dependency-free validation for local Markdown paths and headings and runs it in CI

Issue #24 acceptance map

Acceptance area	Evidence
Landing page and task index	docs/README.md routes operators to docs/OPERATOR-WORKFLOWS.md
Worker/tester/deployer boundaries	Role and outcome tables identify allowed authority and mandatory separation
Host-role quickstarts	Current worker lifecycle has install/check commands; unavailable tester/deployer paths stop at their implementation gates instead of inventing commands
Prerequisites, credentials, stops, expected results	Pre/post checklists and outcome-specific stops
Where work runs and whether it mutates	Surface table plus labels before every command
Fictional examples	example-org, placeholder commit, and logical controller only
End-to-end checklist and final report	Worker checklist and private-record report template
Lifecycle operations	Links the one installer to install/adopt/check/upgrade/rollback/uninstall guidance
Status truthfulness	Current/prototype/in-review/planned/not-production-ready legend and role rows
Troubleshooting	Queue, root credential visibility, timer health, cleanup, and unavailable-role stops
Glossary	Existing documentation glossary remains authoritative; this change adds missing tester/deployer role definitions
Documentation validation	scripts/check_doc_links.py validates tracked local Markdown paths/headings in CI

This centralizes selection and stopping logic while leaving detailed commands in their existing authoritative runbooks. Issue #24 should remain open until the separately tracked tester/deployer implementation gates can provide their final role-specific quickstarts.

Validation

• python3 scripts/check_doc_links.py
• sabotage check: a temporary missing local link failed, then the clean tree passed
• python3 -m py_compile scripts/check_doc_links.py
• exact-commit committed-secret scan
• public template validation
• workflow YAML lint during file update
• git diff --check

Docker is unavailable locally. The exact-head repository workflow covers the full container build and canonical repository validation.

Related to #24.

[Nickfost]

@codex review

Focused exact-head review at fa3c48e. Check documentation truthfulness against current main, role/security boundaries, every command context and mutation label, public-example hygiene, and whether the stdlib link validator enforces the documented local-link contract without breaking normal repository Markdown. Apply the objective gate: report only a reproducible documented-workflow failure, real trust-boundary authorization/credential issue, plausible state loss/corruption, or concrete repository/CI/runtime/configuration-contract violation preventing use or validation. Style, speculative expansion, duplicates, and forbidden inputs are non-blocking.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa3c48e043

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Nickfost]

@codex review

Confirmation review for exact head 783ea02 after the single grouped review-fix commit. Confirm only the three accepted objective-gate corrections: remove unsupported --repair, ignore fenced code when validating live Markdown links/headings, and link the required runner-group setup/stop procedure. Do not expand scope to currently unused Markdown syntaxes.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 783ea028fb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".