AGENTS.md git:20260625.a89ce07A

Immutable. This exact content never changes and is served at /api/v1/blob/266bb26285e0db3b.

# AGENTS.md

## Repository Rules

- Do not proactively use browser-use or browser automation unless the user asks for it.
- Use subagents when they can safely parallelize discovery or verification without losing repository context.
- Branch names, commit messages, and PR titles must follow Conventional Commits semantics.
- Commit messages must at least use `type(scope): subject`, for example `feat(cli): add workflow recipes`.
- Use these commit types: `fix`, `feat`, `docs`, `test`, `refactor`, and `chore`.
- Use `!` only for intentional breaking changes.
- Keep PR scope focused, self-assign issues and PRs, include verification results, and explicitly call out generated files, GraphQL codegen, or DB baseline updates when present.

## Lathe And Generated Files

This repository is a codegen wrapper around Mosoo API specs and Lathe. Do not blindly edit Lathe-generated outputs to fix behavior, docs, examples, or command metadata.

- Treat `internal/generated/**`, `cmd/mosoo/cli.yaml`, `specs/sources.yaml`, and `publish/skills/mosoo/references/cli/catalog.md` plus `publish/skills/mosoo/references/cli/modules/*.md` as generated outputs.
- Prefer changing the source of generation, then regenerate with the existing pipeline.
- For command help, examples, notes, prerequisites, and known errors, use the overlay pipeline: update `scripts/render-overlays.ts` and/or the relevant `overlays/*.yaml` source path, then run the build pipeline.
- `publish/skills/mosoo/references/cli.md` is hand-maintained. It is the right place for high-level CLI workflow guidance that should not be generated from Lathe.
- If a required change cannot be expressed through specs, overlays, `cli.yaml`, or existing scripts, first inspect Lathe's supported extension points before editing generated files directly.
- Generated diffs are acceptable only when they are the intentional output of updated specs, overlays, scripts, or Lathe configuration. Do not include incidental generated churn in unrelated PRs.

## Lathe Usage In This Repo

This repo pins Lathe through `go.mod` and builds a repo-local binary at `.cache/bin/lathe`. Do not depend on a globally installed `lathe` from `PATH`.

- Build the local Lathe tool with `make tools`.
- The normal repo flow is `make build`, not a bare `lathe bootstrap`.
- `make build` exports Mosoo specs, renders `specs/sources.yaml`, renders `overlays/*.yaml`, runs Lathe codegen, renders published CLI references, and builds `bin/mosoo`.
- The Lathe command used by the build is:

```sh
.cache/bin/lathe codegen \
  -sources specs/sources.yaml \
  -cache .cache \
  -overlay overlays
```

`cli.yaml` sets `skill.root: .cache/lathe-skill`, so Lathe writes the generated full Skill to `.cache/lathe-skill/mosoo`. `scripts/render-publish-skill.ts` then copies only the generated `references/catalog.md` and `references/modules/*.md` into `publish/skills/mosoo/references/cli/`.

Lathe's relevant commands and flags:

- `lathe specsync`: sync pinned upstream API specs into the local cache.
- `lathe codegen`: generate runtime command specs and optional Skill files.
- `lathe bootstrap`: equivalent to `lathe specsync` plus `lathe codegen`; avoid using it directly here unless you have checked it matches the Makefile pipeline.
- `lathe version`: print version information.
- `lathe codegen -manifest <path>`: choose the `cli.yaml` path, default `cli.yaml`.
- `lathe codegen -sources <path>`: choose the `sources.yaml` path, default `specs/sources.yaml`.
- `lathe codegen -cache <dir>`: choose the cache root, default `$LATHE_SPECS_CACHE` or `.cache`.
- `lathe codegen -overlay <dir>`: load `<module>.yaml` overlays from a directory.
- `lathe codegen -skill-root <dir>`: write generated Skill output there; empty disables Skill generation.
- `lathe codegen -skill-include <dir>`: merge repo-local Skill resources into generated Skill files.

Overlay files must be named for the module key in `specs/sources.yaml`, such as `overlays/console.yaml`, `overlays/consolerest.yaml`, and `overlays/threads.yaml`. Overlays rewrite generated command names, help text, aliases, examples, groups, params, hidden state, ignored commands, notes, prerequisites, and known errors at codegen time. The runtime does not read overlays.

## Build And Verification

- Use `make build` to regenerate specs, overlays, Lathe output, published CLI references, and `bin/mosoo`.
- Use `go test ./...` for Go behavior changes.
- Before finalizing a change, inspect `git status --short` and separate intentional source changes from generated outputs.