Orientation

Read these in order. Together they give you the full picture.

1. Compass — top-level map of doc/. Tells you what every folder is for and how everything fits together.
2. Glossary — what we mean by task, story, sprint, version, capture, function, etc. Every term that appears throughout the docs is defined here.
3. Product identity — what ORE Studio is and is not. Read once; refer back to it whenever you wonder whether a candidate idea is in scope.
4. Agile — how the rolling work is organised. From here you can dive into Versions (composition tree), the Product backlog (ideas not yet in a sprint), or the agile process (how a sprint opens, runs, and closes).

Once those are read, you have the full picture. Browse Compass for the secondary trees (Knowledge, Recipes, Modeling).

You probably want one of:

• A term's meaning → Glossary. Every load-bearing word in the system is defined there with a stable id-link.
• A specific sprint, story, or task → walk down from Versions: version → sprint → story → task. Or grep by tag — every doc carries a :filetags: with its ancestor slugs, so grep -lR ":sprint_15:" doc/agile/versions/ finds every task in sprint 15.
• A how-to ("how do I X?") → Recipes. Each recipe answers one NLP question and carries the executable shell to do it.
• A domain or architecture topic → Knowledge. Single-topic pages grouped by area (Domain / Architecture / Security / Documentation).
• A component or file in the codebase → Modeling (UML overview) or Doxygen (low-level C++ API).
• Pre-sprint ideas → Product backlog, split by horizon (next / deferred).
• Historical design documents → Plans, legacy pre-sprint plans kept for context on past decisions.

Start with LLM instructions — it is the mandatory session entry point with all non-negotiable rules. See LLM Configuration and Artefacts for the map of skills, memory, and settings under doc/llm/.

Before generating any document, read the contract:

1. Document types — the frontmatter every doc must carry, per-type required sections, the title-prefix convention for tasks / stories, and the index-page convention (blurb before first headline, See also is external-only).
2. Lifecycle — the TODO state machine (DISCOVERED → BACKLOG → STARTED → BLOCKED → DONE / ABANDONED) applied uniformly across every stateful type.
3. Cybernetic levels — which system (S1 → S5) owns which decisions. Every phase in the agile process is annotated with its owning system; respect that ownership in your edits.
4. Glossary — load it into context so the terms you encounter later resolve.

The ores.compass tool (./projects/ores.compass/compass.sh) is your primary quality-of-life aid inside this repository. It was designed explicitly for both human contributors and LLM agents: humans use it to avoid manual branch/file creation; LLMs use it to resolve doc references, discover existing recipes, and scaffold artefacts with correct frontmatter instead of guessing paths or UUIDs. When in doubt, reach for compass before reaching for grep or find.

When you need to find something in the doc graph:

• How do I find docs matching a pattern? — compass list over regex, tag, #+type:, or path prefix. Faster than grep -r and it understands the doctype taxonomy.
• How do I show a doc by UUID? — compass show prints a doc's blurb, outgoing links, and incoming links. Accepts UUID prefixes and resolves heading-level anchors (e.g. glossary entries).
• The full set of doc-graph operations lives in the Documentation recipes inventory.

When you need to create a doc:

• See How do I create a new doc? to scaffold every new document — never hand-write frontmatter. The codegen mints the :ID:, applies the per-type prefix on the title, fills in dates, and produces the required skeleton.
• For recipe-shaped docs specifically, see How do I create a recipe? — the conventions on filename = title = question, executable babel blocks, and inventory wiring.

Skim Compass for orientation if you have not yet seen it.

• Developer Links — external resources: GitHub, Doxygen, Discord, CDash, and CI.
• Compass — top-level map of doc/.