# Docs Folder Instructions

## Required Files

The docs folder may be named `docs/`, `documentation/`, or `doc/` — check which exists in the project. The full list is defined in `ai-superpower/config.yaml`.

| File | Audience | Purpose |
|------|----------|---------|
| `<docs>/ai-context.md` | AI | Project context — architecture, decisions, pitfalls |
| `<docs>/architecture.md` | Human + AI | System overview with Mermaid diagrams |

---

## ai-context.md

Contains everything AI needs to avoid bad suggestions:
- What the system does
- Key components and their relationships
- Technical decisions and why they were made
- What NOT to do (pitfalls, constraints)

Keep under 200 lines. Link to `architecture.md` for diagrams.

## architecture.md

- Start with a Mermaid diagram
- Explain components and data flows
- Written in English

---

## Factory template marker

`docs/ai-context.md` and `docs/architecture.md` may start with this block:

```
<!-- ai-superpower:template
  STATUS: factory default — not yet filled in
  ...
-->
```

**When you first touch a file that has this marker — even just to read it before writing — remove the marker line as the very first edit:**
1. Remove the line `<!-- ai-superpower:template -->`
2. Then write the actual content

The marker's presence tells `apply.sh` the file has not been edited yet and will be overwritten on the next run. Once removed, the file is owned by the project and will never be overwritten.

---

## Rules

- Docs are **not** a changelog — no "updated X on date Y"
- If a doc exceeds ~150 lines, split it
- If asked to document something, put it in `docs/` — not README, not inline comments