amorphous-cli 0.1.6 → 0.1.8

package/README.md

@@ -1,6 +1,6 @@
 # amorphous-cli
 
-Build abstracts on Amorphous. An abstract can be anything. Your own agent builds it. Other people open it and write to it.
+Make whatever you want, yourself, with your own agent, or with others. And whatever you want can be private, public, or even have users.
 
 ```bash
 npx amorphous-cli@latest setup

package/hooks/session-start.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Session-start refresh. Claude Code waits for this and rescans skills when
+ * asked. Cursor does not wait; it can still take additional_context if it
+ * reads the output.
+ *
+ * setup --quiet exists from amorphous-cli 0.1.7. An older latest would
+ * install the previous skill, so this exits before calling it.
+ */
+import { spawnSync } from 'node:child_process'
+
+const MIN = [0, 1, 7]
+const target = process.argv[2] === 'cursor' ? 'cursor' : 'claude'
+const win = process.platform === 'win32'
+const npm = win ? 'npm.cmd' : 'npm'
+const npx = win ? 'npx.cmd' : 'npx'
+const spawnOpts = { encoding: 'utf8', shell: win, stdio: ['ignore', 'pipe', 'ignore'] }
+
+function parts(version) {
+  const core = String(version).trim().split('-')[0]
+  return core.split('.').map((n) => Number.parseInt(n, 10))
+}
+
+function atLeast(version, min) {
+  const got = parts(version)
+  if (got.some((n) => Number.isNaN(n))) return false
+  const length = Math.max(got.length, min.length)
+  for (let i = 0; i < length; i++) {
+    const a = got[i] || 0
+    const b = min[i] || 0
+    if (a > b) return true
+    if (a < b) return false
+  }
+  return true
+}
+
+const view = spawnSync(npm, ['view', 'amorphous-cli', 'version'], { ...spawnOpts, timeout: 8_000 })
+if (view.status !== 0 || !atLeast(view.stdout, MIN)) process.exit(0)
+
+const run = spawnSync(npx, ['--yes', 'amorphous-cli@latest', 'setup', '--quiet'], {
+  ...spawnOpts,
+  timeout: 20_000,
+})
+const updated = run.status === 0 && String(run.stdout || '').trim() === 'updated'
+if (!updated) process.exit(0)
+
+if (target === 'cursor') {
+  process.stdout.write(
+    `${JSON.stringify({
+      additional_context:
+        'The Amorphous skill on this machine was just updated. Read ~/.agents/skills/amorphous/SKILL.md and follow it. Invoke the CLI as npx amorphous-cli@latest.',
+    })}\n`,
+  )
+} else {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'SessionStart', reloadSkills: true },
+    })}\n`,
+  )
+}

package/lib/agent-contract.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 import { CLI_VERSION } from './version.mjs'
 
-export const CONTRACT_VERSION = 2
+export const CONTRACT_VERSION = 10
 
 const skillRoot = join(dirname(fileURLToPath(import.meta.url)), '../skill/amorphous')
 

package/lib/agent-contract.test.mjs

@@ -16,7 +16,10 @@ test('setup copies the skill, and an edited contract is left alone', () => {
   const home = mkdtempSync(join(tmpdir(), 'amorphous-skill-'))
   const dirs = installUserSkill(home)
   assert.equal(dirs.length, 2)
-  assert.match(readFileSync(join(dirs[0], 'SKILL.md'), 'utf8'), /build abstracts/)
+  assert.match(
+    readFileSync(join(dirs[0], 'SKILL.md'), 'utf8'),
+    /Make whatever you want, yourself, with your own agent, or with others\./,
+  )
   assert.match(readFileSync(join(dirs[1], 'assets/app.js'), 'utf8'), /amorphous\.me/)
   assert.equal(readFileSync(join(dirs[0], '.amorphous-version'), 'utf8'), `${CLI_VERSION}\n`)
   assert.equal(readFileSync(join(dirs[1], '.amorphous-version'), 'utf8'), `${CLI_VERSION}\n`)

package/lib/agent-hooks.mjs

@@ -0,0 +1,134 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { homedir } from 'node:os'
+
+function hasOurCommand(command, home) {
+  return typeof command === 'string' && command.includes(sessionStartScriptPath(home))
+}
+
+function scriptSource() {
+  return readFileSync(join(dirname(fileURLToPath(import.meta.url)), '../hooks/session-start.mjs'))
+}
+
+export function sessionStartScriptPath(home = homedir()) {
+  return join(home, '.config', 'amorphous', 'session-start.mjs')
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null
+    return undefined
+  }
+}
+
+function writeJson(path, data) {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`)
+}
+
+function commandFor(home, target) {
+  return `node ${JSON.stringify(sessionStartScriptPath(home))} ${target}`
+}
+
+function installScript(home) {
+  const dest = sessionStartScriptPath(home)
+  const next = scriptSource()
+  let prev
+  try {
+    prev = readFileSync(dest)
+  } catch {
+    prev = null
+  }
+  if (prev && prev.equals(next)) return false
+  mkdirSync(dirname(dest), { recursive: true })
+  writeFileSync(dest, next, { mode: 0o755 })
+  try {
+    chmodSync(dest, 0o755)
+  } catch {
+    /* the copy is still runnable via node */
+  }
+  return true
+}
+
+function claudeHook(home) {
+  return {
+    matcher: 'startup|resume',
+    hooks: [{ type: 'command', command: commandFor(home, 'claude') }],
+  }
+}
+
+function ensureClaude(home) {
+  const path = join(home, '.claude', 'settings.json')
+  const current = readJson(path)
+  if (current === undefined) return false
+  const doc = current && typeof current === 'object' && !Array.isArray(current) ? current : {}
+  const hooks = doc.hooks && typeof doc.hooks === 'object' ? doc.hooks : {}
+  const session = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : []
+  const command = commandFor(home, 'claude')
+  const exists = session.some(
+    (entry) =>
+      Array.isArray(entry?.hooks) &&
+      entry.hooks.some((hook) => hasOurCommand(hook?.command, home)),
+  )
+  if (exists) {
+    let changed = false
+    const next = session.map((entry) => {
+      if (!Array.isArray(entry?.hooks)) return entry
+      const hooks = entry.hooks.map((hook) => {
+        if (!hasOurCommand(hook?.command, home)) return hook
+        if (hook.command === command) return hook
+        changed = true
+        return { ...hook, command }
+      })
+      const onlyOurs = hooks.every((hook) => hasOurCommand(hook?.command, home))
+      const matcher = onlyOurs ? 'startup|resume' : entry.matcher
+      if (matcher !== entry.matcher) changed = true
+      return { ...entry, matcher, hooks }
+    })
+    if (!changed) return false
+    writeJson(path, { ...doc, hooks: { ...hooks, SessionStart: next } })
+    return true
+  }
+  writeJson(path, {
+    ...doc,
+    hooks: { ...hooks, SessionStart: [...session, claudeHook(home)] },
+  })
+  return true
+}
+
+function ensureCursor(home) {
+  const path = join(home, '.cursor', 'hooks.json')
+  const current = readJson(path)
+  if (current === undefined) return false
+  const doc = current && typeof current === 'object' && !Array.isArray(current) ? current : {}
+  const hooks = doc.hooks && typeof doc.hooks === 'object' ? doc.hooks : {}
+  const session = Array.isArray(hooks.sessionStart) ? hooks.sessionStart : []
+  const command = commandFor(home, 'cursor')
+  const index = session.findIndex(
+    (hook) => hasOurCommand(hook?.command, home),
+  )
+  if (index >= 0) {
+    if (session[index].command === command) return false
+    const next = session.slice()
+    next[index] = { ...session[index], command }
+    writeJson(path, { ...doc, version: doc.version ?? 1, hooks: { ...hooks, sessionStart: next } })
+    return true
+  }
+  writeJson(path, {
+    ...doc,
+    version: doc.version ?? 1,
+    hooks: { ...hooks, sessionStart: [...session, { command }] },
+  })
+  return true
+}
+
+/** Install the Claude and Cursor session hooks. Leave a broken settings file untouched. */
+export function ensureSessionHooks(home = homedir()) {
+  const script = installScript(home)
+  const claude = ensureClaude(home)
+  const cursor = ensureCursor(home)
+  return script || claude || cursor
+}

package/lib/agent-hooks.test.mjs

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import test from 'node:test'
+import { ensureSessionHooks, sessionStartScriptPath } from './agent-hooks.mjs'
+
+test('session hooks merge and stay idempotent', () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-hooks-'))
+  mkdirSync(join(home, '.claude'), { recursive: true })
+  writeFileSync(
+    join(home, '.claude', 'settings.json'),
+    `${JSON.stringify({ permissions: { allow: ['Bash'] } }, null, 2)}\n`,
+  )
+  mkdirSync(join(home, '.cursor'), { recursive: true })
+  writeFileSync(
+    join(home, '.cursor', 'hooks.json'),
+    `${JSON.stringify({ version: 1, hooks: { stop: [{ command: 'echo keep' }] } }, null, 2)}\n`,
+  )
+
+  assert.equal(ensureSessionHooks(home), true)
+  assert.equal(ensureSessionHooks(home), false)
+
+  const claude = JSON.parse(readFileSync(join(home, '.claude', 'settings.json'), 'utf8'))
+  assert.deepEqual(claude.permissions, { allow: ['Bash'] })
+  assert.equal(claude.hooks.SessionStart.length, 1)
+  assert.equal(claude.hooks.SessionStart[0].matcher, 'startup|resume')
+  assert.equal(
+    claude.hooks.SessionStart[0].hooks[0].command,
+    `node ${JSON.stringify(sessionStartScriptPath(home))} claude`,
+  )
+
+  const cursor = JSON.parse(readFileSync(join(home, '.cursor', 'hooks.json'), 'utf8'))
+  assert.deepEqual(cursor.hooks.stop, [{ command: 'echo keep' }])
+  assert.equal(cursor.hooks.sessionStart.length, 1)
+  assert.match(readFileSync(sessionStartScriptPath(home), 'utf8'), /amorphous-cli@latest', 'setup', '--quiet'/)
+})
+
+test('broken settings are left untouched', () => {
+  const home = mkdtempSync(join(tmpdir(), 'amorphous-hooks-'))
+  mkdirSync(join(home, '.claude'), { recursive: true })
+  writeFileSync(join(home, '.claude', 'settings.json'), '{')
+  assert.equal(ensureSessionHooks(home), true)
+  assert.equal(readFileSync(join(home, '.claude', 'settings.json'), 'utf8'), '{')
+  assert.equal(ensureSessionHooks(home), false)
+})

package/lib/api.mjs

@@ -2,24 +2,24 @@ import { cliAppFetchOrigin, cliAppHostHeader } from './config.mjs'
 import { ensureFreshSession } from './session.mjs'
 
 const FRIENDLY = {
-  'You already own 2 abstracts': 'You already own 2 abstracts. Run: amorphous list',
-  'This abstract already has 8 people': 'This abstract already has 8 people. Run: amorphous people',
-  'User not found': 'No account with that email yet. They sign in once, then run: amorphous invite <email> use',
-  'Grant failed': 'Could not invite. Run: amorphous people',
-  'Cannot revoke owner': "You can't remove the owner. Run: amorphous people",
-  'Cannot remove yourself': "You can't remove yourself. Run: amorphous people",
-  'Collection not found': 'Folder not found. Run: amorphous folder list',
-  Forbidden: "You don't have access. Run: amorphous list",
-  'Not Found': 'Not found. Run: amorphous list',
-  'Owner required': 'Only the owner can do that. Run: amorphous people',
-  'id required': 'Missing id. Run: amorphous list',
-  'userId required': 'Pass an email or id. Run: amorphous people',
-  'Invalid body': 'Invalid request. Run: amorphous pull',
-  'Name required': 'Name required. Run: amorphous rename --name <name>',
-  'Create failed': 'Could not create the abstract. Run: amorphous list',
-  'Publish failed': 'Could not publish. Run: amorphous push',
-  'File too large': 'That file is too large. Run: amorphous pull',
-  'Not logged in. Run: amorphous login <email>': 'Not signed in. Run: amorphous login',
+  'You already own 2 abstracts': 'You already own 2 abstracts. Run: npx amorphous-cli@latest list',
+  'This abstract already has 8 people': 'This abstract already has 8 people. Run: npx amorphous-cli@latest people',
+  'User not found': 'No account with that email yet.',
+  'Grant failed': 'Could not invite. Run: npx amorphous-cli@latest people',
+  'Cannot revoke owner': "You can't remove the owner. Run: npx amorphous-cli@latest people",
+  'Cannot remove yourself': "You can't remove yourself. Run: npx amorphous-cli@latest people",
+  'Collection not found': 'Folder not found. Run: npx amorphous-cli@latest folder list',
+  Forbidden: "You don't have access. Run: npx amorphous-cli@latest list",
+  'Not Found': 'Not found. Run: npx amorphous-cli@latest list',
+  'Owner required': 'Only the owner can do that. Run: npx amorphous-cli@latest people',
+  'id required': 'Missing id. Run: npx amorphous-cli@latest list',
+  'userId required': 'Pass an email or id. Run: npx amorphous-cli@latest people',
+  'Invalid body': 'Invalid request. Run: npx amorphous-cli@latest pull',
+  'Name required': 'Name required. Run: npx amorphous-cli@latest rename --name <name>',
+  'Create failed': 'Could not create the abstract. Run: npx amorphous-cli@latest list',
+  'Publish failed': 'Could not publish. Run: npx amorphous-cli@latest push',
+  'File too large': 'That file is too large. Run: npx amorphous-cli@latest pull',
+  'Not logged in. Run: amorphous login <email>': 'Not signed in. Run: npx amorphous-cli@latest login',
 }
 
 export function friendlyMessage(raw) {

package/lib/commands.mjs

@@ -1,8 +1,13 @@
 import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { installUserSkill, syncProjectContract, writeStarter } from './agent-contract.mjs'
+import { ensureSessionHooks } from './agent-hooks.mjs'
+import { shouldRefreshSkill } from './update-check.mjs'
+import { CLI_VERSION } from './version.mjs'
+import { homedir } from 'node:os'
 import { apiFetch } from './api.mjs'
 import { abstractsOrigin, appOrigin, projectMetaPath } from './config.mjs'
 import { recordsFromLocal, readProjectFiles, writeProjectFiles } from './files.mjs'
+import { startServe } from './serve.mjs'
 import { ALIASES, printHelp, wantsHelp } from './help.mjs'
 import { loginWithBrowser, loginWithMagicLink } from './login.mjs'
 
@@ -18,6 +23,8 @@ const BOOL_FLAGS = new Set([
   'member',
   'open',
   'closed',
+  'quiet',
+  'data',
 ])
 
 function parseFlags(args) {
@@ -70,7 +77,7 @@ function writeMeta(cwd, abstractId) {
 function requireMeta(cwd) {
   const meta = readMeta(cwd)
   if (!meta?.abstractId) {
-    throw new Error('No .amorphous.json here. Run amorphous create first.')
+    throw new Error('No .amorphous.json here. Run npx amorphous-cli@latest create first.')
   }
   return meta.abstractId
 }
@@ -183,9 +190,15 @@ async function cmdMcp(rest) {
 async function cmdSetup(rest) {
   const { flags } = parseFlags(rest)
   if (flags.help) return printHelp('setup')
-  const dirs = installUserSkill()
+  const refresh = shouldRefreshSkill(homedir(), CLI_VERSION)
+  const dirs = refresh ? installUserSkill() : undefined
+  const hooks = ensureSessionHooks()
+  if (flags.quiet) {
+    if (refresh || hooks) console.log('updated')
+    return
+  }
   console.log('Installed the Amorphous skill.')
-  for (const dir of dirs) console.log(dir)
+  for (const dir of dirs ?? installUserSkill()) console.log(dir)
 }
 
 async function cmdCreate(cwd, rest) {
@@ -247,11 +260,14 @@ async function cmdInvite(cwd, rest) {
   const { access, rest: absArgs } = takeAccess(flags, afterEmail)
   const id = await resolveAbstractId(cwd, flags, absArgs)
   const role = parseAccess(access)
-  await apiFetch(`/api/abstracts/${id}/grant`, {
+  const result = await apiFetch(`/api/abstracts/${id}/grant`, {
     method: 'POST',
     body: JSON.stringify({ email, role }),
   })
-  console.log('Invited.')
+  const url = String(result.url || '')
+  if (!url) throw new Error('Could not invite.')
+  if (jsonMode(flags)) printJson({ email, access: role === 'user' ? 'view' : role === 'editor' ? 'edit' : role, url })
+  else console.log(url)
 }
 
 async function cmdRemove(cwd, rest) {
@@ -316,20 +332,45 @@ async function cmdPush(cwd, rest) {
   const { flags } = parseFlags(rest)
   if (flags.help) return printHelp('push')
   const id = requireMeta(cwd)
-  const localRecords = recordsFromLocal(cwd)
-  const { refused } = await apiFetch(`/api/abstracts/${id}/records`, {
-    method: 'POST',
-    body: JSON.stringify({ records: localRecords }),
-  })
-  if (refused?.length) {
-    console.error(`Skipped (already live): ${refused.join(', ')}. Run: amorphous pull`)
+  if (flags.data) {
+    const localRecords = recordsFromLocal(cwd)
+    const { refused } = await apiFetch(`/api/abstracts/${id}/records`, {
+      method: 'POST',
+      body: JSON.stringify({ records: localRecords }),
+    })
+    if (refused?.length) {
+      console.error(`Skipped (already live): ${refused.join(', ')}. Run: npx amorphous-cli@latest pull`)
+    }
   }
   const { html, css, js } = readProjectFiles(cwd)
   await apiFetch(`/api/abstracts/${id}/push`, {
     method: 'POST',
     body: JSON.stringify({ html, css, js }),
   })
-  console.log('Pushed.')
+  console.log(flags.data ? 'Pushed source and records.' : 'Pushed source.')
+}
+
+async function cmdServe(cwd, rest) {
+  const { flags } = parseFlags(rest)
+  if (flags.help) return printHelp('serve')
+  const id = requireMeta(cwd)
+  const port = flags.port ? Number(flags.port) : 0
+  if (flags.port && (!Number.isInteger(port) || port < 1 || port > 65535)) {
+    throw new Error('Use --port <number>.')
+  }
+  const running = await startServe({
+    cwd,
+    abstractId: id,
+    port,
+    json: jsonMode(flags),
+  })
+  await new Promise((resolve) => {
+    const stop = () => {
+      running.close().then(resolve, resolve)
+    }
+    process.once('SIGINT', stop)
+    process.once('SIGTERM', stop)
+  })
 }
 
 function urlsFor(id) {
@@ -615,7 +656,7 @@ async function cmdFolderInvite(rest) {
     method: 'POST',
     body: JSON.stringify({ email }),
   })
-  console.log('Invited.')
+  console.log('Added.')
 }
 
 async function cmdFolderRemove(rest) {
@@ -690,7 +731,7 @@ async function cmdSpaceMember(rest) {
     method: 'POST',
     body: JSON.stringify({ email, role: flags.role || 'member' }),
   })
-  console.log('Invited.')
+  console.log('Added.')
 }
 
 export async function runCommand(argv, cwd = process.cwd()) {
@@ -723,6 +764,8 @@ export async function runCommand(argv, cwd = process.cwd()) {
       return cmdOpen(cwd, rest)
     case 'preview':
       return cmdPreview(cwd, rest)
+    case 'serve':
+      return cmdServe(cwd, rest)
     case 'publish':
       return cmdPublish(cwd, rest)
     case 'live':
@@ -756,6 +799,6 @@ export async function runCommand(argv, cwd = process.cwd()) {
       if (rest[0] === 'member') return cmdSpaceMember(rest.slice(1))
       throw new Error('Use folder instead.')
     default:
-      throw new Error(`Unknown command “${raw}”. Run amorphous --help.`)
+      throw new Error(`Unknown command “${raw}”. Run npx amorphous-cli@latest --help.`)
   }
 }

package/lib/config.mjs

@@ -72,6 +72,36 @@ export function abstractsOrigin() {
   return process.env.ABSTRACTS_ORIGIN || HOSTED.abstractsOrigin
 }
 
+/** Local Herd HTTPS: hit Nuxt on loopback with the abstracts Host header (no TLS). */
+export function cliAbstractsFetchOrigin() {
+  if (process.env.AMORPHOUS_CLI_ABSTRACTS_URL) {
+    return process.env.AMORPHOUS_CLI_ABSTRACTS_URL.replace(/\/$/, '')
+  }
+  const origin = abstractsOrigin()
+  try {
+    const u = new URL(origin)
+    if (u.protocol === 'https:' && (u.hostname.endsWith('.test') || u.hostname === 'localhost')) {
+      const port = process.env.AMORPHOUS_DEV_PORT || '3847'
+      return `http://127.0.0.1:${port}`
+    }
+  } catch {
+    /* ignore */
+  }
+  return origin.replace(/\/$/, '')
+}
+
+export function cliAbstractsHostHeader() {
+  const origin = abstractsOrigin()
+  const fetchOrigin = cliAbstractsFetchOrigin()
+  if (!fetchOrigin.startsWith('http://127.0.0.1')) return {}
+  try {
+    const u = new URL(origin)
+    return { Host: u.host }
+  } catch {
+    return {}
+  }
+}
+
 export function supabaseUrl() {
   return process.env.SUPABASE_URL || HOSTED.supabaseUrl
 }

package/lib/files.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -47,4 +48,45 @@ export function recordsFromLocal(cwd) {
   ]
 }
 
+export function writeLocalRecords(cwd, rows) {
+  writeNdjson(
+    join(cwd, 'data.ndjson'),
+    rows.filter((r) => r.visibility !== 'private'),
+  )
+  writeNdjson(
+    join(cwd, 'private.ndjson'),
+    rows.filter((r) => r.visibility === 'private'),
+  )
+}
+
+export function insertLocalRecord(cwd, row) {
+  const body = { ...(row && typeof row === 'object' ? row : {}) }
+  if (body.visibility && body.visibility !== 'shared' && body.visibility !== 'private') {
+    return { status: 400, message: 'Invalid visibility' }
+  }
+  body.visibility = body.visibility === 'private' ? 'private' : 'shared'
+  if (!body.id) body.id = randomUUID()
+  const rows = recordsFromLocal(cwd)
+  if (rows.some((r) => r.id === body.id)) return { status: 409, message: 'Conflict' }
+  rows.push(body)
+  writeLocalRecords(cwd, rows)
+  return { status: 200, row: body }
+}
+
+export function replaceLocalRecord(cwd, id, row) {
+  const rows = recordsFromLocal(cwd)
+  const index = rows.findIndex((r) => r.id === id)
+  if (index < 0) return { status: 404, message: 'Not Found' }
+  const existing = rows[index]
+  const next = {
+    ...(existing && typeof existing === 'object' ? existing : {}),
+    ...(row && typeof row === 'object' ? row : {}),
+    id,
+    visibility: existing.visibility,
+  }
+  rows[index] = next
+  writeLocalRecords(cwd, rows)
+  return { status: 200, row: next }
+}
+
 export { FILES }

package/lib/help.mjs

@@ -7,12 +7,13 @@ export const ROOT_HELP = `Amorphous
   create                        New abstract
   open [abstract]               Open URL
   preview [abstract]            Preview URL (draft)
+  serve                         Serve this folder locally
   pull                          Pull draft and records to this folder
   push                          Push local files
   publish [--live]              Publish a version; --live is Go live
   live [abstract]               Make a version live
   visibility anyone|members     Anyone can view / Members only
-  invite <email>                Invite
+  invite <email>                Print the link to give them
   remove <email|id>             Remove
   people [abstract]             People
   tag / untag                   Tag
@@ -28,13 +29,14 @@ export const ROOT_HELP = `Amorphous
   folder people                 People on a folder
   rename --name                 Rename
 
-Run amorphous <command> --help for flags. Pass --json where you need machine output.
+Run npx amorphous-cli@latest <command> --help for flags. Pass --json where you need machine output.
 `
 
 export const COMMAND_HELP = {
   setup: `setup
 
-Install the Amorphous skill for Claude Code, Cursor, and Codex.`,
+Install the Amorphous skill for Claude Code, Cursor, and Codex.
+Claude Code and Cursor get a session hook that refreshes it from the current CLI.`,
 
   login: `login [--email <email>] [--code <code>]
 
@@ -63,13 +65,19 @@ Print the Open URL.`,
 
 Print the Preview URL (draft).`,
 
+  serve: `serve [--port <n>] [--json]
+
+Serve this folder on 127.0.0.1 and reload when index.html, styles.css, or app.js changes.
+Records start local, in this folder. The page can switch to prod, which reads and writes the abstract's records.`,
+
   pull: `pull
 
 Pull the draft and records into this directory.`,
 
-  push: `push
+  push: `push [--data]
 
-Push local index.html, styles.css, app.js, and records.`,
+Push local index.html, styles.css, and app.js.
+--data also merges records from this folder. A record changed both here and on the abstract is refused.`,
 
   publish: `publish [--live]
 
@@ -83,9 +91,9 @@ Make this the live version. Uses the latest published version if you omit --vers
 
 Anyone can view, or Members only. Uses the live version if you omit --version.`,
 
-  invite: `invite <email> [view|use|edit] [--abstract <id|name>]
+  invite: `invite <email> [view|use|edit] [--abstract <id|name>] [--json]
 
-Invite someone by email. Access: view, use (Can use), or edit. Default: view.`,
+Save an invite for this email and print the link to give them. Access: view, use, or edit. Default: view.`,
 
   remove: `remove <email|id> [--abstract <id|name>]
 
@@ -136,7 +144,7 @@ Suggest folder from the name. Default is a suggestion only. --apply uses it.`,
   folder remove <folder> <email|id>
   folder people <folder> [--json]
 
-New folder, move a folder, or invite people to a folder.`,
+New folder, or move a folder. folder invite adds someone who already has an account. It does not send an email.`,
 
   rename: `rename [abstract] --name <name>
 

package/lib/login.mjs

@@ -70,7 +70,7 @@ async function loginViaMailpit(supabase, email, redirectTo, sinceMs) {
 async function readCode(email) {
   if (!process.stdin.isTTY) {
     throw new Error(
-      `Code sent to ${email}. Read it from that inbox, then run: amorphous login ${email} --code <code>`,
+      `Code sent to ${email}. Read it from that inbox, then run: npx amorphous-cli@latest login ${email} --code <code>`,
     )
   }
   const rl = createInterface({ input: process.stdin, output: process.stderr })