docs: adopt Diátaxis framework for user documentation

.github/workflows/adr-validation.yml

@@ -22,14 +22,16 @@ jobs:
     steps:
       - name: Checkout repository
         # v6.0.2
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        # v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
       - name: Validate ADR Format
         # main
         uses: zircote/adrscope@f5b56af9f5ebe72a480770ff9389fcc46345cb66
         with:
           command: validate
           input-dir: docs/adr
+          pattern: "[0-9]*.md"
 
       - name: Get ADR Statistics
         # main

docs/README.md

@@ -1,18 +1,88 @@
 # Documentation Index
 
-> All documentation for the nsip project.
+> All documentation for the nsip project organized using the [Diataxis framework](https://diataxis.fr/).
+
+## Quick Start
+
+New to NSIP? Start here:
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started Tutorial](tutorials/GETTING-STARTED.md) | 15-minute hands-on introduction to the NSIP CLI and library |
+| [Understanding EBVs](explanation/EBV-EXPLAINED.md) | Learn what Estimated Breeding Values are and how to interpret them |
+| [CLI Reference](reference/CLI.md) | Complete reference for every CLI subcommand, flag, and option |
+
+---
+
+## Tutorials
+
+Learning-oriented guides that take you through practical exercises step by step.
+
+| Tutorial | Time | Description |
+|----------|------|-------------|
+| [Getting Started](tutorials/GETTING-STARTED.md) | 15 min | Install nsip, search for animals, retrieve genetic data |
+| [Your First API Query](tutorials/FIRST-API-QUERY.md) | 10 min | Use the Rust library to query the NSIP Search API end-to-end |
+| [MCP Server Setup](tutorials/MCP-SERVER-SETUP.md) | 10 min | Configure and start the MCP server for AI assistant integration |
+| [Interpreting Search Results](tutorials/INTERPRETING-RESULTS.md) | 10 min | Read and understand animal search results, EBV traits, and accuracy |
+
+---
+
+## How-To Guides
+
+Problem-oriented guides for accomplishing specific tasks.
+
+| Guide | Description |
+|-------|-------------|
+| [Configure Client](how-to/CONFIGURE-CLIENT.md) | Customize timeout, retries, and base URL for the HTTP client |
+| [Compare Animals](how-to/COMPARE-ANIMALS.md) | Side-by-side genetic trait comparisons via CLI, library, or MCP |
+| [Filter Search Results](how-to/FILTER-SEARCH-RESULTS.md) | Use SearchCriteria to filter by breed, gender, status, date, and trait ranges |
+| [Use MCP Tools](how-to/USE-MCP-TOOLS.md) | Invoke the 13 MCP server tools from AI assistants |
+| [Export JSON](how-to/EXPORT-JSON.md) | Export data as JSON using the `--json` flag or library serialization |
+| [Batch Query Animals](how-to/BATCH-QUERY.md) | Query multiple animals concurrently with Tokio |
+| [Scripting Integration](how-to/SCRIPTING-INTEGRATION.md) | Integrate nsip into shell scripts, CI pipelines, and automation workflows |
+
+---
+
+## Explanation
+
+Understanding-oriented discussions of key concepts.
+
+| Document | Description |
+|----------|-------------|
+| [Understanding EBVs](explanation/EBV-EXPLAINED.md) | What EBVs are, how they're calculated, accuracy, and selection indexes |
+| [NSIP Data Model](explanation/NSIP-DATA-MODEL.md) | Program structure: breed groups, breeds, flocks, animals, and their relationships |
+| [Genetic Evaluation](explanation/GENETIC-EVALUATION.md) | How BLUP works, pedigree and genomic data, and the evaluation pipeline |
+| [Breed Groups and Traits](explanation/BREED-GROUPS-AND-TRAITS.md) | Understanding breed group categories and the 13 EBV trait abbreviations |
+| [From Data to Decisions](explanation/DATA-TO-DECISIONS.md) | How NSIP API data connects to real-world breeding decisions |
+
+---
+
+## Reference
+
+Information-oriented technical descriptions.
+
+| Document | Description |
+|----------|-------------|
+| [CLI Reference](reference/CLI.md) | Every subcommand, flag, and option for the `nsip` binary |
+| [Library API](reference/LIBRARY-API.md) | `NsipClient` methods, `SearchCriteria` builder, and all model types |
+| [MCP Tools](reference/MCP-TOOLS.md) | All 13 MCP server tools with parameters, return types, and examples |
+| [Error Handling](reference/ERROR-HANDLING.md) | Complete `Error` enum reference with handling patterns |
+| [Configuration](reference/CONFIGURATION.md) | Client builder options, defaults, retry behavior, and environment |
+| [MCP Server API](MCP.md) | Full MCP server reference: tools, resources, prompts, and analytics |
+
+---
 
 ## Template Adoption Guides
 
 Guides for developers who just created a repository from this template.
 
 | Guide | Description |
 |-------|-------------|
-| [Getting Started](template/GETTING-STARTED.md) | "Use this template" → first `cargo build` → first CI pass |
+| [Getting Started](template/GETTING-STARTED.md) | "Use this template" to first `cargo build` to first CI pass |
 | [Configuration](template/CONFIGURATION.md) | Cargo.toml fields, placeholder replacement, feature flags, editor setup |
 | [CI Workflows](template/CI-WORKFLOWS.md) | Every included workflow: triggers, secrets, how to enable/disable |
 | [Customization](template/CUSTOMIZATION.md) | Add modules, remove examples, adjust lints, modify release targets |
-| [GitHub Template Features](template/GITHUB-TEMPLATE-FEATURES.md) | What copies when using a template — and what doesn't |
+| [GitHub Template Features](template/GITHUB-TEMPLATE-FEATURES.md) | What copies when using a template -- and what doesn't |
 | [Copilot Jumpstart](template/COPILOT-JUMPSTART.md) | Prompts for automatic project scaffolding with GitHub Copilot |
 
 ## Operational Runbooks
@@ -21,12 +91,12 @@ Step-by-step procedures for ongoing project maintenance.
 
 | Runbook | Description |
 |---------|-------------|
-| [Releasing](runbooks/RELEASING.md) | Version bump → tag → monitor workflows → verify artifacts |
+| [Releasing](runbooks/RELEASING.md) | Version bump, tag, monitor workflows, verify artifacts |
 | [Dependency Updates](runbooks/DEPENDENCY-UPDATES.md) | Dependabot policy, manual cargo-deny audit, handling advisories |
 | [Security Response](runbooks/SECURITY-RESPONSE.md) | Vulnerability triage, fix, coordinated disclosure |
 | [CI Troubleshooting](runbooks/CI-TROUBLESHOOTING.md) | Common CI failure patterns and fixes |
 
-## Reference Documentation
+## Additional Reference
 
 Detailed reference material organized by topic.
 
@@ -90,5 +160,6 @@ Detailed reference material organized by topic.
 |-----|-------------|
 | [ADR-0001](adr/0001-use-architectural-decision-records.md) | Use Architectural Decision Records |
 | [ADR-0002](adr/0002-documentation-directory-structure.md) | Documentation Directory Structure |
+| [ADR-0003](adr/0003-adopt-diataxis-documentation-framework.md) | Adopt Diataxis Documentation Framework |
 
 See [docs/adr/README.md](adr/README.md) for the full ADR process and workflow.

docs/adr/0001-use-architectural-decision-records.md

@@ -1,8 +1,24 @@
-# Use Architectural Decision Records
-
-## Status
+---
+title: "Use Architectural Decision Records"
+description: "Adopt ADRs to document significant architectural decisions"
+type: adr
+category: process
+tags:
+  - documentation
+  - process
+  - adr
+status: accepted
+created: "2026-02-16"
+updated: "2026-02-16"
+author: nsip maintainers
+project: nsip
+technologies:
+  - markdown
+audience:
+  - developers
+---
 
-Accepted
+# Use Architectural Decision Records
 
 ## Context
 

docs/adr/0002-documentation-directory-structure.md

@@ -1,8 +1,23 @@
-# Documentation Directory Structure
-
-## Status
+---
+title: "Documentation Directory Structure"
+description: "Organize docs into template guides and operational runbooks"
+type: adr
+category: documentation
+tags:
+  - documentation
+  - structure
+status: accepted
+created: "2026-02-16"
+updated: "2026-02-16"
+author: nsip maintainers
+project: nsip
+technologies:
+  - markdown
+audience:
+  - developers
+---
 
-Accepted
+# Documentation Directory Structure
 
 ## Context
 

docs/adr/0003-adopt-diataxis-documentation-framework.md

@@ -0,0 +1,168 @@
+---
+title: "Adopt Diataxis Documentation Framework"
+description: "Organize user documentation using the Diataxis framework"
+type: adr
+category: documentation
+tags:
+  - documentation
+  - diataxis
+  - structure
+status: accepted
+created: "2026-02-16"
+updated: "2026-02-16"
+author: nsip maintainers
+project: nsip
+technologies:
+  - markdown
+audience:
+  - developers
+related:
+  - 0002-documentation-directory-structure.md
+---
+
+# Adopt Diataxis Documentation Framework
+
+## Context
+
+The repository had comprehensive technical reference documentation (11,562 lines across 39 markdown files) but lacked structured learning paths for new users. Existing documentation focused on:
+
+- Reference material (API docs, MCP server reference)
+- Operational runbooks (releasing, CI troubleshooting)
+- Template guides (for repository setup)
+
+However, there were no:
+- **Tutorials** - Learning-oriented, hands-on lessons for newcomers
+- **How-To Guides** - Problem-oriented solutions for specific tasks
+- **Explanations** - Understanding-oriented conceptual documentation
+
+This created a documentation gap where users had to jump directly from the README examples to comprehensive API reference, with no intermediate learning materials.
+
+---
+
+## Decision
+
+Adopt the [Diátaxis framework](https://diataxis.fr/) for organizing all user-facing documentation.
+
+### Framework Structure
+
+Diátaxis organizes documentation into four quadrants:
+
+| Type | Orientation | Focus | Example |
+|------|------------|-------|---------|
+| **Tutorials** | Learning | Practical steps | "Getting Started with NSIP" |
+| **How-To Guides** | Problem-solving | Specific goals | "How to Compare Animals" |
+| **Explanation** | Understanding | Concepts | "Understanding EBVs" |
+| **Reference** | Information | Technical facts | "Error Handling Reference" |
+
+### Directory Structure
+
+````
+docs/
+├── README.md              # Documentation index with Diátaxis organization
+├── tutorials/             # Learning-oriented guides
+├── how-to/                # Problem-oriented guides
+├── explanation/           # Understanding-oriented discussions
+├── reference/             # Information-oriented technical docs
+├── runbooks/              # Operational procedures (existing)
+├── template/              # Template adoption guides (existing)
+└── workflows/             # CI/CD documentation (existing)
+````
+
+### Initial Documentation Set
+
+**Tutorials:**
+- `tutorials/GETTING-STARTED.md` - 15-minute introduction to NSIP API
+
+**How-To Guides:**
+- `how-to/CONFIGURE-CLIENT.md` - Customize timeout and retry settings
+- `how-to/COMPARE-ANIMALS.md` - Side-by-side genetic trait comparisons
+
+**Explanation:**
+- `explanation/EBV-EXPLAINED.md` - What EBVs are and how to use them
+
+**Reference:**
+- `reference/ERROR-HANDLING.md` - Complete error type reference
+- `MCP.md` - MCP server API reference (existing, moved to reference category)
+
+---
+
+## Consequences
+
+### Positive
+
+✅ **Clear learning path** - New users can start with tutorials and progress naturally  
+✅ **Findability** - Users know where to look for different types of information  
+✅ **Progressive disclosure** - Information complexity increases with user expertise  
+✅ **Reduced cognitive load** - Each document has a single, clear purpose  
+✅ **Maintainability** - Clear categorization makes updates easier  
+✅ **Industry standard** - Diátaxis is used by Django, NumPy, and other major projects  
+
+### Negative
+
+⚠️ **Migration effort** - Some existing docs may need recategorization  
+⚠️ **Link updates** - Internal references need updating to new paths  
+⚠️ **Duplication risk** - Clear guidelines needed to avoid content overlap  
+
+### Mitigations
+
+- Existing documentation remains in place (runbooks, template guides, workflows)
+- New categories augment rather than replace current structure
+- Documentation index (`docs/README.md`) provides unified navigation
+- Cross-references between quadrants help users discover related content
+
+---
+
+## Alternatives Considered
+
+### 1. Keep Current Ad-Hoc Structure
+
+**Pros:** No changes needed  
+**Cons:** Continues documentation gaps, no clear user journey
+
+### 2. Use README-Only Approach
+
+**Pros:** Simple, single file  
+**Cons:** Doesn't scale, hard to navigate, poor SEO
+
+### 3. Auto-Generated API Docs Only
+
+**Pros:** Always in sync with code  
+**Cons:** No conceptual explanations, steep learning curve
+
+---
+
+## References
+
+- [Diátaxis Framework](https://diataxis.fr/)
+- [Django Documentation](https://docs.djangoproject.com/) - Diátaxis example
+- [Write the Docs: Documentation Systems](https://www.writethedocs.org/guide/docs-as-code/)
+
+---
+
+## Implementation Notes
+
+The `update-docs` workflow detected the documentation framework gap and created initial documentation in each quadrant. Future documentation should follow this structure:
+
+**When writing tutorials:**
+- Use step-by-step instructions
+- Build something tangible
+- Assume minimal prior knowledge
+- Provide complete working examples
+
+**When writing how-to guides:**
+- Start with a clear problem statement
+- Provide solution steps
+- Focus on one specific task
+- Include time estimates
+
+**When writing explanations:**
+- Clarify concepts and theory
+- Connect ideas
+- Provide context and background
+- Use diagrams where helpful
+
+**When writing reference:**
+- Be accurate and complete
+- Use consistent structure
+- Include all parameters/options
+- Provide examples

docs/adr/README.md

@@ -58,3 +58,4 @@ The HTML viewer is uploaded as a build artifact and can be downloaded from the A
 
 - [ADR-0001](0001-use-architectural-decision-records.md) - Use Architectural Decision Records
 - [ADR-0002](0002-documentation-directory-structure.md) - Documentation Directory Structure
+- [ADR-0003](0003-adopt-diataxis-documentation-framework.md) - Adopt Diátaxis Documentation Framework