diff --git a/.agents/skills/update-lifecycle-docs/SKILL.md b/.agents/skills/update-lifecycle-docs/SKILL.md
new file mode 100644
index 00000000..f78b3072
--- /dev/null
+++ b/.agents/skills/update-lifecycle-docs/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: update-lifecycle-docs
+description: Audit, update, correct, reorganize, or review Lifecycle's source-verified ASD-STE100 end-user MDX documentation, raw Markdown routes, and UI screenshots. Use for documentation gap analysis, upstream documentation impact, new or changed product behavior, configuration/schema/API/CLI synchronization, troubleshooting guides, navigation changes, raw Markdown projection, screenshot capture or refresh, and docs drift remediation in lifecycle-docs.
+---
+
+# Update Lifecycle Docs
+
+Follow the repository `AGENTS.md` throughout this workflow.
+
+## Classify the work
+
+For an upstream change, choose one:
+
+- **No docs needed:** Internal behavior has no user, API, configuration,
+  installation, or interface effect.
+- **Docs needed:** A user-visible behavior, workflow, contract, default,
+  command, route, or support boundary changed.
+- **Uncertain:** The authoritative source does not establish the user effect.
+
+Do not manufacture a change for the first case. For the third case, identify
+the missing product decision or evidence.
+
+For a gap analysis, give every claim one disposition:
+
+- **Confirmed — docs:** The owning product contract is clear.
+- **Confirmed — upstream:** The product contract is broken or contradictory.
+- **Blocked — decision:** Implementation exists, but public policy is not
+  resolved.
+- **Adjusted:** The gap is real, but its scope, evidence, or remedy changed.
+- **Refuted:** Authoritative evidence contradicts the claim.
+
+Deduplicate reports before implementation. Do not endorse an upstream defect
+as a documented workflow.
+
+## Update workflow
+
+1. **Choose the user and task.**
+
+   - Name the reader.
+   - State the outcome that the page must help the reader reach.
+
+2. **Find the owning contract.**
+
+   - Use the source routing in `AGENTS.md`.
+   - Resolve sources from the task context. Do not assume sibling directories,
+     local ports, or one contributor's workspace.
+   - Inspect the implementation, schema, OpenAPI artifact, CLI registration,
+     chart values, or live UI as applicable.
+   - Record the exact commit, PR head SHA, release, or immutable artifact for
+     each claim.
+   - Separate committed evidence from uncommitted behavior in a dirty
+     checkout.
+   - Add or update `audience`, `lastVerified`, and `verificationBaseline`
+     frontmatter. Register new source revisions in
+     `documentation-metadata.json`.
+   - If no owning source is available, mark the claim unverified. Do not use
+     memory or another docs page as product evidence.
+   - Treat support status as a product decision. Do not infer it from code
+     presence.
+
+3. **Assess the user journey.**
+
+   - Read the target page, adjacent pages, navigation metadata, and links.
+   - Read `references/language-profile.md` before an end-user content change.
+   - Read `references/ste100-review.md` before page, navigation, or visible
+     site-chrome copy changes.
+   - Prefer an update to an existing page.
+   - Create a page only for a distinct user task or audience.
+
+4. **Author the page.**
+
+   - Set `contentProfile: asd-ste100`.
+   - Apply ASD-STE100 Issue 9 to all end-user prose, frontmatter, headings,
+     tables, callouts, links, captions, navigation text, and image alt text.
+   - Do not create an ASD-STE100 waiver.
+   - Keep procedural sentences at 20 words or fewer.
+   - Keep descriptive sentences at 25 words or fewer.
+   - Lead with the outcome.
+   - Put prerequisites and product status before the procedure.
+   - Use the smallest safe sequence with tested examples.
+   - Add observable success criteria, recovery, troubleshooting, and the next
+     action when they help the task.
+   - Keep exact commands, identifiers, API routes, schema keys, UI labels,
+     statuses, and error messages faithful to the owning source.
+   - Keep the evidence trail out of end-user prose. Do not describe source
+     inspection, code-comment disagreements, revision history, or how an
+     implementation proves a claim.
+   - Do not publish cache tiers, datastore records, handler names, controller
+     names, or similar machinery unless a supported user task requires that
+     detail.
+   - Translate verified evidence into the supported condition, user-observable
+     effect, user action, and expected result. Put source evidence in task
+     scratch, review notes, metadata, or the handoff.
+
+5. **Decide whether a screenshot helps.**
+
+   - Use a screenshot only when recognition, location, or UI density makes the
+     task materially easier.
+   - Read `references/screenshots.md` before capture.
+   - Prefer diagrams for concepts and selectable text for code, commands,
+     schemas, or payloads.
+   - Get explicit authorization before each external state change. Record the
+     exact target, prior state, created identifiers, and cleanup result in
+     private task scratch.
+
+6. **Keep navigation and generated outputs coherent.**
+
+   - Update the nearest `_meta.ts` when you add, move, or rename a page.
+   - Run generated metadata steps and review ordering changes.
+   - Treat `public/llms.txt` as generated output. Change page metadata and
+     navigation, then run `bun run build:llms`.
+   - Read `references/raw-markdown.md` before you add an MDX construct or
+     change the build path.
+   - Treat `public/docs.md` and `public/docs/**/*.md` as generated output.
+     Run `bun run build:raw`.
+   - Add an explicit lossless transform and a golden test for each new MDX
+     construct. Do not discard unsupported content.
+
+7. **Verify content and rendering.**
+
+   - Validate examples against the owning schema, CLI, API, or chart.
+   - Use `references/ste100-review.md` for all 53 rule checks on each changed
+     page.
+   - Supply the portable contract inputs in `README.md` and run
+     `bun run check:contracts --require-all` when schema, API, or CLI claims
+     change. A **SKIP** is not contract verification.
+   - Format changed files only.
+   - Run `bun run check:styles`.
+   - Run `bun run check:raw`.
+   - After the complete human review, run
+     `bun run update:style-baseline`. Review the page, navigation, and visible
+     site-chrome hash diff.
+   - Run `bun run verify`.
+   - Resolve the preview URL from the task, `DOCS_BASE_URL`, or development
+     server output. Inspect every changed route with an approved desktop
+     browser inspection tool.
+   - Inspect `src/theme.config.tsx` and check each enabled theme.
+   - Run `bun run check:screenshots` for screenshot changes. Manually inspect
+     the final pixels and live UI state.
+   - Complete a user-voice review of every changed sentence. Keep a sentence
+     only when it gives a prerequisite, condition, action, observable result,
+     recovery step, safety boundary, or necessary explanation for the reader.
+     Remove sentences that only show how the writer verified a claim.
+   - If the browser or runtime is unavailable, report visual verification as
+     incomplete.
+
+8. **Prepare the handoff.**
+
+   - Summarize the reader task, authoritative revisions, changed routes,
+     validation, and remaining uncertainty.
+   - Keep private fixture identifiers in task scratch.
+   - Create a docs PR only when authorized. Do not merge without explicit
+     authorization.
+
+## Page shape
+
+Use this order when it helps the task:
+
+1. Outcome
+2. Audience, prerequisites, and support status
+3. Procedure
+4. Verify the result
+5. Recover or roll back
+6. Troubleshoot
+7. Next steps
+8. Version and owner last verified
+
+Do not force headings that add no value. Do not omit safety, verification, or
+recovery when the workflow changes state.
+
+## Safety and accuracy
+
+- Do not infer public support from code acceptance.
+- Do not publish the reasoning used to verify a user-facing claim.
+- Do not add `supportStatus` without a product or release decision.
+- Do not describe Labs or admin-gated controls as universally available.
+- Do not publish private values, credentials, unrestricted examples, or
+  destructive shortcuts.
+- Do not silently reconcile conflicting contracts.
+- Do not add placeholders or TODO-only pages to navigation.
+- Do not record personal paths, private fixture identities, fixed local URLs,
+  or local credentials in tracked files.
+- Do not edit generated files by hand.
+- Do not copy or commit licensed ASD-STE100 rule text, dictionaries, PDFs, or
+  checker data.
+- Do not treat an automated style check or matching baseline hash as complete
+  ASD-STE100 certification.
+- Do not claim that a screenshot is private-data-safe or current from
+  automated checks alone.
diff --git a/.agents/skills/update-lifecycle-docs/agents/openai.yaml b/.agents/skills/update-lifecycle-docs/agents/openai.yaml
new file mode 100644
index 00000000..9d3bd7f8
--- /dev/null
+++ b/.agents/skills/update-lifecycle-docs/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update Lifecycle Docs"
+  short_description: "Maintain source-verified Lifecycle docs"
+  default_prompt: "Use $update-lifecycle-docs to audit or update Lifecycle documentation with source verification, ASD-STE100 review, raw Markdown parity, and evidence-backed screenshots."
diff --git a/.agents/skills/update-lifecycle-docs/references/language-profile.md b/.agents/skills/update-lifecycle-docs/references/language-profile.md
new file mode 100644
index 00000000..502a40c1
--- /dev/null
+++ b/.agents/skills/update-lifecycle-docs/references/language-profile.md
@@ -0,0 +1,86 @@
+# Lifecycle documentation language profile
+
+Read this reference before you add, remove, move, or change an end-user page.
+
+## Scope
+
+All end-user documentation under `src/pages/docs/**` must follow ASD-STE100
+Issue 9. This requirement includes every nested documentation route.
+
+Repository maintainer files, source comments, generated Markdown, and code
+examples are not end-user prose. Keep them clear and portable.
+
+## ASD-STE100 profile
+
+Use the
+[official ASD-STE100 Issue 9 standard](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)
+during the human editorial review. Do not copy or commit its
+controlled-language dictionary, rule text, PDF, or licensed checker data.
+Use `ste100-review.md` to track all 53 rule identifiers for every page. Its
+short review questions do not replace the official standard.
+
+Apply these project controls:
+
+- Use American English.
+- Use one term for one concept.
+- Use the approved general vocabulary when it expresses the correct meaning.
+- Treat exact Lifecycle product terms, UI labels, schema keys, API fields,
+  commands, paths, statuses, and other required domain terms as technical
+  terms.
+- Define a new technical term when a reader cannot understand it from the
+  task context.
+- Prefer active voice.
+- Use simple verb groups.
+- Write all necessary words. Do not use contractions.
+- Do not use semicolons.
+- Put a condition before its instruction.
+- Write one instruction in each procedural sentence.
+- Use the imperative for an instruction.
+- Keep a procedural sentence at 20 words or fewer.
+- Keep a descriptive sentence at 25 words or fewer.
+- Keep one topic in each descriptive paragraph.
+- Keep a descriptive paragraph at six sentences or fewer.
+- Use a note for information. Do not put an instruction in a note.
+
+Apply the same profile to titles, descriptions, navigation text, headings,
+paragraphs, callouts, tables, list text, link text, captions, and image alt
+text.
+
+Do not change an exact code block, command, API route, identifier, schema key,
+UI label, status, or error message only to satisfy a prose rule. Correct an
+exact string only when the owning product source proves that the string is
+wrong.
+
+Set this frontmatter value on every end-user page:
+
+```yaml
+contentProfile: asd-ste100
+```
+
+Do not create a page-level ASD-STE100 waiver.
+
+## Review and validation
+
+Run:
+
+```sh
+bun run check:styles
+```
+
+The style baseline stores a hash, profile, and review date for every page. It
+also covers maintained documentation navigation and visible site chrome. The
+baseline makes later prose changes require another review. It preserves the
+review date for an unchanged page.
+
+After the human review and all checks pass, update the baseline:
+
+```sh
+bun run update:style-baseline
+```
+
+Review the baseline diff. Do not update it to hide an incomplete language
+review.
+
+No automated tool can certify complete ASD-STE100 compliance. The author and
+reviewer remain responsible for vocabulary, technical-term selection,
+sentence meaning, and context-dependent rules.
diff --git a/.agents/skills/update-lifecycle-docs/references/raw-markdown.md b/.agents/skills/update-lifecycle-docs/references/raw-markdown.md
new file mode 100644
index 00000000..ae5ade02
--- /dev/null
+++ b/.agents/skills/update-lifecycle-docs/references/raw-markdown.md
@@ -0,0 +1,111 @@
+# Raw Markdown routes
+
+Read this reference when you add a page, change MDX component usage, or change
+the build and deployment path.
+
+## Architecture decision
+
+This repository uses Nextra 3 with the Next.js Pages Router and
+[static export](https://nextra.site/docs/guide/static-exports). Nextra 3 does
+not provide raw Markdown endpoints. Nextra 4 requires the App Router, and its
+copy-page feature copies MDX source rather than a clean Markdown rendering.
+
+[Next.js static export](https://nextjs.org/docs/pages/guides/static-exports)
+does not support a runtime API route or rewrite for this purpose. A pre-build
+projection into `public/` gives local development, static export, GitHub Pages,
+and Nginx the same files.
+
+Re-evaluate this decision only during an intentional framework migration.
+Require the replacement to support clean Markdown, exact `.md` paths, static
+export, component conversion, and fail-closed handling.
+
+## Public contract
+
+Append `.md` to an HTML documentation route to get clean Markdown:
+
+| HTML route           | Raw Markdown route      |
+| -------------------- | ----------------------- |
+| `/docs`              | `/docs.md`              |
+| `/docs/releases`     | `/docs/releases.md`     |
+| `/docs/features/cli` | `/docs/features/cli.md` |
+
+The mapping follows the public route. It does not follow the `.mdx` file name
+when that file is an `index.mdx`.
+
+## Source and generated files
+
+The `.mdx` page is the source. `scripts/generateRawMarkdown.ts` creates a clean
+GitHub Flavored Markdown projection under `public/` before the Next.js static
+export.
+
+Generated raw files have a sentinel and are ignored by Git:
+
+```txt
+public/docs.md
+public/docs/**/*.md
+```
+
+Do not edit or commit them. The generator refuses to replace or delete a
+reserved Markdown file without its generated sentinel.
+
+Use:
+
+```sh
+bun run build:raw
+bun run check:raw
+```
+
+`build:prep`, `dev`, and `build` run the generator. If you edit an MDX file
+while `next dev` is already running, run `bun run build:raw` again to refresh
+its `.md` route.
+
+## Projection contract
+
+The projector keeps normal Markdown and converts the supported MDX vocabulary:
+
+- `Callout` becomes a labeled GitHub alert blockquote.
+- `Steps` keeps its ordered content.
+- `Tabs` becomes a sequence of labeled sections.
+- `Cards` becomes a linked list.
+- `Image` becomes a Markdown image.
+- `Iframe` becomes a titled link.
+- A static string inside `<code>` becomes inline code.
+- Layout-only `div` elements keep their content.
+- `br` becomes a Markdown line break.
+- Useful code-fence filenames become adjacent Markdown text.
+- Imports are removed.
+
+The projector fails with the source file and line when it finds an unknown
+component, dynamic expression, unsafe attribute, raw HTML, or unsupported
+code-fence metadata. It must never discard unknown content silently.
+
+When you introduce a new MDX construct:
+
+1. Define its lossless Markdown representation.
+2. Add the explicit projector transform.
+3. Add a golden projection test.
+4. Confirm that all documentation pages project.
+5. Run the full build and inspect the emitted `.md` file under `out/`.
+
+## Index policy
+
+`public/llms.txt` lists the public pages and links to their raw Markdown
+routes. Update frontmatter and navigation, then regenerate the index. Do not
+edit `public/llms.txt` directly.
+
+## Deployment
+
+Next.js copies generated files from `public/` to `out/`. GitHub Pages serves
+them from the static export. The repository Nginx configuration gives `.md`
+files the `text/markdown; charset=utf-8` media type and returns 404 for a
+missing `.md` path. Its HTML fallback checks `$uri.html` before `$uri`. This
+order prevents a page asset directory, such as `/docs/guide/`, from hiding the
+exported `/docs/guide.html` page.
+
+After a deployment-path or asset-path change, use the production server
+configuration to confirm all four conditions:
+
+- Each documentation `.md` route returns `200` and readable UTF-8 Markdown.
+- A missing `.md` route returns `404` instead of the HTML fallback.
+- A page with a same-name asset directory still returns its exported HTML.
+- The page assets return `200`.
diff --git a/.agents/skills/update-lifecycle-docs/references/screenshots.md b/.agents/skills/update-lifecycle-docs/references/screenshots.md
new file mode 100644
index 00000000..8662c5f9
--- /dev/null
+++ b/.agents/skills/update-lifecycle-docs/references/screenshots.md
@@ -0,0 +1,181 @@
+# Lifecycle documentation screenshots
+
+Use this reference only when adding, replacing, or reviewing UI screenshots.
+
+## Contents
+
+- [When a screenshot is worth maintaining](#when-a-screenshot-is-worth-maintaining)
+- [Capture standard](#capture-standard)
+- [Fixture workflow](#fixture-workflow)
+- [Asset placement and accessibility](#asset-placement-and-accessibility)
+- [Screenshot catalog](#screenshot-catalog)
+- [Capture checklist](#capture-checklist)
+
+## When a Screenshot Is Worth Maintaining
+
+Use a screenshot when it materially helps a reader:
+
+- Recognize a page, dialog, or state
+- Find an action in a dense interface
+- Distinguish success, pending, and failure states
+- Understand the relationship between an Environment, its Services, logs, or Agent activity
+
+Do not use a screenshot for:
+
+- Code, terminal commands, schemas, or API payloads
+- Conceptual architecture that a diagram explains more clearly
+- Decorative proof that a feature exists
+- Rapidly changing Labs controls unless the page names the status and the catalog has a refresh owner
+
+Keep the smallest screenshot set that explains the journey.
+
+## Capture Standard
+
+- Resolve the running Lifecycle UI from the task context, runtime output, or
+  `LIFECYCLE_UI_URL`. Never assume a host, port, authentication provider, or
+  test user.
+- Use an available desktop browser inspection tool and an authorized,
+  authenticated non-production session. Follow the owning UI repository's
+  instructions when they are available; do not invent credentials or bypass
+  authentication.
+- Set the viewport to 1440×900 at device scale factor 1 and browser zoom 100%.
+- Use the theme required by the page and keep a screenshot series consistent.
+  Record the chosen theme in the catalog rather than assuming one here.
+- Enable Labs only through the supported task/runtime procedure. Do not publish
+  a local cookie or developer bypass as an end-user enablement step.
+- Wait for loading, transitions, toasts, and live updates to settle.
+- Prefer a component or application-region capture. Keep enough surrounding UI for orientation.
+- Use viewport position or element capture instead of editing pixels afterward.
+- Do not bake arrows, labels, or explanatory text into the bitmap; put explanation in prose and captions.
+- Do not use generative image editing on product screenshots.
+- Capture PNG for UI text. Optimize only when legibility and dimensions remain unchanged.
+- Keep raw captures in task scratch; only reviewed images belong in `public/`.
+- If the browser tool cannot persist a file, save the returned image bytes
+  exactly through a trusted task-local mechanism. Do not re-render or transform
+  the UI.
+- Prefer neutral fixture values at the source. For an authorized,
+  non-production fixture whose incidental identity, hostname, UUID, or
+  timestamp cannot be controlled at the source or cropped without losing the
+  teaching point, substitute only those identity-bearing DOM text or link
+  values before capture. Record every substitution in task scratch, preserve
+  product labels, statuses, actions, controls, and messages exactly, and
+  re-inspect the final pixels and live state. Never use this exception for
+  private or production data.
+- If no approved browser tool or authenticated runtime is available, stop the
+  capture and report visual verification as incomplete. Do not infer the
+  rendered state from source or disrupt another session's browser.
+
+Use neutral fixtures. Exclude or avoid:
+
+- Tokens, secrets, environment-variable values, and one-time credentials
+- Personal names, avatars, emails, and private repository ownership
+- Internal cluster identifiers or unrelated local resources
+- Incidental timestamps, random identifiers, and hostnames when they do not teach the task
+- Browser chrome, developer-tool overlays, unrelated tabs, and transient notifications
+
+Crop or choose a narrower UI region rather than blurring. If a user-facing identifier is necessary to explain the task, use a neutral fixture value.
+
+## Fixture Workflow
+
+Use only a disposable fixture repository explicitly authorized for the task.
+Resolve its identity at runtime from `DOCS_SCREENSHOT_FIXTURE_REPOSITORY`, the
+task context, or the fixture checkout. Never put a private repository or owner
+in tracked instructions:
+
+```sh
+gh repo view "$DOCS_SCREENSHOT_FIXTURE_REPOSITORY" \
+  --json nameWithOwner,defaultBranchRef,viewerPermission
+```
+
+Before mutation:
+
+1. Confirm the user authorized every planned external mutation: branch push,
+   PR creation, label or comment changes, PR closure, branch deletion, and
+   resulting Lifecycle resource creation/cleanup.
+2. Inspect and record the exact repository, default branch, current revision,
+   worktree status, existing worktrees, open PRs, and current `lifecycle.yaml`.
+3. Never switch the user's existing checkout or reuse, close, or modify a pre-existing PR.
+4. Resolve the fixture's default branch and remote, then create a unique branch
+   in an isolated temporary worktree from the fetched default-branch revision.
+5. Use one minimal Service and a neutral PR title.
+6. Never merge a fixture PR.
+7. Record the branch, PR, Environment UUID, and cleanup status in task scratch.
+
+Build the smallest fixture from the current authoritative schema. Do not keep a
+copy of a product manifest in this skill: it will drift independently from the
+runtime contract. Validate the fixture with the current server-side validator
+before pushing it. Use current configured control labels rather than assuming
+their default names.
+
+For a failure screenshot, prefer a deterministic, reversible fault with one
+changed input. Record the exact change and verify that the resulting user-facing
+state is the state the guide explains. Do not infer a build-versus-deploy
+failure from the fixture alone.
+
+Cleanup order:
+
+1. Verify the PR's head branch exactly matches the recorded fixture branch.
+2. Close the PR without deleting the branch.
+3. Wait for teardown and confirm the recorded Environment reached the expected
+   terminal cleanup state, such as `Torn down`, through the user-visible UI or
+   supported API. Lifecycle can retain terminal Environment history. Use
+   cluster inspection only when the task explicitly includes operator access.
+4. Delete only the recorded remote branch.
+5. Remove the temporary worktree.
+6. Attempt to delete the local branch with `git branch -d`. A fixture branch
+   from an unmerged, closed PR may require `git branch -D`; before doing that,
+   re-verify its exact name and commit against the task record and confirm the
+   remote branch is gone and the Environment reached its terminal cleanup
+   state.
+7. Stop if cleanup finds unexpected changes or a target mismatch.
+
+If any authorized cleanup cannot complete, leave unrelated state untouched and
+report the exact remaining PR, branch, Environment, Site, or session identifier
+and the last verified state in the private task handoff. Use only a sanitized
+cleanup statement in a public PR or issue.
+
+## Asset Placement and Accessibility
+
+- Mirror the page route under `public/docs/`; for example, a screenshot for `/docs/troubleshooting/deploy-issues` belongs under `public/docs/troubleshooting/deploy-issues/`.
+- After you add a page asset directory, test the parent HTML route through the
+  deployment server. The server must prefer the exported `.html` file over the
+  same-name directory.
+- Use a descriptive, stable filename such as `service-deploy-failure.png`, not a UUID or date.
+- Add explicit `width`, `height`, and `ratio` to `<Image>`.
+- Write alt text that explains the information contributed by the image, not every visible control.
+- Keep all operational instructions in nearby text so the page remains usable without the image.
+- Add a caption when the state, scope, or support status is not obvious.
+
+## Screenshot Catalog
+
+Update this table whenever a tracked screenshot is added, refreshed, removed,
+or found to be stale. `keep` means the final pixels and live state were manually
+reviewed. `replace` and `remove` deliberately fail `bun run check:screenshots`
+until the referenced debt is resolved.
+
+| Asset                                                             | Docs page                                   | User point                                  | UI route/state                                                      | Fixture                                                                                                                        | Viewport/theme   | UI revision                                | Last verified | Review |
+| ----------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------ | ------------- | ------ |
+| `/docs/getting-started/explore-environment/environment-ready.png` | `/docs/getting-started/explore-environment` | Recognize a ready Environment and Service   | Environment details, selected Service Summary, `Deployed` / `Ready` | Authorized disposable fixture; incidental identity, hostname, UUID, and timestamp values generalized in DOM; cleanup confirmed | 1440×900 / light | `b1df0cd64b4680fb241364be6cab985a2dce1f4f` | 2026-07-24    | `keep` |
+| `/docs/getting-started/onboard-repository/repository-list.png`    | `/docs/getting-started/onboard-repository`  | Find and select a repository for onboarding | `/onboard`, installed but not-onboarded repository filtered         | Authorized disposable fixture; incidental identity, hostname, UUID, and timestamp values generalized in DOM; cleanup confirmed | 1440×900 / light | `b1df0cd64b4680fb241364be6cab985a2dce1f4f` | 2026-07-24    | `keep` |
+| `/docs/features/lifecycle-ui/environment-list.png`                | `/docs/features/lifecycle-ui`               | Find, filter, and select an Environment     | `/environments`, one `Torn down` Environment filtered               | Authorized disposable fixture; incidental identity, hostname, UUID, and timestamp values generalized in DOM; cleanup confirmed | 1440×900 / light | `b1df0cd64b4680fb241364be6cab985a2dce1f4f` | 2026-07-24    | `keep` |
+
+The structural check cannot read meaning from rendered pixels. A `keep` status
+is a human assertion that the final image contains no secret, personal,
+private, local-only, stale, or misleading content; automation verifies only
+references, intrinsic dimensions, catalog state, and detectable tracked-text
+markers.
+
+## Capture Checklist
+
+- [ ] The screenshot teaches a point that text or a diagram cannot communicate as well.
+- [ ] The owning UI behavior was verified in the running app.
+- [ ] The fixture is neutral, minimal, and recorded.
+- [ ] Loading, animation, and transient UI have settled.
+- [ ] No secret, personal, private, or unrelated data is visible.
+- [ ] The crop retains enough context for orientation.
+- [ ] Alt text and adjacent instructions carry the same essential meaning.
+- [ ] The asset path and catalog entry are updated.
+- [ ] The rendered page was checked in every theme enabled by
+      `src/theme.config.tsx`.
+- [ ] `bun run check:screenshots` passes.
+- [ ] Temporary PR, branch, Environment, Site, or session state was cleaned up.
diff --git a/.agents/skills/update-lifecycle-docs/references/ste100-review.md b/.agents/skills/update-lifecycle-docs/references/ste100-review.md
new file mode 100644
index 00000000..c1fc04cb
--- /dev/null
+++ b/.agents/skills/update-lifecycle-docs/references/ste100-review.md
@@ -0,0 +1,92 @@
+# ASD-STE100 review coverage
+
+Use this checklist for every canonical end-user page. It tracks all 53 writing
+rules in ASD-STE100 Issue 9 without reproducing the standard. Read the
+[official Issue 9 PDF](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf)
+for the authoritative rule text, definitions, permitted forms, categories,
+and examples.
+
+`check:styles` is a mechanical aid. In the table:
+
+- **Mechanical** means that the repository check covers an objective part of
+  the rule.
+- **Human** means that an editor must review meaning and context.
+- **Source** means that product source or approved terminology must establish
+  the technical term.
+
+No end-user page or rule has a waiver.
+
+## Complete rule matrix
+
+| Rule | Project review question                                                                           | Coverage          |
+| ---- | ------------------------------------------------------------------------------------------------- | ----------------- |
+| 1.1  | Is each general word approved, or is it a necessary technical term?                               | Human, Source     |
+| 1.2  | Does each approved word use its permitted part of speech?                                         | Human             |
+| 1.3  | Does each approved word use its permitted meaning?                                                | Human             |
+| 1.4  | Does each verb or adjective use a permitted form?                                                 | Human             |
+| 1.5  | Does each technical noun fit an Issue 9 technical-noun category?                                  | Human, Source     |
+| 1.6  | Is each unapproved word used only as a valid technical noun?                                      | Human, Source     |
+| 1.7  | Is every technical noun used as a noun, not as a verb?                                            | Human             |
+| 1.8  | Does product or industry evidence approve each technical noun?                                    | Human, Source     |
+| 1.9  | Is each selected technical noun short and easy to understand?                                     | Human             |
+| 1.10 | Is technical terminology free of regional language, slang, and jargon?                            | Human             |
+| 1.11 | Does one technical noun identify one item consistently?                                           | Human, Source     |
+| 1.12 | Does each technical verb fit an Issue 9 technical-verb category?                                  | Human, Source     |
+| 1.13 | Is every technical verb used as a verb, not as a noun?                                            | Human             |
+| 1.14 | Does prose use American English spelling?                                                         | Human             |
+| 2.1  | Does a normal multi-word noun contain no more than three words?                                   | Human             |
+| 2.2  | Is an official technical noun longer than three words written in full?                            | Human, Source     |
+| 3.1  | Does each general verb use a dictionary-approved form?                                            | Human             |
+| 3.2  | Does each verb use a form and tense permitted by Issue 9?                                         | Human             |
+| 3.3  | Is each past participle used only in a permitted adjective role?                                  | Human             |
+| 3.4  | Does prose avoid complex auxiliary verb groups?                                                   | Mechanical, Human |
+| 3.5  | Does each `-ing` form have a permitted technical-noun or modifier role?                           | Human             |
+| 3.6  | Is the voice active unless Issue 9 permits passive voice in that context?                         | Human             |
+| 3.7  | Does each action use a verb instead of a noun phrase?                                             | Human             |
+| 4.1  | Is each sentence short, direct, and clear?                                                        | Mechanical, Human |
+| 4.2  | Does each sentence keep necessary words and avoid contractions?                                   | Mechanical, Human |
+| 4.3  | Does complex information use a vertical list?                                                     | Human             |
+| 4.4  | Do related sentences use clear, approved connections?                                             | Human             |
+| 4.5  | Does prose include necessary articles or demonstrative adjectives?                                | Human             |
+| 5.1  | Does each procedural sentence contain no more than 20 words?                                      | Mechanical        |
+| 5.2  | Does each procedural sentence contain one instruction, except for an allowed simultaneous action? | Mechanical, Human |
+| 5.3  | Does each instruction use the imperative form?                                                    | Mechanical, Human |
+| 5.4  | Does a necessary condition occur before its instruction?                                          | Mechanical, Human |
+| 5.5  | Does each note contain information only?                                                          | Human             |
+| 6.1  | Does descriptive text introduce information in a useful sequence?                                 | Human             |
+| 6.2  | Do headings and key terms make the information structure clear?                                   | Human             |
+| 6.3  | Does each descriptive sentence contain no more than 25 words?                                     | Mechanical        |
+| 6.4  | Does each paragraph contain related information?                                                  | Human             |
+| 6.5  | Does each paragraph have one topic?                                                               | Human             |
+| 6.6  | Does each descriptive paragraph contain no more than six sentences?                               | Mechanical        |
+| 7.1  | Does each safety message identify the correct severity?                                           | Human, Source     |
+| 7.2  | Does each safety instruction start with an unambiguous command or condition?                      | Human             |
+| 7.3  | Does each safety message state the risk or possible result?                                       | Human, Source     |
+| 8.1  | Does prose avoid semicolons and use punctuation correctly?                                        | Mechanical, Human |
+| 8.2  | Do hyphens connect only directly related words?                                                   | Human             |
+| 8.3  | Does each parenthetical expression have a permitted purpose?                                      | Human             |
+| 8.4  | Does a colon introduce vertical-list content clearly?                                             | Human             |
+| 8.5  | Does sentence-length review count a parenthetical expression as Issue 9 specifies?                | Mechanical, Human |
+| 8.6  | Does sentence-length review count protected strings and symbols as Issue 9 specifies?             | Mechanical, Human |
+| 8.7  | Does sentence-length review count a hyphenated word as one word?                                  | Mechanical        |
+| 9.1  | If direct wording is not possible, does a new sentence construction keep the meaning?             | Human             |
+| 9.2  | Is each approved word correct for its selected meaning and context?                               | Human             |
+| 9.3  | Does prose avoid unapproved phrasal verbs?                                                        | Human             |
+| 9.4  | Are terminology and sentence patterns consistent across the page and site?                        | Human, Source     |
+
+## Review record
+
+For each changed canonical page:
+
+1. Verify facts and technical terms against the owning source revision.
+2. Review all rule rows against the title, description, navigation text,
+   headings, paragraphs, lists, tables, callouts, links, captions, and alt
+   text.
+3. Run `bun run check:styles` and resolve every mechanical finding.
+4. Review the rendered page for sentence purpose, topic boundaries, safety
+   meaning, and information sequence.
+5. Run `bun run update:style-baseline` only after the complete review.
+
+The baseline stores a content hash, profile, and review date for every route.
+It proves review coverage and detects later changes. It does not certify
+compliance.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index cf9884aa..27afe3d4 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,11 +1,39 @@
-## Fixes
+## Reader and task
 
-- Fixes #
+- Audience:
+- Task/outcome:
 
-## Proposed Changes
+## Source of truth
 
-- Change
+- Exact owning repository revisions, PR head SHAs, or immutable artifacts:
+- Frontmatter verification baseline added or reused:
+- Product or runtime verification:
+- Contract checks (schema / OpenAPI / CLI; identify any **SKIP**):
+- Unavailable or unresolved sources:
 
----
+## Documentation changes
 
-> Read about referenced issues [here](https://help.github.com/articles/closing-issues-using-keywords/). Replace words with this Pull Request's context.
+- Changed pages:
+- ASD-STE100 human review:
+- Navigation or redirects:
+- Raw Markdown projection:
+- External state: sanitized authorization and cleanup assertion, with only
+  public or non-sensitive references (keep private identifiers in task scratch):
+- Screenshots, catalog status, and manual pixel/state review:
+
+## Verification
+
+- [ ] Formatted changed files
+- [ ] Kept source-review evidence and non-actionable implementation details out of end-user prose
+- [ ] Confirmed that each changed sentence helps the reader understand, complete, verify, or recover the task
+- [ ] Reviewed all 53 rule rows in `.agents/skills/update-lifecycle-docs/references/ste100-review.md`
+- [ ] `bun run check:styles`
+- [ ] Updated the style baseline only after the complete human review
+- [ ] `bun run check:raw`
+- [ ] `bun run verify`
+- [ ] `bun run check:contracts --require-all` when schema, API, or CLI claims changed
+- [ ] Checked changed routes with an approved desktop browser inspection tool
+- [ ] Checked every theme enabled by the current theme config
+- [ ] Ran `bun run check:screenshots` when visuals changed
+- [ ] Confirmed screenshots contain no secrets or personal/private data
+- [ ] Confirmed tracked guidance has no contributor-specific paths, hosts, credentials, or fixture identities
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e0f51199..2695a1bd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,7 +34,6 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
-      - run: bun install
-      - run: bun run lint
-      - run: bun run test
+          bun-version: 1.2.8
+      - run: bun install --frozen-lockfile
+      - run: bun run verify
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index b1f625ed..625b91d2 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -31,10 +31,10 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: latest
+          bun-version: 1.2.8
 
       - name: Install dependencies
-        run: bun install
+        run: bun install --frozen-lockfile
 
       - name: Deploy app
         run: bun run deploy
@@ -46,4 +46,5 @@ jobs:
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
+          clean: true
           folder: out
diff --git a/.gitignore b/.gitignore
index dbdca016..43d22450 100644
--- a/.gitignore
+++ b/.gitignore
@@ -141,6 +141,8 @@ bun.lockb
 
 # Generated content
 public/styles.css
+public/docs.md
+public/docs/**/*.md
 
 # Local build files
 .vercel
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..8b68c100
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,197 @@
+# Lifecycle Docs Agent Guide
+
+Lifecycle Docs is the public, end-user documentation for Lifecycle. Keep it accurate, task-oriented, safe to follow, and easy to scan.
+
+## Load Order
+
+1. Read `PRODUCT.md` for audiences, voice, and accessibility goals. It is editorial direction, not product-behavior truth.
+2. Read `README.md` for MDX and component mechanics.
+3. Read the target page, its nearest `_meta.ts`, and adjacent pages before editing.
+4. Read `DESIGN.md` and `DESIGN.json` only for component, layout, brand, or visual-system work.
+5. Inspect the owning product source before asserting behavior.
+6. Use `$update-lifecycle-docs` for documentation synchronization, new guides, troubleshooting, or UI screenshots.
+
+## Sources of Truth
+
+Resolve product sources from the task context instead of assuming a particular
+workspace layout. Prefer, in order:
+
+1. A source checkout or path explicitly supplied for the task
+2. A configured workspace mapping
+3. The upstream commit or PR head SHA, schema, OpenAPI document, release
+   artifact, or published repository
+
+These optional environment variables provide a portable source map for scripts
+and agent sessions:
+
+| Variable                     | Owning source                                     |
+| ---------------------------- | ------------------------------------------------- |
+| `LIFECYCLE_SOURCE_DIR`       | API, OpenAPI, `lifecycle.yaml`, and Agent runtime |
+| `LIFECYCLE_UI_SOURCE_DIR`    | UI routes, labels, states, and interactions       |
+| `LIFECYCLE_CLI_SOURCE_DIR`   | CLI commands, flags, output, and exit behavior    |
+| `LIFECYCLE_HELM_SOURCE_DIR`  | Installation defaults and Helm values             |
+| `LIFECYCLE_INFRA_SOURCE_DIR` | Demo/evaluation infrastructure                    |
+
+For automated cross-repository checks, provide
+`DOCS_SCHEMA_VALIDATOR_COMMAND`, `DOCS_OPENAPI_SPEC_PATH`, and
+`DOCS_CLI_COMMAND` as documented in `README.md`. Run
+`bun run check:contracts --require-all` when all three reviewed artifacts are
+available. A reported **SKIP** is not contract verification.
+
+Do not require those exact variables when another authoritative source is
+already available. If an owning source cannot be resolved, require an upstream
+PR, commit, contract artifact, or maintainer decision. Mark the claim
+unverified instead of guessing. Never use an existing docs page as proof that
+the same page is correct.
+
+Before editing, record the exact owning source revision for each claim. If a
+checkout is dirty, distinguish committed evidence from uncommitted behavior.
+When no checkout is available, use an immutable public commit, exact PR head
+SHA, release, or contract URL. If none exists, stop at an explicit unverified
+claim or decision request; do not fill the gap from memory.
+
+The public explanation, navigation, and task guidance belong in this
+repository only after the owning product contract has been verified.
+
+## Authoring Rules
+
+- Read
+  `.agents/skills/update-lifecycle-docs/references/language-profile.md`
+  completely before any end-user content change.
+- Name the intended reader and task before editing.
+- Lead with the outcome, then prerequisites, steps, expected result, recovery, and next action.
+- Explain user-observable behavior rather than internal implementation.
+- Keep source comparisons, code-comment discrepancies, verification reasoning,
+  and implementation evidence in private review notes. Do not publish them as
+  end-user documentation.
+- In the final user-voice review, keep each sentence only when it helps the
+  reader understand, complete, verify, or recover the documented task.
+- Prefer canonical product language. Use **Environment** for the user concept; mention **Build** only when an API or CLI compatibility context requires it.
+- Give every page useful `title`, `description`, `audience`, `lastVerified`,
+  and `verificationBaseline` frontmatter. Resolve allowed values and exact
+  source revisions through `documentation-metadata.json`.
+- Prefer updating an existing page unless a distinct user task needs its own page.
+- Put copyable code, commands, and payloads in text—not screenshots.
+- Give every meaningful image descriptive alt text and adjacent instructions or a caption.
+- Give every iframe a useful title.
+- Clearly label Stable, Alpha/Beta, Labs, admin-gated, evaluation-only, and production-supported behavior.
+- Add `supportStatus` only when a product or release decision establishes it;
+  the absence of the field never implies Stable.
+- Use a product decision, release note, or visible product label as the source
+  for support status. Code presence alone does not prove public support; if the
+  status is unresolved, say so in the handoff instead of inventing a label.
+- Never publish credentials, secret values, broad secret-decoding commands, direct database mutation as normal setup, or destructive diagnostic shortcuts.
+- Do not expose private repository ownership, personal identities, access tokens, internal-only hostnames, or incidental local data in screenshots.
+- Keep tracked agent guidance portable. Do not record contributor-specific
+  filesystem paths, fixed development hosts or ports, private fixture
+  repositories, local credentials, or one workspace's process-management
+  rules.
+- Treat generated navigation and `public/llms.txt` as derivatives. Update their
+  canonical page/frontmatter/navigation sources, then run the generators and
+  review the diff; do not hand-edit generated output.
+- Preserve unrelated changes and review generated `_meta.ts` output for accidental ordering churn.
+
+## ASD-STE100 Language Profile
+
+- Maintain one end-user documentation tree under `src/pages/docs/**`.
+- Apply ASD-STE100 Issue 9 to every title, description, heading,
+  paragraph, callout, table, list, link label, caption, and image alt text.
+- Apply the same profile to maintained navigation titles and visible
+  site-chrome copy.
+- Use
+  `.agents/skills/update-lifecycle-docs/references/ste100-review.md` to review
+  all 53 rule identifiers for every changed page.
+- Set `contentProfile: asd-ste100` on each page.
+- Do not create a page-level ASD-STE100 exclusion.
+- Run `bun run check:styles`.
+- Update `documentation-style-baseline.json` only after the complete human
+  review. The baseline covers pages, documentation navigation, root Docs
+  navigation, and visible site chrome. A matching hash records review
+  coverage; it does not certify ASD-STE100 compliance.
+- Do not copy or commit the ASD-STE100 PDF, dictionaries, licensed checker
+  data, or verbatim rule text.
+
+## Raw Markdown
+
+- Read
+  `.agents/skills/update-lifecycle-docs/references/raw-markdown.md` before you
+  add an MDX construct or change the build path.
+- Every HTML documentation route must also work when `.md` is appended.
+- `scripts/generateRawMarkdown.ts` is the fail-closed MDX-to-GFM projector.
+- Treat `public/docs.md` and `public/docs/**/*.md` as untracked generated
+  files. Do not edit or commit them.
+- Add an explicit projector transform and a golden test for each new MDX
+  construct. Never discard an unknown construct silently.
+- Keep `public/llms.txt` canonical-only and link it to the raw `.md` routes.
+- Run `bun run check:raw` and confirm the static build contains every expected
+  Markdown route.
+
+## UI and Screenshot Work
+
+- Resolve the UI URL from the task, runtime output, or `LIFECYCLE_UI_URL`;
+  never assume a host or port.
+- Verify UI claims in a running desktop UI through an available browser
+  inspection tool; source inspection alone is not enough for visual behavior.
+- Use a 1440×900 desktop viewport. Do not add mobile captures unless the task explicitly requires them.
+- Enable Labs only through the supported task/runtime procedure, and label
+  Labs surfaces in the resulting documentation.
+- Never create a fixture PR, push a fixture branch, or mutate another external
+  repository unless the user authorized that external state change.
+- Before any authorized external mutation, record the exact target and
+  pre-existing state. Record every created PR, branch, Environment, Site, or
+  session and its cleanup result. Authorization to create state does not imply
+  permission to merge, reuse, or delete unrelated state.
+- Capture only stable, task-relevant states. Prefer focused application regions over full browser windows.
+- Use neutral, reversible fixture data and meaningful alt text. Do not use blur or generative editing to hide sensitive content.
+- Read `.agents/skills/update-lifecycle-docs/references/screenshots.md` before creating or refreshing screenshots.
+
+## Verification
+
+Format only the files you changed:
+
+```sh
+bunx prettier --check <changed-files>
+```
+
+Run the repository verification suite:
+
+```sh
+bun run verify
+```
+
+The suite includes STE100 mechanical checks, style-review hashes, and raw
+Markdown projection.
+
+When the task changes schema, API, or CLI claims, also supply the exact reviewed
+contract inputs and run:
+
+```sh
+bun run check:contracts --require-all
+```
+
+For screenshot changes, also inspect the focused output from
+`bun run check:screenshots`. It verifies structural properties but cannot
+replace manual review of rendered pixels and live UI state.
+
+When content or visuals change, inspect the rendered routes with an approved
+desktop browser inspection tool. If no such tool or authenticated runtime is
+available, report visual verification as incomplete; do not infer rendered
+behavior from source or disrupt another session's browser. Derive the required
+theme checks from `src/theme.config.tsx` instead of recording a theme
+assumption in tracked guidance.
+
+For local rendering, run `bun run dev` and use the URL printed by the
+development server. A caller may supply `DOCS_BASE_URL` when verification is
+performed against an existing preview or deployment.
+
+In the PR summary, identify:
+
+- Intended reader and task
+- Exact owning source revisions or immutable artifacts used for each claim
+- Changed pages
+- Runtime/browser verification
+- A sanitized external-state authorization and cleanup assertion, when
+  applicable. Keep private fixture repositories, branches, PRs, users, and
+  other contributor-specific identifiers in task scratch; include only public
+  or non-sensitive references in the PR.
+- Screenshot structural audit and manual pixel/state review, when applicable
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..e02a1cf6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# Lifecycle Docs
+
+Read and follow `AGENTS.md` before changing this repository. For
+documentation updates, language-profile work, raw Markdown, or UI screenshots,
+also read `.agents/skills/update-lifecycle-docs/SKILL.md`.
diff --git a/Dockerfile b/Dockerfile
index cd3031c7..abc4ea08 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # Stage 1: Build the Nextra app with secrets injection
-FROM oven/bun:1.2.4 AS builder
+FROM oven/bun:1.2.8 AS builder
 WORKDIR /app
 
 # Copy dependency files
diff --git a/README.md b/README.md
index 85ef4ffb..f65d8246 100644
--- a/README.md
+++ b/README.md
@@ -2,35 +2,75 @@
 
 Documentation for Lifecycle.
 
+Agents and contributors must read `AGENTS.md` before making changes. For
+documentation synchronization, gap analysis, or screenshot work, also follow
+`.agents/skills/update-lifecycle-docs/SKILL.md`.
+
 ---
 
-## Making a post
+## Adding documentation
 
-Making a post can be done in a few steps.
+1. Create the `.mdx` page under `src/pages/docs`.
+2. Add the required task and verification frontmatter:
 
-1. Create a new `.mdx` file in the `src/pages` directory.
-2. Add frontmatter to the top of the file including at least `title`, and `description`.
-   It will look like so:
    ```md
-    ---
-      title: "My Post"
-      description: "This is a description of my post."
-    ---
+   ---
+   title: My task
+   description: Complete the task safely and verify the result.
+   audience:
+     - application-developer
+   lastVerified: "<YYYY-MM-DD>"
+   verificationBaseline: "<registered-baseline-id>"
+   contentProfile: asd-ste100
+   ---
+   ```
+
+   Use audience and baseline values registered in
+   `documentation-metadata.json`. Add `supportStatus` only when that registry
+   contains a product-approved value; omission does not mean Stable.
+
+3. Read
+   `.agents/skills/update-lifecycle-docs/references/language-profile.md`.
+   Write the page to ASD-STE100 Issue 9. Use
+   `.agents/skills/update-lifecycle-docs/references/ste100-review.md` to cover
+   all 53 rule identifiers.
+4. Add the page to the nearest `_meta.ts` in its intended public navigation
+   order.
+5. Put any maintained image under `public/` in a directory that mirrors the
+   documentation route:
+
+   ```txt
+   src/pages/docs/troubleshooting/<new-page>.mdx
+   public/docs/troubleshooting/<new-page>/
    ```
-3. Write your content in markdown.
-4. Add images to the `public` directory and reference them in your markdown.
-   Images should be placed in a subdirectory of `public` with the same name as the `.mdx` file.
-     ```txt
-       // example
-       src/pages/docs/troubleshooting/<new-page>
-       public/docs/troubleshooting/new-page>
-     ```
+
+6. When adding a UI screenshot, follow the capture and catalog workflow in
+   `.agents/skills/update-lifecycle-docs/references/screenshots.md`.
+
+---
+
+## External contract checks
+
+`bun run check:contracts` validates against upstream contracts when their
+portable inputs are supplied:
+
+| Variable | Value |
+| --- | --- |
+| `DOCS_SCHEMA_VALIDATOR_COMMAND` | JSON argv array for the canonical validator; each extracted `filename="lifecycle.yaml"` file is appended |
+| `DOCS_OPENAPI_SPEC_PATH` | Path to the reviewed OpenAPI JSON artifact |
+| `DOCS_CLI_COMMAND` | JSON argv array for the reviewed `lfc` executable |
+
+The default command reports every unavailable input as **SKIP**. Use
+`bun run check:contracts --require-all` in a cross-repository validation job
+that supplies all three inputs. Commands are argv arrays, not shell strings, so
+the workflow remains portable and does not evaluate contributor-specific shell
+syntax.
 
 ---
 
 ## Components
 
-Lifecycle Docs provides a few extra components [in addition to components provided by Nextra](https://nextra.site/docs/guide/built-ins).
+Lifecycle Docs provides a few extra components [in addition to components provided by Nextra](https://nextra.site/docs/built-ins).
 View all the currently exported components [here](https://github.com/GoodRxOSS/lifecycle-docs/blob/main/src/components/index.tsx).
 
 - Components like Image & Iframe have been added to make the docs look more consistent visually.
@@ -41,23 +81,25 @@ View all the currently exported components [here](https://github.com/GoodRxOSS/l
 The `<Image>` component is a wrapper around next/image that provides a few extra features to make it easier to look nice in the docs.
 
 ```mdx
-import Image from '@lifecycle-docs/components';
+import { Image } from '@lifecycle-docs/components';
 
 <Image src="/path/to/image.png" alt="Alt text" width={16} height={9} ratio={16 / 9} />
 ```
 
-You can center the image by adding the `center` prop and some extra JSX.
+`alt` is required. Describe the information the image contributes to the
+surrounding instructions.
+
+You can constrain and center an image with normal layout classes:
 
 ```mdx
 <div className="grid pt-6">
-  <div className="place-self-center w-[500px]">
+  <div className="w-[500px] place-self-center">
     <Image
       src="/custom-multi-service-lifecycle-environments/additional-optional-services.png"
       alt="Additional Optional Services"
       height={906}
       width={538}
       ratio={538 / 906}
-      imagePosition="center"
     />
   </div>
 </div>
@@ -79,14 +121,7 @@ import { Iframe } from '@lifecycle-docs/components';
 
 ## Development
 
-Ensure you're using the correct version of node
-
-```bash
-# or, n i auto
-npm install bun -g
-```
-
-Install the dependencies
+Install the Bun version declared by `packageManager`, then install dependencies:
 
 ```bash
 bun install
@@ -98,71 +133,69 @@ Run the development server
 bun run dev
 ```
 
-## Deployment
+Open the URL printed by the development server.
 
-This site is deployed to GitHub Pages using GitHub Actions. When changes are pushed to the `oss` branch, a GitHub Action workflow automatically builds the site and deploys it to the `gh-pages` branch.
+Before opening a pull request, run:
 
-### Automatic Deployment
+```bash
+bun run verify
+```
 
-The deployment process is handled by a GitHub Actions workflow defined in `.github/workflows/deploy.yml`. This workflow:
+Useful focused checks:
 
-1. Runs when changes are pushed to the `oss` branch
-2. Sets up Bun
-3. Installs dependencies
-4. Builds the static site
-5. Deploys the built site to the `gh-pages` branch
+```bash
+bun run check:docs
+bun run check:styles
+bun run check:llms
+bun run check:raw
+bun run check:screenshots
+```
 
-### GitHub Pages Configuration
+`public/llms.txt` is generated from curated public navigation and page
+frontmatter. Update the canonical page and `_meta.ts` files, then run
+`bun run build:llms`; do not edit `public/llms.txt` directly.
 
-To enable GitHub Pages for this repository:
+## Raw Markdown
 
-1. Go to the repository on GitHub
-2. Click on "Settings"
-3. Scroll down to the "GitHub Pages" section
-4. Under "Source", select "Deploy from a branch"
-5. Under "Branch", select "gh-pages" and "/ (root)"
-6. Click "Save"
+Every documentation route also has clean Markdown at the same path with `.md`
+appended:
 
-The site will be available at `https://uselifecycle.com/`.
+| HTML | Markdown |
+| --- | --- |
+| `/docs` | `/docs.md` |
+| `/docs/features/cli` | `/docs/features/cli.md` |
 
-### Static Build for GitHub Pages
+`bun run build:raw` projects MDX into untracked files under `public/` before
+the static build. Do not edit or commit `public/docs.md` or
+`public/docs/**/*.md`.
 
-For GitHub Pages deployment, we use a simplified build process that doesn't require GitHub API access. This avoids the need for setting up GitHub secrets for the deployment workflow.
+The projector supports the repository component vocabulary and fails when a
+component cannot be represented without content loss. Read
+`.agents/skills/update-lifecycle-docs/references/raw-markdown.md` before you
+add a new MDX construct.
 
-The deployment process:
-1. Builds the site using the standard build process
-2. Creates a `.nojekyll` file to prevent GitHub Pages from processing the site with Jekyll
+`documentation-style-baseline.json` stores hashes for completed ASD-STE100
+page reviews. It also tracks documentation navigation, the visible root Docs
+navigation, and visible site chrome. After
+the human review and focused checks pass, run
+`bun run update:style-baseline`. Do not update the baseline only to silence a
+content change.
 
-### Manual Deployment
+The screenshot check validates references, intrinsic dimensions, catalog
+coverage, review status, and detectable tracked-text markers. It cannot decide
+whether rendered pixels show private data or whether the captured UI state is
+current. Manually inspect every final image and record the review in
+`.agents/skills/update-lifecycle-docs/references/screenshots.md`.
 
-You can also build and deploy the site manually:
+## Deployment
 
-1. Build the site:
-   ```bash
-   bun run deploy
-   ```
+The canonical deployment path is the GitHub Actions workflow in
+`.github/workflows/deploy.yml`. A push to `main` builds the static site and
+publishes `out/` to the `gh-pages` branch.
 
-2. The static site will be generated in the `out` directory with a `.nojekyll` file.
-
-3. To deploy manually, you can push the `out` directory to the `gh-pages` branch:
-   ```bash
-   # First time setup
-   git checkout --orphan gh-pages
-   git reset --hard
-   git commit --allow-empty -m "Initial gh-pages commit"
-   git push origin gh-pages
-   git checkout oss
-
-   # For subsequent deployments
-   bun run deploy
-   git checkout gh-pages
-   git rm -rf .
-   cp -r out/* .
-   touch .nojekyll
-   git add .
-   git commit -m "Deploy to GitHub Pages"
-   git push origin gh-pages
-   git checkout oss
-   ```
+`bun run deploy` creates the local static output and `.nojekyll` marker; it does
+not authorize or perform a production publication. Do not switch deployment
+branches, push generated output, or change GitHub Pages settings unless a
+maintainer explicitly authorizes that external state change.
 
-However, it's recommended to let the GitHub Actions workflow handle the deployment automatically.
+The public site is available at `https://uselifecycle.com/`.
diff --git a/bun.lock b/bun.lock
index 41829a4f..ce4c94b7 100644
--- a/bun.lock
+++ b/bun.lock
@@ -53,6 +53,7 @@
         "eslint": "^9.27.0",
         "eslint-plugin-react": "^7.37.5",
         "fast-glob": "^3.3.3",
+        "github-slugger": "^2.0.0",
         "globals": "^16.2.0",
         "gray-matter": "^4.0.3",
         "husky": "^9.1.7",
@@ -63,11 +64,16 @@
         "postcss": "^8.5.3",
         "postcss-import": "^16.1.0",
         "prettier": "^3.5.3",
+        "remark-gfm": "^4.0.1",
+        "remark-mdx": "^3.1.0",
+        "remark-parse": "^11.0.0",
+        "remark-stringify": "^11.0.0",
         "rimraf": "^6.0.1",
         "tailwindcss": "^^3.4.15",
         "tailwindcss-animate": "^^1.0.7",
         "typescript": "^5.8.3",
         "typescript-eslint": "^8.33.0",
+        "unified": "^11.0.5",
       },
     },
   },
diff --git a/default.conf b/default.conf
index d77e940e..7e9ffb00 100644
--- a/default.conf
+++ b/default.conf
@@ -4,13 +4,27 @@ server {
 
     root /usr/share/nginx/html;
     index index.html;
+    location = /docs/cm {
+        return 404;
+    }
+    location = /docs/cm.md {
+        return 404;
+    }
+    location ^~ /docs/cm/ {
+        return 404;
+    }
+    location ~ \.md$ {
+        types {}
+        default_type "text/markdown; charset=utf-8";
+        try_files $uri =404;
+    }
     location / {
-        try_files $uri $uri.html /index.html;
+        try_files $uri.html $uri $uri/ /index.html;
     }
     location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|otf|svg|map)$ {
         expires 6M;
         access_log off;
         add_header Cache-Control "public";
     }
-    error_page 404 /index.html;
+    error_page 404 /404.html;
 }
diff --git a/documentation-metadata.json b/documentation-metadata.json
new file mode 100644
index 00000000..1d46f1d7
--- /dev/null
+++ b/documentation-metadata.json
@@ -0,0 +1,48 @@
+{
+  "schemaVersion": 1,
+  "maintenance": {
+    "owner": "@GoodRxOSS/lifecycle-core",
+    "reviewTrigger": "owning-contract-change"
+  },
+  "audiences": [
+    "evaluator",
+    "application-developer",
+    "platform-operator",
+    "administrator",
+    "agent-user",
+    "api-user"
+  ],
+  "supportStatuses": [],
+  "verificationBaselines": {
+    "2026-07-24-comprehensive-audit": {
+      "verifiedOn": "2026-07-24",
+      "sources": {
+        "lifecycle": "9956d3e70a89c81a23c6502d03e237750c3886a4",
+        "lifecycle-ui": "b1df0cd64b4680fb241364be6cab985a2dce1f4f",
+        "lifecycle-cli": "3f8600dca8c97a715c7ae01c3a3087ba934fa4e1",
+        "helm-charts": "4c9504c8a264cfb39e09cb8cc4adbac50188dde7",
+        "lifecycle-opentofu": "b14865912608096379c28ef648f7ed99538b5600"
+      }
+    },
+    "2026-08-01-configuration-schema-fix": {
+      "verifiedOn": "2026-08-01",
+      "sources": {
+        "lifecycle": "9956d3e70a89c81a23c6502d03e237750c3886a4",
+        "lifecycle-ui": "b1df0cd64b4680fb241364be6cab985a2dce1f4f",
+        "lifecycle-cli": "483115e47542b5b210ff416d507ebceaf7dd4932",
+        "helm-charts": "4c9504c8a264cfb39e09cb8cc4adbac50188dde7",
+        "lifecycle-opentofu": "b14865912608096379c28ef648f7ed99538b5600"
+      }
+    },
+    "2026-08-01-lifecycle-mcp-preparation": {
+      "verifiedOn": "2026-08-01",
+      "sources": {
+        "lifecycle": "73b6a27f36c030ed5874a57d9ebf03848657201f",
+        "lifecycle-ui": "03d25cb7940ced77118611674582f88e15f0f7e1",
+        "lifecycle-cli": "483115e47542b5b210ff416d507ebceaf7dd4932",
+        "helm-charts": "c0257d1f88b5b30533f490d12f6293fa465b906c",
+        "lifecycle-opentofu": "b14865912608096379c28ef648f7ed99538b5600"
+      }
+    }
+  }
+}
diff --git a/documentation-style-baseline.json b/documentation-style-baseline.json
new file mode 100644
index 00000000..33f4c7d9
--- /dev/null
+++ b/documentation-style-baseline.json
@@ -0,0 +1,552 @@
+{
+  "schemaVersion": 3,
+  "updatedOn": "2026-08-01",
+  "references": {
+    "canonical": "ASD-STE100 Issue 9",
+    "canonicalRules": [
+      "1.1",
+      "1.2",
+      "1.3",
+      "1.4",
+      "1.5",
+      "1.6",
+      "1.7",
+      "1.8",
+      "1.9",
+      "1.10",
+      "1.11",
+      "1.12",
+      "1.13",
+      "1.14",
+      "2.1",
+      "2.2",
+      "3.1",
+      "3.2",
+      "3.3",
+      "3.4",
+      "3.5",
+      "3.6",
+      "3.7",
+      "4.1",
+      "4.2",
+      "4.3",
+      "4.4",
+      "4.5",
+      "5.1",
+      "5.2",
+      "5.3",
+      "5.4",
+      "5.5",
+      "6.1",
+      "6.2",
+      "6.3",
+      "6.4",
+      "6.5",
+      "6.6",
+      "7.1",
+      "7.2",
+      "7.3",
+      "8.1",
+      "8.2",
+      "8.3",
+      "8.4",
+      "8.5",
+      "8.6",
+      "8.7",
+      "9.1",
+      "9.2",
+      "9.3",
+      "9.4"
+    ]
+  },
+  "pages": {
+    "/docs": {
+      "file": "src/pages/docs/index.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "803e08b3b479ebad947b70ef369232203221cedd75cd185c4d4e0ca02f93ee50"
+    },
+    "/docs/api-authentication/api-keys": {
+      "file": "src/pages/docs/api-authentication/api-keys.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "abccff28a910388f751789b3cd1ba7aba1ef81fc98e31ba66379427332eb6257"
+    },
+    "/docs/api-authentication/overview": {
+      "file": "src/pages/docs/api-authentication/overview.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "b03afe35c3cc89a3539636567be27a94c831d7a205e0752ac6db4bf67546815a"
+    },
+    "/docs/api/overview": {
+      "file": "src/pages/docs/api/overview.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "7d157e87da781f5bd05a43ccfd2030763ab00050a958a9ca53c1c0008add6cd4"
+    },
+    "/docs/features/agent-administration": {
+      "file": "src/pages/docs/features/agent-administration.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "22fdd43dff37ccad2c1a3c3b2a3d7b1f737a24de960c00bea0da3d0a8971343d"
+    },
+    "/docs/features/agent-sessions": {
+      "file": "src/pages/docs/features/agent-sessions.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "c440c089b444d668b0026952590da606cdbbecd17790d8dfdb2346d7d2588035"
+    },
+    "/docs/features/ai-agent": {
+      "file": "src/pages/docs/features/ai-agent.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "29e68ca32de6e3de8f1eb8c3877afd82c88024d99432e62af60bdc696c4b5283"
+    },
+    "/docs/features/ai-agent-configuration": {
+      "file": "src/pages/docs/features/ai-agent-configuration.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "88ca72aa79051de8b75605615e2ed5496749b72eafbf0b91a25f9c5e621f5646"
+    },
+    "/docs/features/api-environments": {
+      "file": "src/pages/docs/features/api-environments.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "12ea39615d56eeab2a02438c2addbe6ed863b3d6e0c6baf4caff672a5c3fa39a"
+    },
+    "/docs/features/authentication": {
+      "file": "src/pages/docs/features/authentication.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "9b2447691c45022e4c7362631710ace90d38d06d4f9bcc6666b8971c6896a449"
+    },
+    "/docs/features/auto-deployment": {
+      "file": "src/pages/docs/features/auto-deployment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "c2d16a04ef6fbb671ad70f475f2a8e16f67812d01b3fbea5425f2750328178df"
+    },
+    "/docs/features/build-metadata-links": {
+      "file": "src/pages/docs/features/build-metadata-links.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "97c55fb5f65e6c7c39011bd46d1814da17e208abf13a8aaca2646d59324a8d09"
+    },
+    "/docs/features/cli": {
+      "file": "src/pages/docs/features/cli.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "88a35c2ebf6bb6ac52874de2df6edd96b99dab582e6e3de3414226d12cbe5c7c"
+    },
+    "/docs/features/cli-telemetry": {
+      "file": "src/pages/docs/features/cli-telemetry.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "c77fd2bd08a0f8cc751a87a80d8a5f8dc92918f1a43d08eef3043862e74eac37"
+    },
+    "/docs/features/configurable-labels": {
+      "file": "src/pages/docs/features/configurable-labels.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "a0728eac4304db001755e92933695858dfb7873b1870f586dae003874ceab01c"
+    },
+    "/docs/features/environment-ttl": {
+      "file": "src/pages/docs/features/environment-ttl.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "6979cbee45db7f8b518a0e05d0b461b9b67e0787b215a4519e400d18a3201ca4"
+    },
+    "/docs/features/ignore-file-patterns": {
+      "file": "src/pages/docs/features/ignore-file-patterns.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "61394d94394663b1ae2e2be2dd52c0ef9be3a03905255a917bb35d96cf4bc9e5"
+    },
+    "/docs/features/lifecycle-ui": {
+      "file": "src/pages/docs/features/lifecycle-ui.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "e9e8e26803ea904d4851dd46787a3ded142baeb721bff7a812654f7a9560ca30"
+    },
+    "/docs/features/mcp-integration": {
+      "file": "src/pages/docs/features/mcp-integration.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "d5139af83f22fbb59fa44543df90e2975f05bd1093d4a0997f3c48fa1eece2b5"
+    },
+    "/docs/features/mcp-server": {
+      "file": "src/pages/docs/features/mcp-server.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "49addadbc408af37d03f1f2e4f8b12e4ca0dcf03c6e4b7b48bb6a3fee963f582"
+    },
+    "/docs/features/native-helm-deployment": {
+      "file": "src/pages/docs/features/native-helm-deployment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "a58acbf6c95124f944ec8c910d4d4f25b79d14dd3923bc353182190d143e81fb"
+    },
+    "/docs/features/secrets": {
+      "file": "src/pages/docs/features/secrets.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "7cdaec4ca63d7e47fa7b734419ba30e323a25987fba155e81cd24834e5d6210b"
+    },
+    "/docs/features/service-dependencies": {
+      "file": "src/pages/docs/features/service-dependencies.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "9f531b80fb779a91458a096c27abf6fb6a8ed6e75a20fe8873537ad231b35b3e"
+    },
+    "/docs/features/sites": {
+      "file": "src/pages/docs/features/sites.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "598f40560777f7d3f2074137ba9b2a102ceb4f61946fc05bc74f3a85d64d6bca"
+    },
+    "/docs/features/template-variables": {
+      "file": "src/pages/docs/features/template-variables.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "0a4e4dd70e223a78eb6c642dfee60e0c34d3dae8609078db60131f3c46dfc3aa"
+    },
+    "/docs/features/webhooks": {
+      "file": "src/pages/docs/features/webhooks.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "fb218fe2659838ddabb475f1645e28048522715296a8718f5d37df7f9dc0466e"
+    },
+    "/docs/features/workspace-backends": {
+      "file": "src/pages/docs/features/workspace-backends.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "860c0b9f77ec3fb83d6d403d6f3d4d05e94cc6114cb02cd4acf3f4d675dd1264"
+    },
+    "/docs/getting-started/configure-environment": {
+      "file": "src/pages/docs/getting-started/configure-environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "afd9bcd8201163e9b1a93290309691d4c46f5f09b1567d309cb7b73b2116eea0"
+    },
+    "/docs/getting-started/create-environment": {
+      "file": "src/pages/docs/getting-started/create-environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "993562c14fafa481eead12346d1337de93fafe819662e26f356eedc13a880e2b"
+    },
+    "/docs/getting-started/delete-environment": {
+      "file": "src/pages/docs/getting-started/delete-environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "5637386b9ba1ad495e72df3ac476c7a62e5e95824a20fe6d983a5211da2f945d"
+    },
+    "/docs/getting-started/explore-environment": {
+      "file": "src/pages/docs/getting-started/explore-environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "3f67a2a743c38aaeb18cb2275c1076c9df51769898e465cced19dd369e99a6f1"
+    },
+    "/docs/getting-started/explore-static-environment": {
+      "file": "src/pages/docs/getting-started/explore-static-environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "4fe9e1b3aebcc5319cd28d1343217facd32715acfdfecc4819706419a8ce3522"
+    },
+    "/docs/getting-started/onboard-repository": {
+      "file": "src/pages/docs/getting-started/onboard-repository.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "b961c2f7e702280b4cdc4c859dca6399da9462b9c91b5ce7a1b1d6e2cea44c67"
+    },
+    "/docs/getting-started/terminology": {
+      "file": "src/pages/docs/getting-started/terminology.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "0abb535486483ce37b7532e4e8b814bc1bc411f33bb1719b0afbfe36e7c081b4"
+    },
+    "/docs/operations/architecture": {
+      "file": "src/pages/docs/operations/architecture.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "95378ac1babc753221f891b23ac1b7da589d9fab2f43f9fd8cc976b3df14dfff"
+    },
+    "/docs/operations/configuration": {
+      "file": "src/pages/docs/operations/configuration.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "dcf78161c9d44e74638153de0f0b074361ba9ac6a8878a41338d35716860d755"
+    },
+    "/docs/operations/day-two": {
+      "file": "src/pages/docs/operations/day-two.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "6f82683c8823a309bf7ceabc9115c3f82da189341f66a774315d2c3d3c00fc1f"
+    },
+    "/docs/operations/monitoring": {
+      "file": "src/pages/docs/operations/monitoring.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "8f28ff718b35b9c600da263b60057ebd8975ade6f222c52c9a14f6aee1dc8ebc"
+    },
+    "/docs/operations/security": {
+      "file": "src/pages/docs/operations/security.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "892aafebdd33b0c39b51f5c8ae6817e067679e3797d02eaaceee949b6ce13365"
+    },
+    "/docs/reference/statuses": {
+      "file": "src/pages/docs/reference/statuses.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "9f1e546c90f54816d6911a71bb2abd5c72334fe153e4a52849d6a30814abb753"
+    },
+    "/docs/releases": {
+      "file": "src/pages/docs/releases/index.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "db4c73e5c8a52b1785a19cb695fcacae932cdbe68a66814750b29af5b0368261"
+    },
+    "/docs/releases/compatibility": {
+      "file": "src/pages/docs/releases/compatibility.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "1901b9d61ca33af98a41c41382624e7c07607c6cbaffb112e71718c3e17bbb1f"
+    },
+    "/docs/schema/aurora-restore": {
+      "file": "src/pages/docs/schema/aurora-restore.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "6229361f88865ef443fe5535b240b81cd6d9a2b54793db1e23f822576f13cfa9"
+    },
+    "/docs/schema/codefresh": {
+      "file": "src/pages/docs/schema/codefresh.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "3fa10fd918e625b41feab7103a22d5cffba74ca71eb73b7fccf02a3a417d1f3b"
+    },
+    "/docs/schema/configuration": {
+      "file": "src/pages/docs/schema/configuration.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "e5af418530f552fd083d0855844e7ed89f49a7c0335d4a4d0d9662d959eb30b8"
+    },
+    "/docs/schema/docker": {
+      "file": "src/pages/docs/schema/docker.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "0cebead1b57cb6f87eb53de1bf15507376e535678bfab1922813682737009638"
+    },
+    "/docs/schema/environment": {
+      "file": "src/pages/docs/schema/environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "2ae5e1523d0bb7b3892d572f5db34c609ac09cfd38610e425157cd1ec0681ace"
+    },
+    "/docs/schema/external-http": {
+      "file": "src/pages/docs/schema/external-http.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "166fecf7f0f1a0a0e451f4451e17306cef615a1c01a124e553ce39c851e86065"
+    },
+    "/docs/schema/github": {
+      "file": "src/pages/docs/schema/github.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "6d90c58a426518bc34d557468d91c80088ad64a6784c16eb692bd91c292fd6f3"
+    },
+    "/docs/schema/helm": {
+      "file": "src/pages/docs/schema/helm.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "8e15742511246d8df0a91df004ccbd5b376fa9add9ec5bf1f8123cf0832e9a1d"
+    },
+    "/docs/schema/overview": {
+      "file": "src/pages/docs/schema/overview.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "7e139fbe62aadacded3c7bed3374fe3d86c34c86770a53a824271c35d9dc5e3f"
+    },
+    "/docs/schema/webhooks": {
+      "file": "src/pages/docs/schema/webhooks.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "15b53414913120374ca076b4396cb1fd2987a781ede7921341839973e3681a3f"
+    },
+    "/docs/setup/configure-lifecycle": {
+      "file": "src/pages/docs/setup/configure-lifecycle.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "da07ffe41700f90967f179fb7b65ac7130d90d5650e777ffa3ff77809973285f"
+    },
+    "/docs/setup/create-github-app": {
+      "file": "src/pages/docs/setup/create-github-app.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "638f90b9cc97e49aa17b08d4b14b8940690fd15ba30f9d7eacda75bbaf31deb3"
+    },
+    "/docs/setup/install-lifecycle": {
+      "file": "src/pages/docs/setup/install-lifecycle.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "675a15ac05fef8f53b5cd2e177eb24b1fac1f745e5189ae6d8fc3133d9580a0c"
+    },
+    "/docs/setup/prerequisites": {
+      "file": "src/pages/docs/setup/prerequisites.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "4281e28f958ec899b17ef6727607609e5653863b1cd403cedbf26e2d506f5bd0"
+    },
+    "/docs/setup/setup-infra": {
+      "file": "src/pages/docs/setup/setup-infra.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "d8ffadca7fa1879acbb8767228028cf06f3c9626fa36ba21b6ac534e82f10682"
+    },
+    "/docs/tips/telemetry": {
+      "file": "src/pages/docs/tips/telemetry.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "3db850a9cd8838f2cb9fd3581d897aff17e9b7cc02b3971bb50d1c524f3267a5"
+    },
+    "/docs/tips/using-mission-control": {
+      "file": "src/pages/docs/tips/using-mission-control.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "bd2d05f591c2321894649ee20489379594ee668e07e78ed9e85f664ce72594b1"
+    },
+    "/docs/troubleshooting": {
+      "file": "src/pages/docs/troubleshooting/index.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "121575542a6f0eeb000c5b3dace388b9b02ec2a34e745de1b6a83be068f9b397"
+    },
+    "/docs/troubleshooting/access-and-api": {
+      "file": "src/pages/docs/troubleshooting/access-and-api.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "90266f91972e88f323196a84db38ffa4ca0b6562b40dcb501ddc40ac9b5a443a"
+    },
+    "/docs/troubleshooting/build-issues": {
+      "file": "src/pages/docs/troubleshooting/build-issues.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "e0e56dd4687dc250a63ad88c978b1a55e95d5756d7501fc5175358e4da798453"
+    },
+    "/docs/troubleshooting/deploy-issues": {
+      "file": "src/pages/docs/troubleshooting/deploy-issues.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "d5d101e74cab84ef57079865d027370e604f9afdd3135b6a0a893094c6534e91"
+    },
+    "/docs/troubleshooting/github-app-webhooks": {
+      "file": "src/pages/docs/troubleshooting/github-app-webhooks.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "369cf931c1dedf0b7a5ee1915256f573320144db64f5c8dc0ffaba6b0cf7a49a"
+    },
+    "/docs/troubleshooting/stuck-environment": {
+      "file": "src/pages/docs/troubleshooting/stuck-environment.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "a6fb2730cb2e2a790b3fa60b44262485a26288a56a5c487ed65db8d77e88bd55"
+    },
+    "/docs/what-is-lifecycle": {
+      "file": "src/pages/docs/what-is-lifecycle.mdx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-25",
+      "sha256": "862c7c055e26b81214de6bc67851bdfc1b4e94851fab1a53b6d51771f6003b6f"
+    }
+  },
+  "surfaces": {
+    "navigation:/": {
+      "file": "src/pages/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "938d828e4bfadebd36f42d46f1c7179e67e3c6392d5b547d35f61b75a8f32a47"
+    },
+    "navigation:/docs": {
+      "file": "src/pages/docs/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "91cb82f6d854583230b2bd31f748bbcbbf27f6c89b62dbffd0a54b05f30a34e0"
+    },
+    "navigation:/docs/api": {
+      "file": "src/pages/docs/api/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "5daaf80fab18bbc39c5e61cbb87c1e3982073f49762a013ab13dd1e920537096"
+    },
+    "navigation:/docs/api-authentication": {
+      "file": "src/pages/docs/api-authentication/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "0cc155f6a10b2eed69130667b87d8d5c727c9405725a6a9bf823082434717601"
+    },
+    "navigation:/docs/features": {
+      "file": "src/pages/docs/features/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-08-01",
+      "sha256": "c9f3976a1784098cd78e6ff983b41716c1b092a3e499e1c99026bcabcadeb6b8"
+    },
+    "navigation:/docs/getting-started": {
+      "file": "src/pages/docs/getting-started/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "2c14dd06201f896050d9b9e31e6529cd3c0f015c1ea9755cb345e7e6b85367d7"
+    },
+    "navigation:/docs/operations": {
+      "file": "src/pages/docs/operations/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "2d6d4446e4934f8d04034a668ead60fc3acaa021ff7c97a7a7fd35b9a99a9f80"
+    },
+    "navigation:/docs/reference": {
+      "file": "src/pages/docs/reference/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "2f0e10969ad4580b91c720127824ee839722b6945b81387eb0d3567cecc28ea9"
+    },
+    "navigation:/docs/releases": {
+      "file": "src/pages/docs/releases/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "b48afe0e55e7cc786c8ceacc908cc32889479778af3621f6591874d5346a0dd5"
+    },
+    "navigation:/docs/schema": {
+      "file": "src/pages/docs/schema/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "bb9d40d6f76628dbf7b02b560f73b5b2a7796deed7db05e4976eba9303e3a11f"
+    },
+    "navigation:/docs/setup": {
+      "file": "src/pages/docs/setup/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "75696ccc95304e52455775f63e2674af41345dc4710ed7fc396e7dd3314c6bd4"
+    },
+    "navigation:/docs/tips": {
+      "file": "src/pages/docs/tips/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "be9cd78ce9140f3f813d18b60e7474801db6c7d6ee182569dea19a7c6755b209"
+    },
+    "navigation:/docs/troubleshooting": {
+      "file": "src/pages/docs/troubleshooting/_meta.ts",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "2dd61f939bffd5c7e7a55e45b35afd24af071229e05e6fe06e3915ad0f6b9e97"
+    },
+    "site-chrome:footer": {
+      "file": "src/components/site-footer/index.tsx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "6f7323a479f6c6b5e303f69d5e6d83caae0c7f4bd43232502ac0aba946f8e2c6"
+    },
+    "site-chrome:theme": {
+      "file": "src/theme.config.tsx",
+      "profile": "asd-ste100",
+      "reviewedOn": "2026-07-24",
+      "sha256": "a5d21a5e718c568406303219afde508fc5f0cb172fc42b623bf8b27e14f6c4f8"
+    }
+  }
+}
diff --git a/package.json b/package.json
index ed5c3d15..360a6b6b 100644
--- a/package.json
+++ b/package.json
@@ -7,10 +7,17 @@
     "build": "bun run build:prep && bun run build:styles && next build",
     "build:styles": "tailwindcss -i ./src/styles/globals.css -o public/styles.css",
     "build:meta": "bun run ./scripts/generateMeta.ts",
-    "build:tags": "bun run ./scripts/generateTagPages.ts",
-    "build:prep": "bun run clean && bun run build:tags && bun run build:meta",
+    "build:llms": "bun run ./scripts/generateLlms.ts",
+    "build:raw": "bun run ./scripts/generateRawMarkdown.ts",
+    "build:prep": "bun run clean && bun run build:meta && bun run build:llms && bun run build:raw",
+    "check:contracts": "bun run ./scripts/validateContracts.ts",
+    "check:docs": "bun run ./scripts/validateDocs.ts",
+    "check:llms": "bun run ./scripts/generateLlms.ts --check",
+    "check:raw": "bun run ./scripts/generateRawMarkdown.ts --check",
+    "check:screenshots": "bun run ./scripts/validateDocs.ts --screenshots-only",
+    "check:styles": "bun run ./scripts/validateSte100.ts",
     "clean": "rimraf src/pages/tags src/lib/data",
-    "dev": "bun run build:prep && next dev -p 3333",
+    "dev": "bun run build:prep && next dev",
     "deploy": "bun run build && touch out/.nojekyll",
     "start": "next start",
     "lint": "eslint . && next lint",
@@ -22,7 +29,9 @@
     "test": "bun test",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
-    "update": "codependence --update"
+    "update:style-baseline": "bun run ./scripts/validateSte100.ts --update-baseline",
+    "update": "codependence --update",
+    "verify": "bun run lint && bun run typecheck && bun run check:docs && bun run check:styles && bun run check:contracts && bun run check:llms && bun run check:raw && bun run check:screenshots && bun run test && bun run build"
   },
   "dependencies": {
     "@code-hike/mdx": "^0.9.0",
@@ -75,6 +84,7 @@
     "fast-glob": "^3.3.3",
     "globals": "^16.2.0",
     "gray-matter": "^4.0.3",
+    "github-slugger": "^2.0.0",
     "husky": "^9.1.7",
     "js-yaml": "^4.1.0",
     "lint-staged": "^16.1.0",
@@ -84,10 +94,15 @@
     "postcss-import": "^16.1.0",
     "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx": "^3.1.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
     "tailwindcss": "^^3.4.15",
     "tailwindcss-animate": "^^1.0.7",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.33.0"
+    "typescript-eslint": "^8.33.0",
+    "unified": "^11.0.5"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,md,mdx}": [
diff --git a/public/docs/features/lifecycle-ui/environment-list.png b/public/docs/features/lifecycle-ui/environment-list.png
new file mode 100644
index 00000000..2e034242
Binary files /dev/null and b/public/docs/features/lifecycle-ui/environment-list.png differ
diff --git a/public/docs/getting-started/explore-environment/environment-ready.png b/public/docs/getting-started/explore-environment/environment-ready.png
new file mode 100644
index 00000000..41d3f515
Binary files /dev/null and b/public/docs/getting-started/explore-environment/environment-ready.png differ
diff --git a/public/docs/getting-started/onboard-repository/repository-list.png b/public/docs/getting-started/onboard-repository/repository-list.png
new file mode 100644
index 00000000..1ac7de8e
Binary files /dev/null and b/public/docs/getting-started/onboard-repository/repository-list.png differ
diff --git a/public/docs/operations/architecture/request-flow.svg b/public/docs/operations/architecture/request-flow.svg
new file mode 100644
index 00000000..9a641fe7
--- /dev/null
+++ b/public/docs/operations/architecture/request-flow.svg
@@ -0,0 +1,108 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="title description">
+  <title id="title">Lifecycle request-to-Environment flow</title>
+  <desc id="description">GitHub, user clients, and the identity provider send requests to Lifecycle web and API services. Redis sends queued work to Lifecycle workers. Web and worker services use Postgres. Workers use object storage and run builds, Kubernetes workloads, and Site delivery. Lifecycle returns status, logs, and URLs to clients.</desc>
+  <defs>
+    <marker id="arrow-gold" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#f4d400"/>
+    </marker>
+    <marker id="arrow-muted" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#8d8a82"/>
+    </marker>
+    <filter id="soft-shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="12" flood-color="#000000" flood-opacity="0.24"/>
+    </filter>
+    <style>
+      .group { fill: #12110f; stroke: #302e29; stroke-width: 2; }
+      .box { fill: #1b1916; stroke: #49463e; stroke-width: 2; }
+      .box-accent { fill: #201d12; stroke: #f4d400; stroke-width: 2; }
+      .group-title { fill: #aaa69c; font: 600 16px Inter, ui-sans-serif, system-ui, sans-serif; letter-spacing: 2px; }
+      .label { fill: #f7f5ef; font: 650 20px Inter, ui-sans-serif, system-ui, sans-serif; }
+      .sub { fill: #b8b4aa; font: 400 15px Inter, ui-sans-serif, system-ui, sans-serif; }
+      .result-label { fill: #f4d400; font: 650 20px Inter, ui-sans-serif, system-ui, sans-serif; }
+      .result-sub { fill: #d2cec4; font: 400 16px Inter, ui-sans-serif, system-ui, sans-serif; }
+      .line-gold { fill: none; stroke: #f4d400; stroke-width: 3; marker-end: url(#arrow-gold); }
+      .line-muted { fill: none; stroke: #8d8a82; stroke-width: 2.5; marker-end: url(#arrow-muted); }
+      .line-bidirectional { fill: none; stroke: #8d8a82; stroke-width: 2.5; marker-start: url(#arrow-muted); marker-end: url(#arrow-muted); }
+    </style>
+  </defs>
+
+  <rect width="1280" height="720" rx="24" fill="#0c0b0a"/>
+
+  <rect class="group" x="30" y="42" width="260" height="535" rx="20"/>
+  <rect class="group" x="320" y="42" width="560" height="535" rx="20"/>
+  <rect class="group" x="910" y="42" width="340" height="535" rx="20"/>
+
+  <text class="group-title" x="58" y="82">REQUESTS</text>
+  <text class="group-title" x="348" y="82">LIFECYCLE CONTROL PLANE</text>
+  <text class="group-title" x="938" y="82">WORK AND DELIVERY</text>
+
+  <g filter="url(#soft-shadow)">
+    <rect class="box" x="58" y="110" width="204" height="80" rx="14"/>
+    <text class="label" x="82" y="143">GitHub</text>
+    <text class="sub" x="82" y="168">Repository events</text>
+
+    <rect class="box-accent" x="58" y="244" width="204" height="92" rx="14"/>
+    <text class="label" x="82" y="278">User clients</text>
+    <text class="sub" x="82" y="304">UI · CLI · API · MCP</text>
+
+    <rect class="box" x="58" y="390" width="204" height="80" rx="14"/>
+    <text class="label" x="82" y="423">Identity provider</text>
+    <text class="sub" x="82" y="448">Interactive sign-in</text>
+
+    <rect class="box-accent" x="370" y="110" width="220" height="86" rx="14"/>
+    <text class="label" x="394" y="145">Web and API</text>
+    <text class="sub" x="394" y="171">Authenticate and accept work</text>
+
+    <rect class="box" x="620" y="110" width="210" height="86" rx="14"/>
+    <text class="label" x="644" y="145">Redis</text>
+    <text class="sub" x="644" y="171">Queued work</text>
+
+    <rect class="box-accent" x="620" y="248" width="210" height="86" rx="14"/>
+    <text class="label" x="644" y="283">Workers</text>
+    <text class="sub" x="644" y="309">Build, deploy, and clean up</text>
+
+    <rect class="box" x="370" y="404" width="220" height="86" rx="14"/>
+    <text class="label" x="394" y="439">Postgres</text>
+    <text class="sub" x="394" y="465">Lifecycle data</text>
+
+    <rect class="box" x="620" y="404" width="210" height="86" rx="14"/>
+    <text class="label" x="644" y="439">Object storage</text>
+    <text class="sub" x="644" y="465">Logs and Site content</text>
+
+    <rect class="box" x="950" y="110" width="260" height="86" rx="14"/>
+    <text class="label" x="974" y="145">BuildKit or external CI</text>
+    <text class="sub" x="974" y="171">Build application images</text>
+
+    <rect class="box" x="950" y="248" width="260" height="86" rx="14"/>
+    <text class="label" x="974" y="283">Kubernetes</text>
+    <text class="sub" x="974" y="309">Run Environment workloads</text>
+
+    <rect class="box" x="950" y="404" width="260" height="86" rx="14"/>
+    <text class="label" x="974" y="439">Site gateway</text>
+    <text class="sub" x="974" y="465">Serve published Site content</text>
+  </g>
+
+  <path class="line-muted" d="M 262 150 C 310 150, 326 150, 370 150"/>
+  <path class="line-gold" d="M 262 290 C 308 290, 326 170, 370 158"/>
+  <path class="line-muted" d="M 262 430 C 312 430, 326 188, 370 174"/>
+
+  <path class="line-gold" d="M 590 153 L 620 153"/>
+  <path class="line-gold" d="M 725 196 L 725 248"/>
+  <path class="line-bidirectional" d="M 480 196 L 480 404"/>
+  <path class="line-bidirectional" d="M 620 291 C 568 291, 558 404, 548 404"/>
+  <path class="line-muted" d="M 725 334 L 725 404"/>
+
+  <path class="line-gold" d="M 830 276 C 882 252, 900 153, 950 153"/>
+  <path class="line-gold" d="M 830 291 L 950 291"/>
+  <path class="line-muted" d="M 830 447 L 950 447"/>
+
+  <path class="line-muted" d="M 1080 196 L 1080 606"/>
+  <path class="line-muted" d="M 1110 334 L 1110 606"/>
+  <path class="line-muted" d="M 1140 490 L 1140 606"/>
+  <path class="line-muted" d="M 830 466 C 860 520, 900 570, 960 606"/>
+
+  <rect x="320" y="614" width="930" height="76" rx="18" fill="#17150f" stroke="#f4d400" stroke-width="2"/>
+  <text class="result-label" x="354" y="647">Result</text>
+  <text class="result-sub" x="430" y="647">Environment status, logs, and URLs return to the UI, CLI, API, GitHub comments, and MCP clients.</text>
+  <path class="line-gold" d="M 320 652 C 210 652, 160 580, 160 336"/>
+</svg>
diff --git a/public/docs/simple-workflow.png b/public/docs/simple-workflow.png
deleted file mode 100644
index 00a51175..00000000
Binary files a/public/docs/simple-workflow.png and /dev/null differ
diff --git a/public/getting-started/pr-comment.png b/public/getting-started/pr-comment.png
deleted file mode 100644
index 6175c3d6..00000000
Binary files a/public/getting-started/pr-comment.png and /dev/null differ
diff --git a/public/getting-started/status-comment-building.png b/public/getting-started/status-comment-building.png
deleted file mode 100644
index 096de48c..00000000
Binary files a/public/getting-started/status-comment-building.png and /dev/null differ
diff --git a/public/getting-started/status-comment.png b/public/getting-started/status-comment.png
deleted file mode 100644
index 15b6098b..00000000
Binary files a/public/getting-started/status-comment.png and /dev/null differ
diff --git a/public/llms.txt b/public/llms.txt
index 192d494a..9090c1df 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -1,850 +1,106 @@
 # Lifecycle
 
-> Lifecycle is an ephemeral environment generator that creates isolated dev environments from a `lifecycle.yaml` config file. This guide helps AI agents assist developers in configuring their repositories.
+> End-user documentation for Lifecycle environments, configuration, automation, agents, and platform operations.
 
-## Documentation
+This index is generated from the human documentation. Follow the linked page for current prerequisites, procedures, support boundaries, and recovery guidance.
 
-- [What is Lifecycle](https://uselifecycle.com/docs/what-is-lifecycle): Overview of Lifecycle and core concepts.
-- [Terminology](https://uselifecycle.com/docs/getting-started/terminology): Key terms and definitions.
-- [Create Environment](https://uselifecycle.com/docs/getting-started/create-environment): Tutorial for creating your first environment.
-- [Configure Environment](https://uselifecycle.com/docs/getting-started/configure-environment): Tutorial for configuring services.
+## Start here
 
-## Schema Reference
+- [What is Lifecycle?](https://uselifecycle.com/docs/what-is-lifecycle.md): Understand how Lifecycle creates connected, isolated application Environments for pull requests and API-driven workflows. _(audience: evaluator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
 
-- [Schema Overview](https://uselifecycle.com/docs/schema/overview): Complete lifecycle.yaml structure reference.
-- [Environment Schema](https://uselifecycle.com/docs/schema/environment): Environment-level configuration options.
-- [GitHub Service](https://uselifecycle.com/docs/schema/github): Build services from source code.
-- [Docker Service](https://uselifecycle.com/docs/schema/docker): Deploy pre-built Docker images.
-- [Helm Service](https://uselifecycle.com/docs/schema/helm): Deploy Helm charts.
-- [Codefresh Service](https://uselifecycle.com/docs/schema/codefresh): External CI/CD pipeline integration.
-- [Configuration Service](https://uselifecycle.com/docs/schema/configuration): Metadata-only services.
-- [Webhooks Schema](https://uselifecycle.com/docs/schema/webhooks): Webhook configuration reference.
+## Getting started
 
-## Features
-
-- [Auto-Deployment](https://uselifecycle.com/docs/features/auto-deployment): Automatic deployment on PR updates.
-- [Template Variables](https://uselifecycle.com/docs/features/template-variables): Dynamic references between services.
-- [Service Dependencies](https://uselifecycle.com/docs/features/service-dependencies): Hard dependencies with `requires`.
-- [Secrets](https://uselifecycle.com/docs/features/secrets): AWS/GCP secret manager integration.
-- [Webhooks](https://uselifecycle.com/docs/features/webhooks): Trigger actions on deployment events.
-- [Configurable Labels](https://uselifecycle.com/docs/features/configurable-labels): GitHub label configuration.
-- [Environment TTL](https://uselifecycle.com/docs/features/environment-ttl): Automatic cleanup of inactive environments.
-- [Native Helm Deployment](https://uselifecycle.com/docs/features/native-helm-deployment): Kubernetes job-based Helm deployments.
-
----
-
-## Getting Started
-
-**File location:** Create `lifecycle.yaml` at the root of your repository.
-
-**Trigger deployment:** Add `lifecycle-deploy!` label to a PR, or set `autoDeploy: true` in config.
-
-**Access environment:** After deployment, environment URLs appear in PR comments.
-
-**Minimum viable config:**
-```yaml
-version: "1.0.0"
-
-environment:
-  defaultServices:
-    - name: "api"
-
-services:
-  - name: "api"
-    github:
-      repository: "org/repo"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-```
-
----
-
-## Core Concepts
-
-| Term | Definition |
-|------|------------|
-| **Service** | A deployable unit (container, database, etc.) |
-| **Environment** | A stack of services deployed together |
-| **Build/UUID** | Unique identifier for an environment instance (e.g., `arm-model-060825`) |
-| **defaultServices** | Services always deployed with every environment |
-| **optionalServices** | Services available on-demand via UI or labels |
-| **branchName** | Default branch for the repository (used for builds) |
-| **defaultTag** | Docker image tag, typically matches the default branch name |
-
-Docs: [Terminology](https://uselifecycle.com/docs/getting-started/terminology)
-
----
-
-## Decision Tree for Agents
-
-When a user wants to add a service, ask these questions in order:
-
-### Step 1: Service Type
-```
-Q: Is this service built from source code or using a pre-built image?
-
-→ "Built from source, deployed directly" → Use `github` type
-→ "Pre-built image"                      → Use `docker` type
-→ "Deploy via Helm chart"                → Use `helm` type
-```
-
-### Step 2: Build Configuration
-
-For `github` type:
-```
-Q: Where is your Dockerfile located?
-   Default: "Dockerfile" in repo root
-
-Q: What port does your application listen on?
-   Common: 3000, 8080, 80
-
-Q: Does it need a health check endpoint?
-   Common: /health, /healthz, /ready
-```
-
-For `helm` type:
-```
-Q: Is this a public chart (e.g. Bitnami), a local chart in the repo, or an OCI registry chart?
-
-Q: What is the chart name and (if public) the Helm repository URL?
-
-Q: Does it need a custom Docker build? (If yes, also collect Dockerfile location and ports)
-
-Q: What Helm values need to be set? (e.g. auth credentials, replica count)
-```
-
-### Step 3: Runtime Configuration
-```
-Q: What environment variables does your service need?
-   → Add to `env` section
-
-Q: Does it need to connect to other services?
-   → Use template variables (always quote them): "{{{service_name_internalHostname}}}"
-
-Q: Should it be publicly accessible?
-   → Set `deployment.public: true`
-```
-
-### Step 4: Dependencies
-```
-Q: Does this service depend on other services (databases, caches)?
-   → Add to `requires` array
-   → Or add dependency as separate service in defaultServices
-```
-
----
-
-## Service Types
-
-### GitHub Service (Build from Source)
-
-Use when: Building a Docker image from source code in a GitHub repository.
-
-Docs: [GitHub Schema](https://uselifecycle.com/docs/schema/github)
-
-**Required fields:**
-- `github.repository` - GitHub org/repo (e.g., "myorg/api")
-- `github.branchName` - Default branch (e.g., "main")
-- `github.docker.defaultTag` - Image tag, typically same as default branch
-- `github.docker.app.dockerfilePath` - Path to Dockerfile
-- `github.docker.app.ports` - Array of exposed ports
-
-**Nesting rules (common source of errors):**
-- `env` lives at `github.docker.app.env` — deep inside the `app` block
-- `deployment` lives at `github.deployment` — sibling of `docker`, NOT inside `docker`
-
-This asymmetry is intentional but easy to get wrong. Use the annotated template below as the reference.
-
-**Template (with env, deployment, and health check):**
-```yaml
-services:
-  - name: "SERVICE_NAME"
-    github:                          # ← github level
-      repository: "ORG/REPO"
-      branchName: "main"
-      docker:                        # ← github.docker level
-        defaultTag: "main"
-        app:                         # ← github.docker.app level
-          dockerfilePath: "Dockerfile"
-          ports:
-            - PORT_NUMBER
-          env:                       # ← env goes HERE (github.docker.app.env)
-            KEY: "value"
-      deployment:                    # ← deployment goes HERE (github.deployment, sibling of docker)
-        public: true
-        readiness:
-          httpGet:
-            path: "/health"
-            port: PORT_NUMBER
-          initialDelaySeconds: 10
-          periodSeconds: 5
-```
-
-**Optional: build engine** — add `builder` under `docker` to select the build engine (default is `buildkit`):
-```yaml
-      docker:
-        defaultTag: "main"
-        builder:
-          engine: "buildkit"   # buildkit (default), kaniko, codefresh
-        app:
-          # ...
-```
-
-**With resource limits:**
-```yaml
-services:
-  - name: "api"
-    github:
-      repository: "myorg/api"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-      deployment:
-        public: true
-        resource:
-          cpu:
-            request: "100m"
-            limit: "500m"
-          memory:
-            request: "256Mi"
-            limit: "512Mi"
-```
-
-### Docker Service (Pre-built Images)
-
-Use when: Deploying existing Docker images (databases, Redis, third-party services).
-
-Docs: [Docker Schema](https://uselifecycle.com/docs/schema/docker)
-
-**Required fields:**
-- `docker.dockerImage` - Image name (e.g., "postgres", "redis")
-- `docker.defaultTag` - Image tag (e.g., "15-alpine", "7")
-- `docker.ports` - Array of exposed ports
-
-**Important:** For docker services, `deployment` is nested **inside** `docker:`, not at the service level.
-
-**Template:**
-```yaml
-services:
-  - name: "SERVICE_NAME"
-    docker:
-      dockerImage: "IMAGE_NAME"
-      defaultTag: "TAG"
-      ports:
-        - PORT_NUMBER
-      env:
-        KEY: "value"
-      deployment:
-        public: false
-        readiness:
-          tcpSocketPort: PORT_NUMBER
-```
-
-**Common database examples:**
-
-PostgreSQL:
-```yaml
-services:
-  - name: "postgres"
-    docker:
-      dockerImage: "postgres"
-      defaultTag: "15-alpine"
-      ports:
-        - 5432
-      env:
-        POSTGRES_USER: "app"
-        POSTGRES_PASSWORD: "password"
-        POSTGRES_DB: "appdb"
-```
-
-Redis:
-```yaml
-services:
-  - name: "redis"
-    docker:
-      dockerImage: "redis"
-      defaultTag: "7-alpine"
-      ports:
-        - 6379
-      deployment:
-        readiness:
-          tcpSocketPort: 6379
-```
-
-MySQL:
-```yaml
-services:
-  - name: "mysql"
-    docker:
-      dockerImage: "mysql"
-      defaultTag: "8.0"
-      ports:
-        - 3306
-      env:
-        MYSQL_ROOT_PASSWORD: "password"
-        MYSQL_DATABASE: "appdb"
-```
-
-MongoDB:
-```yaml
-services:
-  - name: "mongo"
-    docker:
-      dockerImage: "mongo"
-      defaultTag: "6"
-      ports:
-        - 27017
-      env:
-        MONGO_INITDB_ROOT_USERNAME: "admin"
-        MONGO_INITDB_ROOT_PASSWORD: "password"
-```
-
-Nginx (public with deployment):
-```yaml
-services:
-  - name: "nginx"
-    docker:
-      dockerImage: "nginx"
-      defaultTag: "latest"
-      ports:
-        - 80
-      deployment:
-        public: true
-        resource:
-          cpu:
-            request: "10m"
-          memory:
-            request: "200Mi"
-        readiness:
-          tcpSocketPort: 80
-```
-
-### Helm Service (Helm Charts)
-
-Use when: Deploying services via Helm charts — local charts, OCI registries, or public repositories like Bitnami. Supports an optional Docker build step.
-
-Docs: [Helm Schema](https://uselifecycle.com/docs/schema/helm), [Native Helm Deployment](https://uselifecycle.com/docs/features/native-helm-deployment)
-
-**Required fields:**
-- `helm.chart.name` - Chart name, local path (`./charts/app`), OCI URL (`oci://...`), or public chart name
-- `helm.chart.repoUrl` - Helm repository URL (required for public charts)
-
-**Recommended:**
-- `helm.deploymentMethod: "native"` - Runs Helm as a Kubernetes job for real-time logs and better concurrency handling
-
-**Nesting rules:**
-- `repository` and `branchName` go directly under `helm:` (only needed when using `docker:` for a build)
-- `envMapping` goes directly under `helm:` (sibling of `chart:` and `docker:`)
-- `docker.app.env` goes at `helm.docker.app.env` — same depth as in github services
-
-**Passing env vars to Helm services — two approaches:**
-
-**Approach 1: Via `chart.values`** (for public/Bitnami charts with no custom build)
-Pass env as Helm values directly in `key=value` format. See the "Template: Public chart" example below.
-
-**Approach 2: Via `docker.app.env` + `envMapping`** (for local/org charts with a Docker build)
-Define env vars in `docker.app.env`, then use `envMapping` to tell Lifecycle where to inject them in the chart's values. Without a service-level `envMapping`, env vars will only be passed if a chart-level default is configured in `global_config`; otherwise they are not injected. See the "Template: Local chart with Docker build" example below.
-
-**Template: Public chart (e.g. Bitnami PostgreSQL)**
-```yaml
-services:
-  - name: "SERVICE_NAME"
-    helm:
-      deploymentMethod: "native"
-      chart:
-        name: "postgresql"
-        repoUrl: "https://charts.bitnami.com/bitnami"
-        version: "12.9.0"
-        values:
-          - "auth.username=myuser"
-          - "auth.password=mypassword"
-          - "auth.database=mydb"
-```
-
-**Template: Local chart with Docker build and env vars**
-```yaml
-services:
-  - name: "SERVICE_NAME"
-    helm:
-      deploymentMethod: "native"
-      repository: "ORG/REPO"
-      branchName: "main"
-      chart:                         # ← helm.chart level
-        name: "./charts/app"
-        valueFiles:
-          - "./helm/values.yaml"
-      envMapping:                    # ← helm.envMapping level (sibling of chart and docker)
-        app:
-          format: "array"            # array or map, depending on your chart's values.yaml
-          path: "env"                # path in chart values where env vars are injected
-      docker:                        # ← helm.docker level
-        defaultTag: "main"
-        builder:
-          engine: "buildkit"
-        app:                         # ← helm.docker.app level
-          dockerfilePath: "Dockerfile"
-          ports:
-            - PORT_NUMBER
-          env:                       # ← env goes HERE (helm.docker.app.env)
-            KEY: "value"
-```
-
-**Common Bitnami chart examples:**
-
-Redis:
-```yaml
-services:
-  - name: "redis"
-    helm:
-      deploymentMethod: "native"
-      chart:
-        name: "redis"
-        repoUrl: "https://charts.bitnami.com/bitnami"
-        version: "18.4.0"
-        values:
-          - "architecture=standalone"
-```
-
----
-
-## Template Variables
-
-Connect services using template variables. **Always wrap template variables in quotes.**
-
-Docs: [Template Variables](https://uselifecycle.com/docs/features/template-variables)
-
-**Format:** `"{{{variable_name}}}"`
+- [Terminology](https://uselifecycle.com/docs/getting-started/terminology.md): Canonical Lifecycle terms for Environments, Services, deployments, and automation. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Onboard a repository](https://uselifecycle.com/docs/getting-started/onboard-repository.md): Add a GitHub App installation repository to Lifecycle so pull-request and push events can create Environments. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Create your first Environment](https://uselifecycle.com/docs/getting-started/create-environment.md): Onboard a repository and create a pull-request Environment from a correct Lifecycle configuration. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Explore an Environment](https://uselifecycle.com/docs/getting-started/explore-environment.md): Make sure an Environment is ready, open a deployed Service, and use Lifecycle's pull request comments. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Configure an Environment](https://uselifecycle.com/docs/getting-started/configure-environment.md): Set Service selection, dependencies, builds, and deployments in lifecycle.yaml. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Delete an Environment](https://uselifecycle.com/docs/getting-started/delete-environment.md): Tear down a pull-request or API-created Environment safely from GitHub, the UI, the CLI, or the API. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Create a default static Environment](https://uselifecycle.com/docs/getting-started/explore-static-environment.md): Create and pin a long-lived dev-0 Environment with supported Lifecycle controls. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
 
-| Variable | Description | Example Value |
-|----------|-------------|---------------|
-| `{{{buildUUID}}}` | Environment identifier | `arm-model-060825` |
-| `{{{namespace}}}` | Kubernetes namespace | `env-arm-model-060825` |
-| `{{{SERVICE_internalHostname}}}` | Internal DNS for service | `api.env-xxx.svc.cluster.local` |
-| `{{{SERVICE_publicUrl}}}` | External URL (if public) | `api-xxx.example.com` |
-
-**Service name to variable mapping:**
-- Service name `postgres` → `"{{{postgres_internalHostname}}}"`
-- Service name `users-service` → `"{{{users-service_internalHostname}}}"`
-- Hyphens in service names are preserved in variable names
-
-**Example usage:**
-```yaml
-env:
-  DATABASE_URL: "postgresql://app:password@{{{postgres_internalHostname}}}:5432/appdb"
-  REDIS_URL: "redis://{{{redis_internalHostname}}}:6379"
-  API_URL: "https://{{{api_publicUrl}}}"
-```
-
----
-
-## Multi-Service Environments
-
-### Connecting Services
-
-Docs: [Service Dependencies](https://uselifecycle.com/docs/features/service-dependencies)
-
-**Example: API connecting to PostgreSQL and Redis**
-```yaml
-version: "1.0.0"
-
-environment:
-  defaultServices:
-    - name: "api"
-    - name: "postgres"
-    - name: "redis"
-
-services:
-  - name: "api"
-    github:
-      repository: "myorg/api"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-          env:
-            DATABASE_URL: "postgresql://app:password@{{{postgres_internalHostname}}}:5432/appdb"
-            REDIS_URL: "redis://{{{redis_internalHostname}}}:6379"
-      deployment:
-        public: true
-
-  - name: "postgres"
-    docker:
-      dockerImage: "postgres"
-      defaultTag: "15-alpine"
-      ports:
-        - 5432
-      env:
-        POSTGRES_USER: "app"
-        POSTGRES_PASSWORD: "password"
-        POSTGRES_DB: "appdb"
-
-  - name: "redis"
-    docker:
-      dockerImage: "redis"
-      defaultTag: "7-alpine"
-      ports:
-        - 6379
-```
-
-### Service Dependencies with `requires`
-
-Use `requires` when a service has hard dependencies that must be deployed together:
-
-```yaml
-services:
-  - name: "api"
-    requires:
-      - name: "postgres"
-    github:
-      # ... config
-
-  - name: "postgres"
-    docker:
-      # ... config
-```
-
-Note: `requires` only resolves 1 level deep.
-
-### Full Stack Example (Frontend + Backend + Database)
-
-```yaml
-version: "1.0.0"
-
-environment:
-  autoDeploy: true
-  defaultServices:
-    - name: "frontend"
-    - name: "api"
-    - name: "postgres"
-
-services:
-  - name: "frontend"
-    github:
-      repository: "myorg/frontend"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-          env:
-            API_URL: "https://{{{api_publicUrl}}}"
-      deployment:
-        public: true
-
-  - name: "api"
-    requires:
-      - name: "postgres"
-    github:
-      repository: "myorg/api"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 8080
-          env:
-            DATABASE_URL: "postgresql://app:password@{{{postgres_internalHostname}}}:5432/appdb"
-      deployment:
-        public: true
-        readiness:
-          httpGet:
-            path: "/health"
-            port: 8080
-
-  - name: "postgres"
-    docker:
-      dockerImage: "postgres"
-      defaultTag: "15-alpine"
-      ports:
-        - 5432
-      env:
-        POSTGRES_USER: "app"
-        POSTGRES_PASSWORD: "password"
-        POSTGRES_DB: "appdb"
-```
-
----
-
-## Environment Configuration
-
-Docs: [Environment Schema](https://uselifecycle.com/docs/schema/environment)
-
-### Auto-Deploy
-
-Automatically deploy on PR creation/updates:
-
-Docs: [Auto-Deployment](https://uselifecycle.com/docs/features/auto-deployment)
-
-```yaml
-environment:
-  autoDeploy: true
-```
-
-### Optional Services
-
-Services that can be deployed on-demand (not by default):
-
-```yaml
-environment:
-  defaultServices:
-    - name: "api"
-  optionalServices:
-    - name: "debug-tools"
-```
-
-### Cross-Repository Services
-
-Reference services from other repositories:
-
-```yaml
-environment:
-  defaultServices:
-    - name: "api"
-    - name: "shared-service"
-      repository: "myorg/shared-infra"
-      branch: "main"
-```
-
----
-
-## Advanced Features
-
-### Cloud Secrets
-
-Reference secrets from AWS Secrets Manager or GCP Secret Manager.
-
-Docs: [Secrets](https://uselifecycle.com/docs/features/secrets)
-
-```yaml
-env:
-  DB_PASSWORD: "{{aws:myapp/database:password}}"
-  API_KEY: "{{gcp:project/api-keys:main}}"
-```
-
-Format: `{{<provider>:<secret-path>:<key>}}`
-
-### Webhooks
-
-Trigger actions after deployment (e.g., run tests).
-
-Docs: [Webhooks](https://uselifecycle.com/docs/features/webhooks), [Webhooks Schema](https://uselifecycle.com/docs/schema/webhooks)
-
-```yaml
-environment:
-  webhooks:
-    - name: "E2E Tests"
-      state: deployed
-      type: docker
-      docker:
-        image: "myorg/e2e-tests:latest"
-        command: ["npm", "run", "test"]
-      env:
-        TEST_URL: "https://{{{frontend_publicUrl}}}"
-```
-
-### Persistent Storage
-
-Add persistent volumes to services:
-
-```yaml
-deployment:
-  serviceDisks:
-    - name: "data"
-      mountPath: "/var/lib/data"
-      storageSize: "5Gi"
-```
-
----
-
-## Validation Checklist
-
-Before finalizing a lifecycle.yaml, verify:
-
-- [ ] `version: "1.0.0"` is present
-- [ ] File is named `lifecycle.yaml` and located at repository root
-- [ ] Every service in `defaultServices` has a matching definition in `services`
-- [ ] All `github` services have: `repository`, `branchName`, `docker.defaultTag`, `docker.app.dockerfilePath`, `docker.app.ports`
-- [ ] All `docker` services have: `dockerImage`, `defaultTag`, `ports`
-- [ ] All `helm` services have: `chart.name` and `chart.repoUrl` (for public charts); when using a `docker:` build step also verify `repository`, `branchName`, `docker.defaultTag`, `docker.app.dockerfilePath`, and `docker.app.ports`
-- [ ] Template variables are wrapped in quotes (e.g., `"{{{postgres_internalHostname}}}"`)
-- [ ] Template variables reference existing service names
-- [ ] Public services have `deployment.public: true`
-- [ ] Health check paths match actual endpoints in the application
-
----
-
-## Information to Gather from Users
-
-When helping a user configure Lifecycle, collect:
-
-### For each service:
-1. **Service name** - Identifier used in config and template variables
-2. **Service type** - Building from source or using pre-built image?
-3. **Source details** (if building):
-   - GitHub repository (org/repo)
-   - Dockerfile location
-4. **Image details** (if pre-built):
-   - Image name and tag
-5. **Ports** - What ports does the service expose?
-6. **Environment variables** - Required config values
-7. **Dependencies** - What other services does it connect to?
-8. **Public access** - Should it be externally accessible?
-9. **Health check** - Endpoint path for readiness probe
-
-### For the environment:
-1. **Auto-deploy** - Should it deploy automatically on PR updates?
-2. **Default vs optional** - Which services are always deployed vs on-demand?
-
----
-
-## Common Patterns
-
-### Pattern: API with Database
-```yaml
-environment:
-  defaultServices:
-    - name: "api"
-    - name: "db"
-
-services:
-  - name: "api"
-    github:
-      repository: "org/api"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 8080
-          env:
-            DATABASE_URL: "postgresql://user:pass@{{{db_internalHostname}}}:5432/app"
-      deployment:
-        public: true
-
-  - name: "db"
-    docker:
-      dockerImage: "postgres"
-      defaultTag: "15-alpine"
-      ports:
-        - 5432
-      env:
-        POSTGRES_USER: "user"
-        POSTGRES_PASSWORD: "pass"
-        POSTGRES_DB: "app"
-```
-
-### Pattern: Microservices with Shared Database
-```yaml
-environment:
-  defaultServices:
-    - name: "gateway"
-    - name: "users-service"
-    - name: "orders-service"
-    - name: "postgres"
-
-services:
-  - name: "gateway"
-    github:
-      repository: "org/gateway"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 8080
-          env:
-            USERS_URL: "http://{{{users-service_internalHostname}}}:3000"
-            ORDERS_URL: "http://{{{orders-service_internalHostname}}}:3000"
-      deployment:
-        public: true
-
-  - name: "users-service"
-    github:
-      repository: "org/users-service"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-          env:
-            DATABASE_URL: "postgresql://user:pass@{{{postgres_internalHostname}}}:5432/users"
-
-  - name: "orders-service"
-    github:
-      repository: "org/orders-service"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-          env:
-            DATABASE_URL: "postgresql://user:pass@{{{postgres_internalHostname}}}:5432/orders"
-
-  - name: "postgres"
-    docker:
-      dockerImage: "postgres"
-      defaultTag: "15-alpine"
-      ports:
-        - 5432
-      env:
-        POSTGRES_USER: "user"
-        POSTGRES_PASSWORD: "pass"
-```
-
-### Pattern: Frontend + BFF (Backend for Frontend)
-```yaml
-environment:
-  defaultServices:
-    - name: "web"
-    - name: "bff"
-
-services:
-  - name: "web"
-    github:
-      repository: "org/web"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 3000
-          env:
-            API_URL: "https://{{{bff_publicUrl}}}"
-      deployment:
-        public: true
+## Features
 
-  - name: "bff"
-    github:
-      repository: "org/bff"
-      branchName: "main"
-      docker:
-        defaultTag: "main"
-        app:
-          dockerfilePath: "Dockerfile"
-          ports:
-            - 8080
-      deployment:
-        public: true
-```
+- [Authentication](https://uselifecycle.com/docs/features/authentication.md): Sign in to Lifecycle, link GitHub, sign out, and verify access controls. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Auto-deploy and labels](https://uselifecycle.com/docs/features/auto-deployment.md): Automatically deploy pull request Environments and control them with configurable GitHub labels. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Ignore File Patterns](https://uselifecycle.com/docs/features/ignore-file-patterns.md): Skip push redeploys for documentation, metadata, and other non-runtime changes. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Configurable Labels](https://uselifecycle.com/docs/features/configurable-labels.md): Use deployment-specific GitHub labels to control Environments, cleanup, and status comments. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Template Variables](https://uselifecycle.com/docs/features/template-variables.md): Use Environment, Service, and configuration values in Lifecycle Service settings. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Build metadata links](https://uselifecycle.com/docs/features/build-metadata-links.md): Add administrator-managed links to Environment details using build environment variables as templates. _(audience: application-developer, platform-operator, administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Webhooks](https://uselifecycle.com/docs/features/webhooks.md): Run Codefresh pipelines or Kubernetes Jobs after an Environment deploys, fails, or is torn down. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Service Dependencies](https://uselifecycle.com/docs/features/service-dependencies.md): Understand Service dependencies, their effects, and configuration. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Native Helm deployment](https://uselifecycle.com/docs/features/native-helm-deployment.md): Deploy Services with Helm directly in Kubernetes without an external CI/CD deployment pipeline. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Cloud secrets](https://uselifecycle.com/docs/features/secrets.md): Reference External Secrets Operator values from Lifecycle Services and native Helm deployments. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Environment expiration and cleanup](https://uselifecycle.com/docs/features/environment-ttl.md): Understand how Lifecycle cleans up pull-request environments and expires API-created environments. _(audience: application-developer, platform-operator, administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [API-created Environments](https://uselifecycle.com/docs/features/api-environments.md): Create branch-based Lifecycle Environments without a pull request. Then, track, extend, redeploy, or tear them down. _(audience: api-user, application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Sites](https://uselifecycle.com/docs/features/sites.md): Upload and manage static HTML sites through Lifecycle's UI, CLI, or authenticated v2 API. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Lifecycle Agent](https://uselifecycle.com/docs/features/ai-agent.md): Investigate a Lifecycle Environment, examine evidence, and do approved recovery tasks from the Environment details page. _(audience: agent-user; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Configure Lifecycle Agent](https://uselifecycle.com/docs/features/ai-agent-configuration.md): Configure models, instructions, tools, approvals, and repository overrides for Lifecycle Agent from Settings. _(audience: administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Agent Sessions](https://uselifecycle.com/docs/features/agent-sessions.md): Start, examine, and continue repository work with Lifecycle Agent in an isolated workspace. _(audience: agent-user; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Agent administration](https://uselifecycle.com/docs/features/agent-administration.md): Administer Lifecycle Agent availability, models, instructions, permissions, tools, workspaces, and session audit. _(audience: administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Agent workspace backends](https://uselifecycle.com/docs/features/workspace-backends.md): Compare and safely activate the runtime backend used for new Lifecycle Agent workspaces. _(audience: administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Connect external MCP servers](https://uselifecycle.com/docs/features/mcp-integration.md): Add administrator-approved Model Context Protocol servers and complete authentication for each Lifecycle Agent user. _(audience: agent-user, administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Lifecycle MCP](https://uselifecycle.com/docs/features/mcp-server.md): Enable Lifecycle MCP, connect an OAuth client, and use Lifecycle tools with existing user permissions. _(audience: agent-user, administrator, platform-operator; last verified: 2026-08-01; baseline: 2026-08-01-lifecycle-mcp-preparation)_
+- [CLI (lfc)](https://uselifecycle.com/docs/features/cli.md): Install and use the Lifecycle CLI to examine Environments, manage Services, stream logs, and validate configuration. _(audience: application-developer, platform-operator; last verified: 2026-08-01; baseline: 2026-08-01-configuration-schema-fix)_
+- [Lifecycle CLI telemetry](https://uselifecycle.com/docs/features/cli-telemetry.md): Understand the pseudonymous command-usage event sent by lfc, its destination, and how to opt out. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Use the Lifecycle UI](https://uselifecycle.com/docs/features/lifecycle-ui.md): Use the web UI to find Environments, examine Services and logs, run actions, and examine webhooks. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## API authentication
+
+- [API authentication](https://uselifecycle.com/docs/api-authentication/overview.md): Select a supported authentication method for Lifecycle v2 API requests and understand typical authorization failures. _(audience: api-user, administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [API keys](https://uselifecycle.com/docs/api-authentication/api-keys.md): Create, scope, use, rotate, and revoke personal or service API keys for authenticated Lifecycle v2 requests. _(audience: api-user, administrator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## HTTP API
+
+- [Lifecycle API overview](https://uselifecycle.com/docs/api/overview.md): Use the authenticated Lifecycle v2 API, read response envelopes, and make safe integrations. _(audience: api-user; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Lifecycle schema
+
+- [Schema overview](https://uselifecycle.com/docs/schema/overview.md): Understand the lifecycle.yaml configuration file and its structure. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Environment configuration](https://uselifecycle.com/docs/schema/environment.md): Configure deployment behavior, Service groups, and automation for ephemeral Environments. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Webhook configuration](https://uselifecycle.com/docs/schema/webhooks.md): Configure webhooks that start automated actions after Environment events. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [GitHub Service](https://uselifecycle.com/docs/schema/github.md): Build and deploy Services from GitHub repositories with Docker. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Docker Service](https://uselifecycle.com/docs/schema/docker.md): Deploy pre-built Docker images for databases, caches, and other infrastructure components. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Helm Service](https://uselifecycle.com/docs/schema/helm.md): Deploy Services with local, OCI, or public Helm charts. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Codefresh Service](https://uselifecycle.com/docs/schema/codefresh.md): Trigger external Codefresh pipelines for deployment and teardown. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Aurora Restore Service](https://uselifecycle.com/docs/schema/aurora-restore.md): Make an AWS Aurora point-in-time copy for an ephemeral Environment. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Configuration Service](https://uselifecycle.com/docs/schema/configuration.md): Deploy configuration-only Services for feature flags and shared configuration. _(audience: application-developer; last verified: 2026-08-01; baseline: 2026-08-01-configuration-schema-fix)_
+- [External HTTP Service](https://uselifecycle.com/docs/schema/external-http.md): Use an existing hosted HTTP dependency. Lifecycle does not build or deploy it. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Reference
+
+- [Environment and Service statuses](https://uselifecycle.com/docs/reference/statuses.md): Interpret Lifecycle Environment, build, deployment, and Service states. Select the correct response. _(audience: application-developer, api-user, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Setup and installation
+
+- [Starter infrastructure prerequisites](https://uselifecycle.com/docs/setup/prerequisites.md): Prepare cloud, DNS, domain, and command-line access for the starter OpenTofu evaluation path. _(audience: evaluator, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Set up an evaluation cluster](https://uselifecycle.com/docs/setup/setup-infra.md): Provision starter GKE or EKS infrastructure, DNS, dependencies, and Lifecycle for evaluation. _(audience: evaluator, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Install Lifecycle](https://uselifecycle.com/docs/setup/install-lifecycle.md): Select the OpenTofu-managed or standalone Helm installation path. Make sure that the API, UI, identity, and cluster are healthy. _(audience: evaluator, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Create the GitHub App](https://uselifecycle.com/docs/setup/create-github-app.md): Create and connect a private GitHub App for Lifecycle. _(audience: platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Optional configuration](https://uselifecycle.com/docs/setup/configure-lifecycle.md): Apply optional installation-wide settings safely after Lifecycle is running. _(audience: platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Operations
+
+- [Lifecycle architecture](https://uselifecycle.com/docs/operations/architecture.md): Understand how requests become Lifecycle Environments and plan dependencies, security controls, availability, and recovery. _(audience: evaluator, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Runtime configuration surfaces](https://uselifecycle.com/docs/operations/configuration.md): Select a supported UI, API, Helm, or repository configuration surface and verify each change. _(audience: platform-operator, administrator; last verified: 2026-08-01; baseline: 2026-08-01-lifecycle-mcp-preparation)_
+- [Security boundaries](https://uselifecycle.com/docs/operations/security.md): Understand Lifecycle authentication, network, Kubernetes, secret, and Agent boundaries before other networks can reach a deployment. _(audience: platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Monitor Lifecycle](https://uselifecycle.com/docs/operations/monitoring.md): Interpret health endpoints, verify end-to-end operation, and collect safe diagnostic data for stuck work. _(audience: platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Day-two operations](https://uselifecycle.com/docs/operations/day-two.md): Plan Lifecycle upgrades, backups, rollback decisions, recovery validation, and uninstall. _(audience: platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Releases and compatibility
+
+- [Releases](https://uselifecycle.com/docs/releases.md): Find your installed Lifecycle versions and the release information for an upgrade. _(audience: platform-operator, application-developer; last verified: 2026-08-01; baseline: 2026-08-01-lifecycle-mcp-preparation)_
+- [Compatibility and deprecation policy](https://uselifecycle.com/docs/releases/compatibility.md): Select compatible Lifecycle components and prepare a safe upgrade or rollback. _(audience: platform-operator, application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Troubleshooting
+
+- [Troubleshooting](https://uselifecycle.com/docs/troubleshooting.md): Start from a Lifecycle symptom and open the guide for the failed phase with safe evidence and recovery steps. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Troubleshoot a stuck Environment](https://uselifecycle.com/docs/troubleshooting/stuck-environment.md): Find the last Lifecycle phase that changed and distinguish queue, build, deployment, readiness, and teardown delays. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Troubleshoot a failed build](https://uselifecycle.com/docs/troubleshooting/build-issues.md): Identify the failed Service build, examine the correct job logs, correct the source or build configuration, and check a redeploy. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Troubleshoot a failed deployment](https://uselifecycle.com/docs/troubleshooting/deploy-issues.md): Find the failed Service, examine the related logs, correct the cause, and redeploy an Environment. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Missing PR comment](https://uselifecycle.com/docs/troubleshooting/github-app-webhooks.md): Diagnose failed GitHub App webhook deliveries without exposing credentials. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Troubleshoot access and API errors](https://uselifecycle.com/docs/troubleshooting/access-and-api.md): Diagnose Lifecycle sign-in, GitHub linking, API key, scope, repository, and feature-policy failures while credentials stay secret. _(audience: api-user, application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+
+## Tips
+
+- [Use the Mission Control comment](https://uselifecycle.com/docs/tips/using-mission-control.md): Select Services, change sources, set Environment overrides, and request actions from Lifecycle's editable pull-request comment. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Datadog application telemetry](https://uselifecycle.com/docs/tips/telemetry.md): Add standard Datadog labels so Datadog can correlate application telemetry by Environment and Service. _(audience: application-developer, platform-operator; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
diff --git a/public/setup/app-installed.png b/public/setup/app-installed.png
deleted file mode 100644
index 0742993a..00000000
Binary files a/public/setup/app-installed.png and /dev/null differ
diff --git a/public/setup/cert-ready.png b/public/setup/cert-ready.png
deleted file mode 100644
index 0c401cfe..00000000
Binary files a/public/setup/cert-ready.png and /dev/null differ
diff --git a/public/setup/github-app-installed.png b/public/setup/github-app-installed.png
deleted file mode 100644
index c4d90994..00000000
Binary files a/public/setup/github-app-installed.png and /dev/null differ
diff --git a/public/setup/github-app-setup.png b/public/setup/github-app-setup.png
deleted file mode 100644
index 6f0b3209..00000000
Binary files a/public/setup/github-app-setup.png and /dev/null differ
diff --git a/scripts/docsMetadata.ts b/scripts/docsMetadata.ts
new file mode 100644
index 00000000..8320e93f
--- /dev/null
+++ b/scripts/docsMetadata.ts
@@ -0,0 +1,236 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const DOCUMENTATION_METADATA = "documentation-metadata.json";
+
+export type VerificationBaseline = {
+  sources: Record<string, string>;
+  verifiedOn: string;
+};
+
+export type DocumentationMetadata = {
+  audiences: Set<string>;
+  baselines: Map<string, VerificationBaseline>;
+  maintenance: {
+    owner: string;
+    reviewTrigger: string;
+  };
+  supportStatuses: Set<string>;
+};
+
+export type ResolvedPageMetadata = {
+  audience: string[];
+  lastVerified: string;
+  supportStatus: string | null;
+  verificationBaseline: string;
+};
+
+export type PageMetadataResolution = {
+  issues: string[];
+  metadata: ResolvedPageMetadata | null;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isIsoDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const date = new Date(`${value}T00:00:00.000Z`);
+  return (
+    !Number.isNaN(date.valueOf()) && date.toISOString().slice(0, 10) === value
+  );
+}
+
+function stringRegistry(
+  value: unknown,
+  field: string,
+  { allowEmpty = false }: { allowEmpty?: boolean } = {},
+): string[] {
+  if (
+    !Array.isArray(value) ||
+    (!allowEmpty && value.length === 0) ||
+    value.some((item) => typeof item !== "string" || item.trim() === "")
+  ) {
+    throw new Error(
+      `${field} requires ${allowEmpty ? "an" : "a non-empty"} array of strings`,
+    );
+  }
+  const values = value as string[];
+  if (new Set(values).size !== values.length) {
+    throw new Error(`${field} must not contain duplicate values`);
+  }
+  return values;
+}
+
+export async function loadDocumentationMetadata(
+  rootDir: string,
+): Promise<DocumentationMetadata> {
+  const file = path.join(rootDir, DOCUMENTATION_METADATA);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await fs.promises.readFile(file, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `documentation metadata is missing or invalid JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  if (!isRecord(parsed) || parsed.schemaVersion !== 1) {
+    throw new Error("documentation metadata requires schemaVersion 1");
+  }
+
+  const maintenance = parsed.maintenance;
+  if (
+    !isRecord(maintenance) ||
+    typeof maintenance.owner !== "string" ||
+    maintenance.owner.trim() === "" ||
+    typeof maintenance.reviewTrigger !== "string" ||
+    maintenance.reviewTrigger.trim() === ""
+  ) {
+    throw new Error(
+      "maintenance requires a non-empty owner and event-driven reviewTrigger",
+    );
+  }
+
+  const audiences = stringRegistry(parsed.audiences, "audiences");
+  const supportStatuses = stringRegistry(
+    parsed.supportStatuses,
+    "supportStatuses",
+    { allowEmpty: true },
+  );
+  const baselines = new Map<string, VerificationBaseline>();
+  if (!isRecord(parsed.verificationBaselines)) {
+    throw new Error("verificationBaselines requires a keyed object");
+  }
+
+  for (const [id, rawBaseline] of Object.entries(
+    parsed.verificationBaselines,
+  )) {
+    if (
+      !id.trim() ||
+      !isRecord(rawBaseline) ||
+      typeof rawBaseline.verifiedOn !== "string" ||
+      !isIsoDate(rawBaseline.verifiedOn) ||
+      !isRecord(rawBaseline.sources) ||
+      Object.keys(rawBaseline.sources).length === 0 ||
+      Object.entries(rawBaseline.sources).some(
+        ([source, revision]) =>
+          !source.trim() ||
+          typeof revision !== "string" ||
+          !/^[0-9a-f]{40}$/i.test(revision),
+      )
+    ) {
+      throw new Error(
+        `verification baseline ${id || "(empty)"} requires verifiedOn YYYY-MM-DD and one or more named full commit revisions`,
+      );
+    }
+    baselines.set(id, {
+      sources: rawBaseline.sources as Record<string, string>,
+      verifiedOn: rawBaseline.verifiedOn,
+    });
+  }
+  if (baselines.size === 0) {
+    throw new Error("verificationBaselines requires at least one baseline");
+  }
+
+  return {
+    audiences: new Set(audiences),
+    baselines,
+    maintenance: {
+      owner: maintenance.owner.trim(),
+      reviewTrigger: maintenance.reviewTrigger.trim(),
+    },
+    supportStatuses: new Set(supportStatuses),
+  };
+}
+
+export function resolvePageMetadata(
+  data: Record<string, unknown>,
+  registry: DocumentationMetadata,
+  today = new Date().toISOString().slice(0, 10),
+): PageMetadataResolution {
+  const issues: string[] = [];
+  const rawAudience = data.audience;
+  const audience = Array.isArray(rawAudience)
+    ? rawAudience.filter(
+        (value): value is string =>
+          typeof value === "string" && value.trim() !== "",
+      )
+    : [];
+  if (
+    audience.length === 0 ||
+    audience.length !== rawAudience?.length ||
+    new Set(audience).size !== audience.length ||
+    audience.some((value) => !registry.audiences.has(value))
+  ) {
+    issues.push(
+      "frontmatter requires a non-empty, unique audience array using documentation-metadata.json values",
+    );
+  }
+
+  const lastVerified =
+    typeof data.lastVerified === "string" ? data.lastVerified : "";
+  if (!isIsoDate(lastVerified)) {
+    issues.push("frontmatter requires lastVerified in YYYY-MM-DD format");
+  } else if (lastVerified > today) {
+    issues.push("lastVerified cannot be in the future");
+  }
+
+  const verificationBaseline =
+    typeof data.verificationBaseline === "string"
+      ? data.verificationBaseline
+      : "";
+  const baseline = registry.baselines.get(verificationBaseline);
+  if (!baseline) {
+    issues.push(
+      "frontmatter requires a verificationBaseline defined in documentation-metadata.json",
+    );
+  } else if (isIsoDate(lastVerified) && lastVerified < baseline.verifiedOn) {
+    issues.push(
+      `lastVerified cannot predate verification baseline ${verificationBaseline} (${baseline.verifiedOn})`,
+    );
+  }
+
+  const supportStatus =
+    typeof data.supportStatus === "string" ? data.supportStatus : null;
+  if (
+    data.supportStatus !== undefined &&
+    (!supportStatus || !registry.supportStatuses.has(supportStatus))
+  ) {
+    issues.push(
+      "supportStatus must use an established value from documentation-metadata.json",
+    );
+  }
+
+  return {
+    issues,
+    metadata:
+      issues.length === 0
+        ? {
+            audience,
+            lastVerified,
+            supportStatus,
+            verificationBaseline,
+          }
+        : null,
+  };
+}
diff --git a/scripts/generateLlms.ts b/scripts/generateLlms.ts
new file mode 100644
index 00000000..43f67c51
--- /dev/null
+++ b/scripts/generateLlms.ts
@@ -0,0 +1,401 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import fg from "fast-glob";
+import matter from "gray-matter";
+import {
+  loadDocumentationMetadata,
+  resolvePageMetadata,
+  type DocumentationMetadata,
+} from "./docsMetadata";
+import { docsRouteToRawOutputRelativePath } from "./generateRawMarkdown";
+
+export type PublicDocsPage = {
+  audience: string[];
+  lastVerified: string;
+  route: string;
+  sectionTitle: string;
+  supportStatus: string | null;
+  title: string;
+  description: string;
+  verificationBaseline: string;
+};
+
+export type DocsGenerationOptions = {
+  rootDir?: string;
+  publicOrigin?: string;
+};
+
+type MetaEntry = {
+  display?: unknown;
+  href?: unknown;
+  title?: unknown;
+  type?: unknown;
+};
+
+const START_SECTION = "Start here";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pageRoute(rootDir: string, file: string): string {
+  const relative = path
+    .relative(path.join(rootDir, "src/pages"), file)
+    .replace(/\\/g, "/")
+    .replace(/\.mdx$/, "");
+  return `/${relative.replace(/\/index$/, "")}`;
+}
+
+function fallbackTitle(slug: string): string {
+  return slug
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function normalizeDescription(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function normalizeOrigin(value: string): string {
+  const url = new URL(value);
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error(`Docs public URL must use http or https: ${value}`);
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+async function resolvePublicOrigin(
+  rootDir: string,
+  explicitOrigin?: string,
+): Promise<string> {
+  if (explicitOrigin) return normalizeOrigin(explicitOrigin);
+  if (process.env.DOCS_PUBLIC_URL) {
+    return normalizeOrigin(process.env.DOCS_PUBLIC_URL);
+  }
+  const cname = (
+    await fs.promises.readFile(path.join(rootDir, "public/CNAME"), "utf8")
+  ).trim();
+  if (!cname) throw new Error("public/CNAME must contain the docs hostname");
+  return normalizeOrigin(`https://${cname}`);
+}
+
+async function loadMeta(directory: string): Promise<Record<string, unknown>> {
+  const metaPath = path.join(directory, "_meta.ts");
+  let stat: fs.Stats;
+  try {
+    stat = await fs.promises.stat(metaPath);
+  } catch {
+    throw new Error(
+      `${metaPath} is required to define curated public navigation`,
+    );
+  }
+
+  const url = pathToFileURL(metaPath);
+  url.searchParams.set("revision", `${stat.mtimeMs}-${stat.size}`);
+  const imported: unknown = await import(url.href);
+  const exported = isRecord(imported) ? imported.default : null;
+  if (!isRecord(exported)) {
+    throw new Error(`${metaPath} must default-export a navigation object`);
+  }
+  return exported;
+}
+
+async function directoryContainsPage(directory: string): Promise<boolean> {
+  const matches = await fg("**/*.mdx", {
+    cwd: directory,
+    onlyFiles: true,
+  });
+  return matches.length > 0;
+}
+
+function metaEntry(value: unknown): MetaEntry {
+  if (typeof value === "string") return { title: value };
+  return isRecord(value) ? value : {};
+}
+
+function isSeparator(entry: MetaEntry): boolean {
+  return entry.type === "separator";
+}
+
+function isHidden(entry: MetaEntry): boolean {
+  return entry.display === "hidden";
+}
+
+function isExternalOnly(entry: MetaEntry): boolean {
+  const href = nonEmptyString(entry.href);
+  return Boolean(href && !href.startsWith("/docs"));
+}
+
+async function readPage(
+  rootDir: string,
+  file: string,
+  sectionTitle: string,
+  navigationTitle: string | null,
+  registry: DocumentationMetadata,
+): Promise<PublicDocsPage> {
+  const source = await fs.promises.readFile(file, "utf8");
+  const { data } = matter(source);
+  const title = nonEmptyString(data.title);
+  const description = nonEmptyString(data.description);
+  const relative = path.relative(rootDir, file);
+
+  if (!title || !description) {
+    const missing = [
+      !title ? "title" : null,
+      !description ? "description" : null,
+    ]
+      .filter(Boolean)
+      .join(" and ");
+    throw new Error(
+      `${relative} requires non-empty ${missing} frontmatter before llms.txt can be generated`,
+    );
+  }
+  const resolution = resolvePageMetadata(data, registry);
+  if (!resolution.metadata) {
+    throw new Error(
+      `${relative} has invalid documentation metadata: ${resolution.issues.join("; ")}`,
+    );
+  }
+  const { audience, lastVerified, supportStatus, verificationBaseline } =
+    resolution.metadata;
+
+  return {
+    audience,
+    lastVerified,
+    route: pageRoute(rootDir, file),
+    sectionTitle,
+    supportStatus,
+    title: navigationTitle || title,
+    description: normalizeDescription(description),
+    verificationBaseline,
+  };
+}
+
+async function collectDirectoryPages({
+  rootDir,
+  directory,
+  sectionTitle,
+  visible,
+  isDocsRoot,
+  registry,
+}: {
+  rootDir: string;
+  directory: string;
+  sectionTitle: string;
+  visible: boolean;
+  isDocsRoot: boolean;
+  registry: DocumentationMetadata;
+}): Promise<PublicDocsPage[]> {
+  const navigation = await loadMeta(directory);
+  const diskEntries = await fs.promises.readdir(directory, {
+    withFileTypes: true,
+  });
+  const pageSlugs = new Set(
+    diskEntries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".mdx"))
+      .map((entry) => entry.name.replace(/\.mdx$/, "")),
+  );
+  const directorySlugs = new Set<string>();
+
+  for (const entry of diskEntries) {
+    if (
+      entry.isDirectory() &&
+      (await directoryContainsPage(path.join(directory, entry.name)))
+    ) {
+      directorySlugs.add(entry.name);
+    }
+  }
+
+  const declaredTargets = new Set<string>();
+  const pages: PublicDocsPage[] = [];
+
+  for (const [slug, rawEntry] of Object.entries(navigation)) {
+    const entry = metaEntry(rawEntry);
+    if (isSeparator(entry) || isExternalOnly(entry)) continue;
+    if (isDocsRoot && slug === "cm") {
+      throw new Error(
+        `${path.relative(rootDir, path.join(directory, "_meta.ts"))} declares the retired /docs/cm target`,
+      );
+    }
+
+    const pageExists = pageSlugs.has(slug);
+    const directoryExists = directorySlugs.has(slug);
+    if (pageExists && directoryExists) {
+      throw new Error(
+        `${path.relative(rootDir, directory)} navigation target "${slug}" is ambiguous`,
+      );
+    }
+    if (!pageExists && !directoryExists) {
+      throw new Error(
+        `${path.relative(rootDir, path.join(directory, "_meta.ts"))} declares missing target "${slug}"`,
+      );
+    }
+
+    declaredTargets.add(slug);
+    const navigationTitle = nonEmptyString(entry.title) || fallbackTitle(slug);
+    const entryVisible = visible && !isHidden(entry);
+
+    if (pageExists) {
+      const page = await readPage(
+        rootDir,
+        path.join(directory, `${slug}.mdx`),
+        sectionTitle,
+        navigationTitle,
+        registry,
+      );
+      if (entryVisible) pages.push(page);
+      continue;
+    }
+
+    const nestedSection = isDocsRoot ? navigationTitle : sectionTitle;
+    pages.push(
+      ...(await collectDirectoryPages({
+        rootDir,
+        directory: path.join(directory, slug),
+        sectionTitle: nestedSection,
+        visible: entryVisible,
+        isDocsRoot: false,
+        registry,
+      })),
+    );
+  }
+
+  const undeclared = [...pageSlugs, ...directorySlugs]
+    .filter((slug) => !declaredTargets.has(slug))
+    .sort();
+  if (undeclared.length > 0) {
+    throw new Error(
+      `${path.relative(rootDir, path.join(directory, "_meta.ts"))} omits public target(s): ${undeclared.join(", ")}`,
+    );
+  }
+
+  return pages;
+}
+
+export async function collectPublicDocsPages({
+  rootDir = process.cwd(),
+}: Pick<DocsGenerationOptions, "rootDir"> = {}): Promise<PublicDocsPage[]> {
+  const resolvedRoot = path.resolve(rootDir);
+  const docsRoot = path.join(resolvedRoot, "src/pages/docs");
+  const registry = await loadDocumentationMetadata(resolvedRoot);
+  const pages = await collectDirectoryPages({
+    rootDir: resolvedRoot,
+    directory: docsRoot,
+    sectionTitle: START_SECTION,
+    visible: true,
+    isDocsRoot: true,
+    registry,
+  });
+  const routes = new Set<string>();
+  for (const page of pages) {
+    if (routes.has(page.route)) {
+      throw new Error(
+        `Curated navigation contains duplicate route ${page.route}`,
+      );
+    }
+    routes.add(page.route);
+  }
+  return pages;
+}
+
+export function renderLlms(
+  pages: PublicDocsPage[],
+  publicOrigin: string,
+): string {
+  const lines = [
+    "# Lifecycle",
+    "",
+    "> End-user documentation for Lifecycle environments, configuration, automation, agents, and platform operations.",
+    "",
+    "This index is generated from the human documentation. Follow the linked page for current prerequisites, procedures, support boundaries, and recovery guidance.",
+    "",
+  ];
+
+  let currentSection: string | null = null;
+  for (const page of pages) {
+    if (page.sectionTitle !== currentSection) {
+      if (currentSection !== null) lines.push("");
+      currentSection = page.sectionTitle;
+      lines.push(`## ${page.sectionTitle}`, "");
+    }
+    const metadata = [
+      `audience: ${page.audience.join(", ")}`,
+      `last verified: ${page.lastVerified}`,
+      `baseline: ${page.verificationBaseline}`,
+      page.supportStatus ? `status: ${page.supportStatus}` : null,
+    ]
+      .filter(Boolean)
+      .join("; ");
+    const rawMarkdownPath = `/${docsRouteToRawOutputRelativePath(page.route)}`;
+    lines.push(
+      `- [${page.title}](${publicOrigin}${rawMarkdownPath}): ${page.description} _(${metadata})_`,
+    );
+  }
+
+  return `${lines.join("\n").trim()}\n`;
+}
+
+export async function generateLlms({
+  rootDir = process.cwd(),
+  publicOrigin,
+}: DocsGenerationOptions = {}): Promise<string> {
+  const resolvedRoot = path.resolve(rootDir);
+  const pages = await collectPublicDocsPages({ rootDir: resolvedRoot });
+  const origin = await resolvePublicOrigin(resolvedRoot, publicOrigin);
+  return renderLlms(pages, origin);
+}
+
+async function runCli() {
+  const rootDir = process.cwd();
+  const output = await generateLlms({ rootDir });
+  const outputPath = path.join(rootDir, "public/llms.txt");
+  if (process.argv.includes("--check")) {
+    let current: string | null = null;
+    try {
+      current = await fs.promises.readFile(outputPath, "utf8");
+    } catch {
+      current = null;
+    }
+    if (current !== output) {
+      throw new Error(
+        "public/llms.txt is stale or missing. Run `bun run build:llms` and commit the result.",
+      );
+    }
+    console.log("public/llms.txt matches the documentation page tree.");
+    return;
+  }
+
+  await fs.promises.writeFile(outputPath, output);
+  console.log("Generated public/llms.txt from curated public navigation.");
+}
+
+if (import.meta.main) {
+  try {
+    await runCli();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
diff --git a/scripts/generateRawMarkdown.ts b/scripts/generateRawMarkdown.ts
new file mode 100644
index 00000000..54bec1eb
--- /dev/null
+++ b/scripts/generateRawMarkdown.ts
@@ -0,0 +1,1346 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import matter from "gray-matter";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import remarkStringify from "remark-stringify";
+import { unified } from "unified";
+
+export const GENERATED_RAW_MARKDOWN_SENTINEL =
+  "<!-- GENERATED BY scripts/generateRawMarkdown.ts. DO NOT EDIT. -->";
+
+export type RawMarkdownRoute = {
+  outputRelativePath: string;
+  route: string;
+  sourceRelativePath: string;
+};
+
+export type RawMarkdownPage = RawMarkdownRoute & {
+  markdown: string;
+  sourcePath: string;
+};
+
+export type RawMarkdownGenerationOptions = {
+  check?: boolean;
+  rootDir?: string;
+};
+
+export type RawMarkdownGenerationResult = {
+  outdatedCount: number;
+  projectedCount: number;
+  removedCount: number;
+  staleCount: number;
+  writtenCount: number;
+};
+
+type Position = {
+  start?: {
+    column?: number;
+    line?: number;
+  };
+};
+
+type AstNode = {
+  [key: string]: unknown;
+  attributes?: AstNode[];
+  children?: AstNode[];
+  data?: {
+    estree?: AstNode;
+  };
+  meta?: string | null;
+  name?: string | null;
+  position?: Position;
+  type: string;
+  value?: unknown;
+};
+
+type TransformContext = {
+  lineOffset: number;
+  sourcePath: string;
+};
+
+const STANDARD_PHRASE_NODES = new Set([
+  "break",
+  "delete",
+  "emphasis",
+  "footnoteReference",
+  "image",
+  "imageReference",
+  "inlineCode",
+  "link",
+  "linkReference",
+  "strong",
+  "text",
+]);
+
+const DECORATIVE_CALLOUT_EMOJI_LITERALS = new Set(["⚠️"]);
+const DECORATIVE_CALLOUT_ICON_NAMES = new Set(["Info"]);
+
+function normalizedSourceRelativePath(sourceRelativePath: string): string {
+  const normalized = sourceRelativePath.replace(/\\/g, "/");
+  const segments = normalized.split("/");
+  if (
+    !normalized ||
+    path.posix.isAbsolute(normalized) ||
+    !normalized.endsWith(".mdx") ||
+    segments.some((segment) => !segment || segment === "." || segment === "..")
+  ) {
+    throw new Error(
+      `Documentation source path must be a safe relative .mdx path: ${sourceRelativePath}`,
+    );
+  }
+  return normalized;
+}
+
+export function sourceRelativePathToDocsRoute(
+  sourceRelativePath: string,
+): string {
+  const normalized = normalizedSourceRelativePath(sourceRelativePath);
+  let slug = normalized.slice(0, -".mdx".length);
+  if (slug === "index") slug = "";
+  else if (slug.endsWith("/index")) slug = slug.slice(0, -"/index".length);
+  return slug ? `/docs/${slug}` : "/docs";
+}
+
+export function docsRouteToRawOutputRelativePath(route: string): string {
+  if (
+    route !== "/docs" &&
+    (!route.startsWith("/docs/") ||
+      route.endsWith("/") ||
+      route.split("/").some((segment) => segment === "." || segment === ".."))
+  ) {
+    throw new Error(`Invalid documentation route: ${route}`);
+  }
+  return route === "/docs" ? "docs.md" : `${route.slice(1)}.md`;
+}
+
+export function docsRouteToHtmlOutputRelativePath(route: string): string {
+  docsRouteToRawOutputRelativePath(route);
+  return route === "/docs" ? "docs.html" : `${route.slice(1)}.html`;
+}
+
+export function sourceRelativePathToRawOutputRelativePath(
+  sourceRelativePath: string,
+): string {
+  return docsRouteToRawOutputRelativePath(
+    sourceRelativePathToDocsRoute(sourceRelativePath),
+  );
+}
+
+export function rawMarkdownRouteForSource(
+  sourceRelativePath: string,
+): RawMarkdownRoute {
+  const normalized = normalizedSourceRelativePath(sourceRelativePath);
+  const route = sourceRelativePathToDocsRoute(normalized);
+  return {
+    outputRelativePath: docsRouteToRawOutputRelativePath(route),
+    route,
+    sourceRelativePath: normalized,
+  };
+}
+
+export function validateRawRouteCollisions(routes: RawMarkdownRoute[]): void {
+  const byRoute = new Map<string, string>();
+  const byOutput = new Map<string, string>();
+  for (const item of routes) {
+    const priorRoute = byRoute.get(item.route);
+    if (priorRoute) {
+      throw new Error(
+        `Raw Markdown route collision: ${priorRoute} and ${item.sourceRelativePath} both map to ${item.route}`,
+      );
+    }
+    byRoute.set(item.route, item.sourceRelativePath);
+
+    const priorOutput = byOutput.get(item.outputRelativePath);
+    if (priorOutput) {
+      throw new Error(
+        `Raw Markdown output collision: ${priorOutput} and ${item.sourceRelativePath} both map to ${item.outputRelativePath}`,
+      );
+    }
+    byOutput.set(item.outputRelativePath, item.sourceRelativePath);
+  }
+}
+
+export function validateExportedFileBijection(
+  routes: RawMarkdownRoute[],
+): void {
+  const htmlFiles = new Map<string, string>();
+  const rawFiles = new Map<string, string>();
+
+  for (const item of routes) {
+    const expectedRaw = docsRouteToRawOutputRelativePath(item.route);
+    const html = docsRouteToHtmlOutputRelativePath(item.route);
+    if (item.outputRelativePath !== expectedRaw) {
+      throw new Error(
+        `Exported documentation file mismatch: ${item.sourceRelativePath} maps to ${html}, so its raw counterpart must be ${expectedRaw}, not ${item.outputRelativePath}`,
+      );
+    }
+
+    const priorHtml = htmlFiles.get(html);
+    if (priorHtml) {
+      throw new Error(
+        `Exported HTML file collision: ${priorHtml} and ${item.sourceRelativePath} both map to ${html}`,
+      );
+    }
+    htmlFiles.set(html, item.sourceRelativePath);
+
+    const priorRaw = rawFiles.get(expectedRaw);
+    if (priorRaw) {
+      throw new Error(
+        `Exported raw Markdown file collision: ${priorRaw} and ${item.sourceRelativePath} both map to ${expectedRaw}`,
+      );
+    }
+    rawFiles.set(expectedRaw, item.sourceRelativePath);
+  }
+
+  if (htmlFiles.size !== rawFiles.size || htmlFiles.size !== routes.length) {
+    throw new Error(
+      `Exported documentation file mismatch: found ${htmlFiles.size} HTML file(s), ${rawFiles.size} raw Markdown file(s), and ${routes.length} route(s)`,
+    );
+  }
+}
+
+export function validateDocumentationSourcePaths(
+  sourceRelativePaths: string[],
+): number {
+  const normalized = sourceRelativePaths.map(normalizedSourceRelativePath);
+  const retired = normalized.filter(
+    (item) => item === "cm.mdx" || item.startsWith("cm/"),
+  );
+  if (retired.length > 0) {
+    throw new Error(
+      `The retired /docs/cm route namespace cannot contain source pages: ${retired.sort().join(", ")}`,
+    );
+  }
+  return normalized.length;
+}
+
+function location(node: AstNode, context: TransformContext): string {
+  const line = node.position?.start?.line;
+  const column = node.position?.start?.column;
+  if (line === undefined) return context.sourcePath;
+  return `${context.sourcePath}:${line + context.lineOffset}:${column ?? 1}`;
+}
+
+function unsupported(
+  node: AstNode,
+  context: TransformContext,
+  detail: string,
+): never {
+  const name = node.name ? ` <${node.name}>` : "";
+  throw new Error(
+    `${location(node, context)}: ${detail} [${node.type}${name}]`,
+  );
+}
+
+function cloneScalarFields(
+  node: AstNode,
+  fields: string[],
+): Record<string, unknown> {
+  const cloned: Record<string, unknown> = { type: node.type };
+  for (const field of fields) {
+    if (node[field] !== undefined && node[field] !== null) {
+      cloned[field] = node[field];
+    }
+  }
+  return cloned;
+}
+
+function validateAttributes(
+  node: AstNode,
+  allowed: Set<string>,
+  context: TransformContext,
+): void {
+  for (const attribute of node.attributes ?? []) {
+    if (
+      attribute.type !== "mdxJsxAttribute" ||
+      typeof attribute.name !== "string"
+    ) {
+      unsupported(
+        attribute,
+        context,
+        "JSX spread attributes are not supported",
+      );
+    }
+    if (!allowed.has(attribute.name)) {
+      unsupported(
+        attribute,
+        context,
+        `Unsupported attribute "${attribute.name}" on <${node.name}>`,
+      );
+    }
+  }
+}
+
+function findAttribute(node: AstNode, name: string): AstNode | null {
+  return (
+    node.attributes?.find(
+      (attribute) =>
+        attribute.type === "mdxJsxAttribute" && attribute.name === name,
+    ) ?? null
+  );
+}
+
+function requiredLiteralAttribute(
+  node: AstNode,
+  name: string,
+  context: TransformContext,
+): string {
+  const attribute = findAttribute(node, name);
+  if (!attribute || typeof attribute.value !== "string") {
+    unsupported(
+      attribute ?? node,
+      context,
+      `<${node.name}> requires a literal "${name}" attribute`,
+    );
+  }
+  if (!attribute.value.trim()) {
+    unsupported(
+      attribute,
+      context,
+      `<${node.name}> requires a non-empty "${name}" attribute`,
+    );
+  }
+  return attribute.value;
+}
+
+function optionalLiteralAttribute(
+  node: AstNode,
+  name: string,
+  context: TransformContext,
+): string | null {
+  const attribute = findAttribute(node, name);
+  if (!attribute) return null;
+  if (typeof attribute.value !== "string") {
+    unsupported(
+      attribute,
+      context,
+      `<${node.name}> "${name}" must be a literal string`,
+    );
+  }
+  return attribute.value;
+}
+
+function expressionFromEstree(node: AstNode): AstNode | null {
+  const program = node.data?.estree;
+  if (!program || program.type !== "Program" || !Array.isArray(program.body)) {
+    return null;
+  }
+  if (program.body.length !== 1) return null;
+  const statement = program.body[0];
+  if (
+    !statement ||
+    statement.type !== "ExpressionStatement" ||
+    typeof statement.expression !== "object" ||
+    statement.expression === null
+  ) {
+    return null;
+  }
+  return statement.expression as AstNode;
+}
+
+function tabsLabels(node: AstNode, context: TransformContext): string[] {
+  const attribute = findAttribute(node, "items");
+  if (
+    !attribute ||
+    typeof attribute.value !== "object" ||
+    attribute.value === null
+  ) {
+    unsupported(
+      attribute ?? node,
+      context,
+      "<Tabs> requires an items string-array expression",
+    );
+  }
+  const expression = expressionFromEstree(attribute.value as AstNode);
+  if (
+    !expression ||
+    expression.type !== "ArrayExpression" ||
+    !Array.isArray(expression.elements)
+  ) {
+    unsupported(
+      attribute,
+      context,
+      "<Tabs> items must be a static array of string literals",
+    );
+  }
+  const labels: string[] = [];
+  for (const element of expression.elements) {
+    if (
+      typeof element !== "object" ||
+      element === null ||
+      (element as AstNode).type !== "Literal" ||
+      typeof (element as AstNode).value !== "string"
+    ) {
+      unsupported(
+        attribute,
+        context,
+        "<Tabs> items must contain only string literals",
+      );
+    }
+    labels.push((element as AstNode).value as string);
+  }
+  return labels;
+}
+
+function literalStringExpression(
+  node: AstNode,
+  context: TransformContext,
+): string {
+  const expression = expressionFromEstree(node);
+  if (
+    !expression ||
+    expression.type !== "Literal" ||
+    typeof expression.value !== "string"
+  ) {
+    unsupported(
+      node,
+      context,
+      "Only a static string expression is supported inside <code>",
+    );
+  }
+  return expression.value;
+}
+
+function isReviewedCalloutIconElement(expression: AstNode): boolean {
+  if (expression.type !== "JSXElement") return false;
+  const opening = expression.openingElement;
+  if (typeof opening !== "object" || opening === null) return false;
+  const openingElement = opening as Record<string, unknown>;
+  const name = openingElement.name;
+  if (typeof name !== "object" || name === null) return false;
+  const identifier = name as Record<string, unknown>;
+
+  return (
+    openingElement.type === "JSXOpeningElement" &&
+    openingElement.selfClosing === true &&
+    Array.isArray(openingElement.attributes) &&
+    openingElement.attributes.length === 0 &&
+    identifier.type === "JSXIdentifier" &&
+    typeof identifier.name === "string" &&
+    DECORATIVE_CALLOUT_ICON_NAMES.has(identifier.name) &&
+    expression.closingElement === null &&
+    Array.isArray(expression.children) &&
+    expression.children.length === 0
+  );
+}
+
+function validateCalloutDecoration(
+  node: AstNode,
+  context: TransformContext,
+): void {
+  const emoji = findAttribute(node, "emoji");
+  if (emoji) {
+    const expression =
+      typeof emoji.value === "object" && emoji.value !== null
+        ? expressionFromEstree(emoji.value as AstNode)
+        : null;
+    const reviewedEmoji =
+      (typeof emoji.value === "string" &&
+        DECORATIVE_CALLOUT_EMOJI_LITERALS.has(emoji.value)) ||
+      (expression !== null && isReviewedCalloutIconElement(expression));
+    if (!reviewedEmoji) {
+      unsupported(
+        emoji,
+        context,
+        '<Callout> "emoji" must be a reviewed static decoration: emoji="⚠️" or emoji={<Info />}',
+      );
+    }
+  }
+
+  const icon = findAttribute(node, "icon");
+  if (icon) {
+    const expression =
+      typeof icon.value === "object" && icon.value !== null
+        ? expressionFromEstree(icon.value as AstNode)
+        : null;
+    if (
+      !expression ||
+      expression.type !== "Identifier" ||
+      typeof expression.name !== "string" ||
+      !DECORATIVE_CALLOUT_ICON_NAMES.has(expression.name)
+    ) {
+      unsupported(
+        icon,
+        context,
+        '<Callout> "icon" must be the reviewed static decoration icon={Info}',
+      );
+    }
+  }
+}
+
+function transformPhrasingChildren(
+  children: AstNode[] | undefined,
+  context: TransformContext,
+): AstNode[] {
+  return (children ?? []).flatMap((child) =>
+    transformPhrasingNode(child, context),
+  );
+}
+
+function transformPhrasingNode(
+  node: AstNode,
+  context: TransformContext,
+): AstNode[] {
+  if (node.type === "mdxTextExpression") {
+    unsupported(
+      node,
+      context,
+      "Standalone MDX expressions are not supported; only static strings inside <code> can be projected",
+    );
+  }
+
+  if (node.type === "mdxJsxTextElement") {
+    if (node.name === "br") {
+      validateAttributes(node, new Set(), context);
+      if ((node.children?.length ?? 0) > 0) {
+        unsupported(node, context, "<br> cannot have children");
+      }
+      return [{ type: "break" }];
+    }
+
+    if (node.name === "code") {
+      validateAttributes(node, new Set(), context);
+      let value = "";
+      for (const child of node.children ?? []) {
+        if (child.type === "text" && typeof child.value === "string") {
+          value += child.value;
+        } else if (child.type === "mdxTextExpression") {
+          value += literalStringExpression(child, context);
+        } else {
+          unsupported(
+            child,
+            context,
+            "<code> can contain only text or static string expressions",
+          );
+        }
+      }
+      return [{ type: "inlineCode", value }];
+    }
+
+    if (node.name === "div") {
+      validateAttributes(node, new Set(["className"]), context);
+      return transformPhrasingChildren(node.children, context);
+    }
+
+    unsupported(node, context, "Unsupported inline JSX element");
+  }
+
+  if (!STANDARD_PHRASE_NODES.has(node.type)) {
+    unsupported(node, context, "Unsupported Markdown phrasing node");
+  }
+
+  switch (node.type) {
+    case "text":
+    case "inlineCode":
+      if (typeof node.value !== "string") {
+        unsupported(node, context, "Text node does not contain a string");
+      }
+      return [{ type: node.type, value: node.value }];
+    case "break":
+      return [{ type: "break" }];
+    case "image":
+      return [cloneScalarFields(node, ["url", "title", "alt"]) as AstNode];
+    case "imageReference":
+      return [
+        cloneScalarFields(node, [
+          "identifier",
+          "label",
+          "referenceType",
+          "alt",
+        ]) as AstNode,
+      ];
+    case "footnoteReference":
+      return [cloneScalarFields(node, ["identifier", "label"]) as AstNode];
+    case "link":
+    case "linkReference": {
+      const fields =
+        node.type === "link"
+          ? ["url", "title"]
+          : ["identifier", "label", "referenceType"];
+      return [
+        {
+          ...cloneScalarFields(node, fields),
+          children: transformPhrasingChildren(node.children, context),
+        } as AstNode,
+      ];
+    }
+    case "delete":
+    case "emphasis":
+    case "strong":
+      return [
+        {
+          type: node.type,
+          children: transformPhrasingChildren(node.children, context),
+        },
+      ];
+    default:
+      return unsupported(node, context, "Unsupported Markdown phrasing node");
+  }
+}
+
+function filenameParagraph(filename: string): AstNode {
+  return {
+    type: "paragraph",
+    children: [
+      {
+        type: "strong",
+        children: [{ type: "text", value: "File:" }],
+      },
+      { type: "text", value: " " },
+      { type: "inlineCode", value: filename },
+    ],
+  };
+}
+
+function codeFilename(node: AstNode, context: TransformContext): string | null {
+  const meta = node.meta?.trim();
+  if (!meta) return null;
+
+  const explicit = /(?:^|\s)filename=(?:"([^"]+)"|'([^']+)'|([^\s]+))/.exec(
+    meta,
+  );
+  const filename = explicit
+    ? (explicit[1] ?? explicit[2] ?? explicit[3])
+    : null;
+  let remaining = explicit
+    ? `${meta.slice(0, explicit.index)} ${meta.slice(
+        explicit.index + explicit[0].length,
+      )}`
+    : meta;
+  remaining = remaining.replace(/\{[^{}]*\}/g, " ").trim();
+
+  if (filename) {
+    if (remaining) {
+      unsupported(
+        node,
+        context,
+        `Unsupported code-fence metadata after filename: ${remaining}`,
+      );
+    }
+    return filename;
+  }
+
+  if (remaining && !/\s/.test(remaining) && !remaining.includes("=")) {
+    return remaining;
+  }
+  if (!remaining) return null;
+  unsupported(node, context, `Unsupported code-fence metadata: ${remaining}`);
+}
+
+function transformCode(node: AstNode, context: TransformContext): AstNode[] {
+  if (typeof node.value !== "string") {
+    unsupported(node, context, "Code block does not contain a string");
+  }
+  const code: AstNode = {
+    type: "code",
+    value: node.value,
+  };
+  if (typeof node.lang === "string" && node.lang) code.lang = node.lang;
+  const filename = codeFilename(node, context);
+  return filename ? [filenameParagraph(filename), code] : [code];
+}
+
+function transformCallout(node: AstNode, context: TransformContext): AstNode[] {
+  validateAttributes(node, new Set(["emoji", "icon", "type"]), context);
+  validateCalloutDecoration(node, context);
+  const type = optionalLiteralAttribute(node, "type", context) ?? "info";
+  const labels: Record<string, string> = {
+    caution: "CAUTION",
+    danger: "CAUTION",
+    error: "CAUTION",
+    important: "IMPORTANT",
+    info: "NOTE",
+    note: "NOTE",
+    tip: "TIP",
+    warning: "WARNING",
+  };
+  const label = labels[type.toLowerCase()];
+  if (!label) {
+    unsupported(node, context, `Unsupported Callout type "${type}"`);
+  }
+  const children = transformBlockChildren(node.children, context);
+  const marker: AstNode = { type: "html", value: `[!${label}]\n` };
+  if (children[0]?.type === "paragraph") {
+    children[0] = {
+      ...children[0],
+      children: [marker, ...(children[0].children ?? [])],
+    };
+  } else {
+    children.unshift({
+      type: "paragraph",
+      children: [{ type: "html", value: `[!${label}]` }],
+    });
+  }
+  return [{ type: "blockquote", children }];
+}
+
+function transformTabs(node: AstNode, context: TransformContext): AstNode[] {
+  validateAttributes(node, new Set(["items"]), context);
+  const labels = tabsLabels(node, context);
+  const tabs = node.children ?? [];
+  if (tabs.length !== labels.length) {
+    unsupported(
+      node,
+      context,
+      `<Tabs> has ${labels.length} label(s) but ${tabs.length} tab panel(s)`,
+    );
+  }
+
+  return tabs.flatMap((tab, index) => {
+    if (
+      !["mdxJsxFlowElement", "mdxJsxTextElement"].includes(tab.type) ||
+      tab.name !== "Tabs.Tab"
+    ) {
+      unsupported(tab, context, "<Tabs> can contain only <Tabs.Tab> elements");
+    }
+    validateAttributes(tab, new Set(), context);
+    return [
+      {
+        type: "paragraph",
+        children: [
+          {
+            type: "strong",
+            children: [{ type: "text", value: labels[index] }],
+          },
+        ],
+      },
+      ...transformBlockChildren(tab.children, context),
+    ] as AstNode[];
+  });
+}
+
+function transformCard(node: AstNode, context: TransformContext): AstNode {
+  validateAttributes(node, new Set(["href", "title"]), context);
+  const title = requiredLiteralAttribute(node, "title", context);
+  const href = requiredLiteralAttribute(node, "href", context);
+  const description = transformBlockChildren(node.children, context);
+  const link: AstNode = {
+    type: "link",
+    url: href,
+    children: [{ type: "text", value: title }],
+  };
+
+  if (description[0]?.type === "paragraph") {
+    const [first, ...rest] = description;
+    return {
+      type: "listItem",
+      children: [
+        {
+          type: "paragraph",
+          children: [
+            link,
+            { type: "text", value: " — " },
+            ...(first.children ?? []),
+          ],
+        },
+        ...rest,
+      ],
+    };
+  }
+
+  return {
+    type: "listItem",
+    children: [{ type: "paragraph", children: [link] }, ...description],
+  };
+}
+
+function transformCards(node: AstNode, context: TransformContext): AstNode[] {
+  validateAttributes(node, new Set(), context);
+  const items = (node.children ?? []).map((card) => {
+    if (
+      !["mdxJsxFlowElement", "mdxJsxTextElement"].includes(card.type) ||
+      card.name !== "Cards.Card"
+    ) {
+      unsupported(
+        card,
+        context,
+        "<Cards> can contain only <Cards.Card> elements",
+      );
+    }
+    return transformCard(card, context);
+  });
+  return [{ type: "list", ordered: false, spread: false, children: items }];
+}
+
+function transformFlowJsx(node: AstNode, context: TransformContext): AstNode[] {
+  switch (node.name) {
+    case "Callout":
+      return transformCallout(node, context);
+    case "Steps":
+      validateAttributes(node, new Set(), context);
+      return transformBlockChildren(node.children, context);
+    case "Tabs":
+      return transformTabs(node, context);
+    case "Cards":
+      return transformCards(node, context);
+    case "Image": {
+      validateAttributes(
+        node,
+        new Set([
+          "alt",
+          "className",
+          "height",
+          "priority",
+          "ratio",
+          "src",
+          "title",
+          "width",
+        ]),
+        context,
+      );
+      const src = requiredLiteralAttribute(node, "src", context);
+      const alt = requiredLiteralAttribute(node, "alt", context);
+      const title = optionalLiteralAttribute(node, "title", context);
+      return [
+        {
+          type: "paragraph",
+          children: [
+            {
+              type: "image",
+              url: src,
+              alt,
+              ...(title ? { title } : {}),
+            },
+          ],
+        },
+      ];
+    }
+    case "Iframe": {
+      validateAttributes(node, new Set(["src", "title"]), context);
+      const src = requiredLiteralAttribute(node, "src", context);
+      const title = requiredLiteralAttribute(node, "title", context);
+      return [
+        {
+          type: "paragraph",
+          children: [
+            {
+              type: "link",
+              url: src,
+              children: [{ type: "text", value: title }],
+            },
+          ],
+        },
+      ];
+    }
+    case "div":
+      validateAttributes(node, new Set(["className"]), context);
+      return transformBlockChildren(node.children, context);
+    case "br":
+    case "code":
+      return [
+        {
+          type: "paragraph",
+          children: transformPhrasingNode(
+            { ...node, type: "mdxJsxTextElement" },
+            context,
+          ),
+        },
+      ];
+    case "Cards.Card":
+      return unsupported(
+        node,
+        context,
+        "<Cards.Card> must be a direct child of <Cards>",
+      );
+    case "Tabs.Tab":
+      return unsupported(
+        node,
+        context,
+        "<Tabs.Tab> must be a direct child of <Tabs>",
+      );
+    default:
+      return unsupported(node, context, "Unsupported flow JSX element");
+  }
+}
+
+function transformBlockChildren(
+  children: AstNode[] | undefined,
+  context: TransformContext,
+): AstNode[] {
+  return (children ?? []).flatMap((child) =>
+    transformBlockNode(child, context),
+  );
+}
+
+function transformBlockNode(
+  node: AstNode,
+  context: TransformContext,
+): AstNode[] {
+  switch (node.type) {
+    case "mdxjsEsm": {
+      const program = node.data?.estree;
+      const body =
+        program?.type === "Program" && Array.isArray(program.body)
+          ? program.body
+          : null;
+      if (
+        !body ||
+        body.some(
+          (statement) =>
+            typeof statement !== "object" ||
+            statement === null ||
+            (statement as AstNode).type !== "ImportDeclaration",
+        )
+      ) {
+        unsupported(
+          node,
+          context,
+          "Only import declarations can be removed from raw Markdown",
+        );
+      }
+      return [];
+    }
+    case "mdxFlowExpression":
+    case "mdxTextExpression":
+      return unsupported(
+        node,
+        context,
+        "Standalone MDX expressions are not supported",
+      );
+    case "mdxJsxFlowElement":
+      return transformFlowJsx(node, context);
+    case "mdxJsxTextElement":
+      return [
+        {
+          type: "paragraph",
+          children: transformPhrasingNode(node, context),
+        },
+      ];
+    case "paragraph":
+      return [
+        {
+          type: "paragraph",
+          children: transformPhrasingChildren(node.children, context),
+        },
+      ];
+    case "heading":
+      if (typeof node.depth !== "number" || node.depth < 1 || node.depth > 6) {
+        unsupported(node, context, "Heading depth must be between 1 and 6");
+      }
+      return [
+        {
+          type: "heading",
+          depth: node.depth,
+          children: transformPhrasingChildren(node.children, context),
+        },
+      ];
+    case "blockquote":
+      return [
+        {
+          type: "blockquote",
+          children: transformBlockChildren(node.children, context),
+        },
+      ];
+    case "list":
+      return [
+        {
+          ...cloneScalarFields(node, ["ordered", "start", "spread"]),
+          children: (node.children ?? []).flatMap((child) => {
+            if (child.type !== "listItem") {
+              unsupported(child, context, "A list can contain only list items");
+            }
+            return transformBlockNode(child, context);
+          }),
+        } as AstNode,
+      ];
+    case "listItem":
+      return [
+        {
+          ...cloneScalarFields(node, ["checked", "spread"]),
+          children: transformBlockChildren(node.children, context),
+        } as AstNode,
+      ];
+    case "code":
+      return transformCode(node, context);
+    case "thematicBreak":
+      return [{ type: "thematicBreak" }];
+    case "definition":
+      return [
+        cloneScalarFields(node, [
+          "identifier",
+          "label",
+          "title",
+          "url",
+        ]) as AstNode,
+      ];
+    case "footnoteDefinition":
+      return [
+        {
+          ...cloneScalarFields(node, ["identifier", "label"]),
+          children: transformBlockChildren(node.children, context),
+        } as AstNode,
+      ];
+    case "table":
+      return [
+        {
+          ...cloneScalarFields(node, ["align"]),
+          children: (node.children ?? []).flatMap((child) =>
+            transformBlockNode(child, context),
+          ),
+        } as AstNode,
+      ];
+    case "tableRow":
+      return [
+        {
+          type: "tableRow",
+          children: (node.children ?? []).flatMap((child) =>
+            transformBlockNode(child, context),
+          ),
+        },
+      ];
+    case "tableCell":
+      return [
+        {
+          type: "tableCell",
+          children: transformPhrasingChildren(node.children, context),
+        },
+      ];
+    case "html":
+      return unsupported(
+        node,
+        context,
+        "Raw HTML is not supported in projected Markdown",
+      );
+    default:
+      if (STANDARD_PHRASE_NODES.has(node.type)) {
+        return [
+          {
+            type: "paragraph",
+            children: transformPhrasingNode(node, context),
+          },
+        ];
+      }
+      return unsupported(node, context, "Unsupported Markdown block node");
+  }
+}
+
+function normalizeDescription(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function projectMdxToMarkdown(
+  source: string,
+  sourcePath = "<source>",
+): string {
+  const parsed = matter(source);
+  const title =
+    typeof parsed.data.title === "string" ? parsed.data.title.trim() : "";
+  const description =
+    typeof parsed.data.description === "string"
+      ? normalizeDescription(parsed.data.description)
+      : "";
+  if (!title || !description) {
+    const missing = [
+      !title ? "title" : null,
+      !description ? "description" : null,
+    ]
+      .filter(Boolean)
+      .join(" and ");
+    throw new Error(
+      `${sourcePath}: raw Markdown projection requires non-empty ${missing} frontmatter`,
+    );
+  }
+
+  const bodyStart = source.indexOf(parsed.content);
+  const lineOffset =
+    bodyStart < 0 ? 0 : source.slice(0, bodyStart).split(/\r?\n/).length - 1;
+  const context: TransformContext = { lineOffset, sourcePath };
+  let parsedTree: AstNode;
+  try {
+    parsedTree = unified()
+      .use(remarkParse)
+      .use(remarkGfm)
+      .use(remarkMdx)
+      .parse(parsed.content) as AstNode;
+  } catch (error) {
+    throw new Error(
+      `${sourcePath}: cannot parse MDX for raw Markdown: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  const body = transformBlockChildren(parsedTree.children, context);
+  const tree: AstNode = {
+    type: "root",
+    children: [
+      {
+        type: "heading",
+        depth: 1,
+        children: [{ type: "text", value: title }],
+      },
+      {
+        type: "paragraph",
+        children: [{ type: "text", value: description }],
+      },
+      ...body,
+    ],
+  };
+  const markdown = unified()
+    .use(remarkGfm)
+    .use(remarkStringify, {
+      bullet: "-",
+      fences: true,
+      listItemIndent: "one",
+      rule: "-",
+    })
+    .stringify(tree as never)
+    .trim();
+  return `${GENERATED_RAW_MARKDOWN_SENTINEL}\n\n${markdown}\n`;
+}
+
+export async function collectRawMarkdownPages(
+  rootDir = process.cwd(),
+): Promise<{
+  pages: RawMarkdownPage[];
+}> {
+  const resolvedRoot = path.resolve(rootDir);
+  const docsRoot = path.join(resolvedRoot, "src/pages/docs");
+  const sourceRelativePaths = (
+    await fg("**/*.mdx", {
+      cwd: docsRoot,
+      onlyFiles: true,
+    })
+  )
+    .map((item) => item.replace(/\\/g, "/"))
+    .sort();
+  if (sourceRelativePaths.length === 0) {
+    throw new Error(`${docsRoot} does not contain any .mdx pages`);
+  }
+
+  validateDocumentationSourcePaths(sourceRelativePaths);
+  const routes = sourceRelativePaths.map(rawMarkdownRouteForSource);
+  validateRawRouteCollisions(routes);
+  validateExportedFileBijection(routes);
+  const pages = await Promise.all(
+    routes.map(async (route): Promise<RawMarkdownPage> => {
+      const sourcePath = path.join(docsRoot, route.sourceRelativePath);
+      const source = await fs.promises.readFile(sourcePath, "utf8");
+      return {
+        ...route,
+        markdown: projectMdxToMarkdown(
+          source,
+          path.relative(resolvedRoot, sourcePath).replace(/\\/g, "/"),
+        ),
+        sourcePath,
+      };
+    }),
+  );
+  return { pages };
+}
+
+function isMissingFile(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+async function readIfPresent(file: string): Promise<string | null> {
+  try {
+    return await fs.promises.readFile(file, "utf8");
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
+  }
+}
+
+function generatedFile(contents: string): boolean {
+  return contents.startsWith(`${GENERATED_RAW_MARKDOWN_SENTINEL}\n`);
+}
+
+function reservedRawMarkdownPath(relative: string): boolean {
+  const normalized = relative.replace(/\\/g, "/");
+  return normalized === "docs.md" || normalized.startsWith("docs/");
+}
+
+function outputPath(publicRoot: string, relative: string): string {
+  const resolvedPublicRoot = path.resolve(publicRoot);
+  const resolved = path.resolve(resolvedPublicRoot, relative);
+  if (!resolved.startsWith(`${resolvedPublicRoot}${path.sep}`)) {
+    throw new Error(`Raw Markdown output escapes public/: ${relative}`);
+  }
+  return resolved;
+}
+
+async function removeEmptyParents(
+  directory: string,
+  publicRoot: string,
+): Promise<void> {
+  let current = path.resolve(directory);
+  const stop = path.resolve(publicRoot);
+  while (current !== stop && current.startsWith(`${stop}${path.sep}`)) {
+    try {
+      await fs.promises.rmdir(current);
+    } catch (error) {
+      if (
+        isMissingFile(error) ||
+        (typeof error === "object" &&
+          error !== null &&
+          "code" in error &&
+          ["ENOTEMPTY", "EEXIST"].includes(String(error.code)))
+      ) {
+        return;
+      }
+      throw error;
+    }
+    current = path.dirname(current);
+  }
+}
+
+export async function generateRawMarkdown({
+  check = false,
+  rootDir = process.cwd(),
+}: RawMarkdownGenerationOptions = {}): Promise<RawMarkdownGenerationResult> {
+  const resolvedRoot = path.resolve(rootDir);
+  const publicRoot = path.join(resolvedRoot, "public");
+  const { pages } = await collectRawMarkdownPages(resolvedRoot);
+  const expected = new Map<string, RawMarkdownPage>();
+  const existing = new Map<string, string | null>();
+
+  for (const page of pages) {
+    const target = outputPath(publicRoot, page.outputRelativePath);
+    expected.set(target, page);
+    const contents = await readIfPresent(target);
+    if (contents !== null && !generatedFile(contents)) {
+      throw new Error(
+        `Refusing to overwrite non-generated raw Markdown file: ${path.relative(
+          resolvedRoot,
+          target,
+        )}`,
+      );
+    }
+    existing.set(target, contents);
+  }
+
+  const publicMarkdownFiles = await fg("**/*.md", {
+    cwd: publicRoot,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+  });
+  const outdated = [...expected].filter(
+    ([target, page]) =>
+      existing.get(target) !== null && existing.get(target) !== page.markdown,
+  );
+  const stale: string[] = [];
+  for (const relative of publicMarkdownFiles.sort()) {
+    const target = outputPath(publicRoot, relative);
+    if (expected.has(target)) continue;
+    const contents = await fs.promises.readFile(target, "utf8");
+    if (generatedFile(contents)) {
+      stale.push(target);
+    } else if (reservedRawMarkdownPath(relative)) {
+      throw new Error(
+        `Refusing unmanaged file in the reserved raw Markdown namespace: ${path.relative(
+          resolvedRoot,
+          target,
+        )}`,
+      );
+    }
+  }
+
+  if (check) {
+    return {
+      outdatedCount: outdated.length,
+      projectedCount: pages.length,
+      removedCount: 0,
+      staleCount: stale.length,
+      writtenCount: 0,
+    };
+  }
+
+  let writtenCount = 0;
+  for (const [target, page] of expected) {
+    if (existing.get(target) === page.markdown) continue;
+    await fs.promises.mkdir(path.dirname(target), { recursive: true });
+    await fs.promises.writeFile(target, page.markdown);
+    writtenCount += 1;
+  }
+
+  for (const target of stale) {
+    const contents = await fs.promises.readFile(target, "utf8");
+    if (!generatedFile(contents)) {
+      throw new Error(
+        `Refusing to delete raw Markdown file after its generated sentinel changed: ${path.relative(
+          resolvedRoot,
+          target,
+        )}`,
+      );
+    }
+    await fs.promises.unlink(target);
+    await removeEmptyParents(path.dirname(target), publicRoot);
+  }
+
+  return {
+    outdatedCount: outdated.length,
+    projectedCount: pages.length,
+    removedCount: stale.length,
+    staleCount: stale.length,
+    writtenCount,
+  };
+}
+
+export async function runRawMarkdownCli(
+  args = process.argv.slice(2),
+  rootDir = process.cwd(),
+): Promise<RawMarkdownGenerationResult> {
+  const unexpected = args.filter((arg) => arg !== "--check");
+  if (unexpected.length > 0) {
+    throw new Error(
+      `Unknown raw Markdown generator argument(s): ${unexpected.join(", ")}`,
+    );
+  }
+  const check = args.includes("--check");
+  const result = await generateRawMarkdown({ check, rootDir });
+  if (check) {
+    const issues = [
+      result.outdatedCount > 0
+        ? `${result.outdatedCount} outdated generated raw Markdown file(s) differ from their MDX source`
+        : null,
+      result.staleCount > 0
+        ? `${result.staleCount} stale generated raw Markdown file(s) remain`
+        : null,
+    ].filter((issue): issue is string => issue !== null);
+    if (issues.length > 0) {
+      throw new Error(`${issues.join("; ")}. Run \`bun run build:raw\`.`);
+    }
+    console.log(
+      `Projected ${result.projectedCount} raw Markdown routes; generated files are not required in --check mode.`,
+    );
+  } else {
+    console.log(
+      `Generated ${result.projectedCount} raw Markdown routes; wrote ${result.writtenCount} and removed ${result.removedCount} stale file(s).`,
+    );
+  }
+  return result;
+}
+
+if (import.meta.main) {
+  try {
+    await runRawMarkdownCli();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
diff --git a/scripts/generateTagPages.ts b/scripts/generateTagPages.ts
deleted file mode 100755
index db41380f..00000000
--- a/scripts/generateTagPages.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-/**
- * Copyright 2025 GoodRx, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-// scripts/generate-tag-pages.js
-import { writeFile, readFile, readdir, mkdir, stat } from "node:fs/promises";
-import { join } from "node:path";
-import matter from "gray-matter";
-
-import { Command } from "commander";
-
-const program = new Command();
-
-async function processDirectory(directory, tags, data) {
-  const fileNames = await readdir(directory);
-
-  for (const fileName of fileNames) {
-    const filePath = join(directory, fileName);
-    const foundState = await stat(filePath);
-
-    if (foundState.isDirectory()) {
-      await processDirectory(filePath, tags, data);
-    } else if (foundState.isFile() && fileName.endsWith(".mdx")) {
-      const specificDir = "pages";
-      const startIndex = filePath.indexOf(specificDir) + specificDir.length;
-      const updatedPath = filePath.substring(startIndex);
-      const fileContents = await readFile(filePath, "utf8");
-      const matterResult = matter(fileContents);
-      matterResult.data.tags?.forEach((tag) => tags.add(tag));
-
-      const lowerCaseTags =
-        matterResult.data.tags?.map((tag) => tag.toLowerCase()) || [];
-
-      data.push({
-        name: fileName.replace(".mdx", ""),
-        title: matterResult.data.title,
-        description: matterResult.data.description,
-        tags: lowerCaseTags,
-        path: updatedPath.replace(".mdx", ""),
-      });
-    }
-  }
-}
-
-export async function generateTagPages({
-  dir = "src/pages",
-  out = "src/pages/tag",
-  template = "scripts/tagtemplatepage.mdx",
-  dataDir = "src/lib/data",
-  isDebugging = false,
-} = {}) {
-  const contentDirectory = join(process.cwd(), dir);
-  const outputDirectory = join(process.cwd(), out);
-  const templatePath = join(process.cwd(), template);
-  const dataDirectory = join(process.cwd(), dataDir);
-  const templateContent = await readFile(templatePath, "utf8");
-  const fileNames = await readdir(contentDirectory);
-
-  if (isDebugging) console.log({ fileNames });
-  const tags = new Set();
-  const data = [] as unknown as {
-    name: string;
-    title: string;
-    description: string;
-    tags: string[];
-  }[];
-
-  await processDirectory(contentDirectory, tags, data);
-
-  if (isDebugging) console.log({ tags, data });
-
-  for (const tag of tags) {
-    const lowerCaseTag = (tag as string).toLowerCase();
-    const tagPageContent = templateContent.replace(
-      /\[tag\]/g,
-      lowerCaseTag as string,
-    );
-    await mkdir(outputDirectory, { recursive: true });
-    const tagPagePath = join(outputDirectory, `${lowerCaseTag}.mdx`);
-    await writeFile(tagPagePath, tagPageContent, "utf8");
-
-    const tagDataDir = join(dataDirectory, lowerCaseTag as string);
-    await mkdir(tagDataDir, { recursive: true });
-
-    const tagDataPath = join(tagDataDir, "tag.data.ts");
-    const tagData = data.filter((item) =>
-      item.tags?.includes(lowerCaseTag as string),
-    );
-    const dataContent = `export default ${JSON.stringify(tagData, null, 2)};`;
-    await writeFile(tagDataPath, dataContent, "utf8");
-    if (isDebugging)
-      console.log(
-        `wrote "${lowerCaseTag}.mdx" and "/src/lib/data/${lowerCaseTag}" with:`,
-        {
-          tagData,
-        },
-      );
-  }
-}
-
-program
-  .option("-d, --dir <directory>", "directory of pages", "./src/pages")
-  .option("-o, --out <directory>", "output directory", "./src/pages/tags")
-  .option(
-    "-t, --template <path>",
-    "path to template file",
-    "scripts/tagtemplatepage.mdx",
-  )
-  .option(
-    "--dataDir <directory>",
-    "output directory for data files",
-    "./src/lib/data",
-  )
-  .option("--debug", "enable debug logs", false);
-
-program.parse(process.argv);
-
-const { dir, out, debug, template, dataDir } = program.opts();
-
-(async () => {
-  await generateTagPages({
-    dir: dir,
-    out: out,
-    template: template,
-    isDebugging: debug,
-    dataDir: dataDir,
-  });
-  console.log("Meta files generated successfully!");
-})();
diff --git a/scripts/navigationMetadata.ts b/scripts/navigationMetadata.ts
new file mode 100644
index 00000000..82c768b9
--- /dev/null
+++ b/scripts/navigationMetadata.ts
@@ -0,0 +1,135 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from "node:fs";
+import ts from "typescript";
+
+export type NavigationSource = {
+  navigation: Record<string, unknown>;
+  source: string;
+};
+
+function propertyName(
+  name: ts.PropertyName,
+  sourceFile: ts.SourceFile,
+): string {
+  if (
+    ts.isIdentifier(name) ||
+    ts.isStringLiteral(name) ||
+    ts.isNumericLiteral(name)
+  ) {
+    return name.text;
+  }
+  throw new Error(
+    `${sourceFile.fileName}:${sourceFile.getLineAndCharacterOfPosition(name.getStart()).line + 1} navigation keys must be static strings`,
+  );
+}
+
+function literalValue(
+  expression: ts.Expression,
+  sourceFile: ts.SourceFile,
+): unknown {
+  if (
+    ts.isAsExpression(expression) ||
+    ts.isSatisfiesExpression(expression) ||
+    ts.isParenthesizedExpression(expression)
+  ) {
+    return literalValue(expression.expression, sourceFile);
+  }
+  if (
+    ts.isStringLiteral(expression) ||
+    ts.isNoSubstitutionTemplateLiteral(expression)
+  ) {
+    return expression.text;
+  }
+  if (ts.isNumericLiteral(expression)) return Number(expression.text);
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (expression.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (
+    ts.isPrefixUnaryExpression(expression) &&
+    expression.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(expression.operand)
+  ) {
+    return -Number(expression.operand.text);
+  }
+  if (ts.isArrayLiteralExpression(expression)) {
+    return expression.elements.map((element) =>
+      literalValue(element, sourceFile),
+    );
+  }
+  if (ts.isObjectLiteralExpression(expression)) {
+    const value: Record<string, unknown> = {};
+    for (const property of expression.properties) {
+      if (!ts.isPropertyAssignment(property)) {
+        throw new Error(
+          `${sourceFile.fileName}:${sourceFile.getLineAndCharacterOfPosition(property.getStart()).line + 1} navigation metadata must use static property assignments`,
+        );
+      }
+      value[propertyName(property.name, sourceFile)] = literalValue(
+        property.initializer,
+        sourceFile,
+      );
+    }
+    return value;
+  }
+  throw new Error(
+    `${sourceFile.fileName}:${sourceFile.getLineAndCharacterOfPosition(expression.getStart()).line + 1} navigation metadata must use literal values`,
+  );
+}
+
+export async function readNavigationMetadata(
+  file: string,
+): Promise<NavigationSource> {
+  const source = await fs.promises.readFile(file, "utf8");
+  const sourceFile = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const parseError = sourceFile.parseDiagnostics.find(
+    (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+  );
+  if (parseError) {
+    const position = sourceFile.getLineAndCharacterOfPosition(
+      parseError.start ?? 0,
+    );
+    throw new Error(
+      `${file}:${position.line + 1} ${ts.flattenDiagnosticMessageText(parseError.messageText, " ")}`,
+    );
+  }
+  const assignment = sourceFile.statements.find(
+    (statement): statement is ts.ExportAssignment =>
+      ts.isExportAssignment(statement) && !statement.isExportEquals,
+  );
+  if (!assignment) {
+    throw new Error(`${file} must default-export a navigation object`);
+  }
+  const navigation = literalValue(assignment.expression, sourceFile);
+  if (
+    typeof navigation !== "object" ||
+    navigation === null ||
+    Array.isArray(navigation)
+  ) {
+    throw new Error(`${file} must default-export a navigation object`);
+  }
+  return {
+    navigation: navigation as Record<string, unknown>,
+    source,
+  };
+}
diff --git a/scripts/tagtemplatepage.mdx b/scripts/tagtemplatepage.mdx
deleted file mode 100644
index f64bb5d6..00000000
--- a/scripts/tagtemplatepage.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
----
-title: [tag]
-description: 'Lifecycle "[tag]" docs'
----
-
-import { LifecycleDocsCards as Cards } from "@lifecycle-docs/components";
-import meta from "@/lib/data/[tag]/tag.data";
-
-<Cards meta={meta} name="[tag]" />
diff --git a/scripts/validateContracts.ts b/scripts/validateContracts.ts
new file mode 100644
index 00000000..2e0eb500
--- /dev/null
+++ b/scripts/validateContracts.ts
@@ -0,0 +1,604 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import fg from "fast-glob";
+
+export type ContractIssue = {
+  file: string;
+  message: string;
+};
+
+export type ContractCheck = {
+  detail: string;
+  name: "schema" | "openapi" | "cli";
+  status: "fail" | "pass" | "skip";
+};
+
+export type ContractInputs = {
+  cliCommand?: string[];
+  openApiSpecPath?: string;
+  schemaValidatorCommand?: string[];
+};
+
+export type ContractValidationOptions = {
+  inputs?: ContractInputs;
+  requireAll?: boolean;
+  rootDir?: string;
+};
+
+export type ContractValidationResult = {
+  checks: ContractCheck[];
+  issues: ContractIssue[];
+};
+
+type SourceFile = {
+  file: string;
+  source: string;
+};
+
+type CommandResult = {
+  code: number;
+  output: string;
+};
+
+type CliInvocation = {
+  file: string;
+  line: number;
+  source: string;
+  tokens: string[];
+};
+
+const INPUT_NAMES = {
+  schemaValidatorCommand: "DOCS_SCHEMA_VALIDATOR_COMMAND",
+  openApiSpecPath: "DOCS_OPENAPI_SPEC_PATH",
+  cliCommand: "DOCS_CLI_COMMAND",
+} as const;
+
+const HTTP_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+];
+const GLOBAL_OPTIONS_WITH_VALUES = new Set([
+  "--api-url",
+  "--profile",
+  "--config-dir",
+]);
+
+function lineAt(source: string, index: number): number {
+  return source.slice(0, index).split("\n").length;
+}
+
+function parseArgv(
+  name: string,
+  value: string | undefined,
+): string[] | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error(`${name} must be a JSON argv array`);
+  }
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length === 0 ||
+    parsed.some((item) => typeof item !== "string" || item.trim() === "")
+  ) {
+    throw new Error(`${name} must be a non-empty JSON array of strings`);
+  }
+  return parsed as string[];
+}
+
+export function contractInputsFromEnvironment(
+  env: Record<string, string | undefined> = process.env,
+): ContractInputs {
+  return {
+    schemaValidatorCommand: parseArgv(
+      INPUT_NAMES.schemaValidatorCommand,
+      env[INPUT_NAMES.schemaValidatorCommand],
+    ),
+    openApiSpecPath: env[INPUT_NAMES.openApiSpecPath]?.trim() || undefined,
+    cliCommand: parseArgv(INPUT_NAMES.cliCommand, env[INPUT_NAMES.cliCommand]),
+  };
+}
+
+async function runCommand(
+  argv: string[],
+  extra: string[] = [],
+): Promise<CommandResult> {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(argv[0], [...argv.slice(1), ...extra], {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const chunks: Buffer[] = [];
+    child.stdout.on("data", (chunk: Buffer) => chunks.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => chunks.push(chunk));
+    child.once("error", reject);
+    child.once("close", (code) => {
+      resolve({
+        code: code ?? 1,
+        output: Buffer.concat(chunks).toString("utf8").trim(),
+      });
+    });
+  });
+}
+
+async function readSources(rootDir: string): Promise<SourceFile[]> {
+  const files = (
+    await fg("src/pages/docs/**/*.mdx", {
+      absolute: true,
+      cwd: rootDir,
+    })
+  ).sort();
+  return await Promise.all(
+    files.map(async (file) => ({
+      file,
+      source: await fs.promises.readFile(file, "utf8"),
+    })),
+  );
+}
+
+async function validateSchemaExamples(
+  rootDir: string,
+  sources: SourceFile[],
+  command: string[],
+): Promise<{ count: number; issues: ContractIssue[] }> {
+  const examples: Array<{
+    content: string;
+    file: string;
+    line: number;
+  }> = [];
+  for (const { file, source } of sources) {
+    for (const match of source.matchAll(/```ya?ml([^\n]*)\n([\s\S]*?)```/g)) {
+      if (!/\bfilename=["']lifecycle\.ya?ml["']/.test(match[1])) continue;
+      examples.push({
+        content: match[2],
+        file,
+        line: lineAt(source, match.index ?? 0),
+      });
+    }
+  }
+
+  const temporaryRoot = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "lifecycle-docs-contracts-"),
+  );
+  const issues: ContractIssue[] = [];
+  try {
+    for (const [index, example] of examples.entries()) {
+      const temporaryFile = path.join(temporaryRoot, `example-${index}.yaml`);
+      await fs.promises.writeFile(temporaryFile, example.content);
+      const result = await runCommand(command, [temporaryFile]);
+      if (result.code !== 0) {
+        issues.push({
+          file: `${path.relative(rootDir, example.file)}:${example.line}`,
+          message: `canonical lifecycle.yaml validation failed${
+            result.output ? `: ${result.output.replace(/\s+/g, " ")}` : ""
+          }`,
+        });
+      }
+    }
+  } finally {
+    await fs.promises.rm(temporaryRoot, { force: true, recursive: true });
+  }
+  return { count: examples.length, issues };
+}
+
+function normalizeApiPath(value: string): string {
+  return value
+    .replace(/[`'",.;:)\]]+$/g, "")
+    .split(/[?#]/, 1)[0]
+    .replace(/<[^>]+>|\{[^}]+\}/g, "{}")
+    .replace(/\/$/, "");
+}
+
+function collectApiClaims(
+  rootDir: string,
+  sources: SourceFile[],
+): Array<{
+  file: string;
+  line: number;
+  method: string;
+  normalized: string;
+  path: string;
+}> {
+  const claims: Array<{
+    file: string;
+    line: number;
+    method: string;
+    normalized: string;
+    path: string;
+  }> = [];
+  for (const { file, source } of sources) {
+    for (const [index, line] of source.split(/\r?\n/).entries()) {
+      for (const pathMatch of line.matchAll(/\/api\/v2(?:\/[^\s`"')|,]+)+/g)) {
+        const prefix = line.slice(0, pathMatch.index);
+        const methods = HTTP_METHODS.filter((method) =>
+          new RegExp(`\\b${method}\\b`).test(prefix),
+        );
+        for (const method of methods) {
+          claims.push({
+            file: path.relative(rootDir, file),
+            line: index + 1,
+            method,
+            normalized: normalizeApiPath(pathMatch[0]),
+            path: pathMatch[0],
+          });
+        }
+      }
+    }
+  }
+  return claims;
+}
+
+async function validateOpenApiClaims(
+  rootDir: string,
+  sources: SourceFile[],
+  specPath: string,
+): Promise<{ count: number; issues: ContractIssue[] }> {
+  const resolvedPath = path.resolve(rootDir, specPath);
+  const spec: unknown = JSON.parse(
+    await fs.promises.readFile(resolvedPath, "utf8"),
+  );
+  if (
+    typeof spec !== "object" ||
+    spec === null ||
+    !("paths" in spec) ||
+    typeof spec.paths !== "object" ||
+    spec.paths === null
+  ) {
+    throw new Error(`${specPath} does not contain an OpenAPI paths object`);
+  }
+
+  const operations = new Map<string, Set<string>>();
+  for (const [apiPath, pathItem] of Object.entries(
+    spec.paths as Record<string, unknown>,
+  )) {
+    if (typeof pathItem !== "object" || pathItem === null) continue;
+    operations.set(
+      normalizeApiPath(apiPath),
+      new Set(Object.keys(pathItem).map((method) => method.toUpperCase())),
+    );
+  }
+
+  const claims = collectApiClaims(rootDir, sources);
+  const issues: ContractIssue[] = [];
+  for (const claim of claims) {
+    if (!operations.get(claim.normalized)?.has(claim.method)) {
+      issues.push({
+        file: `${claim.file}:${claim.line}`,
+        message: `${claim.method} ${claim.path} is not present in the supplied OpenAPI contract`,
+      });
+    }
+  }
+  return { count: claims.length, issues };
+}
+
+function shellTokens(command: string): string[] {
+  const tokens: string[] = [];
+  for (const match of command.matchAll(/"([^"]*)"|'([^']*)'|([^\s]+)/g)) {
+    tokens.push(match[1] ?? match[2] ?? match[3]);
+  }
+  return tokens;
+}
+
+function collectCliInvocations(
+  rootDir: string,
+  sources: SourceFile[],
+): CliInvocation[] {
+  const invocations: CliInvocation[] = [];
+  for (const { file, source } of sources) {
+    for (const fence of source.matchAll(
+      /```(?:sh|bash|shell)[^\n]*\n([\s\S]*?)```/g,
+    )) {
+      const content = fence[1].replace(/\\\r?\n[ \t]*/g, " ");
+      const fenceLine = lineAt(source, fence.index ?? 0);
+      for (const [offset, line] of content.split(/\r?\n/).entries()) {
+        const lfcIndex = line.search(/\blfc(?:\s|$)/);
+        if (lfcIndex < 0) continue;
+        const invocation = line
+          .slice(lfcIndex)
+          .replace(/\s+#.*$/, "")
+          .trim();
+        invocations.push({
+          file: path.relative(rootDir, file),
+          line: fenceLine + offset + 1,
+          source: invocation,
+          tokens: shellTokens(invocation),
+        });
+      }
+    }
+  }
+  return invocations;
+}
+
+function helpCommands(output: string): Set<string> {
+  const commands = new Set<string>();
+  const lines = output.split(/\r?\n/);
+  let inCommands = false;
+  for (const line of lines) {
+    if (/^\s*Commands:\s*$/.test(line)) {
+      inCommands = true;
+      continue;
+    }
+    if (!inCommands) continue;
+    if (/^\S/.test(line) || /^\s*(?:Options|Arguments):\s*$/.test(line)) break;
+    const command = line.match(/^\s{2,}([a-z][a-z0-9-]*)\b/)?.[1];
+    if (command) commands.add(command);
+  }
+  return commands;
+}
+
+function optionName(token: string): string | null {
+  const cleaned = token.replace(/^[[(]+|[\]),;]+$/g, "").split("=", 1)[0];
+  return /^--?[a-z][a-z0-9-]*$/i.test(cleaned) ? cleaned : null;
+}
+
+async function validateCliInvocations(
+  rootDir: string,
+  sources: SourceFile[],
+  command: string[],
+): Promise<{ count: number; issues: ContractIssue[] }> {
+  const invocations = collectCliInvocations(rootDir, sources);
+  const issues: ContractIssue[] = [];
+  const helpCache = new Map<string, CommandResult>();
+  async function help(commandPath: string[]): Promise<CommandResult> {
+    const key = commandPath.join(" ");
+    const cached = helpCache.get(key);
+    if (cached) return cached;
+    const result = await runCommand(command, [...commandPath, "--help"]);
+    helpCache.set(key, result);
+    return result;
+  }
+
+  const rootHelp = await help([]);
+  if (rootHelp.code !== 0) {
+    throw new Error(
+      `CLI root --help failed${rootHelp.output ? `: ${rootHelp.output}` : ""}`,
+    );
+  }
+  const rootCommands = helpCommands(rootHelp.output);
+
+  for (const invocation of invocations) {
+    const raw = invocation.tokens.slice(1);
+    const helpOutputs = [rootHelp.output];
+    const commandSetsByToken = new Map<number, Set<string>>();
+    let topIndex = -1;
+    for (let index = 0; index < raw.length; index += 1) {
+      const token = raw[index];
+      if (GLOBAL_OPTIONS_WITH_VALUES.has(token)) {
+        index += 1;
+        continue;
+      }
+      if (token.startsWith("-")) continue;
+      if (rootCommands.has(token)) {
+        topIndex = index;
+        break;
+      }
+    }
+
+    const commandPath: string[] = [];
+    if (topIndex < 0) {
+      const hasUnexpectedPositional = raw.some((token, index) => {
+        if (index > 0 && GLOBAL_OPTIONS_WITH_VALUES.has(raw[index - 1])) {
+          return false;
+        }
+        return token !== "|" && !token.startsWith("-") && !/^[[(<]/.test(token);
+      });
+      if (hasUnexpectedPositional) {
+        issues.push({
+          file: `${invocation.file}:${invocation.line}`,
+          message: `cannot resolve a documented CLI command from: ${invocation.source}`,
+        });
+      }
+    } else {
+      commandPath.push(raw[topIndex]);
+      commandSetsByToken.set(topIndex, rootCommands);
+      let commandTokenIndex = topIndex;
+
+      while (commandPath.length > 0) {
+        const commandHelp = await help(commandPath);
+        if (commandHelp.code !== 0) {
+          issues.push({
+            file: `${invocation.file}:${invocation.line}`,
+            message: `CLI command is unavailable: lfc ${commandPath.join(" ")}`,
+          });
+          break;
+        }
+        helpOutputs.push(commandHelp.output);
+
+        const subcommands = helpCommands(commandHelp.output);
+        if (subcommands.size === 0) break;
+
+        const nextIndex = commandTokenIndex + 1;
+        const nextToken = raw[nextIndex];
+        if (!nextToken) break;
+        const nextCommand = nextToken.replace(/^[[(]+|[\]),;]+$/g, "");
+        if (subcommands.has(nextCommand)) {
+          commandPath.push(nextCommand);
+          commandSetsByToken.set(nextIndex, subcommands);
+          commandTokenIndex = nextIndex;
+          continue;
+        }
+
+        if (
+          nextToken === "|" ||
+          nextToken.startsWith("-") ||
+          /^[[(<]/.test(nextToken)
+        ) {
+          break;
+        }
+        issues.push({
+          file: `${invocation.file}:${invocation.line}`,
+          message: `CLI subcommand is unavailable: lfc ${[
+            ...commandPath,
+            nextCommand,
+          ].join(" ")}`,
+        });
+        break;
+      }
+    }
+
+    const availableHelp = helpOutputs.join("\n");
+    for (const token of raw) {
+      const option = optionName(token);
+      if (
+        option &&
+        option !== "--help" &&
+        !new RegExp(
+          `(^|[\\s,])${option.replace(/-/g, "\\-")}(?=[\\s,=<\\[])`,
+          "m",
+        ).test(availableHelp)
+      ) {
+        issues.push({
+          file: `${invocation.file}:${invocation.line}`,
+          message: `${option} is not present in help for ${
+            commandPath.length > 0 ? `lfc ${commandPath.join(" ")}` : "lfc"
+          }`,
+        });
+      }
+    }
+
+    for (let index = 1; index < raw.length - 1; index += 1) {
+      if (raw[index] !== "|") continue;
+      const siblingCommands = commandSetsByToken.get(index - 1);
+      if (!siblingCommands) continue;
+      const alternative = raw[index + 1]?.replace(/^[[(]+|[\]),;]+$/g, "");
+      if (alternative && !siblingCommands.has(alternative)) {
+        issues.push({
+          file: `${invocation.file}:${invocation.line}`,
+          message: `CLI subcommand alternative is unavailable: ${alternative}`,
+        });
+      }
+    }
+  }
+  return { count: invocations.length, issues };
+}
+
+export async function validateContracts({
+  rootDir = process.cwd(),
+  inputs = contractInputsFromEnvironment(),
+  requireAll = false,
+}: ContractValidationOptions = {}): Promise<ContractValidationResult> {
+  const resolvedRoot = path.resolve(rootDir);
+  const sources = await readSources(resolvedRoot);
+  const issues: ContractIssue[] = [];
+  const checks: ContractCheck[] = [];
+
+  for (const [key, environmentName] of Object.entries(INPUT_NAMES)) {
+    if (requireAll && !inputs[key as keyof ContractInputs]) {
+      issues.push({
+        file: "contract inputs",
+        message: `${environmentName} is required by --require-all`,
+      });
+    }
+  }
+
+  if (inputs.schemaValidatorCommand) {
+    const result = await validateSchemaExamples(
+      resolvedRoot,
+      sources,
+      inputs.schemaValidatorCommand,
+    );
+    issues.push(...result.issues);
+    checks.push({
+      name: "schema",
+      status: result.issues.length > 0 ? "fail" : "pass",
+      detail: `${result.count} named lifecycle.yaml example(s) checked`,
+    });
+  } else {
+    checks.push({
+      name: "schema",
+      status: "skip",
+      detail: `${INPUT_NAMES.schemaValidatorCommand} not supplied`,
+    });
+  }
+
+  if (inputs.openApiSpecPath) {
+    const result = await validateOpenApiClaims(
+      resolvedRoot,
+      sources,
+      inputs.openApiSpecPath,
+    );
+    issues.push(...result.issues);
+    checks.push({
+      name: "openapi",
+      status: result.issues.length > 0 ? "fail" : "pass",
+      detail: `${result.count} explicit API operation claim(s) checked`,
+    });
+  } else {
+    checks.push({
+      name: "openapi",
+      status: "skip",
+      detail: `${INPUT_NAMES.openApiSpecPath} not supplied`,
+    });
+  }
+
+  if (inputs.cliCommand) {
+    const result = await validateCliInvocations(
+      resolvedRoot,
+      sources,
+      inputs.cliCommand,
+    );
+    issues.push(...result.issues);
+    checks.push({
+      name: "cli",
+      status: result.issues.length > 0 ? "fail" : "pass",
+      detail: `${result.count} CLI invocation(s) checked`,
+    });
+  } else {
+    checks.push({
+      name: "cli",
+      status: "skip",
+      detail: `${INPUT_NAMES.cliCommand} not supplied`,
+    });
+  }
+
+  return { checks, issues };
+}
+
+async function runCli() {
+  let result: ContractValidationResult;
+  try {
+    result = await validateContracts({
+      requireAll: process.argv.includes("--require-all"),
+    });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+
+  for (const check of result.checks) {
+    console.log(`${check.status.toUpperCase()} ${check.name}: ${check.detail}`);
+  }
+  for (const issue of result.issues) {
+    console.error(`${issue.file} — ${issue.message}`);
+  }
+  if (result.issues.length > 0) process.exit(1);
+}
+
+if (import.meta.main) {
+  await runCli();
+}
diff --git a/scripts/validateDocs.ts b/scripts/validateDocs.ts
new file mode 100644
index 00000000..c8ba549e
--- /dev/null
+++ b/scripts/validateDocs.ts
@@ -0,0 +1,1199 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import GithubSlugger from "github-slugger";
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import {
+  DOCUMENTATION_METADATA,
+  loadDocumentationMetadata,
+  resolvePageMetadata,
+  type DocumentationMetadata,
+} from "./docsMetadata";
+
+export type ValidationIssue = {
+  file: string;
+  message: string;
+};
+
+export type ValidationOptions = {
+  rootDir?: string;
+};
+
+type ValidationContext = {
+  publicRoot: string;
+  rootDir: string;
+};
+
+type ScreenshotReference = {
+  asset: string;
+  declaredHeight: number | null;
+  declaredWidth: number | null;
+  file: string;
+  index: number;
+  source: string;
+};
+
+type ScreenshotCatalogEntry = {
+  asset: string;
+  fields: string[];
+  line: number;
+  status: string;
+};
+
+type ImageDimensions = {
+  height: number;
+  width: number;
+};
+
+const SCREENSHOT_CATALOG =
+  ".agents/skills/update-lifecycle-docs/references/screenshots.md";
+const RAW_MARKDOWN_SERVER_CONFIG = "default.conf";
+const RASTER_EXTENSIONS = new Set([".gif", ".jpeg", ".jpg", ".png", ".webp"]);
+const NON_SCREENSHOT_RASTERS = new Set(["/logo.png"]);
+const SCREENSHOT_STATUSES = new Set(["keep", "remove", "replace"]);
+const PORTABLE_GUIDANCE_FILES = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "README.md",
+  ".github/PULL_REQUEST_TEMPLATE.md",
+  ".agents/skills/update-lifecycle-docs/SKILL.md",
+  ".agents/skills/update-lifecycle-docs/references/language-profile.md",
+  ".agents/skills/update-lifecycle-docs/references/raw-markdown.md",
+  ".agents/skills/update-lifecycle-docs/references/screenshots.md",
+  ".agents/skills/update-lifecycle-docs/references/ste100-review.md",
+  ".agents/skills/update-lifecycle-docs/agents/openai.yaml",
+  "package.json",
+];
+const PORTABILITY_PATTERNS = [
+  {
+    pattern: /\/Users\/[^/\s"'`]+/g,
+    message: "tracked guidance contains a contributor-specific macOS path",
+  },
+  {
+    pattern: /\/home\/[^/\s"'`]+/g,
+    message: "tracked guidance contains a contributor-specific home path",
+  },
+  {
+    pattern: /[A-Za-z]:\\Users\\[^\\\s"'`]+/g,
+    message: "tracked guidance contains a contributor-specific Windows path",
+  },
+  {
+    pattern:
+      /https?:\/\/(?:localhost|127(?:\.\d{1,3}){3})(?::\d{2,5})?(?:[/?#][^\s"'`]*)?/gi,
+    message: "tracked guidance contains a fixed local development URL",
+  },
+  {
+    pattern: /\b[^\s"'`]*\.nip\.io\b/gi,
+    message: "tracked guidance contains a local-only nip.io hostname",
+  },
+  {
+    pattern: /(?<!\S)(?:-p|--port)\s+\d{2,5}\b/g,
+    message: "tracked guidance or scripts contain a fixed development port",
+  },
+  {
+    pattern: /\blabs\s*=\s*true\b/gi,
+    message: "tracked guidance contains a local Labs bypass",
+  },
+  {
+    pattern: /\borigin\/main\b/g,
+    message: "tracked guidance assumes the fixture default branch",
+  },
+  {
+    pattern:
+      /\b(?:standard local workspace|standard personal workspace|personal workspace)\b/gi,
+    message: "tracked guidance assumes one contributor's workspace",
+  },
+];
+const DOCUMENTATION_AUDIT_PATTERNS = [
+  {
+    pattern: /\b(?:current UI|reviewed(?: UI)?) source\b/gi,
+    message:
+      "end-user prose must state supported behavior, not narrate source inspection",
+  },
+  {
+    pattern: /\bat the reviewed revision\b/gi,
+    message:
+      "end-user prose must not include the documentation verification timeline",
+  },
+  {
+    pattern: /\b(?:source|code|implementation) comment\b/gi,
+    message:
+      "end-user prose must not compare product behavior with source comments",
+  },
+  {
+    pattern:
+      /\b(?:the )?(?:current )?(?:source code|implementation)\s+(?:shows?|confirms?|reveals?|uses?|stores?|exposes?|calls?|defines?|accepts?|rejects?)\b/gi,
+    message:
+      "end-user prose must state supported behavior, not narrate implementation evidence",
+  },
+  {
+    pattern:
+      /\b(?:verified|reviewed|checked|compared)\s+(?:against|in)\s+(?:the )?(?:source|source code|implementation|revision|commit)\b/gi,
+    message: "end-user prose must keep verification evidence in review notes",
+  },
+  {
+    pattern:
+      /\b(?:at|in)\s+(?:the )?(?:reviewed|current)\s+(?:revision|commit)\b/gi,
+    message:
+      "end-user prose must not include the documentation verification timeline",
+  },
+  {
+    pattern: /\ban older [^.\n]{0,80}\bcomment\b/gi,
+    message:
+      "end-user prose must not compare product behavior with older comments",
+  },
+  {
+    pattern: /\bincorrectly calls?\b/gi,
+    message:
+      "end-user prose must not narrate a discrepancy found during source review",
+  },
+  {
+    pattern: /\bwhat the implementation exposes\b/gi,
+    message:
+      "end-user headings must describe the user capability, not the implementation",
+  },
+  {
+    pattern: /\binternally,\s+Lifecycle\b/gi,
+    message:
+      "end-user prose must describe user-observable behavior, not implementation machinery",
+  },
+  {
+    pattern: /\binternally\b/gi,
+    message:
+      "end-user prose must describe user-observable behavior, not implementation machinery",
+  },
+  {
+    pattern: /\bprocess-local\b/gi,
+    message:
+      "end-user prose must not expose process cache implementation details",
+  },
+  {
+    pattern: /\btyped configuration writes clear\b/gi,
+    message:
+      "end-user prose must describe supported configuration results, not cache implementation",
+  },
+  {
+    pattern: /\bperiodic refresh code\b/gi,
+    message:
+      "end-user prose must describe supported configuration results, not refresh implementation",
+  },
+  {
+    pattern:
+      /\b(?:database (?:record|row|table)|Redis (?:key|record)|handler name|controller name|service class)\b/gi,
+    message:
+      "end-user prose must not expose non-actionable implementation structures",
+  },
+  {
+    pattern:
+      /\b(?:stored|cached)\s+in\s+(?:the\s+)?(?:database|Postgres|Redis|memory|process)\b/gi,
+    message:
+      "end-user prose must describe the supported task, not internal persistence or cache placement",
+  },
+  {
+    pattern: /\bsource-backed\b/gi,
+    message:
+      "end-user prose must state the verified result without documentation-audit labels",
+  },
+  {
+    pattern: /\bdocumentation (?:verification )?baseline\b/gi,
+    message:
+      "end-user prose must not expose documentation maintenance metadata",
+  },
+  {
+    pattern: /\bmachine-readable audience\b/gi,
+    message:
+      "end-user prose must not expose documentation maintenance metadata",
+  },
+  {
+    pattern: /\bmaintainer-access source revision\b/gi,
+    message:
+      "end-user prose must not expose maintainer-only verification evidence",
+  },
+  {
+    pattern:
+      /\bthis (?:JSON|example|reference) documents the runtime (?:shape|value)\b/gi,
+    message:
+      "end-user prose must explain the supported task, not how an internal value was documented",
+  },
+  {
+    pattern: /\bnot a database-edit procedure\b/gi,
+    message:
+      "end-user prose must not frame internal data as a documentation procedure",
+  },
+  {
+    pattern: /\bthe database is not a supported editor\b/gi,
+    message:
+      "end-user prose must name the supported configuration surface instead of internal storage",
+  },
+  {
+    pattern: /\bproduct contract has a defect\b/gi,
+    message:
+      "end-user prose must give a supported action instead of maintainer triage",
+  },
+  {
+    pattern: /\bowning maintainer\b/gi,
+    message:
+      "end-user prose must give a user support path instead of maintainer workflow",
+  },
+  {
+    pattern: /\bversioned,\s+release-approved\b/gi,
+    message:
+      "end-user prose must link a supported procedure instead of describing review status",
+  },
+];
+
+function context(rootDir: string): ValidationContext {
+  const resolvedRoot = path.resolve(rootDir);
+  return {
+    rootDir: resolvedRoot,
+    publicRoot: path.join(resolvedRoot, "public"),
+  };
+}
+
+export async function validateRawMarkdownDelivery({
+  rootDir = process.cwd(),
+}: ValidationOptions = {}): Promise<ValidationIssue[]> {
+  const resolvedRoot = path.resolve(rootDir);
+  const configPath = path.join(resolvedRoot, RAW_MARKDOWN_SERVER_CONFIG);
+  let source: string;
+  try {
+    source = await fs.promises.readFile(configPath, "utf8");
+  } catch (error) {
+    return [
+      {
+        file: RAW_MARKDOWN_SERVER_CONFIG,
+        message: `raw Markdown server configuration is unavailable: ${
+          error instanceof Error ? error.message.split("\n")[0] : String(error)
+        }`,
+      },
+    ];
+  }
+
+  const location = source.match(
+    /location\s+~\s+\\\.md\$\s*\{([\s\S]*?)^\s*\}/m,
+  )?.[1];
+  if (!location) {
+    return [
+      {
+        file: RAW_MARKDOWN_SERVER_CONFIG,
+        message: "raw Markdown requires a dedicated .md location",
+      },
+    ];
+  }
+
+  const issues: ValidationIssue[] = [];
+  if (!/\btypes\s*\{\s*\}/.test(location)) {
+    issues.push({
+      file: RAW_MARKDOWN_SERVER_CONFIG,
+      message:
+        "raw Markdown must clear inherited MIME mappings before setting its UTF-8 media type",
+    });
+  }
+  if (
+    !/\bdefault_type\s+["']text\/markdown;\s*charset=utf-8["']\s*;/i.test(
+      location,
+    )
+  ) {
+    issues.push({
+      file: RAW_MARKDOWN_SERVER_CONFIG,
+      message:
+        'raw Markdown must use Content-Type "text/markdown; charset=utf-8"',
+    });
+  }
+  if (!/\btry_files\s+\$uri\s+=404\s*;/.test(location)) {
+    issues.push({
+      file: RAW_MARKDOWN_SERVER_CONFIG,
+      message:
+        "raw Markdown must return 404 for a missing file instead of the HTML fallback",
+    });
+  }
+  const retiredRouteLocations = [
+    /location\s*=\s*\/docs\/cm\s*\{\s*return\s+404\s*;\s*\}/,
+    /location\s*=\s*\/docs\/cm\.md\s*\{\s*return\s+404\s*;\s*\}/,
+    /location\s+\^~\s+\/docs\/cm\/\s*\{\s*return\s+404\s*;\s*\}/,
+  ];
+  if (retiredRouteLocations.some((pattern) => !pattern.test(source))) {
+    issues.push({
+      file: RAW_MARKDOWN_SERVER_CONFIG,
+      message: "retired /docs/cm routes must return 404",
+    });
+  }
+  if (!/\berror_page\s+404\s+\/404\.html\s*;/.test(source)) {
+    issues.push({
+      file: RAW_MARKDOWN_SERVER_CONFIG,
+      message: "404 responses must use the exported 404 page",
+    });
+  }
+  const htmlLocation = source.match(/location\s+\/\s*\{([\s\S]*?)^\s*\}/m)?.[1];
+  if (
+    !htmlLocation ||
+    !/\btry_files\s+\$uri\.html\s+\$uri(?:\s+\$uri\/)?\s+\/index\.html\s*;/.test(
+      htmlLocation,
+    )
+  ) {
+    issues.push({
+      file: RAW_MARKDOWN_SERVER_CONFIG,
+      message:
+        "HTML routes must prefer the exported .html file before a same-name asset directory",
+    });
+  }
+  return issues;
+}
+
+function routeFor(rootDir: string, file: string): string {
+  const relative = path
+    .relative(path.join(rootDir, "src/pages"), file)
+    .replace(/\\/g, "/")
+    .replace(/\.mdx$/, "");
+  return `/${relative.replace(/\/index$/, "")}`;
+}
+
+function stripDestination(destination: string): string {
+  return destination.split(/[?#]/, 1)[0].replace(/\/$/, "") || "/";
+}
+
+function headingText(markdown: string): string {
+  return markdown
+    .replace(/\s+\{#[^}]+\}\s*$/, "")
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/[`*_~]/g, "")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .trim();
+}
+
+function headingFragments(source: string): Set<string> {
+  const fragments = new Set<string>();
+  const slugger = new GithubSlugger();
+  const withoutFences = source.replace(
+    /^(?: {0,3})(`{3,}|~{3,})[^\n]*\n[\s\S]*?^(?: {0,3})\1[ \t]*$/gm,
+    "",
+  );
+
+  for (const match of withoutFences.matchAll(
+    /^(?: {0,3})#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$/gm,
+  )) {
+    const explicit = match[1].match(/\s+\{#([^}]+)\}\s*$/)?.[1];
+    if (explicit) fragments.add(explicit);
+    const text = headingText(match[1]);
+    if (text) fragments.add(slugger.slug(text));
+  }
+
+  for (const match of withoutFences.matchAll(
+    /<(?:a|[hH][1-6])\b[^>]*\bid=["']([^"']+)["'][^>]*>/g,
+  )) {
+    fragments.add(match[1]);
+  }
+
+  return fragments;
+}
+
+function sourceLine(source: string, index: number): number {
+  return source.slice(0, index).split("\n").length;
+}
+
+function addIssue(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+  index: number,
+  message: string,
+) {
+  issues.push({
+    file: `${path.relative(ctx.rootDir, file)}:${sourceLine(source, index)}`,
+    message,
+  });
+}
+
+function validateFrontmatter(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  data: Record<string, unknown>,
+  metadata: DocumentationMetadata | null,
+) {
+  for (const key of ["title", "description"]) {
+    if (typeof data[key] !== "string" || data[key].trim() === "") {
+      issues.push({
+        file: path.relative(ctx.rootDir, file),
+        message: `frontmatter requires a non-empty ${key}`,
+      });
+    }
+  }
+
+  if (metadata) {
+    for (const message of resolvePageMetadata(data, metadata).issues) {
+      issues.push({ file: path.relative(ctx.rootDir, file), message });
+    }
+  }
+}
+
+function validateInternalLinks(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+  routes: Set<string>,
+  fragmentsByRoute: Map<string, Set<string>>,
+) {
+  const destinations = [
+    ...source.matchAll(/\]\(((?:\/[^)\s]+|#[^)\s]+))(?:\s+["'][^"']*["'])?\)/g),
+    ...source.matchAll(/\bhref=["']((?:\/[^"']+|#[^"']+))["']/g),
+  ];
+
+  for (const match of destinations) {
+    const destination = match[1];
+    if (!destination.startsWith("/docs") && !destination.startsWith("#")) {
+      continue;
+    }
+    if (destination.includes(".mdx")) {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        `internal link must use a public route, not an .mdx path: ${destination}`,
+      );
+      continue;
+    }
+
+    const route = destination.startsWith("#")
+      ? routeFor(ctx.rootDir, file)
+      : stripDestination(destination);
+    if (!routes.has(route)) {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        `internal link targets a missing docs route: ${destination}`,
+      );
+      continue;
+    }
+
+    const encodedFragment = destination.includes("#")
+      ? destination.slice(destination.indexOf("#") + 1)
+      : "";
+    if (!encodedFragment) continue;
+
+    let fragment = encodedFragment;
+    try {
+      fragment = decodeURIComponent(encodedFragment);
+    } catch {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        `internal link contains an invalid encoded fragment: ${destination}`,
+      );
+      continue;
+    }
+
+    if (!fragmentsByRoute.get(route)?.has(fragment)) {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        `internal link targets a missing docs fragment: ${destination}`,
+      );
+    }
+  }
+}
+
+function localAssetPath(
+  ctx: ValidationContext,
+  sourcePath: string,
+): string | null {
+  if (!sourcePath.startsWith("/")) return null;
+  const normalized = path.posix.normalize(sourcePath.split(/[?#]/, 1)[0]);
+  const resolved = path.resolve(ctx.publicRoot, normalized.replace(/^\/+/, ""));
+  const publicPrefix = `${path.resolve(ctx.publicRoot)}${path.sep}`;
+  if (!resolved.startsWith(publicPrefix)) return null;
+  return resolved;
+}
+
+function validateMedia(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+) {
+  for (const match of source.matchAll(/<Image\b[\s\S]*?\/>/g)) {
+    const component = match[0];
+    const index = match.index ?? 0;
+    for (const prop of ["src", "alt", "width", "height"]) {
+      if (!new RegExp(`\\b${prop}=`).test(component)) {
+        addIssue(issues, ctx, file, source, index, `<Image> requires ${prop}`);
+      }
+    }
+
+    const src = component.match(/\bsrc=["']([^"']+)["']/)?.[1];
+    if (src?.startsWith("/")) {
+      const asset = localAssetPath(ctx, src);
+      if (!asset || !fs.existsSync(asset)) {
+        addIssue(
+          issues,
+          ctx,
+          file,
+          source,
+          index,
+          `<Image> asset does not exist: ${src}`,
+        );
+      }
+    }
+  }
+
+  for (const match of source.matchAll(/<Iframe\b[\s\S]*?\/>/g)) {
+    if (!/\btitle=/.test(match[0])) {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        "<Iframe> requires title",
+      );
+    }
+  }
+
+  for (const match of source.matchAll(/!\[([^\]]*)\]\(([^)]+)\)/g)) {
+    if (match[1].trim() === "") {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        "Markdown images require descriptive alt text",
+      );
+    }
+  }
+}
+
+function validateYaml(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+) {
+  for (const match of source.matchAll(/```ya?ml[^\n]*\n([\s\S]*?)```/g)) {
+    try {
+      yaml.loadAll(match[1]);
+    } catch (error) {
+      addIssue(
+        issues,
+        ctx,
+        file,
+        source,
+        match.index ?? 0,
+        `YAML example does not parse: ${
+          error instanceof Error ? error.message.split("\n")[0] : String(error)
+        }`,
+      );
+    }
+  }
+}
+
+function validatePlaceholders(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+  content: string,
+) {
+  const match = /\b(?:TODO|TBD|FIXME)\b/.exec(content);
+  if (match) {
+    const contentOffset = source.indexOf(content);
+    addIssue(
+      issues,
+      ctx,
+      file,
+      source,
+      Math.max(contentOffset, 0) + match.index,
+      "published docs must not contain unresolved TODO, TBD, or FIXME markers",
+    );
+  }
+}
+
+function validateHeadingHierarchy(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+  content: string,
+) {
+  const withoutFences = content.replace(
+    /^(?: {0,3})(`{3,}|~{3,})[^\n]*\n[\s\S]*?^(?: {0,3})\1[ \t]*$/gm,
+    "",
+  );
+  const contentOffset = source.indexOf(content);
+
+  for (const match of withoutFences.matchAll(/^(?: {0,3})#[ \t]+.+$/gm)) {
+    addIssue(
+      issues,
+      ctx,
+      file,
+      source,
+      Math.max(contentOffset, 0) + (match.index ?? 0),
+      "page body headings must start at level 2 because frontmatter renders the page H1",
+    );
+  }
+}
+
+function maskMarkdownCode(source: string): string {
+  const mask = (value: string) => value.replace(/[^\n]/g, " ");
+  return source
+    .replace(
+      /^(?: {0,3})(`{3,}|~{3,})[^\n]*\n[\s\S]*?^(?: {0,3})\1[ \t]*$/gm,
+      mask,
+    )
+    .replace(/`[^`\n]+`/g, mask);
+}
+
+function validateDocumentationVoice(
+  issues: ValidationIssue[],
+  ctx: ValidationContext,
+  file: string,
+  source: string,
+) {
+  const prose = maskMarkdownCode(source);
+  for (const { pattern, message } of DOCUMENTATION_AUDIT_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of prose.matchAll(pattern)) {
+      addIssue(issues, ctx, file, source, match.index ?? 0, message);
+    }
+  }
+}
+
+export async function validatePortableGuidance({
+  rootDir = process.cwd(),
+}: ValidationOptions = {}): Promise<ValidationIssue[]> {
+  const ctx = context(rootDir);
+  const issues: ValidationIssue[] = [];
+
+  for (const relative of PORTABLE_GUIDANCE_FILES) {
+    const file = path.join(ctx.rootDir, relative);
+    if (!fs.existsSync(file)) continue;
+    const source = await fs.promises.readFile(file, "utf8");
+    for (const { pattern, message } of PORTABILITY_PATTERNS) {
+      pattern.lastIndex = 0;
+      for (const match of source.matchAll(pattern)) {
+        addIssue(issues, ctx, file, source, match.index ?? 0, message);
+      }
+    }
+  }
+
+  return issues;
+}
+
+function numericProp(component: string, name: string): number | null {
+  const match = component.match(
+    new RegExp(`\\b${name}=\\{?\\s*["']?(\\d+)["']?\\s*\\}?`),
+  );
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+function collectScreenshotReferences(
+  files: Array<{ file: string; source: string }>,
+): ScreenshotReference[] {
+  const references: ScreenshotReference[] = [];
+  for (const { file, source } of files) {
+    for (const match of source.matchAll(/<Image\b[\s\S]*?\/>/g)) {
+      const component = match[0];
+      const src = component.match(/\bsrc=["']([^"']+)["']/)?.[1];
+      if (!src?.startsWith("/")) continue;
+      const asset = path.posix.normalize(src.split(/[?#]/, 1)[0]);
+      if (!RASTER_EXTENSIONS.has(path.posix.extname(asset).toLowerCase())) {
+        continue;
+      }
+      references.push({
+        asset,
+        file,
+        source,
+        index: match.index ?? 0,
+        declaredWidth: numericProp(component, "width"),
+        declaredHeight: numericProp(component, "height"),
+      });
+    }
+  }
+  return references;
+}
+
+function parseCatalog(source: string): Map<string, ScreenshotCatalogEntry[]> {
+  const entries = new Map<string, ScreenshotCatalogEntry[]>();
+  const lines = source.split(/\r?\n/);
+
+  for (const [index, line] of lines.entries()) {
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+    const asset = cells[0]?.match(/^`(\/[^`]+)`$/)?.[1];
+    if (!asset) continue;
+    const status = cells.at(-1)?.replace(/`/g, "").trim().toLowerCase() || "";
+    const entry = { asset, fields: cells, line: index + 1, status };
+    entries.set(asset, [...(entries.get(asset) || []), entry]);
+  }
+
+  return entries;
+}
+
+function pngDimensions(buffer: Buffer): ImageDimensions | null {
+  const signature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+  if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature)) {
+    return null;
+  }
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20),
+  };
+}
+
+function gifDimensions(buffer: Buffer): ImageDimensions | null {
+  const header = buffer.subarray(0, 6).toString("ascii");
+  if (buffer.length < 10 || (header !== "GIF87a" && header !== "GIF89a")) {
+    return null;
+  }
+  return {
+    width: buffer.readUInt16LE(6),
+    height: buffer.readUInt16LE(8),
+  };
+}
+
+function jpegDimensions(buffer: Buffer): ImageDimensions | null {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) {
+    return null;
+  }
+  const startOfFrame = new Set([
+    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce,
+    0xcf,
+  ]);
+  let offset = 2;
+
+  while (offset + 3 < buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    const marker = buffer[offset + 1];
+    offset += 2;
+    if (marker === 0xd8 || marker === 0xd9) continue;
+    if (offset + 1 >= buffer.length) break;
+    const segmentLength = buffer.readUInt16BE(offset);
+    if (segmentLength < 2 || offset + segmentLength > buffer.length) break;
+    if (startOfFrame.has(marker) && segmentLength >= 7) {
+      return {
+        height: buffer.readUInt16BE(offset + 3),
+        width: buffer.readUInt16BE(offset + 5),
+      };
+    }
+    offset += segmentLength;
+  }
+
+  return null;
+}
+
+function uint24LE(buffer: Buffer, offset: number): number {
+  return (
+    buffer[offset] | (buffer[offset + 1] << 8) | (buffer[offset + 2] << 16)
+  );
+}
+
+function webpDimensions(buffer: Buffer): ImageDimensions | null {
+  if (
+    buffer.length < 30 ||
+    buffer.subarray(0, 4).toString("ascii") !== "RIFF" ||
+    buffer.subarray(8, 12).toString("ascii") !== "WEBP"
+  ) {
+    return null;
+  }
+
+  const chunk = buffer.subarray(12, 16).toString("ascii");
+  if (chunk === "VP8X") {
+    return {
+      width: uint24LE(buffer, 24) + 1,
+      height: uint24LE(buffer, 27) + 1,
+    };
+  }
+  if (chunk === "VP8 " && buffer.length >= 30) {
+    return {
+      width: buffer.readUInt16LE(26) & 0x3fff,
+      height: buffer.readUInt16LE(28) & 0x3fff,
+    };
+  }
+  if (chunk === "VP8L" && buffer.length >= 25 && buffer[20] === 0x2f) {
+    return {
+      width: 1 + buffer[21] + ((buffer[22] & 0x3f) << 8),
+      height:
+        1 + (buffer[22] >> 6) + (buffer[23] << 2) + ((buffer[24] & 0x0f) << 10),
+    };
+  }
+  return null;
+}
+
+async function readImageDimensions(file: string): Promise<ImageDimensions> {
+  const buffer = await fs.promises.readFile(file);
+  const extension = path.extname(file).toLowerCase();
+  const dimensions =
+    extension === ".png"
+      ? pngDimensions(buffer)
+      : extension === ".gif"
+        ? gifDimensions(buffer)
+        : extension === ".jpg" || extension === ".jpeg"
+          ? jpegDimensions(buffer)
+          : extension === ".webp"
+            ? webpDimensions(buffer)
+            : null;
+  if (!dimensions || dimensions.width <= 0 || dimensions.height <= 0) {
+    throw new Error(`cannot read intrinsic ${extension || "image"} dimensions`);
+  }
+  return dimensions;
+}
+
+function catalogIssue(
+  issues: ValidationIssue[],
+  line: number,
+  message: string,
+) {
+  issues.push({ file: `${SCREENSHOT_CATALOG}:${line}`, message });
+}
+
+function isUnverifiedCatalogValue(value: string): boolean {
+  const normalized = value.replace(/`/g, "").trim();
+  return (
+    normalized === "" ||
+    /^(?:n\/a\b|none\b)/i.test(normalized) ||
+    /\b(?:pending|tbd|unknown|unverified)\b/i.test(normalized)
+  );
+}
+
+function catalogText(value: string): string {
+  return value.replace(/^`|`$/g, "").trim();
+}
+
+export async function validateScreenshots({
+  rootDir = process.cwd(),
+}: ValidationOptions = {}): Promise<ValidationIssue[]> {
+  const ctx = context(rootDir);
+  const issues: ValidationIssue[] = [];
+  const docsFiles = (
+    await fg("src/pages/docs/**/*.mdx", {
+      absolute: true,
+      cwd: ctx.rootDir,
+    })
+  ).sort();
+  const sources = await Promise.all(
+    docsFiles.map(async (file) => ({
+      file,
+      source: await fs.promises.readFile(file, "utf8"),
+    })),
+  );
+  const references = collectScreenshotReferences(sources);
+  const referencesByAsset = new Map<string, ScreenshotReference[]>();
+  for (const reference of references) {
+    referencesByAsset.set(reference.asset, [
+      ...(referencesByAsset.get(reference.asset) || []),
+      reference,
+    ]);
+  }
+
+  const catalogPath = path.join(ctx.rootDir, SCREENSHOT_CATALOG);
+  if (!fs.existsSync(catalogPath)) {
+    issues.push({
+      file: SCREENSHOT_CATALOG,
+      message: "screenshot catalog does not exist",
+    });
+    return issues;
+  }
+  const catalogSource = await fs.promises.readFile(catalogPath, "utf8");
+  const catalog = parseCatalog(catalogSource);
+
+  for (const [asset, entries] of catalog) {
+    if (entries.length > 1) {
+      catalogIssue(
+        issues,
+        entries[1].line,
+        `screenshot catalog contains duplicate asset ${asset}`,
+      );
+    }
+    const entry = entries[0];
+    if (!SCREENSHOT_STATUSES.has(entry.status)) {
+      catalogIssue(
+        issues,
+        entry.line,
+        `${asset} requires review status keep, replace, or remove`,
+      );
+    } else if (entry.status !== "keep") {
+      catalogIssue(
+        issues,
+        entry.line,
+        `${asset} is marked ${entry.status} and must be remediated`,
+      );
+    } else {
+      const requiredFields = [
+        ["user point", entry.fields[2] || ""],
+        ["UI route/state", entry.fields[3] || ""],
+        ["fixture and cleanup", entry.fields[4] || ""],
+        ["viewport/theme", entry.fields[5] || ""],
+        ["UI revision", entry.fields[6] || ""],
+        ["verification date", entry.fields[7] || ""],
+      ];
+      const unresolvedFields = requiredFields
+        .filter(([, value]) => isUnverifiedCatalogValue(value))
+        .map(([label]) => label);
+      if (unresolvedFields.length > 0) {
+        catalogIssue(
+          issues,
+          entry.line,
+          `${asset} is marked keep but has unresolved catalog field(s): ${unresolvedFields.join(", ")}`,
+        );
+      }
+    }
+
+    if (!referencesByAsset.has(asset)) {
+      catalogIssue(
+        issues,
+        entry.line,
+        `${asset} is cataloged but not referenced by a docs page`,
+      );
+    } else {
+      const catalogRoute = catalogText(entry.fields[1] || "");
+      const referenceRoutes = new Set(
+        (referencesByAsset.get(asset) || []).map((reference) =>
+          routeFor(ctx.rootDir, reference.file),
+        ),
+      );
+      if (
+        !catalogRoute.startsWith("/docs") ||
+        referenceRoutes.size !== 1 ||
+        !referenceRoutes.has(catalogRoute)
+      ) {
+        catalogIssue(
+          issues,
+          entry.line,
+          `${asset} catalog docs page ${catalogRoute || "(missing)"} does not match reference route(s): ${[...referenceRoutes].join(", ")}`,
+        );
+      }
+    }
+    const file = localAssetPath(ctx, asset);
+    if (!file || !fs.existsSync(file)) {
+      catalogIssue(
+        issues,
+        entry.line,
+        `${asset} is cataloged but the public asset does not exist`,
+      );
+    }
+  }
+
+  for (const reference of references) {
+    if (!catalog.has(reference.asset)) {
+      addIssue(
+        issues,
+        ctx,
+        reference.file,
+        reference.source,
+        reference.index,
+        `${reference.asset} is missing from the screenshot catalog`,
+      );
+    }
+
+    const file = localAssetPath(ctx, reference.asset);
+    if (!file || !fs.existsSync(file)) continue;
+    if (reference.declaredWidth === null || reference.declaredHeight === null) {
+      addIssue(
+        issues,
+        ctx,
+        reference.file,
+        reference.source,
+        reference.index,
+        `${reference.asset} requires numeric width and height for the screenshot audit`,
+      );
+      continue;
+    }
+
+    try {
+      const actual = await readImageDimensions(file);
+      if (
+        actual.width !== reference.declaredWidth ||
+        actual.height !== reference.declaredHeight
+      ) {
+        addIssue(
+          issues,
+          ctx,
+          reference.file,
+          reference.source,
+          reference.index,
+          `${reference.asset} declares ${reference.declaredWidth}x${reference.declaredHeight} but is ${actual.width}x${actual.height}`,
+        );
+      }
+    } catch (error) {
+      addIssue(
+        issues,
+        ctx,
+        reference.file,
+        reference.source,
+        reference.index,
+        `${reference.asset} ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  const publicRasters = await fg("public/**/*.{gif,jpeg,jpg,png,webp}", {
+    cwd: ctx.rootDir,
+    onlyFiles: true,
+  });
+  for (const relative of publicRasters) {
+    const asset = `/${path
+      .relative(ctx.publicRoot, path.join(ctx.rootDir, relative))
+      .replace(/\\/g, "/")}`;
+    if (
+      !NON_SCREENSHOT_RASTERS.has(asset) &&
+      !referencesByAsset.has(asset) &&
+      !catalog.has(asset)
+    ) {
+      issues.push({
+        file: relative,
+        message:
+          "raster asset is neither referenced nor classified in the screenshot catalog",
+      });
+    }
+  }
+
+  for (const { pattern, message } of PORTABILITY_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of catalogSource.matchAll(pattern)) {
+      addIssue(
+        issues,
+        ctx,
+        catalogPath,
+        catalogSource,
+        match.index ?? 0,
+        `screenshot catalog ${message}`,
+      );
+    }
+  }
+
+  return issues;
+}
+
+export async function validateDocs({
+  rootDir = process.cwd(),
+}: ValidationOptions = {}): Promise<ValidationIssue[]> {
+  const ctx = context(rootDir);
+  const files = (
+    await fg("src/pages/docs/**/*.mdx", {
+      absolute: true,
+      cwd: ctx.rootDir,
+    })
+  ).sort();
+  const routes = new Set(files.map((file) => routeFor(ctx.rootDir, file)));
+  const sources = new Map(
+    await Promise.all(
+      files.map(async (file) => [
+        file,
+        await fs.promises.readFile(file, "utf8"),
+      ]),
+    ),
+  );
+  const fragmentsByRoute = new Map(
+    files.map((file) => [
+      routeFor(ctx.rootDir, file),
+      headingFragments(sources.get(file) || ""),
+    ]),
+  );
+  const issues: ValidationIssue[] = [];
+  let metadata: DocumentationMetadata | null = null;
+  try {
+    metadata = await loadDocumentationMetadata(ctx.rootDir);
+  } catch (error) {
+    issues.push({
+      file: DOCUMENTATION_METADATA,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  for (const file of files) {
+    const source = sources.get(file) || "";
+    let parsed: ReturnType<typeof matter> | null = null;
+    try {
+      parsed = matter(source);
+    } catch (error) {
+      issues.push({
+        file: path.relative(ctx.rootDir, file),
+        message: `frontmatter does not parse: ${
+          error instanceof Error ? error.message.split("\n")[0] : String(error)
+        }`,
+      });
+    }
+    if (parsed) validateFrontmatter(issues, ctx, file, parsed.data, metadata);
+    validateInternalLinks(issues, ctx, file, source, routes, fragmentsByRoute);
+    validateMedia(issues, ctx, file, source);
+    validateYaml(issues, ctx, file, source);
+    validateDocumentationVoice(issues, ctx, file, source);
+    if (parsed) {
+      validateHeadingHierarchy(issues, ctx, file, source, parsed.content);
+      validatePlaceholders(issues, ctx, file, source, parsed.content);
+    }
+  }
+
+  issues.push(...(await validatePortableGuidance({ rootDir })));
+  issues.push(...(await validateRawMarkdownDelivery({ rootDir })));
+  return issues;
+}
+
+async function runCli() {
+  const screenshotsOnly = process.argv.includes("--screenshots-only");
+  const issues = screenshotsOnly
+    ? await validateScreenshots()
+    : await validateDocs();
+  if (issues.length > 0) {
+    for (const issue of issues) {
+      console.error(`${issue.file} — ${issue.message}`);
+    }
+    console.error(
+      `\n${screenshotsOnly ? "Screenshot" : "Documentation"} validation failed with ${issues.length} issue(s).`,
+    );
+    process.exit(1);
+  }
+
+  if (screenshotsOnly) {
+    console.log(
+      "Screenshot structural validation passed. Manual pixel privacy and live-state review is still required.",
+    );
+  } else {
+    console.log("Documentation validation passed.");
+  }
+}
+
+if (import.meta.main) {
+  await runCli();
+}
diff --git a/scripts/validateSte100.ts b/scripts/validateSte100.ts
new file mode 100644
index 00000000..24d72a5a
--- /dev/null
+++ b/scripts/validateSte100.ts
@@ -0,0 +1,1002 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import matter from "gray-matter";
+import {
+  readNavigationMetadata,
+  type NavigationSource,
+} from "./navigationMetadata";
+
+export const STYLE_BASELINE_FILE = "documentation-style-baseline.json";
+export const ASD_STE100_REFERENCE = "ASD-STE100 Issue 9";
+export const CANONICAL_CONTENT_PROFILE = "asd-ste100";
+export const ASD_STE100_RULE_IDS = [
+  ...Array.from({ length: 14 }, (_, index) => `1.${index + 1}`),
+  ...Array.from({ length: 2 }, (_, index) => `2.${index + 1}`),
+  ...Array.from({ length: 7 }, (_, index) => `3.${index + 1}`),
+  ...Array.from({ length: 5 }, (_, index) => `4.${index + 1}`),
+  ...Array.from({ length: 5 }, (_, index) => `5.${index + 1}`),
+  ...Array.from({ length: 6 }, (_, index) => `6.${index + 1}`),
+  ...Array.from({ length: 3 }, (_, index) => `7.${index + 1}`),
+  ...Array.from({ length: 7 }, (_, index) => `8.${index + 1}`),
+  ...Array.from({ length: 4 }, (_, index) => `9.${index + 1}`),
+];
+export type Ste100Issue = {
+  file: string;
+  line: number;
+  message: string;
+};
+
+export type StyleBaselineIssue = {
+  file: string;
+  message: string;
+};
+
+export type Ste100ValidationOptions = {
+  rootDir?: string;
+};
+
+type ProseBlock = {
+  informationalCallout: boolean;
+  line: number;
+  procedure: boolean;
+  text: string;
+};
+
+type StylePage = {
+  file: string;
+  hash: string;
+  profile: string;
+  route: string;
+};
+
+type StyleSurface = {
+  file: string;
+  hash: string;
+  id: string;
+  profile: string;
+};
+
+type StyleBaselineEntry = {
+  file: string;
+  profile: string;
+  reviewedOn: string;
+  sha256: string;
+};
+
+type StyleBaseline = {
+  schemaVersion: number;
+  updatedOn: string;
+  references: {
+    canonical: string;
+    canonicalRules: string[];
+  };
+  pages: Record<string, StyleBaselineEntry>;
+  surfaces: Record<string, StyleBaselineEntry>;
+};
+
+const SITE_CHROME_FILES = [
+  {
+    file: "src/theme.config.tsx",
+    id: "site-chrome:theme",
+  },
+  {
+    file: "src/components/site-footer/index.tsx",
+    id: "site-chrome:footer",
+  },
+] as const;
+
+const CONTRACTIONS =
+  /\b(?:aren't|can't|couldn't|didn't|doesn't|don't|hadn't|hasn't|haven't|he'll|he's|isn't|it'll|it's|mustn't|shan't|she'll|she's|shouldn't|that's|there's|they'll|they're|they've|wasn't|we'll|we're|we've|weren't|won't|wouldn't|you'll|you're|you've)\b/gi;
+const COMPLEX_VERB_GROUP =
+  /\b(?:has|have|had|will)\s+(?:not\s+)?(?:been|being|have)\b|\b(?:am|are|is|was|were)\s+(?:not\s+)?being\b/gi;
+const CONDITION = /\b(?:after|before|if|when)\b/i;
+const INSTRUCTION_STARTS = new Set([
+  "add",
+  "apply",
+  "attach",
+  "build",
+  "check",
+  "choose",
+  "click",
+  "close",
+  "configure",
+  "confirm",
+  "copy",
+  "create",
+  "delete",
+  "deploy",
+  "disable",
+  "enable",
+  "enter",
+  "follow",
+  "go",
+  "install",
+  "keep",
+  "make",
+  "open",
+  "provide",
+  "remove",
+  "replace",
+  "review",
+  "run",
+  "save",
+  "select",
+  "set",
+  "start",
+  "stop",
+  "use",
+  "verify",
+  "wait",
+]);
+
+function routeFor(relative: string): string {
+  return `/${relative
+    .replace(/\\/g, "/")
+    .replace(/\.mdx$/, "")
+    .replace(/\/index$/, "")}`;
+}
+
+function replaceProtected(source: string): string {
+  return source
+    .replace(
+      /^ {0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?^ {0,3}\1[ \t]*$/gm,
+      (value) => value.replace(/[^\n]/g, " "),
+    )
+    .replace(/`+[^`\n]+`+/g, " TERM ")
+    .replace(/\{[^{}\n]*\}/g, " TERM ")
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/<[^>]+>/g, (value) => value.replace(/[^\n]/g, " "))
+    .replace(/https?:\/\/\S+/g, " URL ")
+    .replace(/&(?:amp|lt|gt|quot|apos);/g, " TERM ");
+}
+
+function plainText(source: string): string {
+  return replaceProtected(source)
+    .replace(/^ {0,3}#{1,6}[ \t]+/gm, "")
+    .replace(/^ {0,3}(?:[-+*]|\d+[.)])[ \t]+/gm, "")
+    .replace(/^ {0,3}>[ \t]?/gm, "")
+    .replace(/\*\*|__|~~/g, "")
+    .replace(/(?<!\w)[*_](?!\w)/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function firstWord(value: string): string {
+  return (
+    plainText(value)
+      .match(/^[("'[]*([A-Za-z]+)/)?.[1]
+      ?.toLowerCase() || ""
+  );
+}
+
+function isInstruction(value: string): boolean {
+  return INSTRUCTION_STARTS.has(firstWord(value));
+}
+
+function collectBlocks(content: string, lineOffset = 0): ProseBlock[] {
+  const lines = content.split(/\r?\n/);
+  const blocks: ProseBlock[] = [];
+  let current: string[] = [];
+  let currentInformationalCallout = false;
+  let currentLine = 1;
+  let currentProcedure = false;
+  let fence: string | null = null;
+  let inImport = false;
+  let stepsDepth = 0;
+  const calloutStack: boolean[] = [];
+
+  function flush(): void {
+    const text = plainText(current.join(" "));
+    if (text) {
+      blocks.push({
+        informationalCallout: currentInformationalCallout,
+        line: currentLine,
+        procedure: currentProcedure || isInstruction(text),
+        text,
+      });
+    }
+    current = [];
+    currentInformationalCallout = false;
+    currentProcedure = false;
+  }
+
+  for (const [index, line] of lines.entries()) {
+    const lineNumber = index + 1 + lineOffset;
+    const fenceMarker = line.match(/^ {0,3}(`{3,}|~{3,})/)?.[1];
+    if (fence) {
+      if (
+        fenceMarker?.startsWith(fence[0]) &&
+        fenceMarker.length >= fence.length
+      ) {
+        fence = null;
+      }
+      continue;
+    }
+    if (fenceMarker) {
+      flush();
+      fence = fenceMarker;
+      continue;
+    }
+
+    if (inImport) {
+      if (/;\s*$/.test(line)) inImport = false;
+      continue;
+    }
+    if (/^\s*import\b/.test(line)) {
+      flush();
+      inImport = !/;\s*$/.test(line);
+      continue;
+    }
+
+    const callout = line.match(/<Callout\b([^>]*)>/);
+    if (callout) {
+      flush();
+      const type = callout[1].match(/\btype=["']([^"']+)["']/i)?.[1];
+      calloutStack.push(
+        type === undefined || ["info", "note"].includes(type.toLowerCase()),
+      );
+    }
+    if (/<Steps\b/.test(line)) stepsDepth += 1;
+    const closesSteps = /<\/Steps>/.test(line);
+    const closesCallout = /<\/Callout>/.test(line);
+    const stripped = plainText(line);
+    const isTable = /^\s*\|.*\|\s*$/.test(line);
+    const isTableRule =
+      isTable &&
+      line
+        .split("|")
+        .slice(1, -1)
+        .every((cell) => /^\s*:?-{3,}:?\s*$/.test(cell));
+    const startsList = /^\s*(?:[-+*]|\d+[.)])\s+/.test(line);
+    const ordered = /^\s*\d+[.)]\s+/.test(line);
+    const heading = /^\s*#{1,6}\s+/.test(line);
+    const informationalCallout = calloutStack.includes(true);
+
+    if (!stripped || isTableRule) {
+      flush();
+    } else if (isTable) {
+      flush();
+      for (const cell of line.split("|").slice(1, -1)) {
+        const text = plainText(cell);
+        if (text) {
+          blocks.push({
+            informationalCallout,
+            line: lineNumber,
+            procedure: isInstruction(text),
+            text,
+          });
+        }
+      }
+    } else if (startsList || heading) {
+      flush();
+      currentLine = lineNumber;
+      currentInformationalCallout = informationalCallout;
+      currentProcedure = ordered || stepsDepth > 0;
+      current.push(line);
+      flush();
+    } else {
+      if (current.length === 0) currentLine = lineNumber;
+      currentInformationalCallout ||= informationalCallout;
+      currentProcedure ||= stepsDepth > 0;
+      current.push(line);
+    }
+
+    if (closesSteps) stepsDepth = Math.max(0, stepsDepth - 1);
+    if (closesCallout) {
+      flush();
+      calloutStack.pop();
+    }
+  }
+  flush();
+  return blocks;
+}
+
+function collectMdxProseAttributes(
+  content: string,
+  lineOffset = 0,
+): ProseBlock[] {
+  const fields = new Map<string, Set<string>>([
+    ["Cards.Card", new Set(["title"])],
+    ["Iframe", new Set(["title"])],
+    ["Image", new Set(["alt", "title"])],
+  ]);
+  const blocks: ProseBlock[] = [];
+  for (const element of content.matchAll(
+    /<(Cards\.Card|Iframe|Image)\b([\s\S]*?)>/g,
+  )) {
+    const allowed = fields.get(element[1]);
+    if (!allowed) continue;
+    const attributes = element[2];
+    for (const attribute of attributes.matchAll(
+      /\b([A-Za-z][A-Za-z0-9]*)=(?:"([^"]*)"|'([^']*)')/g,
+    )) {
+      if (!allowed.has(attribute[1])) continue;
+      const text = plainText(attribute[2] ?? attribute[3] ?? "");
+      if (!text) continue;
+      const index =
+        (element.index ?? 0) +
+        element[0].indexOf(attributes) +
+        (attribute.index ?? 0);
+      blocks.push({
+        informationalCallout: false,
+        line: lineOffset + content.slice(0, index).split(/\r?\n/).length,
+        procedure: false,
+        text,
+      });
+    }
+  }
+  return blocks;
+}
+
+function sentences(text: string): string[] {
+  const values = text.match(/[^.!?]+(?:[.!?]+(?=\s|$)|$)/g) || [];
+  return values.map((value) => value.trim()).filter(Boolean);
+}
+
+export function ste100WordCount(sentence: string): number {
+  const counted = sentence
+    .replace(/["“][^"”\n]+["”]/g, " TERM ")
+    .replace(/\([^().!?\n]*\)/g, " TERM ")
+    .replace(
+      /\b\d+(?:[.,]\d+)?\s+(?:bytes?|days?|degrees?\s+(?:Celsius|Fahrenheit)|gib|gb|hours?|kb|kilobytes?|mb|milliseconds?|minutes?|mib|ms|seconds?|tb|vcpus?)\b/gi,
+      " TERM ",
+    );
+  return (
+    counted.match(/\b(?:[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)*|TERM|URL)\b/g) || []
+  ).length;
+}
+
+function isInstructionSentence(value: string): boolean {
+  if (isInstruction(value)) return true;
+  const afterCondition = plainText(value).match(
+    /^(?:after|before|if|when)\b[^,]*,\s*(.+)$/i,
+  )?.[1];
+  return afterCondition ? isInstruction(afterCondition) : false;
+}
+
+function indexOfSentence(block: ProseBlock, sentence: string): number {
+  return Math.max(0, block.text.indexOf(sentence));
+}
+
+function sentenceLine(block: ProseBlock, sentence: string): number {
+  return (
+    block.line +
+    block.text.slice(0, indexOfSentence(block, sentence)).split("\n").length -
+    1
+  );
+}
+
+function checkPattern(
+  issues: Ste100Issue[],
+  file: string,
+  block: ProseBlock,
+  pattern: RegExp,
+  message: string,
+): void {
+  pattern.lastIndex = 0;
+  for (const match of block.text.matchAll(pattern)) {
+    issues.push({
+      file,
+      line: block.line,
+      message: `${message}: ${match[0]}`,
+    });
+  }
+}
+
+function validateBlocks(
+  issues: Ste100Issue[],
+  file: string,
+  blocks: ProseBlock[],
+): void {
+  for (const block of blocks) {
+    checkPattern(
+      issues,
+      file,
+      block,
+      /;/g,
+      "STE100 prose must not use a semicolon",
+    );
+    checkPattern(
+      issues,
+      file,
+      block,
+      CONTRACTIONS,
+      "STE100 prose must not use a contraction",
+    );
+    checkPattern(
+      issues,
+      file,
+      block,
+      /\band\/or\b/gi,
+      "STE100 prose must state the applicable alternative",
+    );
+    checkPattern(
+      issues,
+      file,
+      block,
+      COMPLEX_VERB_GROUP,
+      "STE100 prose must use a simple verb group",
+    );
+
+    const blockSentences = sentences(block.text);
+    if (!block.procedure && blockSentences.length > 6) {
+      issues.push({
+        file,
+        line: block.line,
+        message: `STE100 descriptive paragraph has ${blockSentences.length} sentences; maximum is 6`,
+      });
+    }
+
+    for (const sentence of blockSentences) {
+      if (block.informationalCallout && isInstructionSentence(sentence)) {
+        issues.push({
+          file,
+          line: sentenceLine(block, sentence),
+          message: "STE100 note must give information, not an instruction",
+        });
+      }
+
+      const count = ste100WordCount(sentence);
+      const maximum = block.procedure ? 20 : 25;
+      if (count > maximum) {
+        issues.push({
+          file,
+          line: sentenceLine(block, sentence),
+          message: `STE100 ${block.procedure ? "procedural" : "descriptive"} sentence has ${count} words; maximum is ${maximum}`,
+        });
+      }
+
+      if (block.procedure) {
+        const condition = sentence.match(CONDITION);
+        if (condition && (condition.index || 0) > 2) {
+          issues.push({
+            file,
+            line: sentenceLine(block, sentence),
+            message:
+              "STE100 procedure must put an after, before, if, or when condition first",
+          });
+        }
+        const secondInstruction = sentence.match(
+          new RegExp(
+            `\\band\\s+(?:then\\s+)?(?:${[...INSTRUCTION_STARTS].join("|")})\\b`,
+            "i",
+          ),
+        );
+        if (secondInstruction) {
+          issues.push({
+            file,
+            line: sentenceLine(block, sentence),
+            message: "STE100 procedural sentence must contain one instruction",
+          });
+        }
+      }
+    }
+  }
+}
+
+function navigationEntry(value: unknown): Record<string, unknown> {
+  if (typeof value === "string") return { title: value };
+  return isRecord(value) ? value : {};
+}
+
+function navigationTitleBlocks(
+  source: NavigationSource,
+  visibleOnly: boolean,
+): ProseBlock[] {
+  const blocks: ProseBlock[] = [];
+  for (const value of Object.values(source.navigation)) {
+    const entry = navigationEntry(value);
+    if (
+      entry.type === "separator" ||
+      (visibleOnly && entry.display === "hidden")
+    ) {
+      continue;
+    }
+    const title =
+      typeof value === "string"
+        ? value
+        : typeof entry.title === "string"
+          ? entry.title
+          : null;
+    if (!title?.trim()) continue;
+    const index = source.source.indexOf(JSON.stringify(title));
+    blocks.push({
+      informationalCallout: false,
+      line: index < 0 ? 1 : source.source.slice(0, index).split(/\r?\n/).length,
+      procedure: false,
+      text: plainText(title),
+    });
+  }
+  return blocks;
+}
+
+async function validateCanonicalNavigation(
+  issues: Ste100Issue[],
+  rootDir: string,
+): Promise<void> {
+  const docsMetaFiles = (
+    await fg("src/pages/docs/**/_meta.ts", {
+      absolute: true,
+      cwd: rootDir,
+      onlyFiles: true,
+    })
+  ).sort();
+  const rootMeta = path.join(rootDir, "src/pages/_meta.ts");
+  const files = [
+    ...docsMetaFiles.map((file) => ({ file, visibleOnly: false })),
+    ...(fs.existsSync(rootMeta) ? [{ file: rootMeta, visibleOnly: true }] : []),
+  ];
+
+  for (const { file, visibleOnly } of files) {
+    const relative = path.relative(rootDir, file).replace(/\\/g, "/");
+    try {
+      const source = await readNavigationMetadata(file);
+      validateBlocks(
+        issues,
+        `${relative} (navigation title)`,
+        navigationTitleBlocks(source, visibleOnly),
+      );
+    } catch (error) {
+      issues.push({
+        file: relative,
+        line: 1,
+        message: `navigation metadata does not parse: ${
+          error instanceof Error ? error.message.split("\n")[0] : String(error)
+        }`,
+      });
+    }
+  }
+}
+
+export async function validateSte100({
+  rootDir = process.cwd(),
+}: Ste100ValidationOptions = {}): Promise<Ste100Issue[]> {
+  const resolvedRoot = path.resolve(rootDir);
+  const files = (
+    await fg("src/pages/docs/**/*.mdx", {
+      absolute: true,
+      cwd: resolvedRoot,
+      onlyFiles: true,
+    })
+  ).sort();
+  const issues: Ste100Issue[] = [];
+
+  for (const file of files) {
+    const relative = path.relative(resolvedRoot, file);
+    const source = await fs.promises.readFile(file, "utf8");
+    let parsed: ReturnType<typeof matter>;
+    try {
+      parsed = matter(source);
+    } catch (error) {
+      issues.push({
+        file: relative,
+        line: 1,
+        message: `frontmatter does not parse: ${
+          error instanceof Error ? error.message.split("\n")[0] : String(error)
+        }`,
+      });
+      continue;
+    }
+
+    if (parsed.data.contentProfile !== CANONICAL_CONTENT_PROFILE) {
+      issues.push({
+        file: relative,
+        line: 1,
+        message: `documentation frontmatter requires contentProfile: ${CANONICAL_CONTENT_PROFILE}`,
+      });
+    }
+    if (
+      parsed.data.docsVariant !== undefined ||
+      parsed.data.canonicalRoute !== undefined
+    ) {
+      issues.push({
+        file: relative,
+        line: 1,
+        message:
+          "documentation frontmatter must not declare docsVariant or canonicalRoute",
+      });
+    }
+
+    const frontmatterProse = [
+      ["title", parsed.data.title],
+      ["description", parsed.data.description],
+      ["navtext", parsed.data.navtext],
+    ] as const;
+    for (const [field, value] of frontmatterProse) {
+      if (typeof value !== "string" || value.trim() === "") continue;
+      validateBlocks(issues, `${relative} (${field})`, [
+        {
+          informationalCallout: false,
+          line: 1,
+          procedure: false,
+          text: plainText(value),
+        },
+      ]);
+    }
+    const bodyStart = source.indexOf(parsed.content);
+    const lineOffset =
+      bodyStart < 0 ? 0 : source.slice(0, bodyStart).split(/\r?\n/).length - 1;
+    validateBlocks(issues, relative, collectBlocks(parsed.content, lineOffset));
+    validateBlocks(
+      issues,
+      relative,
+      collectMdxProseAttributes(parsed.content, lineOffset),
+    );
+  }
+
+  await validateCanonicalNavigation(issues, resolvedRoot);
+
+  return issues;
+}
+
+function styleHash(source: string): string {
+  const parsed = matter(source);
+  const reviewed = JSON.stringify({
+    title: parsed.data.title || null,
+    description: parsed.data.description || null,
+    navtext: parsed.data.navtext || null,
+    content: parsed.content.replace(/\r\n/g, "\n"),
+  });
+  return createHash("sha256").update(reviewed).digest("hex");
+}
+
+function reviewedHash(value: string | Record<string, unknown>): string {
+  const reviewed =
+    typeof value === "string"
+      ? value.replace(/\r\n/g, "\n")
+      : JSON.stringify(value);
+  return createHash("sha256").update(reviewed).digest("hex");
+}
+
+async function collectStylePages(rootDir: string): Promise<StylePage[]> {
+  const files = (
+    await fg("src/pages/docs/**/*.mdx", {
+      absolute: true,
+      cwd: rootDir,
+      onlyFiles: true,
+    })
+  ).sort();
+  return await Promise.all(
+    files.map(async (file) => {
+      const relative = path.relative(rootDir, file).replace(/\\/g, "/");
+      const source = await fs.promises.readFile(file, "utf8");
+      const data = matter(source).data;
+      return {
+        file: relative,
+        hash: styleHash(source),
+        profile:
+          typeof data.contentProfile === "string" ? data.contentProfile : "",
+        route: routeFor(path.relative(path.join(rootDir, "src/pages"), file)),
+      };
+    }),
+  );
+}
+
+async function collectStyleSurfaces(rootDir: string): Promise<StyleSurface[]> {
+  const docsMetaFiles = (
+    await fg("src/pages/docs/**/_meta.ts", {
+      absolute: true,
+      cwd: rootDir,
+      onlyFiles: true,
+    })
+  ).sort();
+  const surfaces: StyleSurface[] = [];
+
+  for (const file of docsMetaFiles) {
+    const relative = path.relative(rootDir, file).replace(/\\/g, "/");
+    const { navigation } = await readNavigationMetadata(file);
+    const docsDirectory = path
+      .relative(path.join(rootDir, "src/pages"), path.dirname(file))
+      .replace(/\\/g, "/");
+    surfaces.push({
+      file: relative,
+      hash: reviewedHash(navigation),
+      id: `navigation:/${docsDirectory}`,
+      profile: CANONICAL_CONTENT_PROFILE,
+    });
+  }
+
+  const rootMetaFile = path.join(rootDir, "src/pages/_meta.ts");
+  if (fs.existsSync(rootMetaFile)) {
+    const relative = path.relative(rootDir, rootMetaFile).replace(/\\/g, "/");
+    const { navigation } = await readNavigationMetadata(rootMetaFile);
+    const visibleNavigation = Object.fromEntries(
+      Object.entries(navigation).filter(([slug, value]) => {
+        if (slug === "*") return false;
+        return navigationEntry(value).display !== "hidden";
+      }),
+    );
+    surfaces.push({
+      file: relative,
+      hash: reviewedHash(visibleNavigation),
+      id: "navigation:/",
+      profile: CANONICAL_CONTENT_PROFILE,
+    });
+  }
+
+  for (const chrome of SITE_CHROME_FILES) {
+    const file = path.join(rootDir, chrome.file);
+    if (!fs.existsSync(file)) continue;
+    surfaces.push({
+      file: chrome.file,
+      hash: reviewedHash(await fs.promises.readFile(file, "utf8")),
+      id: chrome.id,
+      profile: CANONICAL_CONTENT_PROFILE,
+    });
+  }
+
+  return surfaces.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseBaseline(value: unknown): StyleBaseline | null {
+  if (
+    !isRecord(value) ||
+    value.schemaVersion !== 3 ||
+    typeof value.updatedOn !== "string" ||
+    !isRecord(value.references) ||
+    value.references.canonical !== ASD_STE100_REFERENCE ||
+    Object.keys(value.references).sort().join(",") !==
+      "canonical,canonicalRules" ||
+    !Array.isArray(value.references.canonicalRules) ||
+    JSON.stringify(value.references.canonicalRules) !==
+      JSON.stringify(ASD_STE100_RULE_IDS) ||
+    !isRecord(value.pages) ||
+    !isRecord(value.surfaces)
+  ) {
+    return null;
+  }
+  return value as unknown as StyleBaseline;
+}
+
+export async function validateStyleBaseline({
+  rootDir = process.cwd(),
+}: Ste100ValidationOptions = {}): Promise<StyleBaselineIssue[]> {
+  const resolvedRoot = path.resolve(rootDir);
+  const baselinePath = path.join(resolvedRoot, STYLE_BASELINE_FILE);
+  let baseline: StyleBaseline | null = null;
+  try {
+    baseline = parseBaseline(
+      JSON.parse(await fs.promises.readFile(baselinePath, "utf8")),
+    );
+  } catch {
+    baseline = null;
+  }
+  if (!baseline) {
+    return [
+      {
+        file: STYLE_BASELINE_FILE,
+        message:
+          "style review baseline is missing or invalid; run the reviewed baseline update workflow",
+      },
+    ];
+  }
+
+  const [pages, surfaces] = await Promise.all([
+    collectStylePages(resolvedRoot),
+    collectStyleSurfaces(resolvedRoot),
+  ]);
+  const actualRoutes = new Set(pages.map((page) => page.route));
+  const actualSurfaceIds = new Set(surfaces.map((surface) => surface.id));
+  const issues: StyleBaselineIssue[] = [];
+  for (const page of pages) {
+    const entry = baseline.pages[page.route];
+    if (!entry) {
+      issues.push({
+        file: page.file,
+        message: `style review baseline does not include ${page.route}`,
+      });
+      continue;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.reviewedOn)) {
+      issues.push({
+        file: STYLE_BASELINE_FILE,
+        message: `${page.route} requires a reviewedOn date`,
+      });
+    }
+    if (
+      entry.file !== page.file ||
+      entry.profile !== page.profile ||
+      entry.sha256 !== page.hash
+    ) {
+      issues.push({
+        file: page.file,
+        message: `reviewed ${page.profile || "(missing)"} content changed; complete its language-profile review and update ${STYLE_BASELINE_FILE}`,
+      });
+    }
+  }
+  for (const route of Object.keys(baseline.pages).filter(
+    (route) => !actualRoutes.has(route),
+  )) {
+    issues.push({
+      file: STYLE_BASELINE_FILE,
+      message: `style review baseline contains stale route ${route}`,
+    });
+  }
+  for (const surface of surfaces) {
+    const entry = baseline.surfaces[surface.id];
+    if (!entry) {
+      issues.push({
+        file: surface.file,
+        message: `style review baseline does not include ${surface.id}`,
+      });
+      continue;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.reviewedOn)) {
+      issues.push({
+        file: STYLE_BASELINE_FILE,
+        message: `${surface.id} requires a reviewedOn date`,
+      });
+    }
+    if (
+      entry.file !== surface.file ||
+      entry.profile !== surface.profile ||
+      entry.sha256 !== surface.hash
+    ) {
+      issues.push({
+        file: surface.file,
+        message: `reviewed ${surface.profile} surface changed; complete its language-profile review and update ${STYLE_BASELINE_FILE}`,
+      });
+    }
+  }
+  for (const id of Object.keys(baseline.surfaces).filter(
+    (id) => !actualSurfaceIds.has(id),
+  )) {
+    issues.push({
+      file: STYLE_BASELINE_FILE,
+      message: `style review baseline contains stale surface ${id}`,
+    });
+  }
+  return issues;
+}
+
+export async function writeStyleBaseline({
+  rootDir = process.cwd(),
+}: Ste100ValidationOptions = {}): Promise<void> {
+  const resolvedRoot = path.resolve(rootDir);
+  const ste100Issues = await validateSte100({ rootDir: resolvedRoot });
+  if (ste100Issues.length > 0) {
+    throw new Error(
+      `cannot update the style baseline while ${ste100Issues.length} mechanical STE100 issue(s) remain`,
+    );
+  }
+  const [pages, surfaces] = await Promise.all([
+    collectStylePages(resolvedRoot),
+    collectStyleSurfaces(resolvedRoot),
+  ]);
+  const invalidProfiles = pages.filter(
+    (page) => page.profile !== CANONICAL_CONTENT_PROFILE,
+  );
+  if (invalidProfiles.length > 0) {
+    throw new Error(
+      `cannot update the style baseline while ${invalidProfiles.length} page(s) have an invalid contentProfile`,
+    );
+  }
+  let prior: StyleBaseline | null = null;
+  try {
+    prior = parseBaseline(
+      JSON.parse(
+        await fs.promises.readFile(
+          path.join(resolvedRoot, STYLE_BASELINE_FILE),
+          "utf8",
+        ),
+      ),
+    );
+  } catch {
+    prior = null;
+  }
+  const today = new Date().toISOString().slice(0, 10);
+  const baseline: StyleBaseline = {
+    schemaVersion: 3,
+    updatedOn: today,
+    references: {
+      canonical: ASD_STE100_REFERENCE,
+      canonicalRules: ASD_STE100_RULE_IDS,
+    },
+    pages: Object.fromEntries(
+      pages
+        .sort((left, right) => left.route.localeCompare(right.route))
+        .map((page) => [
+          page.route,
+          (() => {
+            const priorEntry = prior?.pages[page.route];
+            const unchanged =
+              priorEntry?.file === page.file &&
+              priorEntry.profile === page.profile &&
+              priorEntry.sha256 === page.hash;
+            return {
+              file: page.file,
+              profile: page.profile,
+              reviewedOn: unchanged ? priorEntry.reviewedOn : today,
+              sha256: page.hash,
+            };
+          })(),
+        ]),
+    ),
+    surfaces: Object.fromEntries(
+      surfaces.map((surface) => [
+        surface.id,
+        (() => {
+          const priorEntry = prior?.surfaces[surface.id];
+          const unchanged =
+            priorEntry?.file === surface.file &&
+            priorEntry.profile === surface.profile &&
+            priorEntry.sha256 === surface.hash;
+          return {
+            file: surface.file,
+            profile: surface.profile,
+            reviewedOn: unchanged ? priorEntry.reviewedOn : today,
+            sha256: surface.hash,
+          };
+        })(),
+      ]),
+    ),
+  };
+  await fs.promises.writeFile(
+    path.join(resolvedRoot, STYLE_BASELINE_FILE),
+    `${JSON.stringify(baseline, null, 2)}\n`,
+  );
+}
+
+async function runCli(): Promise<void> {
+  if (process.argv.includes("--update-baseline")) {
+    try {
+      await writeStyleBaseline();
+      console.log(
+        `Updated ${STYLE_BASELINE_FILE} after the completed human language-profile review.`,
+      );
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+    return;
+  }
+
+  const [ste100Issues, baselineIssues] = await Promise.all([
+    validateSte100(),
+    validateStyleBaseline(),
+  ]);
+  for (const issue of ste100Issues) {
+    console.error(`${issue.file}:${issue.line} — ${issue.message}`);
+  }
+  for (const issue of baselineIssues) {
+    console.error(`${issue.file} — ${issue.message}`);
+  }
+  if (ste100Issues.length + baselineIssues.length > 0) {
+    console.error(
+      `\nLanguage profile validation failed with ${
+        ste100Issues.length + baselineIssues.length
+      } issue(s).`,
+    );
+    process.exit(1);
+  }
+  console.log(
+    "All documentation pages pass mechanical STE100 checks, and all reviewed style hashes match.",
+  );
+}
+
+if (import.meta.main) {
+  await runCli();
+}
diff --git a/src/components/home/hero/HeroContent.tsx b/src/components/home/hero/HeroContent.tsx
index a60c8ae8..d4d655ce 100644
--- a/src/components/home/hero/HeroContent.tsx
+++ b/src/components/home/hero/HeroContent.tsx
@@ -17,31 +17,14 @@
 "use client";
 
 import Link from "next/link";
-import { useState } from "react";
 import { motion } from "framer-motion";
-import { ArrowRight, Check, Copy, Github } from "lucide-react";
+import { ArrowRight, Github } from "lucide-react";
 import { buttonVariants } from "@/components/ui/button";
 import { cn } from "@/lib/utils";
 
-const installCommand = "git clone https://github.com/GoodRxOSS/lifecycle";
 const easeOutQuart = [0.25, 1, 0.5, 1] as const;
 
-type CopyState = "idle" | "copied" | "failed";
-
 export function HeroContent() {
-  const [copyState, setCopyState] = useState<CopyState>("idle");
-
-  const handleCopy = async () => {
-    try {
-      await navigator.clipboard.writeText(installCommand);
-      setCopyState("copied");
-      setTimeout(() => setCopyState("idle"), 1800);
-    } catch {
-      setCopyState("failed");
-      setTimeout(() => setCopyState("idle"), 2400);
-    }
-  };
-
   return (
     <div className="mx-auto flex max-w-3xl flex-col items-start text-left motion-reduce:transition-none">
       <motion.div
@@ -78,68 +61,16 @@ export function HeroContent() {
         initial={{ opacity: 0, y: 12 }}
         animate={{ opacity: 1, y: 0 }}
         transition={{ duration: 0.6, ease: easeOutQuart, delay: 0.18 }}
-        className="mt-8 w-full max-w-xl"
-      >
-        <div className="flex items-stretch overflow-hidden rounded-md border border-border bg-muted/40 font-mono text-[13px]">
-          <span className="flex shrink-0 items-center px-3 text-muted-foreground">
-            $
-          </span>
-          <code className="flex-1 truncate py-2.5 pr-2 text-foreground">
-            {installCommand}
-          </code>
-          <button
-            type="button"
-            onClick={handleCopy}
-            aria-label={
-              copyState === "copied"
-                ? "Copied"
-                : copyState === "failed"
-                  ? "Copy failed"
-                  : "Copy install command"
-            }
-            className="flex shrink-0 items-center gap-1.5 border-l border-border px-3 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-0"
-          >
-            {copyState === "copied" ? (
-              <>
-                <Check className="h-3.5 w-3.5" aria-hidden="true" />
-                copied
-              </>
-            ) : (
-              <>
-                <Copy className="h-3.5 w-3.5" aria-hidden="true" />
-                copy
-              </>
-            )}
-          </button>
-        </div>
-        <p
-          role="status"
-          aria-live="polite"
-          className={cn(
-            "mt-2 kicker transition-opacity",
-            copyState === "failed"
-              ? "text-foreground/80 opacity-100"
-              : "opacity-0",
-          )}
-        >
-          {copyState === "failed" ? "copy blocked · use ⌘C / Ctrl+C" : " "}
-        </p>
-      </motion.div>
-
-      <motion.div
-        initial={{ opacity: 0, y: 12 }}
-        animate={{ opacity: 1, y: 0 }}
-        transition={{ duration: 0.6, ease: easeOutQuart, delay: 0.24 }}
-        className="mt-6 flex flex-col gap-3 sm:flex-row sm:items-center sm:gap-4"
+        className="mt-8 flex flex-col gap-3 sm:flex-row sm:items-center sm:gap-4"
       >
         <Link
-          href="/docs/getting-started/create-environment"
+          href="/docs"
           className={cn(
             buttonVariants({ size: "lg" }),
             "group h-11 px-6 text-base",
           )}
         >
-          Get started
+          Choose your path
           <ArrowRight
             className="ml-2 h-4 w-4 transition-transform duration-200 group-hover:translate-x-0.5 motion-reduce:transition-none"
             aria-hidden="true"
diff --git a/src/components/home/main/index.tsx b/src/components/home/main/index.tsx
index 779aa384..871300b1 100644
--- a/src/components/home/main/index.tsx
+++ b/src/components/home/main/index.tsx
@@ -46,7 +46,10 @@ export const Main = () => {
         </div>
       </header>
       <figure className="mt-6 flex md:mb-0 justify-center items-center md:w-[75%]">
-        <Iframe src="https://www.youtube.com/embed/ld9rWBPU3R8?si=1TTGy7cPhaqoF2Ev" />
+        <Iframe
+          src="https://www.youtube.com/embed/ld9rWBPU3R8?si=1TTGy7cPhaqoF2Ev"
+          title="Lifecycle product overview video"
+        />
       </figure>
     </>
   );
diff --git a/src/components/home/two-doors/index.tsx b/src/components/home/two-doors/index.tsx
index 3e9325d3..78479cdf 100644
--- a/src/components/home/two-doors/index.tsx
+++ b/src/components/home/two-doors/index.tsx
@@ -17,7 +17,7 @@
 "use client";
 
 import Link from "next/link";
-import { ArrowRight, BookOpen, Github } from "lucide-react";
+import { ArrowRight, CircleDot, Github } from "lucide-react";
 import { FaDiscord } from "react-icons/fa";
 import { motion, type Variants } from "framer-motion";
 import { buttonVariants } from "@/components/ui/button";
@@ -58,7 +58,7 @@ export function TwoDoors() {
             id="two-doors-heading"
             className="mt-3 text-headline text-foreground"
           >
-            Run it, or build it with us.
+            Evaluate it, or build it with us.
           </h2>
         </motion.header>
 
@@ -67,24 +67,24 @@ export function TwoDoors() {
             variants={blockVariants}
             className="flex flex-col bg-background p-7 sm:p-9"
           >
-            <p className="kicker text-muted-foreground">01 · run it</p>
+            <p className="kicker text-muted-foreground">01 · evaluate it</p>
             <h3 className="mt-3 text-2xl font-semibold tracking-tight text-foreground">
-              Get it running on a sample repo.
+              Evaluate Lifecycle safely.
             </h3>
             <p className="mt-3 max-w-md text-sm leading-relaxed text-muted-foreground">
-              Clone, follow the guide, watch your first pull request spin up its
-              own env in under ten minutes.
+              Compare the starter OpenTofu and existing-cluster Helm paths, then
+              review the security work required beyond evaluation.
             </p>
 
             <div className="mt-auto pt-7">
               <Link
-                href="/docs/getting-started/create-environment"
+                href="/docs/setup/install-lifecycle"
                 className={cn(
                   buttonVariants({ size: "lg" }),
                   "group h-11 px-6 text-base sm:w-auto",
                 )}
               >
-                Read the getting-started guide
+                Choose an installation path
                 <ArrowRight
                   className="ml-2 h-4 w-4 transition-transform duration-200 group-hover:translate-x-0.5"
                   aria-hidden="true"
@@ -118,9 +118,9 @@ export function TwoDoors() {
                   label: "Join the Discord",
                 },
                 {
-                  href: "https://github.com/GoodRxOSS/lifecycle/blob/main/CONTRIBUTING.md",
-                  icon: BookOpen,
-                  label: "Contributing guide",
+                  href: "https://github.com/GoodRxOSS/lifecycle/issues",
+                  icon: CircleDot,
+                  label: "Browse issues",
                 },
               ].map(({ href, icon: Icon, label }) => (
                 <li key={href}>
diff --git a/src/components/iframe/index.tsx b/src/components/iframe/index.tsx
index 07a86061..4ce5dafa 100644
--- a/src/components/iframe/index.tsx
+++ b/src/components/iframe/index.tsx
@@ -21,12 +21,16 @@ import { Loader } from "@/components";
 import { AspectRatio } from "@/components/ui/aspect-ratio";
 import { Card, CardContent } from "@/components/ui/card";
 import { IframeProps } from "@/components/iframe/types";
-export const Iframe = ({ src }: IframeProps) => {
+export const Iframe = ({ src, title }: IframeProps) => {
   return (
     <Card className="relative w-full my-8 border rounded-md pt-6 my-4">
       <CardContent>
         <AspectRatio ratio={16 / 9}>
-          <iframe src={src} className="absolute inset-0 h-full w-full" />
+          <iframe
+            src={src}
+            title={title}
+            className="absolute inset-0 h-full w-full"
+          />
         </AspectRatio>
       </CardContent>
     </Card>
diff --git a/src/components/iframe/types.ts b/src/components/iframe/types.ts
index e2867c0e..60e1779b 100644
--- a/src/components/iframe/types.ts
+++ b/src/components/iframe/types.ts
@@ -18,4 +18,5 @@ export type IframeProps = {
   border?: boolean;
   panelSize?: number;
   src: string;
+  title: string;
 };
diff --git a/src/components/image/index.tsx b/src/components/image/index.tsx
index 055ee4cb..3ad55491 100644
--- a/src/components/image/index.tsx
+++ b/src/components/image/index.tsx
@@ -24,7 +24,7 @@ import { ImageProps, DefinedImageProps } from "@/components/image/types";
 
 export const LifecycleDocsImg = ({
   src,
-  alt = "",
+  alt,
   border = true,
   ratio,
   width = 800,
@@ -48,7 +48,7 @@ export const LifecycleDocsImg = ({
 
 export const DefinedImage = ({
   src,
-  alt = "",
+  alt,
   width = 800,
   height = 500,
 }: DefinedImageProps) => {
diff --git a/src/components/image/types.ts b/src/components/image/types.ts
index f4c9eaa5..40db90cf 100644
--- a/src/components/image/types.ts
+++ b/src/components/image/types.ts
@@ -15,7 +15,7 @@
  */
 
 export type ImageProps = {
-  alt?: string;
+  alt: string;
   src: string;
   border?: boolean;
   ratio?: number;
@@ -24,7 +24,7 @@ export type ImageProps = {
 };
 
 export type DefinedImageProps = {
-  alt?: string;
+  alt: string;
   src: string;
   width?: number;
   height?: number;
diff --git a/src/components/tags/index.tsx b/src/components/tags/index.tsx
index 59ec1f35..14c2a96e 100644
--- a/src/components/tags/index.tsx
+++ b/src/components/tags/index.tsx
@@ -14,23 +14,20 @@
  * limitations under the License.
  */
 
-import { buttonVariants } from "@/components/ui/button";
-import Link from "next/link";
 import { TagsProps } from "@/components/tags/types";
 
 export const TagContent = ({ tags }: TagsProps) => {
   return (
-    <section>
+    <ul className="flex flex-wrap gap-2" aria-label="Page topics">
       {tags.map((tag) => (
-        <Link
+        <li
           key={tag}
-          className={`my-2 mr-4 rounded-md ${buttonVariants({ variant: "outline" })}`}
-          href={`/tags/${tag}`}
+          className="rounded-md border border-border px-2 py-1 text-xs text-muted-foreground"
         >
           {tag}
-        </Link>
+        </li>
       ))}
-    </section>
+    </ul>
   );
 };
 
diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx
index b9cb4a73..cfdede92 100644
--- a/src/pages/_app.tsx
+++ b/src/pages/_app.tsx
@@ -17,9 +17,7 @@
 import { useEffect, useState } from "react";
 import type { AppProps } from "next/app";
 import { IBM_Plex_Sans, JetBrains_Mono } from "next/font/google";
-import { useConfig } from "nextra-theme-docs";
 import { MotionConfig } from "framer-motion";
-import TagContent from "@/components/tags";
 import "../styles/globals.css";
 import "@xyflow/react/dist/style.css";
 
@@ -32,7 +30,6 @@ const jetbrainsMono = JetBrains_Mono({ subsets: ["latin"], display: "swap" });
 
 export default function App({ Component, pageProps }: AppProps) {
   const [isClient, setIsClient] = useState(false);
-  const { frontMatter } = useConfig();
 
   useEffect(() => {
     if (!isClient) return;
@@ -58,7 +55,6 @@ export default function App({ Component, pageProps }: AppProps) {
         }
       `}</style>
       <Component {...pageProps} />
-      {frontMatter?.tags?.length > 0 && <TagContent tags={frontMatter.tags} />}
     </MotionConfig>
   );
 }
diff --git a/src/pages/_meta.ts b/src/pages/_meta.ts
index 29881f57..342bdc7f 100644
--- a/src/pages/_meta.ts
+++ b/src/pages/_meta.ts
@@ -28,9 +28,5 @@ export default {
   "docs": {
     "title": "Docs",
     "type": "page"
-  },
-  "tags": {
-    "title": "Tags",
-    "type": "page"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/_meta.ts b/src/pages/docs/_meta.ts
index 4de5d8d9..6ebc7cf9 100644
--- a/src/pages/docs/_meta.ts
+++ b/src/pages/docs/_meta.ts
@@ -16,37 +16,49 @@
 
 export default {
   "index": {
-    "title": "What is Lifecycle?",
+    "title": "Lifecycle documentation",
     "display": "hidden"
   },
   "what-is-lifecycle": {
     "title": "What is Lifecycle?"
   },
-  "setup": {
-    "title": "Setup & Installation"
+  "getting-started": {
+    "title": "Getting started"
+  },
+  "features": {
+    "title": "Features"
   },
   "-": {
     "type": "separator"
   },
-  "getting-started": {
-    "title": "Getting Started"
+  "api-authentication": {
+    "title": "API authentication"
+  },
+  "api": {
+    "title": "HTTP API"
   },
   "schema": {
-    "title": "Schema Reference"
+    "title": "Lifecycle schema"
+  },
+  "reference": {
+    "title": "Reference"
   },
   "--": {
     "type": "separator"
   },
-  "features": {
-    "title": "Features"
+  "setup": {
+    "title": "Setup and installation"
   },
-  "tips": {
-    "title": "Tips"
+  "operations": {
+    "title": "Operations"
+  },
+  "releases": {
+    "title": "Releases and compatibility"
   },
   "troubleshooting": {
     "title": "Troubleshooting"
   },
-  "----": {
-    "type": "separator"
+  "tips": {
+    "title": "Tips"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/api-authentication/_meta.ts b/src/pages/docs/api-authentication/_meta.ts
new file mode 100644
index 00000000..c478e0fa
--- /dev/null
+++ b/src/pages/docs/api-authentication/_meta.ts
@@ -0,0 +1,24 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export default {
+  "overview": {
+    "title": "API authentication"
+  },
+  "api-keys": {
+    "title": "API keys"
+  }
+};
\ No newline at end of file
diff --git a/src/pages/docs/api-authentication/api-keys.mdx b/src/pages/docs/api-authentication/api-keys.mdx
new file mode 100644
index 00000000..0f0a4aad
--- /dev/null
+++ b/src/pages/docs/api-authentication/api-keys.mdx
@@ -0,0 +1,131 @@
+---
+title: API keys
+description: Create, scope, use, rotate, and revoke personal or service API keys for authenticated Lifecycle v2 requests.
+audience:
+  - api-user
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - api
+  - authentication
+  - api-keys
+  - security
+---
+
+import { Callout } from "nextra/components";
+
+API keys give scripts and integrations access with scope limits to Lifecycle's
+v2 API. Use a personal key for work attributable to one user and a service key
+for a shared automation identity.
+
+## Create a personal key
+
+1. Open **Settings**.
+2. Open **My API keys**.
+3. Enter a name that identifies the caller and purpose.
+4. Grant only the scopes necessary for the caller.
+5. Select **All repositories** or select up to 50 repositories.
+6. Select an explicit expiration.
+7. Create the key.
+8. Copy the key from the one-time result.
+9. Store the key in an approved secret manager.
+10. Close the result.
+
+Personal key values begin with `lfc_pat_`. Lifecycle shows the full value only
+at creation. By default, each user can have 10 active personal keys. An
+administrator can change this limit.
+
+If you reach the active key limit, revoke a previous key. Then, create the new
+key.
+
+Administrators use **Settings → API key management**:
+
+- Use **Service keys** to create or revoke automation identities.
+- Use **User keys** to examine or revoke personal keys.
+- Use **Access controls** to set authentication, issuance, scope policy,
+  repository policy, and rate limits.
+
+Service key values begin with `lfc_svc_`. Lifecycle reveals them only at
+creation.
+
+## Select scopes
+
+Lifecycle recognizes seven scopes:
+
+| Scope         | Access                                                              |
+| ------------- | ------------------------------------------------------------------- |
+| `env:read`    | Read Environments and Builds                                        |
+| `env:write`   | Create or change Environments and Builds. Also satisfies `env:read` |
+| `sites:read`  | Read sites. `sites:write` satisfies this scope.                     |
+| `sites:write` | Upload, replace, extend, or delete sites                            |
+| `repos:read`  | Read repository information. `repos:write` satisfies this scope.    |
+| `repos:write` | Change supported repository configuration                           |
+| `env:admin`   | Legacy/reserved Environment administration                          |
+
+New keys can request only the first six scopes. A legacy service key can keep
+`env:admin`. You cannot grant this scope to a new key.
+
+Write implies read only for the same resource. For example, `env:write` does not
+grant `sites:read`.
+
+<Callout type="warning">
+  **All repositories** is an explicit broad grant. Prefer a selected repository
+  list, especially for CI. An empty selected list does not mean all
+  repositories.
+</Callout>
+
+## Select an expiration
+
+The personal-key policy defaults to a 168-hour (7-day) selection and caps finite
+personal keys at 720 hours (30 days). An administrator can decrease the
+available UI options. The running deployment's policy controls the active key
+limit, available expirations, scopes, and repository constraints.
+
+If you do not send `ttlHours` and `expiresAt`, the API creates a non-expiring key.
+Omission does not mean the UI default. Always send or select an explicit finite
+expiration. An approved service-key policy can specify a different expiration.
+
+## Key check
+
+Use the v2 authentication context without exposing the key value:
+
+```bash
+curl --fail --silent --show-error \
+  --header "Authorization: Bearer ${LIFECYCLE_API_KEY}" \
+  "${LIFECYCLE_URL}/api/v2/auth/context"
+```
+
+Before you use the key in automation, make sure of its type, scopes, repository
+constraint, and expiry.
+
+Lifecycle applies a rate limit to API-key requests. The default limit is 600
+requests per minute. Lifecycle aggregates requests by key owner. An
+administrator can change the limit. Honor `Retry-After` on a `429` response.
+
+## Management routes
+
+| Purpose                     | Authenticated v2 route            |
+| --------------------------- | --------------------------------- |
+| My key policy               | `GET /api/v2/me/tokens/policy`    |
+| List or create my keys      | `GET` or `POST /api/v2/me/tokens` |
+| Revoke one of my keys       | `DELETE /api/v2/me/tokens/{id}`   |
+| List or create service keys | `GET` or `POST /api/v2/tokens`    |
+| Revoke a managed key        | `DELETE /api/v2/tokens/{id}`      |
+
+Personal management routes accept only the user's browser session. Service-key
+management routes accept only an administrator session. For request and
+response schemas, use the running deployment's generated API reference.
+
+## Rotate a key after exposure
+
+1. Create a replacement with the smallest scopes and repository set.
+2. Update the caller through its secret manager.
+3. Make sure that the replacement works with `/api/v2/auth/context`.
+4. Revoke the previous key.
+5. If you think that a key leaked, revoke it immediately.
+6. Tell an administrator to examine the API and key-management audit events.
+
+If the full key is not available, Lifecycle cannot show it. Create a
+replacement.
diff --git a/src/pages/docs/api-authentication/overview.mdx b/src/pages/docs/api-authentication/overview.mdx
new file mode 100644
index 00000000..39560344
--- /dev/null
+++ b/src/pages/docs/api-authentication/overview.mdx
@@ -0,0 +1,70 @@
+---
+title: API authentication
+description: Select a supported authentication method for Lifecycle v2 API requests and understand typical authorization failures.
+audience:
+  - api-user
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - api
+  - authentication
+  - security
+---
+
+import { Callout } from "nextra/components";
+
+Lifecycle's v2 API authenticates interactive users with an OIDC session and
+programmatic callers with API keys. Some routes accept only one of these
+methods.
+
+<Callout type="warning">
+  API keys operate only with deployment authentication. The operator must also
+  enable issuance and key authentication. Do not expose Lifecycle by turning
+  authentication off. See [Authentication](/docs/features/authentication) for
+  deployment security requirements.
+</Callout>
+
+## Select an authentication method
+
+| Caller                         | Method       | Use                                                   |
+| ------------------------------ | ------------ | ----------------------------------------------------- |
+| Browser UI                     | OIDC session | Interactive use and administrator-only session routes |
+| Script, CI job, or integration | API key      | Programmatic v2 routes allowed by the key's scopes    |
+
+An API key does not replace an administrator browser session. Some configuration
+routes accept only a session. Broad key scopes do not change this restriction.
+
+## Send an API key
+
+Store the key in your approved secret manager and send it as a bearer
+credential:
+
+```bash
+curl --fail --silent --show-error \
+  --header "Authorization: Bearer ${LIFECYCLE_API_KEY}" \
+  "${LIFECYCLE_URL}/api/v2/auth/context"
+```
+
+Do not print the environment variable, pass the key in a query string, commit it
+to a repository, or paste it into documentation.
+
+The authentication context reports how Lifecycle interpreted the caller. It
+reports resolved roles, scopes, and repository constraints. Use it as the first
+check after issuing or rotating a key.
+
+## Understand failures
+
+- `401 Unauthorized` means Lifecycle could not authenticate the credential. The
+  key can be missing, malformed, revoked, or expired. The policy can disable the
+  key.
+- `403 Forbidden` means Lifecycle recognized the credential, but the necessary
+  role, scope, repository access, or enabled feature is not available.
+- `429 Too Many Requests` means the key owner exceeded the configured API-key
+  rate limit. Honor `Retry-After`.
+
+Do not disable authentication for a `401`. Rotate or correct the credential.
+
+Continue with [API keys](/docs/api-authentication/api-keys) and [API
+overview](/docs/api/overview).
diff --git a/src/pages/docs/api/_meta.ts b/src/pages/docs/api/_meta.ts
new file mode 100644
index 00000000..ca588ec0
--- /dev/null
+++ b/src/pages/docs/api/_meta.ts
@@ -0,0 +1,21 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export default {
+  "overview": {
+    "title": "Lifecycle API overview"
+  }
+};
\ No newline at end of file
diff --git a/src/pages/docs/api/overview.mdx b/src/pages/docs/api/overview.mdx
new file mode 100644
index 00000000..9d3ad225
--- /dev/null
+++ b/src/pages/docs/api/overview.mdx
@@ -0,0 +1,105 @@
+---
+title: Lifecycle API overview
+description: Use the authenticated Lifecycle v2 API, read response envelopes, and make safe integrations.
+audience:
+  - api-user
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - api
+  - integration
+  - authentication
+---
+
+import { Callout } from "nextra/components";
+
+Lifecycle's supported integration surface is the authenticated v2 API at this
+path on your deployment:
+
+```text
+https://lifecycle.example.com/api/v2/
+```
+
+Use the API reference that the deployment generates:
+
+- `/v2/docs` — interactive API documentation
+- `/api/docs` — OpenAPI document
+
+These documents contain the methods and schemas for the running release.
+
+<Callout type="warning">
+  Do not build a new integration on `/api/v1`, expose legacy routes, or disable
+  authentication to make a request work. v1 is a legacy compatibility surface.
+  Use authenticated v2 routes.
+</Callout>
+
+## Authenticate
+
+Programmatic routes accept a Lifecycle API key when its scopes and repository
+constraint authorize the operation:
+
+```bash
+curl --fail --silent --show-error \
+  --header "Authorization: Bearer ${LIFECYCLE_API_KEY}" \
+  "${LIFECYCLE_URL}/api/v2/environments?page=1&limit=25"
+```
+
+Administrator and personal-settings routes can accept only an OIDC browser
+session. An API key cannot access these routes. Examine the operation's security
+declaration in the generated reference. See [API
+authentication](/docs/api-authentication/overview).
+
+## Read responses
+
+v2 success responses use a standard envelope:
+
+```json
+{
+  "request_id": "envi_8fb675af-3432-4c4e-8f0e-6a0434e50c64",
+  "data": {},
+  "error": null
+}
+```
+
+List responses can also include `metadata.pagination`. Errors keep `data` null
+and contain a stable machine-readable `error.code`:
+
+```json
+{
+  "request_id": "envi_8fb675af-3432-4c4e-8f0e-6a0434e50c64",
+  "data": null,
+  "error": {
+    "code": "forbidden_scope",
+    "message": "The API key does not grant the required scope."
+  }
+}
+```
+
+Log `request_id` with your integration's own operation ID. Branch on HTTP status
+and `error.code`, not the human-readable message.
+
+## Design a reliable caller
+
+- Use `page` and `limit` only as documented for that list operation.
+- Read the pagination metadata in the response.
+- Honor `Retry-After` after a `429` response.
+- Retry transient failures with bounded exponential backoff.
+- Do not retry validation or authorization failures without changing the
+  request or credential.
+- Send an `idempotencyKey` when you create an API Environment.
+- Use the same key again with the same caller and request to replay the existing
+  Environment.
+- A different request with the same key returns a conflict.
+- Do not log bearer credentials, request bodies containing secret values, or
+  one-time API-key creation responses.
+
+Only Environment creation supports idempotency. Treat a different write route
+as idempotent only if the generated reference says so.
+
+## Typical task guides
+
+- [Create and manage API Environments](/docs/features/api-environments)
+- [Create and scope API keys](/docs/api-authentication/api-keys)
+- [Manage sites](/docs/features/sites)
+- [Add build metadata links](/docs/features/build-metadata-links)
diff --git a/src/pages/docs/features/_meta.ts b/src/pages/docs/features/_meta.ts
index e3625e86..0248502e 100644
--- a/src/pages/docs/features/_meta.ts
+++ b/src/pages/docs/features/_meta.ts
@@ -19,7 +19,7 @@ export default {
     "title": "Authentication"
   },
   "auto-deployment": {
-    "title": "Auto Deploy & Labels"
+    "title": "Auto-deploy and labels"
   },
   "ignore-file-patterns": {
     "title": "Ignore File Patterns"
@@ -31,7 +31,7 @@ export default {
     "title": "Template Variables"
   },
   "build-metadata-links": {
-    "title": "Metadata Links"
+    "title": "Build metadata links"
   },
   "webhooks": {
     "title": "Webhooks"
@@ -40,27 +40,48 @@ export default {
     "title": "Service Dependencies"
   },
   "native-helm-deployment": {
-    "title": "Native Helm Deployment"
+    "title": "Native Helm deployment"
   },
   "secrets": {
-    "title": "Cloud Secrets"
+    "title": "Cloud secrets"
   },
   "environment-ttl": {
-    "title": "Environment TTL"
+    "title": "Environment expiration and cleanup"
+  },
+  "api-environments": {
+    "title": "API-created Environments"
+  },
+  "sites": {
+    "title": "Sites"
   },
   "ai-agent": {
-    "title": "AI Agent"
+    "title": "Lifecycle Agent"
   },
   "ai-agent-configuration": {
-    "title": "AI Agent Configuration"
+    "title": "Configure Lifecycle Agent"
+  },
+  "agent-sessions": {
+    "title": "Agent Sessions"
+  },
+  "agent-administration": {
+    "title": "Agent administration"
+  },
+  "workspace-backends": {
+    "title": "Agent workspace backends"
   },
   "mcp-integration": {
-    "title": "MCP Integration"
+    "title": "Connect external MCP servers"
   },
   "mcp-server": {
-    "title": "MCP Server"
+    "title": "Lifecycle MCP"
   },
   "cli": {
     "title": "CLI (lfc)"
+  },
+  "cli-telemetry": {
+    "title": "Lifecycle CLI telemetry"
+  },
+  "lifecycle-ui": {
+    "title": "Use the Lifecycle UI"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/features/agent-administration.mdx b/src/pages/docs/features/agent-administration.mdx
new file mode 100644
index 00000000..b74912fe
--- /dev/null
+++ b/src/pages/docs/features/agent-administration.mdx
@@ -0,0 +1,112 @@
+---
+title: Agent administration
+description: Administer Lifecycle Agent availability, models, instructions, permissions, tools, workspaces, and session audit.
+audience:
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - ai
+  - agent
+  - administration
+  - security
+---
+
+import { Callout } from "nextra/components";
+
+**Agent administration** controls Lifecycle Agent and Agent Sessions.
+Restrictive global settings provide the starting policy. Repository settings
+can supply necessary differences.
+
+<Callout type="info">
+  Agent administration is available only to Lifecycle administrators. If the
+  section is missing, ask the deployment owner if Agent Sessions is available.
+</Callout>
+
+## Find the right section
+
+| Section                       | Use it to                                                             |
+| ----------------------------- | --------------------------------------------------------------------- |
+| **Availability & models**     | Configure Agent availability, providers, allowed models, and defaults |
+| **Instructions & run limits** | Set administrator guidance and bound agent iterations                 |
+| **Permissions & approvals**   | Allow, require approval for, or deny action categories                |
+| **Tools & integrations**      | Control built-in tools and shared MCP servers                         |
+| **Agent workspaces**          | Configure workspace behavior and cleanup                              |
+| **Runtime backends**          | Configure workspace provider connections, tests, and activation       |
+| **Safety lists**              | Exclude tools or paths and constrain file writes                      |
+| **Session review**            | Examine session, run, tool, approval, and usage history               |
+
+Personal settings are in different sections:
+
+- Use **My connections** for your provider keys and tool sign-ins.
+- When policy permits custom Agent definitions, use **My agents** to manage
+  them.
+
+## Make a safe change
+
+1. Select the intended scope: **Global** or one repository.
+2. Record the current behavior.
+3. Change one policy subject.
+4. Use prompt preview or the section's test action.
+5. Save the change.
+6. Start a new session as a representative non-admin user.
+7. Do an allowed action, an approval-required action, and a denied action.
+8. Before you expand the change, examine the session record.
+
+Repository settings combine with global settings. Examine the combined result
+because a repository setting can make the policy less restrictive.
+
+## Use least privilege
+
+- Offer only models approved for the data users will send.
+- Allow read-only tools first.
+- Require approval for workspace writes, shell commands, Git changes, network
+  access, Kubernetes mutations, and external writes.
+- Only if an approved workflow makes it necessary, apply a less restrictive
+  policy.
+- Deny capabilities that are not necessary for the workflow.
+- Constrain repository and file writes.
+- Limit custom Agent creation until an owner and an approval procedure are
+  available.
+- After you change a shared MCP server, examine the tools in a test session.
+
+<Callout type="warning">
+  Agent instructions are guidance, not a security boundary. Enforce security
+  with authenticated routes, tool capability policy, approval policy, workspace
+  isolation, repository constraints, and provider controls.
+</Callout>
+
+## Examine sessions
+
+Use **Session review** to find:
+
+- the user who started the session
+- the target repository, Environment, or workspace
+- the selected model and Agent definition
+- tool results and approval results
+- the current workspace status
+
+Tool input and output can contain sensitive data. Give access to **Session
+review** only to administrators with a support or security task. Follow your
+organization's retention policy.
+
+## Related configuration
+
+- [Configure Lifecycle Agent](/docs/features/ai-agent-configuration) covers
+  instructions, overrides, and approval semantics.
+- [MCP integration](/docs/features/mcp-integration) covers shared servers and
+  personal connections.
+- [Workspace backends](/docs/features/workspace-backends) covers provider
+  activation and tests.
+- [Agent Sessions](/docs/features/agent-sessions) shows the user workflow that
+  you must test.
+
+## Roll back
+
+If a change behaves unexpectedly, complete these steps:
+
+1. Disable the affected capability or restore the prior policy.
+2. Examine active sessions that can still use the previous settings.
+3. Start a new session to make sure that the rollback works.
+4. Keep related request IDs and session information for investigation.
diff --git a/src/pages/docs/features/agent-sessions.mdx b/src/pages/docs/features/agent-sessions.mdx
new file mode 100644
index 00000000..426ee591
--- /dev/null
+++ b/src/pages/docs/features/agent-sessions.mdx
@@ -0,0 +1,126 @@
+---
+title: Agent Sessions
+description: Start, examine, and continue repository work with Lifecycle Agent in an isolated workspace.
+audience:
+  - agent-user
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - ai
+  - agent
+  - sessions
+  - workspaces
+---
+
+import { Callout } from "nextra/components";
+
+Agent Sessions keep a conversation for repository work. A session can also open
+an isolated workspace. You can suspend, resume, or release the workspace.
+
+<Callout type="info">
+  Agent Sessions is a Labs feature. If **New Chat**, **Sessions**, or **My
+  agents** is missing, ask an administrator if the feature is available.
+</Callout>
+
+## Start a session
+
+1. Open **New Chat**.
+2. Select the built-in Agent or an available custom Agent.
+3. When more than one model is available, select a model.
+4. Examine optional tool and MCP selections.
+5. Give the task, repository, branch, and necessary outcome.
+6. Before work begins, examine the resolved repository or Environment context.
+
+A session can start without a workspace. The Agent can start a workspace when
+the task needs repository files or commands.
+
+Good first messages set a boundary:
+
+```text
+Investigate why the checkout service test fails on feature/retry-policy.
+Give the evidence first. Do not modify files until I approve the plan.
+```
+
+## Follow the run
+
+The session shows messages, tool calls, workspace state, and pending approval.
+Tool information is evidence. Before you accept a result or change, examine the
+tool information.
+
+When an action needs approval:
+
+1. Read the full command, file change, network request, or external operation.
+2. Make sure of the repository and workspace target.
+3. Approve only that action, or deny it with corrective feedback.
+4. When you understand its scope, use **Always allow ... in this chat** only
+   with administrator permission.
+
+<Callout type="warning">
+  Lifecycle can send repository content and prompts to the configured model
+  provider. When selected, external MCP or workspace providers also receive this
+  data. Do not include credentials or data that those providers are not approved
+  to process.
+</Callout>
+
+## Use the workspace
+
+Depending on the active [workspace
+backend](/docs/features/workspace-backends), a session can offer:
+
+- **Open editor**
+- authenticated preview ports
+- suspend and resume
+- **Keep workspace**
+- **Release workspace**
+
+For a suspended workspace, the session shows when Lifecycle can reclaim it
+automatically. Automatic reclamation can discard uncommitted files. Select
+**Keep workspace** to prevent automatic reclamation. A kept workspace can still
+suspend and resume.
+
+When you select **Release workspace**, Lifecycle stops its processes and
+discards its files. The conversation stays, and a new task can start a new
+workspace. Before release, commit wanted changes or keep them in a different
+approved system.
+
+## Continue and examine sessions
+
+Open **Sessions** to search recent or archived work and resume a conversation.
+Before continuing a previous session:
+
+- reread its repository and branch context
+- find whether its workspace continues to be the same one
+- examine pending or failed actions
+- state the changed goal
+
+When prior context must not influence the next task, select **Reset
+conversation**.
+
+## Custom Agents and connections
+
+**My agents** contains user-created Agent definitions when policy allows
+creation.
+An administrator can disable custom Agents, limit them to administrators, or
+use an allowlist.
+
+Manage personal model or MCP connections in **Settings → My connections**.
+After a connection change, start a new run. Make sure that the expected tools
+are available.
+
+## Environment-scoped investigations
+
+For a failure tied to one Lifecycle Environment, the Agent panel on that
+Environment's details page selects the Build context. See
+[Lifecycle Agent](/docs/features/ai-agent). Use Agent Sessions for broader
+repository work that benefits from a dedicated workspace.
+
+## Troubleshooting
+
+- **No model is available:** an administrator must enable a provider and model.
+- **Workspace setup fails:** Examine the displayed stage. An administrator
+  must test the active backend.
+- **A tool is unavailable:** Examine the selected Agent, personal connection,
+  and combined repository policy.
+- **An action does not continue:** Resolve its approval or deny it with
+  feedback. Do not send duplicate write actions.
diff --git a/src/pages/docs/features/ai-agent-configuration.mdx b/src/pages/docs/features/ai-agent-configuration.mdx
index dc73a154..762e2d11 100644
--- a/src/pages/docs/features/ai-agent-configuration.mdx
+++ b/src/pages/docs/features/ai-agent-configuration.mdx
@@ -1,512 +1,119 @@
 ---
-title: AI Agent Configuration
+title: Configure Lifecycle Agent
+description: Configure models, instructions, tools, approvals, and repository overrides for Lifecycle Agent from Settings.
+audience:
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - ai
   - agent
-  - configuration
-  - admin
-  - api
+  - administration
+  - settings
 ---
 
 import { Callout } from "nextra/components";
 
-The AI Agent configuration system gives administrators fine-grained control over agent behavior at two levels: **global defaults** that apply to all repositories, and **per-repository overrides** for specific projects. All configuration is managed through REST API endpoints.
+Lifecycle administrators configure Agent behavior in **Settings**. Start with a
+small global policy. Preview the combined instructions. Add repository
+overrides only where they are necessary.
 
 <Callout type="info">
-  For an overview of the AI Agent itself, see [AI
-  Agent](/docs/features/ai-agent). To extend the agent with external tools, see
-  [MCP Integration](/docs/features/mcp-integration).
+  Agent administration is available only to Lifecycle administrators. If these
+  settings are missing, ask the deployment owner if Agent Sessions is available.
 </Callout>
 
-## Configuration hierarchy
+## Before you start
 
-Global defaults live in the Lifecycle `global_config` table under the `aiAgent` key. Per-repository overrides are stored in the `ai_agent_repo_config` table and merged on top of global defaults at runtime.
+These items are necessary:
 
-### Fields
+- Lifecycle administrator access
+- At least one model provider configured by the deployment owner
+- A test repository and nonproduction Environment
+- Agreement on which actions need approval
 
-| Field                              | Type               | Default                               | Description                                                                    |
-| ---------------------------------- | ------------------ | ------------------------------------- | ------------------------------------------------------------------------------ |
-| `enabled`                          | `boolean`          | `false`                               | Whether the AI Agent is available                                              |
-| `maxMessagesPerSession`            | `number`           | `50`                                  | Maximum messages per chat session                                              |
-| `sessionTTL`                       | `number`           | `3600`                                | Session time-to-live in seconds                                                |
-| `providers`                        | `ProviderConfig[]` | `[]`                                  | LLM provider configurations (global only)                                      |
-| `additiveRules`                    | `string[]`         | `[]`                                  | Extra rules appended to the system prompt                                      |
-| `systemPromptOverride`             | `string`           | `undefined`                           | Full replacement for the system prompt                                         |
-| `excludedTools`                    | `string[]`         | `[]`                                  | Tools the agent cannot use                                                     |
-| `excludedFilePatterns`             | `string[]`         | `[]`                                  | Glob patterns for files the agent cannot access                                |
-| `allowedWritePatterns`             | `string[]`         | `["lifecycle.yaml", "lifecycle.yml"]` | Glob patterns for additional file paths the agent is allowed to write to       |
-| `maxIterations`                    | `number`           | `20`                                  | Maximum orchestration loop iterations (global only)                            |
-| `maxToolCalls`                     | `number`           | `50`                                  | Maximum total tool calls per query (global only)                               |
-| `maxRepeatedCalls`                 | `number`           | `1`                                   | Maximum repeated calls with same arguments before loop detection (global only) |
-| `compressionThreshold`             | `number`           | `80000`                               | Token count before conversation history is compressed (global only)            |
-| `observationMaskingRecencyWindow`  | `number`           | `3`                                   | Number of recent tool results preserved when masking (global only)             |
-| `observationMaskingTokenThreshold` | `number`           | `25000`                               | Token count before observation masking activates (global only)                 |
-| `toolExecutionTimeout`             | `number`           | `30000`                               | Tool execution timeout in milliseconds (global only)                           |
-| `toolOutputMaxChars`               | `number`           | `30000`                               | Maximum characters in tool output before truncation (global only)              |
-| `retryBudget`                      | `number`           | `10`                                  | Maximum retry attempts per query on provider errors (global only)              |
+Keep provider credentials in the approved deployment secret store. Do not put
+credentials in Agent instructions, chats, or repositories.
 
-### How merging works
+## Configure the global policy
 
-When a repository has an override, the effective configuration is computed by merging the override on top of global defaults:
+Open **Settings**. Examine each Agent section:
 
-- **Scalar fields** (`enabled`, `maxMessagesPerSession`, `sessionTTL`, `systemPromptOverride`) — the repository value replaces the global value.
-- **Array fields** (`additiveRules`, `excludedTools`, `excludedFilePatterns`, `allowedWritePatterns`) — repository values are **appended** to global values. Duplicates are removed automatically.
+| Section                       | What it controls                                                  |
+| ----------------------------- | ----------------------------------------------------------------- |
+| **Availability & models**     | If Agent is available and which models users can select           |
+| **Instructions & run limits** | Administrator guidance and the maximum number of agent iterations |
+| **Permissions & approvals**   | Which classes of action run, require approval, or are denied      |
+| **Tools & integrations**      | Built-in tool availability and shared MCP servers                 |
+| **Agent workspaces**          | Workspace behavior and lifecycle                                  |
+| **Runtime backends**          | Where new Agent workspaces run                                    |
+| **Safety lists**              | Excluded tools and paths, plus allowed write paths                |
+| **Session review**            | Audit records for Agent sessions                                  |
 
-Here's a concrete example. Say your global config looks like this:
+Save one section at a time. Use a test session to make sure that each result is
+correct. A new session clearly shows the changed instructions or policy.
 
-```json
-{
-  "enabled": true,
-  "maxMessagesPerSession": 50,
-  "excludedTools": ["patch_k8s_resource"], // blocked org-wide
-  "additiveRules": ["Always confirm before scaling."]
-}
-```
+## Add instructions for one repository
 
-And `myorg/frontend` has this override:
-
-```json
-{
-  "maxMessagesPerSession": 100, // raises the limit
-  "excludedTools": ["update_github_file"], // blocked for this repo only
-  "additiveRules": ["Prefer CSS fixes over JS."] // repo-specific rule
-}
-```
-
-The effective config for `myorg/frontend`:
-
-```json
-{
-  "enabled": true, // inherited
-  "maxMessagesPerSession": 100, // replaced
-  "excludedTools": ["patch_k8s_resource", "update_github_file"], // combined
-  "additiveRules": [
-    "Always confirm before scaling.",
-    "Prefer CSS fixes over JS."
-  ] // combined
-}
-```
-
-### Provider and model configuration
-
-The `providers` field defines which LLM providers and models are available. This is a **global-only** field — repository overrides cannot change provider configuration.
-
-Each provider entry has the following structure:
-
-| Field          | Type            | Required | Description                                           |
-| -------------- | --------------- | -------- | ----------------------------------------------------- |
-| `name`         | `string`        | Yes      | Provider identifier (`anthropic`, `openai`, `gemini`) |
-| `enabled`      | `boolean`       | Yes      | Whether this provider is available                    |
-| `apiKeyEnvVar` | `string`        | Yes      | Environment variable containing the API key           |
-| `models`       | `ModelConfig[]` | Yes      | List of models for this provider                      |
-
-Each model entry:
-
-| Field                  | Type      | Required | Description                                                     |
-| ---------------------- | --------- | -------- | --------------------------------------------------------------- |
-| `id`                   | `string`  | Yes      | Model identifier sent to the provider API                       |
-| `displayName`          | `string`  | Yes      | Human-readable name shown in the UI dropdown                    |
-| `enabled`              | `boolean` | Yes      | Whether this model is selectable                                |
-| `default`              | `boolean` | Yes      | Whether this is the default model (one per provider)            |
-| `maxTokens`            | `integer` | Yes      | Maximum output tokens for the model                             |
-| `inputCostPerMillion`  | `number`  | No       | Cost per 1M input tokens (USD). Enables cost display in the UI  |
-| `outputCostPerMillion` | `number`  | No       | Cost per 1M output tokens (USD). Enables cost display in the UI |
-
-<Callout type="info">
-  When `inputCostPerMillion` and `outputCostPerMillion` are both set for a
-  model, the UI displays a computed cost alongside token counts in the X-Ray
-  debug panel. If either field is omitted, cost is not shown.
-</Callout>
-
-Example with pricing configured:
-
-```json
-{
-  "providers": [
-    {
-      "name": "anthropic",
-      "enabled": true,
-      "apiKeyEnvVar": "ANTHROPIC_API_KEY",
-      "models": [
-        {
-          "id": "claude-sonnet-4-20250514",
-          "displayName": "Claude Sonnet",
-          "enabled": true,
-          "default": true,
-          "maxTokens": 8096,
-          "inputCostPerMillion": 3.0,
-          "outputCostPerMillion": 15.0
-        }
-      ]
-    },
-    {
-      "name": "gemini",
-      "enabled": true,
-      "apiKeyEnvVar": "GEMINI_API_KEY",
-      "models": [
-        {
-          "id": "gemini-2.5-pro-preview-05-06",
-          "displayName": "Gemini 2.5 Pro",
-          "enabled": true,
-          "default": true,
-          "maxTokens": 65536,
-          "inputCostPerMillion": 1.25,
-          "outputCostPerMillion": 10.0
-        }
-      ]
-    }
-  ]
-}
-```
-
-### Caching
-
-<Callout type="info">
-  Configurations are cached at three layers: in-memory (30 seconds), Redis (5
-  minutes), and the database (source of truth). Updating via the API immediately
-  invalidates both the Redis and in-memory caches for that repository.
-</Callout>
-
----
-
-## Prompt customization
-
-### Additive rules
-
-The `additiveRules` field accepts an array of strings appended to the system prompt. Use this to add organization-specific guidelines, restrict behaviors, or provide extra context.
-
-Because additive rules use **additive merge**, global rules and repository rules are combined. Set organization-wide rules globally and layer project-specific rules per repository.
-
-```json
-{
-  "additiveRules": [
-    "Always check pod resource limits before suggesting scaling changes.",
-    "Prefer rolling restarts over full redeployments."
-  ]
-}
-```
-
-### System prompt override
-
-The `systemPromptOverride` field replaces the entire default system prompt. This is a **full replacement**, not additive.
+Repository settings combine with the global policy. Before you save, use the
+preview to examine the final instructions and policy.
 
 <Callout type="warning">
-  Setting `systemPromptOverride` replaces the entire built-in system prompt,
-  including safety instructions. Use this only when you need complete control
-  over the agent's behavior. Maximum length is **50,000 characters**.
-</Callout>
-
-When set at the repository level, the override applies only to that repository. The scalar merge rule means the repository value fully replaces any global override.
-
----
-
-## Access control
-
-### Excluded tools
-
-The `excludedTools` field prevents the agent from using specific tools. This is useful for restricting write operations in sensitive repositories.
-
-Available tool names:
-
-- `get_k8s_resources`
-- `get_lifecycle_logs`
-- `patch_k8s_resource`
-- `query_database`
-- `get_github_file`
-- `list_github_directory`
-- `update_github_file`
-- `get_issue_comment`
-
-<Callout type="warning">
-  `query_database` is a **core tool** and cannot be excluded. Attempting to
-  exclude it returns a `400` error.
-</Callout>
-
-Because excluded tools use additive merge, tools excluded at the global level cannot be "un-excluded" at the repository level.
-
-### Excluded file patterns
-
-The `excludedFilePatterns` field accepts glob patterns that restrict which files the agent can access through the GitHub tools.
-
-**Validation rules:**
-
-| Rule                       | Limit                                  |
-| -------------------------- | -------------------------------------- |
-| Maximum number of patterns | 50                                     |
-| Maximum pattern length     | 200 characters                         |
-| Forbidden patterns         | `*`, `**`, `**/*` (overly broad)       |
-| Path traversal             | `../` is not allowed                   |
-| Absolute paths             | Patterns starting with `/` not allowed |
-
-```json
-{
-  "excludedFilePatterns": [
-    "*.env", // environment files
-    "secrets/**", // secrets directory
-    "config/production.*" // production configs
-  ]
-}
-```
-
-Like other array fields, file patterns use additive merge. Global patterns and repository patterns are combined and deduplicated.
-
-### Allowed write patterns
-
-The `allowedWritePatterns` field controls which file paths the agent is permitted to modify through the `update_file` tool. By default, the agent can only write to `lifecycle.yaml` and `lifecycle.yml` (plus any files explicitly referenced in the lifecycle configuration such as Dockerfiles and Helm value files).
-
-To allow the agent to modify additional files, add glob patterns to this field. For example, to allow modifications to Helm charts, Dockerfiles, and Ansible playbooks:
-
-```json
-{
-  "allowedWritePatterns": [
-    "lifecycle.yaml",
-    "lifecycle.yml",
-    "helm/**/*.{yaml,yml}",
-    "sysops/helm/**/*.{yaml,yml}",
-    "sysops/dockerfiles/**/*.dockerfile",
-    "sysops/ansible/**/*.{yaml,yml}"
-  ]
-}
-```
-
-<Callout type="warning">
-  Setting `allowedWritePatterns` at the global or repository level defines the
-  full set of writable paths (in addition to files referenced in the lifecycle
-  config). Keep the list minimal to limit the blast radius of agent changes.
-</Callout>
-
-Like other array fields, allowed write patterns use additive merge. Global patterns and repository patterns are combined and deduplicated.
-
----
-
-## Orchestration limits
-
-These fields control the agent's internal behavior. They are all **global-only** settings — repository overrides cannot change them. If omitted, the defaults below are used.
-
-### Loop protection
-
-Controls for the agent's tool-calling loop that prevent runaway behavior.
-
-| Field              | Default | Description                                                                                         |
-| ------------------ | ------- | --------------------------------------------------------------------------------------------------- |
-| `maxIterations`    | `20`    | Maximum number of LLM round-trips in a single query. Prevents runaway conversations.                |
-| `maxToolCalls`     | `50`    | Maximum total tool invocations across all iterations. Caps resource usage for broad investigations. |
-| `maxRepeatedCalls` | `1`     | How many times the same tool can be called with identical arguments before loop detection kicks in. |
-
-When a limit is hit, the agent stops and returns an error message to the user explaining what happened.
-
-### Context management
-
-Controls how the agent manages conversation context to stay within LLM token limits.
-
-| Field                              | Default | Description                                                                                                                               |
-| ---------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `compressionThreshold`             | `80000` | Token count at which the conversation history is summarized into a compact form. Higher values preserve more context but use more tokens. |
-| `observationMaskingRecencyWindow`  | `3`     | Number of recent tool results kept in full when masking older observations. Older results are replaced with placeholders.                 |
-| `observationMaskingTokenThreshold` | `25000` | Token count at which observation masking activates. Below this threshold, all tool results are kept in full.                              |
-
-### Tool execution
-
-Controls for tool execution behavior and output handling.
-
-| Field                  | Default | Description                                                                                                                     |
-| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `toolExecutionTimeout` | `30000` | Maximum time in milliseconds a single tool call can run before being terminated. Increase for slow K8s clusters or MCP servers. |
-| `toolOutputMaxChars`   | `30000` | Maximum characters in a tool's output before truncation. Larger values give the agent more data but cost more tokens.           |
-
-### Resilience
-
-Controls for error recovery when communicating with LLM providers.
-
-| Field         | Default | Description                                                                                                                                |
-| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `retryBudget` | `10`    | Maximum retry attempts per query when the LLM provider returns transient errors. Higher values improve reliability at the cost of latency. |
-
-```json
-{
-  "maxIterations": 30,
-  "maxToolCalls": 80,
-  "maxRepeatedCalls": 2,
-  "compressionThreshold": 100000,
-  "observationMaskingRecencyWindow": 5,
-  "observationMaskingTokenThreshold": 40000,
-  "toolExecutionTimeout": 60000,
-  "toolOutputMaxChars": 50000,
-  "retryBudget": 15
-}
-```
-
-<Callout type="info">
-  Increasing these limits allows the agent to perform deeper investigations but
-  consumes more LLM tokens. Lower values are safer for cost control.
+  A repository override can make the combined policy more permissive. Preview
+  the merged result. Test the merged result.
 </Callout>
 
----
-
-## Managing configuration via API
-
-All endpoints are under `/api/v2/ai/agent-config`. Request and response bodies use JSON.
-
-### Global configuration
-
-**Get the current global config:**
-
-```
-GET /api/v2/ai/agent-config
-```
+## Preview combined instructions
 
-```json
-{
-  "status": "success",
-  "data": {
-    "enabled": true,
-    "providers": [],
-    "maxMessagesPerSession": 50,
-    "sessionTTL": 3600,
-    "additiveRules": [],
-    "excludedTools": [],
-    "excludedFilePatterns": [],
-    "allowedWritePatterns": ["lifecycle.yaml", "lifecycle.yml"]
-  }
-}
-```
+Use the prompt preview to examine the instruction order. Check the
+administrator instructions, global rules, repository rules, and added guidance.
 
-**Update the global config:**
+The preview does not include session-dependent tools, skills, or runtime
+context. Use a test session to make sure that those parts operate correctly.
 
-```
-PUT /api/v2/ai/agent-config
-```
-
-```json
-{
-  "enabled": true,
-  "providers": [],
-  "maxMessagesPerSession": 100, // raise the session limit
-  "sessionTTL": 7200 // 2 hours
-}
-```
-
-Returns the updated configuration on success. Returns `400` for validation failures (invalid schema, prompt too long, core tool exclusion, bad file patterns).
-
----
-
-### Repository overrides
-
-**List all repository overrides:**
-
-```
-GET /api/v2/ai/agent-config/repos
-```
-
-```json
-{
-  "status": "success",
-  "data": [
-    {
-      "id": 1,
-      "repositoryFullName": "myorg/myrepo",
-      "config": {
-        "enabled": false,
-        "excludedTools": ["patch_k8s_resource"]
-      },
-      "createdAt": "2025-01-15T10:00:00.000Z",
-      "updatedAt": "2025-01-15T10:00:00.000Z"
-    }
-  ]
-}
-```
-
-**Get a single repository override:**
-
-```
-GET /api/v2/ai/agent-config/repos/{owner}/{repo}
-```
-
-Returns only the override fields, not the merged result. Returns `404` if no override exists.
-
-**Get the effective (merged) configuration:**
-
-```
-GET /api/v2/ai/agent-config/repos/{owner}/{repo}/effective
-```
-
-```json
-{
-  "status": "success",
-  "data": {
-    "repoFullName": "myorg/myrepo",
-    "effectiveConfig": {
-      "enabled": false,
-      "providers": [],
-      "maxMessagesPerSession": 50,
-      "sessionTTL": 3600,
-      "additiveRules": [],
-      "excludedTools": ["patch_k8s_resource"], // merged from global + repo
-      "excludedFilePatterns": [],
-      "allowedWritePatterns": ["lifecycle.yaml", "lifecycle.yml"]
-    }
-  }
-}
-```
-
-<Callout type="tip">
-  Use the `/effective` endpoint to verify exactly what configuration a
-  repository uses at runtime, after merge.
-</Callout>
-
-**Create or update a repository override:**
-
-```
-PUT /api/v2/ai/agent-config/repos/{owner}/{repo}
-```
-
-Uses upsert semantics. Only include the fields you want to override.
-
-```json
-{
-  "enabled": false,
-  "excludedTools": ["patch_k8s_resource", "update_github_file"],
-  "additiveRules": ["Do not restart pods without explicit user confirmation."]
-}
-```
-
-Returns the saved override on success. Returns `400` for validation failures.
-
-**Delete a repository override:**
-
-```
-DELETE /api/v2/ai/agent-config/repos/{owner}/{repo}
-```
-
-Soft-deletes the override. The repository reverts to global defaults.
-
----
+## Set approval policy
 
-## Troubleshooting
+Each action category can be:
 
-### Config changes not taking effect
+- `allow` — run without a person approving it
+- `require_approval` — pause and show the full action
+- `deny` — do not offer or run the action
 
-Configuration is cached at multiple layers. The API automatically invalidates caches on update, but if you changed the database directly, you may need to wait:
+Categories include read operations, external MCP reads, workspace writes, shell
+execution, Git writes, network access, Kubernetes mutations, and external MCP
+writes. Allow read operations first. Require approval for consequential
+actions. Deny actions that are not necessary for users.
 
-- **In-memory cache** — expires after 30 seconds
-- **Redis cache** — expires after 5 minutes
+Capabilities can be available to users, reserved for administrators or the
+system, or disabled. You can also limit custom Agent creation.
 
-Use the `/effective` endpoint to confirm what the agent sees.
+## Configure MCP and workspace backends
 
-### Cannot exclude a core tool
+- Use [MCP integration](/docs/features/mcp-integration) to add shared tools.
+- Let users complete their own connection fields.
+- Use [Workspace backends](/docs/features/workspace-backends) to select where
+  new workspace-backed sessions run.
 
-`query_database` is required for agent operation. If you include it in `excludedTools`, the API returns:
+After a backend change, start a test session and verify a new workspace.
 
-```
-Cannot exclude core tool: "query_database". Core tools are required for agent operation.
-```
+## Configuration API
 
-Remove it from your exclusion list.
+Use **Settings** for interactive administration. For automation, use the
+authenticated v2 routes in the deployment API reference:
 
-### Excluded tool still being used
+- `GET`, `PUT`, or `PATCH /api/v2/ai/agent/runtime-config`
+- repository runtime configuration below
+  `/api/v2/ai/agent/runtime-config/repos/`
+- instruction rules, templates, and prompt preview below
+  `/api/v2/ai/admin/agent/`
 
-Array fields use **additive merge**. If you removed a tool from a repository override but it's still excluded, check the global config — the tool may be excluded there. Global exclusions cannot be overridden at the repo level.
+See [API overview](/docs/api/overview) for authentication and discovery.
 
-### System prompt override not working as expected
+## Change check
 
-`systemPromptOverride` **completely replaces** the built-in prompt, including safety instructions and tool usage guidelines. If the agent behaves unexpectedly, try `additiveRules` instead — it appends to the default prompt rather than replacing it.
+1. Preview the combined global and repository instructions.
+2. Start a new Agent session as a representative user.
+3. Make sure that the intended model and tools are available.
+4. Do one read, one approval-required action, and one denied action.
+5. Before you expand access, examine the session audit.
diff --git a/src/pages/docs/features/ai-agent.mdx b/src/pages/docs/features/ai-agent.mdx
index 5231fe7f..699780cc 100644
--- a/src/pages/docs/features/ai-agent.mdx
+++ b/src/pages/docs/features/ai-agent.mdx
@@ -1,151 +1,102 @@
 ---
-title: AI Agent
+title: Lifecycle Agent
+description: Investigate a Lifecycle Environment, examine evidence, and do approved recovery tasks from the Environment details page.
+audience:
+  - agent-user
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - ai
   - agent
   - debugging
-  - investigation
-  - llm
+  - environments
 ---
 
 import { Callout } from "nextra/components";
 
-The **AI Agent** is an interactive assistant built into Lifecycle that helps you debug and investigate issues in your ephemeral environments. It inspects Kubernetes resources, reads pod logs, queries the Lifecycle database, browses your GitHub repository, and can apply fixes directly.
+Lifecycle Agent helps you investigate and recover an Environment without leaving
+its details page. It starts with the build and namespace in context, then uses
+the tools your administrator has allowed.
 
 <Callout type="info">
-  An administrator must enable the AI Agent before you can use it. If the
-  feature is not enabled, you see an **"AI Agent Not Enabled"** message with a
-  prompt to contact your administrator. See [AI Agent
-  Configuration](/docs/features/ai-agent-configuration) for setup details.
+  Lifecycle Agent is an administrator-controlled feature. The Agent panel and
+  available models or actions can be different for each deployment and
+  repository.
 </Callout>
 
-## Accessing the agent
+## Investigate an Environment
 
-Navigate to the AI Agent from any build's detail view:
+1. Open **Environments**.
+2. Select the Environment that you want to investigate.
+3. Open **Lifecycle Agent** from the Environment details page.
+4. Select **Diagnose failure**, **Repair**, or enter a focused question.
+5. Examine the agent's explanation and the evidence from its tool calls.
+6. After you check its target and effect, approve a proposed write action.
 
-```
-/builds/<build-uuid>/ai
-```
+Good prompts name the observed symptom and the outcome you want:
 
-The chat interface is scoped to that build's environment — the agent already knows which namespace, services, and resources to inspect.
+- "Why did the latest deploy fail?"
+- "Which Service cannot become ready, and what evidence supports that?"
+- "Propose the smallest repair. Do not make changes."
 
----
+The agent can offer follow-up actions such as **Investigate more**, **Open
+editor**, **Continue with workspace**, or **Start workspace** when those
+capabilities are available.
 
-## Debugging a failing environment
+## Tools and approvals
 
-Here's a typical debugging session:
+The agent can use these evidence types together:
 
-1. Open the AI Agent page for your build.
-2. Click one of the suggested prompts — for example, **"Why are my pods not starting?"**
-3. The agent queries Kubernetes for pod statuses, reads recent logs, and checks deployment configurations.
-4. It returns a structured response with a summary, per-service findings, and suggested fixes.
+| Area         | Typical use                                                     |
+| ------------ | --------------------------------------------------------------- |
+| Lifecycle    | Examine Environment, Build, Service, and job state              |
+| Kubernetes   | Read resources, events, and logs in the Environment namespace   |
+| Repository   | Read related source and configuration                           |
+| Workspace    | Examine or edit files and run commands in an isolated workspace |
+| External MCP | Use administrator-approved tools from connected MCP servers     |
 
-At this point, you should see a response with **service cards** and an **activity panel** (described below). If the agent suggests a fix, you can apply it with one click.
+Administrator and repository policies control tool availability. Some reads can
+run without approval. Policies can require approval for or deny writes, shell
+commands, network access, and deployment changes.
 
-<Callout type="tip">
-  You don't need to know which Kubernetes commands to run. Describe your problem
-  in plain language and let the agent investigate.
+<Callout type="warning">
+  An approval immediately authorizes the proposed action. The action can change
+  a running Environment or an external system. Before you approve it, make sure
+  of the repository, namespace, command, and affected files.
 </Callout>
 
-The suggested prompts on first load are:
-
-- **"Why is my build failing?"**
-- **"What's wrong with deployments?"**
-- **"Why are my pods not starting?"**
-
-You can also type your own question.
-
----
-
-## Understanding responses
-
-The agent returns two response formats depending on the question:
-
-- **Plain text** — for simple or conversational answers
-- **Structured investigation** — for debugging queries, containing the sections below
+## Select a model
 
-### Summary
+If your deployment offers more than one model, use the model selector in the
+Agent panel. The configured provider, allowed models, and default model are
+controlled by an administrator.
 
-A brief overview at the top describing overall environment health and key findings.
+Do not paste provider credentials into a chat or repository.
 
-### Service cards
+## Start over
 
-Each service gets its own card with:
-
-- **Status chip** — service health: `healthy`, `degraded`, `failing`, `pending`, or `unknown`
-- **Issue** — root cause or current problem
-- **Errors** — specific error messages from logs or events
-- **Suggested fixes** — actionable steps you can follow
-- **Auto-fix button** — applies a fix directly (for example, restarting a deployment or committing a config change to your PR branch)
-- **Evidence** — links back to the tool calls that support the findings
-
-### Activity panel
-
-Each response includes a collapsible **Investigation** panel showing every tool call the agent made:
-
-- **Status icon** — spinner (in progress), green checkmark (success), or red X (failure)
-- **Description** — what the agent did (e.g., "Fetched pods in namespace env-abc123")
-- **Duration chip** — how long the call took
-
-A **total investigation time** appears at the top of the panel. Evidence references in the response link to specific entries in this panel.
-
----
+When prior messages do not apply, select **Reset conversation**. The new
+conversation does not include the previous investigation messages.
 
-## Selecting a model
+## Lifecycle Agent and Agent Sessions
 
-A **Model** dropdown in the chat header displays available models in the format `provider:modelId` (for example, "Claude Sonnet" or "GPT-4o"). Your selection is saved to `localStorage` and persists across sessions.
+The Environment details panel covers one Lifecycle Environment. Agent Sessions
+support broader repository work when the Labs feature is available. See [Agent
+Sessions](/docs/features/agent-sessions) for the distinction.
 
-A **Clear** button appears when you have messages. It clears the conversation history and starts a new session.
+## Troubleshooting
 
-### Supported providers
-
-Each provider requires its own API key configured on the server:
-
-| Provider      | Environment Variable | Fallback Variable |
-| ------------- | -------------------- | ----------------- |
-| **Anthropic** | `ANTHROPIC_API_KEY`  | `AI_API_KEY`      |
-| **OpenAI**    | `OPENAI_API_KEY`     | `AI_API_KEY`      |
-| **Gemini**    | `GEMINI_API_KEY`     | `AI_API_KEY`      |
-
-<Callout type="tip">
-  Set `AI_API_KEY` as a universal fallback if all providers share the same key.
-  Provider-specific keys take precedence.
-</Callout>
-
----
-
-## Agent capabilities
-
-The agent has access to tools organized by category:
-
-| Category       | Tools                                           | What they do                                                                       |
-| -------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
-| **Kubernetes** | Get Resources, Get Pod Logs, Get Lifecycle Logs | Inspect pods, deployments, services, events, and logs in the build namespace       |
-| **Kubernetes** | Patch Resource                                  | Restart deployments, scale replicas, delete stuck resources, apply patches         |
-| **Kubernetes** | Query Database                                  | Run read-only queries against the Lifecycle database for build and deploy metadata |
-| **GitHub**     | Get File, List Directory                        | Browse repository files and directories on the PR branch                           |
-| **GitHub**     | Update File                                     | Commit a fix directly to the PR branch                                             |
-| **GitHub**     | Get Issue Comment                               | Read PR comments for additional context                                            |
-
-<Callout>
-  Administrators can restrict which tools the agent uses per repository. See [AI
-  Agent Configuration](/docs/features/ai-agent-configuration#access-control) for
-  details.
-</Callout>
-
-You can also extend the agent with external tools via [MCP Integration](/docs/features/mcp-integration).
-
----
+- **The Agent panel is missing:** an administrator can tell you if your
+  deployment and repository enable Lifecycle Agent.
+- **No models are available:** an administrator must configure a provider and
+  at least one allowed model.
+- **A tool is missing or denied:** tool and approval policies can be global or
+  for one repository. Tell an administrator to examine the combined policy.
+- **An action is waiting:** open its approval request and examine the full
+  operation. Only an authorized user can approve it.
 
-## Summary
-
-| Feature             | Details                                                                                       |
-| ------------------- | --------------------------------------------------------------------------------------------- |
-| Access URL          | `/builds/<build-uuid>/ai`                                                                     |
-| Prerequisite        | Must be enabled by an administrator                                                           |
-| Suggested prompts   | "Why is my build failing?", "What's wrong with deployments?", "Why are my pods not starting?" |
-| Response format     | Plain text or structured investigation with service cards                                     |
-| Activity panel      | Collapsible list of tool calls with status and duration                                       |
-| Model selection     | Dropdown in header, persisted in localStorage                                                 |
-| Supported providers | Anthropic, OpenAI, Gemini                                                                     |
-| Auto-fix            | One-click fixes via Kubernetes patches or GitHub commits                                      |
+Administrators can continue with [Lifecycle Agent
+configuration](/docs/features/ai-agent-configuration), [MCP
+integration](/docs/features/mcp-integration), and [Agent
+administration](/docs/features/agent-administration).
diff --git a/src/pages/docs/features/api-environments.mdx b/src/pages/docs/features/api-environments.mdx
new file mode 100644
index 00000000..f07cf011
--- /dev/null
+++ b/src/pages/docs/features/api-environments.mdx
@@ -0,0 +1,137 @@
+---
+title: API-created Environments
+description: Create branch-based Lifecycle Environments without a pull request. Then, track, extend, redeploy, or tear them down.
+audience:
+  - api-user
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - environments
+  - api
+  - automation
+  - ttl
+---
+
+import { Callout } from "nextra/components";
+
+API-created Environments are branch-based ephemeral Environments without a pull
+request. You can create them from the UI or authenticated v2 API.
+
+<Callout type="info">
+  An administrator must enable API Environments and API-key access.
+  Authentication and repository permissions also control access.
+</Callout>
+
+## Create from the UI
+
+1. Open **Environments**.
+2. Select **New environment**.
+3. Select an onboarded repository.
+4. Select a branch.
+5. If a custom name is necessary, enter a DNS-safe name.
+6. Select a lifespan.
+7. If advanced options are necessary, expand the section:
+   - pause the initial deploy
+   - track the source branch automatically
+   - override environment values
+   - select or change service sources
+8. Check the summary.
+9. Create the Environment.
+
+Lifecycle reads `lifecycle.yaml` from the selected source and creates the
+Environment asynchronously. Open its details page to follow Service and deploy
+status.
+
+Do not put secret values in environment overrides. Use the repository's
+supported secret references and your organization's secret-management workflow.
+
+## Create through v2
+
+The caller needs `env:write` and access to the selected repository:
+
+```bash
+curl --fail --silent --show-error \
+  --request POST \
+  --header "Authorization: Bearer ${LIFECYCLE_API_KEY}" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "repository": "acme/payments",
+    "branch": "feature/retry-policy",
+    "name": "payments-retry",
+    "ttlHours": 48,
+    "deployEnabled": true,
+    "autoTrack": false,
+    "idempotencyKey": "payments-retry-run-001"
+  }' \
+  "${LIFECYCLE_URL}/api/v2/environments"
+```
+
+A new request returns `202` with data shaped like:
+
+```json
+{
+  "uuid": "payments-retry",
+  "status": "queued",
+  "namespace": "env-payments-retry",
+  "expiresAt": "2030-04-15T18:00:00.000Z",
+  "statusUrl": "/api/v2/environments/payments-retry",
+  "replayed": false
+}
+```
+
+The standard v2 envelope wraps the actual response. Repeating the same
+`idempotencyKey` with the same caller and request returns the existing
+Environment with `200`. Reusing it for different input returns a conflict.
+
+## Poll to completion
+
+Poll the returned `statusUrl` with `env:read`. Terminal statuses are:
+
+- `deployed`
+- `error`
+- `config_error`
+- `torn_down`
+
+Use bounded polling with backoff. Keep `request_id` from failures so an
+operator can correlate the request.
+
+## Manage an Environment
+
+| Task               | Method and route                          | Scope       |
+| ------------------ | ----------------------------------------- | ----------- |
+| Get details        | `GET /api/v2/environments/{uuid}`         | `env:read`  |
+| Change overrides   | `PATCH /api/v2/environments/{uuid}`       | `env:write` |
+| Deploy or redeploy | `POST /api/v2/environments/{uuid}/deploy` | `env:write` |
+| Extend its lease   | `POST /api/v2/environments/{uuid}/extend` | `env:write` |
+| Tear it down       | `DELETE /api/v2/environments/{uuid}`      | `env:write` |
+
+An extension starts at the greater value: the current time or the current
+expiry. The administrator's maximum lifespan limits the result. If the request
+does not include `hours`, Lifecycle uses the configured extension increment.
+
+Use `GET /api/v2/environments/policy` to get the current default, maximum, and
+extension values.
+
+## Teardown and reuse
+
+Deletion queues teardown and returns `202`. Continue polling while the details
+route returns `200`. A subsequent `404` means teardown is complete. You can
+then reuse its vanity name.
+
+Pull-request inactivity cleanup and keep labels do not change API leases.
+See [Environment expiration and
+cleanup](/docs/features/environment-ttl).
+
+## Troubleshooting
+
+- `403`: The administrator disabled API Environments, the key lacks `env:write`,
+  or the repository does not match its constraint.
+- `404 repo_not_onboarded`: onboard the repository before creating the
+  Environment.
+- `409 name_conflict`: select a different vanity name or wait for teardown.
+- `422 auto_track_pinned_source`: do not set `autoTrack: true` with an immutable
+  `sha`.
+
+See [API overview](/docs/api/overview) for response and retry conventions.
diff --git a/src/pages/docs/features/authentication.mdx b/src/pages/docs/features/authentication.mdx
index 15d0588a..a9223355 100644
--- a/src/pages/docs/features/authentication.mdx
+++ b/src/pages/docs/features/authentication.mdx
@@ -1,104 +1,80 @@
 ---
 title: Authentication
+description: Sign in to Lifecycle, link GitHub, sign out, and verify access controls.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - authentication
-  - security
   - keycloak
-  - sso
-  - oidc
+  - github
+  - security
 ---
 
-import { Callout, Steps } from "nextra/components";
-
-**Authentication** in Lifecycle is powered by Keycloak, providing robust identity management and authorization capabilities to ensure the UI is protected and secure.
+import { Callout } from "nextra/components";
 
-By default, Lifecycle deploys a Keycloak instance configured via the `lifecycle-keycloak` Helm chart. This automated setup handles the creation of necessary realms, clients, and default users to get you started quickly without manual intervention.
+Lifecycle uses OpenID Connect (OIDC) for interactive sign-in. It uses API keys
+for programmatic access.
 
-<Callout type="info">
-  For advanced configuration details and Helm chart values, refer to the
-  [lifecycle-keycloak Helm Chart
-  repository](https://github.com/GoodRxOSS/helm-charts/tree/main/charts/lifecycle-keycloak).
+<Callout type="error">
+  The stock installation is not a complete authentication-on profile for
+  shared-network exposure. Before exposure, use a complete authentication-on
+  profile and procedure for the installed release. If the release does not
+  supply this procedure, keep the deployment isolated. Do not disable
+  authentication to bypass a failed test.
 </Callout>
 
----
-
-## Default configuration
+## Sign in
 
-When you install Lifecycle, the Keycloak operator automatically provisions the following defaults:
+1. Open your organization's Lifecycle URL.
+2. Complete the identity-provider sign-in.
+3. If your organization requires multifactor authentication, complete it.
+4. Make sure that Lifecycle shows the expected account.
 
-- **Realm**: A default realm named `internal` is created.
-- **Default User**: Within the `internal` realm, a default user is provisioned.
+If sign-in fails, select **Try again**. If the failure continues, send the
+displayed message to your administrator.
 
-The default credentials for this user are:
+## Link your GitHub identity
 
-- **Username**: `lifecycle`
-- **Password**: `lifecycle`
+GitHub account linking is different from signing in to Lifecycle. After sign-in,
+Lifecycle can show a GitHub connection prompt. The connection identifies your
+GitHub user for repository actions and Agent workflows.
 
-This allows you to log in to the Lifecycle UI immediately after installation without any additional configuration.
+You can select **Skip this step** and connect later. Select **Link GitHub** from
+the account menu when you are ready.
 
----
-
-## Configuring an external OIDC provider
-
-If you prefer to use an external OIDC provider (such as Okta, Auth0, or Azure AD) instead of the default Keycloak setup, you can easily configure Keycloak to federate authentication to your provider.
-
-Here is how you can set up an external OIDC provider:
+If Lifecycle cannot use the saved authorization, select **Reconnect GitHub**.
+Do not create a second Lifecycle account.
 
 <Callout type="info">
-  To log in to the Keycloak Admin Console, you need the bootstrap administrator
-  credentials. By default, these are stored in a Kubernetes secret named
-  `lifecycle-keycloak-bootstrap-admin` within the namespace where Keycloak and
-  Lifecycle are installed (default is `lifecycle-app`).
+  Connecting GitHub does not replace company SSO. It adds a repository identity
+  to your existing Lifecycle account.
 </Callout>
 
-<Steps>
-### Access Keycloak Admin Console
-Log in to your Keycloak Admin Console using your administrator credentials.
-
-### Select the realm
-
-Select the **lifecycle** realm from the top-left dropdown menu.
+## Sign out
 
-### Navigate to Identity Providers
+1. Open the account menu.
+2. Select **Log out**.
+3. Open a protected Lifecycle page.
+4. Make sure that Lifecycle requires sign-in.
 
-In the left-hand menu, click on **Identity Providers**.
+## Check the security boundary
 
-### Select the SSO provider
+Before you make a deployment available on an untrusted network, make sure that:
 
-Select the **company-sso** provider from the list of available identity providers.
-
-### Update provider settings
-
-Update the following settings to match your external provider (e.g., Okta):
-
-- **Client Authentication**: Change this from `jwt` to `Client secret sent as basic auth`.
-- **Client ID**: Replace with the Client ID provided by your external OIDC provider.
-- **Client Secret**: Replace with the Client Secret provided by your external OIDC provider.
-- **Authorization URL**: Update to your provider's authorization endpoint.
-- **Token URL**: Update to your provider's token endpoint.
-- **JWKS URL**: Update to your provider's JSON Web Key Set endpoint.
-
-### Save changes
-
-Click **Save** to apply your changes.
-
-</Steps>
-
-Once configured, users will be able to authenticate using your external OIDC provider when accessing the Lifecycle UI.
-
-<Callout type="tip">
-  Ensure that your external OIDC provider is configured to allow redirects back
-  to your Keycloak instance's URL.
-</Callout>
-
----
+1. An unauthenticated UI request redirects to sign-in.
+2. An unauthenticated v2 API request returns `401`.
+3. A signed-in user receives only the expected Lifecycle role.
+4. A forbidden administrator action returns `403`.
+5. GitHub linking changes only GitHub-dependent features.
+6. Signing out invalidates the browser session.
 
-## Summary
+Also test the token issuer, audience, redirect URIs, trusted proxy headers, and
+TLS. Test secret rotation before you rely on the deployment.
 
-| Feature                 | Details                                                                    |
-| :---------------------- | :------------------------------------------------------------------------- |
-| **Provider**            | Keycloak                                                                   |
-| **Default Realm**       | `internal`                                                                 |
-| **Default Credentials** | `lifecycle` / `lifecycle`                                                  |
-| **External OIDC**       | Supported via the `company-sso` identity provider in the `lifecycle` realm |
-| **Helm Chart**          | `lifecycle-keycloak`                                                       |
+For programmatic access, continue with [API
+authentication](/docs/api-authentication/overview) and [API
+keys](/docs/api-authentication/api-keys).
diff --git a/src/pages/docs/features/auto-deployment.mdx b/src/pages/docs/features/auto-deployment.mdx
index 67160bea..3703e831 100644
--- a/src/pages/docs/features/auto-deployment.mdx
+++ b/src/pages/docs/features/auto-deployment.mdx
@@ -1,6 +1,12 @@
 ---
-title: Auto Deploy & Labels
-description: How to setup auto deploy for pull requests and control envionment with labels
+title: Auto-deploy and labels
+description: Automatically deploy pull request Environments and control them with configurable GitHub labels.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - deploy
   - auto
@@ -9,57 +15,57 @@ tags:
   - lifecycle-disabled
 ---
 
-## Auto-Deploy Configuration
+## Configure auto-deploy
 
-To enable **automatic deployment** when a PR is created, set the `autoDeploy` attribute in your repository's `lifecycle.yaml` file:
+To deploy automatically when a pull request opens, set `autoDeploy` in the
+repository's `lifecycle.yaml` file:
 
 ```yaml {2} filename="lifecycle.yaml"
 environment:
   autoDeploy: true
-  defaultServices:
 ```
 
-- Lifecycle will **automatically create** the environment as soon as a PR is opened.
-- A `lifecycle-deploy!` label will be added to the PR to indicate that the environment has been deployed.
+- Lifecycle creates the Environment when a pull request opens.
+- Lifecycle adds the configured deploy label. Its default name is
+  `lifecycle-deploy!`.
 
 ---
 
-## Managing Deployments with Labels
+## Manage deployments with labels
 
-If **auto-deploy is not enabled**, you can manually control the environment using PR labels.
+If **auto-deploy is not enabled**, you can manually control the Environment
+using pull request labels. The names below are defaults. Ask your deployment
+owner for the configured names.
 
 ### Deploy an Environment
 
-To create an ephemeral environment for a PR, **add** the `lifecycle-deploy!` label.
+To create an Environment for a pull request, add the `lifecycle-deploy!` label.
 
-### Tear Down an Environment
+### Tear down an Environment
 
-To **delete** an active environment, use either of these labels:
+To delete an active Environment, use one of these actions:
 
 - **Remove** `lifecycle-deploy!`
 - **Add** `lifecycle-disabled!`
 
----
-
-## Automatic Cleanup on PR Closure
+### Prevent TTL cleanup
 
-When a PR is **closed**, Lifecycle will:
+Add `lifecycle-keep!`. This label prevents inactivity-based TTL cleanup. It does
+not prevent manual teardown. When the pull request closes, the label does not
+prevent cleanup. See
+[Environment TTL](/docs/features/environment-ttl).
 
-1. **Tear down** the active environment.
-2. **Remove** the `lifecycle-deploy!` label from the PR.
+---
 
-This ensures that unused environments do not persist after the PR lifecycle is complete.
+## Clean up a closed pull request
 
----
+When a pull request closes, Lifecycle:
 
-## Summary
+1. Tears down the active Environment.
+2. Removes the configured deploy label from the pull request.
 
-| Feature                      | Behavior                                        |
-| ---------------------------- | ----------------------------------------------- |
-| `autoDeploy: true` in config | PR environments are **automatically** deployed. |
-| `lifecycle-deploy!`          | **Manually deploy** an environment.             |
-| Remove `lifecycle-deploy!`   | **Tear down** the environment.                  |
-| Add `lifecycle-disabled!`    | **Tear down** the environment manually.         |
-| PR closed                    | **Environment is deleted automatically**.       |
+These actions remove Environments that are not necessary after the pull request
+closes.
 
-Using these configurations and labels, teams can efficiently manage **ephemeral environments** in their development workflow.
+See [Configurable labels](/docs/features/configurable-labels) for label effects
+and customized names.
diff --git a/src/pages/docs/features/build-metadata-links.mdx b/src/pages/docs/features/build-metadata-links.mdx
index d360c301..2c9b98cf 100644
--- a/src/pages/docs/features/build-metadata-links.mdx
+++ b/src/pages/docs/features/build-metadata-links.mdx
@@ -1,110 +1,103 @@
 ---
-title: Metadata Links
+title: Build metadata links
+description: Add administrator-managed links to Environment details using build environment variables as templates.
+audience:
+  - application-developer
+  - platform-operator
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
-  - build
+  - environments
   - metadata
   - links
-  - observability
-  - template
-  - variables
+  - administration
 ---
 
 import { Callout } from "nextra/components";
 
-Build metadata links let your Lifecycle installation show useful links for each ephemeral environment. They are most commonly used for observability links, but they can point to any tool that helps your team understand, debug, or operate an environment.
+Build metadata links place deployment-specific destinations on an
+Environment's details page. Examples include logs, traces, dashboards, and
+runbooks. Lifecycle renders each link with that build's environment-variable
+context.
 
-When metadata links are configured, Lifecycle renders them from the current build context. That means one link template can work for every environment because Lifecycle fills in values like the build UUID, namespace, branch name, pull request number, repository name, and service-specific variables.
+## Plan a link
 
-## Common Use Case: Observability
+Each link has:
 
-The environment details page can show a row of observability buttons for the current build. Teams often use these buttons for:
+| Field      | Purpose                        |
+| ---------- | ------------------------------ |
+| `text`     | User-facing label              |
+| `icon`     | Icon identifier used by the UI |
+| `link`     | Absolute URL template          |
+| `position` | Integer used to order links    |
 
-- Container or pod views
-- Distributed traces
-- Environment logs
-- Build or job logs
-- Edge, gateway, or ingress logs
+Use Mustache placeholders for values available in the build environment:
 
-These links help reviewers and service owners jump directly from a Lifecycle environment to the right view in their observability platform.
-
-<Callout type="info">
-  Build metadata links are configured centrally for a Lifecycle installation. If
-  your team needs a new link, ask the person or team that manages your Lifecycle
-  configuration.
-</Callout>
-
-## How Links Are Configured
-
-Each link has a few display fields and a URL template:
-
-| Field      | Purpose                                                  |
-| ---------- | -------------------------------------------------------- |
-| `text`     | The button label shown to users                          |
-| `icon`     | The icon shown next to the label                         |
-| `link`     | The URL template rendered for each build                 |
-| `position` | The order links appear in the UI and other build outputs |
-
-The `link` field supports Mustache syntax. For example, a link can include `{{{buildUUID}}}` so Lifecycle replaces it with the current environment UUID before showing the link.
-
-```txt
-https://observability.example.com/logs?env={{{buildUUID}}}
-```
-
-For a build named `calm-river-123456`, the rendered link would point to:
-
-```txt
-https://observability.example.com/logs?env=calm-river-123456
+```text
+https://logs.example.com/search?namespace={{NAMESPACE}}
 ```
 
-## Template Variables
-
-Metadata links can use the same build environment template variables that Lifecycle uses elsewhere. `buildUUID` is the most common variable for observability links, but templates can also use variables such as:
-
-- `namespace`
-- `branchName`
-- `repoName`
-- `pullRequestNumber`
-- service-specific variables like `<service_name>_publicUrl`, `<service_name>_internalHostname`, or `<service_name>_sha`
-
-Use triple curly braces, such as `{{{buildUUID}}}`, when you want the raw value inserted into a URL without HTML escaping.
-
-See [Template Variables](/docs/features/template-variables) for the full list of supported variables and service-specific naming rules.
+Lifecycle renders double- and triple-brace placeholders as unescaped URL text.
+Unknown variables render as empty strings. Test the link with build data.
 
-<Callout>
-  If a template references a variable that is not available for a build,
-  Lifecycle renders that value as an empty string. Make sure important links use
-  variables that are available for the environments your team creates.
+<Callout type="warning">
+  Metadata links are global and can give deployment context to an external
+  service. Use only trusted `http` or `https` destinations. Do not put secrets
+  in query strings. Before you publish the link, check the rendered host.
 </Callout>
 
-## Icons
+## Manage links
 
-Lifecycle supports a small set of link icons in the UI. Common observability icon names include:
+Build metadata configuration is an administrator operation. Use these v2
+routes:
 
-- `Container`
-- `Route`
-- `FileCog`
-- `ClipboardList`
-- `Timer`
+| Operation              | Route                                 |
+| ---------------------- | ------------------------------------- |
+| List templates         | `GET /api/v2/config/metadata`         |
+| Create a template      | `POST /api/v2/config/metadata`        |
+| Update selected fields | `PATCH /api/v2/config/metadata/{id}`  |
+| Delete a template      | `DELETE /api/v2/config/metadata/{id}` |
 
-If a configured icon is not recognized by the UI, Lifecycle falls back to a generic link icon.
+Only an authenticated **administrator browser session** can use these routes.
+They do not accept API keys. Use the deployment API reference from an approved
+administrator session. Do not copy a browser session token into a shell.
 
-## What Makes A Good Metadata Link
+A create request accepts only `text`, `icon`, `link`, and optional `position`.
+Lifecycle generates the `id`:
 
-Good metadata links are specific, stable, and useful during review. Prefer links that take users directly to the relevant environment, service, trace, log query, dashboard, run, or external system page.
+```json
+{
+  "text": "Application logs",
+  "icon": "file",
+  "link": "https://logs.example.com/search?namespace={{NAMESPACE}}",
+  "position": 0
+}
+```
+
+A patch changes only the supplied fields:
 
-Useful links might include:
+```json
+{
+  "text": "Runtime logs",
+  "position": 1
+}
+```
 
-- Observability dashboards filtered to the current build
-- Logs filtered to a namespace, build UUID, or service
-- CI or deployment job pages
-- Feature flag dashboards scoped to the environment
-- Runbooks or support pages for a service
-- External tools that understand a Lifecycle environment identifier
+## Check the result
 
-Avoid broad landing pages that require users to search manually after clicking.
+1. Create or update the link.
+2. Open an Environment that defines all referenced variables.
+3. Check the label, icon, and ordering.
+4. Before you follow the link, examine the rendered destination.
+5. Test a build that has no optional variable.
 
-## Safety
+The build-specific read route renders configured templates:
 
-Lifecycle validates rendered URLs before returning them to the UI. Unsafe schemes such as `javascript:` and `data:` are rejected.
+```text
+GET /api/v2/builds/{uuid}/metadata
+```
 
-Because metadata links can use build and service variables, treat them as shared team configuration. Avoid adding links that expose sensitive values or send environment-specific data to systems your team does not trust.
+See [API overview](/docs/api/overview) for the supported API version and
+deployment-local reference.
diff --git a/src/pages/docs/features/cli-telemetry.mdx b/src/pages/docs/features/cli-telemetry.mdx
new file mode 100644
index 00000000..78b10e66
--- /dev/null
+++ b/src/pages/docs/features/cli-telemetry.mdx
@@ -0,0 +1,75 @@
+---
+title: Lifecycle CLI telemetry
+description: Understand the pseudonymous command-usage event sent by lfc, its destination, and how to opt out.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - cli
+  - telemetry
+  - privacy
+---
+
+import { Callout } from "nextra/components";
+
+By default, the `lfc` CLI attempts to send one usage event to the configured
+Lifecycle deployment. The event helps deployment owners understand command
+reliability and adoption.
+
+## What the CLI sends
+
+Each event can contain:
+
+- a random identifier for the CLI installation
+- the command path, such as `builds list`
+- names of flags passed on the command line
+- duration, success or error outcome, and process exit code
+- error class, HTTP status, and stable Lifecycle error code when available
+- CLI version, Node.js runtime version, operating-system platform, and
+  architecture
+
+The telemetry event does not contain flag **values**, positional arguments,
+command output, repository content, or user identity.
+
+<Callout type="info">
+  The install identifier is pseudonymous. It lets a deployment count recurring
+  CLI installations. It is not a name or account ID.
+</Callout>
+
+## Where it goes
+
+The CLI posts to its own configured Lifecycle deployment:
+
+```text
+POST /api/v2/telemetry/events
+```
+
+It does not send this usage event directly to a shared external analytics
+service. A telemetry failure does not change the command result.
+
+## Opt out
+
+Set `LFC_TELEMETRY_DISABLED` to a non-empty value other than `0` or `false`:
+
+```bash
+export LFC_TELEMETRY_DISABLED=1
+```
+
+Set it in the environment where `lfc` runs and in CI. This keeps the setting for
+that caller.
+
+## Retention and access
+
+Each deployment controls retention. The CLI contract does not specify
+retention. Get this information from your Lifecycle operator:
+
+- how long the deployment keeps CLI events
+- which administrators can see aggregate statistics
+- if the deployment sends events to a different observability system
+- how your privacy policy handles the installation identifier
+
+For application workload labels sent through your platform's Datadog pipeline,
+see [Datadog application telemetry](/docs/tips/telemetry).
diff --git a/src/pages/docs/features/cli.mdx b/src/pages/docs/features/cli.mdx
index 07213cd4..40a6f38e 100644
--- a/src/pages/docs/features/cli.mdx
+++ b/src/pages/docs/features/cli.mdx
@@ -1,5 +1,12 @@
 ---
 title: CLI (lfc)
+description: Install and use the Lifecycle CLI to examine Environments, manage Services, stream logs, and validate configuration.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-08-01"
+verificationBaseline: "2026-08-01-configuration-schema-fix"
+contentProfile: asd-ste100
 tags:
   - cli
   - lfc
@@ -10,64 +17,62 @@ tags:
 
 import { Callout } from "nextra/components";
 
-`lfc` is the command-line interface for Lifecycle. It lets you view and manage
-preview environments (builds), redeploy services, stream logs, host static
-sites, and validate configuration — straight from your terminal. It is built
-for **humans and agents**: every command supports `--json`, human-readable
-messages go to `stderr`, and machine output goes to `stdout`.
+`lfc` is the command-line interface for Lifecycle. Use it to view and manage
+preview Environments (Builds), redeploy Services, stream logs, host static
+sites, and validate configuration. Use `--json` for machine-readable results.
 
 <Callout type="info">
-  The CLI ships with **no deployment URLs baked in**. You point it at your own
-  Lifecycle deployment once with `lfc init`. All examples below use generic
-  placeholder hosts such as `https://lifecycle.example.com` and `myorg/myrepo` —
-  substitute your own values.
+  `lfc init` selects the Lifecycle deployment before first use.
+
+These examples use generic placeholder hosts such as
+`https://lifecycle.example.com` and `myorg/myrepo`. Your commands must use your
+deployment values.
+
 </Callout>
 
 ## Overview
 
-Requires Node ≥ 20.
+Node ≥ 20 is necessary.
 
 ```sh
 npm install -g lfc-cli
 lfc --help
 ```
 
-- **`--help` everywhere.** `lfc <command> --help` works on every command and
-  subcommand and lists all flags.
-- **`--json` everywhere.** Add `--json` for machine-readable output, or set
-  `LFC_JSON=1` to enable it globally.
-- **Humans and agents.** Interactive prompts appear only on a TTY; without one,
-  commands fail fast and name the missing flag/argument, so scripts and agents
-  stay deterministic. Run `lfc llms` to print agent-oriented instructions.
-
-## How it works
-
-`lfc` is a thin client over your Lifecycle deployment's HTTP API. Nothing about
-your deployment is hard-coded — you configure it once and the CLI stores a
-**profile** locally.
-
-- **Profiles.** Each profile points at one deployment (API URL, optional UI URL,
-  and auth settings). You can keep several (e.g. `default`, `staging`, `local`)
-  and switch between them. Config lives at
-  `~/.config/lifecycle-cli/config.json`.
-- **Authentication.** Deployments that enforce SSO use Keycloak (Authorization
-  Code + PKCE, or device code for headless machines). Tokens are cached per
-  profile under `~/.config/lifecycle-cli/tokens/` and refresh automatically.
-  Auth-less deployments (`authEnabled: false`) skip all of this.
-- **Output & scripting.** JSON goes to `stdout`; informational messages go to
-  `stderr`. Commands return meaningful exit codes:
-
-  | Code | Meaning                                                     |
-  | ---- | ----------------------------------------------------------- |
-  | `0`  | success                                                     |
-  | `1`  | failure (API error, failed build, invalid schema)           |
-  | `2`  | watch timeout (`--watch` did not converge in time)          |
-  | `3`  | not found (unknown uuid, no matching build, no config file) |
-  | `4`  | authentication error (not logged in, expired session)       |
+- **`--help` for all commands.** `lfc <command> --help` works on all commands
+  and subcommands and lists all flags.
+- **`--json` for automation.** Add `--json`, or set `LFC_JSON=1`.
+- **`--quiet` when scripting.** Add `--quiet` to suppress informational output
+  while preserving command results and errors.
+- **Humans and agents.** Interactive prompts show only on a TTY. Without one,
+  commands fail fast and name the missing flag or argument. This behavior keeps
+  scripts and agents deterministic. Run `lfc llms` to print agent-oriented
+  instructions.
+
+## Profiles and output
+
+Each profile selects one Lifecycle deployment. Use separate profiles for
+deployments such as production and staging.
+
+Commands use these exit codes:
+
+| Code | Meaning                                                           |
+| ---- | ----------------------------------------------------------------- |
+| `0`  | Success                                                           |
+| `1`  | API error, failed build, or invalid schema                        |
+| `2`  | Watch timeout or `lfc doctor` warning                             |
+| `3`  | Not found, missing config, or unresolved `lfc doctor --fix` error |
+| `4`  | Authentication error                                              |
 
 <Callout type="warning">
-  On exit code `4`, run `lfc login` (or `lfc login --device` on a headless
-  machine) and retry. Verify who you are with `lfc whoami`.
+  If the exit code is `4`, use one login command:
+
+- `lfc login`
+- `lfc login --device` on a headless machine
+
+Retry the failed command. Make sure of your identity:
+`lfc whoami`
+
 </Callout>
 
 ## Configuration
@@ -87,54 +92,27 @@ lfc init \
   --ui-url  https://lifecycle-ui.example.com \
   --issuer  https://sso.example.com/realms/lifecycle
 
-# auth-less deployment (e.g. local)
+# Authentication-free, trusted local deployment
 lfc init --api-url http://localhost:8080 --no-auth --name local
 ```
 
-`init` verifies the URL is reachable, writes the profile, and (when auth is on)
-starts the SSO login. Useful flags: `--ui-url` (enables `lfc builds open`),
-`--no-login` (skip the login step), `--device` (device-code login),
-`--name <profile>`, `--force` (overwrite an existing profile).
-
-### Config file structure
-
-Configuration lives at `~/.config/lifecycle-cli/config.json` and holds one entry
-per deployment under `profiles`, with the active one named by `currentProfile`:
-
-```json
-{
-  "currentProfile": "default",
-  "profiles": {
-    "default": {
-      "apiUrl": "https://lifecycle.example.com",
-      "uiUrl": "https://lifecycle-ui.example.com",
-      "authEnabled": true,
-      "keycloak": {
-        "issuer": "https://sso.example.com/realms/lifecycle",
-        "clientId": "lifecycle-cli"
-      }
-    },
-    "local": {
-      "apiUrl": "http://localhost:8080",
-      "authEnabled": false
-    }
-  }
-}
-```
+`init` validates the URL format and tries to reach the API. If the API is not
+reachable, `init` shows a warning and saves the profile. When authentication is
+on, it starts the SSO login. These flags are useful:
 
-| Field               | Description                                                         |
-| ------------------- | ------------------------------------------------------------------- |
-| `apiUrl`            | Base URL of the Lifecycle API (required).                           |
-| `uiUrl`             | Base URL of the Lifecycle UI (optional; enables `lfc builds open`). |
-| `authEnabled`       | Whether the deployment enforces SSO.                                |
-| `keycloak.issuer`   | Keycloak realm issuer URL (when `authEnabled` is `true`).           |
-| `keycloak.clientId` | OAuth client id (defaults to `lifecycle-cli`).                      |
+- `--ui-url` enables `lfc builds open`.
+- `--no-login` skips the login step.
+- `--device` uses device-code login.
+- `--name <profile>` names the profile.
+- `--force` overwrites an existing profile.
 
-Manage profiles without editing the file by hand:
+### Manage profiles
 
 ```sh
 lfc config list                         # all profiles
 lfc config get                          # active profile as JSON (no secrets)
+lfc config get apiUrl                   # one active-profile value
+lfc config set uiUrl https://lifecycle-ui.example.com
 lfc config add-profile staging --api-url https://lifecycle-staging.example.com --issuer <url>
 lfc config use-profile staging          # switch the active profile
 lfc --profile staging builds list       # one-off profile override
@@ -161,19 +139,20 @@ lfc --api-url http://localhost:8080 builds list
 
 ```sh
 lfc login                 # SSO in the browser
-lfc login --device        # headless: prints a URL + code to confirm elsewhere
+lfc login --device        # headless: prints a URL + code to enter in a browser
+lfc login --no-browser    # PKCE login: print the URL instead of opening it
 lfc whoami                # logged-in user, roles, token expiry
 lfc logout
 ```
 
-### Builds (preview environments)
+### Builds (preview Environments)
 
 ```sh
-lfc builds list [--mine] [--search <text>] [--all] [-n <limit>] [-p <page>]
-lfc builds get <uuid> [--manifest]
-lfc builds find --pr <url|number> [--repo myorg/myrepo]   # resolve a PR/branch → build
+lfc builds list [--mine] [--search <text>] [--exclude <statuses>] [--all] [-n <limit>] [-p <page>]
+lfc builds find --pr <url|number> [--repo myorg/myrepo]
 lfc builds find --branch <name> --repo myorg/myrepo
-lfc builds status <uuid> [--watch]        # exit 0 deployed, 1 failed, 2 timeout
+lfc builds get <uuid> [--manifest]
+lfc builds status <uuid> [--watch] [--interval <duration>] [--timeout <duration>]
 lfc builds redeploy <uuid> [--watch]
 lfc builds destroy <uuid> --yes
 lfc builds update-uuid <uuid> <new-uuid>
@@ -182,12 +161,18 @@ lfc builds webhooks <uuid> [--invoke]
 lfc builds open <uuid> [--print]          # open in the Lifecycle UI
 ```
 
-`builds find` resolves a build from a PR or branch — useful when you have a PR
-URL but not the uuid. A PR URL is self-contained; a bare PR number or a branch
-needs `--repo`. With `--json` it returns `{ found, build, matches }` (more than
-one `matches` entry means the selector was ambiguous). Exit `0` found, `3` no
-build yet (e.g. the PR was just opened), `1` if the scan was truncated before
-resolving.
+When you know the pull request or branch but do not know the Environment ID,
+use `lfc builds find`. A full pull request URL identifies the repository. A
+pull request number or branch name also needs `--repo`.
+
+When you use `--json`, a successful result contains `found`, `build`, and
+`matches`.
+Exit code `3` means that no build exists. Exit code `1` means that the scan
+stopped before it could give a conclusive result.
+
+Use `lfc builds list --search <text>` to search by Environment ID, namespace,
+pull request title, repository, or author. By default, list excludes
+`torn_down` and `pending`. Use `--all` or add `--exclude` to change that filter.
 
 Per-build environment-variable overrides:
 
@@ -197,24 +182,29 @@ lfc builds env set <uuid> KEY=VALUE [KEY=VALUE ...] [--init]
 lfc builds env unset <uuid> KEY [KEY ...]
 ```
 
-### Services (within a build)
+### Services in a build
 
 ```sh
 lfc services list <build-uuid> [--all]
 lfc services redeploy <build-uuid> <service>
-lfc services enable | disable <build-uuid> <service>
+lfc services enable <build-uuid> <service>
+lfc services disable <build-uuid> <service>
 lfc services set-branch <build-uuid> <service> <branch-or-url>
+lfc services edit <build-uuid>                         # interactive editor
 lfc services history <build-uuid> <service>          # build/deploy job history
-lfc services logs <build-uuid> <service> [--deploy] [--job <name>] [-f]
+lfc services logs <build-uuid> <service> [--deploy] [--job <name>] [-f] [--tail <n>] [--timestamps]
 ```
 
 ### Pods & runtime logs
 
 ```sh
 lfc pods list <build-uuid> [--service <name>]
-lfc pods logs <build-uuid> <pod-name> [-c <container>] [-f] [--tail <n>] [--timestamps]
+lfc pods logs <build-uuid> [pod-name] [--service <name>] [-c <container>] [-f] [--tail <n>] [--timestamps]
 ```
 
+On an interactive terminal, run the command without `pod-name` to select a pod
+and container. In automation, specify the pod and container.
+
 ### Schema validation
 
 ```sh
@@ -222,7 +212,13 @@ lfc schema validate [path]                              # finds lifecycle.yaml l
 lfc schema validate --repo myorg/myrepo --branch <branch>   # server-side check
 ```
 
-Exit `0` valid, `1` invalid (per-field errors printed), `3` no config file found.
+Exit code `0` means valid. Exit code `1` means invalid and prints errors for
+each field. Exit code `3` means that the CLI did not find a configuration file.
+
+<Callout type="warning">
+  Offline validation uses the schema in your installed CLI. If results differ,
+  use `--repo` and `--branch`. The server result controls that deployment.
+</Callout>
 
 ### Static sites
 
@@ -239,12 +235,13 @@ lfc sites delete <id> --yes
 
 ```sh
 lfc doctor                # environment/config/auth health checks
+lfc doctor --fix          # repair supported local permission issues
 lfc llms                  # print full agent-oriented usage instructions
 lfc --version
 ```
 
 <Callout type="info">
-  Every command supports `--help` and `--json`. For scripting and automation,
-  combine `--json` with a JSON processor, e.g.
+  All commands support `--help`. For automation, send `--json` results to a
+  JSON processor. For example, use
   `lfc builds get <uuid> --json | jq '.deploys[] | {name: .deployable.name, url: .publicUrl}'`.
 </Callout>
diff --git a/src/pages/docs/features/configurable-labels.mdx b/src/pages/docs/features/configurable-labels.mdx
index 28a875a7..4ebdb888 100644
--- a/src/pages/docs/features/configurable-labels.mdx
+++ b/src/pages/docs/features/configurable-labels.mdx
@@ -1,5 +1,12 @@
 ---
 title: Configurable Labels
+description: Use deployment-specific GitHub labels to control Environments, cleanup, and status comments.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - labels
   - configuration
@@ -7,78 +14,73 @@ tags:
   - disabled
   - keep
   - status-comments
-  - global-config
 ---
 
 import { Callout } from "nextra/components";
 
-Lifecycle allows you to customize the GitHub labels that control environment deployments, TTL behavior, and status comments through the `global_config.labels` configuration.
+Lifecycle uses GitHub labels to control pull-request Environments and comments.
+The label names can differ between deployments.
 
-## Configuration
-
-The labels configuration is stored in the `global_config` table with the key `labels`:
-
-```json
-{
-  "deploy": ["lifecycle-deploy!", "lfc-deploy"],
-  "disabled": ["lifecycle-disabled!", "lfc-skip"],
-  "keep": ["lifecycle-keep!", "lfc-keep"],
-  "statusComments": ["lifecycle-status-comments!"],
-  "defaultStatusComments": true,
-  "defaultControlComments": true
-}
-```
-
-### `deploy`
-
-Labels that trigger environment deployment. When any deploy label is added to a PR, Lifecycle creates an ephemeral environment. The first label in the array is used when adding labels programmatically. Supports multiple labels for different teams or naming conventions.
-
-**Default:** `["lifecycle-deploy!"]`
+<Callout type="info">
+  The names on this page are defaults. The deployment owner can provide the
+  names that apply to your deployment.
+</Callout>
 
-### `disabled`
+<Callout type="warning">
+  These settings have no supported UI, typed API, or Helm value. A deployment
+  owner must use a supported operator procedure for the installed release. See
+  [Runtime configuration surfaces](/docs/operations/configuration). If no such
+  procedure exists for the installed release, keep the default labels.
+</Callout>
 
-Labels that prevent or teardown deployments. When any disabled label is added or deploy label is removed, the active environment will be torn down.
+## Label effects
 
-**Default:** `["lifecycle-disabled!"]`
+| Default label                | Observable effect                                 |
+| ---------------------------- | ------------------------------------------------- |
+| `lifecycle-deploy!`          | Environment creation and later push redeploys     |
+| `lifecycle-disabled!`        | Prevent or tear down the Environment              |
+| `lifecycle-keep!`            | Prevent cleanup caused by inactivity              |
+| `lifecycle-status-comments!` | Show status comments when they are off by default |
 
-### `keep`
+## Deploy or tear down an Environment
 
-Labels that disable TTL cleanup for an environment. When present on a PR, prevents automatic teardown due to inactivity and sets `lfc/ttl-enable: false` on the Kubernetes namespace.
+If auto-deploy is off, add the deploy label to create an Environment.
 
-**Default:** `["lifecycle-keep!"]`
+To tear down the Environment, do one of these actions:
 
-### `statusComments`
+- Remove the deploy label.
+- Add the disabled label.
 
-Labels that control status comment visibility on a per-PR basis. Behavior depends on the `defaultStatusComments` setting.
+Closing the pull request also tears down its Environment. Lifecycle removes the
+deploy label after the pull request closes.
 
-**Default:** `["lifecycle-status-comments!"]`
+## Keep an inactive Environment
 
-### `defaultStatusComments`
+Before the inactivity limit, add the keep label. The label prevents only
+inactivity-based cleanup.
 
-Controls whether status comments are enabled by default across all PRs. When `true`, status comments show for all PRs. When `false`, status comments only show when the status comment label is present.
+The keep label does not prevent these actions:
 
-**Default:** `true`
+- manual teardown
+- teardown after pull-request closure
+- cleanup of an API-created Environment after its lease expires
 
-### `defaultControlComments`
+## Show status comments
 
-Enables or disables control-related comments system-wide.
+Lifecycle can enable status comments by default for a repository. If comments
+are off by default, add the status-comments label to the pull request.
 
-**Default:** `true`
+The deployment owner also controls Lifecycle control comments. A pull-request
+label does not override that setting.
 
-<Callout type="warning">
-  Changes to label configuration require refreshing the global config cache or
-  waiting for the automatic refresh cycle.
-</Callout>
+## Check a label problem
 
----
+If a label has no effect:
 
-## Summary
+1. Make sure that you used the configured label name.
+2. Make sure that the label is on the correct pull request.
+3. Check whether the Environment is pull-request or API-created.
+4. Ask the deployment owner to verify the repository label settings.
 
-| Property                 | Type     | Purpose                             |
-| ------------------------ | -------- | ----------------------------------- |
-| `deploy`                 | string[] | Trigger environment deployment      |
-| `disabled`               | string[] | Prevent or teardown deployments     |
-| `keep`                   | string[] | Disable TTL cleanup                 |
-| `statusComments`         | string[] | Control status comment visibility   |
-| `defaultStatusComments`  | boolean  | Enable status comments by default   |
-| `defaultControlComments` | boolean  | Enable control comments system-wide |
+See [Auto-deploy and labels](/docs/features/auto-deployment) and [Environment
+expiration and cleanup](/docs/features/environment-ttl).
diff --git a/src/pages/docs/features/environment-ttl.mdx b/src/pages/docs/features/environment-ttl.mdx
index 6648f487..96cb8453 100644
--- a/src/pages/docs/features/environment-ttl.mdx
+++ b/src/pages/docs/features/environment-ttl.mdx
@@ -1,92 +1,85 @@
 ---
-title: Environment TTL
+title: Environment expiration and cleanup
+description: Understand how Lifecycle cleans up pull-request environments and expires API-created environments.
+audience:
+  - application-developer
+  - platform-operator
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
-  - ttl
+  - environments
   - cleanup
-  - lifecycle-keep
-  - inactivity
-  - global-config
+  - ttl
+  - api
 ---
 
 import { Callout } from "nextra/components";
 
-Lifecycle automatically cleans up inactive ephemeral environments based on configurable TTL (Time To Live) settings. This helps reduce resource usage while allowing teams to keep environments alive when needed.
-
-## Configuration
-
-The TTL cleanup configuration is stored in the `global_config` table with the key `ttl_cleanup`:
-
-```json
-{
-  "enabled": true,
-  "dryRun": false,
-  "inactivityDays": 14,
-  "checkIntervalMinutes": 240,
-  "commentTemplate": "This environment has been inactive for {inactivityDays} days and will be automatically cleaned up.",
-  "excludedRepositories": []
-}
-```
-
-### `enabled`
-
-Enables or disables automatic cleanup of inactive environments.
-
-**Default:** `false`
-
-### `dryRun`
-
-Runs cleanup process without actually tearing down environments. Useful for testing.
-
-**Default:** `true`
+Lifecycle has two different cleanup models:
 
-### `inactivityDays`
+| Environment type         | Cleanup model                                |
+| ------------------------ | -------------------------------------------- |
+| Pull-request environment | Deployment inactivity and pull-request state |
+| API-created environment  | An explicit `expiresAt` lease                |
 
-Number of days of inactivity before an environment is eligible for cleanup.
+First, identify the model that created an Environment. Keep labels and
+inactivity settings do not extend an API Environment lease.
 
-**Default:** `14`
+## Pull-request environments
 
-### `checkIntervalMinutes`
+Lifecycle records activity when it deploys or redeploys the Environment.
+Viewing the Environment in the UI does not refresh that activity
+timestamp.
 
-How frequently the cleanup job runs to check for stale environments.
+For an open pull request, Lifecycle can clean up the Environment after the
+configured inactivity period.
 
-**Default:** `240` (4 hours)
-
-### `commentTemplate`
-
-Custom message posted to the PR when cleaning up. Supports `{inactivityDays}` placeholder and dynamic label replacements.
-
-**Default:** `"Tearing down lifecycle env since no activity in the past {inactivityDays} days."`
-
-### `excludedRepositories`
-
-Repository names (format: `owner/repo`) to exclude from automatic cleanup.
+<Callout type="warning">
+  Pull-request cleanup settings have no supported UI, typed API, or Helm value.
+  A deployment owner must use a supported operator procedure for the installed
+  release. The procedure can change the inactivity period or exclude
+  repositories. See [Runtime configuration
+  surfaces](/docs/operations/configuration). If no such procedure exists for the
+  installed release, do not change these settings.
+</Callout>
 
-**Default:** `[]`
+Closing a pull request can tear down the Environment without waiting for the
+inactivity period.
 
-<Callout type="warning">
-  Changes to TTL configuration require refreshing the global config cache or
-  waiting for the automatic refresh cycle.
+<Callout type="info">
+  Activity means deployment activity, not page views or ordinary application
+  traffic. To refresh the inactivity timestamp intentionally, redeploy the
+  Environment.
 </Callout>
 
----
+## API-created environments
 
-## How It Works
+An API Environment has an `expiresAt` timestamp. Its lease starts from the
+requested lifespan. The administrator's policy controls lease extensions.
 
-Lifecycle tracks environment expiration using `lfc/ttl-expireAtUnix` labels on Kubernetes namespaces. The cleanup service runs periodically to scan for expired environments, validates eligibility (PR is open, not static, not excluded), and tears down environments by removing the deploy label and adding the disabled label.
+The create form applies the current default and maximum lifespan. API clients
+can use `GET /api/v2/environments/policy` to get these values.
 
-### Preventing Cleanup
+See [API-created environments](/docs/features/api-environments) for creation,
+extension, and teardown.
 
-Add the `keep` label to a PR to prevent automatic cleanup. This disables TTL on the namespace and keeps the environment alive indefinitely. See [Configurable Labels](/docs/features/configurable-labels) to customize the keep label.
+## Keep an environment
 
----
+For a pull-request Environment, use the keep label defined by your
+administrator and repository workflow. For an API-created Environment, use the
+supported lease-extension action before `expiresAt`.
+
+A pull-request label does not change an API lease.
 
-## Summary
+## Troubleshooting
 
-| Property               | Type     | Purpose                            |
-| ---------------------- | -------- | ---------------------------------- |
-| `enabled`              | boolean  | Enable/disable automatic cleanup   |
-| `dryRun`               | boolean  | Test mode without actual cleanup   |
-| `inactivityDays`       | number   | Days of inactivity before cleanup  |
-| `checkIntervalMinutes` | number   | Cleanup job frequency in minutes   |
-| `commentTemplate`      | string   | Custom cleanup message for PRs     |
-| `excludedRepositories` | string[] | Repositories excluded from cleanup |
+- **An environment expired while I was viewing it:** page views do not refresh
+  pull-request activity or an API lease.
+- **A keep label had no effect:** Check the Environment type and configured
+  label. Then, check when the label was applied.
+- **An API extension was rejected:** The requested result can exceed the
+  maximum lifespan. The administrator can also disable API Environments.
+- **Cleanup started early:** Check whether the pull request closed or a user
+  requested teardown.
diff --git a/src/pages/docs/features/ignore-file-patterns.mdx b/src/pages/docs/features/ignore-file-patterns.mdx
index 75883cc3..9b38b879 100644
--- a/src/pages/docs/features/ignore-file-patterns.mdx
+++ b/src/pages/docs/features/ignore-file-patterns.mdx
@@ -1,6 +1,12 @@
 ---
 title: Ignore File Patterns
-description: Skip unnecessary push redeploys for documentation, metadata, and other non-runtime changes.
+description: Skip push redeploys for documentation, metadata, and other non-runtime changes.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - ignoreFiles
   - push
@@ -10,16 +16,30 @@ tags:
 
 import { Callout } from "nextra/components";
 
-## Use Case
+## Purpose
 
-Use `ignoreFiles` when changes to certain files should not redeploy an active
-Lifecycle environment. Common examples are docs, generated metadata, examples,
-or workflow files that do not affect a running service.
+When some file changes do not change a running Service, use `ignoreFiles` to
+prevent a redeploy. Examples are documentation, generated
+metadata, examples, and workflow files.
 
 <Callout type="info">
-  Lifecycle skips a push redeploy only when every changed file is ignored by
-  every active affected service. If Lifecycle cannot prove the push is safe to
-  skip, it redeploys.
+  Lifecycle skips a push redeploy only when all active related Services ignore
+  all changed files. If Lifecycle cannot prove the push is safe to skip, it
+  redeploys.
+</Callout>
+
+## Confirm availability
+
+An administrator must enable ignore-file enforcement for the deployment.
+When enforcement is off, Lifecycle redeploys even when all patterns match.
+
+<Callout type="warning">
+  This deployment switch has no supported UI, typed API, or Helm value. An
+  administrator must use a supported operator procedure for the installed
+  release. See [Runtime configuration surfaces](/docs/operations/configuration).
+  If no such procedure exists for the installed release, do not rely on
+  `ignoreFiles`. A correct repository configuration alone does not enable
+  enforcement.
 </Callout>
 
 ## Config
@@ -42,7 +62,7 @@ services:
     ignoreFiles:
       - "openapi/**"
     github:
-      repository: "lifecycle/web-app"
+      repository: "acme/web-app"
       branchName: "main"
       docker:
         defaultTag: "main"
@@ -51,7 +71,7 @@ services:
 
   - name: "frontend"
     github:
-      repository: "lifecycle/web-app"
+      repository: "acme/web-app"
       branchName: "main"
       docker:
         defaultTag: "main"
@@ -61,24 +81,24 @@ services:
 
 This config means:
 
-- `docs/**` and `**/*.md` apply to both `api` and `frontend`.
+- `docs/**` and `**/*.md` apply to `api` and `frontend`.
 - `openapi/**` applies only to `api`.
-- A push that changes only `docs/readme.md` can skip both services.
-- A push that changes only `openapi/schema.yaml` can skip only when every active
-  affected service ignores that path.
+- A push that changes only `docs/readme.md` can skip the two Services.
+- A push that changes only `openapi/schema.yaml` can skip only when all active
+  affected Services ignore that path.
 
 <Callout type="info">
-  Environment patterns are inherited by each service. Service patterns only
-  apply to that service.
+  Each Service inherits the Environment patterns. Service patterns apply only to
+  that Service.
 </Callout>
 
 ## Rules
 
-Patterns are matched against GitHub file paths.
+Lifecycle matches patterns against GitHub file paths.
 
 | Rule             | Example                                      |
 | ---------------- | -------------------------------------------- |
-| Use `/` paths    | `docs/setup.md`, not `docs\\setup.md`        |
+| Use `/` paths    | `docs/setup.md`                              |
 | Repo-relative    | `docs/**`, not `/docs/**`                    |
 | Case-sensitive   | `docs/**` does not match `Docs/guide.md`     |
 | Dotfiles match   | `.github/**` matches `.github/workflows.yml` |
@@ -86,10 +106,15 @@ Patterns are matched against GitHub file paths.
 
 <Callout type="warning">
   Paths are repo-relative and case-sensitive. `docs/**` and `Docs/**` are
-  different paths, and patterns should not start with `/`.
+  different paths. Patterns must not start with `/`.
 </Callout>
 
-Common patterns:
+Each Environment or Service list accepts at most 50 patterns. Each pattern can
+be at most 200 characters, cannot be empty, cannot start with `/`, and cannot
+contain a `..` path segment. Lifecycle redeploys if the policy data is not
+correct.
+
+Example patterns:
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -101,45 +126,49 @@ environment:
 ```
 
 <Callout type="warning">
-  Broad patterns like `**/*` are allowed, but use them only when the service
-  should ignore all push file changes from that repo.
+  Lifecycle accepts broad patterns such as `**/*`. Use them only when the
+  Service must ignore all push file changes from that repository.
 </Callout>
 
 ## Active Services
 
-Only active services affected by the pushed repository and branch need matching
+Only active Services that use the pushed repository and branch must match the
 ignore patterns.
 
 <Callout type="info">
-  Optional services only count when they are deployed in the current
-  environment. If `worker` is optional and not deployed, its `ignoreFiles`
-  config does not affect the skip decision.
+  Optional Services count only when they are deployed in the current
+  Environment. If `worker` is optional and not deployed, its `ignoreFiles`
+  config does not change the skip decision.
 </Callout>
 
-If one active affected service does not ignore a changed file, Lifecycle
-redeploys instead of skipping.
+If one active affected Service does not ignore a changed file, Lifecycle
+redeploys.
 
-## Always Redeploys
+## Changes that always cause a redeploy
 
 <Callout type="warning">
-  Lifecycle always redeploys when `lifecycle.yaml` or `lifecycle.yml` changes,
-  when the current deploy is already failing, and for static environments.
+  Lifecycle always redeploys when `lifecycle.yaml`, `lifecycle.yml`,
+  `.lifecycle.yaml`, or `.lifecycle.yml` changes, when the current deploy is in
+  a failure state, and for static Environments. Auto-tracked API Environments
+  also redeploy without this check.
 </Callout>
 
 Lifecycle also redeploys when:
 
-- a changed file does not match every active affected service's ignore patterns
+- a changed file does not match all related active Service ignore patterns
 - Lifecycle cannot safely read the changed file list
 
 ## Debug
 
 If a push redeployed when you expected it to skip, check:
 
-1. Did the push change `lifecycle.yaml` or `lifecycle.yml`?
-2. Did every changed file match the patterns exactly, including casing?
-3. Did every active affected service inherit or define a matching pattern?
-4. Is an optional service currently deployed in the environment?
-5. Is the current deploy already in an error state?
+1. If enforcement status is unknown, ask the deployment owner.
+2. Did the push change a supported Lifecycle configuration filename?
+3. Did all changed files match the patterns and letter case?
+4. Did all related active Services have a matching pattern?
+5. Is an optional Service active in the Environment?
+6. Is the current deploy in an error state?
+7. Is the Environment static or an auto-tracked API Environment?
 
-When in doubt, keep the pattern narrow. It is better to redeploy one extra time
-than to skip a change that affects a running service.
+If you are not sure that a pattern is safe, keep it narrow. One more
+redeploy is safer than a skipped runtime change.
diff --git a/src/pages/docs/features/lifecycle-ui.mdx b/src/pages/docs/features/lifecycle-ui.mdx
new file mode 100644
index 00000000..42e32255
--- /dev/null
+++ b/src/pages/docs/features/lifecycle-ui.mdx
@@ -0,0 +1,98 @@
+---
+title: Use the Lifecycle UI
+description: Use the web UI to find Environments, examine Services and logs, run actions, and examine webhooks.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - ui
+  - environment
+  - logs
+---
+
+import { Callout } from "nextra/components";
+import { Image } from "@lifecycle-docs/components";
+
+Use the Lifecycle UI to find the Environment that has a problem. Identify the
+failed Service and phase. Then select the applicable action.
+
+## Find an Environment
+
+Open **Environments** in the sidebar.
+
+- **My envs** starts with Environments for your linked GitHub identity. Select
+  **All envs** for the wider list.
+- Search by Environment ID, repository, pull request, branch, or author.
+- Filter by status to isolate active or failed Environments.
+- Pin an Environment you use often.
+- **New environment** creates an API-style Environment without a pull request
+  when an administrator enables that feature.
+
+If **New environment** says **Turned off by your admin**, use a pull request. An
+administrator can give information about API Environment access.
+
+<Image
+  src="/docs/features/lifecycle-ui/environment-list.png"
+  alt="Environments list with one torn-down Environment, search, scope controls, status filters, and the pin control."
+  width={1184}
+  height={386}
+  ratio={1184 / 386}
+/>
+
+If **New environment** is disabled, pull-request Environments continue to work.
+
+## Read Environment and Service status
+
+Open an Environment row. The Environment status summarizes the full run.
+Select a Service to see its build and deployment state.
+
+| Question                             | Open                 |
+| ------------------------------------ | -------------------- |
+| What is running and where?           | **Summary**          |
+| Why did the image build fail?        | **Console → Build**  |
+| Why did the workload fail to deploy? | **Console → Deploy** |
+| What is the application emitting?    | **Console → Pods**   |
+| Did an Environment webhook run?      | **Webhooks**         |
+
+Read the earliest actionable failure in the matching phase before retrying.
+See [status vocabulary](/docs/reference/statuses) for terminal and transitional
+states.
+
+## Change runtime Environment variables
+
+Use the Environment variable override dialog for an Environment-specific value.
+Overrides do not update `lifecycle.yaml`. Record shared configuration in the
+repository.
+
+Do not paste secrets into a screenshot, issue, or support message. Use the
+deployment's [cloud-secret reference](/docs/features/secrets) where that
+execution path supports it.
+
+## Run an action
+
+The **Actions** menu can expose:
+
+- **Redeploy** queues the Environment again.
+- **Destroy** tears down a non-static Environment.
+- **Update UUID** changes the human-readable Environment ID.
+- **Run webhooks** invokes the Environment's configured webhook actions.
+
+Your permissions and Environment state control the available actions. For a
+static Environment redeploy, you must type the requested text. You must unpin a
+static Environment before you destroy it.
+
+<Callout type="warning">
+  Redeploy and Destroy change running infrastructure. Before you continue, make
+  sure of the Environment ID and current state.
+</Callout>
+
+## Next steps
+
+- [Create a pull-request Environment](/docs/getting-started/create-environment)
+- [Create a PR-less Environment](/docs/features/api-environments)
+- [Troubleshoot a build](/docs/troubleshooting/build-issues)
+- [Troubleshoot a deployment](/docs/troubleshooting/deploy-issues)
+- [Configure and examine webhooks](/docs/features/webhooks)
diff --git a/src/pages/docs/features/mcp-integration.mdx b/src/pages/docs/features/mcp-integration.mdx
index 066ca716..7d551883 100644
--- a/src/pages/docs/features/mcp-integration.mdx
+++ b/src/pages/docs/features/mcp-integration.mdx
@@ -1,278 +1,130 @@
 ---
-title: MCP Integration
+title: Connect external MCP servers
+description: Add administrator-approved Model Context Protocol servers and complete authentication for each Lifecycle Agent user.
+audience:
+  - agent-user
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - ai
-  - agent
   - mcp
-  - tools
-  - integration
+  - integrations
+  - administration
 ---
 
 import { Callout } from "nextra/components";
 
-The **Model Context Protocol (MCP)** is an open standard that lets AI agents discover and call tools from external servers. Lifecycle supports MCP, so you can extend the [AI Agent](/docs/features/ai-agent) with tools beyond the built-in Kubernetes and GitHub capabilities.
-
-When you register an MCP server, Lifecycle connects to it, discovers the available tools, caches their definitions, and makes them available during chat sessions. MCP tools appear alongside built-in tools and work the same way.
+Model Context Protocol (MCP) lets Lifecycle Agent use tools from an external
+service. Administrators specify shared server settings. Individual users
+complete personal credentials or OAuth connections if necessary.
 
 <Callout type="info">
-  MCP servers must be reachable from the Lifecycle server at the configured URL.
-  Lifecycle validates connectivity whenever you create or update a server
-  configuration.
-</Callout>
-
-## Configuring MCP servers
-
-MCP server configurations are managed through the REST API. Each configuration includes these fields:
-
-| Field         | Type              | Required | Default    | Description                                                                                      |
-| ------------- | ----------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
-| `slug`        | `string`          | Yes      | —          | Unique identifier. Lowercase alphanumeric and hyphens, 1–100 chars, no leading/trailing hyphens. |
-| `name`        | `string`          | Yes      | —          | Human-readable display name.                                                                     |
-| `url`         | `string`          | Yes      | —          | Full URL of the MCP server endpoint.                                                             |
-| `scope`       | `string`          | Yes      | `"global"` | Either `"global"` or a repo full name (e.g. `"myorg/myrepo"`).                                   |
-| `description` | `string`          | No       | `null`     | Optional description of the server's purpose.                                                    |
-| `headers`     | `object`          | No       | `{}`       | HTTP headers sent with every request (e.g. auth tokens).                                         |
-| `envVars`     | `object`          | No       | `{}`       | Environment variables associated with this server.                                               |
-| `enabled`     | `boolean`         | No       | `true`     | Whether the server is active. Disabled servers are excluded from tool resolution.                |
-| `timeout`     | `number`          | No       | `30000`    | Timeout in milliseconds for handshake and tool calls.                                            |
-| `cachedTools` | `McpCachedTool[]` | Auto     | `[]`       | Auto-populated during connectivity validation with discovered tool definitions.                  |
-
-### Transport auto-negotiation
-
-Lifecycle automatically negotiates the transport protocol. It tries **StreamableHTTP** first, then falls back to **SSE (Server-Sent Events)**. If both fail, the connection is rejected with an error describing what went wrong.
-
-### Connectivity validation
-
-Lifecycle checks that the MCP server is reachable and returns at least one tool:
-
-- **On create** — Validation always runs. If the server is unreachable or returns zero tools, the request fails with `422`.
-- **On update** — Validation only runs when `url` or `headers` change. If neither changes, the existing cached tools are preserved.
-
-During validation, `cachedTools` is automatically populated with the tools discovered from the server.
-
----
-
-## Scoping and merge behavior
-
-MCP servers can be scoped at two levels:
-
-- **Global** (`scope: "global"`) — Available to all repositories.
-- **Per-repository** (`scope: "myorg/myrepo"`) — Available only to that specific repository.
-
-### Runtime merge
-
-When the AI Agent starts a session, Lifecycle resolves the effective set of MCP servers by combining:
-
-1. All **enabled global** servers (minus any in the repository's `disabledSlugs` list)
-2. All **enabled per-repository** servers for that build's repository
-
-The combined list gives the agent the full set of MCP tools.
-
-### Disabling global servers per-repository
-
-A repository can opt out of specific global MCP servers by adding their slugs to the `disabledSlugs` list. This prevents those servers from contributing tools for that repository without affecting others.
-
-<Callout>
-  For per-repository AI Agent settings (like `disabledSlugs`, excluded tools,
-  and custom rules), see [AI Agent
-  Configuration](/docs/features/ai-agent-configuration).
+  Your Lifecycle release and administrator policy control MCP availability.
+  **Tools & integrations** can be unavailable to some users.
 </Callout>
 
----
-
-## Managing MCP servers via API
-
-All endpoints are under `/api/v2/ai/config/mcp-servers`. Request and response bodies use JSON. Header values are redacted to `"******"` in all responses.
-
-### List servers
-
-```
-GET /api/v2/ai/config/mcp-servers?scope={scope}
-```
-
-Returns all MCP server configurations for the given scope. Defaults to `"global"` if `scope` is omitted.
-
-```json
-{
-  "status": "success",
-  "data": [
-    {
-      "id": 1,
-      "slug": "my-server",
-      "name": "My MCP Server",
-      "description": "Provides custom tools",
-      "url": "https://mcp.example.com",
-      "scope": "global",
-      "headers": { "Authorization": "******" }, // redacted in responses
-      "envVars": {},
-      "enabled": true,
-      "timeout": 30000,
-      "cachedTools": [
-        {
-          "name": "lookup_user",
-          "description": "Look up a user by ID",
-          "inputSchema": {
-            "type": "object",
-            "properties": { "userId": { "type": "string" } }
-          }
-        }
-      ],
-      "createdAt": "2025-01-15T10:00:00.000Z",
-      "updatedAt": "2025-01-15T10:00:00.000Z"
-    }
-  ]
-}
-```
-
-### Create a server
-
-```
-POST /api/v2/ai/config/mcp-servers
-```
-
-Registers a new MCP server. Lifecycle validates connectivity before saving.
-
-```json
-{
-  "slug": "my-server",
-  "name": "My MCP Server",
-  "url": "https://mcp.example.com",
-  "scope": "global",
-  "description": "Provides custom tools",
-  "headers": { "Authorization": "Bearer token123" }, // sent with every request
-  "enabled": true,
-  "timeout": 30000 // milliseconds
-}
-```
-
-Returns the created configuration (status `201`) with redacted headers and populated `cachedTools`.
-
-| Error | Cause                                                               |
-| ----- | ------------------------------------------------------------------- |
-| `400` | Missing required fields (`slug`, `name`, `url`)                     |
-| `409` | A server with the same slug already exists in the same scope        |
-| `422` | Slug validation failed, or server unreachable / returned zero tools |
-
-### Get a server by slug
-
-```
-GET /api/v2/ai/config/mcp-servers/{slug}?scope={scope}
-```
-
-Returns a single configuration with redacted headers. Defaults to `"global"` scope. Returns `404` if not found.
-
-### Update a server
-
-```
-PUT /api/v2/ai/config/mcp-servers/{slug}?scope={scope}
-```
-
-Only include the fields you want to change. If `url` or `headers` change, connectivity is re-validated.
-
-```json
-{
-  "name": "Updated Name",
-  "timeout": 60000 // bump timeout to 60 seconds
-}
-```
+## Understand shared and personal settings
 
-Returns the updated configuration. Returns `404` if not found, `422` if connectivity validation fails.
+An MCP integration has two layers:
 
-### Delete a server
+| Layer           | Managed by              | Examples                                                              |
+| --------------- | ----------------------- | --------------------------------------------------------------------- |
+| Shared server   | Lifecycle administrator | Name, transport, URL or command, shared arguments, allowed tools      |
+| User connection | Each user               | Personal access token, OAuth grant, or a different field for one user |
 
-```
-DELETE /api/v2/ai/config/mcp-servers/{slug}?scope={scope}
-```
+Lifecycle does not share secrets entered for a user with other users. Do not put
+a personal token into a shared URL, argument, or repository file.
 
-Soft-deletes the configuration. Returns `204` on success, `404` if not found.
+## Add a shared server
 
-### Health check
+1. Open **Settings**.
+2. Go to **Tools & integrations**.
+3. Add an MCP server or select an available preset.
+4. Select the server's documented transport:
+   - **HTTP**
+   - **SSE**
+   - **stdio**
+5. Enter only the connection fields supplied by the MCP service owner.
+6. Discover the advertised tools.
+7. Examine the advertised tools.
+8. Allow only the tools necessary for the intended workflow.
+9. Save the server.
+10. Test the server with an Agent session that contains no sensitive data.
 
-```
-GET /api/v2/ai/config/mcp-servers/health
-```
+Lifecycle does not auto-detect or negotiate a transport. A mismatched transport,
+URL, or stdio command prevents discovery.
 
-Checks connectivity for all enabled servers. Connects to each one, lists tools, and reports reachability. If the tool list changed since the last check, cached tools are automatically refreshed.
+## Complete a personal connection
 
-```json
-{
-  "healthy": true, // true only when ALL servers are reachable
-  "servers": [
-    {
-      "slug": "my-server",
-      "name": "My MCP Server",
-      "reachable": true,
-      "toolCount": 3,
-      "latencyMs": 245,
-      "error": null,
-      "cacheRefreshed": false // true if tools changed since last check
-    }
-  ]
-}
-```
+If authentication for each user is necessary for a shared server:
 
----
+1. Open **Settings**.
+2. Open **My connections**.
+3. Select the server.
+4. Enter the requested personal fields or complete the OAuth flow.
+5. Make sure that the connection operates correctly.
+6. Start a new Agent session so its tool list reflects the connection.
 
-## Tool naming and safety
+An administrator can make a shared server available to selected users and
+tools. Agent approval policy continues to apply after a connection operates
+correctly.
 
-### Naming convention
+## Recognize MCP tool names
 
-To avoid collisions between servers, MCP tools are exposed with a namespaced name:
+Lifecycle namespaces external tools to prevent collisions:
 
+```text
+mcp__<server_slug>__<tool_name>
 ```
-mcp__{slug}__{toolName}
-```
-
-For example, a tool called `lookup_user` from a server with slug `my-server` becomes `mcp__my-server__lookup_user`. The agent handles this automatically.
-
-### Safety mapping
 
-MCP tool annotations are mapped to Lifecycle safety levels that influence how the agent uses each tool:
+Lifecycle converts unsupported characters in the server slug to underscores.
+For example, a server slug `my-server` can expose
+`mcp__my_server__search`.
 
-| MCP Annotation          | Lifecycle Safety Level | What happens                            |
-| ----------------------- | ---------------------- | --------------------------------------- |
-| `destructiveHint: true` | `DANGEROUS`            | Description prefixed with `[DANGEROUS]` |
-| `readOnlyHint: true`    | `SAFE`                 | Description prefixed with `[SAFE]`      |
-| `openWorldHint: true`   | `CAUTIOUS`             | No prefix added                         |
-| No annotations          | `CAUTIOUS`             | Default safety level                    |
+## API routes
 
-Annotations are evaluated in priority order: `destructiveHint` takes precedence over `readOnlyHint`, which takes precedence over `openWorldHint`.
+The Settings UI is the primary management surface. Authenticated v2 routes
+include:
 
-### Error handling
+- `/api/v2/ai/config/mcp-presets`
+- `/api/v2/ai/config/mcp-servers`
+- `/api/v2/ai/agent/mcp-connections`
 
-MCP tool errors fall into three categories:
+Use the generated API reference from your deployment for methods and schemas.
+Lifecycle tests an MCP server through tool discovery. It does not use a
+`/health` route.
 
-| Error Code             | Trigger                                         | Recoverable |
-| ---------------------- | ----------------------------------------------- | ----------- |
-| `MCP_CONNECTION_ERROR` | Server unreachable, timeout, connection refused | Yes         |
-| `MCP_TOOL_ERROR`       | Tool returned an error result                   | Yes         |
-| `MCP_PROTOCOL_ERROR`   | JSON-RPC or protocol-level failure              | No          |
+## Security checklist
 
-Recoverable errors let the agent retry or suggest alternatives. Protocol errors indicate a fundamental compatibility issue between Lifecycle and the server.
+- Trust the MCP operator.
+- Make sure of the destinations for requests and data.
+- Before you allow discovered tools, examine their descriptions.
+- Require approval for external writes unless there is a documented reason not
+  to.
+- Store credentials only through the connection UI or approved secret system.
+- When access must end, revoke the upstream credential.
+- Revoke the Lifecycle connection.
+- After the upstream server changes its advertised tools, test the connection
+  again.
 
----
+<Callout type="warning">
+  An MCP tool can send Lifecycle context to a different system or make changes
+  in that system. Examine each tool description and approval policy before you
+  allow the tool.
+</Callout>
 
 ## Troubleshooting
 
-### Server fails connectivity check
-
-1. **Check the URL** — Confirm the URL is correct and reachable from the Lifecycle server.
-2. **Check the transport** — Your server must support StreamableHTTP or SSE. Stdio-only servers do not work with Lifecycle.
-3. **Check authentication** — If your server requires auth headers, make sure they are included in the `headers` field. Header values are redacted in responses, so you cannot read them back.
-4. **Check the timeout** — If the server is slow to respond, increase the `timeout` value.
-
-### Tools not appearing in the agent
-
-1. **Verify the server returns at least one tool** — Lifecycle rejects servers that expose zero tools during validation.
-2. **Check the `enabled` flag** — Disabled servers are excluded from tool resolution.
-3. **Check the scope** — A server scoped to a specific repo does not appear for builds in other repos.
-4. **Check `disabledSlugs`** — A repo-level configuration may be opting out of your global server.
-
-### Health check shows unreachable
-
-Run the health check endpoint to see the specific error message in the `error` field. Common causes include the server being down or network policies blocking traffic from Lifecycle pods.
-
-<Callout type="tip">
-  Use `GET /api/v2/ai/config/mcp-servers/health` to verify all servers are
-  reachable and their tool caches are current.
-</Callout>
+- **Discovery fails:** make sure of the explicit transport and the URL or stdio
+  command from the server owner.
+- **A user sees no tools:** make sure of the shared server, user connection,
+  discovered-tool allowlist, and Agent capability policy.
+- **OAuth cannot complete:** the administrator must make sure that the
+  registered redirect URI and upstream client configuration are correct.
+- **A changed tool is missing:** Rediscover the tools. Examine the new tool
+  description. Start a new Agent session.
+
+The Lifecycle MCP server has a different support boundary. See
+[Lifecycle MCP server](/docs/features/mcp-server).
diff --git a/src/pages/docs/features/mcp-server.mdx b/src/pages/docs/features/mcp-server.mdx
index de5ccb7b..b3923ff2 100644
--- a/src/pages/docs/features/mcp-server.mdx
+++ b/src/pages/docs/features/mcp-server.mdx
@@ -1,293 +1,200 @@
 ---
-title: MCP Server
+title: Lifecycle MCP
+description: Enable Lifecycle MCP, connect an OAuth client, and use Lifecycle tools with existing user permissions.
+audience:
+  - agent-user
+  - administrator
+  - platform-operator
+lastVerified: "2026-08-01"
+verificationBaseline: "2026-08-01-lifecycle-mcp-preparation"
+contentProfile: asd-ste100
 tags:
-  - ai
   - mcp
-  - tools
-  - claude
-  - cursor
-  - vscode
-  - codex
+  - oauth
+  - agents
+  - administration
 ---
 
-import { Callout, Steps } from "nextra/components";
+import { Callout } from "nextra/components";
 
-Lifecycle ships a built-in **MCP server** (Model Context Protocol — a standard way for AI
-assistants to call tools), so assistants like Claude Code, Cursor, VS Code, and Codex can look at
-your preview environments for you. Once connected, you can ask your AI tool things like:
+Lifecycle MCP lets external MCP clients use Lifecycle through one authenticated
+URL. Users add the URL, sign in with Lifecycle, and discover available tools.
 
-- _"Is the environment for my PR up? What's the frontend URL?"_
-- _"Why did the backend build fail in `snowy-field-978044`? Show me the logs."_
-- _"List my environments and tell me which ones errored."_
-
-The assistant answers by calling Lifecycle directly — no copy-pasting UUIDs, dashboards, or log
-snippets into the chat.
+Lifecycle MCP is different from an external MCP server that gives Lifecycle
+Agent more tools. See [Connect external MCP
+servers](/docs/features/mcp-integration) for that task.
 
 <Callout type="info">
-  Looking for the opposite direction — connecting **external** MCP servers to
-  Lifecycle's built-in [AI Agent](/docs/features/ai-agent)? See [MCP
-  Integration](/docs/features/mcp-integration).
+  Lifecycle MCP requires administrator enablement. It accepts OAuth bearer
+  tokens only.
 </Callout>
 
-## Connect your AI tool
+## Connect an MCP client
 
-Your Lifecycle MCP URL is your Lifecycle app host plus `/mcp` — for example
-`https://app.lifecycle.example.com/mcp`. If your admin has enabled dynamic client registration,
-that URL is all you need — registration and login happen automatically. Otherwise (the default),
-you also need an OAuth client ID from your admin — see
-[Without dynamic client registration](#without-dynamic-client-registration).
+Ask your administrator for the Lifecycle MCP URL. The URL ends with `/mcp`.
 
-<Callout type="info">
-  Two prerequisites: your Lifecycle admin must have the MCP server **enabled**,
-  and you need network access to your Lifecycle app host (e.g. VPN) — the same
-  reachability as the Lifecycle UI.
-</Callout>
+1. Add the URL as a remote HTTP MCP server in your client.
+2. Start the sign-in flow.
+3. Sign in with your Lifecycle account.
+4. Approve the requested access.
+5. Let the client discover the available tools.
 
-The first time you connect, your browser opens your organization's normal single sign-on page —
-the same login as the Lifecycle UI and `lfc` CLI — followed by a one-time consent screen. That's
-it. When your session eventually expires, just run the client's login step again.
+The client uses OAuth discovery and handles registration automatically. You do
+not configure an OAuth client, API key, token claim, or Keycloak object.
 
-### Claude Code
+Lifecycle applies your existing user permissions to every tool call. Lifecycle
+MCP does not grant access to an Environment, repository, Site, or action.
 
-```bash
-claude mcp add --transport http lifecycle https://app.lifecycle.example.com/mcp
-claude mcp login lifecycle
-```
+## Understand the available tools
 
-Or run `/mcp` inside a session and pick **lifecycle → Authenticate**.
+Lifecycle MCP groups its core tools into three capabilities. When Lifecycle
+Sites is enabled, clients also discover a fourth **View Hosted Sites**
+capability.
 
-### Cursor
+### Understand Environments
 
-Add the server to `~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`):
+| Tool                         | Result                                              |
+| ---------------------------- | --------------------------------------------------- |
+| `get_context`                | Shows useful Lifecycle context for the current user |
+| `list_repositories`          | Lists repositories that the user can access         |
+| `preview_environment_config` | Previews resolved Environment configuration         |
+| `validate_lifecycle_config`  | Validates Lifecycle configuration                   |
+| `list_environments`          | Lists visible Environments                          |
+| `get_environment`            | Gets bounded Environment state                      |
+| `wait_for_environment`       | Waits for a specified Environment state             |
 
-```json filename="~/.cursor/mcp.json"
-{
-  "mcpServers": {
-    "lifecycle": { "url": "https://app.lifecycle.example.com/mcp" }
-  }
-}
-```
+### Diagnose Environments
 
-Cursor shows a **Needs login** prompt next to the server in _Settings → MCP_; clicking it opens
-the browser sign-in.
+| Tool                   | Result                                       |
+| ---------------------- | -------------------------------------------- |
+| `diagnose_environment` | Summarizes likely Environment problems       |
+| `get_logs`             | Gets a bounded, redacted log tail            |
+| `get_kubernetes_state` | Gets bounded Kubernetes workload information |
 
-### VS Code
+### Manage Environments
 
-Add the server to `.vscode/mcp.json` in your workspace (or your user-level `mcp.json`):
+| Tool                    | Result                                    |
+| ----------------------- | ----------------------------------------- |
+| `create_environment`    | Creates an Environment                    |
+| `configure_environment` | Changes Environment configuration         |
+| `deploy_environment`    | Starts an Environment deployment          |
+| `extend_environment`    | Extends Environment expiration            |
+| `destroy_environment`   | Previews or destroys an exact Environment |
 
-```json filename=".vscode/mcp.json"
-{
-  "servers": {
-    "lifecycle": {
-      "type": "http",
-      "url": "https://app.lifecycle.example.com/mcp"
-    }
-  }
-}
-```
+### View Hosted Sites
 
-VS Code prompts you to trust and authenticate the server the first time Copilot Chat uses it.
+When Sites is enabled, these tools are available:
 
-### Codex CLI
+| Tool         | Result                |
+| ------------ | --------------------- |
+| `list_sites` | Lists visible Sites   |
+| `get_site`   | Gets one visible Site |
 
-Add the server to `~/.codex/config.toml`, then log in:
+An administrator can turn off all change tools. When change tools are off,
+clients do not discover them, and Lifecycle rejects their invocation.
 
-```toml filename="~/.codex/config.toml"
-[mcp_servers.lifecycle]
-url = "https://app.lifecycle.example.com/mcp"
-```
+## Use tools safely
 
-```bash
-codex mcp login lifecycle
-```
+Lifecycle rechecks administrator policy and user authorization for every tool
+call. Administrator policy can reduce access, but it cannot add user
+permissions.
 
-<Callout type="tip">
-  Try it with a prompt like _"using the lifecycle tools, list my environments"_.
-  Every tool call runs under your identity — the same login as the Lifecycle UI
-  — but note that this scopes filters, not visibility; see the note under [What
-  you can do](#what-you-can-do).
-</Callout>
+Environment reads return an immutable `environmentId`. Change and wait tools
+use that exact identifier instead of a reusable Environment name.
 
-## What you can do
+Environment reads and create or deploy receipts include a `lifecycleUiUrl`
+value. Open this URL to view the current deployment status in Lifecycle.
 
-All v1 tools are **read-only**: your assistant can look things up, but it cannot deploy, redeploy,
-delete, or change environment variables from here — use the Lifecycle UI or the `lfc` CLI for
-those.
+Environment creation uses an idempotency key. Other changes use the
+concurrency behavior of their underlying Lifecycle service.
 
-<Callout type="warning">
-  Like the REST API and UI, any authenticated user can read any build, service,
-  log, or site — `myEnvironmentsOnly`/`mineOnly` are convenience filters, not
-  access controls. If a preview environment's logs may contain sensitive output,
-  treat them as visible to all authenticated Lifecycle users.
-</Callout>
+Environment destruction uses two calls. The first call previews the exact
+Environment and returns a short-lived confirmation. The second call uses that
+confirmation.
 
-| Tool            | What it answers                                                                                    |
-| --------------- | -------------------------------------------------------------------------------------------------- |
-| `list_builds`   | "What environments exist?" — searchable, pageable, with a _my environments only_ filter            |
-| `get_build`     | "What's the status of environment X?" — services, URLs, branch, and PR details for one build       |
-| `list_services` | "Which services are in this environment, and where are they running?" — status, branch, image, URL |
-| `get_job_logs`  | "Why did the build/deploy fail?" — build-job or deploy-job logs, live from the cluster or archived |
-| `list_sites`    | "What static sites are published?"                                                                 |
-| `get_site`      | "Where is site X and when does it expire?"                                                         |
-
-It also exposes one MCP **resource**, `lifecycle://builds/{uuid}`, which returns a build's detail
-document as JSON for clients that support attaching resources.
-
-### Tool reference
-
-| Tool            | Parameters                                                                                                                                                                                                                 |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list_builds`   | `search` (string, optional) · `myEnvironmentsOnly` (boolean, optional) · `page` (int, optional) · `limit` (int, optional, default 25, max 100)                                                                             |
-| `get_build`     | `uuid` (string, required)                                                                                                                                                                                                  |
-| `list_services` | `uuid` (string, required)                                                                                                                                                                                                  |
-| `get_job_logs`  | `uuid` (string, required) · `service` (string, required) · `jobType` (`build` \| `deploy`, required) · `jobName` (string, optional — defaults to the most recent job) · `tailLines` (int, optional, default 200, max 2000) |
-| `list_sites`    | `mineOnly` (boolean, optional) · `page` (int, optional) · `limit` (int, optional, default 25, max 100)                                                                                                                     |
-| `get_site`      | `siteId` (string, required)                                                                                                                                                                                                |
-
-## How it works
-
-A one-page tour for the curious:
-
-1. **One endpoint on the web service.** The MCP server is part of the Lifecycle web deployment,
-   served over MCP's Streamable HTTP transport at `/mcp`. There is nothing extra to run — it reads
-   the same data the UI and API do, and it's stateless, so it scales with your web replicas.
-
-2. **Login is your normal SSO.** Lifecycle's Keycloak realm acts as the OAuth 2.1 authorization
-   server. When a tool connects for the first time it discovers the auth settings automatically
-   (via standard OAuth metadata), identifies itself to Keycloak — by registering itself when your
-   admin has enabled dynamic client registration, or with the client ID your admin pre-registered —
-   and sends you through the same browser single sign-on used by the UI and the `lfc` CLI. A
-   one-time consent screen shows what the tool is asking for.
-
-3. **Tokens only work here.** Access tokens issued for the MCP server are bound to its exact URL
-   (the OAuth _audience_). A CLI or UI token is rejected at `/mcp`, and an MCP token is rejected
-   by the REST API — one leaked token never unlocks the other surface.
-
-4. **Everything runs under your identity.** Each tool call executes under the identity in your
-   token, so filters like _my environments only_ use your account — though, as in the UI, any
-   authenticated user can read any environment (see [What you can do](#what-you-can-do)). Tool
-   output never includes service environment variables, which can contain secrets.
-
-## Setup (admins)
-
-Enabling the MCP server for your Lifecycle deployment is two switches — one on the app, one on
-Keycloak.
-
-<Steps>
-### Enable the endpoint on the web service
-
-Set two environment variables on the Lifecycle web deployment:
-
-```yaml filename="values.yaml (lifecycle chart, web component)"
-components:
-  web:
-    deployment:
-      extraEnv:
-        - name: MCP_SERVER_ENABLED
-          value: "true"
-        - name: MCP_RESOURCE_URL
-          value: "https://app.lifecycle.example.com/mcp"
-```
+Lifecycle bounds and redacts tool output. Treat repository content, logs, and
+Kubernetes events as untrusted evidence.
 
-`MCP_RESOURCE_URL` is the canonical URL clients will use — access tokens are audience-bound to
-this exact value, so it **must match** the `resourceUrl` you give Keycloak below, byte for byte
-(scheme, host, port, path). The endpoint is served only by the web process (`LIFECYCLE_MODE`
-`web`/`all`) and is absent unless `MCP_SERVER_ENABLED` is `true`.
-
-### Configure the Keycloak realm
-
-The realm needs an `mcp` client scope (with audience and identity mappers) and, optionally,
-anonymous dynamic client registration so tools can self-register. The `lifecycle-keycloak` chart
-does this for you with an idempotent post-install/post-upgrade job:
-
-```yaml filename="values.yaml (lifecycle-keycloak chart)"
-mcp:
-  enabled: true
-  resourceUrl: "https://app.lifecycle.example.com/mcp"
-  # Only when Keycloak is NOT reachable from the public internet — see the warning below.
-  dcr:
-    enabled: true
-  # Alternate URLs for the SAME deployment (e.g. in-cluster access, host dev server):
-  # extraAudiences:
-  #   - "http://lifecycle-web.lifecycle-app.svc.cluster.local/mcp"
-  #   - "http://localhost:8000/mcp"
-```
+## Enable Lifecycle MCP
+
+An administrator enables Lifecycle MCP from **Platform administration →
+Lifecycle MCP**.
 
-The Job is idempotent and runs on both fresh installs and existing realms, so a Helm upgrade with
-these values is all that's needed — no separate script to run by hand.
+The page shows:
+
+- whether Lifecycle MCP is on or off
+- the canonical MCP URL
+- an enable or disable control
+- the **Allow changes** control
+- capability and tool information
+- one actionable issue when enablement fails
+
+Enablement is one bounded request. Lifecycle configures the required Keycloak
+sign-in settings and verifies them against the MCP URL.
+
+Lifecycle stores the enabled setting only after verification succeeds. If
+enablement fails, Lifecycle keeps access off and shows one corrective action.
 
 <Callout type="warning">
-  All URLs listed (`resourceUrl` + `extraAudiences`) share a single token trust
-  boundary — an access token issued for one is accepted by all of them. Use
-  `extraAudiences` only for alternate URLs of the **same** deployment; do not
-  use it to share one realm across production and staging.
+  The first enablement makes a durable Keycloak realm configuration change.
+  Disabling Lifecycle MCP does not revert that configuration.
 </Callout>
 
-### Verify
+During enablement, Lifecycle can remove Keycloak's exact stock anonymous
+`Trusted Hosts` component. Lifecycle does not replace a customized or
+ambiguous component. A conflict keeps Lifecycle MCP off.
+
+Disabling Lifecycle MCP closes tool access. It does not delete registered
+OAuth clients, remove Lifecycle-managed Keycloak objects, or restore the stock
+`Trusted Hosts` component.
+
+When an administrator enables Lifecycle MCP again, Lifecycle reconciles and
+verifies the Keycloak configuration before it restores access.
 
-```bash
-curl https://app.lifecycle.example.com/.well-known/oauth-protected-resource/mcp
+The stored administrator policy has two fields:
+
+```json
+{
+  "enabled": false,
+  "allowChanges": false
+}
 ```
 
-should return the server's OAuth metadata, and connecting any MCP client to
-`https://app.lifecycle.example.com/mcp` should walk you through browser login.
-
-</Steps>
-
-<Callout type="error" emoji="⚠️">
-  **Anonymous dynamic client registration is off by default and one-way to
-  enable.** It lets anyone who can reach your Keycloak host register an OAuth
-  client (registering grants no access by itself — a real SSO login is still
-  required for tokens), and turning it on **deletes** the realm's anonymous
-  Trusted Hosts policy, which cannot be undone by disabling the setting later.
-  Only enable it (`mcp.dcr.enabled: true` in the chart, or
-  `--enable-anonymous-dcr` with the script) when Keycloak is **not** reachable
-  from the public internet. Otherwise leave it off and pre-register a client for
-  your users, as described below. Back up the realm first if you may want to
-  revert.
-</Callout>
+Use the Settings page for normal administration. The typed administrator API
+uses `GET /api/v2/config/mcp` and `PUT /api/v2/config/mcp`.
+
+## Prepare authentication
+
+For a new bundled Keycloak realm, the supported chart creates private API
+service credentials during the initial realm import. It does not configure the
+MCP OAuth contract.
+
+For an existing realm, a platform operator completes one management-client
+migration before enablement. Read [Adopt Lifecycle
+MCP](/docs/releases#adopt-lifecycle-mcp) for the migration steps.
+
+When an administrator enables Lifecycle MCP, Lifecycle API configures the
+fixed contract in bundled Keycloak. Normal MCP administration does not require
+a setup job or direct Keycloak changes.
+
+Provisioning does not turn on Lifecycle authentication. Before you enable
+Lifecycle MCP, enable normal Lifecycle authentication. See
+[Authentication](/docs/features/authentication).
+
+Lifecycle validates every token before it runs a tool. It also applies the
+stored administrator controls and the signed-in user's permissions.
+
+## Troubleshoot access
+
+| Symptom                                 | Action                                                          |
+| --------------------------------------- | --------------------------------------------------------------- |
+| The administrator cannot enable it      | Follow the corrective action on the Lifecycle MCP page.         |
+| Sign-in does not start                  | Confirm that the client supports remote HTTP MCP with OAuth.    |
+| A tool is missing                       | Check **Allow changes** and your permissions.                   |
+| A tool call is denied                   | Confirm that your Lifecycle account can perform the action.     |
+| An Environment change targets old state | Read the Environment again and use its current `environmentId`. |
+| A destructive confirmation expires      | Preview the destruction again.                                  |
+| Output is truncated                     | Narrow the request or use the Lifecycle UI, API, or CLI.        |
 
-### Without dynamic client registration
-
-When dynamic client registration stays disabled (the default), pre-register one OAuth client in
-the Lifecycle Keycloak realm and distribute its client ID to your users:
-
-1. In the realm, create a **public** client (no client secret) with the **Standard flow** enabled
-   and PKCE enforced (set _Proof Key for Code Exchange Code Challenge Method_ to `S256` in the
-   client's advanced settings).
-2. Turn on **Consent required** in the client's settings, so users get the same one-time consent
-   screen that dynamically registered clients show.
-3. Add the redirect URIs your users' MCP clients need — CLI tools typically use a localhost
-   callback such as `http://localhost:8080/callback`, while some editors use fixed HTTPS or
-   app-scheme callbacks. Check each client's documentation for its exact callback URL.
-4. Assign the `mcp` client scope to the client (as an optional client scope).
-5. Hand the client ID to your users.
-
-Support for pre-registered client IDs varies by MCP client, so check your client's documentation
-for its current state. At the time of writing:
-
-- **Claude Code** supports it — pass the ID and pin the callback port when adding the server, and
-  register the matching `http://localhost:8080/callback` redirect URI in Keycloak:
-
-  ```bash
-  claude mcp add --transport http --client-id <client-id> --callback-port 8080 \
-    lifecycle https://app.lifecycle.example.com/mcp
-  ```
-
-- **Cursor** supports it — add an `auth` object next to the server's `url` in `mcp.json` with
-  `"CLIENT_ID": "<client-id>"`, and register Cursor's fixed callbacks as redirect URIs:
-  `https://www.cursor.com/agents/mcp/oauth/callback` (web/cloud agents) and
-  `cursor://anysphere.cursor-mcp/oauth/callback` (desktop app).
-
-- **VS Code** and **Codex CLI** rely on dynamic client registration and do not currently document
-  a way to supply a pre-registered client ID — consult their documentation for updates.
-
-## Troubleshooting
-
-| Symptom                                                         | Likely cause                                                                                                                                                                                                 |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Client says the server needs authentication and nothing happens | Run the client's login step (`claude mcp login …`, `codex mcp login …`, or the login prompt in Cursor/VS Code settings)                                                                                      |
-| Browser login loops or shows `invalid_scope`                    | The Keycloak realm is missing the `mcp` client scope configuration — re-run the setup job or script                                                                                                          |
-| `401` with a valid login                                        | The token audience doesn't match `MCP_RESOURCE_URL` — make sure the URL configured in your client matches it exactly                                                                                         |
-| Tools list is empty or calls fail after login                   | The endpoint may be disabled (`MCP_SERVER_ENABLED`) on the web deployment                                                                                                                                    |
-| Registration rejected                                           | Dynamic client registration is disabled — the expected default. Use a pre-registered client ID (see [Without dynamic client registration](#without-dynamic-client-registration)) or ask your Lifecycle admin |
+Do not put OAuth tokens or client secrets in client configuration files,
+support messages, or logs.
diff --git a/src/pages/docs/features/native-helm-deployment.mdx b/src/pages/docs/features/native-helm-deployment.mdx
index 889538a4..0b261c45 100644
--- a/src/pages/docs/features/native-helm-deployment.mdx
+++ b/src/pages/docs/features/native-helm-deployment.mdx
@@ -1,6 +1,12 @@
 ---
-title: Native Helm Deployment
-description: Deploy services using Helm directly in Kubernetes without external CI/CD dependencies
+title: Native Helm deployment
+description: Deploy Services with Helm directly in Kubernetes without an external CI/CD deployment pipeline.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - helm
   - deployment
@@ -10,776 +16,270 @@ tags:
 
 import { Callout } from "nextra/components";
 
-**Native Helm** is an alternative deployment method that runs Helm deployments directly within Kubernetes jobs, eliminating the need for external CI/CD systems. This provides a more self-contained and portable deployment solution.
+Native Helm deploys a Helm release without an external CI/CD deployment
+pipeline. Lifecycle runs the deployment in the Environment namespace and shows
+its logs with the Service.
 
-<Callout type="info">
-  Native Helm deployment is an opt-in feature that can be enabled globally or
-  per-service.
-</Callout>
-
-## Overview
-
-When enabled, Native Helm:
-
-- Creates Kubernetes jobs to execute Helm deployments
-- Runs in ephemeral namespaces with proper RBAC
-- Provides real-time deployment logs via WebSocket
-- Handles concurrent deployments automatically
-- Supports all standard Helm chart types
-
-## Quickstart
-
-Want to try native Helm deployment? Here's the fastest way to get started:
-
-```yaml filename="lifecycle.yaml" {5}
-services:
-  - name: my-api
-    defaultUUID: "dev-0"
-    helm:
-      deploymentMethod: "native" # That's it!
-      chart:
-        name: "local"
-        valueFiles:
-          - "./helm/values.yaml"
-```
-
-This configuration:
-
-1. Enables native Helm for the `my-api` service
-2. Uses a local Helm chart from your repository
-3. Applies values from `./helm/values.yaml`
-4. Runs deployment as a Kubernetes job
-
-<Callout type="tip">
-  To enable native Helm for all services at once, see [Global
-  Configuration](#enabling-native-helm).
-</Callout>
+## Before you start
 
-## Configuration
+Make sure that these conditions are true:
 
-### Enabling Native Helm
+- Your Lifecycle deployment supports native Helm.
+- The Lifecycle deployment can pull the necessary Helm runner image.
+- The chart and its value files are available to Lifecycle.
+- The chart can operate with namespace-scoped permissions.
 
-There are two ways to enable native Helm deployment:
-
-#### Per Service Configuration
-
-Enable native Helm for individual services:
-
-```yaml {4} filename="lifecycle.yaml"
-services:
-  - name: my-service
-    helm:
-      deploymentMethod: "native" # Enable for this service only
-      chart:
-        name: my-chart
-```
-
-#### Global Configuration
-
-Enable native Helm for all services:
-
-```yaml {3} filename="lifecycle.yaml"
-helm:
-  nativeHelm:
-    enabled: true # Enable for all services
-```
-
-### Configuration Precedence
-
-Lifecycle uses a hierarchical configuration system with three levels of precedence:
-
-1. **helmDefaults** - Base defaults for all deployments (database: `global_config` table)
-2. **Chart-specific config** - Per-chart defaults (database: `global_config` table)
-3. **Service YAML config** - Service-specific overrides (highest priority)
-
-<Callout>
-  Service-level configuration always takes precedence over global defaults.
-</Callout>
+An operator can make native Helm the installation default. An explicit
+`helm.deploymentMethod` value for a Service takes precedence over that default.
 
-### Global Configuration (Database)
-
-Global configurations are stored in the `global_config` table in the database. Each configuration is stored as a row with:
-
-- **key**: The configuration name (e.g., 'helmDefaults', 'postgresql', 'redis')
-- **config**: JSON object containing the configuration
-
-#### helmDefaults Configuration
-
-Stored in database with key `helmDefaults`:
-
-```json
-{
-  "nativeHelm": {
-    "enabled": true,
-    "defaultArgs": "--wait --timeout 30m",
-    "defaultHelmVersion": "3.12.0",
-    "image": "registry.example.com/helm-runner:1.0.0",
-    "postRenderer": {
-      "enabled": true,
-      "command": "/opt/bin/post-renderer",
-      "args": ["--mode=preview"]
-    }
-  }
-}
-```
-
-**Field Descriptions**:
-
-- `enabled`: Enables default native Helm behavior in global config. Services still typically opt in with `deploymentMethod: "native"` or service-level native Helm settings.
-- `defaultArgs`: Arguments automatically appended to every Helm command (appears before service-specific args)
-- `defaultHelmVersion`: The Helm version to use when not specified at the service or chart level
-- `image`: Custom runner image for the native Helm job
-- `postRenderer.enabled`: Enables or disables the configured Helm post-renderer
-- `postRenderer.command`: Executable passed to Helm with `--post-renderer`
-- `postRenderer.args`: Arguments passed to Helm as repeated `--post-renderer-args` flags
-
-#### Chart-specific Configuration
-
-Example: PostgreSQL configuration stored with key `postgresql`:
-
-```json
-{
-  "version": "3.13.0",
-  "args": "--force --timeout 60m0s --wait",
-  "chart": {
-    "name": "postgresql",
-    "repoUrl": "https://charts.bitnami.com/bitnami",
-    "version": "12.9.0",
-    "values": ["auth.username=postgres_user", "auth.database=postgres_db"]
-  }
-}
-```
-
-<Callout type="info">
-  These global configurations are managed by administrators and stored in the
-  database. They provide consistent defaults across all environments and can be
-  overridden at the service level.
+<Callout type="warning">
+  A chart can create or change Kubernetes resources. Examine the chart, its
+  dependencies, and its values before deployment.
 </Callout>
 
-### Custom Runner Images and Post-Renderers
-
-Native Helm supports two related customization points:
-
-- `nativeHelm.image` changes the container image used for the Helm job
-- `nativeHelm.postRenderer` configures Helm's `--post-renderer` integration
-
-This keeps the model aligned with Helm itself: Lifecycle configures the runner
-image and optionally tells Helm which post-renderer executable to invoke.
-
-#### Global Defaults Only
-
-```json
-{
-  "nativeHelm": {
-    "enabled": true,
-    "defaultArgs": "--wait --timeout 30m",
-    "image": "registry.example.com/helm-runner:1.0.0"
-  }
-}
-```
-
-Services can then opt into native Helm without repeating the runner image:
-
-```yaml filename="lifecycle.yaml"
-services:
-  - name: api
-    helm:
-      deploymentMethod: "native"
-      chart:
-        name: "./charts/api"
-```
-
-#### Global Custom Image with Post-Renderer
-
-```json
-{
-  "nativeHelm": {
-    "enabled": true,
-    "image": "registry.example.com/helm-runner:1.0.0",
-    "postRenderer": {
-      "enabled": true,
-      "command": "/opt/bin/post-renderer",
-      "args": ["--mode=preview"]
-    }
-  }
-}
-```
-
-#### Service-Level Override
-
-Service config can override either the image or the post-renderer settings:
-
-```yaml filename="lifecycle.yaml"
-services:
-  - name: api
-    helm:
-      deploymentMethod: "native"
-      nativeHelm:
-        image: "registry.example.com/custom-runner:2.0.0"
-        postRenderer:
-          enabled: true
-          command: "/custom/bin/render"
-          args:
-            - "--tenant=preview"
-      chart:
-        name: "./charts/api"
-```
-
-#### Disable an Inherited Post-Renderer
+## Deploy a public chart
 
-If a post-renderer is defined globally, a service can explicitly disable it:
+This example deploys a public PostgreSQL chart:
 
 ```yaml filename="lifecycle.yaml"
-services:
-  - name: api
-    helm:
-      deploymentMethod: "native"
-      nativeHelm:
-        postRenderer:
-          enabled: false
-      chart:
-        name: "./charts/api"
-```
-
-<Callout type="info">
-  Custom runner images should include Helm and any post-renderer binary
-  referenced by `nativeHelm.postRenderer.command`. A common pattern is to start
-  from an existing Helm image and add your post-renderer binary on top.
-</Callout>
-
-<Callout type="info">
-  Repo-local post-renderer commands for public charts are not supported today
-  unless the deployment already clones the repository for another reason. For
-  public charts, prefer a post-renderer binary that already exists in the runner
-  image.
-</Callout>
-
-## Usage Examples
+version: "1.0.0"
 
-### Quick Experiment: Deploy Jenkins!
-
-Want to see native Helm in action? Let's deploy everyone's favorite CI/CD tool - Jenkins! This example shows how easy it is to deploy popular applications using native Helm.
-
-```yaml filename="lifecycle.yaml"
 environment:
   defaultServices:
-    - name: "my-app"
-    - name: "jenkins" # Add Jenkins to your default services
+    - name: "database"
 
 services:
-  - name: "jenkins"
+  - name: "database"
     helm:
+      deploymentMethod: "native"
+      version: "3.14.0"
       chart:
-        name: "jenkins"
+        name: "postgresql"
         repoUrl: "https://charts.bitnami.com/bitnami"
-        version: "13.6.8"
+        version: "12.9.0"
         values:
-          - "service.type=ClusterIP"
-          - "ingress.enabled=true"
-          - "ingress.hostname={{jenkins_publicUrl}}"
-          - "ingress.ingressClassName=nginx"
+          - "auth.database=preview"
+          - "primary.persistence.size=10Gi"
 ```
 
-<Callout type="info">
-  🎉 That's it! With just a few lines of configuration, you'll have Jenkins
-  running in your Kubernetes cluster.
-</Callout>
+The two `version` fields have different purposes:
 
-To access your Jenkins instance:
+- `helm.version` selects the Helm version for the deployment Job.
+- `helm.chart.version` selects the chart version.
 
-1. Check the deployment status in your PR comment
-2. Click the **Deploy Logs** link to monitor the deployment
-3. Once deployed, Jenkins will be available at the internal hostname
+Pin both versions. Before an upgrade, read the chart release notes and test the
+upgrade with non-sensitive data.
 
-<Callout type="tip">
-  For more Jenkins configuration options and values, check out the [Bitnami
-  Jenkins chart
-  documentation](https://github.com/bitnami/charts/tree/main/bitnami/jenkins).
-  This same pattern works for any Bitnami chart (PostgreSQL, Redis, MongoDB) or
-  any other public Helm chart!
-</Callout>
+## Deploy a chart from a repository
 
-### Basic Service Deployment
+Set the repository and branch for a chart that is in source control:
 
 ```yaml filename="lifecycle.yaml"
-services:
-  - name: web-api
-    helm:
-      deploymentMethod: "native"
-      chart:
-        name: web-app
-        version: "1.2.0"
-```
+version: "1.0.0"
 
-### PostgreSQL with Overrides
+environment:
+  defaultServices:
+    - name: "api"
 
-```yaml filename="lifecycle.yaml"
 services:
-  - name: database
+  - name: "api"
     helm:
       deploymentMethod: "native"
-      version: "3.14.0" # Override Helm version
-      args: "--atomic" # Override deployment args
+      version: "3.14.0"
+      repository: "docs-example/preview-app"
+      branchName: "main"
       chart:
-        name: postgresql
-        values: # Additional values merged with defaults
-          - "persistence.size=20Gi"
-          - "replicaCount=2"
+        name: "./charts/api"
+        valueFiles:
+          - "./charts/api/values-preview.yaml"
+        values:
+          - "replicaCount=1"
 ```
 
-### Custom Environment Variables
+Use paths relative to the checked-out repository. If the chart path or value
+file is missing, the deployment fails before Helm can apply the release.
+
+## Configuration reference
+
+These Service fields control a native Helm deployment:
+
+| Field                                | Purpose                                         |
+| ------------------------------------ | ----------------------------------------------- |
+| `helm.deploymentMethod`              | Select `native` or `ci` deployment              |
+| `helm.version`                       | Select the Helm version                         |
+| `helm.args`                          | Add Helm arguments for this Service             |
+| `helm.repository`                    | Select the chart source repository              |
+| `helm.branchName`                    | Select the chart source branch                  |
+| `helm.chart.name`                    | Set a chart name or relative chart path         |
+| `helm.chart.repoUrl`                 | Set the repository URL for a public chart       |
+| `helm.chart.version`                 | Select the chart version                        |
+| `helm.chart.values`                  | Add `key=value` settings                        |
+| `helm.chart.valueFiles`              | Add value files from the checked-out repository |
+| `helm.nativeHelm.image`              | Override the Helm runner image                  |
+| `helm.nativeHelm.postRenderer`       | Configure a post-renderer for this Service      |
+| `helm.nativeHelm.defaultArgs`        | Set fallback Helm arguments for this Service    |
+| `helm.nativeHelm.defaultHelmVersion` | Set a fallback Helm version for this Service    |
+
+Service configuration overrides matching installation defaults. If an operator
+manages a field centrally, get the approved value before you override it.
 
-Lifecycle supports flexible environment variable formatting through the `envMapping` configuration. This feature allows you to control how environment variables from your service configuration are passed to your Helm chart.
-
-<Callout type="info">
-  **Why envMapping?** Different Helm charts expect environment variables in
-  different formats. Some expect an array of objects with `name` and `value`
-  fields (Kubernetes standard), while others expect a simple key-value map. The
-  `envMapping` feature lets you adapt to your chart's requirements.
+<Callout type="warning">
+  Do not put a root-level `helm` block in `lifecycle.yaml`. Put Helm
+  configuration under each applicable `services[]` entry.
 </Callout>
 
-#### Default envMapping Configuration
-
-You can define default `envMapping` configurations in the `global_config` database table. These defaults apply to all services using that chart unless overridden at the service level.
-
-**Example: Setting defaults for your organization's chart**
-
-```json
-// In global_config table, key: "myorg-web-app"
-{
-  "chart": {
-    "name": "myorg-web-app",
-    "repoUrl": "https://charts.myorg.com"
-  },
-  "envMapping": {
-    "app": {
-      "format": "array",
-      "path": "deployment.containers[0].env"
-    }
-  }
-}
-```
+## Pass application environment values
 
-With this configuration, any service using the `myorg-web-app` chart will automatically use array format for environment variables:
+For a local chart with `helm.docker`, `helm.envMapping` maps Service environment
+values into chart values. Select the format that the chart expects.
 
-```yaml filename="lifecycle.yaml"
-services:
-  - name: api
-    helm:
-      deploymentMethod: "native"
-      chart:
-        name: "myorg-web-app" # Inherits envMapping from global_config
-      docker:
-        app:
-          env:
-            API_KEY: "secret"
-            # These will be formatted as array automatically
-```
+### Array format
 
-<Callout type="tip">
-  Setting `envMapping` in global_config is particularly useful when: - You have
-  a standard organizational chart used by many services - You want consistent
-  environment variable handling across services - You're migrating multiple
-  services and want to reduce configuration duplication
-</Callout>
-
-#### Array Format
+Use `array` for a chart that expects Kubernetes `name` and `value` entries:
 
-Best for charts that expect Kubernetes-style env arrays.
-
-```yaml {7-9} filename="lifecycle.yaml"
+```yaml filename="lifecycle.yaml"
 services:
-  - name: api
+  - name: "api"
     helm:
       deploymentMethod: "native"
+      version: "3.14.0"
+      repository: "docs-example/preview-app"
+      branchName: "main"
       chart:
-        name: local
+        name: "./charts/api"
       envMapping:
         app:
           format: "array"
-          path: "env"
+          path: "deployment.env"
       docker:
+        defaultTag: "main"
         app:
+          dockerfilePath: "services/api/Dockerfile"
           env:
-            DATABASE_URL: "postgres://localhost:5432/mydb"
-            API_KEY: "secret-key-123"
-            NODE_ENV: "production"
-```
-
-**This produces the following Helm values:**
-
-```bash
---set env[0].name=DATABASE_URL
---set env[0].value=postgres://localhost:5432/mydb
---set env[1].name=API_KEY
---set env[1].value=secret-key-123
---set env[2].name=NODE_ENV
---set env[2].value=production
+            API_MODE: "preview"
+            DATABASE_HOST: "{{{database_internalHostname}}}"
 ```
 
-**Your chart's values.yaml would use it like:**
-
-```yaml
-env:
-  - name: DATABASE_URL
-    value: postgres://localhost:5432/mydb
-  - name: API_KEY
-    value: secret-key-123
-  - name: NODE_ENV
-    value: production
-```
+Lifecycle adds entries under `deployment.env` for `API_MODE` and
+`DATABASE_HOST`.
 
-#### Map Format
+### Map format
 
-Best for charts that expect a simple key-value object.
+Use `map` for a chart that expects a key-value object:
 
-```yaml {7-9} filename="lifecycle.yaml"
+```yaml filename="lifecycle.yaml"
 services:
-  - name: api
+  - name: "api"
     helm:
       deploymentMethod: "native"
+      version: "3.14.0"
+      repository: "docs-example/preview-app"
+      branchName: "main"
       chart:
-        name: local
+        name: "./charts/api"
       envMapping:
         app:
           format: "map"
-          path: "envVars"
+          path: "config.environment"
       docker:
+        defaultTag: "main"
         app:
+          dockerfilePath: "services/api/Dockerfile"
           env:
-            DATABASE_URL: "postgres://localhost:5432/mydb"
-            API_KEY: "secret-key-123"
-            NODE_ENV: "production"
-```
-
-**This produces the following Helm values:**
-
-```bash
---set envVars.DATABASE__URL=postgres://localhost:5432/mydb
---set envVars.API__KEY=secret-key-123
---set envVars.NODE__ENV=production
+            API_MODE: "preview"
 ```
 
-<Callout type="warning">
-  Note: Underscores in environment variable names are converted to double
-  underscores (`__`) in map format to avoid Helm parsing issues.
-</Callout>
+In map format, Lifecycle changes each underscore in a variable name to two
+underscores. For example, `API_MODE` becomes `API__MODE`.
 
-**Your chart's values.yaml would use it like:**
+`envMapping` applies only to a local chart that has `helm.docker`
+configuration. It does not change values for a public chart.
 
-```yaml
-envVars:
-  DATABASE__URL: postgres://localhost:5432/mydb
-  API__KEY: secret-key-123
-  NODE__ENV: production
-```
+## Use secret-backed chart values
 
-#### Complete Example with Multiple Services
+Native Helm supports a cloud secret reference as the complete value after `=`.
+Lifecycle gives the secret value to Helm through a file.
 
 ```yaml filename="lifecycle.yaml"
 services:
-  # Service using array format (common for standard Kubernetes deployments)
-  - name: frontend
-    helm:
-      deploymentMethod: "native"
-      repository: "myorg/apps"
-      branchName: "main"
-      envMapping:
-        app:
-          format: "array"
-          path: "deployment.env"
-      chart:
-        name: "./charts/web-app"
-      docker:
-        app:
-          dockerfilePath: "frontend/Dockerfile"
-          env:
-            REACT_APP_API_URL: "https://api.example.com"
-            REACT_APP_VERSION: "{{{buildUUID}}}"
-
-  # Service using map format (common for custom charts)
-  - name: backend
+  - name: "database"
     helm:
       deploymentMethod: "native"
-      repository: "myorg/apps"
-      branchName: "main"
-      envMapping:
-        app:
-          format: "map"
-          path: "config.environment"
-      chart:
-        name: "./charts/api"
-      docker:
-        builder:
-          engine: "buildkit"
-        defaultTag: "main"
-        app:
-          dockerfilePath: "docker/backend.dockerfile"
-          ports:
-            - 3000
-          env:
-            NODE_ENV: "production"
-            SERVICE_NAME: "backend"
-
-  - name: "mysql-database"
-    helm:
-      deploymentMethod: "native"
-      repository: "myorg/api-services"
-      branchName: "main"
+      version: "3.14.0"
       chart:
-        name: "mysql" # Using public Helm chart
-        version: "9.14.1"
+        name: "postgresql"
         repoUrl: "https://charts.bitnami.com/bitnami"
-        valueFiles:
-          - "deploy/helm/mysql-values.yaml"
+        version: "12.9.0"
+        values:
+          - "auth.password={{aws:preview/database:password}}"
 ```
 
-<Callout type="info">
-  For supported template variables, see the [Template Variables
-  guide](/docs/features/template-variables).
-</Callout>
-
-## Chart Types
-
-Lifecycle automatically detects and handles three chart types:
+Partial secret interpolation is not supported. Put a complete composite value
+in the secret provider and reference that value directly.
 
-| Type          | Detection                                    | Features                                       |
-| ------------- | -------------------------------------------- | ---------------------------------------------- |
-| **ORG_CHART** | Matches `orgChartName` AND has `helm.docker` | Docker image injection, env var transformation |
-| **LOCAL**     | Name is "local" or starts with "./" or "../" | Flexible `envMapping` support                  |
-| **PUBLIC**    | Everything else                              | Standard labels and tolerations                |
-
-<Callout>
-  The `orgChartName` is configured in the database's `global_config` table with
-  key `orgChart`. This allows organizations to define their standard internal
-  Helm chart.
+<Callout type="warning">
+  Do not use `--debug` or `--dry-run` with secret-backed chart values. Lifecycle
+  rejects this combination because Helm can print rendered values.
 </Callout>
 
-## Troubleshooting
-
-### Deployment Fails with "Another Operation in Progress"
-
-**Symptom**: Helm reports an existing operation is blocking deployment
-
-**Solution**: Native Helm automatically handles this by killing existing jobs. If the issue persists:
-
-```bash
-# Check for stuck jobs
-kubectl get jobs -n env-{uuid} -l service={serviceName}
-
-# Force delete if needed
-kubectl delete job {jobName} -n env-{uuid} --force --grace-period=0
-```
-
-### Environment Variables Not Working
-
-**Symptom**: Environment variables not passed to the deployment
+See [Cloud secrets](/docs/features/secrets) for provider syntax and failure
+behavior.
 
-**Common Issues**:
+## Use a custom runner or post-renderer
 
-1. `envMapping` placed under `chart` instead of directly under `helm`
-2. Incorrect format specification (array vs map)
-3. Missing path configuration
-
-**Correct Configuration**:
-
-```yaml {4-7}
-helm:
-  deploymentMethod: "native"
-  chart:
-    name: local
-  envMapping: # Correct: directly under helm
-    app:
-      format: "array"
-      path: "env"
-```
-
-## Migration Example
-
-Here's a complete example showing how to migrate from GitHub-type services to Helm-type services:
-
-### Before: GitHub-type Services
+An approved runner image can contain a required plugin or post-renderer:
 
 ```yaml filename="lifecycle.yaml"
 services:
-  - name: "api-gateway"
-    github:
-      repository: "myorg/api-services"
-      branchName: "main"
-      docker:
-        builder:
-          engine: "buildkit"
-        defaultTag: "main"
-        app:
-          dockerfilePath: "docker/api.dockerfile"
-          env:
-            BACKEND_URL: "{{backend-service_internalHostname}}:3000"
-            LOG_LEVEL: "info"
-            ENV_NAME: "production"
-          ports:
-            - 8080
-      deployment:
-        public: true
-        resource:
-          cpu:
-            request: "100m"
-          memory:
-            request: "256Mi"
-        readiness:
-          tcpSocketPort: 8080
-        hostnames:
-          host: "example.com"
-          defaultInternalHostname: "api-gateway-prod"
-          defaultPublicUrl: "api.example.com"
-
-  - name: "backend-service"
-    github:
-      repository: "myorg/api-services"
-      branchName: "main"
-      docker:
-        builder:
-          engine: "buildkit"
-        defaultTag: "main"
-        app:
-          dockerfilePath: "docker/backend.dockerfile"
-          ports:
-            - 3000
-          env:
-            NODE_ENV: "production"
-            SERVICE_NAME: "backend"
-      deployment:
-        public: false
-        resource:
-          cpu:
-            request: "50m"
-          memory:
-            request: "128Mi"
-        readiness:
-          tcpSocketPort: 3000
-
-  - name: "mysql-database"
-    docker:
-      dockerImage: "mysql"
-      defaultTag: "8.0-debian"
-      ports:
-        - 3306
-      env:
-        MYSQL_ROOT_PASSWORD: "strongpassword123"
-        MYSQL_DATABASE: "app_database"
-        MYSQL_USER: "app_user"
-        MYSQL_PASSWORD: "apppassword456"
-      deployment:
-        public: false
-        resource:
-          cpu:
-            request: "100m"
-          memory:
-            request: "512Mi"
-        readiness:
-          tcpSocketPort: 3306
-        serviceDisks:
-          - name: "mysql-data"
-            mountPath: "/var/lib/mysql"
-            accessModes: "ReadWriteOnce"
-            storageSize: "10Gi"
+  - name: "api"
+    helm:
+      deploymentMethod: "native"
+      nativeHelm:
+        image: "registry.example.com/helm-runner:2.0.0"
+        postRenderer:
+          enabled: true
+          command: "/opt/bin/post-renderer"
+          args:
+            - "--mode=preview"
+      chart:
+        name: "./charts/api"
 ```
 
-### After: Helm-type Services with Native Deployment
+The runner image must contain Helm and the configured executable. The
+post-renderer must not depend on a repository file that the Job cannot access.
 
-```yaml filename="lifecycle.yaml"
-services:
-  - name: "api-gateway"
-    helm:
-      deploymentMethod: "native" # Enable native Helm
-      version: "3.14.0"
-      repository: "myorg/api-services"
-      branchName: "main"
-      args: "--wait --timeout 10m"
-      envMapping:
-        app:
-          format: "array"
-          path: "containers.api.env"
-      chart:
-        name: "./charts/microservices"
-        values:
-          - "service.type=LoadBalancer"
-          - "ingress.enabled=true"
-        valueFiles:
-          - "deploy/helm/base-values.yaml"
-          - "deploy/helm/api-gateway-values.yaml"
-      docker:
-        builder:
-          engine: "buildkit"
-        defaultTag: "main"
-        app:
-          dockerfilePath: "docker/api.dockerfile"
-          env:
-            BACKEND_URL: "{{{backend-service_internalHostname}}}:3000"
-            LOG_LEVEL: "info"
-            ENV_NAME: "production"
-          ports:
-            - 8080
+To disable an inherited post-renderer for one Service, set
+`helm.nativeHelm.postRenderer.enabled` to `false`.
 
-  - name: "backend-service"
-    helm:
-      deploymentMethod: "native"
-      version: "3.14.0"
-      repository: "myorg/api-services"
-      branchName: "main"
-      envMapping:
-        app:
-          format: "map" # Using map format for this service
-          path: "env"
-      chart:
-        name: "./charts/microservices"
-        values:
-          - "replicaCount=2"
-        valueFiles:
-          - "deploy/helm/base-values.yaml"
-          - "deploy/helm/backend-values.yaml"
-      docker:
-        builder:
-          engine: "buildkit"
-        defaultTag: "main"
-        app:
-          dockerfilePath: "docker/backend.dockerfile"
-          ports:
-            - 3000
-          env:
-            NODE_ENV: "production"
-            SERVICE_NAME: "backend"
+## Migrate a Service to native Helm
 
-  - name: "mysql-database"
-    helm:
-      deploymentMethod: "native"
-      repository: "myorg/api-services"
-      branchName: "main"
-      chart:
-        name: "mysql" # Using public Helm chart
-        version: "9.14.1"
-        repoUrl: "https://charts.bitnami.com/bitnami"
-        valueFiles:
-          - "deploy/helm/mysql-values.yaml"
-```
+For a Service that currently uses `github`, complete these changes:
 
-### Key Migration Points
+1. Replace the `github` block with a `helm` block.
+2. Move `repository` and `branchName` into the `helm` block.
+3. Set `deploymentMethod` to `native`.
+4. Set the Helm version.
+5. Add the chart name, version, values, and value files.
+6. If Lifecycle builds an image, keep the `docker` block under `helm`.
+7. If the local chart needs Service environment values, add `envMapping`.
+8. Validate `lifecycle.yaml`.
+9. Deploy the change in a test Environment.
 
-1. **Service Type Change**: Changed from `github:` to `helm:` configuration
-2. **Repository Location**: `repository` and `branchName` move from under `github:` to directly under `helm:`
-3. **Deployment Method**: Added `deploymentMethod: "native"` to enable native Helm
-4. **Chart Configuration**: Added `chart:` section with local or public charts
-5. **Environment Mapping**: Added `envMapping:` to control how environment variables are passed
-6. **Helm Arguments**: Added `args:` for Helm command customization
-7. **Docker Configuration**: Kept existing `docker:` config for build process
+Check the generated release, Service URL, readiness, and deployment logs. Do not
+remove the previous deployment path until the native Helm test succeeds.
 
-<Callout type="warning">
-  Note that when converting from GitHub-type to Helm-type services, the
-  `repository` and `branchName` fields move from being nested under `github:` to
-  being directly under `helm:`.
-</Callout>
+## Troubleshooting
 
-<Callout type="tip">
-  Many configuration options (like Helm version, args, and chart details) can be
-  defined in the `global_config` database table, making the service YAML
-  cleaner. Only override when needed.
-</Callout>
+- **Lifecycle does not use native Helm:** Check `helm.deploymentMethod`. Then,
+  ask the operator whether the release supports native Helm.
+- **The Helm version is missing:** Set `helm.version`. If the operator supplies
+  a custom runner, use the approved runner configuration.
+- **A local chart or value file is missing:** Check `repository`, `branchName`,
+  and each relative path.
+- **Environment values are absent:** Make sure that the chart is local and has
+  `helm.docker`. Check the `envMapping` format and path.
+- **Helm reports another operation in progress:** Examine the current Deploy
+  logs. If an earlier Job is stuck, give its Environment and Service names to
+  the operator.
+- **A secret-backed value fails:** Check the provider, path, key, and complete
+  value syntax. Remove `--debug` and `--dry-run`.
diff --git a/src/pages/docs/features/secrets.mdx b/src/pages/docs/features/secrets.mdx
index b98378b4..73d09cb3 100644
--- a/src/pages/docs/features/secrets.mdx
+++ b/src/pages/docs/features/secrets.mdx
@@ -1,566 +1,275 @@
 ---
-title: Cloud Secrets
+title: Cloud secrets
+description: Reference External Secrets Operator values from Lifecycle Services and native Helm deployments.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - secrets
   - aws
   - gcp
+  - barbican
   - environment variables
   - security
 ---
 
 import { Callout } from "nextra/components";
 
-## Overview
+Lifecycle can get cloud secrets through External Secrets Operator (ESO). You
+reference a secret in supported `lifecycle.yaml` fields. Lifecycle then gives
+the synchronized value to the applicable workload or pipeline.
 
-Lifecycle integrates with cloud secret providers to securely inject secrets into your ephemeral environments. You can reference secrets directly in your `lifecycle.yaml` environment variables and native Helm custom values using a template syntax, and Lifecycle handles the rest.
+## Before you start
 
-Supported providers:
+Get this information from your platform team:
 
-- **AWS Secrets Manager**
-- **GCP Secret Manager**
+- The provider prefix for your cluster
+- The secret paths that Lifecycle can read
+- The key name for each JSON secret
+- The expected secret refresh interval
 
-## Configuration
+Common provider prefixes are `aws`, `gcp`, and `barbican`. Use only a prefix
+that your platform team supports.
 
-Secret providers are configured in the Lifecycle `global_config` database table under the `secretProviders` key.
+The cluster must have ESO and a matching `ClusterSecretStore`. The store
+identity must have access to the requested secret path.
 
-### Default Configuration
+## Secret reference syntax
 
-Both AWS and GCP providers are **enabled by default**. The ClusterSecretStore created by your platform team determines which provider actually works in your cluster.
+Use this syntax for a JSON secret:
 
-```json
-{
-  "secretProviders": {
-    "aws": {
-      "enabled": true,
-      "clusterSecretStore": "aws-secretsmanager",
-      "refreshInterval": "1h",
-      "allowedPrefixes": []
-    },
-    "gcp": {
-      "enabled": true,
-      "clusterSecretStore": "gcp-secretmanager",
-      "refreshInterval": "1h",
-      "allowedPrefixes": []
-    }
-  }
-}
-```
-
-- **On AWS (EKS):** Use `{{aws:path:key}}` syntax. The `aws-secretsmanager` ClusterSecretStore handles the request.
-- **On GCP (GKE):** Use `{{gcp:path:key}}` syntax. The `gcp-secretmanager` ClusterSecretStore handles the request.
-
-If you reference a provider that doesn't have a ClusterSecretStore in your cluster, the secret will fail to sync and a warning will be logged.
-
-### Configuration Fields
-
-| Field                | Required | Description                                                        |
-| -------------------- | -------- | ------------------------------------------------------------------ |
-| `enabled`            | Yes      | Enable this provider                                               |
-| `clusterSecretStore` | Yes      | Name of the ClusterSecretStore CR configured by your platform team |
-| `refreshInterval`    | Yes      | How often ESO syncs secrets (e.g., `1h`, `30m`)                    |
-| `allowedPrefixes`    | No       | Restrict which secret paths can be referenced (empty = allow all)  |
-
-<Callout type="info">
-  If you're unsure which `clusterSecretStore` to use, check with your platform
-  team. They configure the External Secrets Operator and ClusterSecretStore as
-  part of cluster setup.
-</Callout>
-
-## Syntax
-
-Reference secrets using the following pattern:
-
-```
+```text
 {{<provider>:<secret-path>:<key>}}
 ```
 
-| Component     | Description                           | Example                      |
-| ------------- | ------------------------------------- | ---------------------------- |
-| `provider`    | Cloud provider (`aws` or `gcp`)       | `aws`                        |
-| `secret-path` | Full path to the secret               | `myapp/database-credentials` |
-| `key`         | JSON key within the secret (optional) | `password`                   |
-
-<Callout type="info">
-  If your secret is a plaintext value (not JSON), omit the key portion: `
-  {"{{aws:myapp/api-key}}"}`.
-</Callout>
-
-## Basic Usage
-
-### JSON Secrets
-
-For secrets stored as JSON objects, specify the key to extract:
-
-```yaml
-services:
-  - name: api-server
-    github:
-      repository: myorg/api-server
-      branchName: main
-      docker:
-        app:
-          env:
-            DB_PASSWORD: "{{aws:myapp/rds-credentials:password}}"
-            DB_USERNAME: "{{aws:myapp/rds-credentials:username}}"
-            DB_HOST: "{{aws:myapp/rds-credentials:host}}"
-```
-
-If your AWS secret `myapp/rds-credentials` contains:
+Use this syntax for a plain-text secret:
 
-```json
-{
-  "username": "admin",
-  "password": "supersecret",
-  "host": "db.example.com"
-}
+```text
+{{<provider>:<secret-path>}}
 ```
 
-Your pod will receive:
-
-- `DB_USERNAME=admin`
-- `DB_PASSWORD=supersecret`
-- `DB_HOST=db.example.com`
-
-### Plaintext Secrets
-
-For secrets stored as plain strings, omit the key:
+For example:
 
 ```yaml
 env:
-  STRIPE_API_KEY: "{{aws:myapp/stripe-key}}"
+  DB_USERNAME: "{{aws:preview/orders-database:username}}"
+  DB_PASSWORD: "{{aws:preview/orders-database:password}}"
+  API_TOKEN: "{{gcp:preview/orders-api-token}}"
 ```
 
-### Nested JSON
-
-For nested JSON structures, use dot notation:
+The reference must not contain spaces. Provider names, paths, and keys are
+case-sensitive.
 
-```yaml
-env:
-  REDIS_HOST: "{{aws:myapp/cache-config:redis.host}}"
-  REDIS_PORT: "{{aws:myapp/cache-config:redis.port}}"
-```
+<Callout type="warning">
+  Do not commit a secret value to `lifecycle.yaml`. Commit only the secret
+  reference.
+</Callout>
 
-For a secret containing:
+## Use secrets in a Service
 
-```json
-{
-  "redis": {
-    "host": "redis.example.com",
-    "port": "6379"
-  }
-}
-```
+Lifecycle resolves secret references in supported Service environment blocks.
+This example uses a GitHub Service:
 
-## Where Secrets Work
+```yaml filename="lifecycle.yaml"
+version: "1.0.0"
 
-The secret syntax works in all `env` blocks and in native Helm custom values:
-
-### GitHub Services
+environment:
+  defaultServices:
+    - name: "api"
 
-```yaml
 services:
-  - name: my-service
+  - name: "api"
     github:
+      repository: "docs-example/orders-api"
+      branchName: "main"
       docker:
+        defaultTag: "main"
         app:
+          dockerfilePath: "Dockerfile"
           env:
-            SECRET_KEY: "{{aws:path:key}}"
-        init:
-          env:
-            INIT_SECRET: "{{aws:path:key}}"
+            DB_USERNAME: "{{aws:preview/orders-database:username}}"
+            DB_PASSWORD: "{{aws:preview/orders-database:password}}"
 ```
 
-### Docker Services
+You can also use the syntax in these Service locations:
 
-```yaml
-services:
-  - name: my-service
-    docker:
-      dockerImage: myorg/image
-      defaultTag: latest
-      env:
-        SECRET_KEY: "{{aws:path:key}}"
-```
+- `github.docker.app.env`
+- `github.docker.init.env`
+- `docker.env`
+- `helm.docker.app.env`
+- `helm.docker.init.env`
+- Codefresh Service `env`
+- Native Helm `chart.values`
 
-### Webhooks
+For Service environment blocks, Lifecycle adds the synchronized values to the
+workload environment.
 
-```yaml
-environment:
-  webhooks:
-    - name: run-migrations
-      state: deployed
-      type: docker
-      docker:
-        image: myorg/migrator:latest
-      env:
-        DB_ADMIN_PASSWORD: "{{aws:myapp/rds-credentials:admin_password}}"
-```
+If a Service secret reference is invalid, Lifecycle can log a warning. The
+Service can fail because the necessary value is unavailable.
 
-<Callout type="warning">
-  Codefresh Helm deployments do not support cloud secrets in Helm custom values.
-  Use native Helm deployment for secret-backed Helm values.
-</Callout>
-
-### Native Helm Custom Values
+## Use secrets with Codefresh
 
-Native Helm deployments support full-value secret references in `helm.chart.values`.
-Lifecycle mounts the synced Kubernetes Secret into the Helm job and passes the
-value with Helm `--set-file`, so the resolved secret value is read from a file
-instead of being written into the Helm command.
+A Codefresh Service can use complete secret references in nested `env` objects
+or arrays:
 
-```yaml
+```yaml filename="lifecycle.yaml"
 services:
-  - name: postgres
-    helm:
-      repository: myorg/orders-api
-      branchName: main
-      deploymentMethod: native
-      chart:
-        name: postgresql
-        repoUrl: https://charts.example.com
-        values:
-          - "auth.username={{aws:myapp/postgres:username}}"
-          - "auth.password={{aws:myapp/postgres:password}}"
-          - "auth.database=orders"
+  - name: "legacy-api"
+    codefresh:
+      repository: "docs-example/legacy-api"
+      branchName: "main"
+      env:
+        API_TOKEN: "{{aws:preview/legacy-api:token}}"
+        DATABASE:
+          username: "{{gcp:preview/database:username}}"
+          password: "{{gcp:preview/database:password}}"
+      deploy:
+        pipelineId: "deploy-pipeline-id"
+      destroy:
+        pipelineId: "destroy-pipeline-id"
 ```
 
-Lifecycle renders the plain value normally and turns the secret-backed values
-into `--set-file` arguments:
-
-```bash
-helm upgrade --install postgres bitnami/postgresql \
-  --set auth.database=orders \
-  --set-file auth.username=/var/run/lifecycle/helm-secrets/.../helm.auth.username... \
-  --set-file auth.password=/var/run/lifecycle/helm-secrets/.../helm.auth.password...
-```
+Lifecycle resolves the values before it starts the Codefresh pipeline. If a
+value cannot resolve, Lifecycle does not start the pipeline.
 
-Only complete Helm values can be secret references:
+Codefresh Helm deployments do not support secret references in
+`helm.chart.values`. Use native Helm for secret-backed chart values.
 
-```yaml
-chart:
-  values:
-    # Correct
-    - "auth.password={{aws:myapp/postgres:password}}"
+## Use secrets with native Helm
 
-    # Wrong: partial interpolation is not supported for Helm secret values
-    - "databaseUrl=postgres://app:{{aws:myapp/postgres:password}}@postgres:5432/orders"
-```
+For native Helm, the complete value after `=` can be a secret reference:
 
-For composite values, put the full value in your cloud secret and reference it
-directly:
-
-```yaml
-chart:
-  values:
-    - "databaseUrl={{aws:myapp/postgres:databaseUrl}}"
-```
-
-Native Helm custom values can still use regular Lifecycle template variables:
-
-```yaml
+```yaml filename="lifecycle.yaml"
 services:
-  - name: api
-    requires:
-      - name: postgres
+  - name: "database"
     helm:
-      deploymentMethod: native
+      deploymentMethod: "native"
+      version: "3.14.0"
       chart:
-        name: api
+        name: "postgresql"
+        repoUrl: "https://charts.bitnami.com/bitnami"
+        version: "12.9.0"
         values:
-          - "env.DATABASE_HOST={{postgres_internalHostname}}"
-          - "env.DATABASE_PASSWORD={{aws:myapp/postgres:password}}"
+          - "auth.username={{aws:preview/orders-database:username}}"
+          - "auth.password={{aws:preview/orders-database:password}}"
+          - "auth.database=orders"
 ```
 
-If the same Helm key is set more than once, Lifecycle resolves the final winning
-value first, then decides whether to pass it with `--set` or `--set-file`:
+Lifecycle gives secret-backed values to Helm through files. Plain values use
+the usual Helm value argument.
+
+Partial secret interpolation is not supported:
 
 ```yaml
 chart:
   values:
-    # Secret value wins because it is later
-    - "env.API_TOKEN={{api_internalHostname}}"
-    - "env.API_TOKEN={{aws:myapp/api:token}}"
-
-    # Template value wins because it is later
-    - "env.CALLBACK_HOST={{aws:myapp/api:callbackHost}}"
-    - "env.CALLBACK_HOST={{api_internalHostname}}"
-```
-
-In the first pair, Lifecycle emits `--set-file env.API_TOKEN=...`. In the
-second pair, Lifecycle emits `--set env.CALLBACK_HOST=...`.
-
-<Callout type="warning">
-  Do not add Helm `--debug` or `--dry-run` args when using secret-backed Helm
-  values. Lifecycle rejects those combinations because Helm can print rendered
-  values into job logs.
-</Callout>
-
-## Mixing Secrets with Template Variables
-
-You can combine cloud secrets with regular template variables in the same `env` block:
-
-```yaml
-env:
-  # Cloud secret
-  DB_PASSWORD: "{{aws:myapp/rds-credentials:password}}"
-
-  # Template variable (service reference)
-  BACKEND_URL: "{{{backend_publicUrl}}}"
-
-  # Static value
-  APP_ENV: "ephemeral"
+    # Supported
+    - "databaseUrl={{aws:preview/orders-database:databaseUrl}}"
 
-  # Build context
-  BUILD_UUID: "{{{buildUUID}}}"
+    # Not supported
+    - "databaseUrl=postgres://user:{{aws:preview/orders-database:password}}@database/orders"
 ```
 
-## Multiple Providers
-
-Both providers are enabled by default. If your platform team has configured ClusterSecretStores for both AWS and GCP, you can reference secrets from either in the same deployment:
-
-```yaml
-env:
-  AWS_SECRET: "{{aws:myapp/aws-config:key}}"
-  GCP_SECRET: "{{gcp:my-project/gcp-config:key}}"
-```
-
-<Callout type="info">
-  Each provider requires its own ClusterSecretStore. Contact your platform team
-  if you need multi-cloud secret access.
-</Callout>
-
-## Error Handling
-
-Lifecycle uses a "warn and continue" approach for secret errors:
-
-| Scenario                           | Behavior                                              |
-| ---------------------------------- | ----------------------------------------------------- |
-| Secret not found                   | Warning logged, env var not set, deployment continues |
-| Key not found in JSON              | Warning logged, env var not set                       |
-| Provider not enabled               | Warning logged, env var not set                       |
-| Invalid syntax                     | Validation error at deploy time                       |
-| Partial Helm secret interpolation  | Validation error at deploy time                       |
-| Helm value secret ref on Codefresh | Unsupported deploy path error                         |
+For a composite value, store the complete value with the provider. Then,
+reference that value directly.
 
 <Callout type="warning">
-  If a required secret is missing, your application may fail to start or behave
-  unexpectedly. Always verify your secrets exist before deploying.
+  Do not add `--debug` or `--dry-run` to a native Helm deployment with secret
+  values. Lifecycle rejects this combination because Helm can print rendered
+  values.
 </Callout>
 
-## Best Practices
-
-### Use Descriptive Secret Paths
-
-Organize secrets with meaningful paths:
-
-```yaml
-# Good
-DB_PASSWORD: "{{aws:myorg/api-server/production/database:password}}"
-
-# Less clear
-DB_PASSWORD: "{{aws:db-creds:password}}"
-```
-
-### Group Related Secrets
-
-Store related credentials in a single JSON secret:
+See [Native Helm deployment](/docs/features/native-helm-deployment) for the
+complete Service configuration.
 
-```json
-// myapp/database-credentials
-{
-  "host": "db.example.com",
-  "port": "5432",
-  "username": "app_user",
-  "password": "secret123",
-  "database": "myapp"
-}
-```
-
-Then reference individual keys:
-
-```yaml
-env:
-  DB_HOST: "{{aws:myapp/database-credentials:host}}"
-  DB_PORT: "{{aws:myapp/database-credentials:port}}"
-  DB_USER: "{{aws:myapp/database-credentials:username}}"
-  DB_PASS: "{{aws:myapp/database-credentials:password}}"
-  DB_NAME: "{{aws:myapp/database-credentials:database}}"
-```
-
-### Avoid Secrets in Build Logs
-
-Be cautious when using secrets in build-time environment variables, as they may appear in build logs. Prefer injecting secrets at runtime when possible.
-
-## Troubleshooting
-
-### Secret Not Injected
+## Understand unsupported locations
 
-1. **Check the secret exists** in AWS Secrets Manager / GCP Secret Manager
-2. **Verify the path** matches exactly (case-sensitive)
-3. **Check the key name** if using JSON secrets
-4. **Review Lifecycle logs** for warnings about missing secrets
-5. **Verify provider is enabled** in global configuration
+Webhook `env` does not resolve cloud secret references. The webhook receives
+the reference as text.
 
-### Syntax Errors
+If a webhook needs credentials, use a credential mechanism that its Job or
+pipeline supports. Do not put a secret-bearing URL in `lifecycle.yaml`.
 
-Common syntax mistakes:
+## Understand native image builds
 
-```yaml
-# Wrong - spaces in pattern
-DB_PASSWORD: "{{ aws:path:key }}"
-
-# Wrong - trailing colon
-DB_PASSWORD: "{{aws:path:}}"
-
-# Wrong - missing provider
-DB_PASSWORD: "{{path:key}}"
-
-# Correct
-DB_PASSWORD: "{{aws:path:key}}"
-```
-
-For native Helm custom values, the whole value after `=` must be the secret
-reference:
-
-```yaml
-chart:
-  values:
-    # Wrong - partial Helm secret interpolation
-    - "auth.password=prefix-{{aws:path:key}}"
-
-    # Correct
-    - "auth.password={{aws:path:key}}"
-```
-
-### Permission Denied
-
-If you see permission errors:
-
-1. Verify the External Secrets Operator has access to the secret path
-2. Check IAM policies allow access to the specific secret
-3. Contact your platform team if the secret is in a restricted path
-
-### Wrong Provider for Cluster
-
-If you use `{{gcp:...}}` on an AWS cluster (or vice versa), the ExternalSecret will fail to sync because the ClusterSecretStore doesn't exist. Check Lifecycle logs for warnings like "ClusterSecretStore not found".
-
-## Prerequisites
-
-For cloud secrets to work, your platform team must set up:
-
-| Component                     | Description                                                                    |
-| ----------------------------- | ------------------------------------------------------------------------------ |
-| **External Secrets Operator** | Kubernetes operator that syncs secrets from cloud providers                    |
-| **ClusterSecretStore**        | CR that configures ESO to connect to AWS Secrets Manager or GCP Secret Manager |
-| **IAM/Workload Identity**     | Permissions for ESO to read secrets (IRSA for AWS, Workload Identity for GCP)  |
-
-The `clusterSecretStore` value in your Lifecycle config must match the ClusterSecretStore name configured by your platform team.
-
-## Build-Time Secrets
-
-The cloud secrets described above are **runtime secrets** — they get mounted into your running pods. Lifecycle also supports **build-time secrets**, which are injected during the Docker image build as build arguments.
-
-You use the same `{{provider:path:key}}` syntax. The difference is where the secret is consumed: build-time secrets are available during `docker build`, while runtime secrets are mounted into the final running container.
-
-Common use cases:
-
-- **Private NPM registry tokens** (e.g., `NPM_TOKEN` for `.npmrc`)
-- **Private package repository credentials**
-- **License keys** required during compilation
-- **Authentication tokens** for private base images
-
-### Configuration
-
-Define build-time secrets in the `env` block of your service's `docker` configuration, just like runtime secrets:
-
-```yaml
-services:
-  - name: my-service
-    github:
-      repository: myorg/my-service
-      branchName: main
-      docker:
-        app:
-          env:
-            # Build-time secret from AWS Secrets Manager
-            NPM_TOKEN: "{{aws:myorg/npm-registry:token}}"
-            # Another build-time secret
-            ARTIFACTORY_PASSWORD: "{{aws:myorg/artifactory:password}}"
-```
-
-Your `Dockerfile` then references them as build arguments:
+For native BuildKit and Kaniko builds, a Service environment secret is also a
+Docker build argument. The Dockerfile receives the value only if it declares a
+matching `ARG`.
 
 ```dockerfile
 FROM node:20-alpine
+
 ARG NPM_TOKEN
-RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
-RUN npm install
-RUN rm -f .npmrc
+RUN set -eu; \
+    printf '%s\n' "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /tmp/npmrc; \
+    npm_config_userconfig=/tmp/npmrc npm ci; \
+    rm -f /tmp/npmrc
 ```
 
-### How It Works
-
-When you reference a `{{provider:path:key}}` value in a build service's `env` block, Lifecycle resolves the secret from your cloud provider before the build starts. The resolved values are passed to Docker as build arguments (`--build-arg`), making them available as `ARG` variables in your Dockerfile.
-
-Lifecycle waits for the secret to sync before starting the build, so you don't need to worry about race conditions with the External Secrets Operator.
-
-<Callout type="info">
-  Both Buildkit and Kaniko build engines support build-time secrets. The secret
-  resolution process is the same regardless of which engine you use.
-</Callout>
-
-### Security Considerations
-
 <Callout type="warning">
-  Build-time secrets are **not masked** in build logs. Any `RUN` command that
-  prints environment variables (e.g., `echo $NPM_TOKEN`, `env`, `printenv`) will
-  expose secret values in the build output. Build logs are fetched on-demand
-  from Kubernetes and are visible to anyone with access to the Lifecycle UI.
+  Docker build arguments are not secret mounts. Build logs, cache, image
+  metadata, or Dockerfile commands can expose their values.
 </Callout>
 
-To minimize exposure:
+A build-time secret is applicable only to image construction. For a necessary
+build-time value:
 
-- **Never print environment variables** during build steps
-- **Delete credential files** after use (e.g., `RUN rm -f .npmrc` after `npm install`)
-- **Use multi-stage builds** so secrets are only present in the builder stage, not the final image
-- **Prefer runtime secrets** when possible — only use build-time secrets when the value is genuinely needed during image construction
+1. Do not print the value.
+2. Create the temporary credential file in one `RUN` instruction.
+3. Use the credential in the same `RUN` instruction.
+4. Delete the credential file in the same `RUN` instruction.
+5. Use a multi-stage build to keep temporary files out of the final image.
 
-### Troubleshooting
+## Failure behavior
 
-#### Secret Not Available During Build
+| Condition                                 | User-visible result                                |
+| ----------------------------------------- | -------------------------------------------------- |
+| Service reference is invalid              | Lifecycle logs a warning, and the Service can fail |
+| Secret synchronization fails before build | The Service build fails                            |
+| Codefresh secret cannot resolve           | Lifecycle does not start the pipeline              |
+| Native Helm secret cannot resolve         | Lifecycle does not start the Helm deployment       |
+| Helm value contains a partial reference   | Lifecycle reports a configuration error            |
+| Webhook `env` contains a secret reference | The webhook receives the reference as text         |
 
-1. **Verify the syntax** — make sure your env var uses the `{{provider:path:key}}` pattern
-2. **Check that the secret exists** in AWS Secrets Manager or GCP Secret Manager
-3. **Confirm the ExternalSecret synced** — Lifecycle waits for sync before building, but if the secret path is wrong or permissions are missing, the sync will fail
-4. **Check build logs** for warnings about missing or unresolved secrets
+## Troubleshooting
 
-#### Secret Value Is Empty
+### Lifecycle omits a Service value
 
-```yaml
-# Wrong - missing the key
-NPM_TOKEN: "{{aws:myorg/npm-registry}}"
+1. Check the provider prefix.
+2. Check the case-sensitive secret path.
+3. For a JSON secret, check the key.
+4. Ask the platform team whether the path is allowed.
+5. Examine the Service logs for a secret warning.
 
-# Correct - includes the JSON key
-NPM_TOKEN: "{{aws:myorg/npm-registry:token}}"
-```
+### Secret synchronization fails
 
-If your secret is stored as a plaintext string (not JSON), you can omit the key. But if the secret is JSON, you must specify which key to extract.
+1. Give the provider, path, Environment ID, and Service name to the platform
+   team.
+2. Ask the team to check the matching `ClusterSecretStore`.
+3. Ask the team to check the provider identity and path permissions.
+4. After the team corrects access, redeploy the Service.
 
-#### Dockerfile Not Receiving the Value
+Do not include the secret value in an issue, chat message, or log excerpt.
 
-Make sure your Dockerfile declares the build argument with `ARG`:
+### A native Helm value fails
 
-```dockerfile
-# Wrong - no ARG declaration
-RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
+1. Make sure that the entry has `key=value` syntax.
+2. Make sure that the complete value is one secret reference.
+3. Remove `--debug` and `--dry-run`.
+4. Check the provider, path, and JSON key.
 
-# Correct - ARG declared before use
-ARG NPM_TOKEN
-RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
-```
+### A Dockerfile does not receive a value
+
+1. Make sure that the Service uses a native BuildKit or Kaniko build.
+2. Add an `ARG` instruction with the same name.
+3. Keep the value out of build output.
+4. Rebuild the Service.
 
-## Related
+## Related pages
 
-- [Template Variables](/docs/features/template-variables) - Learn about other template syntax
-- [Webhooks](/docs/features/webhooks) - Using secrets in webhook environment variables
-- [Native Builds](/docs/features/native-builds) - Build pipeline that consumes build-time secrets
+- [Template variables](/docs/features/template-variables)
+- [Webhooks](/docs/features/webhooks)
+- [Native Helm deployment](/docs/features/native-helm-deployment)
diff --git a/src/pages/docs/features/service-dependencies.mdx b/src/pages/docs/features/service-dependencies.mdx
index 1b0f7ffd..7554b7cd 100644
--- a/src/pages/docs/features/service-dependencies.mdx
+++ b/src/pages/docs/features/service-dependencies.mdx
@@ -1,6 +1,12 @@
 ---
 title: Service Dependencies
-description: Understand service dependencies, their impact, and configuration.
+description: Understand Service dependencies, their effects, and configuration.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - lifecycle
   - service-dependencies
@@ -11,173 +17,131 @@ tags:
 
 import { Callout } from "nextra/components";
 
-This document will cover `environment.{defaultServices,optionalServices}` and `service.requires`, their differences, impact scope, and usage.
+Lifecycle has different controls for selecting Services and ordering their
+deployment:
+
+- `environment.defaultServices` and `environment.optionalServices` select the
+  Environment's starting catalog.
+- `services[].requires` includes a service dependency.
+- `services[].deploymentDependsOn` orders deployment of Services in the
+  Environment.
 
 ## `environment.{defaultServices,optionalServices}`
 
-### Impact scope
+These lists select the Services offered by the current repository's
+Environment:
 
-| Scope                     | Impact |
-| ------------------------- | ------ |
-| Service repo<sup>\*</sup> | ✅     |
-| Outside repo<sup>\*</sup> | ❌     |
-| dev-0<sup>\*</sup>        | ❌     |
+- Lifecycle selects `defaultServices` initially.
+- Users can select `optionalServices`.
 
-This represents the default environment that will be created by lifecycle when a pull request is opened in the service repo<sup>\*</sup> and does not have any impact on outside repos, dev-0, or any other static environments that use this service.
+They do not rewrite the default or optional lists in a different repository, and
+they do not change an existing static Environment.
 
 ## `services.requires`
 
-### Impact scope
-
-| Scope                     | Impact |
-| ------------------------- | ------ |
-| Service repo<sup>\*</sup> | ✅     |
-| Outside repo<sup>\*</sup> | ✅     |
-| dev-0<sup>\*</sup>        | ✅     |
-
-`services.requires` has an impact across the board; hence, it is important to understand how it works and when we should use them.
-
-**Please read the info blocks below carefully.**
-
-You can think of `services.requires` as a hard dependency definition. For example, if you have an API service and a database, the API service will have a hard dependency on the database.
-In this scenario, the database should not be defined as the default service. Instead, we should make the dependency explicitly clear by adding the database to the API’s `requires` block.
-By doing this, we ensure that any outside repo that wants to use our API service will get the database along with it but only needs to specify the API service in their `defaultServices` or `optionalServices`.
-
-<Callout type="warning">
-  Only services defined in `lifecycle.yaml` should be used in the `requires`
-  array. If a service is defined in an outside repo, use
-  `environment.defaultServices` instead.
-</Callout>
-
-Do not use services in the `services.requires` if the service itself is not
-defined in the same lifecycle.yaml.
-
-<Callout type="warning">
-  Services defined in the `requires` block will only be resolved 1 level down.
-</Callout>
-
-**This is a very important nuance, which we get tripped by regularly.**
-
----
-
-## Examples
-
-To better illustrate the above statement, consider this example.
-
-Repository A `r-A` has 3 services `s-A`, `s-B`, and `s-C`.
-
-- `s-A` requires `s-B`.
-- `s-B` requires `s-C`.
-
-As you can see, `s-A` has an indirect dependency on `s-C` through `s-B`.
-
-### Scenario 1: Pull Request in Service repo<sup>\*</sup> ✅
-
-When we open a pull request in `r-A` repo, lifecycle will deploy 3 services: `s-A`, `s-B`, and `s-C`.
-
-#### Breakdown
-
-- Lifecycle deploys `s-A` and `s-B` because they are defined in `defaultServices`.
-- Services defined in the `requires` block will only be resolved **one level down**.
-- Only services defined in `lifecycle.yaml` should be used in the `requires` array. If a service is defined in an outside repo, use `environment.defaultServices` instead.
+If a selected Service must include a different Service from the same
+`lifecycle.yaml`, use `requires`. For example, an API can include its database:
 
-```yaml
-# `r-A.lifecycle.yaml`
+```yaml filename="lifecycle.yaml"
 environment:
   defaultServices:
-    - name: "s-A"
-    - name: "s-B"
+    - name: "api"
 
 services:
-  - name: "s-A"
+  - name: "api"
     requires:
-      - name: "s-B"
-    helm: ...
+      - name: "database"
+    docker:
+      dockerImage: "ghcr.io/docs-example/api"
+      defaultTag: "latest"
+      ports:
+        - 8080
+
+  - name: "database"
+    docker:
+      dockerImage: "postgres"
+      defaultTag: "15-alpine"
+      ports:
+        - 5432
+```
 
-  - name: "s-B"
-    requires:
-      - name: "s-C"
-    helm: ...
+Selecting `api` includes `database` when a different repository references
+`api` as a default or optional Service.
 
-  - name: "s-C"
-    helm: ...
-```
+<Callout type="warning">
+  `requires` resolves only one level. If `api` has a direct `requires` entry for
+  `database`, and `database` has one for `storage`, selecting `api` does not
+  include `storage` automatically.
+</Callout>
+
+For a deeper dependency, add a direct requirement to the selected Service. You
+can also list the dependency explicitly in the consuming Environment.
 
-### Scenario 2: ❌
+## `services[].deploymentDependsOn`
 
-Repository B `r-B` has service `s-X` and also defines an outside repo `r-A` service `s-A` as `environment.defaultServices`.
+When one selected Service must finish before a different Service starts, use
+`deploymentDependsOn`. Its values are Service names:
 
-```yaml
-#  `r-B.lifecycle.yaml`
+```yaml filename="lifecycle.yaml"
 environment:
   defaultServices:
-    - name: "s-X"
-    - name: "s-A"
-      repository: "lifecycle/r-A"
-      branch: "main"
+    - name: "database"
+    - name: "api"
 
 services:
-  - name: "s-X"
-    helm: ...
+  - name: "database"
+    docker:
+      dockerImage: "postgres"
+      defaultTag: "15-alpine"
+      ports:
+        - 5432
+
+  - name: "api"
+    deploymentDependsOn:
+      - "database"
+    docker:
+      dockerImage: "ghcr.io/myorg/api"
+      defaultTag: "latest"
+      ports:
+        - 8080
 ```
 
-#### Breakdown
-
-1. Lifecycle deploys `s-X` and `s-A` because they are defined in `defaultServices`.
-2. Lifecycle deploys `s-B` because it is a 1st level dependency of a service (`s-A`) listed in `defaultServices`.
-3. Lifecycle **does not** deploy `s-C` since it is **not** a 1st level dependency of any service listed in `defaultServices` or `optionalServices`.
-
-The way this scenario manifests is lifecycle will deploy `s-X`, `s-A`, and `s-B`, but the build will likely **fail** because `s-B` is missing a required dependency `s-C`.
+Lifecycle deploys services at the same dependency level in parallel, then moves
+to the next level. A dependency cycle marks the affected deploys as
+`deploy_failed` with a cycle error.
 
-### Solutions
-
-There are 2 ways to address this depending on your use case.
+<Callout type="warning">
+  `requires` does not guarantee deployment order. If the API needs the database
+  included and must wait for it, use `requires` and `deploymentDependsOn`. Each
+  name must match a selected Service.
+</Callout>
 
-#### Solution 1
+## Reference a Service from a different repository
 
-Add `s-B` to `r-B`’s `environment.defaultServices` block in `r-B.lifecycle.yaml`. In effect, this will make `s-C` a first-level dependency.
+A consuming repository can select a Service defined elsewhere:
 
-```yaml
+```yaml filename="lifecycle.yaml"
 environment:
   defaultServices:
-    - name: "s-X"
-    - name: "s-A"
-      repository: "lifecycle/r-A"
+    - name: "api"
+      repository: "docs-example/service-catalog"
       branch: "main"
-    - name: "s-B"
-      repository: "lifecycle/r-A"
-      branch: "main"
-```
-
-#### Solution 2
-
-Add `s-C` to the `services.requires` block of `r-A` in `r-A.lifecycle.yaml`. This will also make `s-C` a first-level dependency.
-
-```yaml
-environment:
-  defaultServices:
-    - name: "s-A"
-    - name: "s-B"
-
-services:
-  - name: "s-A"
-    requires:
-      - name: "s-B"
-      - name: "s-C"
-    helm: ...
 ```
 
-### Choosing the Right Solution
-
-In summary, the solution you should use depends on how you want your service to be consumed in an outside repo<sup>\*</sup>.
+Lifecycle reads `api` and its direct `requires` entries from that repository.
+The consuming repository does not have to duplicate those direct dependencies.
+It must list each dependency that `requires` does not resolve.
 
-- If you want outside repos to explicitly include `s-A` and `s-B`, use **Solution 1**.
-- If you want outside repos to only include `s-A` and let dependencies resolve automatically, use **Solution 2**.
+## Check the graph
 
----
+After changing dependencies:
 
-### Terminology
+1. Validate `lifecycle.yaml`.
+2. Examine the selected Service set in Mission Control.
+3. Check that the selected Service set contains all direct requirements.
+4. Check that deployment starts in the order declared by
+   `deploymentDependsOn`.
 
-- **Service repo**: The repository where `lifecycle.yaml` is defined.
-- **Outside repo**: Another repository referencing it.
-- **dev-0**: Default static environment.
+If a Service is missing, check for a direct requirement. Then, check for an
+unsupported transitive dependency. If deployment starts before its dependency,
+add `deploymentDependsOn`. Do not add a `requires` entry only for ordering.
diff --git a/src/pages/docs/features/sites.mdx b/src/pages/docs/features/sites.mdx
new file mode 100644
index 00000000..3bc89b61
--- /dev/null
+++ b/src/pages/docs/features/sites.mdx
@@ -0,0 +1,116 @@
+---
+title: Sites
+description: Upload and manage static HTML sites through Lifecycle's UI, CLI, or authenticated v2 API.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - sites
+  - static-hosting
+  - cli
+  - api
+---
+
+import { Callout } from "nextra/components";
+
+Sites publishes a static HTML file or ZIP archive at a stable Lifecycle URL. It
+is useful for generated reports, prototypes, and documentation previews. A
+server-side application is not necessary.
+
+<Callout type="warning">
+  Sites requires storage, gateway, DNS, and authentication configuration. If
+  **Sites** is not available, contact your deployment owner.
+</Callout>
+
+## Upload from the UI
+
+1. Open **Sites**.
+2. Select **Add site**.
+3. Select one HTML file or a ZIP archive with the entry point that your
+   deployment's upload policy requires.
+4. Add an optional display name.
+5. Examine the file.
+6. Upload the file.
+7. Open the returned URL.
+8. Make sure that its content is correct.
+
+Use search plus **All sites** or **My sites** to find an upload. From a site's
+actions menu you can replace its content or delete it.
+
+<Callout type="info">
+  **My sites** is a convenience filter based on creator or updater identity. It
+  does not make a site private. A caller with `sites:read` can list active
+  sites.
+</Callout>
+
+## Upload a directory with the CLI
+
+The CLI can upload a ZIP, one HTML file, or a directory:
+
+```bash
+lfc sites create ./dist --name "performance report"
+lfc sites list --mine
+lfc sites get a1b2c3d4e5
+lfc sites update a1b2c3d4e5 ./dist
+lfc sites extend a1b2c3d4e5
+lfc sites delete a1b2c3d4e5 --yes
+```
+
+For a directory, `lfc` builds the ZIP locally. It applies built-in ignores such
+as `.git`, `node_modules`, cache directories, and coverage output. Add an
+`.lfcsiteignore` file for patterns in the repository.
+
+Before creating or updating a site, the CLI fetches the deployment's upload
+policy and checks allowed extensions, file count, extracted size, and upload
+size.
+
+## Prepare static content
+
+- Build the site locally. Lifecycle does not run a server-side build command.
+- When the site generator supports relative asset URLs, use them.
+- Include the entry file that your deployment's Sites policy specifies.
+- Remove source maps, credentials, and internal data. Remove output that is not
+  necessary.
+- Open the published URL.
+- Before you share the URL, check its navigation and assets.
+
+When you replace content, the site keeps its URL. When you delete a site, its
+URL stops working. You cannot undo the deletion.
+
+## Expiration
+
+When the operator enables Sites TTL, a new site receives the deployment's
+configured expiration. **Extend** pushes the expiry out by the configured
+increment. When the operator disables TTL, a site can have no expiry.
+
+Use the expiry displayed by the UI or CLI. Do not use a fixed number of days.
+Get cleanup and previous-version retention information from the deployment
+owner.
+
+## API access
+
+Sites uses authenticated v2 routes:
+
+| Task            | Route                                    | Scope                         |
+| --------------- | ---------------------------------------- | ----------------------------- |
+| List or create  | `GET` or `POST /api/v2/sites`            | `sites:read` or `sites:write` |
+| Get or delete   | `GET` or `DELETE /api/v2/sites/{siteId}` | `sites:read` or `sites:write` |
+| Replace content | `PUT /api/v2/sites/{siteId}/content`     | `sites:write`                 |
+| Extend expiry   | `POST /api/v2/sites/{siteId}/extend`     | `sites:write`                 |
+
+Uploads use `multipart/form-data`. Use the deployment-local generated API
+reference for the current limits and schema. See [API
+overview](/docs/api/overview) and [API
+keys](/docs/api-authentication/api-keys).
+
+## Troubleshooting
+
+- **Sites is disabled or missing:** contact the deployment owner.
+- **The upload is rejected:** compare the file type, entry point, count, and
+  sizes with the policy returned by the deployment.
+- **Assets return 404:** rebuild with relative paths or the published base URL.
+- **A URL stopped working:** Lifecycle can expire a site, or a user can delete
+  it. Before you upload a replacement, examine the Sites list.
diff --git a/src/pages/docs/features/template-variables.mdx b/src/pages/docs/features/template-variables.mdx
index 4754da13..36bd0d9f 100644
--- a/src/pages/docs/features/template-variables.mdx
+++ b/src/pages/docs/features/template-variables.mdx
@@ -1,5 +1,12 @@
 ---
 title: Template Variables
+description: Use Environment, Service, and configuration values in Lifecycle Service settings.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - template
   - variables
@@ -17,62 +24,110 @@ import { Callout } from "nextra/components";
 
 ## Overview
 
-Lifecycle uses [Mustache](https://github.com/janl/mustache.js) as the template rendering engine.
+Lifecycle uses [Mustache](https://github.com/janl/mustache.js) to render
+templates.
 
 ## Available Template Variables
 
-The following template variables are available for use within your configuration. Variables related to specific services should use the service name as a prefix.
+You can use these template variables in your configuration. A Service-specific
+variable starts with the Service name.
 
 ### General Variables
 
-- **`{{{buildUUID}}}`** - The unique identifier for the Lifecycle environment, e.g., `lively-down-881123`.
-- **`{{{namespace}}}`** - Namespace for the deployments, e.g., `env-lively-down-881123`.
-- **`{{{pullRequestNumber}}}`** - The GitHub pull request number associated with the environment.
-- **`{{{branchName}}}`** - The branch name of the pull request that triggered the environment.
-- **`{{{repoName}}}`** - The full repository name (e.g., `org/repo`) associated with the environment.
+- **`{{{buildUUID}}}`** - The unique Environment identifier, for example,
+  `lively-down-881123`.
+- **`{{{buildSHA}}}`** - The Lifecycle-generated build revision for the
+  Environment.
+- **`{{{namespace}}}`** - The deployment namespace, for example,
+  `env-lively-down-881123`.
+- **`{{{pullRequestNumber}}}`** - The GitHub pull request number, when the Environment has one.
+- **`{{{branchName}}}`** - The source branch name.
+- **`{{{repoName}}}`** - The full source repository name, such as `org/repo`.
 
 ### Service-Specific Variables
 
-For service-specific variables, replace `<service_name>` with the actual service name.
+For a Service-specific variable, replace `<service_name>` with the Service name.
 
-- **`{{{<service_name>_branchName}}}`** - The branch name associated with that service's deployment.
-- **`{{{<service_name>_dockerImage}}}`** - The fully qualified Docker image reference for the service.
-- **`{{{<service_name>_initDockerImage}}}`** - The fully qualified Docker image reference for the service's init container image.
-- **`{{{<service_name>_internalHostname}}}`** - The internal hostname of the deployed service. If the service is optional and not deployed, it falls back to `defaultInternalHostname`.
+- **`{{{<service_name>_branchName}}}`** - The branch name for the Service
+  deployment.
+- **`{{{<service_name>_dockerImage}}}`** - The fully qualified Docker image
+  reference for the Service.
+- **`{{{<service_name>_initDockerImage}}}`** - The fully qualified image
+  reference for the Service init container.
+- **`{{{<service_name>_internalHostname}}}`** - The internal hostname of the
+  deployed Service. For an optional Service that is not deployed, the value is
+  `defaultInternalHostname`.
 
   <Callout type="info">
-    `service_internalHostname` will be substituted with local cluster full
-    domain name like `service.namespace.svc.cluster.local` to be able to work
-    with deployments across namespaces.
+    Lifecycle replaces `service_internalHostname` with a cluster domain name
+    such as `service.namespace.svc.cluster.local`. This name supports
+    deployments across namespaces.
   </Callout>
 
 - **`{{{<service_name>_ipAddress}}}`** - The service IP address.
-- **`{{{<service_name>_namespace}}}`** - The Kubernetes namespace used by the service.
-- **`{{{<service_name>_publicUrl}}}`** - The public URL of the deployed service. If optional and not deployed, it defaults to `defaultPublicUrl` under the `services` table.
-- **`{{{<service_name>_sha}}}`** - The GitHub SHA that triggered the Lifecycle build.
-- **`{{{<service_name>_UUID}}}`** - The build UUID of the service. If listed under `optionalServices` or `defaultServices`, its value depends on whether the service is selected:
+- **`{{{<service_name>_namespace}}}`** - The Kubernetes namespace that the
+  Service uses.
+- **`{{{<service_name>_publicUrl}}}`** - The public URL of the deployed Service.
+  For an optional Service that is not deployed, the value is
+  `services.defaultPublicUrl`.
+- **`{{{<service_name>_sha}}}`** - The `sha` value of the Service deploy.
+- **`{{{<service_name>_UUID}}}`** - The build UUID of the Service. For a Service
+  in `optionalServices` or `defaultServices`, the value depends on its
+  selection:
   - If selected, it is equal to `buildUUID`.
-  - If not selected (or if service not part of deploys created), it defaults to **`dev-0`**.
+  - If not selected, Lifecycle uses the Service override for `defaultUUID`.
+  - If the Service has no override, Lifecycle uses the installation default.
 
-## Usage Example
+When a Service uses `deployment.network.hostPortMapping`, Lifecycle also
+creates `{{{<host>-<service_name>_publicUrl}}}` variables for the mapped hosts.
+
+### Configuration Data
+
+Lifecycle makes each key in an active
+[`configuration` Service](/docs/schema/configuration) available as a template
+variable. A data entry named `FEATURE_MODE` becomes
+`{{{FEATURE_MODE}}}`. The configuration Service name is not a prefix.
+
+## Example
+
+```yaml filename="lifecycle.yaml"
+version: "1.0.0"
+
+environment:
+  defaultServices:
+    - name: "frontend"
+    - name: "backend"
 
-```yaml
 services:
-  frontend:
-    # ...
-    env:
-      API_URL: "{{{backend_publicUrl}}}"
-      UUID: "{{{buildUUID}}}"
-      BACKEND_IMAGE: "{{{backend_dockerImage}}}"
-      BACKEND_NAMESPACE: "{{{backend_namespace}}}"
+  - name: "frontend"
+    github:
+      repository: "myorg/frontend"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "Dockerfile"
+          env:
+            API_URL: "https://{{{backend_publicUrl}}}"
+            ENVIRONMENT_ID: "{{{buildUUID}}}"
+            SOURCE_SHA: "{{{buildSHA}}}"
+            BACKEND_IMAGE: "{{{backend_dockerImage}}}"
+            BACKEND_NAMESPACE: "{{{backend_namespace}}}"
+
+  - name: "backend"
+    docker:
+      dockerImage: "ghcr.io/myorg/backend"
+      defaultTag: "latest"
+      ports:
+        - 8080
 ```
 
-This ensures the `PUBLIC_URL` and `INTERNAL_HOST` variables are dynamically assigned based on the ephemeral environment deployment.
+Lifecycle renders the frontend values from the current Environment and backend
+Service before creating the workload.
 
- <Callout>
-- Undefined variables will result in an empty string unless handled explicitly.
-- Use triple curly braces (`{{{ }}}`) to prevent unwanted HTML escaping.
-- Ensure service names are correctly referenced in the template without any spaces.
+<Callout type="warning">
+  Undefined variables render as an empty string. For a raw URL or image name,
+  use triple braces (`{{{ }}}`). Make sure that Service names match.
 </Callout>
 
-For more details, refer to the [Mustache.js documentation](https://github.com/janl/mustache.js).
+See the [Mustache.js documentation](https://github.com/janl/mustache.js).
diff --git a/src/pages/docs/features/webhooks.mdx b/src/pages/docs/features/webhooks.mdx
index 6edcb5af..91138dae 100644
--- a/src/pages/docs/features/webhooks.mdx
+++ b/src/pages/docs/features/webhooks.mdx
@@ -1,5 +1,12 @@
 ---
 title: Webhooks
+description: Run Codefresh pipelines or Kubernetes Jobs after an Environment deploys, fails, or is torn down.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - webhook
   - automation
@@ -12,38 +19,45 @@ tags:
 
 import { Callout } from "nextra/components";
 
-Lifecycle can invoke **third-party services** when a build state changes.
+Lifecycle can invoke third-party services when an Environment status changes.
 
-Webhooks allow users to automate external processes such as running tests, performing cleanup tasks, or sending notifications based on environment build states.
+Webhooks can run tests, clean up resources, or send notifications for specified
+Environment statuses.
 
-## Supported Types
+## Supported types
 
 Lifecycle supports three types of webhooks:
 
-1. **`codefresh`** - Trigger Codefresh pipelines
-2. **`docker`** - Execute Docker images as Kubernetes jobs
-3. **`command`** - Run shell commands in a specified Docker image
+1. **`codefresh`:** Trigger Codefresh pipelines.
+2. **`docker`:** Run Docker images as Kubernetes Jobs.
+3. **`command`:** Run shell commands in a specified Docker image.
 
-## Common Use Cases
+## Example operations
 
-- When a build status is `deployed`, trigger **end-to-end tests**.
-- When a build status is `error`, trigger **infrastructure cleanup** or alert the team.
-- Run **security scans** on built containers.
-- Execute **database migrations** after deployment.
-- Send **notifications** to Slack, Discord, or other communication channels.
-- Perform **smoke tests** using custom test containers.
+- When an Environment status is `deployed`, trigger end-to-end tests.
+- When an Environment status is `error`, clean up infrastructure or send an
+  alert to the team.
+- Run security scans on built containers.
+- After deployment, run database migrations.
+- Send notifications to communication channels.
+- Run smoke tests in custom test containers.
 
 ## Configuration
 
-Webhooks are defined in the `lifecycle.yaml` under the `environment.webhooks` section.
+Define webhooks in the `environment.webhooks` section of `lifecycle.yaml`.
 
-Below is an example configuration for triggering end-to-end tests when the `deployed` state is reached.
+This example triggers end-to-end tests when the Environment reaches
+`deployed`.
+
+An administrator can disable all `lifecycle.yaml` webhooks. If no configured
+webhook starts, ask the administrator whether webhooks are available.
 
 ## Examples
 
 ### `codefresh`
 
-The `codefresh` type triggers existing Codefresh pipelines when build states change.
+The `codefresh` type triggers existing Codefresh pipelines when an Environment
+status changes.
 
 ```yaml
 # Trigger End-to-End Tests on Deployment
@@ -53,7 +67,7 @@ environment:
     - name: "frontend"
   optionalServices:
     - name: "backend"
-      repository: "lifecycle/backend"
+      repository: "docs-example/backend"
       branch: "main"
   webhooks:
     - state: deployed
@@ -62,17 +76,19 @@ environment:
       pipelineId: 64598362453cc650c0c9cd4d
       trigger: tests
       env:
-        branch: "{{frontend_branchName}}"
-        TEST_URL: "https://{{frontend_publicUrl}}"
+        branch: "{{{frontend_branchName}}}"
+        TEST_URL: "https://{{{frontend_publicUrl}}}"
   # ...
 ```
 
-- **`state: deployed`** → Triggers the webhook when the build reaches the `deployed` state.
-- **`type: codefresh`** → Specifies that this webhook triggers a **Codefresh pipeline**.
-- **`name`** → A human-readable name for the webhook.
-- **`pipelineId`** → The unique Codefresh pipeline ID.
-- **`trigger`** → Codefresh pipeline's trigger to execute.
-- **`env`** → Passes relevant environment variables (e.g., `branch` and `TEST_URL`).
+- **`state: deployed`:** Triggers the webhook when the Environment reaches
+  `deployed`.
+- **`type: codefresh`:** Specifies a Codefresh pipeline webhook.
+- **`name`:** A human-readable name for the webhook.
+- **`pipelineId`:** The unique Codefresh pipeline ID.
+- **`trigger`:** The Codefresh pipeline trigger to run. This value is necessary.
+- **`env`:** Passes specified environment variables, such as `branch` and
+  `TEST_URL`.
 
 ---
 
@@ -87,24 +103,26 @@ environment:
       pipelineId: 74283905723ff650c0d9ab7e
       trigger: cleanup
       env:
-        branch: "{{frontend_branchName}}"
+        branch: "{{{frontend_branchName}}}"
         CLEANUP_TARGET: "frontend"
   # ...
 ```
 
-- **`state: error`** → Triggers the webhook when the build fails.
-- **`type: codefresh`** → Invokes a Codefresh cleanup pipeline.
-- **`trigger: cleanup`** → Codefresh pipeline's trigger to execute.
-- **`env`** → Includes necessary variables, such as `branch` and `CLEANUP_TARGET`.
+- **`state: error`:** Triggers the webhook when the Environment fails.
+- **`type: codefresh`:** Invokes a Codefresh cleanup pipeline.
+- **`trigger: cleanup`:** Runs the Codefresh pipeline's `cleanup` trigger.
+- **`env`:** Includes necessary variables, such as `branch` and
+  `CLEANUP_TARGET`.
 
 ### `docker`
 
-The `docker` type allows you to execute any Docker image as a Kubernetes job when build states change.
+The `docker` type runs a Docker image as a Kubernetes Job when an Environment
+status changes.
 
 <Callout type="info">
-  Docker webhooks run as Kubernetes jobs in the same namespace as your build.
-  They have a default timeout of 30 minutes and resource limits of 200m CPU and
-  1Gi memory.
+  Docker webhooks run as Kubernetes Jobs in the same namespace as the
+  Environment. They have a default timeout of 30 minutes and resource limits of
+  200m CPU and 1Gi memory.
 </Callout>
 
 ```yaml
@@ -119,64 +137,80 @@ environment:
       docker:
         image: "myorg/e2e-tests:latest"
         command: ["npm", "run", "e2e"]
-        timeout: 1200 # 1 hour (optional, default: 1800 seconds)
+        timeout: 1200 # 20 minutes (optional, default: 1800 seconds)
       env:
-        BASE_URL: "https://{{frontend_publicUrl}}"
+        BASE_URL: "https://{{{frontend_publicUrl}}}"
         ENVIRONMENT: "ephemeral"
 ```
 
-- **`docker.image`** → Docker image to execute (required)
-- **`docker.command`** → Override the default entrypoint (optional)
-- **`docker.args`** → Arguments to pass to the command (optional)
-- **`docker.timeout`** → Maximum execution time in seconds (optional, default: 1800)
+- **`docker.image`:** Docker image to run. You must supply this field.
+- **`docker.command`:** Optional override for the default entry point.
+- **`docker.args`:** Optional arguments for the command.
+- **`docker.timeout`:** Optional maximum run time in seconds. The default is
+  1800, and the permitted range is 1–86400.
 
 ### `command`
 
-The `command` type is a simplified version of Docker webhooks, ideal for running shell scripts or simple commands.
+The `command` type runs shell scripts and simple commands in a Docker image.
 
 ```yaml
-# Slack Notification Example
+# Record a deployment with a non-secret receiver
 environment:
   # ...
   webhooks:
-    - name: "Deployment Notification"
-      description: "Notify team of successful deployment"
+    - name: "Record Deployment"
+      description: "Send a deployment event to an internal receiver"
       state: deployed
       type: command
       command:
         image: "alpine:latest"
         script: |
           apk add --no-cache curl
-          curl -X POST "$WEBHOOK_URL" \
+          curl --fail --request POST "$EVENT_ENDPOINT" \
             -H "Content-Type: application/json" \
-            -d "{\"text\":\"🚀 Deployed $SERVICE_NAME to $DEPLOY_URL\"}"
+            -d "{\"service\":\"$SERVICE_NAME\",\"url\":\"$DEPLOY_URL\"}"
         timeout: 300 # 5 minutes (optional)
       env:
-        WEBHOOK_URL: "https://hooks.slack.com/services/XXX/YYY/ZZZ"
-        SERVICE_NAME: "{{frontend_internalHostname}}"
-        DEPLOY_URL: "https://{{frontend_publicUrl}}"
+        EVENT_ENDPOINT: "https://events.example.org/lifecycle"
+        SERVICE_NAME: "{{{frontend_internalHostname}}}"
+        DEPLOY_URL: "https://{{{frontend_publicUrl}}}"
 ```
 
 <Callout type="warning">
-  Make sure to replace placeholder values like webhook URLs and pipeline IDs
-  with your actual values.
+  Do not commit credentials or secret-bearing webhook URLs in `lifecycle.yaml`.
+  Webhook `env` does not resolve cloud secret references. If a receiver needs
+  authentication, use an approved credential-delivery mechanism. The target Job
+  or pipeline must accept the mechanism.
 </Callout>
 
-- **`command.image`** → Docker image to run the script in (required)
-- **`command.script`** → Shell script to execute (required)
-- **`command.timeout`** → Maximum execution time in seconds (optional, default: 1800)
+- **`command.image`:** Docker image for the script. You must supply this field.
+- **`command.script`:** Shell script to run. You must supply this field.
+- **`command.timeout`:** Optional maximum run time in seconds. The default is
+  1800, and the permitted range is 1–86400.
 
 ## Trigger states
 
-Webhooks can be triggered on the following build states:
+Webhooks can run for these Environment statuses:
+
+- **`deployed`:** The Services deployed correctly.
+- **`error`:** A build or deployment failed.
+- **`torn_down`:** Lifecycle tore down the Environment.
+
+Use only these lowercase values. A different value does not start a webhook.
 
-- **`deployed`** → Service successfully deployed and running
-- **`error`** → Build or deployment failed
-- **`torn_down`** → Environment has been destroyed
+<Callout type="warning">
+  Webhook `env` resolves Lifecycle template variables, but it does not resolve
+  cloud secret references such as <code>{"{{aws:path:key}}"}</code>. The webhook
+  receives that reference as literal text. Use a secret delivery mechanism
+  supported by the target Job or pipeline.
+</Callout>
 
-## Note
+## Behavior
 
-- All webhooks for the same state are executed **serially** in the order defined.
-- Webhook failures do not affect the build status.
-- Webhook invocations can be viewed at `/builds/[uuid]/webhooks` page(latest 20 invocations). Use the API to view all invocations.
-- `docker` and `command` type's logs are not streamed when the job is still in progress and are available only after the job completes.
+- Lifecycle starts matching webhooks for the same status serially in configured
+  order.
+- Webhook failures do not change the build status.
+- The Environment's **Webhooks** page shows the invocation history that the v2
+  API returns.
+- Docker and command webhook logs are available after the Job completes.
+  Lifecycle does not stream them while the Job runs.
diff --git a/src/pages/docs/features/workspace-backends.mdx b/src/pages/docs/features/workspace-backends.mdx
new file mode 100644
index 00000000..26f50c53
--- /dev/null
+++ b/src/pages/docs/features/workspace-backends.mdx
@@ -0,0 +1,91 @@
+---
+title: Agent workspace backends
+description: Compare and safely activate the runtime backend used for new Lifecycle Agent workspaces.
+audience:
+  - administrator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - ai
+  - agent
+  - workspaces
+  - administration
+---
+
+import { Callout } from "nextra/components";
+
+A workspace backend is the runtime where Lifecycle Agent checks out code, runs
+commands, and serves previews. Administrators select one active backend for new
+workspaces.
+
+<Callout type="info">
+  Your Lifecycle release and administrator policy control backend
+  administration. **Runtime backends** can be unavailable to some users.
+</Callout>
+
+## Compare backends
+
+| Backend         | Necessary connection                                          | Capabilities                                                                                    |
+| --------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Kubernetes**  | Lifecycle's cluster integration                               | Supports chat, Develop, environment and sandbox sessions, editor, previews, resume, and prewarm |
+| **OpenSandbox** | Workspace image. API key when the service makes it necessary. | Chat and sandbox sessions, previews, and resume. Editor when the image includes code-server.    |
+| **E2B**         | API key and template                                          | Chat and sandbox sessions, previews, and resume. Editor when the template includes code-server. |
+| **Modal**       | Token ID, token secret, and image                             | Chat and sandbox sessions, previews, and checkpoint-based resume. No editor.                    |
+| **Daytona**     | API key and snapshot                                          | Chat and sandbox sessions, previews, and resume. Editor when the snapshot includes code-server. |
+| **Substrate**   | Not configurable                                              | Coming soon                                                                                     |
+
+The remote backends do not support Develop workspaces, Environment sessions, or
+workspace prewarm. Capabilities can change. The running Settings page shows the
+current capability data.
+
+## Backend configuration and tests
+
+1. Open the backend in **Runtime backends**.
+2. Enter its necessary image, template, snapshot, endpoint, and credential
+   fields.
+3. Save the connection.
+4. Select **Test connection** to validate credentials and basic configuration.
+5. Select **Launch test sandbox** for an end-to-end check.
+6. Examine each check stage and gateway authentication.
+7. When the backend supports an editor, examine editor access.
+8. After the test sandbox succeeds, select **Use for new workspaces**.
+
+The test sandbox creates and deletes a provider resource. The provider can
+briefly bill for this resource.
+
+<Callout type="warning">
+  Activating a third-party backend sends repository content, Agent instructions,
+  commands, and runtime data to that provider. Examine its data handling,
+  residency, access controls, network boundary, billing, and deletion guarantees
+  before activation.
+</Callout>
+
+## Handle credentials
+
+Credential fields do not show stored values. To rotate a credential, replace
+it. Then, run the connection test and sandbox test again.
+
+Provider environment variables can supply some credentials, but the Settings
+page does not show their values. Follow your deployment's secret-management
+procedure rather than placing credentials in a repository.
+
+## Understand activation
+
+After activation, **Use for new workspaces** affects only new workspaces.
+Existing workspaces keep their original backend and provider billing.
+
+Before switching:
+
+- read the capability-loss warning in Settings
+- complete important work or keep it on the current backend
+- use a representative repository on the candidate backend
+- make sure that its editor and preview behavior is correct
+- record the rollback selection
+
+After switching, start a new test session. Make sure that checkout, command
+execution, preview access, suspend/resume, and cleanup operate correctly.
+
+See [Agent Sessions](/docs/features/agent-sessions) for the user workflow and
+[Agent administration](/docs/features/agent-administration) for the related
+policy.
diff --git a/src/pages/docs/getting-started/_meta.ts b/src/pages/docs/getting-started/_meta.ts
index 989b7bda..31752673 100644
--- a/src/pages/docs/getting-started/_meta.ts
+++ b/src/pages/docs/getting-started/_meta.ts
@@ -15,22 +15,25 @@
  */
 
 export default {
+  "terminology": {
+    "title": "Terminology"
+  },
+  "onboard-repository": {
+    "title": "Onboard a repository"
+  },
   "create-environment": {
-    "title": "Create environment"
+    "title": "Create your first Environment"
   },
   "explore-environment": {
-    "title": "Explore environment"
+    "title": "Explore an Environment"
   },
   "configure-environment": {
-    "title": "Configure environment"
+    "title": "Configure an Environment"
   },
   "delete-environment": {
-    "title": "Delete environment"
+    "title": "Delete an Environment"
   },
   "explore-static-environment": {
-    "title": "Explore static environment"
-  },
-  "terminology": {
-    "title": "Terminology"
+    "title": "Create a default static Environment"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/getting-started/configure-environment.mdx b/src/pages/docs/getting-started/configure-environment.mdx
index 99b1a962..80a779a4 100644
--- a/src/pages/docs/getting-started/configure-environment.mdx
+++ b/src/pages/docs/getting-started/configure-environment.mdx
@@ -1,5 +1,11 @@
 ---
-title: Configure environment
+title: Configure an Environment
+description: Set Service selection, dependencies, builds, and deployments in lifecycle.yaml.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - tutorial
   - configure
@@ -8,137 +14,145 @@ tags:
 
 import { Callout } from "nextra/components";
 
-Now that we've created and deployed our first Lifecycle environment, let's learn how to customize it by configuring services and dependencies.
+Use the repository-root `lifecycle.yaml` to define the initial and optional
+Services. The file also defines relationships between Services.
 
-## Understanding Configuration
+## Start with a small Service set
 
-First, let's take a look at the `lifecycle.yaml` configuration file at the root dir of [lifecycle-examples](https://github.com/GoodRxOSS/lifecycle-examples/blob/main/lifecycle.yaml) repository:
+This example uses generalized repository and Service names. Replace all
+repositories, paths, ports, and branches with values from your application:
 
 ```yaml filename="lifecycle.yaml"
+version: "1.0.0"
+
 environment:
   autoDeploy: true
   defaultServices:
-    - name: "frontend"
-    - name: "backend"
+    - name: "web"
+    - name: "api"
   optionalServices:
-    - name: "cache"
+    - name: "worker"
 
 services:
-  - name: "frontend"
-    defaultUUID: "dev-0"
+  - name: "web"
+    deploymentDependsOn:
+      - "api"
     github:
-      repository: "iceycake/lifecycle-examples"
+      repository: "docs-example/preview-app"
       branchName: "main"
       docker:
-        builder:
-          engine: "buildkit"
         defaultTag: "main"
         app:
-          dockerfilePath: "Dockerfile.frontend"
+          dockerfilePath: "services/web/Dockerfile"
           ports:
             - 3000
           env:
-            COMPONENT: "app"
-            ENV: "lifecycle"
-            API_URL: "https://{{{backend_publicUrl}}}"
-            CACHE_URL: "{{{cache_internalHostname}}}"
-            WES_IS: "GOAT"
-  - name: "backend"
-    requires:
-      - name: "db"
-    defaultUUID: "dev-0"
-    # ...
-  - name: "db"
-    defaultUUID: "dev-0"
-    # ...
-  - name: "cache"
-    defaultUUID: "dev-0"
-    # ...
-```
-
-### Default and Optional Services
+            API_URL: "https://{{{api_publicUrl}}}"
 
-We have our dependencies defined in **`defaultServices`** and **`optionalServices`**:
-
-- **`defaultServices`** – These services are always **built and deployed** with the environment. They form the core foundation of the environment and are required for it to function correctly.
-- **`optionalServices`** – These services **can be built on demand**, only when explicitly needed. If they are not selected during a PR, they default to using a **static environment** (e.g., `dev-0`).
+  - name: "api"
+    github:
+      repository: "docs-example/preview-app"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "services/api/Dockerfile"
+          ports:
+            - 8080
 
-### Template Variables
+  - name: "worker"
+    requires:
+      - name: "api"
+    deploymentDependsOn:
+      - "api"
+    github:
+      repository: "docs-example/preview-app"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "services/worker/Dockerfile"
+```
 
-Notice how there are template variables defined in service named `frontend` > `github.docker.env`:
+When the CLI is available, validate the file before you push it:
 
-```yaml
-API_URL: "https://{{{backend_publicUrl}}}"
-CACHE_URL: "{{{cache_internalHostname}}}"
+```sh
+lfc schema validate lifecycle.yaml
 ```
 
-This `API_URL` and `CACHE_URL` variables are dynamically templated by Lifecycle and provided during the **build** and **deploy** steps for the frontend service.
+## Select default and optional Services
 
-<Callout type="info">
-  Read more about supported template variables
-  [here](/docs/features/template-variables)
-</Callout>
+- Lifecycle selects `defaultServices` when it first creates the Environment.
+- Mission Control shows `optionalServices` as selectable Services. Lifecycle
+  builds them only after selection.
 
-## Static Environment as a Fallback
+To try the optional `worker` Service:
 
-Since `cache` is an **optional service**, this service defaulted to using a **static environment**(`dev-0`) as a fallback. This allows us to reuse existing environments instead of rebuilding everything from scratch when there are no changes.
+1. Open the Mission Control comment on the pull request.
+2. Select the `worker` checkbox.
+3. Save the comment.
+4. Wait until Lifecycle saves the selection.
+5. Before the `worker` deploy begins, make sure that `api` is available.
 
-### Check Template Variables
+Clear the checkbox. Lifecycle then uses the default Service set again. Each
+saved selection can queue work. Put related checkbox changes in one edit.
 
-To view how the fallback URL works,
+## Use different controls for inclusion and deployment order
 
-1. Open your **Tasks App**(frontend) from the deployed environment.
-2. Navigate to the `Variables` page.
-3. Search for `_URL` and check its value.
-   - It should look like:
-     ```
-     API_URL: https://backend-<build_uuid>.<your_domain>
-     CACHE_URL: cache-dev-0.env-dev-0.svc.cluster.local
-     ```
-   - Notice how `CACHE_URL` defaults to the `dev-0`(static) environment for the optional cache.
+`requires` and `deploymentDependsOn` control different operations:
 
-## Configuring Services
+- `requires` includes a different Service when its parent Service is selected.
+- `deploymentDependsOn` waits for named Services to deploy successfully before
+  starting the dependent Service.
 
-Now, let's say you also want to the `cache` component to **test, build and deploy it in your environment**.
+The example `worker` includes `api` and waits for it. `requires` does not create
+deployment ordering by itself. See
+[Service dependencies](/docs/features/service-dependencies) for cycle and
+failure behavior.
 
-### Enable Cache Deployment
+## Use resolved Service values
 
-1. Navigate to the **Lifecycle PR comment** on GitHub.
-2. Select the `cache` checkbox in the comment. That's it!
-3. Lifecycle will now start **building and deploying the cache service** for your specific environment.
-4. Wait for the build to complete. You can monitor the progress in the **status comment**.
+Lifecycle resolves template variables in supported build and deployment
+configuration. The example gives the current `api` public URL to `web`:
 
-### Confirm the New Cache URL
+```yaml
+env:
+  API_URL: "https://{{{api_publicUrl}}}"
+```
 
-5. Once the cache is deployed, go back to your **frontend app’s Variables page**.
-6. Check the `CACHE_URL` value.
-   - It should now look like:
-     ```
-     cache-<build_uuid>.env-<build_uuid>.svc.cluster.local
-     ```
-7. Now, you're running your cache **from your own environment** instead of an existing static deploy!
-8. Check the application’s **Tasks** page while you’re here and observe the completely different data, as this environment uses a freshly built and seeded database.
+Use only a documented variable. Select the public or internal hostname that
+matches the caller's network path. See
+[Template variables](/docs/features/template-variables).
 
-## Build Flexible Environments
+## Static fallback
 
-With this approach, you can:
+A Service can set `defaultUUID` to reference a long-lived static Environment
+when that Service is not selected:
 
-- Build **any combination** of frontend and backend services.
-- Use **custom branches** for different services.
-- Test **different versions** of your app.
+```yaml
+services:
+  - name: "shared-api"
+    defaultUUID: "shared-dev"
+    # Service source and deployment configuration...
+```
 
-<Callout type="info">
-  Check how to use Mission Control comments for configuring your environment
-  [here](/docs/tips/using-mission-control)
+<Callout type="warning">
+  `defaultUUID` does not create or operate the static Environment. Use it only
+  when your platform team operates that specified Environment ID. The team must
+  also define ownership, compatibility, and cleanup policies. If the team does
+  not define them, select the Service in the current Environment.
 </Callout>
 
-This gives you a **custom, isolated testing environment** that mirrors your
-production setup while allowing flexibility in development and validation.
+## Check the change
 
-## Summary
+After pushing the configuration:
 
-- Services marked as **optional** in `lifecycle.yaml` will default to static environments unless explicitly built.
-- You can enable/disable any service directly from the **Lifecycle PR comment**.
-- Lifecycle automates dependency management, ensuring your services deploy in the correct order.
+1. Make sure that Lifecycle accepts the file without a configuration error.
+2. Examine the selected Service set in Mission Control.
+3. Check dependency ordering in the Environment timeline or logs.
+4. Open the application.
+5. Test the path that uses the resolved dependency.
 
-**Now you're ready to customize your Lifecycle environments like a pro!** 👩‍💻
+Continue with [Use the Mission Control
+comment](/docs/tips/using-mission-control) for branch, URL, and Environment
+overrides.
diff --git a/src/pages/docs/getting-started/create-environment.mdx b/src/pages/docs/getting-started/create-environment.mdx
index a720dd63..500d8752 100644
--- a/src/pages/docs/getting-started/create-environment.mdx
+++ b/src/pages/docs/getting-started/create-environment.mdx
@@ -1,126 +1,120 @@
 ---
-title: Create environment
+title: Create your first Environment
+description: Onboard a repository and create a pull-request Environment from a correct Lifecycle configuration.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - lifecycle
   - tutorial
-  - ephemeral-env
-  - start
-  - first environment
+  - environment
 ---
 
-import { Callout } from "nextra/components";
-import { Info, Settings } from "lucide-react";
+import { Callout, Steps } from "nextra/components";
 
-In this walk through, we will make a simple change to an example frontend repository and create our first ephemeral environment using Lifecycle.
+Use this procedure to create a deployed pull-request Environment from an
+onboarded repository.
 
-## 1. Fork the Repository
+## Prerequisites
 
-Fork the [`lifecycle-examples`](https://github.com/GoodRxOSS/lifecycle-examples) repository to your org or personal account and install your newly minted GitHub App to the forked repository.
+Before you start, make sure that you have:
 
-- Navigate to `https://github.com/settings/apps` (for personal accounts) or `https://github.com/organizations/<org>/settings/apps` (for org accounts).
-- Find the **Lifecycle GitHub App** and click on **Edit**.
-- Choose `Install App` from sidebar and click the Settings <Settings className="inline" /> icon.
-- Select the forked repository from the list and select **Save**.
+- Access to a Lifecycle installation
+- A repository where the Lifecycle GitHub App is installed
+- Permission to create a branch and pull request
+- A correct `lifecycle.yaml` in the repository root
 
-## 2. Create a New Branch
-
-Clone the repo and create a branch named `lfc-config`:
-
-```sh
-git checkout -b lfc-config
-```
+<Callout type="important">
+  Installing the GitHub App and onboarding a repository are different steps.
+  Lifecycle ignores repository webhooks until the repository is onboarded.
+  Complete [Onboard a repository](/docs/getting-started/onboard-repository)
+  before opening the pull request.
+</Callout>
 
-or if you are using GitHub Desktop, you can create a new branch from the UI.
+For a disposable example, fork
+[`GoodRxOSS/lifecycle-examples`](https://github.com/GoodRxOSS/lifecycle-examples).
+Then, replace each repository value in `lifecycle.yaml` with a repository that
+you can access.
 
-## 3. Update Lifecycle Configuration
+## Create the Environment
 
-Open the `lifecycle.yaml` file in the root of the repository and update the `frontend` service's repository to your github username or org.
+<Steps>
 
-**Before:**
+### Create a branch
 
-```yaml filename="lifecycle.yaml"
-github:
-  repository: "GoodRxOSS/lifecycle-examples"
+```sh
+git switch -c docs-first-environment
 ```
 
-**After:**
+### Validate the configuration
 
-```yaml filename="lifecycle.yaml"
-github:
-  repository: "<your-github-username>/lifecycle-examples"
-```
+Lifecycle accepts `lifecycle.yaml`, `lifecycle.yml`, `.lifecycle.yaml`, and
+`.lifecycle.yml`. The recommended name is `lifecycle.yaml`.
 
-## 4. Commit & Push Your Changes
+If you use the Lifecycle CLI, validate before pushing:
 
 ```sh
-git add .
-git commit -m "update config"
-git push origin lfc-config
+lfc schema validate lifecycle.yaml
 ```
 
-## 5. Create a Pull Request
-
-1. Open a **Pull Request (PR)** from `lfc-config` to `main` in the forked repository.
-2. Submit the PR.
+The server also validates the pushed file. See [Lifecycle
+CLI](/docs/features/cli#schema-validation) for CLI validation.
 
-## 6. Lifecycle PR Comment
+### Commit and push
 
-After submitting the PR, you’ll see a **GitHub comment from Lifecycle** on your pull request.
-
-🔹 This PR comment is the **mission control** for your ephemeral environment. It provides:
-
-- A **status update** of the build and deploy process.
-- A **list of services** configured for the environment.
-- A **link to the Lifecycle UI** where you can view logs, deployments, and environment details.
+```sh
+git add lifecycle.yaml
+git commit -m "configure Lifecycle environment"
+git push -u origin docs-first-environment
+```
 
-<Callout type="error">
-  If there is no comment from Lifecycle, it means the app is not configured
-  correctly or the GitHub App is not installed in the repository. Please refer
-  to the [Missing Comment](/docs/troubleshooting/github-app-webhooks) page for
-  more information.
-</Callout>
+### Open a pull request
 
-## 7. Add `lifecycle-status-comments!` label
+Open a pull request from the branch into the repository's default branch.
 
-The additional label `lifecycle-status-comments!` provides more detailed information about the environment status and links to access the running application.
+- If `environment.autoDeploy` is `true`, opening the pull request queues the
+  Environment automatically.
+- If `environment.autoDeploy` is not `true`, add the configured deploy label.
+  The default label is `lifecycle-deploy!`.
 
-🔹 The comments provides insights into:
+Label names are operator-configurable. Use the label that your installation
+shows. Do not hard-code the default name in automation.
 
-- **Build & Deploy Status**: Track when your environment is ready.
-- **Environment URLs**: Access the running frontend app.
-- **Telemetry Links**: Links to telemetry, build and deploy logs. (if enabled)
+### Follow the Lifecycle comment
 
-## 8. Wait for Deployment
+Lifecycle posts a Mission Control comment with the Environment identifier,
+selected Services, actions, and a link to the UI. Lifecycle also adds status updates by
+default. If your organization disabled default status comments, apply its
+configured status-comment label.
 
-Wait for the **builds & deploys** to complete. Once the status updates to **`deployed`**, your environment is live! 🚀
+</Steps>
 
-When a new commit is pushed to your pull request Lifecycle automatically builds and deploys again so you always have the latest version of the application.
+## Check the result
 
-<Callout type="info" icon={Info}>
-  If there are any errors during the build or deploy process, the environment
-  will not be created, and you will see an error message in the Lifecycle
-  comment.
-  <br />
-  <div>
-    You can check the logs from `lifecycle-worker` pods in your cluster to debug
-    the issue: <br /> `kubectl logs deploy/lifecycle-worker -n lifecycle-app -f
-    `
-  </div>
-</Callout>
+Open the Environment link.
 
-## 9. Checkout the deployed application
+Check these results:
 
-Once the deployment is complete, you can access your environment at the URL provided in the Lifecycle comment on your pull request. Click on the `frontend` link to open your application in a new tab.
+- The Environment reaches **Deployed**.
+- Each necessary Service reaches **Ready**.
+- The Service URL opens the expected application.
 
-The application has two simple pages:
+You can also wait from a terminal:
 
-- **`/tasks`** – A simple to-do list.
-- **`/variables`** – Displays all environment variables from the container.
+```sh
+lfc builds status <environment-id> --watch
+```
 
-## Next Steps
+If Lifecycle does not comment, start with
+[Missing pull-request comment](/docs/troubleshooting/github-app-webhooks).
+If a Service fails, use the phase-specific
+[build](/docs/troubleshooting/build-issues) or
+[deployment](/docs/troubleshooting/deploy-issues) guide.
 
-Now that your first ephemeral environment is ready, move on to the next section where we:
+## Next steps
 
-🧪 Test the environment.<br />
-🧭 Explore the comments and logs.<br />
-⚙️ Customize the configuration.
+- [Explore the Environment](/docs/getting-started/explore-environment)
+- [Configure Services and dependencies](/docs/getting-started/configure-environment)
+- [Use Mission Control](/docs/tips/using-mission-control)
diff --git a/src/pages/docs/getting-started/delete-environment.mdx b/src/pages/docs/getting-started/delete-environment.mdx
index 3ed120dd..dd5e5e57 100644
--- a/src/pages/docs/getting-started/delete-environment.mdx
+++ b/src/pages/docs/getting-started/delete-environment.mdx
@@ -1,37 +1,100 @@
 ---
-title: Delete environment
+title: Delete an Environment
+description: Tear down a pull-request or API-created Environment safely from GitHub, the UI, the CLI, or the API.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - lifecycle
-  - tutorial
-  - delete
-  - tear down
+  - environment
   - cleanup
-  - lifecycle-disabled
-  - close
 ---
 
 import { Callout } from "nextra/components";
 
-To **tear down** an environment, you can do one of the following:
+Deleting an Environment queues teardown of its workloads and releases its
+human-readable Environment ID. Select the control surface that created or owns
+the Environment.
 
-1. **Merge or close the pull request**: This will automatically clean up the environment.
-2. **Apply the `lifecycle-disabled!` label**: This will immediately trigger the environment deletion process.
+## Pull-request Environments
 
----
+Merge or close the pull request to tear down its Environment automatically.
+When the pull request remains open, apply your installation's configured disable
+label to tear down the Environment. The default label is
+`lifecycle-disabled!`.
+
+Label names are configurable. See
+[Auto deploy and labels](/docs/features/auto-deployment).
+
+## Lifecycle UI
+
+1. Open **Environments**.
+2. Select the Environment.
+3. Open **Actions**.
+4. Select **Destroy**.
+5. Check the selected Environment ID.
+6. If the Environment ID is correct, start the destructive action.
+
+The UI disables **Destroy** for a pinned static Environment. Unpin it only when
+you intend to remove its persistence guarantee.
+
+## CLI
+
+The CLI shows a confirmation prompt:
+
+```sh
+lfc builds destroy <environment-id>
+```
+
+For non-interactive automation, use `--yes` only after the script checks the
+Environment ID:
 
-The **`lifecycle-disabled!`** label is useful in scenarios where:
+```sh
+lfc builds destroy <environment-id> --yes
+```
 
-- The environment infrastructure is **experiencing issues**.
-- The data within the environment is **corrupt**.
-- You need to **restart or rebuild** the environment from scratch without waiting for a PR to be merged or closed.
+## API-created Environments
 
-Simply apply the label to the **PR associated with the environment**, and Lifecycle will automatically tear it down.
+Send an authenticated request with `env:write` access:
 
-<Callout type="info">
-  Read more about how pull request labels control auto deploy in repositories
-  [here](/docs/features/auto-deployment)
+```sh
+curl --request DELETE \
+  --header "Authorization: Bearer $LIFECYCLE_API_KEY" \
+  "$LIFECYCLE_API_URL/api/v2/environments/<environment-id>"
+```
+
+The API rejects deletion of a static Environment. Use a supported UI or CLI
+control to remove the static pin first:
+
+```sh
+lfc builds set <environment-id> --no-static
+```
+
+<Callout type="warning">
+  Teardown is asynchronous. Do not reuse the Environment ID until Lifecycle no
+  longer returns the active Environment detail.
 </Callout>
 
----
+## Check teardown
+
+Follow the status until it reaches **Torn down**:
+
+```sh
+lfc builds status <environment-id> --watch
+```
+
+Before you reuse an API-created Environment ID, wait until its detail route
+returns `404`:
+
+```sh
+curl --silent --output /dev/null --write-out "%{http_code}\n" \
+  --header "Authorization: Bearer $LIFECYCLE_API_KEY" \
+  "$LIFECYCLE_API_URL/api/v2/environments/<environment-id>"
+```
 
-Using these methods, you can efficiently manage and clean up environments to ensure smooth development and testing workflows. 🧹
+`lfc builds list --all` intentionally includes torn-down history. A historical
+row does not mean the ID is active. Application URLs also stop serving. If
+teardown does not complete, give the operator the Environment ID, its latest
+status message, and the affected Service names. Do not include secret values.
diff --git a/src/pages/docs/getting-started/explore-environment.mdx b/src/pages/docs/getting-started/explore-environment.mdx
index 16a43708..0efa29f3 100644
--- a/src/pages/docs/getting-started/explore-environment.mdx
+++ b/src/pages/docs/getting-started/explore-environment.mdx
@@ -1,5 +1,11 @@
 ---
-title: Explore environment
+title: Explore an Environment
+description: Make sure an Environment is ready, open a deployed Service, and use Lifecycle's pull request comments.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - lifecycle
   - tutorial
@@ -10,70 +16,78 @@ import { Callout } from "nextra/components";
 import { Info } from "lucide-react";
 import { Image } from "@lifecycle-docs/components";
 
-Now that we've deployed our first Lifecycle environment, let’s take a tour of the PR comments to understand how to interact with our ephemeral environment.
+After Lifecycle deploys your first Environment, make sure that its Services are
+ready before you start testing. You can examine the Environment in the
+Lifecycle UI and use the comments on your pull request to change or monitor it.
 
-## Test Your Application
+## Make sure that the Environment is ready
 
-Let's navigate to the deployed `frontend` app from the PR comment.
-
-1. Click on the `frontend` link in the PR comment to navigate to your deployed application.
-2. Add a task and complete few tasks to update data in backend.
-3. Navigate to the `variables` page and checkout the variables in your application's container.
-4. Thats it! You have successfully deployed and tested the best todo app in the world! 🎉
-
-## Mission Control Comment
-
-The **Lifecycle PR comment** in your pull request serves as the **mission control** for your ephemeral environment.
+1. Follow the **View details** link in the Lifecycle comment, or open
+   **Environments** in Lifecycle and select your Environment.
+2. Make sure that the Environment status is **Deployed**.
+3. Select each Service you plan to test. A correctly deployed Service shows
+   **Ready** and the message **Kubernetes pods are ready**.
+4. Select **Visit URL** to open a public Service.
 
 <Image
-  src="/getting-started/pr-comment.png"
-  width={2106}
-  height={2278}
-  ratio={2106 / 2278}
+  src="/docs/getting-started/explore-environment/environment-ready.png"
+  alt="Environment details with Deployed status and a web Service with Ready status."
+  width={1440}
+  height={900}
+  ratio={1440 / 900}
 />
 
-### What You Can Do in the PR Comment
+If a Service shows **Build failed**, **Deploy failed**, or **Error**, open its
+**Console**. See [Troubleshoot a failed
+deployment](/docs/troubleshooting/deploy-issues) for the recovery workflow.
 
-- **Editable Checkboxes**: Select or deselect services to include in your environment.
-- **Redeploy Checkbox**: Triggers a redeploy (useful for transient issues).
-- **Deployment Section**: Provides URLs to your **deployed services**.
+## Test your application
 
-<Callout type="info" emoji={<Info />}>
-  Read more about [Mission Control comment
-  here](/docs/tips/using-mission-control.mdx)
-</Callout>
+Open a deployed public Service from **Visit URL** or from the pull request
+comment, then:
 
-## Status Comment
+1. Test the smallest user path that shows the deployed change.
+2. Make sure that calls to each necessary backend or dependency succeed.
+3. Check only non-secret runtime configuration through a surface your
+   application intentionally exposes.
+4. Go back to Lifecycle to examine a different Service or its logs.
 
-When we add the `lifecycle-status-comments!` label to our pull request, Lifecycle will automatically add a **status comment** to the PR.
+## Use the Mission Control comment
 
-This comment provides real-time updates on the status, links to your deployments including the build progress and service statuses.
+Lifecycle's editable pull-request comment is the GitHub control surface for the
+Environment. It can contain:
 
-<Image
-  src="/getting-started/status-comment.png"
-  width={1902}
-  height={894}
-  ratio={1902 / 894}
-/>
+- **Service checkboxes:** Select or deselect optional Services.
+- **Branch or external URL values:** Change the source used for an eligible
+  Service.
+- **Environment ID and variable overrides:** Apply changes to this Environment
+  without editing the repository configuration.
+- **Actions:** Queue a redeploy and run other configured operations.
+- **Options:** Change conditional settings that the installation exposes.
+
+<Callout type="info" emoji={<Info />}>
+  Lifecycle parses the comment as product input. Its headings and syntax control
+  the parsed values. The [Mission Control comment
+  reference](/docs/tips/using-mission-control) has correct examples.
+</Callout>
 
-Notice the following while the environment is being built:
+## Follow status updates
 
-- The status comment is **updated in real-time**.
-- The **status** of each service is displayed.
-- The **build logs** are available for each service.
+Lifecycle adds status comments by default. It updates them when the Environment
+status changes. An operator can turn that repository default off. If the
+operator turns it off, apply the configured status-comment label.
 
-<Image
-  src="/getting-started/status-comment-building.png"
-  width={1894}
-  height={1222}
-  ratio={1894 / 1222}
-/>
+Use the status comment to see:
 
-### Next Steps
+- Current Environment changes
+- Each Service's current status
+- Available build-log links from the deployment backend
 
-In the next section, we will:
+Operators can change the default label names. See
+[Configurable labels](/docs/features/configurable-labels) before you write
+automation that uses a literal label.
 
-⚙️ Customize our configuration<br />
-☑️ Enable and build an optional service(`cache`) support your application<br />
+## Next steps
 
-**Ready to level up your ephemeral environment? Let\'s go!** 🏃‍➡️
+Next, [configure your Environment](/docs/getting-started/configure-environment)
+and try selecting one optional Service from your own configuration.
diff --git a/src/pages/docs/getting-started/explore-static-environment.mdx b/src/pages/docs/getting-started/explore-static-environment.mdx
index d74e1f7d..3fc6184f 100644
--- a/src/pages/docs/getting-started/explore-static-environment.mdx
+++ b/src/pages/docs/getting-started/explore-static-environment.mdx
@@ -1,81 +1,106 @@
 ---
-title: Explore static environment
-description: Create the first and default static environment
+title: Create a default static Environment
+description: Create and pin a long-lived dev-0 Environment with supported Lifecycle controls.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
-  - tutorial
+  - environment
   - dev-0
   - static
-  - onboard
 ---
 
-import { Callout } from "nextra/components";
+import { Callout, Steps } from "nextra/components";
 
-A **static environment** in Lifecycle is a persistent environment that serves as a fallback when dependent services do not need to be rebuilt.
+A static Environment does not use the usual pull-request teardown lifecycle.
+Teams use `dev-0` as a fallback for Services that an ephemeral Environment does
+not override.
 
-Unlike ephemeral environments that are built on short lived pull requests, static environments are built on top of long lived pull requests. These environments exist continuously and update automatically as changes are merged into the default branch of configured services.
+## Prerequisites
 
-## What is `dev-0`
-
-The **default static environment** is `dev-0`. This environment ensures that there is always a **stable and up-to-date version** of services available without needing to build every dependency manually.
+Required items are the Lifecycle CLI, Environment management permission, and an
+onboarded repository with the fallback Services.
 
 <Callout type="warning">
+  Lifecycle can reserve `dev-0` with an empty placeholder. Release the name with
+  the CLI procedure below.
+</Callout>
 
-The `dev-0` environment should be created for your installation.
+## Create `dev-0`
 
-During the initial bootstrapping of Lifecycle, the `dev-0` build record is created automatically but this itself does not have any services built.
+<Steps>
 
-</Callout>
+### Examine the placeholder
 
-## Create `dev-0`
+```sh
+lfc builds get dev-0
+```
+
+If this is the empty reserved placeholder, continue. If it is a non-placeholder
+Environment, do not replace it.
 
-- Delete the dummy `dev-0` build record from `builds` table in the database
+### Release the reserved name
 
-```sql
-DELETE FROM builds WHERE uuid = 'dev-0';
+```sh
+lfc builds update-uuid dev-0 dev-0-placeholder
 ```
 
-- Create a repository named `lifecycle-static-env` in your GitHub account
-- Install the Lifecycle GitHub App in this repository
-- Create a pull request in this repository with branch `dev-0`
-- Add `lifecycle.yaml` file to the root of the repository with all the services you want to include in the `dev-0` environment
-
-  **Example:**
-
-```yaml
-environment:
-  defaultServices:
-    - name: "frontend"
-      repository: "account/frontend-repo"
-      branch: "main"
-    - name: "grpc"
-      repository: "account/backend-grpc"
-      branch: "main"
+If your installed CLI or server rejects this operation, stop and contact the
+platform operator. The operator can upgrade Lifecycle or give you the supported
+migration procedure.
+
+### Create the source Environment
+
+Create a long-lived pull request in the onboarded repository. Its
+`lifecycle.yaml` must select the fallback Services and their default
+branches. Wait until the generated Environment is deployed.
+
+### Rename and pin it
+
+```sh
+lfc builds update-uuid <generated-environment-id> dev-0
+lfc builds set dev-0 --static --track-defaults
 ```
 
-- Deploy the `dev-0` environment by adding `lifecycle-deploy!` label to the pull request
-- Update `uuid` for the environment to `dev-0` in the [mission control comment](/docs/tips/using-mission-control#override-uuid)
-- Finally, execute this query to track default branches of the services in the `dev-0` environment:
-
-```sql
-UPDATE builds
-SET
-    "trackDefaultBranches" = true,
-    "isStatic" = true
-WHERE
-    uuid = 'dev-0';
+`--static` prevents usual automatic teardown. When a default branch moves,
+`--track-defaults` redeploys Services that have no explicit branch override.
+
+### Remove the placeholder
+
+```sh
+lfc builds destroy dev-0-placeholder
 ```
 
-## Key Features
+</Steps>
 
-**🏗️ Fallback for Optional Services**
+## Check the fallback
+
+```sh
+lfc builds get dev-0
+```
 
-- When optional services are not explicitly built in an ephemeral environment, Lifecycle defaults to using the latest build from `dev-0`.
+Make sure that the output identifies the Environment as static. Check that
+default-branch tracking is enabled. Make sure that all fallback Services are
+**Ready**.
 
-**💪 Based on a Persistent PR**
+In a different ephemeral Environment, do not select an optional Service. Make sure that
+its generated template variables point to the Service from `dev-0`. The fallback
+comes from each Service's configured `defaultUUID`. The template resolver does
+not always use `dev-0`.
 
-- Similar to ephemeral environments, `dev-0` is based on a PR, but it remains open and continuously updates.
+## Change or remove the static Environment
 
-**👣 Tracks Changes on Default Branch Merges**
+To stop tracking default branches without removing the Environment:
 
-- Whenever a service has a new change merged to its `main` branch, `dev-0` will **automatically pull, build, and redeploy** the latest changes.
-- This ensures `dev-0` always contains **the freshest version** of all services.
+```sh
+lfc builds set dev-0 --no-track-defaults
+```
+
+To remove it, first unpin and then destroy it:
+
+```sh
+lfc builds set dev-0 --no-static
+lfc builds destroy dev-0
+```
diff --git a/src/pages/docs/getting-started/onboard-repository.mdx b/src/pages/docs/getting-started/onboard-repository.mdx
new file mode 100644
index 00000000..9324655e
--- /dev/null
+++ b/src/pages/docs/getting-started/onboard-repository.mdx
@@ -0,0 +1,76 @@
+---
+title: Onboard a repository
+description: Add a GitHub App installation repository to Lifecycle so pull-request and push events can create Environments.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - github
+  - repository
+  - onboarding
+---
+
+import { Callout, Steps } from "nextra/components";
+import { Image } from "@lifecycle-docs/components";
+
+Onboarding adds a GitHub repository to Lifecycle's repository allowlist.
+Installing the Lifecycle GitHub App grants GitHub access, but it does not
+onboard the repository automatically.
+
+## Prerequisites
+
+- A platform operator has completed the Lifecycle GitHub App setup.
+- The App is installed for the repository or its organization.
+- Your Lifecycle account is allowed to manage repositories.
+
+## Onboard from the UI
+
+<Steps>
+
+### Open repository onboarding
+
+Open your Lifecycle UI. Go to `/onboard`.
+
+### Find the repository
+
+Search for your GitHub `owner/repository` name. Lifecycle lists only
+repositories that its GitHub App installation can access.
+
+<Image
+  src="/docs/getting-started/onboard-repository/repository-list.png"
+  alt="Repository onboarding shows one example repository, the Onboard action, Pick a repository, and Confirm."
+  width={768}
+  height={346}
+  ratio={768 / 346}
+/>
+
+If the repository is missing, update the App installation's repository access
+in GitHub. Then, go back to Lifecycle and retry.
+
+### Confirm the repository
+
+1. Select **Onboard**.
+2. Check the repository name.
+3. When the name is correct, select **Onboard repository**.
+
+After onboarding succeeds, the row shows the onboarded state.
+
+</Steps>
+
+## Check with a pull request
+
+Open a pull request that contains a correct Lifecycle configuration. If onboarding
+is correct, Lifecycle handles the webhook and creates a Mission Control
+comment.
+
+<Callout type="info">
+  Removing a repository from Lifecycle stops future repository events from
+  creating or updating Environments. Lifecycle keeps the existing build history.
+  You can onboard the repository again subsequently.
+</Callout>
+
+If the App is installed and the repository is onboarded but no comment appears,
+continue with
+[Missing pull-request comment](/docs/troubleshooting/github-app-webhooks).
diff --git a/src/pages/docs/getting-started/terminology.mdx b/src/pages/docs/getting-started/terminology.mdx
index 29ef3c35..d28d5c65 100644
--- a/src/pages/docs/getting-started/terminology.mdx
+++ b/src/pages/docs/getting-started/terminology.mdx
@@ -1,5 +1,11 @@
 ---
 title: Terminology
+description: Canonical Lifecycle terms for Environments, Services, deployments, and automation.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - build
   - terminology
@@ -12,49 +18,69 @@ tags:
   - review
 ---
 
-This glossary provides an overview of key Lifecycle concepts and terminology. Let's see how they fit into the environment setup and deployment process.
+When you read the UI and documentation, use these terms. Some APIs and CLI
+commands use legacy names for compatibility. These sections identify the
+compatibility terms.
 
 ## Repository
 
-A **repository** refers to a GitHub repository. Each environment that is built **must** have a default repository and an associated pull request.
+A **repository** is a GitHub repository that contains application source or a
+`lifecycle.yaml` configuration. A pull request is one Environment source.
+Static and API-created Environments are not tied to a pull request.
 
 ## Service
 
-A **service** is a deployable artifact. It can be a Docker container, CI pipeline, RDS database, or Helm chart. A single repository can contain multiple services.
+A **Service** is a named unit in `lifecycle.yaml`. Service types include GitHub
+source builds, pre-built Docker images, Helm charts, Codefresh pipelines,
+external HTTP dependencies, Aurora restores, and configuration-only data. A
+single repository can define multiple Services.
 
 **Example:** <br/>
-`frontend-service` and `frontend-cache` are two services required for the frontend application to function correctly.
+The frontend application needs the `frontend-service` and `frontend-cache`
+Services.
 
 ## Environment
 
-An **environment** is a stack of services built and connected together.
+An **Environment** is an isolated set of selected Services and their resolved
+configuration.
 
-- **`defaultServices`** are built and deployed in an environment by default.
-- **`optionalServices`** can be built and deployed only when needed; otherwise, they fallback to the **default static environment**.
+- Lifecycle builds and deploys **`defaultServices`** in an Environment by
+  default.
+- Users can select **`optionalServices`**. If a user does not select an optional
+  Service, its template variables can use a configured `defaultUUID` fallback.
+
+## Environment ID
+
+Lifecycle assigns each Environment a human-readable identifier such as
+`payments-preview` or `dev-0`. APIs, template variables, and the CLI can use
+the name `uuid` or `buildUUID` for compatibility. It is an Environment
+identifier, not an RFC-formatted UUID.
 
 ## Static Environment
 
-A **static environment** is a long-lived environment based on a pull request. It tracks branches from configured services and updates automatically when new changes are merged.
+A **static Environment** is long-lived and can track configured Service
+branches. Cleanup for one pull request does not remove it. It can supply
+fallback endpoints for optional Services.
 
 ## Build
 
-A **build** is the actual instance of the process to build and deploy services within an environment.
-
-- Each build is uniquely identified by Lifecycle using a UUID (e.g., `arm-model-060825` or `dev-0`).
-- A build contains **one deploy per service** in the configuration.
+**Build** is the legacy API and CLI term for an Environment record and its
+current orchestration state. User-facing guidance uses **Environment** unless
+it names a literal command, field, or status.
 
 ## Deploy
 
-A **deploy** manages the build and deployment execution of a service within an environment.
-
-**Example:**<br/>
-In a frontend environment, `frontend-service` and `frontend-cache` are two deploys created for the environment, each mapped to a unique build UUID.
+A **Deploy** is the per-Service execution record in an Environment. It
+tracks the selected branch/image, status, endpoints, and build or deployment
+jobs for one Service.
 
 ## Webhook
 
-Lifecycle can invoke third-party services when a build state changes. Currently, only **Codefresh triggers** are supported.
+A **webhook** runs automation when an Environment reaches `deployed`, `error`,
+or `torn_down`. Lifecycle supports Codefresh pipelines, Docker-image Jobs, and
+command Jobs.
 
 ### Example
 
-- When the build status is `deployed`, trigger end-to-end tests.
-- When the build status is `error`, trigger infrastructure cleanup.
+- When the Environment status is `deployed`, start end-to-end tests.
+- When the Environment status is `error`, start infrastructure cleanup.
diff --git a/src/pages/docs/index.mdx b/src/pages/docs/index.mdx
index 3e833c6f..9bb2c27c 100644
--- a/src/pages/docs/index.mdx
+++ b/src/pages/docs/index.mdx
@@ -1,12 +1,112 @@
 ---
-title: What is Lifecycle?
-description: Lifecycle is your effortless way to test and create ephemeral environments
+title: Lifecycle documentation
+description: Select a task-oriented path through Lifecycle as an application developer, evaluator, platform operator, API user, or Agent administrator.
+audience:
+  - evaluator
+  - application-developer
+  - platform-operator
+  - agent-user
+  - api-user
+  - administrator
+lastVerified: "2026-08-01"
+verificationBaseline: "2026-08-01-lifecycle-mcp-preparation"
+contentProfile: asd-ste100
 tags:
   - core
   - lifecycle
-  - intro
+  - start
 ---
 
-import WhatIsLifecycle from "./what-is-lifecycle.mdx";
+import { Cards } from "nextra/components";
 
-<WhatIsLifecycle />
+## Create, use, and operate Lifecycle Environments
+
+Select the path that matches your task. An administrator can disable features
+or add role gates. Thus, each guide identifies its applicable prerequisites.
+
+## I develop applications
+
+<Cards>
+  <Cards.Card
+    title="Create my first Environment"
+    href="/docs/getting-started/create-environment"
+  >
+    Onboard a repository. Open a pull request. Make sure that the Services are
+    deployed.
+  </Cards.Card>
+  <Cards.Card title="Use the Lifecycle UI" href="/docs/features/lifecycle-ui">
+    Find Environments. Examine build and deployment logs. Start available
+    actions.
+  </Cards.Card>
+  <Cards.Card title="Configure lifecycle.yaml" href="/docs/schema/overview">
+    Select Services, branches, dependencies, builds, deployments, and webhooks.
+  </Cards.Card>
+</Cards>
+
+## I evaluate or operate the platform
+
+<Cards>
+  <Cards.Card
+    title="Understand the system"
+    href="/docs/operations/architecture"
+  >
+    See the components, request flow, storage, identity, and trust boundaries.
+  </Cards.Card>
+  <Cards.Card
+    title="Select an installation path"
+    href="/docs/setup/install-lifecycle"
+  >
+    Compare the starter OpenTofu and existing-cluster Helm evaluation paths.
+    Then, make sure that your selected path is safe.
+  </Cards.Card>
+  <Cards.Card title="Operate Lifecycle" href="/docs/operations/day-two">
+    Plan upgrades, backups, recovery, monitoring, and configuration changes.
+  </Cards.Card>
+</Cards>
+
+## I automate Lifecycle
+
+<Cards>
+  <Cards.Card title="Use the CLI" href="/docs/features/cli">
+    Authenticate. Examine Environments. Follow status. Read logs. Start actions.
+  </Cards.Card>
+  <Cards.Card title="Use API keys" href="/docs/api-authentication/api-keys">
+    Create a scoped credential. Use authenticated v2 endpoints. Revoke the
+    credential.
+  </Cards.Card>
+  <Cards.Card title="Use the HTTP API" href="/docs/api/overview">
+    Find the generated OpenAPI reference and understand authentication
+    boundaries.
+  </Cards.Card>
+</Cards>
+
+## I use or administer Agents
+
+Deployment packaging, configuration, and role policy control Agent and MCP
+availability. Check each page's availability boundary before you use its
+workflow.
+
+<Cards>
+  <Cards.Card
+    title="Check Agent Session availability"
+    href="/docs/features/agent-sessions"
+  >
+    When your deployment makes the feature available, see the current Labs
+    boundary. Then, launch a governed workspace.
+  </Cards.Card>
+  <Cards.Card
+    title="Learn Agent administration"
+    href="/docs/features/agent-administration"
+  >
+    See which models, instructions, permissions, tools, runtimes, and inspection
+    controls are available in a deployment.
+  </Cards.Card>
+  <Cards.Card title="Connect to Lifecycle MCP" href="/docs/features/mcp-server">
+    Lifecycle MCP uses one URL and OAuth sign-in for the tools that your account
+    permits.
+  </Cards.Card>
+</Cards>
+
+If you are not sure where to start, read [What is
+Lifecycle?](/docs/what-is-lifecycle) and the [terminology
+reference](/docs/getting-started/terminology).
diff --git a/src/pages/docs/operations/_meta.ts b/src/pages/docs/operations/_meta.ts
new file mode 100644
index 00000000..4916d767
--- /dev/null
+++ b/src/pages/docs/operations/_meta.ts
@@ -0,0 +1,33 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export default {
+  "architecture": {
+    "title": "Lifecycle architecture"
+  },
+  "configuration": {
+    "title": "Runtime configuration surfaces"
+  },
+  "security": {
+    "title": "Security boundaries"
+  },
+  "monitoring": {
+    "title": "Monitor Lifecycle"
+  },
+  "day-two": {
+    "title": "Day-two operations"
+  }
+};
\ No newline at end of file
diff --git a/src/pages/docs/operations/architecture.mdx b/src/pages/docs/operations/architecture.mdx
new file mode 100644
index 00000000..54f8acb1
--- /dev/null
+++ b/src/pages/docs/operations/architecture.mdx
@@ -0,0 +1,94 @@
+---
+title: Lifecycle architecture
+description: Understand how requests become Lifecycle Environments and plan dependencies, security controls, availability, and recovery.
+audience:
+  - evaluator
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - operator
+  - architecture
+  - security
+---
+
+import { Image } from "@lifecycle-docs/components";
+
+Lifecycle receives requests, builds applications, and deploys Environments to
+Kubernetes. The following flow shows the components and dependencies that
+operators must configure.
+
+## Request-to-Environment flow
+
+<Image
+  src="/docs/operations/architecture/request-flow.svg"
+  alt="Requests move through Lifecycle web, queued work, workers, data services, and execution targets."
+  width={1280}
+  height={720}
+  ratio={1280 / 720}
+/>
+
+1. GitHub delivers a repository event, or an authenticated user calls the UI,
+   CLI, or v2 API.
+2. Lifecycle authenticates the request and checks the applicable policy.
+3. Lifecycle uses Postgres for Lifecycle data and Redis for queued work.
+4. Lifecycle reads `lifecycle.yaml` and selects the applicable Services.
+5. Lifecycle builds images or invokes external pipelines and applies workloads
+   to Kubernetes.
+6. When enabled, object storage keeps archived logs and Site content.
+7. The UI, CLI, API, GitHub comments, and MCP surfaces show the resulting status
+   and logs.
+8. When one of these events occurs, Lifecycle removes the Environment:
+   - A pull request closes.
+   - A user requests removal.
+   - The Environment TTL expires.
+   - The API lease expires.
+
+## Components
+
+| Component           | Responsibility                                                            |
+| ------------------- | ------------------------------------------------------------------------- |
+| Web                 | Receives UI, API, and GitHub requests and applies authentication          |
+| Worker              | Runs build, deploy, Agent, Site, and cleanup work                         |
+| Gateway             | Serves Site content when the Sites feature is enabled                     |
+| Lifecycle UI        | Provides Environments, Sites, Agents, and Settings                        |
+| Keycloak            | Provides identity services for the chart authentication configuration     |
+| Postgres            | Stores Lifecycle data, including Environments and configuration           |
+| Redis               | Coordinates queued work for web and worker components                     |
+| BuildKit / registry | Builds and distributes images when the native build configuration is used |
+| Kubernetes          | Runs Environment workloads, jobs, Services, ingress, and Secrets          |
+| Object storage      | Stores archived build and deploy logs and Site content when configured    |
+
+## Availability and recovery boundaries
+
+The default values use one web replica, one worker replica, and standalone
+Redis. This configuration is not a high-availability profile.
+
+- Monitor Postgres and Redis as separate dependencies. `/api/health` returns
+  `Unhealthy` when either dependency is unavailable. It does not check object
+  storage.
+- Back up Postgres, configuration Secrets, and the `ENCRYPTION_KEY` Secret as
+  one recovery set. Test the matched restore in an isolated deployment.
+- Decide whether Redis queued-work state must survive a recovery. After an
+  outage or data loss, examine affected Environments before a retry.
+- When archived logs or Sites must survive a failure, back up object storage and
+  its credential Secret. Test the object storage restore with the related
+  Lifecycle data.
+
+## Trust boundaries
+
+- The default ClusterRole has wildcard Kubernetes permissions. Limit cluster and
+  network access before you expose Lifecycle.
+- Use `ENABLE_AUTH=false` only in an isolated local evaluation. Requests get
+  administrator permissions in this mode.
+- GitHub App installation, Lifecycle repository onboarding, and a user's linked
+  GitHub identity are separate authorization relationships.
+- Restrict access to the `ENCRYPTION_KEY`. If you lose this key, Lifecycle cannot
+  decrypt protected configuration.
+- Review the permissions, approvals, credentials, and network access for each
+  Agent tool and external MCP connection.
+
+Continue with [Security boundaries](/docs/operations/security),
+[configuration surfaces](/docs/operations/configuration), and
+[day-two operations](/docs/operations/day-two).
diff --git a/src/pages/docs/operations/configuration.mdx b/src/pages/docs/operations/configuration.mdx
new file mode 100644
index 00000000..af46b1fb
--- /dev/null
+++ b/src/pages/docs/operations/configuration.mdx
@@ -0,0 +1,56 @@
+---
+title: Runtime configuration surfaces
+description: Select a supported UI, API, Helm, or repository configuration surface and verify each change.
+audience:
+  - platform-operator
+  - administrator
+lastVerified: "2026-08-01"
+verificationBaseline: "2026-08-01-lifecycle-mcp-preparation"
+contentProfile: asd-ste100
+tags:
+  - operator
+  - configuration
+  - settings
+---
+
+Different surfaces own Lifecycle configuration. Select the surface that owns
+the value that you want to change. Use only a documented configuration surface.
+
+## Configuration map
+
+| What you are changing                                                  | Supported surface                                                                                |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| Application Services, builds, deployments, and Environment defaults    | Repository [`lifecycle.yaml`](/docs/schema/overview)                                             |
+| Personal API keys                                                      | [API keys](/docs/api-authentication/api-keys) in **Settings**                                    |
+| User connections                                                       | [External MCP connections](/docs/features/mcp-integration) in **Settings**                       |
+| Lifecycle MCP enablement and change-tool policy                        | [**Platform administration → Lifecycle MCP**](/docs/features/mcp-server)                         |
+| API key policy and service keys                                        | [**Settings → API key management** or its typed v2 API](/docs/api-authentication/api-keys)       |
+| PR-less Environment policy                                             | [**Settings** or the typed API Environment policy endpoint](/docs/features/api-environments)     |
+| Sites limits and availability                                          | [**Settings → Sites** or its typed v2 config endpoint](/docs/features/sites)                     |
+| Agent models, instructions, tools, workspaces, and session review      | [Admin Agent sections in **Settings**](/docs/features/agent-administration)                      |
+| Environment metadata links                                             | [Authenticated v2 metadata configuration API](/docs/features/build-metadata-links#manage-links)  |
+| Component replicas, resources, ingress, dependencies, and pod settings | [Versioned Helm values](/docs/setup/install-lifecycle#path-b-operator-managed-helm-installation) |
+| Infrastructure, DNS, and evaluation cluster resources                  | [The selected installation and infrastructure workflow](/docs/setup/install-lifecycle)           |
+
+If the map does not contain your setting, do not change the value through an
+undocumented method. Ask your deployment owner for a versioned procedure.
+
+## Configuration change procedure
+
+For a supported change:
+
+1. Record the previous value without recording secrets.
+2. Make the smallest change through the owning surface.
+3. If the feature requires a restart or propagation procedure, apply it.
+4. Make sure that one affected task operates correctly.
+5. If the task does not operate correctly, apply the previous value through the
+   same surface.
+
+Do not restart all components unless the applicable procedure tells you to do
+so.
+
+## Secret handling
+
+Keep credentials in Kubernetes Secrets, an external secret provider, or the
+approved credential UI or API for the feature. Do not put plaintext tokens in
+Helm history, screenshots, issue text, `lifecycle.yaml`, or diagnostic commands.
diff --git a/src/pages/docs/operations/day-two.mdx b/src/pages/docs/operations/day-two.mdx
new file mode 100644
index 00000000..b1f0dcd4
--- /dev/null
+++ b/src/pages/docs/operations/day-two.mdx
@@ -0,0 +1,78 @@
+---
+title: Day-two operations
+description: Plan Lifecycle upgrades, backups, rollback decisions, recovery validation, and uninstall.
+audience:
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - operator
+  - upgrade
+  - backup
+---
+
+import { Callout } from "nextra/components";
+
+Do not assume that an upgrade supports zero downtime or that an application
+rollback also reverses data changes. Test each version transition before you use
+it in production.
+
+## Before an upgrade
+
+Record:
+
+- the umbrella chart, core application, UI chart, Keycloak chart, and CLI
+  versions
+- the deployed Helm values and deliberate overrides
+- the database, object-storage, registry, and Kubernetes versions
+- the `ENCRYPTION_KEY` Secret backup location
+- active Environments and long-running Agent or Site operations
+- the applicable Lifecycle changelog and chart release notes.
+
+Back up durable state with the provider's supported tools. Include the database,
+object storage used for logs or Sites, and encryption and configuration Secrets.
+Test that you can restore the related assets together.
+
+## Migration behavior
+
+<Callout type="warning">
+  Do not run an undocumented manual migration. An upgrade can change stored
+  data, and `helm rollback` does not reverse those changes.
+</Callout>
+
+Back up stored data before the upgrade. Test the selected version transition in
+a representative non-production deployment.
+
+## Upgrade checkpoint
+
+Continue only when the release information identifies:
+
+1. a supported component-version combination
+2. necessary configuration or data migrations
+3. a backup and restore validation point
+4. the rollout order
+5. the rollback safety boundary.
+
+After rollout, make sure that `/api/health`, UI sign-in, repository webhooks,
+and one representative Environment operate correctly. Make sure that queued
+work progresses. Test each enabled Site or Agent surface. The health endpoint
+does not prove end-to-end operation.
+
+## Rollback and restore
+
+`helm rollback` cannot restore data to its pre-upgrade state. If a release does
+not declare backward compatibility, restore all matched recovery assets. These
+assets include the application, database, configuration Secrets, and
+object-storage snapshot. Test the recovery in an isolated deployment.
+
+## Uninstall
+
+Before uninstalling, select the resources to keep: Environment
+namespaces, durable data, object storage, registry images, kept Secrets, and DNS
+records. Record each approved target. Remove each approved target explicitly.
+Do not use a broad namespace or cluster deletion command. It can remove
+unintended resources.
+
+See [Compatibility and deprecation policy](/docs/releases/compatibility) before
+you select an upgrade or rollback procedure.
diff --git a/src/pages/docs/operations/monitoring.mdx b/src/pages/docs/operations/monitoring.mdx
new file mode 100644
index 00000000..734eb30e
--- /dev/null
+++ b/src/pages/docs/operations/monitoring.mdx
@@ -0,0 +1,54 @@
+---
+title: Monitor Lifecycle
+description: Interpret health endpoints, verify end-to-end operation, and collect safe diagnostic data for stuck work.
+audience:
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - operator
+  - monitoring
+  - troubleshooting
+---
+
+Lifecycle probes show component and dependency reachability. They do not prove
+that queued work progresses or that an Environment operates correctly.
+
+## Health endpoints
+
+| Endpoint      | What it proves                              | What it does not prove                                                                                    |
+| ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `/api/health` | Required data services are reachable.       | GitHub delivery, queue progress, Kubernetes access, build capacity, object storage, or workload readiness |
+| `/api/jobs`   | The worker endpoint responds with HTTP 200. | Queue lag, active consumption, failed jobs, retries, or stalled work                                      |
+
+The chart uses `/api/health` for component liveness and `/api/jobs` for worker
+readiness.
+
+## Stuck Environment investigation
+
+1. Record the Environment ID, current status, status message, and most recent
+   update time.
+2. Identify the most recent completed phase: webhook receipt, configuration,
+   queue, build, deploy, or readiness.
+3. Check `/api/health` on the affected component.
+4. Correlate web and worker logs by Environment ID and request ID.
+5. If other Environments are in the same phase, check their progress.
+6. Before retrying, examine the specified build or deploy job.
+
+Use [Troubleshoot a stuck Environment](/docs/troubleshooting/stuck-environment)
+for the full triage sequence. When you know the most recent phase, continue with
+[build recovery](/docs/troubleshooting/build-issues) or [deployment
+recovery](/docs/troubleshooting/deploy-issues).
+
+Do not decode Secrets. Do not dump Environment variables. Do not attach
+unredacted logs. A safe escalation bundle contains component and version,
+Environment ID, Service, phase, job name, timestamps, request ID, and the
+smallest related error excerpt.
+
+## Verify end-to-end operation
+
+Create an end-to-end canary Environment on a schedule. Verify that Lifecycle
+receives the request, builds the selected Services, deploys the workloads, and
+reports readiness. Use this result with the health endpoints. The endpoints
+alone do not show overall readiness.
diff --git a/src/pages/docs/operations/security.mdx b/src/pages/docs/operations/security.mdx
new file mode 100644
index 00000000..429ed0fd
--- /dev/null
+++ b/src/pages/docs/operations/security.mdx
@@ -0,0 +1,63 @@
+---
+title: Security boundaries
+description: Understand Lifecycle authentication, network, Kubernetes, secret, and Agent boundaries before other networks can reach a deployment.
+audience:
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - operator
+  - security
+  - authentication
+---
+
+import { Callout } from "nextra/components";
+
+The default chart configuration is not a production security profile. Complete
+the following inspection before users or shared networks can reach Lifecycle.
+
+## Authentication boundary
+
+<Callout type="error">
+  Use `ENABLE_AUTH=false` only for an isolated local evaluation. With this
+  value, requests get administrator permissions, and API-key bearer tokens do
+  not work. Do not make this configuration reachable from a shared network.
+</Callout>
+
+The stock installation is not a complete authentication-on profile for
+shared-network exposure. Before exposure, use a versioned authentication
+procedure for the installed release. The procedure must protect the API, UI,
+and identity provider together. If the release does not supply this procedure,
+keep the deployment isolated.
+
+After configuration, test browser sessions, API bearer tokens, API keys, roles,
+and user synchronization.
+
+## Predeployment inspection
+
+| Boundary        | Check                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Kubernetes RBAC | The chart's default ClusterRole uses wildcard permissions.                                                         |
+| Network         | Web and worker NetworkPolicies default off.                                                                        |
+| Pod security    | Default container settings are not a hardened restricted profile.                                                  |
+| Ingress and TLS | Core API, UI, auth, wildcard Environment, and optional Site hosts have different exposure needs.                   |
+| Secrets         | Helm values/history and broad diagnostic commands can leak credentials.                                            |
+| Encryption key  | A Secret contains the generated 64-hex-character key. Lifecycle needs the key to decrypt stored ciphertext.        |
+| GitHub App      | Requested write permissions and webhook events must agree with enabled capabilities.                               |
+| API             | Use authenticated v2. Reachable v1 endpoints are not a supported automation interface.                             |
+| Agents and MCP  | Tool permissions, approvals, external connections, workspace egress, and session review expand the trust boundary. |
+| Backups         | Recovery must include database, key material, and object storage together.                                         |
+
+## Vulnerability reporting
+
+No private vulnerability-reporting channel is published. Do not post suspected
+vulnerabilities, tokens, private logs, or exploit details in a public issue.
+Contact your deployment owner through an approved private channel.
+
+## Related guidance
+
+- [Authentication](/docs/features/authentication)
+- [API keys](/docs/api-authentication/api-keys)
+- [Lifecycle architecture](/docs/operations/architecture)
+- [Day-two operations](/docs/operations/day-two)
diff --git a/src/pages/docs/reference/_meta.ts b/src/pages/docs/reference/_meta.ts
new file mode 100644
index 00000000..4f1c720a
--- /dev/null
+++ b/src/pages/docs/reference/_meta.ts
@@ -0,0 +1,21 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export default {
+  "statuses": {
+    "title": "Environment and Service statuses"
+  }
+};
\ No newline at end of file
diff --git a/src/pages/docs/reference/statuses.mdx b/src/pages/docs/reference/statuses.mdx
new file mode 100644
index 00000000..301364f3
--- /dev/null
+++ b/src/pages/docs/reference/statuses.mdx
@@ -0,0 +1,72 @@
+---
+title: Environment and Service statuses
+description: Interpret Lifecycle Environment, build, deployment, and Service states. Select the correct response.
+audience:
+  - application-developer
+  - api-user
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - reference
+  - status
+  - troubleshooting
+---
+
+Lifecycle reports an overall Environment status. It also reports a status for
+each Service. UI labels use title case. API, CLI, and webhook values use these
+lowercase forms.
+
+## Environment statuses
+
+| API value      | Meaning                                                | Typical response                                              |
+| -------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
+| `pending`      | The Environment exists. Lifecycle has not queued work. | If it does not move, examine policy or worker health.         |
+| `queued`       | Lifecycle accepted the request and queued work.        | If it stays stale, contact an operator to examine queue work. |
+| `building`     | One or more Services make an image or artifact.        | If progress stops, open the Service's Build view.             |
+| `built`        | Necessary build work completed.                        | Deployment usually follows.                                   |
+| `deploying`    | Lifecycle is applying or waiting on workloads.         | Open Deploy, then Pods, for the affected Service.             |
+| `deployed`     | The Environment completed deployment.                  | Make sure necessary Services are **Ready**.                   |
+| `tearing_down` | Cleanup is in progress.                                | Before you use the Environment ID again, wait for cleanup.    |
+| `torn_down`    | Cleanup completed.                                     | No Environment operates.                                      |
+| `config_error` | Lifecycle could not validate or resolve configuration. | Correct `lifecycle.yaml` or repository access.                |
+| `error`        | The Environment ended in a terminal failure.           | Select the Service with the failure. Identify its phase.      |
+
+## Service statuses
+
+Services can report the applicable Environment states. They can also report
+`cloning`, `waiting`, `ready`, `build_failed`, and `deploy_failed`.
+
+| API value       | Meaning                                                                |
+| --------------- | ---------------------------------------------------------------------- |
+| `cloning`       | Lifecycle is fetching source.                                          |
+| `waiting`       | The Service is waiting for a dependency or different deployment level. |
+| `ready`         | The deployed workload passed its readiness condition.                  |
+| `build_failed`  | The build phase made no deployable artifact.                           |
+| `deploy_failed` | Deployment or readiness failed after the build phase.                  |
+
+An overall **Deployed** Environment can contain a Service that is not
+**Ready**. Make sure the Services for your test are ready. Do not use only the
+aggregate status.
+
+## Webhook states
+
+A webhook can start only for these `environment.webhooks[].state` values:
+
+- `deployed`
+- `error`
+- `torn_down`
+
+Use these lowercase values. A different value does not start a webhook.
+
+## Terminal and transitional states
+
+`deployed`, `torn_down`, `config_error`, and `error` are terminal for an
+Environment attempt. A subsequent push, redeploy, or teardown can start a new
+transition. `build_failed` and `deploy_failed` are terminal for the affected
+Service attempt.
+
+See [build troubleshooting](/docs/troubleshooting/build-issues) and
+[deployment troubleshooting](/docs/troubleshooting/deploy-issues) for the
+phase-specific recovery path.
diff --git a/src/pages/docs/releases/_meta.ts b/src/pages/docs/releases/_meta.ts
new file mode 100644
index 00000000..4c40e8e9
--- /dev/null
+++ b/src/pages/docs/releases/_meta.ts
@@ -0,0 +1,24 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export default {
+  "index": {
+    "title": "Releases"
+  },
+  "compatibility": {
+    "title": "Compatibility and deprecation policy"
+  }
+};
\ No newline at end of file
diff --git a/src/pages/docs/releases/compatibility.mdx b/src/pages/docs/releases/compatibility.mdx
new file mode 100644
index 00000000..282ae1db
--- /dev/null
+++ b/src/pages/docs/releases/compatibility.mdx
@@ -0,0 +1,39 @@
+---
+title: Compatibility and deprecation policy
+description: Select compatible Lifecycle components and prepare a safe upgrade or rollback.
+audience:
+  - platform-operator
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - release
+  - compatibility
+  - deprecation
+---
+
+Do not assume that all Lifecycle component versions are compatible. A complete
+version matrix, deprecation window, and rollback guarantee are not available.
+
+## Compatibility limits
+
+- Use the component versions that the same umbrella-chart release bundles or
+  explicitly tests.
+- Validate `lifecycle.yaml` with your deployed Lifecycle version. Use that
+  result for the deployment.
+- Do not use an older CLI schema as proof that a newer server accepts a
+  configuration.
+- Do not roll an application binary back across a database migration unless the
+  release explicitly supports it.
+
+## Before an upgrade
+
+1. Record the chart, application, UI, identity service, and CLI versions.
+2. Read the release notes for configuration, API, data, and security changes.
+3. Identify required data or Secret migrations.
+4. Back up the matched application data, configuration, and key material.
+5. Test the upgrade with representative data and enabled features.
+6. Test the documented rollback or restore checkpoint.
+
+Use [Day-two operations](/docs/operations/day-two) for the full procedure.
diff --git a/src/pages/docs/releases/index.mdx b/src/pages/docs/releases/index.mdx
new file mode 100644
index 00000000..8838f995
--- /dev/null
+++ b/src/pages/docs/releases/index.mdx
@@ -0,0 +1,103 @@
+---
+title: Releases
+description: Find your installed Lifecycle versions and the release information for an upgrade.
+audience:
+  - platform-operator
+  - application-developer
+lastVerified: "2026-08-01"
+verificationBaseline: "2026-08-01-lifecycle-mcp-preparation"
+contentProfile: asd-ste100
+tags:
+  - release
+  - version
+  - changelog
+---
+
+Record your installed versions before you upgrade or troubleshoot Lifecycle.
+The chart, application, UI, identity service, CLI, and infrastructure can have
+different versions.
+
+## Find your installed versions
+
+Set the Helm release name and namespace:
+
+```bash
+export LIFECYCLE_RELEASE="<release>"
+export LIFECYCLE_NAMESPACE="<namespace>"
+```
+
+Show the installed chart and application version:
+
+```bash
+helm status "$LIFECYCLE_RELEASE" --namespace "$LIFECYCLE_NAMESPACE"
+```
+
+Record the applied values:
+
+```bash
+helm get values "$LIFECYCLE_RELEASE" \
+  --namespace "$LIFECYCLE_NAMESPACE" \
+  --all
+```
+
+Show the installed CLI version:
+
+```bash
+lfc --version
+```
+
+## Find release information
+
+- Read the [Lifecycle changelog](https://github.com/GoodRxOSS/lifecycle/blob/main/CHANGELOG.md).
+- Read the [Helm chart releases](https://github.com/GoodRxOSS/helm-charts/releases).
+- Read the [Lifecycle CLI releases](https://github.com/GoodRxOSS/lifecycle-cli/releases).
+- Use the schema and API reference from the Lifecycle deployment that you run.
+
+## Before adopting a release
+
+1. Read [Compatibility and deprecation policy](/docs/releases/compatibility).
+2. Follow the [day-two upgrade checklist](/docs/operations/day-two).
+3. Record the installed versions and Helm values.
+4. Read the release notes for each component that changes.
+5. Test the upgrade and restore procedure in a non-production deployment.
+
+## Adopt Lifecycle MCP
+
+The compatible Helm chart includes the credentials that Lifecycle API needs
+for MCP Keycloak configuration. Administrator enablement and change tools are
+off by default.
+
+For a new bundled Keycloak realm, the initial realm import creates the required
+Lifecycle API credentials.
+
+If the Lifecycle realm already exists, complete this migration before you
+enable Lifecycle MCP:
+
+1. Create an enabled confidential OpenID Connect client named `lifecycle-api-keycloak-management`.
+2. Enable service accounts for the client.
+3. Disable the standard, implicit, and direct-access flows.
+4. Set full-scope access to off.
+5. Assign only `manage-clients` and `manage-realm` from the `realm-management` client to the service account.
+6. Add the same roles to the client scope mappings.
+7. Configure its secret to match the Secret referenced by `keycloak.clients.lifecycleApiKeycloakManagement.clientSecret.secretKeyRef`.
+8. Verify that its client-credentials token contains the required roles.
+
+Use your approved external Keycloak administration process. Do not print or
+log the credential. Credential disclosure can compromise Lifecycle Keycloak.
+
+Before the first enablement, record or back up the current anonymous client
+registration policy. Enablement can remove the exact stock `Trusted Hosts`
+component. Disable does not restore it.
+
+1. Confirm the canonical Lifecycle MCP URL.
+2. Open **Platform administration → Lifecycle MCP**.
+3. Enable Lifecycle MCP.
+4. When agents need change tools, enable **Allow changes**.
+5. Add the URL to a compatible client.
+6. Complete Lifecycle OAuth sign-in.
+
+The chart declares the API credentials in its initial realm import. Lifecycle
+configures and verifies the MCP OAuth contract during enablement.
+
+Lifecycle MCP accepts OAuth bearer tokens only. Read [Lifecycle
+MCP](/docs/features/mcp-server) for tools, permissions, and troubleshooting.
diff --git a/src/pages/docs/schema/_meta.ts b/src/pages/docs/schema/_meta.ts
index 602298df..b1ffcd38 100644
--- a/src/pages/docs/schema/_meta.ts
+++ b/src/pages/docs/schema/_meta.ts
@@ -16,13 +16,13 @@
 
 export default {
   "overview": {
-    "title": "Schema Overview"
+    "title": "Schema overview"
   },
   "environment": {
-    "title": "Environment Configuration"
+    "title": "Environment configuration"
   },
   "webhooks": {
-    "title": "Webhooks Configuration"
+    "title": "Webhook configuration"
   },
   "---": {
     "type": "separator"
@@ -44,5 +44,8 @@ export default {
   },
   "configuration": {
     "title": "Configuration Service"
+  },
+  "external-http": {
+    "title": "External HTTP Service"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/schema/aurora-restore.mdx b/src/pages/docs/schema/aurora-restore.mdx
index f1335a3d..17f5a94e 100644
--- a/src/pages/docs/schema/aurora-restore.mdx
+++ b/src/pages/docs/schema/aurora-restore.mdx
@@ -1,6 +1,11 @@
 ---
 title: Aurora Restore Service
-description: Restore AWS Aurora database snapshots for ephemeral environments
+description: Make an AWS Aurora point-in-time copy for an ephemeral Environment.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - aurora
@@ -11,39 +16,38 @@ tags:
 
 import { Callout } from "nextra/components";
 
-The `auroraRestore` service type restores AWS Aurora database snapshots for use in ephemeral environments. This allows you to test against production-like data.
+The `auroraRestore` Service makes an AWS Aurora copy for an ephemeral
+Environment. It uses the latest restorable time of a tagged source cluster.
 
-<Callout type="warning">
-  This documentation is still in progress and will be updated shortly with the
-  latest information.
-</Callout>
+An operator must enable Aurora restore and configure its AWS credentials, region,
+network, engine, and instance values. You cannot supply these installation
+settings in `lifecycle.yaml`. If Aurora restore is not available, ask your
+operator to configure it.
 
-## Required Fields
+## Required fields
 
-| Field       | Type   | Description                                  |
-| ----------- | ------ | -------------------------------------------- |
-| `command`   | string | Command to execute for the restore operation |
-| `arguments` | string | Arguments passed to the command              |
+| Field       | Type   | Description                                       |
+| ----------- | ------ | ------------------------------------------------- |
+| `command`   | string | Path to the built-in Aurora helper.               |
+| `arguments` | string | Source-tag and cost-attribution helper arguments. |
 
 ```yaml filename="lifecycle.yaml"
 services:
-  - name: "database-restore"
+  - name: "database-copy"
     auroraRestore:
-      command: "/restore/run.sh" # Required
-      arguments: "--snapshot-id latest" # Required
+      command: "scripts/aurora-helper.ts"
+      arguments: "--sourceTagKey restore-for --sourceTagValue preview-source --appShort payments"
 ```
 
-## How It Works
+## How it works
 
-1. When the environment is deployed, Lifecycle executes the configured command with arguments
-2. The command typically triggers an Aurora snapshot restore process
-3. Once complete, the restored database is available for other services
+1. Lifecycle finds Aurora clusters that match the source tag.
+2. Lifecycle selects the matching cluster with the latest creation time.
+3. Lifecycle makes a copy at the latest restorable time.
+4. Lifecycle makes an Aurora instance for the new cluster.
+5. Lifecycle makes the cluster endpoint available to other Services.
 
-<Callout type="info">
-  The `auroraRestore` service type is a specialized service that runs a command
-  to initiate database restoration. The actual restore logic is implemented in
-  your command/script.
-</Callout>
+Put only source selection and `appShort` arguments in `arguments`.
 
 ## Example
 
@@ -69,30 +73,29 @@ services:
 
   - name: "aurora-db"
     auroraRestore:
-      command: "/scripts/restore-aurora.sh"
-      arguments: "--cluster my-cluster --snapshot production-backup"
+      command: "scripts/aurora-helper.ts"
+      arguments: "--sourceTagKey restore-for --sourceTagValue preview-source --appShort payments"
 ```
 
-## Use Cases
+## Typical tasks
 
-- **Production data testing** - Test features against realistic production data
-- **Database migrations** - Validate migrations against production schema
-- **Performance testing** - Benchmark against production-scale data
-- **Bug reproduction** - Reproduce issues with production data state
+- Test changes against representative data.
+- Test database migrations against a representative schema.
+- Reproduce a defect that depends on database state.
 
 <Callout type="warning">
-  When restoring from production snapshots, ensure sensitive data is properly
-  anonymized or that access is appropriately restricted.
+  Source data can contain sensitive information. Before you make a copy, apply
+  your necessary data controls and access limits.
 </Callout>
 
-## Implementation Notes
+## Teardown behavior
 
-The restore command is executed as part of the environment deployment process. Your script should:
+Lifecycle deletes the copied instance and cluster during Environment teardown.
 
-1. Handle authentication with AWS
-2. Initiate the snapshot restore
-3. Wait for the restore to complete
-4. Configure network access to the restored instance
-5. Return the connection information
+<Callout type="warning">
+  Teardown does not create a final snapshot. Do not put unique or durable data
+  in the copied cluster.
+</Callout>
 
-The restored database endpoint can then be referenced by other services using template variables.
+Other Services can read the Aurora Service template variables after the cluster
+is ready.
diff --git a/src/pages/docs/schema/codefresh.mdx b/src/pages/docs/schema/codefresh.mdx
index 707e9c1d..b5932333 100644
--- a/src/pages/docs/schema/codefresh.mdx
+++ b/src/pages/docs/schema/codefresh.mdx
@@ -1,6 +1,11 @@
 ---
 title: Codefresh Service
-description: Trigger external Codefresh pipelines for deployment and destruction
+description: Trigger external Codefresh pipelines for deployment and teardown.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - codefresh
@@ -10,7 +15,8 @@ tags:
 
 import { Callout } from "nextra/components";
 
-The `codefresh` service type delegates deployment to external Codefresh pipelines. This is useful when you have existing CI/CD pipelines that handle complex build and deployment logic.
+The `codefresh` Service uses external Codefresh pipelines for deployment. Use
+it when existing CI/CD pipelines contain complex build and deployment logic.
 
 ## Example
 
@@ -25,36 +31,48 @@ services:
         DATABASE_URL: "postgres://{{database_internalHostname}}:5432/app"
         CACHE_URL: "redis://{{cache_internalHostname}}:6379"
         LOG_LEVEL: "info"
-      deploy: # Required - deployment pipeline configuration
+      deploy: # Required for deployment
         pipelineId: "64598362453cc650c0c9cd4d" # Codefresh pipeline ID for deployment
-        trigger: "lifecycle-deploy" # Pipeline trigger name
-      destroy: # Required - destruction pipeline configuration
+        trigger: "lifecycle-deploy" # Optional pipeline trigger name
+      destroy: # Required for teardown
         pipelineId: "74283905723ff650c0d9ab7e" # Codefresh pipeline ID for destruction
-        trigger: "lifecycle-destroy" # Pipeline trigger name
+        trigger: "lifecycle-destroy" # Optional pipeline trigger name
 ```
 
-## Required Fields
+## Required fields
 
 | Field                | Type   | Description                              |
 | -------------------- | ------ | ---------------------------------------- |
 | `repository`         | string | GitHub repository in `owner/repo` format |
 | `branchName`         | string | Branch to build from                     |
 | `deploy.pipelineId`  | string | Codefresh pipeline ID for deployment     |
-| `deploy.trigger`     | string | Pipeline trigger name for deployment     |
 | `destroy.pipelineId` | string | Codefresh pipeline ID for destruction    |
-| `destroy.trigger`    | string | Pipeline trigger name for destruction    |
 
-## Optional Fields
+## Optional fields
 
-| Field | Type   | Description                               |
-| ----- | ------ | ----------------------------------------- |
-| `env` | object | Environment variables passed to pipelines |
+| Field             | Type   | Description                               |
+| ----------------- | ------ | ----------------------------------------- |
+| `env`             | object | Environment variables passed to pipelines |
+| `deploy.trigger`  | string | Pipeline trigger name for deployment      |
+| `destroy.trigger` | string | Pipeline trigger name for destruction     |
 
-## Pipeline Configuration
+<Callout type="warning">
+  Set `repository`, `branchName`, and both pipeline IDs. A missing pipeline ID
+  causes the related deployment or teardown operation to fail.
+</Callout>
+
+## Authentication
+
+Before you run Codefresh Services or the Docker `ci` builder, configure
+`CODEFRESH_API_KEY` in Lifecycle. Ask the operator to supply this credential
+through the approved Secret process. Use the same process to rotate it. Do not
+put it in `lifecycle.yaml`.
+
+## Pipeline configuration
 
 ### deploy
 
-Configure the pipeline triggered when deploying the service.
+Configure the pipeline that deploys the Service.
 
 ```yaml
 codefresh:
@@ -65,7 +83,7 @@ codefresh:
 
 ### destroy
 
-Configure the pipeline triggered when tearing down the environment.
+Configure the pipeline that tears down the Environment.
 
 ```yaml
 codefresh:
@@ -74,9 +92,9 @@ codefresh:
     trigger: "destroy"
 ```
 
-## Environment Variables
+## Environment variables
 
-Pass environment variables to both deploy and destroy pipelines:
+Pass environment variables to the deploy and destroy pipelines:
 
 ```yaml
 codefresh:
@@ -89,32 +107,37 @@ codefresh:
 ```
 
 <Callout type="info">
-  Environment variables defined in `env` are passed to both deploy and destroy
-  pipelines. Use template variables to reference other services.
+  Environment variables in `env` go to the deploy and destroy pipelines.
+  Template variables can refer to other Services. Full-value cloud secret
+  references resolve before invocation. More information is in [Cloud
+  Secrets](/docs/features/secrets#use-secrets-with-codefresh).
 </Callout>
 
-## How It Works
+## How it works
 
-1. When an environment is deployed, Lifecycle triggers the `deploy` pipeline with the configured environment variables.
-2. The pipeline receives context about the deployment including branch, namespace, and service information.
-3. When the environment is torn down, Lifecycle triggers the `destroy` pipeline to clean up resources.
+1. When Lifecycle deploys an Environment, it triggers the `deploy` pipeline
+   with the configured environment variables.
+2. The pipeline receives the branch, namespace, and Service information.
+3. When Lifecycle tears down the Environment, it triggers the `destroy`
+   pipeline to remove resources.
 
-## Use Cases
+## Typical tasks
 
-- **Complex build processes** - When builds require multi-stage pipelines or custom tooling
-- **External dependencies** - When deployment requires interaction with external systems
-- **Existing CI/CD** - When you have established Codefresh pipelines you want to reuse
-- **Custom deployment logic** - When standard Kubernetes deployment isn't sufficient
+- **Complex builds** — Multi-stage pipelines or custom tooling.
+- **External dependencies** — Deployments that interact with external systems.
+- **Existing CI/CD** — Established Codefresh pipelines.
+- **Custom deployment logic** — Deployments that standard Kubernetes
+  configuration cannot express.
 
 <Callout type="warning">
   Codefresh pipelines run asynchronously. Lifecycle tracks pipeline status but
-  the actual deployment logic is managed by Codefresh.
+  Codefresh manages the deployment logic.
 </Callout>
 
-## Finding Pipeline IDs
+## Find pipeline IDs
 
 To find your Codefresh pipeline ID:
 
-1. Open your pipeline in Codefresh
-2. The pipeline ID is in the URL: `https://g.codefresh.io/pipelines/edit/new/.../<pipeline-id>`
-3. Or use the Codefresh CLI: `codefresh get pipelines`
+1. Open your pipeline in Codefresh.
+2. Find the pipeline ID in the URL: `https://g.codefresh.io/pipelines/edit/new/.../<pipeline-id>`.
+3. Or, run `codefresh get pipelines`.
diff --git a/src/pages/docs/schema/configuration.mdx b/src/pages/docs/schema/configuration.mdx
index cb93227c..b0565e8d 100644
--- a/src/pages/docs/schema/configuration.mdx
+++ b/src/pages/docs/schema/configuration.mdx
@@ -1,6 +1,11 @@
 ---
 title: Configuration Service
-description: Deploy configuration-only services for feature flags and shared configuration
+description: Deploy configuration-only Services for feature flags and shared configuration.
+audience:
+  - application-developer
+lastVerified: "2026-08-01"
+verificationBaseline: "2026-08-01-configuration-schema-fix"
+contentProfile: asd-ste100
 tags:
   - schema
   - configuration
@@ -10,40 +15,54 @@ tags:
 
 import { Callout } from "nextra/components";
 
-The `configuration` service type creates a configuration-only service that doesn't deploy any containers. It's useful for managing feature flags, shared configuration, or service metadata that other services can reference.
+Use a `configuration` Service to make shared string values available to other
+Services without deploying a container or pod.
+
+## Fields
+
+| Field        | Type              | Required | Description                              |
+| ------------ | ----------------- | -------- | ---------------------------------------- |
+| `data`       | object of strings | Yes      | Values added to the template environment |
+| `branchName` | string            | No       | Optional branch metadata                 |
 
 <Callout type="warning">
-  This documentation is still in progress and will be updated shortly with the
-  latest information.
+  Set `data`. You can set `branchName`. Do not set `defaultTag` because
+  Lifecycle rejects it. Before you push the file, run `lfc schema validate
+  lifecycle.yaml`.
 </Callout>
 
-## Required Fields
+```yaml filename="lifecycle.yaml"
+version: "1.0.0"
 
-| Field        | Type   | Description                          |
-| ------------ | ------ | ------------------------------------ |
-| `defaultTag` | string | Configuration version tag            |
-| `branchName` | string | Branch name for configuration source |
+environment:
+  defaultServices:
+    - name: "api"
+    - name: "shared-config"
 
-```yaml filename="lifecycle.yaml"
 services:
-  - name: "config"
+  - name: "shared-config"
     configuration:
-      defaultTag: "v1.0.0" # Required
-      branchName: "main" # Required
+      data:
+        FEATURE_MODE: "preview"
+        LOG_LEVEL: "debug"
+      branchName: "main"
 ```
 
-## How It Works
+## How it works
 
-A configuration service:
+A configuration Service:
 
-1. Does not deploy any containers or pods
-2. Registers a service entry in Lifecycle for reference by other services
-3. Provides a way to version and track configuration changes
-4. Can be referenced by other services using template variables
+1. Lifecycle does not deploy containers or pods for the Service.
+2. Lifecycle adds each `data` key to the template variables for other Services.
+
+Lifecycle does not prefix configuration keys with the Service name. For
+example, `FEATURE_MODE` becomes `{{FEATURE_MODE}}`.
 
 ## Example
 
 ```yaml filename="lifecycle.yaml"
+version: "1.0.0"
+
 environment:
   defaultServices:
     - name: "api"
@@ -59,40 +78,43 @@ services:
         app:
           dockerfilePath: "Dockerfile"
           env:
-            CONFIG_VERSION: "{{feature-flags_branchName}}"
+            FEATURE_MODE: "{{FEATURE_MODE}}"
+            CONFIG_LOG_LEVEL: "{{CONFIG_LOG_LEVEL}}"
           ports:
             - 3000
 
   - name: "feature-flags"
     configuration:
-      defaultTag: "v2.1.0"
-      branchName: "main"
+      data:
+        FEATURE_MODE: "preview"
+        CONFIG_LOG_LEVEL: "info"
 ```
 
-## Use Cases
+## Typical tasks
 
-### Feature Flags
+### Feature flags
 
-Track feature flag configuration versions:
+Share feature switches with deployed Services:
 
 ```yaml
 services:
   - name: "feature-flags"
     configuration:
-      defaultTag: "2024.01.15"
-      branchName: "main"
+      data:
+        ENABLE_NEW_CHECKOUT: "true"
+        CHECKOUT_VARIANT: "preview"
 ```
 
-### Shared Configuration
+### Shared configuration
 
-Reference shared configuration across services:
+Make the same values available to multiple Services:
 
 ```yaml
 services:
   - name: "shared-config"
     configuration:
-      defaultTag: "v1.0.0"
-      branchName: "production"
+      data:
+        CONFIG_BRANCH: "production"
 
   - name: "api"
     github:
@@ -103,7 +125,7 @@ services:
         app:
           dockerfilePath: "Dockerfile"
           env:
-            CONFIG_BRANCH: "{{shared-config_branchName}}"
+            CONFIG_BRANCH: "{{CONFIG_BRANCH}}"
 
   - name: "worker"
     github:
@@ -114,23 +136,36 @@ services:
         app:
           dockerfilePath: "Dockerfile"
           env:
-            CONFIG_BRANCH: "{{shared-config_branchName}}"
+            CONFIG_BRANCH: "{{CONFIG_BRANCH}}"
 ```
 
-### Environment Metadata
+### Environment metadata
 
-Track environment-specific metadata:
+Use shared data with built-in template variables:
 
 ```yaml
 services:
   - name: "env-metadata"
     configuration:
-      defaultTag: "ephemeral"
-      branchName: "{{PR_BRANCH}}"
+      data:
+        DEPLOYMENT_TIER: "ephemeral"
+
+  - name: "api"
+    github:
+      repository: "myorg/api"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "Dockerfile"
+          env:
+            DEPLOYMENT_TIER: "{{DEPLOYMENT_TIER}}"
+            SOURCE_BRANCH: "{{branchName}}"
 ```
 
 <Callout type="info">
-  Configuration services are lightweight entries in Lifecycle's service
-  registry. They don't consume cluster resources but allow other services to
-  reference configuration state.
+  Configuration Services do not consume workload resources.
 </Callout>
+
+Include the configuration Service in the Environment. Its data is then
+available during template rendering.
diff --git a/src/pages/docs/schema/docker.mdx b/src/pages/docs/schema/docker.mdx
index a7cccc39..fc38a510 100644
--- a/src/pages/docs/schema/docker.mdx
+++ b/src/pages/docs/schema/docker.mdx
@@ -1,6 +1,11 @@
 ---
 title: Docker Service
-description: Deploy pre-built Docker images like databases, caches, and other infrastructure components
+description: Deploy pre-built Docker images for databases, caches, and other infrastructure components.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - docker
@@ -12,11 +17,16 @@ tags:
 import { Callout } from "nextra/components";
 import { Tabs } from "nextra/components";
 
-The `docker` service type deploys pre-built Docker images without building from source. This is ideal for databases, caches, message queues, and other infrastructure components.
+The `docker` Service deploys a pre-built Docker image. Lifecycle does not build
+source for this Service type.
+
+The examples use AWS-style [cloud-secret
+references](/docs/features/secrets). Replace them with a provider and path from
+your Lifecycle operator. Do not commit passwords to `lifecycle.yaml`.
 
 ## Examples
 
-<Tabs items={["PostgreSQL", "Redis", "MySQL with Persistence", "Complete"]}>
+<Tabs items={["PostgreSQL", "Redis", "MySQL with Persistence", "All fields"]}>
 
 <Tabs.Tab>
 PostgreSQL database (internal only):
@@ -31,17 +41,17 @@ services:
         - 5432
       env:
         POSTGRES_USER: "app"
-        POSTGRES_PASSWORD: "secret"
+        POSTGRES_PASSWORD: "{{aws:preview/postgres:password}}"
         POSTGRES_DB: "myapp"
       deployment:
         public: false # No ingress - internal only
 ```
 
-Reference from other services:
+For other Services:
 
 ```yaml
 env:
-  DATABASE_URL: "postgres://app:secret@{{database_internalHostname}}:5432/myapp"
+  DATABASE_HOST: "{{database_internalHostname}}"
 ```
 
 </Tabs.Tab>
@@ -67,7 +77,7 @@ services:
             limit: "256Mi"
 ```
 
-Reference from other services:
+For other Services:
 
 ```yaml
 env:
@@ -88,10 +98,10 @@ services:
       ports:
         - 3306
       env:
-        MYSQL_ROOT_PASSWORD: "rootpassword"
+        MYSQL_ROOT_PASSWORD: "{{aws:preview/mysql:root-password}}"
         MYSQL_DATABASE: "myapp"
         MYSQL_USER: "app"
-        MYSQL_PASSWORD: "apppassword"
+        MYSQL_PASSWORD: "{{aws:preview/mysql:app-password}}"
       deployment:
         public: false
         resource:
@@ -113,7 +123,7 @@ services:
 </Tabs.Tab>
 
 <Tabs.Tab>
-Complete configuration with all options:
+Expanded configuration with all options:
 
 ```yaml filename="lifecycle.yaml"
 services:
@@ -127,12 +137,12 @@ services:
         - 5432
       env:
         POSTGRES_USER: "app"
-        POSTGRES_PASSWORD: "secret"
+        POSTGRES_PASSWORD: "{{aws:preview/postgres:password}}"
         POSTGRES_DB: "myapp"
         PGDATA: "/var/lib/postgresql/data/pgdata"
       deployment:
         public: false # false = internal only, no ingress
-        capacityType: "on-demand" # Options: spot, on-demand
+        capacityType: "ON_DEMAND" # Options: SPOT, ON_DEMAND
         resource: # Custom CPU/memory requests and limits
           cpu:
             request: "250m"
@@ -156,48 +166,55 @@ services:
 
 </Tabs>
 
-## Fields Reference
+## Field reference
 
-### Required Fields
+### Required fields
 
-| Field         | Type   | Description                                   |
-| ------------- | ------ | --------------------------------------------- |
-| `dockerImage` | string | Docker image name (e.g., `postgres`, `redis`) |
-| `defaultTag`  | string | Image tag (e.g., `15-alpine`, `7-alpine`)     |
+| Field         | Type   | Description                                           |
+| ------------- | ------ | ----------------------------------------------------- |
+| `dockerImage` | string | Docker image name, for example, `postgres` or `redis` |
+| `defaultTag`  | string | Image tag, for example, `15-alpine` or `7-alpine`     |
 
-### Optional Fields
+### Optional fields
 
-| Field        | Type    | Description                                                                              |
-| ------------ | ------- | ---------------------------------------------------------------------------------------- |
-| `command`    | string  | Override container entrypoint                                                            |
-| `arguments`  | string  | Arguments passed to the command. Use `%%SPLIT%%` for spaces                              |
-| `env`        | object  | Environment variables                                                                    |
-| `ports`      | array   | Exposed container ports                                                                  |
-| `deployment` | object  | Deployment configuration (see below)                                                     |
-| `envLens`    | boolean | Enable environment lens ingress banner. Overrides the global `features.envLens` default. |
+| Field        | Type    | Description                                                   |
+| ------------ | ------- | ------------------------------------------------------------- |
+| `command`    | string  | Override container entrypoint                                 |
+| `arguments`  | string  | Arguments passed to the command. Use `%%SPLIT%%` for spaces   |
+| `env`        | object  | Environment variables                                         |
+| `ports`      | array   | Exposed container ports                                       |
+| `deployment` | object  | Deployment configuration. See the Deployment options section. |
+| `envLens`    | boolean | Enable the Environment Lens ingress banner                    |
 
-## Deployment Options
+## Deployment options
 
-The `deployment` section configures how the service is deployed to Kubernetes. All fields are optional.
+The `deployment` section configures how Lifecycle deploys the Service to
+Kubernetes. All fields are optional.
 
-See [GitHub Service - Deployment Options](/docs/schema/github#deployment-options) for detailed documentation of each field.
+See [GitHub Service deployment options](/docs/schema/github#deployment-options)
+for information about each field.
 
-| Field          | Description                                                               |
-| -------------- | ------------------------------------------------------------------------- |
-| `public`       | `true` = creates ingress, `false` = internal only                         |
-| `capacityType` | Node type: `spot` or `on-demand`                                          |
-| `resource`     | CPU and memory requests/limits                                            |
-| `readiness`    | Health check using `httpGet` or `tcpSocketPort`                           |
-| `hostnames`    | Custom hostname config (auto-constructed from `global_config` if omitted) |
-| `network`      | IP whitelist, port mapping, gRPC support                                  |
-| `serviceDisks` | Persistent volume mounts                                                  |
+| Field          | Description                                                             |
+| -------------- | ----------------------------------------------------------------------- |
+| `public`       | `true` = creates ingress, `false` = internal only                       |
+| `capacityType` | Node type: `SPOT` (default) or `ON_DEMAND`                              |
+| `resource`     | CPU and memory requests/limits                                          |
+| `readiness`    | Health check using `httpGet` or `tcpSocketPort`                         |
+| `hostnames`    | Custom hostname configuration. Lifecycle generates hostnames if omitted |
+| `network`      | IP whitelist, port mapping, gRPC support                                |
+| `serviceDisks` | Persistent volume mounts                                                |
 
 <Callout type="info">
-  For databases and caches, you typically want `public: false` to keep them
-  internal to the cluster.
+  `public: false` keeps a database or cache internal to the cluster.
+</Callout>
+
+For a database or cache that needs only cluster access, set `public: false`.
+
+<Callout type="warning">
+  Use `SPOT` or `ON_DEMAND`. Other spellings can prevent workload scheduling.
 </Callout>
 
-## Common Images
+## Typical images
 
 ### Databases
 
@@ -210,9 +227,10 @@ docker:
     - 5432
   env:
     POSTGRES_USER: "user"
-    POSTGRES_PASSWORD: "pass"
+    POSTGRES_PASSWORD: "{{aws:preview/postgres:password}}"
     POSTGRES_DB: "db"
 
+---
 # MySQL
 docker:
   dockerImage: "mysql"
@@ -220,9 +238,10 @@ docker:
   ports:
     - 3306
   env:
-    MYSQL_ROOT_PASSWORD: "root"
+    MYSQL_ROOT_PASSWORD: "{{aws:preview/mysql:root-password}}"
     MYSQL_DATABASE: "db"
 
+---
 # MongoDB
 docker:
   dockerImage: "mongo"
@@ -231,10 +250,10 @@ docker:
     - 27017
   env:
     MONGO_INITDB_ROOT_USERNAME: "admin"
-    MONGO_INITDB_ROOT_PASSWORD: "pass"
+    MONGO_INITDB_ROOT_PASSWORD: "{{aws:preview/mongodb:password}}"
 ```
 
-### Caches & Queues
+### Caches and queues
 
 ```yaml
 # Redis
@@ -244,6 +263,7 @@ docker:
   ports:
     - 6379
 
+---
 # Memcached
 docker:
   dockerImage: "memcached"
@@ -251,6 +271,7 @@ docker:
   ports:
     - 11211
 
+---
 # RabbitMQ
 docker:
   dockerImage: "rabbitmq"
@@ -260,5 +281,5 @@ docker:
     - 15672
   env:
     RABBITMQ_DEFAULT_USER: "guest"
-    RABBITMQ_DEFAULT_PASS: "guest"
+    RABBITMQ_DEFAULT_PASS: "{{aws:preview/rabbitmq:password}}"
 ```
diff --git a/src/pages/docs/schema/environment.mdx b/src/pages/docs/schema/environment.mdx
index 4d6a7c94..3196b019 100644
--- a/src/pages/docs/schema/environment.mdx
+++ b/src/pages/docs/schema/environment.mdx
@@ -1,6 +1,11 @@
 ---
-title: Environment Configuration
-description: Configure deployment behavior, service grouping, and automation for ephemeral environments
+title: Environment configuration
+description: Configure deployment behavior, Service groups, and automation for ephemeral Environments.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - environment
@@ -11,23 +16,32 @@ tags:
 import { Callout } from "nextra/components";
 import { Tabs } from "nextra/components";
 
-The `environment` section controls how Lifecycle deploys and manages your ephemeral environments. It defines which services are deployed by default, which are optional, and how automation (webhooks) should behave.
+The `environment` section controls each ephemeral Environment. It selects
+default Services, optional Services, and webhook automation.
 
-## Fields Reference
+## Field reference
 
-| Field                    | Type    | Required | Description                              |
-| ------------------------ | ------- | -------- | ---------------------------------------- |
-| `autoDeploy`             | boolean | No       | Automatically deploy on PR updates       |
-| `defaultServices`        | array   | Yes      | Services deployed with every environment |
-| `optionalServices`       | array   | No       | Services available on-demand             |
-| `webhooks`               | array   | No       | Automation triggers on state changes     |
-| `enabledFeatures`        | array   | No       | Feature flags for the environment        |
-| `githubDeployments`      | boolean | No       | Create GitHub deployment records         |
-| `useGithubStatusComment` | boolean | No       | Post status comments on PRs              |
+| Field               | Type    | Required | Description                                |
+| ------------------- | ------- | -------- | ------------------------------------------ |
+| `autoDeploy`        | boolean | No       | Automatically deploy on PR updates         |
+| `defaultServices`   | array   | No       | Services active when an Environment starts |
+| `optionalServices`  | array   | No       | Services available on demand               |
+| `ignoreFiles`       | array   | No       | Shared push-redeploy ignore patterns       |
+| `webhooks`          | array   | No       | Automation triggers on state changes       |
+| `enabledFeatures`   | array   | No       | Per-Environment behavior flags             |
+| `githubDeployments` | boolean | No       | Create GitHub deployment records           |
+
+<Callout type="warning">
+  Do not use `useGithubStatusComment`. It has no effect. Use [configurable
+  labels](/docs/features/configurable-labels) for GitHub comment behavior.
+</Callout>
 
 ## defaultServices
 
-Services listed in `defaultServices` are deployed automatically when an environment is created. At least one default service is required.
+Lifecycle automatically deploys the Services in `defaultServices` when it
+creates an Environment. This field is optional. If `defaultServices` and
+`optionalServices` are missing, Lifecycle activates all Services in the same
+`lifecycle.yaml`.
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -37,16 +51,21 @@ environment:
     - name: "database"
 ```
 
-### Service Reference Fields
+### Service reference fields
 
-Each entry in `defaultServices` can include optional fields to override the service configuration:
+Each entry in `defaultServices` can include optional fields that override the
+Service configuration:
 
 | Field        | Type   | Description                                                   |
 | ------------ | ------ | ------------------------------------------------------------- |
 | `name`       | string | **Required.** Name matching a service in the `services` array |
 | `repository` | string | Override the repository for this service                      |
 | `branch`     | string | Override the branch for this service                          |
-| `serviceId`  | number | Internal service ID reference                                 |
+
+<Callout type="warning">
+  Specify Services by `name`. Do not use `serviceId`. It causes an unsupported
+  field error. You can also add `repository` and `branch`.
+</Callout>
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -58,7 +77,8 @@ environment:
 
 ## optionalServices
 
-Services listed in `optionalServices` are not deployed by default but can be added to an environment on-demand through the Lifecycle UI or API.
+Lifecycle does not deploy `optionalServices` by default. Add them through the
+Lifecycle UI or API when an Environment needs them.
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -74,14 +94,14 @@ environment:
 ```
 
 <Callout type="info">
-  Optional services are useful for components that aren't always needed, like
-  background workers, caching layers, or additional databases for specific
-  testing scenarios.
+  Optional Services are useful for components that are not always necessary.
+  Examples include workers, caches, and more test databases.
 </Callout>
 
 ## autoDeploy
 
-When `autoDeploy` is enabled, Lifecycle automatically triggers a deployment whenever the PR is updated (new commits pushed).
+When `autoDeploy` is enabled, Lifecycle starts a deployment after each new
+commit on the pull request.
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -91,13 +111,28 @@ environment:
 ```
 
 <Callout type="info">
-  With `autoDeploy: true`, environments are created automatically on every
-  commit to the PR branch without requiring manual label addition.
+  With `autoDeploy: true`, Lifecycle automatically creates Environments for each
+  commit to the pull-request branch. No manual label is necessary.
 </Callout>
 
+## ignoreFiles
+
+`ignoreFiles` contains repo-relative glob patterns shared by all Services in
+the Environment. An operator must also enable the global feature flag. See
+[Ignore File Patterns](/docs/features/ignore-file-patterns) before relying on a
+push skip.
+
+## enabledFeatures
+
+You can use this feature value:
+
+- `no-default-env-resolve` — do not substitute an unselected service's static
+  Environment hostname.
+
 ## webhooks
 
-Webhooks allow you to trigger external actions when the environment reaches certain states. See the [Webhooks](/docs/schema/webhooks) page for detailed configuration.
+Webhooks start external actions at specified Environment states. See
+[Webhooks](/docs/schema/webhooks) for the configuration.
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -115,10 +150,10 @@ environment:
 
 ## Examples
 
-<Tabs items={["Minimal", "With Optional Services", "Complete"]}>
+<Tabs items={["Minimal", "Optional Services", "All fields"]}>
 
 <Tabs.Tab>
-The minimal configuration requires only `defaultServices`:
+To select a subset explicitly, add `defaultServices`:
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -129,7 +164,7 @@ environment:
 </Tabs.Tab>
 
 <Tabs.Tab>
-Configuration with both default and optional services:
+Configuration with default and optional Services:
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -153,13 +188,12 @@ environment:
 </Tabs.Tab>
 
 <Tabs.Tab>
-Complete configuration with all options:
+Expanded configuration with all options:
 
 ```yaml filename="lifecycle.yaml"
 environment:
   autoDeploy: true
   githubDeployments: true
-  useGithubStatusComment: true
 
   defaultServices:
     - name: "api"
@@ -184,21 +218,49 @@ environment:
         API_URL: "https://{{api_publicUrl}}"
         FRONTEND_URL: "https://{{frontend_publicUrl}}"
 
-    # Notify on errors
-    - name: "Slack Alert"
+    # Record errors with a non-secret receiver
+    - name: "Record Deployment Error"
       state: error
       type: command
       command:
         image: "alpine:latest"
         script: |
           apk add --no-cache curl
-          curl -X POST "$SLACK_WEBHOOK" \
+          curl --fail --request POST "$EVENT_ENDPOINT" \
             -H "Content-Type: application/json" \
-            -d '{"text":"Deployment failed for PR"}'
+            -d '{"event":"deployment_error"}'
       env:
-        SLACK_WEBHOOK: "https://hooks.slack.com/services/XXX/YYY/ZZZ"
+        EVENT_ENDPOINT: "https://events.example.org/lifecycle"
 ```
 
 </Tabs.Tab>
 
 </Tabs>
+
+## Environment and Service statuses
+
+The UI, API, CLI, and webhook configuration have related but different status
+sets.
+
+### Environment statuses
+
+| Status         | Meaning                                     |
+| -------------- | ------------------------------------------- |
+| `pending`      | Waiting for orchestration to begin          |
+| `queued`       | Lifecycle queued the work                   |
+| `building`     | Lifecycle builds one or more Service images |
+| `built`        | Image builds completed                      |
+| `deploying`    | Lifecycle deploys Services                  |
+| `deployed`     | The Environment deployed without errors     |
+| `tearing_down` | Teardown is in progress                     |
+| `torn_down`    | Teardown completed                          |
+| `error`        | Build or deployment failed                  |
+| `config_error` | Lifecycle could not apply configuration     |
+
+### Service Deploy statuses
+
+A Service can also report `cloning`, `ready`, `waiting`, `build_failed`, and
+`deploy_failed`. Examine the affected Service when one of these appears.
+
+Only lowercase `deployed`, `error`, and `torn_down` start `lifecycle.yaml`
+webhooks. See [Webhook configuration](/docs/schema/webhooks).
diff --git a/src/pages/docs/schema/external-http.mdx b/src/pages/docs/schema/external-http.mdx
new file mode 100644
index 00000000..95d22279
--- /dev/null
+++ b/src/pages/docs/schema/external-http.mdx
@@ -0,0 +1,54 @@
+---
+title: External HTTP Service
+description: Use an existing hosted HTTP dependency. Lifecycle does not build or deploy it.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - schema
+  - service
+  - external
+---
+
+An `externalHttp` Service defines an HTTP dependency that runs outside the
+Lifecycle Environment. Lifecycle marks the Service ready without creating a
+workload. It makes the configured endpoints available to dependent Services.
+
+## Schema
+
+```yaml filename="lifecycle.yaml"
+version: "1.0.0"
+
+services:
+  - name: payments-api
+    externalHttp:
+      defaultInternalHostname: payments-api.shared.svc.cluster.local
+      defaultPublicUrl: https://payments.preview.example
+```
+
+| Field                     | Required | Description                                                       |
+| ------------------------- | -------- | ----------------------------------------------------------------- |
+| `defaultInternalHostname` | Yes      | Cluster-reachable fallback hostname used by other Services.       |
+| `defaultPublicUrl`        | Yes      | Public fallback URL exposed for users and URL template variables. |
+
+Use `externalHttp` as the nested key.
+
+## When to use it
+
+Use `externalHttp` for a dependency with all these properties:
+
+- a team outside Lifecycle manages it
+- appears in Service resolution and generated variables
+- has stable internal and public endpoints.
+
+Do not use it for a Service that Lifecycle must build or deploy. Select
+`github`, `docker`, `helm`, `codefresh`, or a different supported deployable
+type.
+
+## Environment overrides
+
+An Environment can point an eligible external HTTP Service at a different URL.
+Make sure that the user and applicable workloads can reach the new target.
+Lifecycle does not provision, monitor, or remove the external system.
diff --git a/src/pages/docs/schema/github.mdx b/src/pages/docs/schema/github.mdx
index 46720646..2949a7f3 100644
--- a/src/pages/docs/schema/github.mdx
+++ b/src/pages/docs/schema/github.mdx
@@ -1,6 +1,11 @@
 ---
 title: GitHub Service
-description: Build and deploy services from GitHub repositories with Docker
+description: Build and deploy Services from GitHub repositories with Docker.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - github
@@ -12,11 +17,13 @@ tags:
 import { Callout } from "nextra/components";
 import { Tabs } from "nextra/components";
 
-The `github` service type builds and deploys applications from a GitHub repository using a Dockerfile. This is the most common service type for application code that needs to be built from source.
+The `github` Service type builds and deploys applications from a GitHub
+repository with a Dockerfile. Use this Service type for application code that
+Lifecycle must build from source.
 
 ## Examples
 
-<Tabs items={["Minimal", "With Deployment Options", "Complete"]}>
+<Tabs items={["Minimal", "Deployment options", "All fields"]}>
 
 <Tabs.Tab>
 Minimal configuration with only required fields:
@@ -49,7 +56,7 @@ services:
       docker:
         defaultTag: "main"
         builder:
-          engine: "buildkit" # Options: buildkit (default), codefresh, kaniko
+          engine: "buildkit" # Options: buildkit, kaniko, ci
         app:
           dockerfilePath: "Dockerfile"
           env:
@@ -77,7 +84,7 @@ services:
 </Tabs.Tab>
 
 <Tabs.Tab>
-Complete configuration with all options:
+Expanded configuration with all options:
 
 ```yaml filename="lifecycle.yaml"
 services:
@@ -88,7 +95,7 @@ services:
       docker:
         defaultTag: "main"
         builder:
-          engine: "buildkit" # Options: buildkit (default), codefresh, kaniko
+          engine: "buildkit" # Options: buildkit, kaniko, ci
           resources: # Optional - custom CPU/memory for the build job
             requests:
               cpu: "1"
@@ -119,7 +126,7 @@ services:
             - 9090
       deployment:
         public: true # true = creates ingress, false = internal only
-        capacityType: "spot" # Options: spot, on-demand
+        capacityType: "SPOT" # Options: SPOT, ON_DEMAND
         resource: # Custom CPU/memory requests and limits
           cpu:
             request: "100m"
@@ -135,7 +142,7 @@ services:
           periodSeconds: 10 # Check interval
           timeoutSeconds: 5 # Check timeout
           failureThreshold: 3 # Failures before unhealthy
-        hostnames: # Optional - auto-constructed from global_config if omitted
+        hostnames: # Optional - Lifecycle generates hostnames if omitted
           host: "api.example.com"
           defaultPublicUrl: "api.myapp.example.com"
         network: # Optional - advanced routing
@@ -158,9 +165,9 @@ services:
 
 </Tabs>
 
-## Docker Configuration
+## Docker configuration
 
-The `docker` section defines how the application is built and run.
+The `docker` section defines how Lifecycle builds and runs the application.
 
 ### docker.defaultTag
 
@@ -168,111 +175,155 @@ The default Docker image tag, typically matching the branch name.
 
 ### docker.builder
 
-Configuration for the Docker build process.
+Configuration for the Docker build operation.
 
-| Field                | Type                    | Description                                                                        |
-| -------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
-| `engine`             | string                  | Build engine: `buildkit` (default), `kaniko`, `codefresh`                          |
-| `resources.requests` | object                  | Minimum CPU/memory guaranteed for the build job                                    |
-| `resources.limits`   | object                  | Maximum CPU/memory allowed for the build job                                       |
-| `podAnnotations`     | `Record<string,string>` | Custom annotations applied to the build pod template (merged with global defaults) |
+| Field                | Type                    | Description                                          |
+| -------------------- | ----------------------- | ---------------------------------------------------- |
+| `engine`             | string                  | Build engine: `buildkit`, `kaniko`, or `ci`          |
+| `resources.requests` | object                  | Minimum CPU/memory guaranteed for the build job      |
+| `resources.limits`   | object                  | Maximum CPU/memory allowed for the build job         |
+| `podAnnotations`     | `Record<string,string>` | Custom annotations applied to the build pod template |
 
-The `resources` field lets you configure CPU and memory for the build job container. Values use standard Kubernetes resource units (e.g., `"500m"` for CPU, `"1Gi"` for memory).
+The `resources` field configures CPU and memory for the build Job container.
+Use standard Kubernetes resource units. For example, use `"500m"` for CPU and
+`"1Gi"` for memory.
 
-**Precedence:** Per-service `resources` in lifecycle.yaml take priority over values set in `global_config`. If neither is set, built-in defaults are used.
+Service resource values replace the installation defaults. If you need a
+specific build engine, set `engine` explicitly. For `engine: ci`, also set
+`docker.pipelineId` to the Codefresh image-build pipeline.
 
 <Callout type="info">
-  Build pods automatically include the annotation
+  Each build pod automatically has the annotation
   `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"` to prevent the
   Kubernetes cluster autoscaler from evicting long-running build jobs during
-  scale-down. You can add custom annotations per-service via `podAnnotations`
-  above, or globally via `podAnnotations` in `global_config.buildDefaults`.
-  Per-service values override global defaults, and the hardcoded `safe-to-evict`
-  annotation cannot be overridden.
+  scale-down. The `podAnnotations` field adds Service annotations. It cannot
+  override the `safe-to-evict` value.
 </Callout>
 
-| Engine   | Default CPU Request | Default Memory Request | Default CPU Limit | Default Memory Limit |
+| Engine   | Default CPU request | Default memory request | Default CPU limit | Default memory limit |
 | -------- | ------------------- | ---------------------- | ----------------- | -------------------- |
 | buildkit | 500m                | 1Gi                    | 2                 | 4Gi                  |
 | kaniko   | 300m                | 750Mi                  | 1                 | 2Gi                  |
 
 ```yaml filename="lifecycle.yaml"
-docker:
-  builder:
-    engine: "buildkit"
-    resources:
-      requests:
-        cpu: "1"
-        memory: "2Gi"
-      limits:
-        cpu: "4"
-        memory: "8Gi"
-    podAnnotations:
-      my-org/team: "backend"
-      my-org/cost-center: "engineering"
+services:
+  - name: "api"
+    github:
+      repository: "myorg/api"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        builder:
+          engine: "buildkit"
+          resources:
+            requests:
+              cpu: "1"
+              memory: "2Gi"
+            limits:
+              cpu: "4"
+              memory: "8Gi"
+          podAnnotations:
+            my-org/team: "backend"
+            my-org/cost-center: "engineering"
+        app:
+          dockerfilePath: "Dockerfile"
 ```
 
-### docker.app (Required)
+### docker.app (required)
 
 Configuration for the main application container:
 
 - `dockerfilePath` - **Required.** Path to Dockerfile relative to repo root
 - `command` - Override container entrypoint
-- `arguments` - Arguments passed to the command. Use `%%SPLIT%%` as a delimiter for spaces (e.g., `-c%%SPLIT%%npm run start`)
+- `arguments` - Arguments passed to the command. Use `%%SPLIT%%` to delimit
+  spaces, for example, `-c%%SPLIT%%npm run start`.
 - `env` - Environment variables
 - `ports` - Exposed container ports
 
-### docker.init (Optional)
+Optional Docker-level fields:
+
+| Field        | Description                                           |
+| ------------ | ----------------------------------------------------- |
+| `pipelineId` | Codefresh image-build pipeline used by `engine: ci`   |
+| `ecr`        | Registry identifier override used for the built image |
+
+`docker.app.afterBuildPipelineConfig` can configure a follow-up Codefresh
+pipeline:
+
+| Field                       | Description                                   |
+| --------------------------- | --------------------------------------------- |
+| `afterBuildPipelineId`      | Pipeline to run after an image build succeeds |
+| `description`               | Human-readable pipeline description           |
+| `detatchAfterBuildPipeline` | Legacy misspelled compatibility field         |
+
+<Callout type="warning">
+  `detatchAfterBuildPipeline` is the accepted spelling. Use it only with an
+  existing configuration that needs this behavior. Do not add it to a new
+  configuration.
+</Callout>
+
+### docker.init (optional)
 
-Configuration for an init container that runs before the main application. Uses the same fields as `docker.app`.
+Configuration for an init container that runs before the primary application
+container. The init container has the fields from `docker.app`.
 
-## Deployment Options
+## Deployment options
 
-The `deployment` section configures how the service is deployed to Kubernetes. All fields are optional.
+The `deployment` section configures how Lifecycle deploys the Service to
+Kubernetes. All fields are optional.
 
 ### public
 
-Controls whether the service is exposed via ingress for external access.
+The `public` field controls ingress exposure.
 
-- `true` - Creates an ingress, service gets a public URL
-- `false` - Internal only, accessible only within the cluster
+- `true` - Lifecycle creates an ingress and a public URL.
+- `false` - Users can access the Service only in the cluster.
 
 ### capacityType
 
 Specifies the node capacity type for scheduling:
 
-- `spot` - Use spot/preemptible instances (cost-effective)
-- `on-demand` - Use on-demand instances (more reliable)
+- `SPOT` - Prefer spot instances. This is the default.
+- `ON_DEMAND` - Use only on-demand instances.
+
+`SPOT` adds a preferred spot-node affinity. Kubernetes can select on-demand
+capacity when spot capacity is unavailable. `ON_DEMAND` adds a mandatory
+on-demand affinity.
+
+<Callout type="warning">
+  Use `SPOT` or `ON_DEMAND`. Other spellings can prevent workload scheduling.
+</Callout>
 
 ### resource
 
 CPU and memory requests and limits for the container:
 
-| Field            | Description                               |
-| ---------------- | ----------------------------------------- |
-| `cpu.request`    | Minimum CPU guaranteed (e.g., `100m`)     |
-| `cpu.limit`      | Maximum CPU allowed (e.g., `1000m`)       |
-| `memory.request` | Minimum memory guaranteed (e.g., `256Mi`) |
-| `memory.limit`   | Maximum memory allowed (e.g., `1Gi`)      |
+| Field            | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| `cpu.request`    | Minimum CPU guaranteed, for example, `100m`     |
+| `cpu.limit`      | Maximum CPU allowed, for example, `1000m`       |
+| `memory.request` | Minimum memory guaranteed, for example, `256Mi` |
+| `memory.limit`   | Maximum memory allowed, for example, `1Gi`      |
 
 ### readiness
 
-Health check configuration to determine when the service is ready to receive traffic.
+A health check tells Lifecycle when the Service is ready to receive traffic.
 
 **HTTP health check:**
 
-| Field          | Description                          |
-| -------------- | ------------------------------------ |
-| `httpGet.path` | HTTP endpoint path (e.g., `/health`) |
-| `httpGet.port` | Port to check                        |
+| Field          | Description                                |
+| -------------- | ------------------------------------------ |
+| `httpGet.path` | HTTP endpoint path, for example, `/health` |
+| `httpGet.port` | Port to check                              |
 
 **TCP health check:**
 
-| Field           | Description                    |
-| --------------- | ------------------------------ |
-| `tcpSocketPort` | TCP port to check connectivity |
+| Field           | Description                           |
+| --------------- | ------------------------------------- |
+| `disabled`      | Disable the generated readiness probe |
+| `tcpSocketPort` | TCP port to check connectivity        |
 
-**Common fields:**
+**Shared fields:**
 
 | Field                 | Description                          |
 | --------------------- | ------------------------------------ |
@@ -284,7 +335,8 @@ Health check configuration to determine when the service is ready to receive tra
 
 ### hostnames
 
-Custom hostname configuration. If omitted, hostnames are auto-constructed from `global_config` values.
+Custom hostname configuration. If `hostnames` is missing, Lifecycle generates
+the hostnames.
 
 | Field                     | Description                     |
 | ------------------------- | ------------------------------- |
@@ -297,29 +349,36 @@ Custom hostname configuration. If omitted, hostnames are auto-constructed from `
 
 Advanced network configuration:
 
-| Field             | Description                                |
-| ----------------- | ------------------------------------------ |
-| `ipWhitelist`     | Array of allowed IP ranges (CIDR notation) |
-| `pathPortMapping` | Map URL paths to container ports           |
-| `hostPortMapping` | Map hostnames to container ports           |
-| `grpc.enable`     | Enable gRPC support                        |
-| `grpc.host`       | gRPC hostname                              |
+| Field              | Description                                |
+| ------------------ | ------------------------------------------ |
+| `ipWhitelist`      | Array of allowed IP ranges (CIDR notation) |
+| `pathPortMapping`  | Map URL paths to container ports           |
+| `hostPortMapping`  | Map hostnames to container ports           |
+| `grpc.enable`      | Enable gRPC support                        |
+| `grpc.host`        | gRPC hostname                              |
+| `grpc.defaultHost` | Default gRPC hostname fallback             |
 
 ### serviceDisks
 
 Persistent volume mounts for stateful data:
 
-| Field         | Required | Description                        |
-| ------------- | -------- | ---------------------------------- |
-| `name`        | Yes      | Volume name                        |
-| `mountPath`   | Yes      | Path inside the container          |
-| `storageSize` | Yes      | Storage size (e.g., `10Gi`)        |
-| `accessModes` | No       | `ReadWriteOnce` or `ReadWriteMany` |
-| `medium`      | No       | Storage medium                     |
+| Field         | Required | Description                                                             |
+| ------------- | -------- | ----------------------------------------------------------------------- |
+| `name`        | Yes      | Volume name                                                             |
+| `mountPath`   | Yes      | Container path                                                          |
+| `storageSize` | Yes      | Storage size, for example, `10Gi`                                       |
+| `accessModes` | No       | `ReadWriteOnce`, `ReadOnlyMany`, `ReadWriteMany`, or `ReadWriteOncePod` |
+| `medium`      | No       | Storage medium                                                          |
+
+### Node placement
+
+Use `deployment.node_selector` for simple Kubernetes node-label matches and
+`deployment.node_affinity` for a full Kubernetes `nodeAffinity` object.
+Custom node affinity replaces Lifecycle's capacity-type affinity.
 
-## Fields Reference
+## Field reference
 
-### Required Fields
+### Required fields
 
 | Field        | Type   | Description                              |
 | ------------ | ------ | ---------------------------------------- |
@@ -327,16 +386,17 @@ Persistent volume mounts for stateful data:
 | `branchName` | string | Branch to build from                     |
 | `docker`     | object | Docker build configuration (see above)   |
 
-### Optional Fields
+### Optional fields
 
-| Field        | Type    | Description                                                                              |
-| ------------ | ------- | ---------------------------------------------------------------------------------------- |
-| `deployment` | object  | Deployment configuration (see above)                                                     |
-| `envLens`    | boolean | Enable environment lens ingress banner. Overrides the global `features.envLens` default. |
+| Field        | Type    | Description                                |
+| ------------ | ------- | ------------------------------------------ |
+| `deployment` | object  | Deployment configuration (see above)       |
+| `envLens`    | boolean | Enable the Environment Lens ingress banner |
 
-## Template Variables
+## Template variables
 
-Reference other services in your configuration using template variables. See the [Template Variables](/docs/features/template-variables) guide for the complete list.
+Use template variables to reference other Services in your configuration. See
+[Template variables](/docs/features/template-variables) for the full list.
 
 ```yaml
 env:
diff --git a/src/pages/docs/schema/helm.mdx b/src/pages/docs/schema/helm.mdx
index 46a2e11b..f0b99262 100644
--- a/src/pages/docs/schema/helm.mdx
+++ b/src/pages/docs/schema/helm.mdx
@@ -1,6 +1,11 @@
 ---
 title: Helm Service
-description: Deploy services using Helm charts - local, OCI, or public repositories
+description: Deploy Services with local, OCI, or public Helm charts.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - helm
@@ -11,17 +16,21 @@ tags:
 import { Callout } from "nextra/components";
 import { Tabs } from "nextra/components";
 
-The `helm` service type deploys applications using Helm charts. It supports local charts, OCI registries, and public Helm repositories. You can optionally include a Docker build step for custom images.
+The `helm` Service type deploys applications with Helm charts. It supports
+local charts, OCI registries, and public Helm repositories. You can include an
+optional Docker build step for custom images.
 
 <Callout type="info">
-  For advanced Helm deployment features like native Helm and environment
-  variable mapping, see the [Native Helm
-  Deployment](/docs/features/native-helm-deployment) guide.
+  Native Helm includes environment variable mapping and advanced deployment
+  features.
 </Callout>
 
+See [Native Helm deployment](/docs/features/native-helm-deployment) for more
+information.
+
 ## Examples
 
-<Tabs items={["Local Chart", "OCI Registry", "Public Bitnami", "Complete"]}>
+<Tabs items={["Local chart", "OCI registry", "Public Bitnami", "All fields"]}>
 
 <Tabs.Tab>
 Local chart with Docker build:
@@ -64,7 +73,7 @@ services:
       docker:
         defaultTag: "main"
         builder:
-          engine: "buildkit" # Options: buildkit (default), codefresh, kaniko
+          engine: "buildkit" # Options: buildkit, kaniko, ci
         app:
           dockerfilePath: "Dockerfile"
           command: "node" # Optional - override entrypoint
@@ -76,8 +85,12 @@ services:
 ```
 
 <Callout type="info">
-  For Helm template variables that should be resolved at deployment time, use triple braces `{{{variable}}}` to prevent Helm from processing them prematurely.
+  Triple braces keep a Lifecycle variable unchanged until deployment.
 </Callout>
+
+For a Lifecycle variable that resolves during deployment, write
+`{{{variable}}}`.
+
 </Tabs.Tab>
 
 <Tabs.Tab>
@@ -110,6 +123,7 @@ chart:
     - "auth.username=myuser"
     - "auth.database=mydb"
 
+---
 # Redis
 chart:
   name: "redis"
@@ -122,7 +136,7 @@ chart:
 </Tabs.Tab>
 
 <Tabs.Tab>
-Complete configuration with all options:
+Expanded configuration with all options:
 
 ```yaml filename="lifecycle.yaml"
 services:
@@ -155,7 +169,7 @@ services:
       docker:
         defaultTag: "main"
         builder:
-          engine: "buildkit" # Options: buildkit (default), codefresh, kaniko
+          engine: "buildkit" # Options: buildkit, kaniko, ci
           resources: # Optional - custom CPU/memory for the build job
             requests:
               cpu: "1"
@@ -185,16 +199,12 @@ services:
 
 </Tabs>
 
-## Chart Configuration
+## Chart configuration
 
-The `chart` section is required and defines which Helm chart to deploy.
+The `chart` section is required and defines which Helm chart to deploy. Set the
+chart fields in the Service configuration.
 
-<Callout type="info">
-  Commonly used charts can be configured in the `global_config` table to reuse
-  chart configuration across multiple services.
-</Callout>
-
-### chart.name (Required)
+### chart.name (required)
 
 The chart name can be one of:
 
@@ -206,11 +216,11 @@ The chart name can be one of:
 
 ### chart.repoUrl
 
-URL of the Helm repository (required for public charts).
+URL of the Helm repository. This field is necessary for public charts.
 
 ### chart.version
 
-Specific chart version to deploy.
+Specified chart version to deploy.
 
 ### chart.values
 
@@ -220,9 +230,11 @@ Array of Helm values in `key=value` format.
 
 Array of value file paths relative to the repository root.
 
-## Docker Configuration
+## Docker configuration
 
-The optional `docker` section defines how to build a custom image. This uses the same configuration as the [GitHub service docker section](/docs/schema/github#docker-configuration).
+The optional `docker` section defines how to build a custom image. Its
+configuration matches the [GitHub Service Docker
+section](/docs/schema/github#docker-configuration).
 
 ### docker.defaultTag
 
@@ -230,50 +242,57 @@ The default Docker image tag, typically matching the branch name.
 
 ### docker.builder
 
-Configuration for the Docker build process. See the [GitHub service docker.builder](/docs/schema/github#dockerbuilder) section for the full reference, including `resources` configuration for build job CPU/memory and details on the `safe-to-evict` pod annotation.
+Configuration for the Docker build operation. See [GitHub Service
+docker.builder](/docs/schema/github#dockerbuilder) for the full field list. That
+section includes the `resources` field and the `safe-to-evict` pod annotation.
 
-| Field                | Type                    | Description                                                                        |
-| -------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
-| `engine`             | string                  | Build engine: `buildkit` (default), `kaniko`, `codefresh`                          |
-| `resources.requests` | object                  | Minimum CPU/memory guaranteed for the build job                                    |
-| `resources.limits`   | object                  | Maximum CPU/memory allowed for the build job                                       |
-| `podAnnotations`     | `Record<string,string>` | Custom annotations applied to the build pod template (merged with global defaults) |
+| Field                | Type                    | Description                                          |
+| -------------------- | ----------------------- | ---------------------------------------------------- |
+| `engine`             | string                  | Build engine: `buildkit`, `kaniko`, or `ci`          |
+| `resources.requests` | object                  | Minimum CPU/memory guaranteed for the build job      |
+| `resources.limits`   | object                  | Maximum CPU/memory allowed for the build job         |
+| `podAnnotations`     | `Record<string,string>` | Custom annotations applied to the build pod template |
 
-### docker.app (Required when using docker)
+### docker.app (required with docker)
 
 Configuration for the main application container:
 
 - `dockerfilePath` - **Required.** Path to Dockerfile relative to repo root
 - `command` - Override container entrypoint
-- `arguments` - Arguments passed to the command. Use `%%SPLIT%%` as a delimiter for spaces (e.g., `-c%%SPLIT%%npm run start`)
+- `arguments` - Arguments passed to the command. Use `%%SPLIT%%` to delimit
+  spaces, for example, `-c%%SPLIT%%npm run start`.
 - `env` - Environment variables
 - `ports` - Exposed container ports
 
-### docker.init (Optional)
+### docker.init (optional)
 
-Configuration for an init container that runs before the main application. Uses the same fields as `docker.app`.
+Configuration for an init container that runs before the main application. The
+init container has the fields from `docker.app`.
 
-## Fields Reference
+## Field reference
 
-| Field              | Type    | Required   | Description                                                                              |
-| ------------------ | ------- | ---------- | ---------------------------------------------------------------------------------------- |
-| `chart.name`       | string  | **Yes**    | Chart name or path                                                                       |
-| `chart.repoUrl`    | string  | For public | Helm repository URL                                                                      |
-| `chart.version`    | string  | No         | Chart version                                                                            |
-| `chart.values`     | array   | No         | Inline Helm values                                                                       |
-| `chart.valueFiles` | array   | No         | Value file paths                                                                         |
-| `repository`       | string  | For builds | GitHub repository                                                                        |
-| `branchName`       | string  | For builds | Branch to build from                                                                     |
-| `docker`           | object  | No         | Docker build config                                                                      |
-| `args`             | string  | No         | Additional Helm arguments                                                                |
-| `version`          | string  | No         | Helm CLI version                                                                         |
-| `deploymentMethod` | string  | No         | `"native"` or `"ci"`                                                                     |
-| `envLens`          | boolean | No         | Enable environment lens ingress banner. Overrides the global `features.envLens` default. |
+| Field                        | Type    | Required   | Description                                                    |
+| ---------------------------- | ------- | ---------- | -------------------------------------------------------------- |
+| `chart.name`                 | string  | **Yes**    | Chart name or path                                             |
+| `chart.repoUrl`              | string  | For public | Helm repository URL                                            |
+| `chart.version`              | string  | No         | Chart version                                                  |
+| `chart.values`               | array   | No         | Inline Helm values                                             |
+| `chart.valueFiles`           | array   | No         | Value file paths                                               |
+| `repository`                 | string  | For builds | GitHub repository                                              |
+| `branchName`                 | string  | For builds | Branch to build from                                           |
+| `docker`                     | object  | No         | Docker build config                                            |
+| `args`                       | string  | No         | More Helm arguments                                            |
+| `version`                    | string  | No         | Helm CLI version                                               |
+| `deploymentMethod`           | string  | No         | `"native"` or `"ci"`                                           |
+| `envLens`                    | boolean | No         | Enable the Environment Lens ingress banner                     |
+| `grpc`                       | boolean | No         | Enable gRPC behavior for the Helm Service                      |
+| `disableIngressHost`         | boolean | No         | Disable Lifecycle's generated ingress host                     |
+| `overrideDefaultIpWhitelist` | boolean | No         | Let the Service configuration replace the default IP whitelist |
 
-## Native Helm Configuration
+## Native Helm configuration
 
-When `deploymentMethod: "native"` is enabled, you can further customize the
-native Helm job with the `nativeHelm` block.
+When `deploymentMethod: "native"` is enabled, configure more native Helm Job
+settings with the `nativeHelm` block.
 
 ```yaml filename="lifecycle.yaml"
 services:
@@ -290,23 +309,31 @@ services:
         name: "./charts/api"
 ```
 
-| Field                             | Type    | Required | Description                                                       |
-| --------------------------------- | ------- | -------- | ----------------------------------------------------------------- |
-| `nativeHelm.postRenderer.enabled` | boolean | No       | Enables or disables an inherited post-renderer                    |
-| `nativeHelm.postRenderer.command` | string  | No       | Executable passed to Helm with `--post-renderer`                  |
-| `nativeHelm.postRenderer.args`    | array   | No       | Arguments passed to Helm as repeated `--post-renderer-args` flags |
+| Field                             | Type    | Required | Description                                                     |
+| --------------------------------- | ------- | -------- | --------------------------------------------------------------- |
+| `nativeHelm.enabled`              | boolean | No       | When no `deploymentMethod` override exists, enable native Helm  |
+| `nativeHelm.defaultHelmVersion`   | string  | No       | Helm version used by the runner                                 |
+| `nativeHelm.jobTimeout`           | number  | No       | Native Helm Job timeout                                         |
+| `nativeHelm.serviceAccount`       | string  | No       | Kubernetes ServiceAccount for the Job                           |
+| `nativeHelm.defaultArgs`          | string  | No       | Default Helm arguments                                          |
+| `nativeHelm.image`                | string  | No       | Custom native Helm runner image                                 |
+| `nativeHelm.postRenderer.enabled` | boolean | No       | Enables or disables an inherited post-renderer                  |
+| `nativeHelm.postRenderer.command` | string  | No       | Executable passed to Helm with `--post-renderer`                |
+| `nativeHelm.postRenderer.args`    | array   | No       | Helm receives one `--post-renderer-args` flag for each argument |
 
-## Templated Variables
+## Templated variables
 
-Use templated variables in chart values to reference dynamic deployment values. See the [Template Variables](/docs/features/template-variables) guide for the complete list.
+Write Lifecycle template variables with triple braces. See the [Template
+variables](/docs/features/template-variables) for the full list.
 
 <Callout type="info">
-  Use triple braces `{{{variable}}}` for Lifecycle template variables. This prevents Helm from trying to process them as Helm template functions.
+  Triple braces `{{{variable}}}` distinguish a Lifecycle variable from a Helm
+  template function.
 </Callout>
 
-## Native Helm Deployment
+## Native Helm deployment
 
-For more control over Helm deployments, enable native Helm:
+To control Helm deployments, enable native Helm:
 
 ```yaml filename="lifecycle.yaml"
 services:
@@ -316,11 +343,8 @@ services:
       # ... rest of config
 ```
 
-Native Helm provides:
-
-- Direct Kubernetes job execution
-- Real-time deployment logs
-- Better handling of concurrent deployments
-- Full Helm argument control
+Native Helm runs the deployment as a Kubernetes Job. It streams deployment logs
+and accepts Helm arguments.
 
-See the [Native Helm Deployment](/docs/features/native-helm-deployment) guide for details.
+See [Native Helm deployment](/docs/features/native-helm-deployment) for more
+information.
diff --git a/src/pages/docs/schema/overview.mdx b/src/pages/docs/schema/overview.mdx
index 0b917b31..49d7b66f 100644
--- a/src/pages/docs/schema/overview.mdx
+++ b/src/pages/docs/schema/overview.mdx
@@ -1,6 +1,11 @@
 ---
-title: Schema Overview
-description: Introduction to the lifecycle.yaml configuration file and its structure
+title: Schema overview
+description: Understand the lifecycle.yaml configuration file and its structure.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - configuration
@@ -9,11 +14,20 @@ tags:
 
 import { Callout } from "nextra/components";
 
-The `lifecycle.yaml` file is the core configuration file that defines how Lifecycle manages your ephemeral environments. Place this file at the root of your repository.
+Lifecycle reads its configuration from the repository root. The supported
+filenames are:
 
-## File Structure
+- `lifecycle.yaml` (recommended)
+- `lifecycle.yml`
+- `.lifecycle.yaml`
+- `.lifecycle.yml`
 
-A `lifecycle.yaml` file has three main sections:
+Keep only one supported file in each repository. If the repository has multiple
+files, Lifecycle does not guarantee which file it selects.
+
+## File structure
+
+A `lifecycle.yaml` file has three primary sections:
 
 ```yaml filename="lifecycle.yaml"
 version: "1.0.0" # Schema version
@@ -22,34 +36,41 @@ environment: # Environment-level configuration
   autoDeploy: true
   defaultServices:
     - name: "my-service"
-  # optionalServices, webhooks, etc.
+  # Add optionalServices or webhooks if necessary.
 
 services: # Service definitions
   - name: "my-service"
     github: # Service type configuration
-      # ...
+      repository: "myorg/my-service"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "Dockerfile"
 ```
 
 | Section       | Description                                                  |
 | ------------- | ------------------------------------------------------------ |
-| `version`     | Schema version (currently `"1.0.0"`)                         |
+| `version`     | Schema version. Use `"1.0.0"`                                |
 | `environment` | Controls deployment behavior, service grouping, and webhooks |
 | `services`    | Array of service definitions with their configurations       |
 
-## Service Types
+## Service types
 
-Each service in the `services` array must have exactly one service type configured. Choose based on your deployment needs:
+Each entry in `services` must have one Service type only. Select the type for
+your deployment.
 
-| Service Type                                     | Use Case                                                          |
-| ------------------------------------------------ | ----------------------------------------------------------------- |
-| [**github**](/docs/schema/github)                | Build and deploy from a GitHub repository with Dockerfile         |
-| [**docker**](/docs/schema/docker)                | Deploy pre-built Docker images (databases, caches, etc.)          |
-| [**helm**](/docs/schema/helm)                    | Deploy using Helm charts (local or remote)                        |
-| [**codefresh**](/docs/schema/codefresh)          | Trigger external Codefresh pipelines for deployment               |
-| [**auroraRestore**](/docs/schema/aurora-restore) | Restore AWS Aurora database snapshots                             |
-| [**configuration**](/docs/schema/configuration)  | Deploy configuration-only services (feature flags, shared config) |
+| Service type                                     | Purpose                                                      |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| [**github**](/docs/schema/github)                | Source build and deployment from a GitHub repository         |
+| [**docker**](/docs/schema/docker)                | Deploy pre-built Docker images, such as databases and caches |
+| [**helm**](/docs/schema/helm)                    | Deploy using Helm charts (local or remote)                   |
+| [**codefresh**](/docs/schema/codefresh)          | Trigger external Codefresh pipelines for deployment          |
+| [**externalHttp**](/docs/schema/external-http)   | Use an existing internal and public HTTP endpoint            |
+| [**auroraRestore**](/docs/schema/aurora-restore) | Restore AWS Aurora database snapshots                        |
+| [**configuration**](/docs/schema/configuration)  | Provide shared values without a workload                     |
 
-## Choosing a Service Type
+## Select a Service type
 
 ```
 Do you need to build from source?
@@ -62,12 +83,52 @@ Do you need to build from source?
                   ├─ Yes → helm (without docker section)
                   └─ No  → Is it a CI/CD pipeline?
                            ├─ Yes → codefresh
-                           └─ No  → configuration or auroraRestore
+                           └─ No  → Is the dependency already hosted?
+                                    ├─ Yes → externalHttp
+                                    └─ No  → configuration or auroraRestore
 ```
 
-## Minimal Example
+## Shared Service fields
+
+These fields sit directly on each `services[]` entry with its Service type:
+
+| Field                 | Type     | Required | Description                                           |
+| --------------------- | -------- | -------- | ----------------------------------------------------- |
+| `name`                | string   | Yes      | Service name used by references and template keys     |
+| `appShort`            | string   | No       | Short application identifier                          |
+| `defaultUUID`         | string   | No       | Static Environment fallback for an unselected service |
+| `ignoreFiles`         | string[] | No       | Service-specific push-redeploy ignore patterns        |
+| `requires`            | object[] | No       | Services to include with this service                 |
+| `deploymentDependsOn` | string[] | No       | Selected services that must deploy first              |
+
+`requires` controls inclusion. `deploymentDependsOn` controls order. See
+[Service Dependencies](/docs/features/service-dependencies).
+
+## External HTTP Service
+
+Use `externalHttp` for an endpoint that Lifecycle does not build or deploy:
+
+```yaml filename="lifecycle.yaml"
+version: "1.0.0"
+
+environment:
+  defaultServices:
+    - name: "shared-api"
+
+services:
+  - name: "shared-api"
+    externalHttp:
+      defaultInternalHostname: "shared-api.platform.svc.cluster.local"
+      defaultPublicUrl: "shared-api.example.com"
+```
+
+The two endpoint fields are necessary. Lifecycle marks this Service ready
+without a source build. It makes the resolved URLs available to template
+variables.
+
+## Minimal example
 
-Here's the simplest valid `lifecycle.yaml` for a single service:
+Use this minimal `lifecycle.yaml` for one Service:
 
 ```yaml filename="lifecycle.yaml"
 version: "1.0.0"
@@ -89,9 +150,9 @@ services:
             - 3000
 ```
 
-## Complete Example
+## Expanded example
 
-A more complete example with multiple service types:
+An expanded example with multiple Service types:
 
 ```yaml filename="lifecycle.yaml"
 version: "1.0.0"
@@ -138,7 +199,7 @@ services:
         - 5432
       env:
         POSTGRES_USER: "app"
-        POSTGRES_PASSWORD: "secret"
+        POSTGRES_PASSWORD: "{{aws:preview/postgres:password}}"
         POSTGRES_DB: "myapp"
       deployment:
         public: false
@@ -152,16 +213,18 @@ services:
         - 6379
 ```
 
-## Template Variables
+## Template variables
 
-Throughout your configuration, you can use template variables like `{{api_publicUrl}}` or `{{database_internalHostname}}` to reference dynamic values from other services.
+Use template variables in your configuration. For example, `{{api_publicUrl}}`
+and `{{database_internalHostname}}` supply dynamic values from other Services.
 
-See the [Template Variables](/docs/features/template-variables) guide for the complete list of available variables and usage examples.
+See [Template variables](/docs/features/template-variables) for the full list
+and examples.
 
-## Next Steps
+## Related pages
 
 - [Environment Configuration](/docs/schema/environment) - Configure deployment behavior and service grouping
 - [Webhooks](/docs/schema/webhooks) - Automate actions on deployment events
-- [GitHub Service](/docs/schema/github) - Build and deploy from source
+- [GitHub Service](/docs/schema/github) - Source build and deployment
 - [Docker Service](/docs/schema/docker) - Deploy pre-built images
 - [Helm Service](/docs/schema/helm) - Deploy with Helm charts
diff --git a/src/pages/docs/schema/webhooks.mdx b/src/pages/docs/schema/webhooks.mdx
index 12420bba..f35487ee 100644
--- a/src/pages/docs/schema/webhooks.mdx
+++ b/src/pages/docs/schema/webhooks.mdx
@@ -1,6 +1,11 @@
 ---
-title: Webhooks Configuration
-description: Schema reference for configuring webhooks to automate actions on deployment events
+title: Webhook configuration
+description: Configure webhooks that start automated actions after Environment events.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - schema
   - webhooks
@@ -11,16 +16,18 @@ tags:
 
 import { Callout } from "nextra/components";
 
-Webhooks allow you to trigger automated actions when an environment reaches certain states. They are configured under `environment.webhooks` in your `lifecycle.yaml`.
+Webhooks start automated actions at specified Environment states. Configure
+them in `environment.webhooks` in `lifecycle.yaml`.
 
 <Callout type="info">
-  For detailed use cases, examples, and execution behavior, see the
-  [Webhooks](/docs/features/webhooks) guide.
+  The Webhooks feature page contains examples and execution behavior.
 </Callout>
 
-## Common Fields
+See [Webhooks](/docs/features/webhooks) for more information.
 
-All webhook types share these common fields:
+## Shared fields
+
+All webhook types share these fields:
 
 | Field         | Type   | Required | Description                                        |
 | ------------- | ------ | -------- | -------------------------------------------------- |
@@ -32,13 +39,13 @@ All webhook types share these common fields:
 
 ## Trigger States
 
-| State       | Description                                    |
-| ----------- | ---------------------------------------------- |
-| `deployed`  | All services successfully deployed and running |
-| `error`     | Build or deployment failed                     |
-| `torn_down` | Environment has been destroyed                 |
+| State       | Description                          |
+| ----------- | ------------------------------------ |
+| `deployed`  | Lifecycle reached the deployed state |
+| `error`     | Build or deployment failed           |
+| `torn_down` | Lifecycle destroyed the Environment  |
 
-## Webhook Types
+## Webhook types
 
 ### codefresh
 
@@ -47,7 +54,12 @@ Triggers an existing Codefresh pipeline.
 | Field        | Type   | Required | Description           |
 | ------------ | ------ | -------- | --------------------- |
 | `pipelineId` | string | Yes      | Codefresh pipeline ID |
-| `trigger`    | string | No       | Pipeline trigger name |
+| `trigger`    | string | Yes      | Pipeline trigger name |
+
+<Callout type="warning">
+  Set both `pipelineId` and `trigger`. If a value is missing, the webhook fails
+  when it runs.
+</Callout>
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -63,14 +75,14 @@ environment:
 
 ### docker
 
-Runs a Docker image as a Kubernetes job.
+Runs a Docker image in a Kubernetes Job.
 
-| Field            | Type   | Required | Description                                   |
-| ---------------- | ------ | -------- | --------------------------------------------- |
-| `docker.image`   | string | **Yes**  | Docker image to execute                       |
-| `docker.command` | array  | No       | Override entrypoint command                   |
-| `docker.args`    | array  | No       | Arguments to pass to the command              |
-| `docker.timeout` | number | No       | Max execution time in seconds (default: 1800) |
+| Field            | Type   | Required | Description                      |
+| ---------------- | ------ | -------- | -------------------------------- |
+| `docker.image`   | string | **Yes**  | Docker image to execute          |
+| `docker.command` | array  | No       | Override entrypoint command      |
+| `docker.args`    | array  | No       | Arguments to pass to the command |
+| `docker.timeout` | number | No       | Seconds, 1–86400 (default: 1800) |
 
 ```yaml filename="lifecycle.yaml"
 environment:
@@ -90,32 +102,41 @@ environment:
 
 Runs a shell script in a specified Docker image.
 
-| Field             | Type   | Required | Description                                   |
-| ----------------- | ------ | -------- | --------------------------------------------- |
-| `command.image`   | string | **Yes**  | Docker image to run the script in             |
-| `command.script`  | string | **Yes**  | Shell script to execute                       |
-| `command.timeout` | number | No       | Max execution time in seconds (default: 1800) |
+| Field             | Type   | Required | Description                       |
+| ----------------- | ------ | -------- | --------------------------------- |
+| `command.image`   | string | **Yes**  | Docker image to run the script in |
+| `command.script`  | string | **Yes**  | Shell script to execute           |
+| `command.timeout` | number | No       | Seconds, 1–86400 (default: 1800)  |
 
 ```yaml filename="lifecycle.yaml"
 environment:
   webhooks:
-    - name: "Slack Notification"
+    - name: "Record Deployment"
       state: deployed
       type: command
       command:
         image: "alpine:latest"
         script: |
           apk add --no-cache curl
-          curl -X POST "$SLACK_WEBHOOK" \
+          curl --fail --request POST "$EVENT_ENDPOINT" \
             -H "Content-Type: application/json" \
-            -d '{"text":"Deployed to $URL"}'
+            -d "{\"event\":\"deployed\",\"url\":\"$URL\"}"
       env:
-        SLACK_WEBHOOK: "https://hooks.slack.com/services/XXX"
+        EVENT_ENDPOINT: "https://events.example.org/lifecycle"
         URL: "https://{{api_publicUrl}}"
 ```
 
-## Template Variables
+## Template variables
 
-You can use template variables like `{{api_publicUrl}}` in the `env` section to reference dynamic values from your services.
+Use template variables in `env`. For example, `{{api_publicUrl}}` inserts a
+dynamic value from a Service.
 
-See the [Template Variables](/docs/features/template-variables) guide for the complete list of available variables.
+See [Template variables](/docs/features/template-variables) for the full list.
+
+<Callout type="warning">
+  Lifecycle does not resolve cloud secret references in webhook `env`. The Job
+  or pipeline receives literal text for values such as
+  <code>{"{{aws:path:key}}"}</code>. Do not commit credentials or secret-bearing
+  webhook URLs. Use a credential-delivery mechanism supported by the target Job
+  or pipeline.
+</Callout>
diff --git a/src/pages/docs/setup/_meta.ts b/src/pages/docs/setup/_meta.ts
index b8cfa19c..22074ca9 100644
--- a/src/pages/docs/setup/_meta.ts
+++ b/src/pages/docs/setup/_meta.ts
@@ -16,18 +16,18 @@
 
 export default {
   "prerequisites": {
-    "title": "Prerequisites"
+    "title": "Starter infrastructure prerequisites"
   },
   "setup-infra": {
-    "title": "Setup your cluster"
+    "title": "Set up an evaluation cluster"
   },
   "install-lifecycle": {
     "title": "Install Lifecycle"
   },
   "create-github-app": {
-    "title": "Configure Application"
+    "title": "Create the GitHub App"
   },
   "configure-lifecycle": {
-    "title": "Additional Configuration"
+    "title": "Optional configuration"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/setup/configure-lifecycle.mdx b/src/pages/docs/setup/configure-lifecycle.mdx
index a8de9ffa..72b000d6 100644
--- a/src/pages/docs/setup/configure-lifecycle.mdx
+++ b/src/pages/docs/setup/configure-lifecycle.mdx
@@ -1,5 +1,11 @@
 ---
-title: Additional Configuration
+title: Optional configuration
+description: Apply optional installation-wide settings safely after Lifecycle is running.
+audience:
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - configure
   - lifecycle
@@ -9,81 +15,86 @@ tags:
 
 import { Callout } from "nextra/components";
 
-We are in the final step of the setup process.
+After the GitHub App setup, use these optional settings to improve security and
+usability.
 
-**This step is Optional but highly recommended to ensure the default IP Whitelist is set for the environments created by the Lifecycle app.** This will help in securing the environments and restricting access to only the specified IPs or CIDR blocks.
+## Configure BuildKit
 
-## Set Default IP Whitelist
+The standard Helm installation supplies a BuildKit endpoint. Select the build
+engine for each Service in `lifecycle.yaml`. See the [GitHub Service builder
+schema](/docs/schema/github#dockerbuilder).
 
-- Connect to the `postgres` database using the `psql` command line tool or any other database client.
+Lifecycle build pods include
+`cluster-autoscaler.kubernetes.io/safe-to-evict: "false"`. Add other
+annotations for each Service with `github.docker.builder.podAnnotations`. The
+Service configuration cannot override the `safe-to-evict` value.
 
-  <Callout type="info">
-
-  Database password was auto generated during the infra setup and can be found
-  retrieved from the `app-postgres` secret in the `lifecycle-app`
-  namespace.
-
-  </Callout>
-
-- Retrieve the database password:
-
-```sh
-   kubectl get secret app-postgres --namespace lifecycle-app \
-      -o jsonpath='{.data}' | jq 'with_entries(.value |= @base64d)'
-```
+<Callout type="warning">
+  The installation-wide IP allowlist starts open to `0.0.0.0/0`. Before an
+  Environment is reachable, limit each public Service to approved networks.
+  Apply your organization's network, identity, and security controls.
+</Callout>
 
-- Run the following SQL commands to update the configuration:
-
-```sql
--- provide a default IP whitelist for the environments, default is open to all IPs
-UPDATE public.global_config
-SET
-    config = (
-        config::jsonb ||
-        '{
-            "defaultIPWhiteList": "{ 0.0.0.0/0 }"
-         }'::jsonb
-    )::json,
-    "updatedAt" = NOW()
-WHERE "key" = 'serviceDefaults';
+## Limit public Service access
+
+Use the supported service-level `deployment.network.ipWhitelist` field. Replace
+the documentation CIDR shown with the networks that must reach the Service:
+
+```yaml filename="lifecycle.yaml"
+version: "1.0.0"
+
+services:
+  - name: "api"
+    github:
+      repository: "myorg/api"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "Dockerfile"
+          ports:
+            - 8080
+      deployment:
+        public: true
+        network:
+          ipWhitelist:
+            - "203.0.113.0/24"
 ```
 
-<Callout type="error" emoji="⚠️">
-  Note that the infra setup with the OpenTofu modules below will **open your
-  cluster to the world.** <br />
-  🛡️ Make sure to **<a href="https://translate.google.com/details?sl=auto&tl=hy&text=shield&op=translate">shield</a>** your cluster by implementing appropriate network policies
-  and access controls after the initial setup.
-
-Replace the `defaultIPWhiteList` under `global_config.serviceDefaults` with your actual IP whitelist or CIDR block to restrict access to the deployed environments.
-
+<Callout type="warning">
+  This documentation uses `203.0.113.0/24` only as an example. It does not grant
+  your users access. Supply your office, VPN, or gateway CIDRs.
 </Callout>
 
----
-
-## Enable Environment Lens Globally
-
-The environment lens banner can be enabled globally for all services via the `features` row in `global_config`. Individual services can still override this by setting `envLens` explicitly in their `lifecycle.yaml`.
-
-```sql
--- Enable envLens globally for all services
-INSERT INTO public.global_config ("key", config, "createdAt", "updatedAt")
-VALUES ('features', '{"envLens": true}'::json, NOW(), NOW())
-ON CONFLICT ("key")
-DO UPDATE SET
-    config = (public.global_config.config::jsonb || '{"envLens": true}'::jsonb)::json,
-    "updatedAt" = NOW();
+Set `deployment.public: false` for a Service that must have no public
+ingress. See the [GitHub service network
+schema](/docs/schema/github#network) for hostname and port-mapping options.
+
+## Enable Environment Lens for a Service
+
+When you want an Environment banner on a Service ingress, set `envLens` on that
+Service:
+
+```yaml filename="lifecycle.yaml"
+services:
+  - name: "web"
+    github:
+      repository: "myorg/web"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        app:
+          dockerfilePath: "Dockerfile"
+          ports:
+            - 3000
+      envLens: true
 ```
 
-After running this, [refresh the config cache](#refresh-config-cache) to apply the change.
-
----
-
-## Refresh config cache
-
-```sh
-curl -X PUT https://app.<your_domain>/api/v1/config/cache
-```
+Commit the change. Then, create or redeploy an Environment and make sure that the
+banner appears.
 
-This will refresh the configuration cache and apply the changes you made to the database for the Lifecycle app.
+## Change other settings
 
-We are all set! 🎉 And ready to create our first PR based ephemeral environment.
+Use the [runtime configuration map](/docs/operations/configuration) to select a
+documented configuration surface. After each change, test one affected
+workflow.
diff --git a/src/pages/docs/setup/create-github-app.mdx b/src/pages/docs/setup/create-github-app.mdx
index 39f0a9da..686c63e6 100644
--- a/src/pages/docs/setup/create-github-app.mdx
+++ b/src/pages/docs/setup/create-github-app.mdx
@@ -1,5 +1,11 @@
 ---
-title: Configure Application
+title: Create the GitHub App
+description: Create and connect a private GitHub App for Lifecycle.
+audience:
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - github
   - app
@@ -7,137 +13,125 @@ tags:
   - setup
 ---
 
-import { Callout } from "nextra/components";
-import { Image } from "@lifecycle-docs/components";
-
-## Configure BuildKit Endpoint
-
-Before creating the GitHub app, you need to configure the BuildKit endpoint in the database:
+import { Callout, Steps } from "nextra/components";
+
+Lifecycle creates a private GitHub App from a generated manifest. Before
+approval, examine the manifest. Install the App only on intended repositories.
+Continue configuration in Lifecycle.
+
+## Before you start
+
+- Lifecycle's API, UI, identity, DNS, and TLS checks are healthy.
+- You can administer the GitHub account or organization that will own the App.
+- Your organization has approved the listed permissions and webhook events.
+- One or more repositories are ready to grant to the App.
+
+## What Lifecycle requests
+
+Lifecycle derives the webhook and setup URLs from its configured public
+application host:
+
+| Manifest field   | Generated destination                                           |
+| ---------------- | --------------------------------------------------------------- |
+| Webhook          | `https://app.lifecycle.example.org/api/webhooks/github`         |
+| Setup completion | `https://app.lifecycle.example.org/api/v1/setup/installed`      |
+| Setup redirect   | `https://app.lifecycle.example.org/api/v1/setup/callback`       |
+| Sign-in callback | The GitHub broker callback configured for the identity provider |
+
+`app.lifecycle.example.org` is a documentation-only hostname. The generated
+manifest uses your deployment's configured host and creates a **private**
+GitHub App.
+
+The generated manifest requests these repository and organization permissions:
+
+| Permission    | Level | Why Lifecycle requests it                                              |
+| ------------- | ----- | ---------------------------------------------------------------------- |
+| Contents      | Write | Read Lifecycle configuration and update approved repository files      |
+| Workflows     | Write | Update `.github/workflows/*` during an approved repository-file change |
+| Pull requests | Write | Read and update the pull-request workflow                              |
+| Issues        | Write | Create and update issue-style pull-request comments and labels         |
+| Deployments   | Write | Publish deployment-related state                                       |
+| Statuses      | Read  | Read repository commit-status context                                  |
+| Metadata      | Read  | Identify repositories and their metadata                               |
+| Members       | Read  | Resolve organization membership                                        |
+| Emails        | Read  | Resolve the GitHub user identity                                       |
+
+The App subscribes to:
+
+```text
+issues
+issue_comment
+label
+membership
+organization
+repository
+public
+pull_request
+push
+team
+```
 
 <Callout type="warning">
-  Set the `HELM_RELEASE` environment variable to your actual Helm release name
-  before running the commands below.
-</Callout>
-
-<Callout type="info">
-  The following commands will create the `buildkit` object and `endpoint`
-  configuration if they don't exist, or update them if they do.
+  **Workflows: write** and the other write permissions are consequential. The
+  generated App requests them for installations that do not use all related
+  features. If your organization cannot approve that boundary, stop. Examine it
+  with the Lifecycle deployment owner. Removing a permission can make enabled
+  workflows not fully functional.
 </Callout>
 
-### Option 1: Using kubectl exec with psql
-
-Execute the following commands to connect to the PostgreSQL pod and run the query:
-
-```bash
-# Set your Helm release name (replace with your actual release name)
-export HELM_RELEASE=<YOUR-HELM-RELEASE>
-
-# Get the database password from the secret
-export PGPASSWORD=$(kubectl get secret ${HELM_RELEASE}-postgres -n lifecycle-app -o jsonpath='{.data.POSTGRES_USER_PASSWORD}' | base64 -d)
-
-# Run the query
-kubectl exec -it ${HELM_RELEASE}-postgres-0 -n lifecycle-app -- env PGPASSWORD=$PGPASSWORD psql -U lifecycle -d lifecycle -c "
-UPDATE global_config
-SET config = jsonb_set(
-    jsonb_set(
-        COALESCE(config::jsonb, '{}'::jsonb),
-        '{buildkit}',
-        COALESCE(config::jsonb->'buildkit', '{}'::jsonb),
-        true
-    ),
-    '{buildkit,endpoint}',
-    '\"tcp://${HELM_RELEASE}-buildkit.lifecycle-app.svc.cluster.local:1234\"'::jsonb,
-    true
-),
-\"updatedAt\" = NOW()
-WHERE key = 'buildDefaults';"
-```
-
-### Option 2: Direct SQL query
-
-If you have direct database access, run the following SQL query (replace `<YOUR-HELM-RELEASE>` with your actual Helm release name):
-
-```sql
-UPDATE global_config
-SET config = jsonb_set(
-    jsonb_set(
-        COALESCE(config::jsonb, '{}'::jsonb),
-        '{buildkit}',
-        COALESCE(config::jsonb->'buildkit', '{}'::jsonb),
-        true
-    ),
-    '{buildkit,endpoint}',
-    '"tcp://<YOUR-HELM-RELEASE>-buildkit.lifecycle-app.svc.cluster.local:1234"'::jsonb,
-    true
-),
-"updatedAt" = NOW()
-WHERE key = 'buildDefaults';
-```
-
-### Configure Build Pod Annotations
-
-Build pods automatically include the `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"` annotation to prevent eviction during cluster scale-down.
-
-You can add custom annotations in two ways:
-
-- **Per-service:** Set `podAnnotations` in the `docker.builder` section of your `lifecycle.yaml`. See the [GitHub service schema](/docs/schema/github#dockerbuilder) for details.
-- **Globally:** Set `podAnnotations` in the `buildDefaults` row of the `global_config` table. These apply to all build jobs and can be overridden per-service.
+## App creation and installation
 
-The hardcoded `safe-to-evict` annotation always takes final precedence and cannot be overridden.
+<Steps>
 
-### Refresh Configuration Cache
+### Open Lifecycle setup
 
-After running either option above, refresh the configuration cache:
+Open `https://app.lifecycle.example.org/setup`, replacing the documentation
+hostname with your Lifecycle API host.
 
-```bash
-curl -X 'PUT' \
-  'https://app.<your_domain>/api/v1/config/cache' \
-  -H 'accept: application/json'
-```
+Select **Personal** or **Organization** for the account that owns the App.
 
-Replace `<your_domain>` with your actual domain (e.g., `0env.com`).
+### Name the App
 
-## Create GitHub App
+Enter a unique GitHub App name. GitHub App names can contain letters, numbers,
+and hyphens. Lifecycle accepts at most 34 characters. For an organization-owned
+App, enter the organization login.
 
-To create a Github app that will send events to the Lifecycle with necessary permissions, follow these steps:
+Select **Create App**. Lifecycle sends the generated manifest to GitHub.
 
-<Callout type="info">
-  Make sure you have admin access to the Github organization or account where
-  you want to create the app.
-</Callout>
+### Examine the GitHub manifest
 
-- Navigate to your installed Lifecycle app at `https://app.<your_domain>/setup` (replace `<your_domain>` with your actual domain. e.g. `https://app.0env.com/setup`).
-  <Image src="/setup/github-app-setup.png" width={1872} height={1068} />
-- Select `Personal` or `Organization` based on your needs.
-- Fill in the required fields:
+Make sure that the owner, callback URLs, permissions, and events agree with the
+approved values. Create the App.
 
-  - **Github App Name**: A name for your app. (should be unique, use a prefix with your name or organization. Refer Github app naming convention [here](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/)
-  - **Organization Name**: Github organization name where the app will be created. Required if you selected `Organization`.
+### Select repository access
 
-- Click `Create App`
-- On the Github app creation page, confirm the app name and click `Create`
-- Once the app is created, you will be redirected to the app installation page where you can choose one or more repositories to install the the newly minted app.
+Install the App on the repositories that Lifecycle can use.
+Selecting only approved repositories is narrower than granting all current
+and future repositories in the account.
 
-  <Callout type="info">
-    Make sure to select the repositories you want the app to have access to. You
-    can always change this later in the app settings but **adding atleast one
-    repository is required to proceed with the setup**.
-  </Callout>
+Before setup can continue, select one or more repositories.
 
-  <br />
+### Continue in Lifecycle
 
-- Voila! 🎉 Your Github app is now created and installed.
+After GitHub returns to Lifecycle, make sure that the installed state is
+correct. Select **Configure and Restart**. Before you continue, wait for healthy
+Lifecycle workloads and UI.
 
-<Image src="/setup/github-app-installed.png" width={1902} height={1088} />
+</Steps>
 
-- Click `Configure and Restart` to apply the changes and start using the app.
+## Test the connection
 
-<Callout type="info">
-  The step above, sets up the global config values that Lifecycle app will use
-  creating ephemeral environments and processing pull requests. And restarts the
-  `deployment` for the github app secrets to take effect.
-</Callout>
+1. In GitHub, make sure that the App installation lists the intended
+   repositories.
+2. In Lifecycle, open `/onboard`.
+3. Make sure that an installed repository is available.
+4. [Onboard the repository](/docs/getting-started/onboard-repository).
+5. Open a pull request with a valid `lifecycle.yaml`.
+6. Make sure that Lifecycle receives the webhook.
+7. Make sure that Lifecycle creates the Mission Control comment.
 
----
+Installing the GitHub App and onboarding a repository are different actions. If
+GitHub shows the installed App but Lifecycle does not show a repository, examine
+the App's repository access before changing Lifecycle configuration.
 
-Let's move on the final step where we will configure the Lifecycle app config for processing pull requests and creating ephemeral environments.
+Continue with [repository onboarding](/docs/getting-started/onboard-repository).
diff --git a/src/pages/docs/setup/install-lifecycle.mdx b/src/pages/docs/setup/install-lifecycle.mdx
index 45785a01..8bcf7441 100644
--- a/src/pages/docs/setup/install-lifecycle.mdx
+++ b/src/pages/docs/setup/install-lifecycle.mdx
@@ -1,49 +1,169 @@
 ---
 title: Install Lifecycle
+description: Select the OpenTofu-managed or standalone Helm installation path. Make sure that the API, UI, identity, and cluster are healthy.
+audience:
+  - evaluator
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - lifecycle
   - install
-  - getting-started
+  - helm
   - setup
 ---
 
 import { Callout } from "nextra/components";
-import { Image } from "@lifecycle-docs/components";
 
-Now that the infrastructure components are setup, let's install the lifecycle app and create a new Github app that will send events to the application to process and create ephemeral dev environments.
+Select one installation owner for the Lifecycle Helm release. Do not let
+OpenTofu and a manual Helm command manage the same release.
 
-<Callout type="info">
-  Make sure you have updated the kube config to be able to `helm install` in the
-  cluster you just created!
+<Callout type="error">
+  The starter OpenTofu module and stock installation are evaluation paths, not a
+  production-hardening profile. The stock installation is not a complete
+  authentication-on profile for shared-network exposure. Before exposure, use a
+  complete authentication-on procedure for the installed release. If the release
+  does not supply this procedure, keep the deployment isolated. Also examine the
+  [security boundaries](/docs/operations/security).
 </Callout>
 
-- Follow installation steps in [lifecycle helm chart](https://github.com/GoodRxOSS/helm-charts/blob/main/charts/lifecycle/README.md)
+## Path A: OpenTofu-managed installation
 
-- Wait for the installation to complete and verify that the pods are running:
+The [starter infrastructure flow](/docs/setup/setup-infra) enables
+`app_lifecycle_enabled` by default. In that mode, `tofu apply` installs a Helm
+release named `lifecycle`. Do not install the chart a second time.
+
+Set the namespace that you selected in `secrets.auto.tfvars`. Examine the
+managed release:
 
 ```sh
-kubectl get pods -n lifecycle-app
+export LIFECYCLE_NAMESPACE="<namespace>"
+
+helm status lifecycle --namespace "$LIFECYCLE_NAMESPACE"
+kubectl get pods --namespace "$LIFECYCLE_NAMESPACE"
+kubectl get ingress --namespace "$LIFECYCLE_NAMESPACE"
 ```
 
-- Once the pods are running, you can access the application at your configured domain (e.g. `https://app.0env.com`)
+OpenTofu pins its own chart and application versions. Before a module upgrade,
+examine the plan and pinned versions. Test a standalone chart version before
+you replace a module pin.
 
-<Image src="/setup/app-installed.png" width={1890} height={1089} />
+## Path B: operator-managed Helm installation
 
-Just like that, you have successfully installed Lifecycle and set up the necessary infrastructure to start creating ephemeral environments for your GitHub pull requests!
+If you operate a compatible Kubernetes cluster, use this path. You can also use
+it after you set `app_lifecycle_enabled = false` in the starter module.
 
-If you notice any secure certificate issues when accessing the application, you can check the status of your certificate using the following command:
+Use chart `0.9.10` with this procedure. Pin the version. Do not install an
+untested latest release.
 
 ```sh
-kubectl get certificate -n lifecycle-app
+export LIFECYCLE_CHART_VERSION="0.9.10"
+export LIFECYCLE_RELEASE="lifecycle"
+export LIFECYCLE_NAMESPACE="<namespace>"
+
+helm show values \
+  oci://ghcr.io/goodrxoss/helm-charts/lifecycle \
+  --version "$LIFECYCLE_CHART_VERSION" > lifecycle-values.yaml
+```
+
+Examine the generated file. Replace all `example.com` values. The core API, UI,
+identity provider, registry, and BuildKit registry must use one domain:
+
+```yaml
+global:
+  domain: lifecycle.example.org
+
+distribution:
+  ingress:
+    hostname: distribution.lifecycle.example.org
+
+buildkit:
+  buildkitdToml: |
+    debug = true
+    [registry."distribution.lifecycle.example.org"]
+      http = true
+      insecure = true
+    [worker.oci]
+      platforms = [ "linux/amd64" ]
+      reservedSpace = "60%"
+      maxUsedSpace = "80%"
+      max-parallelism = 25
+
+keycloak:
+  hostname: https://auth.lifecycle.example.org
+  clients:
+    lifecycleUi:
+      url: https://ui.lifecycle.example.org
+
+ui:
+  config:
+    apiUrl: https://app.lifecycle.example.org
+    authBaseUrl: https://auth.lifecycle.example.org
+    authRealm: lifecycle
 ```
 
-<Image
-  src="/setup/cert-ready.png"
-  width={2572}
-  height={844}
-  ratio={2572 / 844}
-/>
+`lifecycle.example.org` is a documentation-only domain. Use a domain that you
+control. Configure its DNS, ingress class, certificate issuer, storage classes,
+resource limits, secrets, backup policy, and identity integration. Do not put
+credentials in a committed values file or command line.
+
+Before installation, render the Kubernetes objects. Examine the output:
+
+```sh
+helm template "$LIFECYCLE_RELEASE" \
+  oci://ghcr.io/goodrxoss/helm-charts/lifecycle \
+  --version "$LIFECYCLE_CHART_VERSION" \
+  --namespace "$LIFECYCLE_NAMESPACE" \
+  --values lifecycle-values.yaml > rendered-lifecycle.yaml
+```
+
+After you examine the output, install the same pinned version:
+
+```sh
+helm upgrade --install "$LIFECYCLE_RELEASE" \
+  oci://ghcr.io/goodrxoss/helm-charts/lifecycle \
+  --version "$LIFECYCLE_CHART_VERSION" \
+  --namespace "$LIFECYCLE_NAMESPACE" \
+  --create-namespace \
+  --values lifecycle-values.yaml \
+  --wait \
+  --timeout 15m
+```
+
+## Test the installation
+
+An installed Helm release is not, by itself, proof that Lifecycle is ready.
+Make sure that each boundary is correct:
+
+1. `helm status` reports the expected release and chart version.
+2. All necessary pods are ready, and no workload is in a restart loop.
+3. The core API hostname answers its health endpoint with trusted TLS.
+4. The UI hostname loads with trusted TLS.
+5. After sign-in, make sure that the identity provider returns the user to
+   Lifecycle.
+6. Lifecycle rejects an unauthenticated v2 API request. The request does not
+   receive an administrator identity.
+
+```sh
+helm status "$LIFECYCLE_RELEASE" --namespace "$LIFECYCLE_NAMESPACE"
+kubectl get pods --namespace "$LIFECYCLE_NAMESPACE"
+kubectl get ingress --namespace "$LIFECYCLE_NAMESPACE"
+curl --fail --silent --show-error https://app.lifecycle.example.org/api/health
+```
+
+See [Authentication](/docs/features/authentication) for the full sign-in and
+security checks. If a workload is unhealthy, start with [platform
+monitoring](/docs/operations/monitoring) rather than continuing setup.
+
+## Continue setup
+
+When the API, UI, and sign-in flow are healthy:
 
-Make sure the certificate is in the `Ready` state. If it is not, you may need to wait a bit longer for the certificate to be issued or troubleshoot any issues with your DNS settings.
+1. [Create the GitHub App](/docs/setup/create-github-app).
+2. [Onboard a repository](/docs/getting-started/onboard-repository).
+3. [Create the first Environment](/docs/getting-started/create-environment).
 
-Let's move on to the next step where we will create a GitHub app to connect Lifecycle with your repositories.
+The repository-installation step grants GitHub App access. Onboarding is a
+different Lifecycle step. Lifecycle cannot use the repository before
+onboarding.
diff --git a/src/pages/docs/setup/prerequisites.mdx b/src/pages/docs/setup/prerequisites.mdx
index 5a275021..f654be6f 100644
--- a/src/pages/docs/setup/prerequisites.mdx
+++ b/src/pages/docs/setup/prerequisites.mdx
@@ -1,5 +1,12 @@
 ---
-title: Prerequisites
+title: Starter infrastructure prerequisites
+description: Prepare cloud, DNS, domain, and command-line access for the starter OpenTofu evaluation path.
+audience:
+  - evaluator
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - requirements
   - prerequisites
@@ -10,48 +17,73 @@ import { Callout } from "nextra/components";
 import { Tabs } from "nextra/components";
 import { Info } from "lucide-react";
 
-Before we start with the setup, let's make sure the following prerequisites are in place:
+Before you collect prerequisites, select the installation path:
 
-- **GitHub Account**: You'll need either a personal or an organization GitHub account. [Sign up for GitHub](https://github.com/join)
+- **Starter OpenTofu evaluation:** Use this page. Then, [set up the starter
+  infrastructure](/docs/setup/setup-infra). OpenTofu creates GKE or EKS,
+  dependencies, DNS, and a Lifecycle Helm release.
+- **Existing-cluster Helm evaluation:** Skip the OpenTofu- and
+  cloud-account-specific requirements on this page. Start with [Install
+  Lifecycle](/docs/setup/install-lifecycle) and validate the compatible
+  cluster, ingress, DNS, TLS, storage, identity, and secret requirements for
+  your release.
 
-- **Cloud Provider Account**: A Google Kubernetes Engine (GKE) or Amazon Web Services (AWS) Account. You'll need an active account with either platform to proceed.
-  - [Sign up for Google Cloud](https://cloud.google.com) and create a project
-  - [Sign up for AWS](https://aws.amazon.com/)
+<Callout type="warning">
+  Use both paths for evaluation only. Before shared-network exposure, examine
+  the [security boundaries](/docs/operations/security).
+</Callout>
+
+This page applies to the **starter OpenTofu evaluation path**.
+Prepare these accounts, tools, and DNS capabilities:
+
+- **GitHub account**: Use a personal or organization GitHub account. [Create a
+  GitHub account](https://github.com/join).
+
+- **Cloud provider account**: Use an active Google Cloud or AWS account.
+  - [Create a Google Cloud account](https://cloud.google.com) and a project.
+  - [Create an AWS account](https://aws.amazon.com/).
 
 <Callout icon={Info}>
-  We recommend using an isolated project or account in your cloud provider
-  specifically for this setup to begin with. This helps to keep your resources
-  organized and manageable as you experiment with Lifecycle.
+  An isolated cloud project or account keeps the evaluation resources away from
+  other workloads.
 </Callout>
 
 - **CLI Tools**
 
-  - **[OpenTofu](https://opentofu.org/docs/intro/install/)** — Infrastructure as code tool (OpenTofu is a community-driven fork of Terraform).
-  - **[kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)** — Command-line tool for interacting with Kubernetes clusters.
-  - **[gcloud](https://formulae.brew.sh/cask/google-cloud-sdk)** or **[aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)** — Command-line tools for managing Google Cloud or AWS resources, respectively.
+  - **[OpenTofu](https://opentofu.org/docs/intro/install/)** — Infrastructure
+    management tool.
+  - **[kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)** —
+    Kubernetes command-line tool.
+  - **[gcloud](https://formulae.brew.sh/cask/gcloud-cli)** or
+    **[aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)**
+    — Command-line tool for the selected cloud provider.
 
-- **Custom Domain**: You will need a custom domain (e.g., `0env.com`) to route traffic to your application environments. This is particularly important for setting up:
+- **Custom domain**: Use a custom domain, for example,
+  `lifecycle.example.org`, to route Environment traffic. The domain supports:
 
   - Public callback and webhook URLs for the GitHub App
-  - Ingress routing within the Kubernetes cluster
-  - Secure (HTTPS) access via TLS certificates
+  - Ingress routing in the Kubernetes cluster
+  - HTTPS access with TLS certificates
 
-- **DNS Provider with Wildcard Support**: The domain must be managed by a DNS provider that supports wildcard DNS records (e.g., \*.0env.com). This is necessary to dynamically route traffic from GitHub to the Lifecycle app and to ephemeral environments.
+- **DNS provider with wildcard support**: Use a provider that supports wildcard
+  records, for example, `*.lifecycle.example.org`. Wildcards route traffic to
+  Lifecycle and ephemeral Environments.
 
-  Supported DNS providers that support wildcard for infrastructure setup include:
+  The infrastructure setup supports these wildcard DNS providers:
 
 <Tabs items={["Google Cloud DNS", "AWS Route 53", "Cloudflare"]}>
 
   <Tabs.Tab>
-  **Manual Setup**:
-        Setup a [public DNS zone in Google Cloud](https://cloud.google.com/dns) to manage your domain's DNS records.
+  **Manual setup**
 
-      - Follow steps [here](https://cloud.google.com/dns/docs/zones#create-pub-zone) to setup a
-      public DNS zone.
+1. Open [Google Cloud DNS](https://cloud.google.com/dns).
+2. Follow the [Google Cloud instructions](https://cloud.google.com/dns/docs/zones#create-pub-zone).
+3. Create a public DNS zone for your domain.
 
-      - Wildcard DNS records will be created by the OpenTofu modules in the next steps.
+The OpenTofu modules create the wildcard DNS records during the subsequent
+steps.
 
-**CLI Setup**:
+**CLI setup**
 Use the `gcloud` CLI to create a public DNS zone for your domain:
 
 ```sh
@@ -61,55 +93,48 @@ gcloud services enable dns.googleapis.com --project=<PROJECT_ID>
 gcloud dns --project=<PROJECT_ID> managed-zones create <DNS_ZONE_NAME> --description="Lifecycle OSS starter DNS public zone" --dns-name="<YOUR_DOMAIN>." --visibility="public" --dnssec-state="off"
 ```
 
-_Update your domain's DNS records with NS records provided by Google Cloud DNS. You can find these in the Google Cloud Console under the DNS zone you created._
+Add the Google Cloud DNS name server records to your domain. Find the records in
+the Google Cloud Console in the new DNS zone.
 
   </Tabs.Tab>
 
 <Tabs.Tab>
   **[AWS Route 53](https://aws.amazon.com/route53/)**: Amazon's scalable DNS web
-  service designed to route end users to Internet applications.
+  service for routing users to Internet applications.
 
-**Manual Setup**:
+**Manual setup**
 
-- Authenticate with AWS CLI using the role/usr you desire.
-- Ensure you have [your domain provisioned to accept wildcards](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html); eg `*.lifecycle.<your-domain>.com`
+- Authenticate with the AWS CLI using the intended role or user.
+- Make sure that your [domain accepts wildcards](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingNewSubdomain.html).
+  For example, use `*.lifecycle.<your-domain>.com`.
 
-**CLI Setup**:
+**CLI check**
 
 ```sh
-aws configure
+aws route53 list-hosted-zones-by-name \
+  --dns-name "<your-domain>." \
+  --max-items 1
 ```
 
-```sh
-aws route53 change-resource-record-sets --hosted-zone-id <hosted-zone> --change-batch '{
-  "Comment": "CREATE wildcard for <your-domain>",
-  "Changes": [
-    {
-      "Action": "CREATE",
-      "ResourceRecordSet": {
-        "Name": "<subdomain>.<your-domain>.com",
-        "Type": "A",
-        "TTL": 300,
-        "ResourceRecords": [
-          {
-            "Value": "*********"
-          }
-        ]
-      }
-    }
-  ]
-}'
-```
+Make sure that the returned public hosted zone agrees with the Lifecycle
+domain. Make sure that the registrar delegates to its name servers. Before cluster
+ingress provisioning, do not create a placeholder wildcard A record. The
+starter OpenTofu flow manages the necessary records.
 
 </Tabs.Tab>
 
 <Tabs.Tab>
-  If you want to use Cloudflare as your primary DNS provider and manage your DNS
-  records on Cloudflare, your domain should be using a full setup. This means
-  that you are using Cloudflare for your authoritative DNS nameservers. Follow
-  the steps
-  [here](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/) to
-  setup a public DNS zone in Cloudflare.
+  If Cloudflare is your primary DNS provider, use a full setup. Configure
+  Cloudflare to be the authoritative DNS provider. Follow the
+  [Cloudflare setup instructions](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/).
+
+Create a Cloudflare API token that can manage DNS records for that zone. The
+OpenTofu setup reads it from `cloudflare_api_token` in
+`secrets.auto.tfvars`. Do not commit that file. Do not print the token in command
+output. See the [Lifecycle infrastructure
+repository](https://github.com/GoodRxOSS/lifecycle-opentofu/) for the token-scope
+requirements.
+
 </Tabs.Tab>
 
 </Tabs>
@@ -117,13 +142,18 @@ aws route53 change-resource-record-sets --hosted-zone-id <hosted-zone> --change-
 ---
 
 <Callout type="info">
-  Ensure that your domain’s nameservers are pointing to your chosen DNS provider
-  at your registrar, and that you have permission to create and manage DNS
-  records programmatically. <br /> **This is crucial for the setup to work
-  correctly and will take time to propagate.**
 
-Use https://dnschecker.org/#NS to verify that your domain's nameservers are correctly set up.
+DNS record changes do not occur immediately.
 
 </Callout>
 
-Once you have these prerequisites in place, you can proceed to the next steps in setting up the cluster and application.
+Before you continue:
+
+1. Make sure that the registrar uses the name servers of your DNS provider.
+2. Make sure that you can use automation to manage the DNS records.
+3. Use https://dnschecker.org/#NS to examine the domain name servers.
+
+When you have these starter-path prerequisites, [set up the evaluation
+cluster](/docs/setup/setup-infra). If you currently operate a compatible
+cluster, use the [existing-cluster Helm
+path](/docs/setup/install-lifecycle#path-b-operator-managed-helm-installation).
diff --git a/src/pages/docs/setup/setup-infra.mdx b/src/pages/docs/setup/setup-infra.mdx
index c39a5acb..c0b7065b 100644
--- a/src/pages/docs/setup/setup-infra.mdx
+++ b/src/pages/docs/setup/setup-infra.mdx
@@ -1,5 +1,12 @@
 ---
-title: Setup your cluster
+title: Set up an evaluation cluster
+description: Provision starter GKE or EKS infrastructure, DNS, dependencies, and Lifecycle for evaluation.
+audience:
+  - evaluator
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - cluster
   - setup
@@ -8,32 +15,49 @@ tags:
 ---
 
 import { Callout } from "nextra/components";
-import { Info, Cog } from "lucide-react";
-import { Cards } from "nextra/components";
+import { Info } from "lucide-react";
 
-Based on the prerequisites you've set up, you're now ready to configure your Kubernetes cluster for Lifecycle. This setup will ensure that your cluster is properly configured to run Lifecycle and manage your application environments effectively.
+When you have all [starter infrastructure
+prerequisites](/docs/setup/prerequisites), use this page to provision GKE or
+EKS. The OpenTofu module creates the cluster, supporting services, DNS, and, by
+default, Lifecycle itself.
 
 <Callout type="error" emoji="⚠️">
-  Note that the infra setup with the OpenTofu modules below will **open your
-  cluster to the world.** <br />
-  🛡️ Make sure to **<a href="https://translate.google.com/details?sl=auto&tl=hy&text=shield&op=translate">shield</a>** your cluster by implementing appropriate network policies
-  and access controls after the initial setup.
+  The starter OpenTofu module creates publicly reachable resources and is
+  intended for testing, demos, and learning, not production. Apply applicable
+  network policies and identity controls. Your organization must approve these
+  security controls.
+</Callout>
+
+## Select the installation path
+
+Use this **evaluation and demo path** for a starter cluster. The OpenTofu module
+defaults `app_lifecycle_enabled` to `true`. Thus, `tofu apply` creates the
+infrastructure and installs the `lifecycle` Helm release. Do not install
+Lifecycle a second time with this default path.
 
+An **operator-managed Helm path** needs a supported existing cluster. If you use
+the starter module, set `app_lifecycle_enabled = false` before you apply it.
+Then, follow [Install Lifecycle](/docs/setup/install-lifecycle).
+
+<Callout type="warning">
+  Use these paths for evaluation only. The module pins chart and application
+  versions. Before each apply, examine the OpenTofu plan and pinned versions.
 </Callout>
 
-Click on the cloud provider you are using to set up your cluster:
+Select the cloud provider for the evaluation cluster:
 
 - [Google Cloud Platform (GCP)](#google-cloud-platform)
 - [Amazon Web Services (AWS)](#amazon-web-services)
 
 ## Google Cloud Platform
 
-### Setup application credentials
+### Set up application credentials
 
 ```sh
-# setup current project
+# Select the project.
 gcloud config set project <PROJECT_ID>
-# creates the application default credentials
+# Create the application default credentials.
 gcloud auth application-default login
 ```
 
@@ -45,19 +69,20 @@ gcloud services enable dns.googleapis.com --project=<PROJECT_ID>
 ```
 
 <Callout type="info" icon={Info}>
-  Note that you need to replace `<PROJECT_ID>` with your actual Google Cloud project ID not the project name.
+  `<PROJECT_ID>` is the Google Cloud project ID, not the project name.
 </Callout>
 
 ### Bootstrap infrastructure
 
-- Clone the infrastructure repository:
+Clone the infrastructure repository:
 
 ```sh
 git clone https://github.com/GoodRxOSS/lifecycle-opentofu/
 cd lifecycle-opentofu
+git checkout b14865912608096379c28ef648f7ed99538b5600
 ```
 
-- Follow steps in the [infrastructure repository](https://github.com/GoodRxOSS/lifecycle-opentofu/?tab=readme-ov-file#%EF%B8%8F-quick-start) to set up the necessary infrastructure components.
+Copy the example input file:
 
 ```sh
 cp example.auto.tfvars secrets.auto.tfvars
@@ -66,19 +91,31 @@ cp example.auto.tfvars secrets.auto.tfvars
 Example `secrets.auto.tfvars` file:
 
 ```hcl secrets.auto.tfvars
-gcp_project          = "<PROJECT_ID>"
-gcp_region           = "<REGION_TO_DEPLOY>"
+gcp_project = "<PROJECT_ID>"
+gcp_region  = "<REGION_TO_DEPLOY>"
 # this is the default credentials file created by gcloud cli
-gcp_credentials_file = "~/.config/gcloud/application_default_credentials.json"
-cluster_provider     = "gke"
-dns_provider         = "cloud-dns"     # [cloudflare|route53|cloud-dns]
-app_domain           = "<YOUR_DOMAIN>" # e.g. 0env.com
-
-cluster_name         = "lifecycle-gke" # change this to your preferred cluster name
-app_namespace        = "lifecycle-app" # use default namespace
+gcp_credentials_file  = "~/.config/gcloud/application_default_credentials.json"
+cluster_provider      = "gke"
+dns_provider          = "cloud-dns"     # [cloudflare|route53|cloud-dns]
+app_domain            = "<YOUR_DOMAIN>" # e.g. lifecycle.example.org
+app_lifecycle_enabled = true            # evaluation path installs Lifecycle
+# Required only when dns_provider = "cloudflare":
+# cloudflare_api_token = "<CLOUDFLARE_API_TOKEN>"
+
+cluster_name  = "lifecycle-gke" # change this to your preferred cluster name
+app_namespace = "lifecycle-app" # chosen namespace for this guide
 ```
 
-- Initialize and apply the Terraform configuration:
+<Callout type="warning">
+  When `dns_provider = "cloudflare"`, uncomment `cloudflare_api_token`. Use a
+  Cloudflare API token that can manage the selected DNS zone. Keep the token in
+  `secrets.auto.tfvars`. The infrastructure repository ignores this file. Do not
+  commit it. See the [infrastructure
+  revision](https://github.com/GoodRxOSS/lifecycle-opentofu/tree/b14865912608096379c28ef648f7ed99538b5600)
+  for the token-scope requirements.
+</Callout>
+
+Initialize OpenTofu. Examine the plan. Apply the plan:
 
 ```sh
 tofu init
@@ -86,55 +123,54 @@ tofu plan
 tofu apply
 ```
 
-This will create the necessary infrastructure components, including the Kubernetes cluster, DNS records, database, redis and other resources required for Lifecycle to function properly.
-
-After the Terraform apply completes, you should have a fully functional Kubernetes cluster with the necessary resources set up.
+This creates the Kubernetes cluster, supporting services, DNS records, and,
+because `app_lifecycle_enabled` is `true`, the Lifecycle Helm release.
 
-Let's test the public DNS setup by accessing the test application deployed called `kuard` and follow the rest of the setup instructions from the `tofu apply` output.
+After the apply completes, follow its kubeconfig instructions. Then, test the
+sample application:
 
 ```sh
-curl -v https://kuard.0env.com  # replace with your domain
+curl -v "https://kuard.<YOUR_DOMAIN>"
 ```
 
-Refer example output [here](https://github.com/GoodRxOSS/lifecycle-opentofu/?tab=readme-ov-file#4-initialize--apply) to setup kubeconfig and access the cluster using `kubectl`.
-
-Now that your cluster is set up, you can proceed to installing Lifecycle application to your cluster.
-
-<br />
-<Cards.Card
-  icon={<Cog />}
-  title="Install Lifecycle"
-  href="/docs/setup/install-lifecycle"
-  arrow
-/>
+See the example [apply
+output](https://github.com/GoodRxOSS/lifecycle-opentofu/blob/b14865912608096379c28ef648f7ed99538b5600/README.md#4-initialize--apply)
+for more kubeconfig details. Continue to [test the evaluation
+installation](#test-the-evaluation-installation). Do not run a second Helm
+installation.
 
 ---
 
 ## Amazon Web Services
 
 ```sh
-# setup current project
+# Configure the evaluation profile
 aws configure --profile lifecycle-oss-eks
 AWS Access Key ID [***]: <key id, or enter>
-AWS AWS Secret Access Key [***]: <secret key, or enter>
+AWS Secret Access Key [***]: <secret key, or enter>
 Default Region name: <region, or enter>
 Default output format: <format, or enter>
 ```
 
-\*This profile needs to have access a user with `AdministratorAccess` access.
+<Callout type="warning">
+  The AWS evaluation procedure uses `AdministratorAccess`. Limit that access to
+  an isolated evaluation account. Remove the access when the test ends. Use
+  approved least-privilege permissions for an operator-managed deployment.
+</Callout>
 
 ---
 
 ### Bootstrap infrastructure
 
-- Clone the infrastructure repository:
+Clone the infrastructure repository:
 
 ```sh
 git clone https://github.com/GoodRxOSS/lifecycle-opentofu/
 cd lifecycle-opentofu
+git checkout b14865912608096379c28ef648f7ed99538b5600
 ```
 
-- Follow steps in the [infrastructure repository](https://github.com/GoodRxOSS/lifecycle-opentofu/?tab=readme-ov-file#%EF%B8%8F-quick-start) to set up the necessary infrastructure components.
+Copy the example input file:
 
 ```sh
 cp example.auto.tfvars secrets.auto.tfvars
@@ -143,19 +179,29 @@ cp example.auto.tfvars secrets.auto.tfvars
 Example `secrets.auto.tfvars` file:
 
 ```hcl secrets.auto.tfvars
-# gcp_project          = "<PROJECT_ID>"
-$ gcp_region           = "<REGION_TO_DEPLOY>"
-# this is the default credentials file created by gcloud cli
-# gcp_credentials_file = "~/.config/gcloud/application_default_credentials.json"
-cluster_provider     = "aws"
-dns_provider         = "route53"     # [cloudflare|route53|cloud-dns]
-app_domain           = "example.com" # e.g. 0env.com
-
-cluster_name         = "lifecycle-eks" # change this to your preferred cluster name
-app_namespace        = "lifecycle-app" # use default namespace
+aws_profile           = "lifecycle-oss-eks"
+aws_region            = "<REGION_TO_DEPLOY>"
+cluster_provider      = "eks"
+dns_provider          = "route53"     # [cloudflare|route53|cloud-dns]
+app_domain            = "lifecycle.example.org"
+app_lifecycle_enabled = true          # evaluation path installs Lifecycle
+# Required only when dns_provider = "cloudflare":
+# cloudflare_api_token = "<CLOUDFLARE_API_TOKEN>"
+
+cluster_name  = "lifecycle-eks" # change this to your preferred cluster name
+app_namespace = "lifecycle-app" # chosen namespace for this guide
 ```
 
-- Initialize and apply the Terraform configuration:
+<Callout type="warning">
+  When `dns_provider = "cloudflare"`, uncomment `cloudflare_api_token`. Use a
+  Cloudflare API token that can manage the selected DNS zone. Keep the token in
+  `secrets.auto.tfvars`. The infrastructure repository ignores this file. Do not
+  commit it. See the [infrastructure
+  revision](https://github.com/GoodRxOSS/lifecycle-opentofu/tree/b14865912608096379c28ef648f7ed99538b5600)
+  for the token-scope requirements.
+</Callout>
+
+Initialize OpenTofu. Examine the plan. Apply the plan:
 
 ```sh
 tofu init
@@ -163,24 +209,35 @@ tofu plan
 tofu apply
 ```
 
-This will create the necessary infrastructure components, including the Kubernetes cluster, DNS records, database, redis and other resources required for Lifecycle to function properly.
-
-After the Terraform apply completes, you should have a fully functional Kubernetes cluster with the necessary resources set up.
+This creates the Kubernetes cluster, supporting services, DNS records, and,
+because `app_lifecycle_enabled` is `true`, the Lifecycle Helm release.
 
-Let's test the public DNS setup by accessing the test application deployed called `kuard` and follow the rest of the setup instructions from the `tofu apply` output.
+After the apply completes, follow its kubeconfig instructions. Then, test the
+sample application:
 
 ```sh
-curl -v https://kuard.0env.com  # replace with your domain
+curl -v "https://kuard.<YOUR_DOMAIN>"
 ```
 
-Refer example output [here](https://github.com/GoodRxOSS/lifecycle-opentofu/?tab=readme-ov-file#4-initialize--apply) to setup kubeconfig and access the cluster using `kubectl`.
+See the example [apply
+output](https://github.com/GoodRxOSS/lifecycle-opentofu/blob/b14865912608096379c28ef648f7ed99538b5600/README.md#4-initialize--apply)
+for more kubeconfig details. Continue to the installation test section. Do not
+run a second Helm installation.
+
+## Test the evaluation installation
+
+Use the same namespace and host values supplied to OpenTofu:
+
+```sh
+export LIFECYCLE_NAMESPACE="<app_namespace>"
+export LIFECYCLE_APP_HOST="<app_subdomain>.<app_domain>"
+
+kubectl get deployments,pods --namespace "$LIFECYCLE_NAMESPACE"
+curl --fail --head "https://${LIFECYCLE_APP_HOST}"
+```
 
-Now that your cluster is set up, you can proceed to installing Lifecycle application to your cluster.
+Wait for the Lifecycle deployments. Make sure that the HTTPS endpoint responds.
+If the module's pinned release fails, examine the OpenTofu and Kubernetes output.
+Do not add a second Helm release.
 
-<br />
-<Cards.Card
-  icon={<Cog />}
-  title="Install Lifecycle"
-  href="/docs/setup/install-lifecycle"
-  arrow
-/>
+Then, [create and connect the GitHub App](/docs/setup/create-github-app).
diff --git a/src/pages/docs/tips/_meta.ts b/src/pages/docs/tips/_meta.ts
index 6270149b..faec09a0 100644
--- a/src/pages/docs/tips/_meta.ts
+++ b/src/pages/docs/tips/_meta.ts
@@ -16,9 +16,9 @@
 
 export default {
   "using-mission-control": {
-    "title": "Mission Control comment"
+    "title": "Use the Mission Control comment"
   },
   "telemetry": {
-    "title": "Telemetry"
+    "title": "Datadog application telemetry"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/tips/telemetry.mdx b/src/pages/docs/tips/telemetry.mdx
index d7c1215e..55425522 100644
--- a/src/pages/docs/tips/telemetry.mdx
+++ b/src/pages/docs/tips/telemetry.mdx
@@ -1,43 +1,92 @@
 ---
-title: Telemetry
+title: Datadog application telemetry
+description: Add standard Datadog labels so Datadog can correlate application telemetry by Environment and Service.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
-  - logs
-  - metrics
   - telemetry
   - datadog
-  - observability
+  - kubernetes
 ---
 
-Lifecycle comes with built-in support for Datadog telemetry. To collect logs and metrics from your cluster and deployed applications, install the Datadog Agent and Cluster Agent in your cluster.
+import { Callout } from "nextra/components";
 
-The deployed applications are already configured with the necessary Datadog labels and environment variables for seamless integration:
+Lifecycle can add standard Datadog labels to deployed workloads. Datadog uses
+these labels to correlate application logs, metrics, and traces with a service
+and environment.
 
-**Pod labels:**
+This is application workload telemetry. It is different from pseudonymous
+[Lifecycle CLI usage telemetry](/docs/features/cli-telemetry).
+
+## Understand the label values
+
+For a Service that does not use native Helm, Lifecycle puts these labels on the
+Deployment and its pod template:
 
 ```yaml
-tags.datadoghq.com/env: lifecycle-binlab-zero-101010
-tags.datadoghq.com/service: frontend
-tags.datadoghq.com/version: binlab-zero-101010
+metadata:
+  labels:
+    tags.datadoghq.com/env: "lifecycle-<environment-id>"
+    tags.datadoghq.com/service: "<service-name>"
+    tags.datadoghq.com/version: "<environment-id>"
 ```
 
-**Environment variables:**
+It also sets `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` from these pod labels when
+the application does not set those variables.
 
-```yaml
-- name: DD_ENV
-  valueFrom:
-    fieldRef:
-      apiVersion: v1
-      fieldPath: metadata.labels['tags.datadoghq.com/env']
-- name: DD_SERVICE
-  valueFrom:
-    fieldRef:
-      apiVersion: v1
-      fieldPath: metadata.labels['tags.datadoghq.com/service']
-- name: DD_VERSION
-  valueFrom:
-    fieldRef:
-      apiVersion: v1
-      fieldPath: metadata.labels['tags.datadoghq.com/version']
+## Add labels to a native Helm chart
+
+Lifecycle cannot add labels to an arbitrary native Helm chart. The chart must
+put them on the pod template. For example, a chart can define these values:
+
+```yaml filename="templates/deployment.yaml"
+spec:
+  template:
+    metadata:
+      labels:
+        tags.datadoghq.com/env: { { .Values.datadog.environment | quote } }
+        tags.datadoghq.com/service: { { .Values.datadog.service | quote } }
+        tags.datadoghq.com/version: { { .Values.datadog.version | quote } }
+```
+
+Then, pass the Lifecycle values through that chart's `values` contract:
+
+```yaml filename="lifecycle.yaml"
+services:
+  - name: "web"
+    helm:
+      deploymentMethod: "native"
+      repository: "example-org/example-app"
+      branchName: "main"
+      chart:
+        name: "./charts/web"
+        values:
+          - "datadog.environment=lifecycle-{{{buildUUID}}}"
+          - "datadog.service=web"
+          - "datadog.version={{{buildUUID}}}"
 ```
 
-This setup ensures that Datadog automatically detects the environment, service, and version for each application, enabling rich observability and correlation of logs and metrics in the Datadog platform.
+Use the value names that your chart defines. Keep the labels on the pod
+template. Datadog agents observe pods, not only the parent Deployment object.
+
+## Rendered-value check
+
+1. Deploy the chart through Lifecycle.
+2. Examine the rendered workload and pod labels.
+3. Make sure that the Environment ID and Service name values exist.
+4. Make sure that the values do not contain credentials or other sensitive
+   data.
+5. Query the related tags in your organization's Datadog account.
+
+If a field is empty, examine the chart's value names and the generated Helm
+values for that Environment.
+
+<Callout type="info">
+  These labels help Datadog correlate telemetry. They do not install or
+  configure a Datadog agent. Your platform team must supply the collection
+  pipeline and retention policy.
+</Callout>
diff --git a/src/pages/docs/tips/using-mission-control.mdx b/src/pages/docs/tips/using-mission-control.mdx
index 8c43ef6a..1664b922 100644
--- a/src/pages/docs/tips/using-mission-control.mdx
+++ b/src/pages/docs/tips/using-mission-control.mdx
@@ -1,91 +1,110 @@
 ---
-title: Mission Control comment
-description: >-
-  Use the Mission Control PR Comment to modify and customize your environment
-  directly from the pull request comment.
+title: Use the Mission Control comment
+description: Select Services, change sources, set Environment overrides, and request actions from Lifecycle's editable pull-request comment.
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - pull request
   - comment
-  - mission control
   - environment
-  - pr
 ---
 
 import { Callout } from "nextra/components";
 
-Lifecycle uses **Mission Control PR Comments** to allow users to modify and customize their environments directly from the pull request comment. This enables easy **service selection**, **branch customization**, and **environment variable overrides** without modifying `lifecycle.yaml`.
+Lifecycle's Mission Control comment is a status surface and structured input.
+Edit only the values and checkboxes in this comment. Keep the generated
+headings and the syntax around them so Lifecycle can parse the result.
 
----
-
-## Selecting and Deselecting Services
-
-Each pull request environment includes **default services** and optional additional services. You can enable or disable services using the checkboxes.
+## Select Services
 
-- **Enabled Services** are marked with `[x]`.
-- **Disabled Services** are marked with `[ ]`.
-
-**Example:**
+The comment groups selected default Services and available optional Services.
+Lifecycle enables a checked item:
 
 ```md
-// Default Services
+### Default Services
 
-- [x] frontend: dev-default
-- [x] fastly: main
+- [x] web: main
 
-// Optional Additional Services
+### Optional Services
 
-- [ ] backend-service: main
-- [ ] backend-db: main
-- [ ] backend-cache: main
+- [ ] worker: main
+- [ ] cache: main
 ```
 
-To **enable** a service, change `[ ]` to `[x]`. To **disable** a service, change `[x]` to `[ ]`. As simple as that!
-
-<Callout type="warning">
-  If you need to make multiple selections or deselections at once, use the
-  **Edit Comment** option instead of clicking checkboxes individually. This
-  prevents multiple back-to-back builds, as each selection triggers an event in
-  Lifecycle without deduplication.
-</Callout>
-
-## Choosing a Branch
+When possible, check or clear multiple Services in one edit. Each saved
+checkbox change can queue work.
 
-To deploy a specific branch for a service, modify the branch name after the service name.
+## Change a branch or external URL
 
-**Example:**
+For an editable Service, replace the value after its name:
 
 ```md
-- [x] frontend: feature-branch
-- [x] fastly: main
+- [x] web: feature/navigation
+- [x] shared-api: https://api.preview.example
 ```
 
-This will deploy `frontend` using the `feature-branch` instead of the default branch.
+Lifecycle checks whether the Service type accepts a branch or external URL.
+If it restores the previous value, examine the generated comment message and the
+repository configuration.
 
-## Overriding Environment Variables
+## Change the Environment ID
 
-To set additional environment variables, use the **Override Environment Variables** section in the PR comment.
-
-**Example:**
+The comment uses the historical label **UUID**, but the value is a
+human-readable Environment ID, not an RFC UUID:
 
 ```md
-// **Override Environment Variables:** _ENV:[KEY]:[VALUE]_
-ENV:API_URL:https://api.custom.dev.0env.com
-ENV:CHIEF_INTERN:ICEYCAKE
+### UUID
+
+url: docs-preview
 ```
 
-This sets `API_URL` and `CHIEF_INTERN` in the environment without modifying the service configuration.
+IDs use 3–50 lowercase letters, numbers, and hyphens. If you change the ID,
+Lifecycle also changes URLs and references that contain it.
 
-## Override UUID
+## Set temporary Environment variables
 
-To set a custom UUID (subdomain) for the environment, use the **Override UUID** section in the PR comment.
+Add one runtime override per line:
 
 ```md
-// UUID (Pick your own custom subdomain)
-url: wagon-builder-060825
+### Environment variable overrides
+
+ENV:API_BASE_URL:https://api.preview.example
+ENV:FEATURE_MODE:review
 ```
 
-Replace `wagon-builder-060825` with your desired subdomain. This allows you to customize the environment URL without changing the underlying service configuration.
+These values apply to this Environment and do not update `lifecycle.yaml`.
+Move a durable non-secret value into repository configuration after the test.
 
----
+<Callout type="warning">
+  Do not put secrets in a pull-request comment. Pull-request participants and
+  repository integrations can read comment history. Use a supported cloud-secret
+  reference in the execution paths that resolve it.
+</Callout>
+
+## Request actions
+
+The generated **Actions** section exposes operations supported for the current
+Environment, such as redeploy. Keep the action text and change only the
+shown checkbox or value.
+
+An **Options** section appears only for settings that apply to the current
+Environment. For example, a configured CDN Service can expose a purge option.
+Default-branch tracking controls are conditional. Their presence does not mean
+that all Environments can enable tracking from the comment.
+
+## Edit check
+
+After you save the comment, complete these steps:
+
+1. Wait for Lifecycle to update the comment.
+2. Make sure that Lifecycle retained the value.
+3. Open the linked Environment.
+4. Check the queued status.
+5. Use the UI or `lfc builds status <environment-id> --watch` to follow the
+   result.
 
-Using the **Mission Control PR Comment**, you can easily customize your environment **without modifying code**, making it a flexible way to test and deploy changes dynamically.
+If the comment does not update, see
+[Missing pull-request comment](/docs/troubleshooting/github-app-webhooks).
diff --git a/src/pages/docs/troubleshooting/_meta.ts b/src/pages/docs/troubleshooting/_meta.ts
index aa85da6f..ea8c3688 100644
--- a/src/pages/docs/troubleshooting/_meta.ts
+++ b/src/pages/docs/troubleshooting/_meta.ts
@@ -15,13 +15,22 @@
  */
 
 export default {
+  "index": {
+    "title": "Troubleshooting"
+  },
+  "stuck-environment": {
+    "title": "Troubleshoot a stuck Environment"
+  },
   "build-issues": {
-    "title": "Build Issues"
+    "title": "Troubleshoot a failed build"
   },
   "deploy-issues": {
-    "title": "Deploy Issues"
+    "title": "Troubleshoot a failed deployment"
   },
   "github-app-webhooks": {
     "title": "Missing PR comment"
+  },
+  "access-and-api": {
+    "title": "Troubleshoot access and API errors"
   }
 };
\ No newline at end of file
diff --git a/src/pages/docs/troubleshooting/access-and-api.mdx b/src/pages/docs/troubleshooting/access-and-api.mdx
new file mode 100644
index 00000000..9a417826
--- /dev/null
+++ b/src/pages/docs/troubleshooting/access-and-api.mdx
@@ -0,0 +1,73 @@
+---
+title: Troubleshoot access and API errors
+description: Diagnose Lifecycle sign-in, GitHub linking, API key, scope, repository, and feature-policy failures while credentials stay secret.
+audience:
+  - api-user
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - troubleshooting
+  - authentication
+  - api
+---
+
+Keep browser identity, linked GitHub identity, API-key authorization, and
+feature policy as different concepts. They are related but not interchangeable.
+
+## Cannot sign in
+
+1. Make sure that the UI and identity hostnames resolve and have valid TLS.
+2. Use the identity provider configured by your Lifecycle operator.
+3. If using the bundled temporary bootstrap account, complete the necessary
+   first-login password change.
+4. Give the operator the time, browser-visible error, and request ID. Do not
+   send a password, session cookie, authorization code, or token.
+
+If the deployment has authentication disabled, do not work around the error by
+exposing it to a shared network. Auth-off mode is only an isolated local
+evaluation posture.
+
+## Signed in but GitHub features are missing
+
+A successful sign-in does not link a GitHub user. Use the **Link GitHub**
+prompt or the Account or Settings connection control. A linked user is also
+different from:
+
+- installing the Lifecycle GitHub App
+- [onboarding a repository](/docs/getting-started/onboard-repository)
+
+Examine the three relationships for repository creation, attribution, and Agent
+Git operations.
+
+## API returns 401
+
+- Make sure that the header uses `Authorization: Bearer <token>`.
+- When you created the key, you had to copy its plaintext value. Lifecycle
+  cannot retrieve the key again.
+- Make sure that the key was not revoked or expired.
+- Make sure that the deployment has supported authentication and API-key
+  issuance enabled.
+- Record only the non-secret token prefix and key ID—not the token.
+
+## API returns 403
+
+- Make sure that the key type can request the necessary scope.
+- Examine scope implication: write includes read for the same resource.
+- Examine selected-repository access and repository onboarding.
+- Examine the administrator's feature switch for API keys, API Environments,
+  or Sites.
+- Remember that a reachable endpoint does not bypass its policy gate.
+
+Use the authenticated v2 auth-context endpoint described in
+[API keys](/docs/api-authentication/api-keys) to examine the resolved principal
+without printing a credential.
+
+## API returns 429
+
+The API-access default is 600 requests per minute. Administrators can change
+this policy. When the response contains `Retry-After`, respect its value. Use
+pagination. Do not poll faster than necessary for the task. Use idempotency keys
+for create requests that support them.
diff --git a/src/pages/docs/troubleshooting/build-issues.mdx b/src/pages/docs/troubleshooting/build-issues.mdx
index c5d5ef59..52f6bde3 100644
--- a/src/pages/docs/troubleshooting/build-issues.mdx
+++ b/src/pages/docs/troubleshooting/build-issues.mdx
@@ -1,17 +1,86 @@
 ---
-title: Troubleshooting Build Issues
-description: Understand how to handle common build issues with environments
+title: Troubleshoot a failed build
+description: Identify the failed Service build, examine the correct job logs, correct the source or build configuration, and check a redeploy.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
+  - troubleshooting
   - build
-  - issues
-  - error
-  - codefresh
-navtext: Build Issues
+  - logs
 ---
 
 import { Callout } from "nextra/components";
 
-<Callout type="info">
-  TODO: This document will cover common build issues that you may encounter when
-  working with Lifecycle environments.
+A **Build failed** Service did not create the image or build artifact necessary
+for deployment. Start with build history and build logs. Pod logs give
+information about a deployed workload. They usually cannot identify this
+phase's cause.
+
+## 1. Find the failing phase
+
+Open the Environment. Select the failed Service.
+
+- **Config error** means Lifecycle could not accept or resolve the repository
+  configuration. Correct the validation error first.
+- **Build failed** means a native or external image build failed. Continue
+  with the next steps.
+- **Deploy failed** means the image was built but the workload could not be
+  applied or become ready. Use
+  [Troubleshoot a failed deployment](/docs/troubleshooting/deploy-issues).
+
+## 2. Read the failed build attempt
+
+In the UI, open **Console → Build**. Select the newest failed attempt. Find the
+earliest actionable error. Later lines usually show a downstream error such as
+“job failed.”
+
+From the CLI:
+
+```sh
+lfc services history <environment-id> <service-name>
+lfc services logs <environment-id> <service-name> --tail 500 --timestamps
+```
+
+For a previous attempt, use `--job <job-name>`. While the current job runs, use
+`--follow`.
+
+## 3. Match the error to a cause
+
+| Signal                              | Check                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| Repository or revision not found    | GitHub App repository access, onboarding, repository spelling, branch, and SHA |
+| Dockerfile or build context missing | `dockerfile`, `context`, and paths relative to the source repository           |
+| Base image or dependency denied     | Registry credentials, image name, tag, network access, and rate limits         |
+| Build command or compiler error     | The first source error and the revision shown for the attempt                  |
+| No space, out of memory, or timeout | Builder capacity, resource limits, and context size                            |
+| External pipeline failed            | The linked pipeline run, configured pipeline ID, and provider authentication   |
+
+Do not copy credentials or full Environment-variable output into an issue.
+Share the Environment ID, Service name, job name, source SHA, engine, and the
+smallest redacted error excerpt.
+
+## 4. Correct and retry
+
+Commit source or `lifecycle.yaml` fixes to the owning branch. Lifecycle usually
+queues the updated Service after the push. To retry unchanged inputs:
+
+```sh
+lfc services redeploy <environment-id> <service-name>
+lfc builds status <environment-id> --watch
+```
+
+<Callout type="warning">
+  Another retry does not correct a deterministic configuration, source,
+  credential, or capacity failure. Before you redeploy, read the first failed
+  attempt.
 </Callout>
+
+## 5. Recovery check
+
+The Service goes from **Building** to **Built**. Then, it goes through its
+deployment phase to **Ready**. If the build succeeds but deployment fails,
+switch to the deployment guide. Do not continue to examine build logs.
diff --git a/src/pages/docs/troubleshooting/deploy-issues.mdx b/src/pages/docs/troubleshooting/deploy-issues.mdx
index 7d460662..f21a9c3f 100644
--- a/src/pages/docs/troubleshooting/deploy-issues.mdx
+++ b/src/pages/docs/troubleshooting/deploy-issues.mdx
@@ -1,17 +1,136 @@
 ---
-title: Deploy Issues
-description: Understand how to handle common deploy issues with environments
+title: Troubleshoot a failed deployment
+description: Find the failed Service, examine the related logs, correct the cause, and redeploy an Environment.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - deploy
-  - issues
-  - error
-  - todo
-  - codefresh
+  - troubleshooting
+  - errors
+  - logs
 ---
 
 import { Callout } from "nextra/components";
 
+When an Environment shows **Config error** or **Error**, use this workflow. Also
+use this workflow when a Service shows **Deploy failed** or **Error**. If a
+Service shows **Build failed**, use
+[Troubleshoot a failed build](/docs/troubleshooting/build-issues).
+
+## Resolve a Config error first
+
+A **Config error** happens before Lifecycle can run the affected Services. A
+failed Service or Console does not always exist.
+
+1. Read the **Config error** in the Environment metadata.
+2. Check **Current branch schema**.
+
+   - **Invalid:** Correct `lifecycle.yaml` using the
+     [schema reference](/docs/schema/overview).
+   - **Valid now:** The branch is correct, but the Environment continues to
+     record the earlier failed snapshot.
+
+3. When the branch is valid, select **Actions**.
+4. Select **Redeploy**.
+
+For a static Environment, an administrator must do this action.
+
+## Find the first useful failure reason
+
+For an Environment-level **Error** or a Service failure:
+
+1. Open **Environments** in Lifecycle.
+2. Select the affected Environment.
+3. If the Environment shows **Error**, hover over or focus that status to read
+   the Environment failure message.
+4. If a Service shows **Build failed**, **Deploy failed**, or **Error**, select
+   it from the Service list. The UI shows failed Services before healthy
+   Services.
+5. Before you open longer logs, read the Service **Failure reason** on the
+   **Summary** tab.
+
+If no Service failed, use the Environment failure message as the primary
+evidence. Then, [escalate it](#escalate-with-useful-evidence). Service Console
+logs might not exist.
+
+The summary tells you which Service failed. It identifies the cause or narrows
+the failure to a phase. For example, a Failure reason such as
+`Kubernetes apply job failed` identifies the deployment phase, but not the root
+cause. Open the **Deploy** logs to find the actionable error before retrying.
+
+## Open the related logs
+
+For a failed Service, select **Console**. Then, use the phase that matches its
+status.
+
+- **Build failed:** Select **Build**. Open the failed build attempt.
+- **Deploy failed:** Select **Deploy**. Open the failed deployment attempt.
+- **Error:** Start with the **Failure reason**. Then, examine **Build** or
+  **Deploy** for the last completed phase.
+- **Ready, but the application is unhealthy:** Select **Pods** to examine the
+  running container logs.
+
+A red dot on **Build** or **Deploy** marks the failed phase. If Lifecycle uses an
+external pipeline for that phase, the Console can show a link to its logs as an
+alternative to native job logs.
+
+Look for the earliest actionable error, not all symptoms that follow it. Do not
+include tokens, secret values, or full environment-variable output when
+sharing logs.
+
+## Correct the cause
+
+Use the Environment message or Service failure reason and logs to check the
+failed phase:
+
+| Failure             | Check first                                                                                                                |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Configuration error | The **Current branch schema** result and the related [`lifecycle.yaml` reference](/docs/schema/overview)                   |
+| Build failed        | Repository and branch access, Dockerfile path, build context, base images, and registry access                             |
+| Deploy failed       | Container image and tag, deployment dependencies, environment-variable names, resource limits, and readiness configuration |
+| Ready but unhealthy | Application startup output, health endpoints, dependency URLs, and runtime configuration                                   |
+
+If the failure comes from repository content, commit the correction. Push the
+correction before you retry.
+
+## Redeploy
+
+After correcting the cause:
+
+1. To retry one Service, select the circular-arrow **Redeploy** control on its
+   row.
+2. To retry the full Environment, select **Actions**, then **Redeploy**.
+3. Make sure that Lifecycle queues the redeploy.
+4. Wait until the Environment shows **Deployed**.
+5. Make sure that each necessary Service shows **Ready**.
+
+If you changed shared configuration or more than one Service, use a full
+Environment redeploy. A redeploy reuses the current source and configuration.
+Thus, it does not correct a deterministic error by itself.
+
+Lifecycle disables full redeploy for non-administrators on a static
+Environment. Administrators must enter `redeploy`.
+
 <Callout type="info">
-  TODO: This document will cover common deploy issues that you may encounter
-  when working with Lifecycle environments.
+  Application developers must start with the Lifecycle UI and the logs linked
+  there. Cluster-level diagnostics are an operator workflow, not the usual
+  recovery path for a failed Service.
 </Callout>
+
+## Escalate with useful evidence
+
+If the corrected deployment continues to fail, give your platform team:
+
+- Environment ID and, when applicable, Service name
+- Current status and the Environment failure message or Service **Failure
+  reason**
+- If **Build**, **Deploy**, or **Pods** contains the related error
+- Commit short SHA and approximate failure time
+- The smallest log excerpt that includes the actionable error
+
+Do not include credentials, tokens, secret values, or unrelated application
+data.
diff --git a/src/pages/docs/troubleshooting/github-app-webhooks.mdx b/src/pages/docs/troubleshooting/github-app-webhooks.mdx
index 8add6fc3..98884111 100644
--- a/src/pages/docs/troubleshooting/github-app-webhooks.mdx
+++ b/src/pages/docs/troubleshooting/github-app-webhooks.mdx
@@ -1,5 +1,12 @@
 ---
 title: Missing PR comment
+description: Diagnose failed GitHub App webhook deliveries without exposing credentials.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - mission control
   - comment
@@ -10,41 +17,99 @@ tags:
 
 import { Callout } from "nextra/components";
 
-Let's quickly validate that the app is able to send events to the Lifecycle app successfully.
+When the Mission Control comment is missing, start with the matching GitHub
+`pull_request` delivery for that repository and time. An `installation`
+delivery can succeed while the affected pull-request event continues to fail.
 
-- Navigate to your Github app
-- Click `App Settings` link in the Github application page
-- Choose `Advanced` from the left sidebar
-- `Recent Deliveries` section should show a successful delivery of the `installation` event to the Lifecycle app.
+## Examine the affected delivery
 
-  <Callout type="warning">
-    If you see an error or no deliveries, make sure the app is installed in the
-    atleast one repository and that the webhook URL is set correctly by
-    navigating to the `General` section from the left sidebar and checking the
-    `Webhook URL` field.
-  </Callout>
+1. Open the Lifecycle GitHub App's **Advanced** settings.
+2. In **Recent deliveries**, select the `pull_request` event for the affected
+   repository and action.
+3. Record the non-secret delivery ID, event, action, timestamp, response status,
+   and response message.
+4. Make sure that the target is the configured Lifecycle webhook URL.
+5. Make sure that its TLS
+   certificate is valid.
 
-- If the delivery is successful, you should see a status code of `200 OK`
+If no matching delivery exists, make sure that:
 
-## Failing deliveries
+- an App installation includes that repository
+- the App subscribes to pull-request events
+- the App has the documented repository permissions
+- the repository is [onboarded in
+  Lifecycle](/docs/getting-started/onboard-repository)
 
-If you see a delivery failure, it could be due to various reasons. Here are some common issues and how to resolve them:
+Do not create a different pull request at this time. Keep the first failed
+delivery so the request and response stay correlated.
 
-### Github App secrets
+## Match the Lifecycle request
 
-- Make sure that the Github App secrets are correctly set in the `lifecycle-app` namespace. You can verify this by running the following command:
+Set the Helm release and namespace used by the installation, then search recent
+web logs for the GitHub delivery ID:
 
 ```sh
-kubectl get secret app-secrets --namespace lifecycle-app \
-      -o jsonpath='{.data}' | jq 'with_entries(.value |= @base64d)'
+export HELM_RELEASE="<release-name>"
+export HELM_NAMESPACE="<namespace>"
+export GITHUB_DELIVERY_ID="<delivery-id>"
+
+kubectl logs --namespace "$HELM_NAMESPACE" \
+  -l "app.kubernetes.io/instance=$HELM_RELEASE,app.kubernetes.io/component=web" \
+  --all-containers=true --since=30m --prefix \
+  | grep -F "$GITHUB_DELIVERY_ID"
 ```
 
-- The output should include all the `GITHUB_*` variables with the correct values.
+Use the response and matching log message to select the next check:
+
+| Evidence                         | Next check                                                                                                               |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| DNS, connection, or TLS failure  | Correct the public webhook hostname, DNS, certificate, or ingress path                                                   |
+| Signature or credential error    | Bootstrap Secret key presence and the approved credential-rotation workflow                                              |
+| Repository ignored or not found  | Make sure of App access and Lifecycle onboarding                                                                         |
+| Accepted delivery but no comment | Examine the worker queue and the affected Environment using [stuck Environment](/docs/troubleshooting/stuck-environment) |
+
+When you share evidence, include the delivery ID and status. Do not include
+payload secrets, signatures, authorization headers, or private repository
+content.
+
+## GitHub App key check
 
-- If the secrets are present but the delivery is still failing, try restarting the following deployments.
+When the response or Lifecycle log points to GitHub App configuration, run this
+procedure.
+
+Lifecycle computes the bootstrap Secret name from the Helm release. You can
+override this name. Use chart labels to find it:
 
 ```sh
- kubectl rollout restart  deployment lifecycle-web lifecycle-worker -n lifecycle-app
+BOOTSTRAP_SECRET="$(
+  kubectl get secrets --namespace "$HELM_NAMESPACE" \
+    -l "app.kubernetes.io/instance=$HELM_RELEASE,app.kubernetes.io/component=bootstrap" \
+    -o jsonpath='{.items[0].metadata.name}'
+)"
+test -n "$BOOTSTRAP_SECRET"
 ```
 
-- Try triggering a new event (create a pull request) by making a change in the repository or by manually redelivering a failed delivery.
+Make sure that the expected keys exist. Do not decode or print their values:
+
+```sh
+kubectl get secret "$BOOTSTRAP_SECRET" --namespace "$HELM_NAMESPACE" \
+  -o json | jq -r '.data | keys[]' | sort
+```
+
+The key list must include the necessary `GITHUB_*` entries. If a value can be
+incorrect, use the secure installation procedure to rotate it. Do not paste
+decoded secrets into terminals, tickets, or chat.
+
+## Correction check
+
+After you correct the identified cause, redeliver the same failed GitHub
+delivery. Make sure that it receives a success response. Make sure that
+Lifecycle creates or updates the Mission Control comment.
+
+Only if the approved procedure specifies a restart, restart the component. Key
+presence alone is not a reason to restart the web and worker deployments.
+
+<Callout type="warning">
+  A second delivery can queue duplicate work after a response timeout. Before
+  you redeliver, examine the Environment and queue state.
+</Callout>
diff --git a/src/pages/docs/troubleshooting/index.mdx b/src/pages/docs/troubleshooting/index.mdx
new file mode 100644
index 00000000..dd5a2936
--- /dev/null
+++ b/src/pages/docs/troubleshooting/index.mdx
@@ -0,0 +1,43 @@
+---
+title: Troubleshooting
+description: Start from a Lifecycle symptom and open the guide for the failed phase with safe evidence and recovery steps.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - troubleshooting
+  - support
+---
+
+Start with the user-visible symptom. Before you know which phase failed, do not
+make broad cluster changes. Do not start another redeploy, edit the database, or
+dump secrets.
+
+| Symptom                                                      | First check                                   | Guide                                                                                 |
+| ------------------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------- |
+| No Lifecycle comment on a pull request                       | GitHub App access and repository onboarding   | [Missing pull-request comment](/docs/troubleshooting/github-app-webhooks)             |
+| Environment shows **Config error**                           | Repository configuration validation           | [Failed deployment](/docs/troubleshooting/deploy-issues#resolve-a-config-error-first) |
+| Service shows **Build failed**                               | **Console → Build**                           | [Failed build](/docs/troubleshooting/build-issues)                                    |
+| Service shows **Deploy failed** or does not become **Ready** | **Console → Deploy**, then **Pods**           | [Failed deployment](/docs/troubleshooting/deploy-issues)                              |
+| Environment remains queued or stale                          | Last update time and if other work progresses | [Stuck Environment](/docs/troubleshooting/stuck-environment)                          |
+| Cannot sign in, link GitHub, or call an API                  | Identity, key prefix, scopes, and request ID  | [Access and API errors](/docs/troubleshooting/access-and-api)                         |
+| MCP, Agent workspace, or Site feature is missing             | Feature availability and administrator policy | The feature's availability section                                                    |
+
+## Safe escalation bundle
+
+Collect:
+
+- Lifecycle component and version
+- Environment ID and Service name
+- current status and status message
+- source repository, branch, and short SHA when they are not private
+- job name, phase, and timestamps
+- request or correlation ID
+- the smallest related, redacted log excerpt
+
+Do not include access tokens, one-time API keys, OAuth callback query strings,
+Secret values, full Environment-variable dumps, private repository contents, or
+unredacted Agent conversations.
diff --git a/src/pages/docs/troubleshooting/stuck-environment.mdx b/src/pages/docs/troubleshooting/stuck-environment.mdx
new file mode 100644
index 00000000..cf2eed0e
--- /dev/null
+++ b/src/pages/docs/troubleshooting/stuck-environment.mdx
@@ -0,0 +1,75 @@
+---
+title: Troubleshoot a stuck Environment
+description: Find the last Lifecycle phase that changed and distinguish queue, build, deployment, readiness, and teardown delays.
+audience:
+  - application-developer
+  - platform-operator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
+tags:
+  - troubleshooting
+  - environment
+  - queue
+---
+
+An Environment is stuck when its status and last-update time stop changing for
+longer than comparable work in the same installation. Lifecycle does not
+publish a universal phase timeout. Compare it with the local workload and
+operator expectations.
+
+## Find the last phase
+
+```sh
+lfc builds get <environment-id>
+lfc builds status <environment-id>
+```
+
+Then use the status:
+
+| Status         | Examine                                                                 |
+| -------------- | ----------------------------------------------------------------------- |
+| `pending`      | Feature policy, repository processing, and whether a worker queued work |
+| `queued`       | Worker availability and whether other queued Environments change        |
+| `building`     | Service build history and the active build job                          |
+| `deploying`    | Service deploy job, Kubernetes apply output, and readiness              |
+| `tearing_down` | Cleanup worker output and remaining Environment state                   |
+
+If the phase has a failure status, switch to [build
+recovery](/docs/troubleshooting/build-issues) or [deployment
+recovery](/docs/troubleshooting/deploy-issues).
+
+For a view of one Service:
+
+```sh
+lfc services history <environment-id> <service-name>
+```
+
+## Check the control plane
+
+Operators can query `/api/health` on the affected component. A success response
+confirms only Postgres and Redis connections. A worker `/api/jobs` response
+does not confirm that jobs move through the queue.
+
+Correlate web and worker logs with the Environment ID and request ID. Before you
+restart a component, examine the same worker phase for a different Environment.
+See [Monitor Lifecycle](/docs/operations/monitoring) for the documented probe boundaries
+and a safe escalation bundle.
+
+## Retry only after diagnosis
+
+When one Service has a transient build or deploy problem, use a Service
+redeploy:
+
+```sh
+lfc services redeploy <environment-id> <service-name>
+```
+
+When the failure spans Services, use a full-Environment redeploy:
+
+```sh
+lfc builds redeploy <environment-id> --watch
+```
+
+Another retry can multiply queued work and hide the first error. Do not restart
+all workers or delete queue data as a first response.
diff --git a/src/pages/docs/what-is-lifecycle.mdx b/src/pages/docs/what-is-lifecycle.mdx
index 3cfe53dc..2a621f62 100644
--- a/src/pages/docs/what-is-lifecycle.mdx
+++ b/src/pages/docs/what-is-lifecycle.mdx
@@ -1,52 +1,75 @@
 ---
 title: What is Lifecycle?
-description: Lifecycle is your effortless way to test and create ephemeral environments
+description: Understand how Lifecycle creates connected, isolated application Environments for pull requests and API-driven workflows.
+audience:
+  - evaluator
+lastVerified: "2026-07-24"
+verificationBaseline: "2026-07-24-comprehensive-audit"
+contentProfile: asd-ste100
 tags:
   - core
   - lifecycle
-  - intro
+  - concepts
 ---
 
-import { Image } from "@lifecycle-docs/components";
 import Iframe from "@/components/iframe";
 
-Lifecycle is an **ephemeral** _(/əˈfem(ə)rəl/, lasting for a very short time)_ environment orchestrator that transforms your GitHub pull requests into fully functional development environments. It enables developers to test, validate, and collaborate on features without the hassle of managing infrastructure manually.
-
-> With **Lifecycle**, every pull request gets its own connected playground—ensuring that changes can be previewed, integrated, and verified before merging into its main branch.
-
-## A Developer’s Story
-
-Imagine working in an organization that develops multiple services. Managing and testing changes across these services can be challenging, especially when multiple developers are working on different features simultaneously.
-
-Meet **Nick Holiday 👨‍💻**, an engineer who needs to update a database schema and modify the corresponding API in a backend service. Additionally, his change requires frontend service updates to display the new data correctly.
-
-### Traditional Workflow Challenges
-
-- **Shared environments** – Nick deploys his backend service changes to a shared dev or staging environment, but another engineer is testing unrelated changes at the same time.
-- **Conflicting updates** – The frontend engineers working on the UI might face issues if their code depends on a stable backend service that keeps changing.
-- **Environment management** – Setting up and maintaining an isolated environment for testing requires significant effort.
-
-### Enter Lifecycle
-
-With Lifecycle, as soon as Nick opens a pull request, the system automatically:
-
-1. 🏗️ **Creates an isolated development environment** – This environment includes Nick’s updated backend service along with the necessary frontend services.
-2. 🚀 **Deploys the application** – Everything is set up exactly as it would be in production, ensuring a reliable test scenario.
-3. 🔗 **Generates a shareable URL** – Nick and his teammates can interact with the new features without setting up anything locally.
-4. 🧹 **Cleans up automatically** – Once the PR is merged or closed, Lifecycle removes the environment, keeping things tidy.
-
-## Watch a Quick Demo
-
-<Iframe src="https://www.youtube.com/embed/ld9rWBPU3R8?si=ff-_y0lXTNOmRxdT" />
-
-## How It Works
-
-<Image src="/docs/simple-workflow.png" width={1941} height={1613} />
-
-## Why Use Lifecycle?
-
-- **Faster Feedback Loops** - Get instant previews of your changes without waiting for staging deployments.
-- **Isolation** - Each PR runs in its own sandbox, preventing conflicts.
-- **Seamless Collaboration** - Share URLs with stakeholders, designers, or QA engineers.
-- **Automatic Cleanup** - No more stale test environments; Lifecycle manages cleanup for you.
-- **Works with Your Stack** - Supports containerized applications and integrates with Kubernetes.
+Lifecycle creates isolated application Environments on Kubernetes. It selects
+the Services that a change requires. It builds the changed sources and
+deploys the result with its dependencies. Lifecycle publishes useful URLs and
+cleans up Environments that are no longer necessary.
+
+Pull requests are the usual trigger, but Lifecycle can also create
+Environments without a pull request through an enabled UI or API workflow.
+Long-lived static Environments can supply fallback Services.
+
+## The core flow
+
+1. A repository contains a correct Lifecycle configuration.
+2. A pull request, UI action, or API request asks for an Environment.
+3. Lifecycle resolves necessary and optional Services and their source
+   revisions.
+4. Lifecycle builds the changed sources and deploys the Kubernetes workloads.
+5. Users examine status, logs, URLs, and actions in GitHub, the UI, CLI, API, or
+   MCP.
+6. When the owning workflow ends or its lease expires, Lifecycle tears down
+   ephemeral resources.
+
+An **Environment** is the user-facing unit. Some API and CLI interfaces use the
+historical term **build** or the field name `uuid`. Those names usually refer to
+the same Environment or its human-readable ID.
+
+## What Lifecycle helps with
+
+- **Fast feedback:** Test changes before merging.
+- **Isolation:** Prevent unrelated changes from colliding in a shared staging
+  Environment.
+- **Connected Services:** Use changed Services with configured
+  dependencies and fallbacks.
+- **Shareable results:** Supply developers, QA, and stakeholders with stable links
+  for the lifetime of the Environment.
+- **Controlled cleanup:** Tear down pull-request Environments automatically
+  and expire leased API Environments.
+- **Agent workflows:** When enabled, let users and approved AI tools examine
+  the same Lifecycle state through governed interfaces.
+
+## View the demo
+
+<Iframe
+  src="https://www.youtube.com/embed/ld9rWBPU3R8?si=ff-_y0lXTNOmRxdT"
+  title="Lifecycle product overview video"
+/>
+
+## Select your next step
+
+- **Application developer:** [Onboard a repository](/docs/getting-started/onboard-repository)
+  and [create your first Environment](/docs/getting-started/create-environment).
+- **Evaluator or platform operator:** [Select an installation
+  path](/docs/setup/install-lifecycle). Use the [starter infrastructure
+  prerequisites](/docs/setup/prerequisites) only for the OpenTofu evaluation
+  path.
+- **API user:** [Create a personal API key](/docs/api-authentication/api-keys)
+  and [create a PR-less Environment](/docs/features/api-environments).
+- **Agent user or administrator:** Start with
+  [Agent Sessions](/docs/features/agent-sessions) and
+  [Agent administration](/docs/features/agent-administration).
diff --git a/src/theme.config.tsx b/src/theme.config.tsx
index 8f91ddb0..efead9bf 100644
--- a/src/theme.config.tsx
+++ b/src/theme.config.tsx
@@ -68,11 +68,24 @@ const updateProjectLink = (frontMatter: {
 };
 
 export const HeadMeta = () => {
+  const { frontMatter, title: pageTitle } = useConfig();
+  const title =
+    typeof pageTitle === "string" && pageTitle.trim()
+      ? `${pageTitle} – Lifecycle`
+      : "Lifecycle documentation";
+  const description =
+    typeof frontMatter?.description === "string" &&
+    frontMatter.description.trim()
+      ? frontMatter.description
+      : "Documentation for Lifecycle";
+
   return (
     <>
+      <title>{title}</title>
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-      <meta property="og:title" content="Lifecycle" />
-      <meta property="og:description" content="Documentation for Lifecycle" />
+      <meta name="description" content={description} />
+      <meta property="og:title" content={title} />
+      <meta property="og:description" content={description} />
       <link rel="icon" type="image/png" href="/logo.png" />
     </>
   );
@@ -82,6 +95,7 @@ export const MainTemplate = ({ children }: MainProps) => {
   const config = useConfig();
   const frontMatter = config.frontMatter;
   const layout = config.normalizePagesResult?.activeThemeContext?.layout;
+
   if (layout !== "full") {
     return (
       <>
@@ -124,7 +138,7 @@ export const TocExtraContent = () => {
     frontMatter?.tags?.length > 0 && (
       <section>
         <Separator className="_my-8" />
-        <p className="_mb-4 _font-semibold _tracking-tight">Related Content</p>
+        <p className="_mb-4 _font-semibold _tracking-tight">Topics</p>
         <TagContent tags={frontMatter.tags} />
         <Separator className="_my-8" />
       </section>
@@ -141,7 +155,7 @@ export default {
   editLink: {
     text: "Edit this page",
   },
-  head: <HeadMeta />,
+  head: HeadMeta,
   logo,
   main: MainTemplate,
   navbar: {
diff --git a/tests/scripts/docsMetadata.test.ts b/tests/scripts/docsMetadata.test.ts
new file mode 100644
index 00000000..9e05e38e
--- /dev/null
+++ b/tests/scripts/docsMetadata.test.ts
@@ -0,0 +1,180 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  loadDocumentationMetadata,
+  resolvePageMetadata,
+  type DocumentationMetadata,
+} from "../../scripts/docsMetadata";
+
+const temporaryRoots = new Set<string>();
+
+function registry(supportStatuses: string[] = []): DocumentationMetadata {
+  return {
+    audiences: new Set(["application-developer", "platform-operator"]),
+    baselines: new Map([
+      [
+        "source-a",
+        {
+          verifiedOn: "2026-07-01",
+          sources: {
+            lifecycle: "9956d3e70a89c81a23c6502d03e237750c3886a4",
+          },
+        },
+      ],
+    ]),
+    maintenance: {
+      owner: "Lifecycle documentation maintainers",
+      reviewTrigger: "owning-contract-change",
+    },
+    supportStatuses: new Set(supportStatuses),
+  };
+}
+
+function page(overrides: Record<string, unknown> = {}) {
+  return {
+    audience: ["application-developer"],
+    lastVerified: "2026-07-24",
+    verificationBaseline: "source-a",
+    ...overrides,
+  };
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...temporaryRoots].map((root) =>
+      fs.promises.rm(root, { force: true, recursive: true }),
+    ),
+  );
+  temporaryRoots.clear();
+});
+
+describe("page documentation metadata", () => {
+  test("accepts later reverification and an omitted support status", () => {
+    const result = resolvePageMetadata(page(), registry(), "2026-07-24");
+    expect(result.issues).toEqual([]);
+    expect(result.metadata?.supportStatus).toBeNull();
+  });
+
+  test("accepts only registered support status values", () => {
+    expect(
+      resolvePageMetadata(
+        page({ supportStatus: "labs" }),
+        registry(["labs"]),
+        "2026-07-24",
+      ).issues,
+    ).toEqual([]);
+    expect(
+      resolvePageMetadata(
+        page({ supportStatus: "stable" }),
+        registry(["labs"]),
+        "2026-07-24",
+      ).issues,
+    ).toContain(
+      "supportStatus must use an established value from documentation-metadata.json",
+    );
+  });
+
+  test("rejects unknown or duplicate audiences", () => {
+    expect(
+      resolvePageMetadata(
+        page({ audience: ["unknown"] }),
+        registry(),
+        "2026-07-24",
+      ).issues[0],
+    ).toContain("audience");
+    expect(
+      resolvePageMetadata(
+        page({
+          audience: ["application-developer", "application-developer"],
+        }),
+        registry(),
+        "2026-07-24",
+      ).issues[0],
+    ).toContain("unique");
+  });
+
+  test("rejects malformed, future, and pre-baseline dates", () => {
+    expect(
+      resolvePageMetadata(
+        page({ lastVerified: "24 July 2026" }),
+        registry(),
+        "2026-07-24",
+      ).issues,
+    ).toContain("frontmatter requires lastVerified in YYYY-MM-DD format");
+    expect(
+      resolvePageMetadata(
+        page({ lastVerified: "2026-07-25" }),
+        registry(),
+        "2026-07-24",
+      ).issues,
+    ).toContain("lastVerified cannot be in the future");
+    expect(
+      resolvePageMetadata(
+        page({ lastVerified: "2026-06-30" }),
+        registry(),
+        "2026-07-24",
+      ).issues[0],
+    ).toContain("cannot predate verification baseline");
+  });
+
+  test("rejects an unknown verification baseline", () => {
+    expect(
+      resolvePageMetadata(
+        page({ verificationBaseline: "missing" }),
+        registry(),
+        "2026-07-24",
+      ).issues,
+    ).toContain(
+      "frontmatter requires a verificationBaseline defined in documentation-metadata.json",
+    );
+  });
+});
+
+describe("documentation metadata registry", () => {
+  test("rejects malformed source revisions", async () => {
+    const root = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "lifecycle-docs-metadata-"),
+    );
+    temporaryRoots.add(root);
+    await fs.promises.writeFile(
+      path.join(root, "documentation-metadata.json"),
+      JSON.stringify({
+        schemaVersion: 1,
+        maintenance: {
+          owner: "Lifecycle documentation maintainers",
+          reviewTrigger: "owning-contract-change",
+        },
+        audiences: ["application-developer"],
+        supportStatuses: [],
+        verificationBaselines: {
+          source: {
+            verifiedOn: "2026-07-24",
+            sources: { lifecycle: "short-sha" },
+          },
+        },
+      }),
+    );
+
+    await expect(loadDocumentationMetadata(root)).rejects.toThrow(
+      "one or more named full commit revisions",
+    );
+  });
+});
diff --git a/tests/scripts/generateLlms.test.ts b/tests/scripts/generateLlms.test.ts
new file mode 100644
index 00000000..e887aee9
--- /dev/null
+++ b/tests/scripts/generateLlms.test.ts
@@ -0,0 +1,301 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  collectPublicDocsPages,
+  generateLlms,
+} from "../../scripts/generateLlms";
+
+const temporaryRoots = new Set<string>();
+const repositoryRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../..",
+);
+
+async function temporaryRoot(): Promise<string> {
+  const root = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "lifecycle-docs-llms-"),
+  );
+  temporaryRoots.add(root);
+  await fs.promises.mkdir(path.join(root, "src/pages/docs"), {
+    recursive: true,
+  });
+  await write(root, "public/CNAME", "docs.example.test\n");
+  await write(
+    root,
+    "documentation-metadata.json",
+    JSON.stringify({
+      schemaVersion: 1,
+      maintenance: {
+        owner: "Lifecycle documentation maintainers",
+        reviewTrigger: "owning-contract-change",
+      },
+      audiences: ["application-developer"],
+      supportStatuses: [],
+      verificationBaselines: {
+        test: {
+          verifiedOn: "2026-07-24",
+          sources: {
+            lifecycle: "9956d3e70a89c81a23c6502d03e237750c3886a4",
+          },
+        },
+      },
+    }),
+  );
+  return root;
+}
+
+async function write(
+  root: string,
+  relative: string,
+  contents: string,
+): Promise<void> {
+  const file = path.join(root, relative);
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  await fs.promises.writeFile(file, contents);
+}
+
+function page(title: string, description?: string): string {
+  return `---
+title: ${title}
+${description === undefined ? "" : `description: ${description}\n`}audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: test
+---
+
+# ${title}
+`;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...temporaryRoots].map((root) =>
+      fs.promises.rm(root, { force: true, recursive: true }),
+    ),
+  );
+  temporaryRoots.clear();
+});
+
+describe("llms.txt generation", () => {
+  test("follows curated navigation order and excludes hidden pages", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/_meta.ts",
+      `export default {
+        index: { title: "Home", display: "hidden" },
+        overview: { title: "Lifecycle overview" },
+        guides: { title: "Guides" },
+        separator: { type: "separator" },
+        upstream: { title: "Upstream", href: "https://example.test" }
+      };`,
+    );
+    await write(
+      root,
+      "src/pages/docs/guides/_meta.ts",
+      `export default {
+        second: { title: "Second guide" },
+        first: { title: "First guide" },
+        private: { title: "Private guide", display: "hidden" }
+      };`,
+    );
+    await write(root, "src/pages/docs/index.mdx", page("Home", "Landing page"));
+    await write(
+      root,
+      "src/pages/docs/overview.mdx",
+      page("Overview", "Understand Lifecycle"),
+    );
+    await write(
+      root,
+      "src/pages/docs/guides/first.mdx",
+      page("First", "First description"),
+    );
+    await write(
+      root,
+      "src/pages/docs/guides/second.mdx",
+      page("Second", "Second description"),
+    );
+    await write(
+      root,
+      "src/pages/docs/guides/private.mdx",
+      page("Private", "Hidden description"),
+    );
+
+    const pages = await collectPublicDocsPages({ rootDir: root });
+    expect(pages.map((item) => item.route)).toEqual([
+      "/docs/overview",
+      "/docs/guides/second",
+      "/docs/guides/first",
+    ]);
+    expect(pages.map((item) => item.sectionTitle)).toEqual([
+      "Start here",
+      "Guides",
+      "Guides",
+    ]);
+
+    const output = await generateLlms({
+      rootDir: root,
+      publicOrigin: "https://docs.example.test/",
+    });
+    expect(output).toContain(
+      "- [Lifecycle overview](https://docs.example.test/docs/overview.md): Understand Lifecycle",
+    );
+    expect(output.indexOf("Second guide")).toBeLessThan(
+      output.indexOf("First guide"),
+    );
+    expect(output).not.toContain("Private guide");
+    expect(output).not.toContain("Upstream");
+  });
+
+  test("fails when a public page lacks required frontmatter", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/_meta.ts",
+      `export default { guide: { title: "Guide" } };`,
+    );
+    await write(root, "src/pages/docs/guide.mdx", page("Guide"));
+
+    await expect(collectPublicDocsPages({ rootDir: root })).rejects.toThrow(
+      "requires non-empty description frontmatter",
+    );
+  });
+
+  test("fails when navigation omits a local page", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/_meta.ts",
+      `export default { guide: { title: "Guide" } };`,
+    );
+    await write(root, "src/pages/docs/guide.mdx", page("Guide", "A guide"));
+    await write(
+      root,
+      "src/pages/docs/orphan.mdx",
+      page("Orphan", "Not in navigation"),
+    );
+
+    await expect(collectPublicDocsPages({ rootDir: root })).rejects.toThrow(
+      "omits public target(s): orphan",
+    );
+  });
+
+  test("fails when navigation points to a missing target", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/_meta.ts",
+      `export default { missing: { title: "Missing" } };`,
+    );
+
+    await expect(collectPublicDocsPages({ rootDir: root })).rejects.toThrow(
+      'declares missing target "missing"',
+    );
+  });
+
+  test("rejects the retired /docs/cm navigation target", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/_meta.ts",
+      `export default { cm: { title: "Retired docs" } };`,
+    );
+    await write(
+      root,
+      "src/pages/docs/cm/_meta.ts",
+      `export default { guide: { title: "Guide" } };`,
+    );
+    await write(
+      root,
+      "src/pages/docs/cm/guide.mdx",
+      page("Guide", "Retired guide"),
+    );
+
+    await expect(collectPublicDocsPages({ rootDir: root })).rejects.toThrow(
+      "declares the retired /docs/cm target",
+    );
+  });
+
+  test("fails when a public documentation directory lacks navigation metadata", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/_meta.ts",
+      `export default { guides: { title: "Guides" } };`,
+    );
+    await write(
+      root,
+      "src/pages/docs/guides/guide.mdx",
+      page("Guide", "A nested guide"),
+    );
+
+    await expect(collectPublicDocsPages({ rootDir: root })).rejects.toThrow(
+      "src/pages/docs/guides/_meta.ts is required",
+    );
+  });
+
+  test("covers the repository's key end-user journeys", async () => {
+    const pages = await collectPublicDocsPages({ rootDir: repositoryRoot });
+    const routes = pages.map((item) => item.route);
+    const requiredRoutes = [
+      "/docs/what-is-lifecycle",
+      "/docs/setup/prerequisites",
+      "/docs/getting-started/onboard-repository",
+      "/docs/getting-started/create-environment",
+      "/docs/features/lifecycle-ui",
+      "/docs/features/cli",
+      "/docs/features/cli-telemetry",
+      "/docs/features/api-environments",
+      "/docs/features/sites",
+      "/docs/features/agent-sessions",
+      "/docs/features/agent-administration",
+      "/docs/features/workspace-backends",
+      "/docs/features/ai-agent-configuration",
+      "/docs/features/mcp-server",
+      "/docs/api/overview",
+      "/docs/api-authentication/overview",
+      "/docs/api-authentication/api-keys",
+      "/docs/operations/architecture",
+      "/docs/operations/configuration",
+      "/docs/operations/day-two",
+      "/docs/operations/monitoring",
+      "/docs/operations/security",
+      "/docs/reference/statuses",
+      "/docs/releases",
+      "/docs/releases/compatibility",
+      "/docs/schema/overview",
+      "/docs/schema/configuration",
+      "/docs/schema/environment",
+      "/docs/schema/external-http",
+      "/docs/setup/install-lifecycle",
+      "/docs/troubleshooting/access-and-api",
+      "/docs/troubleshooting/build-issues",
+      "/docs/troubleshooting/deploy-issues",
+      "/docs/troubleshooting/github-app-webhooks",
+      "/docs/troubleshooting/stuck-environment",
+    ];
+
+    expect(new Set(routes).size).toBe(routes.length);
+    expect(routes.length).toBeGreaterThanOrEqual(65);
+    for (const route of requiredRoutes) expect(routes).toContain(route);
+  });
+});
diff --git a/tests/scripts/generateRawMarkdown.test.ts b/tests/scripts/generateRawMarkdown.test.ts
new file mode 100644
index 00000000..96582cd3
--- /dev/null
+++ b/tests/scripts/generateRawMarkdown.test.ts
@@ -0,0 +1,531 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  collectRawMarkdownPages,
+  docsRouteToHtmlOutputRelativePath,
+  generateRawMarkdown,
+  GENERATED_RAW_MARKDOWN_SENTINEL,
+  projectMdxToMarkdown,
+  rawMarkdownRouteForSource,
+  runRawMarkdownCli,
+  sourceRelativePathToDocsRoute,
+  sourceRelativePathToRawOutputRelativePath,
+  validateDocumentationSourcePaths,
+  validateExportedFileBijection,
+} from "../../scripts/generateRawMarkdown";
+
+const temporaryRoots = new Set<string>();
+
+async function temporaryRoot(): Promise<string> {
+  const root = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "lifecycle-docs-raw-markdown-"),
+  );
+  temporaryRoots.add(root);
+  await fs.promises.mkdir(path.join(root, "src/pages/docs"), {
+    recursive: true,
+  });
+  return root;
+}
+
+async function write(
+  root: string,
+  relative: string,
+  contents: string,
+): Promise<void> {
+  const file = path.join(root, relative);
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  await fs.promises.writeFile(file, contents);
+}
+
+function page(title: string, body = "Body text."): string {
+  return `---
+title: ${title}
+description: Learn how to complete this task.
+---
+
+${body}
+`;
+}
+
+async function writePage(
+  root: string,
+  sourceRelativePath: string,
+  source = page("Documentation page"),
+): Promise<void> {
+  await write(root, `src/pages/docs/${sourceRelativePath}`, source);
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...temporaryRoots].map((root) =>
+      fs.promises.rm(root, { force: true, recursive: true }),
+    ),
+  );
+  temporaryRoots.clear();
+});
+
+describe("MDX to raw Markdown projection", () => {
+  test("converts the supported component vocabulary without losing technical text", () => {
+    const source = `---
+title: Raw Markdown example
+description: Show every supported projection.
+---
+
+import { Callout, Cards, Steps, Tabs } from "nextra/components";
+import { Image, Iframe } from "@lifecycle-docs/components";
+
+<Callout type="warning">
+  Keep <code>{"{{aws:path:key}}"}</code> literal.
+</Callout>
+
+<Steps>
+
+1. Preserve [the link](https://example.test) and \`inline_code\`.
+2. Keep the template \`{{{service_publicUrl}}}\`.
+
+</Steps>
+
+<Tabs items={["First option", "Second option"]}>
+
+<Tabs.Tab>
+
+| Name | Value |
+| --- | --- |
+| one | two |
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+\`\`\`mermaid filename="flow.mmd" {1}
+graph LR
+  A --> B
+\`\`\`
+
+</Tabs.Tab>
+
+</Tabs>
+
+<Cards>
+  <Cards.Card title="Read a guide" href="/docs/guide">
+    Description with ordinary text.
+  </Cards.Card>
+</Cards>
+
+<div className="grid">
+  <Image src="/docs/example.png" alt="Example state" width={100} height={50} />
+</div>
+
+<Iframe src="https://video.example.test/embed/1" title="Product video" />
+
+Line one.<br />Line two.
+
+![Existing image](/existing.png)
+
+\`\`\`yaml filename="lifecycle.yaml" {2-3}
+value: "{{template_value}}"
+literal: "{{{triple_template}}}"
+\`\`\`
+`;
+
+    const output = projectMdxToMarkdown(source, "src/pages/docs/example.mdx");
+
+    expect(output.startsWith(GENERATED_RAW_MARKDOWN_SENTINEL)).toBe(true);
+    expect(output).toContain("# Raw Markdown example");
+    expect(output).toContain("Show every supported projection.");
+    expect(output).toContain(
+      "> [!WARNING]\n> Keep `{{aws:path:key}}` literal.",
+    );
+    expect(output).toContain("1. Preserve [the link](https://example.test)");
+    expect(output).toContain("`{{{service_publicUrl}}}`");
+    expect(output).toContain("**First option**");
+    expect(output).toContain("| Name | Value |");
+    expect(output).toContain("**Second option**");
+    expect(output).toContain("**File:** `flow.mmd`");
+    expect(output).toContain("```mermaid\ngraph LR\n  A --> B\n```");
+    expect(output).toContain(
+      "- [Read a guide](/docs/guide) — Description with ordinary text.",
+    );
+    expect(output).toContain("![Example state](/docs/example.png)");
+    expect(output).toContain(
+      "[Product video](https://video.example.test/embed/1)",
+    );
+    expect(output).toContain("Line one.\\\nLine two.");
+    expect(output).toContain("![Existing image](/existing.png)");
+    expect(output).toContain("**File:** `lifecycle.yaml`");
+    expect(output).toContain('value: "{{template_value}}"');
+    expect(output).toContain('literal: "{{{triple_template}}}"');
+    expect(output).not.toContain("filename=");
+    expect(output).not.toContain("<Callout");
+    expect(output).not.toContain("<Tabs");
+    expect(output).not.toContain("<Cards");
+    expect(output).not.toContain("<Image");
+    expect(output).not.toContain("<Iframe");
+    expect(output).not.toContain("import {");
+    expect(output).not.toContain("description:");
+  });
+
+  test("preserves a bare CodeHike filename as adjacent prose", () => {
+    const output = projectMdxToMarkdown(
+      page(
+        "Bare filename",
+        `\`\`\`hcl secrets.auto.tfvars
+token = "redacted"
+\`\`\``,
+      ),
+      "src/pages/docs/example.mdx",
+    );
+    expect(output).toContain(
+      '**File:** `secrets.auto.tfvars`\n\n```hcl\ntoken = "redacted"\n```',
+    );
+  });
+
+  test("fails closed with file and node context for unsupported JSX", () => {
+    expect(() =>
+      projectMdxToMarkdown(
+        page("Unsupported", "<Accordion>Hidden details.</Accordion>"),
+        "src/pages/docs/unsupported.mdx",
+      ),
+    ).toThrow(
+      /src\/pages\/docs\/unsupported\.mdx:\d+:\d+: Unsupported (?:inline|flow) JSX element \[mdxJsx(?:Text|Flow)Element <Accordion>\]/,
+    );
+  });
+
+  test("rejects dynamic expressions and non-import module code", () => {
+    expect(() =>
+      projectMdxToMarkdown(
+        page("Dynamic", "The value is {dynamicValue}."),
+        "src/pages/docs/dynamic.mdx",
+      ),
+    ).toThrow("Standalone MDX expressions are not supported");
+
+    expect(() =>
+      projectMdxToMarkdown(
+        page("Export", "export const value = 1;"),
+        "src/pages/docs/export.mdx",
+      ),
+    ).toThrow("Only import declarations can be removed from raw Markdown");
+  });
+
+  test("accepts only the reviewed static Callout decorations used by the repository", () => {
+    const output = projectMdxToMarkdown(
+      page(
+        "Decorative Callouts",
+        `import { Info } from "lucide-react";
+
+<Callout type="error" emoji="⚠️">
+  Static warning decoration.
+</Callout>
+
+<Callout type="info" emoji={<Info />}>
+  Static JSX decoration.
+</Callout>
+
+<Callout icon={Info}>
+  Static icon reference.
+</Callout>`,
+      ),
+      "src/pages/docs/decorations.mdx",
+    );
+
+    expect(output).toContain("> [!CAUTION]\n> Static warning decoration.");
+    expect(output).toContain("> [!NOTE]\n> Static JSX decoration.");
+    expect(output).toContain("> [!NOTE]\n> Static icon reference.");
+  });
+
+  test("rejects Callout decorations that could carry discarded meaning or behavior", () => {
+    expect(() =>
+      projectMdxToMarkdown(
+        page(
+          "Meaningful emoji",
+          `<Callout emoji="Read this first">
+
+Important text.
+
+</Callout>`,
+        ),
+        "src/pages/docs/meaningful-emoji.mdx",
+      ),
+    ).toThrow('"emoji" must be a reviewed static decoration');
+
+    expect(() =>
+      projectMdxToMarkdown(
+        page(
+          "Dynamic icon",
+          `<Callout icon={selectIcon(state)}>
+
+Important text.
+
+</Callout>`,
+        ),
+        "src/pages/docs/dynamic-icon.mdx",
+      ),
+    ).toThrow('"icon" must be the reviewed static decoration');
+
+    expect(() =>
+      projectMdxToMarkdown(
+        page(
+          "Meaningful JSX",
+          `<Callout emoji={<Info label="Read this" />}>
+
+Important text.
+
+</Callout>`,
+        ),
+        "src/pages/docs/meaningful-jsx.mdx",
+      ),
+    ).toThrow('"emoji" must be a reviewed static decoration');
+  });
+});
+
+describe("raw Markdown routes", () => {
+  test("maps root, nested indexes, and leaf pages", () => {
+    expect(sourceRelativePathToDocsRoute("index.mdx")).toBe("/docs");
+    expect(sourceRelativePathToRawOutputRelativePath("index.mdx")).toBe(
+      "docs.md",
+    );
+    expect(sourceRelativePathToDocsRoute("guides/index.mdx")).toBe(
+      "/docs/guides",
+    );
+    expect(sourceRelativePathToRawOutputRelativePath("guides/index.mdx")).toBe(
+      "docs/guides.md",
+    );
+    expect(sourceRelativePathToRawOutputRelativePath("guides/task.mdx")).toBe(
+      "docs/guides/task.md",
+    );
+    expect(docsRouteToHtmlOutputRelativePath("/docs")).toBe("docs.html");
+    expect(docsRouteToHtmlOutputRelativePath("/docs/guides/task")).toBe(
+      "docs/guides/task.html",
+    );
+  });
+
+  test("validates one exported raw Markdown file for every HTML file", () => {
+    const routes = [
+      rawMarkdownRouteForSource("index.mdx"),
+      rawMarkdownRouteForSource("guides/index.mdx"),
+      rawMarkdownRouteForSource("guides/task.mdx"),
+    ];
+
+    expect(() => validateExportedFileBijection(routes)).not.toThrow();
+    expect(() =>
+      validateExportedFileBijection([
+        {
+          ...routes[1],
+          outputRelativePath: "docs/guides/index.md",
+        },
+      ]),
+    ).toThrow(
+      "maps to docs/guides.html, so its raw counterpart must be docs/guides.md",
+    );
+  });
+
+  test("rejects the retired /docs/cm source namespace", () => {
+    expect(
+      validateDocumentationSourcePaths(["index.mdx", "guides/task.mdx"]),
+    ).toBe(2);
+    expect(() =>
+      validateDocumentationSourcePaths(["index.mdx", "cm/guide.mdx"]),
+    ).toThrow(
+      "The retired /docs/cm route namespace cannot contain source pages: cm/guide.mdx",
+    );
+    expect(() => validateDocumentationSourcePaths(["cm.mdx"])).toThrow(
+      "The retired /docs/cm route namespace cannot contain source pages: cm.mdx",
+    );
+  });
+
+  test("collects every documentation route", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await writePage(root, "guides/task.mdx");
+
+    const { pages } = await collectRawMarkdownPages(root);
+
+    expect(pages).toHaveLength(2);
+    expect(pages.map((item) => item.route)).toEqual([
+      "/docs/guides/task",
+      "/docs",
+    ]);
+    expect(new Set(pages.map((item) => item.outputRelativePath)).size).toBe(2);
+  });
+
+  test("rejects index and leaf pages that reserve the same raw route", async () => {
+    const root = await temporaryRoot();
+    await write(root, "src/pages/docs/guide.mdx", page("Guide leaf"));
+    await write(root, "src/pages/docs/guide/index.mdx", page("Guide index"));
+
+    await expect(collectRawMarkdownPages(root)).rejects.toThrow(
+      "both map to /docs/guide",
+    );
+  });
+});
+
+describe("raw Markdown file generation", () => {
+  test("--check projects every page without requiring generated files", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await writePage(root, "guides/task.mdx");
+
+    const result = await generateRawMarkdown({ check: true, rootDir: root });
+
+    expect(result).toEqual({
+      outdatedCount: 0,
+      projectedCount: 2,
+      removedCount: 0,
+      staleCount: 0,
+      writtenCount: 0,
+    });
+    expect(await fs.promises.readdir(root)).not.toContain("public");
+  });
+
+  test("CLI check rejects outdated present files and accepts exact present files", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await generateRawMarkdown({ rootDir: root });
+
+    await expect(runRawMarkdownCli(["--check"], root)).resolves.toMatchObject({
+      outdatedCount: 0,
+      projectedCount: 1,
+    });
+
+    await write(
+      root,
+      "src/pages/docs/index.mdx",
+      page("Documentation page", "Updated body text."),
+    );
+    const result = await generateRawMarkdown({ check: true, rootDir: root });
+    expect(result.outdatedCount).toBe(1);
+    await expect(runRawMarkdownCli(["--check"], root)).rejects.toThrow(
+      "1 outdated generated raw Markdown file(s) differ from their MDX source",
+    );
+  });
+
+  test("writes exact .md routes and safely removes stale generated files", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await writePage(root, "guides/task.mdx");
+    await write(
+      root,
+      "public/docs/stale/old.md",
+      `${GENERATED_RAW_MARKDOWN_SENTINEL}\n\n# Old\n`,
+    );
+    await write(root, "public/manual.md", "# Maintained by a human\n");
+
+    const result = await generateRawMarkdown({ rootDir: root });
+
+    expect(result.writtenCount).toBe(2);
+    expect(result.removedCount).toBe(1);
+    expect(
+      await fs.promises.readFile(path.join(root, "public/docs.md"), "utf8"),
+    ).toContain("# Documentation page");
+    expect(
+      await fs.promises.readFile(
+        path.join(root, "public/docs/guides/task.md"),
+        "utf8",
+      ),
+    ).toContain("# Documentation page");
+    expect(
+      await fs.promises
+        .access(path.join(root, "public/docs/stale/old.md"))
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(false);
+    expect(
+      await fs.promises.readFile(path.join(root, "public/manual.md"), "utf8"),
+    ).toBe("# Maintained by a human\n");
+  });
+
+  test("refuses to overwrite a reserved non-generated .md file", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "guides/task.mdx");
+    await write(
+      root,
+      "public/docs/guides/task.md",
+      "# Maintained by a human\n",
+    );
+
+    await expect(generateRawMarkdown({ rootDir: root })).rejects.toThrow(
+      "Refusing to overwrite non-generated raw Markdown file: public/docs/guides/task.md",
+    );
+    expect(
+      await fs.promises.readFile(
+        path.join(root, "public/docs/guides/task.md"),
+        "utf8",
+      ),
+    ).toBe("# Maintained by a human\n");
+  });
+
+  test("refuses an unexpected non-generated file in the reserved namespace", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await write(root, "public/docs/orphan.md", "# Maintained by a human\n");
+
+    await expect(generateRawMarkdown({ rootDir: root })).rejects.toThrow(
+      "Refusing unmanaged file in the reserved raw Markdown namespace: public/docs/orphan.md",
+    );
+  });
+
+  test("CLI check reports stale generated raw files", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await write(
+      root,
+      "public/docs/stale.md",
+      `${GENERATED_RAW_MARKDOWN_SENTINEL}\n\n# Stale\n`,
+    );
+
+    await expect(runRawMarkdownCli(["--check"], root)).rejects.toThrow(
+      "1 stale generated raw Markdown file(s) remain",
+    );
+  });
+
+  test("removes generated files for the retired /docs/cm namespace", async () => {
+    const root = await temporaryRoot();
+    await writePage(root, "index.mdx");
+    await write(
+      root,
+      "public/docs/cm.md",
+      `${GENERATED_RAW_MARKDOWN_SENTINEL}\n\n# Retired\n`,
+    );
+    await write(
+      root,
+      "public/docs/cm/legacy.md",
+      `${GENERATED_RAW_MARKDOWN_SENTINEL}\n\n# Retired\n`,
+    );
+
+    const check = await generateRawMarkdown({ check: true, rootDir: root });
+    expect(check.staleCount).toBe(2);
+
+    const result = await generateRawMarkdown({ rootDir: root });
+    expect(result.removedCount).toBe(2);
+    expect(
+      await fs.promises
+        .access(path.join(root, "public/docs/cm.md"))
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(false);
+    expect(
+      await fs.promises
+        .access(path.join(root, "public/docs/cm/legacy.md"))
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(false);
+  });
+});
diff --git a/tests/scripts/validateContracts.test.ts b/tests/scripts/validateContracts.test.ts
new file mode 100644
index 00000000..2c62c74d
--- /dev/null
+++ b/tests/scripts/validateContracts.test.ts
@@ -0,0 +1,249 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  contractInputsFromEnvironment,
+  validateContracts,
+} from "../../scripts/validateContracts";
+
+const temporaryRoots = new Set<string>();
+
+async function temporaryRoot(): Promise<string> {
+  const root = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "lifecycle-docs-contract-test-"),
+  );
+  temporaryRoots.add(root);
+  await fs.promises.mkdir(path.join(root, "src/pages/docs"), {
+    recursive: true,
+  });
+  return root;
+}
+
+async function write(
+  root: string,
+  relative: string,
+  contents: string,
+): Promise<string> {
+  const file = path.join(root, relative);
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  await fs.promises.writeFile(file, contents);
+  return file;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...temporaryRoots].map((root) =>
+      fs.promises.rm(root, { force: true, recursive: true }),
+    ),
+  );
+  temporaryRoots.clear();
+});
+
+describe("portable contract inputs", () => {
+  test("rejects malformed command argv", () => {
+    expect(() =>
+      contractInputsFromEnvironment({
+        DOCS_SCHEMA_VALIDATOR_COMMAND: "node validator.js",
+      }),
+    ).toThrow("must be a JSON argv array");
+  });
+
+  test("require-all reports every unavailable contract", async () => {
+    const root = await temporaryRoot();
+    const result = await validateContracts({
+      rootDir: root,
+      inputs: {},
+      requireAll: true,
+    });
+    expect(result.issues).toHaveLength(3);
+    expect(result.checks.every((check) => check.status === "skip")).toBe(true);
+  });
+});
+
+describe("schema contract checks", () => {
+  test("reports the source page and line for a rejected named example", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guides/guide.mdx",
+      `# Guide
+
+\`\`\`yaml filename="lifecycle.yaml"
+invalid: true
+\`\`\`
+`,
+    );
+    const validator = await write(
+      root,
+      "validator.mjs",
+      `import fs from "node:fs";
+const content = fs.readFileSync(process.argv[2], "utf8");
+if (content.includes("invalid")) {
+  console.error("invalid example");
+  process.exit(1);
+}
+`,
+    );
+
+    const result = await validateContracts({
+      rootDir: root,
+      inputs: {
+        schemaValidatorCommand: [process.execPath, validator],
+      },
+    });
+    expect(result.issues).toEqual([
+      {
+        file: "src/pages/docs/guides/guide.mdx:3",
+        message: "canonical lifecycle.yaml validation failed: invalid example",
+      },
+    ]);
+    expect(result.checks.find((check) => check.name === "schema")?.status).toBe(
+      "fail",
+    );
+  });
+});
+
+describe("OpenAPI contract checks", () => {
+  test("accepts present operations and reports missing methods", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/api.mdx",
+      `Use GET /api/v2/environments/{uuid}.
+Do not claim DELETE /api/v2/environments/{uuid}.
+`,
+    );
+    const spec = await write(
+      root,
+      "openapi.json",
+      JSON.stringify({
+        openapi: "3.0.0",
+        paths: {
+          "/api/v2/environments/{environmentId}": {
+            get: {},
+          },
+        },
+      }),
+    );
+
+    const result = await validateContracts({
+      rootDir: root,
+      inputs: { openApiSpecPath: spec },
+    });
+    expect(result.issues).toEqual([
+      {
+        file: "src/pages/docs/api.mdx:2",
+        message:
+          "DELETE /api/v2/environments/{uuid}. is not present in the supplied OpenAPI contract",
+      },
+    ]);
+    expect(
+      result.checks.find((check) => check.name === "openapi")?.status,
+    ).toBe("fail");
+  });
+});
+
+describe("CLI contract checks", () => {
+  test("checks command paths and documented flags through help", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/cli.mdx",
+      `\`\`\`sh
+lfc builds list --mine
+lfc builds list --invented
+\`\`\`
+`,
+    );
+    const cli = await write(
+      root,
+      "lfc.mjs",
+      `const args = process.argv.slice(2);
+if (args.join(" ") === "--help") {
+  console.log("Commands:\\n  builds  manage builds");
+} else if (args.join(" ") === "builds --help") {
+  console.log("Commands:\\n  list  list builds");
+} else if (args.join(" ") === "builds list --help") {
+  console.log("Options:\\n  --mine  show my builds");
+} else {
+  process.exit(1);
+}
+`,
+    );
+
+    const result = await validateContracts({
+      rootDir: root,
+      inputs: { cliCommand: [process.execPath, cli] },
+    });
+    expect(result.issues).toEqual([
+      {
+        file: "src/pages/docs/cli.mdx:3",
+        message: "--invented is not present in help for lfc builds list",
+      },
+    ]);
+    expect(result.checks.find((check) => check.name === "cli")?.status).toBe(
+      "fail",
+    );
+  });
+
+  test("walks nested command help and rejects an invented leaf", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/cli.mdx",
+      `\`\`\`sh
+lfc builds env get <uuid> --json
+lfc builds env invented <uuid>
+\`\`\`
+`,
+    );
+    const cli = await write(
+      root,
+      "lfc.mjs",
+      `const command = process.argv.slice(2).join(" ");
+const help = {
+  "--help": "Options:\\n  --version  print version\\nCommands:\\n  builds  manage builds",
+  "builds --help": "Commands:\\n  env  manage environment variables",
+  "builds env --help": "Commands:\\n  get  read values\\n  set  write values\\n  unset  remove values",
+  "builds env get --help": "Options:\\n  --json  print JSON",
+};
+if (help[command]) {
+  console.log(help[command]);
+} else {
+  process.exit(1);
+}
+`,
+    );
+
+    const result = await validateContracts({
+      rootDir: root,
+      inputs: { cliCommand: [process.execPath, cli] },
+    });
+    expect(result.issues).toEqual([
+      {
+        file: "src/pages/docs/cli.mdx:3",
+        message: "CLI subcommand is unavailable: lfc builds env invented",
+      },
+    ]);
+    expect(result.checks.find((check) => check.name === "cli")?.status).toBe(
+      "fail",
+    );
+  });
+});
diff --git a/tests/scripts/validateDocs.test.ts b/tests/scripts/validateDocs.test.ts
new file mode 100644
index 00000000..d395271d
--- /dev/null
+++ b/tests/scripts/validateDocs.test.ts
@@ -0,0 +1,615 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  validateDocs,
+  validatePortableGuidance,
+  validateRawMarkdownDelivery,
+  validateScreenshots,
+} from "../../scripts/validateDocs";
+
+const temporaryRoots = new Set<string>();
+const catalogPath =
+  ".agents/skills/update-lifecycle-docs/references/screenshots.md";
+
+async function temporaryRoot(): Promise<string> {
+  const root = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "lifecycle-docs-validation-"),
+  );
+  temporaryRoots.add(root);
+  await write(
+    root,
+    "documentation-metadata.json",
+    JSON.stringify({
+      schemaVersion: 1,
+      maintenance: {
+        owner: "Lifecycle documentation maintainers",
+        reviewTrigger: "owning-contract-change",
+      },
+      audiences: ["application-developer"],
+      supportStatuses: ["labs"],
+      verificationBaselines: {
+        test: {
+          verifiedOn: "2026-07-24",
+          sources: {
+            lifecycle: "9956d3e70a89c81a23c6502d03e237750c3886a4",
+          },
+        },
+      },
+    }),
+  );
+  await write(
+    root,
+    "default.conf",
+    `server {
+  location = /docs/cm { return 404; }
+  location = /docs/cm.md { return 404; }
+  location ^~ /docs/cm/ { return 404; }
+  location ~ \\.md$ {
+    types {}
+    default_type "text/markdown; charset=utf-8";
+    try_files $uri =404;
+  }
+  location / {
+    try_files $uri.html $uri $uri/ /index.html;
+  }
+  error_page 404 /404.html;
+}
+`,
+  );
+  return root;
+}
+
+async function write(
+  root: string,
+  relative: string,
+  contents: string | Buffer,
+): Promise<void> {
+  const file = path.join(root, relative);
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  await fs.promises.writeFile(file, contents);
+}
+
+function page(contents = ""): string {
+  return `---
+title: Guide
+description: Complete the task safely
+audience:
+  - application-developer
+lastVerified: "2026-07-24"
+verificationBaseline: test
+---
+
+## Guide
+
+${contents}
+`;
+}
+
+function png(width: number, height: number): Buffer {
+  const buffer = Buffer.alloc(24);
+  Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]).copy(buffer);
+  buffer.writeUInt32BE(width, 16);
+  buffer.writeUInt32BE(height, 20);
+  return buffer;
+}
+
+function catalog(asset: string, status = "keep"): string {
+  return `| Asset | Docs page | User point | UI route/state | Fixture | Viewport/theme | UI revision | Last verified | Review |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| \`${asset}\` | \`/docs/guide\` | Find the control | Guide view | Neutral fixture | 1440×900 / light | \`abc123\` | 2026-07-24 | \`${status}\` |
+`;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...temporaryRoots].map((root) =>
+      fs.promises.rm(root, { force: true, recursive: true }),
+    ),
+  );
+  temporaryRoots.clear();
+});
+
+describe("documentation validation", () => {
+  test("accepts complete frontmatter, routes, media, and YAML", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(`[Return to this guide](/docs/guide#guide)
+
+\`\`\`yaml
+service:
+  name: api
+\`\`\``),
+    );
+
+    expect(await validateDocs({ rootDir: root })).toEqual([]);
+  });
+
+  test("reports missing metadata, broken links, invalid YAML, and placeholders", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      `---
+title: Guide
+---
+
+[Missing](/docs/missing.mdx)
+
+\`\`\`yaml
+service: [
+\`\`\`
+
+TODO
+`,
+    );
+
+    const messages = (await validateDocs({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain("frontmatter requires a non-empty description");
+    expect(
+      messages.some((message) => message.includes("not an .mdx path")),
+    ).toBe(true);
+    expect(messages.some((message) => message.includes("does not parse"))).toBe(
+      true,
+    );
+    expect(
+      messages.some((message) => message.includes("unresolved TODO")),
+    ).toBe(true);
+  });
+
+  test("reports broken local documentation fragments", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(`[Good section](#guide)
+
+[Missing section](/docs/guide#not-a-heading)`),
+    );
+
+    const messages = (await validateDocs({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      "internal link targets a missing docs fragment: /docs/guide#not-a-heading",
+    );
+    expect(messages).not.toContain(
+      "internal link targets a missing docs fragment: #guide",
+    );
+  });
+
+  test("reports contributor-specific local guidance", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "README.md",
+      "Run `next dev -p 3333`, then open http://localhost:3333 from /Users/example/work.",
+    );
+    await write(
+      root,
+      ".agents/skills/update-lifecycle-docs/references/ste100-review.md",
+      "Read the review copy from /home/example/private-review.",
+    );
+
+    const messages = (await validatePortableGuidance({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      "tracked guidance contains a fixed local development URL",
+    );
+    expect(messages).toContain(
+      "tracked guidance contains a contributor-specific macOS path",
+    );
+    expect(messages).toContain(
+      "tracked guidance contains a contributor-specific home path",
+    );
+    expect(messages).toContain(
+      "tracked guidance or scripts contain a fixed development port",
+    );
+  });
+
+  test("reports malformed frontmatter without aborting validation", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      `---
+title: [
+---
+
+# Guide
+`,
+    );
+
+    const messages = (await validateDocs({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(
+      messages.some((message) =>
+        message.startsWith("frontmatter does not parse"),
+      ),
+    ).toBe(true);
+  });
+
+  test("reports a second page-level heading outside code fences", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(`# Duplicate page title
+
+\`\`\`dockerfile
+# This is a comment, not a heading
+\`\`\``),
+    );
+
+    expect(
+      (await validateDocs({ rootDir: root })).map((issue) => issue.message),
+    ).toContain(
+      "page body headings must start at level 2 because frontmatter renders the page H1",
+    );
+  });
+
+  test("reports documentation-audit narration in end-user prose", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(`Current UI source places this feature behind a gate.
+
+Typed configuration writes clear the process-local cache. An older source
+comment incorrectly calls the interval hourly.
+
+The current implementation stores the setting in a database record. The
+periodic refresh code reads it later. This was verified against the source.
+
+The documentation baseline includes a maintainer-access source revision.
+This JSON documents the runtime shape, not a database-edit procedure.`),
+    );
+
+    const messages = (await validateDocs({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      "end-user prose must state supported behavior, not narrate source inspection",
+    );
+    expect(messages).toContain(
+      "end-user prose must not expose process cache implementation details",
+    );
+    expect(messages).toContain(
+      "end-user prose must state supported behavior, not narrate implementation evidence",
+    );
+    expect(messages).toContain(
+      "end-user prose must keep verification evidence in review notes",
+    );
+    expect(messages).toContain(
+      "end-user prose must describe supported configuration results, not refresh implementation",
+    );
+    expect(messages).toContain(
+      "end-user prose must not expose non-actionable implementation structures",
+    );
+    expect(messages).toContain(
+      "end-user prose must not narrate a discrepancy found during source review",
+    );
+    expect(messages).toContain(
+      "end-user prose must not expose documentation maintenance metadata",
+    );
+    expect(messages).toContain(
+      "end-user prose must not expose maintainer-only verification evidence",
+    );
+    expect(messages).toContain(
+      "end-user prose must explain the supported task, not how an internal value was documented",
+    );
+  });
+
+  test("ignores documentation-audit phrases in code examples", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(`Use this test fixture:
+
+\`\`\`text
+Current UI source
+process-local
+\`\`\``),
+    );
+
+    expect(await validateDocs({ rootDir: root })).toEqual([]);
+  });
+
+  test("accepts current source as an Environment input", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page("A redeploy reuses the current source and configuration."),
+    );
+
+    expect(await validateDocs({ rootDir: root })).toEqual([]);
+  });
+
+  test("requires UTF-8 Markdown delivery and a fail-closed missing route", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "default.conf",
+      `server {
+  location = /docs/cm { return 404; }
+  location = /docs/cm.md { return 404; }
+  location ^~ /docs/cm/ { return 404; }
+  location ~ \\.md$ {
+    default_type text/markdown;
+    try_files $uri $uri.html /index.html;
+  }
+  location / {
+    try_files $uri.html $uri $uri/ /index.html;
+  }
+  error_page 404 /404.html;
+}
+`,
+    );
+
+    expect(
+      (await validateRawMarkdownDelivery({ rootDir: root })).map(
+        (issue) => issue.message,
+      ),
+    ).toEqual([
+      "raw Markdown must clear inherited MIME mappings before setting its UTF-8 media type",
+      'raw Markdown must use Content-Type "text/markdown; charset=utf-8"',
+      "raw Markdown must return 404 for a missing file instead of the HTML fallback",
+    ]);
+  });
+
+  test("requires explicit 404 responses for the retired /docs/cm routes", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "default.conf",
+      `server {
+  location ~ \\.md$ {
+    types {}
+    default_type "text/markdown; charset=utf-8";
+    try_files $uri =404;
+  }
+  location / {
+    try_files $uri.html $uri $uri/ /index.html;
+  }
+  error_page 404 /404.html;
+}
+`,
+    );
+
+    expect(
+      (await validateRawMarkdownDelivery({ rootDir: root })).map(
+        (issue) => issue.message,
+      ),
+    ).toEqual(["retired /docs/cm routes must return 404"]);
+  });
+
+  test("requires the exported 404 page for missing routes", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "default.conf",
+      `server {
+  location = /docs/cm { return 404; }
+  location = /docs/cm.md { return 404; }
+  location ^~ /docs/cm/ { return 404; }
+  location ~ \\.md$ {
+    types {}
+    default_type "text/markdown; charset=utf-8";
+    try_files $uri =404;
+  }
+  location / {
+    try_files $uri.html $uri $uri/ /index.html;
+  }
+  error_page 404 /index.html;
+}
+`,
+    );
+
+    expect(
+      (await validateRawMarkdownDelivery({ rootDir: root })).map(
+        (issue) => issue.message,
+      ),
+    ).toEqual(["404 responses must use the exported 404 page"]);
+  });
+
+  test("prefers an exported HTML page over a same-name asset directory", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "default.conf",
+      `server {
+  location = /docs/cm { return 404; }
+  location = /docs/cm.md { return 404; }
+  location ^~ /docs/cm/ { return 404; }
+  location ~ \\.md$ {
+    types {}
+    default_type "text/markdown; charset=utf-8";
+    try_files $uri =404;
+  }
+  location / {
+    try_files $uri $uri.html /index.html;
+  }
+  error_page 404 /404.html;
+}
+`,
+    );
+
+    expect(
+      (await validateRawMarkdownDelivery({ rootDir: root })).map(
+        (issue) => issue.message,
+      ),
+    ).toEqual([
+      "HTML routes must prefer the exported .html file before a same-name asset directory",
+    ]);
+  });
+});
+
+describe("screenshot validation", () => {
+  const asset = "/docs/guide/control.png";
+
+  test("accepts a cataloged image with matching intrinsic dimensions", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(
+        `<Image src="${asset}" alt="The control in the guide" width={8} height={5} ratio={8 / 5} />`,
+      ),
+    );
+    await write(root, `public${asset}`, png(8, 5));
+    await write(root, catalogPath, catalog(asset));
+
+    expect(await validateScreenshots({ rootDir: root })).toEqual([]);
+  });
+
+  test("reports dimension drift and unresolved catalog review", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(
+        `<Image src="${asset}" alt="The control in the guide" width={9} height={5} ratio={9 / 5} />`,
+      ),
+    );
+    await write(root, `public${asset}`, png(8, 5));
+    await write(root, catalogPath, catalog(asset, "replace"));
+
+    const messages = (await validateScreenshots({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      `${asset} is marked replace and must be remediated`,
+    );
+    expect(messages).toContain(`${asset} declares 9x5 but is 8x5`);
+  });
+
+  test("reports referenced screenshots missing from the catalog", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(
+        `<Image src="${asset}" alt="The control in the guide" width={8} height={5} ratio={8 / 5} />`,
+      ),
+    );
+    await write(root, `public${asset}`, png(8, 5));
+    await write(
+      root,
+      catalogPath,
+      "| Asset | Docs page | Review |\n| --- | --- | --- |\n",
+    );
+
+    const messages = (await validateScreenshots({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      `${asset} is missing from the screenshot catalog`,
+    );
+  });
+
+  test("reports detectable local markers in tracked screenshot records", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(
+        `<Image src="${asset}" alt="The control in the guide" width={8} height={5} ratio={8 / 5} />`,
+      ),
+    );
+    await write(root, `public${asset}`, png(8, 5));
+    await write(
+      root,
+      catalogPath,
+      catalog(asset).replace(
+        "Neutral fixture",
+        "Fixture at http://localhost:3333",
+      ),
+    );
+
+    const messages = (await validateScreenshots({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      "screenshot catalog tracked guidance contains a fixed local development URL",
+    );
+  });
+
+  test("does not accept unresolved provenance or cleanup for a kept screenshot", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(
+        `<Image src="${asset}" alt="The control in the guide" width={8} height={5} ratio={8 / 5} />`,
+      ),
+    );
+    await write(root, `public${asset}`, png(8, 5));
+    await write(
+      root,
+      catalogPath,
+      catalog(asset).replace(
+        "Neutral fixture",
+        "Authorized fixture; cleanup pending",
+      ),
+    );
+
+    const messages = (await validateScreenshots({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      `${asset} is marked keep but has unresolved catalog field(s): fixture and cleanup`,
+    );
+  });
+
+  test("reports a catalog page that does not own the image reference", async () => {
+    const root = await temporaryRoot();
+    await write(
+      root,
+      "src/pages/docs/guide.mdx",
+      page(
+        `<Image src="${asset}" alt="The control in the guide" width={8} height={5} ratio={8 / 5} />`,
+      ),
+    );
+    await write(root, `public${asset}`, png(8, 5));
+    await write(
+      root,
+      catalogPath,
+      catalog(asset).replace(
+        " | `/docs/guide` | Find",
+        " | `/docs/other` | Find",
+      ),
+    );
+
+    const messages = (await validateScreenshots({ rootDir: root })).map(
+      (issue) => issue.message,
+    );
+    expect(messages).toContain(
+      `${asset} catalog docs page /docs/other does not match reference route(s): /docs/guide`,
+    );
+  });
+});
diff --git a/tests/scripts/validateSte100.test.ts b/tests/scripts/validateSte100.test.ts
new file mode 100644
index 00000000..73cf6309
--- /dev/null
+++ b/tests/scripts/validateSte100.test.ts
@@ -0,0 +1,439 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  ASD_STE100_RULE_IDS,
+  ste100WordCount,
+  validateSte100,
+  validateStyleBaseline,
+  writeStyleBaseline,
+} from "../../scripts/validateSte100";
+
+const roots = new Set<string>();
+
+async function root(): Promise<string> {
+  const value = await fs.promises.mkdtemp(
+    path.join(os.tmpdir(), "lifecycle-ste100-"),
+  );
+  roots.add(value);
+  return value;
+}
+
+async function write(
+  rootDir: string,
+  relative: string,
+  source: string,
+): Promise<void> {
+  const file = path.join(rootDir, relative);
+  await fs.promises.mkdir(path.dirname(file), { recursive: true });
+  await fs.promises.writeFile(file, source);
+}
+
+function page(profile: string, content: string): string {
+  return `---
+title: Deploy an Environment
+description: Deploy an Environment and verify its status.
+contentProfile: ${profile}
+---
+
+${content}
+`;
+}
+
+async function writeStyleSurfaceFixture(rootDir: string): Promise<void> {
+  await write(
+    rootDir,
+    "src/pages/docs/_meta.ts",
+    `export default {
+      index: { title: "Start", display: "hidden" }
+    };`,
+  );
+  await write(
+    rootDir,
+    "src/pages/_meta.ts",
+    `export default {
+      "*": { type: "page" },
+      index: { title: "Lifecycle home", display: "hidden" },
+      docs: { title: "Docs", type: "page" }
+    };`,
+  );
+  await write(
+    rootDir,
+    "src/theme.config.tsx",
+    `export default { search: { placeholder: "Search documentation" } };`,
+  );
+  await write(
+    rootDir,
+    "src/components/site-footer/index.tsx",
+    `export function SiteFooter() {
+      return <footer>Lifecycle documentation</footer>;
+    }`,
+  );
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...roots].map((value) =>
+      fs.promises.rm(value, { force: true, recursive: true }),
+    ),
+  );
+  roots.clear();
+});
+
+describe("STE100 validation", () => {
+  test("tracks all 53 Issue 9 writing-rule identifiers", async () => {
+    expect(ASD_STE100_RULE_IDS).toHaveLength(53);
+    expect(new Set(ASD_STE100_RULE_IDS).size).toBe(53);
+    const matrix = await fs.promises.readFile(
+      path.join(
+        process.cwd(),
+        ".agents/skills/update-lifecycle-docs/references/ste100-review.md",
+      ),
+      "utf8",
+    );
+    const rows = [...matrix.matchAll(/^\| (\d+\.\d+)\s+\|/gm)].map(
+      (match) => match[1],
+    );
+    expect(rows).toEqual(ASD_STE100_RULE_IDS);
+  });
+
+  test("uses Issue 9 word-count treatment for protected text", () => {
+    expect(ste100WordCount('Touch the "Service Overview" arrow.')).toBe(4);
+    expect(ste100WordCount("Remove the safety pin (10).")).toBe(5);
+    expect(ste100WordCount("Installation of a Business Class (B/C) Seat")).toBe(
+      7,
+    );
+    expect(ste100WordCount("The timeout is 10 minutes.")).toBe(4);
+    expect(ste100WordCount("Use the source-backed setup-infra page.")).toBe(5);
+  });
+
+  test("checks every documentation page in nested directories", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/deploy.mdx",
+      page(
+        "asd-ste100",
+        `## Deploy
+
+1. If the build is ready, select **Deploy**.
+
+Lifecycle shows the Environment status.`,
+      ),
+    );
+    await write(
+      rootDir,
+      "src/pages/docs/guides/verify.mdx",
+      page(
+        "wrong-profile",
+        `## Verify
+
+Check the Environment status.`,
+      ),
+    );
+
+    expect(await validateSte100({ rootDir })).toEqual([
+      {
+        file: "src/pages/docs/guides/verify.mdx",
+        line: 1,
+        message:
+          "documentation frontmatter requires contentProfile: asd-ste100",
+      },
+    ]);
+  });
+
+  test("rejects retired page-variant frontmatter", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/deploy.mdx",
+      `---
+title: Deploy an Environment
+description: Deploy an Environment and verify its status.
+contentProfile: asd-ste100
+docsVariant: legacy
+canonicalRoute: /docs/deploy
+---
+
+## Deploy
+
+Check the Environment status.
+`,
+    );
+
+    expect(
+      (await validateSte100({ rootDir })).map((issue) => issue.message),
+    ).toEqual([
+      "documentation frontmatter must not declare docsVariant or canonicalRoute",
+    ]);
+  });
+
+  test("reports objective sentence, punctuation, and procedure violations", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/deploy.mdx",
+      page(
+        "asd-ste100",
+        `## Deploy
+
+1. Select **Deploy** and then open the logs after the Environment is ready.
+
+This isn't valid; this descriptive sentence contains far too many separate words for the maximum sentence length that the controlled language permits in descriptive documentation text for Lifecycle users and administrators.`,
+      ),
+    );
+
+    const messages = (await validateSte100({ rootDir })).map(
+      (issue) => issue.message,
+    );
+    expect(
+      messages.some((message) => message.includes("condition first")),
+    ).toBe(true);
+    expect(
+      messages.some((message) => message.includes("one instruction")),
+    ).toBe(true);
+    expect(messages.some((message) => message.includes("semicolon"))).toBe(
+      true,
+    );
+    expect(messages.some((message) => message.includes("contraction"))).toBe(
+      true,
+    );
+    expect(messages.some((message) => message.includes("maximum is 25"))).toBe(
+      true,
+    );
+  });
+
+  test("rejects instructions in informational callouts", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/deploy.mdx",
+      page(
+        "asd-ste100",
+        `## Deploy
+
+<Callout type="info">
+  Use the deployment log to find the status.
+</Callout>
+
+<Callout type="warning">
+  Stop the deployment.
+</Callout>`,
+      ),
+    );
+
+    expect(
+      (await validateSte100({ rootDir })).map((issue) => issue.message),
+    ).toEqual(["STE100 note must give information, not an instruction"]);
+  });
+
+  test("checks literal image alt text and component titles", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/deploy.mdx",
+      page(
+        "asd-ste100",
+        `## Deploy
+
+<Image
+  src="/environment.png"
+  alt="This image description contains too many words because it repeats unnecessary information about the Environment page and all its visible controls for every application developer who reads it."
+/>
+
+<Cards.Card
+  title="This card title also contains far too many words for a clear descriptive sentence in the canonical Lifecycle documentation site navigation and repeats details that belong on the destination page."
+  href="/docs/next"
+>
+  Open the next guide.
+</Cards.Card>`,
+      ),
+    );
+
+    const issues = await validateSte100({ rootDir });
+    expect(
+      issues.filter((issue) => issue.message.includes("maximum is 25")),
+    ).toHaveLength(2);
+    expect(issues.every((issue) => issue.line > 1)).toBe(true);
+  });
+
+  test("checks navigation titles in every documentation directory", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/_meta.ts",
+      `export default {
+        guide: { title: "This isn't valid" }
+      };`,
+    );
+    await write(
+      rootDir,
+      "src/pages/docs/guides/_meta.ts",
+      `export default {
+        verify: { title: "This isn't valid either" }
+      };`,
+    );
+
+    expect(
+      (await validateSte100({ rootDir })).map((issue) => ({
+        file: issue.file,
+        message: issue.message,
+      })),
+    ).toEqual([
+      {
+        file: "src/pages/docs/_meta.ts (navigation title)",
+        message: "STE100 prose must not use a contraction: isn't",
+      },
+      {
+        file: "src/pages/docs/guides/_meta.ts (navigation title)",
+        message: "STE100 prose must not use a contraction: isn't",
+      },
+    ]);
+  });
+
+  test("tracks every reviewed page by route, profile, and content hash", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/index.mdx",
+      page("asd-ste100", "## Start\n\nUse the navigation."),
+    );
+    await writeStyleSurfaceFixture(rootDir);
+
+    await writeStyleBaseline({ rootDir });
+    expect(await validateStyleBaseline({ rootDir })).toEqual([]);
+    const baseline = JSON.parse(
+      await fs.promises.readFile(
+        path.join(rootDir, "documentation-style-baseline.json"),
+        "utf8",
+      ),
+    );
+    expect(baseline.schemaVersion).toBe(3);
+    expect(Object.keys(baseline.pages)).toEqual(["/docs"]);
+    expect(Object.keys(baseline.references).sort()).toEqual([
+      "canonical",
+      "canonicalRules",
+    ]);
+
+    baseline.references.extra = "legacy";
+    await write(
+      rootDir,
+      "documentation-style-baseline.json",
+      `${JSON.stringify(baseline, null, 2)}\n`,
+    );
+    expect(
+      (await validateStyleBaseline({ rootDir })).map((issue) => issue.message),
+    ).toEqual([
+      "style review baseline is missing or invalid; run the reviewed baseline update workflow",
+    ]);
+    delete baseline.references.extra;
+    await write(
+      rootDir,
+      "documentation-style-baseline.json",
+      `${JSON.stringify(baseline, null, 2)}\n`,
+    );
+
+    await write(
+      rootDir,
+      "src/pages/docs/index.mdx",
+      page("asd-ste100", "## Start\n\nUse the main navigation."),
+    );
+    expect(
+      (await validateStyleBaseline({ rootDir })).map((issue) => issue.message),
+    ).toContain(
+      "reviewed asd-ste100 content changed; complete its language-profile review and update documentation-style-baseline.json",
+    );
+  });
+
+  test("invalidates the baseline when maintained navigation copy changes", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/index.mdx",
+      page("asd-ste100", "## Start\n\nUse the navigation."),
+    );
+    await writeStyleSurfaceFixture(rootDir);
+    await writeStyleBaseline({ rootDir });
+
+    await write(
+      rootDir,
+      "src/pages/_meta.ts",
+      `export default {
+        "*": { type: "page" },
+        index: { title: "Lifecycle home", display: "hidden" },
+        docs: { title: "Documentation", type: "page" }
+      };`,
+    );
+
+    expect(
+      (await validateStyleBaseline({ rootDir })).map((issue) => issue.message),
+    ).toContain(
+      "reviewed asd-ste100 surface changed; complete its language-profile review and update documentation-style-baseline.json",
+    );
+  });
+
+  test("invalidates the baseline when visible theme copy changes", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/index.mdx",
+      page("asd-ste100", "## Start\n\nUse the navigation."),
+    );
+    await writeStyleSurfaceFixture(rootDir);
+    await writeStyleBaseline({ rootDir });
+
+    await write(
+      rootDir,
+      "src/theme.config.tsx",
+      `export default { search: { placeholder: "Find documentation" } };`,
+    );
+
+    expect(
+      (await validateStyleBaseline({ rootDir })).map((issue) => issue.message),
+    ).toContain(
+      "reviewed asd-ste100 surface changed; complete its language-profile review and update documentation-style-baseline.json",
+    );
+  });
+
+  test("invalidates the baseline when visible footer copy changes", async () => {
+    const rootDir = await root();
+    await write(
+      rootDir,
+      "src/pages/docs/index.mdx",
+      page("asd-ste100", "## Start\n\nUse the navigation."),
+    );
+    await writeStyleSurfaceFixture(rootDir);
+    await writeStyleBaseline({ rootDir });
+
+    await write(
+      rootDir,
+      "src/components/site-footer/index.tsx",
+      `export function SiteFooter() {
+        return <footer>Lifecycle user documentation</footer>;
+      }`,
+    );
+
+    expect(
+      (await validateStyleBaseline({ rootDir })).map((issue) => issue.message),
+    ).toContain(
+      "reviewed asd-ste100 surface changed; complete its language-profile review and update documentation-style-baseline.json",
+    );
+  });
+});