AGENTS.md git:20261008.ecc729eA

Immutable. This exact content never changes and is served at /api/v1/blob/0e036791ca037a7c.

# Repository Guidelines

## Project Shape

- TEA skills and the `bmod-tea` module record live in `skills/`; the knowledge base is `skills/bmod-tea/knowledge/`.
- Public documentation lives in `docs/`; the Starlight site consumes it through `website/`.
- GitHub Actions workflows live in `.github/workflows/`.
- Release metadata must stay synchronized across `package.json`, `package-lock.json`, `.claude-plugin/marketplace.json`, and `skills/bmod-tea/bmod.toml`.

## Common Commands

- `npm test`: full quality gate used before release. CI runs it in shards; the pre-commit hook does not, because the hook's budget is 30 seconds and anything slower belongs in CI.
- `npm run format:check`: Prettier check.
- `npm run lint`: ESLint check.
- `npm run lint:md`: markdownlint check.
- `npm run docs:validate-links`: docs link validation.
- `npm run docs:build`: full docs and site build.
- `npm run test:release-metadata`: package/lockfile/marketplace version sync check.

## Changelog Discipline

- For any user-facing change, documentation change, workflow/CI change, release behavior change, or bug fix, update `CHANGELOG.md` in the same PR.
- Put unreleased work under the top `## [Unreleased]` section using Keep a Changelog headings such as `Added`, `Changed`, `Fixed`, `Deprecated`, or `Removed`.
- Stable releases convert `[Unreleased]` into a dated version section on their own. The publish workflow runs `node tools/stamp-changelog.js` after the version bump and commits the result, so do not hand-write a `## [1.16.0] - YYYY-MM-DD` heading in a normal PR. Writing entries under `[Unreleased]` is the whole job.
- Keep the `## [Unreleased]` heading present. The stamping step targets it and fails the release if it is gone.
- Repairing history is the one case for editing a version section by hand, for example when an earlier release shipped without notes.

## PR Notes

- Mention validation commands actually run.
- For docs-only changes, at minimum run `npm run docs:validate-links`, `npm run lint:md`, and `npm run format:check`.
- For workflow or release changes, run `npm run format:check`, `npm run lint:md`, `npm run lint`, and `npm run test:release-metadata`.