AGENTS.md ยท diff

git:20261115.9fe61ce to git:20261115.086163c

1 added, 1 removed. Audit B to B.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# Caligrafy Quill: instructions for AI coding agents
This file is for any coding agent (Cursor, Codex, Copilot, Claude Code...). Claude Code also gets the
`caligrafy-quill` plugin from `.claude/settings.json`; other agents should read the same knowledge files below.
## What this project is
A Caligrafy Quill PHP MVC project (PHP 8.3+, MySQL via PDO, Pug views, GUMP validation, Vue 3 client apps).
Your code goes in `application/` (routes in `application/config/routing/web.php`, services, models, Pug views) and `public/<app>/` (client apps). `framework/` is the framework itself: change it only when asked.
## Read before writing code
- `claude-plugin/skills/caligrafy/SKILL.md`: the index of the framework knowledge and the workflow rules.
- `claude-plugin/skills/caligrafy/reference/api-reference.md`: exact signatures, verified against the source.
- - `claude-plugin/skills/caligrafy/reference/gotchas.md`: verified pitfalls G1-G170 (read the relevant ones).
+ - `claude-plugin/skills/caligrafy/reference/gotchas.md`: verified pitfalls G1-G171 (read the relevant ones).
- `claude-plugin/skills/caligrafy/reference/13-build-once-services-capabilities-mcp.md`: capabilities, tokens, MCP.
- `claude-plugin/skills/caligrafy/reference/ui-guidelines.md`: how every new page and client app looks (page components).
- `ARCHITECTURE.md`: how a request runs and the build-once design.
- `claude-plugin/skills/caligrafy/reference/59-snap-cards-and-the-assistant.md`: Snap Cards and the assistant (`Route::snap()`).
- Step-by-step procedures: `claude-plugin/skills/<idea | new-resource | new-capability | new-app | assistant | server | db | design | ship | deploy | update>/SKILL.md`.
## Build once, experience everywhere
A project that was never set up: `.bin/caligrafer quickstart` (database, framework tables, `/capabilities` and `/mcp`;
`--example` adds the Tasks example). It asks before `initialize` deletes `.git`.
A feature that more than one channel needs (Pug pages, a Vue app, a REST API, AI agents) is a **capability**:
`php caligrafer.php service <Folder>/<Name> --scope <resource:action>` creates a `Caligrafy\Service` with
`#[Capability]` in `application/services/`. Declare every input in `$rules`, return data from `handle()`, refuse with
`ServiceError`; never render, redirect, print or read the session there. Read data with the query builder
(`Book::where(...)->with('author')->paginate(20, $input['page'] ?? 1)`, `Database::table()`, 2.19.0+). Expose it with
`Route::page` (pages), `Route::form` (form posts), `Route::download` (CSV/JSON exports), `Route::webhook` (a
service's events), `Route::action` with a `webOnly: true` capability for custom HTTP (2.21.0, no controller),
`Route::capability()` (REST), `Route::capabilities()` + `php caligrafer.php client` (Vue apps), `Route::mcp()`
(agents) and `Route::snap()` (2.23.0+: every capability as a card, and an assistant that answers with them; `php caligrafer.php snap`
checks it). `php caligrafer.php capabilities` lists them.
## Rules
- Only capabilities touch models: pages use `Route::page` (with `data` from capabilities), forms `Route::form`, sign-in `Route::auth` (2.19.0+), webhooks `Route::webhook`, exports `Route::download`, anything else `Route::action` on a `webOnly: true` capability (2.21.0); no new controller (existing ones call `$this->call()`), never a model in a controller, a route or a view, and never data work in a closure route.
- The query builder or bound queries only (`?` placeholders and `'bindings'`): never concatenate request data into SQL; load related rows with `with()`, never a query per row.
- Every new page extends `../default/master/site` and uses the page components of `public/css/layout.css` (`section.cq-hero.cq-hero--page`,
`section.cq-band`, `.cq-field`, `ul.cq-rows`, `.cq-tiles`), and every client app the same classes: see `ui-guidelines.md`, and check it at desktop and phone width. In Pug, strings join with `.`, never `+`.
- A JSON call to `Route::action` needs the page's `X-CSRF-Token` or an API token that grants `*`, signed in or not (2.21.1). A route variable wins over the query string (2.21.2).
- To sign in with an email, keep the lower-cased address in the `username` column (wiki `9.1-Authentication#emailsignin`). A session opened with a face alone must not change how the account signs in (`AuthRoutes::signedInBy()`, 2.21.3).
- Another look is a design style (`DESIGN_STYLE` in `.env`, `php caligrafer.php design`): restyle only in
`public/css/designs/<name>.css`, written from its `DESIGN.md` (`framework/design/`, or the project's own in
`application/design/<name>/`); never edit `tokens.css`, `theme.css`, `styles.css` or the views for it, so that an
empty `DESIGN_STYLE` gives the Caligrafy look back.
- Never put an API key or a personal access token in a page, a `VITE_` variable or a bundle: browser clients use the
session through the generated JS client; programs and agents use tokens (`php caligrafer.php token create`).
- Never print or commit secrets from `.env`. `php caligrafer.php initialize --yes` deletes `.git` (since 2.9.2 it keeps it without `--yes`): ask before running it.
- Describe it. Approve it. Ship it.: an idea becomes a complete app in three steps - describe it (start, data,
capabilities), approve it (experiences, people and trust, checks; the user approves the plan once), ship it
(online); Claude Code users run `/caligrafy-quill:idea`.
- Putting it online (2.4.0+): the root `Dockerfile` is the production image and runs `php caligrafer.php deploy` at
start (new or changed `create_db.sql`: keep them safe to run again; then the pending migrations); `php caligrafer.php cloud` deploys to
`https://<name>.caligrafy.com`. `cloud login` (2.7.0+) is approved by the user in the browser page it opens: never
handle the token. Claude Code users run `/caligrafy-quill:ship`.
- Pages call their own JSON routes with the session: `apiHeaders()` (`X-CSRF-Token`) or the JS client, never the
legacy API key, which is off online (`LEGACY_API_KEY=false` on Caligrafy Cloud).
- To move a project to a newer release: `php caligrafer.php update --check`, then `update` (2.9.0+: framework, untouched
release files, merged settings, `upgrade --apply`); merge each `<file>.caligrafy-new` into the project's version.
- A change to a table that already has data is a migration (2.18.0+): `php caligrafer.php migrate make <name>`, then
`migrate`; never edit a migration that ran. Slow work goes through `Caligrafy\Queue::push()` (a `queue_work` job in
`application/config/schedule.php` runs it); what a capability uses comes through its constructor (`Caligrafy\Container`).
- Sessions start only when used (2.19.0+): read the CSRF token with `session('token')`, and every form carries `=csrf()`. `.env.php` (compiled by `php caligrafer.php env cache` and the deploy step) is never committed.
- After changing PHP, run `php -l <file>`; run the app's tests with `php caligrafer.php test` (`tests/`,
`Caligrafy\Testing\TestCase`); check the project with `php caligrafer.php doctor` (read-only).
- Framework changes need the QA suite: `vendor/bin/phpunit` and `./qa/run.sh` (see `CONTRIBUTING.md`).
## Working on the framework itself
Only in the framework repository (`github.com/caligrafy/caligrafy-quill`, no `application/` folder), never in a project:
- `CONTRIBUTING.md` has the setup: `composer install`, `vendor/bin/phpunit` (unit tests) and `./qa/run.sh` (the whole QA
suite, with Docker; `QA_WIKI=../caligrafy-quill.wiki` also checks the wiki).
- A change reaches the plugin, the README, the wiki, the version and the changelog: `.claude/skills/caligrafy-contributor/SKILL.md`
lists every step. `framework/settings/application` is the template that `initialize` copies to `application/`.
- `llms.txt` (written by hand) and `llms-full.txt` (`php qa/build-llms-full.php ../caligrafy-quill.wiki`) describe the
framework to agents; `context7.json` tells Context7 what to index. `initialize` removes them from a project.