@jkwd/inbase 0.1.8 → 0.1.10

package/apps/explorer/src/ui/HUD.tsx

@@ -29,6 +29,16 @@ function reviewTitle(status: AgentIntentStatus) {
   return 'Visual workflow'
 }
 
+function sessionTabLabel(intent: AgentIntent, sessions: AgentIntent[]) {
+  const title = intent.feature?.trim() || reviewTitle(intent.status)
+  const same = sessions.filter(
+    (item) => (item.feature?.trim() || reviewTitle(item.status)) === title,
+  )
+  if (same.length < 2) return title
+  const id = intent.sessionId ?? ''
+  return `${title} · ${id.slice(-4)}`
+}
+
 function fileBase(id: string) {
   return id.split('/').pop() ?? id
 }
@@ -264,7 +274,8 @@ function SessionPanel({
   const sessionId = intent.sessionId
   const pending = intent.status === 'pending' && intent.isActiveDiff
   const askingBlueprint = intent.status === 'blueprint_ask'
-  const creatingBlueprint = intent.creationMode || intent.status === 'blueprint'
+  const sendingBlueprint = intent.status === 'blueprint'
+  const canPlace = Boolean(intent.creationMode)
   const preparing = intent.status === 'preparing'
   const planReady = intent.status === 'planned'
   const working = intent.status === 'working' || intent.status === 'replanning'
@@ -286,7 +297,7 @@ function SessionPanel({
   const addedImports = intent.addedImports ?? []
   const changedFunctions = intent.changedFunctions ?? []
   const changedVariables = intent.changedVariables ?? []
-  const doneSteps = new Set(
+  const acceptedSteps = new Set(
     intent.status === 'finished'
       ? intent.steps.map((step) => step.index)
       : intent.chain
@@ -297,22 +308,23 @@ function SessionPanel({
           .map((entry) => entry.step),
   )
   if (intent.status === 'approved' && typeof intent.step === 'number') {
-    doneSteps.add(intent.step)
-  }
-  if (pending && typeof intent.step === 'number' && !lastStep) {
-    doneSteps.add(intent.step)
+    acceptedSteps.add(intent.step)
   }
-  const nextStep =
-    intent.status === 'finished'
-      ? null
-      : (intent.steps.find((step) => !doneSteps.has(step.index)) ?? null)
-  const canRunNext =
-    Boolean(nextStep) && (planReady || pending) && !working
-  const canComplete = pending && lastStep
+  const proposalStep =
+    pending && typeof intent.step === 'number' ? intent.step : null
+  const processingStep =
+    working && typeof intent.step === 'number' ? intent.step : null
+  const invokeStep =
+    planReady && !working
+      ? (intent.steps.find((step) => !acceptedSteps.has(step.index)) ?? null)
+      : null
+  const canRunNext = stepByStep && Boolean(invokeStep)
+  const canAcceptProposal = proposalStep !== null
   const panelDone =
     intent.status === 'finished' ||
     intent.status === 'approved' ||
-    doneSteps.size > 0
+    acceptedSteps.size > 0 ||
+    canAcceptProposal
 
   useEffect(() => {
     setInstruction('')
@@ -358,22 +370,26 @@ function SessionPanel({
           {!stepByStep && (
             <p className="hud-mode-hint">
               LLM implements the full plan. You can still walk the diffs, then
-              Complete.
+              Accept proposal.
+            </p>
+          )}
+          {intent.llmIdle && !working && !preparing && (
+            <p className="hud-mode-hint">
+              LLM is idle. Current changes stay on the map.
             </p>
           )}
           {intent.feature && <p className="hud-feature">{intent.feature}</p>}
           {askingBlueprint ? (
             <>
               <p>
-                {intent.canEnterBlueprint
-                  ? 'Place files and folders for this chat, then send them as a blueprint for the LLM?'
-                  : `Blueprint edit mode is active in another chat (${intent.blueprintSessionId}). Finish or stop it before starting here.`}
+                Place files and folders for this chat, then send them as a
+                blueprint for the LLM? You can still add files and islands on
+                later steps.
               </p>
               <div className="hud-decide">
                 <button
                   className="hud-button hud-button-approve"
                   type="button"
-                  disabled={!intent.canEnterBlueprint}
                   onClick={() => act('blueprint_yes')}
                 >
                   Create blueprint
@@ -394,12 +410,12 @@ function SessionPanel({
                 </button>
               </div>
             </>
-          ) : creatingBlueprint ? (
+          ) : sendingBlueprint ? (
             <>
               <p>
                 Walk the map, press <kbd>Space</kbd> for a file and{' '}
                 <kbd>B</kbd> for an island. Send the blueprint when the layout
-                is ready.
+                is ready. You can keep placing files after this handshake.
               </p>
               <div className="hud-decide">
                 <button
@@ -457,50 +473,53 @@ function SessionPanel({
               {intent.reason ? ` · ${intent.reason}` : ''}
             </p>
           )}
-          {!askingBlueprint && !creatingBlueprint && (
+          {!askingBlueprint && !sendingBlueprint && (
             <>
+              {canPlace && (
+                <p>
+                  <kbd>Space</kbd> places a file, <kbd>B</kbd> an island for
+                  this session.
+                </p>
+              )}
               {intent.steps?.length > 0 && (
                 <ol className="hud-steps">
-                  {intent.steps.map((step) => (
-                    <li
-                      key={step.index}
-                      data-current={
-                        intent.status !== 'finished' &&
-                        step.index === intent.step &&
-                        !doneSteps.has(step.index)
-                      }
-                      data-done={doneSteps.has(step.index)}
-                      data-next={
-                        nextStep?.index === step.index &&
-                        !doneSteps.has(step.index)
-                      }
-                    >
-                      <span className="hud-step-index">{step.index}.</span>
-                      <span className="hud-step-main">
-                        <span className="hud-step-title">{step.title}</span>
-                        {((stepByStep &&
-                          canRunNext &&
-                          nextStep?.index === step.index) ||
-                          (canComplete && step.index === intent.step)) && (
-                          <button
-                            className="hud-button hud-button-approve hud-run-step"
-                            type="button"
-                            onClick={() =>
-                              canComplete && step.index === intent.step
-                                ? act('continue')
-                                : act('invoke', {
-                                    step: step.index,
-                                  })
-                            }
-                          >
-                            {canComplete && step.index === intent.step
-                              ? 'Complete'
-                              : 'Run step'}
-                          </button>
-                        )}
-                      </span>
-                    </li>
-                  ))}
+                  {intent.steps.map((step) => {
+                    const proposed = proposalStep === step.index
+                    const processing = processingStep === step.index
+                    const accepted = acceptedSteps.has(step.index)
+                    return (
+                      <li
+                        key={step.index}
+                        data-done={accepted || proposed}
+                        data-active={processing || proposed}
+                      >
+                        <span className="hud-step-index">{step.index}.</span>
+                        <span className="hud-step-main">
+                          <span className="hud-step-title">{step.title}</span>
+                          {((canRunNext && invokeStep?.index === step.index) ||
+                            (canAcceptProposal && proposed)) && (
+                            <button
+                              className="hud-button hud-button-approve hud-run-step"
+                              type="button"
+                              onClick={() =>
+                                proposed
+                                  ? lastStep
+                                    ? act('continue')
+                                    : act('invoke', {
+                                        step: step.index + 1,
+                                      })
+                                  : act('invoke', {
+                                      step: step.index,
+                                    })
+                              }
+                            >
+                              {proposed ? 'Accept proposal' : 'Run step'}
+                            </button>
+                          )}
+                        </span>
+                      </li>
+                    )
+                  })}
                 </ol>
               )}
               {intent.chain.length > 0 && (
@@ -661,15 +680,6 @@ function SessionPanel({
                     />
                   </label>
                   <div className="hud-decide">
-                    {lastStep && (
-                      <button
-                        className="hud-button hud-button-approve"
-                        type="button"
-                        onClick={() => act('continue')}
-                      >
-                        Complete
-                      </button>
-                    )}
                     <button
                       className="hud-button hud-button-extend"
                       type="button"
@@ -732,7 +742,7 @@ function InstructionList({ items }: { items: ExplorerInstruction[] }) {
 }
 
 function explorerInstructions({
-  creatingBlueprint,
+  canPlace,
   hasChangeSet,
   changePathsOnly,
   selectedUserCreated,
@@ -742,7 +752,7 @@ function explorerInstructions({
   canStop,
   sessionCount,
 }: {
-  creatingBlueprint: boolean
+  canPlace: boolean
   hasChangeSet: boolean
   changePathsOnly: boolean
   selectedUserCreated: boolean
@@ -753,7 +763,7 @@ function explorerInstructions({
   sessionCount: number
 }): ExplorerInstructionSection[] {
   const backspace: ExplorerInstruction[] =
-    selectedUserCreated && creatingBlueprint
+    selectedUserCreated && canPlace
       ? [{ id: 'backspace', keys: ['Backspace'], label: 'Delete' }]
       : []
   const info: ExplorerInstruction[] = [
@@ -796,7 +806,7 @@ function explorerInstructions({
         { id: 'wasd', keys: ['W', 'A', 'S', 'D'], label: 'Walk' },
         { id: 'mouse-look', keys: ['Mouse'], label: 'Look around' },
         { id: 'shift', keys: ['Shift'], label: 'Sprint' },
-        ...(creatingBlueprint
+        ...(canPlace
           ? [
               { id: 'space', keys: ['Space'], label: 'Place file' },
               { id: 'b-island', keys: ['B'], label: 'Place island' },
@@ -856,7 +866,7 @@ function explorerInstructions({
           keys: ['Click'],
           label: 'An island for its files',
         },
-        ...(creatingBlueprint
+        ...(canPlace
           ? [
               { id: 'select-island', keys: ['Click'], label: 'Select an island' },
               {
@@ -1042,9 +1052,7 @@ export function HUD({
   const [thumbnailMinimized, setThumbnailMinimized] = useState(false)
   const [thumbnailMaximized, setThumbnailMaximized] = useState(false)
   const infoPanelRef = useRef<HTMLDivElement>(null)
-  const creatingBlueprint = sessions.some(
-    (item) => item.creationMode || item.status === 'blueprint',
-  )
+  const canPlace = Boolean(intent.creationMode)
   const previewing = intent.preview
   const addedFunctions = intent.addedFunctions ?? []
   const addedVariables = intent.addedVariables ?? []
@@ -1111,7 +1119,7 @@ export function HUD({
     (item) => !selected?.imports.includes(item.from),
   )
   const canEditBlueprint =
-    creatingBlueprint && Boolean(selected) && !selected?.id.startsWith('draft:')
+    canPlace && Boolean(selected) && !selected?.id.startsWith('draft:')
   const canInspectFile = (fileId: string, userCreated = false) =>
     Boolean(onInspectFile) &&
     !fileId.startsWith('draft:') &&
@@ -1268,7 +1276,7 @@ export function HUD({
   }, [instructionsOpen])
 
   const instructionSections = explorerInstructions({
-    creatingBlueprint,
+    canPlace,
     hasChangeSet,
     changePathsOnly,
     selectedUserCreated: Boolean(selected?.userCreated),
@@ -1298,7 +1306,7 @@ export function HUD({
             <p>
               <kbd>W</kbd> <kbd>A</kbd> <kbd>S</kbd> <kbd>D</kbd> walk,{' '}
               <kbd>Shift</kbd> sprint
-              {creatingBlueprint ? (
+              {canPlace ? (
                 <>
                   , <kbd>Space</kbd> place a file, <kbd>B</kbd> place an island
                 </>
@@ -1362,19 +1370,39 @@ export function HUD({
 
       {sessions.length > 0 && (
         <div className="hud-left-stack">
-          {sessions.map((session) => (
-            <SessionPanel
-              key={session.sessionId}
-              intent={session}
-              focused={session.sessionId === (focusedSessionId ?? intent.sessionId)}
-              naming={naming}
-              onFocus={() => {
-                if (session.sessionId) onFocusSession?.(session.sessionId)
-              }}
-              onWorkflowAction={onWorkflowAction}
-              onNavigateDiff={onNavigateDiff}
-            />
-          ))}
+          {sessions.length > 1 && (
+            <div className="hud-session-tabs" role="tablist" aria-label="LLM sessions">
+              {sessions.map((session) => {
+                const active =
+                  session.sessionId === (focusedSessionId ?? intent.sessionId)
+                return (
+                  <button
+                    className="hud-button hud-session-tab"
+                    type="button"
+                    role="tab"
+                    aria-selected={active}
+                    data-active={active}
+                    key={session.sessionId}
+                    onClick={() => {
+                      if (session.sessionId) onFocusSession?.(session.sessionId)
+                    }}
+                  >
+                    {sessionTabLabel(session, sessions)}
+                  </button>
+                )
+              })}
+            </div>
+          )}
+          <SessionPanel
+            intent={intent}
+            focused
+            naming={naming}
+            onFocus={() => {
+              if (intent.sessionId) onFocusSession?.(intent.sessionId)
+            }}
+            onWorkflowAction={onWorkflowAction}
+            onNavigateDiff={onNavigateDiff}
+          />
         </div>
       )}
 
@@ -1675,7 +1703,7 @@ export function HUD({
               ))}
             </ul>
           )}
-          {creatingBlueprint && mapping && onMapAddFile && onMapAddFolder && (
+          {canPlace && mapping && onMapAddFile && onMapAddFolder && (
             <div className="hud-decide hud-map-blueprint">
               <button
                 className="hud-button hud-button-approve"

package/apps/explorer/vite.config.ts

@@ -10,7 +10,7 @@ import { dataDir, targetRoot } from './scripts/target-config.mjs'
 import { editorFileUri, openInEditor } from './scripts/open-editor.mjs'
 import {
   answerBlueprint,
-  clearDiffSessions,
+  recoverOpenDiffSessions,
   continueDiff,
   inspectTargetFile,
   invokeStep,
@@ -20,6 +20,7 @@ import {
   sendBlueprint,
   sessionIntent,
   setStepByStep,
+  focusSession,
   stopSession,
   updateBlueprint,
 } from './scripts/session-store.mjs'
@@ -84,8 +85,8 @@ function jsonFilePlugin(): Plugin {
   return {
     name: 'visual-coder-json-files',
     configureServer(server) {
-      clearDiffSessions(dataDir, targetRoot)
-      rescanTarget('after clearing diff sessions')
+      recoverOpenDiffSessions(dataDir, targetRoot)
+      rescanTarget('after recovering diff sessions')
       server.middlewares.use('/api/user-context', (req, res, next) => {
         if (req.method === 'GET') {
           sendJson(res, 200, readUserContext())
@@ -208,6 +209,7 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       action !== 'blueprint_no' &&
       action !== 'blueprint_send' &&
       action !== 'blueprint_update' &&
+      action !== 'focus' &&
       action !== 'set_step_by_step'
     ) {
       sendJson(res, 400, { error: 'invalid workflow action' })
@@ -249,7 +251,9 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         body.sessionId,
         body.diffId,
         body.instruction ?? '',
+        targetRoot,
       )
+      rescanTarget('after withdrawing a patch')
     } else if (action === 'blueprint_yes') {
       answerBlueprint(dataDir, body.sessionId, true)
     } else if (action === 'blueprint_no') {
@@ -270,6 +274,8 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         addedVariables: body.addedVariables,
         addedImports: body.addedImports,
       })
+    } else if (action === 'focus') {
+      focusSession(dataDir, body.sessionId)
     } else if (action === 'set_step_by_step') {
       if (typeof body.stepByStep !== 'boolean') {
         sendJson(res, 400, { error: 'stepByStep is required' })

package/bin/session.mjs

@@ -88,8 +88,8 @@ export async function waitForBlueprint(args) {
       const islands = blueprint.userCreatedIslands ?? []
       console.log(
         blueprint.enabled
-          ? `VISUAL_CODER_BLUEPRINT_READY The user sent ${blocks.length} file(s) and ${islands.length} island(s) for this chat. The blueprint is leading: create those paths and honor addedFunctions, addedVariables, and addedImports even if they are not on disk. 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.`
-          : 'VISUAL_CODER_BLUEPRINT_READY The user skipped the blueprint. Continue without user-placed files or islands.',
+          ? `VISUAL_CODER_BLUEPRINT_READY The user sent ${blocks.length} file(s) and ${islands.length} island(s) for this chat. The blueprint is leading: create those paths and honor addedFunctions, addedVariables, and addedImports even if they are not on disk. 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 still place files and islands on later steps; re-read this session's blueprint.json before each step.`
+          : 'VISUAL_CODER_BLUEPRINT_READY The user skipped the initial blueprint. They can still place files and islands on later steps; re-read this session\'s blueprint.json before each step. Continue without user-placed files until that file is enabled.',
       )
       console.log('VISUAL_CODER_BLUEPRINT_START')
       console.log(JSON.stringify(blueprint, null, 2))
@@ -157,8 +157,8 @@ export async function waitForApproval(args) {
       ? `Waiting for the user to invoke step ${afterAdvance.currentStep}...`
       : afterAdvance.phase === 'review' && afterAdvance.diffs?.at(-1)
         ? afterAdvance.stepByStep === false
-          ? `Waiting for the finish step after ${afterAdvance.diffs.at(-1).id}...`
-          : `Waiting for the user to run the next step after ${afterAdvance.diffs.at(-1).id}...`
+          ? `Waiting for the user to accept the proposal after ${afterAdvance.diffs.at(-1).id}...`
+          : `Waiting for the user to accept the proposal on ${afterAdvance.diffs.at(-1).id}...`
         : `Waiting for the visual workflow in session ${sessionId}...`,
   )
 
@@ -185,7 +185,7 @@ export async function waitForApproval(args) {
     if (manifest.phase === 'working') {
       const next = manifest.steps.find((step) => step.index === manifest.currentStep)
       console.log(
-        `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${next ? `: ${next.title}` : ''}. Implement only this step, publish its incremental diff with inbase propose-patch --session ${sessionId}, then wait again.`,
+        `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${next ? `: ${next.title}` : ''}. Re-read this session's blueprint.json before implementing; the user can place files and islands on any step. Patch files are the source of truth: write only this step's unified diff against the current live files (baseline + accepted patches), publish it with inbase propose-patch --session ${sessionId}, then wait again. Do not Write, StrReplace, or Delete project files.`,
       )
       process.exit(0)
     }
@@ -194,7 +194,7 @@ export async function waitForApproval(args) {
         ? `\nVISUAL_CODER_INSTRUCTION_START\n${manifest.pendingInstruction}\nVISUAL_CODER_INSTRUCTION_END`
         : ''
       console.log(
-        `VISUAL_CODER_REPLAN Keep accepted steps before step ${manifest.currentStep}. Replace the plan from step ${manifest.currentStep} onward using the instruction below. The session blueprint remains leading; if this instruction would differ from it, ask the user before replacing the plan. Report the revised tail with inbase report-plan, then wait for invocation.${instruction}`,
+        `VISUAL_CODER_REPLAN Keep accepted patch files before step ${manifest.currentStep}. Replace the withdrawn step with a new patch against those live files, not against the withdrawn proposal. Do not edit project files. The session blueprint remains leading; if this instruction would differ from it, ask the user before replacing the plan. Report the revised tail with inbase report-plan, then wait for invocation.${instruction}`,
       )
       process.exit(4)
     }
@@ -259,9 +259,9 @@ export async function proposePatch(args) {
   const last = entry.step >= manifest.steps.length
   console.log(
     manifest.phase === 'working'
-      ? `VISUAL_CODER_STEP_READY Published diff ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Step by step is off, so the next step is already invoked. Wait again.`
+      ? `VISUAL_CODER_STEP_READY Stored patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Applied the live patch files. Do not edit project files. Step by step is off, so the next step is already invoked. Wait again.`
       : last
-        ? `VISUAL_CODER_STEP_READY Published diff ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Walk the diffs, then Complete to finish.`
-        : `VISUAL_CODER_STEP_READY Published diff ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Wait for Continue or an alternative instruction.`,
+        ? `VISUAL_CODER_STEP_READY Stored patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Applied the live patch files. Do not edit project files. Walk the diffs, then Accept proposal to finish.`
+        : `VISUAL_CODER_STEP_READY Stored patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Applied the live patch files. Do not edit project files. Wait for Accept proposal or an alternative instruction.`,
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jkwd/inbase",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A first-person 3D map of a codebase, with a visual coding workflow for Cursor.",
   "repository": {
     "type": "git",

package/skill/inbase/SKILL.md

@@ -3,8 +3,10 @@ name: inbase
 description: >-
   Grounds source-file changes in the Inbase visual map. Use when creating,
   editing, or deleting application source files in this repository. Lists every
-  feature step, then works only via patch files. Do not use for git, docs-only,
-  lockfiles, or questions.
+  feature step, then works only via patch files. Patch files are the single
+  source of truth: never Write, StrReplace, or Delete project files; only write
+  a unified diff and publish it. Do not use for git, docs-only, lockfiles, or
+  questions.
 ---
 
 # Inbase visual edits
@@ -14,13 +16,19 @@ Skip it for git, lockfiles, `.inbase`, `.cursor`, or questions with no code
 changes.
 
 The LLM uses a plan-first loop. It reports the complete plan before writing a
-patch. When **Step by step** is on, it waits for the user to invoke the
-highlighted step, publishes only that step's diff, then waits for **Run step**
-on the following step or an alternative instruction. When **Step by step** is
+patch. When **Step by step** is on, it waits for the user to invoke the first
+step, publishes only that step's diff, then waits for **Accept proposal** on
+that step or an alternative instruction. When **Step by step** is
 off, `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE` for every
-remaining step without the user clicking Run step; after the last patch, wait
-for the user to **Complete**. They can still walk Previous/Next over the diffs.
-Always work via patch files. Do not Write, StrReplace, or Delete project files.
+remaining step without the user clicking; after the last patch, wait
+for the user to **Accept proposal**. They can still walk Previous/Next over the diffs.
+
+**Patch files are the single source of truth.** Do not Write, StrReplace, or
+Delete project files. Only write a unified diff and publish it with
+`inbase propose-patch`. That command stores the patch and applies the live
+patch chain (baseline + accepted patches + this step). A later instruction
+replaces the withdrawn step's patch; write the new diff against the accepted
+live files, not against the withdrawn proposal.
 
 Every Cursor chat has an explicit session ID. Pass that same ID to every
 command. The visualizer stores immutable diffs under `.inbase/diff-sessions/<session-id>/diffs/`.
@@ -45,9 +53,12 @@ npx inbase wait-for-blueprint --session "<current-cursor-chat-id>"
 ```
 
    The explorer asks **Setup blueprint: Yes vs No**.
-   - **No**: skip placement; continue without user-placed files or islands.
+   - **No**: skip the initial placement. The user can still place files and
+     islands on later steps; re-read this session's `blueprint.json` before
+     each step.
    - **Yes**: the user places files (`Space`) and islands (`B`), then clicks
-     **Send blueprint**.
+     **Send blueprint**. They can keep placing on later steps. This chat's
+     blueprint is stored only for this session.
 3. Read the handshake output between `VISUAL_CODER_BLUEPRINT_START` and
    `VISUAL_CODER_BLUEPRINT_END`, or read
    `.inbase/diff-sessions/<session-id>/blueprint.json`.
@@ -92,8 +103,11 @@ npx inbase wait-for-approval --session "<current-cursor-chat-id>"
 ```
 
    Do not write a patch until this prints `VISUAL_CODER_EXECUTE`. If Step by
-   step is off, this returns immediately for each remaining step.
-9. Implement only the invoked step as a unified diff. Paths are relative to the
+   step is off, this returns immediately for each remaining step. Before
+   implementing, re-read this session's `blueprint.json`; the user can place
+   files and islands on any step.
+9. Implement only the invoked step as a unified diff against the current live
+   files (baseline + accepted patch files). Paths are relative to the
    project root (same ids as `codebase.json`):
 
 ```diff
@@ -122,12 +136,15 @@ npx inbase propose-patch \
 ```
 
    The patch path or stdin is required. Never write or replace a patch already
-   stored in the session folder.
+   stored in the session folder. `inbase propose-patch` stores the new file and
+   applies the live patch chain. Do not `git apply`, copy files, or edit
+   project files yourself.
 
-10. **Stop.** Do not apply the patch and do not edit project files directly.
-11. Wait until the user clicks **Run step** on the next step (or, when Step by
+10. **Stop.** Do not edit project files. The stored patch files are already the
+    live tree.
+11. Wait until the user clicks **Accept proposal** on the current step (or, when Step by
    step is off, until the next step is auto-invoked), sends an alternative
-   instruction, clicks **Complete** on the last step, or stops the workflow:
+   instruction, or stops the workflow:
 
 ```bash
 npx inbase wait-for-approval --session "<current-cursor-chat-id>"
@@ -135,15 +152,18 @@ npx inbase wait-for-approval --session "<current-cursor-chat-id>"
 
 12. Read the wait command output:
 
-   - Exit `0` (`VISUAL_CODER_EXECUTE`): the highlighted step was invoked. Build
-     only that step, publish its incremental diff with `inbase propose-patch`,
-     then wait again.
+   - Exit `0` (`VISUAL_CODER_EXECUTE`): the highlighted step was invoked. Re-read
+     this session's `blueprint.json` first; the user can place files and islands
+     on any step, not only during the initial blueprint. Build only that step as
+     a unified diff against the live files, publish it with `inbase propose-patch`,
+     then wait again. Do not edit project files.
    - Exit `5` (`VISUAL_CODER_FINISHED`): that was the last step. The visualizer
      already applied the final patch and removed stored session diffs and
      blueprint drafts. Optionally run `--clear` if anything remains, tell the
      user the feature is done, and **stop**. Do not propose another patch.
-   - Exit `4` (`VISUAL_CODER_REPLAN`): do **not** apply files and do not rewrite
-     an earlier diff. Follow the text between
+   - Exit `4` (`VISUAL_CODER_REPLAN`): do **not** edit project files and do not
+     rewrite an earlier accepted patch. The withdrawn proposal is no longer live;
+     disk is baseline + accepted patch files. Follow the text between
      `VISUAL_CODER_INSTRUCTION_START` and `VISUAL_CODER_INSTRUCTION_END`, read
      this session's `blueprint.json` when it is enabled (files, islands,
      `addedFunctions`, `addedVariables`, `addedImports`). The blueprint stays
@@ -151,7 +171,8 @@ npx inbase wait-for-approval --session "<current-cursor-chat-id>"
      replacing the plan. Read `user-context.json` (follow the viewpoint only if
      `followLook` is true), replace the plan from the current step onward using
      `inbase report-plan`, then wait for the user to invoke the first revised
-     step.
+     step. The replacement patch must apply on top of the accepted live files,
+     not the withdrawn proposal.
    - Exit `2` (`VISUAL_CODER_STOPPED`) or `3` (timeout): make no further
      project changes.
 
@@ -172,6 +193,9 @@ npx inbase propose-patch --session "<current-cursor-chat-id>" --clear
 - Read global `user-context.json` for placed files; those live on the session blueprint
 - Follow the user's look when `followLook` is false
 - Write, edit, create, or delete project files directly
+- `git apply`, copy, or otherwise materialize a patch yourself
+- Treat on-disk project files as something to edit; they are a replay of the
+  stored patch files
 - Announce file lists instead of a patch
 - Write a patch before its plan step is invoked
 - Propose the next step before `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE`