Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

docs/ - Documentation

Documentation hub for the Research Project Template

Forking the template? Start here: the code and prose exemplars each ship a 5-minute walkthrough at projects/templates/template_code_project/docs/forking_guide.md (numerical research) and projects/templates/template_prose_project/docs/forking_guide.md (editorial review). The Active Inference exemplar is documented at projects/templates/template_active_inference/README.md. The AutoResearch exemplar is documented at projects/templates/template_autoresearch_project/README.md. The meta-template exemplar is documented at projects/templates/template_template/README.md. The drift checker that gates your fork against the template's contract is scripts/audit/check_template_drift.py (run uv run python scripts/audit/check_template_drift.py from the repo root).

Quick Reference: Documentation Index | How To Use | Architecture | Publication Runbook | FAQ | GitHub / CI | Canonical Facts

Purpose

The docs/ directory contains project documentation organized by purpose and audience. This is the central hub for all project documentation beyond code comments.

projects/ is a rotating set: directories are promoted, archived, or moved to projects/working/ over time. The only workspace guaranteed to stay in the tree as the control-positive layout for paths and commands is projects/templates/template_code_project/. For the current discovered list, link _generated/active_projects.md—do not treat any other sibling name as permanent.

Machine-generated snippets (including that authoritative list) live under _generated/. Human-written pages should link there instead of copying project rosters.

Evidence and freshness

Documentation is a view over source-owned facts, not a second place to maintain them. Use the narrowest authoritative source for each kind of claim:

Claim type Authoritative source Documentation rule
Runtime behavior, defaults, and precedence Implementation, schema, and tests Verify the documented command or code path; do not infer behavior from an older guide.
Repository counts, public roster, coverage, and stage tables _generated/ and its named producers Link the generated artifact; do not copy volatile literals into prose.
Manuscript metrics and statistical results Project analysis outputs → output/data/manuscript_variables.json → hydrated output/manuscript/ Inject {{TOKEN}} values at render time; never hand-copy result numbers into manuscript source.
Scholarly claims Primary sources, project bibliography, and claim/evidence registries where present Match the strength of the prose to the design and evidence; distinguish observation, association, prediction, and causation.
Figures, captions, and accessibility text The same analysis artifact plus figure/artifact registries Keep plot values, caption statistics, labels, units, uncertainty, provenance, and alt text consistent and source-bound.
Publication or release status Fresh local gates, hosted CI, publication receipts, and the remote commit Report these separately; a green local check is not proof of publication or remote synchronization.

The detailed authoring rules live in rules/documentation_standards.md, manuscript syntax in guides/manuscript-semantics.md, and the reusable deep-review prompt in prompts/comprehensive-assessment/references/comprehensive-research-software-manuscript-review-prompt.md.

Documentation Navigation Map

graph TD
    subgraph EntryPoints["Entry points"]
        README[README.md<br/>Project Overview]
        DOC_INDEX[documentation-index.md<br/>Full Index]
        HOW_TO[core/how-to-use.md<br/>Usage Guide<br/>12 Skill Levels]
    end

    subgraph CoreDocs["Core documentation"]
        ARCH[core/architecture.md<br/>System Design]
        WORKFLOW[core/workflow.md<br/>Development Process]
    end

    subgraph SkillLevels["Skill-based learning"]
        L1[guides/getting-started.md<br/>Levels 1-3: Beginner]
        L2[guides/figures-and-analysis.md<br/>Levels 4-6: Intermediate]
        L3[guides/testing-and-reproducibility.md<br/>Levels 7-9: Advanced]
        L4[guides/extending-and-automation.md<br/>Levels 10-12: Expert]
    end

    subgraph Operational["Operational"]
        PIPELINE[RUN_GUIDE.md<br/>Pipeline Orchestration]
        BUILD[operational/build<br/>uv, CI/CD]
        TROUBLESHOOT[operational/troubleshooting<br/>Fix Issues]
        CONFIG[operational/config<br/>Settings and Performance]
        LOGGING[operational/logging<br/>Logging System]
    end

    subgraph Reference["Reference"]
        FAQ[reference/faq.md<br/>Common Questions]
        CHEATSHEET[reference/quick-start-cheatsheet.md<br/>Command Reference]
        API[reference/api-reference.md<br/>Unified API Docs]
        RULES[rules/AGENTS.md<br/>Development Standards]
    end

    README --> DOC_INDEX
    README --> HOW_TO
    DOC_INDEX --> CoreDocs
    DOC_INDEX --> SkillLevels
    DOC_INDEX --> Operational
    DOC_INDEX --> Reference

    HOW_TO --> L1
    L1 --> L2
    L2 --> L3
    L3 --> L4

    ARCH --> WORKFLOW

    PIPELINE --> BUILD
    BUILD --> TROUBLESHOOT
    TROUBLESHOOT --> CONFIG

    FAQ --> CHEATSHEET
    CHEATSHEET --> API
    API --> RULES
Loading

Directory Structure

Directory Purpose Key Contents
core/ Essential documentation how-to-use.md, architecture.md, workflow.md
guides/ Skill-level guides (1-12) getting-started, figures-and-analysis, testing, extending
architecture/ System design two-layer-architecture.md, thin-orchestrator, decision-tree
usage/ Content authoring & patterns examples, markdown guide, style guide, visualization
operational/ Operational workflows build/, config/, logging/, troubleshooting/
maintenance/ Long-horizon ops private-projects-repo, ci-local, regression, archival, bundle
reference/ Reference materials api-reference, faq, glossary, cheatsheet, workflows
modules/ Infrastructure modules modules-guide, scientific simulation, pdf-validation, guides/
development/ Development & contribution contributing, security, roadmap, testing/ sub-folder
best-practices/ Best practices version-control, migration, multi-project, backup-recovery
prompts/ AI prompt templates (see prompts/AGENTS.md) manuscript, registry cross-refs, literature synthesis, code, test, feature, refactor, docs, infra, validation, assessment
security/ Security & provenance steganography, hashing, secure execution
rules/ Project Rules AGENTS, README, testing, manuscript, etc.
audit/ Generated point-in-time audit records filepath audit snapshot and its producer contract
plans/ Active repo-wide handoffs scoped plans with acceptance lines; completed history stays in git
images/ Documentation-only visual assets small, public, referenced diagrams or screenshots
streams/ Livestream & talk notes timestamped session notes tied to releases or papers
_generated/ Generated facts and indexes counts, public roster, coverage/status evidence, architecture, publication records, skills index

Quick Navigation

New Users Start Here

  1. ../README.md - Project overview
  2. core/how-to-use.md - Usage guide
  3. guides/getting-started.md - Getting started (Levels 1-3)
  4. reference/faq.md - Common questions

Creating a New Project

  1. guides/new-project-setup.md - Complete setup checklist with all pitfalls
  2. guides/manuscript-semantics.md - Canonical manuscript syntax (citations, cross-references, sections, {{TOKEN}} substitution) shared by all public template exemplars
  3. architecture/thin-orchestrator-summary.md - Script pattern

Developers Start Here

  1. core/architecture.md - System design overview
  2. architecture/two-layer-architecture.md - Full architecture guide
  3. architecture/thin-orchestrator-summary.md - Pattern details
  4. core/workflow.md - Development process
  5. development/contributing.md - How to contribute

Quick Links

Need Document
Get started core/how-to-use.md
Create a new project guides/new-project-setup.md
Understand design architecture/two-layer-architecture.md
See examples usage/examples.md
Find answers reference/faq.md
System reference (PAI) PAI.md
Cloud deployment guide CLOUD_DEPLOY.md
Fix an issue operational/troubleshooting/
Contribute development/contributing.md
Report security issue development/security.md
Understand modules modules/modules-guide.md
Publish a project guides/publication-runbook.md
Best practices best-practices/best-practices.md
Review accessibility accessibility.md
Security policies security/README.md
Validate docs ../scripts/audit/lint_docs.py

Documentation verification

Run these from the repository root after changing documentation or a producer that feeds it:

uv run python scripts/audit/lint_docs.py --json --repo-root .
uv run python scripts/audit/audit_documentation.py --format markdown
uv run python scripts/audit/check_template_drift.py --strict
uv run python scripts/docgen/counts.py --check
uv run python scripts/docgen/exemplar_roster.py --check
uv run python scripts/docgen/status_evidence.py --check
uv run python scripts/docgen/api_reference.py --check
uv run python -m infrastructure.skills check
uv run python -m infrastructure.skills check-contracts

lint_docs.py and the generated-file checks are blocking correctness checks. audit_documentation.py is a broad RedTeam inventory whose advisories require review and disposition; its raw count is not itself a release verdict.

Topic routing (canonical → deep dives)

Topic Start here Deep dives
Pipeline ops RUN_GUIDE.md operational/pipeline-control.md, operational/runbook.md
Methods orchestration guides/methods-orchestration.md architecture/thin-orchestrator-summary.md, RUN_GUIDE.md
Agent code navigation guides/codegraph-local.md, guides/leann-local.md modules/guides/project-module.md, architecture/thin-orchestrator-summary.md
Logging operational/logging/output-design.md operational/logging/python-logging.md, operational/logging/bash-logging.md (operational scripts only)
Secure / steganography guides/secure-research-guide.md → security/README.md security/secure_execution.md, modules/guides/steganography-module.md
Literature search guides/literature-workflow-guide.md core/literature-data-flow.md, modules/literature-search-and-references.md, streams/inferant-stream-019-literature-search.md (historical)
Publication guides/publication-runbook.md guides/publishing-guide.md, guides/zenodo-doi-strategy.md, modules/guides/publishing-module.md
Development rules rules/README.md
Session notes (streams) streams/README.md

See Also