Human walkthrough of tutorial (after automated pass)

[rdwj]

Goal

A clean-room read-through by someone who hasn't seen the material, focused on flow and clarity rather than correctness. Particularly important for the prerequisites module and the five setup guides under docs/guides/, which were added in the April 2026 rebrand and have less student exposure than the original Module 1–9 sequence.

Acceptance criteria

• Reader can complete 00-prerequisites.md → Module 11 without external help
• Friction points captured as their own follow-up issues
• Each "obvious to the author" leap that tripped the reader is rewritten

Notes

Blocked by #28 — automated walkthrough must complete (and any doc bugs it finds must be fixed) before a human reader is brought in. Otherwise we burn the human's time on bugs the automated pass would have caught.

[rdwj]

Human Walkthrough Rubric

This rubric is for a clean-room read-through focused on flow and clarity, not correctness (the automated pass in #28 already covered that). Print it out or keep it open in a side window as you work through the tutorial. Check each item as you go; file friction points as individual issues with the documentation label, linking back to #29.

---

How to use this rubric

1. Work through the tutorial from Module 0 to Module 11, in order, as if you were a new student.
2. For each module, evaluate the checklist items below. You don't need to write an essay -- a checkmark means "this was fine," and an unchecked box means "file an issue."
3. When you hit friction, file a GitHub issue immediately (don't batch them). Use the title format: docs: Module N — <short description of friction>. Add the documentation label and mention #29 in the body.
4. After completing all modules, evaluate the cross-cutting questions at the end.

What counts as friction: anything that made you stop, re-read, Google something, or wonder "am I doing this right?" -- even if you eventually figured it out. The goal is zero external help needed.

---

Setup Guides

These guides are referenced from Module 0 and other modules. You'll encounter them as you work through prerequisites. Evaluate each one when you first hit it.

Choosing a Cluster (guides/cluster-options.md)

• Can you determine which cluster option to use based on what you have available, without prior OpenShift experience?
• Is the Path A / Path B distinction clear at this point, and do you understand the tradeoff (GPU vs external model)?
• Are the cost and time-to-ready estimates realistic enough to make a decision?
• If you pick Developer Sandbox or CRC (Path B), is it clear what you won't be able to do later in the tutorial?

Install OpenShift AI (guides/install-openshift-ai.md)

• Is it clear that Path B users can skip this entirely?
• Does the guide explain what OpenShift AI is before asking you to install it, or does it assume you already know?
• Are the operator channel choices (fast-3.x vs stable-3.x) explained well enough to pick one confidently?
• Is the DataScienceCluster step clear about which components to enable and which are optional?

Serve an LLM (guides/serve-an-llm.md)

• Is the relationship between InferenceService, ServingRuntime, and the model clear, or does it feel like three unexplained nouns?
• For Path B users, is it clear how to find the MODEL_ENDPOINT and MODEL_NAME values for their external provider?
• Is the gpt-oss-20b model choice explained (why this model, what's special about it), or does it feel arbitrary?
• If the model takes a long time to load, does the guide set expectations and give you a way to check progress?

Install CLI Tools (guides/install-cli-tools.md)

• Are all five tools listed upfront so you know the full scope before you start?
• Does the guide cover your OS? (macOS, Fedora/RHEL, Debian/Ubuntu)
• Is pipx explained, or does the guide assume you know what it is and why it's used instead of pip?
• After completing the guide, can you verify all five tools work with the verification commands?

Registry Setup (guides/registry-setup.md)

• Is it clear which path to pick (Quay vs internal registry), and when you'd choose one over the other?
• If you've never used a container registry before, does the guide provide enough context?
• Are the robot account / pull secret steps clear, or do they assume familiarity with registry authentication?

Install OGX (guides/install-ogx.md) — reached from Module 10

• Is the OGX/LlamaStack rebrand confusion handled clearly (you're told what names to actually type)?
• Is it clear that you don't need this until Module 10?
• Does the guide explain what OGX does before diving into installation steps?
• Are the VLLM_URL and VLLM_INFERENCE_MODEL values easy to derive from what you set up in "Serve an LLM"?

Configure Safety Shields (guides/configure-shields.md)

• Is the distinction between Path A (code-scanner) and Path B (Llama Guard) clear, and is Path A clearly sufficient for the tutorial?
• Is the warning about userConfig replacing (not merging) the ConfigMap prominent enough? Could a reader miss it?
• After completing the guide, do you have confidence that the shield is actually working?

Observability Backends (guides/observability-backends.md)

• Is it clear that this is only needed for Module 10's tracing walkthrough?
• For Path A (Jaeger all-in-one), is the scope clear -- this is for dev/tutorial, not production?
• After deploying, can you verify Jaeger is actually receiving data?

---

Core Modules

Module 0: Before You Begin (00-prerequisites.md)

• After reading the overview page (index.md) and this module, do you have a clear mental picture of the end-state system you're building?
• Is the Path A / Path B distinction clear, and do you know which one you're on?
• Are the five requirements presented in a logical order, or would you rearrange them?
• Does the "Quick verification" section at the bottom give you confidence that you're ready, or are there gaps (e.g., registry access isn't verified)?
• Is export CTX=$(oc config current-context) explained well enough? A reader unfamiliar with kubeconfig contexts may not understand why this matters.
• After completing this module and its linked setup guides, do you feel prepared or overwhelmed?

Module 1: Scaffold Your Agent (01-scaffold-agent.md)

• Is the output of fips-agents create agent explained, or are you staring at a list of files wondering which ones matter?
• Does the agent.yaml walkthrough cover the right amount of detail? Too much (you're bored) or too little (you're confused)?
• Is the two-plane tool system (agent_only vs llm_only) explained with enough context for someone who hasn't built an agent before?
• Is the step() method's role clear -- that it's called in a loop, not once?
• Does make install && make run-local work on the first try, or is there an unmentioned dependency (e.g., needing to set MODEL_ENDPOINT first)?
• Is the MemoryHub log line warning sufficient, or would it cause alarm?
• Is the transition to Module 2 natural ("the scaffolded project runs but is still generic")?

Module 2: Configure and Deploy (02-configure-and-deploy.md)

• Is the Helm chart explanation sufficient for someone who has never used Helm? The "What is a Helm chart?" callout exists, but is it enough?
• Is Option A (BuildConfig) vs Option B (local build + push) guidance clear enough to pick one without agonizing?
• Is the oc new-project step explained (what a project/namespace is), or does it assume OpenShift knowledge?
• Is the helm install command with its many --set flags intimidating, and are the explanations of each flag sufficient?
• Does the "When things go wrong" section cover the problems a first-time reader is most likely to hit?
• Is the optional observability section clearly marked as optional, so readers don't feel they must do it now?
• Is the transition to Module 3 smooth?

Module 3: Build an MCP Server (03-build-mcp-server.md)

• Is the MCP protocol explained at the level needed here, or does it assume you've read the reference page?
• Is the "safe namespace" security concept in calc.py motivated clearly? (Why can't we just use sympify?)
• Is the amount of code shown appropriate? Too much (you're copying walls of code) or too little (you're guessing)?
• Are the curl commands for testing MCP over streamable-http explained well enough? The session-id dance is non-trivial for someone unfamiliar with the protocol.
• Is the deploy.sh deploy mechanism explained, given that Module 2 used Helm? The info box about deploy mechanisms helps, but does it come early enough?
• Would a reader know how to debug if ./deploy.sh calculus-mcp fails?

Module 4: Wire MCP to Agent (04-wire-mcp-to-agent.md)

• Is the "what changes and what doesn't" table effective at framing the scope of work?
• Is the Kubernetes service DNS pattern (<service>.<namespace>.svc.cluster.local) explained for readers who haven't memorized it?
• Is it clear that the agent class rename is cosmetic, not functional?
• Does the "architectural takeaway" section land, or does it feel preachy?
• After the curl test, does the reader understand the full request flow (user -> agent -> LLM -> MCP server -> SymPy -> back)?
• Is the transition from "testing with curl" to "we need a real UI" well-motivated?

Module 5: Gateway and UI (05-gateway-and-ui.md)

• Is the architecture diagram (Browser -> UI -> Gateway -> Agent -> MCP) clear at this point, or is it the first time you see the full picture?
• Is the "why not just expose the agent directly?" justification for the gateway convincing, or does it feel like over-engineering for a tutorial?
• Is the Go gateway / Go UI surprising (everything else is Python)? Is the language choice explained?
• Are the two make build-openshift + make deploy cycles (gateway, then UI) clear, or do you lose track of which directory you should be in?
• Is the route timeout annotation explained well enough? The "silent 504" warning is good, but would a reader know to do this proactively?
• After the end-to-end test, do you feel a sense of accomplishment (full stack working)?

Module 6: Code Execution Sandbox (06-code-sandbox.md)

• Is the security architecture (AST analysis, import hook, Landlock, resource limits) explained at the right level? Too shallow (you don't trust it) or too deep (you're lost in kernel details)?
• Is it clear why the sandbox runs as a sidecar (same pod) rather than a separate deployment?
• Is the Landlock/Linux caveat for macOS users clear (you can still dev locally, but one security layer is absent)?
• Is the code_executor tool simple enough that you could write a similar tool for a different backend?
• Does the security walkthrough (testing blocked imports, blocked patterns, resource exhaustion) feel hands-on and useful, or tedious?
• Is the oc port-forward step for direct sandbox testing explained well enough for someone who hasn't used it before?
• Is the "Composable capabilities" section effective at showing the bigger picture?

Module 7: Extend with AI (07-extend-with-ai.md)

• Is the slash-command workflow (/plan-tools -> /create-tools -> /exercise-tools -> /deploy-mcp) clear as a pipeline?
• Is the warning about running from calculus-helper/ (not calculus-agent/) prominent enough?
• Is it clear that you need Claude Code specifically for this module, and that it's different from the oc/helm CLI tools used elsewhere?
• Does the skill concept (progressive disclosure, loaded on demand) make sense, or does it blur with tools and prompts?
• Is "tools vs skills vs prompts" well-differentiated? Could you explain the difference to someone else after reading this?
• Is the "meta point" (using AI to build AI tools) insightful or cliche?
• If you don't have access to Claude Code, is there a manual fallback path, or are you stuck?

Module 8: Production Hardening (08-secrets-and-production.md)

• Is the pacing right? This module covers FIPS, litellm migration, secrets, JWT auth, security config, resource limits, scaling, monitoring, sessions, metrics, traces, OTEL export, and user feedback. Does it feel like a coherent module or a grab-bag?
• Is the FIPS section useful if your cluster isn't FIPS-enabled? Does it clearly explain that it's environment-dependent?
• Is the litellm supply chain warning appropriately scary without being preachy?
• Are the Secrets management steps clear for someone who has never created a Kubernetes Secret?
• Is the JWT auth section (MCP server authentication) self-contained, or does it assume OAuth/OIDC knowledge?
• Is the user feedback section a natural part of "production hardening" or does it feel tacked on?
• Does the module clearly distinguish "do this now" from "do this when you need it"?

Module 9: File Uploads (09-file-uploads.md)

• Is the pipeline diagram (size cap -> MIME sniff -> virus scan -> parse -> persist) easy to follow?
• Is the Docling dependency (+5 GB to the image) surprise managed well, or would you only discover this during a long build?
• Is the ClamAV sidecar setup realistic? The tip about needing an HTTP shim is important -- is it prominent enough?
• Is the lab exercise (PDF Q&A) achievable with the instructions given, or are there hidden steps?
• Is the "S3 backend not yet shipped" warning appropriate for a tutorial (pointing at future work), or is it confusing?
• Are the security verification steps (415 for wrong MIME, 413 for oversized) satisfying to run?

Module 10: Platform Mode and Guardrails (10-guardrails-and-observability.md)

• Is the before/after architecture diagram effective at showing what moves from agent-side to platform-side?
• Is the fipsagents>=0.21 version bump handled smoothly, or is it jarring after 9 modules on v0.11?
• Is the three-guide prerequisite sequence (Install OGX, Configure Shields, Observability Backends) manageable, or is it a wall of setup before you get to the interesting part?
• Is the MODEL_NAME change (RedHatAI/gpt-oss-20b -> vllm/RedHatAI/gpt-oss-20b) explained clearly enough that you wouldn't miss it?
• Is the guardrail trigger test satisfying? Can you see the shield fire and understand why?
• Is the streaming + late-firing output shields warning comprehensible, or too abstract without seeing it happen?
• Is the moderation vs guardrails distinction clear?
• Does "references vs inline URLs" (Part 3) feel like important knowledge or a tangent?

Module 11: Scaling with llm-d (11-scaling-with-llm-d.md)

• Is it clear from the start that this is a conceptual module with no hands-on steps?
• Is the prefill/decode split explained clearly enough for someone without ML inference background?
• Does the "when to reach for it" decision table help you understand whether llm-d is relevant to your use case?
• Is the OpenShift caveat (PermissionError on /.triton) useful or premature for a conceptual chapter?
• Does the module earn its place in the tutorial, or should it be a supplementary module?

Where to Go Next (where-next.md)

• Does this page feel like a natural conclusion, or does the tutorial just stop?
• Is the Kagenti section appropriately balanced -- informative without being a sales pitch?
• Are the "before you install" warnings about Kagenti (pre-1.0, service mesh conflicts, resource footprint) helpful?
• Does the "other pointers" list give you enough to explore without being overwhelming?

---

Cross-Cutting Questions

Evaluate these after completing all modules.

Difficulty curve

• Does the difficulty ramp smoothly from Module 0 to 11, or are there sharp jumps?
• Identify the single hardest module. Was the difficulty inherent to the topic, or caused by unclear writing?

Setup guide discoverability

• Were setup guides easy to find when modules referenced them?
• Did you ever get lost bouncing between a module and a setup guide and lose your place?
• Should any setup guide content be inlined into the module that references it?

Path A / Path B consistency

• If you followed Path B (external model), were Path B instructions present in every module that needed them?
• Were there any modules where Path B felt like an afterthought?

Supplementary module boundary

• Is the line between core modules (required, sequential) and supplementary modules (optional, standalone) clear?
• Could you explain to another student which supplementary modules exist and when to do them?

Error recovery

• When something went wrong, did the troubleshooting sections help you recover?
• Were there any failures that had no troubleshooting guidance at all?

Terminology consistency

• Were terms used consistently? (e.g., "MCP server" vs "tool server", "agent" vs "bot", "OGX" vs "LlamaStack")
• Were new terms defined before first use?

Time expectations

• Did any module take significantly longer than you expected?
• Would estimated completion times per module be helpful?

---

Reporting template

When filing a friction-point issue, use this structure:

Title: docs: Module N — [short description]
Labels: documentation
Body:
## Friction point
[What tripped you up — be specific about which sentence or step]

## Suggestion
[How you think it should be fixed]

## Context
Part of human walkthrough rubric (#29).