# Agent setup — reference moved out of AGENTS.md

`AGENTS.md` keeps the rules most tasks need. This file holds the tooling
reference: what each steering file covers, how skills are mirrored, which shell
commands Codex may run, which MCP servers exist, and the full command list.

## Steering files (`.kiro/steering/`)

| File | Covers |
|------|--------|
| `business-logic.md` | BRD alignment, business rules BR-01…30, lifecycles, money formulas, terminology |
| `api-surfaces.md` | The four surfaces, file layout, access boundaries, Flutter/React response rules |
| `feature-documentation.md` | When/how to write feature docs, SemVer, definition of done |
| `architecture.md` | Request lifecycle, response format, services, translations, media |
| `crud-conventions.md` | Config-only admin controllers, single Form Request, BaseCRUDService |
| `code-standards.md` | PHPDoc, section separators, naming, type safety |
| `base-project-style.md` | Resource and file-shape conventions |
| `postman-collection.md` | Postman collection contract: documented request keys + real captured response examples for every route, enforced by `postman:generate --check` (TD-56); generated request chaining through saved variables (TD-57) |

## Project skills

The `joshen-*` skills live in **`.agents/skills/`** (canonical — read by Codex,
Antigravity, OpenCode) and are mirrored to `.claude/skills/` for Claude Code.
They point to the steering files instead of copying them, so a rule changes in
one place. After editing a `joshen-*` skill, re-sync the mirror:

```bash
for d in .agents/skills/joshen-*; do rm -rf ".claude/skills/$(basename "$d")"; cp -r "$d" .claude/skills/; done
```

The other skills (`laravel-best-practices`, `testing-best-practices`,
`infer-conventions`, `tailwindcss-development`) are managed by Laravel Boost —
refresh them with `php artisan boost:update`, don't edit them.

## Codex command rules

`.codex/rules/joshen.rules` decides which shell commands Codex may run on its own
(loaded automatically for this trusted project; `.codex/config.toml` holds only
the Boost MCP entry, managed by Boost):

| Decision | Commands |
|----------|----------|
| allow | `php artisan test / route:list / db:show / db:table / config:show / list / about / postman:generate`, `env RECORD_API_EXAMPLES=1 php artisan test`, `vendor/bin/pint`, `vendor/bin/phpunit`, `composer style / style:check / validate / show` |
| ask first | `php artisan migrate*` / `db:seed`, `boost:install` / `boost:update`, `key:generate`, `composer require / remove / update / install`, `git push / commit / reset / rebase / checkout / switch / merge` |
| never | `php artisan db:wipe`, `git push --force / -f / --force-with-lease` |

Check a command against it:
`codex execpolicy check --pretty --rules .codex/rules/joshen.rules -- php artisan migrate:fresh`

## MCP servers

Markdown docs hold the **business memory**; MCP servers give **live facts** about
the code. Prefer checking with a tool over guessing.

| Server | Use it for | Status |
|--------|-----------|--------|
| **Laravel Boost** | Database schema, read-only queries, route list, config, logs, version-specific Laravel docs search | Installed (`laravel/boost`, dev). Configured for Claude Code (`.mcp.json`), Codex (`.codex/config.toml`), OpenCode (`opencode.json`), Antigravity (`.agents/mcp_config.json`). Run `php artisan boost:update` to refresh its guidelines and skills. **Never runs in production:** `config/boost.php` disables it when `APP_ENV=production` (override with `BOOST_ENABLED`). |
| **Postman** | Syncing/testing the API collection generated by `php artisan postman:generate` | Needs authentication in the MCP client |
| **Figma** | Reading app designs when a feature doc must map screens to endpoints | Optional |

When an MCP server is unavailable, fall back to `php artisan route:list`,
`php artisan db:show` / `db:table`, and reading migrations.

## Commands

```bash
php artisan test                       # run tests
php artisan test --filter=AcCust012    # one acceptance scenario
composer style                         # format with Pint
composer style:check                   # check formatting
php artisan postman:generate           # regenerate the Postman collection (prunes fixed baseline gaps)
php artisan postman:generate --check   # fail on undocumented keys / missing response examples (TD-56)
env RECORD_API_EXAMPLES=1 php artisan test --compact <file>   # merge real responses + payloads into docs/postman-collection.json (TD-81)
php artisan postman:generate --forget-example="route|code|name"   # drop an example of a renamed/deleted test
php artisan route:list --path=api/v1/client
```
