diff --git a/.github/skills/diataxis-docs-planner/SKILL.md b/.github/skills/diataxis-docs-planner/SKILL.md
index 55bad30..87f5828 100644
--- a/.github/skills/diataxis-docs-planner/SKILL.md
+++ b/.github/skills/diataxis-docs-planner/SKILL.md
@@ -5,7 +5,7 @@ description: Audit, plan, and structure Python package documentation following t
 
 # Diátaxis Documentation Planner
 
-Audit existing documentation and produce a structured plan following the Diátaxis framework - four quadrants of documentation that serve distinct user needs.
+Audit existing documentation and produce a structured plan following the Diátaxis framework — four quadrants of documentation that serve distinct user needs.
 
 ## The Four Quadrants
 
@@ -55,7 +55,7 @@ Read all files in `docs/` and classify each page by quadrant using the compass:
 For a well-documented Python package, expect at minimum:
 
 **Tutorials** (at least 1):
-- Getting Started / First Steps - install, import, first meaningful result
+- Getting Started / First Steps — install, import, first meaningful result
 
 **How-to Guides** (varies by feature count):
 - One per common task/problem users face
@@ -73,17 +73,18 @@ For a well-documented Python package, expect at minimum:
 **Explanation** (at least 1-2):
 - Architecture / design overview
 - Key concepts and terminology
-- Advantages of the chosen tooling and patterns (focus on benefits, not justification)
+- Design decisions / "why" docs
+- Comparison with alternatives (when useful)
 
 ### Step 4: Produce the Plan
 
 Output a structured documentation plan:
 
-1. **Gap analysis table** - what exists, what is missing, what needs reclassification
-2. **Recommended pages** - organized by quadrant, with title, purpose, priority (high/medium/low)
-3. **MkDocs nav structure** - ready to paste into `mkdocs.yml`
-4. **Implementation order** - tutorials and key how-tos first (highest user impact)
-5. **Skill recommendations** - name the specific writer skill for each page:
+1. **Gap analysis table** — what exists, what is missing, what needs reclassification
+2. **Recommended pages** — organized by quadrant, with title, purpose, priority (high/medium/low)
+3. **MkDocs nav structure** — ready to paste into `mkdocs.yml`
+4. **Implementation order** — tutorials and key how-tos first (highest user impact)
+5. **Skill recommendations** — name the specific writer skill for each page:
    - Tutorial pages → `diataxis-tutorial-writer`
    - How-to pages → `diataxis-howto-writer`
    - Reference pages → `diataxis-reference-writer`
@@ -91,36 +92,35 @@ Output a structured documentation plan:
 
 ## MkDocs Nav Patterns
 
-Typical Python package nav structure:
+Canonical Python package nav structure using `pages/` folder-per-quadrant:
 
 ```yaml
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md          # tutorial
+  - Tutorials:                                    # tutorial
+    - Getting Started: pages/tutorials/getting-started.md
   - How-to Guides:                                # how-to
-    - how-to/index.md
-    - How to Configure X: how-to/configure-x.md
-    - How to Integrate with Y: how-to/integrate-y.md
+    - How to Configure X: pages/how-to/configure-x.md
+    - How to Integrate with Y: pages/how-to/integrate-y.md
+    - Contributing: pages/how-to/contribute.md
   - Reference:                                    # reference
-    - reference/index.md
-    - API Reference: reference/api.md
-    - CLI Reference: reference/cli.md
-    - Configuration: reference/configuration.md
+    - API Reference: pages/reference/api.md
+    - CLI Reference: pages/reference/cli.md
+    - Configuration: pages/reference/configuration.md
   - Explanation:                                  # explanation
-    - explanation/index.md
-    - Architecture: explanation/architecture.md
-  - Contributing: contributing.md                 # how-to (for contributors)
+    - Architecture: pages/explanation/architecture.md
+    - Design Decisions: pages/explanation/design-decisions.md
 ```
 
 For complex packages with multiple user types or deployment targets, see [references/compass-and-patterns.md](references/compass-and-patterns.md) for multi-layer hierarchy and two-dimensional structure guidance.
 
 ## Common Anti-Patterns to Flag
 
-- **The mega-README**: Everything in one file - split by quadrant
-- **Tutorial-reference hybrid**: "Getting Started" that is actually an API walkthrough - separate
+- **The mega-README**: Everything in one file — split by quadrant
+- **Tutorial-reference hybrid**: "Getting Started" that is actually an API walkthrough — separate
 - **How-to disguised as explanation**: "Understanding X" that is really step-by-step instructions
 - **Missing tutorials entirely**: Only reference docs (common with auto-generated docs)
-- **Explanation scattered everywhere**: Bits of "why" sprinkled across how-to guides - consolidate
+- **Explanation scattered everywhere**: Bits of "why" sprinkled across how-to guides — consolidate
 
 ## Quality Signals
 
@@ -128,7 +128,7 @@ When auditing, also note:
 
 - **Functional quality**: accuracy, completeness, consistency, precision
 - **Deep quality**: flow, fit to user needs, anticipation of the user
-- Use the `mkdocs` skill for site configuration and build concerns - this skill focuses on content structure
+- Use the `mkdocs` skill for site configuration and build concerns — this skill focuses on content structure
 
 ## Output Format
 
@@ -152,16 +152,16 @@ When auditing, also note:
 
 ### Recommended Pages
 #### Tutorials (use `diataxis-tutorial-writer`)
-1. **Getting Started** - Install, first use, verify result [HIGH]
+1. **Getting Started** — Install, first use, verify result [HIGH]
 
 #### How-to Guides (use `diataxis-howto-writer`)
-1. **How to configure X** - ... [HIGH]
+1. **How to configure X** — ... [HIGH]
 
 #### Reference (use `diataxis-reference-writer`)
-1. **API Reference** - Full public API [HIGH]
+1. **API Reference** — Full public API [HIGH]
 
 #### Explanation (use `diataxis-explanation-writer`)
-1. **Architecture Overview** - ... [MEDIUM]
+1. **Architecture Overview** — ... [MEDIUM]
 
 ### Proposed MkDocs Nav
 nav:
diff --git a/.github/skills/diataxis-docs-planner/references/compass-and-patterns.md b/.github/skills/diataxis-docs-planner/references/compass-and-patterns.md
index b535a5f..45132ee 100644
--- a/.github/skills/diataxis-docs-planner/references/compass-and-patterns.md
+++ b/.github/skills/diataxis-docs-planner/references/compass-and-patterns.md
@@ -25,33 +25,33 @@ Adjacent quadrants share affinities that cause content to bleed across boundarie
 ## Python Package Page Patterns
 
 ### Typical Tutorial Pages
-- **Getting Started** - Install via pip/uv, import, call a function, verify output
-- **Your First <Feature>** - Build something small end-to-end
-- **Tutorial Series Part N** - Multi-part progressive learning path
+- **Getting Started** — Install via pip/uv, import, call a function, verify output
+- **Your First <Feature>** — Build something small end-to-end
+- **Tutorial Series Part N** — Multi-part progressive learning path
 
 ### Typical How-to Pages
 - **How to install** (with variations: pip, uv, conda, Docker, from source)
-- **How to configure <feature>** - Settings, env vars, config files
-- **How to integrate with <library>** - Using the package alongside another tool
-- **How to deploy** - Production setup, CI/CD integration
-- **How to extend / write plugins** - For extensible packages
-- **How to migrate from vX to vY** - Upgrade guides
-- **Troubleshooting** - Common problems and solutions
+- **How to configure <feature>** — Settings, env vars, config files
+- **How to integrate with <library>** — Using the package alongside another tool
+- **How to deploy** — Production setup, CI/CD integration
+- **How to extend / write plugins** — For extensible packages
+- **How to migrate from vX to vY** — Upgrade guides
+- **Troubleshooting** — Common problems and solutions
 
 ### Typical Reference Pages
-- **API Reference** - Auto-generated via mkdocstrings (modules → classes → methods)
-- **CLI Reference** - Commands, flags, options, exit codes
-- **Configuration Reference** - All settings with types, defaults, descriptions
-- **Error Reference** - Exception classes, error codes, meanings
-- **Changelog** - Version history (auto-generated via git-cliff or similar)
+- **API Reference** — Auto-generated via mkdocstrings (modules → classes → methods)
+- **CLI Reference** — Commands, flags, options, exit codes
+- **Configuration Reference** — All settings with types, defaults, descriptions
+- **Error Reference** — Exception classes, error codes, meanings
+- **Changelog** — Version history (auto-generated via git-cliff or similar)
 
 ### Typical Explanation Pages
-- **Architecture Overview** - How the package is structured and why
-- **Design Decisions** - Why certain approaches were chosen
-- **Key Concepts** - Domain terminology and mental models
-- **Comparison with Alternatives** - How this package differs from similar tools
-- **Performance Characteristics** - Complexity, benchmarks, trade-offs
-- **Security Model** - Trust boundaries, threat model (when applicable)
+- **Architecture Overview** — How the package is structured and why
+- **Design Decisions** — Why certain approaches were chosen
+- **Key Concepts** — Domain terminology and mental models
+- **Comparison with Alternatives** — How this package differs from similar tools
+- **Performance Characteristics** — Complexity, benchmarks, trade-offs
+- **Security Model** — Trust boundaries, threat model (when applicable)
 
 ## Complex Hierarchy Patterns
 
@@ -107,13 +107,13 @@ docs/
 ## Quality Checklist
 
 ### Functional Quality (measurable)
-- [ ] Accurate - code examples run, commands produce stated output
-- [ ] Complete - all public API surface documented
-- [ ] Consistent - terminology, formatting, style uniform across pages
-- [ ] Up-to-date - matches current version of the package
+- [ ] Accurate — code examples run, commands produce stated output
+- [ ] Complete — all public API surface documented
+- [ ] Consistent — terminology, formatting, style uniform across pages
+- [ ] Up-to-date — matches current version of the package
 
 ### Deep Quality (experiential)
-- [ ] Flow - reader progresses naturally without jarring transitions
-- [ ] Fit to needs - each page serves a clear user need
-- [ ] Anticipation - docs address questions before they arise
-- [ ] Minimal friction - no unnecessary detours or digressions
+- [ ] Flow — reader progresses naturally without jarring transitions
+- [ ] Fit to needs — each page serves a clear user need
+- [ ] Anticipation — docs address questions before they arise
+- [ ] Minimal friction — no unnecessary detours or digressions
diff --git a/.github/skills/diataxis-explanation-writer/SKILL.md b/.github/skills/diataxis-explanation-writer/SKILL.md
index 29b8de5..ed204f6 100644
--- a/.github/skills/diataxis-explanation-writer/SKILL.md
+++ b/.github/skills/diataxis-explanation-writer/SKILL.md
@@ -5,16 +5,20 @@ description: Generate understanding-oriented explanation documentation for Pytho
 
 # Diátaxis Explanation Writer
 
-Generate explanation documentation - understanding-oriented discussion that helps the reader make sense of a topic through reflection.
+Generate explanation documentation — understanding-oriented discussion that helps the reader make sense of a topic through reflection.
 
 Explanation is like reading **On Food and Cooking** by Harold McGee: it does not teach you to cook or give you recipes, but it places cooking in context of history, science, and society, deepening your understanding of the craft.
 
+## File Placement
+
+Place explanation pages in `docs/pages/explanation/`. Example: `docs/pages/explanation/concepts.md`.
+
 ## What Explanation Is
 
 - Discursive treatment of a subject that permits reflection
 - Deepens and broadens understanding by providing context, connections, and perspective
 - An answer to "Can you tell me about…?"
-- The only documentation you might read in the bath - away from the keyboard
+- The only documentation you might read in the bath — away from the keyboard
 
 Explanation serves the user's **study**, not their work. It is the counterpart to reference (which also contains propositional knowledge but serves work).
 
@@ -24,7 +28,7 @@ Explanation serves the user's **study**, not their work. It is the counterpart t
 
 - What concept, decision, or aspect of the package would benefit from deeper understanding?
 - Frame it as an implicit "About…": "About the plugin architecture", "About authentication design"
-- Choose a topic that can be meaningfully bounded - not the entire package, but a coherent area
+- Choose a topic that can be meaningfully bounded — not the entire package, but a coherent area
 
 ### Step 2: Gather Context
 
@@ -41,19 +45,19 @@ Structure as a discussion that circles around the topic from different angles. A
 
 ### Make connections
 
-Weave a web of understanding. Connect the topic to other things - even outside the immediate subject - if it helps comprehension.
+Weave a web of understanding. Connect the topic to other things — even outside the immediate subject — if it helps comprehension.
 
 "The event system works similarly to browser DOM events, where handlers are registered for specific event types and called when those events fire."
 
 ### Provide context
 
-Describe the advantages of the approach taken. Focus on what is gained - not on defending the choice or comparing with rejected alternatives. Draw implications. Mention specific examples.
+Explain **why** things are the way they are: design decisions, historical reasons, technical constraints. Draw implications. Mention specific examples.
 
-"SQLite requires zero configuration and ships with Python's standard library. For production workloads exceeding 100 concurrent writers, see the PostgreSQL backend."
+"We chose SQLite as the default backend because it requires zero configuration and ships with Python's standard library. For production workloads exceeding 100 concurrent writers, see the PostgreSQL backend."
 
 ### Talk about the subject
 
-Explanation guides are **about** a topic - they circle around it. The title should allow an implicit "about": "About user authentication", "About the caching strategy".
+Explanation guides are **about** a topic — they circle around it. The title should allow an implicit "about": "About user authentication", "About the caching strategy".
 
 Discuss:
 - The bigger picture
@@ -61,47 +65,62 @@ Discuss:
 - Choices, alternatives, possibilities
 - Why: reasons and justifications
 
-### State advantages, not justifications
+### Admit opinion and perspective
 
-Describe what the chosen approach provides. Do not include "Why X over Y" sections or comparison tables with alternatives. The reader wants to understand the benefits, not the decision-making process.
+All human creation is invested with opinion. Explanation can and must consider alternatives, counter-examples, and multiple approaches. It is a discussion, not a decree.
+
+"Some teams prefer a monolithic configuration file while others split settings by concern. Both approaches have trade-offs…"
 
 ### Keep explanation closely bounded
 
-One risk of explanation is absorbing other things. The urge to include instruction (how-to) or technical description (reference) is strong. Resist it - those have their own places. Allowing them in interferes with the explanation and removes them from where they belong.
+One risk of explanation is absorbing other things. The urge to include instruction (how-to) or technical description (reference) is strong. Resist it — those have their own places. Allowing them in interferes with the explanation and removes them from where they belong.
 
 ## Language Patterns
 
-- **"The reason for X is because historically, Y…"** - Explain origins
-- **"W is better than Z, because…"** - Offer judgements where appropriate
-- **"An X in this system is analogous to a Y in…"** - Provide context through analogy
-- **"Some users prefer W (because Z). This can be a good approach, but…"** - Weigh alternatives
-- **"X interacts with Y as follows:…"** - Unfold internal workings to build understanding
+- **"The reason for X is because historically, Y…"** — Explain origins
+- **"W is better than Z, because…"** — Offer judgements where appropriate
+- **"An X in this system is analogous to a Y in…"** — Provide context through analogy
+- **"Some users prefer W (because Z). This can be a good approach, but…"** — Weigh alternatives
+- **"X interacts with Y as follows:…"** — Unfold internal workings to build understanding
 
 ## Python Package Explanation Template
 
 ```markdown
 # About [Topic]
 
-[Opening paragraph that frames the topic and its role in the package.]
+[Opening paragraph that frames the topic and why it matters to the reader's
+understanding of the package.]
 
 ## Overview
 
-[High-level description of the concept, system, or approach.
+[High-level description of the concept, system, or decision being explained.
 Connect it to the reader's existing knowledge.]
 
-## [Component/Aspect Name]
+## Why [This Approach]
+
+[Explain the reasoning behind the design. What problem does it solve? What
+alternatives were considered? What constraints shaped the decision?]
 
-[Describe what it does and the advantages it provides.
-Focus on benefits, not on justifying the choice or comparing with alternatives.
-Keep sections concise - state what is gained, not what was rejected.]
+For example, [concrete example that illustrates the concept].
 
 ## How It Works
 
-[Describe the mechanism at a conceptual level - not a step-by-step procedure
+[Describe the mechanism at a conceptual level — not a step-by-step procedure
 (that would be a how-to), but the logic and flow of the system.]
 
 [Diagrams or analogies are valuable here.]
 
+## Trade-offs and Alternatives
+
+[Discuss what was gained and what was given up. Mention alternative approaches
+and why they were not chosen — or when they might be better.]
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Current approach | ... | ... |
+| Alternative A | ... | ... |
+| Alternative B | ... | ... |
+
 ## Connections
 
 [Link this topic to related concepts, other parts of the system, or broader
@@ -114,11 +133,14 @@ patterns in the ecosystem.]
 
 ## Typical Explanation Pages for Python Packages
 
-- **Architecture Overview** - How the package is structured, the component graph, data flow
-- **Key Concepts** - Domain terminology, mental models, glossary with depth
-- **Plugin/Extension Model** - How extensibility works
-- **Performance Characteristics** - Complexity analysis, caching strategy, benchmarks with context
-- **Security Model** - Trust boundaries, threat model, security approach
+- **Architecture Overview** — How the package is structured, the component graph, data flow
+- **Design Decisions** — Why certain approaches were chosen (ADR-style or narrative)
+- **Key Concepts** — Domain terminology, mental models, glossary with depth
+- **Plugin/Extension Model** — How extensibility works and why it is designed this way
+- **Performance Characteristics** — Complexity analysis, caching strategy rationale, benchmarks with context
+- **Security Model** — Trust boundaries, threat model, why certain security choices were made
+- **Comparison with Alternatives** — How this package differs from similar tools, when to choose which
+- **History and Evolution** — How the package got to its current state (for mature projects)
 
 ## Distinction from Reference
 
@@ -134,10 +156,9 @@ patterns in the ecosystem.]
 
 ## Anti-Patterns to Avoid
 
-- **Disguised reference** - Lists of parameters or API details belong in reference
-- **Disguised how-to** - Step-by-step procedures belong in how-to guides
-- **No clear topic** - Every explanation must be "about" something bounded
-- **Too abstract** - Ground discussion in concrete examples from the actual package
-- **Missing the "why"** - If it does not explain advantages or mechanisms, it is probably reference, not explanation
-- **Justification mode** - "Why X over Y" sections and comparison tables belong in ADRs, not docs
-- **Unbounded scope** - Explanation that tries to cover everything covers nothing well
+- **Disguised reference** — Lists of parameters or API details belong in reference
+- **Disguised how-to** — Step-by-step procedures belong in how-to guides
+- **No clear topic** — Every explanation must be "about" something bounded
+- **Too abstract** — Ground discussion in concrete examples from the actual package
+- **Missing the "why"** — If it does not answer "why", it is probably reference, not explanation
+- **Unbounded scope** — Explanation that tries to cover everything covers nothing well
diff --git a/.github/skills/diataxis-howto-writer/SKILL.md b/.github/skills/diataxis-howto-writer/SKILL.md
index b5204aa..99d3c51 100644
--- a/.github/skills/diataxis-howto-writer/SKILL.md
+++ b/.github/skills/diataxis-howto-writer/SKILL.md
@@ -5,10 +5,14 @@ description: Generate task-oriented how-to guide documentation for Python packag
 
 # Diátaxis How-to Guide Writer
 
-Generate how-to guides - task-oriented documentation that helps already-competent users accomplish specific goals.
+Generate how-to guides — task-oriented documentation that helps already-competent users accomplish specific goals.
 
 A how-to guide is a **recipe**. It addresses a real-world problem and provides practical directions to solve it. The reader already knows what they want to do.
 
+## File Placement
+
+Place how-to guides in `docs/pages/how-to/`. Example: `docs/pages/how-to/configure.md`.
+
 ## What a How-to Guide Is
 
 - Directions that guide the reader through a problem or towards a result
@@ -30,7 +34,7 @@ A how-to guide is NOT a tutorial. Tutorials serve learning; how-to guides serve
 ### Step 2: Determine Prerequisites
 
 - What should the user already know or have set up?
-- List these briefly at the top - do not teach them (that is a tutorial's job)
+- List these briefly at the top — do not teach them (that is a tutorial's job)
 
 ### Step 3: Write the Guide
 
@@ -50,7 +54,7 @@ Practical usability over completeness. A how-to guide should start and end in so
 
 ### Provide a set of instructions
 
-The steps are in the form of actions - including thinking and judgement, not just physical acts. Address how the user thinks as well as what the user does.
+The steps are in the form of actions — including thinking and judgement, not just physical acts. Address how the user thinks as well as what the user does.
 
 ### Describe a logical sequence
 
@@ -64,7 +68,7 @@ Ground sequences in the user's activity patterns. A workflow that has the user r
 - How long must they hold a thought before resolving it in action?
 - Does the guide require unnecessary back-and-forth?
 
-At its best, a how-to guide anticipates the user - the helper who has the tool ready before you reach for it.
+At its best, a how-to guide anticipates the user — the helper who has the tool ready before you reach for it.
 
 ### Pay attention to naming
 
@@ -76,13 +80,13 @@ Titles must say exactly what the guide shows:
 
 ### No digression, explanation, or teaching
 
-Anything beyond action dilutes the guide. Do not explain concepts inline - link to explanation pages. Do not teach basics - that is a tutorial's job. Do not provide exhaustive reference - link to reference pages.
+Anything beyond action dilutes the guide. Do not explain concepts inline — link to explanation pages. Do not teach basics — that is a tutorial's job. Do not provide exhaustive reference — link to reference pages.
 
 ## Language Patterns
 
-- **"This guide shows you how to…"** - Describe the problem and what will be solved
-- **"If you want x, do y. To achieve w, do z."** - Conditional imperatives
-- **"Refer to the X reference guide for a full list of options."** - Don't pollute with every option
+- **"This guide shows you how to…"** — Describe the problem and what will be solved
+- **"If you want x, do y. To achieve w, do z."** — Conditional imperatives
+- **"Refer to the X reference guide for a full list of options."** — Don't pollute with every option
 
 ## Python Package How-to Template
 
@@ -94,7 +98,7 @@ This guide shows you how to [goal description]. Use this when you need to
 
 ## Prerequisites
 
-- <package-name> installed ([Getting Started](../getting-started.md))
+- <package-name> installed ([Getting Started](../tutorials/getting-started.md))
 - [Other requirement]
 
 ## Steps
@@ -142,21 +146,21 @@ If you are [condition B] instead:
 
 ## See Also
 
-- [API Reference for X](../reference/api.md) - full list of options
-- [About Y architecture](../explanation/architecture.md) - understanding the design
+- [API Reference for X](../reference/api.md) — full list of options
+- [About Y architecture](../explanation/architecture.md) — understanding the design
 ```text
 
 ## Typical How-to Guides for Python Packages
 
-- **How to install** - pip, uv, conda, Docker, from source variations
-- **How to configure <feature>** - settings, env vars, config files
-- **How to integrate with <library>** - using alongside pytest, FastAPI, Django, etc.
-- **How to deploy to production** - WSGI, Docker, cloud platforms
-- **How to write a plugin / extension** - for extensible packages
-- **How to migrate from vX to vY** - upgrade path with breaking changes
-- **How to test your code** - patterns for testing code that uses the package
-- **How to troubleshoot <category>** - common problems and solutions
-- **How to contribute** - development setup, workflow, conventions
+- **How to install** — pip, uv, conda, Docker, from source variations
+- **How to configure <feature>** — settings, env vars, config files
+- **How to integrate with <library>** — using alongside pytest, FastAPI, Django, etc.
+- **How to deploy to production** — WSGI, Docker, cloud platforms
+- **How to write a plugin / extension** — for extensible packages
+- **How to migrate from vX to vY** — upgrade path with breaking changes
+- **How to test your code** — patterns for testing code that uses the package
+- **How to troubleshoot <category>** — common problems and solutions
+- **How to contribute** — development setup, workflow, conventions
 
 ## Distinction from Tutorials
 
@@ -167,16 +171,16 @@ If you are [condition B] instead:
 | Goal | Learning experience | Task completion |
 | Path | Single, managed | Branching, real-world |
 | Setting | Contrived, safe | Real world, unpredictable |
-| Choices | None - pick for them | Conditional alternatives |
+| Choices | None — pick for them | Conditional alternatives |
 | Responsibility | Teacher's | User's |
-| Explanation | Minimal, inline | None - link out |
+| Explanation | Minimal, inline | None — link out |
 
 A tutorial teaches general skills through a specific exercise. A how-to guide helps accomplish a specific task using existing skills.
 
 ## Anti-Patterns to Avoid
 
-- **Teaching basics** - Do not explain what a function is; the user is competent
-- **Exhaustive options** - List 2-3 variations, link to reference for the rest
-- **Tool-centric framing** - "How to use the X class" is not addressed to a human need
-- **Missing conditionals** - Real-world tasks branch; acknowledge this with if/then guidance
-- **Burying the action** - Lead with what to do, not why
+- **Teaching basics** — Do not explain what a function is; the user is competent
+- **Exhaustive options** — List 2-3 variations, link to reference for the rest
+- **Tool-centric framing** — "How to use the X class" is not addressed to a human need
+- **Missing conditionals** — Real-world tasks branch; acknowledge this with if/then guidance
+- **Burying the action** — Lead with what to do, not why
diff --git a/.github/skills/diataxis-reference-writer/SKILL.md b/.github/skills/diataxis-reference-writer/SKILL.md
index 826f3f6..796c61e 100644
--- a/.github/skills/diataxis-reference-writer/SKILL.md
+++ b/.github/skills/diataxis-reference-writer/SKILL.md
@@ -5,10 +5,14 @@ description: Generate and structure information-oriented reference documentation
 
 # Diátaxis Reference Writer
 
-Generate reference documentation - information-oriented technical descriptions of the machinery, meant to be consulted, not read.
+Generate reference documentation — information-oriented technical descriptions of the machinery, meant to be consulted, not read.
 
 Reference material is like a **map**: it describes the territory accurately so the user can navigate it confidently while working. It is austere, authoritative, and free of interpretation.
 
+## File Placement
+
+Place reference pages in `docs/pages/reference/`. Example: `docs/pages/reference/api.md`.
+
 ## What Reference Is
 
 - Technical description of the machinery and how to operate it
@@ -16,7 +20,7 @@ Reference material is like a **map**: it describes the territory accurately so t
 - Led by the **product structure**, not by user needs
 - Purpose: describe, as succinctly as possible, in an orderly way
 
-Reference is what the user needs while they are at work - applying their existing skills.
+Reference is what the user needs while they are at work — applying their existing skills.
 
 ## Generation Workflow
 
@@ -31,7 +35,7 @@ Reference is what the user needs while they are at work - applying their existin
 
 ### Step 2: Mirror the Code Structure
 
-The documentation structure must reflect the code structure - like a map reflects territory. If a method belongs to a class in a module, the docs should show the same hierarchy.
+The documentation structure must reflect the code structure — like a map reflects territory. If a method belongs to a class in a module, the docs should show the same hierarchy.
 
 ```text
 reference/
@@ -59,7 +63,7 @@ If instruction or explanation feels necessary, link to how-to guides or explanat
 
 Reference is useful when it is consistent. Use the same format for every function, every class, every CLI command. Standard patterns let users scan rapidly.
 
-No creative vocabulary or varied styles - reference is not the place.
+No creative vocabulary or varied styles — reference is not the place.
 
 ### Respect the structure of the machinery
 
@@ -74,13 +78,13 @@ Short usage examples illustrate without distracting. An example of a command inv
 client = MyClient(timeout=30)
 ```
 
-Keep examples minimal - just enough to illustrate, not to teach.
+Keep examples minimal — just enough to illustrate, not to teach.
 
 ## Language Patterns
 
-- **"<Class> provides…"**, **"<Function> returns…"** - State facts about the machinery
-- **"Parameters: a, b, c"** - List inputs, outputs, options
-- **"You must use X. You must not apply Y unless Z."** - Warnings where appropriate
+- **"<Class> provides…"**, **"<Function> returns…"** — State facts about the machinery
+- **"Parameters: a, b, c"** — List inputs, outputs, options
+- **"You must use X. You must not apply Y unless Z."** — Warnings where appropriate
 - **"See [How to configure X] for usage guidance."** — Link out
 
 ## mkdocstrings Integration
@@ -220,8 +224,8 @@ The configuration file is read from `~/.config/package/config.toml`.
 
 ## Anti-Patterns to Avoid
 
-- **Creeping explanation** - Examples that expand into "why" discussions; keep examples terse
-- **Missing structure** - Flat lists of functions with no hierarchy; mirror the code
-- **Incomplete coverage** - Every public API surface must be documented, no gaps
-- **Stale content** - Reference must match the current version; automate where possible
-- **Instruction mixed in** - "To use this, first do X" is a how-to; reference just describes
+- **Creeping explanation** — Examples that expand into "why" discussions; keep examples terse
+- **Missing structure** — Flat lists of functions with no hierarchy; mirror the code
+- **Incomplete coverage** — Every public API surface must be documented, no gaps
+- **Stale content** — Reference must match the current version; automate where possible
+- **Instruction mixed in** — "To use this, first do X" is a how-to; reference just describes
diff --git a/.github/skills/diataxis-tutorial-writer/SKILL.md b/.github/skills/diataxis-tutorial-writer/SKILL.md
index fc6aaa6..fca6780 100644
--- a/.github/skills/diataxis-tutorial-writer/SKILL.md
+++ b/.github/skills/diataxis-tutorial-writer/SKILL.md
@@ -5,10 +5,14 @@ description: Generate learning-oriented tutorial documentation for Python packag
 
 # Diátaxis Tutorial Writer
 
-Generate tutorials - learning-oriented documentation where the reader acquires skills through hands-on practice under guidance.
+Generate tutorials — learning-oriented documentation where the reader acquires skills through hands-on practice under guidance.
 
 A tutorial is a **lesson**. The reader does things, and learns by doing. The author is the teacher; the reader is the student.
 
+## File Placement
+
+Place tutorial pages in `docs/pages/tutorials/`. Example: `docs/pages/tutorials/getting-started.md`.
+
 ## What a Tutorial Is
 
 - A practical activity where the student learns by doing something meaningful
@@ -31,11 +35,11 @@ A tutorial is like a driving lesson: the purpose is to develop skills and confid
 
 Choose a concrete goal the learner will achieve. Structure it as:
 
-1. **Setup** - Install the package, verify installation
-2. **First contact** - Import, call the simplest function, see a result
-3. **Build** - Incrementally add complexity, one concept at a time
-4. **Completion** - Arrive at a meaningful, visible result
-5. **Next steps** - Link to how-to guides and explanation (not more tutorials)
+1. **Setup** — Install the package, verify installation
+2. **First contact** — Import, call the simplest function, see a result
+3. **Build** — Incrementally add complexity, one concept at a time
+4. **Completion** — Arrive at a meaningful, visible result
+5. **Next steps** — Link to how-to guides and explanation (not more tutorials)
 
 Every step should produce a **visible, verifiable result**.
 
@@ -49,7 +53,7 @@ Apply all key principles below. Use the language patterns. Target 500-1500 words
 
 Open with what they will achieve: "In this tutorial, we will create a [concrete thing]. Along the way we will [encounter X, Y, Z]."
 
-Never say "In this tutorial you will learn…" - that is presumptuous.
+Never say "In this tutorial you will learn…" — that is presumptuous.
 
 ### Deliver visible results early and often
 
@@ -82,11 +86,11 @@ Explanation distracts the learner's attention and blocks learning. Resist the ur
 
 ### Focus on the concrete
 
-Focus on *this* problem, *this* action, *this* result. Lead the learner from step to concrete step. General patterns will emerge naturally from concrete examples - the mind does this automatically.
+Focus on *this* problem, *this* action, *this* result. Lead the learner from step to concrete step. General patterns will emerge naturally from concrete examples — the mind does this automatically.
 
 ### Ignore options and alternatives
 
-There may be many interesting diversions - ignore them. Stay on the path to the conclusion. Every option adds cognitive load. Save alternatives for how-to guides.
+There may be many interesting diversions — ignore them. Stay on the path to the conclusion. Every option adds cognitive load. Save alternatives for how-to guides.
 
 ### Encourage and permit repetition
 
@@ -100,12 +104,12 @@ Every step must produce the stated result for every user, every time. A learner
 
 Use these templates:
 
-- **"We…"** - First-person plural affirms the teacher-learner relationship
-- **"In this tutorial, we will…"** - Describe what the learner will accomplish
-- **"First, do x. Now, do y. Now that you have done y, do z."** - No ambiguity
-- **"The output should look something like…"** - Set expectations
-- **"Notice that…"**, **"Remember that…"**, **"Let's check…"** - Confirm they are on track
-- **"You have built a…"** - Celebrate the accomplishment at the end
+- **"We…"** — First-person plural affirms the teacher-learner relationship
+- **"In this tutorial, we will…"** — Describe what the learner will accomplish
+- **"First, do x. Now, do y. Now that you have done y, do z."** — No ambiguity
+- **"The output should look something like…"** — Set expectations
+- **"Notice that…"**, **"Remember that…"**, **"Let's check…"** — Confirm they are on track
+- **"You have built a…"** — Celebrate the accomplishment at the end
 
 ## Python Package Tutorial Template
 
@@ -189,16 +193,16 @@ You have [accomplished concrete thing]. Along the way, you:
 
 ## Anti-Patterns to Avoid
 
-- **Starting with explanation** - Do not open with "X is a framework that…"; open with what they will do
-- **Offering choices** - "You can use either A or B" forces a decision; just pick one
-- **Assumed knowledge** - Do not skip steps because they seem obvious
-- **Wall of code** - Break into small steps, each with visible output
-- **Missing output examples** - Every code block needs its expected output
-- **Teaching by telling** - Show, do not explain; link to explanation pages instead
+- **Starting with explanation** — Do not open with "X is a framework that…"; open with what they will do
+- **Offering choices** — "You can use either A or B" forces a decision; just pick one
+- **Assumed knowledge** — Do not skip steps because they seem obvious
+- **Wall of code** — Break into small steps, each with visible output
+- **Missing output examples** — Every code block needs its expected output
+- **Teaching by telling** — Show, do not explain; link to explanation pages instead
 
 ## What a Tutorial Is NOT
 
 - Not a how-to guide (serves work, not study)
 - Not a reference (describes machinery, doesn't guide action)
 - Not an explanation (discusses topics, doesn't guide action)
-- Not "the basics" - tutorials can be advanced; the distinction is study vs. work
+- Not "the basics" — tutorials can be advanced; the distinction is study vs. work
diff --git a/pyproject.toml b/pyproject.toml
index e3a6003..64c03ca 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -138,6 +138,7 @@ exclude = ["CHANGELOG.md", "template", "site", "htmlcov", ".nox", ".venv"]
 
 [tool.rumdl.per-file-ignores]
 ".github/PULL_REQUEST_TEMPLATE.md" = ["MD041"]  # PR template starts with checklist
+".github/skills/**" = ["MD007"]  # Nested lists in skill files use variable indent
 "README.md" = ["MD041"]  # README starts with badges, not heading
 "docs/index.md" = ["MD041"]  # Landing page starts with logo, not heading
 
diff --git a/template/.github/skills/diataxis-docs-planner/SKILL.md b/template/.github/skills/diataxis-docs-planner/SKILL.md
index 8cd3558..87f5828 100644
--- a/template/.github/skills/diataxis-docs-planner/SKILL.md
+++ b/template/.github/skills/diataxis-docs-planner/SKILL.md
@@ -85,33 +85,31 @@ Output a structured documentation plan:
 3. **MkDocs nav structure** — ready to paste into `mkdocs.yml`
 4. **Implementation order** — tutorials and key how-tos first (highest user impact)
 5. **Skill recommendations** — name the specific writer skill for each page:
-    - Tutorial pages → `diataxis-tutorial-writer`
-    - How-to pages → `diataxis-howto-writer`
-    - Reference pages → `diataxis-reference-writer`
-    - Explanation pages → `diataxis-explanation-writer`
+   - Tutorial pages → `diataxis-tutorial-writer`
+   - How-to pages → `diataxis-howto-writer`
+   - Reference pages → `diataxis-reference-writer`
+   - Explanation pages → `diataxis-explanation-writer`
 
 ## MkDocs Nav Patterns
 
-Typical Python package nav structure:
+Canonical Python package nav structure using `pages/` folder-per-quadrant:
 
 ```yaml
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md          # tutorial
+  - Tutorials:                                    # tutorial
+    - Getting Started: pages/tutorials/getting-started.md
   - How-to Guides:                                # how-to
-    - how-to/index.md
-    - How to Configure X: how-to/configure-x.md
-    - How to Integrate with Y: how-to/integrate-y.md
+    - How to Configure X: pages/how-to/configure-x.md
+    - How to Integrate with Y: pages/how-to/integrate-y.md
+    - Contributing: pages/how-to/contribute.md
   - Reference:                                    # reference
-    - reference/index.md
-    - API Reference: reference/api.md
-    - CLI Reference: reference/cli.md
-    - Configuration: reference/configuration.md
+    - API Reference: pages/reference/api.md
+    - CLI Reference: pages/reference/cli.md
+    - Configuration: pages/reference/configuration.md
   - Explanation:                                  # explanation
-    - explanation/index.md
-    - Architecture: explanation/architecture.md
-    - Design Decisions: explanation/design-decisions.md
-  - Contributing: contributing.md                 # how-to (for contributors)
+    - Architecture: pages/explanation/architecture.md
+    - Design Decisions: pages/explanation/design-decisions.md
 ```
 
 For complex packages with multiple user types or deployment targets, see [references/compass-and-patterns.md](references/compass-and-patterns.md) for multi-layer hierarchy and two-dimensional structure guidance.
diff --git a/template/.github/skills/diataxis-explanation-writer/SKILL.md b/template/.github/skills/diataxis-explanation-writer/SKILL.md
index cf33a4c..ed204f6 100644
--- a/template/.github/skills/diataxis-explanation-writer/SKILL.md
+++ b/template/.github/skills/diataxis-explanation-writer/SKILL.md
@@ -9,6 +9,10 @@ Generate explanation documentation — understanding-oriented discussion that he
 
 Explanation is like reading **On Food and Cooking** by Harold McGee: it does not teach you to cook or give you recipes, but it places cooking in context of history, science, and society, deepening your understanding of the craft.
 
+## File Placement
+
+Place explanation pages in `docs/pages/explanation/`. Example: `docs/pages/explanation/concepts.md`.
+
 ## What Explanation Is
 
 - Discursive treatment of a subject that permits reflection
diff --git a/template/.github/skills/diataxis-howto-writer/SKILL.md b/template/.github/skills/diataxis-howto-writer/SKILL.md
index f04a8c2..99d3c51 100644
--- a/template/.github/skills/diataxis-howto-writer/SKILL.md
+++ b/template/.github/skills/diataxis-howto-writer/SKILL.md
@@ -9,6 +9,10 @@ Generate how-to guides — task-oriented documentation that helps already-compet
 
 A how-to guide is a **recipe**. It addresses a real-world problem and provides practical directions to solve it. The reader already knows what they want to do.
 
+## File Placement
+
+Place how-to guides in `docs/pages/how-to/`. Example: `docs/pages/how-to/configure.md`.
+
 ## What a How-to Guide Is
 
 - Directions that guide the reader through a problem or towards a result
@@ -94,7 +98,7 @@ This guide shows you how to [goal description]. Use this when you need to
 
 ## Prerequisites
 
-- <package-name> installed ([Getting Started](../getting-started.md))
+- <package-name> installed ([Getting Started](../tutorials/getting-started.md))
 - [Other requirement]
 
 ## Steps
diff --git a/template/.github/skills/diataxis-reference-writer/SKILL.md b/template/.github/skills/diataxis-reference-writer/SKILL.md
index f735605..796c61e 100644
--- a/template/.github/skills/diataxis-reference-writer/SKILL.md
+++ b/template/.github/skills/diataxis-reference-writer/SKILL.md
@@ -9,6 +9,10 @@ Generate reference documentation — information-oriented technical descriptions
 
 Reference material is like a **map**: it describes the territory accurately so the user can navigate it confidently while working. It is austere, authoritative, and free of interpretation.
 
+## File Placement
+
+Place reference pages in `docs/pages/reference/`. Example: `docs/pages/reference/api.md`.
+
 ## What Reference Is
 
 - Technical description of the machinery and how to operate it
diff --git a/template/.github/skills/diataxis-tutorial-writer/SKILL.md b/template/.github/skills/diataxis-tutorial-writer/SKILL.md
index 8642bfe..fca6780 100644
--- a/template/.github/skills/diataxis-tutorial-writer/SKILL.md
+++ b/template/.github/skills/diataxis-tutorial-writer/SKILL.md
@@ -9,6 +9,10 @@ Generate tutorials — learning-oriented documentation where the reader acquires
 
 A tutorial is a **lesson**. The reader does things, and learns by doing. The author is the teacher; the reader is the student.
 
+## File Placement
+
+Place tutorial pages in `docs/pages/tutorials/`. Example: `docs/pages/tutorials/getting-started.md`.
+
 ## What a Tutorial Is
 
 - A practical activity where the student learns by doing something meaningful
diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja
index c2de48e..dfc390e 100644
--- a/template/pyproject.toml.jinja
+++ b/template/pyproject.toml.jinja
@@ -207,6 +207,7 @@ exclude = ["CHANGELOG.md", "site", "htmlcov", ".nox", ".venv"]
 
 [tool.rumdl.per-file-ignores]
 ".github/PULL_REQUEST_TEMPLATE.md" = ["MD041"]  # PR template starts with checklist
+".github/skills/**" = ["MD007"]  # Nested lists in skill files use variable indent
 "README.md" = ["MD041"]  # README starts with logo, not heading
 "docs/index.md" = ["MD041"]  # Landing page starts with logo, not heading
 "CONTRIBUTING.md" = ["MD057"]  # Relative link to docs/ is valid at project level