Skip to content

API Snap

Jump to bottom
Dory Azar edited this page Nov 15, 2026 · 2 revisions

Snap

Caligrafy Quill 2.26.0. Generated from the source by php qa/build-api-reference.php; the guides explain how to use these classes, this reference says exactly what each public method takes and returns. Back to the API reference.

Snap Cards and the assistant (namespace Caligrafy\Snap): cards built from what capabilities declare, the conversation, the planner and the setup.

Class What it is
Caligrafy\Snap\Cards Snap Cards (2.23.0): every card is built from what a capability already declares
Caligrafy\Snap\Hints Snap Cards work without any hint: every card is built from what a capability declares (its rules, descriptions, readOnly and destructive).
Caligrafy\Snap\Views How a Show card looks, best first (2.25.0): 1. its card view: application/views/snap/<capability>.pug, a Pug view made for the card, in the app's own markup and
Caligrafy\Snap\Designer A capability shown through its own page uses that page (Snap\Views).
Caligrafy\Snap\Conversation The Snap shell's two spaces (2.23.0)
Caligrafy\Snap\Planner The Snap shell's planner (2.23.0): Claude reads what the person typed or said and answers with cards.
Caligrafy\Snap\Flow The next card for a capability and its inputs, the same whoever asks (a card that is sent, the shell's fast path, the model's choice): one place decides, so the planner can never take a shortcut around consent.
Caligrafy\Snap\Input The inputs of a card arrive as an object, or its JSON (agents and addresses send JSON text): this gives the plain values only (a nested object or list is left out: a card's inputs are scalars).
Caligrafy\Snap\Reads The reads of one request, once (2.23.0): Home asks the same lists for its alerts, insights and picks; each runs once per person per request.
Caligrafy\Snap\Say The assistant's line after every action (2.23.0): whatever the person did (sent a form, picked a choice, confirmed, opened a row, undid, saved a shortcut), the answer carries what the assistant says about it, shown in ...
Caligrafy\Snap\Consent Snap consent (2.23.0): nothing that changes data runs from a card until the person confirms it.
Caligrafy\Snap\Offers Offer: Suggestion and Offer: Routine (2.23.0): the assistant notices what a person does again and again, only if they turned noticing on, and offers to help.
Caligrafy\Snap\Shortcuts Go: Shortcut cards (2.23.0): a request a person saved (a capability with its inputs), run with one click.
Caligrafy\Snap\Tasks Track: Task cards (2.23.0): work that runs in the background for one person.
Caligrafy\Snap\Discover Discover (2.23.0): Home surfaces the things this application is about, to invite browsing, the way a shop surfaces products.
Caligrafy\Snap\Setup install: the tables (framework/settings/platform.sql), a starter application/config/snap.php when there is none, then the two lines to add by hand (they are the app's own files): Route::snap(); in web.php, and the ...
Caligrafy\Snap\Shell The Snap shell's fast path (2.23.0): what it can answer without a model, at once and for free

class Caligrafy\Snap\Cards

Snap Cards (2.23.0): every card is built from what a capability already declares

Its 16 public methods have a page of their own: Caligrafy\Snap\Cards.

class Caligrafy\Snap\Hints

namespace Caligrafy\Snap;

class Hints

Source: framework/core/Snap/Hints.php:30

Class Hints Snap Cards work without any hint: every card is built from what a capability declares (its rules, descriptions, readOnly and destructive). Hints only make them better, from one file the app owns, application/config/snap.php:

return [
    'about' => 'a library app',                       // what the assistant is the assistant of (the planner)
    'cards' => [                                      // keyed by capability name
        'list_books' => ['title' => 'The catalog', 'columns' => ['title', 'author.name'], 'empty' => 'No book yet.'],
        'reading_report' => ['async' => true, 'working' => ['Counting the books…']],
    ],
];

A file that returns the cards alone (no 'cards' key) works too. The keys of a card are in the wiki page "Snap Cards and the Assistant": title, lead, submit, columns, labels, hide, values, choices, open, full, empty, variant, noun, icon, done, undo, next, applies, empty_next, alert, insight, discover, working, async, consequence, confirm, card (2.25.0: its card view, 'Folder/view' under application/views, or false), view (2.24.0: the page whose part marked data-snap shows it, or false) and design (2.24.0: how its data is shown without a card view or a page). A capability is async when #[Capability(async: true)] says so, or its hint does.

Methods

Hints::for()

public static function for($name)

The hints of one capability (an empty array when it has none)

Parameters

  • $name

Source: framework/core/Snap/Hints.php:37

Hints::about()

public static function about()

What the app is about, for the assistant ("a library app"); empty when the file does not say

Source: framework/core/Snap/Hints.php:46

Hints::forget()

public static function forget()

Forgets the file read (tests, and a file that changed)

Source: framework/core/Snap/Hints.php:54

class Caligrafy\Snap\Views

namespace Caligrafy\Snap;

class Views

Source: framework/core/Snap/Views.php:25

Class Views How a Show card looks, best first (2.25.0):

  1. its card view: application/views/snap/<capability>.pug, a Pug view made for the card, in the app's own markup and classes, rendered on the server into the card (the hint 'card' => 'Folder/view' names another, false none). It gets $result (what the capability returned), $rows and $page for a list, $record for one record, $input, $card, $home, $authorized and $user. A link with data-snap-open="<capability>" and data-snap-input='{"id":7}' opens that card in the conversation. Written by Claude from the app's views (the assistant skill); its first line names the page it was made from and that page's fingerprint, so php caligrafer.php snap views says when it is stale.
  2. the part of its page marked data-snap="<capability>" (a Route::page whose first data it is), embedded in the card (?snap-embed: no frame, sized to it); a whole page only when the hint 'view' names it
  3. a card designed for its data in the app's design system (Snap\Designer)

Methods

Views::embed()

public static function embed($name, array $inputs)

The address of the page that shows a capability, with its inputs in place, in embed mode; null when there is none (no page uses it as data, or one of the page's route variables is not among the inputs)

Parameters

  • $name
  • $inputs array

Source: framework/core/Snap/Views.php:31

Views::page()

public static function page($html)

Renders a page in embed mode: its style sheet and script go in, so the page shows without the site's frame and tells the card its height

Parameters

  • $html

Source: framework/core/Snap/Views.php:97

Views::card()

public static function card($name, $result, array $input, array $card = array())

The HTML of a capability's card view, or null when it has none (or it failed: the card is then designed)

Parameters

  • $name
  • $result mixed: what the capability returned, as plain arrays
  • $input array
  • $card array, default array()

Source: framework/core/Snap/Views.php:114

Views::cardFile()

public static function cardFile($name)

The card view file of a capability, or null: the hint 'card' (a view name, or false), else views/snap/<name>.pug

Parameters

  • $name

Source: framework/core/Snap/Views.php:152

Views::source()

public static function source($file)

What the first line of a card view says it was made from: array('view' => 'Bookshelf/books', 'print' => '1a2b3c4d') (//- snap card of list_books, from Bookshelf/books.pug 1a2b3c4d), or null

Parameters

  • $file

Source: framework/core/Snap/Views.php:166

Views::fingerprint()

public static function fingerprint($view)

A view's fingerprint, written in the card views made from it: when the view changes, they are stale

Parameters

  • $view

Source: framework/core/Snap/Views.php:175

Views::cards()

public static function cards()

Every card view of the app, with what it was made from and whether it is stale: [name => ['file', 'from', 'stale' (true, false, or null when its first line names no view)]]

Source: framework/core/Snap/Views.php:185

class Caligrafy\Snap\Designer

namespace Caligrafy\Snap;

class Designer

Source: framework/core/Snap/Designer.php:23

Class Designer A capability shown through its own page uses that page (Snap\Views). Without one, its card is designed, never dumped: a design says which of the data makes the title, the line under it, the badges, the numbers that stand out, the details, the longer text and the tags of a record, or the title, line, details and badge of each row of a list. The page then draws it with the app's own design tokens (its DESIGN_STYLE), so it looks like the rest of the app.

Who designs it: the hint 'design' of application/config/snap.php when the app gives one; else Claude (when the assistant has its key), once for each shape of data, kept in the cache; else rules from the names of the fields.

Constants

  • FORMATS = array('text', 'number', 'money', 'percent', 'date', 'datetime', 'bool', 'email', 'url')
  • TONES = array('success', 'warning', 'danger', 'info', 'neutral')
  • CACHE_DAYS = 30

Public properties

  • public static $model = true: bool false: rules only, never the model (tests, and a design asked for while answering)
  • public static $transport = null: Tests fake Claude's design here (a callable that takes the request and returns the response), apart from the planner's: a test that fakes the planner never sees the designer's requests

Methods

Designer::record()

public static function record($name, array $record)

The blocks of a record's card, values in place and formatted: hero (eyebrow, title, subtitle, badges), stats, fields, text, tags

Parameters

  • $name
  • $record array

Source: framework/core/Snap/Designer.php:50

Designer::rows()

public static function rows($name, array $rows)

Each row of a list, designed: title, subtitle, details (meta), a badge

Parameters

  • $name
  • $rows array

Source: framework/core/Snap/Designer.php:89

Designer::spec()

public static function spec($name, $kind, array $sample)

The design of a capability's data: the app's hint, else Claude's (kept for its shape), else the rules

Parameters

  • $name
  • $kind
  • $sample array

Source: framework/core/Snap/Designer.php:116

Designer::paths()

public static function paths(array $data, $prefix = '', $depth = 0)

The data's fields, flattened: path => a sample value (author.name => 'Octavia E. Butler'), lists kept whole

Parameters

  • $data array
  • $prefix, default ''
  • $depth, default 0

Source: framework/core/Snap/Designer.php:138

Designer::format()

public static function format($value, $format)

No doc comment.

Parameters

  • $value
  • $format

Source: framework/core/Snap/Designer.php:321

class Caligrafy\Snap\Conversation

The Snap shell's two spaces (2.23.0)

Its 15 public methods have a page of their own: Caligrafy\Snap\Conversation.

class Caligrafy\Snap\Planner

namespace Caligrafy\Snap;

class Planner

Source: framework/core/Snap/Planner.php:25

The Snap shell's planner (2.23.0): Claude reads what the person typed or said and answers with cards.

What the model may do, enforced here, not in the prompt:

  • look things up with the read-only capabilities this person may call (as tools, run with their permissions);
  • answer with show_cards: which capability, with which values, and one sentence of caption.

Every card it names goes through Snap\Flow like any other: a read runs, a change comes back as an Ask: Confirm whose token only the person's click sends. The model never sees a token and never runs a change. Tool results are the app's data: the system prompt says so, and nothing in them can reach a change anyway.

Claude through the official PHP SDK (anthropic-ai/sdk), claude-opus-5-5 at low effort (a quick turn in a UI), server-side refusal fallbacks on. Without ANTHROPIC_API_KEY the planner is off and the shell uses its fast path.

Constants

  • MODEL = 'claude-opus-5-5'
  • MAX_STEPS = 6
  • RESULT_BYTES = 12000
  • FILE_TYPES = array('image/png', 'image/jpeg', 'image/gif', 'image/webp', 'application/pdf', 'text/plain', 'text/csv', 'text/markdown')
  • FILE_BYTES = 5242880
  • FILES = 3

Public properties

  • public static $transport = null: callable|null tests: fn (array $request): object (a response with ->stopReason and ->content)

Methods

Planner::on()

public static function on()

No doc comment.

Source: framework/core/Snap/Planner.php:34

Planner::files()

public static function files($files)

The files the person attached, checked: [name, type, data (base64)] of an allowed type, 3 at most, 5 MB in all

Parameters

  • $files

  • @throws ServiceError invalid when a file is refused (the message says which)

Source: framework/core/Snap/Planner.php:60

Planner::plan()

public static function plan($text, Context $context, $instead = null, array $files = array(), $memory = '')

No doc comment.

Parameters

  • $text
  • $context Context
  • $instead, default null
  • $files array, default array()
  • $memory, default ''

Source: framework/core/Snap/Planner.php:107

Planner::send()

public static function send(array $request)

No doc comment.

Parameters

  • $request array

Source: framework/core/Snap/Planner.php:163

class Caligrafy\Snap\Flow

namespace Caligrafy\Snap;

class Flow

Source: framework/core/Snap/Flow.php:16

The next card for a capability and its inputs, the same whoever asks (a card that is sent, the shell's fast path, the model's choice): one place decides, so the planner can never take a shortcut around consent.

read:        inputs missing -> its Ask card; complete -> runs -> Show card
write/destroy: inputs missing -> its Ask card; refused by its rules -> Ask with errors; else -> Ask: Confirm

A change runs only in SnapRun, with the token of that Confirm.

Methods

Flow::next()

public static function next($name, array $inputs, Context $context)

Parameters

  • $name
  • $inputs array
  • $context Context

Returns array: [card, http status]

Source: framework/core/Snap/Flow.php:21

Flow::refused()

public static function refused($name, Context $context, array $inputs, ServiceError $e)

No doc comment.

Parameters

  • $name
  • $context Context
  • $inputs array
  • $e ServiceError

Source: framework/core/Snap/Flow.php:55

class Caligrafy\Snap\Input

namespace Caligrafy\Snap;

class Input

Source: framework/core/Snap/Input.php:15

Class Input The inputs of a card arrive as an object, or its JSON (agents and addresses send JSON text): this gives the plain values only (a nested object or list is left out: a card's inputs are scalars).

Methods

Input::decode()

public static function decode($value)

No doc comment.

Parameters

  • $value

Source: framework/core/Snap/Input.php:17

class Caligrafy\Snap\Reads

namespace Caligrafy\Snap;

class Reads

Source: framework/core/Snap/Reads.php:12

The reads of one request, once (2.23.0): Home asks the same lists for its alerts, insights and picks; each runs once per person per request. Cards::forget() (after a change) forgets them too.

Methods

Reads::plain()

public static function plain($name, Context $context)

A read-only capability's plain result, without inputs, once per request and person (its errors too)

Parameters

  • $name
  • $context Context

Source: framework/core/Snap/Reads.php:19

Reads::forget()

public static function forget()

No doc comment.

Source: framework/core/Snap/Reads.php:36

class Caligrafy\Snap\Say

namespace Caligrafy\Snap;

class Say

Source: framework/core/Snap/Say.php:11

The assistant's line after every action (2.23.0): whatever the person did (sent a form, picked a choice, confirmed, opened a row, undid, saved a shortcut), the answer carries what the assistant says about it, shown in the conversation section. Written here, at once and for free, from what the card is; the model writes only the captions of free questions. Also: which answers deserve a celebration.

Methods

Say::for()

public static function for(array $card, $after = null)

The line for a card the person just reached, and whether it is a moment to celebrate

Parameters

  • $card array
  • $after, default null

Returns array: [say, celebrate]

Source: framework/core/Snap/Say.php:17

Say::on()

public static function on(array $card)

Adds the line (and the celebration) to a card

Parameters

  • $card array

Source: framework/core/Snap/Say.php:95

class Caligrafy\Snap\Consent

namespace Caligrafy\Snap;

class Consent

Source: framework/core/Snap/Consent.php:20

Snap consent (2.23.0): nothing that changes data runs from a card until the person confirms it.

  • snap_run answers a change with an Ask: Confirm: what will change (before -> after), and a one-time token bound to this person, this capability and these exact inputs, for 10 minutes, kept in the session (never in the card's address). Only the person's click on that card sends it back; a model, a page or a link cannot make one.
  • A confirmed change is recorded in Caligrafy's audit log (capability snap_confirm, detail: what was confirmed).
  • What the change can be undone with is decided here, from what was true before (update_), what was created (create_ -> delete_), or a hint ('undo' in application/config/snap.php). Undoing is a change too: it gets its own Confirm.

Constants

  • TTL = 600
  • KEEP = 20
  • KEY = 'snap_consent'

Methods

Consent::ask()

public static function ask($name, Context $context, array $inputs, $message = null)

The Ask: Confirm card of a change, with a fresh token

Parameters

  • $name
  • $context Context
  • $inputs array
  • $message, default null

Source: framework/core/Snap/Consent.php:29

Consent::take()

public static function take($token, $name, Context $context, array $inputs)

Whether $token confirms exactly this change by this person; a token works once

Parameters

  • $token
  • $name
  • $context Context
  • $inputs array

Returns array|null: what was kept with it (the values before the change)

Source: framework/core/Snap/Consent.php:47

Consent::undo()

public static function undo($name, array $inputs, $result, array $kept, Context $context)

The action that undoes a done change, or null when there is none

Parameters

  • $name
  • $inputs array
  • $result
  • $kept array
  • $context Context

Source: framework/core/Snap/Consent.php:64

class Caligrafy\Snap\Offers

namespace Caligrafy\Snap;

class Offers

Source: framework/core/Snap/Offers.php:26

Offer: Suggestion and Offer: Routine (2.23.0): the assistant notices what a person does again and again, only if they turned noticing on, and offers to help. Built to stay quiet rather than noisy:

  • opt-in per person (snap_settings.noticing), off by default; "What I've noticed" shows every pattern, each deletable, and turning noticing off deletes what was noticed
  • a pattern is the same request (capability + inputs) on 3 different days or more, on the same weekday (weekly) or around the same hour (daily); anything weaker says nothing
  • every offer says why ("you did this 4 Mondays in a row"), has Not now and Don't suggest this again, and at most MAX_OFFERS are shown at a time
  • Offer: Suggestion: it is the usual moment and it was not done yet today: do it now (through Snap\Flow, so a change still asks for its Confirm)
  • Offer: Routine: do it on that rhythm, at a level the person picks: suggest (a Suggestion at that moment), confirm (its Confirm ready at that moment), auto (it runs as a task and they are told). Accepting a routine is itself a change with its Ask: Confirm. A delete is never automatic.

Constants

  • MIN_DAYS = 3
  • MAX_OFFERS = 2
  • WINDOW_DAYS = 42
  • LEVELS = array('suggest', 'confirm', 'auto')
  • DAYS = array(1 => 'Monday', 2 => 'Tuesday', 3 => 'Wednesday', 4 => 'Thursday', 5 => 'Friday', 6 => 'Saturday', 7 => 'Sunday')

Public properties

  • public static $now = null: int|null tests: the time "now" is

Methods

Offers::noticing()

public static function noticing(Context $context)

No doc comment.

Parameters

  • $context Context

Source: framework/core/Snap/Offers.php:39

Offers::setNoticing()

public static function setNoticing(Context $context, $on)

No doc comment.

Parameters

  • $context Context
  • $on

Source: framework/core/Snap/Offers.php:44

Offers::record()

public static function record(Context $context, $name, array $inputs)

Something this person did through a card (a read that ran, a change they confirmed, a task they started)

Parameters

  • $context Context
  • $name
  • $inputs array

Source: framework/core/Snap/Offers.php:64

Offers::forget()

public static function forget(Context $context, $fingerprint = null)

No doc comment.

Parameters

  • $context Context
  • $fingerprint, default null

Source: framework/core/Snap/Offers.php:74

Offers::patterns()

public static function patterns(Context $context)

What was noticed: each request done on MIN_DAYS different days or more, with its rhythm and why

Parameters

  • $context Context

Source: framework/core/Snap/Offers.php:88

Offers::offers()

public static function offers(Context $context)

The offers to show now: routines that are due, then suggestions of this moment, then routines to propose; never more than MAX_OFFERS, never one dismissed

Parameters

  • $context Context

Source: framework/core/Snap/Offers.php:121

Offers::dismiss()

public static function dismiss(Context $context, $fingerprint, $kind)

No doc comment.

Parameters

  • $context Context
  • $fingerprint
  • $kind

Source: framework/core/Snap/Offers.php:147

Offers::routines()

public static function routines(Context $context)

No doc comment.

Parameters

  • $context Context

Source: framework/core/Snap/Offers.php:162

Offers::saveRoutine()

public static function saveRoutine(Context $context, $capability, array $inputs, $weekday, $hour, $level)

Keeps a routine (snap_routine_save, after its Ask: Confirm): the consent to do it on a rhythm, recorded in the audit log

Parameters

  • $context Context
  • $capability
  • $inputs array
  • $weekday
  • $hour
  • $level

Source: framework/core/Snap/Offers.php:174

Offers::deleteRoutine()

public static function deleteRoutine(Context $context, $id)

No doc comment.

Parameters

  • $context Context
  • $id

Source: framework/core/Snap/Offers.php:194

Offers::runDue()

public static function runDue()

The scheduler's side (snap_routines_due, every minute): routines at the auto level that are due run as a task, as their owner, and they are told (by the task). Others wait for the person, as offers.

Source: framework/core/Snap/Offers.php:206

Offers::rhythmText()

public static function rhythmText(array $r)

No doc comment.

Parameters

  • $r array

Source: framework/core/Snap/Offers.php:313

Offers::fingerprint()

public static function fingerprint($name, array $inputs)

No doc comment.

Parameters

  • $name
  • $inputs array

Source: framework/core/Snap/Offers.php:333

class Caligrafy\Snap\Shortcuts

namespace Caligrafy\Snap;

class Shortcuts

Source: framework/core/Snap/Shortcuts.php:14

Go: Shortcut cards (2.23.0): a request a person saved (a capability with its inputs), run with one click. Running one goes through Snap\Flow like any card: a read shows its result, a change asks for its Confirm.

Constants

  • TABLE = 'caligrafy_snap_shortcuts'
  • MAX = 12

Methods

Shortcuts::of()

public static function of(Context $context)

No doc comment.

Parameters

  • $context Context

Source: framework/core/Snap/Shortcuts.php:19

Shortcuts::save()

public static function save(Context $context, $title, $capability, array $inputs)

No doc comment.

Parameters

  • $context Context
  • $title
  • $capability
  • $inputs array

Source: framework/core/Snap/Shortcuts.php:35

Shortcuts::delete()

public static function delete(Context $context, $id)

No doc comment.

Parameters

  • $context Context
  • $id

Source: framework/core/Snap/Shortcuts.php:49

Shortcuts::mark()

public static function mark(array $card, Context $context)

A Show card says whether it is one of this person's shortcuts already (its id), so its control shows the state: saved (with Remove) or not (Save)

Parameters

  • $card array
  • $context Context

Source: framework/core/Snap/Shortcuts.php:62

Shortcuts::find()

public static function find(Context $context, $text)

The shortcut whose title matches what was typed, or null

Parameters

  • $context Context
  • $text

Source: framework/core/Snap/Shortcuts.php:81

class Caligrafy\Snap\Tasks

namespace Caligrafy\Snap;

class Tasks

Source: framework/core/Snap/Tasks.php:24

Track: Task cards (2.23.0): work that runs in the background for one person.

A capability declared #[Capability(async: true)] (or with the hint 'async' in application/config/snap.php) does not run in the request: a read starts as a task at once, a change after its Ask: Confirm. The task is a row of snap_tasks and a job of Caligrafy's queue (snap_task_run). The worker runs the capability AS THE PERSON who asked (their user, the web channel: their permissions, not the queue's full access), keeps the card of what came out, and notifies them:

done        -> the Show card of the result
needs_input -> the Ask card of what the capability refused (the person answers it, a new task starts)
failed      -> a notice, after the queue's retries

The Track card shows where it is: queued, running, then the card it ended with.

Constants

  • TABLE = 'caligrafy_snap_tasks'
  • LABELS = ...

Methods

Tasks::async()

public static function async($name)

No doc comment.

Parameters

  • $name

Source: framework/core/Snap/Tasks.php:30

Tasks::start()

public static function start($name, array $inputs, Context $context)

Starts a task for this person: the row, then its job. Returns its Track card.

Parameters

  • $name
  • $inputs array
  • $context Context

Source: framework/core/Snap/Tasks.php:40

Tasks::run()

public static function run($id)

The worker (snap_task_run, in the queue): runs the task as its owner, keeps the card it ends with, notifies

Parameters

  • $id

Source: framework/core/Snap/Tasks.php:55

Tasks::get()

public static function get($id, Context $context)

One task's Track card, for its owner only

Parameters

  • $id
  • $context Context

Source: framework/core/Snap/Tasks.php:90

Tasks::of()

public static function of(Context $context, $limit = 6)

This person's latest tasks, newest first ("Coming up" and what just finished)

Parameters

  • $context Context
  • $limit, default 6

Source: framework/core/Snap/Tasks.php:102

class Caligrafy\Snap\Discover

namespace Caligrafy\Snap;

class Discover

Source: framework/core/Snap/Discover.php:28

Discover (2.23.0): Home surfaces the things this application is about, to invite browsing, the way a shop surfaces products. Out of the box, from one hint on a list capability ('discover'):

  • for you more like what this person looked at (only when they turned noticing on: what they opened is in snap_events), e.g. another book by the author of a book they opened
  • new what was added last
  • the rule a business rule of the app: only what is available now (not in another list, e.g. not lent)

Each pick is a Home card that opens the object in the task space; each says why it is there.

The hint: 'discover' => array(

'open' => 'get_book', 'key' => 'id',                     how an object opens (capability, the field it takes)
'title' => 'title', 'meta' => array('author.name', ...),   what a pick shows
'new' => 'created_at',                                   the field that says when it was added
'related' => 'author.id', 'by' => 'author.name',          what "more like it" shares, and its name
'opened' => array('get_book' => 'id', 'lend_book' => 'book_id'),   the requests that mean "looked at it"
'unavailable' => array('capability' => 'list_loans', 'field' => 'book_id'),   the business rule
'title_section' => 'On the shelf for you')

Constants

  • PICKS = 6

Methods

Discover::sections()

public static function sections(Context $context)

Parameters

  • $context Context

Returns array: [title, cards, nudge] for each list capability with a 'discover' hint this person may read

Source: framework/core/Snap/Discover.php:35

Discover::dig()

public static function dig($row, $path)

No doc comment.

Parameters

  • $row
  • $path

Source: framework/core/Snap/Discover.php:155

class Caligrafy\Snap\Setup

namespace Caligrafy\Snap;

class Setup

Source: framework/core/Snap/Setup.php:17

Class Setup install: the tables (framework/settings/platform.sql), a starter application/config/snap.php when there is none, then the two lines to add by hand (they are the app's own files): Route::snap(); in web.php, and the routines' job in application/config/schedule.php. status: each of those, the queue (tasks run in it), and the assistant's model (ANTHROPIC_API_KEY).

Constants

  • CONFIG = 'application/config/snap.php'
  • TEMPLATE = 'framework/settings/snap.php.template'
  • ROUTES = 'application/config/routing/web.php'
  • SCHEDULE = 'application/config/schedule.php'

Methods

Setup::status()

public static function status($root = '.')

What is ready, and what is not: [label => [ok (bool), detail]]

Parameters

  • $root, default '.'

Source: framework/core/Snap/Setup.php:27

Setup::config()

public static function config($root = '.')

Writes the starter application/config/snap.php when there is none

Parameters

  • $root, default '.'

Returns bool: true when it was written

Source: framework/core/Snap/Setup.php:49

class Caligrafy\Snap\Shell

namespace Caligrafy\Snap;

class Shell

Source: framework/core/Snap/Shell.php:15

The Snap shell's fast path (2.23.0): what it can answer without a model, at once and for free:

  • "What can I do?" (help, menu, ?): the cards this person may use, by family
  • the title of one of their shortcuts: that Go: Shortcut, run
  • the title or the name of a card ("the catalog", "lend a book", "list_loans"): that card

Anything else goes to the planner (Claude) when it is on.

Constants

  • MENU = array('what can i do', 'what else can i do', 'what can you do', 'help', 'menu', '?', 'options')
  • ON_IT = ...

Methods

Shell::onFocus()

public static function onFocus($text, Context $context, $focus)

A follow-up on the record the conversation is about, at once: "delete it", "change this", "lend that one". Anything longer ("lend it to Sam") goes to the planner, with the conversation's memory.

Parameters

  • $text
  • $context Context
  • $focus array|null: ['capability' => 'get_book', 'input' => ['id' => 7]]

Source: framework/core/Snap/Shell.php:31

Shell::fast()

public static function fast($text, Context $context)

No doc comment.

Parameters

  • $text
  • $context Context

Source: framework/core/Snap/Shell.php:51

Shell::menuCard()

public static function menuCard(Context $context)

The menu as a card: Go: Shortcut in its menu variant (ready-made starts the system offers, not ones you saved)

Parameters

  • $context Context

Source: framework/core/Snap/Shell.php:73

Shell::menu()

public static function menu(Context $context)

The menu: every card this person may start, with its family and type

Parameters

  • $context Context

Source: framework/core/Snap/Shell.php:84

Shell::normalize()

public static function normalize($text)

No doc comment.

Parameters

  • $text

Source: framework/core/Snap/Shell.php:99

Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.

Start here

Why Caligrafy: the benefits, the measurements, and what it is not yet

  1. Quickstart with Claude: describe it, approve it, ship it

    or the Quickstart: the same three steps by hand, in 5 minutes

  2. How Caligrafy works: the ideas in 5 minutes
  3. Your first capability: build a feature, page included

Capabilities

Experiences

Data and people

  1. Models
  2. Relationships
  3. Queries: filters, paging, related rows
  4. Sign-in, users and tokens

Built-in features

Put it online

Build with AI

Reference

Clone this wiki locally