# Contributing to LifeStack

This document defines the **documentation rule** for the project.  
**Nothing ships without its matching doc entry.**

---

## The Rule: Doc-First Development

Every change that adds, removes, or significantly modifies a feature must include
**all three** of the following before the commit is made:

| # | Action | Where |
|---|---|---|
| 1 | **Create or update a doc file** | `docs/<topic>.md` |
| 2 | **Update README.md** | File Structure table + relevant section |
| 3 | **Update `docs/INDEX.md`** | Add a one-line entry for the new doc |

> [!IMPORTANT]
> A pull request / commit that adds a new script, module, or feature **without**
> updating `docs/INDEX.md` and `README.md` is considered incomplete and should
> not be merged.

---

## What Counts as "a Feature"

| Change type | Doc required? |
|---|---|
| New Python module (`core/`, `agent/`, `intake/`) | ✅ Yes — `docs/<module>.md` |
| New script (`scripts/*.py`) | ✅ Yes — entry in `docs/scripts.md` |
| New Gradio tab in `app.py` | ✅ Yes — entry in `docs/app.md` |
| New CLI argument to an existing script | ✅ Yes — update relevant doc |
| Bug fix with no API surface change | ❌ No (but update changelog if breaking) |
| Refactor with no API surface change | ❌ No |
| New environment variable / secret | ✅ Yes — update `docs/configuration.md` |
| New dependency in `requirements.txt` | ✅ Yes — note in relevant doc + README |

---

## Doc File Conventions

- All docs live in `docs/`. No `.md` files at repo root except `README.md` and this file.
- File names are lowercase with underscores: `docs/lifestack_env.md`, `docs/eval.md`.
- Each doc starts with a `# Title` h1 and a one-line summary.
- Use `## Overview`, `## Usage`, `## API / Parameters`, `## Examples` sections.
- Code blocks must have a language tag (` ```python `, ` ```bash `).

---

## Checklist (copy into every PR / commit message)

```
Docs checklist:
[ ] docs/<topic>.md created or updated
[ ] docs/INDEX.md updated with new entry
[ ] README.md File Structure table updated
[ ] README.md Quickstart / relevant section updated (if CLI changed)
```

---

## Docs Folder Structure

```
docs/
├── INDEX.md              ← Master index of all docs (ALWAYS update this)
├── CONTRIBUTING.md       ← This file — the rule
├── lifestack_env.md      ← core/lifestack_env.py reference
├── reward.md             ← core/reward.py reference
├── task.md               ← core/task.py schema reference
├── memory.md             ← agent/memory.py reference
├── conflict_generator.md ← agent/conflict_generator.py reference
├── app.md                ← app.py Gradio interface reference
├── eval.md               ← scripts/eval.py reference
├── train_trl.md          ← scripts/train_trl.md reference
├── scripts.md            ← All other scripts reference
└── configuration.md      ← Env vars, secrets, openenv.yaml
```

---

## Commit Message Format

```
<type>: <short description>

- <file changed>: <what changed>
- docs/<doc>.md: <created|updated>
- docs/INDEX.md: <added entry for X>
- README.md: <updated section Y>

Docs checklist: ✅ all three updated
```

Types: `feat` | `fix` | `refactor` | `docs` | `test` | `chore`