@quo-systems/dock 0.1.0

package/beings/quo-dock.md

@@ -0,0 +1,698 @@
+# The dock
+
+This is the trunk of the dock: what every estate on Quo needs and nobody writes
+twice. `packages/quo/SPEC.md` is the truth of `packages/quo/src` and knows
+nothing of this folder; the four documents under `packages/dock/` are the truth
+of their folders in the same way, and where any of them disagrees with
+`packages/quo/SPEC.md`, the spec wins and the document is rewritten. Nothing
+here adds a word to harbor, ward or being.
+
+Three layers, one repository, and the words for them:
+
+| layer     | folder            | package             | published       |
+| --------- | ----------------- | ------------------- | --------------- |
+| Quo       | `packages/quo/`   | `@quo-systems/quo`  | yes, Apache 2.0 |
+| the dock  | `packages/dock/`  | `@quo-systems/dock` | yes, Apache 2.0 |
+| an estate | `estates/*`       | none                | never           |
+
+**An estate is all of one owner's harbors.** The droplet, the edge and the
+Mac under one root, with the desk, the user being and the avatars living
+across them: that is one estate, and `estates/lab/` is its folder. 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. It is general by two rules, under "Generality", and it
+is published so an adopter installs it once and writes only their estate.
+
+The four documents of the dock:
+
+| document               | owns                                             |
+| ---------------------- | ------------------------------------------------ |
+| `beings/quo-dock.md`   | this: the beings and rules every side shares     |
+| `human/quo-human.md`   | the human side: a blueprint spoken as HTML       |
+| `mcp/quo-mcp.md`       | the model side: a blueprint spoken as tools      |
+| `harbor/quo-harbor.md` | transports: harbor core, reach, store, directory |
+
+Each names only its folder. The human document never says WebSocket or
+OAuth; the model document never says form; the harbor document never says
+being. Anything two sides need lives here.
+
+## 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. 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 whose methods call out. 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 born on
+the device's seed with the world's code, and never has to be moved home,
+because it was never anywhere else. 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 device: one daemon holds the
+harbor, the socket is the only owner door, occupants come in by routes.
+
+## 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     | boot a being, invite for her, knock for her | 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
+
+- **User being.** One being per human, running 24/7 on a dialable harbor.
+  Holds the human's standings: acme, calendar, bank, the house. Everything
+  anyone does for the human goes through her.
+- **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 on the user's harbor that strangers and fresh
+  clients meet first. It holds a standing to every user being and can ask
+  one for a device invitation. It is the only being that is ever public, and
+  only for the first hello.
+- **Envoy.** A being whose methods call a non-Quo thing and whose describe
+  is that thing's surface. A SaaS, an MCP server someone else runs, an
+  Arduino behind serial: each enters a world as a being like any other.
+- **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.
+- **Route.** A hostname a reverse proxy sends to one process: `web.`, `quo.`,
+  `mcp.`. Routes are deployment, never boundaries.
+
+## Architecture
+
+One droplet, one harbor, three routes. Every other placement is a subset.
+
+```
+acme.com, or razvan.com: the dialable part of an estate
+  reverse proxy
+    web.   serves the bundle, runs 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
+  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       front desk, one user being per human, envoys
+    ward avatars    one avatar per client identity
+    ward estate     optional: what the estate agent asks
+
+mac
+  quo serve (laptop, dialer, holds a socket to quo.)
+    unix socket     owner asks, local only
+    ward main       the human's local beings
+    ward avatars    avatars for 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 lab -> 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 main       the human's avatar for this device
+  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 trust, not by feature. Avatars live in their own ward so
+that a class bug in an avatar takes down avatars, not the user beings. There
+is no rule that says so; it is the cheapest isolation a harbor offers.
+
+## 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.
+
+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 the way step 11 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.
+
+## 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 moves, and Quo exists so that nothing breaks
+when a being moves.
+
+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 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 }
+device({ proof })                -> invitation | { error }   proof is what a route produced
+```
+
+`proof` is the outcome of a credential exchange that already happened outside
+Quo: a session cookie `web.` set, an OAuth grant `mcp.` verified, a signed
+nonce from a local process. The front desk checks it with the verifier for
+that proof kind, 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.
+
+## The credential exchange
+
+The only piece that looks like today's SaaS, and it is deliberately kept as
+thin as one call. Every route ends the same way:
+
+1. The route authenticates by its own means. Password, passkey, OAuth, a
+   bearer token from a client, a nonce from a local process.
+2. The route asks the front desk `device({ proof })` and receives an
+   invitation.
+3. The route hands the invitation to the avatar it is about to boot, or to
+   the one already booted for this client identity if it is a reconnect, in
+   which case nothing is handed and the existing standing is used.
+4. The avatar knocks. The heir dies. From here there is no token anywhere.
+
+The human decides one more thing at step 1, on the same page that names
+the identity: whether this device may **wake** the human's other devices.
+The word travels with the proof, the user being writes it 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 that 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. The note is written when the occupant is minted; to change it, remove
+the occupant and allow again, because reconnect mints nothing.
+
+Tokens, cookies and grants exist for the length of step 1 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.
+
+```
+quo init [--dir D]        mint a seed, boot a harbor and one ward over a disk store, write both
+quo serve [--dir D] [--dial URL]  the daemon: harbor from disk, the unix socket, the routes' listeners, the agents, a socket held to URL
+quo pilot [--dir D] [--via S] the owner pilot over stdio: boot, invite, knock, remove, census; 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|invite|knock|remove  the four owner asks from a shell, for scripts and for agents under cron; --via S sends them to another ward
+quo reach <pk> <url>      a hint for the harbor's directory: that world's ward lives at that quo. route
+```
+
+**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.
+
+**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. `packages/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, `lab`. Owning is one of the human's standings, so she holds
+it as she holds acme. From then on `quo pilot --via lab`, and the bare
+owner asks with `--via lab`, 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: the non-Quo world coming in
+
+Every API, SaaS, MCP server run by someone else, and every device that
+speaks no Quo, enters a world as an envoy being:
+
+- Her methods call the outside thing. Her describe is that thing's surface,
+  narrowed to what the human wants exposed.
+- Her credential for the outside thing comes from the device's environment
+  through her class, never through her cells. Cells are values in the
+  partition, and the partition is the harbor's to persist; a secret written
+  there would be a secret the harbor has to lie about.
+- She is an ordinary occupant of the user being, or the user being holds a
+  standing to her, by the same invitation dance as any relation.
+
+## 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
+
+Six 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                |
+| proof        | turning a credential into an invitation    | one verifier, a daemon nonce, three kinds        |
+| envoy        | a non-Quo surface as a being               | none built: a name until its first user          |
+
+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 held across three terrains and moved into
+`packages/quo/src` with `packages/quo/SPEC.md` in the same commit on 2026-09-04;
+what stays here of them is each terrain's store, loader, lease and listener. The
+other three are dock conventions and stay here.
+
+## 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. Envoys read secrets from the device, not from cells.
+10. Nothing under `packages/dock/` imports a private path of `packages/quo/src`,
+    only the four package exports; nothing under `estates/` imports a path of
+    `packages/dock/` or of `packages/quo/src`, only the two packages by name.
+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.
+
+## 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.
+
+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 vectors under `packages/quo/vectors/`
+  are the hand that will be extended when the time comes.
+
+The order of work, each step usable on its own and each proving a sentence
+above or sending us back to fix it:
+
+1. Done. `packages/dock/` scaffold: its own package linking the library, the
+   four exports only, `check:dock` in the root gate, the terrain test pointed at
+   `packages/dock/beings`. The disk harbor in `packages/dock/harbor/disk.ts`:
+   one folder per ward holding seed, partition and the class source, a ward
+   record, the lease, and a save after every call. The `quo` CLI: init, serve,
+   census, boot, invite, knock, over the daemon's unix socket. Pilot and side
+   landed at steps 4 and 5.
+2. Done. The beings in `packages/dock/beings/`: `User`, `Desk`, `Avatar`, proven
+   on the memory harbor in `packages/dock/test/beings.test.ts`. A fake proof
+   becomes an invitation the user being minted, the avatar knocks and takes
+   her, and her tool list equals the user being's describe for her;
+   reconnect mints nothing; two clients see two tool lists; a push is a
+   reverse ask that reaches the side; remove is revocation. The ids that
+   carry the conventions: the desk is the occupant the root named `desk`
+   at the user being; the desk holds each user being as `user:<name>`; the
+   user being holds each device's way back as `to:<client>`; the avatar
+   holds the user being as `user` and is pushed to as `user:push`, two ids
+   because standings and occupants share one namespace.
+3. Done. The side in `packages/dock/beings/side.ts`: a function of the avatar
+   that runs until closed, and `word`, which tells the three words and the
+   object apart before any side renders them. The MCP server in
+   `packages/dock/mcp/server.ts`, proven over the SDK's in-memory transport in
+   `packages/dock/test/mcp.test.ts`: tools/list is her describe spoken as tools,
+   tools/call is a named ask, an object is a result, an error object and
+   the two words are error results with the text the trunk gives them, a
+   push is a logging notification, and a session closing and opening
+   reuses the standing. The SDK is the dock's first dependency, under
+   `packages/dock/` alone.
+4. Done. `quo side --as NAME` over stdio, proven in
+   `packages/dock/test/cli.test.ts` with the SDK's stdio client as a child
+   process: the daemon finds or boots
+   `avatar:NAME`, enters her with a nonce the desk honours once, and runs
+   the model side beside her; the tool list is the user being's describe
+   for that client; a second start is a reconnect and mints nothing; a
+   `local` proof from anywhere else is refused. `quo init` now does the
+   root's setup, the desk public and one user being named by `--user`, so
+   a fresh folder is a world. Claude Code and Claude Desktop on the Mac
+   need only `quo serve` running and `quo side --as claude` as the server
+   command: no droplet, no OAuth.
+5. Done. `quo pilot` in `packages/dock/mcp/pilot.ts`, proven in
+   `packages/dock/test/cli.test.ts` with the SDK's stdio client as a child
+   process: the owner's asks as tools and no more, census, boot, invite,
+   knock and, since step 16, remove, each
+   one an owner ask on the daemon's root socket, logged to stderr with
+   what it made. It is the root and not an avatar: nothing is booted for
+   it and no occupant is minted for it. With no daemon it says so and
+   exits. Claude Code as the owner is `claude mcp add` with
+   `quo pilot` as the command.
+6. Done. `quo serve --http PORT`: the HTTP door on loopback, `/health`
+   naming the wards, routes mounting by path so a hostname on the proxy is
+   a path on the daemon; proven in `packages/dock/test/cli.test.ts`. The systemd
+   unit and the Caddyfile are in `estates/lab/droplet/`. Disk store, the
+   lease and reboot from disk with relations intact were steps 1 and 4.
+7. Done. OAuth on the `mcp.` route in `packages/dock/mcp/oauth.ts`, mounted by
+   the daemon when `<dir>/routes.json` names the two public origins, and
+   proven over real HTTP in `packages/dock/test/oauth.test.ts`: metadata,
+   protected-resource metadata, dynamic registration, PKCE with S256, the
+   code grant, refresh with rotation, opaque tokens mapping a bearer to a
+   client identity, revoke by identity, and expiry. The conventions pinned
+   here: a pending request and a code live ten minutes, an access token
+   one hour, a refresh token thirty days; a code is spent the first time
+   it is offered, right or wrong; the client identity is chosen at the
+   allow page, not taken from the client's registration, because a client
+   like claude.ai registers a fresh client id on every connect and the
+   avatar must outlive that. The store is `<dir>/oauth.json`, the route's
+   own, mode 0600, and holds no secret of Quo's.
+8. Done. The exchange pages in `packages/dock/mcp/web/exchange.ts`, mounted on
+   the web route, proven over real HTTP in `packages/dock/test/web.test.ts`.
+   Login checks `QUO_OWNER_PASSWORD` in constant time and sets a signed
+   session cookie that lives ten minutes, the life of a request; with no
+   password set the exchange is closed. Allow names the client, where it
+   returns to, and the identity it will be, suggested from the client's
+   name and editable, one word and not the user or the desk. Allow admits
+   her through the one path every side uses: find or boot the avatar,
+   enter with a nonce the desk honours once under the `web` proof kind,
+   then complete the OAuth request with that identity. Deny sends the
+   client `access_denied`. Two pages, hand-written, rendering no blueprint.
+9. Done. The MCP endpoint in `packages/dock/mcp/http.ts` at `/mcp` on the mcp
+   route: streamable HTTP, a bearer names the identity, the identity names
+   her avatar through the same admit path, the side from step 3 runs
+   beside her, one session per connection, a session belonging to the
+   identity that opened it. Proven in `packages/dock/test/http.test.ts` with the
+   SDK's streamable HTTP client over the whole exchange. MCP is complete:
+   every human-assisted case on every device, with nothing of Quo's
+   crossing a machine.
+10. Done. The runner in `packages/dock/mcp/runner.ts`: the second side, an MCP
+    client written inline for a model that speaks function calling. Her
+    describe is a tools array, a tool call is a named ask, the three words
+    are tool messages, a line from the human or a push from the user being
+    starts a turn, and turns never overlap. Proven in
+    `packages/dock/test/runner.test.ts` over a scripted endpoint on loopback, and
+    live against Qwen3 Coder 30B in LM Studio on the Mac, which read her
+    describe, called `whoami` through the gate and answered with the id she
+    minted. What it taught: LM Studio refuses a parameters schema with no
+    `properties`, so the runner is where a describe is narrowed for an
+    endpoint, and nowhere else.
+11. Done. The agent side in `packages/dock/mcp/agent.ts`: the world is the loop.
+    A push from the user being is acknowledged at once by her `notify`,
+    lands in her inbox, which is the queue in her cells, and the side runs
+    it, one event at a time in order, then asks the user being back with
+    `report({ event, result })`, the ask this step added to her, gated to
+    devices. A run is a function of the event or a process in the agent's
+    folder with the event as its last argument, which is what `claude -p`
+    is. Proven in `packages/dock/test/agent.test.ts` with a fake run and a fake
+    process: the ask is answered before the run ends, a throw reports an
+    error object, and events that came while no side was up run when one
+    comes up. What it decided: the queue lives in the partition and not in
+    the side, so a restart loses nothing but the one run in flight. On a
+    device, `<dir>/agents.json` names each agent's identity, command and
+    folder, and the daemon admits her on the local proof and runs her side
+    beside her avatar; proven in the same suite over a disk harbor.
+12. The `quo.` route: Done. The reach interface with request and socket, since
+    the library move `packages/quo/src/harbor/reach.ts`, the disk harbor holds
+    the directory, and the daemon mounts `/quo` and dials with `--dial`. The
+    library's conformance suite passed untouched over two disk harbors on
+    loopback under both reaches, and the rendezvous carried a knock from a third
+    harbor to a dialer through its listener; `packages/dock/test/wire.test.ts`.
+    Live: a Mac daemon dialed `quo.lab.quo.systems`, an avatar there knocked at
+    the lab's user being across the internet, the lab knocked back over the held
+    socket and took `to:mac`, and a push from the lab landed in her inbox on the
+    Mac. What it taught: the proxy rewrites the route root with a trailing
+    slash, and a ward pk is 64 bytes on the wire;
+    `packages/dock/harbor/quo-harbor.md` has both.
+13. The browser harbor: Done. Harbor core carved out of the disk harbor
+    into a core of its own, since the library move `packages/quo/src/harbor/core.ts`,
+    the store a piece with files and IndexedDB under it, the dialer its
+    own terrain-free piece, the socket reach on the standard surface.
+    `packages/dock/harbor/browser.ts` is the core in a tab: IndexedDB, a web lock
+    for the lease, one socket per world.
+    The library's conformance suite passed untouched inside a real
+    Chromium against two browser harbors in one tab through a daemon on
+    loopback, migration between two databases included;
+    `packages/dock/test/terrain/browser.test.ts`, behind `check:terrain`. And the
+    first screen, `packages/dock/human/tab.ts`, rudimentary on purpose: a page on
+    the web route that boots a harbor in the tab, takes the owner password
+    once under the `tab` proof kind, and renders her describe as buttons,
+    with pushes landing on the page; a reload asks nothing. What it taught:
+    a tab's store keeps values through JSON because the cells guard refuses
+    structured clone; a side in a tab saves after the exchange and after
+    every call, as the daemon does; and a dialed socket is the fallback
+    from the moment it is dialed, because a ward asks the instant it boots.
+14. Owners at the door in the CLI: Done. The root socket takes `via`, a
+    standing the user being holds at another ward, and the daemon asks on
+    it in-process and saves; `quo pilot` and the bare owner asks take
+    `--via S`. Scene 8 on two daemons over a dialed socket in
+    `packages/dock/test/cli.test.ts`: the far root invites on its ward's pk, the
+    user being here knocks and takes `lab`, census and boot land there,
+    invite on the far pk is refused at the door, the standing survives a
+    restart, and the owner removed meets silence. What it taught: the
+    library had no owner ask that removes an owner, and the test reached
+    into the ward's cells; the word is `remove` now, decided in `packages/quo/SPEC.md`
+    at step 16.
+15. The human side, minimal: Done. Three pieces under `packages/dock/human/`:
+    `html.ts`, pure, a schema as a form, a form back as typed arguments,
+    an answer as a view, the three words with faces; `screen.ts`, the side
+    over a surface that can only show a page and hand back a form,
+    re-asking her describe after every call so the page follows the
+    digest; `dom.ts`, the surface on an element. The tab keeps its harbor
+    and exchange and hands the avatar to the side. Proven on the memory
+    harbor with a fake surface in `packages/dock/test/human.test.ts`, and in
+    Chromium behind `check:terrain`. Minimal on purpose: design, a
+    switcher, the guest's page and the native app are left to the human
+    document's own sitting, and none of them blocks a world from having
+    a screen.
+16. Removing: Done. `packages/quo/SPEC.md` gave the owner its fourth ask, `remove`,
+    the mirror of knock: a relation out of a being by id, occupant or
+    standing, and on the ward's own pk an owner, by the root alone. In
+    `packages/quo/src/ward/owner.ts` with its test; the pilot's fourth tool; `quo
+    remove` from the shell, the same word; the step 14 test asks it
+    instead of reaching into the cells. The lab's leftovers went with it,
+    recorded in `estates/lab/lab.md`.
+17. What the lab wants: Done. A launchd agent beside the systemd unit in
+    `estates/lab/droplet/`, the daemon as the user forever with
+    `~/.quo/dial.json` naming the routes it holds a socket to, installed
+    on the operator's Mac against the lab. And `quo run`: the runner from
+    a terminal, the same pipe as `quo side` with a model named in the
+    hello, the daemon running the runner beside the avatar, a line in a
+    turn and the final text a line out, proven with a scripted endpoint
+    as a child process in `packages/dock/test/cli.test.ts`. The gate profile per
+    client identity the road lists is defined nowhere and was not built.
+18. The edge terrain: Done. `packages/dock/harbor/edge/`, the core over a Durable
+    Object: its storage the store with the seed sealed under a platform
+    secret, the deployed worker the code, the object the lease; reached by
+    request, holding dialers' sockets, the root a route under a platform
+    secret. The conformance suite passed untouched inside the platform's
+    runtime, behind `check:terrain`; deployed to the lab's account and
+    piloted from the Mac over a standing, `--via edge`. The third terrain
+    the library move waited for; the `ws` question answered in the harbor
+    document. `estates/lab/lab.md` keeps the record, one slip included.
+
+19. The split, in flight: the estate folder became the dock, the lab's own
+    things moved to `estates/lab/`, its units and its document, and
+    the dock's package took its name. Then the repository took the shape
+    that says what ships by where it lives: `packages/quo/` and
+    `packages/dock/` are the two published packages, `estates/` is private,
+    and the root is nobody's package, the workspaces and the gate. The lab
+    redeployed from the new paths and a copy of `estates/lab/` booting in
+    an empty repository are what close it.
+20. The dock published: Done. `@quo-systems/dock` 0.1.0, the same shape
+    the library took, an emitted `dist/` with the `quo` command pointing
+    into it, the source and the four documents beside it, and
+    `packages/dock/test/package.test.ts` as the one suite that meets it as
+    an adopter: the library's tarball and this one installed into an empty
+    folder with nothing but Node, then `quo init`, a daemon, and
+    `quo census` answering with the desk and the user being. The library
+    went to 0.2.0 first, since the door's words moved the wire. What it
+    decided: the daemon bundles the tab from beside itself, emitted or
+    source, whichever is there, the one place the dock reads a file by
+    path at run time.
+
+Steps 1 to 18 and 20 are in the tree and on the lab, and MCP is complete;
+step 19 is in flight, and it is the one gap named today. `next.md` is where
+the next sitting starts.
+
+## Glossary
+
+- **avatar**: a being that is someone's voice from outside Quo.
+- **client identity**: what a credential exchange establishes; one avatar.
+- **envoy**: a being whose methods call a non-Quo thing.
+- **dock**: what every estate needs and nobody writes twice, `packages/dock/`,
+  published as `@quo-systems/dock`.
+- **estate**: all of one owner's harbors, with what is theirs alone, one
+  folder under `estates/`, never published. Also the agent under cron that
+  holds the owner pilot for one.
+- **front desk**: the being every fresh client meets; hands out invitations
+  minted by user beings.
+- **gate**: `for(occupant, asker)`; the whole permission model.
+- **owner pilot**: `quo pilot`, the four owner asks over stdio, reaching
+  the daemon's socket; with `--via`, a ward elsewhere through a standing.
+- **daemon**: `quo serve`, the one process on a device that holds a harbor.
+- **proof**: what a route produces after authenticating; the front desk
+  trades it for an invitation.
+- **route**: a hostname a reverse proxy sends to one process.
+- **side**: the interface an avatar speaks through to someone outside Quo.
+- **user being**: one per human, 24/7, holding all of the human's standings.