docs: activation fixes, run-outcome reference, and security packet additions - #111
Merged
Merged
Conversation
…ditions Activation and first-run: - Add a per-OS install matrix (bash/zsh, PowerShell, cmd.exe quoting for pip extras, venv guidance, Python version check, Linux AT-SPI prerequisites) to the first-workflow page. - Embed the openadapt-flow showcase demo.gif on the get-started and first-workflow pages (asset copied from openadapt-flow docs/showcase). - Document the bundled MockMed fixture as the evaluator's first target (demo-record; replay with no --url serves it). - Add "expected failure" callouts where lint, certify, and the drift-halt demo intentionally exit nonzero, with the exit codes verified from openadapt-flow main. - Fix record-command drift: examples now show the explicit `record --backend web --url` form and note the demo-profile default. Reference: - New "Run outcomes and halt reasons" page: one table each for execution outcomes, transaction outcomes, effect-verifier verdicts, typed safety-refusal halt codes with per-reason remediation, the hosted Execute lifecycle states, and CLI exit codes; all values sourced from openadapt_flow (execution_profiles, ir, transaction, __main__) and the openadapt-cloud execute contract. Linked from troubleshooting, run-reports, first-workflow, get-started, and the CLI reference. - Complete the glossary: capability ladder, certification vs qualification, effect contract, halt, identity gate, policy, profile, substrate; jargon linked on first use in the get-started pages. Security packet: - New subprocessors page (providers read from the openadapt-cloud deploy configuration) with hosted retention/deletion behavior and a data-flow diagram; boundary diagram also added to the security packet. - New vulnerability-disclosure page (private GitHub advisories for OSS, hello@openadapt.ai for hosted; 5-business-day acknowledgment target). - New one-page PHI-handling narrative tying together openadapt-privacy scrubbing, the sanitize/review/approve gate, and the allow-list receipt. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Implements the docs-review fixes for docs.openadapt.ai, in eight parts. Every product fact was verified against
origin/mainof the source repo named beside it.1. Run outcomes and halt reasons (new reference page)
docs/reference/run-outcomes.md— one table each for:VERIFIED/COMPLETED_UNVERIFIED/HALTED/FAILED/ROLLED_BACK(openadapt-flowexecution_profiles.py,ir.py),HALTED_BEFORE_EFFECT/RECONCILIATION_REQUIRED(transaction.py),confirmed/refuted/indeterminate+ observed-effect states (ir.py),ir.pySafetyRefusalEvidence),decision_required(openadapt-cloudsrc/lib/executeContract.ts),replay/run/tutorial/lint/certify/teach(__main__.py).Linked from troubleshooting, run-reports, first-workflow, get-started, and the CLI reference.
2. "Expected failure" callouts
Get-started drift-halt demo,
lint, andcertifynow carry admonitions saying the nonzero exit is the safety boundary working and which step to continue with. Exit behavior verified:lintexits 1 only aterrorseverity,certifyexits 2 on policy failure, drift replay exits 1 on the expected halt.3. Per-OS install matrix
first-workflow now has tabs for bash/zsh, PowerShell, and cmd.exe — including the cmd.exe double-quote form of
pip install "openadapt[browser]"(single quotes fail there) — plus venv guidance, Python 3.10–3.12 check, and the Debian/Ubuntu AT-SPI prerequisites for the native Linux backend (from openadapt-flowdocs/desktop/LINUX_NATIVE.md).4. Visuals
docs/showcase/demo.gif(241 KB) copied from openadapt-flow origin/main intodocs/assets/showcase/and embedded on get-started and first-workflow. The other showcase directories are run artifacts, not images; nothing synthetic added.5. Glossary completion
Adds capability ladder, certification (vs qualification), effect contract, halt, identity gate, policy, profile, qualification, substrate; BYOC kept. Jargon linked on first use in the get-started pages.
6. Security packet additions
commercial/subprocessors.md: providers verified from openadapt-clouddocs/DEPLOY.md(Netlify, Supabase, Modal, Stripe, Resend, GitHub, PostHog, GlitchTip, Google Analytics) + hosted retention/deletion behavior (versioned env-configured policy, fail-closed deletion gate, legal holds, erasure receipts) + data-flow diagram.commercial/vulnerability-disclosure.md: private GitHub advisories for OSS repos,hello@openadapt.aifor hosted (per openadapt-cloudSECURITY.md;security@exists only as an example VAPID subject, so not used), 5-business-day acknowledgment target.commercial/phi-handling.md: one-page narrative — openadapt-privacy/Presidio scrubbing, the sanitize → review-sanitized → approve-sanitized gate, and the allow-list receipt (receipt.py).7. Public demo target
MockMed documented as the evaluator's first target on first-workflow:
demo-recordserves it and records the canonical demo;replaywith no--urlserves it as the replay target (verified in__main__.py). Framed as a local development fixture, not a product outcome.8. Record-command drift
All
recordexamples now use the explicitrecord --backend web --url ...form; the demo-profile default (web, with a printed notice) is noted. Verified from_cmd_record: production profiles refuse an implicit backend.Facts deliberately omitted (could not verify)
retentionPolicy.ts), not public constants — the page says to request the current policy version instead.security@openadapt.aimailbox could be verified; the disclosure page uses the channels the SECURITY.md files actually name.Verification
Ran the exact CI steps locally in the worktree:
uv sync --locked --extra dev,pytest tests/ -q(132 passed),scripts/validate_docs.py,check_published_version_claims.py --offline, andmkdocs build --strict— all green. Anchors and the gif verified present in the built site.🤖 Generated with Claude Code