The project's docs
Mahou has no shared knowledge base about a project. The project keeps one itself, in a folder it owns, usually docs/. Skills bring the process for writing into it; the project decides the structure. A skill that contains a string which would be wrong in a different repository is a bug. That is why no skill carries a template body.
Finding the folder
In this order:
.mahou/basics.md, when it names one.- A section in the project's
CLAUDE.md pointing at one. The one mahou:init writes is ## Docs, but any section naming a documentation folder counts.
- A
docs/ directory holding a README.md.
When none of these exists, say the project's docs are not set up and mention mahou:init. Never create the folder as a side effect of another skill.
What the structure is made of
These are the parts you may assume exist. What each one is called, contains or looks like is the project's, and you read it rather than assume it.
- The charter is the
README.md at the folder's root. It says what each folder holds, how files are named, what frontmatter they carry, how a note is written, and how the indexes work.
- Each folder's index is its own
README.md. It is either a hand-kept table, where a note joins by getting a row, or generated (an Obsidian base querying a tag), where a note joins by existing with the right tag and a wrong tag drops it out silently.
- Templates, when the project has them, live where the charter says, usually
_templates/. A note is created from the template for its kind; when there is none, from the closest existing note in that folder, and you say which.
- Notes explain how a part is, in the present tense. Some projects also keep records (a quest log, a decision register) that say what was tried or intended; the charter says which folders hold which, and the note-writing rules do not govern records.
How a note is shaped
The project's note template decides this, and the template is the project's to edit, so read it rather than this description. The shape mahou:init seeds is:
- An overview first. What the part is, what it is responsible for, the principles its design follows. A reader can stop after it and still know what the part does.
- Then a menu of sections, not a fixed shape and not a closed list. The template lists the sections that have been useful (architecture, modeling, flow, states, rules, what it exposes, implementation details, sources), each with when it applies and the diagram that fits it. A note keeps the ones its subject needs, drops the rest, and adds one the menu lacks when the subject asks for it. Leaving a section out is never a defect, and neither is adding one. Worth reporting is a new section that duplicates a menu section under another name, or one that holds what the template routes to a callout.
- Order for the reader, not for the menu. Sections go in whatever order makes the note easiest to follow, usually the thing a reader has to hold first.
- Reasoning, failure modes and rejected alternatives are callouts beside the mechanism they belong to, in the kinds the charter names. There is no reasoning section and no edge-cases section. An edge case goes in the prose of the section it belongs to, or in a callout.
- Headings carry an emoji that names the subject at a glance, when the charter says so. The template carries the usual ones; a section the note adds picks its own.
The rule
Read the charter and the target folder's README before writing or judging a line. Where the project differs from anything a skill or an agent sketches as an example, the project is right. If the charter and CLAUDE.md disagree, the charter is right, and you fix both.
1---2name: docs3description: Loaded by skills and agents that read or write the project's own documentation. Carries how to find the docs folder, what its structure is made of, and the rule that the project's charter wins over anything a skill assumes.4---56# The project's docs78Mahou has no shared knowledge base about a project. The project keeps one itself, in a folder it owns, usually `docs/`. Skills bring the process for writing into it; the project decides the structure. A skill that contains a string which would be wrong in a different repository is a bug. That is why no skill carries a template body.910## Finding the folder1112In this order:13141. `.mahou/basics.md`, when it names one.152. A section in the project's `CLAUDE.md` pointing at one. The one mahou:init writes is `## Docs`, but any section naming a documentation folder counts.163. A `docs/` directory holding a `README.md`.1718When none of these exists, say the project's docs are not set up and mention mahou:init. Never create the folder as a side effect of another skill.1920## What the structure is made of2122These are the parts you may assume exist. What each one is called, contains or looks like is the project's, and you read it rather than assume it.2324- **The charter** is the `README.md` at the folder's root. It says what each folder holds, how files are named, what frontmatter they carry, how a note is written, and how the indexes work.25- **Each folder's index** is its own `README.md`. It is either a hand-kept table, where a note joins by getting a row, or generated (an Obsidian base querying a tag), where a note joins by existing with the right tag and a wrong tag drops it out silently.26- **Templates**, when the project has them, live where the charter says, usually `_templates/`. A note is created from the template for its kind; when there is none, from the closest existing note in that folder, and you say which.27- **Notes explain how a part is**, in the present tense. Some projects also keep **records** (a quest log, a decision register) that say what was tried or intended; the charter says which folders hold which, and the note-writing rules do not govern records.2829## How a note is shaped3031The project's note template decides this, and the template is the project's to edit, so read it rather than this description. The shape mahou:init seeds is:3233- **An overview first.** What the part is, what it is responsible for, the principles its design follows. A reader can stop after it and still know what the part does.34- **Then a menu of sections, not a fixed shape and not a closed list.** The template lists the sections that have been useful (architecture, modeling, flow, states, rules, what it exposes, implementation details, sources), each with when it applies and the diagram that fits it. A note keeps the ones its subject needs, drops the rest, and adds one the menu lacks when the subject asks for it. Leaving a section out is never a defect, and neither is adding one. Worth reporting is a new section that duplicates a menu section under another name, or one that holds what the template routes to a callout.35- **Order for the reader, not for the menu.** Sections go in whatever order makes the note easiest to follow, usually the thing a reader has to hold first.36- **Reasoning, failure modes and rejected alternatives are callouts** beside the mechanism they belong to, in the kinds the charter names. There is no reasoning section and no edge-cases section. An edge case goes in the prose of the section it belongs to, or in a callout.37- **Headings carry an emoji** that names the subject at a glance, when the charter says so. The template carries the usual ones; a section the note adds picks its own.3839## The rule4041Read the charter and the target folder's README before writing or judging a line. Where the project differs from anything a skill or an agent sketches as an example, the project is right. If the charter and `CLAUDE.md` disagree, the charter is right, and you fix both.
asermax