Building a yaks app
The platform is yaks.app, written the way its address is: lowercase, with the .app. An app built on yaks.app is a yaks app.
A yaks app is an index.html and whatever files sit beside it, served live at <space>.yaks.app/<app>/. No build step is needed: what you write is what the browser gets, except TypeScript and npm imports, which app_deploy compiles. Every other HTML file is a page at its own address, and a site any tool builds serves as built from a folder of the app (code). Every app comes with its own store, a graph of entities, and a small client for reading and writing it from the page. Apps in the same space can work with one entity across those stores.
Make one with app_new, write files with app_files (the whole set in one call, as files: [{path, content}, ...]), and check the private draft with app_preview(app, width: 390) and app_preview(app, width: 1280). Each call returns a screenshot, the page's console messages and JavaScript errors, WCAG 2.1 AA accessibility problems with their rule, element and fix, and a private preview URL. The browser runs on Cloudflare; use these connector tools directly without a local checkout, shell or browser. Fix the reported accessibility problems and other issues, then app_deploy, and give the person the released URL.
The person can also make or update one without you: the drop zone on their space's own page accepts a .zip of an app's files, or a single index.html.
This page is the map. Each section says what a subject is and names the page that covers it; the pages are the reference. Add .md to any page's address for the markdown an assistant reads.
Frontend Data
Every app is served a client at ./api/client.js for reading and writing the app's own store: apply saves, query lists, search searches, subscribe is a query that keeps calling back as rows change, upload saves bytes, and me reports who is looking. It exports more for particular jobs: was and outbox for writes, digest for a file's SHA-256, drafts and draftEid for typed input, publish, unpublish and publicFiles for public files, and store(base) for another app's store. Write every address in the app as a relative path from the page's own folder: the platform gives each page a <base href> at its folder under the app's address, so the same files work wherever the app is served or installed. A page in a folder reaches the client at ../api/client.js.
import { apply, me, query, search, subscribe, upload }
from './api/client.js'
await apply({ entity: { eid: '$cake' },
doc: { title: 'Lemon cake', body: '3 lemons...' } })
let recipes = await query('.doc')An entity is a bundle, {entity: {eid}, ...components}; a $alias in place of the eid creates one. Who may read and write is the app's access: public, open or private. Ask me() on load and shape the page before anyone types.
Deeper: Frontend Data — every function of the client, the HTTP endpoints underneath, and who may read and write.
Performance
A page's load time is set by its network round trips, and a read that waits for another read's answer adds a round trip. So a page subscribes to what it draws, every kind in one line, and calls me() at the same time rather than first:
subscribe('(.recipe|.chore)&?doc', draw) // its first rows over HTTP
let who = await me() // beside them, not aheadThat loads in one round trip. subscribe(...).ready resolves with the first rows, for a page that needs them before it continues, so a page never queries a filter and then subscribes to the same filter.
Deeper: Performance — why that is one round trip, how to see a slow page's round trips and the Server-Timing header on every response, and what else slows a page: chains of module imports, images, and work done on every change.
Files and Uploads
app_deploy releases the app's draft. Open pages get a yak-release event with {version, reload} and an optional or required Reload notice, never an automatic reload. An app can take over the notice without losing input. Use reload: 'required' on app_deploy for a changed contract the vocabulary cannot describe; otherwise the platform derives the level.
An icon.svg beside index.html, square and without <text>, is drawn as the app's icon on a home screen. upload takes a file and returns where its bytes live, addressed by their own SHA-256, and a row that points at them is what a gallery draws. An upload is held to the space's room and the app's blob word, so downscale a photo on the page to keep it quick to send.
Deeper: Files and Uploads — releases, yak-release, app_deploy's reload, the app's icon, uploads, pictures, and a gallery that never shows one twice.
Copy and On-Page Editing
An app's copy, the words its pages show, goes in copy.json at its root, a key per snippet, and each element names the snippet it shows with data-copy. The platform fills the element as it serves the page. Write every new app this way: the person can then change any word on the page itself, where a member who writes the app sees a pencil in the bottom-right corner that lets them type over each snippet, kept as their draft. Save writes their changed snippets into copy.json and releases only it: app_versions lists the release and app_rollback takes it back.
{ "cost": { "title": "What it costs",
"limits": "Tax is included. %{plans}.",
"plans": "Compare plans and limits" } }
<h2 data-copy="cost.title"></h2>
<p data-copy="cost.limits">
<a href="/pricing" data-copy-slot="plans" data-copy="cost.plans"></a>
</p>A value is plain text; a link or a bold word inside a sentence is a slot, %{name}, filled by the child marked data-copy-slot. A script that draws text reads ./copy.json and marks what it draws the same way. An existing app moves its text into copy.json only when its owner asks.
Deeper: Copy and On-Page Editing — the file, attributes such as data-copy-placeholder, slots, text a script draws, editing on the page, and moving an existing app's copy.
Visual Design
A page's look starts from what the app is about, who uses it and its main job. Plan four to six colors by role, one or two typefaces and a type scale, and the first screen at 390 and 1280 pixels before writing code, and put them in CSS custom properties. Open with the thing the app is for, put emphasis in one place, keep motion to what answers an action, and meet keyboard focus, contrast and reduced motion without being asked. The defaults a model reaches for when nobody chose (a cream page with a serif and an orange accent, identical rounded cards, gradients, capitals above every heading) are what to avoid unless the person asked for them.
Deeper: Visual Design — planning, type, color, layout, motion, accessibility, interface wording, the defaults that look generated, and checking with app_preview.
Components and vocab.json
A component is a named set of properties an entity carries. The platform's own, doc, task, completed, comment, person, attachment, image and the rest, are shared by every app. An app declares components of its own in a vocab.json at its root, and app_deploy installs them in that app's store:
{ "$defs": { "recipe": {
"description": "A dish someone cooks, shown as a card on the box's front page",
"properties": {
"serves": { "type": "number" },
"minutes": { "type": "number", "description": "Time from start to table" } } } } }Give every component a description saying what it is and where a person sees it, and each property one where its name doesn't say what it takes. They are the app's documentation: every agent that works in the app reads them first.
A later deploy may add a property; one that already has rows is never dropped or retyped. A new capability is a new component, not a new tool.
Deeper: Components and vocab.json — every component with its properties, and vocab.json for declaring an app's own components.
Deeper: Realtime Sync and Persistence — sync, durable, pace and save: what players see, what stays in a browser, and what the store keeps.
Multiplayer Games
A game's page reads the graph, computes rules and writes bundles. @yaks/game provides rules, controls and HUD parts; @yaks/stage draws ordinary geometry and sound, and @yaks/voxel/three supplies a voxel look. One elected page advances shared creatures; the others draw their relayed values.
Deeper: Multiplayer Games — Holdfast's working multiplayer pattern, toolkit dependencies, shared time, owner handoff and dropped orders.
Scheduling
An app has no cron job and no process that keeps running. Any row can carry a wake component with a time and a recurrence; at that time the store wakes and writes fired on the row. What a firing does is a rule declared in vocab.json, and an app's own commands can be scheduled the same way.
Deeper: Scheduling — every property, recurrence and time zones, pausing and resuming, what a rule may match, scheduling a command, and why there is no cron trigger to configure.
Cross-App Data
An eid means the same entity everywhere. Apps in one space can each add their own component to it, or one app can use a component another app declares. Each component has one home, so a page or command reads and writes it there without copying rows between apps. Each app's access still decides who can read or write its part. graph_query with no app named reads every app the person can reach.
Deeper: Cross-App Data — which app a component lives in, and a two-app pair end to end.
App Commands
An app can declare commands, so the person's agent can act on it without a page open: a $defs entry of vocab.json marked "tool": true, the way a yaks package declares its tools, with a description, an argument schema, and one action, an apply template or a query. They are listed by commands and run by command; they never join the connector's own tool list, which is fixed and the same for everyone. Declare one for each task the app's person does again and again when it is more than adding one row of one component, named as they would say it (add_agenda, schedule_meeting); each component already has an add_ and a find_.
"log_run": {
"tool": true,
"description": "Log a run for the club leaderboard",
"input": { "who": { "type": "string" },
"miles": { "type": "number" } },
"required": ["who", "miles"],
"apply": { "entity": { "eid": "$run" },
"jog": { "who": "$who", "miles": "$miles" } } }Deeper: App Commands — the whole reference for a command, and the view protocol.
AI Models
An app asks a model with rows, not a key: a page writes an entry in a transcript (any entity wearing session) with using{model} and sending{instructions}, the app's own store asks the model, and the reply lands in the same transcript for any page subscribed to see. questions beside the entry are answered by the typesafe/jev model as answer rows (a choice, a yes-or-no, a score), and a command marked "model": true is one the model may call. One call answered at once is a post to ./api/ai/run, or env.AI.run in a worker, and a question about a picture is one of those, the picture inside it. Every call spends the space's monthly budget, weighed in dollars by the model's price.
Deeper: AI Models — the rows that ask and the rows that come back, typed questions, one call at once, asking about a picture, who may ask, and the models and their prices.
Voice Calls
People using an app can talk to each other by voice: a page joins a call through the app's own ./api/rtc/ door with @yaks/rtc, publishes the microphone, and hears the voices it asks for. Who is speaking is the relayed rtc component on the entity they speak as. Every voice received spends the same monthly budget models do.
Deeper: Voice Calls — speaking, hearing, placing a voice in space, who may speak, and what it costs.
App Notes (NOTES.md)
A rule the person wants followed every time goes in a NOTES.md beside index.html: weights in grams, one photo per recipe. Any agent that can reach the app is given it, so the rule is stated once and followed from then on.
Deeper: App Notes (NOTES.md) — what belongs in the file, its size limit, and the three places it is handed over.
Memories
A memory keeps the person's own words for the whole space: store_memory_save stores a sentence verbatim with a line of context, and store_memory_recall finds it by what it is about. Save their words as soon as they say how they want something built or handled.
Deeper: Memories — the shape of a memory, what context is for, and how a recall is ranked.
Backend Code
An app's backend code is a worker.js beside index.html. Every request that is not /api/... reaches it first, and any request it answers with a 404 falls through to the app's files. env.STORE is the app's own store as the person looking, and a key the person connected (store_connection_need) arrives as env.NAME. Using a key does not need a worker: a page calls a connected service through ./api/fetch, which adds the key to the outgoing request.
A worker and a page's scripts may be TypeScript and may import npm packages: name the packages in a package.json, and app_deploy compiles them, pinning the versions it installed in package-lock.json.
Deeper: Backend Code — env, routes, keys, limits, whole workers to copy, and TypeScript and npm packages.
Sandbox
Each person has a private Linux container in each space, the sandbox, where an agent runs commands and keeps files while it works: a script over an attachment, a CSV reconciled against an app's data, an API call, a compile to WebAssembly, a site built with Vite or Astro. sandbox_write puts a file in, sandbox_shell runs a command, sandbox_read reads a file out, and sandbox_ship copies files into an app. Its files are temporary: only what sandbox_ship copied into an app is kept.
Python includes pypdf and pdfplumber for PDFs, python-docx for Word, openpyxl for Excel, python-pptx for PowerPoint, pandas for CSV and tabular data, and Pillow for images. pandoc converts document formats, and poppler-utils extracts PDF text and renders pages. LibreOffice Writer, Calc and Impress run headless for office-file conversion and PDF output. Copy an attachment's original bytes in with sandbox_write and its attachment id, then read, edit or write the file with sandbox_shell.
Deeper: Sandbox — the toolchains installed, how long files last, the network, the monthly compute time, and the yak CLI it is signed in with.
Front Page and Routing
The space's front page, set with app_set(app, home: true), is served at the bare address and is the space's router as well as its homepage: it sees every path no other app claims, and can ask for paths other apps own. A router that breaks fails open, so it never takes the space down.
Deeper: Front Page and Routing — the five steps a request goes through, the first globs, why a broken router fails open, and where the space's mail lands.
Web Clipping
An app can save a page from another website: a worker route fetches the URL and reads the page's metadata, and a bookmarklet opens that route with the URL of the page the person is on.
Deeper: Web Clipping — the whole clipper, the bookmarklet, and what to do when a site refuses.
Document Q&A
An app can answer questions from a library of documents: on an open app with "models": "open" and "blob": {"floor": "editor"}, its editors upload PDFs, Word files and web articles, and anyone with the link asks ./api/documents/ask and gets an answer citing the document and page.
Deeper: Document Q&A — the man