Keep tutorial source and explanations together

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

@@ -25,10 +25,12 @@ Do not write like a paper, specification, PR description, release note, test log
 
 ## Keep the source readable
 
-Include complete core source before the detailed walkthrough, exactly as implemented. Introduce each file with one sentence explaining its role. If the full source is long enough to interrupt the lesson, place each file in a collapsed `<details>` block, then reopen only the important excerpts in the walkthrough.
+Include complete core source exactly as implemented. Teach one component at a time: introduce its role, present its source inline, and immediately explain the important logic before moving on. Do not hide source in `<details>` and do not separate a long source dump from all of its explanation.
 
 Do not simplify code, insert ellipses, rewrite comments, or hand-edit synchronized source blocks. Link tests and build boilerplate unless they are part of the mechanism being taught.
 
+Link every other tutorial with its canonical absolute URL. Do not use relative cross-tutorial paths such as `../49-hid/README.md`, because those links break when the page is published outside the repository. Keep relative links only for files inside the current lesson.
+
 ## Keep scope honest
 
 Describe what the implementation actually provides. A bounded lab command is a bounded lab command. Do not inflate it into a daemon, controller, production scheduler, security product, or operational platform.

.agents/skills/bpf-tutorial-writing-style/references/prose-and-bilingual-checklist.md

@@ -43,11 +43,12 @@ Use it as a reader-focused editing guide, not as a reason to add review rounds.
 ## Code and evidence presentation
 
 - Present full core source exactly as it exists before excerpting it again for explanation. Mark complete-source blocks for the workflow Skill's synchronizer, then require its `--check` mode to pass against the complete source inventory. Never silently shorten functions, replace blocks with ellipses, translate comments, or “clean up” commands.
-- Introduce each complete file with its role in the kernel/user-space flow. After the file, select only the parts that need deeper explanation.
-- When full source spans several files or hundreds of lines, place each exact file in a collapsed `<details>` block. The code still appears before the walkthrough, but it does not become a wall that hides the article.
+- Teach one component at a time. Introduce the file's role, present its complete source inline, and immediately explain the parts that matter before starting the next component.
+- Never hide source in `<details>` and never place several complete files in one uninterrupted dump followed by a distant walkthrough. Long examples need stronger component boundaries and local explanations, not collapsed code.
 - Explain what advanced developers need to know: program type, attach point, context restrictions, helper or kfunc semantics, map ownership, state lifetime, concurrency, verifier constraints, event/control path, error handling, and cleanup.
 - Keep build and run commands copyable. Explain prerequisites before the command and interpret real output after it.
 - Label volatile fields and distinguish demonstrations, functional tests, and benchmarks.
+- Use canonical absolute URLs for every link to another tutorial. Reject `../<lesson>/README.md` and `../<lesson>/README.zh.md`; reserve relative links for files inside the current lesson.
 
 ## Natural Chinese
 

.agents/skills/bpf-tutorial-writing-style/references/repository-house-style.md

@@ -12,7 +12,7 @@ Open with a concrete situation the reader can picture. Name the small tool or ex
 
 Give enough background to explain why the hook or kernel subsystem matters. Then introduce the whole kernel/user-space path before individual functions. Keep returning to the same packet, event, device, or failure so adjacent sections feel causally connected.
 
-Present complete core source before the detailed walkthrough, as required by the advanced tutorial guidelines. A small program can stay inline. When several files or hundreds of source lines would bury the story, wrap each complete file in a collapsed `<details>` block. The code remains present and exact, while the reader can continue to the explanation.
+Present complete core source exactly as required by the advanced tutorial guidelines, but organize it by component. Introduce one file, show it inline, explain its important behavior, and only then move to the next file. Never hide source in `<details>` and never make readers cross several complete files before reaching the explanation.
 
 After the source, explain the BPF structure, attach point, state and ownership, relevant helpers or kfuncs, kernel interaction, user-space lifecycle, error handling, and cleanup. Spend words on advanced constraints and surprising behavior. Do not explain ordinary C syntax.
 
@@ -31,9 +31,9 @@ The first `53-egress-pacer` draft was technically accurate but still failed as a
 - called a fixed-duration lab demo a production or operational tool without matching CLI capabilities;
 - wrote Chinese by following English sentence order.
 
-The successful rewrite kept all four complete source files, commands, output, versions, failure paths, and limits. It replaced the invented production story with an honest lab scope, followed one skb through ownership and timing, collapsed the long source listings, reduced 12 main sections to 9, and moved KVM evidence into compilation and execution. Repeated `EEXIST` discussion fell from six mentions to two without losing the behavior.
+The rewrite kept all four complete source files, commands, output, versions, failure paths, and limits. It replaced the invented production story with an honest lab scope and followed one skb through ownership and timing. Reader review then exposed a structural problem: collecting the files before their explanations made the tutorial read like a design document. The corrected method places each complete file beside its component explanation, as tutorials 47 and 49 do.
 
-Reuse the method, not those exact counts. Shrink overloaded openings, give the reader one useful mental model, collapse long full-source listings, and make the walkthrough answer the questions raised by the scenario. Keep each technical fact, but place it once where the reader is ready for it.
+Reuse the corrected method, not exact section counts. Shrink overloaded openings, give the reader one useful mental model, and alternate complete component source with nearby explanation. Keep each technical fact, but place it once where the reader is ready for it.
 
 ## Preserve modern correctness
 

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

@@ -31,10 +31,12 @@ Do not turn the README into a validation transcript. Runtime provenance supports
 
 Follow the project-provided advanced tutorial guidelines through `$bpf-tutorial-writing-style`. Start with one concrete situation, explain the whole kernel/user-space path, include the complete core source exactly as implemented, then walk through the important mechanisms.
 
-When the complete source would dominate the page, keep it in the README but wrap each file in a collapsed `<details>` block. The source must remain searchable, copyable, byte-exact, and placed before the detailed walkthrough.
+Follow the selected precedent's component rhythm. Introduce one component, present its complete source inline, and explain its important logic before moving to the next component. Do not hide source in `<details>` or collect every file into one uninterrupted source dump. The source must remain searchable, copyable, and byte-exact.
 
 Explain advanced eBPF behavior, not ordinary C syntax. Keep build, run, expected output, requirements, cleanup, limitations, summary, and primary references. State once what the evidence proves and once where the example stops.
 
+Use canonical absolute URLs when linking to another tutorial. Never publish cross-tutorial links such as `../20-tc/README.md` or `../20-tc/README.zh.md`. Relative links are allowed only for files that belong to the current lesson, such as its `Makefile`, source files, and tests.
+
 ## 4. Write Chinese from the same facts
 
 Write `README.zh.md` from the implementation and the paragraph's purpose, not by translating English sentence by sentence. Keep the same section progression, code, commands, output, claims, limitations, and references. Allow natural Chinese sentence and paragraph boundaries.