@bahulam/code 2.6.1 → 2.6.3

package/README.md

@@ -9,6 +9,13 @@ prior sessions, and keeps local project context in `~/.bahulam/`.
 - Sub-agents, skills, workflows, and MCP support
 - Bring your own model (40+ supported)
 
+## About the name
+
+**Bahulam** (बहुलम्) is Sanskrit for *abundance*. The name reflects a
+philosophy: tokens are not rationed, model choice is not gated, and
+intelligence is not metered per feature. The restrictions most agents
+ship with are design decisions — ones we chose not to make.
+
 ## Install
 
 ```bash
@@ -56,7 +63,7 @@ skills, workflows, session tools).
 
 - Published under both `@bahulam/code` and `@bahulamai/code` scopes.
 - Full removal of legacy `b0` references from CLI help, error messages,
-  analytics headers, and internal comments.
+  analytics headers, internal comments, and Pulse dashboard.
 
 ## 2.6.0 Highlights
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@bahulam/code",
-  "version": "2.6.1",
-  "description": "Bahulam Code — Bahulam's coding agent. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
+  "version": "2.6.3",
+  "description": "Bahulam Code \u2014 abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {
+    "bahulam": "src/terminal/main.mjs",
     "bahulam-code": "src/terminal/main.mjs"
   },
   "files": [
@@ -13,7 +14,7 @@
   ],
   "scripts": {
     "start": "node src/terminal/main.mjs",
-    "test": "BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-backend-url.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-agent-history.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-sse-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-tool-executor.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-project-artifacts.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-work-scope.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-skills.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-callback.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-rate-limit-display.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-preflight.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-formatter.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-terminal-rendering.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-input-dock.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-slash-commands.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval-log.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-kepler-contract.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-session-manager.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-safety.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-jsonl-writer.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-analytics.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-stagnation.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-attachments.mjs"
+    "test": "BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-backend-url.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-agent-history.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-sse-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-tool-executor.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-project-artifacts.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-work-scope.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-skills.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-callback.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-rate-limit-display.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-preflight.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-formatter.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-terminal-rendering.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-input-dock.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-live-steering-client.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-slash-commands.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-approval-log.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-kepler-contract.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-session-manager.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-safety.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-jsonl-writer.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-analytics.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-stagnation.mjs && BAHULAM_HOME=/tmp/bahulam-code-test-home node test/test-attachments.mjs"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -43,7 +44,11 @@
     "url": "git+https://github.com/raviakasapu/codekepler-npm.git"
   },
   "dependencies": {
+    "pdf-parse": "^1.1.1",
     "tree-sitter-wasms": "^0.1.13",
     "web-tree-sitter": "^0.26.9"
+  },
+  "optionalDependencies": {
+    "@bahulam/runtime-darwin-arm64": "2.6.3"
   }
 }

package/pulse/app/activity/page.tsx

@@ -175,7 +175,7 @@ export default function ActivityPage() {
                     <CalendarDays className="h-4 w-4 shrink-0 text-muted-foreground" />
                     Day of Week
                   </CardTitle>
-                  <CardDescription>Which days you use b0 most</CardDescription>
+                  <CardDescription>Which days you use Bahulam Code most</CardDescription>
                 </CardHeader>
                 <CardContent className="flex flex-1 flex-col justify-between pt-3 pb-0">
                   <DayOfWeekChart data={data.dow_counts} />

package/pulse/app/globals.css

@@ -86,9 +86,9 @@
   --radius-lg: var(--radius);
   --radius-xl: calc(var(--radius) + 4px);
 
-  /* b0 accent colors */
-  --color-kepler-cyan: #06b6d4;
-  --color-kepler-cyan-light: #22d3ee;
+  /* Bahulam accent colors */
+  --color-bahulam-cyan: #06b6d4;
+  --color-bahulam-cyan-light: #22d3ee;
   --color-terminal-cyan: #06b6d4;
   --color-terminal-green: #34d399;
   --color-terminal-amber: #f59e0b;

package/pulse/app/help/page.tsx

@@ -2,14 +2,14 @@ import { TopBar } from '@/components/layout/top-bar'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 
 const CLI_COMMANDS = [
-  { cmd: 'b0', desc: 'Start interactive REPL' },
-  { cmd: 'b0 "instruction"', desc: 'Run a single instruction and exit' },
-  { cmd: 'b0 dashboard', desc: 'Open b0 Pulse analytics dashboard' },
-  { cmd: 'b0 sessions', desc: 'List recent local sessions' },
-  { cmd: 'b0 stats', desc: 'Show aggregate local session stats' },
-  { cmd: 'b0 history', desc: 'Show recent prompt history' },
-  { cmd: 'b0 login', desc: 'Sign in via browser' },
-  { cmd: 'b0 version', desc: 'Show version' },
+  { cmd: 'bahulam-code', desc: 'Start interactive REPL' },
+  { cmd: 'bahulam-code "instruction"', desc: 'Run a single instruction and exit' },
+  { cmd: 'bahulam-code dashboard', desc: 'Open Bahulam Pulse analytics dashboard' },
+  { cmd: 'bahulam-code sessions', desc: 'List recent local sessions' },
+  { cmd: 'bahulam-code stats', desc: 'Show aggregate local session stats' },
+  { cmd: 'bahulam-code history', desc: 'Show recent prompt history' },
+  { cmd: 'bahulam-code login', desc: 'Sign in via browser' },
+  { cmd: 'bahulam-code version', desc: 'Show version' },
 ]
 
 const REPL_COMMANDS = [
@@ -47,7 +47,7 @@ const FEATURES = [
   { title: 'Multi-Agent Orchestration', desc: 'Primary agent spawns explore, plan, and review sub-agents for complex tasks.' },
   { title: 'Smart Tool Routing', desc: 'Write operations routed to CLI for local execution. Read tools run server-side.' },
   { title: 'Safety Guardrails', desc: 'Destructive commands (rm, delete) always require approval. Path validation on all file operations.' },
-  { title: 'Local JSONL Analytics', desc: 'Every session is recorded to ~/.bahulam/ for offline analytics via b0 Pulse.' },
+  { title: 'Local JSONL Analytics', desc: 'Every session is recorded to ~/.bahulam/ for offline analytics via Bahulam Pulse.' },
   { title: 'Conversation History', desc: 'Multi-turn conversations within a REPL session. Context preserved across turns.' },
   { title: 'BM25 Code Index', desc: 'Project files indexed on startup for fast semantic code search.' },
 ]
@@ -68,7 +68,7 @@ function CommandTable({ commands }: { commands: { cmd: string; desc: string }[]
 export default function HelpPage() {
   return (
     <div className="flex flex-col min-h-screen">
-      <TopBar title="Help" subtitle="b0 CLI commands, shortcuts, and configuration" />
+      <TopBar title="Help" subtitle="Bahulam Code CLI commands, shortcuts, and configuration" />
       <div className="px-6 py-6 space-y-6">
 
         <Card>

package/pulse/app/layout.tsx

@@ -20,8 +20,8 @@ const pressStart2P = Press_Start_2P({
 })
 
 export const metadata: Metadata = {
-  title: 'b0 Pulse',
-  description: 'Real-time analytics for your b0 agent sessions',
+  title: 'Bahulam Pulse',
+  description: 'Real-time analytics for your Bahulam Code agent sessions',
 }
 
 export default function RootLayout({

package/pulse/app/memory/page.tsx

@@ -260,7 +260,7 @@ export default function MemoryPage() {
 
   return (
     <div className="flex flex-col min-h-screen">
-      <TopBar title="b0-pulse · memory" subtitle="~/.bahulam/projects/*/memory/" />
+      <TopBar title="Bahulam Pulse · memory" subtitle="~/.bahulam/projects/*/memory/" />
       <div className="p-4 md:p-6 space-y-5">
 
         {error && <p className="text-[#f87171] text-sm font-mono">Error loading memories.</p>}

package/pulse/app/overview-client.tsx

@@ -381,7 +381,7 @@ export function OverviewClient() {
       <Card>
         <CardHeader>
           <CardTitle>Recent Sessions</CardTitle>
-          <CardDescription>Your latest b0 sessions</CardDescription>
+          <CardDescription>Your latest Bahulam Code sessions</CardDescription>
         </CardHeader>
         <CardContent>
           <OverviewConversationTable sessions={sessions} />

package/pulse/app/page.tsx

@@ -5,8 +5,8 @@ export default function OverviewPage() {
   return (
     <div className="flex flex-col min-h-screen">
       <TopBar
-        title="b0 Pulse"
-        subtitle="Real-time analytics for your b0 agent sessions"
+        title="Bahulam Pulse"
+        subtitle="Real-time analytics for your Bahulam Code agent sessions"
       />
       <OverviewClient />
     </div>

package/pulse/app/plans/page.tsx

@@ -251,7 +251,7 @@ export default function PlansPage() {
 
   return (
     <div className="flex flex-col min-h-screen">
-      <TopBar title="b0-pulse · plans" subtitle="~/.bahulam/plans/" />
+      <TopBar title="Bahulam Pulse · plans" subtitle="~/.bahulam/plans/" />
       <div className="p-4 md:p-6 space-y-5">
 
         {error && <p className="text-[#f87171] text-sm font-mono">Error: {String(error)}</p>}

package/pulse/app/sessions/page.tsx

@@ -18,7 +18,7 @@ export default function SessionsPage() {
   return (
     <div className="flex flex-col min-h-screen">
       <TopBar
-        title="b0 Pulse · Sessions"
+        title="Bahulam Pulse · Sessions"
         subtitle={data ? `${data.total} total sessions` : 'loading...'}
       />
       <div className="p-6">

package/pulse/app/settings/page.tsx

@@ -83,7 +83,7 @@ export default function SettingsPage() {
 
   return (
     <div className="flex flex-col min-h-screen">
-      <TopBar title="b0-pulse · settings" subtitle="~/.bahulam/settings.json" />
+      <TopBar title="Bahulam Pulse · settings" subtitle="~/.bahulam/settings.json" />
       <div className="p-4 md:p-6 space-y-6">
         {error && <p className="text-[#f87171] text-sm font-mono">Error: {String(error)}</p>}
         {isLoading && (

package/pulse/app/tools/page.tsx

@@ -201,7 +201,7 @@ export default function ToolsPage() {
             {data.versions.length > 0 && (
               <Card>
                 <CardHeader>
-                  <CardTitle>b0 Version History</CardTitle>
+                  <CardTitle>Bahulam Version History</CardTitle>
                   <CardDescription>Versions seen across your sessions</CardDescription>
                 </CardHeader>
                 <CardContent>

package/pulse/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * b0 Pulse — local analytics dashboard launcher.
+ * Bahulam Pulse — local analytics dashboard launcher.
  * Launches a Next.js dev server from ~/.bahulam-pulse/ cache directory.
  */
 
@@ -13,7 +13,7 @@ const fs   = require('fs')
 const PKG_DIR   = __dirname
 const CACHE_DIR = path.join(os.homedir(), '.bahulam-pulse')
 
-// ANSI helpers — b0 cyan palette
+// ANSI helpers — Bahulam cyan palette
 const C   = '\x1b[36m'     // cyan
 const C2  = '\x1b[96m'     // bright cyan
 const DIM = '\x1b[2m'
@@ -25,7 +25,7 @@ function printBanner() {
   console.log()
   const configDir = resolveConfigDir()
   console.log(`  ${B}${C}B · 0${R}`)
-  console.log(`  ${B}${C2}b0 Pulse${R}   ${DIM}real-time agent analytics${R}`)
+  console.log(`  ${B}${C2}Bahulam Pulse${R}   ${DIM}real-time agent analytics${R}`)
   console.log()
   console.log(`  ${DIM}Data dir:${R}    ${C2}${configDir}${R}`)
   console.log()
@@ -82,7 +82,7 @@ function syncSource(pkg) {
   }
   // Write a minimal package.json with only runtime dependencies
   fs.writeFileSync(path.join(CACHE_DIR, 'package.json'), JSON.stringify({
-    name: 'b0-pulse-runtime',
+    name: 'bahulam-pulse-runtime',
     version: pkg.version,
     dependencies: pkg.dependencies,
   }, null, 2))
@@ -125,13 +125,13 @@ async function main() {
   const url  = `http://localhost:${port}`
 
   // Pass config vars to the Next.js process so it reads from ~/.bahulam.
-  const keplerDir = resolveConfigDir()
+  const configDir = resolveConfigDir()
   const env = {
     ...process.env,
     PORT: String(port),
-    BAHULAM_CONFIG_DIR: keplerDir,
-    KEPLER_CONFIG_DIR: keplerDir,
-    CLAUDE_CONFIG_DIR: keplerDir,
+    BAHULAM_CONFIG_DIR: configDir,
+    KEPLER_CONFIG_DIR: configDir,
+    CLAUDE_CONFIG_DIR: configDir,
   }
 
   console.log(`  ${DIM}Starting server on${R} ${C2}${B}${url}${R}\n`)

package/pulse/components/layout/sidebar.tsx

@@ -102,7 +102,7 @@ function SidebarContents({
             <span
               className="dark:[text-shadow:0_1px_0_#0e4f5c,0_2px_0_#083344,0_3px_6px_rgba(0,0,0,0.35)] [text-shadow:0_1px_0_rgba(255,255,255,0.4)]"
             >
-              b0 Pulse
+              Bahulam Pulse
             </span>
           </span>
         )}
@@ -141,7 +141,7 @@ function SidebarContents({
       )}>
         {!collapsed && (
           <span className="text-xs text-sidebar-foreground/50">
-            b0 Pulse
+            Bahulam Pulse
           </span>
         )}
         <button

package/pulse/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "b0-pulse",
+  "name": "bahulam-pulse",
   "version": "1.0.1",
   "private": true,
-  "description": "b0 Pulse — real-time analytics dashboard for b0 agent sessions",
+  "description": "Bahulam Pulse — real-time analytics dashboard for Bahulam Code agent sessions",
   "scripts": {
     "dev": "next dev",
     "build": "next build",

package/src/agents/workflow_scaffold.mjs

@@ -141,7 +141,7 @@ export function createWorkflowFile({
   const normalizedEdges = normalizeWorkflowEdges(edges, agentSlugs);
 
   const lines = [
-    'apiVersion: kepler.workflow/v1',
+    'apiVersion: bahulam.workflow/v1',
     'kind: MultiWorkflow',
     'metadata:',
     `  name: ${yamlQuote(name)}`,

package/src/core/attachments.mjs

@@ -5,8 +5,23 @@ import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+// Text-first document formats we can extract client-side and inline into the
+// user turn as plain text — zero backend upload, zero tool call. PDFs go
+// through pdf-parse; the rest are read as UTF-8.
+const DOCUMENT_EXTENSIONS = new Set([
+  '.pdf',
+  '.txt', '.md', '.mdx', '.rst',
+  '.csv', '.tsv', '.log',
+  '.json', '.yaml', '.yml', '.toml', '.ini', '.env',
+  '.html', '.htm', '.xml',
+]);
 const DEFAULT_MAX_IMAGE_BYTES = 8 * 1024 * 1024;
 const DEFAULT_MAX_TURN_BYTES = 20 * 1024 * 1024;
+// Per-document and per-turn caps for inlined document text. Keep well under
+// context so multiple attachments still leave room for the actual work.
+const DEFAULT_MAX_DOC_CHARS = 80_000;
+const DEFAULT_MAX_TURN_DOC_CHARS = 200_000;
+const DEFAULT_MAX_DOC_BYTES = 5 * 1024 * 1024;
 
 function envInt(name, fallback) {
   const raw = process.env[name];
@@ -78,11 +93,27 @@ export function parseImageReferences(input, { cwd = process.cwd() } = {}) {
       parsed = readBare(text, i + 1);
     }
 
-    if (!parsed || !looksLikeImagePath(parsed.value)) {
+    if (!parsed || (!looksLikeImagePath(parsed.value) && !isClipboardAlias(parsed.value))) {
       cleaned += text[i++];
       continue;
     }
 
+    // @clipboard / @paste — resolve via OS clipboard, attach the resulting
+    // temp file path. Skipping (with a stderr note) on unsupported platforms
+    // or empty clipboards so the rest of the parse continues cleanly.
+    if (isClipboardAlias(parsed.value)) {
+      try {
+        const filePath = writeClipboardImageToTemp();
+        attachments.push({ raw: parsed.value, path: filePath, source: 'clipboard' });
+      } catch (err) {
+        try {
+          process.stderr.write(`  ! @${parsed.value} skipped — ${err.message || String(err)}\n`);
+        } catch {}
+      }
+      i = parsed.end;
+      continue;
+    }
+
     attachments.push({
       raw: parsed.value,
       path: resolveAttachmentPath(parsed.value, cwd),
@@ -361,6 +392,261 @@ export function prepareImageAttachments(input, {
   };
 }
 
+// ── Document attachments (PRD-091 shared tools mirror) ──────────────────
+//
+// Same @path parser shape as images, but for text-first formats we can
+// extract client-side and inline as text into the user turn. Zero upload,
+// zero tool round-trip. PDFs go through pdf-parse; text formats are read
+// as UTF-8 with a byte + char cap. Kept in this module so callers get one
+// unified attachment pipeline.
+
+function looksLikeDocumentPath(value) {
+  const ext = path.extname(String(value || '').toLowerCase());
+  return DOCUMENT_EXTENSIONS.has(ext);
+}
+
+// Special reference tokens (no path extension) — parser recognises them
+// and resolves at parse time.
+const CLIPBOARD_ALIASES = new Set(['clipboard', 'paste']);
+
+function isClipboardAlias(value) {
+  return CLIPBOARD_ALIASES.has(String(value || '').trim().toLowerCase());
+}
+
+function looksLikeAttachment(value) {
+  return looksLikeImagePath(value) || looksLikeDocumentPath(value) || isClipboardAlias(value);
+}
+
+/**
+ * Parse @path references from `input` for BOTH images and documents.
+ * Returns a cleaned instruction (with @refs removed) plus separate
+ * image + document reference lists. Mirrors parseImageReferences but
+ * dispatches on extension.
+ */
+export function parseAttachmentReferences(input, { cwd = process.cwd() } = {}) {
+  const text = String(input || '');
+  const images = [];
+  const documents = [];
+  let cleaned = '';
+  let i = 0;
+
+  while (i < text.length) {
+    if (text[i] !== '@') {
+      cleaned += text[i++];
+      continue;
+    }
+    const next = text[i + 1];
+    let parsed = null;
+    if (next === '"' || next === "'") {
+      parsed = readQuoted(text, i + 1);
+    } else if (next && !/\s/.test(next)) {
+      parsed = readBare(text, i + 1);
+    }
+    if (!parsed || !looksLikeAttachment(parsed.value)) {
+      cleaned += text[i++];
+      continue;
+    }
+
+    // @clipboard / @paste — resolve now via the OS clipboard helper. Side
+    // effect (writes a temp PNG) is fine at parse time because the parser
+    // is called once per turn, matching when the user typed @clipboard.
+    if (isClipboardAlias(parsed.value)) {
+      try {
+        const filePath = writeClipboardImageToTemp();
+        images.push({ raw: parsed.value, path: filePath, source: 'clipboard' });
+      } catch (err) {
+        // Emit a stderr note so the user knows why their @clipboard
+        // reference didn't attach anything, then drop it from the parse.
+        try {
+          process.stderr.write(`  ! @${parsed.value} skipped — ${err.message || String(err)}\n`);
+        } catch {}
+      }
+      i = parsed.end;
+      continue;
+    }
+
+    const attachment = {
+      raw: parsed.value,
+      path: resolveAttachmentPath(parsed.value, cwd),
+    };
+    if (looksLikeImagePath(parsed.value)) images.push(attachment);
+    else documents.push(attachment);
+    i = parsed.end;
+  }
+
+  return {
+    instruction: cleaned.replace(/\s+/g, ' ').trim(),
+    images,
+    documents,
+  };
+}
+
+async function extractPdfText(filePath, { maxChars }) {
+  // pdf-parse is a CJS module. Dynamic import so ESM callers stay clean and
+  // we don't pay the parse cost on startup for CLIs that never touch PDFs.
+  const { default: pdfParse } = await import('pdf-parse');
+  const buffer = fs.readFileSync(filePath);
+  const parsed = await pdfParse(buffer);
+  const raw = String(parsed?.text || '').trim();
+  const truncated = raw.length > maxChars;
+  return {
+    text: truncated ? raw.slice(0, maxChars) : raw,
+    pages: parsed?.numpages || 0,
+    truncated,
+  };
+}
+
+function extractPlainText(filePath, { maxChars }) {
+  const buffer = fs.readFileSync(filePath);
+  // Best-effort UTF-8; binary files that sneak through the ext list will
+  // still decode but likely with replacement chars. That's a signal to the
+  // model that this attachment is not meaningful text.
+  const raw = buffer.toString('utf-8');
+  const truncated = raw.length > maxChars;
+  return {
+    text: truncated ? raw.slice(0, maxChars) : raw,
+    pages: 0,
+    truncated,
+  };
+}
+
+/**
+ * Load a single document attachment. Reads locally, extracts text, returns
+ * a public metadata block plus the extracted text. Errors bubble as
+ * throws — callers should catch per-document and continue.
+ */
+export async function loadDocumentAttachment(filePath, {
+  cwd = process.cwd(),
+  maxBytes = DEFAULT_MAX_DOC_BYTES,
+  maxChars = DEFAULT_MAX_DOC_CHARS,
+} = {}) {
+  const resolved = path.isAbsolute(filePath) ? filePath : resolveAttachmentPath(filePath, cwd);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Document not found: ${filePath}`);
+  }
+  const stat = fs.statSync(resolved);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: ${filePath}`);
+  }
+  if (stat.size > maxBytes) {
+    throw new Error(
+      `Document ${path.basename(resolved)} is ${Math.round(stat.size / 1024)} KB, ` +
+      `exceeds ${Math.round(maxBytes / 1024)} KB cap`,
+    );
+  }
+
+  const ext = path.extname(resolved).toLowerCase();
+  const isPdf = ext === '.pdf';
+  const { text, pages, truncated } = isPdf
+    ? await extractPdfText(resolved, { maxChars })
+    : extractPlainText(resolved, { maxChars });
+
+  const buffer = fs.readFileSync(resolved);
+  const sha256 = createHash('sha256').update(buffer).digest('hex');
+
+  return {
+    id: randomUUID(),
+    path: resolved,
+    name: path.basename(resolved),
+    ext,
+    kind: isPdf ? 'pdf' : 'text',
+    bytes: stat.size,
+    chars: text.length,
+    pages,
+    truncated,
+    sha256,
+    text,
+  };
+}
+
+/**
+ * Public metadata for a document (drop the text body — that's for the
+ * inline block, not the transcript log).
+ */
+export function publicDocumentMetadata(doc) {
+  if (!doc) return null;
+  return {
+    id: doc.id,
+    name: doc.name,
+    path: doc.path,
+    ext: doc.ext,
+    kind: doc.kind,
+    bytes: doc.bytes,
+    chars: doc.chars,
+    pages: doc.pages,
+    truncated: doc.truncated,
+    sha256: doc.sha256,
+  };
+}
+
+export function documentSummaryLine(doc) {
+  if (!doc) return '';
+  const size = doc.bytes > 1024
+    ? `${Math.round(doc.bytes / 1024)} KB`
+    : `${doc.bytes} B`;
+  const extra = doc.pages ? `, ${doc.pages} page${doc.pages === 1 ? '' : 's'}` : '';
+  const trunc = doc.truncated ? ' · truncated' : '';
+  return `${doc.name} (${doc.kind}${extra}, ${size}${trunc})`;
+}
+
+/**
+ * Batch-prepare document attachments (parse + load) with a per-turn
+ * character budget. Returns { instruction (@refs stripped), documents,
+ * metadata }. Throws if the combined extracted text exceeds
+ * DEFAULT_MAX_TURN_DOC_CHARS.
+ */
+export async function prepareDocumentAttachments(input, {
+  cwd = process.cwd(),
+  extraPaths = [],
+  maxDocBytes = envInt('BAHULAM_DOC_MAX_BYTES', DEFAULT_MAX_DOC_BYTES),
+  maxDocChars = envInt('BAHULAM_DOC_MAX_CHARS', DEFAULT_MAX_DOC_CHARS),
+  maxTurnDocChars = envInt('BAHULAM_DOC_MAX_TURN_CHARS', DEFAULT_MAX_TURN_DOC_CHARS),
+} = {}) {
+  const parsed = parseAttachmentReferences(input, { cwd });
+  const paths = [
+    ...parsed.documents.map(ref => ref.path),
+    ...extraPaths.map(p => resolveAttachmentPath(p, cwd)),
+  ];
+  const uniquePaths = [...new Set(paths)];
+  const documents = [];
+  for (const p of uniquePaths) {
+    documents.push(await loadDocumentAttachment(p, { cwd, maxBytes: maxDocBytes, maxChars: maxDocChars }));
+  }
+  const totalChars = documents.reduce((sum, d) => sum + (d.chars || 0), 0);
+  if (totalChars > maxTurnDocChars) {
+    throw new Error(
+      `Attached documents total ${totalChars.toLocaleString()} chars, ` +
+      `exceeds per-turn cap of ${maxTurnDocChars.toLocaleString()}`,
+    );
+  }
+  return {
+    instruction: parsed.instruction || String(input || '').trim(),
+    documents,
+    metadata: documents.map(publicDocumentMetadata),
+  };
+}
+
+/**
+ * Fold extracted document text into the user turn as a bounded block. The
+ * agent sees the content directly — no tool call needed. Format is stable
+ * so read_attachment output and inlined output look the same shape to the
+ * model.
+ */
+export function appendDocumentsToInstruction(instruction, documents) {
+  const docs = (documents || []).filter(d => d && d.text);
+  if (!docs.length) return String(instruction || '');
+  const parts = [String(instruction || '').trim()];
+  for (const doc of docs) {
+    const meta = `${doc.name}` +
+      (doc.pages ? ` · ${doc.pages} page${doc.pages === 1 ? '' : 's'}` : '') +
+      (doc.truncated ? ` · truncated to ${doc.chars.toLocaleString()} chars` : '');
+    parts.push('');
+    parts.push(`[Attached document: ${meta}]`);
+    parts.push(doc.text);
+  }
+  return parts.join('\n');
+}
+
 export function appendVisionAnalysisToInstruction(instruction, analysis) {
   const summary = String(analysis?.summary || '').trim();
   if (!summary) return String(instruction || '');

package/src/core/backend-url.mjs

@@ -8,20 +8,33 @@
  */
 
 const BACKEND_URLS = {
+    // Four supported environments:
+    //   local     — Docker Compose backend on the developer's own machine.
+    //   dev       — Bahulam Cloud development (Azure Container Apps, eastus).
+    //   production — Bahulam Cloud live (Azure Container Apps, centralus).
+    //   bundled   — CLI-local Python runtime spawned as a subprocess. URL is
+    //               overridden by bundled-runtime.mjs at spawn time; sentinel
+    //               value below is only used if the runtime isn't up yet.
     local:       'http://127.0.0.1:8150',
-    treetop:     'https://codekepler-backend-dev.kindisland-9034322d.eastus.azurecontainerapps.io',
+    dev:         'https://codekepler-backend-dev.kindisland-9034322d.eastus.azurecontainerapps.io',
     production:  'https://codekepler-backend-prod.gentlerock-9816c6b8.centralus.azurecontainerapps.io',
+    bundled:     'http://127.0.0.1:0',   // sentinel — real URL comes from bundled-runtime.mjs
 };
 
-// Aliases
-BACKEND_URLS.prod = BACKEND_URLS.production;
+// Aliases (backwards compat + convenience)
+BACKEND_URLS.prod    = BACKEND_URLS.production;
+BACKEND_URLS.treetop = BACKEND_URLS.dev;             // legacy alias
+BACKEND_URLS.docker  = BACKEND_URLS.local;           // convenience alias
 
 const WEB_URLS = {
     local:       'http://localhost:3100',
-    treetop:     'https://treetop.codekepler.ai',
+    dev:         'https://treetop.codekepler.ai',
     production:  'https://codekepler.ai',
+    bundled:     'http://localhost:3100',   // bundled mode reuses local web if user runs it
 };
-WEB_URLS.prod = WEB_URLS.production;
+WEB_URLS.prod    = WEB_URLS.production;
+WEB_URLS.treetop = WEB_URLS.dev;             // legacy alias
+WEB_URLS.docker  = WEB_URLS.local;
 
 /**
  * Resolve the web dashboard URL from environment.