Make tutorials 50–53 safer to operate

.agents/skills/bpf-tutorial-writing-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bpf-tutorial-writing-style
-description: Style checklist for English and Chinese bpf-developer-tutorial README files. Use while drafting or reviewing a tutorial so it reads like the established series, preserves technical detail, and presents complete source clearly.
+description: Style checklist for English and Chinese bpf-developer-tutorial README files. Use while drafting or reviewing a tutorial so it reads like the established series, preserves technical detail, and presents complete kernel source clearly.
 ---
 
 # BPF Tutorial Writing Style
@@ -32,8 +32,9 @@ For advanced tutorials (40+), follow this exact section order:
 
 5. **Code Implementation**:
    - First introduce the overall processing logic
-   - Show complete source code for each component (header, BPF program, user-space loader)
-   - After each complete code block, explain the key parts with paragraph style (not bullet lists)
+   - Show complete kernel/BPF source and the core headers needed to understand it
+   - Include the complete user-space loader when it is concise; when it is long, use focused excerpts that cover the normal user workflow and link to the lesson directory for the full file
+   - After each code block, explain the key parts with paragraph style (not bullet lists)
    - Focus on logic and advanced features, not basic syntax
 
 6. **Additional Concepts** (if needed): Deeper explanation of specific features, edge cases, or semantics
@@ -87,8 +88,9 @@ Use this Chinese paragraph only as a voice reference for connected rhythm, restr
 
 ## Teach from complete source
 
-- Introduce one component, show its complete source in an ordinary Markdown fence, then explain the important logic before moving to the next component.
-- Keep source byte-exact. Preserve comments and commands; use focused excerpts only after the complete block.
+- Introduce one component, show its complete kernel/BPF source in an ordinary Markdown fence, then explain the important logic before moving to the next component.
+- Show core headers completely. Include a complete user-space file when it remains readable; otherwise use focused excerpts that preserve the public control flow without making the tutorial a source dump.
+- Keep every complete source block byte-exact. Preserve comments and commands in excerpts, and link once to the lesson directory for omitted user-space details.
 - Use neither `<details>` nor HTML synchronization markers.
 - Link to the complete lesson once through its GitHub directory. Avoid an opening catalog of individual files.
 - Every Markdown link uses an absolute `https://github.com/...` target. Omit a link when no stable GitHub target exists.

.agents/skills/find-bpf-tutorial-topic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: find-bpf-tutorial-topic
-description: Audit bpf-developer-tutorial coverage, research current Linux BPF work and real open-source eBPF projects, maintain the repository tutorial candidate registry, and rank the next lesson by reader value, eBPF leverage, reproducibility, distinctness, teaching clarity, ecosystem evidence, maturity, and maintenance cost. Use when deciding what eBPF tutorial to write next, checking whether an idea is already covered, comparing feature-driven and scenario-driven topics, refreshing the topic roadmap, or asking which candidate has the highest value.
+description: Audit bpf-developer-tutorial coverage, research current Linux BPF work and real open-source eBPF projects, maintain the repository tutorial candidate registry, and rank the next lesson by reader value, operational usefulness, eBPF leverage, reproducibility, distinctness, teaching clarity, ecosystem evidence, maturity, and maintenance cost. Use when deciding what eBPF tutorial to write next, checking whether an idea is already covered or practically usable, comparing feature-driven and scenario-driven topics, refreshing the topic roadmap, or asking which candidate has the highest value.
 ---
 
 # Find the Next BPF Tutorial Topic
@@ -43,26 +43,42 @@ Convert each project feature into a small independent lesson. Teach the mechanis
 
 ## Define the runnable lesson before scoring
 
-For every serious candidate, write five short fields:
+For every serious candidate, write seven short fields:
 
 - the concrete question a reader can reproduce;
 - the event, packet, request, task, or workload followed end to end;
 - the BPF hook, map, helper, kfunc, or program type that makes the answer possible;
+- the exact command a reader would realistically run and the decision or action its output enables;
+- the natural lifecycle: single-pass action, bounded diagnostic, or persistent monitor, including how it stops and cleans up;
 - the deterministic fixture and observable success output;
 - the closest existing lesson and the new knowledge this candidate adds.
 
 Defer an idea when these fields remain vague. A helper name alone is not a tutorial topic.
 
+## Apply the practicality gate before scoring
+
+Walk through the proposed public workflow as an operator, separately from the deterministic test harness:
+
+- A naturally one-shot operation, such as an iterator scan or atomic state change, may run once and exit. An observability or enforcement monitor must attach before independent workloads, remain useful for its natural lifetime, and stop cleanly by signal, duration, or an explicit completion condition.
+- The fixture may be artificial, but the public command must not exist only to launch `/bin/true` or another toy trigger. A launch-scoped command is acceptable only when launch scoping is itself the lesson's real use case.
+- Require an explicit readiness signal before an independent workload starts; fixed sleeps do not prove that attachment or setup finished.
+- Define target scope and filters, concurrent-event or admission behavior, failure and drop visibility, cleanup after normal exit and signals, and what a reader does with the result.
+- For asynchronous work, define shutdown as: stop admission, wait for completed work rather than merely started callbacks, drain output, report stable health, then destroy resources.
+- Reject a design whose output merely proves that a helper ran. The output must answer the stated operational question or drive the stated action.
+
+Redesign or defer a candidate when the fixture is its only plausible user, when the lifecycle contradicts the scenario, or when safe cleanup and bounded resource behavior cannot be explained and tested.
+
 ## Score value
 
 Score from evidence, then subtract costs. Keep the breakdown in working notes and place the final score in `TUTORIAL_IDEAS.md`.
 
 | Dimension | Maximum | Question |
 |---|---:|---|
-| Reader problem | 25 | Does it answer a recurring, consequential question? |
-| eBPF leverage | 20 | Does eBPF provide visibility or control that ordinary tools cannot provide as cleanly? |
+| Reader problem | 20 | Does it answer a recurring, consequential question? |
+| Operational usefulness | 15 | Is the public command and lifecycle useful outside the test fixture? |
+| eBPF leverage | 15 | Does eBPF provide visibility or control that ordinary tools cannot provide as cleanly? |
 | Coverage gap | 15 | Does it add a distinct mechanism or scenario to this repository? |
-| Reproducibility | 15 | Can one bounded local or KVM fixture prove the result? |
+| Reproducibility | 10 | Can one bounded local or KVM fixture prove the result? |
 | Teaching clarity | 10 | Can the lesson follow one understandable path and show decisive output? |
 | Ecosystem evidence | 10 | Do maintained projects or upstream tests validate the use case? |
 | Maturity | 5 | Are the required kernel and userspace interfaces stable enough to maintain? |
@@ -76,6 +92,8 @@ Newness breaks close ties; it does not replace reader value. Favor a stable less
 A candidate can become `ready` only when:
 
 - it has a concrete reproducible problem and expected output;
+- its documented invocation and lifecycle match how a reader would use the tool outside the fixture;
+- its target scope, concurrency or admission bound, failure visibility, and cleanup path are explicit;
 - eBPF is central to the solution;
 - the repository does not already teach the same flow;
 - the example can fit one coherent tutorial;

.agents/skills/find-bpf-tutorial-topic/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Find BPF Tutorial Topic"
-  short_description: "Rank the next high-value eBPF tutorial topic"
-  default_prompt: "Use $find-bpf-tutorial-topic to audit coverage and recommend the next eBPF tutorial."
+  short_description: "Rank practical, high-value eBPF tutorial topics"
+  default_prompt: "Use $find-bpf-tutorial-topic to audit coverage, practical usability, and recommend the next eBPF tutorial."

.agents/skills/write-bpf-production-tutorial/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-bpf-production-tutorial
-description: Write or rewrite one bilingual bpf-developer-tutorial lesson with pinned Claude Opus 4.5, then verify the result against the implementation. Use when creating README.md and README.zh.md, preserving full source, testing the example, or preparing tutorial changes for review.
+description: Design, write, or rewrite one practical bilingual bpf-developer-tutorial lesson with pinned Claude Opus 4.5, then verify the public workflow and prose against the implementation. Use when creating README.md and README.zh.md, checking whether a tutorial tool has a realistic CLI and lifecycle, preserving complete kernel source, testing the example, or preparing tutorial changes for review.
 ---
 
 # Write a BPF Tutorial
@@ -17,18 +17,35 @@ Read these inputs before writing:
 - the current README pair when revising an existing lesson;
 - primary upstream sources for versions and feature semantics.
 
-Collect the facts the reader needs: the problem, why traditional approaches fail, the kernel/user-space flow, feature versions, requirements, commands, real output, cleanup, limits, and references. Keep every claim grounded in the code, tests, captured output, or a primary source. Preserve an existing draft before a from-scratch rewrite.
+Collect the facts the reader needs: the problem, why traditional approaches fail, the kernel/user-space flow, feature versions, requirements, intended public commands, real output, concurrency or admission behavior, cleanup, limits, and references. Keep every claim grounded in the code, tests, captured output, or a primary source. Preserve an existing draft before a from-scratch rewrite.
 
 Build and run the example when the environment supports it. Use `$test-bpf-tutorial-kvm` for kernel features that need the repository's KVM environment. Runtime details support the tutorial; local workspace paths, VM names, shared repositories, caches, prompts, and agent traces stay private.
 
-## 2. Structure requirements
+## 2. Pass the practical-design gate
+
+Validate the tool as an operator before writing prose. Keep its public workflow separate from the deterministic fixture:
+
+- State the operational question, the exact command a reader would run, the independent workload or target, the useful output, and how the tool stops.
+- Classify the lifecycle. A scan or atomic control action may be one-shot; a tracer or monitor must attach before the workload and remain active until a signal, duration, or real completion condition.
+- Do not turn a blocked toy child or `/bin/true` fixture into the public CLI merely because it removes a test race. Launch-scoped tracing is valid only when it is the intended real workflow.
+- Emit and test an explicit readiness signal before starting an independent workload. Do not use a fixed sleep as proof that setup or attachment completed.
+- Check target scope and filters, concurrent state, admission bounds, drop and failure counters, exit status, normal cleanup, signal cleanup, and destructive-action safety in proportion to the lesson.
+- For asynchronous work, stop admission first, wait for completed work rather than merely entered callbacks, drain output, report stable health, and only then destroy resources.
+- Execute the documented command as written. The test must prove the real lifecycle plus one relevant failure or cleanup path, not only that the BPF program loaded.
+- Describe the current public workflow directly. Do not narrate removed flags, old child-command modes, or other migration history unless backward compatibility is itself the lesson.
+- Keep repository tests out of the reader-facing tutorial path. Use them as private validation evidence, but teach the normal command, independent workload, useful tool output, and shutdown sequence.
+- Show only output emitted by the documented tool in public examples. Never include harness lines such as `TEST-*` or `PASS`, fixture setup, test assertions, or local test-infrastructure provenance.
+
+If the implementation only demonstrates a helper but is awkward or misleading as a tool, revise the implementation and test before asking the writer to explain it. Do not let polished prose overclaim an impractical design.
+
+## 3. Structure requirements
 
 For advanced tutorials (40+), follow this exact section order as defined in `$bpf-tutorial-writing-style`:
 
 1. **Title + Introduction**: Concrete problem scenario, link to source
 2. **Background / Why This Approach**: Explain traditional approaches and their limitations, then what eBPF enables
 3. **High-Level Mechanism**: How the feature works before showing code
-4. **Code Implementation**: Complete source blocks, then paragraph explanations
+4. **Code Implementation**: Complete kernel/BPF source and core headers, plus a complete user-space loader when concise or focused user-space excerpts when long, then paragraph explanations
 5. **Additional Concepts** (if needed)
 6. **Compilation and Execution**: AFTER code analysis, not before
 7. **Summary + Call to Action**
@@ -39,7 +56,7 @@ The "Background / Why" section is critical. It must explain:
 - Why each doesn't work well
 - What the eBPF approach enables
 
-## 3. Let Opus write
+## 4. Let Opus write
 
 Claude Opus writes all reader-facing tutorial prose. Use the exact model ID `claude-opus-4-5-20251101`. Stop if that model is unavailable instead of substituting another model.
 
@@ -55,22 +72,24 @@ Do not paste a second checklist, paragraph plan, fact inventory, or review rubri
 
 Run Claude from the repository root with the pinned model and permission to read the repository and write the two README files. Opus does not commit or push.
 
-## 4. Check the result
+## 5. Check the result
 
 Inspect both files and the diff instead of trusting the model's final message. Confirm that:
 
 - both languages are complete and tell the same technical story;
+- the documented command, target, lifecycle, signals, concurrency bounds, cleanup, and health output match the practical design gate;
 - the opening reads like a tutorial rather than an abstract or feature list;
 - there is a "Why" section explaining traditional approaches and their limitations;
 - the high-level mechanism is explained BEFORE code sections;
 - compilation/execution is AFTER code analysis;
-- every core source file appears once in a complete ordinary Markdown fence;
+- every kernel/BPF source and core header appears once in a complete ordinary Markdown fence; a concise user-space loader should also be complete, while a long loader may use focused excerpts that cover the normal public control flow;
 - code, commands, output, versions, requirements, cleanup, and limits agree with the repository;
+- sample output comes from the normal public workflow and contains no test-harness or migration/deprecation narration;
 - the opening source link points only to the lesson directory;
 - every published link is an absolute `https://github.com/...` URL;
 - no local infrastructure, prompt, model, agent, or trace detail appears in public text.
 
-Check source blocks with the bundled `sync-source-blocks.py`, then run `git diff --check`, the lesson build, its tests, and the relevant runtime test. Treat a functional run as a functional run rather than a benchmark.
+Check the required complete-source inventory with the bundled `sync-source-blocks.py`: always include kernel/BPF sources and core headers, and include user-space files only when the README presents them as complete. Then run `git diff --check`, the lesson build, its tests, the exact documented public command, and the relevant runtime test. Treat a functional run as a functional run rather than a benchmark.
 
 Read the finished pair once as an intermediate eBPF developer. If a concrete problem remains, give Opus a short defect list in the same session and let it revise the whole pair before returning. Keep prompts, responses, partial drafts, and failed runs; never delete real conversation or agent history.
 

.agents/skills/write-bpf-production-tutorial/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "BPF Tutorial Writer"
-  short_description: "Write and test clear bilingual eBPF lessons"
-  default_prompt: "Use $write-bpf-production-tutorial to turn this eBPF example into a clear, tested bilingual tutorial."
+  short_description: "Design and test practical bilingual eBPF lessons"
+  default_prompt: "Use $write-bpf-production-tutorial to turn this eBPF example into a practical, tested bilingual tutorial."

src/50-tcx/Makefile

@@ -44,9 +44,16 @@ endef
 $(call allow-override,CC,$(CROSS_COMPILE)cc)
 $(call allow-override,LD,$(CROSS_COMPILE)ld)
 
-.PHONY: all
+.PHONY: all test
 all: $(APPS)
 
+test: all
+	@if [ "$$(id -u)" -ne 0 ]; then \
+		echo "test requires root; run it inside the tutorial KVM" >&2; \
+		exit 1; \
+	fi
+	python3 tests/test_tcx_demo.py ./tcx_demo
+
 .PHONY: clean
 clean:
 	$(call msg,CLEAN)