@jkwd/inbase 0.1.21 → 0.1.22

package/bin/session.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { explorerRoot, takeFlagValue, takeFlagValues } from './project.mjs'
+import { explorerRoot, instanceFile, readInstanceFile, takeFlagValue, takeFlagValues } from './project.mjs'
 
 async function loadExplorer() {
   const storePath = pathToFileURL(
@@ -104,7 +104,19 @@ function emitStopped(store, dataDir, sessionId) {
   process.exit(2)
 }
 
-function emitApprovalHandshake(store, dataDir, sessionId, manifest, initialDiff) {
+function emitTargetExplain(store, explain, dataDir, sessionId) {
+  const consumed = explain.consumeExplainStart(dataDir)
+  if (!consumed) return false
+  const label = explain.explainTargetLabel(consumed)
+  signalAck(store, dataDir, sessionId, 'explain', label)
+  const quoted = JSON.stringify(consumed.question)
+  console.log(
+    `VISUAL_CODER_EXPLAIN The user clicked Explain on the ${label}. Do not edit project files. Do not accept or invoke the next step. Do not start the map walk overlay. The visualizer shows a single-explanation card. Run: npx inbase explain start --question ${quoted} Then inspect that ${consumed.kind} and where it fits in the codebase, and report one explanation with npx inbase explain report --question ${quoted} --step "..." --body "...". Use a single --step. After reporting, run npx inbase explain wait. If explain wait returns VISUAL_CODER_EXPLAIN for another file or folder, replace the explanation with one new step. When explain wait returns stopped or timeout, run wait-for-approval again.`,
+  )
+  process.exit(7)
+}
+
+function emitApprovalHandshake(store, explain, dataDir, sessionId, manifest, initialDiff, pendingStart) {
   const current = initialDiff
     ? manifest?.diffs.find((entry) => entry.id === initialDiff.id)
     : null
@@ -119,6 +131,36 @@ function emitApprovalHandshake(store, dataDir, sessionId, manifest, initialDiff)
     )
     process.exit(5)
   }
+  if (pendingStart) {
+    emitTargetExplain(store, explain, dataDir, sessionId)
+  }
+  if (manifest.pendingExplain) {
+    const consumed = store.consumeExplainRequest(dataDir, sessionId) ?? manifest
+    const reviewing = consumed.phase === 'review'
+    const active = reviewing ? consumed.diffs?.at(-1) : null
+    const step = active?.step ?? consumed.currentStep
+    const title =
+      consumed.steps?.find((item) => item.index === step)?.title ||
+      active?.title ||
+      `step ${step}`
+    signalAck(
+      store,
+      dataDir,
+      sessionId,
+      'explain',
+      `the proposal for ${title}`,
+    )
+    const target = reviewing
+      ? 'inspect the live files this proposal changed'
+      : 'inspect the live files and folders this plan step will use'
+    const waiting = reviewing
+      ? 'The proposal is still waiting for Accept proposal.'
+      : 'The plan is still waiting for Create proposal.'
+    console.log(
+      `VISUAL_CODER_EXPLAIN The user clicked Explain proposal for step ${step}: ${title}. Do not edit project files. Do not accept or invoke the next step. Start explain mode and walk this proposal on the map. Run: npx inbase explain start --question "Explain the current proposal: ${title}" Then ${target} and report steps with npx inbase explain report --question "Explain the current proposal: ${title}" --step "..." --body "..." --files path [--folders path] [--select path] [--zoom path] [--relations from:to] [--info] [--highlight function:name] [--point function:name]. After reporting, run npx inbase explain wait. If the user asks about a step, report sub-steps with --parent and wait again. When explain wait returns stopped or timeout, run wait-for-approval again. ${waiting}`,
+    )
+    process.exit(7)
+  }
   if (manifest.phase === 'working') {
     const next = manifest.steps.find((step) => step.index === manifest.currentStep)
     const title = next?.title
@@ -150,7 +192,7 @@ function emitApprovalHandshake(store, dataDir, sessionId, manifest, initialDiff)
       console.log(
         continuing
           ? `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${title ? `: ${title}` : ''}. Continue immediately: edit live files for this step only, then inbase propose-patch --session ${sessionId} with no patch file. Do not explore, re-plan, or run wait-for-blueprint.`
-          : `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${title ? `: ${title}` : ''}. Re-read the shared blueprint.json before implementing; the user can place files and islands at any time. Edit the live project files for this step only (Write, StrReplace, Delete). Then record the step with inbase propose-patch --session ${sessionId} — no patch file. Inbase diffs those edits against the invoke snapshot and stores the patch. Do not write a unified diff yourself.`,
+          : `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${title ? `: ${title}` : ''}. Re-read the global blueprint.json and this session's local blueprint before implementing; the user can place files and islands at any time. Edit the live project files for this step only (Write, StrReplace, Delete). Then record the step with inbase propose-patch --session ${sessionId} — no patch file. Inbase diffs those edits against the invoke snapshot and stores the patch. Do not write a unified diff yourself.`,
       )
     }
     process.exit(0)
@@ -190,26 +232,84 @@ export async function startSession(args) {
 
 export async function attachSession(args) {
   const { store, config } = await loadExplorer()
+  if (!readInstanceFile(instanceFile(config.dataDir))) {
+    console.error(store.NOT_RUNNING_MESSAGE)
+    process.exit(1)
+  }
   const sessionId = takeFlagValue(args, '--session')
-  const manifest = store.attachSession(config.dataDir, sessionId)
+  const colorQuery = takeFlagValue(args, '--color')
+  const manifest = store.attachSession(config.dataDir, sessionId, { color: colorQuery })
+  const color = store.resolveSessionColor(manifest.color)
+  const colorName = color?.name || null
   console.log(`VISUAL_CODER_SESSION ${manifest.sessionId}`)
-  printAck('attached', manifest.name || manifest.sessionId)
+  if (colorName) console.log(`VISUAL_CODER_COLOR ${colorName}`)
+  printAck('attached', colorName || manifest.name || manifest.sessionId)
   console.log(
-    `VISUAL_CODER_ATTACHED Attached to the next waiting visualizer session ${manifest.name || manifest.sessionId} (${manifest.phase}). Use --session ${manifest.sessionId} for every later command. Run inbase wait-for-blueprint --session ${manifest.sessionId} to read the optional blueprint, instruction, and attached files; it does not wait.`,
+    colorName
+      ? `VISUAL_CODER_ATTACHED Attached to the ${colorName} session (${manifest.phase}). Tell the user you connected to the ${colorName} chat. Use --session ${manifest.sessionId} for every later command. Run inbase wait-for-blueprint --session ${manifest.sessionId} to read the optional blueprint, instruction, and attached files; it does not wait. Then run wait-for-approval so map Explain clicks are heard.`
+      : `VISUAL_CODER_ATTACHED Attached to the next waiting visualizer session ${manifest.name || manifest.sessionId} (${manifest.phase}). Use --session ${manifest.sessionId} for every later command. Run inbase wait-for-blueprint --session ${manifest.sessionId} to read the optional blueprint, instruction, and attached files; it does not wait. Then run wait-for-approval so map Explain clicks are heard.`,
   )
 }
 
-function printBlueprintDump(blueprint) {
+function printBlueprintDump(blueprint, options = {}) {
   const blocks = blueprint.userCreatedBlocks ?? []
   const islands = blueprint.userCreatedIslands ?? []
-  console.log(
-    blueprint.enabled
-      ? `VISUAL_CODER_BLUEPRINT_READY The shared blueprint has ${blocks.length} file(s) and ${islands.length} island(s). The blueprint is leading: create those paths and honor addedFunctions, addedVariables, addedImports, and notes even if they are not on disk. Notes are extra instructions or pseudo code for a file, function, or variable — follow them when implementing those items. Do not omit, rename, relocate, or replace them. Extra new files not in the blueprint are a deviation. If you would differ from the blueprint, ask the user first; do not silently deviate. The user can keep placing files and islands; re-read the shared blueprint.json when it is printed again.`
-      : 'VISUAL_CODER_BLUEPRINT_READY The shared blueprint is empty. The user can still place files and islands; re-read the shared blueprint.json when it is printed again. Continue without user-placed files until that file has content.',
-  )
-  console.log('VISUAL_CODER_BLUEPRINT_START')
+  const local = options.local === true
+  const colorName = options.colorName || 'session'
+  const readyTag = local
+    ? 'VISUAL_CODER_LOCAL_BLUEPRINT_READY'
+    : 'VISUAL_CODER_BLUEPRINT_READY'
+  const startTag = local
+    ? 'VISUAL_CODER_LOCAL_BLUEPRINT_START'
+    : 'VISUAL_CODER_BLUEPRINT_START'
+  const endTag = local
+    ? 'VISUAL_CODER_LOCAL_BLUEPRINT_END'
+    : 'VISUAL_CODER_BLUEPRINT_END'
+  if (local) {
+    console.log(
+      blueprint.enabled
+        ? `${readyTag} The ${colorName} session blueprint has ${blocks.length} file(s) and ${islands.length} island(s). This local blueprint is only for this ${colorName} chat. It is leading together with the global blueprint: create those paths and honor addedFunctions, addedVariables, addedImports, and notes even if they are not on disk. Do not omit, rename, relocate, or replace them. Extra new files not in either blueprint are a deviation. If you would differ from this local blueprint, ask the user first.`
+        : `${readyTag} The ${colorName} session blueprint is empty. Only this ${colorName} chat can see a local blueprint if the user places one later.`,
+    )
+  } else {
+    console.log(
+      blueprint.enabled
+        ? `${readyTag} The global blueprint has ${blocks.length} file(s) and ${islands.length} island(s). The global blueprint is shared with every session and is leading: create those paths and honor addedFunctions, addedVariables, addedImports, and notes even if they are not on disk. Notes are extra instructions or pseudo code for a file, function, or variable — follow them when implementing those items. Do not omit, rename, relocate, or replace them. Extra new files that are not in the global or this session's local blueprint are a deviation. If you would differ from the blueprint, ask the user first; do not silently deviate. The user can keep placing files and islands; re-read the global blueprint.json when it is printed again.`
+        : `${readyTag} The global blueprint is empty. The user can still place files and islands on the global or this session's color; re-read the global blueprint.json when it is printed again. Continue without user-placed files until that file has content.`,
+    )
+  }
+  console.log(startTag)
   console.log(JSON.stringify(blueprint, null, 2))
-  console.log('VISUAL_CODER_BLUEPRINT_END')
+  console.log(endTag)
+}
+
+function printSessionBlueprints(store, dataDir, sessionId) {
+  const global = store.readBlueprint(dataDir)
+  const local = store.readLocalBlueprint(dataDir, sessionId)
+  const colorName =
+    store.resolveSessionColor(store.readManifest(dataDir, sessionId)?.color)?.name ||
+    'session'
+  const blocks = (global.userCreatedBlocks ?? []).length
+  const islands = (global.userCreatedIslands ?? []).length
+  const localBlocks = (local.userCreatedBlocks ?? []).length
+  const localIslands = (local.userCreatedIslands ?? []).length
+  const detail = [
+    global.enabled ? `global ${blocks} file(s), ${islands} island(s)` : null,
+    local.enabled
+      ? `${colorName} ${localBlocks} file(s), ${localIslands} island(s)`
+      : null,
+  ]
+    .filter(Boolean)
+    .join('; ')
+  printBlueprintDump(global)
+  printBlueprintDump(local, { local: true, colorName })
+  store.markBlueprintSeen(dataDir, sessionId, global.revision, local.revision)
+  return {
+    global,
+    local,
+    colorName,
+    detail: detail || 'none',
+  }
 }
 
 export async function waitForBlueprint(args) {
@@ -233,20 +333,14 @@ export async function waitForBlueprint(args) {
     emitStopped(store, config.dataDir, sessionId)
   }
 
-  const blueprint = store.readBlueprint(config.dataDir)
-  const blocks = blueprint.userCreatedBlocks ?? []
-  const islands = blueprint.userCreatedIslands ?? []
+  const dumped = printSessionBlueprints(store, config.dataDir, sessionId)
   signalAck(
     store,
     config.dataDir,
     sessionId,
     'blueprint',
-    blueprint.enabled
-      ? `${blocks.length} file(s), ${islands.length} island(s)`
-      : 'none',
+    dumped.detail,
   )
-  printBlueprintDump(blueprint)
-  store.markBlueprintSeen(config.dataDir, sessionId, blueprint.revision)
   const instruction =
     typeof manifest.initialInstruction === 'string'
       ? manifest.initialInstruction.trim()
@@ -273,6 +367,10 @@ export async function waitForBlueprint(args) {
       console.log('VISUAL_CODER_CONTEXT_FILE_END')
     }
   }
+  const explain = await loadExplainStore()
+  if (explain.readExplain(config.dataDir).pendingStart) {
+    emitTargetExplain(store, explain, config.dataDir, sessionId)
+  }
   process.exit(0)
 }
 
@@ -323,35 +421,57 @@ export async function waitForApproval(args) {
   }
   store.autoAdvance(config.dataDir, sessionId, config.targetRoot)
 
+  const explain = await loadExplainStore()
   const { manifest: manifestPath } = store.sessionPaths(config.dataDir, sessionId)
+  const explainFile = path.join(config.dataDir, explain.EXPLAIN_FILE)
   const gate = createManifestGate(manifestPath)
+  const explainGate = createManifestGate(explainFile)
   let lastWaiting = null
   try {
     while (Date.now() - started < timeoutMs) {
       store.touchSessionConnection(config.dataDir, sessionId)
       store.autoAdvance(config.dataDir, sessionId, config.targetRoot)
       const manifest = store.readManifest(config.dataDir, sessionId)
-      emitApprovalHandshake(store, config.dataDir, sessionId, manifest, initialDiff)
+      const pendingStart = explain.readExplain(config.dataDir).pendingStart
+      emitApprovalHandshake(
+        store,
+        explain,
+        config.dataDir,
+        sessionId,
+        manifest,
+        initialDiff,
+        pendingStart,
+      )
       if (!manifest) continue
-      const blueprint = store.readBlueprint(config.dataDir)
-      const seen = manifest.blueprintRevision ?? 0
-      if (blueprint.revision > seen) {
-        const blocks = blueprint.userCreatedBlocks ?? []
-        const islands = blueprint.userCreatedIslands ?? []
+      const global = store.readBlueprint(config.dataDir)
+      const local = store.readLocalBlueprint(config.dataDir, sessionId)
+      const seenGlobal = manifest.blueprintRevision ?? 0
+      const seenLocal = manifest.localBlueprintRevision ?? 0
+      const globalChanged = global.revision > seenGlobal
+      const localChanged = local.revision > seenLocal
+      if (globalChanged || localChanged) {
+        const dumped = printSessionBlueprints(store, config.dataDir, sessionId)
+        const colorName = dumped.colorName
         signalAck(
           store,
           config.dataDir,
           sessionId,
           'blueprint',
-          blueprint.enabled
-            ? `${blocks.length} file(s), ${islands.length} island(s)`
-            : 'none',
-        )
-        console.log(
-          'VISUAL_CODER_BLUEPRINT The shared blueprint changed. Follow the latest files, islands, functions, variables, imports, and notes. Do not omit, rename, relocate, or replace them. If this would differ from the current plan, ask the user before replacing the plan. Then run wait-for-approval again.',
+          dumped.detail,
         )
-        printBlueprintDump(blueprint)
-        store.markBlueprintSeen(config.dataDir, sessionId, blueprint.revision)
+        if (globalChanged && localChanged) {
+          console.log(
+            `VISUAL_CODER_BLUEPRINT The global blueprint and the ${colorName} session blueprint changed. Follow the latest files, islands, functions, variables, imports, and notes from both. Do not omit, rename, relocate, or replace them. The ${colorName} blueprint is only for this chat. If this would differ from the current plan, ask the user before replacing the plan. Then run wait-for-approval again.`,
+          )
+        } else if (localChanged) {
+          console.log(
+            `VISUAL_CODER_BLUEPRINT The ${colorName} session blueprint changed. This local blueprint is only for this chat. Follow its latest files, islands, functions, variables, imports, and notes together with the global blueprint. Do not omit, rename, relocate, or replace them. If this would differ from the current plan, ask the user before replacing the plan. Then run wait-for-approval again.`,
+          )
+        } else {
+          console.log(
+            'VISUAL_CODER_BLUEPRINT The global blueprint changed. Follow the latest files, islands, functions, variables, imports, and notes. Do not omit, rename, relocate, or replace them. If this would differ from the current plan, ask the user before replacing the plan. Then run wait-for-approval again.',
+          )
+        }
         process.exit(6)
       }
       const waiting = waitingMessage(sessionId, manifest)
@@ -359,13 +479,15 @@ export async function waitForApproval(args) {
         console.log(waiting)
         lastWaiting = waiting
       }
-      await gate.wait(50)
+      await Promise.race([gate.wait(50), explainGate.wait(50)])
     }
   } finally {
     gate.close()
+    explainGate.close()
   }
 
   signalAck(store, config.dataDir, sessionId, 'timeout', 'no visualizer signal')
+  store.stopSession(config.dataDir, sessionId, config.targetRoot)
   console.error('Timed out waiting for visualizer review. Do not modify files.')
   process.exit(3)
 }
@@ -383,7 +505,7 @@ export async function proposePatch(args) {
     if (!sessionId) usage('propose-patch', '--session <cursor-chat-id> --clear')
     store.stopSession(config.dataDir, sessionId, config.targetRoot)
     console.log(
-      `Cleared session ${sessionId}; stored diffs were removed. The shared blueprint remains.`,
+      `Cleared session ${sessionId}; stored diffs were removed. The global blueprint remains.`,
     )
     process.exit(0)
   }
@@ -429,3 +551,130 @@ export async function proposePatch(args) {
         : `VISUAL_CODER_STEP_READY Recorded live edits as patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Immediately run wait-for-approval. Do not explore or plan. Accept proposal invokes the next step; when EXECUTE returns, implement that step at once.`,
   )
 }
+
+async function loadExplainStore() {
+  const explainPath = pathToFileURL(
+    path.join(explorerRoot, 'scripts/explain-store.mjs'),
+  ).href
+  return import(explainPath)
+}
+
+export async function runExplain(args) {
+  const { store, config } = await loadExplorer()
+  if (!readInstanceFile(instanceFile(config.dataDir))) {
+    console.error(store.NOT_RUNNING_MESSAGE)
+    process.exit(1)
+  }
+  const explain = await loadExplainStore()
+  const parsed = explain.parseExplainCli(args)
+  if (parsed.action === 'stop') {
+    explain.stopExplain(config.dataDir)
+    console.log('VISUAL_CODER_EXPLAIN_STOPPED Explain mode is off.')
+    return
+  }
+  if (parsed.action === 'wait') {
+    await waitForExplain(explain, config.dataDir, args)
+    return
+  }
+  if (parsed.action === 'start') {
+    if (!parsed.question) {
+      usage('explain start', '--question "How does this work?"')
+    }
+    explain.startExplain(config.dataDir, parsed.question)
+    console.log(`VISUAL_CODER_EXPLAIN_STARTED ${parsed.question}`)
+    console.log(
+      'The map is in explain mode. Explore the codebase, then run inbase explain report with --step / --body / --files / --folders / --select / --zoom / --relations / --info / --highlight / --point.',
+    )
+    return
+  }
+  if (!parsed.steps.length) {
+    usage(
+      'explain report',
+      '--question "How does this work?" --step "Title" --body "..." --files path [--folders path] [--select path] [--zoom path] [--relations from:to] [--info] [--highlight function:name] [--point function:name] [--parent 7]',
+    )
+  }
+  const next = explain.reportExplain(config.dataDir, {
+    question: parsed.question,
+    parent: parsed.parent,
+    steps: parsed.steps,
+  })
+  if (parsed.parent) {
+    const added = next.steps.filter((step) =>
+      explain.isExplainDescendant(step.index, parsed.parent),
+    ).length
+    console.log(
+      `VISUAL_CODER_EXPLAIN_READY Reported ${added} follow-up step(s) under ${parsed.parent} for "${parsed.question || next.question}". Walk ${parsed.parent}.1 … then continue at the next parent step.`,
+    )
+  } else {
+    console.log(
+      `VISUAL_CODER_EXPLAIN_READY Reported ${next.steps.length} explanation step(s) for "${next.question}". The user can walk them on the map.`,
+    )
+  }
+  console.log(
+    'Run inbase explain wait for a question about the current step, or until the user exits.',
+  )
+}
+
+async function waitForExplain(explain, dataDir, args) {
+  const timeoutMs = Number(takeFlagValue(args, '--timeout') ?? 600000)
+  const started = Date.now()
+  const explainFile = path.join(dataDir, explain.EXPLAIN_FILE)
+  const gate = createManifestGate(explainFile)
+  let lastWaiting = null
+  try {
+    while (Date.now() - started < timeoutMs) {
+      const current = explain.readExplain(dataDir)
+      if (!current.active) {
+        printAck('stopped', 'explain mode was closed')
+        console.log(
+          'VISUAL_CODER_EXPLAIN_STOPPED The user exited explain mode. Do not report more steps.',
+        )
+        process.exit(2)
+      }
+      if (current.pendingStart) {
+        const request = explain.consumeExplainStart(dataDir)
+        if (!request) continue
+        const quoted = JSON.stringify(request.question)
+        printAck('explain', explain.explainTargetLabel(request))
+        console.log(
+          `VISUAL_CODER_EXPLAIN The user clicked Explain on the ${explain.explainTargetLabel(request)}. Replace the current explanation. Do not edit project files. Do not report sub-steps. Do not start the map walk overlay. The visualizer shows a single-explanation card. Run: npx inbase explain start --question ${quoted} Then inspect that ${request.kind} and where it fits in the codebase, and report one explanation with npx inbase explain report --question ${quoted} --step "..." --body "...". Use a single --step. Then run npx inbase explain wait again.`,
+        )
+        process.exit(0)
+      }
+      if (current.pendingQuestion && !current.answering) {
+        const asked = explain.consumeExplainQuestion(dataDir)
+        if (!asked) continue
+        const insertParent = asked.parent
+        const aboutId = asked.from && asked.from !== asked.parent ? asked.from : asked.parent
+        const about =
+          current.steps.find((step) => step.index === aboutId) ??
+          current.steps.find((step) => step.index === insertParent)
+        const title = asked.fromTitle || about?.title || `step ${aboutId}`
+        printAck('question', `step ${aboutId}`)
+        console.log(
+          `VISUAL_CODER_EXPLAIN_QUESTION The user asked about step ${aboutId}: ${title}. Do not replace the whole explanation. Report one-level sub-steps under ${insertParent} with --parent "${insertParent}". This replaces any current sub-steps. Do not nest further (no ${insertParent}.1.1).`,
+        )
+        console.log(`VISUAL_CODER_PARENT ${insertParent}`)
+        console.log(`VISUAL_CODER_INSTRUCTION_START\n${asked.question}\nVISUAL_CODER_INSTRUCTION_END`)
+        console.log(
+          `Run: npx inbase explain report --parent "${insertParent}" --question ${JSON.stringify(asked.question)} --step "..." --body "..." --files path [--folders path] [--select path] [--zoom path] [--relations from:to] [--info] [--highlight function:name] [--point function:name]. Repeat --step for ${insertParent}.1, ${insertParent}.2, … Then run npx inbase explain wait again.`,
+        )
+        process.exit(0)
+      }
+      const waiting = 'Waiting for a question on an explanation step...'
+      if (waiting !== lastWaiting) {
+        console.log(waiting)
+        lastWaiting = waiting
+      }
+      await gate.wait(50)
+    }
+  } finally {
+    gate.close()
+  }
+
+  printAck('timeout', 'no explain question')
+  console.error(
+    'Timed out waiting for an explain question. Do not report more steps.',
+  )
+  process.exit(3)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jkwd/inbase",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "A first-person 3D map of a codebase, with a visual coding workflow for Cursor.",
   "license": "MIT",
   "author": "Joris Kuijper",
@@ -45,6 +45,8 @@
     "apps/explorer/src/ui",
     "apps/explorer/scripts/branch-changes.d.ts",
     "apps/explorer/scripts/branch-changes.mjs",
+    "apps/explorer/scripts/explain-store.d.ts",
+    "apps/explorer/scripts/explain-store.mjs",
     "apps/explorer/scripts/js-source.mjs",
     "apps/explorer/scripts/open-editor.d.ts",
     "apps/explorer/scripts/open-editor.mjs",
@@ -76,6 +78,7 @@
     "@react-three/drei": "^9.117.3",
     "@react-three/fiber": "^8.17.10",
     "@vitejs/plugin-react": "^4.3.4",
+    "kokoro-js": "^1.2.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "three": "^0.170.0",

package/skill/commands/amber.md

@@ -0,0 +1,23 @@
+---
+description: Attach this chat to the Amber Inbase session
+---
+
+The user invoked `/amber`. Attach this chat to the **Amber** Inbase session, not the next empty slot.
+
+Do **not** ask for a session id. Do **not** run `inbase start-session`.
+
+1. Attach to the Amber session:
+
+```bash
+npx inbase attach --color amber
+```
+
+If attach fails with `VISUAL_CODER_NOT_RUNNING`, `VISUAL_CODER_CHAT_LIMIT`, `VISUAL_CODER_COLOR_BUSY`, or `VISUAL_CODER_COLOR_UNKNOWN`, reply with that message and stop.
+
+2. Read `VISUAL_CODER_SESSION` from the output. That id is the session to use for every later `inbase` command.
+
+3. Continue the Inbase visual edits skill from `wait-for-blueprint` onward with that `--session` id. Attach already started the session. `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files; it does not wait.
+
+The user's request is:
+
+$ARGUMENTS

package/skill/commands/blue.md

@@ -0,0 +1,13 @@
+---
+description: Blue is the global blueprint, not an Inbase chat
+---
+
+The user invoked `/blue`. Blue is the **global blueprint**, not a chat slot. There is no Blue LLM session.
+
+Reply with exactly this, then stop. Do not run `inbase attach`.
+
+Blue is the global blueprint, not a chat. Connect with `/coral`, `/amber`, `/lime`, `/orange`, or `/violet` (or `/red`, `/yellow`, `/green`, `/purple`).
+
+The user's request was:
+
+$ARGUMENTS

package/skill/commands/coral.md

@@ -0,0 +1,23 @@
+---
+description: Attach this chat to the Coral Inbase session
+---
+
+The user invoked `/coral`. Attach this chat to the **Coral** Inbase session, not the next empty slot.
+
+Do **not** ask for a session id. Do **not** run `inbase start-session`.
+
+1. Attach to the Coral session:
+
+```bash
+npx inbase attach --color coral
+```
+
+If attach fails with `VISUAL_CODER_NOT_RUNNING`, `VISUAL_CODER_CHAT_LIMIT`, `VISUAL_CODER_COLOR_BUSY`, or `VISUAL_CODER_COLOR_UNKNOWN`, reply with that message and stop.
+
+2. Read `VISUAL_CODER_SESSION` from the output. That id is the session to use for every later `inbase` command.
+
+3. Continue the Inbase visual edits skill from `wait-for-blueprint` onward with that `--session` id. Attach already started the session. `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files; it does not wait.
+
+The user's request is:
+
+$ARGUMENTS

package/skill/commands/explain.md

@@ -0,0 +1,77 @@
+---
+description: Explain a codebase question on the Inbase map
+---
+
+The user invoked `/explain`. Do **not** attach an Inbase coding session. Do **not** edit project files. Do **not** run `inbase start-session`.
+
+Explain mode only runs on the map. Start it so the visualizer switches to a map-only overlay, then walk the question step by step on that map.
+
+The user's question is:
+
+$ARGUMENTS
+
+1. Start explain mode (requires `npx inbase run`):
+
+```bash
+npx inbase explain start --question "$ARGUMENTS"
+```
+
+If that fails with `VISUAL_CODER_NOT_RUNNING`, reply with that message and stop.
+
+2. Reply in this chat first with one short sentence that you opened explain mode on the map.
+
+3. Read the codebase for this question. Use the map's files and folders as the source of truth: file ids are repo-relative paths.
+
+4. Report the explanation as ordered steps. Each step can highlight files and folders, select a block to show import relations, and zoom the map:
+
+```bash
+npx inbase explain report \
+  --question "$ARGUMENTS" \
+  --step "Short title" \
+  --body "What this step is showing." \
+  --files path/to/file.ts \
+  --folders path/to/folder \
+  --select path/to/file.ts \
+  --zoom path/to/folder \
+  --relations path/to/file.ts:path/to/other.ts \
+  --info \
+  --highlight function:currentExplainStep \
+  --point function:currentExplainStep
+```
+
+Repeat `--step` for every step. Flags after a `--step` apply to that step. Use `--imported-by` when the step should show who imports the selected file. `--files` and `--folders` stay at full opacity; everything else on the map goes to 0.5. `--select` clicks that block so its relations draw. `--zoom` frames that folder or file.
+
+`--info` opens the file info panel (functions, vars, classes). Pass `--info path/to/file.ts` to choose the file; otherwise it uses `--select` or the first `--files` path. `--highlight function:name` (or `variable:`, `class:`, or a bare name) lights those symbols in the panel. `--point function:name` draws an arrow from this step to that row. `--point file` points at the file title. `--highlight` / `--point` imply `--info`.
+
+Keep steps small. Prefer real paths from the repo.
+
+5. Wait for a follow-up on a step, or until the user exits:
+
+```bash
+npx inbase explain wait
+```
+
+6. Read the wait output. Reply in this chat with the `VISUAL_CODER_ACK` line first, then:
+
+- Exit `0` (`VISUAL_CODER_ACK explain` / `VISUAL_CODER_EXPLAIN`): the user clicked `?` on a file, folder, or symbol. Replace the current explanation. Do not use `--parent`. Do not walk the map. Read the path from the ACK line, then start and report **one** explanation for the modal:
+
+```bash
+npx inbase explain start --question "Explain the function of the file path/to/file.ts and where it fits in the codebase."
+```
+
+Use the printed `--question` text. Then inspect that file or folder and report a single `--step` / `--body` with `npx inbase explain report`. Then run `npx inbase explain wait` again.
+
+- Exit `0` (`VISUAL_CODER_ACK question` / `VISUAL_CODER_EXPLAIN_QUESTION`): the user asked about the printed parent step. Do not replace the whole explanation. Read the question between `VISUAL_CODER_INSTRUCTION_START` and `VISUAL_CODER_INSTRUCTION_END`. Report closer sub-steps with `--parent` (they become `7.1`, `7.2`, … and Next walks those until the original next step):
+
+```bash
+npx inbase explain report \
+  --parent "7" \
+  --question "the user's follow-up" \
+  --step "Closer look" \
+  --body "What this sub-step is showing." \
+  --files path/to/file.ts
+```
+
+Then run `npx inbase explain wait` again. Asking another question replaces the current sub-steps. Sub-steps stay one level (`7.1`, `7.2`) — never `7.1.1`. If they asked from `7.1`, still report with `--parent "7"`.
+
+- Exit `2` (`VISUAL_CODER_ACK stopped` / `VISUAL_CODER_EXPLAIN_STOPPED`) or `3` (`VISUAL_CODER_ACK timeout`): stop. Do not attach a coding session.

package/skill/commands/green.md

@@ -0,0 +1,23 @@
+---
+description: Attach this chat to the Lime (green) Inbase session
+---
+
+The user invoked `/green`. Attach this chat to the **Lime** Inbase session, not the next empty slot.
+
+Do **not** ask for a session id. Do **not** run `inbase start-session`.
+
+1. Attach to the Lime session:
+
+```bash
+npx inbase attach --color green
+```
+
+If attach fails with `VISUAL_CODER_NOT_RUNNING`, `VISUAL_CODER_CHAT_LIMIT`, `VISUAL_CODER_COLOR_BUSY`, or `VISUAL_CODER_COLOR_UNKNOWN`, reply with that message and stop.
+
+2. Read `VISUAL_CODER_SESSION` from the output. That id is the session to use for every later `inbase` command.
+
+3. Continue the Inbase visual edits skill from `wait-for-blueprint` onward with that `--session` id. Attach already started the session. `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files; it does not wait.
+
+The user's request is:
+
+$ARGUMENTS

package/skill/commands/inbase.md

@@ -1,17 +1,19 @@
 ---
-description: Attach this chat to the next waiting Inbase visualizer session
+description: Attach this chat to the next empty Inbase session
 ---
 
-The user invoked `/inbase`. This is how a chat joins the visualizer session that **Setup LLM session** already created.
+The user invoked `/inbase`. Attach this chat to the next unconnected Inbase session. You do not need this command — a regular Cursor chat does the same thing.
 
-Do **not** ask for a session id. Do **not** run `inbase start-session`. Do **not** print the "direct chat interaction not allowed" message.
+Do **not** ask for a session id. Do **not** run `inbase start-session`.
 
-1. Attach to the next waiting visualizer session (oldest first; skip sessions that already have an LLM):
+1. Attach to the next unconnected visualizer session (oldest first; skip sessions that already have an LLM):
 
 ```bash
 npx inbase attach
 ```
 
+If attach fails with `VISUAL_CODER_NOT_RUNNING`, `VISUAL_CODER_CHAT_LIMIT`, `VISUAL_CODER_COLOR_BUSY`, or `VISUAL_CODER_COLOR_UNKNOWN`, reply with that message and stop.
+
 2. Read `VISUAL_CODER_SESSION` from the output. That id is the session to use for every later `inbase` command.
 
-3. Continue the Inbase visual edits skill from `wait-for-blueprint` onward with that `--session` id. `/inbase` already started the session. `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files; it does not wait.
+3. Continue the Inbase visual edits skill from `wait-for-blueprint` onward with that `--session` id. Attach already started the session. `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files; it does not wait.