assistant · git:20261115.c69c5aa · 2026-11-15 · sha256 5aaa2540d0d0d818

assistant git:20261115.c69c5aaB

Immutable. This exact content never changes and is served at /api/v1/blob/5aaa2540d0d0d818.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_4nuk2utdfo3gup2s/5aaa2540d0d0d8186bebb58d06844ab3dae8a39b55aab717bb3a696e24cd7530.json

Then /plugin install assistant@markdownregistry-4nuk2utdfo3gup2s in Claude Code. It installs this exact version, the one graded B here, pinned to the commit it was graded at, and leaves it there.

---
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, 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-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. Card views: how the cards look (2.25.0)

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):

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 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 card views and hints written,
what is async, and whether the model is on.