# 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](../README.md)** | File structure table + relevant section |
| 3 | **Update [docs/README.md](README.md)** | Add a one-line entry in the right table |

> [!IMPORTANT]
> A pull request or commit that adds a new script, module, or feature **without**
> updating **docs/README.md** and the root **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 tab or API route in `app_flask.py` | Yes — entry in `docs/app.md` |
| New CLI argument to an existing script | Yes — update the relevant doc |
| Bug fix with no API surface change | No (note in changelog if breaking) |
| Refactor with no API surface change | No |
| New environment variable / secret | Yes — `docs/configuration.md` |
| New dependency in `requirements.txt` | Yes — note in relevant doc + README |

---

## Doc file conventions

- All documentation lives in **`docs/`**. The **only** markdown file at the repository root is **`README.md`** (GitHub project landing page).
- Prefer **lowercase with underscores**: `docs/lifestack_env.md`, `docs/kaggle_train.md`.
- Promotional or Hugging Face collateral also lives under `docs/` (e.g. `blog.md`, `model_card.md`).
- Each doc starts with a `# Title` heading and a one-line summary.
- Code blocks must have a language tag (` ```python `, ` ```bash `).

---

## Checklist (copy into PR or commit message)

```
Docs checklist:
[ ] docs/<topic>.md created or updated
[ ] docs/README.md updated with new entry
[ ] README.md file structure / quickstart updated (if needed)
```

---

## Docs folder layout (representative)

```
docs/
├── README.md              ← Master index (always update for new docs)
├── CONTRIBUTING.md        ← This file
├── training_guide.md
├── train_trl.md
├── configuration.md
├── reward.md
├── lifestack_env.md
├── task.md
├── memory.md
├── conflict_generator.md
├── eval.md
├── scripts.md
├── app.md
├── DEPLOYMENT.md
├── blog.md
├── model_card.md
├── mentor_pitch.md
├── implementation_summary.md
└── kaggle_train.md
```

---

## Commit message format

```
<type>: <short description>

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

Docs checklist: all items updated
```

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