Documentation templates
Table of Contents
This page is the literate source for the doc facet of the
codegen template library. Each section documents one template and
holds its source in a mustache block tangled to the sibling
.mustache file consumed by generator.py. The .mustache files are
generated artefacts — edit this document, then run the tangle
(compass build --direct tangle_codegen_templates or
projects/ores.lisp/src/ores-build-codegen-templates.el directly).
Output paths and profile membership come from
facet_catalogue.org.
Summary
Twenty org-document scaffolds — one per compass add /
doc_generate document type: the agile composition tree (version,
sprint, story, task), the knowledge family (knowledge, recipe,
runbook, manual, component, investigation, product identity), the
workflow docs (capture, memory, release notes, skill), the codegen
model formats (entity_org, field_group, table, junction, lookup_entity,
service_registry, dataset overview), and this
library's own facet / facet_group types. No profile involvement:
doc_generate.py's TYPE_TO_TEMPLATE maps type → template directly.
The doc facet
These templates are self-hosting: they are mustache sources that
render to org-mode documents, and they are themselves owned by an
org-mode document (this one). The model element is doc_generate's
variables dict — id, title, description, filetags, date,
state, plus type-specific extras (parent links for the agile tree,
recipe section bodies, memory subtype fields, component name/brief,
dataset metadata, facet_group). The rendered artefacts follow the
project document contract: :PROPERTIES:/:ID: drawer, #+keyword
frontmatter, glossary-linked blurb, skeleton sections.
Mustache incantations
doc_generate renders with pystache.Renderer(escape=identity), so
double-stache is effectively triple-stache here — titles and bodies
land verbatim, and HTML-escaping never applies. List sections
({{#acceptance}}, {{#see_also}}) render repeatable bullets, with
{{#has_acceptance}}-style guards selecting placeholder text when
empty. doc_facet.org.mustache contains a delimiter swap
({{=<< >>}} … =) so the GENERATED FILE header example in
its output survives rendering as literal mustache — the same trick
this library uses one level up.
Archetypes
| Archetype | Description |
|---|---|
| doc_capture.org.mustache | Product-backlog capture: What/Why skeleton plus the bucket-aware blurb ({{bucket}} names inbox/next/deferred). |
| doc_component.org.mustache | Component component_overview.org: #+component_name / #+brief keywords read back by codegen, plus the standard overview sections. |
| doc_dataset.org.mustache | Seeder dataset page: #+dataset_name/version/type and source_methodology metadata for ores.seeder datasets. |
| doc_entity_org.org.mustache | Literate codegen entity model (the org-migration story's format): frontmatter plus the section/table skeleton the org_loader parses. |
| doc_facet_group.org.mustache | This library's group doc scaffold: generated * Facets inventory note and shared-conventions section. Self-hosting. |
| doc_facet.org.mustache | This library's facet doc scaffold: #+facet_group keyword, tangle-workflow blurb, and the per-template section guidance. Self-hosting. |
| doc_field_group.org.mustache | Codegen field-group model (*_field_group.org suffix drives loader dispatch); carries #+brief. |
| doc_junction.org.mustache | Codegen junction (join-table + C++) model: Left/Right FK sections plus SQL/Repository/C++ skeletons. |
| doc_lookup_entity.org.mustache | Codegen batch-loaded lookup-entity: frontmatter flags + Primary key + Columns + Artefact indexes. |
| doc_service_registry.org.mustache | Codegen service-registry: one section per service with psql_var/env_key/iam_role PROPERTIES and DML-prefix list. |
| doc_table.org.mustache | Codegen SQL-only table (*_table.org suffix): Primary key, Columns, Validation function, Insert trigger. |
| doc_investigation.org.mustache | Investigation doc with the Investigation: title prefix and findings skeleton. |
| doc_knowledge.org.mustache | Generic knowledge page: Summary / Detail / See also. |
| doc_manual.org.mustache | User-manual chapter under doc/manual/user_guide/. |
| doc_memory.org.mustache | Project memory: #+memory_subtype plus statement / why / how-to-apply one-shot body fields. |
| doc_product_identity.org.mustache | Product-identity page skeleton. |
| doc_recipe.org.mustache | Recipe with Question / Answer / Script / Tested-by sections, each renderable verbatim from flags (--question, --answer, …). |
| doc_release_notes.org.mustache | Sprint release-notes page generated at sprint close. |
| doc_runbook.org.mustache | Runbook: Goal / Preconditions / Steps / Postconditions composition of recipes and skills. |
| doc_skill.org.mustache | Claude Code skill SKILL.org (tangled by the skills build into .claude/skills/). |
| doc_sprint.org.mustache | Sprint page: Mission, Status table (state STARTED), themed * Stories tables. |
| doc_story.org.mustache | Story page: Goal, Status table, Acceptance, * Tasks table compass wires rows into, Decisions, Out of scope. |
| doc_task.org.mustache | Task page: Goal, Status, Acceptance, transient Plan, Notes, * PRs and * Review tables, Result. #+branch: / #+pr: drive compass pr matching. |
| doc_version.org.mustache | Version page topping the agile composition tree. |
See also
- (Parent template group doc:
<group>_group.org.) - Codegen template library — the groups overview.
- Facet — the MASD concept these templates project.
- Documentation facet — the facet's modeling reference.
- Applied MASD — the facet catalogue and codegen routes.
- facet_catalogue.org — profile → template/output mapping.