@quo-systems/dock 0.1.0 → 0.2.0

package/README.md

@@ -8,10 +8,17 @@ built on the dock, on Quo.
 
 ```bash
 npm install @quo-systems/dock
-npx quo init
-npx quo serve
+npx quo estate my-estate --domain example.com
+npx quo init --dir my-estate/droplet
+npx quo serve --dir my-estate/droplet
 ```
 
+`quo estate` writes an estate folder: one folder per harbor, the first a
+droplet's quo directory with its routes under your domain, its unit and
+its Caddyfile, and a package file that depends on the dock and nothing
+else. Add your beings to `droplet/classes/`, and your placement to the
+routes and agents files.
+
 `beings/quo-dock.md` is the truth of this package and the trunk of its four
 documents; read it first. It knows nothing the spec of Quo does not say,
 and adds no word to harbor, ward or being.

package/beings/quo-dock.md

@@ -288,12 +288,13 @@ 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 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|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 boot|public|invite|knock|remove  the five 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
+quo estate <dir> --domain D  an estate folder of the shape every estate has: a droplet's quo directory, its unit and Caddyfile, a package on this dock
 ```
 
 **One process owns the harbor.** `quo serve` is the only process that ever
@@ -502,13 +503,12 @@ above or sending us back to fix it:
    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.
+   process: the model side of step 3 over the ward's owner asks, the
+   ward's describe as tools and no list of its own, each call an owner ask
+   on the daemon's root socket, and nothing logged. 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
@@ -521,7 +521,10 @@ above or sending us back to fix it:
    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
+   one hour, a refresh token thirty days; 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 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
@@ -651,14 +654,23 @@ above or sending us back to fix it:
     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.
+19. The split: Done. The estate folder became the dock, the lab's own
+    things moved to `estates/lab/`, 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 is an estate folder of the shape this
+    document names, one folder per harbor, and `estates/lab/test/boot.test.ts`
+    is invariant 12 proven: a copy of the folder, the two packages installed
+    into it and nothing else, and the droplet boots. The lab redeployed
+    from it: the droplet from a clean export of HEAD with its unit copied
+    from the estate's folder, the edge from the estate's own config
+    resolving the dock's worker by name, the Mac's agent on the new path.
+    What it taught: a nested npm under `npm run` inherits the outer run's
+    local prefix by environment and installs into the repository instead
+    of the empty folder, so the stranger tests keep nothing of it; and
+    `npx` in a workspace runs at the package root, so an estate names its
+    edge config from its own folder.
 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
@@ -671,9 +683,34 @@ above or sending us back to fix it:
     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.
+21. A second estate: Done, and live. `estates/gherghina/`,
+    staging like the lab and nothing more, one harbor on the shared droplet
+    `nervur-staging-0`, routes under `gherghina.quo.systems`, no agents and
+    no classes of its own yet, the same unit and Caddyfile shape as the
+    lab's. It is the first proof that the dock has two users: its folder
+    depends on the dock alone, and `estates/gherghina/test/boot.test.ts`
+    runs the one proof every estate here runs, `estates/proof.ts`, shared
+    between them and shipped nowhere. The three staging droplets are shared
+    by every estate in this repository, and none of them is production or
+    holds real data. Its droplet stood up the same day, its document says
+    how; what it taught went into both estates' units: the agent's folders
+    are optional to the daemon, since a harbor may have no agent.
+
+22. The scaffold: Done. `quo estate <dir> --domain D` writes an estate
+    folder of the shape the two estates here agreed on: a package file
+    depending on this dock and nothing else, one document to fill in, and
+    `droplet/` as the first harbor, its routes under the domain, no
+    agents, no classes of its own, and that device's unit and Caddyfile
+    from templates the dock ships beside its command. The unit it writes
+    runs the installed dock from the estate's folder on the box, since an
+    adopter has no tree there; the two estates here run the tree. Proven
+    in `packages/dock/test/cli.test.ts`: the folder is written, refuses to
+    overwrite a package or take a name that is no domain, and its droplet
+    boots, `quo init` into it and a daemon answering the census.
+
+Steps 1 to 22 are in the tree and on the machines, and MCP is complete;
+the documents and the folders agree up to step 22. There is no gap named
+today. `next.md` is where the next sitting starts.
 
 ## Glossary
 
@@ -688,7 +725,7 @@ the next sitting starts.
 - **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
+- **owner pilot**: `quo pilot`, the model side over a ward's owner asks, 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

package/beings/setup.ts

@@ -15,7 +15,9 @@ export async function setup(hosted: Hosted, user: string): Promise<void> {
     const out = (await hosted.ask('boot', args)) as { booted?: string; error?: string };
     if (out.error) throw new Error(`init: ${out.error}`);
   };
-  await boot({ key: 'desk', class: 'Desk', public: true });
+  await boot({ key: 'desk', class: 'Desk' });
+  const pub = (await hosted.ask('public', { key: 'desk' })) as { error?: string };
+  if (pub.error) throw new Error(`init: ${pub.error}`);
   await boot({ key: user, class: 'User' });
   const inv = (await hosted.ask('invite', { being: user, id: DESK })) as Invitation;
   const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello' })) as { taken?: string };

package/cli/estate/Caddyfile

@@ -0,0 +1,25 @@
+# Three hostnames, one daemon, one loopback port. Caddy faces the world and
+# terminates TLS; the daemon never does. Each hostname is a route, and a
+# route is a path on the daemon's HTTP door. Replace DOMAIN.
+#
+#   mcp.   the model side: streamable HTTP MCP, with the credential exchange in front
+#   web.   the bundle for plain tabs, and the exchange pages
+#   quo.   the socket door for other harbors: requests in, sockets held, the rendezvous
+#
+# There is no cli. route. The root owner is the unix socket, reached on the
+# device or over SSH, and never through here.
+
+mcp.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /mcp{uri}
+}
+
+web.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /web{uri}
+}
+
+quo.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /quo{uri}
+}

package/cli/estate/quo.service

@@ -0,0 +1,36 @@
+# The daemon on a droplet, as one user, forever. Install with:
+#   sudo cp droplet/quo.service /etc/systemd/system/quo.service
+#   sudo systemctl enable --now quo
+# The unit runs as the `quo` user, whose home holds the estate folder and
+# the harbor folder, so the seed, the lease and the sockets are that user's
+# alone. The HTTP door is loopback only; Caddy fronts it. See Caddyfile
+# beside this file.
+[Unit]
+Description=quo: one harbor on this device
+After=network.target
+
+[Service]
+User=quo
+Group=quo
+Environment=QUO_DIR=/home/quo/.quo
+Environment=QUO_HTTP=8787
+# QUO_OWNER_PASSWORD, root-only. Without it the exchange pages are closed.
+# CLAUDE_CODE_OAUTH_TOKEN, when an agent folder runs `claude -p`: the agent
+# reads its credential from the device, never from cells.
+EnvironmentFile=-/etc/quo/env
+WorkingDirectory=/home/quo/ESTATE
+ExecStart=/usr/bin/node /home/quo/ESTATE/node_modules/@quo-systems/dock/dist/cli/quo.js serve
+Restart=always
+RestartSec=2
+KillSignal=SIGTERM
+TimeoutStopSec=10
+NoNewPrivileges=true
+ProtectSystem=strict
+# Agents run in their folders and Claude Code keeps its own state in the
+# user's home; both must be writable for a run to happen, and a harbor
+# with no agent has neither.
+ReadWritePaths=/home/quo/.quo -/home/quo/agents -/home/quo/.claude -/home/quo/.claude.json /tmp
+PrivateTmp=false
+
+[Install]
+WantedBy=multi-user.target

package/cli/estate.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// `quo estate DIR --domain D`: an estate folder, written once, of the shape
+// every estate has. One folder per harbor, here the first, `droplet/`: the
+// quo directory that device runs minus what it mints, its routes under the
+// domain, no agents, no classes of its own, and that device's unit and
+// Caddyfile. A package file that depends on this dock and nothing else, and
+// one document to fill in. An estate needs nothing the dock does not give
+// it, and this is the dock giving it.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// This package's own version, read beside the emitted or the source tree.
+async function version(): Promise<string> {
+  for (const rel of ['../package.json', '../../package.json']) {
+    const at = fileURLToPath(new URL(rel, import.meta.url));
+    if (!existsSync(at)) continue;
+    const pkg = JSON.parse(await readFile(at, 'utf8')) as { name?: string; version?: string };
+    if (pkg.name === '@quo-systems/dock' && pkg.version) return pkg.version;
+  }
+  return '0.1.0';
+}
+const template = (name: string) => readFile(fileURLToPath(new URL(`estate/${name}`, import.meta.url)), 'utf8');
+
+export async function estate(dir: string, domain: string): Promise<{ dir: string; name: string; files: string[] }> {
+  if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(domain)) throw new Error(`estate: ${domain} is not a domain`);
+  if (existsSync(join(dir, 'package.json'))) throw new Error(`estate: ${dir} already holds a package`);
+  const name = basename(dir);
+  const files: Record<string, string> = {
+    'package.json': JSON.stringify({ name, private: true, description: `The ${name} estate: one owner's harbors, built on the dock and nothing else.`, type: 'module', dependencies: { '@quo-systems/dock': `^${await version()}` } }, null, 2) + '\n',
+    [`${name}.md`]: `# ${name}\n\nAn estate: all of one owner's harbors. One folder per harbor, each the quo\ndirectory that device runs minus what it mints, plus that device's unit.\n\`droplet/\` is the first: its routes under \`${domain}\`, its agents, its\nclasses, its systemd unit and its Caddyfile. This folder depends on the\ndock and nothing else.\n\n## The droplet\n\nWhere it is, how it is reached, and what was done to stand it up: yours\nto write.\n`,
+    'droplet/routes.json': JSON.stringify({ mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}` }) + '\n',
+    'droplet/agents.json': '{}\n',
+    'droplet/classes/index.ts': '// The classes this harbor holds beside the dock\'s built-in ones, exported\n// by name.\nexport {};\n',
+    'droplet/quo.service': (await template('quo.service')).replaceAll('ESTATE', name),
+    'droplet/Caddyfile': (await template('Caddyfile')).replaceAll('DOMAIN', domain),
+  };
+  for (const [rel, text] of Object.entries(files)) {
+    await mkdir(join(dir, rel, '..'), { recursive: true });
+    await writeFile(join(dir, rel), text);
+  }
+  return { dir, name, files: Object.keys(files) };
+}

package/cli/quo.ts

@@ -15,6 +15,7 @@
 //   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
 //   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
 //   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//   quo estate <dir> --domain D              an estate folder of the shape every estate has: a droplet's quo directory, unit and Caddyfile, on this dock
 //
 // D defaults to $QUO_DIR, then ~/.quo. W defaults to main. init takes
 // --user NAME for the user being, defaulting to the device's user. run
@@ -31,8 +32,9 @@ import { DiskHarbor } from '../harbor/disk.ts';
 import { serve } from './daemon.ts';
 import { ask, side, reach, type Run } from './client.ts';
 import { pilotSide } from '../mcp/pilot.ts';
+import { estate } from './estate.ts';
 
-const OWNER_ASKS = new Set(['boot', 'invite', 'knock', 'remove']);
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove']);
 
 function parse(argv: string[]) {
   const flags: Record<string, string> = {};
@@ -80,7 +82,7 @@ async function main(argv: string[]): Promise<number> {
   }
   if (cmd === 'pilot') {
     await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
-    const serving = await pilotSide(dir, ward, new StdioServerTransport(), (line) => console.error(`pilot ${line}`), via);
+    const serving = await pilotSide(dir, ward, new StdioServerTransport(), via);
     process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
     return -1;
   }
@@ -93,6 +95,14 @@ async function main(argv: string[]): Promise<number> {
     process.once('SIGTERM', stop);
     return -1; // stays up
   }
+  if (cmd === 'estate') {
+    if (!json || !flags.domain) {
+      console.error('quo estate needs <dir> --domain D');
+      return 2;
+    }
+    print(await estate(json, flags.domain));
+    return 0;
+  }
   if (cmd === 'reach') {
     if (!json || !more) {
       console.error('quo reach needs <pk> <url>');
@@ -111,7 +121,7 @@ async function main(argv: string[]): Promise<number> {
     const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
     return failed ? 1 : 0;
   }
-  console.error('usage: quo init|serve|census|boot|invite|knock|remove|side|run|pilot|reach [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+  console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
   return 2;
 }
 

package/dist/beings/setup.js

@@ -7,7 +7,10 @@ export async function setup(hosted, user) {
         if (out.error)
             throw new Error(`init: ${out.error}`);
     };
-    await boot({ key: 'desk', class: 'Desk', public: true });
+    await boot({ key: 'desk', class: 'Desk' });
+    const pub = (await hosted.ask('public', { key: 'desk' }));
+    if (pub.error)
+        throw new Error(`init: ${pub.error}`);
     await boot({ key: user, class: 'User' });
     const inv = (await hosted.ask('invite', { being: user, id: DESK }));
     const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello' }));

package/dist/cli/estate/Caddyfile

@@ -0,0 +1,25 @@
+# Three hostnames, one daemon, one loopback port. Caddy faces the world and
+# terminates TLS; the daemon never does. Each hostname is a route, and a
+# route is a path on the daemon's HTTP door. Replace DOMAIN.
+#
+#   mcp.   the model side: streamable HTTP MCP, with the credential exchange in front
+#   web.   the bundle for plain tabs, and the exchange pages
+#   quo.   the socket door for other harbors: requests in, sockets held, the rendezvous
+#
+# There is no cli. route. The root owner is the unix socket, reached on the
+# device or over SSH, and never through here.
+
+mcp.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /mcp{uri}
+}
+
+web.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /web{uri}
+}
+
+quo.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /quo{uri}
+}

package/dist/cli/estate/quo.service

@@ -0,0 +1,36 @@
+# The daemon on a droplet, as one user, forever. Install with:
+#   sudo cp droplet/quo.service /etc/systemd/system/quo.service
+#   sudo systemctl enable --now quo
+# The unit runs as the `quo` user, whose home holds the estate folder and
+# the harbor folder, so the seed, the lease and the sockets are that user's
+# alone. The HTTP door is loopback only; Caddy fronts it. See Caddyfile
+# beside this file.
+[Unit]
+Description=quo: one harbor on this device
+After=network.target
+
+[Service]
+User=quo
+Group=quo
+Environment=QUO_DIR=/home/quo/.quo
+Environment=QUO_HTTP=8787
+# QUO_OWNER_PASSWORD, root-only. Without it the exchange pages are closed.
+# CLAUDE_CODE_OAUTH_TOKEN, when an agent folder runs `claude -p`: the agent
+# reads its credential from the device, never from cells.
+EnvironmentFile=-/etc/quo/env
+WorkingDirectory=/home/quo/ESTATE
+ExecStart=/usr/bin/node /home/quo/ESTATE/node_modules/@quo-systems/dock/dist/cli/quo.js serve
+Restart=always
+RestartSec=2
+KillSignal=SIGTERM
+TimeoutStopSec=10
+NoNewPrivileges=true
+ProtectSystem=strict
+# Agents run in their folders and Claude Code keeps its own state in the
+# user's home; both must be writable for a run to happen, and a harbor
+# with no agent has neither.
+ReadWritePaths=/home/quo/.quo -/home/quo/agents -/home/quo/.claude -/home/quo/.claude.json /tmp
+PrivateTmp=false
+
+[Install]
+WantedBy=multi-user.target

package/dist/cli/estate.d.ts

@@ -0,0 +1,5 @@
+export declare function estate(dir: string, domain: string): Promise<{
+    dir: string;
+    name: string;
+    files: string[];
+}>;

package/dist/cli/estate.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// `quo estate DIR --domain D`: an estate folder, written once, of the shape
+// every estate has. One folder per harbor, here the first, `droplet/`: the
+// quo directory that device runs minus what it mints, its routes under the
+// domain, no agents, no classes of its own, and that device's unit and
+// Caddyfile. A package file that depends on this dock and nothing else, and
+// one document to fill in. An estate needs nothing the dock does not give
+// it, and this is the dock giving it.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// This package's own version, read beside the emitted or the source tree.
+async function version() {
+    for (const rel of ['../package.json', '../../package.json']) {
+        const at = fileURLToPath(new URL(rel, import.meta.url));
+        if (!existsSync(at))
+            continue;
+        const pkg = JSON.parse(await readFile(at, 'utf8'));
+        if (pkg.name === '@quo-systems/dock' && pkg.version)
+            return pkg.version;
+    }
+    return '0.1.0';
+}
+const template = (name) => readFile(fileURLToPath(new URL(`estate/${name}`, import.meta.url)), 'utf8');
+export async function estate(dir, domain) {
+    if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(domain))
+        throw new Error(`estate: ${domain} is not a domain`);
+    if (existsSync(join(dir, 'package.json')))
+        throw new Error(`estate: ${dir} already holds a package`);
+    const name = basename(dir);
+    const files = {
+        'package.json': JSON.stringify({ name, private: true, description: `The ${name} estate: one owner's harbors, built on the dock and nothing else.`, type: 'module', dependencies: { '@quo-systems/dock': `^${await version()}` } }, null, 2) + '\n',
+        [`${name}.md`]: `# ${name}\n\nAn estate: all of one owner's harbors. One folder per harbor, each the quo\ndirectory that device runs minus what it mints, plus that device's unit.\n\`droplet/\` is the first: its routes under \`${domain}\`, its agents, its\nclasses, its systemd unit and its Caddyfile. This folder depends on the\ndock and nothing else.\n\n## The droplet\n\nWhere it is, how it is reached, and what was done to stand it up: yours\nto write.\n`,
+        'droplet/routes.json': JSON.stringify({ mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}` }) + '\n',
+        'droplet/agents.json': '{}\n',
+        'droplet/classes/index.ts': '// The classes this harbor holds beside the dock\'s built-in ones, exported\n// by name.\nexport {};\n',
+        'droplet/quo.service': (await template('quo.service')).replaceAll('ESTATE', name),
+        'droplet/Caddyfile': (await template('Caddyfile')).replaceAll('DOMAIN', domain),
+    };
+    for (const [rel, text] of Object.entries(files)) {
+        await mkdir(join(dir, rel, '..'), { recursive: true });
+        await writeFile(join(dir, rel), text);
+    }
+    return { dir, name, files: Object.keys(files) };
+}

package/dist/cli/quo.js

@@ -15,6 +15,7 @@
 //   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
 //   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
 //   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//   quo estate <dir> --domain D              an estate folder of the shape every estate has: a droplet's quo directory, unit and Caddyfile, on this dock
 //
 // D defaults to $QUO_DIR, then ~/.quo. W defaults to main. init takes
 // --user NAME for the user being, defaulting to the device's user. run
@@ -31,7 +32,8 @@ import { DiskHarbor } from '../harbor/disk.js';
 import { serve } from './daemon.js';
 import { ask, side, reach } from './client.js';
 import { pilotSide } from '../mcp/pilot.js';
-const OWNER_ASKS = new Set(['boot', 'invite', 'knock', 'remove']);
+import { estate } from './estate.js';
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove']);
 function parse(argv) {
     const flags = {};
     const rest = [];
@@ -78,7 +80,7 @@ async function main(argv) {
     }
     if (cmd === 'pilot') {
         await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
-        const serving = await pilotSide(dir, ward, new StdioServerTransport(), (line) => console.error(`pilot ${line}`), via);
+        const serving = await pilotSide(dir, ward, new StdioServerTransport(), via);
         process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
         return -1;
     }
@@ -91,6 +93,14 @@ async function main(argv) {
         process.once('SIGTERM', stop);
         return -1; // stays up
     }
+    if (cmd === 'estate') {
+        if (!json || !flags.domain) {
+            console.error('quo estate needs <dir> --domain D');
+            return 2;
+        }
+        print(await estate(json, flags.domain));
+        return 0;
+    }
     if (cmd === 'reach') {
         if (!json || !more) {
             console.error('quo reach needs <pk> <url>');
@@ -109,7 +119,7 @@ async function main(argv) {
         const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
         return failed ? 1 : 0;
     }
-    console.error('usage: quo init|serve|census|boot|invite|knock|remove|side|run|pilot|reach [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+    console.error('usage: quo init|serve|census|boot|public|invite|knock|remove|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
     return 2;
 }
 main(process.argv.slice(2)).then((code) => {

package/dist/harbor/edge/exercise.js

@@ -63,7 +63,9 @@ function probe(base, state, env) {
                     learn(i, w);
                 }
                 wardOf.set(key, name);
-                assert.deepEqual(await w.ask('boot', { key, class: Class.name, public: isPublic }), { booted: key });
+                assert.deepEqual(await w.ask('boot', { key, class: Class.name }), { booted: key });
+                if (isPublic)
+                    assert.deepEqual(await w.ask('public', { key }), { public: key });
                 if (Object.keys(cells).length)
                     Object.assign(at(name).p.beings[key], cells);
                 return {

package/dist/harbor/edge/platform.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// The edge platform, as much of it as the harbor touches and no more. The
+// vendor's own type package declares every global a worker has, and it
+// collides with the DOM library this tree compiles against; these few
+// lines are what the edge harbor and worker actually call.
+export type Storage = {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list<T = unknown>(options?: { prefix?: string }): Promise<Map<string, T>>;
+};
+export type State = { id: { toString(): string; name?: string }; storage: Storage };
+export type Stub = { fetch(input: string | Request, init?: RequestInit): Promise<Response> };
+export type Namespace = { idFromName(name: string): unknown; get(id: unknown): Stub };
+export type Env = { HARBOR: Namespace; QUO_SEED_KEY?: string; QUO_ROOT?: string; QUO_EXERCISE?: string };
+// The server end of a WebSocketPair: the standard surface plus accept.
+export type ServerSocket = { accept(): void; readyState: number; binaryType: string; send(data: string | Uint8Array): void; close(): void; addEventListener(type: string, fn: (e: never) => void): void };
+declare global {
+  // eslint-disable-next-line no-var
+  var WebSocketPair: new () => { 0: ServerSocket; 1: ServerSocket };
+  interface ResponseInit {
+    webSocket?: unknown;
+  }
+  interface Response {
+    readonly webSocket?: unknown;
+  }
+}

package/dist/mcp/oauth.d.ts

@@ -6,6 +6,7 @@ export type Client = {
     client_id: string;
     client_name: string;
     redirect_uris: string[];
+    exp: number;
 };
 export type Pending = {
     client_id: string;
@@ -62,6 +63,7 @@ export declare class OAuth {
     register(body: unknown): Promise<Client | {
         error: string;
     }>;
+    client(id: string): Client | undefined;
     authorize(q: URLSearchParams): Promise<{
         redirect: string;
     } | {

package/dist/mcp/oauth.js

@@ -60,15 +60,22 @@ export class OAuth {
         const uris = Array.isArray(b.redirect_uris) ? b.redirect_uris.filter((u) => typeof u === 'string' && /^https?:\/\//.test(u)) : [];
         if (uris.length === 0)
             return { error: 'invalid_redirect_uri' };
-        const client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris };
+        const client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris, exp: this.now() + CODE_TTL };
         this.store.clients[client.client_id] = client;
+        this.sweep();
         await this.o.persist(this.store);
-        return client;
+        const { exp: _, ...shown } = client;
+        return shown;
+    }
+    // A client still alive, by id.
+    client(id) {
+        const c = own(this.store.clients, id);
+        return c && c.exp >= this.now() ? c : undefined;
     }
     // Start a request. What comes back is where to send the browser: the web
     // route with the request id, or the client's redirect with an error.
     async authorize(q) {
-        const client = own(this.store.clients, q.get('client_id') ?? '');
+        const client = this.client(q.get('client_id') ?? '');
         const redirect = q.get('redirect_uri') ?? client?.redirect_uris[0] ?? null;
         if (!client || redirect === null || !client.redirect_uris.includes(redirect))
             return { error: 'invalid_client' };
@@ -89,7 +96,7 @@ export class OAuth {
         const p = own(this.store.pending, id);
         if (!p || p.exp < this.now())
             return null;
-        const client = own(this.store.clients, p.client_id);
+        const client = this.client(p.client_id);
         return client ? { ...p, client } : null;
     }
     // The web route's last step: the human allowed this client as this identity.
@@ -140,6 +147,9 @@ export class OAuth {
         const access_token = token(), refresh_token = token();
         this.store.access[access_token] = { identity, client_id, exp: this.now() + ACCESS_TTL };
         this.store.refresh[refresh_token] = { identity, client_id, exp: this.now() + REFRESH_TTL };
+        const c = own(this.store.clients, client_id);
+        if (c)
+            c.exp = this.now() + REFRESH_TTL; // allowed: the client lives as long as what it was granted
         this.sweep();
         await this.o.persist(this.store);
         return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'quo' };
@@ -162,10 +172,10 @@ export class OAuth {
     }
     sweep() {
         const now = this.now();
-        for (const k of ['pending', 'codes', 'access', 'refresh'])
+        for (const k of ['clients', 'pending', 'codes', 'access', 'refresh'])
             for (const [t, g] of Object.entries(this.store[k]))
-                if (g.exp < now)
-                    delete this.store[k][t];
+                if (!(g.exp >= now))
+                    delete this.store[k][t]; // a record with no exp is from before there was one, and goes too
     }
     // The HTTP face. `rest` is the path under the route.
     async handle(req, res, rest) {

package/dist/mcp/pilot.d.ts

@@ -1,6 +1,5 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import { type Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Serving } from '../beings/side.ts';
-export declare const PILOT_TOOLS: Tool[];
-export type Log = (line: string) => void;
-export declare function pilotSide(dir: string, ward: string, transport: Transport, log?: Log, via?: string): Promise<Serving>;
+import { type Subject } from './server.ts';
+export declare function owner(dir: string, ward: string, via?: string): Subject;
+export declare function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving>;

package/dist/mcp/pilot.js

@@ -1,68 +1,22 @@
-// SPDX-License-Identifier: Apache-2.0
-// The owner pilot: `quo pilot`. An MCP server over stdio that reaches a
-// ward's owner asks through the daemon's root socket, and exposes four tools
-// and no more, plus the one read. Whoever runs this process is the owner, by
-// the device's own rules: the root of the ward here, or, with `via`, an
-// owner at another ward's door, on a standing the user being here holds
-// there. Every call is logged with what it made. The owner creates and
-// places; the work goes through `quo side`, under a gate.
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { ask } from '../cli/client.js';
-export const PILOT_TOOLS = [
-    {
-        name: 'census',
-        description: 'the empty ask: the ward pk and every being, with class, public and digest',
-        inputSchema: { type: 'object', properties: {} },
-    },
-    {
-        name: 'boot',
-        description: 'boot a being by class name under a key; public marks the one public being',
-        inputSchema: { type: 'object', properties: { key: { type: 'string' }, class: { type: 'string' }, public: { type: 'boolean' } }, required: ['key', 'class'] },
-    },
-    {
-        name: 'invite',
-        description: 'mint an invitation on a being of the ward, under an id she will know the occupant by',
-        inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-    },
-    {
-        name: 'knock',
-        description: 'knock for a being of the ward with an invitation, and take the standing under id if answered',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                being: { description: 'a key already booted, or { boot: class, key } to boot her first' },
-                id: { type: 'string' },
-                invitation: { type: 'object' },
-                method: { type: 'string' },
-                args: { type: 'object' },
-                wanted: { type: 'object', properties: { time: { type: 'number' } } },
-            },
-            required: ['being', 'id', 'invitation'],
-        },
-    },
-    {
-        name: 'remove',
-        description: 'take a relation out of a being of the ward by id, occupant or standing; on the ward pk, an owner, by the root alone',
-        inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-    },
-];
+import { mcpSide } from './server.js';
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-export async function pilotSide(dir, ward, transport, log = () => { }, via) {
-    const server = new Server({ name: 'quo-pilot', version: '0.0.0' }, { capabilities: { tools: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: PILOT_TOOLS }));
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const name = req.params.name;
-        const args = req.params.arguments ?? {};
-        if (!PILOT_TOOLS.some((t) => t.name === name))
-            return { content: [{ type: 'text', text: JSON.stringify({ error: 'unknown ask' }) }], structuredContent: { error: 'unknown ask' }, isError: true };
-        const out = await ask(dir, name === 'census' ? undefined : name, args, ward, via);
-        const value = 'error' in out ? { error: out.error } : out.result;
-        const failed = 'error' in out || (typeof value === 'object' && value !== null && 'error' in value);
-        log(`${via === undefined ? ward : `${ward} via ${via}`} ${name} ${JSON.stringify(args)} -> ${JSON.stringify(value)}`);
-        const structured = isRecord(value) ? { structuredContent: value } : {};
-        return { content: [{ type: 'text', text: JSON.stringify(value) }], ...structured, ...(failed ? { isError: true } : {}) };
-    });
-    await server.connect(transport);
-    return { close: () => server.close() };
+// The owner hears objects: the socket's own failure, a silence and a word
+// each come back as an error object named for what it was.
+export function owner(dir, ward, via) {
+    const one = async (method, args) => {
+        const out = await ask(dir, method, args, ward, via);
+        if ('error' in out)
+            return { error: out.error };
+        const r = out.result;
+        if (isRecord(r) && r.silence === true)
+            return { error: 'silence' };
+        if (isRecord(r) && typeof r.word === 'string')
+            return { error: r.word };
+        return r;
+    };
+    return { tools: () => one(undefined, {}), call: (name, args) => one(name, args), ears: new Set() };
+}
+export function pilotSide(dir, ward, transport, via) {
+    return mcpSide(owner(dir, ward, via), transport);
 }

package/dist/mcp/server.d.ts

@@ -1,9 +1,16 @@
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { type Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Blueprint } from '@quo-systems/quo';
-import type { Avatar } from '../beings/avatar.ts';
+import type { Answer, Blueprint, JsonObject } from '@quo-systems/quo';
 import { type Serving } from '../beings/side.ts';
 export declare const NAME = "quo";
 export declare const VERSION = "0.0.0";
+export type Subject = {
+    tools(): Promise<Blueprint | {
+        error: string;
+    }>;
+    call(name: string, args: JsonObject): Promise<Answer>;
+    ears: Set<(object: JsonObject) => void>;
+};
+export declare const DESCRIBE: Tool;
 export declare function tools(bp: Blueprint): Tool[];
-export declare function mcpSide(avatar: Avatar, transport: Transport, after?: () => Promise<void>): Promise<Serving>;
+export declare function mcpSide(avatar: Subject, transport: Transport, after?: () => Promise<void>): Promise<Serving>;

package/dist/mcp/server.js

@@ -1,19 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
-// The model side as an MCP server: one avatar, one transport. The mapping is
-// total and needs nothing beyond this envelope. tools/list is her describe,
-// tools/call is a named ask on her one standing, a push is a logging
-// notification, and the three words for "no object" each cross as the table
-// in quo-mcp.md says. The transport is whatever the caller connected: the
+// The model side as an MCP server: one subject, one transport. The subject
+// is whoever answers the empty ask and a named one: an avatar on her one
+// standing, or a ward's owner asks through the pilot. The mapping is total
+// and needs nothing beyond this envelope. tools/list is her describe, and
+// the empty ask itself is the first tool, so the notes of the describe are
+// readable; tools/call is a named ask, a push is a logging notification,
+// and the three words for "no object" each cross as the table in
+// quo-mcp.md says. The transport is whatever the caller connected: the
 // SDK's in-memory pair in a test, stdio for a local client, HTTP on a route.
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
-// Her describe, spoken as tools. Name, description and input are verbatim;
-// an output schema crosses when she declared one.
+// The empty ask as a tool: her describe whole, asks and notes.
+export const DESCRIBE = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
+// Her describe, spoken as tools, the empty ask first. Name, description and
+// input are verbatim; an output schema crosses when she declared one.
 export function tools(bp) {
-    return bp.asks.map((a) => {
+    const asks = bp.asks.map((a) => {
         const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
         if (a.description !== undefined)
             t.description = a.description;
@@ -21,6 +26,7 @@ export function tools(bp) {
             t.outputSchema = { ...a.output, type: 'object' };
         return t;
     });
+    return [DESCRIBE, ...asks];
 }
 // `after` runs when a call is done: a harbor that must write what the ward
 // changed hooks it, since a same-ward ask never crosses the harbor.
@@ -33,7 +39,7 @@ export async function mcpSide(avatar, transport, after = async () => { }) {
         return { tools: tools(bp) };
     });
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const w = word(await avatar.call(req.params.name, (req.params.arguments ?? {})));
+        const w = word(req.params.name === DESCRIBE.name ? await avatar.tools() : await avatar.call(req.params.name, (req.params.arguments ?? {})));
         await after();
         if (w.word === 'object') {
             const structured = w.value !== null && typeof w.value === 'object' && !Array.isArray(w.value) ? { structuredContent: w.value } : {};

package/harbor/edge/exercise.ts

@@ -70,7 +70,8 @@ function probe(base: string, state: State, env: Env): () => Promise<World> {
           learn(i, w);
         }
         wardOf.set(key, name);
-        assert.deepEqual(await w.ask('boot', { key, class: Class.name, public: isPublic }), { booted: key });
+        assert.deepEqual(await w.ask('boot', { key, class: Class.name }), { booted: key });
+        if (isPublic) assert.deepEqual(await w.ask('public', { key }), { public: key });
         if (Object.keys(cells).length) Object.assign(at(name).p.beings[key]!, cells);
         return {
           pk: w.pk,

package/mcp/oauth.ts

@@ -28,7 +28,10 @@ export const CODE_TTL = 10 * 60 * 1000; // a code, and a pending request, live t
 export const ACCESS_TTL = 60 * 60 * 1000; // an access token, one hour
 export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000; // a refresh token, thirty days
 
-export type Client = { client_id: string; client_name: string; redirect_uris: string[] };
+// A client lives ten minutes from registration, the life of a request, and
+// as long as its refresh token once the human allowed it: the register door
+// is open to anyone, and what nobody allowed must not stay on disk.
+export type Client = { client_id: string; client_name: string; redirect_uris: string[]; exp: number };
 export type Pending = { client_id: string; redirect_uri: string; challenge: string; state: string | null; resource: string | null; exp: number };
 export type Grant = { identity: string; client_id: string; exp: number };
 export type Store = {
@@ -87,16 +90,24 @@ export class OAuth {
     const b = body as { client_name?: unknown; redirect_uris?: unknown };
     const uris = Array.isArray(b.redirect_uris) ? b.redirect_uris.filter((u): u is string => typeof u === 'string' && /^https?:\/\//.test(u)) : [];
     if (uris.length === 0) return { error: 'invalid_redirect_uri' };
-    const client: Client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris };
+    const client: Client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris, exp: this.now() + CODE_TTL };
     this.store.clients[client.client_id] = client;
+    this.sweep();
     await this.o.persist(this.store);
-    return client;
+    const { exp: _, ...shown } = client;
+    return shown as Client;
+  }
+
+  // A client still alive, by id.
+  client(id: string): Client | undefined {
+    const c = own(this.store.clients, id);
+    return c && c.exp >= this.now() ? c : undefined;
   }
 
   // Start a request. What comes back is where to send the browser: the web
   // route with the request id, or the client's redirect with an error.
   async authorize(q: URLSearchParams): Promise<{ redirect: string } | { error: string }> {
-    const client = own(this.store.clients, q.get('client_id') ?? '');
+    const client = this.client(q.get('client_id') ?? '');
     const redirect = q.get('redirect_uri') ?? client?.redirect_uris[0] ?? null;
     if (!client || redirect === null || !client.redirect_uris.includes(redirect)) return { error: 'invalid_client' };
     const back = (error: string) => ({ redirect: withQuery(redirect, { error, state: q.get('state') }) });
@@ -114,7 +125,7 @@ export class OAuth {
   pending(id: string): (Pending & { client: Client }) | null {
     const p = own(this.store.pending, id);
     if (!p || p.exp < this.now()) return null;
-    const client = own(this.store.clients, p.client_id);
+    const client = this.client(p.client_id);
     return client ? { ...p, client } : null;
   }
 
@@ -166,6 +177,8 @@ export class OAuth {
       refresh_token = token();
     this.store.access[access_token] = { identity, client_id, exp: this.now() + ACCESS_TTL };
     this.store.refresh[refresh_token] = { identity, client_id, exp: this.now() + REFRESH_TTL };
+    const c = own(this.store.clients, client_id);
+    if (c) c.exp = this.now() + REFRESH_TTL; // allowed: the client lives as long as what it was granted
     this.sweep();
     await this.o.persist(this.store);
     return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'quo' };
@@ -188,7 +201,7 @@ export class OAuth {
 
   sweep() {
     const now = this.now();
-    for (const k of ['pending', 'codes', 'access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (g.exp < now) delete this.store[k][t];
+    for (const k of ['clients', 'pending', 'codes', 'access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (!(g.exp >= now)) delete this.store[k][t]; // a record with no exp is from before there was one, and goes too
   }
 
   // The HTTP face. `rest` is the path under the route.

package/mcp/pilot.ts

@@ -1,73 +1,34 @@
 // SPDX-License-Identifier: Apache-2.0
-// The owner pilot: `quo pilot`. An MCP server over stdio that reaches a
-// ward's owner asks through the daemon's root socket, and exposes four tools
-// and no more, plus the one read. Whoever runs this process is the owner, by
-// the device's own rules: the root of the ward here, or, with `via`, an
-// owner at another ward's door, on a standing the user being here holds
-// there. Every call is logged with what it made. The owner creates and
-// places; the work goes through `quo side`, under a gate.
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+// The owner pilot: `quo pilot`. The model side pointed at a ward instead of
+// an avatar. The ward is a being to her owner, so her describe is the tool
+// list and a tool call is an owner ask, exactly as for anyone; nothing here
+// names an ask. Whoever runs this process is the owner, by the device's own
+// rules: the root of the ward here, through the daemon's socket, or, with
+// `via`, an owner at another ward's door, on a standing the user being here
+// holds there. The owner creates and places; the work goes through
+// `quo side`, under a gate.
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
-import { ListToolsRequestSchema, CallToolRequestSchema, type CallToolResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Answer, Blueprint, JsonObject } from '@quo-systems/quo';
 import { ask } from '../cli/client.ts';
 import type { Serving } from '../beings/side.ts';
+import { mcpSide, type Subject } from './server.ts';
 
-export const PILOT_TOOLS: Tool[] = [
-  {
-    name: 'census',
-    description: 'the empty ask: the ward pk and every being, with class, public and digest',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'boot',
-    description: 'boot a being by class name under a key; public marks the one public being',
-    inputSchema: { type: 'object', properties: { key: { type: 'string' }, class: { type: 'string' }, public: { type: 'boolean' } }, required: ['key', 'class'] },
-  },
-  {
-    name: 'invite',
-    description: 'mint an invitation on a being of the ward, under an id she will know the occupant by',
-    inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-  },
-  {
-    name: 'knock',
-    description: 'knock for a being of the ward with an invitation, and take the standing under id if answered',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        being: { description: 'a key already booted, or { boot: class, key } to boot her first' },
-        id: { type: 'string' },
-        invitation: { type: 'object' },
-        method: { type: 'string' },
-        args: { type: 'object' },
-        wanted: { type: 'object', properties: { time: { type: 'number' } } },
-      },
-      required: ['being', 'id', 'invitation'],
-    },
-  },
-  {
-    name: 'remove',
-    description: 'take a relation out of a being of the ward by id, occupant or standing; on the ward pk, an owner, by the root alone',
-    inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-  },
-];
-
-export type Log = (line: string) => void;
 const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 
-export async function pilotSide(dir: string, ward: string, transport: Transport, log: Log = () => {}, via?: string): Promise<Serving> {
-  const server = new Server({ name: 'quo-pilot', version: '0.0.0' }, { capabilities: { tools: {} } });
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: PILOT_TOOLS }));
-  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
-    const name = req.params.name;
-    const args: Record<string, unknown> = req.params.arguments ?? {};
-    if (!PILOT_TOOLS.some((t) => t.name === name)) return { content: [{ type: 'text', text: JSON.stringify({ error: 'unknown ask' }) }], structuredContent: { error: 'unknown ask' }, isError: true };
-    const out = await ask(dir, name === 'census' ? undefined : name, args, ward, via);
-    const value = 'error' in out ? { error: out.error } : out.result;
-    const failed = 'error' in out || (typeof value === 'object' && value !== null && 'error' in value);
-    log(`${via === undefined ? ward : `${ward} via ${via}`} ${name} ${JSON.stringify(args)} -> ${JSON.stringify(value)}`);
-    const structured = isRecord(value) ? { structuredContent: value } : {};
-    return { content: [{ type: 'text', text: JSON.stringify(value) }], ...structured, ...(failed ? { isError: true } : {}) };
-  });
-  await server.connect(transport);
-  return { close: () => server.close() };
+// The owner hears objects: the socket's own failure, a silence and a word
+// each come back as an error object named for what it was.
+export function owner(dir: string, ward: string, via?: string): Subject {
+  const one = async (method: string | undefined, args: JsonObject): Promise<Answer> => {
+    const out = await ask(dir, method, args, ward, via);
+    if ('error' in out) return { error: out.error };
+    const r = out.result;
+    if (isRecord(r) && r.silence === true) return { error: 'silence' };
+    if (isRecord(r) && typeof r.word === 'string') return { error: r.word };
+    return r as Answer;
+  };
+  return { tools: () => one(undefined, {}) as Promise<Blueprint | { error: string }>, call: (name, args) => one(name, args), ears: new Set() };
+}
+
+export function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving> {
+  return mcpSide(owner(dir, ward, via), transport);
 }

package/mcp/quo-mcp.md

@@ -23,6 +23,8 @@ and needs no translation code beyond an envelope:
 | server                   | an avatar's side                                             |
 | session                  | a standing the avatar holds, persistent across sessions      |
 | tools/list               | the empty ask on that standing: describe for this asker      |
+| the `describe` tool      | the empty ask itself, first in the list, so the notes of the |
+|                          | describe are readable and not only its asks                  |
 | tool name, inputSchema   | `asks[].name`, `asks[].input`, verbatim                      |
 | tools/call               | a named ask with args                                        |
 | result content           | the answer object, as JSON                                   |
@@ -198,23 +200,20 @@ the device and crosses only the local socket.
 
 ### A model as the owner
 
-An **owner pilot** is an MCP server over stdio that reaches a ward's owner
-asks, either as the root through the daemon's socket on the device, or as an
-owner the root invited, through a standing over the sealed door, and exposes
-four tools and no more:
-
-```
-boot({ key, class, public? })
-invite({ being, id })
-knock({ being | { boot, key }, id, invitation, method?, args? })
-remove({ being, id })
-```
-
-Plus one read, `census()`, which is the empty ask. Every call is logged
-with what it made. The pilot is handed to one local agent by the device's
-own rules. A remote pilot is a standing at the ward, and still not a route:
-a model without a ward of its own cannot be an owner anywhere. `quo pilot
---via S` is that pilot: S is a standing the user being here holds at the
+An **owner pilot** is the model side above, pointed at a ward instead of an
+avatar. The ward is a being to her owner, and `packages/quo/SPEC.md` says her
+describe carries her asks with a description and an input each, so the
+pilot holds no list of its own: tools/list is the ward's describe, the
+`describe` tool is the census, and a tool call is an owner ask, boot,
+public, invite, knock or remove, in the ward's own words. It reaches those
+asks either as the root through the daemon's socket on the device, or as an
+owner the root invited, through a standing over the sealed door. It keeps
+nothing and logs nothing: what a model did with it is in the host's own
+transcript, and an invitation it was handed is in no file of the dock's.
+The pilot is handed to one local agent by the device's own rules. A remote
+pilot is a standing at the ward, and still not a route: a model without a
+ward of its own cannot be an owner anywhere. `quo pilot --via S` is that
+pilot: S is a standing the user being here holds at the
 far ward, taken when the root here knocked for her with an invitation the
 far root minted on its ward's pk, and every tool call is a sealed ask
 there, answered as the far ward answers an owner at its door.
@@ -259,4 +258,4 @@ On top of the shared ones in the trunk:
   under; governance, never permission.
 - **runner**: an inline MCP client for a model that speaks function calling;
   it drives the loop the MCP client would, over one conversation.
-- **owner pilot**: an MCP server over stdio exposing the four owner asks.
+- **owner pilot**: the model side over a ward's owner asks, over stdio.

package/mcp/server.ts

@@ -1,34 +1,48 @@
 // SPDX-License-Identifier: Apache-2.0
-// The model side as an MCP server: one avatar, one transport. The mapping is
-// total and needs nothing beyond this envelope. tools/list is her describe,
-// tools/call is a named ask on her one standing, a push is a logging
-// notification, and the three words for "no object" each cross as the table
-// in quo-mcp.md says. The transport is whatever the caller connected: the
+// The model side as an MCP server: one subject, one transport. The subject
+// is whoever answers the empty ask and a named one: an avatar on her one
+// standing, or a ward's owner asks through the pilot. The mapping is total
+// and needs nothing beyond this envelope. tools/list is her describe, and
+// the empty ask itself is the first tool, so the notes of the describe are
+// readable; tools/call is a named ask, a push is a logging notification,
+// and the three words for "no object" each cross as the table in
+// quo-mcp.md says. The transport is whatever the caller connected: the
 // SDK's in-memory pair in a test, stdio for a local client, HTTP on a route.
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, type CallToolResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Blueprint, JsonObject } from '@quo-systems/quo';
-import type { Avatar } from '../beings/avatar.ts';
+import type { Answer, Blueprint, JsonObject } from '@quo-systems/quo';
 import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving } from '../beings/side.ts';
 
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
 
-// Her describe, spoken as tools. Name, description and input are verbatim;
-// an output schema crosses when she declared one.
+// What a side speaks for: the empty ask and a named one, and the ears a
+// push reaches. An avatar is one; the owner's asks on a ward are another.
+export type Subject = {
+  tools(): Promise<Blueprint | { error: string }>;
+  call(name: string, args: JsonObject): Promise<Answer>;
+  ears: Set<(object: JsonObject) => void>;
+};
+
+// The empty ask as a tool: her describe whole, asks and notes.
+export const DESCRIBE: Tool = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
+
+// Her describe, spoken as tools, the empty ask first. Name, description and
+// input are verbatim; an output schema crosses when she declared one.
 export function tools(bp: Blueprint): Tool[] {
-  return bp.asks.map((a) => {
+  const asks = bp.asks.map((a) => {
     const t: Tool = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
     if (a.description !== undefined) t.description = a.description;
     if (a.output !== undefined) t.outputSchema = { ...a.output, type: 'object' };
     return t;
   });
+  return [DESCRIBE, ...asks];
 }
 
 // `after` runs when a call is done: a harbor that must write what the ward
 // changed hooks it, since a same-ward ask never crosses the harbor.
-export async function mcpSide(avatar: Avatar, transport: Transport, after: () => Promise<void> = async () => {}): Promise<Serving> {
+export async function mcpSide(avatar: Subject, transport: Transport, after: () => Promise<void> = async () => {}): Promise<Serving> {
   const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
 
   server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -38,7 +52,7 @@ export async function mcpSide(avatar: Avatar, transport: Transport, after: () =>
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
-    const w = word(await avatar.call(req.params.name, (req.params.arguments ?? {}) as JsonObject));
+    const w = word(req.params.name === DESCRIBE.name ? await avatar.tools() : await avatar.call(req.params.name, (req.params.arguments ?? {}) as JsonObject));
     await after();
     if (w.word === 'object') {
       const structured = w.value !== null && typeof w.value === 'object' && !Array.isArray(w.value) ? { structuredContent: w.value } : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/dock",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The dock: what every estate on Quo needs and nobody writes twice. A daemon and the quo command, the front desk, the user being and the avatar, harbors on disk, in a tab and on the edge, the model sides and the screen.",
   "keywords": [
     "quo",
@@ -54,10 +54,14 @@
     "./human/html": {
       "types": "./dist/human/html.d.ts",
       "default": "./dist/human/html.js"
+    },
+    "./harbor/edge/worker": {
+      "types": "./dist/harbor/edge/worker.d.ts",
+      "default": "./dist/harbor/edge/worker.js"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp harbor/edge/platform.d.ts dist/harbor/edge/ && cp -R cli/estate dist/cli/",
     "test": "node --test \"test/*.test.ts\"",
     "check:terrain": "node --test \"test/terrain/*.test.ts\"",
     "prepublishOnly": "cd ../.. && npm run check && npm run check:terrain"