assistant ยท diff

git:20261115.a0fe2fc to git:20261115.c69c5aa

45 added, 18 removed. Audit A to B.

What this update changes in the checks

This update newly trips 1 check:

  • No script tag
    matched: <script

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.

---
name: assistant
- description: Give a Caligrafy Quill project Snap Cards and the assistant (2.23.0, Route::snap()) end to end - every capability becomes a card a person can use (an Ask card: Form, Choice or Confirm; a Show card: Answer or List; a Go card: Shortcut; a Track card: Task; an Offer card: Suggestion or Routine), and /assistant gives each signed-in person a Home that shows what needs them and a conversation that answers with those cards. Adds Route::snap(); to web.php, runs php caligrafer.php snap install, writes application/config/snap.php hints from the app's own capabilities, adds the queue and routines jobs, marks slow capabilities async, asks for an Anthropic API key, and checks /assistant and /snap.
- when_to_use: The user asks for an assistant, Snap, Snap Cards, cards for their capabilities, a Home that shows what needs them, "let people ask the app in their own words", Route::snap, php caligrafer.php snap, or follows the wiki page "Snap Cards and the Assistant" ("/caligrafy-quill:assistant").
+ description: Give a Caligrafy Quill project Snap Cards and the assistant (2.23.0, Route::snap()) end to end - every capability becomes a card a person can use (an Ask card: Form, Choice or Confirm; a Show card: Answer or List; a Go card: Shortcut; a Track card: Task; an Offer card: Suggestion or Routine), and /assistant gives each signed-in person a Home that shows what needs them and a conversation that answers with those cards. Adds Route::snap(); to web.php, runs php caligrafer.php snap install, writes application/config/snap.php hints from the app's own capabilities, writes a card view (application/views/snap/<capability>.pug, 2.25.0) for each main list and record from the app's own pages and look, adds the queue and routines jobs, marks slow capabilities async, asks for an Anthropic API key, and checks /assistant and /snap.
+ when_to_use: The user asks for an assistant, Snap, Snap Cards, cards for their capabilities, card views, better-looking cards, a Home that shows what needs them, "let people ask the app in their own words", Route::snap, php caligrafer.php snap, or follows the wiki page "Snap Cards and the Assistant" ("/caligrafy-quill:assistant").
argument-hint: "[what the app is about, in a few words]"
---
# Snap Cards and the assistant
What the app is about: `$ARGUMENTS` (else read it from the README, `APP_NAME` and the capabilities). Read the wiki page
[Snap Cards and the Assistant](https://github.com/caligrafy/caligrafy-quill/wiki/Snap-Cards-and-the-Assistant), the
- Snap section of [api-reference.md](../caligrafy/reference/api-reference.md#snap) and G153-G162 of
+ Snap section of [api-reference.md](../caligrafy/reference/api-reference.md#snap) and G153-G163 of
[gotchas.md](../caligrafy/reference/gotchas.md). Snap needs Caligrafy Quill 2.23.0 or later
(`php caligrafer.php version`): older, run the `update` skill first.
In Docker, prefix every command with `docker compose exec dev-box` (from the project root). Say which step you are in.
## 1. The route
In `application/config/routing/web.php`, after `Auth::authentication(...)` (the assistant is for signed-in people,
G154) and before `Route::run()`, add once:
```php
// Snap Cards and the assistant: every capability as a card, and an assistant that answers with them
Route::snap();
```
Other addresses only when the user asks: `Route::snap(['assistant' => '/help', 'cards' => '/cards'])`.
## 2. The tables
```bash
php caligrafer.php snap install
```
It creates the `caligrafy_snap_*` tables (from `framework/settings/platform.sql`) and a starter
`application/config/snap.php` when there is none, then prints what is ready. A database error: check `DB_ACTIVATE`
and `DB_*` in `.env` (the `server` skill). The test database needs them too: `platform install` on it (G158).
## 3. The hints: `application/config/snap.php`
Cards work without any hint; hints make them good. Read every capability of the app
(`php caligrafer.php capabilities`, the files of `application/services/`) and write, keyed by capability name, only
the hints that help:
+ `'about'`: what the app is about, one line ("a library app: the books of a catalog, their authors, and the books
lent to people"). The assistant reads it before every answer.
+ Each main list: `title` (a name a person would say: "The catalog"), `columns` (3 or 4 short fields, related ones as
`author.name`), `empty` (what an empty list says), `open` when a row should open another capability
(`array('capability' => 'get_book', 'input' => 'id', 'from' => 'book_id')`).
+ Each change: `done` (the assistant's line once done, `{heading}` is the record: `'Done! {heading} is lent.'`),
`undo` when another capability undoes it, `applies` when it only makes sense for some records
(`array('not_in' => array('capability' => 'list_loans', 'field' => 'book_id'))`: never lend a book that is out).
+ Home: an `insight` on a list whose number calls for an action (always give its `action`: a number alone is noise),
an `alert` on a list whose rows carry a flag (`'when' => 'overdue'`, with its `action`, `yes`, `tag`), and one
`discover` on the list of the things the app is about (what to open, the facts to show, `new` and `related` fields,
an `unavailable` rule when some cannot be used now). Copy the shapes of the wiki page; never invent keys.
+ What fills an empty list: `empty_next` (`array('lend_book')`); what a change leads to: `next`.
`php -l application/config/snap.php` after writing it.
- ## 3b. How the cards look (2.24.0)
+ ## 3b. Card views: how the cards look (2.25.0)
- A card shows the page made for its capability (the `Route::page` whose first data it is), else a card designed for
- its data in the app's design system (Claude designs it when the key is set, rules otherwise). Never a list of fields.
- For each main capability (the lists and records people open):
+ A Show card (a list, a record) shows its **card view** when it has one: `application/views/snap/<capability>.pug`, a
+ small Pug view made for the card, in the app's own markup and classes, rendered by the server inside the card. Without
+ one it shows the part of a page marked `data-snap="<capability>"`, else a card designed from the data. Never a whole
+ page. Write a card view for every read-only capability people open (the main lists and records):
- + Its page shows more than the capability (a list with a create form, a dashboard): add `data-snap='<capability>'`
- to the element of the view that shows it (`section.cq-band(data-snap='list_books')`, several names separated by
- spaces). Only add the attribute; change nothing else in the view.
- + It picks the wrong page, or none while one fits: the hint `'view' => 'Folder/view'`; a page that should not be used:
- `'view' => false`.
- + Without a page, its designed card misses what matters (check it at `/snap/c/<capability>`): a `design` hint naming
- the fields (`'design' => array('title' => 'name', 'subtitle' => 'role', 'meta' => array('email'))`; the wiki page
- lists the keys). Do not write one when the card already reads well.
+ 1. **Start from the page that shows it** (the `Route::page` whose `data` gives it, its view, and the scripts that draw it
+ when the page is drawn by JavaScript). Keep only what the card needs: a list's rows, a record's header and summary.
+ Leave out page titles, breadcrumbs, tabs, filters, toolbars and every form that changes data: the card has its own
+ actions (Change, Delete...) under the view.
+ 2. **The file** is a partial (no `extends`, no `block`). Its first line names the page and that page's fingerprint, so
+ `php caligrafer.php snap views` and `doctor` know when the page changed:
+ ```pug
+ //- snap card of list_books, from Bookshelf/books.pug 5fb9e0cf
+ ul.cq-rows
+ each $b in $rows
+ li.cq-row
+ .cq-row-main
+ p.cq-row-title
+ a(href="{$home}books/{$b['id']}", data-snap-open='get_book', data-snap-input=json_encode(array('id' => $b['id'])))= $b['title']
+ p.cq-row-meta= $b['author']['name'] . ', ' . $b['published_year']
+ ```
+
+ The fingerprint is `shasum application/views/Bookshelf/books.pug | cut -c1-8`. A card view with no page names none:
+ `//- snap card of list_authors (no page: ...)`.
+ 3. **Its variables**: `$rows` (the list) and `$page` (`page`, `pages`, `total`, or null) for a list, `$record` for one
+ record, `$result` (what the capability returned, as is), `$input`, `$card` (`capability`, `title`), `$home`,
+ `$authorized`, `$user`. Use `array(...)` in Pug expressions.
+ 4. **The app's look**: the same elements and classes as its pages (Caligrafy's `cq-*` components, or the app's own).
+ With a built stylesheet (Tailwind and the like), use only classes that exist in it: copy them from the views and
+ scripts, then check every class of the card view is in the built CSS. No `<script>`: a card view is inserted as HTML.
+ 5. **Links**: `data-snap-open="<capability>"` with `data-snap-input='{"id": 7}'` (from `json_encode`) opens that card in
+ the conversation; keep an `href` to the page too. Other links go where they point.
+ 6. **Same shape, one view**: a capability whose result looks like another's uses its card view with the hint
+ `'card' => 'snap/list_books'` (`search_books` shows the catalog's rows). `'card' => false` turns a card view off.
+
+ Check: `php caligrafer.php snap views` shows `[ok]` for each card view (`[!!]`: its page changed, write it again), then
+ open `/snap/c/<capability>` signed in for each one (with `?in={"id":1}` for a record) and look at it: the app's look,
+ sized as a card, nothing that belongs to the page around it.
+
## 4. Slow work: `async: true`
A capability that takes seconds (a report, sending many emails, an import) gets `async: true` in its
`#[Capability(...)]`: Snap runs it in the background as a Track card: Task, as the person (G155: REST, MCP and pages
still call it directly). Give it a `working` hint: what it says while it runs, 2 or 3 short lines.
## 5. The jobs
In `application/config/schedule.php` (create it with `return array(...);` when missing), add what is missing:
```php
array('name' => 'queue', 'capability' => 'queue_work', 'every' => '1m', 'timeout' => 55), // background tasks
array('name' => 'snap-routines', 'capability' => 'snap_routines_due', 'every' => '1m', 'timeout' => 50), // routines
```
Locally they run with `php caligrafer.php schedule work` (the `scheduler` container does it in Docker); Caligrafy
Cloud runs them online.
## 6. The assistant's model (ask first)
Without a key the assistant answers the names of the cards, the shortcuts and "What can I do?". With one, Claude
understands anything. Ask the user whether they want it; if yes, they need an **Anthropic API key**
(console.anthropic.com, API keys). Never ask them to paste it in the chat, and never print it: give them a command that
reads it hidden and writes it to `.env`, for example
```bash
read -rs -p "Anthropic API key: " K && printf '\nANTHROPIC_API_KEY=%s\n' "$K" >> .env && unset K && echo " saved"
```
(when `.env` already has an empty `ANTHROPIC_API_KEY=` line, replace that line instead of adding one). Then check only
that it is set (`grep -c '^ANTHROPIC_API_KEY=.\+' .env`), never its value. `SNAP_MODEL` and `SNAP_EFFORT` stay empty
unless the user asks. The planner also needs the `anthropic-ai/sdk` package: `composer install` after an update (G156).
## 7. Check
```bash
php caligrafer.php snap
```
Every line `[ok]` that the app needs. Then, signed in, open `/assistant` (Home greets the person, its sections show
- what the hints describe), type the name of a card ("the catalog": it shows its page, or a designed card, never
- a list of raw fields), open a record, try an action up to its Confirm
+ what the hints describe), type the name of a card ("the catalog": it shows its card view, never a page or a list of raw
+ fields), open a record, try an action up to its Confirm
(stop there unless the user asked to change data), and open `/snap` (one card per capability the person may use).
- A page that says "Snap is almost ready" means the tables are missing (G153). Report the addresses, the `data-snap` marks and hints written,
+ A page that says "Snap is almost ready" means the tables are missing (G153). Report the addresses, the card views and hints written,
what is async, and whether the model is on.