# guides/ - Usage Guides by Skill Level

> **Progressive learning guides** from beginner to expert

**Quick Reference:** [Getting Started](getting-started.md) | [Figures and Analysis](figures-and-analysis.md) | [Testing and Reproducibility](testing-and-reproducibility.md) | [Extending and Automation](extending-and-automation.md)

## Purpose

The `guides/` directory contains skill-level specific usage guides that progressively teach users how to use the Research Project Template, from basic document creation to expert-level customization.

**Boundary with [`../usage/`](../usage/):** `guides/` = task-driven walkthroughs organized by skill level ("teach me how"); `usage/` = format/style reference consulted while actively authoring ("look up the syntax"). New docs that teach a workflow go here; new docs that catalog options or markup go in `usage/`.

## Contents

| File | Purpose | Skill Level |
|------|---------|-------------|
| [`startup-and-setup.md`](startup-and-setup.md) | Install + validation procedure, copy-pasteable for humans and agents | Beginner |
| [`getting-started.md`](getting-started.md) | Basic usage guide (Levels 1-3) | Beginner |
| [`figures-and-analysis.md`](figures-and-analysis.md) | Figures and analysis guide (Levels 4-6) | Intermediate |
| [`testing-and-reproducibility.md`](testing-and-reproducibility.md) | Testing and reproducibility guide (Levels 7-9) | Advanced |
| [`extending-and-automation.md`](extending-and-automation.md) | Extending and automation guide (Levels 10-12) | Expert |
| [`new-project-setup.md`](new-project-setup.md) | New project checklist (pitfalls and venv) | All levels |
| [`new-project-one-shot-prompt.md`](new-project-one-shot-prompt.md) | Copy-paste LLM prompt (positive controls: template_code_project + template) | All levels |
| [`methods-orchestration.md`](methods-orchestration.md) | Methods-to-pipeline contracts, artifacts, evidence, validation commands | Advanced |
| [`codegraph-local.md`](codegraph-local.md) | Optional local CodeGraph indexing for agent code navigation, with scope guards | Advanced |
| [`leann-local.md`](leann-local.md) | Optional local LEANN semantic retrieval for agent navigation, with generated-index guards | Advanced |
| [`llm-integration-guide.md`](llm-integration-guide.md) | AI-assisted research with Ollama (LLM review, translation) | Expert |
| [`publishing-guide.md`](publishing-guide.md) | Publishing workflow (DOI, Zenodo, arXiv, citations) | Expert |
| [`secure-research-guide.md`](secure-research-guide.md) | PDF watermarking, provenance, and integrity | Expert |
| [`zenodo-doi-strategy.md`](zenodo-doi-strategy.md) | Concept vs version DOI strategy for repeat Zenodo releases | Expert |
| [`manuscript-semantics.md`](manuscript-semantics.md) | **Canonical** manuscript syntax & semantics — Pandoc citations `[@key]`, cross-refs `[@eq:/@fig:/@sec:]`, `{{TOKEN}}` substitution, preamble. Read before authoring any manuscript. | All levels |
| [`fork-an-exemplar.md`](fork-an-exemplar.md) | Fork-readiness walkthrough for canonical exemplars | All levels |
| [`literature-workflow-guide.md`](literature-workflow-guide.md) | Literature discovery → export → synthesis (Ollama-assisted) | Expert |

## Learning Path

### Learning Journey

1. **[Getting Started](getting-started.md)** - Write your first document (Levels 1-3)
2. **[Figures and Analysis](figures-and-analysis.md)** - Add figures and automation (Levels 4-6)
3. **[Testing and Reproducibility](testing-and-reproducibility.md)** - Test-driven development and reproducibility (Levels 7-9)
4. **[Extending and Automation](extending-and-automation.md)** - Extending and automation (Levels 10-12)

## Quick Navigation

### New to the Template?

→ Start with **[Getting Started](getting-started.md)**

### Ready for Automation?

→ Read **[Figures and Analysis](figures-and-analysis.md)**

### Want Test-Driven Development?

→ Study **[Testing and Reproducibility](testing-and-reproducibility.md)**

### Building Custom Systems?

→ Master **[Extending and Automation](extending-and-automation.md)**

## Related Documentation

- **[`new-project-setup.md`](new-project-setup.md)** — step-by-step checklist before first pipeline run
- **[`new-project-one-shot-prompt.md`](new-project-one-shot-prompt.md)** — one-shot scaffold prompt for AI-assisted projects
- **[`methods-orchestration.md`](methods-orchestration.md)** — keep methods prose, pipeline contracts, artifacts, and evidence aligned
- **[`codegraph-local.md`](codegraph-local.md)** — optional local code graph indexing for source navigation and impact checks
- **[`leann-local.md`](leann-local.md)** — optional local semantic retrieval for source navigation and impact checks
- **[`../core/how-to-use.md`](../core/how-to-use.md)** - usage guide (navigation hub)
- **[`../usage/`](../usage/)** - Usage examples and patterns
- **[`../reference/common-workflows.md`](../reference/common-workflows.md)** - Step-by-step recipes
- **[`../reference/quick-start-cheatsheet.md`](../reference/quick-start-cheatsheet.md)** - Quick reference

## See Also

- [`../documentation-index.md`](../documentation-index.md) - documentation index
- [`../README.md`](../README.md) - Documentation hub overview