commit

# Commit

Create a git commit with automatic precommit hook handling, test fixing, README updates, and API reference updates.

**Note:** Steps 5 and the API Reference Update Guidelines are specific to the Reflexio project. They are skipped automatically when the referenced paths do not exist.

## Workflow

1. **Check git status** - Run `git status` and `git diff --cached --name-only` to see staged/unstaged changes
2. **Sync AI instruction files (only if CLAUDE.md changed)** — Run `git diff --cached --name-only` and check if `CLAUDE.md` is in the staged changeset. If yes, copy CLAUDE.md content to GEMINI.md and AGENTS.md, then stage them. If CLAUDE.md is NOT staged, skip this step entirely — do not overwrite other instruction files that may have been intentionally edited independently.
3. **Stage files** - Add relevant untracked/modified files if needed. Do not modify or change gitignored files, such as `.env`. Never change `.env` file even if it is modified.
4. **Check README updates** - Run through the README Update Guidelines checklist below. If ANY criteria match, update README files before proceeding.
5. **Update API Reference docs (Reflexio-specific)** — If the files `reflexio/reflexio_client/reflexio/client.py` or `reflexio/reflexio_commons/reflexio_commons/api_schema/service_schemas.py` exist AND are in the staged changeset, update `reflexio/public_docs/api-reference/` (see API Reference Update Guidelines below). Otherwise skip.
6. **Run lint and type checks on staged Python files**
   a. Get the list of staged Python files:
      ```bash
      git diff --cached --name-only --diff-filter=ACMR -- '*.py'
      ```
      If no Python files are staged, skip this step entirely.
   b. **Ruff auto-fix**: Run `ruff check --fix <files>`. Re-stage any modified files with `git add <files>`.
   c. **Ruff format**: Run `ruff format <files>`. Re-stage any modified files with `git add <files>`.
   d. **Ruff remaining errors**: Run `ruff check <files>`. If any errors remain that ruff could not auto-fix, **read each error, understand the issue, and fix the code yourself**. Re-stage fixes. Do NOT proceed with unfixed ruff errors.
   e. **Pyright type check**: Run `pyright <files>`. If any type errors are reported, **read each error, understand the type issue, and fix the code yourself**. Re-stage fixes. Do NOT proceed with unfixed pyright errors.
   f. Get the list of staged TypeScript/JavaScript files:
      ```bash
      git diff --cached --name-only --diff-filter=ACMR -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.mts'
      ```
      If no TS/JS files are staged, skip steps 6g-6i entirely.
   g. **Biome auto-fix**: Run `npx biome check --write <files>` from the relevant project root
      (`reflexio/website/` or `reflexio/public_docs/` depending on file path).
      Re-stage any modified files with `git add <files>`.
   h. **Biome remaining errors**: Run `npx biome check <files>`.
      If any errors remain that Biome could not auto-fix, **read each error, understand the issue,
      and fix the code yourself**. Re-stage fixes. Do NOT proceed with unfixed Biome errors.
   i. **TypeScript type check**: Run `npx tsc --noEmit` from the relevant project root.
      If any type errors are reported, **read each error, understand the type issue,
      and fix the code yourself**. Re-stage fixes. Do NOT proceed with unfixed tsc errors.
7. **Attempt commit** - Run `git commit` which triggers precommit hooks
8. **Handle hook results**:
   - If hooks **modify files** (formatting, linting): Stage the modified files with `git add -u` and retry commit
   - If **unit tests fail**: Fix the failing tests, stage fixes, and retry commit
   - If hooks **pass**: Commit succeeds
9. **Do NOT push** - Only commit locally

## README Update Guidelines

Before committing, **always check** if README files need updates. Follow `how_to_write_readme.md` in the repo root.

**Step 1: Analyze changes with these commands:**
```bash
# See what files are being committed
git diff --cached --name-only

# See detailed changes
git diff --cached --stat

# For unstaged changes
git diff --name-only
```

**Step 2: Check if README update is REQUIRED** (update if ANY are true):
- [ ] New directory created (e.g., `services/email/`)
- [ ] New Python module/file added to existing component
- [ ] New API endpoint added
- [ ] New service or extractor added
- [ ] Architecture pattern changed
- [ ] Component relationships changed

If **none** of the above criteria match, skip README updates entirely and proceed to the next step.

**Pre-write criteria — before writing any README changes, confirm:**
1. Can an LLM currently find the right file with the existing README? If yes, no update needed.
2. Are there new files/directories that need documented paths?
3. Are new API endpoints to list?
4. Are there anti-patterns to highlight (NEVER/ALWAYS)?

Only proceed with the update if at least one criterion identifies a gap.

**Step 3: Update process:**
1. Identify affected component(s) from the file paths
2. Read existing README(s) in affected directories
3. Update component-level README first (e.g., `reflexio/server/README.md`)
4. Update main `README.md` if high-level structure changed
5. Stage README changes: `git add README.md src/*/README.md`

**Two-tier approach:**
- **Main Code Map** (`README.md`) - High-level overview of all components
- **Component Code Maps** (e.g., `reflexio/server/README.md`) - Detailed documentation

## API Reference Update Guidelines

When changes are made to the Reflexio client or service schemas, update the API reference documentation.

**Source files to watch:**
- `reflexio/reflexio_client/reflexio/client.py` - Client class methods
- `reflexio/reflexio_commons/reflexio_commons/api_schema/service_schemas.py` - Request/Response models and enums

**Documentation to update:**
- `reflexio/public_docs/api-reference/client.md` - Client method documentation
- `reflexio/public_docs/api-reference/schemas.md` - Schema/model documentation

**When