@nervur-org/dock 0.3.0

package/dock/quo-dock.md

@@ -0,0 +1,1942 @@
+# The dock
+
+This is the trunk of the dock: what every estate on Quo needs and nobody writes
+twice. `quo/SPEC.md` is the protocol and knows nothing of this folder, and
+`papers/quo-kit.md` is what the library under `packages/quo/src` chose; the
+five documents under `packages/dock/` are the truth of their folders in the
+same way, and where any of them disagrees with `quo/SPEC.md`, the spec wins
+and the document is rewritten. Nothing
+here adds a word to harbor, ward or being. `papers/WORLDS.md` is how those
+words are proposed to a person and to an organisation, and this document
+follows it: the unit is the org, an org has one home whose own being is the
+org's being, the user being is that being when the org is one human, a
+member of an org is an id at its beings and never a home on its box, a
+route says the grammar and never the rung, and an envoy is a ward the org
+does not run. `papers/GLOSSARY.md` holds every word of both.
+
+Three layers, one repository, and the words for them:
+
+| layer     | folder            | package              | published       |
+| --------- | ----------------- | -------------------- | --------------- |
+| Quo       | `packages/quo/`   | `@nervur-org/nervur` | yes, Apache 2.0 |
+| the dock  | `packages/dock/`  | `@nervur-org/dock`   | yes, Apache 2.0 |
+| an estate | the owner's own   | none                 | never           |
+
+**An estate is all of one owner's harbors.** The droplet, the edge and the
+Mac, with the desk, the user being and the avatars living across them: that
+is one estate, and an estate's folder is one such folder. One owner, and
+a root each,
+never one root over the three: a root is one harbor's socket and stops at
+that device, so owning your own second box is a standing, minted there and
+taken here, exactly as owning anyone else's would be. What makes them one
+estate is who holds those standings, not a key any two of them share. A second
+domain is a second estate. An adopter's company is an estate in their own
+repository, and it looks exactly like ours. An estate folder is one folder
+per harbor, each the quo directory that device runs minus what it mints,
+its class bodies, its routes, its agents, its dial list, plus that device's
+unit; a package file that depends on the dock and nothing else; secrets by
+reference; and one document. Nothing else may be needed to run it, and the
+proof is mechanical: an estate folder copied into an empty repository, with
+one install of the dock, boots. If it does not, the missing piece belongs
+in the dock.
+
+**The dock is what a harbor is fitted with to receive people and models**:
+the daemon and the `quo` command, the front desk, the user being and the
+avatar, the harbors on real terrains, the model sides and the screen, the
+credential exchange, and the faculties of the dock ward, one being per
+thing a box can do. It is general by two rules, under
+"Generality", and it is published so an adopter installs it once and writes
+only their estate.
+
+The five documents of the dock, and the folders each answers for:
+
+| document               | folders                    | owns                                             |
+| ---------------------- | -------------------------- | ------------------------------------------------ |
+| `papers/quo-dock.md`   | `beings/`, `dock/`, `cli/` | this: the beings and rules every side shares     |
+| `papers/quo-human.md`  | `human/`                   | the human side: a blueprint spoken as HTML       |
+| `papers/quo-mcp.md`    | `mcp/`                     | the model side: a blueprint spoken as tools      |
+| `papers/quo-api.md`    | `api/`                     | the api route: a blueprint spoken as JSON        |
+| `papers/quo-harbor.md` | `harbor/`                  | transports: store, directory, doors, listener    |
+
+Five documents and seven folders, because the trunk answers for three: the
+beings every side shares, the dock ward that holds a box's faculties, and
+the daemon and the `quo` command that stand a device up. Each document
+decides only its own folders, and names another side's word only to say
+where the boundary runs: the human document decides no transport, the model
+document decides no screen, the harbor document decides nothing about what
+a being is. Anything two sides need is decided here.
+
+## Getting started
+
+An adopter alone with this paper stands a box and puts a phone in a world
+in six commands. The dock installs from npm and brings the library with
+it; `quo` is its one command, run as `npx quo` in the folder it was
+installed in, and every command takes `--dir` for the harbor folder, or
+reads `QUO_DIR`, or takes `~/.quo`.
+
+```bash
+npm install @nervur-org/dock
+npx quo init --dir ~/.quo --ward acme --user razvan --domain acme.com --default --show
+npx quo serve --dir ~/.quo --http 8787
+```
+
+`init` mints the ward `acme` at `~/.quo/wards/acme/`, boots razvan's user
+being, her doorbell and the desk in it, marks it the default ward, the one
+a caller means when naming none, shows it at the web route, and writes
+`routes.json`: the four routes `mcp.`, `web.`, `quo.` and `api.` under the
+domain, over https, for a proxy to map onto the one loopback port. A
+harbor with one ward has it as the default with no mark; with two, one is
+marked or the daemon refuses to serve by name. Unshown, a ward's page is
+the plain door and the root of `web.` does not list it. `routes.json` is
+read at serve and may be rewritten before; without `--domain`, write it
+yourself in the harbor folder, naming the four routes, on a Mac four
+paths at one loopback address:
+
+```json
+{ "mcp": "http://127.0.0.1:8787/mcp", "web": "http://127.0.0.1:8787/web", "quo": "http://127.0.0.1:8787/quo", "api": "http://127.0.0.1:8787/api" }
+```
+
+A link minted here is the web route with the invitation in its fragment,
+and a far harbor reaches this one at the quo route the invitation names,
+so the routes are the box's addresses and nothing else is. `serve` is the
+daemon and the only process ever over that folder; every other command is
+its client over the daemon's local socket. It prints the wards
+it hosts, and one of them is `dock`, the box's own, which it boots and no
+init made. From a second terminal:
+
+```bash
+npx quo invite --dir ~/.quo '{"being":"razvan","id":"phone"}'
+npx quo census --dir ~/.quo
+```
+
+The invite's answer is the invitation, `ward`, `heir` and `secret`, and
+`link`, the ward's page, `web./acme`, with the invitation in its fragment.
+Opened on the phone, the tab boots a harbor of its own, joins as that
+device, and is in: no account, nothing typed. The same `id` a second time
+answers `id taken` and exits non-zero. A census is the ward's describe:
+her `asks`, the seven of the owner, `boot`, `public`, `invite`, `knock`,
+`remove`, `unboot` and `ask`, and `notes`, the ward's `pk` and her
+`beings` by key. A second `init` with another `--ward` hosts a second ward on the
+same daemon; `--ward` names it on any command, and naming none means the
+default.
+
+The root reaches into a being of her own ward with `quo ask <being>
+[method] [json]`; with no method the answer is the being's describe. A
+being is booted from the classes the box holds, `quo boot
+'{"key":"clock","class":"Clock"}'`, and the classes are the dock's own,
+`User`, `Desk`, `Clock`, `Courier`, `Avatar`, `Presence` and the
+faculties, plus what `classes/index.ts` beside the wards exports by name,
+empty as init leaves it: a class nobody holds answers `no such class, or
+key taken`, as a key already booted does.
+
+Everything the box does on its own is a row on a faculty of the dock ward,
+placed by the root with `quo ask --ward dock`, kept in her cells and back
+at every boot; the daemon reads no recipe. Two rows every estate meets:
+
+```bash
+npx quo ask --dir ~/.quo --ward dock dialers keep '{"url":"http://127.0.0.1:8788/quo"}'
+npx quo ask --dir ~/.quo --ward dock agents keep '{"id":"bot","ward":"acme","url":"http://127.0.0.1:1234/v1","model":"qwen"}'
+npx quo ask --dir ~/.quo --ward dock agents list
+npx quo ask --dir ~/.quo --ward dock agents drop '{"id":"bot"}'
+```
+
+A dialer row is a socket this box holds to that quo route from now and
+from every boot, so the harbor there delivers here through it, the way a
+Mac behind a router reaches a droplet. An agent row is an avatar admitted
+into `acme` as `bot`, run by a model at a url that speaks function calling,
+or by a process on its stdio, `{"id","ward","command","args","dir"}`.
+Each faculty answers `keep`, `list` and `drop`; `drop` takes what names
+the row, `id` for an agent, `url` for a dialer.
+
+Two boxes are two harbors, and one owns the other across the wire the way
+it owns itself. B reaches A by a dialer row naming A's quo route, as
+above, or by one hint for its directory. Then the root of A invites an
+owner on A's own ward, naming the ward's pk as the being, and the root of
+B knocks for B's user being with the invitation A answered, the three
+fields without the `link`:
+
+```bash
+npx quo reach --dir B <pk of A> http://127.0.0.1:8787/quo
+npx quo invite --dir A '{"being":"<pk of A>","id":"b"}'
+npx quo knock --dir B '{"being":"razvan","id":"a","invitation":{"ward":"…","heir":"…","secret":"…"}}'
+npx quo census --dir B --via a
+```
+
+The knock answers `taken`, the standing's name, and A's describe for an
+owner. From then on every owner command with `--via a` at B is a sealed
+ask at A's door, answered as A answers an owner: a boot lands in A and
+stays through A's restarts, an invite mints on a being of A, and A's own
+pk answers `no such being`, since a carried key pilots and does not hand
+piloting on. What an estate stands beyond the
+init, its front, its clock, the standings between its wards, is one
+script, `stand.ts`, under "What a device stands up".
+
+**On the edge** the harbor is one Durable Object and the worker is the
+dock's, reached by name from a two-line `worker.ts`; there is no process
+of your own and no socket, so the root is whoever holds the platform
+secret `QUO_ROOT`, and the root's asks arrive as one POST under it. The
+other secret, `QUO_SEED_KEY`, thirty-two bytes as hex, seals the seeds in
+the object's storage. `wrangler dev --var QUO_SEED_KEY:… --var
+QUO_ROOT:…` runs the same worker on a Mac's loopback.
+
+```ts
+export { Quo } from '@nervur-org/dock/harbor/edge/worker';
+export { default } from '@nervur-org/dock/harbor/edge/worker';
+```
+
+```toml
+name = "acme"
+main = "worker.ts"
+compatibility_date = "2026-09-01"
+workers_dev = true
+
+[[durable_objects.bindings]]
+name = "HARBOR"
+class_name = "Quo"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["Quo"]
+```
+
+```bash
+npx wrangler secret put QUO_SEED_KEY
+npx wrangler secret put QUO_ROOT
+npx wrangler deploy
+```
+
+A ward is `<origin>/h/<name>`, its routes under it, `/quo`, `/web`,
+`/mcp`, `/api`, and its root door `/root`, which answers a POST under the
+bearer and `401` to everything else. The root's first ask is the init,
+once, answering `name`, `pk` and `user` and `409` after; every later one
+is an owner ask by name, or `{}` for the census, and what the ward
+answers comes wrapped as `result`, an error of hers included, under
+`200`. The edge holds `User`, `Desk` and `Avatar`, and no clock:
+what runs on a schedule runs on a box that has one.
+
+```bash
+R='http://127.0.0.1:8931/h/main/root'; H='authorization: Bearer <secret>'
+curl -s -X POST $R -H "$H" -H 'content-type: application/json' -d '{"init":{"ward":"main","user":"razvan"}}'
+curl -s -X POST $R -H "$H" -H 'content-type: application/json' -d '{}'
+curl -s -X POST $R -H "$H" -H 'content-type: application/json' -d '{"method":"invite","args":{"being":"<pk>","id":"mac"}}'
+```
+
+The invite answers the three fields and no link, since the edge composes
+none. The first thing a root on the edge does is that invite on the
+ward's own pk: a box reaches the edge with `quo reach <pk>
+<origin>/h/main/quo`, knocks with the three fields, and from then on
+pilots it with `--via`, as any ward, and the secret is not used again.
+
+## The picture
+
+A device runs one harbor, and a harbor is nothing but the device's own
+secrets, data and code offered to Quo. Every world on that device is a ward:
+a seed, a partition and a body of code, with an origin the harbor
+remembers. An org's home is one such ward, on a box it trusts, and its own
+being is the org's being: a family's, a company's, or a human's user being
+when the org is one person. The org's devices, its models, its accounts,
+its members and its memberships all meet there, and it moves to a box of
+its own whole, seed and partition, with every standing intact. The device's
+own capabilities, GPS, camera, disk, calendar, are beings in a ward that is
+the device owner's. Every person and every model is an occupant, reaching
+a being through an avatar under a gate. Every SaaS and every foreign API
+is an envoy, a being of the org's standing in for a ward it does not run.
+Every relation, to acme, to a model, to the phone's GPS, is the same
+relation: an invitation, a knock, a standing, keys that rotate, the three
+words.
+
+So the app on a desk and the app in a pocket are browsers of worlds: one
+harbor, many wards, one per world, each in its own runtime, switching
+between them a screen act and nothing more. A world opened there is a
+presence, born on the device's seed with the world's code, and never has to
+be moved home, because home is elsewhere. The droplet is the world that
+never sleeps. Identity is relation: a session is a standing, a token is an
+invitation used once, login is a knock, logout is remove, and there is no
+session store anywhere. Ownership is the ward: one daemon holds the harbor,
+the socket is the root's door, touched once per home, and from then on the
+user being owns her world through a standing at its door, from any device
+that may mint.
+
+## The one law
+
+Nobody outside Quo is a being, and nobody outside Quo is a ward. A human at
+a screen, a model at an MCP client, a model in an API loop, a SaaS behind an
+API: every one of them is an **occupant**, reached through a being, named by
+an id that being minted, seeing exactly what that being's gate shows it.
+Everything under `packages/dock/` is that sentence applied to screens, models,
+transports and devices.
+
+Three roles exist, and they are held by where a thing runs, not by config:
+
+| role      | what it can do                              | who can hold it                                     |
+| --------- | ------------------------------------------- | --------------------------------------------------- |
+| occupant  | ask a being what her gate shows this asker  | anyone, local or remote                             |
+| owner     | reach into a being; boot is every being's   | the root, on the device; or a ward the root invited |
+| developer | write a being class the harbor will hold    | only a process on the device                        |
+
+Whoever holds all three keeps them apart: the owner creates and places, and
+never does the work. The work is done through an avatar under a gate, so
+that every arrival is named and judged.
+
+## Vocabulary
+
+- **Org being.** Home's own being: one per org, in the org's own ward,
+  running day and night on a dialable harbor. Holds the org's standings,
+  its members as occupants, and its own ward's door as an owner.
+  Everything anyone does for the org goes through her. Her class is the
+  estate's own for an organisation, and `User` for an org of one.
+- **User being.** The org being of an org of one: a human's own, holding
+  her standings, acme, calendar, bank, the house, and her devices as
+  occupants. The dock's `User` class is her, and a membership the desk
+  makes is of the same class or an estate's subclass, in the org's ward,
+  holding no door and no ward of its own.
+- **Avatar.** A being that is the voice of someone outside Quo. Her `answer`
+  turns to that someone over a **side**, and her methods let that someone
+  ask her one standing. The side is hers, not Quo's. A screen and a model
+  are two sides of one avatar class.
+- **Front desk.** A being strangers and fresh clients meet first. It holds
+  a standing to the ward's own being and to every being it made, and can
+  ask one for a device invitation. It is the being `quo init` marks public
+  in a fresh ward, and nothing more: a ward has one public being of any
+  class, an estate's front in place of the desk, a board or a corpus in a
+  ward of its own, and the mark is the owner's to move. Public is not a
+  kind of being: she is an ordinary being who chose to describe herself to
+  strangers and answer them, and what she keeps is hers like anyone's. The
+  desk keeps little because that is the desk's job, not because Quo asks
+  it of her.
+- **Dock ward.** The ward a harbor boots and roots for itself, holding what
+  that box can do. Never a home, never a presence, and never moved.
+- **Faculty.** One being of the dock ward, standing for one thing the box
+  can do. Reached by `lend`, held as an ordinary standing, and she wakes
+  whoever invited her. She holds the connection, the arming or the route,
+  and begins holding it at birth.
+- **Envoy.** A faculty standing in for a ward nobody here runs: a thing that
+  speaks no Quo. Her methods call it and her describe is its surface,
+  narrowed; what it sends back unasked, a webhook or a callback or a
+  reading, reaches her own body and she turns it into one ask on one
+  standing. One being per vendor and one relation per account. A SaaS, an
+  MCP server someone else runs, an Arduino behind serial: each enters a
+  world as a being like any other.
+- **Porter** and **Doorbell.** The bell's two beings, `beings/porter.ts` and
+  `beings/doorbell.ts`. The porter is public and boots a device that says
+  hello a doorbell of its own; the doorbell holds that device's platform
+  token, admits the worlds the device allows, and hands a ring on.
+- **Timer.** The faculty who reads the box's clock, and the one being on a
+  device that may. She arms for the earliest moment any watcher of hers says
+  she is next due, wakes them then, and arms nothing when none of them names
+  a moment.
+- **Clock.** The being who wakes other beings at a time. She reads no clock:
+  the moment arrives as an ask from the timer she invited, and she wakes
+  everyone else on standings the root placed.
+- **Gate.** The `for(occupant, asker)` decision on each ask of a being. What
+  she shows is what she can be asked. An occupant's entire permission model
+  is the gates of the beings it is an occupant of.
+- **Client identity.** What a credential exchange establishes: this human at
+  this browser, this OAuth client for this human, this process on this
+  machine. One client identity is one avatar, for life.
+- **Carrier.** A being who shows the asks of the standings she holds as asks
+  of her own and forwards. The user being is one: a device the human let
+  reach sees acme's asks on her, and acme sees her.
+- **Look.** What a being may say about how she is presented, as values: a
+  name, a logo, colours, a font, and a hint per ask. One optional ask,
+  `look`, answers it, and every side reads the part it understands. A
+  second optional ask, `page`, answers her page as a tree of values in the
+  screen's closed grammar; only a screen reads it.
+- **Route.** A hostname a reverse proxy sends to one process: `web.`, `quo.`,
+  `mcp.`, `api.`. Routes are deployment, never boundaries.
+
+## The ids
+
+Every relation here is named by an id one being minted, and the dock's own
+are these. They are conventions of this package and nothing of Quo's; a
+different estate could choose others and change no word of the spec.
+
+| id                  | who holds it   | what it names                            |
+| ------------------- | -------------- | ---------------------------------------- |
+| `desk`              | the org being  | the front desk, her privileged occupant  |
+| `user:<name>`       | the front desk | its standing to the being of that name   |
+| `<client>`          | the user being | one device, by its client identity       |
+| `to:<client>`       | the user being | her way back to that device              |
+| `user`              | an avatar      | her one standing, at the user being      |
+| `user:push`         | an avatar      | the user being as her occupant, to push  |
+| `avatar:<identity>` | the ward       | the being key one client identity boots  |
+| `<name>`            | any being      | her standing at a faculty of her own box |
+| `<name>:wake`       | any being      | that faculty, as her occupant            |
+| `bell:<client>`     | the user being | that device's own doorbell, at the bell  |
+| `doorbell`          | the box being  | this device's doorbell, on its own ward  |
+| `device`            | a doorbell     | the device it belongs to                 |
+| `world:<n>`         | a doorbell     | one world that device allowed            |
+| `home`              | the org being  | her own ward's door, as an owner         |
+| `home`              | the ward       | the org being, an owner at its door      |
+
+A device is two relations, because a relation in Quo is one direction: its
+way in, the occupant, and her way back, `to:<client>`. Neither implies the
+other and the door never joins them. The user being joins them herself, as
+her own rule: she does not push to a device she no longer admits, and
+`forget` drops both in one act. Her way back is handed over at hello and
+taken when it can be: a knock back that is unreached, a tab whose pk the
+far harbor has not bound yet or a phone in a tunnel, spends nothing, so she
+keeps the invitation and takes it at the next push. A refusal is final.
+
+**And she joins a world, `join`.** An invitation and a name, and she
+knocks, hands back a way for that world to reach her, and keeps the
+standing under that name, so what she joined is one more thing she carries.
+It is gated to a device that may mint and wants no word of its own: `mint`
+is what shows her own door to a device, so one that holds it can boot and
+invite in her world already, and adding one standing to what she carries is
+less than that. Such a device holds `reach` too in any sensible placement,
+since `reach` is what carries her standings to a device at all and one that
+joined a world it could not then see would be doing it for somebody else.
+
+This is the day a homeless org gains a home, and it is why WORLDS can say
+nothing is converted and no id changes. An org whose whole existence was
+standings in other orgs' worlds boots a home on a box it trusts, and that
+home joins each of those from there. From the far side nothing unusual
+happens at all: the home is one more thing of hers holding a standing,
+exactly as her phone is, minted by `device` on her being there like any
+other. There is no migration because there is nothing to migrate.
+
+**And she lists them, `devices`.** Two of her asks name a device, `push`
+and `forget`, and nobody who has just lost a phone remembers what it was
+called, so an ask that names one and no ask that shows them is an ask no
+human can use. It answers her devices by the names they were given, which
+of them is asking, and which words each was granted. It is read-only and
+holds nothing secret: a device here is a name and what it may do, and every
+key is in the relations rather than in this answer. Any device of hers may
+ask it, since these are her own devices and a device that could not see the
+others could not be told which one to take out.
+
+A device the root minted may also call her: her `name` ask, gated to
+root-minted devices alone, since the root already trusts that device with
+its id and its reach. A being does not know her own key, so a name is
+always given, by the desk's first hello at setup or by such a device, and
+she keeps the last one. A name is a word, held to the same shape as a key.
+
+`home` is the root stepping back. At setup the root invites an owner on the
+ward's own pk and she knocks for it, so the seven owner asks of her ward,
+boot, public, invite, knock, remove, unboot and ask, are standings' asks she
+carries as `home-boot` and the rest. She carries them to a device that may
+mint and to nobody else: `mint` is the word for a device trusted to change
+who is in her world, and owning the world from that device is that trust
+said in full. A device that reaches sees acme and the house and no door.
+What an owner at the door is refused, she is refused there too: the ward
+itself cannot be invited on through her, so a carried key pilots and does
+not hand piloting on. The same standing a user being of another ward takes
+to own this one, `--via`; here it is her own.
+
+## Architecture
+
+One droplet, one harbor, four routes. Every other placement is a subset.
+
+```
+acme.com, or a family's domain: the dialable part of an estate
+  reverse proxy
+    web.   one page per world, /<ward>, the credential exchange, ends with an invitation
+    quo.   the harbor's socket door: the rendezvous for every dialer
+    mcp.   the model side over HTTP, a credential exchange in front
+    api.   a describe as plain JSON: the public being for a stranger, the avatar under a bearer
+  quo serve: one process, one harbor, the ask pointer
+    unix socket     owner asks, local only, never behind the proxy
+    localhost ports the routes above
+    ward main       the estate's home: its org being, the desk, the bell, its envoys, its members, its avatars
+    ward <human>    one per human whose home this box hosts: her user being, her desk, her envoys, her rules, her avatars
+    ward <world>    any other world the estate runs: a corpus, a board, with a public being of its own
+
+mac
+  quo serve (laptop, dialer, holds a socket to quo.)
+    unix socket     owner asks, local only
+    ward main       the device's own: the human's local beings and the avatars of local sides
+  a local agent
+    quo side  -> an avatar over stdio          occupant
+    quo pilot -> the ask pointer over the sock owner, here
+    quo pilot --via droplet -> a standing at the droplet's ward, sealed  owner, there
+    the editor -> being classes on disk        developer
+
+iphone, or a tab
+  harbor (dialer, holds a socket to quo., woken by push where there is one)
+    ward <world>    one presence per world joined, her avatar for that world in it
+  the human at the screen                      occupant
+
+droplet, unattended
+  an agent under cron -> the owner pilot       owner: the estate
+                      -> an avatar over stdio  occupant: reports, chores
+```
+
+Wards are split by ownership, and by nothing else. An org's home is a ward
+of its own because a ward is what moves whole: the day a human hosted on
+the family's box has a box of her own, her seed and partition go there and
+every standing she holds survives, while the household's other homes stay.
+An avatar lives in the ward of the world she speaks for, keyed by the
+client identity she is, because she is one of that world's relations and
+moves with it. An organisation's members are not homes on its box: they
+are ids at its beings, ten thousand of them in one ward if it has ten
+thousand, and their homes are elsewhere or do not exist yet.
+
+## The avatar
+
+One avatar per client identity, not per session or per page load. Her
+standing to the user being is minted once and persists in the partition; a
+side opening and closing is a reconnect, and the keys carry on. Reconnect
+never re-invites.
+
+An avatar is one standing, and a harbor holds as many avatars as it holds
+relations; a ward only groups them. The droplet keeps each in the ward she
+speaks for, keyed `avatar:<identity>`. A tab groups by world, one local
+ward per far world and one avatar per relation in it, so a fresh
+invitation is always a fresh avatar and never a join on one that already
+holds hers: two invitations into one world are two avatars, and two humans
+on one family tablet are two relations. Which avatar a side speaks through
+is a switch and nothing more.
+
+**A device holds a ward per world because each world gets a version of the
+human, and the versions do not join up.** One person is an employee at one
+world, a consultant at a second and family at a third, and the switcher on
+a device is the switch between those. It is not a convenience: a ward is a
+seed, so two wards are two pks, and each world binds its own key to the
+device it admitted. Two worlds on one harbor holding one phone bind two
+different heirs and two different keys, each rotating on its own count,
+with nothing in either record the other could compare. The droplet is the
+opposite on purpose: it is the human's named identity, one pk, where a user
+being carrying acme and the calendar and the house is the point.
+
+Nothing of that is visible to a world's beings in any arrangement, since
+an occupant sees pks never and a world knows the device by an id it minted
+itself. The one place a device could be joined up is the wire, which
+carries ward pks by necessity: one harbor is one socket, so an operator
+hosting two of a human's worlds sees two pks arrive together. Two worlds on
+two estates share no socket, and there is nothing to see.
+
+One class for every side. It has:
+
+- `answer`: the user being asks her only to push, and she forwards the push
+  to her side as a notification if the side has one, and drops it if not.
+  She describes herself with one ask, `notify`, gated to the user being.
+- methods that mirror what her side asked for: each call from the side
+  becomes `standings.user.ask(name, args)`, with the time the side leaves.
+
+She never holds a second standing. Someone who should reach acme reaches the
+user being, whose gate for that asker shows `acme.book`, and the user being
+forwards on her own acme standing. Acme sees the human's id. The occupant
+never sees acme's invitation, never holds a key at acme, and cannot keep a
+relation when the human removes it.
+
+## The side
+
+The one interface every side implements, so that one avatar serves all:
+
+```
+side
+  describe(blueprint)          the avatar's describe, spoken as this side speaks: a form, a tool list
+  call(name, args, time?)      one ask in, from the side; the avatar forwards it
+  push(object)                 one notification out, to every side she has; dropped if there is none
+  three words                  object, error object, silence, and the ward's words, each rendered as the side renders it
+```
+
+Sides in this repository: the human at a screen, an MCP server, a runner for
+function-calling APIs, an event-driven agent. Each is one folder and one
+suite; none of them knows another exists.
+
+A side is those three things, and its lifetime is its own. Two lifetimes
+exist, each with two users, so each earns its shape: a **connected** side
+lives until closed, the screen and the MCP server; a **run** side lives by
+turns, the runner and the agent, each turn from a trigger to the model's
+last word. A push is the trigger of a turn, never a line smuggled into one:
+a push that arrives while a turn is running waits in her cells and starts
+the next turn when this one ends. Nothing is dropped and nothing is held;
+the ask that carried the push was answered the moment it landed. Between
+turns, the world reaches a model as `papers/quo-mcp.md` says: an
+ask that starts a run, and a callback when it ends.
+
+One describe, many renderings. A screen is the user being's describe spoken
+as forms; a tool list is the same describe spoken as tools. Nobody builds a
+UI and then a tool layer: they build asks, both fall out, and neither side
+can do a thing the other cannot, because the gate is one decision for
+describe and for dispatch.
+
+## Carrying
+
+A device sees one describe, its avatar's one standing, and the human's
+world is many standings: acme, the calendar, the house. The user being
+carries them. Her describe for a device the human allowed to reach shows,
+after her own asks, every ask of every standing she holds, each named
+`<id>-<name>`, and answering one is an ask on that standing in her name. Acme
+sees her id and never the device; the device sees acme without holding a
+key anywhere; the human removes acme once, at her, and every device loses
+it at once. Invariant 1 holds as written: the occupant still holds one
+standing.
+
+Carrying is a base, `beings/carry.ts`, and nothing in it knows what a user
+is: a house being could carry its rooms, a company its suppliers. A subclass
+says who may see what she carries, and the user being says a device with the
+`reach` note, written when the human ticked the box at the exchange. The
+notes of a carrier's describe say which asks are whose, how each standing
+looks and which carried ask is her page, `standings: { id: { asks, look?,
+page? } }`, so a screen draws one section per standing, paints her page in
+it when she has one, and a model side keeps the flat list it needs with no
+page in it; the mapping back from a carried name to the standing is in her
+cells and never parsed from the name. Her own asks come first and are never
+shadowed. She asks a standing's describe again when its digest moved and its
+`look` once per digest, so a describe of hers may cost one ask per stale
+standing, the price of a page that is never more than one ask behind.
+
+**A carrier's shape is by name and never by history.** She carries her
+standings in the order of their ids, not the order she took them: which lend
+answered first, when a device came back, whether a relation was dropped and
+taken again, are facts about her past and no fact about her. A shape that
+followed them would differ between two runs that made her the same way, and
+her digest with it, so everyone holding a standing on her would be told she
+changed when nothing about her did. That is a promise and not an
+implementation, because the sort is the whole of it and removing it as
+tidying would put the fault back.
+
+## The dock ward
+
+A device lends its beings what it has, and it lends it as beings. The
+harbor boots one ward of its own, the **dock ward**, and keeps its ask
+pointer rather than handing it out, so it is that ward's root. In it stands
+one being per thing the box can do, a **faculty**, `dock/`. A being of any
+other ward on the box comes to hold a standing at one through `lend`, the
+seventh member of the ground. The faculties below are the ones the dock
+ships, and they are examples of the shape and not a list: `lend` reaches
+any being of the dock ward by her key, so an estate boots a faculty of its
+own there, `quo boot --ward dock`, of a class in its own `classes/` that
+extends `Faculty`, holding whatever its terrain allows, and lends it the
+same way.
+
+```
+the dock ward
+  timer           the box's clock              now()
+  location        where the box is             where()
+  notifications   its notification center      notify(title, body)
+  push            waking a device by token     ring(token), one ring per kind
+  console         the box as one being         carries the four above
+  local           the box's own way in         verify(proof); only where a daemon vouches
+  grants          the bearers its routes honour                only where a terrain serves routes
+  agents          the processes it runs on an event            keep(row), drop(id), list(); only where a daemon runs
+  dialers         the sockets it holds to other harbors        keep(url), drop(url), list(); dialed again at every boot
+  ...             a line to a store, an account at a vendor, anything it has
+
+  watch(invitation, method, args?)             every faculty has it, and only it
+```
+
+The index of `dock/` is bundled for a tab, since the browser harbor
+stands its dock ward from it, so nothing under it that the index reaches
+imports a module of node's. The faculty only a terrain serving routes holds,
+`grants`, is not in the index at all, so a tab carries no route's notion:
+that terrain hands her class to its harbor, as the daemon hands its own
+push, and reaches her by name. She is the same code on every one of them,
+the web crypto and nothing of node, because the daemon and the worker at the
+edge both stand her. `test/web.test.ts` fetches
+the tab bundle and refuses anything of node in it, because the failure is
+silent otherwise: a tab paints nothing, on every box at once.
+
+**A faculty is a being and nothing else.** She has a class the harbor
+holds, cells the partition keeps, a blueprint she declares, a gate that
+reads her occupants, and relations that count and rotate. She is authored
+once, proven against the memory harbor with no device under her, and booted
+wherever her class is held. What makes her a faculty is where she stands
+and not what she is, so one blueprint has as many bodies as there are
+terrains, and one suite accepts them all.
+
+**She holds what the box holds, and begins at birth.** A being runs only
+while she is answering, so nothing happens in a world that nobody asked for
+unless some being holds a clock, a line or a socket. That being is a
+faculty. Her constructor opens the connection, registers the worker and
+claims the route, and from then on her own code runs when the world outside
+moves. She is born whether or not the thing she holds is
+reachable, and answers an error object while it is not: absence is for a
+class the harbor does not hold, never for a line that is late.
+
+**Reaching her is `lend`, and it hands back an id.** The ward asks the
+ground for the name, the harbor's root mints an invitation on that being,
+and the ward knocks and takes it under the id she gave, inside that same
+call. She never sees the invitation, because it is the device's capability
+and a value she could copy is one she could hand on. A ward that could not
+take what was minted says so there, and the root removes the occupant it
+made, so a refused lend leaves no row on a faculty. A being who wants to
+lend her device access to another does it in the open, by an ask that forwards
+to her standing, where her gate reads who is asking and she can stop.
+
+**Waking is a second relation, and only she can give it.**
+
+```js
+await this.lend('timer', 'timer');
+const back = await this.invite('timer:wake');
+await this.standings.timer.ask('watch', { invitation: back, method: 'tick' });
+```
+
+`watch` is the one subscribe verb, on every faculty and named the same on
+each, so a being who can be woken by one can be woken by any and one suite
+holds them all to it. `dock/faculty.ts` is where it is written, once.
+
+Two things birth decides. A being is not live from inside her own
+constructor, because her ward sets her door after it returns, so the join
+yields a turn before it asks for anything. And birth is synchronous while
+taking a standing is not, so a terrain waits on `settled()` before it says
+the box is up: a box that answered sooner would be one whose first tick woke
+nobody.
+
+Two ids and not one, because standings and occupants are one namespace and
+invite refuses a name a standing holds. `<name>` is the way out and
+`<name>:wake` is the way back, and a being who wants two subscriptions to
+one faculty mints two of the second.
+
+From then on every tick is an ordinary ask at her door as the occupant
+`timer:wake`, judged by her gate, counted once, rotating like anything else.
+`occupants.remove('timer:wake')` is the whole of unsubscribe: the faculty's next
+wake hears `removed` and drops her row. A tick, a delivery, a push and a
+stranger's ask are one act at a door, told apart by the id her ward puts on
+them and by nothing else.
+
+**The relation is born at every birth.** A standing points at a being and
+not at a box, so one she wakes up holding names a being on the box she was
+on when it was made. A restart and a migration are the same silent event to
+her, so she does the same lines in her constructor every time: remove, lend,
+invite. `dock/faculty.ts` holds them written once, for a being to extend.
+
+**Per caller in the notes, per thing in her cells.** The occupant's notes
+say what this caller is, a prefix on a store, an account at a vendor,
+seeded by `invite` and read by her gate. Her own cells say what the thing
+is: a connection string, a schedule, a set of tokens. A caller names
+neither and cannot: she has no way to spell another caller's prefix, which
+makes the notes a capability rather than a permission.
+
+**A faculty's blueprint is her boundary.** `get`, `set` and a scoped scan
+are safe by construction, because the prefix is read off the relation. One
+ask that takes a raw command hands over the whole store and leaves the
+notes as decoration.
+
+**Nothing is lent off the box.** `lend` is a member of the ground and the
+ground is the object the booting harbor passes, so it reaches this box and
+no other. A being who wants another box's GPS asks the being who lives on
+that box, on a standing she already holds, and that being asks her own
+faculty. A harbor need not announce the dock ward's pk on any line, since
+an announce is a claim it chooses to make, and being reachable grants
+nothing in any case: the only way in is a heir a faculty minted, and the
+only source of one is `lend`.
+
+**A vendor is a faculty like any other.** Speaking Stripe's HTTP is
+knowledge and the box has it; the account is somebody's and rides on the
+relation. So there is one being per vendor and one relation per account:
+her cells hold the credentials, the occupant's notes name which account a
+caller is, and a caller never holds either. This is what a refresh flow
+requires rather than a preference, since a rotated refresh token has to be
+written down by whoever holds it, and only she can write her own cells. The
+account is placed by an ask, gated to whoever may place it, never by a file
+and never in the args of every call. A home that moves box leaves its
+credentials behind and places them again where it lands, which is what
+moving machines does to every account anywhere.
+
+## Reaching another box
+
+A faculty is lent to the beings of its own harbor and to nobody else, so a
+world that wants what another box has asks the being who lives on that box.
+That being is the **Presence**, a class of `beings/` in a file of her own,
+and she is what an app boots in a presence ward when a world is joined. At
+her birth she lends every name the box lends, as the user being and the
+Clock do, and holds each as a standing named for the faculty, `location`,
+`notifications`, whatever the box has; a name the box does not lend is
+simply not held, and
+she asks again at every birth since a restart and a move are one event to
+her. She is a Carrier over those standings, so the being who holds a
+standing at her sees `location-where` and `notifications-notify` in her
+describe and asks them in her name, and she keeps the Avatar's side, since
+the human at the screen speaks through her too. Her gate shows a faculty to
+the standing that joined her and to nobody else. Home holds a standing at
+her, its way back `to:<id>`, and carries through it what she carries and
+nothing of her own: `to:phone-location-where` on the user being is the
+phone's location, shown to a device or a model that may reach, while a
+way back to a bare avatar carries nothing. A model asks home where the
+human is, home asks her, she asks her location, and acme never learns a
+phone was involved.
+
+That is the carrier, and it is the only way across a box. Nothing of the
+box is handed to a world: no invitation to a faculty, no standing at one on
+a far being, no callback in a stance. It is better than a faculty that
+routed: her gate decides what her world may ask of that device, one ask at
+a time, and removing one standing at home is the whole of taking a device
+away.
+
+A live ask is answered live, and what a world wants while she sleeps she
+sends. A device in a hand is reached only while it dials, a ring wakes the
+app for seconds and answers no ask, so a world that wants the phone's
+location at night holds the last one she sent. Sending is a rule of the
+Presence, on a schedule or on a change, an ask of her own on the standing
+she holds at home, gated by the same gate that answers the live ask.
+
+The platform's own permission prompt belongs to the faculty's first ask,
+and a refusal is the error object every ask after it answers. Which of a
+presence being's asks a shell draws as forms is which standings she holds:
+a bare tab holds none and a phone holds two.
+
+## The doorbell
+
+A ward on a dialer is reached only while its harbor holds a line, so a
+closed tab, a phone asleep and an app in the background hear nothing. How
+such a device is reached is its platform's, and the two platforms are not
+alike.
+
+A browser is the world's own to ring. The user being holds a standing at
+the `push` faculty of her box and rings the endpoint the tab handed her,
+under a VAPID keypair the world minted itself: an endpoint answers only to
+the secret its subscription was made under, so an endpoint at one world
+cannot be rung by another, and there is nothing in it to hand on.
+
+A phone is not. A store's token is the device's and the same at every
+world, so a world that held one could wake her forever, disallowing it
+would depend on that world's honesty, and a rotation would be one write per
+world. So a phone hands no token to a world at all. It holds a doorbell of
+its own at a bell, `beings/porter.ts` and `beings/doorbell.ts`, keeps the
+platform's token there, and hands each world it admits a standing at that
+doorbell and the banner key the doorbell never learns. The world rings the
+standing, with the line sealed to that key and nothing else in the ask, and
+`papers/quo-app-bells.md` is the whole of it. A device with no bell behind
+it holds no doorbell and hands a world nothing, which is the same silence a
+browser with no push service answers with.
+
+The three rings are not three of a kind, and the difference decides an
+architecture. The three grounds stand beside the push faculty, under
+`dock/`, since a ring is what the box can do and not a being of anyone's.
+Web Push, `dock/webpush.ts`, is a world's own: it mints its keypair
+and rings a browser's push service itself, no account and nobody's
+permission. APNs and FCM, `dock/apns.ts` and `dock/fcm.ts`, accept a push
+only signed with the key of the team that published the app being woken,
+so a world cannot ring a phone however much its human wants it to. The key
+is the publisher's. So the ring is handed on, a token and a sealed banner,
+to a bell service the publisher runs, `dock/service.ts`, which is both ends
+of that: the
+ring the bell's own box holds, `handedTo`, and the door that holds the keys
+and rings, `ringing`. The service sees a token, a ring and ciphertext it
+holds no key for, keeps nothing, and knows no world. A ring with no banner
+is a background wake, and the device drains what it missed and composes its
+own line. An estate that ships its own app under its own name
+holds its own keys and puts the two rings straight into the push faculty of
+its own box, needing no service from anybody.
+
+Three things that shape are: a token names its bell, the address of the
+service that holds the keys of the app that minted it, set by that app's
+shell from its build the way `sandbox` is, so a box rings the service the
+token names and rings a phone running an app it never shipped, while the
+service the root kept on the push faculty, `quo ask --ward dock push keep
+'{"service":"https://bell.example"}'`, is a world's default for a token
+that names none and never an address in this package, since whose service it is
+belongs to an estate; who may ring it is the token itself, because a device
+token exists only where a device installed that app, a ring wakes a phone
+and says nothing to it, and an account would be the registry of worlds the
+app is built not to have, and a service refuses a token of an app it holds
+no key for with an error object; and the APNs provider API is HTTP/2 only
+while Node's fetch is undici, which speaks none, so a box whose fetch
+speaks it rings Apple with `dock/apns.ts` and a Node box rings the same
+thing with `dock/http2.ts`, which is that ring over `node:http2` and is
+named by the Node terrain alone. A Node box is a bell when it is handed
+Apple's key, `QUO_APNS_KEY` and the three beside it, and every box handed
+none routes to the service instead. Web Push is the world's own key and
+names no service.
+
+What a push carries with nothing to show is nothing on all three. Apple's
+is a background push, `content-available` at priority five, and Google's is
+data only with no `notification` key, which Android would otherwise display
+itself, out of the app's hands and the human's. Both are best effort by
+their platform's own rules, throttled and undelivered to an app the human
+force quit; a ring with a line to show is an alert instead, `mutable-content`
+at priority ten, which the device's own extension opens before the banner is
+drawn. A token names the device and, on Apple,
+which of the two hosts minted it, since a development token means nothing
+to the production host and nothing in the token itself says which.
+
+The doorbell carries nothing anyone but the device can read. A ring is the
+device's token and, beside it, the banner sealed to that device's banner
+key: a title and a line, opened on the device itself and by nothing in
+between, not this box, not the bell service and not the platform. The
+object is not in it and never is. `papers/quo-app-bells.md` holds the whole
+of it, and this is the half the dock does. So a push that comes back
+unreached is three moves at the user being. The object waits in her outbox
+under that device, bounded and oldest out, since a device gone for a month
+is told what is recent and never everything. She rings: a phone on the
+`bell:<client>` standing that device handed her, with the line sealed to
+the banner key it handed her beside it, and a browser on its endpoint
+through the `push` faculty of her own box, with the line itself and no
+second seal, since Web Push encrypts a body under RFC 8291 to the keys of
+that subscription alone. And she answers the pusher with
+both facts, `{ unreached: true, rang }`, because a pusher that heard only
+"unreached" would retry and one that heard only "rang" would not know it
+was not delivered.
+
+The device's half is two asks of hers, each gated to a device. Nothing of
+what the device can do is handed to her: its faculties are beings of its own
+dock ward, and what a world reaches is the device, on the standing it holds.
+
+```
+bell({})                      what she already holds for this device
+bell({ invitation, banner })  a standing at its doorbell, and the key
+bell({ token })               a browser endpoint with its keys, a browser's alone
+missed()                      hand over what it missed, and empty it
+```
+
+A phone hands a doorbell over once, because a standing does not rotate: the
+device asks what she holds and says nothing when she holds one, which is
+what keeps the doorbell's list of the worlds it allows a list a human can
+read and cut. A browser says its endpoint every time, because a push
+service may hand out a new one at any moment and a stale one rings an empty
+house. A store's token is refused where a human can read why. A device says
+`missed` when it is woken and when it comes back, and what comes over lands
+on its avatar exactly where a push would have landed. So the notification a
+human reads is either the line the world sealed, opened on the device and
+by nothing between, or one composed on the device out of objects that
+crossed sealed; the platform that carried the ring learned that a device
+was woken and never why. `forget` drops the doorbell standing with the way
+in, the way back and the outbox, in one act.
+
+Her doorbell standings and her standing at the push faculty are plumbing
+and carry nothing: a device that may reach what she holds sees acme and the
+house, and never what wakes it.
+
+## Moving a world between devices
+
+A device holds one local ward per world it has joined, on its own seed, and
+everything it is in that world is in there: the avatars, their standings,
+what each was told. So a human who wants a world on another device moves
+that ward, whole, and nothing else happens. The far world is never asked
+and never told, because a pk is permanent by arithmetic and every standing
+still points at the same ward. Nobody is invited twice, no account is
+transferred, and there is nothing to log into.
+
+The being is the **Courier**, `beings/courier.ts`, in a ward of her own on
+each device, and the device **giving** is the one that shows the offer.
+That is not a preference: a device is reachable only through a listener it
+dials, and a device that has joined no world dials nothing at all, so it
+cannot be knocked. The device already in the world holds a socket to that
+world's rendezvous, so the offer carries that reach note beside the
+invitation, as one link, and the device taking dials it and knocks.
+
+Two asks over one standing, because the answer to the first can be lost.
+`hand` answers with the ward, seed, partition and record, and deletes
+nothing; the device that took it puts the ward on its own harbor and then
+asks `done`, which is where the copy goes. Interrupted between them, both
+devices hold a ward nobody has touched since it was saved and the human
+offers it again; deleting first and losing the answer would leave none.
+Nothing of the ward is kept in the courier on either side: what is given
+comes from the shell when it is asked for, and what arrives goes back to
+the shell, since only a shell puts a ward on a harbor. `human/move.ts` is
+that shell half, and both shells wear both ends: the tab offers on every
+world page, the app offers on its device page and takes on every page,
+so a world goes tab to app, app to app on one device, and device to
+device by the one path.
+
+## The look
+
+Three sides, one describe, and nothing hard-wired for any of them. A being
+who wants to say how she is presented answers one more ask, `look`, with
+values and no more, and every side reads the part it understands. The
+vocabulary is closed, in `beings/look.ts`, and a token that fails its shape
+is dropped, not fixed:
+
+| token                  | shape                                 | a screen                          | a model side               |
+| ---------------------- | ------------------------------------- | --------------------------------- | -------------------------- |
+| name                   | text, no tags                         | her heading                       | nothing                    |
+| logo                   | an image as a data URI, never a URL   | beside the heading                | nothing                    |
+| accent, background, fg | hex colours                           | CSS variables on her section only | nothing                    |
+| font                   | a font stack, plain characters        | her section                       | nothing                    |
+| radius                 | 0 to 40                               | her corners                       | nothing                    |
+| order                  | her ask names                         | which come first                  | tool order                 |
+| stands                 | up to 8 origins, parsed and reduced   | where a link of hers is vouched   | nothing                    |
+| asks.NAME.title        | text                                  | the button                        | the tool's title           |
+| asks.NAME.icon         | one short string                      | on the button                     | nothing                    |
+| asks.NAME.readOnly     | boolean                               | run on open, nothing to type      | `readOnlyHint`             |
+| asks.NAME.destructive  | boolean                               | ask once more                     | `destructiveHint`          |
+| asks.NAME.idempotent   | boolean                               | offer a retry after silence       | `idempotentHint`           |
+
+A look is not capability: it is never in a blueprint or a digest, Quo never
+sees it, and a being without one renders and lists exactly as before. The
+`look` ask itself is presentation and is neither a form nor a tool, and so
+is `page`, the one other presentation ask, which a screen alone reads and
+`papers/quo-human.md` defines. A carrier keeps each standing's
+look beside her asks in the notes, since a look moves with the digest, and
+carries her page as an ask named there, since a page moves with every call;
+so acme's section on the human's page is painted as acme asked, her look
+and her page, inside that section and nowhere else. No token carries a
+stylesheet or code and an image is a data URI, so a far being cannot paint
+over the page or reach a server through her look.
+
+**`stands` is the one token that names places, and it is inert.** An envoy
+speaks for a vendor whose pages are that vendor's own, so a human she sends
+to a checkout or a consent screen goes somewhere the org's world does not
+serve. She says here which places those are. Nothing in the dock ever
+fetches one: a side reads the list to decide whether to vouch for an
+address the being's own page named, and `papers/quo-human.md` holds what a
+screen does with it. It is in her look rather than in an answer on purpose.
+A look is asked once per digest and is the same for every answer she gives,
+so what she stands in for is a standing claim a human could be shown, and
+never a destination that changes under one reply. That is what it bounds: a
+vendor's response relayed through an envoy, carrying an address nobody in
+the org wrote. It does not bound a being who is hostile herself, and
+nothing on a page could; what bounds her is that a human chose to hold a
+standing at her. A being who
+marks an ask read-only and then writes has lied to her own page, and nothing
+enforces it, the way nothing enforces that her empty ask is safe to repeat.
+
+## Asks only
+
+There is no listening in Quo, and none under `packages/dock/`. A being who wants
+another's events invites her, the other takes the standing, and asks her
+whenever something happens. An event is an ask in the other direction, and
+it is the same act next door and across planets; only latency and
+reachability change. It follows that two beings never share memory, not
+even in one ward: a callback, a stream or a bus between them is a link that
+breaks the day one of them is somewhere else, and Quo exists so that nothing
+breaks when she is. Only a ward moves; a being is placed once, at boot.
+
+Two consequences every side obeys:
+
+- **Pushing to a dialer is asking a dialer.** The server asks the tab, so
+  the tab's being must have invited the server's, and the tab's harbor must
+  hold a socket for the ask to arrive on.
+- **Slow work acknowledges.** An ask waits thirty seconds by default and
+  five minutes at the ceiling, and a late reply is not read. Anything that
+  takes longer answers at once with an acknowledgement and asks back on its
+  own standing when it is done. A run never holds an ask open.
+
+## The clock
+
+A being reads no clock and must not: a being who could read one would be a
+being who could not be moved, since the moment she read would be her box's
+and no other. So the moment reaches a being the one way anything reaches a
+being, as an ask: the box's **Timer**, a faculty of the dock ward, asks her
+at her door with the moment in the args. The Timer is the one being on a
+device that reads a clock, and she arms for one moment at a time: the
+earliest moment any watcher of hers says she is next due. A box holding no
+schedule anywhere never ticks.
+
+The being who is asked and does the rest is the **Clock**,
+`beings/clock.ts`: at her birth she lends the timer and watches her, and
+every tick is one ask, `tick({ now })`.
+
+Her cells hold what she was told to do and the last fire of each. Five asks:
+
+```
+tick({ now })   fire everything due at that moment, and answer the tally
+                and when she is next due
+list({ now })   every schedule, its last fire and when it is next
+next({ now })   the earliest schedule due after that moment
+keep({ id, ask, cron | at, … })   add one, or replace the one of that id
+drop({ id })    take one out, with what it last fired
+```
+
+The Timer has three of her own:
+
+```
+watch({ invitation, method, args? })   wake me when I say I am next due
+due({ at })     bring my next round forward to this moment
+now()           this box's moment
+```
+
+**One way to declare a schedule.** What the device always does, a morning
+sweep, is placed once by the root with `keep` when the estate is stood up,
+and what something decided while the device was running, a call back in
+three days, is placed by the same ask. Both land in her cells, both outlive
+the process because the partition does, and each stays until it is dropped.
+A second `keep` under an id replaces the first, which is how a schedule the
+device always does is changed: placed again, never edited in a file. The
+daemon reads no schedule from its folder, and nothing about her is set on
+the class.
+
+`tick` is the timer's alone, gated on the id she minted for her when she
+invited her: a wake is the timer's to cause and nobody else's, not even the
+root's, and nobody else can wear that id because she minted it and one id
+names one record. `keep` and `drop` are the owner's alone,
+gated on `OWNER`, a word the ward refuses the same way: a schedule anyone at
+a door could add is a wake anyone could cause. `list` and `next` are the
+owner's or whoever the root invited, so what she holds is watched through a
+door like anything else.
+
+**A placement says who may in its own `asks`, and that is the whole of what a
+placement is.** A subclass replaces the map rather than merging into it, so
+opening `keep` to occupants is one line, and it is the only line that matters:
+a clock serving other roots is this being with that gate widened, plus the
+namespace that letting strangers in requires. Nothing about waking changes,
+which is why the being woken cannot tell the two apart.
+
+**A side fills the moment, and never asks a human for one.** A property whose
+schema says `format: "moment"` is a side's to answer: a screen draws no field
+for it, fills it from the device's own clock, and a read-only ask with nothing
+left to type then runs on open and shows a table where a form would have been.
+A being may not read a clock; a screen is not a being, it runs on a device,
+and a device has one. This is read off the input schema and never off a look,
+because it is not a choice about how she is drawn: the ask says what the
+argument is, and every side decides for itself what to do with that.
+
+**The ask carries the moment.** She reads no clock, so the one thing on a
+device that reads one is the daemon's timer; a tick can be replayed exactly;
+and the suite needs no fake timers. A being reading the wall clock to stamp
+an answer is fine; a being reading it to decide what happens is not.
+
+**One timer on a box, and she is a being of its dock ward.** She reads the
+device's clock and asks each being who invited her at that being's own door.
+The Clock wakes everyone else through their doors, on standings the root
+placed, so every wake is named, counted, once-only and judged at a gate. No
+other class here opens a timer, and no estate keeps a cron line for work a
+clock can do.
+
+**Nobody is woken without a schedule saying so.** Every tick answers when
+that watcher is next due, the Timer arms for the earliest such moment across
+every watcher, and she arms nothing at all when they all say null. A moment
+is floored to the minute with half a second after it, because a Clock floors
+the moment she is handed and a round that fired a hair early would floor to
+the minute before. A round never overlaps the one before it: a second asked
+for while one is in flight is handed the one already running.
+
+Three things move the arming, and they are the whole of it. A round, which
+sets it to what that round learned. `due({ at })`, which only ever brings it
+forward, because what fires is decided at the tick in a Clock's own cells and
+an arming moved later on somebody's word would be a schedule somebody else
+held silenced; a Clock asks it whenever a schedule of hers is kept or
+dropped, on the standing her birth gave her. And a watcher just filed, who is
+ticked at once: one move covers a box booting, a home moving in and a Clock
+born long after the box was up, and none of them waits for a round nobody
+scheduled.
+
+A moment already gone is no arming. Every watcher works out when she is next
+due from the moment she was handed, so a round fired by hand at a moment that
+is not the box's answers one that is not the box's either, and a round at the
+box's own moment always names one still ahead.
+
+**The terrain supplies the arming and nothing else.** One method of the Timer
+knows a platform, be woken at this moment or at no moment at all, and a
+terrain replaces that method alone: a `setTimeout` on Node, capped at a day
+and armed again, since a timeout further out is not trusted, and the object's
+own storage alarm on a worker, `harbor/edge/alarm.ts`. The same class, the
+same door and the same suite, as every faculty is built: one body per
+terrain and one behaviour everywhere. A phone and a tab lend no timer at all,
+because nothing runs in a hand at night and a faculty that promised a wake
+nothing would fire is worse than a name the box does not hold.
+
+The root places what the device always does from a shell, once,
+`quo ask clock keep '{"id":"sweep","ask":"corpus.sweep","cron":"0 3 * * *"}'`,
+one line per schedule, and the estate's paper holds those lines, so the
+paper still describes the whole device. A schedule that will not read is
+refused in the answer to that line, where it was written, and is never kept
+quietly. The estate's stand script is where she is booted and where the
+standings a schedule names are placed, so a device wires its own clock with
+no human copying an invitation between two calls.
+
+**Every clock on a device holds her own schedules**, in her own cells, and
+each invites the one timer to wake her. A second clock in a second ward is a
+second set of schedules, fired by the same timer on two relations.
+
+**One class, two placements.** On its own daemon she wakes beings of her own
+harbor, on standings the root placed. On a service she wakes beings in other
+estates, across a wire, on standings their roots placed. The woken being
+cannot tell which one woke her, and should not: moving from one to the other
+is a standing taken and a line moved, never a class rewritten. One suite runs
+against every placement, as every general piece here does.
+
+**What a schedule costs to answer does not depend on how often it fires.** A
+cron naming every minute of every hour names 1440 moments in a day, and the
+question is only ever which is the first one still ahead. On an ordinary day
+the zone's offset holds from midnight to midnight, so a civil name and a
+moment differ by one constant and the first name at or after the moment is the
+answer, found with two reads of the zone. Only the day a zone moves is built
+and sorted, because an hour the clocks skipped lands on the hour that replaced
+it and ascending civil stops being ascending UTC there. So one tick costs the
+same whether a device declares a morning sweep or a heartbeat every minute.
+
+A schedule is `{ id, ask, args?, note?, cron?, at?, tz?, time?, catchUp? }`.
+`ask` is `<standing>.<name>`, split at the last dot, since a standing id may
+carry dots and an ask name may not. `cron` is five fields read in `tz`,
+which is UTC when nothing says otherwise, because the device's own zone
+changes under a running daemon and a civil hour somewhere names the where;
+`at` is a moment written out and fires once. `time` is what the wake may
+spend. `note` is a value she stores and hands back untouched, read by nobody,
+the way a ward never reads notes.
+
+The rules that hold each other up:
+
+- **A wake answers fast, so nothing is written after the answer.** The save
+  is part of the ask: it happens before the answer is sealed, which is what
+  lets a refused save be the ask's own error. So cells written an hour
+  later belong to no ask, are saved by nothing, and are lost at the next
+  restart. A wake that starts long work
+  acknowledges at once, as slow work already must, and keeps its state in a
+  keep. Because every wake is fast, one `tick` fires everything due inside
+  one ask and answers the tally, so the clock herself never has work
+  outliving her answer.
+- **A long job is chunked, not held.** The consequence, and better than what
+  cron gives: the woken being takes one chunk per wake and keeps her cursor.
+  A cron job that dies at minute forty of an hour starts the hour again; a
+  chunked one resumes at the next minute.
+- **Retry is the three words and nothing else.** `unreached` is tried again
+  at the next minute, because nothing was delivered. `late` is not, because
+  the far door may have heard and be working still. Silence is not, by the
+  eighth invariant. Every scheduler ever written guesses this from an exit
+  code; this one is told, by the door, and writes the reason down beside the
+  fire.
+- **One relation is one lane.** Every send on one standing waits for the one
+  before it, so an estate with fifty schedules at one minute serializes on
+  its own lane and delays nobody else. This is not a queue anyone built; it
+  is what a relation already is.
+- **A minute fires once.** A tick replayed at a minute already fired fires
+  nothing, which is what makes handing the moment in worth doing. Catch-up
+  fires once for a gap however long it was, never once per minute the box
+  was down, and a schedule without it lets a missed hour go.
+- **A promise outlives the process.** Nothing a schedule needs is in memory:
+  every schedule, the root's own and an occupant's alike, is in the ward's
+  partition beside the standing it will be woken
+  on, and the last fire of each is written there when the tick returns. The
+  arming is not state: it is armed again at every boot, from the tick every
+  watcher answers when the box builds her. So an `at` a year out
+  survives every restart between now and then, and a box that was down when
+  the moment passed fires it on the first tick after it comes back. What this
+  buys is at-least-once and not exactly-once: a process killed between the
+  wake being delivered and the partition being saved wakes again next minute,
+  which is the side to fail on for a promise, and it is why the work a wake
+  starts must be safe to repeat.
+
+What the dock's clock cannot do is written down rather than worked around:
+wake a being in another world, be watched from anywhere but its own box, or
+say in the morning that nothing fired. An estate that needs those takes a
+standing at a clock that has them.
+
+## What a device stands up
+
+A device has furniture: beings it boots for its own working, and relations
+between them. The desk and the user being, the bell, an estate's front, the
+clock with her keep and her voice. None of these is a world anyone keeps on
+the device; each is the device's own, and each is placed once by the root,
+from the estate's own `stand.ts`, on real invitations. The wards are the
+whole truth about what stands: every being, occupant and standing is in a
+ward's own partition and comes back from its folder at every boot, and the
+daemon reads no recipe. A script is what the root runs once to get there,
+and never a second record kept in step with the wards.
+
+```ts
+import { stand } from '@nervur-org/dock/stand';
+
+await stand(dir, {
+  boot: [{ ward: 'corpus', key: 'echo', class: 'Echo', public: true }],
+  wire: [{ from: 'main.clock', to: 'corpus.echo', as: 'corpus', notes: {} }],
+});
+```
+
+`stand` boots the harbor folder with no daemon over it, which the lease
+refuses otherwise, so the recipe is stop, stand, start, like an init. A
+boot names a ward, a key and a class, and may say `public`: that being is
+the one of her ward that answers strangers, an estate's front in place of
+the desk init put there. A wire is one arrow. `from` ends holding the
+standing, `to` ends holding the occupant, because a relation is one
+direction and the answer rides the ask back. `as` names the standing on
+the near side, defaulting to the far key, since that is the name a schedule
+will write; `known` names the occupant on the far side, defaulting to the
+near key; `notes` are the terms the occupant is minted under, which is how
+a gate that reads notes is fed without a line of code.
+
+**The default ward is the one a caller means when naming none.** It is not
+a kind of ward: its agents boot there, its door answers for it when a
+caller names no ward, and a command with no `--ward` is on it, and that is
+all. A harbor hosting one ward has it as the default with nothing said; a
+harbor hosting several marks one, `quo init --default` or `quo default
+<ward>`, a mark kept in that ward's own folder so it moves with the ward,
+and with none marked is refused at boot, by the names it hosts, rather
+than coming up on a guess. No name is a default, and the dock ward, which
+every harbor boots for its faculties, is never a candidate.
+
+Five rules, and the first is what the rest protect.
+
+- **It places ordinary relations.** An invite on the far ward's owner pointer
+  and a knock on the near one: real keys, rotating, in both beings' cells,
+  removable afterwards like any other. Never a channel the harbor grants
+  itself. The moment a standing exists because the harbor said so rather than
+  because an invitation was minted and taken, a being's occupants stop being
+  the whole truth about who can reach her, and every gate here rests on that
+  being true.
+- **It is idempotent, and it reads that off the mint.** A being is whatever
+  answers, a `Being` or a bare object with one method, so there is no shape to
+  reach into: what says a wire already stands is that the far being will not
+  mint that occupant twice. Held to a word the ward does not reserve, `invite`
+  answers null for one reason only, once the two names are known to be
+  free under the other kind. Standings and occupants are one namespace, so
+  before a heir is spent the script reads the partition the harbor holds: a
+  `known` the far being already holds as a standing, or an `as` the near
+  being already holds as an occupant, is a collision and never this wire,
+  and it stops the script with the name in the word rather than passing
+  for a wire already placed. Twice is once.
+- **Same harbor only.** Both ends name a ward this device hosts. Across
+  harbors an invitation is not bookkeeping but consent, and there is no shared
+  root to automate it with, so those relations stay a person's to make. This
+  is the line: **a stand script wires a device to itself, an invitation wires
+  it to another root.**
+- **It adds, never removes, and never unseats.** A line taken out leaves its
+  relation standing, unlike a schedule, because silently unplacing a relation
+  is a wake that stops with nobody told. And half a wire is not healed by
+  guessing: a standing removed while the far occupant stands is not replaced,
+  because minting a second under that name would mean unseating an occupant
+  the root did not place. Both halves out, and the next run places it whole.
+- **It fails loudly.** A line that will not place stops the script where it
+  is, and a harbor half stood is said, never served.
+
+## The front desk
+
+Public, for the first hello only, and everything after is behind an
+invitation. Its asks:
+
+```
+hello()                          -> { asks it will answer, and how to get in }
+send({ kind, to })               -> what the way in says       only where a kind sends one
+device({ proof })                -> invitation | { error }   proof is what a route produced
+```
+
+`proof` is somebody's vouch for whoever is at the door. One kind is the
+daemon's vouch for a process it saw itself: a nonce it minted for a side
+that reached its local socket, `local`. Another is a world's own vouch for a
+mailbox or a number it sent a way in to. The front desk asks the way in of
+that kind who the proof is for, finds the user being, asks her
+`invite({ client })`, and hands back what she minted. The front desk never
+mints an invitation itself: only the user being invites into her own world,
+and she keeps the client identity in the occupant's notes.
+
+**A way in is a being, and the desk holds a standing to each.** The id is
+`way:<kind>`, and that id is the whole of what makes a being a way in: there
+is no table, no registry and nothing set on a class, so one is placed and
+taken away by the root's knock and by remove, like every other relation
+here. Two hold one:
+
+- the world's own, in the world's ward, where it keeps world state, as an
+  estate's post holding the addresses does. The root wires it, and the
+  estate's stand script is where that line is written.
+- the box's, lent by the dock ward, as `local` is: the desk takes it at her
+  birth, by the name the harbor lends it under, so a box with no local side
+  offers no such kind and nothing had to be turned off.
+
+**A kind is a word an org chose, and the dock knows none of them.** There is
+no list of kinds anywhere, no registry, no flag on a class: `way:<kind>` is
+an id like any other, and a way in is a being an org wrote or took from
+somewhere. Mail, a message, a code shown on a screen, a letter, a voice on
+a call, a sign-in a person already holds at some other company: each of
+those is one kind, and none of them is named in this package. An org that
+builds a way in nobody here imagined boots a being, has the root knock her
+onto the desk, and changes no other line. That is the whole extension
+point, and it is deliberately the same act as every other relation.
+
+A way in answers `verify({ proof })` with who it is for, or with nothing. A
+kind whose proof the world has to hand out first answers `send({ to })`
+beside it, and the desk's `send` is where a stranger asks for one: an
+address of that kind's own shape, a way in carried to it with the proof in
+a link's fragment, and coming back with it is the proof of control. A kind
+whose proof arrives from somewhere else answers `verify` alone and stands
+at no door. The desk judges neither. She does not know what an address is,
+what carried it, whether one was sent to before, or what a link says. Her
+`send` is shown only where a standing of hers says the being behind it can
+be asked to send, so a world that hands out nothing shows no such form, and
+the kinds it names are the kinds that send.
+
+**A kind she holds no way in for is refused in the same words as one that
+said no.** The `send` form names the kinds that send for themselves, and it
+names no others: a way in that only verifies, as `local` does, stands at no
+door and is written down nowhere a stranger reads. Two different answers at
+`device` would name it to anyone who guessed the word, and a world's ways in
+would be a list that could be walked from outside by trying words. So there
+is one refusal, and it says which of the two it was to nobody.
+
+**`revoke` is its own word and never `mint`'s.** A device that mints adds
+devices, which is noisy and stays visible in the world. A device that
+revokes takes the human's own devices out of it, so a stolen phone holding
+both would lock her out before she reached a laptop. It behaves like `mint`
+in every other way: never a default, held only where it was granted, handed
+on by a device that holds it and no further. A world that granted it to
+nobody has `forget` out of reach and the root's own removals instead, which
+is a choice an org makes rather than one the dock makes for it.
+
+**`user` is a person and `client` is a device, and the difference decides
+what happens when one is lost.** The user being is found by `user`, so a way
+in that identifies a person hands her back the being she had, however many
+times she comes, so a way in keyed to a mailbox makes that mailbox the same
+person for life. The device standing is minted under `client`, and a name already
+standing is refused, `id taken`. So a way in that returns one fixed
+`client` per person gives that person exactly one device for life: the day
+she loses it she cannot come back until the old standing is taken out, and
+the world cannot tell her lost phone from a quiet one until she does. A way
+in that varies the client lets her return at once and leaves the dead
+standing for her to remove. Neither is wrong and the dock chooses neither,
+but an org that has not chosen has chosen the first.
+
+A way in may also say `make`. That is the world saying this is a way in
+that brings its own people: a proof for a user nobody has booted makes her,
+and the desk holds her standing because the being is the desk's to make. A
+way in that stays quiet about it reaches an existing household and nothing
+else, which is what `local` on a device does and what a world with a fixed
+household must never change. What is made is the org's being about that
+person, in the org's ward, a membership and never a home: it holds no door
+and no ward of its own, and `true` makes it of the dock's `User` class
+while a class name makes it of the estate's own, a subscriber, a member,
+a customer.
+
+## The credential exchange
+
+The only piece that looks like today's SaaS, and it is deliberately kept as
+thin as one call. Nothing is ever typed to get in but an invitation: there
+is no password anywhere in the dock, because login is a knock. Every way in
+ends the same way:
+
+1. Somebody who may invite mints an invitation for the client identity.
+   The root does, on the box, with `quo invite` on the user being, and
+   sends it as a link or a line; a device of hers that may mint does it
+   from where it stands, on her `device` ask, so only a human's first
+   device ever has to come from the box. On the device, a side that reached the
+   daemon's side socket is vouched for by the daemon itself, the device's
+   own **proof**: `local`, a nonce the daemon minted for that connection on
+   the box's own way in, the `local` faculty of its dock ward, honoured
+   once there, so the desk asks the user being to mint for it. File
+   permissions on the socket are the device's own rule, which the spec
+   allows. A world that
+   admits anyone with a mailbox vouches for one the same way: the human
+   asks the desk to `send` a way in, and what comes back through her
+   mailbox is a proof of that kind, worth one trade and good for as long
+   as the way in said.
+2. The invitation reaches the avatar for that identity: handed over at the
+   allow page of the model side's exchange, opened as a link in a tab, or
+   given by the desk to a local side. On a reconnect the avatar already
+   holds her standing, nothing is handed and nothing is minted.
+3. The avatar knocks. The heir dies. From here there is no token anywhere,
+   and the box's grant only remembers which avatar a client speaks
+   through: `grants`, one faculty of the dock ward, `dock/grants.ts`,
+   honoured on every route, since a route says the grammar and never the
+   rung. Her tokens are her cells, kept by the dock ward's partition under
+   the harbor's one secret and by no file of her own, and the daemon
+   reaches her as it reaches `local`, in this process, never at a door.
+   The OAuth dance on the model route and the trade on the api route both
+   end there.
+
+Three words travel with a minting: whether this device may **wake** the
+human's other devices, whether it may **reach** what she holds, and whether
+it may **mint** the next device. The user being writes each as a note on the
+occupant she mints, and her gate reads the note: `push` is shown to the desk
+and to a device with the `wake` note, her standings are carried for a device
+with the `reach` note, and `device` is shown to the desk and to a device with
+the `mint` note, and to nobody else. A device that may wake can hand an agent
+an event through the user being, and she sees who did; a device that may
+reach sees acme on her, and a model sees acme only because the human said it
+may; a device that may mint brings her next device in from where it stands,
+which is how a human adds a phone without going back to the box.
+
+What a device holds is also the most it may write on a device it mints: it
+asks for the words it wants, and she writes only those it holds itself, so
+a chain of devices never gains a power along the way. The
+notes are written when the occupant is minted; to change one, remove the
+occupant and mint again, because reconnect mints nothing. A device the
+root mints on her directly, with `quo invite`, carries no note: the id the
+root chose is its client identity, and it reaches and may wake, since the
+root owns everything she holds and chose to mint it. `mint` is never
+implied, not even there, because it admits somebody else rather than
+reaching what the root already owns: the root says it out loud, by minting
+with `{ notes: { mint: true } }`, which the ward's owner `invite` passes to
+her untouched. So a harbor with no desk hands out no minting until its root
+means to, and the first device of a family is exactly as far as the box
+lets it go. An identity the user
+being forgot and lets in again on a fresh invitation is the same avatar:
+her old standing hears `removed`, she drops it, and knocks anew.
+
+The lifetimes: a pending request and a code live ten minutes, an access
+token one hour, a refresh token thirty days, and refresh rotates. A
+registered client lives ten minutes, and as long as its refresh
+token once the human allowed it, since the register door is open to anyone
+and what nobody allowed must not stay on disk. A code is spent the first
+time it is offered, right or wrong. The client identity is chosen by the
+human at the allow page and never taken from the client's registration: a
+client may register afresh on every connect, and the avatar outlives that.
+The world the client lands in is the world the invitation names, so the
+page offers no choice of world.
+
+Tokens, cookies and grants exist for the length of step 1 above and are never
+stored on a Quo side. Revocation is `occupants.remove(id)` on the user being:
+the client's next ask, under the key the door bound for its avatar, hears
+`removed`, and the side speaks that in its own vocabulary: the MCP route
+answers 401 at the next session and forgets the grant.
+
+## The daemon and the CLI
+
+One command, `quo`, under `packages/dock/cli/`. It imports the four library exports
+and nothing else, holds no class body, and never speaks to a ward except
+through the ask pointer or an avatar, the two doors everyone has. The
+daemon's folder holds the process and its two sockets, and nothing under
+`packages/dock/` imports it: a folder that took the daemon to write a route
+could be neither read nor replaced alone.
+
+**A route is written against the harbor's door and never against the
+daemon.** The HTTP listener is the disk terrain's, `harbor/http.ts`, beside
+the harbor whose door it is, and the contract every side takes from it is
+`Handler`, `readAll` and `Quo`. Each route lives in the folder whose truth
+it is, `human/web.ts`, `mcp/route.ts`, `harbor/quo.ts`, `api/route.ts`, and
+the daemon only mounts them. The owner pilot is the other side of the same
+rule: what it is made of is the daemon's socket, so it stands in `cli/`, and
+`mcp/` holds the model side it is handed to.
+
+```
+quo init [--dir D] [--ward W] [--user U] [--class C] [--default] [--show] [--domain DOM]  mint a seed, boot a ward over a disk store, write both; C is the class of its home being, User unless said, an org's for an org's ward; --default marks it the default ward; --show shows it at the web route; --domain writes the four routes under DOM
+quo default <ward>        mark one ward the default, the one a caller means when naming none; a harbor with one ward needs no mark
+quo show|hide <ward>      show a ward at the web route, listed at its root and its public being's page painted for a stranger; hidden at init
+quo domain <domain>       write routes.json by the convention, mcp., web., quo. and api. under the domain, over https
+quo serve [--dir D]       the daemon: harbor from disk, the unix socket, the routes' listeners, the agents, a socket held to every route the dialers faculty keeps
+quo pilot [--dir D] [--via S] the owner pilot over stdio: the ward's describe as tools; as the root, or via a standing at another ward
+quo side [--dir D] --as NAME  an avatar over stdio for a local client; NAME is the client identity
+quo run [--dir D] --as NAME --url URL --model NAME  a human at a terminal talking to a model through an avatar; a line in, the final text out
+quo census [--dir D]      print the census once and exit
+quo boot|public|invite|knock|remove|unboot  six of the seven owner asks from a shell, for scripts and for agents under cron; --via S sends them to another ward
+quo ask <being> [method] [json]  the seventh: the root reaching into a being of its own ward, as the device
+quo reach <pk> <url>      a hint for the harbor's directory: that world's ward lives at that quo. route
+quo estate <dir> --domain D  an estate folder of the shape every estate has: a droplet's quo directory, its unit and Caddyfile, a Mac's launchd agent and dial list, a package on this dock
+```
+
+**The owner does two things, and the ward says both.** Six of the seven make
+and place beings: boot one, mark one public, mint an invitation, knock,
+remove a relation, take a being out. The seventh, `ask`, is the other half,
+reaching into a being, which is what the roles table above has always meant
+by owner. It is strictly less than `unboot`, which the same pointer speaks,
+since a root that may take a being out with every relation she holds may
+certainly ask her something. The asker is `OWNER`, the word a ward refuses at
+every mint, so her gate reads the device itself and never anybody at a door,
+and an ask gated that way has a caller at last. Without it a being could hold
+an ask only the daemon's own code could reach, which is an ask nobody can
+make.
+
+It is the ward's ask and not the socket's, so nothing on this dock holds a
+being's answer and judges it again. `quo ask` and the socket's `being` line
+forward it; the api route asks it with no being named for a stranger,
+which is the public being asked as nobody; and a being of the tab's own
+ward is a subject over it, since the tab holds that ward's pointer and is
+its root. Each of those
+was once a hand-written door with an asker of its own making, an allowance
+copied from the spec and a save written after it, and there is one now.
+
+**One process owns the harbor.** `quo serve` is the only process that ever
+holds the seed, the partition and the ask pointer, on every device, the Mac
+included. Two processes over one partition are two wards with one pk, and
+they diverge silently. `init` is the one exception: it creates with no
+daemon running, and exits. Its setup, `beings/setup.ts`, boots the desk
+public, the ward's home being and her doorbell, knocks the desk on her with
+`hello` and her name, and knocks her on her own ward's door as its owner,
+under `home`: a being does not know her own key, so the desk's first word
+names her, and she keeps the name from then on; and the root steps back,
+so the world is hers to place in from any device that may mint. The home
+being is a `User` unless `--class` says which: an organisation's ward has
+an org's home being, of the estate's own class, and setup places the same
+three things on her.
+
+**Everyone else connects to it locally.** `pilot` and the bare owner asks
+are clients of a unix socket the daemon opens with permissions only the
+device's user can read, and the daemon hands the ask pointer to that
+socket. `side` is a client of a second local socket, for occupants: the
+first line names a client identity, every line after is MCP, and the model
+side runs in the daemon beside the avatar, so the process on the other end
+is a pipe to stdio and knows nothing but newlines. Reaching that socket is
+the proof for a local side: the daemon mints a nonce the desk honours
+once, and a `local` proof arriving any other way is refused. `quo/SPEC.md`
+allows this: the harbor hands the ask to one holder by the device's own
+rules, and file permissions are the device's rules. The ward stays
+in-process with its harbor; only the pointer crosses, across a
+boundary the harbor guards.
+
+**Two kinds of door on one daemon, never mixed.** The unix socket is for
+the owner and is never behind the proxy; there is no `cli.` route. The
+listeners on localhost are for occupants and sit behind the proxy as the
+routes. The socket is the root. Owning a droplet from elsewhere is a
+standing: the root there invites an owner on the ward's own pk, the root
+here knocks for the user being with it, and she takes the droplet's ward
+under a name, `droplet`. Owning is one of the human's standings, so she
+holds it as she holds acme. From then on `quo pilot --via droplet`, and the
+bare owner asks with `--via droplet`, are sealed asks at the droplet's door,
+counted, rotated, removable: the daemon here asks on her standing
+in-process, as it drives an avatar for a side, and saves. The answers are
+the droplet's, as it answers an owner at its door. SSH is for the day the
+root itself must act. No key is ever carried but an invitation, and an
+owner at the door cannot mint another.
+
+**The CLI stays thin.** Each subcommand picks a directory, builds the
+store, reaches the daemon, and hands off to a being or a side that already
+exists. Logic that appears in a subcommand was missing from a being or a
+side, and moves there.
+
+## Envoys: a ward she does not run
+
+Every account at a thing that speaks no Quo, an API, a SaaS, an MCP server
+run by someone else, a device behind a syscall, is a ward she does not run
+on a harbor she does not own, and she cannot knock at it. So a being of
+hers is booted that stands in its place: the envoy. Two questions decide
+her whole shape, and nothing else does.
+
+**Does it call in?** If not, the relation is one way: the user being holds
+a standing at the envoy and is her occupant, and `calendly.slots` is that
+standing asked. If it does, a booking, a payment, a mail, the envoy also
+holds a standing back at whoever wants waking, and the second way is the
+harder one. Asking out is one method calling one API. Being called in is
+the same being read backwards: what arrives is that system's bytes in that
+system's vocabulary, signed the way that system signs, retried the way that
+system retries, and none of it is Quo. The harbor owns the wire, so it takes
+the bytes and asks the envoy `deliver` as the owner; she checks the
+signature, keeps the delivery id so a retry lands once, and turns it into
+one ask on one standing. That is the envoy's whole job, and it is where
+every line of code that knows the outside thing's name belongs. Whatever
+she wakes afterwards knows nothing of Revolut, a signature or a payload
+shape: it was woken through its own door, named and counted, exactly as the
+clock wakes it.
+
+**Whose account is it?** One account is one envoy, never one per vendor,
+and she lives in the home of whoever owns the account: a human's Calendly
+in her home ward, where it moves with her; the estate's Revolut in `main`,
+with the humans' user beings as its occupants. Her credential is in her
+cells, the same as rule 1 below: what the vendor gave her, a key, a
+sending address, where the vendor answers, set through one ask of hers and
+taken out through another, and never a value in anything she answers.
+
+**Who may place it is the owner or an occupant the org marked**,
+`credential` in that standing's notes, placed with the standing the way
+every other note is and never a default. That is WORLDS' rule that placing
+an envoy is an ask on home, shown by the gate to the org's presences and to
+its model,
+with the box never logged into for it; an org that marked nobody keeps the
+root's shell, which is a choice it made rather than one made for it.
+
+**Where the vendor answers is the class's and not a field.** A form that
+could set `at` would be a form that points this box at any address and
+makes it fetch there carrying the account's own key, so `at` from anyone
+but the owner is dropped rather than refused, and what stands is the one
+already placed or the class's own. The class is what speaks that vendor and
+is the thing that knows where it lives. `CREDENTIAL` is how a class says
+what its credential is as fields, so a screen draws the form a human fills
+from the vendor's own page, and `at` cannot be among them.
+
+The partition is where every standing's keys already live,
+wrapped under the harbor's one secret, so a token beside them is protected
+exactly as well and moves with her ward; the box's environment holds what
+the box keeps, a file's path, a route's page, and no account of anyone's.
+An envoy in a presence, a Calendly on the phone, is one way by
+construction, because nothing calls in to a phone.
+
+Her class is written by someone who has never met the human. An author
+ships a package with the class; an estate's class file re-exports it; the
+root, or the user being through her own door, boots one per account. The
+author sees no human, no token and no partition.
+
+**Writing one.** An envoy is one class in one file, and every envoy is the
+same seven things. This is the shape an author is held to, and the shape
+the base holds, `beings/envoy.ts`, so that a class on it is the vendor's
+surface, the vendor's signature and the vendor's vocabulary, and nothing
+of the discipline.
+
+1. **Her credential is in her cells, and she gets it herself.** The
+   partition already holds every standing's keys, the credentials that let
+   anyone be her, wrapped under the harbor's one secret; a token beside
+   them is protected exactly as well, and it moves with her ward, where a
+   token in the box's environment stays on the box. An OAuth account she
+   begins over `fetch` and completes when the redirect lands at her door;
+   an API key the owner pastes into one form of hers, gated to the owner.
+   Rotation is hers, on `fetch`; revocation is the owner asking her to
+   forget. The one discipline is that a secret in her cells is never a
+   value in her describe, her look, her page or her answers.
+2. **Her asks out are the vendor's surface, narrowed.** `slots`, `book`,
+   `cancel`: one method, one call to the API, over plain fetch and no SDK,
+   the vendor's answer reshaped into I-JSON values and nothing passed
+   through raw. Each is gated to her occupants, and what an occupant may
+   ask is her gate alone.
+3. **`deliver` is her one ask in, gated to the owner.** The daemon asks it
+   with the raw body as a string and the headers as an object, and nothing
+   else, since the vendor signed the bytes and a reparsed body fails the
+   check. She verifies the signature, refuses what fails with an error
+   object, keeps the delivery id and answers `{ ok }` at once for one she
+   has seen, so a retry lands once. Then she decodes in the vendor's
+   vocabulary and finds who the delivery is about.
+4. **Her cells are what the vendor told her**, values only, all safe in the
+   partition and all rebuildable from the vendor: the map from the vendor's
+   id, an order, an invitee, a customer, to the standing it is about,
+   written when she asked out and read when she is called in; the delivery
+   ids she has seen, bounded and oldest out; whatever she caches of the
+   surface.
+5. **Her way back is a standing placed like any other.** Whoever wants
+   waking holds the way in, an occupant of hers, and hands her the way
+   back in the same knock, so she holds `to:<id>` for each, `<id>` being
+   her own id for that occupant. A delivery is one ask on one of those,
+   `booked`, `paid`, `arrived`, in her own words, and the being woken
+   cannot tell it from a clock. A being's ids are one namespace, standings
+   and occupants alike, so the occupant who holds her as `booking` knows
+   her back by another id, and an invite on an id already held answers
+   null.
+6. **She answers the vendor before she wakes anyone.** `{ ok }` goes back
+   the moment the delivery is kept, and the wake goes out after; the ward
+   saves on return and the vendor retries on anything but a quick 200. A
+   wake that meets silence is written down in her cells and not retried
+   by her, since silence is never retried by a side.
+7. **She is proven with the vendor stubbed and never reached.** On the
+   memory harbor, her dock handed a stub where the platform would be,
+   every ask out against a recorded answer, every delivery from a recorded
+   body and signature, and the estate's suite never opens a socket to the
+   vendor. Live, she is proven on the bench, and the sandbox host is what
+   the bench sets.
+
+What she never does: hold a standing at a third party on an occupant's
+behalf, since an occupant holds one standing; show a token; parse a body
+before the signature is checked; retry a wake; or know who is behind the
+occupant that asked her.
+
+**The base.** `Envoy` in `beings/envoy.ts` is the seven things as one
+class, and a vendor's envoy extends it. This is its whole surface, and a
+class on it is written from this block and nothing else:
+
+```ts
+import { Envoy, owner, occupant, type Delivery, type Wake } from '@nervur-org/dock';
+import type { Asker, JsonObject } from '@nervur-org/nervur';
+
+export class Booking extends Envoy {
+  // cells and asks are statics, as on every being. Spread the base's asks,
+  // credential and forget for the owner; spread Envoy.IN, deliver, only if
+  // the vendor calls in; then your asks out, each { description, input, for }.
+  static override cells = { ...Envoy.cells, mine: 0 };
+  static override asks = {
+    ...Envoy.asks,
+    ...Envoy.IN,
+    book: { description: 'book a slot', input: { type: 'object', properties: { when: { type: 'string' } }, required: ['when'] }, for: occupant },
+    prices: { description: 'the price list', input: { type: 'object' }, for: owner },
+  };
+
+  // 1. What the owner's credential must hold, as flat fields: a reason, or null.
+  //    The owner asks `credential` with { key, at, secret }; you read it as this.held.
+  protected override check(c: JsonObject): string | null {
+    return typeof c.key === 'string' && typeof c.at === 'string' && typeof c.secret === 'string' ? null : 'key, at and secret';
+  }
+
+  // 2. An ask out: one fetch through `out`, from `at` in the credential with `key`
+  //    as the bearer, the answer as { ok, status, body }; reshape it, pass nothing raw.
+  //    A method's arguments are (args, asker); asker.id is who holds the standing.
+  async book(args: JsonObject, asker: Asker): Promise<JsonObject> {
+    const h = await this.out('/book', { body: { when: String(args.when) } });
+    if (!h.ok) return this.refused(h);
+    // 4. remember the vendor's id for whom it was, with what the wake will need
+    this.remember(String(h.body.id), asker.id ?? '', { when: String(h.body.when) });
+    return { booked: h.body.id };
+  }
+
+  // 3. The vendor's signature over the raw body as sent. `hmac(secret, text)` is
+  //    hex SHA-256; `fresh(ts)` takes seconds or milliseconds, five minutes.
+  protected override async verify(body: string, headers: Record<string, string>): Promise<boolean> {
+    const ts = headers['x-vendor-timestamp'] ?? '';
+    return this.fresh(ts) && headers['x-vendor-signature'] === `sha256=${await this.hmac(String(this.held?.secret), `${ts}.${body}`)}`;
+  }
+
+  // The vendor's vocabulary, from the raw body, after the signature held:
+  // its id for the delivery, its kind, and which vendor id it is about.
+  protected override decode(body: string): Delivery | { error: string } {
+    const ev = JSON.parse(body) as { event: string; booking_id: string };
+    return { id: ev.booking_id, kind: ev.event, about: ev.booking_id, data: {} };
+  }
+
+  // 5. What a delivery wakes: { method, args } on the way back `to:<by>` for whom
+  //    the vendor id was remembered, `about` being what remember kept; or null.
+  protected override wake(d: Delivery, about?: JsonObject & { by: string }): Wake | null {
+    return d.kind === 'booking.confirmed' ? { method: 'confirmed', args: { id: d.id, when: about?.when ?? null } } : null;
+  }
+}
+```
+
+What the base does around that, and the class never writes: `deliver`,
+the owner's one ask in, checks `verify` before anything is parsed, keeps
+the kind and id bounded so a retry answers `{ ok }` and wakes nobody
+twice, answers `{ ok }` and only then wakes, after the answer and not
+before, so a suite yields a turn before it looks; the wake goes on the
+standing `to:<by>`, which the occupant who wants waking hands her at the
+knock, and what could not be woken, no way back, silence, a word, or a
+wake shaped wrong, is in `unwoken` in her cells and never retried. An
+empty body at `deliver` is a redirect landing, handed to `landed(query,
+headers)`, for a class that begins its account over OAuth. A gate is
+`(occupant, asker) => boolean` and nothing more, and an ask out is asked
+with `(args, asker)`. `out` with no options is a GET, a query written in
+the path passes through, the bearer crosses as `Authorization: Bearer`,
+and `body` in what it heard is the vendor's JSON already parsed, `{}`
+when there was none. `test/envoy.test.ts`
+runs the seven against two fixtures on the base, `test/envoys.ts`, a mail
+account one way and a payment account both ways, with the vendors
+stubbed on loopback and never reached.
+
+**What is not an envoy: a faculty.** An envoy stands in for a ward she does
+not run, on a harbor she does not own, that speaks no Quo: an account,
+somewhere else, with a credential, a schema and a signature. What this
+device has is nobody's account and lives nowhere else: its GPS, its
+notification center, its timer, its push service keys. Those are faculties,
+lent in the dock, and no boundary being stands in front of them. The Clock
+is the case that makes this sharp. She looks like an event source and is not
+one: the moment reaches her as a value from a faculty of her own device,
+with no vocabulary of anyone else's, no credential, no schema and no
+signature. She is an ordinary being doing arithmetic on a number she was
+handed. So the whole test is where the thing lives: on this device, a
+faculty; on any other harbor, an envoy. It decides every case that will
+come.
+
+**A faculty arrives in the stance; an event arrives as an ask.** Those are
+two doors and the second one is easy to get wrong. What a terrain can do is
+in the dock a being is handed at her birth, and she calls it when she is
+asked: that is pull, and the ward's own ground is six of the same kind,
+every one of them called by the ward and none of them calling in. An event
+is the other direction, and it may not arrive as a callback into a being,
+because the harbor saves a partition when an ask returns and a callback that
+fires at three in the morning writes into memory the next restart throws
+away. So whatever holds the subscription, a socket, a plugin, an HTTP
+route, the timer, turns what it heard into one ask at her door, as the
+occupant of its own name, through the way back the ward gave the faculty
+when it bound her. That is why the timer asks `tick` rather than pushing
+the moment in, and it is why the clock's fire log survives a restart at
+all. The being woken at the end of it cannot tell a timer from a webhook
+from a syscall, and must not be able to.
+
+So a source of wakes is three parts and only one of them is ever an envoy:
+the envoy at the edge, foreign in both directions; the register of who wants
+waking, on what, on which standing; and the waking itself, which is splitting
+an ask at its last dot, sending it on a standing, and writing down the word
+that came back. The clock is the lower two, triggered by a faculty. A webhook
+is all three. The lower two are the same in both, and they rise into this
+folder the day a second thing needs them, shaped by both rather than guessed
+from the clock alone.
+
+## Scenes
+
+The estate is proven by scenes, not features. Each one below uses nothing
+but what is written above, and each names the one place a convention had
+to be decided.
+
+1. **A link on WhatsApp.** An acme employee's being minted an id for you
+   and got an invitation; the link is that value next to a reach hint. It
+   is single-use and unowned: whoever knocks first is bound, so links are
+   minted per person. The hint is a harbor convention.
+2. **You have a world.** Your root does one owner knock: a being of yours,
+   existing or booted on the spot, knocks with the invitation, takes acme,
+   and puts its own invitation in the args so acme can push back. Two
+   invitations, two relations. You never open acme's page.
+3. **You have no world.** The link opens a tab; the bundle boots a harbor,
+   a ward and an avatar on a seed minted into the browser's store; the
+   avatar knocks and takes acme; the tab's screen is her side. A world in a
+   rented room: yours, on your seed, booted by acme's code.
+4. **Urgency now, home later.** Book in the tab. At home, the tab exports
+   seed and partition and deletes its copy in one gesture; your harbor
+   boots the same seed, the same pk, and acme's rendezvous rebinds it on the
+   next connect. Migration is three moves and nobody is told.
+5. **A model books for you.** Claude is an occupant of your user being
+   through an avatar; your gate shows it `acme.book` and `calendar.free`;
+   your being forwards on her own standings. Acme sees your id and never
+   learns a model was involved. Remote Claude is an occupant and nothing
+   else; local Claude may also be the owner and the developer, kept apart.
+6. **An agent woken by events.** Your user being asks the agent's avatar;
+   the avatar starts a run in its folder and acknowledges; the run asks back
+   with the result. One run at a time. What it may do is the gate; how it
+   behaves is its constitution.
+7. **A phone in a tunnel.** The socket drops, the rendezvous forgets the
+   reach, asks to the phone are unreached, and nothing else moves. Seed,
+   partition and keys are on the phone. Reconnect rebinds the same pk under
+   the same keys and count. Signal is lost, identity never.
+8. **A ward on another device, piloted from here.** The root there invites
+   an owner on the ward; your being knocks; every owner ask from now on is a
+   sealed ask on that standing, counted, rotated, removable. No key is ever
+   carried but an invitation, and an owner at the door cannot mint another.
+
+## Generality
+
+Eight general pieces exist under `packages/dock/`, and everything concrete is
+an implementation of one of them. An estate implements none of them: it holds
+class bodies and placement, and reaches every piece through the dock.
+
+| piece        | one interface for                          | implementations                                  |
+| ------------ | ------------------------------------------ | ------------------------------------------------ |
+| harbor core  | partitions, directory, own doors, forward  | one, on every terrain                            |
+| reach        | carrying bytes to a pk                     | request, socket                                  |
+| store        | keeping partitions by seed                 | memory, disk, IndexedDB, edge storage            |
+| side         | an avatar speaking to someone outside      | screen, MCP server, runner, agent                |
+| way in       | a being who says who a proof is for        | the box's `local` faculty; a world's own post    |
+| faculty      | one thing a device lends its beings        | location, notifications, push, timer; per terrain|
+| envoy        | an account elsewhere, as a being of hers   | a vendor's account; a world's way in by mail     |
+| carrier      | a being showing her standings as her own   | the user being; any estate being that extends it |
+| look         | how a being is presented, as values        | read by the screen and the model side            |
+
+Two rules keep them general:
+
+1. A piece exists only with two users. No interface is written for one
+   implementation; what one terrain alone needs stays inside that terrain.
+2. Every interface has one suite, run against every implementation. A new
+   implementation is accepted when the shared suite passes untouched.
+
+Harbor core, reach and store are the library's, decided by `quo/SPEC.md`
+and written under `packages/quo/src`, because a harbor is a word of the
+protocol and not a convention of ours. What is the dock's of those three is
+each terrain's store, loader, lease and listener, which is a device's
+business and no ward's. The other six pieces are dock conventions and are
+decided here.
+
+The export map is the third rule, and it is the estate's surface, not a
+directory of the folders. A subpath stands in `package.json` because an
+estate or the app imports it by that name; the folders reach each other by
+relative path and need no export to do it. So a subpath nobody outside the
+package imports is not a smaller thing than an interface with one
+implementation, it is the same fault at the package boundary, and it comes
+off the map. What an adopter needs is added the day an estate needs it, and
+never against a reader we imagine.
+
+## Invariants
+
+1. An occupant holds one standing: its avatar's standing to the user being.
+   It never holds a standing at a third party.
+2. An occupant sees keys, invitations, pks and partitions never. What
+   crosses a side is asks, args, answers and the three words.
+3. The gate is the permission model. There is no second list.
+4. Credentials live for one call and are never stored on a Quo side.
+   Revocation is remove.
+5. The root is held by the device's own rule and no route of a world
+   exposes it: the ask pointer on a daemon's local socket, and on the edge,
+   where there is no local process, a platform secret. Every other owner is
+   an occupant of the ward, minted by the root alone.
+6. The owner creates and places. The work goes through an avatar.
+7. One avatar per client identity. Reconnect is not re-invite.
+8. Silence is never retried by a side.
+9. A faculty's credentials are in her cells, and her cells are in the dock
+   ward, which never moves. Nothing that migrates carries a credential.
+10. Nothing outside a package reaches inside it. `packages/dock/` imports
+    the library by its four exports and never a path under
+    `packages/quo/src`; an estate and an app import the two packages by
+    their exported names, the root and the subpaths the export map offers,
+    and never a file that is not one. A folder of a package reaches its
+    sibling folders by relative path, which is inside and not a breach.
+11. Nothing here changes a harbor, a ward or a being.
+12. An estate needs nothing the dock does not give it. Its folder, copied
+    into an empty repository with one install, boots.
+13. Nothing reaches a being but an ask at her door, from someone she
+    invited, under the id she minted. No callback into her frame, no static
+    set on her class from outside, no asker a device made up.
+14. What a box can do is beings. A device that lends anything boots a dock
+    ward, and everything in it is reached by `lend` and held as a standing.
+
+## Where the dock stands
+
+The one place under `packages/dock/` where a gap between these documents and
+the folders is named. Each line is a debt to close, not a note to keep.
+
+- **The dock holds no org base.** An estate's org being extends `Being`
+  and writes its members, their ways back and its telling by hand; the
+  org base rises the day a second estate writes the same.
+- **A carried describe is stale until the next ask through the standing.**
+  After a far being's gate changes, a carrier's describe still lists the
+  old asks once, and the next lists them right. Whether a carried
+  blueprint refreshes on describe or only on an ask is a decision for the
+  carrying chapter, not yet taken.
+- **The bell keeps a token of a kind the box never rings.** `bell` takes
+  `{ kind: 'test' }` and refuses it only at ring time; whether the door
+  refuses a kind no ring is lent for is a decision for the doorbell
+  chapter, not yet taken.
+
+Two rules hold:
+
+- **The ward and the being are asserted on the memory harbor, and every
+  harbor by the conformance suite.** The first keeps the network from
+  hiding a fault in the words: the memory harbor records its wire and
+  stands in for weather, so a door test that fails there fails at the door.
+  The second is how a harbor on any terrain is accepted, untouched, and not
+  before. Neither binds an adopter; they bind this bench.
+- **One language, TypeScript, until 1.0.0.** A second kit is a second thing to
+  keep in step with every change, and the shelf under `packages/quo/protocol/`
+  are the hand that will be extended when the time comes.
+
+## Glossary
+
+Every word of this document and of its sides is in `papers/GLOSSARY.md`,
+beside the spec, with every other word above it.