QA Use Cases — Lab docs

Tool page: tools/docs-system.md. One Astro site, one image, served at docs.rhels.com — the showcase at /, this book at /agent-docs/. Source: rhels/lab-docs-source; the book is a content collection (site/src/content/docs/**/*.md), so adding a page is adding a file — there is no nav file to edit, and llms.txt + inventory.json are generated from the same sources at build time and cannot drift (source: docs-system.md).

Admin stories

DOC-A1 — Publish pipeline green, gates included [config/API]

• Persona: Platform admin (docs maintainer).
• Steps: on a docs change, watch build-deploy.yml: gitleaks on source → inventory regeneration → Astro build → gitleaks on the bundle → audit-bundle.py on the bundle.
• Expected: all gates pass; the audit is the sanitization boundary — it forbids IPs, tailnet/hostname-like suffixes, emails, key material, and token-shaped strings in anything served (source: docs-system.md, “The gates”).
• Assert: workflow conclusion == success; a seeded violation probe (a page containing a token-shaped string, in a throwaway branch) fails the audit — the negative control that proves the gate is a gate. CI itself runs on the mini-k8s runners (see CIR-A2 for the label contract this pipeline once broke).

DOC-A2 — The served image is the pinned image [CLI]

• Persona: Platform admin.
• Steps: read the image tag pinned in the GitOps tree (clusters/docker-desktop/lab-docs/lab-docs.yaml); read the running deployment’s image and the live site’s build marker.
• Expected: all three agree — pinned tag == running image == the marker the live page reports; the tooling-lab-docs app is Synced/Healthy at that revision. Fresh tag per build — never re-tagged (source: docs-system.md, “The publish loop”; PR #17/#18 publish records).
• Assert: gitops_tag == deployment_image_tag == live_marker_tag; Argo pair == Synced/Healthy.

DOC-A3 — A new page joins the book unaided [config/API]

• Persona: Docs maintainer.
• Steps: add a page with valid frontmatter (title, section, order, summary) on a test branch; build.
• Expected: the page appears in the book’s table of contents and in the generated llms.txt with no other file touched (source: docs-system.md Part B, “Add a page”).
• Assert: built output contains /agent-docs/<new-page>/ and an llms.txt entry whose title == the frontmatter title.

DOC-A4 — The public path stays off [config/API]

• Persona: Platform admin.
• Steps: check the would-be public Pages URL and the repo’s Pages setting.
• Expected: Pages disabled; the public URL returns 404. The book is private — served only inside the lab — and a public appearance is an incident, not a launch (source: docs-system.md — “Not published”; index.md).
• Assert: Pages API → 404/disabled; the public URL → 404.

User stories

DOC-U1 — The site loads, styled and complete [browser]

• Persona: The owner on a phone.
• Steps: open docs.rhels.com, then /agent-docs/.
• Expected: the showcase and the book render with the site’s real theme (a build with the wrong base path renders unstyled plain text — the named failure this story guards; the lab image is built with ASTRO_BASE=/) (source: astro config record; docs-system.md).
• Assert: book index returns 200; computed styles on the page show the theme applied (a sentinel element’s class-driven style is non-default); no asset request 404s.

DOC-U2 — Search finds the Service Directory [browser]

• Persona: A reader who needs a credential link.
• Steps: use the book’s search/navigation for “Service Directory”; open the page; follow one “Open in Vault ↗” link.
• Expected: the Service Directory is findable from the book’s own navigation (section “Start here”), and its Vault links behave per FDO-U2 (source: service-directory.md; qa/front-door.md).
• Assert: the page is listed in the built TOC under its section; its URL returns 200; it contains >= 1 Vault UI link (the directory currently carries 21).

DOC-U3 — A tool page answers from its own text [browser]

• Persona: An agent reader (the book’s primary audience).
• Steps: fetch a tool page and its llms.txt entry.
• Expected: the two agree — same title, same summary — because both generate from one source; a page whose llms.txt entry disagrees with its content is impossible by construction, and the story exists to keep it that way (source: docs-system.md — generated endpoints “can never drift from the pages”).
• Assert: llms.txt entry text == the page’s frontmatter summary for a sampled set of pages (sample >= 5, rotated per run).

Gaps

• TBD: no documented freshness expectation for the book as a whole (how stale may a tool page be after its tool changes?). The house rule — “a change to the flow updates this page in the same pass” (namespace-service.md) — is a discipline, not a measurable threshold; several pages in this QA section already cite post-migration drift the rule didn’t catch (see the observability, logging, runners, and ACS sets).
• Manual-only: editorial quality — whether a page reads well — is permanently manual, and deliberately out of the suites’ scope. Everything structural above is codable.