nervur 0.22.2-5 → 0.22.2-7

package/AUTHORING.md

@@ -1,17 +1,17 @@
 # Writing for nervur
 
 This guide teaches the two things you write with `nervur`. A **being**
-holds logic and state. A **faculty** reaches the world outside. A
-**ground** runs them on a machine, and the library ships it. The
-examples build one small shop, and every file here is a file the
-package's own tests run.
+holds logic and state. A **faculty** reaches the world outside, and
+[Writing a faculty](FACULTIES.md) teaches it whole. A **ground** runs them on
+a machine, and the library ships it. The examples build one small shop,
+and every file here is a file the package's own tests run.
 
 The shop has three classes and one faculty.
 
 - `Order` is one order, from its first item to its shipping.
 - `Shop` is the steward, the being that runs the house.
 - `Lobby` is the public being, which strangers may ask.
-- `Payments` is a faculty that charges money, which the ground's
+- `Payments` is a faculty that charges money, which a maker in
   `recipe.ts` makes.
 
 ## Words
@@ -31,7 +31,8 @@ The shop has three classes and one faculty.
 | role | a named test over the asker and her cells |
 | state | a name read from her cells that decides which asks exist |
 | house | what holds beings, keeps their cells, and seals every ask |
-| ground | the process houses run in, holding their seeds, faculties and hands |
+| ground | the process houses run in, holding one key and sealing their seeds, faculties and secrets under it |
+| registry | code that makes faculties and bodies by name, for the ground to stand |
 
 ## A being
 
@@ -169,7 +170,7 @@ JavaScript writes nothing.
 | `args` | the schema of what it takes; omitted, the empty object alone |
 | `result` | the schema of what it answers; omitted, nothing |
 | `hints` | `readOnly`, `idempotent`, `destructive` |
-| `examples` | cells, a role, args, fakes, and what it gives |
+| `examples` | a history of her asks, a role, args, fakes, and what it gives |
 | `description` | one line for readers and agents |
 | `wait` | milliseconds she may run; omitted, thirty seconds |
 
@@ -202,6 +203,9 @@ nothing lands.
 | `this.house.cancelAlarm({ key })` | an alarm removed |
 | `this.<need>.<method>({…}, { reply? })` | an awaited call, or an effect |
 | `this.held(id, Need).<ask>({…}, { reply?, after? })` | the same, on a standing, and a watch where `after` is given |
+| `this.held(id).describe()`, `.ask(method, {…}, options)` | a standing with no need: what it shows her, then any ask it showed |
+| `this.stranger({ ward, at }, Need).<ask>({…})` | a far house's public being, asked as a stranger, every ask awaited |
+| `this.stranger({ ward, at }).describe()`, `.ask(method, {…})` | the same with no need: what she shows a stranger, then any ask it showed |
 | `this.standings` | `list()`, `note(id, notes)` and `drop(id)` |
 | `this.handle(ask, { bind?, notes?, once?, expires? })` | a handle to one of her asks |
 | `this.invite(id, { notes?, expires? })` | a new occupant, as a handle |
@@ -261,6 +265,12 @@ hold: `{ result: [...] }`. From a being, pass the result she holds:
 `readOnly` ask is watched, and a watch on anything else is refused where
 she makes it.
 
+A watch may land as a reply instead: `{ after: seen, reply: 'heard' }`.
+It leaves once her ask lands, as an effect does, and its answer asks her
+`heard`, where she writes what she heard and watches again. So a device
+that only dials, a phone or a Pi behind a router, hears its station the
+moment something changes there, and opens no port.
+
 A watch moves only on what its asker could read, since it runs as that
 asker. One asker holds one watch on one ask with the same args, and a
 second answers the first at once. A watch across a door holds its
@@ -277,7 +287,11 @@ An **occupant** is someone who may ask her. She mints one with
 A **standing** is someone she may ask. She receives one where an ask's
 args carry an invitation under `s.handle`, or where her steward
 introduces one. She asks through it with `this.held(id, Need)`, which
-checks the standing's describe covers the need.
+checks the standing's describe covers the need. A standing from an
+invitation is named `standing:` and sixteen hex digits, and the id is
+what her ask receives. One her steward introduced is named by the being
+it reaches. She asks a far standing from the ask after the one that took
+it.
 
 Every relation carries two sets of notes. `notes` are hers alone.
 `steward` are her steward's, written when the steward made the relation,
@@ -365,13 +379,14 @@ export class Shop extends Being.of({
 | `bear({ kind, id, args })` | places a new being; the same id twice answers the first |
 | `remove({ id })` | removes a being and everything of hers |
 | `list()` | every being, her kind, whether she is absent, and her dead letters |
-| `ask({ id, method, args }, { reply? })` | asks any being as her occupant `steward` |
+| `ask({ id, method, args }, { reply? })` | asks any being as her occupant `steward`; with no method, reads what she shows the steward |
 | `introduce({ from, to, notes })` | gives `from` a standing on `to`, and `to` an occupant |
 | `invite({ id, occupant, notes, expires? })` | gives a being a new occupant, and the steward its handle |
 
 `bear`, `remove`, `introduce` and `invite` land in the steward's own
 write. If her ask fails, none of them happened. A being borne runs her
-`born` ask first, where her class declares one.
+`born` ask first, where her class declares one, asked as the occupant
+`steward`, so its entry says `for: 'steward'`.
 
 Every other being is placed as `normal`. She holds the standing
 `steward` and the occupant `steward`, and can drop neither.
@@ -469,10 +484,19 @@ hold.
 Every need is covered, or she is absent. An absent being answers silence
 and keeps her cells, and answers again once an offer covers her needs.
 
+A standing is matched to a need by rules two to four alone. A describe
+names no blueprint, so the need's name is hers to choose there.
+
+A need she forgot to declare is a member she does not hold, and the call
+throws inside her ask, which answers only `the ask failed`. So check your
+classes with `npx tsc --noEmit` beside your tests, which run with
+`node --test`.
+
 ### Testing on the bench
 
-The bench opens two houses in one process, on fake memory, keys, clock
-and carry. So every ask crosses a door as it would in production.
+The bench opens two houses on one ground in memory, on fake memory,
+keys and clock. A being of the bench's own house asks hers through a
+door, so every ask crosses as it would in production.
 
 ```ts
 // order.test.ts
@@ -495,38 +519,49 @@ test('An order is paid once the provider calls the handle it was given', async (
   assert.deepEqual(await order.ask('add', { sku: 'tea', price: 4 }), { result: { total: 4 } });
   assert.deepEqual(await order.ask('checkout'), { result: null });
   await bench.settle();
-  assert.equal((await order.cells())!.state, 'paying', 'the charge left once checkout landed, and answered pending');
+  assert.equal((await order.describe())?.state, 'paying', 'the charge left once checkout landed, and answered pending');
 
   assert.deepEqual(await payments.settle('first'), { result: null });
   await bench.settle();
-  assert.equal((await order.cells())!.state, 'paid');
+  assert.equal((await order.describe())?.state, 'paid');
   assert.deepEqual(await order.ask('add', { sku: 'jam', price: 1 }), { error: { message: 'not in this state' } });
 });
 ```
 
-`place(Class, { id, cells })` bears a being and starts her from those
-cells. A placed being is asked with `ask(method, args, { role })`,
-described with `describe({ role })`, and read with `cells()`. `settle()`
-lets every effect and reply run, and `advance(ms)` moves the fake clock.
-
-The bench plays a role with an occupant named for it, whose own notes and
-steward notes both hold the role as `true`.
+`place(Class, { id, born })` has the bench's steward bear a being. A
+placed being is asked with `ask(method, args, { role })` and described
+with `describe({ role })`. Test her through her asks first, as every
+asker meets her. `cells()` reads her cells through the hand, as her owner
+inspects them. An effect answers with the reply it brings once it lands.
+`settle()` lets every effect and reply run, and `advance(ms)` moves the
+fake clock.
+
+The bench plays a role as an owner could, judged on her cells as they
+stand. `root`, and a role root holds, is the hand. `steward` is the
+bench's steward, and `being` a being it introduces to her. Any other
+role is an occupant the bench's steward invites, with the role `true` in
+its steward notes. A role read from her own notes is hers to grant, and
+a handle only her own ask mints.
 
 A steward and a public being are placed where the house places them.
 `Bench.open({ steward: Shop, public: Lobby, classes: [Order] })` opens the
 author's house with them there, and `place(Shop)` and `place(Lobby)` find
-them. A role `root` holds is played through the hand, on any being. On
-the public being, a role a stranger holds is played by a box with no
-relation, signed with a key drawn from the bench's seed.
+them. On the public being, a role a stranger holds is played by a being
+of the bench's own house, asking as a stranger. Beside a steward the test
+brings, the bench plays `root` and `stranger` alone, and places no other
+being. A world of your steward and the beings she bears is tested on a
+BenchGround, as [Faces](FACES.md) tests its desk.
 `Bench.check(Shop, { position: 'steward' })` and `Bench.check(Lobby, {
-position: 'public', steward: Shop })` check them.
+position: 'public' })` check them.
 
-An entry's `examples` are tests the bench runs. Each is one ask on a
-fresh bench: `cells` start her, `role` asks, `args` are the ask's,
-`fakes` answer her needs, and `gives` is the answer owed. `Bench.check`
-runs every example twice from one seed and flags a class that answers
-differently. It then describes every state to every role, and names every
-finding that failed.
+An entry's `examples` are tests the bench runs. Each is a history, then
+one ask, on a fresh bench. `given` lists the asks of hers that bring her
+from her `born` to where the example starts. `role` asks, `args` are the
+ask's, `fakes` answer her needs, and `gives` is the answer owed.
+`Bench.check` runs every example twice from one seed and flags a class
+that answers differently, or leaves her cells differently. It then
+describes every state to every role it plays, and names every finding
+that failed.
 
 ## A faculty
 
@@ -553,7 +588,8 @@ type Answer = { result: { pending: boolean } } | { error: { message: string } };
 /**
  * A payment provider in the ground's process. It answers a call id it has
  * seen with the answer it gave, so an effect sent twice charges once. A
- * provider that changes the world keeps these where a restart keeps them.
+ * provider that changes the world keeps these in the memory its maker
+ * receives, where a restart and a move keep them.
  */
 export class Payments {
   readonly #answered = new Map<string, Answer>();
@@ -581,55 +617,31 @@ export class Payments {
 export const paymentsOffer = (payments: Payments): Offer => ({ blueprint: PaymentsBlueprint, object: payments, window: 7 * 86_400_000 });
 ```
 
-An offer is `{ blueprint, object, kinds?, window?, handler?, stop? }`.
-
-- **The object has the blueprint's methods.** Each takes one args object
-  and a context, and answers `{ result }` or `{ error: { message } }`. A
-  throw is a failure to answer, and the house tries again.
-- **The context holds the call id.** An effect arrives again with the same
-  call id when an answer was lost. A faculty that changes the world
-  answers a call id it has seen with the answer it gave.
-- **A handle arrives as a token.** The faculty calls it with
-  `context.call({ token, args, id })`. Its own `id` makes that call run
-  once, however often it is sent.
-- **`kinds` is the ground's grant.** It lists the classes that may hold
-  the offer. Without it, every class whose need it covers holds it.
-- **`window` is how long the faculty remembers a call id.** It is seven
-  days where omitted, and the house gives up on an effect at it.
-- **`handler` answers HTTP on the ground's one listener.** It takes a
-  `Request` and answers a `Response`, or `null` where the request is not
-  its own. A site, an API or an MCP server is a faculty with a handler.
-- **`stop` is called when the ground stops**, faculties in the reverse of
-  the order they were made.
-
-The object arrives living. The ground makes and starts the faculty, and
-the house never starts, stops or restarts it. Every being whose need it
-covers holds the same object.
-
-A faculty is the ground's, never a house's. The ground's recipe makes
-each one by name, from the settings the ground hands it. `env` is the
-ground's environment, so a secret stays on its machine and out of the
-code. `dir(name)` answers a folder of the faculty's own.
+An offer is `{ blueprint, object, kinds?, window? }`. The object answers
+each call with its call id, and one that changes the world answers a
+call id it has seen with the answer it gave. A registry holds a maker
+for each faculty by name. The ground stands a faculty when an entry names
+its maker, and the entry's `kinds` grants it to the classes it names.
+[Writing a faculty](FACULTIES.md) teaches the craft whole, with a faculty
+written in Python.
 
 ```ts
 // recipe.ts
 import { Payments, paymentsOffer } from './payments.ts';
 
-export const faculties = () => ({
-  payments: paymentsOffer(new Payments()),
-});
+// A registry: the ground makes each faculty an entry names, by its maker here.
+export const faculties = {
+  payments: () => paymentsOffer(new Payments()),
+};
 ```
 
-Policy over a faculty is written as a being. Limits, approvals and
-quotas are not the faculty's. One being holds the raw faculty through
-`kinds`, and every other being reaches her through a standing.
-
 ## A ground
 
 A ground is the process houses run in, and you write none. `nervur up`
-runs one on a folder: the recipe of its faculties, and a folder of code
-for each house. It keeps a record of its houses, and opens each on the
-bodies the record names.
+runs one on a folder of code: a folder for each house, and each module
+your entries name. It holds one key in `state/`, and keeps every entry
+sealed in its drawer: which faculties stand, and which houses open on
+which bodies.
 
 ### The shop's folder
 
@@ -641,6 +653,13 @@ nervur-ground/
   state/        made by the ground, its owner's alone
 ```
 
+The folder is a package of ECMAScript modules, so Node reads its
+TypeScript as it is written, with no build step.
+
+```bash
+npm init -y && npm pkg set type=module && npm install nervur
+```
+
 A house's folder names what the house holds.
 
 ```ts
@@ -662,39 +681,65 @@ The ground boots in one order, and a stop is that order reversed, on an
 interrupt and on `SIGTERM`.
 
 1. **Lock.** One ground to its state.
-2. **Its own.** Its seeds and its record open.
-3. **Faculties.** The recipe makes each, in its order.
-4. **Houses.** Each house of the record opens on its bodies.
-5. **Hook.** The listeners, then the hand on its socket.
-6. **Ready.** It tells systemd it is up, where systemd waits.
+2. **Key.** Its key is read from `state/key`, drawn there on the first
+   start.
+3. **Drawer.** Its ledger opens, and the key opens its drawer.
+4. **Ladder.** Each faculty its drawer names stands on its registry. One
+   that fails stays down, and says why.
+5. **Houses.** Each house of the drawer opens on its bodies.
+6. **Hook.** The listeners, then the hand on its socket.
+7. **Ready.** It tells systemd it is up, where systemd waits.
 
 It is set by its environment.
 
 | Setting | What it sets |
 | --- | --- |
-| `NERVUR_TCP_PORT` | its TCP port, 7300 where unset |
+| `NERVUR_TCP_PORT` | its TCP port, 9110 where unset |
 | `NERVUR_HTTP_PORT` | its HTTP port, for Quo over the web and every handler; no HTTP where unset |
-| `NERVUR_ADDRESSES` | the public addresses it writes into invitations, by commas |
+| `NERVUR_ADDRESSES` | the public addresses it writes into invitations, by commas: `tcp`, `https`, `http`, `wss` or `ws` |
+| `NERVUR_ORIGINS` | the pages of other origins it answers on the web, by commas; a page of its own host needs none |
+| `NERVUR_ALLOW_PRIVATE` | `1` to dial private and loopback addresses, as two grounds on one machine do |
 | `NERVUR_BIND` | the address it listens on, `0.0.0.0` where unset |
 | `NERVUR_STATE` | its state, `state/` in its folder where unset |
-| `NERVUR_KEYCHAIN` | a keychain service holding its seeds on macOS, in place of files |
+| `NERVUR_UNLOCK` | `keychain:<account>` keeps its key in the macOS keychain, in place of `state/key` |
 | `NERVUR_WAIT` | its bound on every ask, in milliseconds |
 
-The state holds each house's seed in a file its owner alone reads, and
-each house's ledger. A ledger appends every write and never rewrites
-one, and one behind its witness is refused, so a restored backup cannot
-replay what a house already answered. A lost seed is a lost house.
+The state holds the key in a file its owner alone reads, and the
+ground's ledger. Every house keeps its rows in that ledger, sealed. A
+ledger appends every write and never rewrites one. Its witness keeps
+where it last stood, and a ledger behind its witness is refused. So a
+ledger restored alone cannot replay what a house already answered,
+though a whole state folder restored with its witness is not seen. A
+lost key is a lost ground.
+
+The ladder stands once, and the ground stands it again at every start.
+The first entry stands the folder's `recipe.ts` as a registry, by the
+ground's own maker `module`. The second makes the payments from it.
+
+```bash
+npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+```
+
+```bash
+npx nervur faculties add name=payments from=recipe make=payments
+```
 
 A house is added once, and the ground opens it again at every start.
 
 ```bash
-npx nervur houses add name=shop memory='{"body":"ledger"}' classes='{"body":"folder","at":"classes"}' faculties='["payments"]'
+npx nervur houses add name=shop classes='{"body":"folder","at":"classes"}' faculties='["payments"]'
 ```
 
-`memory` and `classes` name the bodies the house is handed. `ledger` and
-`folder` are the ground's own, and a recipe may add more, a git registry
-or another store among them. `faculties` names what the house receives,
-and within it each offer's `kinds` names the classes that hold it.
+`classes` names the body of the house's code. `folder` is the ground's
+own, and a registry may add more, a git repository among them. A house
+keeps its rows in the ground's ledger unless its entry names a `memory`
+body. `faculties` names what the house receives, and within it each
+faculty's entry names in `kinds` the classes that hold it.
+
+A secret reaches a faculty the same way, and never through the
+environment. `npx nervur secrets set -` reads `{ name, value }` from
+standard input into the ground's sealed drawer. A faculty's entry names
+the secrets its maker receives in `secrets`.
 
 ### The hand
 
@@ -714,17 +759,23 @@ npx nervur houses list
 ```
 
 `ask` asks a being in a house as `root`: the steward, or the being
-`--id` names. The owner lands a paper in a being with one ask, and her
-`accept` names `root` in its `for`, or names no `for`.
+`--id` names. The owner opens an order through the steward, and hands a
+courier's paper to it the same way. The steward's `hire` carries the
+paper unopened, and the order takes it.
 
 ```bash
 npx nervur ask shop open id=first
 ```
 
 ```bash
-npx nervur ask shop --id alice accept invitation=7b22…
+npx nervur ask shop hire order=first courier=7b22…
 ```
 
+`--id` names the being asked in the steward's place, as `npx nervur ask
+shop --id first` shows the order's describe. `--cells` reads her cells
+and asks nothing, as `npx nervur ask shop --id first --cells`. No one
+but the owner reads them, and only her own asks write them.
+
 Each prints one JSON value. It exits 0 on a result and 1 on an error
 answered. It exits 2 where nothing was asked, so a script tells a
 refusal from a ground that is down. The hand is `state/hand` in the
@@ -750,7 +801,7 @@ with `loginctl enable-linger`. On macOS, the agent goes to
 
 ### In a page
 
-`BrowserGround.open({ recipe })` from `nervur/browser` runs the same
+`BrowserGround.open({ registry })` from `nervur/browser` runs the same
 houses in a page. Every tab and the service worker of one origin share
 one ground: the one holding the Web Lock runs it, and the others reach
 its hand over a `BroadcastChannel`. When it closes, the next opens the
@@ -758,12 +809,12 @@ ground from the same storage. `hand` answers the same three requests
 the command sends: `describe`, a faculty's method, and an ask of a being
 in a named house.
 
-Its bodies are the browser's. Seeds are sealed under an AES key that
-IndexedDB holds unextractable, and memory is IndexedDB, named
-`indexeddb` in an entry. Classes load from the page's own origin through
-the `origin` body, `{ body: 'origin', at: '/house/index.js' }`, and a
-path off the origin is refused. The recipe is the object you pass: its
-faculties, made by a function, and any custom body.
+Its bodies are the browser's. The ground's key is sealed under an AES
+key that IndexedDB holds unextractable, and its memory is IndexedDB.
+Classes load from the page's own origin through the `origin` body, `{
+body: 'origin', at: '/house/index.js' }`, and a path off the origin is
+refused. The registry is the object you pass: makers of faculties, and
+of any custom body, beside the terrain's own.
 
 Any script on the origin can use the ground's keys, so the ground is
 whoever serves the origin's script. Give it an origin of its own, serve
@@ -787,10 +838,10 @@ app's web view, on two interfaces the shell fills in native code:
   which lands every write only where each key in `expect` still holds
   what it names, and answers whether it landed.
 
-The library holds the rest. Each house's seed goes into the secret
-store, and each memory into the native store, which the system never
-evicts as it may a web view's storage. A push token reaches the ground
-through a faculty your recipe makes.
+The library holds the rest. The ground's key goes into the secret store,
+and its memory into the native store, which the system never evicts as
+it may a web view's storage. A push token reaches the ground through a
+faculty your registry makes.
 
 ## What the house guarantees
 
@@ -812,3 +863,43 @@ through a faculty your recipe makes.
    leaves her absent, and the refusal says why.
 
 A failed ask changed nothing she owns, so asking again is safe.
+
+## What the house refuses
+
+Each refusal answers why, where it is met: at her class's first resolve,
+at her call, or where an ask arrives.
+
+- A being reaching anything her position, her needs and `this.house` do
+  not give.
+- A ground's own references handed to a being, or offered to her as a
+  faculty.
+- A handle or an invitation in her cells.
+- Her cells read by anyone but the owner's hand.
+- A standing she mints herself. Standings arrive from the house.
+- A far standing asked in the ask that took it. She asks it from her next
+  ask.
+- A write by anyone else to her notes, and by her to her steward's.
+- An occupant id the house reserves, and one she already holds.
+- Two member names that clash.
+- An ask with no entry.
+- A state no ask reaches, an ask no role reaches, and a role unused.
+- A method landing in a state its `to` does not name.
+- A `readOnly` ask that writes.
+- A need and an offer that disagree on `idempotent`.
+- A schema keyword outside the subset `s` writes.
+- Two offers covering one need for one kind, and a kind two sources
+  claim.
+- An effect sent before its ask landed, or sent again while a call for
+  it is pending.
+- An ask a stranger reaches that is not idempotent.
+- An invite from a public being.
+- A seed inside the house, and a seed that is not sixty-four hex digits.
+- A memory opened with keys that derive another bound.
+- A send to a private address, unless its ground allows it.
+- A call on the house beside `House.open`, `door` and `ask`.
+- A faculty in a house's code. Faculties are the ground's.
+- A drawer opened with a key that did not seal it.
+- A secret read by a being, a describe or anyone but a maker its entry
+  names.
+- A faculty entry for `secrets` or `moves`, which the hand alone reaches.
+- A ground an owner must write. Each terrain's ships.

package/COMMAND.md

@@ -0,0 +1,128 @@
+# The command
+
+`nervur` is the command the package installs. It holds no business of
+its own. Two words start things on your machine, and every other word is
+read from what the running ground says it holds. This guide assumes you
+have read [the package's start](README.md), which runs a first ground.
+
+## Starting a ground
+
+`nervur up` runs a NodeGround on a folder until it is stopped. The
+folder holds your code: a folder for each house, and each module or
+program your entries name. `state/` holds the ground's key, its ledger
+and its hand. The key is drawn on the first start, into a file your user
+alone reads.
+
+```bash
+npx nervur up .
+```
+
+The ground stops cleanly on an interrupt and on `SIGTERM`. It takes a
+lock on its state, so a second `nervur up` on the same folder refuses to
+start. Keep `state/` as you keep an ssh key: whoever holds its key and
+its ledger holds the ground, and without the key the ledger opens
+nothing.
+
+`nervur service` prints what keeps the ground running across reboots: a
+systemd unit on Linux, a launchd job on macOS. Nothing is installed; you
+place what it prints.
+
+```bash
+npx nervur service /srv/shop
+```
+
+## Settings
+
+A ground reads its settings from the environment.
+
+| Setting | What it sets |
+| --- | --- |
+| `NERVUR_STATE` | the state folder, `state/` in the ground's folder where unset |
+| `NERVUR_TCP_PORT` | the TCP port Quo listens on, 9110 where unset |
+| `NERVUR_HTTP_PORT` | the port of the web listener, which faces and Quo over the web share; none where unset |
+| `NERVUR_BIND` | the address both listen on, every interface where unset |
+| `NERVUR_ADDRESSES` | the public addresses written into invitations, by commas |
+| `NERVUR_ORIGINS` | the page origins the web listener answers, by commas |
+| `NERVUR_ALLOW_PRIVATE` | `1` to let the ground dial a private or loopback address |
+| `NERVUR_UNLOCK` | on macOS, `keychain:<account>` keeps the key in the keychain in place of `state/key` |
+| `NERVUR_HAND` | where the hand's socket is, `state/hand` where unset; a relative path is read from where the command runs |
+| `NERVUR_WAIT` | the longest any ask may run, in milliseconds |
+
+A ground that people reach names its public addresses. Without them, it
+writes only the addresses it listens on, which a stranger cannot reach.
+
+A socket's path fits 103 bytes on macOS and 107 on Linux, and a longer
+one refuses to start by name. A ground in a deep folder names a shorter
+path in `NERVUR_HAND`, such as `state/hand` run from the folder, and every
+command that reaches it names the same.
+
+## Asking the ground
+
+Every other word goes to the ground's hand, a socket in `state/` that
+your user alone may open. Run the command in the ground's folder, or
+name the socket with `--at <socket>` or `NERVUR_HAND`.
+
+`help` prints what the ground holds: each faculty with its methods, or
+why it is down, and each house.
+
+```bash
+npx nervur help
+```
+
+A faculty is called by its name and a method. Named alone, it prints its
+methods. Four faculties are the ground's own. `secrets` keeps a secret
+in the ground's sealed drawer. `faculties` stands a faculty on the maker
+its entry names, and `houses` opens a house on its entry.
+
+```bash
+npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+npx nervur faculties add name=payments from=recipe make=payments secrets='["stripe-key"]'
+npx nervur houses add name=main classes='{"body":"folder","at":"house"}' faculties='["payments"]'
+```
+
+`ask` asks a being of a house, as the house's owner. `--id <being>` names
+her, and with none it asks the steward. With no method, it prints what
+she shows.
+
+```bash
+npx nervur ask main
+```
+
+`--cells` reads a being's cells as they last landed, and asks nothing.
+Nothing but the hand reads cells, which makes it the tool for a test, a
+repair, or a look at what her asks do not show.
+
+```bash
+npx nervur ask main --cells
+```
+
+The command asks no watch. A watch is held by a being on her standing,
+or by a page through a face, where something waits on its answer.
+
+## Arguments and answers
+
+Arguments are one JSON object, or words `key=value`. A value is read as
+JSON where it reads as JSON, and as text where it does not, so
+`count=3` is a number and `name=Ada` is text.
+
+```bash
+npx nervur ask main hello '{"name":"Ada"}'
+```
+
+A lone `-` reads the one JSON object from standard input instead. So a
+secret never stands on a command line or in a shell's history.
+
+```bash
+npx nervur secrets set - < stripe-key.json
+```
+
+Each word prints one JSON value, the answer, and its exit code says what
+came back.
+
+| Exit | What it means |
+| --- | --- |
+| 0 | a result, or what she shows |
+| 1 | an error the ground or the being answered |
+| 2 | nothing was asked: a word the command does not know, or a hand that does not answer |
+
+So a script tells a refusal from a ground that is down.