Skip to content

docs: strip reader-useless implementation-leak phrasing#47

Merged
abrichr merged 1 commit into
mainfrom
docs/strip-implementation-leak-20260720
Jul 21, 2026
Merged

docs: strip reader-useless implementation-leak phrasing#47
abrichr merged 1 commit into
mainfrom
docs/strip-implementation-leak-20260720

Conversation

@abrichr

@abrichr abrichr commented Jul 21, 2026

Copy link
Copy Markdown
Member

What

Sweep across all authored docs.openadapt.ai pages to remove implementation-leak / internal-plumbing phrasing that is useless to a reader, rewriting to reader-facing value. Trigger example was on /get-started/what-works-today/:

OpenAdapt Hosted has a public $500/month browser-workflow subscription backed by the configured live Stripe Product and Price.

The bolded part describes our internal wiring and means nothing to a user. It now reads: "OpenAdapt Hosted has a public $500/month browser-workflow subscription."

Changes (old -> new)

  • get-started/what-works-today.md
    • "subscription backed by the configured live Stripe Product and Price" -> "subscription." (keeps $500/month + pre-payment-trial evidence)
    • "A non-simulated Modal session on openadapt-flow 1.8.0" -> "A non-simulated hosted browser session on openadapt-flow 1.8.0" (internal vendor name; all evidence retained)
  • guides/hosted.md
    • "Stripe is the commercial source of truth. The website retrieves the live offer server-side and Checkout confirms the same Product and Price before payment." -> "Payment runs through Stripe, and the price shown on the website is the exact price you pay at Checkout."
    • "A qualified Modal browser session" -> "A qualified hosted browser session"
    • "Live mode uses the configured authentication, database, object storage, runner, callback secrets, and billing services." -> "Live mode uses real authentication, database, object storage, runner, and billing services." (keeps the fails-closed contrast)
  • concepts/deployment-matrix.md
    • "Stripe Checkout using the configured product and price;" -> "Stripe Checkout for the public subscription;"
    • "The configured Stripe offer is the commercial source of truth." -> "Stripe is the commercial source of truth for pricing."
  • concepts/substrate-model.md
    • dropped internal "provisioned by the existing oa-vm tooling"; kept the QEMU/KVM + Apache Guacamole architecture (reader-useful)
  • guides/deploy-on-prem.md
    • "One config wires the deployment" / "A production run is wired by a single" -> "One config drives the deployment" / "A production run is defined by a single"
  • guides/induce-a-program.md
    • "effects, actuation, and durability are wired." -> "... are all configured."

Deliberately left as evidence, not plumbing

  • All pinned substrate-evidence copy in what-works-today.md (Windows/macOS/RDP run counts, oracle results, commit hashes, Flow PR numbers, Supported/scoped markers) enforced by test_substrate_evidence_copy.py and validate_docs.py.
  • Reader-useful config the user can act on: env var names (OPENADAPT_INGEST_TOKEN, etc.), OS-keychain resolution order, deployment.yaml, CLI --host/--token defaults referencing the user's configured values.
  • Security posture that substantiates claims: ingest-token/HMAC semantics in security-review.md and hosted.md, signed-webhook activation in the first-customer evidence narrative.
  • "signed-webhook activation" left in place as part of the credibility/evidence chain (borderline evidence vs plumbing).

Guards

mkdocs build --strict, python scripts/validate_docs.py, and pytest tests/ (64 passed) all green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM

Remove internal-plumbing framing that means nothing to a reader while
preserving every reader-useful fact (price, evidence, security posture,
architecture). No changes to the pinned substrate-evidence copy that the
honesty guards enforce.

- what-works-today: drop "backed by the configured live Stripe Product and
  Price"; keep the $500/month fact and the pre-payment-trial evidence.
- what-works-today / hosted: "Modal session" -> "hosted browser session"
  (internal vendor name a reader cannot act on); all evidence retained.
- hosted: replace "website retrieves the live offer server-side and Checkout
  confirms the same Product and Price" with the reader-facing guarantee that
  the website price is the price paid at Checkout.
- hosted: "Live mode uses the configured ... callback secrets ..." ->
  "Live mode uses real ... services"; keeps the fails-closed contrast.
- deployment-matrix: "Stripe Checkout using the configured product and price"
  -> "Stripe Checkout for the public subscription"; "The configured Stripe
  offer is the commercial source of truth" -> "Stripe is the commercial
  source of truth for pricing".
- substrate-model: drop internal "provisioned by the existing oa-vm tooling";
  keep the QEMU/KVM + Guacamole architecture.
- deploy-on-prem / induce-a-program: replace "wired" jargon with plain
  "drives"/"defined by"/"configured".

mkdocs build --strict, validate_docs.py, and pytest tests/ all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM
@abrichr
abrichr merged commit 8f4e5d4 into main Jul 21, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant