nervur 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,53 @@
+# nervur
+
+The nervur CLI — the operator's command-line face over a running carcass.
+It is a client, never the runtime: every verb speaks to the carcass's HTTP
+API, and the same verbs exist at parity on the nervur console, the
+machine-level face the carcass serves on loopback.
+
+nervur is neutral ground for inter-company work: two companies are two
+cryptographic identities meeting in one shared datastore that neither hosts
+and both can read. Humans and AI agents are first-class colleagues on it.
+
+## Install
+
+```sh
+npm create nervur
+```
+
+One command stands the whole thing: verifies Docker (binary · daemon ·
+permission, each failure a one-line fix), pulls the carcass image, lays down
+compose + volume under `~/.nervur`, and mints your first identity.
+
+## Verbs
+
+```text
+carcass family: install, up, down, reset, preflight, whoami, status,
+                identity, use, add, list, remove
+being family:   scaffold, deploy, species
+
+  install                 Docker preflight, then stand a carcass at
+                          NERVUR_HOME (default ~/.nervur)
+  whoami · status         the carcass answers with its identity and state
+  identity add <name>     mint an identity on this machine (silent, idempotent);
+                          --key <file> adopts a brought ed25519 key instead —
+                          it never replaces an existing different owner
+  identity key <name>     print the identity's private key (base64url PKCS8),
+                          the exact shape --key accepts back
+  identity list           identities on this machine · name + public id
+  identity remove <name>  destroy an identity — refused while beings or
+                          sealed lineages remain (only an empty one goes)
+  use [name]              select which identity add/list act as
+  add <kind> [--as name]  add a being under the selected identity
+  list · remove <name>    the fleet registry · retire a being
+  scaffold <name>         mint a species repo (the DNA)
+  deploy <name> <repo> <hash>   grant + pin + run a species
+  species                 list deployed species and their pins
+```
+
+No verb ever prompts — every fork is a flag or env var with a sane default,
+and destructive turns are their own explicitly named verbs.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/completion.js

@@ -0,0 +1,122 @@
+// nervur — shell completion (`nervur completion [bash|zsh]`). Client-local like
+// scaffold: touches no carcass. One verb table is the single truth; both scripts
+// are generated from it so a new verb lands in completion by editing one list.
+// No prompt anywhere: the shell is a positional with a sane default ($SHELL).
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// verb → one-line description; subs/kinds drive second-position completion.
+export const VERBS = [
+  ['install', 'stand a published carcass at NERVUR_HOME'],
+  ['up', '(dev bench) preflight, then stand the ground'],
+  ['down', 'stop the ground'],
+  ['reset', 'stop the ground and wipe its data'],
+  ['preflight', 'run the bench preflight and report'],
+  ['whoami', 'ask the carcass who it is'],
+  ['status', 'ask the carcass for its status'],
+  ['identity', 'manage identities (add · key · list · remove)'],
+  ['use', 'select the identity the verbs act as'],
+  ['add', 'add a being under the selected identity'],
+  ['list', 'list the beings on the ground'],
+  ['remove', 'remove a being'],
+  ['scaffold', 'mint a species repo from a template'],
+  ['deploy', 'grant + pin + run a species'],
+  ['species', 'list deployed species and their pins'],
+  ['completion', 'print the shell completion script (bash · zsh)'],
+  ['help', 'show help']
+]
+
+const names = VERBS.map(([v]) => v).join(' ')
+
+const bash = () => `# nervur completion (bash)
+# load now:   eval "$(nervur completion bash)"
+# persist:    nervur completion bash >> ~/.bashrc   (or into bash_completion.d)
+_nervur() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  case "$prev" in
+    identity)   COMPREPLY=($(compgen -W "add key list remove" -- "$cur")); return ;;
+    completion) COMPREPLY=($(compgen -W "bash zsh" -- "$cur")); return ;;
+    add|--kind) COMPREPLY=($(compgen -W "empty" -- "$cur")); return ;;
+    --dir)      COMPREPLY=($(compgen -d -- "$cur")); return ;;
+  esac
+  case "$cur" in
+    --*) COMPREPLY=($(compgen -W "--as --no-door --kind --dir --key" -- "$cur")); return ;;
+  esac
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${names}" -- "$cur"))
+  fi
+}
+complete -F _nervur nervur
+`
+
+const zsh = () => `#compdef nervur
+# nervur completion (zsh)
+# load now:   eval "$(nervur completion zsh)"
+# persist:    nervur completion zsh > "\${fpath[1]}/_nervur" && rm -f ~/.zcompdump; compinit
+_nervur() {
+  local -a verbs
+  verbs=(
+${VERBS.map(([v, d]) => `    '${v}:${d.replace(/'/g, "'\\''")}'`).join('\n')}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'verb' verbs
+    return
+  fi
+  case "\${words[2]}" in
+    identity)     (( CURRENT == 3 )) && _values 'sub' add key list remove ;;
+    completion)   (( CURRENT == 3 )) && _values 'shell' bash zsh ;;
+    add)          (( CURRENT == 3 )) && _values 'kind' empty ;;
+    scaffold)     _arguments '--kind[template kind]:kind:(empty)' '--dir[target directory]:dir:_directories' ;;
+    up|preflight) _arguments '--no-door[stand on localhost only (headless/CI)]' ;;
+  esac
+}
+if (( ! $+functions[compdef] )); then
+  autoload -Uz compinit
+  compinit
+fi
+compdef _nervur nervur
+`
+
+export function completionScript(shell) {
+  const which = shell ?? (process.env.SHELL?.endsWith('zsh') ? 'zsh' : 'bash')
+  if (which === 'zsh') return zsh()
+  if (which === 'bash') return bash()
+  throw new Error(`usage: nervur completion [bash|zsh] — '${which}' is not a shell I know`)
+}
+
+const MARK_OPEN = '# >>> nervur completion >>>'
+const MARK_CLOSE = '# <<< nervur completion <<<'
+
+// Wire completion for the operator's shell: the script lands as a file in the
+// nervur home and the rc file gains one marked source-block — sourcing a file
+// costs nothing per shell start, where `eval "$(nervur completion)"` would
+// spawn node every time. Idempotent by the marker block (the dev/hosts.sh
+// idiom): re-wiring rewrites the block in place, never stacks a second one.
+export function wireCompletion(home) {
+  const shell = process.env.SHELL?.endsWith('zsh')
+    ? 'zsh'
+    : process.env.SHELL?.endsWith('bash')
+      ? 'bash'
+      : null
+  if (!shell) return { wired: false }
+  mkdirSync(home, { recursive: true })
+  const scriptPath = join(home, `completion.${shell}`)
+  writeFileSync(scriptPath, completionScript(shell))
+  const rc = join(homedir(), shell === 'zsh' ? '.zshrc' : '.bashrc')
+  const block = `${MARK_OPEN}\n[ -f "${scriptPath}" ] && source "${scriptPath}"\n${MARK_CLOSE}\n`
+  const current = existsSync(rc) ? readFileSync(rc, 'utf8') : ''
+  if (current.includes(MARK_OPEN)) {
+    const next = current.replace(
+      current.slice(current.indexOf(MARK_OPEN), current.indexOf(MARK_CLOSE) + MARK_CLOSE.length + 1),
+      block
+    )
+    if (next !== current) writeFileSync(rc, next)
+  } else {
+    appendFileSync(rc, `${current && !current.endsWith('\n') ? '\n' : ''}\n${block}`)
+  }
+  return { wired: true, shell, rc, scriptPath }
+}

package/nervur.js

@@ -6,6 +6,7 @@
 // LIVE ground, not a fresh in-process being.
 
 import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -14,6 +15,8 @@ import { pathToFileURL } from 'node:url'
 import { resolveTemplate } from '@nervur-org/kit/templates.js'
 import { runPreflight, renderChain, blockingFailure } from './preflight.js'
 import { scaffoldSpecies } from './scaffold.js'
+import { completionScript, wireCompletion, VERBS } from './completion.js'
+import { banner, bold, columns, cyan, dim, heading, identityTree, red } from './style.js'
 
 // The one published tag — what `nervur install` pulls, and what a local
 // `docker build` must name for install to find it (papers/dev.md — "the
@@ -144,8 +147,11 @@ const postJsonStatus = async (url, body) => {
 // loopback via the NERVUR_PORT/NERVUR_FACES_PORT seams. Caddy fronting is parked
 // (papers/prod.md — "arrives with the per-box configuration"); this is the honest
 // floor today. Rewritten on every `install` — mechanical, never hand-edited.
-function installCompose() {
-  return `name: nervur
+// Docker derives volume/network names from the project name — a fixed name would
+// share one state volume across every NERVUR_HOME on the machine.
+function installCompose(home) {
+  const scope = createHash('sha256').update(realpathSync(home)).digest('hex').slice(0, 8)
+  return `name: nervur-${scope}
 
 # Generated by \`nervur install\` — the published carcass stand (papers/host.md,
 # papers/dev.md § the published install idiom). Image disposable, volume durable:
@@ -225,6 +231,7 @@ async function main() {
 
   const faceDomain = config.domains?.face
 
+  const bare = rawArgs.length === 0
   const [verb = 'whoami', ...args] = rawArgs
   const print = (v) => console.log(JSON.stringify(v, null, 2))
 
@@ -266,7 +273,7 @@ async function main() {
       console.log(renderChain(results))
       const blocked = blockingFailure(results)
       if (blocked) {
-        console.error(`\n  refusing: ${blocked.name} — ${blocked.note}\n  fix: ${blocked.fix}`)
+        console.error(`\n  ${red('refusing:')} ${blocked.name} — ${blocked.note}\n  ${dim('fix:')} ${blocked.fix}`)
         process.exit(1)
       }
 
@@ -275,17 +282,16 @@ async function main() {
       const port = process.env.NERVUR_PORT ?? '4000'
       const facesPort = process.env.NERVUR_FACES_PORT ?? '4400'
 
-      // The carcass image: present locally, or pullable. No registry is published
-      // yet, so a pull will fail honestly — refuse with the exact local fix rather
-      // than raising a compose against an image that isn't there.
+      // Refused here, before the compose — `compose up` against a missing image
+      // fails too, but far less legibly than this message.
       const inspect = spawnSync('docker', ['image', 'inspect', image], { stdio: 'ignore' })
       if (inspect.status !== 0) {
         console.log(`  · image ${image} not found locally — trying \`docker pull\`…`)
         const pull = spawnSync('docker', ['pull', image], { stdio: 'inherit' })
         if (pull.status !== 0) {
           console.error(
-            `\n  refusing: no carcass image '${image}' locally, and no registry to pull from yet.\n` +
-              `  fix: \`docker build -f carcass/Dockerfile -t ${image} .\` builds it, or \`docker pull ${image}\` once a registry is published`
+            `\n  refusing: no carcass image '${image}' locally, and the pull failed.\n` +
+              `  fix: check the network and the image name — \`docker pull ${image}\` by hand shows the registry's answer; \`docker build -f carcass/Dockerfile -t ${image} .\` builds it locally`
           )
           process.exit(1)
         }
@@ -296,7 +302,7 @@ async function main() {
       // boot converges whatever it finds, papers/host.md).
       mkdirSync(home, { recursive: true })
       const composePath = join(home, 'compose.yml')
-      writeFileSync(composePath, installCompose())
+      writeFileSync(composePath, installCompose(home))
       const groundPath = join(home, 'ground.config.js')
       if (!existsSync(groundPath)) writeFileSync(groundPath, installGroundConfig())
 
@@ -311,8 +317,26 @@ async function main() {
 
       const localUrl = `http://localhost:${port}`
       await knock({ localUrl: `${localUrl}/health` })
-      console.log(`  · carcass standing at ${home} — face on ${localUrl}`)
       print(await getJson(`${localUrl}/whoami`))
+
+      // TTY-gated: CI, probes, and scripts must never gain an rc edit as a
+      // side effect of install; NERVUR_COMPLETION=0 opts a human out too.
+      let completionRow = ['shell', 'nervur completion', 'prints the autocomplete script']
+      if (process.stdout.isTTY && process.env.NERVUR_COMPLETION !== '0') {
+        const wired = wireCompletion(home)
+        if (wired.wired)
+          completionRow = ['shell', `${wired.shell} autocomplete wired`, `${wired.rc} — new shells complete`]
+      }
+
+      const consolePort = process.env.NERVUR_CONSOLE_PORT ?? '4200'
+      console.log(
+        banner('nervur is standing', [
+          ['console', cyan(`http://localhost:${consolePort}`), 'open in your browser'],
+          ['home', home, 'compose + ground config, kept across installs'],
+          completionRow,
+          ['next', 'nervur add empty', 'stand your first being']
+        ]) + `\n    ${dim(`api ${localUrl}`)}\n`
+      )
       break
     }
     case 'preflight': {
@@ -331,7 +355,7 @@ async function main() {
       console.log(renderChain(results))
       const blocked = blockingFailure(results)
       if (blocked) {
-        console.error(`\n  refusing: ${blocked.name} — ${blocked.note}\n  fix: ${blocked.fix}`)
+        console.error(`\n  ${red('refusing:')} ${blocked.name} — ${blocked.note}\n  ${dim('fix:')} ${blocked.fix}`)
         process.exit(1)
       }
       if (config.certs) sh('bash', [config.certs])
@@ -355,6 +379,14 @@ async function main() {
           )
         print(await getJson(`${face()}/whoami`))
       }
+      // The console is loopback-only by design (host.md — "One operator, one
+      // console"), so its URL is localhost even when the face answers through
+      // the domain door.
+      console.log(
+        banner('ground is standing', [
+          ['console', cyan(`http://localhost:${config.console?.port ?? 4200}`), 'open in your browser']
+        ]) + `\n    ${dim(`api ${via === 'domain' ? `https://${faceDomain}` : face()}`)}\n`
+      )
       break
     }
     case 'down':
@@ -366,9 +398,25 @@ async function main() {
       for (const dir of config.dataDirs ?? []) rmSync(dir, { recursive: true, force: true })
       console.log('reset')
       break
-    case 'whoami':
-      print(await getJson(`${face()}/whoami`))
+    case 'whoami': {
+      const who = await getJson(`${face()}/whoami`)
+      if (!bare || !process.stdout.isTTY) {
+        print(who)
+        break
+      }
+      const consoleUrl = `http://localhost:${process.env.NERVUR_CONSOLE_PORT ?? config.console?.port ?? 4200}`
+      const beings = who.beings ?? []
+      const tree = identityTree(who.identities ?? [], beings, selectedIdentity)
+      const hint = beings.length
+        ? ''
+        : `\n\n    ${dim('nervur add empty stands your first being')}`
+      console.log(
+        `\n${heading(`nervur — carcass ${who.health} ${dim(`· v${who.version}`)}`)}\n\n${tree}${hint}\n\n` +
+          `${columns([['console', cyan(consoleUrl), 'open in your browser']])}\n\n` +
+          `    ${dim(`api ${face()} · faces ${who.faces ?? '—'}`)}\n`
+      )
       break
+    }
     case 'status':
       print(await getJson(`${face()}/status`))
       break
@@ -380,22 +428,48 @@ async function main() {
         })
       )
       break
-    case 'list':
-      print(await getJson(`${face()}/fleet/list`))
+    case 'list': {
+      const fleet = await getJson(`${face()}/fleet/list`)
+      if (!process.stdout.isTTY) {
+        print(fleet)
+        break
+      }
+      const identities = (await getJson(`${face()}/identities`)).map((i) => i.name)
+      console.log(`\n${identityTree(identities, fleet, selectedIdentity)}\n`)
       break
+    }
     case 'remove':
       if (!args[0]) throw new Error('usage: nervur remove <name>')
       print(await postJson(`${face()}/fleet/remove`, { name: args[0] }))
       break
     // ── identities (papers/host.md — "The identities"): locally one carcass
-    //    custodies many, one vault each. `add` mints silently, `list` shows the
-    //    public ids only, `remove` refuses (409) while any being is attached —
-    //    never force, never prompt.
+    //    custodies many, one vault each. `add` mints silently — or adopts a brought
+    //    key (`--key`, the bring-your-own-key seed; a different key never replaces
+    //    an owner, 409). `list` shows the public ids only; `key` prints the owner's
+    //    private key (the export half, hand-to-self); `remove` refuses (409) while
+    //    any being is attached — never force, never prompt.
     case 'identity': {
       const [sub, name] = positional(args)
       if (sub === 'add') {
-        if (!name) throw new Error('usage: nervur identity add <name>')
-        print(await postJson(`${face()}/identities/add`, { name }))
+        if (!name) throw new Error('usage: nervur identity add <name> [--key <file>]')
+        const keyFile = flagValue(args, '--key')
+        const key = keyFile ? readFileSync(keyFile, 'utf8').trim() : undefined
+        const { status, body } = await postJsonStatus(`${face()}/identities/add`, { name, key })
+        if (status >= 400) {
+          console.error(`nervur: ${body.error}`)
+          process.exit(1)
+        }
+        print(body)
+      } else if (sub === 'key') {
+        if (!name) throw new Error('usage: nervur identity key <name>')
+        const { status, body } = await postJsonStatus(`${face()}/identities/key`, { name })
+        if (status >= 400) {
+          console.error(`nervur: ${body.error}`)
+          process.exit(1)
+        }
+        // The secret alone, pipe-friendly (`nervur identity key acme > key.txt`) —
+        // base64url PKCS8 DER, the exact shape `identity add --key` accepts back.
+        console.log(body.secret)
       } else if (sub === 'list') {
         const list = await getJson(`${face()}/identities`)
         for (const i of list)
@@ -404,10 +478,17 @@ async function main() {
         if (!name) throw new Error('usage: nervur identity remove <name>')
         const { status, body } = await postJsonStatus(`${face()}/identities/remove`, { name })
         if (status === 409) {
-          console.error(
-            `refused: identity '${name}' still has beings attached: ${body.beings.join(', ')}`
-          )
-          for (const b of body.beings) console.error(`  fix: nervur remove ${b}`)
+          if (body.beings) {
+            console.error(
+              `refused: identity '${name}' still has beings attached: ${body.beings.join(', ')}`
+            )
+            for (const b of body.beings) console.error(`  fix: nervur remove ${b}`)
+          } else {
+            console.error(
+              `refused: identity '${name}' still holds sealed lineages: ${body.lineages.join(', ')}`
+            )
+            console.error('  lineage destruction has no verb yet — the sealed custody stays')
+          }
           process.exit(1)
         }
         if (status >= 400) {
@@ -416,7 +497,7 @@ async function main() {
         }
         print(body)
       } else {
-        throw new Error('usage: nervur identity <add|list|remove> <name>')
+        throw new Error('usage: nervur identity <add|key|list|remove> <name>')
       }
       break
     }
@@ -428,6 +509,26 @@ async function main() {
         console.log(selectedIdentity)
         break
       }
+      // Sticky selection is a client act, but it selects a real vault — an
+      // unknown name is refused against the live list here, never stored to
+      // fail later as a runtime surprise on some other verb.
+      let known
+      try {
+        known = (await getJson(`${face()}/identities`)).map((i) => i.name)
+      } catch {
+        console.error(
+          `nervur: ${red(`cannot verify identity '${name}'`)} — no carcass answering at ${face()}\n` +
+            `  ${dim('fix:')} stand it first — nervur up (bench) or nervur install (published)`
+        )
+        process.exit(1)
+      }
+      if (!known.includes(name)) {
+        console.error(
+          `nervur: ${red(`no identity '${name}'`)} on this carcass — have: ${known.join(' · ') || '(none)'}\n` +
+            `  ${dim('fix:')} nervur identity add ${name}`
+        )
+        process.exit(1)
+      }
       mkdirSync(dirname(stickyPath), { recursive: true })
       writeFileSync(stickyPath, name)
       console.log(`using identity '${name}'`)
@@ -462,34 +563,61 @@ async function main() {
     case 'species':
       print(await getJson(`${face()}/deploy/list`))
       break
+    case 'completion':
+      process.stdout.write(completionScript(positional(args)[0]))
+      break
     case 'help':
     case '--help':
-    case '-h':
+    case '-h': {
+      // Help renders from the same VERBS table completion generates from — a
+      // verb missing here was never added to cli/completion.js.
+      const sig = {
+        up: '[--no-door]',
+        preflight: '[--no-door]',
+        identity: '<add|key|list|remove> [name] [--key <file>]',
+        use: '[name]',
+        add: '<kind> [--as <identity>]',
+        remove: '<name>',
+        scaffold: '<name> [--kind empty] [--dir <path>]',
+        deploy: '<name> <repo> <full-commit-hash>',
+        completion: '[bash|zsh]'
+      }
+      const carcass = new Set([
+        'install', 'up', 'down', 'reset', 'preflight', 'whoami', 'status',
+        'identity', 'use', 'add', 'list', 'remove'
+      ])
+      // Pad on the UNSTYLED signature so ANSI codes never skew the column.
+      const width = Math.max(...VERBS.map(([v]) => `${v} ${sig[v] ?? ''}`.trim().length))
+      const row = ([v, d]) => {
+        const plain = `${v}${sig[v] ? ` ${sig[v]}` : ''}`
+        const left = `${bold(v)}${sig[v] ? ` ${dim(sig[v])}` : ''}`
+        return `  ${left}${' '.repeat(width - plain.length + 2)}${d}`
+      }
       console.log(
-        'nervur — client of a running carcass\n\n' +
-          'carcass family: install, up, down, reset, preflight, whoami, status, identity, use, add, list, remove\n' +
-          'being family:   scaffold, deploy, species\n\n' +
-          '  install                Docker preflight, then stand a carcass at NERVUR_HOME (default ~/.nervur)\n' +
-          '                        [NERVUR_HOME, NERVUR_IMAGE, NERVUR_PORT, NERVUR_FACES_PORT]\n' +
-          '  up [--no-door]        (dev bench) run the bench preflight, then stand the ground\n' +
-          '  preflight [--no-door] run the bench preflight and report (exit code = verdict)\n' +
-          '  identity add <name>   mint an identity on this machine (silent, idempotent)\n' +
-          '  identity list         list identities on this machine · name + public id\n' +
-          '  identity remove <name> destroy an identity — refused (409) while beings remain\n' +
-          '  use [name]            select which identity add/list act as (client-only); no args prints it\n' +
-          '  add <kind> [--as name] add a being under the selected (or --as) identity\n' +
-          '  scaffold <name>       mint a species repo (the DNA) [--kind empty] [--dir <path>]\n' +
-          '  deploy <name> <repo> <full-commit-hash>   grant + pin + run a species\n' +
-          '  species               list the deployed species and their pins\n\n' +
-          'the door is open by default; --no-door (or NERVUR_DOOR=0) stands the ground\n' +
-          'on localhost only for headless/CI — the hosts check degrades, 443 is skipped'
+        `${bold('nervur')} — client of a running carcass\n\n` +
+          `${dim('usage')}  nervur <verb> [args] ${dim('[--as <identity>]')}\n\n` +
+          `${cyan('carcass family')}\n` +
+          VERBS.filter(([v]) => carcass.has(v)).map(row).join('\n') +
+          `\n\n${cyan('being family')}\n` +
+          VERBS.filter(([v]) => !carcass.has(v) && v !== 'help').map(row).join('\n') +
+          `\n\n${dim(
+            'install honors NERVUR_HOME · NERVUR_IMAGE · NERVUR_PORT · NERVUR_FACES_PORT · NERVUR_CONSOLE_PORT\n' +
+              'the door is open by default; --no-door (or NERVUR_DOOR=0) stands the ground\n' +
+              'on localhost only for headless/CI — the hosts check degrades, 443 is skipped'
+          )}`
       )
       break
-    default:
+    }
+    default: {
+      const known = VERBS.map(([v]) => v)
+      const near = known.filter((v) => v.startsWith(verb) || verb.startsWith(v.slice(0, 3)))
       console.error(
-        `nervur: unknown verb: ${verb} (have: install, up, down, reset, preflight, whoami, status, identity, use, add, list, remove, scaffold, deploy, species)`
+        `nervur: ${red(`unknown verb: ${verb}`)}` +
+          (near.length ? ` — did you mean ${near.map(bold).join(' · ')}?` : '') +
+          `\n${dim(`have: ${known.join(', ')}`)}`
       )
       process.exit(1)
+    }
   }
   process.exit(0)
 }
@@ -508,7 +636,7 @@ function invokedAsCli() {
 }
 if (invokedAsCli()) {
   main().catch((e) => {
-    console.error(`nervur: ${e.message}`)
+    console.error(`nervur: ${red(e.message)}`)
     process.exit(1)
   })
 }

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "nervur",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The nervur CLI — a client of a running carcass, never the runtime (papers/host.md).",
   "type": "module",
   "bin": {
-    "nervur": "./nervur.js"
+    "nervur": "nervur.js"
   },
   "files": [
     "nervur.js",
     "preflight.js",
-    "scaffold.js"
+    "scaffold.js",
+    "completion.js",
+    "style.js"
   ],
   "dependencies": {
-    "@nervur-org/kit": "*"
+    "@nervur-org/kit": "^0.1.0"
   },
   "license": "Apache-2.0"
 }

package/preflight.js

@@ -14,6 +14,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { lookup } from 'node:dns/promises'
+import { dim, glyph } from './style.js'
 
 // Status vocabulary: 'ok' passes; 'fail' blocks (refuse at the door); 'warn' is
 // advisory — a real finding that never blocks (browser trust, the door-closed
@@ -146,13 +147,13 @@ export async function runPreflight(config, { door = true } = {}) {
   ]
 }
 
-const GLYPH = { ok: '✓', fail: '✗', warn: '!', skip: '·' }
-
 export function renderChain(results) {
   const lines = []
   for (const r of results) {
-    lines.push(`  ${GLYPH[r.status] ?? '·'} ${r.name.padEnd(9)} ${r.note}`)
-    if ((r.status === 'fail' || r.status === 'warn') && r.fix) lines.push(`      ↳ fix: ${r.fix}`)
+    const note = r.status === 'skip' ? dim(r.note) : r.note
+    lines.push(`  ${glyph[r.status] ?? glyph.skip} ${r.name.padEnd(9)} ${note}`)
+    if ((r.status === 'fail' || r.status === 'warn') && r.fix)
+      lines.push(`      ${dim('↳ fix:')} ${r.fix}`)
   }
   return lines.join('\n')
 }

package/style.js

@@ -0,0 +1,82 @@
+// nervur — CLI presentation: color and the standing banner. Pure node:util
+// styleText, zero dependencies; color only when stdout is a TTY and NO_COLOR is
+// unset, so piped output (probes, scripts) stays plain and machine-stable.
+
+import * as util from 'node:util'
+
+// util.styleText arrives in node 20.12/21.7 — a named import would crash the
+// whole CLI on anything older (an operator's nvm default may lag), so ink is
+// feature-detected: absent, everything renders plain instead of dying.
+const styleText = util.styleText ?? ((_format, text) => text)
+const stripVTControlCharacters = util.stripVTControlCharacters ?? ((s) => s)
+
+const on = () => process.stdout.isTTY && !process.env.NO_COLOR
+
+// paint(format, text) — styleText that degrades to plain text off-TTY. `format`
+// is a styleText format or array of formats ('green', ['bold','cyan'], …).
+export const paint = (format, text) => (on() ? styleText(format, text) : text)
+
+export const dim = (t) => paint('dim', t)
+export const bold = (t) => paint('bold', t)
+export const red = (t) => paint('red', t)
+export const green = (t) => paint('green', t)
+export const yellow = (t) => paint('yellow', t)
+export const cyan = (t) => paint('cyan', t)
+
+// The status glyphs the preflight chain and the probes share, colored: the
+// vocabulary stays ✓ ✗ ! · (preflight.js), only the ink changes.
+export const glyph = {
+  ok: green('✓'),
+  fail: red('✗'),
+  warn: yellow('!'),
+  skip: dim('·')
+}
+
+// The standing banner — printed once the carcass answers, on `install` and `up`.
+// The console line leads: it is the operator's browser door (host.md — "One
+// operator, one console"), and the one URL a fresh operator should open first.
+// rows: [label, value, note?]; labels and notes align in columns, notes ride
+// dim. Values may carry ANSI ink, so columns measure the stripped length.
+const plainLength = (s) => stripVTControlCharacters(s).length
+
+export function columns(rows) {
+  const labelW = Math.max(...rows.map(([label]) => label.length))
+  const valueW = Math.max(...rows.map(([, value]) => plainLength(value)))
+  return rows
+    .map(([label, value, note]) => {
+      const pad = ' '.repeat(valueW - plainLength(value))
+      const noteStr = note ? `${pad}   ${dim(note)}` : ''
+      return `    ${dim(label.padEnd(labelW))}  ${value}${noteStr}`
+    })
+    .join('\n')
+}
+
+export const heading = (title) => `  ${paint(['bold', 'cyan'], '◆')} ${bold(title)}`
+
+export function banner(title, rows) {
+  return `\n${heading(title)}\n\n${columns(rows)}\n`
+}
+
+// The identity → beings tree — the ground's real shape (beings live under
+// identities, never flat). `identities` may lag `beings` (a being can outlive
+// its vault's listing), so the tree is keyed by the union of both.
+export function identityTree(identities, beings, selected) {
+  const byId = new Map(identities.map((i) => [i, []]))
+  for (const b of beings) {
+    if (!byId.has(b.identity)) byId.set(b.identity, [])
+    byId.get(b.identity).push(b)
+  }
+  const nameW = Math.max(0, ...beings.map((b) => b.name.length))
+  const lines = []
+  for (const [id, bs] of byId) {
+    const marks = [
+      id === selected ? cyan(' ← selected') : '',
+      identities.includes(id) ? '' : dim(' (no vault)')
+    ].join('')
+    lines.push(`    ${bold(id)}${marks}`)
+    if (!bs.length) lines.push(dim('      · no beings'))
+    for (const b of bs)
+      lines.push(`      ${b.name.padEnd(nameW)}  ${dim(`${b.kind} · ${b.state}`)}`)
+  }
+  return lines.join('\n')
+}