Public reader quickstart

This repository provides a vendor-neutral adoption guide, a fictional worked example, and historical design lessons. This page is for reviewing and building the public documentation, not provisioning a runtime. For adopting the approach, begin with the adoption guide.

1. Safe public checks

From the repository root, use an isolated Python environment for the docs renderer, then run the static checks:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-docs.txt
make ci DOCS_PYTHON=.venv/bin/python
.venv/bin/python scripts/public-safety-scan
git diff --check

make ci builds docs, checks generated-site links, runs repository-local tests and the full public safety scan. It does not run retired acceptance fixtures or validate a current sandbox or recovery. The scanner is necessary but not sufficient; manually review the public diff before publication.

2. Follow the primary reading path

1. Start here — audience and framework scope.
2. Adoption guide — five stages with outputs and pass/fail checks.
3. Worked example — a complete fictional adoption packet.
4. Verification model — distinguish a test plan from an observed result.
5. Implementation experience — what was reported, what can be generalized, and what remains unmeasured.

3. Preview the static site locally

The public site is static. If a local server is already running from site/, use it. Otherwise:

cd site
python3 -m http.server 3000 --bind 127.0.0.1

Then open:

http://127.0.0.1:3000/

4. Public/private blind-spot review

Before publishing, manually scan the public diff for:

• raw IPs outside documented placeholders;
• host aliases, VM names, service names, routes, ports, and recovery paths;
• SSH key names and key paths;
• NAS or mount paths;
• Telegram/user IDs/handles/tokens or messaging identifiers;
• provider keys, token shapes, .env contents, and secret values;
• private repo paths;
• raw transcripts, logs, screenshots, operator approvals, or incident details.

The public safety scanner is necessary but not sufficient.

5. Historical lab scope

Former host-dependent VM, image, reconcile, and sandbox commands have been retired. Do not use older architecture diagrams or fictional PASS examples as runnable instructions or proof of a current runtime. One reported implementation uses a host, an operator-core VM, logical workload groups, and OpenShell sandboxes. OpenShell and Ansible are choices in that example, not framework requirements. Operational acceptance and recovery claims require separate workload-specific evidence.