amorphous-cli 0.1.13 → 0.3.0

package/lib/commands.mjs

@@ -1,15 +1,34 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, readdirSync, lstatSync, openSync, closeSync, mkdirSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
 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 { appOrigin, projectMetaPath } from './config.mjs'
+import { urlsFromDiscovery } from './app-origins.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'
+import { ensureFreshSession } from './session.mjs'
+import {
+  activateGuideIdentity,
+  guideBodyHash,
+  guidePaths,
+  ensureGuideFilesIgnored,
+  materializeGuide,
+  readGuideSyncState,
+  writeGuideSyncState,
+} from './agent-guides-files.mjs'
+
+const COMBINED_GUIDE_MAX_BYTES = 48 * 1024
+const GUIDE_MAX_BYTES = 32 * 1024
+const QUARANTINE_USER_IDS = [
+  'ffffffff-ffff-4fff-8fff-ffffffffffff',
+  'eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee',
+]
 
 const BOOL_FLAGS = new Set([
   'json',
@@ -80,6 +99,18 @@ function writeMeta(cwd, abstractId) {
   writeFileSync(projectMetaPath(cwd), JSON.stringify({ abstractId }, null, 2) + '\n')
 }
 
+export function writeRecipeFiles(cwd, source) {
+  const files = [['index.html', source?.html], ['styles.css', source?.css], ['app.js', source?.js]]
+  if (files.some(([, content]) => typeof content !== 'string')) throw new Error('Recipe response did not include source files.')
+  const paths = files.map(([name]) => join(cwd, name))
+  if ([...paths, join(cwd, 'data.ndjson'), join(cwd, 'private.ndjson')].some(existsSync)) {
+    throw new Error('Recipe creation needs an empty source folder so it can write the generated files safely.')
+  }
+  for (let index = 0; index < files.length; index++) writeFileSync(paths[index], files[index][1])
+  writeFileSync(join(cwd, 'data.ndjson'), '')
+  writeFileSync(join(cwd, 'private.ndjson'), '')
+}
+
 function requireMeta(cwd) {
   const meta = readMeta(cwd)
   if (!meta?.abstractId) {
@@ -88,12 +119,38 @@ function requireMeta(cwd) {
   return meta.abstractId
 }
 
-async function resolveAbstractId(cwd, flags, positional) {
+async function initializeEmptyAbstractGuide(cwd, abstractId) {
+  ensureGuideFilesIgnored(cwd)
+  const path = join(cwd, 'agent.md')
+  try {
+    // Preserve anything already at this path, including a symlink or directory.
+    lstatSync(path)
+    return false
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  const fd = openSync(path, 'wx', 0o600)
+  closeSync(fd)
+  const { userId } = await guideSession()
+  const paths = guidePaths(cwd, abstractId, userId)
+  if (!existsSync(paths.privateGuide) && !existsSync(paths.activeIdentity)) {
+    const internal = join(cwd, '.amorphous-guides')
+    try { mkdirSync(internal, { mode: 0o700 }) } catch (error) { if (error?.code !== 'EEXIST') throw error }
+    if (lstatSync(internal).isSymbolicLink()) throw new Error('Unsafe agent-guide state directory.')
+    const marker = JSON.stringify({ schemaVersion: 1, abstractId: paths.abstractId, userId: paths.userId }) + '\n'
+    const stateFd = openSync(paths.activeIdentity, 'wx', 0o600)
+    try { writeFileSync(stateFd, marker) } finally { closeSync(stateFd) }
+    materializeGuide({ projectRoot: cwd, abstractId, userId, kind: 'abstract', body: '', revision: 0 })
+  }
+  return true
+}
+
+async function resolveAbstractId(cwd, flags, positional, request = apiFetch) {
   if (flags.abstract) return flags.abstract
   if (positional[0]) {
     const token = positional[0]
     if (/^[0-9a-f-]{36}$/i.test(token)) return token
-    const data = await apiFetch('/api/abstracts?view=all')
+    const data = await request('/api/abstracts?view=all')
     const hit = (data.abstracts || []).find(
       (a) => a.name.toLowerCase() === token.toLowerCase(),
     )
@@ -107,6 +164,176 @@ async function resolveAbstractId(cwd, flags, positional) {
   }
 }
 
+function sessionUserId(accessToken) {
+  try {
+    const payload = accessToken.split('.')[1]
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))
+    if (typeof decoded.sub !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(decoded.sub)) throw new Error()
+    return decoded.sub.toLowerCase()
+  } catch {
+    throw new Error('The signed-in Amorphous session has no valid user identity. Run amorphous-cli login.')
+  }
+}
+
+function validateGuideResponse(value, label) {
+  if (!value || typeof value !== 'object' || typeof value.body !== 'string' ||
+    !Number.isSafeInteger(value.revision) || value.revision < 0) {
+    throw new Error(`The ${label} response is unavailable or invalid.`)
+  }
+  if (Buffer.byteLength(value.body, 'utf8') > 32 * 1024) {
+    throw new Error(`The ${label} exceeds the 32 KiB UTF-8 limit. Neither guide was loaded.`)
+  }
+  return value
+}
+
+async function guideSession() {
+  const session = await ensureFreshSession()
+  return { accessToken: session.access_token, userId: sessionUserId(session.access_token) }
+}
+
+function quarantineActiveGuides(cwd, fallbackAbstractId) {
+  const markerPath = join(cwd, '.amorphous-guides', 'active.json')
+  let marker = null
+  try {
+    const info = lstatSync(markerPath)
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error('Unsafe active guide identity file; local guide bytes were not moved.')
+    try { marker = JSON.parse(readFileSync(markerPath, 'utf8')) } catch { marker = null }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  const validUuid = (value) => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+  const abstractId = validUuid(marker?.abstractId)
+    ? marker.abstractId
+    : validUuid(fallbackAbstractId)
+      ? fallbackAbstractId
+      : '00000000-0000-4000-8000-000000000000'
+  const markedUser = marker?.userId
+  let switched
+  let lastError
+  for (const userId of QUARANTINE_USER_IDS) {
+    if (userId === markedUser) continue
+    try {
+      switched = activateGuideIdentity(cwd, abstractId, userId)
+      break
+    } catch (error) { lastError = error }
+  }
+  if (!switched) throw lastError || new Error('Could not safely quarantine active guide files.')
+  try {
+    const info = lstatSync(markerPath)
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error('Unsafe active guide identity file after recovery.')
+    unlinkSync(markerPath)
+  } catch (error) { if (error?.code !== 'ENOENT') throw error }
+}
+
+function enforceActiveGuideCaps(cwd, abstractId, userId) {
+  const paths = guidePaths(cwd, abstractId, userId)
+  const files = [paths.abstractGuide, paths.privateGuide]
+  let combinedBytes = 0
+  for (const path of files) {
+    const info = lstatSync(path)
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error('Active guide files must be regular non-symlink files.')
+    if (info.size > GUIDE_MAX_BYTES) {
+      throw new Error('An active guide exceeds the 32 KiB UTF-8 context limit. Neither guide was loaded; local text is preserved without truncation.')
+    }
+    combinedBytes += info.size
+  }
+  if (combinedBytes > COMBINED_GUIDE_MAX_BYTES) {
+    throw new Error('Active guide files exceed the combined 48 KiB UTF-8 context limit. Neither guide was loaded; local text is preserved without truncation.')
+  }
+}
+
+async function cmdContext(cwd, rest) {
+  const { flags, positional } = parseFlags(rest)
+  if (flags.help) return printHelp('context')
+  let authorizationComplete = false
+  let id
+  try {
+    const { accessToken, userId } = await guideSession()
+    const request = (path) => apiFetch(path, { accessToken })
+    id = await resolveAbstractId(cwd, flags, positional, request)
+    const [abstractGuide, privateGuide] = await Promise.all([
+      request(`/api/abstracts/${id}/agent-guide`).then((value) => validateGuideResponse(value, 'abstract guide')),
+      request(`/api/abstracts/${id}/private-agent-guide`).then((value) => validateGuideResponse(value, 'private guide')),
+    ])
+    authorizationComplete = true
+    const combinedBytes = Buffer.byteLength(abstractGuide.body, 'utf8') + Buffer.byteLength(privateGuide.body, 'utf8')
+    if (combinedBytes > COMBINED_GUIDE_MAX_BYTES) {
+      throw new Error('Agent guides exceed the combined 48 KiB UTF-8 context limit. Neither guide was loaded; reduce their size and run amorphous-cli context again.')
+    }
+    const identity = activateGuideIdentity(cwd, id, userId)
+    if (!identity.privateSafeToLoad) {
+      throw new Error('Guide identity is uncertain. Existing local files were preserved in recovery and neither guide was loaded; confirm the account and run amorphous-cli context again.')
+    }
+
+    const documents = [
+      { kind: 'abstract', guide: abstractGuide },
+      { kind: 'private', guide: privateGuide },
+    ]
+    const outcomes = []
+    for (const { kind, guide } of documents) {
+      const outcome = materializeGuide({ projectRoot: cwd, abstractId: id, userId, kind, body: guide.body, revision: guide.revision })
+      if (outcome.status === 'identity-uncertain') {
+        throw new Error('Guide identity changed during context loading. Do not use either local guide; confirm the account and run amorphous-cli context again.')
+      }
+      outcomes.push(outcome)
+    }
+    enforceActiveGuideCaps(cwd, id, userId)
+    const conflicts = outcomes.filter((outcome) => outcome.status === 'conflict')
+    if (conflicts.length) {
+      const paths = conflicts.map((item) => item.conflictPath).join(', ')
+      throw new Error(`An agent guide changed locally and remotely. Both copies were preserved; review the ignored conflict file${conflicts.length > 1 ? 's' : ''}: ${paths}. Resolve before asking the agent to use guide context.`)
+    }
+    console.log(`Loaded guide context for ${id} (abstract revision ${abstractGuide.revision}; private revision ${privateGuide.revision}).`)
+    console.log('Context does not fetch source; source release/version is separate from these guide revisions.')
+    console.log('The private guide is supplied to this local agent process and cannot be recalled after download.')
+    console.log('Read agent.md, then private-agent.md before working on the abstract.')
+  } catch (error) {
+    if (!authorizationComplete) {
+      try { quarantineActiveGuides(cwd, id) } catch (quarantineError) {
+        throw new Error(`${error.message} Active guide files could not be safely quarantined: ${quarantineError.message}`)
+      }
+    }
+    throw error
+  }
+}
+
+async function cmdGuide(cwd, rest) {
+  const { flags, positional } = parseFlags(rest)
+  if (flags.help || positional[0] !== 'save') return printHelp('guide')
+  const kind = positional[1]
+  if (!['abstract', 'private'].includes(kind)) throw new Error('Use: amorphous-cli guide save <abstract|private> [abstract].')
+  const abstractToken = positional[2]
+  const { accessToken, userId } = await guideSession()
+  const request = (path, options) => apiFetch(path, { ...options, accessToken })
+  const id = await resolveAbstractId(cwd, flags, abstractToken ? [abstractToken] : [], request)
+  const endpoint = kind === 'abstract' ? 'agent-guide' : 'private-agent-guide'
+  const current = validateGuideResponse(await request(`/api/abstracts/${id}/${endpoint}`), `${kind} guide`)
+  const paths = guidePaths(cwd, id, userId)
+  const identity = activateGuideIdentity(cwd, id, userId)
+  if (!identity.privateSafeToLoad) throw new Error('Guide identity is uncertain; preserved local files are not eligible for saving. Run context after confirming the signed-in account.')
+  const state = readGuideSyncState(cwd, id, userId)
+  const base = state?.guides?.[kind]
+  if (!base) throw new Error('No saved guide revision is available. Run amorphous-cli context first.')
+  if (base.revision !== current.revision) throw new Error('The server guide changed since context was loaded. Run amorphous-cli context, resolve any conflict, then save again.')
+  const path = kind === 'abstract' ? paths.abstractGuide : paths.privateGuide
+  const file = lstatSync(path)
+  if (file.isSymbolicLink() || !file.isFile()) throw new Error('Guide file must be a regular non-symlink file.')
+  const body = readFileSync(path, 'utf8')
+  if (Buffer.byteLength(body, 'utf8') > 32 * 1024) throw new Error('Guide exceeds the 32 KiB UTF-8 limit; it was not saved.')
+  if (guideBodyHash(body) === base.hash) {
+    console.log(`No ${kind} guide changes to save.`)
+    return
+  }
+  const saved = validateGuideResponse(await request(`/api/abstracts/${id}/${endpoint}`, {
+    method: 'PUT', body: JSON.stringify({ body, expectedRevision: base.revision }),
+  }), `${kind} guide save`)
+  writeGuideSyncState(cwd, id, userId, {
+    ...(state?.guides ?? {}),
+    [kind]: { revision: saved.revision, hash: guideBodyHash(body) },
+  })
+  console.log(`Saved ${kind} guide revision ${saved.revision}.`)
+}
+
 async function loadFolders() {
   const meta = await apiFetch('/api/organise/meta')
   return meta.all_collections || meta.collections || []
@@ -215,6 +442,36 @@ They tell you when to push, preview, publish, or invite.`)
 async function cmdCreate(cwd, rest) {
   const { flags } = parseFlags(rest)
   if (flags.help) return printHelp('create')
+  if (flags['recipe-config'] === true) throw new Error('Pass a JSON file with --recipe-config <file>.')
+  if (typeof flags['recipe-config'] === 'string') {
+    const recipePath = flags['recipe-config'].startsWith('/') ? flags['recipe-config'] : join(cwd, flags['recipe-config'])
+    let config
+    try { config = JSON.parse(readFileSync(recipePath, 'utf8')) } catch { throw new Error('Could not read recipe config JSON.') }
+    if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Recipe config must be a JSON object.')
+    if (typeof flags.name === 'string' && flags.name.trim()) config.name = flags.name.trim()
+    const sourceTargets = ['index.html', 'styles.css', 'app.js', 'data.ndjson', 'private.ndjson', '.amorphous.json']
+    if (sourceTargets.some(name => existsSync(join(cwd, name)))) {
+      throw new Error('Recipe creation needs an empty project folder.')
+    }
+    const data = await apiFetch('/api/abstracts/recipe', { method: 'POST', body: JSON.stringify(config) })
+    writeRecipeFiles(cwd, data.source)
+    writeMeta(cwd, data.id)
+    await initializeEmptyAbstractGuide(cwd, data.id)
+    if (data.recoveryContract) {
+      writeFileSync(projectMetaPath(cwd), JSON.stringify({ abstractId: data.id, recoveryContract: data.recoveryContract }, null, 2) + '\n')
+    }
+    const folderName = folderToken(flags)
+    if (folderName) {
+      const folder = await resolveFolder(folderName)
+      await apiFetch(`/api/abstracts/${data.id}/filing`, {
+        method: 'PATCH', body: JSON.stringify({ collection_id: folder.id }),
+      })
+    }
+    syncProjectContract(cwd)
+    if (jsonMode(flags)) printJson({ id: data.id, name: data.name })
+    else { console.log(data.id); console.log('Prefer amorphous-cli serve while you edit.') }
+    return
+  }
   const template = typeof flags.template === 'string' ? flags.template : 'blank'
   const data = await apiFetch('/api/abstracts', { method: 'POST', body: JSON.stringify({ template }) })
   const id = data.id
@@ -235,6 +492,7 @@ async function cmdCreate(cwd, rest) {
     })
   }
   writeStarter(cwd, template)
+  await initializeEmptyAbstractGuide(cwd, id)
   syncProjectContract(cwd)
   if (jsonMode(flags)) printJson({ id, name: name || 'Untitled' })
   else {
@@ -341,24 +599,38 @@ async function cmdPeople(cwd, rest) {
   }
 }
 
+export function writePulledProject(cwd, id, detail, records, { fresh = false } = {}) {
+  if (fresh && readdirSync(cwd).length) {
+    throw new Error('Pulling into a new folder needs an empty directory.')
+  }
+  const abstract = detail?.abstract
+  if (!abstract || typeof abstract.draft_html !== 'string' || typeof abstract.draft_css !== 'string' || typeof abstract.draft_js !== 'string') {
+    throw new Error('Abstract response did not include editable source files.')
+  }
+  const rows = records?.records || []
+  writeProjectFiles(cwd, {
+    html: abstract.draft_html,
+    css: abstract.draft_css,
+    js: abstract.draft_js,
+    shared: rows.filter((r) => r.visibility !== 'private'),
+    private: rows.filter((r) => r.visibility === 'private'),
+  })
+  const recoveryContract = abstract.draft_recovery_contract
+  writeFileSync(projectMetaPath(cwd), JSON.stringify({
+    abstractId: id,
+    ...(recoveryContract && typeof recoveryContract === 'object' ? { recoveryContract } : {}),
+  }, null, 2) + '\n')
+  syncProjectContract(cwd)
+}
+
 async function cmdPull(cwd, rest) {
-  const { flags } = parseFlags(rest)
+  const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('pull')
-  const id = requireMeta(cwd)
+  const id = await resolveAbstractId(cwd, flags, positional)
   const detail = await apiFetch(`/api/abstracts/${id}`)
   warnIfRemoteChanged(detail)
   const records = await apiFetch(`/api/abstracts/${id}/records`)
-  const rows = records.records || []
-  const shared = rows.filter((r) => r.visibility !== 'private')
-  const priv = rows.filter((r) => r.visibility === 'private')
-  writeProjectFiles(cwd, {
-    html: detail.abstract.draft_html,
-    css: detail.abstract.draft_css,
-    js: detail.abstract.draft_js,
-    shared,
-    private: priv,
-  })
-  syncProjectContract(cwd)
+  writePulledProject(cwd, id, detail, records, { fresh: positional.length > 0 || Boolean(flags.abstract) })
   console.log('Pulled.')
   console.log('Prefer amorphous-cli serve while you edit.')
 }
@@ -367,7 +639,8 @@ async function cmdPush(cwd, rest) {
   const { flags } = parseFlags(rest)
   if (flags.help) return printHelp('push')
   const id = requireMeta(cwd)
-  warnIfRemoteChanged(await apiFetch(`/api/abstracts/${id}`))
+  const detail = await apiFetch(`/api/abstracts/${id}`)
+  warnIfRemoteChanged(detail)
   if (flags.data) {
     const localRecords = recordsFromLocal(cwd)
     const { refused } = await apiFetch(`/api/abstracts/${id}/records`, {
@@ -381,7 +654,8 @@ async function cmdPush(cwd, rest) {
   const { html, css, js } = readProjectFiles(cwd)
   await apiFetch(`/api/abstracts/${id}/push`, {
     method: 'POST',
-    body: JSON.stringify({ html, css, js }),
+    body: JSON.stringify({ html, css, js, expectedRevision: detail.abstract.draft_revision,
+      ...(readMeta(cwd)?.recoveryContract ? { recoveryContract: readMeta(cwd).recoveryContract } : {}) }),
   })
   console.log(flags.data ? 'Pushed source and records.' : 'Pushed source.')
 }
@@ -398,6 +672,7 @@ async function cmdServe(cwd, rest) {
     cwd,
     abstractId: id,
     port,
+    environment: flags.preview ? 'preview' : 'production',
     json: jsonMode(flags),
   })
   let warnedRemote = false
@@ -428,19 +703,16 @@ async function cmdServe(cwd, rest) {
   })
 }
 
-function urlsFor(id) {
-  return {
-    open: `${appOrigin().replace(/\/$/, '')}/a/${id}`,
-    preview: `${abstractsOrigin().replace(/\/$/, '')}/${id}/draft`,
-    live: `${abstractsOrigin().replace(/\/$/, '')}/${id}`,
-  }
+async function urlsFor(id) {
+  const discovery = await apiFetch('/api/runtime/origins', { auth: false })
+  return urlsFromDiscovery(id, appOrigin(), discovery, process.env)
 }
 
 async function cmdOpen(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('open')
   const id = await resolveAbstractId(cwd, flags, positional)
-  const urls = urlsFor(id)
+  const urls = await urlsFor(id)
   if (jsonMode(flags)) printJson(urls)
   else console.log(urls.open)
 }
@@ -451,7 +723,7 @@ async function cmdPreview(cwd, rest) {
   const id = await resolveAbstractId(cwd, flags, positional)
   const detail = await apiFetch(`/api/abstracts/${id}`)
   warnIfRemoteChanged(detail)
-  const urls = urlsFor(id)
+  const urls = await urlsFor(id)
   if (jsonMode(flags)) printJson({ preview: urls.preview, remoteChangedSincePush: Boolean(detail.remoteChangedSincePush) })
   else console.log(urls.preview)
 }
@@ -460,11 +732,12 @@ async function cmdPublish(cwd, rest) {
   const { flags, positional } = parseFlags(rest)
   if (flags.help) return printHelp('publish')
   const id = await resolveAbstractId(cwd, flags, positional)
-  warnIfRemoteChanged(await apiFetch(`/api/abstracts/${id}`))
+  const detail = await apiFetch(`/api/abstracts/${id}`)
+  warnIfRemoteChanged(detail)
   const live = Boolean(flags.live)
   const version = await apiFetch(`/api/abstracts/${id}/publish`, {
     method: 'POST',
-    body: JSON.stringify({ live }),
+    body: JSON.stringify({ live, expectedRevision: detail.abstract.draft_revision }),
   })
   if (jsonMode(flags)) printJson({ id: version.id, label: version.label, live })
   else console.log(live ? 'It’s live.' : 'Published.')
@@ -751,6 +1024,10 @@ export async function runCommand(argv, cwd = process.cwd()) {
       return cmdPeople(cwd, rest)
     case 'pull':
       return cmdPull(cwd, rest)
+    case 'context':
+      return cmdContext(cwd, rest)
+    case 'guide':
+      return cmdGuide(cwd, rest)
     case 'push':
       return cmdPush(cwd, rest)
     case 'open':

package/lib/files.mjs

@@ -43,8 +43,10 @@ export function writeProjectFiles(cwd, payload) {
 export function recordsFromLocal(cwd) {
   const { shared, private: priv } = readProjectFiles(cwd)
   return [
-    ...shared.map((r) => ({ ...r, visibility: r.visibility || 'shared' })),
-    ...priv.map((r) => ({ ...r, visibility: 'private' })),
+    ...shared.map((r) => ({ ...r, revision: r.revision || 1, visibility: r.visibility || 'shared',
+      collection: r.collection || 'default', created_by: r.created_by || null })),
+    ...priv.map((r) => ({ ...r, revision: r.revision || 1, visibility: 'private',
+      collection: r.collection || 'default', created_by: r.created_by || null })),
   ]
 }
 
@@ -66,6 +68,9 @@ export function insertLocalRecord(cwd, row) {
   }
   body.visibility = body.visibility === 'private' ? 'private' : 'shared'
   if (!body.id) body.id = randomUUID()
+  body.revision = 1
+  body.collection = 'default'
+  body.created_by = null
   const rows = recordsFromLocal(cwd)
   if (rows.some((r) => r.id === body.id)) return { status: 409, message: 'Conflict' }
   rows.push(body)
@@ -83,6 +88,9 @@ export function replaceLocalRecord(cwd, id, row) {
     ...(row && typeof row === 'object' ? row : {}),
     id,
     visibility: existing.visibility,
+    revision: existing.revision + 1,
+    collection: existing.collection,
+    created_by: existing.created_by,
   }
   rows[index] = next
   writeLocalRecords(cwd, rows)

package/lib/help.mjs

@@ -9,6 +9,8 @@ export const ROOT_HELP = `Amorphous
   preview [abstract]            Preview URL (draft)
   serve                         Develop in this folder
   pull                          Pull draft and records to this folder
+  context [abstract]            Load authorized agent guides only
+  guide save <abstract|private> Save the selected guide explicitly
   push                          Push local files
   publish [--live]              Publish a version; --live is Go live
   recommend [--note <text>]     Send this draft to the owner for review
@@ -52,9 +54,9 @@ Start the local MCP server on stdio.`,
 List abstracts. Default view is all (All Abstracts).
 --folder filters to a folder. --tag filters to a tag.`,
 
-  create: `create [--name <name>] [--folder <name>] [--template blank|list|board|landing] [--json]
+  create: `create [--name <name>] [--folder <name>] [--template blank|list|board|landing] [--recipe-config <file>] [--json]
 
-New abstract. Writes .amorphous.json in this directory.`,
+New abstract. --recipe-config creates a supported recipe and writes its generated source files. Writes .amorphous.json in this directory.`,
 
   open: `open [abstract] [--json]
 
@@ -73,18 +75,28 @@ Records start local, in this folder. The page can switch to prod, which reads an
 
 Pull the draft and records into this directory.`,
 
+  context: `context [abstract]
+
+Load the current user's authorized agent guides without pulling source or records.
+Run once when beginning work on an existing abstract. The guides are ignored local files; private guide text is supplied to this local agent process and cannot be recalled after download.`,
+
+  guide: `guide save <abstract|private> [abstract]
+
+Explicitly save the selected local guide using its last loaded revision. A stale revision is refused so neither copy is overwritten. Generic push, recommend, and publish never save or include guides.`,
+
   push: `push [--data]
 
 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.`,
+--data also merges records from this folder. A record changed both here and on the abstract is refused.
+Agent guides are separate: push never uploads them. Use amorphous-cli guide save explicitly.`,
 
   publish: `publish [--live]
 
-Publish a new version. --live also makes it the live version (Go live).`,
+Publish a new version. --live also makes it the live version (Go live). Guides are not included.`,
 
   recommend: `recommend [--note <text>] [--json]
 
-Send this folder's HTML, CSS, and JavaScript to the owner as a proposal. It does not change the live version.`,
+Send this folder's HTML, CSS, and JavaScript to the owner as a proposal. It does not change the live version or include agent guides.`,
 
   live: `live [abstract] [--version <id>]
 

package/lib/participant-client.mjs

@@ -0,0 +1,82 @@
+const ACTION = /^[a-z][a-z0-9_.-]{0,79}$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const TOKEN = /^[A-Za-z0-9_-]{40,64}$/
+const RECEIPT = /^[0-9a-f]{8}-[0-9a-f-]{27,}$/i
+const ACTION_NAMES = new Set([
+  'records.query', 'records.create', 'records.patch', 'records.delete',
+  'items.add', 'items.done', 'items.move', 'items.edit', 'items.delete',
+  'private.query', 'private.create', 'private.patch', 'private.delete',
+  'form.submit', 'form.mine', 'form.edit',
+])
+
+export function createParticipantClient({ origin, appId, token, hostHeaders = {}, fetchImpl = fetch }) {
+  const base = new URL(origin)
+  if (!['https:', 'http:'].includes(base.protocol) || base.username || base.password ||
+      base.search || base.hash || (base.pathname !== '/' && base.pathname !== '')) {
+    throw new TypeError('Participant app origin must be an HTTP(S) origin')
+  }
+  if (base.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(base.hostname) &&
+      !base.hostname.endsWith('.localhost')) {
+    throw new TypeError('Participant grant requires HTTPS outside local development')
+  }
+  if (!UUID.test(appId) || !TOKEN.test(token)) throw new TypeError('Invalid participant connection settings')
+  if (Object.keys(hostHeaders).some((key) => key.toLowerCase() !== 'host') ||
+      Object.values(hostHeaders).some((value) => typeof value !== 'string' || /[\r\n]/.test(value))) {
+    throw new TypeError('Invalid participant host configuration')
+  }
+  const root = `/api/v1/apps/${appId.toLowerCase()}`
+
+  async function request(path, { method = 'GET', body, idempotencyKey, approvalId } = {}) {
+    if (typeof path !== 'string' || !path.startsWith(`${root}/`) || path.includes('..') || path.includes('?')) {
+      throw new Error('Unsupported participant endpoint')
+    }
+    const actionRoute = new RegExp(`^${root}/actions/([^/]+)/invoke$`).exec(path)
+    const receiptPrefix = `${root}/receipts/`
+    const getOnly = path === `${root}/me` || path === `${root}/actions` ||
+      path === `${root}/status` || path === `${root}/activity` ||
+      (path.startsWith(receiptPrefix) && RECEIPT.test(path.slice(receiptPrefix.length)) )
+    const postAction = Boolean(actionRoute && ACTION_NAMES.has(actionRoute[1]))
+    const allowed = (getOnly && method === 'GET') || (postAction && method === 'POST')
+    if (!allowed) throw new Error('Unsupported participant endpoint')
+    const headers = { ...hostHeaders, Authorization: `AmorphousGrant ${token}`, Accept: 'application/json' }
+    if (body !== undefined) headers['Content-Type'] = 'application/json'
+    if (idempotencyKey !== undefined) {
+      if (typeof idempotencyKey !== 'string' || idempotencyKey.length < 1 || idempotencyKey.length > 200) {
+        throw new TypeError('Invalid idempotency key')
+      }
+      headers['Idempotency-Key'] = idempotencyKey
+    }
+    if (approvalId !== undefined) {
+      if (typeof approvalId !== 'string' || !UUID.test(approvalId)) throw new TypeError('Invalid approval id')
+      headers['Amorphous-Approval'] = approvalId
+    }
+    const response = await fetchImpl(new URL(path, base), {
+      method, headers, redirect: 'error', ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+    const raw = await response.text()
+    let payload
+    try { payload = raw ? JSON.parse(raw) : null } catch { payload = null }
+    if (!response.ok) throw new Error(`Participant request failed (${response.status})`)
+    return payload
+  }
+
+  return Object.freeze({
+    request,
+    me: () => request(`${root}/me`),
+    discover: () => request(`${root}/actions`),
+    invoke: (action, input, idempotencyKey, approvalId) => {
+      if (typeof action !== 'string' || !ACTION.test(action) || !ACTION_NAMES.has(action)) throw new TypeError('Invalid action')
+      if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('Invalid action input')
+      if (approvalId !== undefined && (typeof approvalId !== 'string' || !RECEIPT.test(approvalId))) {
+        throw new TypeError('Invalid approval id')
+      }
+      return request(`${root}/actions/${action}/invoke`, { method: 'POST', body: input, idempotencyKey, approvalId })
+    },
+    receipt: (receiptId) => {
+      if (typeof receiptId !== 'string' || !RECEIPT.test(receiptId)) throw new TypeError('Invalid receipt id')
+      return request(`${root}/receipts/${receiptId}`)
+    },
+    status: () => request(`${root}/status`),
+    activity: () => request(`${root}/activity`),
+  })
+}

package/lib/participant-client.test.mjs

@@ -0,0 +1,34 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createParticipantClient } from './participant-client.mjs'
+
+const id = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+
+test('participant client sends only its grant credential to selected-app endpoints', async () => {
+  const calls = []
+  const client = createParticipantClient({
+    origin: 'https://amorphous.test/', appId: id, token: 'A'.repeat(43),
+    fetchImpl: async (url, options) => {
+      calls.push({ url: String(url), options })
+      return new Response('{"ok":true}', { status: 200, headers: { 'Content-Type': 'application/json' } })
+    },
+  })
+  await client.me()
+  await client.invoke('items.add', { collection: 'items', visibility: 'shared', body: { title: 'Milk' } }, 'req-1', id)
+  assert.equal(calls[0].url, `https://amorphous.test/api/v1/apps/${id}/me`)
+  assert.equal(calls[0].options.headers.Authorization, `AmorphousGrant ${'A'.repeat(43)}`)
+  assert.equal(calls[0].options.redirect, 'error')
+  assert.equal(calls[1].options.headers['Idempotency-Key'], 'req-1')
+  assert.equal(calls[1].options.headers['Amorphous-Approval'], id)
+  assert.equal(calls[1].options.headers.Authorization, `AmorphousGrant ${'A'.repeat(43)}`)
+  assert.equal(calls.some(({ url }) => !url.includes(`/apps/${id}/`)), false)
+})
+
+test('participant client rejects non-selected or privileged routes and invalid actions', async () => {
+  const client = createParticipantClient({ origin: 'https://amorphous.test', appId: id,
+    token: 'A'.repeat(43), fetchImpl: async () => { throw new Error('unexpected network') } })
+  await assert.rejects(client.request('/api/v1/apps'), /Unsupported participant endpoint/)
+  await assert.rejects(client.request(`/api/v1/apps/${id}/actions`, { method: 'POST' }), /Unsupported participant endpoint/)
+  assert.throws(() => client.invoke('items.add', null, 'req-1'), /Invalid action input/)
+  assert.throws(() => client.invoke('publish', {}, 'req-1'), /Invalid action/)
+})