docs-ssot docs.instructions.md

Documentation Rules for docs-ssot

SSOT Principle: Only Edit Source Files

This project generates documentation from source files. The pipeline is:

template/docs/**/*.md  +  template/*.tpl.md  +  docsgen.yaml
                          ↓
              docs-ssot build (make docs)
                          ↓
          README.md / AGENTS.md / CLAUDE.md

Generated Files — Never Edit Directly

The following are build artifacts and must NOT be modified:

• README.md
• AGENTS.md
• CLAUDE.md

If you need to change content in these files, find the source file under docs/ that contains that section and edit it there, then run make docs.

---

Source Files — Where to Make Changes

All documentation content lives under docs/. Edit files here:

Directory	Purpose
docs/01_project/	Project overview, vision, background
docs/02_product/	Product concept and feature descriptions
docs/03_architecture/	System architecture, pipeline, diagrams
docs/04_development/	Setup, testing, linting guides
docs/05_ai/	AI tool-specific instructions (Claude, Cursor, Codex, etc.)
docs/06_reference/	Commands reference, directory structure

Templates — Structure Only

Template files in template/ define document structure using include directives. Modify templates only to change document structure (add/remove/reorder sections), not content.

template/README.tpl.md
template/AGENTS.tpl.md
template/CLAUDE.tpl.md

---

Adding New Content

1. Create or edit the appropriate file under docs/.
2. If it's a new file, add an include directive in the relevant template/*.tpl.md:

   <!-- @include: docs/XX_category/new-file.md -->
   

3. Run make docs to regenerate output files.
4. Commit both the source file and regenerated outputs together.

---

Include Directive Format

Include directives follow the VitePress style:

<!-- @include: path/to/file.md -->