@jkwd/inbase 0.1.18 → 0.1.19

package/README.md

@@ -49,9 +49,9 @@ inbase run --target /path/to/your/project
 
 Inbase does not call a model itself. The visual coding loop currently supports **Cursor**. The installed skill makes the agent work through the map: it reports a plan, waits on the **HUD** (heads-up display — the overlay panel on the 3D map), edits live files for each invoked step, and records that step as a patch. Those stored patches are the session record and are applied on every step update.
 
-Sessions start in the map: click **Setup LLM session**, type an **initial instruction**, optionally place a **blueprint** (`Space` for files, `B` for folders), then open a Cursor chat and run **`/inbase`**. That command connects the chat and starts the work. The layout is the source of truth for the chat. The blueprint is shared across sessions and stays on the map even after those files and folders exist; use **Hide/Show blueprint**, **Clear blueprint**, or **Cleanup blueprint** (drops planned items that already exist). When a session finishes it is discarded; the shared blueprint remains. Restarting the visualizer also starts with no LLM session; leftover session files are not restored.
+Sessions start in the map: click **Setup LLM session**, type an **initial instruction**, optionally drop **context files** for the chat to read, optionally place a **blueprint** (`Space` for files, `B` for folders), then open a Cursor chat and run **`/inbase`**. That command connects the chat and starts the work. The layout is the source of truth for the chat. Dropped context files stay with that session until it ends. The blueprint is shared across sessions and stays on the map even after those files and folders exist; use **Hide/Show blueprint**, **Clear blueprint**, or **Cleanup blueprint** (drops planned items that already exist). When a session finishes it is discarded; the shared blueprint remains. Restarting the visualizer also starts with no LLM session; leftover session files are not restored.
 
-A normal chat request does not open a session. Use `/inbase` after Setup LLM session, or `/skipinbase [request]` to work outside the map. `/inbase` starts the session immediately; `wait-for-blueprint` only reads the optional blueprint.
+A normal chat request does not open a session. Use `/inbase` after Setup LLM session, or `/skipinbase [request]` to work outside the map. `/inbase` starts the session immediately; `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files.
 
 If several sessions are open, `/inbase` attaches the oldest session that is still waiting. Sessions that already have an LLM are skipped, and the map window does not need to be focused.
 

package/apps/explorer/scripts/patch-lib.d.ts

@@ -112,6 +112,7 @@ export const emptyIntent: {
   listening: boolean
   lastAck: { kind: string; detail: string; at: string | null } | null
   initialInstruction: string | null
+  contextFiles: unknown[]
   creationMode: boolean
   canEnterBlueprint: boolean
   blueprintHidden?: boolean

package/apps/explorer/scripts/patch-lib.mjs

@@ -539,6 +539,7 @@ export const emptyIntent = {
   listening: false,
   lastAck: null,
   initialInstruction: null,
+  contextFiles: [],
   creationMode: false,
   canEnterBlueprint: false,
   blueprintHidden: false,

package/apps/explorer/scripts/session-store.d.ts

@@ -17,6 +17,22 @@ export type DiffEntry = {
   decidedAt: string | null
 }
 
+export type SessionContextFile = {
+  id: string
+  name: string
+  storedName: string
+  mimeType: string
+  size: number
+}
+
+export type SessionContextFileInfo = {
+  id: string
+  name: string
+  mimeType: string
+  size: number
+  path?: string
+}
+
 export type DiffManifest = {
   version: number
   sessionId: string
@@ -39,6 +55,7 @@ export type DiffManifest = {
   activeDiffId: string | null
   pendingInstruction: string | null
   initialInstruction?: string | null
+  contextFiles?: SessionContextFile[]
   workStartedAt: string | null
   stepByStep: boolean
   createdAt: string
@@ -61,6 +78,7 @@ export function sessionPaths(
   baseline: string
   baselineFiles: string
   preStep: string
+  context: string
   stopped: string
 }
 export function touchSessionConnection(dataDir: string, sessionId: string): void
@@ -129,6 +147,30 @@ export function setInitialInstruction(
   sessionId: string,
   instruction: string | null | undefined,
 ): DiffManifest
+export const MAX_CONTEXT_FILES: number
+export const MAX_CONTEXT_FILE_BYTES: number
+export const MAX_CONTEXT_TOTAL_BYTES: number
+export function listContextFiles(
+  dataDir: string,
+  sessionId: string,
+): Array<SessionContextFile & { path: string }>
+export function contextFileHandshake(
+  dataDir: string,
+  sessionId: string,
+): {
+  files: Array<{ name: string; path: string; mimeType: string; size: number }>
+  texts: Array<{ name: string; content: string }>
+}
+export function addContextFiles(
+  dataDir: string,
+  sessionId: string,
+  files: unknown,
+): DiffManifest
+export function removeContextFile(
+  dataDir: string,
+  sessionId: string,
+  fileId: string,
+): DiffManifest
 export function readAttachedSession(dataDir: string): string | null
 export function listAttachQueue(dataDir: string): string[]
 export function nextAttachSessionId(dataDir: string): string | null

package/apps/explorer/scripts/session-store.mjs

@@ -16,6 +16,10 @@ import { diffSourceTrees, snapshotSourceTree } from './tree-diff.mjs'
 const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
 const CONNECTED_TTL_MS = 15_000
 const STALLED_WAIT_MS = 2_000
+export const MAX_CONTEXT_FILES = 16
+export const MAX_CONTEXT_FILE_BYTES = 8 * 1024 * 1024
+export const MAX_CONTEXT_TOTAL_BYTES = 24 * 1024 * 1024
+const CONTEXT_TEXT_INLINE_BYTES = 100_000
 
 export function assertSessionId(value) {
   if (typeof value !== 'string' || !SESSION_ID.test(value) || value === '.' || value === '..') {
@@ -65,6 +69,7 @@ export function sessionPaths(dataDir, sessionId) {
     baseline: path.join(root, 'baseline.json'),
     baselineFiles: path.join(root, 'baseline'),
     preStep: path.join(root, 'pre-step'),
+    context: path.join(root, 'context'),
     stopped: path.join(dataDir, 'diff-sessions', `${safeId}.stopped`),
   }
 }
@@ -423,6 +428,129 @@ function blueprintHasContent(blueprint) {
   )
 }
 
+function normalizeContextFiles(value) {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item) => {
+    if (!item || typeof item !== 'object') return []
+    const id = typeof item.id === 'string' ? item.id.trim() : ''
+    const name = typeof item.name === 'string' ? item.name.trim() : ''
+    const storedName =
+      typeof item.storedName === 'string' ? item.storedName.trim() : ''
+    const size = item.size
+    if (!id || !name || !storedName || !Number.isFinite(size) || size < 0) {
+      return []
+    }
+    if (storedName.includes('..') || path.basename(storedName) !== storedName) {
+      return []
+    }
+    return [
+      {
+        id,
+        name,
+        storedName,
+        mimeType:
+          typeof item.mimeType === 'string' && item.mimeType.trim()
+            ? item.mimeType.trim()
+            : 'application/octet-stream',
+        size,
+      },
+    ]
+  })
+}
+
+function safeContextFileName(name) {
+  const base = path.basename(String(name || 'file')).replace(/[\u0000-\u001f]/g, '')
+  const cleaned = base
+    .replace(/[^\w.\- ()[\]]+/g, '_')
+    .replace(/^\.+/, '')
+    .trim()
+  return (cleaned || 'file').slice(0, 120)
+}
+
+function decodeContextFileBytes(file) {
+  if (Buffer.isBuffer(file?.bytes)) return file.bytes
+  if (typeof file?.contentBase64 === 'string' && file.contentBase64.trim()) {
+    if (!/^[A-Za-z0-9+/=\s]+$/.test(file.contentBase64)) {
+      throw new Error('context file content must be base64')
+    }
+    return Buffer.from(file.contentBase64, 'base64')
+  }
+  throw new Error('context file bytes are required')
+}
+
+function contextFileAbsolute(dir, storedName) {
+  const absolute = path.resolve(dir, storedName)
+  const prefix = dir.endsWith(path.sep) ? dir : `${dir}${path.sep}`
+  if (absolute !== dir && !absolute.startsWith(prefix)) {
+    throw new Error(`Invalid context file path ${storedName}`)
+  }
+  return absolute
+}
+
+function publicContextFile(item) {
+  return {
+    id: item.id,
+    name: item.name,
+    mimeType: item.mimeType,
+    size: item.size,
+  }
+}
+
+function isInlineContextText(mimeType, bytes) {
+  if (bytes.length === 0 || bytes.length > CONTEXT_TEXT_INLINE_BYTES) return false
+  if (bytes.includes(0)) return false
+  const mime = typeof mimeType === 'string' ? mimeType.toLowerCase() : ''
+  if (mime.startsWith('audio/') || mime.startsWith('video/')) return false
+  if (mime === 'application/pdf' || mime === 'application/zip') return false
+  if (mime.startsWith('image/') && mime !== 'image/svg+xml') return false
+  if (
+    mime.startsWith('text/') ||
+    mime === 'application/json' ||
+    mime === 'application/javascript' ||
+    mime === 'application/xml' ||
+    mime === 'image/svg+xml' ||
+    mime === 'application/octet-stream' ||
+    mime === ''
+  ) {
+    return true
+  }
+  return !mime.startsWith('image/')
+}
+
+export function listContextFiles(dataDir, sessionId) {
+  const manifest = requireManifest(dataDir, sessionId)
+  const dir = sessionPaths(dataDir, sessionId).context
+  return normalizeContextFiles(manifest.contextFiles).flatMap((item) => {
+    let absolute
+    try {
+      absolute = contextFileAbsolute(dir, item.storedName)
+    } catch {
+      return []
+    }
+    if (!fs.existsSync(absolute)) return []
+    return [{ ...item, path: absolute }]
+  })
+}
+
+export function contextFileHandshake(dataDir, sessionId) {
+  const files = listContextFiles(dataDir, sessionId)
+  const listed = []
+  const texts = []
+  for (const file of files) {
+    listed.push({
+      name: file.name,
+      path: file.path,
+      mimeType: file.mimeType,
+      size: file.size,
+    })
+    const bytes = fs.readFileSync(file.path)
+    if (isInlineContextText(file.mimeType, bytes)) {
+      texts.push({ name: file.name, content: bytes.toString('utf8') })
+    }
+  }
+  return { files: listed, texts }
+}
+
 export function readManifest(dataDir, sessionId) {
   const { manifest } = sessionPaths(dataDir, sessionId)
   const value = readJson(manifest, null)
@@ -448,6 +576,7 @@ export function readManifest(dataDir, sessionId) {
   if (typeof value.stepByStep !== 'boolean') value.stepByStep = true
   value.initialInstruction =
     typeof value.initialInstruction === 'string' ? value.initialInstruction : null
+  value.contextFiles = normalizeContextFiles(value.contextFiles)
   return value
 }
 
@@ -492,9 +621,12 @@ function liveEntries(manifest, diffId) {
   const browsingHistory = selected.id !== manifest.activeDiffId
   return chain.filter((entry) => {
     if (entry.status === 'rejected') return false
-    if (entry.status === 'extended' || entry.status === 'extend') {
+    if (entry.status === 'extended') {
       return browsingHistory && entry.id === selected.id
     }
+    if (entry.status === 'extend') {
+      return entry.id === selected.id
+    }
     return true
   })
 }
@@ -627,6 +759,7 @@ export function sessionIntent(
       typeof manifest.initialInstruction === 'string'
         ? manifest.initialInstruction
         : null,
+    contextFiles: listContextFiles(dataDir, sessionId).map(publicContextFile),
     steps: manifest.steps,
     step: activeView ? manifest.currentStep : selected?.step ?? manifest.currentStep,
     stepByStep: isStepByStep(manifest),
@@ -928,6 +1061,7 @@ export function startSession(dataDir, input) {
     activeDiffId: null,
     pendingInstruction: null,
     initialInstruction: null,
+    contextFiles: [],
     workStartedAt: null,
     createdAt: now,
     updatedAt: now,
@@ -966,6 +1100,7 @@ export function setupSession(dataDir, input = {}) {
     activeDiffId: null,
     pendingInstruction: null,
     initialInstruction: null,
+    contextFiles: [],
     workStartedAt: null,
     createdAt: now,
     updatedAt: now,
@@ -993,6 +1128,92 @@ export function setInitialInstruction(dataDir, sessionId, instruction) {
   return manifest
 }
 
+export function addContextFiles(dataDir, sessionId, files) {
+  const manifest = requireManifest(dataDir, sessionId)
+  if (isTerminalSession(manifest)) {
+    throw sessionStoppedError(sessionId)
+  }
+  const incoming = Array.isArray(files) ? files : files ? [files] : []
+  if (incoming.length === 0) {
+    throw new Error('at least one context file is required')
+  }
+
+  const existing = listContextFiles(dataDir, sessionId)
+  if (existing.length + incoming.length > MAX_CONTEXT_FILES) {
+    throw new Error(`at most ${MAX_CONTEXT_FILES} context files can be attached`)
+  }
+
+  const dir = sessionPaths(dataDir, sessionId).context
+  fs.mkdirSync(dir, { recursive: true })
+  const existingBytes = existing.reduce((sum, item) => sum + item.size, 0)
+  const next = [...existing.map((item) => ({
+    id: item.id,
+    name: item.name,
+    storedName: item.storedName,
+    mimeType: item.mimeType,
+    size: item.size,
+  }))]
+  let addedBytes = 0
+
+  for (const file of incoming) {
+    const bytes = decodeContextFileBytes(file)
+    if (bytes.length === 0) {
+      throw new Error('context file is empty')
+    }
+    if (bytes.length > MAX_CONTEXT_FILE_BYTES) {
+      throw new Error(
+        `context file must be ${MAX_CONTEXT_FILE_BYTES} bytes or smaller`,
+      )
+    }
+    addedBytes += bytes.length
+    if (existingBytes + addedBytes > MAX_CONTEXT_TOTAL_BYTES) {
+      throw new Error(
+        `attached files must total ${MAX_CONTEXT_TOTAL_BYTES} bytes or less`,
+      )
+    }
+    const id = crypto.randomBytes(4).toString('hex')
+    const originalName =
+      typeof file?.name === 'string' ? path.basename(file.name.trim()) : ''
+    const storedName = `${id}-${safeContextFileName(originalName || 'file')}`
+    fs.writeFileSync(contextFileAbsolute(dir, storedName), bytes)
+    next.push({
+      id,
+      name: originalName || storedName,
+      storedName,
+      mimeType:
+        typeof file?.mimeType === 'string' && file.mimeType.trim()
+          ? file.mimeType.trim()
+          : 'application/octet-stream',
+      size: bytes.length,
+    })
+  }
+
+  manifest.contextFiles = next
+  writeManifest(dataDir, manifest)
+  return manifest
+}
+
+export function removeContextFile(dataDir, sessionId, fileId) {
+  const manifest = requireManifest(dataDir, sessionId)
+  if (isTerminalSession(manifest)) {
+    throw sessionStoppedError(sessionId)
+  }
+  const id = typeof fileId === 'string' ? fileId.trim() : ''
+  if (!id) throw new Error('fileId is required')
+  const existing = normalizeContextFiles(manifest.contextFiles)
+  const item = existing.find((file) => file.id === id)
+  if (!item) return manifest
+  const dir = sessionPaths(dataDir, sessionId).context
+  try {
+    fs.unlinkSync(contextFileAbsolute(dir, item.storedName))
+  } catch {
+    // Drop the manifest entry even if the file is already gone.
+  }
+  manifest.contextFiles = existing.filter((file) => file.id !== id)
+  writeManifest(dataDir, manifest)
+  return manifest
+}
+
 function generateVisualizerSessionId(dataDir) {
   for (let attempt = 0; attempt < 8; attempt += 1) {
     const sessionId = `viz-${crypto.randomBytes(6).toString('hex')}`
@@ -1124,6 +1345,7 @@ export function reportPlan(dataDir, input) {
       activeDiffId: null,
       pendingInstruction: null,
       initialInstruction: null,
+      contextFiles: [],
       workStartedAt: null,
       createdAt: now,
       updatedAt: now,
@@ -1299,6 +1521,7 @@ export function appendDiff(dataDir, targetRoot, input) {
   )
   manifest.activeDiffId = id
   manifest.phase = 'review'
+  manifest.pendingInstruction = null
   manifest.workStartedAt = null
   manifest.diffs.push(entry)
   writeManifest(dataDir, manifest)
@@ -1370,11 +1593,12 @@ export function requestReplan(
   active.status = 'extend'
   active.instruction = guidance
   active.decidedAt = new Date().toISOString()
-  manifest.phase = 'replanning'
+  manifest.phase = 'working'
   manifest.pendingInstruction = guidance
   manifest.workStartedAt = new Date().toISOString()
   writeManifest(dataDir, manifest)
-  if (targetRoot) materializeDiff(dataDir, targetRoot, sessionId, active.id)
+  // Keep the current proposal on disk. The instruction updates that latest state.
+  void targetRoot
   return manifest
 }
 

package/apps/explorer/src/App.tsx

@@ -475,10 +475,11 @@ function Explorer({
 
   const flyAlongRelation = useCallback(
     (fromId: string, toId: string) => {
+      if (mode !== 'walk') return
       const [x, z] = walkPos.current
       travelToFile(relationTravelTarget(fromId, toId, x, z, layout.files), true)
     },
-    [layout.files, travelToFile],
+    [layout.files, mode, travelToFile],
   )
 
   const runWorkflowAction = useCallback(

package/apps/explorer/src/agentIntent.ts

@@ -65,6 +65,26 @@ function normalizeAck(
   }
 }
 
+function normalizeContextFiles(value: unknown): NonNullable<AgentIntent['contextFiles']> {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item) => {
+    if (!item || typeof item !== 'object') return []
+    const id = (item as { id?: unknown }).id
+    const name = (item as { name?: unknown }).name
+    const mimeType = (item as { mimeType?: unknown }).mimeType
+    const size = (item as { size?: unknown }).size
+    if (
+      typeof id !== 'string' ||
+      typeof name !== 'string' ||
+      typeof mimeType !== 'string' ||
+      typeof size !== 'number'
+    ) {
+      return []
+    }
+    return [{ id, name, mimeType, size }]
+  })
+}
+
 export const emptyIntent: AgentIntent = {
   updatedAt: null,
   showMap: false,
@@ -101,6 +121,7 @@ export const emptyIntent: AgentIntent = {
   listening: false,
   lastAck: null,
   initialInstruction: null,
+  contextFiles: [],
   creationMode: false,
   canEnterBlueprint: false,
   blueprintHidden: false,
@@ -155,6 +176,7 @@ function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
     lastAck: normalizeAck(data?.lastAck),
     initialInstruction:
       typeof data?.initialInstruction === 'string' ? data.initialInstruction : null,
+    contextFiles: normalizeContextFiles(data?.contextFiles),
     creationMode: Boolean(data?.creationMode),
     canEnterBlueprint: Boolean(data?.canEnterBlueprint),
     blueprintHidden: Boolean(data?.blueprintHidden),
@@ -352,6 +374,50 @@ export function persistInitialInstruction(sessionId: string, instruction: string
   })
 }
 
+export async function persistAddContextFiles(
+  sessionId: string,
+  files: Array<{ name: string; mimeType: string; contentBase64: string }>,
+) {
+  const response = await fetch('/api/agent-intent', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      action: 'add_context_files',
+      sessionId,
+      files,
+    }),
+  })
+  if (!response.ok) {
+    const detail = await response.text()
+    let message = detail || 'Could not attach files'
+    try {
+      const parsed = JSON.parse(detail) as { error?: string }
+      if (parsed?.error) message = parsed.error
+    } catch {
+      // Use the raw body when it is not JSON.
+    }
+    throw new Error(message)
+  }
+  return normalize((await response.json()) as AgentIntent)
+}
+
+export async function persistRemoveContextFile(sessionId: string, fileId: string) {
+  const response = await fetch('/api/agent-intent', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      action: 'remove_context_file',
+      sessionId,
+      fileId,
+    }),
+  })
+  if (!response.ok) {
+    const detail = await response.text()
+    throw new Error(detail || 'Could not remove file')
+  }
+  return normalize((await response.json()) as AgentIntent)
+}
+
 export function persistSessionFocus(sessionId: string) {
   fetch('/api/agent-intent', {
     method: 'POST',

package/apps/explorer/src/index.css

@@ -1133,6 +1133,71 @@ button {
   margin-top: 0;
 }
 
+.hud-context {
+  display: grid;
+  gap: 8px;
+  margin-top: 8px;
+}
+
+.hud-context-drop {
+  width: 100%;
+  min-height: 52px;
+  padding: 10px 8px;
+  color: #8b95a5;
+  background: var(--vc-surface);
+  border: 1px dashed #3a4250;
+  cursor: pointer;
+  font: 12px/1.4 Inter, ui-sans-serif, system-ui, sans-serif;
+  text-align: center;
+}
+
+.hud-context-drop:hover,
+.hud-context-drop:focus-visible,
+.hud-context-drop[data-over='true'] {
+  color: #e7ebf2;
+  border-color: #d6b56a;
+  outline: none;
+}
+
+.hud-context-drop[data-busy='true'],
+.hud-context-drop:disabled {
+  cursor: wait;
+  opacity: 0.7;
+}
+
+.hud-context-list {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.hud-context-list li {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 6px;
+  color: #e7ebf2;
+  font-size: 11px;
+}
+
+.hud-context-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.hud-context-size {
+  color: #8b95a5;
+}
+
+.hud-context-error {
+  margin: 0;
+  color: #ff8a9b;
+  font-size: 11px;
+}
+
 .hud-instruction textarea {
   width: 100%;
   resize: vertical;

package/apps/explorer/src/scene/MapView.tsx

@@ -22,7 +22,6 @@ type MapViewProps = {
   onLand: (x: number, z: number) => void
   onSelect: (fileId: string | null) => void
   onSelectFolder: (folderPath: string | null) => void
-  onTravelTo: (fromId: string, toId: string) => void
   onBlueprintMenu?: (menu: MapBlueprintMenu) => void
 }
 
@@ -36,7 +35,6 @@ export function MapView({
   onLand,
   onSelect,
   onSelectFolder,
-  onTravelTo,
   onBlueprintMenu,
 }: MapViewProps) {
   const size = useThree((state) => state.size)
@@ -157,18 +155,11 @@ export function MapView({
 
       const pick = pickAt(event.clientX, event.clientY)
       if (!pick) return
-      const { relationHit, fileHit } = pick
+      const { fileHit } = pick
       if (fileHit) {
         onSelect(fileHit.object.userData.fileId as string)
         return
       }
-      if (relationHit) {
-        onTravelTo(
-          relationHit.object.userData.relationFrom as string,
-          relationHit.object.userData.relationTo as string,
-        )
-        return
-      }
 
       const hit = new THREE.Vector3()
       const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0)
@@ -286,7 +277,6 @@ export function MapView({
     onBlueprintMenu,
     onSelect,
     onSelectFolder,
-    onTravelTo,
     scene,
     selectedFolder,
   ])

package/apps/explorer/src/scene/World.tsx

@@ -237,7 +237,6 @@ export function World({
         onLand={onLand}
         onSelect={onSelect}
         onSelectFolder={onSelectFolder}
-        onTravelTo={onTravelTo}
         onBlueprintMenu={
           mapping && !placing && onBlueprintMenu ? onBlueprintMenu : undefined
         }

package/apps/explorer/src/types.ts

@@ -324,6 +324,12 @@ export type AgentIntent = {
     at: string | null
   } | null
   initialInstruction?: string | null
+  contextFiles?: Array<{
+    id: string
+    name: string
+    mimeType: string
+    size: number
+  }>
   creationMode: boolean
   canEnterBlueprint: boolean
   blueprintHidden?: boolean

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

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState, type ReactNode } from 'react'
-import { persistInitialInstruction } from '../agentIntent'
+import { persistAddContextFiles, persistInitialInstruction, persistRemoveContextFile } from '../agentIntent'
 import { NameInput } from './NameInput'
 import { SelectionThumbnail } from '../scene/SelectionThumbnail'
 import {
@@ -450,6 +450,119 @@ function InitialInstructionField({
   )
 }
 
+function formatFileSize(bytes: number) {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+async function fileToBase64(file: File) {
+  const bytes = new Uint8Array(await file.arrayBuffer())
+  const chunk = 0x8000
+  let binary = ''
+  for (let offset = 0; offset < bytes.length; offset += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunk))
+  }
+  return btoa(binary)
+}
+
+type ContextFileInfo = {
+  id: string
+  name: string
+  mimeType: string
+  size: number
+}
+
+function ContextFileDrop({
+  files,
+  busy,
+  error,
+  onAdd,
+  onRemove,
+}: {
+  files: ContextFileInfo[]
+  busy: boolean
+  error: string | null
+  onAdd: (files: File[]) => void
+  onRemove: (fileId: string) => void
+}) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [over, setOver] = useState(false)
+
+  const takeFiles = (list: FileList | File[] | null) => {
+    if (!list || busy) return
+    const next = [...list].filter((file) => file.size > 0)
+    if (next.length > 0) onAdd(next)
+  }
+
+  return (
+    <div className="hud-context">
+      <button
+        className="hud-context-drop"
+        type="button"
+        data-over={over}
+        data-busy={busy}
+        disabled={busy}
+        aria-label="Attach files for the LLM"
+        onDragEnter={(event) => {
+          event.preventDefault()
+          if (event.dataTransfer.types.includes('Files')) setOver(true)
+        }}
+        onDragOver={(event) => {
+          event.preventDefault()
+          event.dataTransfer.dropEffect = 'copy'
+        }}
+        onDragLeave={(event) => {
+          if (event.currentTarget.contains(event.relatedTarget as Node)) return
+          setOver(false)
+        }}
+        onDrop={(event) => {
+          event.preventDefault()
+          event.stopPropagation()
+          setOver(false)
+          takeFiles(event.dataTransfer.files)
+        }}
+        onKeyDown={(event) => event.stopPropagation()}
+        onClick={() => inputRef.current?.click()}
+      >
+        <input
+          ref={inputRef}
+          type="file"
+          multiple
+          hidden
+          onChange={(event) => {
+            takeFiles(event.target.files)
+            event.target.value = ''
+          }}
+        />
+        {busy ? 'Attaching…' : 'Drop files or click to attach'}
+      </button>
+      {files.length > 0 && (
+        <ul className="hud-context-list">
+          {files.map((file) => (
+            <li key={file.id}>
+              <span className="hud-context-name" title={file.name}>
+                {file.name}
+              </span>
+              <span className="hud-context-size">{formatFileSize(file.size)}</span>
+              <button
+                className="hud-item-remove"
+                type="button"
+                aria-label={`Remove ${file.name}`}
+                disabled={busy}
+                onClick={() => onRemove(file.id)}
+              >
+                ×
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      {error ? <p className="hud-context-error">{error}</p> : null}
+    </div>
+  )
+}
+
 function blueprintIsDefined(intent: AgentIntent) {
   return (
     (intent.userCreatedBlocks?.length ?? 0) > 0 ||
@@ -464,24 +577,53 @@ function blueprintIsDefined(intent: AgentIntent) {
 function HandshakeSetup({
   instruction,
   onInstructionChange,
+  contextFiles,
+  contextBusy,
+  contextError,
+  onAddContextFiles,
+  onRemoveContextFile,
   blueprintDefined,
   awaitingAttach,
   nextAttachLabel,
 }: {
   instruction: string
   onInstructionChange: (value: string) => void
+  contextFiles: ContextFileInfo[]
+  contextBusy: boolean
+  contextError: string | null
+  onAddContextFiles: (files: File[]) => void
+  onRemoveContextFile: (fileId: string) => void
   blueprintDefined: boolean
   awaitingAttach: boolean
   nextAttachLabel: string | null
 }) {
   return (
     <div className="hud-setup">
-      <section className="hud-setup-section">
+      <section
+        className="hud-setup-section"
+        onDragOver={(event) => {
+          if (event.dataTransfer.types.includes('Files')) event.preventDefault()
+        }}
+        onDrop={(event) => {
+          event.preventDefault()
+          const dropped = [...(event.dataTransfer.files ?? [])].filter(
+            (file) => file.size > 0,
+          )
+          if (dropped.length > 0) onAddContextFiles(dropped)
+        }}
+      >
         <h2 className="hud-setup-heading">Instructions</h2>
         <InitialInstructionField
           value={instruction}
           onChange={onInstructionChange}
         />
+        <ContextFileDrop
+          files={contextFiles}
+          busy={contextBusy}
+          error={contextError}
+          onAdd={onAddContextFiles}
+          onRemove={onRemoveContextFile}
+        />
       </section>
       <section className="hud-setup-section">
         <h2 className="hud-setup-heading">
@@ -649,6 +791,11 @@ function SessionPanel({
   const [initialInstruction, setInitialInstruction] = useState(
     () => intent.initialInstruction ?? '',
   )
+  const [contextFiles, setContextFiles] = useState<ContextFileInfo[]>(
+    () => intent.contextFiles ?? [],
+  )
+  const [contextBusy, setContextBusy] = useState(false)
+  const [contextError, setContextError] = useState<string | null>(null)
   const sessionId = intent.sessionId
   const pending = intent.status === 'pending' && intent.isActiveDiff
   const askingBlueprint = intent.status === 'blueprint_ask'
@@ -710,8 +857,15 @@ function SessionPanel({
 
   useEffect(() => {
     setInitialInstruction(intent.initialInstruction ?? '')
+    setContextFiles(intent.contextFiles ?? [])
+    setContextError(null)
   }, [sessionId])
 
+  useEffect(() => {
+    if (contextBusy) return
+    setContextFiles(intent.contextFiles ?? [])
+  }, [contextBusy, intent.contextFiles])
+
   if (!sessionId || !isReviewingIntent(intent.status)) return null
 
   const updateInitialInstruction = (value: string) => {
@@ -719,6 +873,43 @@ function SessionPanel({
     persistInitialInstruction(sessionId, value)
   }
 
+  const addContextFiles = (files: File[]) => {
+    setContextBusy(true)
+    setContextError(null)
+    void Promise.all(
+      files.map(async (file) => ({
+        name: file.name,
+        mimeType: file.type || 'application/octet-stream',
+        contentBase64: await fileToBase64(file),
+      })),
+    )
+      .then((payload) => persistAddContextFiles(sessionId, payload))
+      .then((next) => {
+        setContextFiles(next.contextFiles ?? [])
+      })
+      .catch((caught) => {
+        setContextError(
+          caught instanceof Error ? caught.message : 'Could not attach files',
+        )
+      })
+      .finally(() => setContextBusy(false))
+  }
+
+  const removeContextFile = (fileId: string) => {
+    setContextBusy(true)
+    setContextError(null)
+    void persistRemoveContextFile(sessionId, fileId)
+      .then((next) => {
+        setContextFiles(next.contextFiles ?? [])
+      })
+      .catch((caught) => {
+        setContextError(
+          caught instanceof Error ? caught.message : 'Could not remove file',
+        )
+      })
+      .finally(() => setContextBusy(false))
+  }
+
   const showInitialInstruction =
     Boolean(intent.awaitingAttach) &&
     (askingBlueprint || sendingBlueprint || preparing)
@@ -800,6 +991,11 @@ function SessionPanel({
             <HandshakeSetup
               instruction={initialInstruction}
               onInstructionChange={updateInitialInstruction}
+              contextFiles={contextFiles}
+              contextBusy={contextBusy}
+              contextError={contextError}
+              onAddContextFiles={addContextFiles}
+              onRemoveContextFile={removeContextFile}
               blueprintDefined={blueprintIsDefined(intent)}
               awaitingAttach={Boolean(intent.awaitingAttach)}
               nextAttachLabel={queuedBehind}
@@ -1437,7 +1633,6 @@ function explorerInstructions({
               },
             ]
           : []),
-        { id: 'click-line', keys: ['Click'], label: 'A line to fly there' },
         {
           id: 'option-click-walk',
           keys: ['Option', 'Click'],

package/apps/explorer/vite.config.ts

@@ -23,6 +23,8 @@ import {
   sendBlueprint,
   sessionIntent,
   setInitialInstruction,
+  addContextFiles,
+  removeContextFile,
   setStepByStep,
   setupSession,
   focusSession,
@@ -265,6 +267,8 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       addedVariables?: unknown[]
       addedImports?: unknown[]
       notes?: unknown[]
+      files?: unknown[]
+      fileId?: string
     }
     const action = body.action
     const blueprintActions = new Set([
@@ -288,6 +292,8 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       action !== 'focus' &&
       action !== 'set_step_by_step' &&
       action !== 'set_initial_instruction' &&
+      action !== 'add_context_files' &&
+      action !== 'remove_context_file' &&
       action !== 'setup_session'
     ) {
       sendJson(res, 400, { error: 'invalid workflow action' })
@@ -342,7 +348,6 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         body.instruction ?? '',
         targetRoot,
       )
-      rescanTarget('after withdrawing a patch')
     } else if (action === 'blueprint_yes') {
       answerBlueprint(dataDir, body.sessionId, true)
     } else if (action === 'blueprint_no') {
@@ -381,6 +386,14 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       return
     } else if (action === 'set_initial_instruction') {
       setInitialInstruction(dataDir, body.sessionId, body.instruction ?? '')
+    } else if (action === 'add_context_files') {
+      addContextFiles(dataDir, body.sessionId, body.files ?? [])
+    } else if (action === 'remove_context_file') {
+      if (!body.fileId) {
+        sendJson(res, 400, { error: 'fileId is required' })
+        return
+      }
+      removeContextFile(dataDir, body.sessionId, body.fileId)
     } else if (action === 'focus') {
       focusSession(dataDir, body.sessionId)
     } else if (action === 'set_step_by_step') {

package/bin/session.mjs

@@ -122,21 +122,37 @@ function emitApprovalHandshake(store, dataDir, sessionId, manifest, initialDiff)
   if (manifest.phase === 'working') {
     const next = manifest.steps.find((step) => step.index === manifest.currentStep)
     const title = next?.title
+    const guidance =
+      typeof manifest.pendingInstruction === 'string'
+        ? manifest.pendingInstruction.trim()
+        : ''
+    const updating = Boolean(guidance)
     signalAck(
       store,
       dataDir,
       sessionId,
       'execute',
-      title
-        ? `step ${manifest.currentStep} — ${title}`
-        : `step ${manifest.currentStep}`,
+      updating
+        ? 'a new instruction'
+        : title
+          ? `step ${manifest.currentStep} — ${title}`
+          : `step ${manifest.currentStep}`,
     )
+    const instruction = updating
+      ? `\nVISUAL_CODER_INSTRUCTION_START\n${guidance}\nVISUAL_CODER_INSTRUCTION_END`
+      : ''
     const continuing = (manifest.diffs?.length ?? 0) > 0
-    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.`,
-    )
+    if (updating) {
+      console.log(
+        `VISUAL_CODER_EXECUTE Update the current proposal for step ${manifest.currentStep}${title ? `: ${title}` : ''}. Live files already contain that proposal — do not reset them. Follow the instruction between VISUAL_CODER_INSTRUCTION_START and END, edit those live files, then inbase propose-patch --session ${sessionId} with no patch file. Do not report a new plan.${instruction}`,
+      )
+    } else {
+      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.`,
+      )
+    }
     process.exit(0)
   }
   if (manifest.phase === 'replanning') {
@@ -145,13 +161,13 @@ function emitApprovalHandshake(store, dataDir, sessionId, manifest, initialDiff)
       dataDir,
       sessionId,
       'replan',
-      `revise the plan from step ${manifest.currentStep}`,
+      `revise the current proposal for step ${manifest.currentStep}`,
     )
     const instruction = manifest.pendingInstruction
       ? `\nVISUAL_CODER_INSTRUCTION_START\n${manifest.pendingInstruction}\nVISUAL_CODER_INSTRUCTION_END`
       : ''
     console.log(
-      `VISUAL_CODER_REPLAN Keep accepted patch files before step ${manifest.currentStep}. Disk is baseline + accepted patches. Do not edit project files until the next EXECUTE. The shared 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 Live files still contain the current proposal for step ${manifest.currentStep}. Do not reset them. Follow the instruction between VISUAL_CODER_INSTRUCTION_START and END, edit those live files, then inbase propose-patch. Do not report a new plan.${instruction}`,
     )
     process.exit(4)
   }
@@ -179,7 +195,7 @@ export async function attachSession(args) {
   console.log(`VISUAL_CODER_SESSION ${manifest.sessionId}`)
   printAck('attached', 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 and instruction; it does not wait.`,
+    `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.`,
   )
 }
 
@@ -243,6 +259,20 @@ export async function waitForBlueprint(args) {
     console.log(instruction)
     console.log('VISUAL_CODER_INSTRUCTION_END')
   }
+  const attached = store.contextFileHandshake(config.dataDir, sessionId)
+  if (attached.files.length > 0) {
+    console.log(
+      'Honor the user\'s attached context files. Read each path with your file tools before planning. They are session-only attachments, not project files to create. Use any printed VISUAL_CODER_CONTEXT_FILE contents directly.',
+    )
+    console.log('VISUAL_CODER_CONTEXT_FILES_START')
+    console.log(JSON.stringify(attached.files, null, 2))
+    console.log('VISUAL_CODER_CONTEXT_FILES_END')
+    for (const file of attached.texts) {
+      console.log(`VISUAL_CODER_CONTEXT_FILE_START ${file.name}`)
+      console.log(file.content)
+      console.log('VISUAL_CODER_CONTEXT_FILE_END')
+    }
+  }
   process.exit(0)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jkwd/inbase",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "A first-person 3D map of a codebase, with a visual coding workflow for Cursor.",
   "license": "MIT",
   "author": "Joris Kuijper",

package/skill/commands/inbase.md

@@ -14,4 +14,4 @@ npx inbase attach
 
 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 and instruction; it does not wait.
+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.

package/skill/inbase/SKILL.md

@@ -85,7 +85,7 @@ new plan.
 ## Required sequence
 
 1. **Read the current layout**. `/inbase` already started the session. Run
-   this once to load the optional blueprint and instruction — it returns
+   this once to load the optional blueprint, instruction, and attached files — it returns
    immediately. Do not wait for the user to send a blueprint. Then report a
    plan.
 
@@ -98,7 +98,11 @@ npx inbase wait-for-blueprint --session "<session-id>"
    keep placing at any time.
    If `wait-for-blueprint` prints `VISUAL_CODER_INSTRUCTION_START` /
    `VISUAL_CODER_INSTRUCTION_END`, that text is the user's request for this
-   session. Plan from that instruction and the blueprint together. The
+   session. If it prints `VISUAL_CODER_CONTEXT_FILES_START` /
+   `VISUAL_CODER_CONTEXT_FILES_END`, those are session-only files the user
+   dropped as initial context. Read each `path` (and any printed
+   `VISUAL_CODER_CONTEXT_FILE` contents). They are not project files to create.
+   Plan from that instruction, attached files, and the blueprint together. The
    instruction does not override an enabled blueprint; if they conflict,
    ask the user.
 3. Read the handshake output between `VISUAL_CODER_BLUEPRINT_START` and
@@ -220,7 +224,7 @@ npx inbase propose-patch --session "<session-id>" --clear
   from **Setup LLM session** in the map
 - Edit files on a direct chat request; reply with the `/skipinbase` line and stop
 - Invent a session id for `/inbase`; run `npx inbase attach` with no `--session`
-- Skip `inbase wait-for-blueprint`; it returns immediately and provides the optional blueprint and instruction
+- Skip `inbase wait-for-blueprint`; it returns immediately and provides the optional blueprint, instruction, and attached files
 - Treat the chat request, viewpoint, or your own plan as overriding an enabled blueprint
 - Skip, rename, relocate, or replace the shared `blueprint.json` files, islands, functions, variables, or imports when `enabled` is true
 - Silently differ from the blueprint; ask the user first