# Contributing

Lessons, translations, fixes, outputs — all welcome. One contribution per pull
request keeps reviews fast and lets contributor counts and credit work
correctly.

## Important: the README and ROADMAP feed the website

`site/build.js` parses `README.md`, `ROADMAP.md`, and `glossary/terms.md` to
generate `site/data.js`. Two patterns must stay intact in any pull request that
touches those files:

- Phase headers in either `### Phase N: Name \`X lessons\`` form or
  `<details><summary><b>Phase N — Name</b> ... <code>X lessons</code> ... <em>Description</em></summary>` form.
- Lesson tables with the column shape `| # | Lesson | Type | Lang |` (or
  `| # | Project | Combines | Lang |` for capstone tables). The `Lang` column
  accepts plain text (`Python, TypeScript`) or the legacy emoji flags
  (`🐍 🟦 🦀 🟣 ⚛️`); both are parser-equivalent.
- ROADMAP status glyphs (`✅`, `🚧`, `⬚`) on phase headers and lesson rows.
  Do not replace them with text — the parser keys off the exact characters.

Run `node site/build.js` after editing those files; `git diff site/data.js`
should show only the timestamp change if your edit was structural-safe.

## Ways to Contribute

### 1. Add a New Lesson

Each lesson lives in `phases/XX-phase-name/NN-lesson-name/` with this structure:

```
NN-lesson-name/
├── code/           At least one runnable implementation
├── notebook/       Jupyter notebook for experimentation (optional)
├── docs/
│   └── en.md       Lesson documentation (required)
└── outputs/        Prompts, skills, or agents this lesson produces (if applicable)
```

**Lesson doc format** (`en.md`):

```markdown
# Lesson Title

> One-line motto — the core idea in one sentence.

## The Problem

Why does this matter? What can't you do without this?

## The Concept

Explain with diagrams, visuals, and intuition. Code comes later.

## Build It

Step-by-step implementation from scratch.

## Use It

Now use a real framework or library to do the same thing.

## Ship It

The prompt, skill, agent, or tool this lesson produces.

## Exercises

1. Exercise one
2. Exercise two
3. Challenge exercise
```

### 2. Add a Translation

Create a new file in any lesson's `docs/` folder:

```
docs/
├── en.md    (English — always required)
├── zh.md    (Chinese)
├── ja.md    (Japanese)
├── es.md    (Spanish)
├── hi.md    (Hindi)
└── ...
```

Keep the same structure as the English version. Translate content, not code.

### 3. Add an Output

If a lesson should produce a reusable prompt, skill, agent, or MCP server:

1. Create it in the lesson's `outputs/` folder
2. Add a reference in the top-level `outputs/` index

**Prompt format:**

```markdown
---
name: prompt-name
description: What this prompt does
phase: 14
lesson: 01
---

[System prompt or template here]
```

**Skill format:**

```markdown
---
name: skill-name
description: What this skill teaches
version: 1.0.0
phase: 14
lesson: 01
tags: [agents, loops]
---

[Skill content here]
```

### 4. Fix Bugs or Improve Existing Lessons

- Fix code that doesn't run
- Improve explanations
- Add better diagrams
- Update outdated information

### 5. Add Exercises or Projects

More exercises and projects are always welcome, especially ones that connect multiple phases.

## Guidelines

- **Code must run.** Every code file should execute without errors with the listed dependencies.
- **No comments in code.** Code should be self-explanatory. Use the docs for explanation.
- **Best language for the job.** Don't force Python where TypeScript or Rust is the better choice.
- **Build from scratch first.** Always implement the concept from first principles before showing the framework version.
- **Keep it practical.** Theory serves practice, not the other way around.
- **No AI slop.** Write like a human. Be direct. Cut filler.

## Pull Request Process

1. Fork the repository
2. Create a feature branch (`git checkout -b add-lesson-phase3-gradient-descent`)
3. Make your changes
4. Ensure all code runs
5. Submit a pull request with a clear description

## Code of Conduct

See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Be kind, be helpful, be constructive.

## Style

- Direct prose. Cut filler. Match the manual's tone, not marketing copy.
- No decorative emojis in headings. Lang column emoji flags are the one
  exception and only because the parser maps them.
- Code runs as-is with the dependencies listed in the lesson.
- Build from scratch first, framework second.
