@bike4mind/cli 0.13.0 → 0.15.0

package/dist/{tools-BhPOnNo3.mjs → tools-ChYlNt33.mjs}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { $ as ProjectEvents, A as GenerateImageToolCallSchema, At as dayjsConfig_default, B as InviteEvents, Bt as sanitizeTelemetryError, C as ElabsEvents, Ct as UnauthorizedError, D as ForbiddenError, Dt as VideoModels, E as FileEvents, Et as VideoGenerationUsageTransaction, F as ImageEditUsageTransaction, Ft as isGPTImage2Model, G as ModalEvents, Gt as buildRateLimitLogEntry, H as KnowledgeType, Ht as settingsMap, I as ImageGenerationUsageTransaction, It as isGPTImageModel, J as OpenAIEmbeddingModel, Jt as parseRateLimitHeaders, K as ModelBackend, Kt as extractSnippetMeta, L as ImageModels, Lt as isZodError, M as GenericCreditDeductTransaction, Mt as getDataLakeTags, N as HTTPError, Nt as getMcpProviderMetadata, O as FriendshipEvents, Ot as XAI_IMAGE_MODELS, P as HttpStatus, Pt as getViewById, Q as ProfileEvents, R as InboxEvents, Rt as obfuscateApiKey, S as DashboardParamsSchema, St as UiNavigationEvents, T as FeedbackEvents, Tt as VIDEO_SIZE_CONSTRAINTS, U as LLMEvents, V as InviteType, Vt as secureParameters, W as MiscEvents, X as Permission, Y as OpenAIImageGenerationInput, Yt as CollectionType, Z as PermissionDeniedError, _ as ChatCompletionCreateInputSchema, _t as TaskScheduleHandler, a as ALERT_THRESHOLDS, at as ReceivedCreditTransaction, b as CompletionApiUsageTransaction, bt as ToolUsageTransaction, c as ApiKeyScope, ct as ResearchModeParamsSchema, d as ArtifactTypeSchema, dt as ResearchTaskType, et as PromptIntentSchema, f as AuthEvents, ft as SessionEvents, gt as TagType, h as BadRequestError, ht as SupportedFabFileMimeTypes, it as RealtimeVoiceUsageTransaction, j as GenericCreditAddTransaction, jt as getAccessibleDataLakes, k as GEMINI_IMAGE_MODELS, kt as b4mLLMTools, l as ApiKeyType, lt as ResearchTaskExecutionType, m as BFL_SAFETY_TOLERANCE, mt as SubscriptionCreditTransaction, n as logger, nt as PurchaseTransaction, o as AiEvents, ot as RechartsChartTypeList, p as BFL_IMAGE_MODELS, pt as SpeechToTextUsageTransaction, q as NotFoundError, qt as isNearLimit, rt as QuestMasterParamsSchema, s as ApiKeyEvents, st as RegInviteEvents, t as ConfigStore, tt as PromptMetaZodSchema, u as AppFileEvents, ut as ResearchTaskPeriodicFrequencyType, v as ChatModels, vt as TextGenerationUsageTransaction, w as FavoriteDocumentType, wt as UnprocessableEntityError, x as CorruptedFileError, xt as TransferCreditTransaction, y as ClaudeArtifactMimeTypes, yt as TooManyRequestsError, z as InternalServerError, zt as resolveNavigationIntents } from "./ConfigStore-C3tokQej.mjs";
+import { $ as ProjectEvents, A as GenerateImageToolCallSchema, At as dayjsConfig_default, B as InviteEvents, Bt as resolveNavigationIntents, C as ElabsEvents, Ct as UnauthorizedError, D as ForbiddenError, Dt as VideoModels, E as FileEvents, Et as VideoGenerationUsageTransaction, F as ImageEditUsageTransaction, Ft as isGPTImage2Model, G as ModalEvents, H as KnowledgeType, Ht as secureParameters, I as ImageGenerationUsageTransaction, It as isGPTImageModel, J as OpenAIEmbeddingModel, Jt as isNearLimit, K as ModelBackend, Kt as buildRateLimitLogEntry, L as ImageModels, Lt as isSupportedEmbeddingModel, M as GenericCreditDeductTransaction, Mt as getDataLakeTags, N as HTTPError, Nt as getMcpProviderMetadata, O as FriendshipEvents, Ot as XAI_IMAGE_MODELS, P as HttpStatus, Pt as getViewById, Q as ProfileEvents, R as InboxEvents, Rt as isZodError, S as DashboardParamsSchema, St as UiNavigationEvents, T as FeedbackEvents, Tt as VIDEO_SIZE_CONSTRAINTS, U as LLMEvents, Ut as settingsMap, V as InviteType, Vt as sanitizeTelemetryError, W as MiscEvents, X as Permission, Xt as CollectionType, Y as OpenAIImageGenerationInput, Yt as parseRateLimitHeaders, Z as PermissionDeniedError, _ as ChatCompletionCreateInputSchema, _t as TaskScheduleHandler, a as ALERT_THRESHOLDS, at as ReceivedCreditTransaction, b as CompletionApiUsageTransaction, bt as ToolUsageTransaction, c as ApiKeyScope, ct as ResearchModeParamsSchema, d as ArtifactTypeSchema, dt as ResearchTaskType, et as PromptIntentSchema, f as AuthEvents, ft as SessionEvents, gt as TagType, h as BadRequestError, ht as SupportedFabFileMimeTypes, it as RealtimeVoiceUsageTransaction, j as GenericCreditAddTransaction, jt as getAccessibleDataLakes, k as GEMINI_IMAGE_MODELS, kt as b4mLLMTools, l as ApiKeyType, lt as ResearchTaskExecutionType, m as BFL_SAFETY_TOLERANCE, mt as SubscriptionCreditTransaction, n as logger, nt as PurchaseTransaction, o as AiEvents, ot as RechartsChartTypeList, p as BFL_IMAGE_MODELS, pt as SpeechToTextUsageTransaction, q as NotFoundError, qt as extractSnippetMeta, rt as QuestMasterParamsSchema, s as ApiKeyEvents, st as RegInviteEvents, t as ConfigStore, tt as PromptMetaZodSchema, u as AppFileEvents, ut as ResearchTaskPeriodicFrequencyType, v as ChatModels, vt as TextGenerationUsageTransaction, w as FavoriteDocumentType, wt as UnprocessableEntityError, x as CorruptedFileError, xt as TransferCreditTransaction, y as ClaudeArtifactMimeTypes, yt as TooManyRequestsError, z as InternalServerError, zt as obfuscateApiKey } from "./ConfigStore-HRgwfPBk.mjs";
 import { a as isUserLockedOut, c as userCanDisableMFA, d as userRequiresMFA, f as verifyBackupCode, i as getLockoutTimeRemaining, l as userEligibleForMFA, n as generateBackupCodes, o as recordFailedAttempt, p as verifyTOTPToken, r as generateTOTPSetup, s as shouldResetFailedAttempts, t as clearFailedAttempts, u as userHasMFAConfigured } from "./utils-PpNti-tY.mjs";
 import { n as isPathAllowed, t as assertPathAllowed } from "./pathValidation-D8tjkQXE-1HwvsuYT.mjs";
-import { t as version } from "./package-DNcd24qN.mjs";
+import { t as version } from "./package-CaPvuP1F.mjs";
 import { execFile, execFileSync, spawn } from "child_process";
-import crypto, { createHash, randomBytes } from "crypto";
+import crypto, { createHash, randomBytes, randomUUID } from "crypto";
 import { existsSync, promises, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "fs";
 import os, { homedir } from "os";
 import path, { dirname, join } from "path";
@@ -559,7 +559,8 @@ const COMMANDS = [
 	},
 	{
 		name: "handoff",
-		description: "Show or generate the session handoff for cross-session continuity (alias for /workflow handoff)"
+		description: "Show or generate the session handoff for cross-session continuity. Use --local for an LLM-free snapshot (works when rate-limited or offline). Alias for /workflow handoff.",
+		args: "[generate|--local]"
 	}
 ];
 /**
@@ -2061,8 +2062,9 @@ var ReActAgent = class extends EventEmitter {
 					cacheConversationHistory: false,
 					cacheTTL: "5m"
 				} : void 0;
+				const iterationIndex = iterations - 1;
 				await this.context.llm.complete(this.context.model, messages, {
-					stream: false,
+					stream: true,
 					tools: this.context.tools,
 					maxTokens,
 					temperature,
@@ -2072,7 +2074,13 @@ var ReActAgent = class extends EventEmitter {
 					thinking: this.context.thinking,
 					cacheStrategy
 				}, async (texts, completionInfo) => {
-					for (const text of texts) if (text) currentText += text;
+					for (const text of texts) if (text) {
+						currentText += text;
+						this.emit("text_delta", {
+							delta: text,
+							iteration: iterationIndex
+						});
+					}
 					if (completionInfo) {
 						const inputTokens = completionInfo.inputTokens || 0;
 						const outputTokens = completionInfo.outputTokens || 0;
@@ -2529,8 +2537,9 @@ Remember: You are an autonomous AGENT. Act independently and solve problems proa
 				cacheConversationHistory: false,
 				cacheTTL: "5m"
 			} : void 0;
+			const iterationIndex = this.iterations - 1;
 			await this.context.llm.complete(this.context.model, this.messages, {
-				stream: false,
+				stream: true,
 				tools: this.context.tools,
 				maxTokens,
 				temperature,
@@ -2540,7 +2549,13 @@ Remember: You are an autonomous AGENT. Act independently and solve problems proa
 				thinking: this.context.thinking,
 				cacheStrategy
 			}, async (texts, completionInfo) => {
-				for (const text of texts) if (text) currentText += text;
+				for (const text of texts) if (text) {
+					currentText += text;
+					this.emit("text_delta", {
+						delta: text,
+						iteration: iterationIndex
+					});
+				}
 				if (completionInfo) {
 					const inputTokens = completionInfo.inputTokens || 0;
 					const outputTokens = completionInfo.outputTokens || 0;
@@ -3156,6 +3171,398 @@ function buildPipelineResult(taskResults, options = {}) {
 		summary: summaryParts.join("\n")
 	};
 }
+/**
+* Drives are bounded scalars in [0, 1] that decay over time and are satisfied
+* by certain action classes. They give the agent a *direction* between
+* explicit prompts — the "Sims needs system" applied to autonomous agents.
+*
+* At policy time, the current drive vector is summarized in natural language
+* and injected into the orient prompt (e.g., "you are feeling curious,
+* somewhat bored, slightly anxious about progress").
+*
+* Each named drive captures one motivational axis:
+*
+* - `curiosity`: satisfied by encountering novelty/surprise; decays when
+*   observations are repetitive.
+* - `progress`: satisfied by measurable goal-state change; decays when
+*   wake cycles produce no advancement.
+* - `social`: satisfied by human interaction; decays when the agent runs
+*   without external input.
+* - `novelty`: satisfied by producing a falsifiable, original hypothesis
+*   (distinct from curiosity, which is satisfied by intake). Decays as the
+*   corpus of read material grows without ideation.
+* - `caution`: rises with budget burn or repeated failure; biases the
+*   policy step toward cheaper / lower-tier actions.
+* - `aesthetic`: satisfied by polish/refinement actions. Tunable for
+*   game-design-style work where craft matters.
+*/
+const DriveVectorSchema = z.object({
+	curiosity: z.number().min(0).max(1),
+	progress: z.number().min(0).max(1),
+	social: z.number().min(0).max(1),
+	novelty: z.number().min(0).max(1),
+	caution: z.number().min(0).max(1),
+	aesthetic: z.number().min(0).max(1)
+});
+/**
+* Evidence tier classifies how strong the support is for a claim or finding.
+*
+* Lifted directly from the patterns evolved in
+* `~/Desktop/quantum-work/q-paper-neutron-scattering/`, where the claims
+* ledger distinguished "engineering evidence" from "paper-facing evidence".
+*
+* This is the most important schema-level invariant inherited from the
+* working paper-reproduction agent: every long-horizon agent must be able
+* to distinguish *"I made this work in my sandbox"* from *"this passes the
+* external bar"*. Drives and budgets behave differently at each tier:
+* exploration is cheap at low tiers and expensive at high tiers.
+*
+* - `engineering-proxy`: works on a small/synthetic proxy of the real
+*   problem. Cheapest to produce, weakest claim.
+* - `engineering-scaled`: works at production-relevant scale, but still
+*   inside the agent's own sandbox. No external validation.
+* - `external-facing`: passes an externally-defined bar (target metric,
+*   reference dataset, paper claim). Still agent-graded.
+* - `human-reviewed`: an external human reviewer has signed off. Highest
+*   tier; required before any public artifact ships.
+*/
+const EvidenceTierSchema = z.enum([
+	"engineering-proxy",
+	"engineering-scaled",
+	"external-facing",
+	"human-reviewed"
+]);
+/**
+* Default charter size budget in bytes. 8KB honors the Ember scarcity insight:
+* a hard cap forces the agent to *curate* rather than accumulate, and curation
+* is the mechanism by which identity and taste emerge.
+*
+* Tunable per agent; production research agents may need more, but the cap
+* itself is load-bearing.
+*/
+const DEFAULT_CHARTER_SIZE_BUDGET_BYTES = 8 * 1024;
+/**
+* Identity is the slow-changing core of the charter. Once set, these fields
+* rarely change — the agent's name and instantiation moment are stable
+* anchors across the inevitable identity discontinuities (deploys, model
+* swaps, context overflows).
+*/
+const CharterIdentitySchema = z.object({
+	/** Stable agent id (the load-bearing key across all storage). */
+	agentId: z.string().min(1),
+	/**
+	* The user who owns this agent. Tool execution runs as this user — their
+	* storage, billing, and permissions scope the agent's actions. Long-horizon
+	* agents are headless but always answer to an owner.
+	*/
+	ownerUserId: z.string().min(1),
+	/**
+	* MISSION LINKAGE: when set, this charter is a Mission of an existing B4M
+	* Agent (the AgentModel id). The mission inherits the agent's persona
+	* (system prompt) and tool policy at act time; `agentId` above remains the
+	* mission's own unique key, so one B4M agent can run many missions.
+	* Absent = a standalone deep agent (the original mode).
+	*/
+	linkedAgentId: z.string().min(1).optional(),
+	/** Human-readable name. Public; appears in logs and dashboards. */
+	name: z.string().min(1),
+	/** Role / archetype, e.g. "paper-repro", "game-designer", "researcher". */
+	role: z.string().min(1),
+	/** ISO-8601 timestamp of first wake. */
+	instantiatedAt: z.string().datetime(),
+	/** Charter schema version, for migrations. */
+	schemaVersion: z.literal(1)
+});
+/**
+* The goal is what the agent is pursuing. `successCriteria` should be
+* concrete enough that the reflect step can decide whether progress was made.
+* `deadlineKind` is intentionally a soft category rather than a wall-clock
+* date — long-horizon research has no real deadline; game prototypes do.
+*/
+const CharterGoalSchema = z.object({
+	description: z.string().min(1),
+	successCriteria: z.array(z.string()).default([]),
+	deadlineKind: z.enum([
+		"none",
+		"soft",
+		"hard"
+	]).default("none"),
+	/** ISO-8601; only meaningful (and only allowed) when deadlineKind !== 'none'. */
+	deadlineAt: z.string().datetime().optional()
+}).refine((goal) => goal.deadlineKind !== "none" || goal.deadlineAt === void 0, {
+	message: "deadlineAt requires deadlineKind to be 'soft' or 'hard'",
+	path: ["deadlineAt"]
+});
+const SubgoalStatusSchema = z.enum([
+	"planned",
+	"active",
+	"blocked",
+	"completed",
+	"abandoned"
+]);
+const SubgoalSchema = z.object({
+	id: z.string().min(1),
+	description: z.string().min(1),
+	status: SubgoalStatusSchema.default("planned"),
+	/** Higher = more important. Used by the policy step to rank. */
+	priority: z.number().int().min(0).max(100).default(50),
+	/** Tier required for this subgoal to be considered "done". */
+	targetTier: EvidenceTierSchema.default("engineering-scaled"),
+	/** IDs of subgoals that must complete before this one is unblocked. */
+	dependsOn: z.array(z.string()).default([])
+});
+/**
+* A semantic memory entry is a single distilled fact the agent has chosen
+* to preserve across wake cycles. Provenance-typed via `evidenceTier`.
+*
+* `sourceEpisodeIds` lets the agent (and humans) trace any claim back to
+* the wake cycles in which it was formed — the audit trail that makes
+* adversarial review tractable.
+*/
+const SemanticMemoryEntrySchema = z.object({
+	id: z.string().min(1),
+	fact: z.string().min(1),
+	evidenceTier: EvidenceTierSchema,
+	/** Subjective confidence in [0, 1]. Self-reported by the agent. */
+	confidence: z.number().min(0).max(1).default(.5),
+	sourceEpisodeIds: z.array(z.string()).default([]),
+	/** ISO-8601 when this entry was last reaffirmed during grooming. */
+	lastAffirmedAt: z.string().datetime()
+});
+z.object({
+	identity: CharterIdentitySchema,
+	goal: CharterGoalSchema,
+	/** Current drive vector (decayed at wake time before policy step). */
+	drives: DriveVectorSchema,
+	subgoals: z.array(SubgoalSchema).default([]),
+	semanticMemory: z.array(SemanticMemoryEntrySchema).default([]),
+	/**
+	* The tier the agent is currently operating at. Tier-gated progression
+	* (Tier 0 charter → Tier N envelope) is inherited from q-paper's tier
+	* system. Drives and budgets behave differently per tier.
+	*/
+	currentTier: EvidenceTierSchema.default("engineering-proxy"),
+	/** Open questions the agent wants to resolve. Free-form. */
+	openQuestions: z.array(z.string()).default([]),
+	/** Active blockers (mirrored from the workflow blocker system if used). */
+	blockers: z.array(z.string()).default([]),
+	/**
+	* The B4M session acting as this charter's mission log — wake summaries and
+	* deliverables land there as chat history. Created lazily on first bridge.
+	*/
+	sessionId: z.string().min(1).optional(),
+	/** Size budget in bytes. Grooming is triggered when exceeded. */
+	sizeBudgetBytes: z.number().int().positive().default(DEFAULT_CHARTER_SIZE_BUDGET_BYTES),
+	/** Monotonic version counter, bumped on every successful groom/update. */
+	version: z.number().int().nonnegative().default(0),
+	/** ISO-8601 of last groom (compaction). */
+	groomedAt: z.string().datetime().optional(),
+	/** ISO-8601 of last update (any field). */
+	updatedAt: z.string().datetime()
+});
+z.object({
+	agentId: z.string().min(1),
+	/** Monotonic counter, bumped on every wake cycle. */
+	wakeCount: z.number().int().nonnegative(),
+	/** ISO-8601 of the most recent wake. */
+	lastWakeAt: z.string().datetime(),
+	/**
+	* One-paragraph summary of what was done in the last wake cycle.
+	* The reflect step writes this. Short enough to fit comfortably in any
+	* subsequent orient prompt.
+	*/
+	lastActionSummary: z.string().default(""),
+	/**
+	* What the agent intends to do on the next wake. Written by the reflect
+	* step. The orient step uses it as a strong prior but is free to override
+	* if drives or new observations dictate.
+	*/
+	nextIntendedAction: z.string().default(""),
+	/**
+	* Hint from the agent about how soon it should wake again, in
+	* milliseconds. The scheduler may honor or override based on drive state,
+	* cost budget, and external triggers.
+	*
+	*   - Hot loop (active debugging): minutes
+	*   - Normal research cadence: hours
+	*   - Waiting on external process (training, build): much longer
+	*/
+	nextWakeIntervalMs: z.number().int().positive().optional(),
+	/**
+	* Active blockers, in human-readable form. Mirrors the workflow blocker
+	* system but local to the agent's working surface.
+	*/
+	openBlockers: z.array(z.string()).default([]),
+	/**
+	* The id of the most recent episode record. Lets the next wake load the
+	* tail of episodic memory without scanning.
+	*/
+	lastEpisodeId: z.string().optional(),
+	/** ISO-8601 of last update. */
+	updatedAt: z.string().datetime()
+});
+/**
+* Deep Agent Episode — the per-wake-cycle structured record.
+*
+* One Episode is written per wake cycle. Episodes are append-only and
+* unbounded; they are the agent's raw experience log. Periodically the
+* grooming process consolidates episodes into Charter semantic memory,
+* compressing many concrete experiences into fewer reusable facts.
+*
+* Key q-paper-neutron-scattering pattern: every Episode carries explicit
+* `scopeLocks` — what the agent *did NOT do* in this wake. This is the
+* agentic equivalent of Postel's principle (be conservative in what you
+* claim to have done) and is what makes adversarial review tractable.
+*/
+/**
+* The policy decision made by the orient step at the start of a wake.
+*
+* The policy step is a cheap LLM call: given charter + recent episodes
+* + current drives, what action class maximizes expected drive
+* satisfaction subject to the goal and tier? Its output is captured
+* here for later analysis of decision quality.
+*/
+const PolicyDecisionSchema = z.object({
+	/**
+	* Named action class (matches a key in the agent's toolbelt profile).
+	* Examples: "read_paper", "run_experiment", "ideate_hypothesis",
+	* "request_review", "consolidate_memory".
+	*/
+	actionKind: z.string().min(1),
+	/** Natural-language justification for the choice. */
+	rationale: z.string().min(1),
+	/**
+	* The drive deltas the policy expects this action to produce.
+	* Compared against actual deltas at reflect time to calibrate
+	* future policy decisions.
+	*/
+	expectedDriveDelta: z.record(z.string(), z.number()).default({})
+});
+/**
+* A single tool/action invocation within a wake cycle.
+*
+* One Episode may contain many ActionsTaken — the ReAct loop iterates
+* within a wake, calling tools, observing, deciding. Each individual
+* tool call is one ActionTaken record.
+*/
+const ActionTakenSchema = z.object({
+	/** Tool or sub-action name. */
+	tool: z.string().min(1),
+	/** Arbitrary structured input. Serialized at persist time. */
+	input: z.unknown(),
+	/** Whether the action completed without throwing. */
+	succeeded: z.boolean(),
+	/** Optional duration in ms — useful for budget accounting. */
+	durationMs: z.number().int().min(0).optional()
+});
+/**
+* An observation returned by the world to the agent.
+*
+* Observations are deliberately separated from ActionsTaken because
+* the same action may yield multiple observations (e.g. a shell command
+* with stdout and stderr) and because some observations are unsolicited
+* (e.g. an external review arrives between wakes).
+*/
+const ObservationSchema = z.object({
+	/** Brief label for what kind of observation this is. */
+	kind: z.string().min(1),
+	/** Natural-language summary of what was observed. */
+	summary: z.string().min(1),
+	/** Optional pointer to a fuller artifact (file path, URL, episode id). */
+	artifactRef: z.string().optional()
+});
+/**
+* A proposed change to the Charter, emitted by the reflect step.
+*
+* CharterDiff is intentionally narrow — we capture *intent to change*,
+* not the resulting Charter. The Charter Repository applies the diff
+* and increments the revision counter. This gives us a clean audit
+* trail of identity drift over time.
+*/
+const CharterDiffSchema = z.object({
+	/** Semantic memory entries to add (ids must be fresh). */
+	addedSemanticMemory: z.array(z.string()).default([]),
+	/** Semantic memory entry ids to remove. */
+	removedSemanticMemoryIds: z.array(z.string()).default([]),
+	/** Subgoal ids whose status changed; details captured in reflection. */
+	subgoalStatusChanges: z.array(z.string()).default([]),
+	/** Free-form prose describing the full diff for human review. */
+	summary: z.string().min(1)
+});
+z.object({
+	/** Stable identifier (ULID or UUID). */
+	id: z.string().min(1),
+	/** Pointer back to the owning agent. */
+	agentId: z.string().min(1),
+	/** ISO timestamp of wake. */
+	wakeAt: z.string().datetime(),
+	/** Drives at start of wake. */
+	drivesBefore: DriveVectorSchema,
+	/** Output of the orient step. */
+	policyDecision: PolicyDecisionSchema,
+	/** Tool invocations that occurred during the act step. */
+	actionsTaken: z.array(ActionTakenSchema).default([]),
+	/** Observations gathered during the act step. */
+	observations: z.array(ObservationSchema).default([]),
+	/**
+	* Natural-language reflection from the reflect step.
+	* Answers: what just happened? what did I learn? what should change?
+	*/
+	reflection: z.string().min(1),
+	/** Proposed Charter changes, applied by the repository. */
+	charterDiff: CharterDiffSchema,
+	/** Drives at end of wake (after applyDelta from observations). */
+	drivesAfter: DriveVectorSchema,
+	/**
+	* SCOPE LOCKS — the q-paper invariant.
+	*
+	* Explicit enumeration of what was NOT done in this wake. Required
+	* for any tier-advancing work; optional but encouraged for routine
+	* work. Examples from q-paper-neutron-scattering:
+	*   "did NOT generate exact Lee 2026 target states"
+	*   "did NOT touch Q-Work"
+	*   "did NOT change evidence labels"
+	*
+	* Scope locks are what make adversarial reviewer subagents tractable:
+	* the reviewer doesn't have to guess what to check against, the actor
+	* told them upfront.
+	*/
+	scopeLocks: z.array(z.string()).default([]),
+	/**
+	* Evidence tier this Episode's work was operating at.
+	* Reviewer routing depends on this — engineering-proxy work can be
+	* self-reviewed; external-facing work requires an adversarial reviewer
+	* subagent; human-reviewed work requires a `request_review_gate` action.
+	*/
+	evidenceTier: EvidenceTierSchema,
+	/** Token spend during this wake (input + output, all model calls). */
+	tokensSpent: z.number().int().min(0).default(0),
+	/** Cost in USD during this wake. */
+	costUsd: z.number().min(0).default(0),
+	/**
+	* Optional pointer to a reviewer Episode that audited this one.
+	* Set after an adversarial reviewer subagent has completed its pass.
+	*/
+	reviewedByEpisodeId: z.string().optional()
+});
+z.object({
+	/**
+	* - approved: claims hold up; tierGranted may certify tier advancement
+	* - needs-changes: salvageable, but issues must be addressed first
+	* - rejected: claims refuted or unsupported
+	*/
+	verdict: z.enum([
+		"approved",
+		"needs-changes",
+		"rejected"
+	]),
+	/** Specific, checkable problems found (empty when approved clean). */
+	issues: z.array(z.string()).default([]),
+	/** Highest evidence tier the reviewer certifies for this work. */
+	tierGranted: EvidenceTierSchema.optional(),
+	/** One-paragraph justification of the verdict. */
+	summary: z.string().min(1)
+});
 String.raw`
 const { parentPort } = require('node:worker_threads');
 const vm = require('node:vm');
@@ -3954,6 +4361,7 @@ function mapMimeTypeToArtifactType(mimeType) {
 		case ClaudeArtifactMimeTypes.CODE: return "code";
 		case ClaudeArtifactMimeTypes.MARKDOWN: return "code";
 		case ClaudeArtifactMimeTypes.LATTICE: return "lattice";
+		case ClaudeArtifactMimeTypes.BLOG_DRAFT: return "blog-draft";
 		default:
 			if (mimeType.includes("javascript") || mimeType.includes("jsx")) return "react";
 			if (mimeType.includes("html")) return "html";
@@ -7323,6 +7731,20 @@ var AIImageService = class {
 	}
 };
 /**
+* AWS Lambda hard limit for synchronous (RequestResponse) invocation payloads.
+* @see https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html
+*/
+const LAMBDA_SYNC_PAYLOAD_LIMIT_BYTES = 6291456;
+/**
+* Max raw image size we allow into the synchronous ImageProcessor invocation.
+* base64 inflates bytes by ~4/3, and the JSON envelope adds a small constant,
+* so a raw image > ~4.5 MB produces a payload over the 6 MB Lambda limit.
+* We guard at 4.4 MiB to leave margin for the JSON wrapper and key names.
+* Use binary MiB (matches how currentSizeMB is computed) so the constant,
+* the user-facing message, and the PR description all agree on "4.4MB".
+*/
+const MAX_RAW_IMAGE_BYTES = 4.4 * 1024 * 1024;
+/**
 * Invokes the image processor Lambda to convert and resize images
 * This is a serverless alternative to using sharp directly
 *
@@ -7341,6 +7763,11 @@ async function invokeImageProcessor(imageBuffer, lambdaFunctionName, maxSizeMB =
 		}
 		console.log(`[ImageProcessorUtils] Processing needed - isPng: ${isPng}, needsResize: ${currentSizeMB > maxSizeMB}`);
 		if (!lambdaFunctionName) throw new Error("ImageProcessor Lambda function name is required. Please pass the Lambda function name as an argument.");
+		if (imageBuffer.length > MAX_RAW_IMAGE_BYTES) {
+			const projectedPayloadMB = (imageBuffer.length * 4 / 3 / (1024 * 1024)).toFixed(2);
+			const maxRawMB = (MAX_RAW_IMAGE_BYTES / (1024 * 1024)).toFixed(1);
+			throw new Error(`Image too large (${currentSizeMB.toFixed(2)}MB). Images sent for editing must be under ${maxRawMB}MB (encoding would produce a ~${projectedPayloadMB}MB request, exceeding the ${(LAMBDA_SYNC_PAYLOAD_LIMIT_BYTES / (1024 * 1024)).toFixed(0)}MB limit). Please resize the image and try again.`);
+		}
 		const lambdaClient = new LambdaClient({});
 		const request = {
 			imageBuffer: imageBuffer.toString("base64"),
@@ -8559,6 +8986,24 @@ function findAutomaticFallback(originalModel, availableModels, apiKeyTable, logg
 			"claude-opus-4-6"
 		],
 		"gemini-1.5-flash": ["claude-haiku-4-5-20251001", "gpt-4o-mini"],
+		"claude-fable-5": [
+			"claude-opus-4-8",
+			"claude-opus-4-7",
+			"claude-opus-4-6",
+			"claude-sonnet-4-6",
+			"gpt-5"
+		],
+		"claude-opus-4-8": [
+			"claude-opus-4-7",
+			"claude-opus-4-6",
+			"claude-sonnet-4-6",
+			"gpt-5"
+		],
+		"claude-opus-4-7": [
+			"claude-opus-4-6",
+			"claude-sonnet-4-6",
+			"gpt-5"
+		],
 		"claude-opus-4-5-20251101": [
 			"claude-sonnet-4-6",
 			"claude-sonnet-4-5-20250929",
@@ -11881,11 +12326,11 @@ function tryDecodeSample(problem, opVarMap, stateIdx) {
 */
 const MAX_QUBITS = 16;
 /** QAOA layers (p). p=1 is standard for NISQ-era problems. */
-const LAYERS = 1;
+const LAYERS$1 = 1;
 /** Grid steps per axis during parameter search (gammaSteps × betaSteps evaluations). */
-const GRID_STEPS = 8;
+const GRID_STEPS$1 = 8;
 /** Bitstring samples drawn from the final optimised circuit. */
-const FINAL_SHOTS = 512;
+const FINAL_SHOTS$1 = 512;
 /** All available solvers */
 const allSolvers = [
 	greedySolver,
@@ -11924,7 +12369,7 @@ const allSolvers = [
 					schedule: greedyResult.schedule,
 					elapsedMs: elapsed(),
 					metadata: {
-						layers: LAYERS,
+						layers: LAYERS$1,
 						shots: 0,
 						gamma: 0,
 						beta: 0,
@@ -11937,14 +12382,14 @@ const allSolvers = [
 			const backend = new LocalSimBackend();
 			progress(20);
 			const { gamma, beta } = await gridSearchOptimize(numQubits, ising, backend, {
-				gammaSteps: GRID_STEPS,
-				betaSteps: GRID_STEPS,
-				p: LAYERS
+				gammaSteps: GRID_STEPS$1,
+				betaSteps: GRID_STEPS$1,
+				p: LAYERS$1
 			});
 			progress(75);
-			const gates = buildQAOACircuit(numQubits, ising, [gamma], [beta], LAYERS);
+			const gates = buildQAOACircuit(numQubits, ising, [gamma], [beta], LAYERS$1);
 			const { probabilities } = await backend.run(numQubits, gates);
-			const samples = sampleFromProbabilities(probabilities, FINAL_SHOTS);
+			const samples = sampleFromProbabilities(probabilities, FINAL_SHOTS$1);
 			progress(90);
 			const candidates = [decodeFromArgmax(problem, encoded.variables, probabilities, greedyResult.schedule), decodeSamples(problem, encoded.variables, samples)].filter((d) => d !== null);
 			const bestQuantum = candidates.length > 0 ? candidates.reduce((a, b) => b.makespan < a.makespan ? b : a) : null;
@@ -11958,8 +12403,8 @@ const allSolvers = [
 				schedule: winner.schedule,
 				elapsedMs: elapsed(),
 				metadata: {
-					layers: LAYERS,
-					shots: FINAL_SHOTS,
+					layers: LAYERS$1,
+					shots: FINAL_SHOTS$1,
 					gamma,
 					beta,
 					rawMakespan: bestQuantum?.makespan ?? greedyResult.makespan,
@@ -12020,12 +12465,12 @@ RESPOND WITH ONLY A JSON OBJECT matching this schema:
 
 No markdown, no explanation, no code blocks — just the raw JSON object.`;
 [
-	"  0  2  4  6  8  10 12",
-	"  ├──┼──┼──┼──┼──┼──┤",
-	"A [■■■■■][  ░░░░░░  ]",
-	"B [░░░░░][  ■■■■■  ]",
-	"C [■■■]     [░░░░░░]",
-	"  ──── time ────────►"
+	"   0   3   6   9  12",
+	"   ├───┼───┼───┼───┤",
+	"M1 ████▓▓▓▓░░░",
+	"M2 ░░░░████    ▓▓▓▓",
+	"M3 ▓▓▓░░░░  ████",
+	"   └──── time ─────▶"
 ].join("\n"), [
 	"J1: [M-A 3t]->[M-B 2t]->[M-C 4t]",
 	"J2: [M-B 2t]->[M-C 3t]->[M-A 2t]",
@@ -12057,15 +12502,16 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"           J4 === (arrived t=5)",
 	"  Must reschedule as jobs arrive!"
 ].join("\n"), [
-	"       A",
-	"      /|\\",
-	"    5/ | \\3",
-	"    /  |  \\",
-	"   B---+---C",
-	"    \\  |  /",
-	"    7\\ | /2",
-	"      \\|/",
-	"       D"
+	"       ●A",
+	"      ╱  ╲",
+	"    8╱    ╲5",
+	"    ╱      ╲",
+	"  D●        ●B",
+	"    ╲      ╱",
+	"    7╲    ╱2",
+	"      ╲  ╱",
+	"       ●C",
+	" tour A→B→C→D→A = 22"
 ].join("\n"), [
 	"Start -> A -> B -> C -> D -> Start",
 	"",
@@ -12085,13 +12531,12 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"|       |       |",
 	"B --6-- C --2-- D"
 ].join("\n"), [
-	"┌──────────────────┐",
-	"│ ████ ░░░░ ██████ │ 92%",
-	"│ ████ ░░░░ ██████ │",
-	"├──────────────────┤",
-	"│ ████████ ░░░░░░░ │ 68%",
-	"│ ████████ ░░░░░░░ │",
-	"└──────────────────┘"
+	"  bin 1      bin 2",
+	" ┌────────┐ ┌────────┐",
+	" │███▓▓░░░│ │█████   │",
+	" │███▓▓░░▒│ │▒▒▒     │",
+	" └────────┘ └────────┘",
+	"  94% full   61% full"
 ].join("\n"), [
 	"Items: [3] [5] [2] [4] [6]",
 	"",
@@ -12110,12 +12555,13 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"                     waste",
 	"Objective: Minimize total waste"
 ].join("\n"), [
-	" Agents    Tasks",
-	"  [A] ────── [1]",
-	"  [B] ──┐",
-	"        └── [2]",
-	"  [C] ────── [3]",
-	"  [D] ────── [4]"
+	" agents      tasks",
+	"  [A]─────────(1)",
+	"  [B]────┐",
+	"  [C]────┼────(2)",
+	"  [D]──┐ └────(3)",
+	"       └──────(4)",
+	"     min Σ cost ▼"
 ].join("\n"), [
 	"Workers      Jobs",
 	"  Alice ---> Design   cost: 3",
@@ -12133,12 +12579,12 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"Agent C (cap 12): [T6:6][T7:4]",
 	"Maximize quality within capacity"
 ].join("\n"), [
-	" a-b-c  |  d-e",
-	" |   |  |  |  |",
-	" f-g    |  h-i",
-	" -------+-------",
-	" Group A | Group B",
-	"    max cut  ✂"
+	"   a───b ╌╌┆╌╌ d",
+	"   │ ╲ │   ┆   │",
+	"   c───e ╌╌┆╌╌ f",
+	"           ┆",
+	"  group A  ┆  group B",
+	"   maximize the cut ▲"
 ].join("\n"), [
 	"Group 0    |    Group 1",
 	"  a--b     |     d--e",
@@ -12157,12 +12603,43 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"      sparse",
 	"Find the natural communities"
 ].join("\n"), [
-	" [■] [·] [■] [·]",
-	" [·] [■] [·] [■]",
-	" [■] [·] [·] [·]",
-	" ───────────────",
-	" ■ = selected  5/12",
-	" score: 847 / 1000"
+	"  ┌──┬──╥──┬──┐",
+	"  │▒▒│▒▒║░░│░░│",
+	"  ├──┼──╫──┼──┤",
+	"  │▒▒│▒▒║░░│░░│",
+	"  └──┴──╨──┴──┘",
+	"  rank A ║ rank B",
+	"  minimize the seam ▲"
+].join("\n"), [
+	"  o─o─o ║ o─o─o",
+	"  │ │ │ ║ │ │ │",
+	"  o─o─o ║ o─o─o",
+	"  n/2   ║   n/2",
+	"  cut = xᵀLx  ▲ minimize"
+].join("\n"), [
+	"  [ A A B B C C ]",
+	"  [ A A B B C C ]",
+	"  [ A A B B C C ]",
+	"   k=3 · each n/3",
+	"  seams pay, balance holds"
+].join("\n"), [
+	"  mesh ──▶ ranks",
+	"  ▒▒▒░░░  halo ↕ exchanged",
+	"  ▒▒▒░░░  every timestep",
+	"  cut faces = network tax"
+].join("\n"), [
+	"  ┌────┬────┐",
+	"  │blk1│blk2│←wires that",
+	"  ├────┼────┤  cross cost",
+	"  │blk3│blk4│  timing",
+	"  └────┴────┘"
+].join("\n"), [
+	"  ▣ ▢ ▣ ▢ ▣ ▢",
+	"  ▢ ▣ ▢ ▢ ▣ ▢",
+	"  ▣ ▢ ▢ ▢ ▢ ▣",
+	"  ─────────────",
+	"  ▣ picked  7/18",
+	"  value 847 ▲ max"
 ].join("\n"), [
 	"Return ^",
 	"       |     * efficient frontier",
@@ -12181,13 +12658,13 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"S4={5,6,7}  S5={1,6}",
 	"Solution: S1 + S3 + S4 (covers all)"
 ].join("\n"), [
-	" P │\\    /",
-	"   │ \\  / Supply",
-	"   │  \\/",
-	"   │  /\\  ← equilibrium",
-	"   │ /  \\",
-	"   │/    \\ Demand",
-	"   └──────── Q"
+	" P│ demand╲   ╱supply",
+	"  │        ╲ ╱",
+	"  │         ⊗ p*",
+	"  │        ╱ ╲",
+	"  │       ╱   ╲",
+	"  └─────────┴────── Q",
+	"            q*"
 ].join("\n"), [
 	"Buyers:  B1=$50 B2=$40 B3=$30",
 	"Sellers: S1=$20 S2=$35 S3=$45",
@@ -12206,13 +12683,13 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	" $20     40     $800",
 	" $25     15     $375"
 ].join("\n"), [
-	" f(x)",
-	"  │  ╱╲",
-	"  │ ╱  ╲   ╱╲",
-	"  │╱    ╲ ╱  ╲",
-	"  │      ╳    ╲",
-	"  │     ↑ min   ╲",
-	"  └───────────── x"
+	" f(x)│",
+	"     │╲     ╱╲      ╱",
+	"     │ ╲   ╱  ╲    ╱",
+	"     │  ╲ ╱    ╲  ╱",
+	"     │   ╳      ╲╱",
+	"     │ local     ▼ min",
+	"     └──────────────── x"
 ].join("\n"), [
 	"Param A: [0.1, 0.2, 0.3, 0.4]",
 	"Param B: [10, 20, 30, 40, 50]",
@@ -12232,9 +12709,388 @@ No markdown, no explanation, no code blocks — just the raw JSON object.`;
 	"            \\/  <- fit here",
 	"Minimize: sum(error^2)"
 ].join("\n");
+/** Build a jittered grid mesh: cells at (col,row), edges between face-sharing neighbors. */
+function gridMesh(cols, rows, cellName, weightAt, jitter) {
+	const nodes = [];
+	const padX = 100 / (cols + 1);
+	const padY = 100 / (rows + 1);
+	for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) {
+		const i = r * cols + c;
+		const { dx, dy } = jitter(i);
+		nodes.push({
+			id: i,
+			name: cellName(i),
+			x: Math.round(padX * (c + 1) + dx),
+			y: Math.round(padY * (r + 1) + dy)
+		});
+	}
+	const edges = [];
+	for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) {
+		const i = r * cols + c;
+		if (c + 1 < cols) edges.push({
+			a: i,
+			b: i + 1,
+			w: weightAt(i, i + 1)
+		});
+		if (r + 1 < rows) edges.push({
+			a: i,
+			b: i + cols,
+			w: weightAt(i, i + cols)
+		});
+	}
+	return {
+		nodes,
+		edges
+	};
+}
+const wobble = (i) => i * 7919 % 11 / 10 - .5;
+const plate = gridMesh(4, 3, (i) => `cell ${i}`, (a, b) => 1 + (a * 31 + b * 17) % 4, (i) => ({
+	dx: wobble(i) * 6,
+	dy: wobble(i + 3) * 6
+}));
+const reservoir = gridMesh(6, 3, (i) => `block ${i}`, (a, b) => 1 + (a * 13 + b * 29) % 5, (i) => ({
+	dx: wobble(i + 1) * 8,
+	dy: wobble(i + 5) * 8
+}));
+const blade = gridMesh(6, 4, (i) => `elem ${i}`, (a, b) => 1 + (a * 23 + b * 19) % 4, (i) => ({
+	dx: wobble(i + 2) * 7,
+	dy: wobble(i + 7) * 7
+}));
+plate.nodes, plate.edges, reservoir.nodes, reservoir.edges, blade.nodes, blade.edges;
+var QuboBuilder = class {
+	size;
+	q = /* @__PURE__ */ new Map();
+	constructor(size) {
+		this.size = size;
+	}
+	add(i, j, v) {
+		const [a, b] = i <= j ? [i, j] : [j, i];
+		const key = `${a},${b}`;
+		this.q.set(key, (this.q.get(key) ?? 0) + v);
+	}
+	entries() {
+		return [...this.q.entries()].map(([key, v]) => {
+			const [i, j] = key.split(",").map(Number);
+			return [
+				i,
+				j,
+				v
+			];
+		});
+	}
+};
+/** Add a one-hot penalty P·(Σx − 1)² over the given variable indices. */
+function oneHot(b, vars, P) {
+	for (const i of vars) b.add(i, i, -P);
+	for (let a = 0; a < vars.length; a++) for (let c = a + 1; c < vars.length; c++) b.add(vars[a], vars[c], 2 * P);
+}
+function schedulingToy() {
+	const b = new QuboBuilder(12);
+	const v = (op, t) => op * 4 + t;
+	for (let op = 0; op < 3; op++) {
+		oneHot(b, [
+			0,
+			1,
+			2,
+			3
+		].map((t) => v(op, t)), 4);
+		for (let t = 0; t < 4; t++) b.add(v(op, t), v(op, t), t);
+	}
+	for (let t = 0; t < 4; t++) b.add(v(0, t), v(1, t), 6);
+	return {
+		familyId: "scheduling",
+		size: 12,
+		entries: b.entries(),
+		variableGloss: "x[i,t] = 1 ⇔ operation i starts at time t",
+		constraintGloss: "one start per op · no two ops share a machine-slot"
+	};
+}
+function routingToy() {
+	const b = new QuboBuilder(16);
+	const v = (city, pos) => city * 4 + pos;
+	const D = [
+		[
+			0,
+			2,
+			3,
+			2
+		],
+		[
+			2,
+			0,
+			2,
+			3
+		],
+		[
+			3,
+			2,
+			0,
+			2
+		],
+		[
+			2,
+			3,
+			2,
+			0
+		]
+	];
+	for (let c = 0; c < 4; c++) oneHot(b, [
+		0,
+		1,
+		2,
+		3
+	].map((p) => v(c, p)), 5);
+	for (let p = 0; p < 4; p++) oneHot(b, [
+		0,
+		1,
+		2,
+		3
+	].map((c) => v(c, p)), 5);
+	for (let p = 0; p < 4; p++) {
+		const next = (p + 1) % 4;
+		for (let c1 = 0; c1 < 4; c1++) for (let c2 = 0; c2 < 4; c2++) if (c1 !== c2) b.add(v(c1, p), v(c2, next), D[c1][c2]);
+	}
+	return {
+		familyId: "routing",
+		size: 16,
+		entries: b.entries(),
+		variableGloss: "x[c,p] = 1 ⇔ city c is visited at tour position p",
+		constraintGloss: "each city once · each position once · pay the leg distance"
+	};
+}
+function packingToy() {
+	const b = new QuboBuilder(12);
+	const v = (item, bin) => item * 3 + bin;
+	const sizes = [
+		3,
+		2,
+		2,
+		1
+	];
+	for (let i = 0; i < 4; i++) oneHot(b, [
+		0,
+		1,
+		2
+	].map((bin) => v(i, bin)), 5);
+	for (let bin = 0; bin < 3; bin++) {
+		for (let i = 0; i < 4; i++) for (let j = i + 1; j < 4; j++) if (sizes[i] + sizes[j] > 4) b.add(v(i, bin), v(j, bin), 3);
+		b.add(v(0, bin), v(0, bin), bin);
+	}
+	return {
+		familyId: "packing",
+		size: 12,
+		entries: b.entries(),
+		variableGloss: "x[i,b] = 1 ⇔ item i rides in bin b",
+		constraintGloss: "each item in one bin · oversized pairs repel each other"
+	};
+}
+function assignmentToy() {
+	const b = new QuboBuilder(16);
+	const v = (agent, task) => agent * 4 + task;
+	const C = [
+		[
+			1,
+			4,
+			3,
+			2
+		],
+		[
+			3,
+			1,
+			4,
+			2
+		],
+		[
+			2,
+			3,
+			1,
+			4
+		],
+		[
+			4,
+			2,
+			3,
+			1
+		]
+	];
+	for (let a = 0; a < 4; a++) oneHot(b, [
+		0,
+		1,
+		2,
+		3
+	].map((t) => v(a, t)), 5);
+	for (let t = 0; t < 4; t++) oneHot(b, [
+		0,
+		1,
+		2,
+		3
+	].map((a) => v(a, t)), 5);
+	for (let a = 0; a < 4; a++) for (let t = 0; t < 4; t++) b.add(v(a, t), v(a, t), C[a][t]);
+	return {
+		familyId: "assignment",
+		size: 16,
+		entries: b.entries(),
+		variableGloss: "x[a,t] = 1 ⇔ agent a takes task t",
+		constraintGloss: "one task per agent · one agent per task · pay the mismatch"
+	};
+}
+function networkToy() {
+	const b = new QuboBuilder(10);
+	for (const [i, j] of [
+		[0, 1],
+		[0, 4],
+		[1, 2],
+		[1, 4],
+		[2, 5],
+		[3, 4],
+		[3, 7],
+		[4, 5],
+		[4, 8],
+		[5, 6],
+		[5, 9],
+		[6, 9],
+		[7, 8],
+		[8, 9]
+	]) {
+		b.add(i, i, -1);
+		b.add(j, j, -1);
+		b.add(i, j, 2);
+	}
+	return {
+		familyId: "network",
+		size: 10,
+		entries: b.entries(),
+		variableGloss: "x[i] = 1 ⇔ node i goes to side B",
+		constraintGloss: "no constraints — max cut IS the raw QUBO"
+	};
+}
+function partitioningToy() {
+	const b = new QuboBuilder(9);
+	const edges = [];
+	for (let r = 0; r < 3; r++) for (let c = 0; c < 3; c++) {
+		const i = r * 3 + c;
+		if (c < 2) edges.push([i, i + 1]);
+		if (r < 2) edges.push([i, i + 3]);
+	}
+	for (const [i, j] of edges) {
+		b.add(i, i, 1);
+		b.add(j, j, 1);
+		b.add(i, j, -2);
+	}
+	const Pb = 1.5;
+	const m = 4.5;
+	for (let i = 0; i < 9; i++) {
+		b.add(i, i, Pb * (1 - 2 * m));
+		for (let j = i + 1; j < 9; j++) b.add(i, j, 2 * Pb);
+	}
+	return {
+		familyId: "partitioning",
+		size: 9,
+		entries: b.entries(),
+		variableGloss: "x[i] = 1 ⇔ mesh cell i goes to rank B",
+		constraintGloss: "minimize the cut — literally xᵀLx, the graph Laplacian · balance is a spring on Σx"
+	};
+}
+function selectionToy() {
+	const b = new QuboBuilder(10);
+	const value = [
+		6,
+		5,
+		8,
+		3,
+		7,
+		4,
+		6,
+		2,
+		5,
+		4
+	];
+	const cost = [
+		3,
+		2,
+		4,
+		1,
+		3,
+		2,
+		3,
+		1,
+		2,
+		2
+	];
+	const B = 10;
+	const P = 1.2;
+	for (let i = 0; i < 10; i++) {
+		b.add(i, i, -value[i] + P * (cost[i] * cost[i] - 2 * B * cost[i]));
+		for (let j = i + 1; j < 10; j++) b.add(i, j, P * 2 * cost[i] * cost[j]);
+	}
+	return {
+		familyId: "selection",
+		size: 10,
+		entries: b.entries(),
+		variableGloss: "x[i] = 1 ⇔ item i makes the portfolio",
+		constraintGloss: "budget enforced as a quadratic spring around B"
+	};
+}
+function economicToy() {
+	const b = new QuboBuilder(10);
+	const price = [
+		8,
+		5,
+		9,
+		4,
+		7,
+		6,
+		5,
+		3,
+		6,
+		4
+	];
+	const conflicts = [
+		[0, 1],
+		[0, 2],
+		[1, 3],
+		[2, 4],
+		[2, 5],
+		[3, 5],
+		[4, 6],
+		[5, 7],
+		[6, 8],
+		[7, 9],
+		[8, 9]
+	];
+	for (let i = 0; i < 10; i++) b.add(i, i, -price[i]);
+	for (const [i, j] of conflicts) b.add(i, j, 12);
+	return {
+		familyId: "economic",
+		size: 10,
+		entries: b.entries(),
+		variableGloss: "x[i] = 1 ⇔ bid i wins its bundle",
+		constraintGloss: "bids sharing a good repel — one sale per asset"
+	};
+}
+function continuousToy() {
+	const b = new QuboBuilder(8);
+	const target = 9;
+	for (let p = 0; p < 2; p++) {
+		const base = p * 4;
+		for (let j = 0; j < 4; j++) {
+			const wj = 2 ** j;
+			b.add(base + j, base + j, wj * wj - 2 * target * wj);
+			for (let k = j + 1; k < 4; k++) b.add(base + j, base + k, 2 * wj * 2 ** k);
+		}
+	}
+	return {
+		familyId: "continuous",
+		size: 8,
+		entries: b.entries(),
+		variableGloss: "x = Σ 2ᵏ·bₖ — a dial spelled in bits",
+		constraintGloss: "(x − x*)² expands into pairwise bit couplings"
+	};
+}
+schedulingToy(), routingToy(), packingToy(), assignmentToy(), networkToy(), partitioningToy(), selectionToy(), economicToy(), continuousToy();
 //#endregion
-//#region ../../b4m-core/services/dist/tools-CtLkSQLQ.mjs
-async function performDeepResearch(context, params, config) {
+//#region ../../b4m-core/services/dist/tools-4APomBDv.mjs
+async function performDeepResearch(context, params, config = {}) {
 	const maxDepth = config.maxDepth || 7;
 	const duration = config.duration || 4.5;
 	const startTime = Date.now();
@@ -12562,7 +13418,7 @@ const deepResearchTool = {
 		toolFn: async (value) => {
 			const params = value;
 			await context.onStart?.("deep_research", params);
-			const result = await performDeepResearch(context, { topic: params.topic }, config);
+			const result = await performDeepResearch(context, { topic: params.topic }, config ?? {});
 			return JSON.stringify(result);
 		},
 		toolSchema: {
@@ -12603,6 +13459,72 @@ async function getDynamicDataLakeAccess(context) {
 		dataLakeTagPrefixes: accessibleLakes.map((dl) => dl.fileTagPrefix)
 	};
 }
+async function semanticDataLakeSearch(params, adapters) {
+	const { userId, userGroups = [], query, tags = [], topK = 10, minScore = 0, embeddingModel, apiKeyTable, dataLakeTags, dataLakeTagPrefixes, maxFiles = 2e3, chunkLoadCap = 1e4, logger } = params;
+	const empty = {
+		results: [],
+		totalChunksSearched: 0,
+		filesInScope: 0,
+		embeddingModel
+	};
+	if (!query.trim() || dataLakeTags.length === 0) return empty;
+	const provider = getProviderFromModel(embeddingModel);
+	const embeddingConfig = {};
+	if (provider === "openai") {
+		if (!apiKeyTable?.openai) throw new Error("OpenAI API key required for semantic search but not found.");
+		embeddingConfig.openaiApiKey = apiKeyTable.openai;
+	} else if (provider === "voyageai") {
+		if (!apiKeyTable?.voyageai) throw new Error("VoyageAI API key required for semantic search but not found.");
+		embeddingConfig.voyageApiKey = apiKeyTable.voyageai;
+	}
+	const queryEmbedding = await new EmbeddingFactory(embeddingConfig).createEmbeddingService(embeddingModel).generateEmbedding(query);
+	const queryDim = queryEmbedding.length;
+	const fileSearch = await adapters.db.fabfiles.search(userId, "", {
+		tags,
+		shared: false
+	}, {
+		page: 1,
+		limit: maxFiles
+	}, {
+		by: "fileName",
+		direction: "asc"
+	}, {
+		textSearch: false,
+		includeShared: true,
+		userGroups,
+		dataLakeTags,
+		dataLakeTagPrefixes,
+		excludeContent: true
+	});
+	const fileIds = fileSearch.data.map((f) => f.id);
+	if (fileIds.length === 0) return empty;
+	const fileById = new Map(fileSearch.data.map((f) => [f.id, f]));
+	const chunks = await adapters.db.fabfilechunks.findVectorsByFabFileIds(fileIds, chunkLoadCap);
+	const scored = [];
+	for (const chunk of chunks) {
+		if (!chunk.vector || chunk.vector.length !== queryDim) continue;
+		const score = computeCosineSimilarity(queryEmbedding, chunk.vector);
+		if (score < minScore) continue;
+		const file = fileById.get(chunk.fabFileId);
+		if (!file) continue;
+		scored.push({
+			chunkId: chunk.id,
+			fileId: chunk.fabFileId,
+			fileName: file.fileName,
+			fileTags: file.tags?.map((t) => t.name) ?? [],
+			chunkText: chunk.text ?? "",
+			score
+		});
+	}
+	scored.sort((a, b) => b.score - a.score);
+	logger?.debug?.(`[semanticDataLakeSearch] ${fileIds.length} files, ${chunks.length} chunks → ${scored.length} above min ${minScore}, top score ${scored[0]?.score?.toFixed(3) ?? "n/a"}`);
+	return {
+		results: scored.slice(0, topK),
+		totalChunksSearched: chunks.length,
+		filesInScope: fileIds.length,
+		embeddingModel
+	};
+}
 const diceRoll = async (parameters) => {
 	if (!parameters?.sides || !parameters?.times) throw new Error("Tool dice roll: Missing required parameters");
 	return sum(times(parameters.times, () => random(1, parameters.sides))).toString();
@@ -14349,6 +15271,49 @@ function parseTransformationResult(llmResponse) {
 		throw new Error("Failed to parse transformation result from LLM");
 	}
 }
+/**
+* Sanitize a title for safe, display-clean embedding in the <artifact title="…">
+* attribute. The pristine title lives in the JSON body (which is what the preview
+* card renders); this attribute is only used as a label/list value and for id
+* resolution. So we strip the parse-breaking characters rather than HTML-entity-
+* encode them — entity encoding renders as "&amp;"/"&lt;" gibberish wherever
+* `metadata.title` is shown verbatim (knowledge viewer list, etc.). See #8905 review.
+*
+* - newlines/tabs → space: the attribute regexes use `.*?`, which won't cross newlines.
+* - strip <,>: keep the tag/attribute matchers ([^>]) from breaking.
+* - straight quotes → typographic quotes: the value matcher is [^"'], so BOTH a "
+*   and a ' (e.g. the apostrophe in "Can't") would terminate it early and truncate
+*   the title. Curly quotes (’ ” “) aren't in that class, so they're parse-safe and
+*   still read naturally.
+* `&` is left as-is: it doesn't break the regexes and React renders it correctly.
+*/
+function sanitizeArtifactTitle(title) {
+	return title.replace(/[\r\n\t]+/g, " ").replace(/[<>]/g, "").replace(/'/g, "’").replace(/"/g, "”").replace(/\s+/g, " ").trim();
+}
+/**
+* Wrap a drafted blog result in an <artifact> tag so it is surfaced as a
+* first-class artifact (streamed into the reply AND persisted via the
+* sharedToolBuilder tool_result extractor). See #8904.
+*
+* Two embedding concerns are handled here:
+* - Title goes in a tag attribute → sanitized via sanitizeArtifactTitle (parse-safe,
+*   display-clean; the real title is preserved untouched in the JSON body).
+* - Blog prose can legitimately contain the literal "</artifact>" sequence, which
+*   would truncate the non-greedy artifact-body regex. We escape it as "<\/artifact>";
+*   JSON.parse treats "\/" as "/" and restores the original losslessly on the client.
+*/
+function wrapDraftAsArtifact(result, identifier) {
+	const artifactTitle = sanitizeArtifactTitle(result.title);
+	const artifactBody = JSON.stringify(result, null, 2).replace(/<\/artifact>/gi, "<\\/artifact>");
+	return `✨ Blog draft created successfully!
+
+<artifact identifier="${identifier}" type="${ClaudeArtifactMimeTypes.BLOG_DRAFT}" title="${artifactTitle}">
+${artifactBody}
+</artifact>
+
+📋 The preview card above is ready for you to review and edit before publishing.
+`;
+}
 const blogDraftTool = {
 	name: "blog_draft",
 	implementation: (context) => ({
@@ -14390,14 +15355,7 @@ const blogDraftTool = {
 					contentLength: result.content.length,
 					tagsCount: result.suggestedTags.length
 				});
-				return `✨ Blog draft created successfully!
-
-\`\`\`json
-${JSON.stringify(result, null, 2)}
-\`\`\`
-
-📋 The preview card will appear below for you to review and edit before publishing.
-`;
+				return wrapDraftAsArtifact(result, `blog-draft-${randomUUID()}`);
 			} catch (error) {
 				logger.error("Blog draft creation failed:", error);
 				throw error;
@@ -15707,6 +16665,95 @@ const planetVisibilityTool = {
 		}
 	})
 };
+const CHUNK_TEXT_CAP = 1200;
+/** Clean "[Category] 01 Some Name.md" → "Some Name" for display. */
+function prettyFileName(fn) {
+	return fn.replace(/\.[a-z0-9]+$/i, "").replace(/^\[[^\]]*\]\s*/, "").replace(/^\d+[\s._-]*/, "").replace(/[-_]+/g, " ").trim();
+}
+/** Format semantic passages WITH their content so the model can answer without retrieving. */
+function formatSemanticResults(results) {
+	const blocks = results.map((r, i) => {
+		const text = r.chunkText.trim();
+		const clipped = text.length > CHUNK_TEXT_CAP ? `${text.slice(0, CHUNK_TEXT_CAP)}…` : text;
+		return `${i + 1}. **${prettyFileName(r.fileName)}** (relevance ${r.score.toFixed(2)})\n${clipped}`;
+	});
+	return `Found ${results.length} relevant passage(s) in the knowledge base — the content is included below, so answer directly and only call retrieve_knowledge_content if you need MORE detail from a specific file:\n\n` + blocks.join("\n\n---\n\n");
+}
+/**
+* Semantic-first KB search: embed the query and cosine-rank against the pre-computed chunk
+* vectors (tag-independent, ranks by meaning), returning the matching passage TEXT inline so
+* the model answers without a search→retrieve-N loop. Returns null to fall through to the
+* keyword path when embedding deps are unavailable or nothing matches.
+*/
+async function trySemanticKbSearch(context, query, tags, maxResults) {
+	const chunkRepo = context.db.fabfilechunks;
+	const adminSettings = context.db.adminSettings;
+	const apiKeys = context.db.apiKeys;
+	if (!context.db.fabfiles || !chunkRepo?.findVectorsByFabFileIds || !adminSettings || !apiKeys) return null;
+	try {
+		const modelRaw = await adminSettings.getSettingsValue("defaultEmbeddingModel");
+		if (!modelRaw || !isSupportedEmbeddingModel(modelRaw)) return null;
+		const embeddingModel = modelRaw;
+		const apiKeyTable = await (0, apiKeyService_exports.getEffectiveLLMApiKeys)(context.userId, {
+			db: {
+				apiKeys,
+				adminSettings
+			},
+			getSettingsByNames
+		}, { logger: context.logger });
+		const provider = getProviderFromModel(embeddingModel);
+		if (provider === "openai" && !apiKeyTable?.openai) return null;
+		if (provider === "voyageai" && !apiKeyTable?.voyageai) return null;
+		const { dataLakeTags, dataLakeTagPrefixes } = await getDynamicDataLakeAccess(context);
+		if (dataLakeTags.length === 0) return null;
+		const search = await semanticDataLakeSearch({
+			userId: context.userId,
+			userGroups: context.user.groups ?? [],
+			query,
+			tags,
+			topK: Math.max(maxResults, 6),
+			minScore: 0,
+			embeddingModel,
+			apiKeyTable,
+			dataLakeTags,
+			dataLakeTagPrefixes,
+			logger: context.logger
+		}, { db: {
+			fabfiles: context.db.fabfiles,
+			fabfilechunks: chunkRepo
+		} });
+		if (search.results.length === 0) return null;
+		const ranked = search.results.slice(0, maxResults);
+		const seenFile = /* @__PURE__ */ new Set();
+		const citables = [];
+		for (const r of ranked) {
+			if (seenFile.has(r.fileId)) continue;
+			seenFile.add(r.fileId);
+			citables.push({
+				id: r.fileId,
+				type: "document",
+				title: r.fileName,
+				url: `/opti?mode=datalake&article=${r.fileId}`,
+				description: r.fileTags.filter((t) => !t.startsWith("datalake:")).slice(0, 4).join(", ") || void 0,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				status: "complete",
+				metadata: {
+					sourceSystem: "knowledge_base",
+					tags: r.fileTags,
+					relevanceScore: r.score
+				}
+			});
+		}
+		const names = citables.slice(0, 3).map((c) => prettyFileName(c.title));
+		const more = citables.length > 3 ? ` +${citables.length - 3} more` : "";
+		await context.statusUpdate({ promptMeta: { citables } }, `📄 Found ${citables.length} relevant doc(s) in the data lake: ${names.join(", ")}${more}`);
+		context.logger.log(`📚 [semantic] returning ${ranked.length}/${search.results.length} passages from ${citables.length} files (top score ${search.results[0].score.toFixed(3)})`);
+		return formatSemanticResults(ranked);
+	} catch (err) {
+		context.logger.warn("📚 [semantic] KB search failed, falling back to keyword:", err);
+		return null;
+	}
+}
 /**
 * Formats fab file search results for LLM consumption
 */
@@ -15722,160 +16769,35 @@ function formatSearchResults(files) {
 }
 const knowledgeBaseSearchTool = {
 	name: "search_knowledge_base",
-	implementation: (context) => ({
-		toolFn: async (value) => {
-			const params = value;
-			await context.onStart?.("search_knowledge_base", params);
-			const { query, tags, file_type, max_results = 5 } = params;
-			context.logger.log("📚 Knowledge Base Search: userId:", context.userId, "query:", query, "tags:", tags);
-			if (!context.db.fabfiles) {
-				context.logger.error("❌ Knowledge Base Search: fabfiles repository not available");
-				return "Knowledge base search is not available at this time.";
-			}
-			try {
-				const { dataLakeTags, dataLakeTagPrefixes } = await getDynamicDataLakeAccess(context);
-				const searchResults = await context.db.fabfiles.search(context.userId, query, {
-					tags: tags || [],
-					type: file_type,
-					shared: false
-				}, {
-					page: 1,
-					limit: Math.min(max_results, 10)
-				}, {
-					by: "fileName",
-					direction: "asc"
-				}, {
-					textSearch: true,
-					includeShared: true,
-					userGroups: context.user.groups || [],
-					dataLakeTags,
-					dataLakeTagPrefixes,
-					excludeContent: true
-				});
-				context.logger.log("📚 Knowledge Base Search: Found", searchResults.data.length, "of", searchResults.total, "results. Files:", searchResults.data.map((f) => f.fileName));
-				if (searchResults.data.length > 0) {
-					const citables = searchResults.data.map((file, index) => {
-						const fileTags = (file.tags?.map((t) => t.name) || []).filter((t) => !t.startsWith("datalake:")).slice(0, 4).join(", ");
-						return {
-							id: file.id,
-							type: "document",
-							title: file.fileName,
-							url: `/opti?mode=datalake&article=${file.id}`,
-							description: fileTags || void 0,
-							timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-							status: "complete",
-							metadata: {
-								sourceSystem: "knowledge_base",
-								tags: file.tags?.map((t) => t.name) || [],
-								relevanceScore: 1 - index * .1
-							}
-						};
-					});
-					await context.statusUpdate({ promptMeta: { citables } }, "Knowledge base search results");
-					context.logger.log(`📚 Knowledge Base Search: Stored ${citables.length} citables`);
+	implementation: (context) => {
+		let searchCallCount = 0;
+		const MAX_SEARCHES = 3;
+		return {
+			toolFn: async (value) => {
+				const params = value;
+				await context.onStart?.("search_knowledge_base", params);
+				const { query, tags, file_type, max_results = 5 } = params;
+				searchCallCount++;
+				if (searchCallCount > MAX_SEARCHES) {
+					context.logger.log(`📚 Knowledge Base Search: call #${searchCallCount} — capped, instructing model to answer`);
+					return `You have already run ${searchCallCount - 1} knowledge-base searches; the relevant passages are in the conversation above. STOP searching and compose your complete answer NOW from those results. Do NOT call search_knowledge_base or retrieve_knowledge_content again unless a specific named fact is genuinely missing.`;
 				}
-				return formatSearchResults(searchResults.data);
-			} catch (error) {
-				context.logger.error("❌ Knowledge Base Search: Error during search:", error);
-				return "An error occurred while searching your knowledge base. Please try again.";
-			}
-		},
-		toolSchema: {
-			name: "search_knowledge_base",
-			description: "Search the user's uploaded knowledge base (fab files). Searches across file names, tags, and notes for broad recall. Returns relevant documents from the user's own files, organization-shared files, and files explicitly shared with them. Use this tool when the user asks about their own documents, uploaded files, or organization knowledge.",
-			parameters: {
-				type: "object",
-				properties: {
-					query: {
-						type: "string",
-						description: "The search query to find relevant documents. Matches against file names, tags, and notes."
-					},
-					tags: {
-						type: "array",
-						items: { type: "string" },
-						description: "Optional: filter results by tag names. Supports partial matching. For optimization docs, use tags like \"opti:family:scheduling\", \"opti:QUBO\", \"opti:solver:highs\". For IonQ sales intelligence, use tags like \"ionq:vertical:pharma\", \"ionq:competitor:ibm\", \"ionq:type:product-specs\", \"ionq:stage:discovery\", \"ionq:offering:forte\". Any matching tag qualifies the file."
-					},
-					file_type: {
-						type: "string",
-						enum: [
-							"pdf",
-							"text",
-							"image",
-							"excel",
-							"word",
-							"json",
-							"csv",
-							"markdown",
-							"code",
-							"url"
-						],
-						description: "Optional: filter results by file type"
-					},
-					max_results: {
-						type: "number",
-						description: "Maximum number of results to return (default: 5, max: 10)",
-						minimum: 1,
-						maximum: 10
-					}
-				},
-				required: ["query"]
-			}
-		}
-	})
-};
-const DEFAULT_MAX_CHARS = 8e3;
-const ABSOLUTE_MAX_CHARS = 16e3;
-const knowledgeBaseRetrieveTool = {
-	name: "retrieve_knowledge_content",
-	implementation: (context) => ({
-		toolFn: async (value) => {
-			const params = value;
-			await context.onStart?.("retrieve_knowledge_content", params);
-			const { file_id, tags, query, max_chars } = params;
-			const charBudget = Math.min(max_chars ?? DEFAULT_MAX_CHARS, ABSOLUTE_MAX_CHARS);
-			context.logger.log("📖 Knowledge Retrieve: params", {
-				file_id,
-				tags,
-				query,
-				max_chars: charBudget
-			});
-			if (!file_id && !tags?.length && !query) return "Error: You must provide at least one of file_id, tags, or query.";
-			if (!context.db.fabfiles) {
-				context.logger.error("❌ Knowledge Retrieve: fabfiles repository not available");
-				return "Knowledge base retrieval is not available at this time.";
-			}
-			if (!context.db.fabfilechunks) {
-				context.logger.error("❌ Knowledge Retrieve: fabfilechunks repository not available");
-				return "Knowledge base retrieval is not available at this time (chunk reader unavailable).";
-			}
-			try {
-				let files = [];
-				if (file_id) {
-					const ownedFile = await context.db.fabfiles.findByIdAndUserId(file_id, context.userId);
-					if (ownedFile) files = [ownedFile];
-					else {
-						const sharedFile = await context.db.fabfiles.findById(file_id);
-						if (sharedFile && !sharedFile.deletedAt && !sharedFile.archivedAt) {
-							const { dataLakeTags, dataLakeTagPrefixes } = await getDynamicDataLakeAccess(context);
-							const fileTags = sharedFile.tags?.map((t) => t.name) || [];
-							const hasMetaTagAccess = dataLakeTags.some((dlt) => fileTags.includes(dlt));
-							const hasPrefixAccess = dataLakeTagPrefixes.some((p) => fileTags.some((t) => t.startsWith(p)));
-							const hasShareAccess = sharedFile.users?.some((u) => u.userId === context.userId && u.permissions?.some((p) => p === "read" || p === "write"));
-							const userGroups = context.user.groups || [];
-							const hasGroupAccess = userGroups.length > 0 && sharedFile.groups?.some((g) => userGroups.includes(g.groupId) && g.permissions?.some((p) => p === "read" || p === "write"));
-							if (hasMetaTagAccess || hasPrefixAccess || hasShareAccess || hasGroupAccess) files = [sharedFile];
-						}
-					}
-					if (files.length === 0) return `No document found with ID "${file_id}". The file may not exist or you may not have access to it. Try using search_knowledge_base to find the correct file ID.`;
+				context.logger.log("📚 Knowledge Base Search: userId:", context.userId, "query:", query, "tags:", tags);
+				if (!context.db.fabfiles) {
+					context.logger.error("❌ Knowledge Base Search: fabfiles repository not available");
+					return "Knowledge base search is not available at this time.";
 				}
-				if (files.length === 0 && (tags?.length || query)) {
+				const semantic = await trySemanticKbSearch(context, query, tags, max_results);
+				if (semantic) return semantic;
+				try {
 					const { dataLakeTags, dataLakeTagPrefixes } = await getDynamicDataLakeAccess(context);
-					files = (await context.db.fabfiles.search(context.userId, query || "", {
+					const searchResults = await context.db.fabfiles.search(context.userId, query, {
 						tags: tags || [],
+						type: file_type,
 						shared: false
 					}, {
 						page: 1,
-						limit: 5
+						limit: dataLakeTags.length > 0 ? 200 : 50
 					}, {
 						by: "fileName",
 						direction: "asc"
@@ -15886,87 +16808,251 @@ const knowledgeBaseRetrieveTool = {
 						dataLakeTags,
 						dataLakeTagPrefixes,
 						excludeContent: true
-					})).data;
-					if (files.length === 0) return `No documents found matching ${[query && `query "${query}"`, tags?.length && `tags [${tags.join(", ")}]`].filter(Boolean).join(" and ")}. Try broadening your search with search_knowledge_base.`;
-				}
-				let totalCharsUsed = 0;
-				const sections = [];
-				const retrievedFiles = [];
-				for (const file of files) {
-					if (totalCharsUsed >= charBudget) break;
-					const chunks = await context.db.fabfilechunks.findByFabFileId(file.id);
-					if (chunks.length === 0) {
-						context.logger.log(`📖 Knowledge Retrieve: No chunks for file ${file.fileName} (${file.id})`);
-						continue;
-					}
-					const fullText = chunks.map((c) => c.text).join("\n");
-					const remainingBudget = charBudget - totalCharsUsed;
-					const truncated = fullText.length > remainingBudget;
-					const content = truncated ? fullText.slice(0, remainingBudget) : fullText;
-					const fileTags = file.tags?.map((t) => t.name).join(", ") || "none";
-					const charLabel = truncated ? `${content.length} (truncated from ${fullText.length})` : `${content.length}`;
-					sections.push(`### ${file.fileName} (ID: ${file.id})\nTags: ${fileTags}\nChunks: ${chunks.length} | Characters: ${charLabel}\n---\n` + content);
-					totalCharsUsed += content.length;
-					retrievedFiles.push(file);
+					});
+					const queryTerms = Array.from(new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3)));
+					const scoreFile = (file) => {
+						const hay = `${file.fileName} ${(file.tags?.map((t) => t.name) || []).join(" ")} ${file.notes || ""}`.toLowerCase();
+						return queryTerms.reduce((n, term) => hay.includes(term) ? n + 1 : n, 0);
+					};
+					const seen = /* @__PURE__ */ new Set();
+					const rankedResults = searchResults.data.filter((f) => {
+						const key = (f.fileName || f.id || "").toLowerCase();
+						if (seen.has(key)) return false;
+						seen.add(key);
+						return true;
+					}).map((f) => ({
+						f,
+						score: scoreFile(f)
+					})).sort((a, b) => b.score - a.score || a.f.fileName.localeCompare(b.f.fileName)).slice(0, max_results).map((r) => r.f);
+					context.logger.log("📚 Knowledge Base Search: Found", rankedResults.length, "of", searchResults.total, "results (deduped + relevance-ranked). Files:", rankedResults.map((f) => f.fileName));
+					if (rankedResults.length > 0) {
+						const citables = rankedResults.map((file, index) => {
+							const fileTags = (file.tags?.map((t) => t.name) || []).filter((t) => !t.startsWith("datalake:")).slice(0, 4).join(", ");
+							return {
+								id: file.id,
+								type: "document",
+								title: file.fileName,
+								url: `/opti?mode=datalake&article=${file.id}`,
+								description: fileTags || void 0,
+								timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+								status: "complete",
+								metadata: {
+									sourceSystem: "knowledge_base",
+									tags: file.tags?.map((t) => t.name) || [],
+									relevanceScore: 1 - index * .1
+								}
+							};
+						});
+						const prettyName = (fn) => fn.replace(/\.[a-z0-9]+$/i, "").replace(/^\[[^\]]*\]\s*/, "").replace(/^\d+[\s._-]*/, "").replace(/[-_]+/g, " ").trim();
+						const names = rankedResults.slice(0, 3).map((f) => prettyName(f.fileName));
+						const more = rankedResults.length > 3 ? ` +${rankedResults.length - 3} more` : "";
+						const foundStatus = `📄 Found ${rankedResults.length} in the data lake: ${names.join(", ")}${more}`;
+						await context.statusUpdate({ promptMeta: { citables } }, foundStatus);
+						context.logger.log(`📚 Knowledge Base Search: Stored ${citables.length} citables`);
+					} else await context.statusUpdate({}, `📭 No data-lake matches for “${query.length > 50 ? query.slice(0, 49) + "…" : query}” — broadening…`);
+					return formatSearchResults(rankedResults);
+				} catch (error) {
+					context.logger.error("❌ Knowledge Base Search: Error during search:", error);
+					return "An error occurred while searching your knowledge base. Please try again.";
 				}
-				if (retrievedFiles.length === 0) return "Found matching documents but they have no indexed content. The files may not have been processed yet.";
-				const citables = retrievedFiles.map((file, index) => {
-					const fileTags = (file.tags?.map((t) => t.name) || []).filter((t) => !t.startsWith("datalake:")).slice(0, 4).join(", ");
-					return {
-						id: file.id,
-						type: "document",
-						title: file.fileName,
-						url: `/opti?mode=datalake&article=${file.id}`,
-						description: fileTags || void 0,
-						timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-						status: "complete",
-						metadata: {
-							sourceSystem: "knowledge_base",
-							tags: file.tags?.map((t) => t.name) || [],
-							relevanceScore: 1 - index * .1
+			},
+			toolSchema: {
+				name: "search_knowledge_base",
+				description: "Semantic search over the user's knowledge base. Ranks documents by MEANING (embeddings) and returns the most relevant passage CONTENT inline — so you can usually answer directly from the results without any further calls. Use a clear natural-language query describing what you need; you do NOT need to know exact tags. Make ONE good search per distinct topic, then compose your answer.",
+				parameters: {
+					type: "object",
+					properties: {
+						query: {
+							type: "string",
+							description: "Natural-language description of what you need (e.g. \"IonQ Aria Forte Tempo product specs, #AQ, gate fidelity, use cases\"). Ranked by semantic similarity — be descriptive."
+						},
+						tags: {
+							type: "array",
+							items: { type: "string" },
+							description: "OPTIONAL narrowing filter — semantic ranking already finds the right docs, so usually omit this. If you do filter, use a real tag (matching is partial + case-insensitive), e.g. \"ionq:vertical:pharma\" or \"ionq:type:product-spec\"."
+						},
+						file_type: {
+							type: "string",
+							enum: [
+								"pdf",
+								"text",
+								"image",
+								"excel",
+								"word",
+								"json",
+								"csv",
+								"markdown",
+								"code",
+								"url"
+							],
+							description: "Optional: filter results by file type"
+						},
+						max_results: {
+							type: "number",
+							description: "Maximum number of results to return (default: 5, max: 10)",
+							minimum: 1,
+							maximum: 10
 						}
-					};
+					},
+					required: ["query"]
+				}
+			}
+		};
+	}
+};
+const DEFAULT_MAX_CHARS = 8e3;
+const ABSOLUTE_MAX_CHARS = 16e3;
+const knowledgeBaseRetrieveTool = {
+	name: "retrieve_knowledge_content",
+	implementation: (context) => {
+		let retrieveCallCount = 0;
+		const MAX_RETRIEVES = 2;
+		return {
+			toolFn: async (value) => {
+				const params = value;
+				await context.onStart?.("retrieve_knowledge_content", params);
+				const { file_id, tags, query, max_chars } = params;
+				const charBudget = Math.min(max_chars ?? DEFAULT_MAX_CHARS, ABSOLUTE_MAX_CHARS);
+				retrieveCallCount++;
+				if (retrieveCallCount > MAX_RETRIEVES) {
+					context.logger.log(`📖 Knowledge Retrieve: call #${retrieveCallCount} — capped, instructing model to answer`);
+					return `You have already retrieved ${retrieveCallCount - 1} documents and the content is in the conversation above. STOP retrieving and compose your complete answer NOW from what you have.`;
+				}
+				context.logger.log("📖 Knowledge Retrieve: params", {
+					file_id,
+					tags,
+					query,
+					max_chars: charBudget
 				});
-				if (citables.length > 0) {
-					await context.statusUpdate({ promptMeta: { citables } }, "Knowledge base content retrieved");
-					context.logger.log(`📖 Knowledge Retrieve: Stored ${citables.length} citables`);
+				if (!file_id && !tags?.length && !query) return "Error: You must provide at least one of file_id, tags, or query.";
+				if (!context.db.fabfiles) {
+					context.logger.error("❌ Knowledge Retrieve: fabfiles repository not available");
+					return "Knowledge base retrieval is not available at this time.";
+				}
+				if (!context.db.fabfilechunks) {
+					context.logger.error("❌ Knowledge Retrieve: fabfilechunks repository not available");
+					return "Knowledge base retrieval is not available at this time (chunk reader unavailable).";
 				}
-				return `Retrieved content from ${retrievedFiles.length} of ${files.length} document(s):\n
+				try {
+					let files = [];
+					if (file_id) {
+						const ownedFile = await context.db.fabfiles.findByIdAndUserId(file_id, context.userId);
+						if (ownedFile) files = [ownedFile];
+						else {
+							const sharedFile = await context.db.fabfiles.findById(file_id);
+							if (sharedFile && !sharedFile.deletedAt && !sharedFile.archivedAt) {
+								const { dataLakeTags, dataLakeTagPrefixes } = await getDynamicDataLakeAccess(context);
+								const fileTags = sharedFile.tags?.map((t) => t.name) || [];
+								const hasMetaTagAccess = dataLakeTags.some((dlt) => fileTags.includes(dlt));
+								const hasPrefixAccess = dataLakeTagPrefixes.some((p) => fileTags.some((t) => t.startsWith(p)));
+								const hasShareAccess = sharedFile.users?.some((u) => u.userId === context.userId && u.permissions?.some((p) => p === "read" || p === "write"));
+								const userGroups = context.user.groups || [];
+								const hasGroupAccess = userGroups.length > 0 && sharedFile.groups?.some((g) => userGroups.includes(g.groupId) && g.permissions?.some((p) => p === "read" || p === "write"));
+								if (hasMetaTagAccess || hasPrefixAccess || hasShareAccess || hasGroupAccess) files = [sharedFile];
+							}
+						}
+						if (files.length === 0) return `No document found with ID "${file_id}". The file may not exist or you may not have access to it. Try using search_knowledge_base to find the correct file ID.`;
+					}
+					if (files.length === 0 && (tags?.length || query)) {
+						const { dataLakeTags, dataLakeTagPrefixes } = await getDynamicDataLakeAccess(context);
+						files = (await context.db.fabfiles.search(context.userId, query || "", {
+							tags: tags || [],
+							shared: false
+						}, {
+							page: 1,
+							limit: 5
+						}, {
+							by: "fileName",
+							direction: "asc"
+						}, {
+							textSearch: true,
+							includeShared: true,
+							userGroups: context.user.groups || [],
+							dataLakeTags,
+							dataLakeTagPrefixes,
+							excludeContent: true
+						})).data;
+						if (files.length === 0) return `No documents found matching ${[query && `query "${query}"`, tags?.length && `tags [${tags.join(", ")}]`].filter(Boolean).join(" and ")}. Try broadening your search with search_knowledge_base.`;
+					}
+					let totalCharsUsed = 0;
+					const sections = [];
+					const retrievedFiles = [];
+					for (const file of files) {
+						if (totalCharsUsed >= charBudget) break;
+						const chunks = await context.db.fabfilechunks.findByFabFileId(file.id);
+						if (chunks.length === 0) {
+							context.logger.log(`📖 Knowledge Retrieve: No chunks for file ${file.fileName} (${file.id})`);
+							continue;
+						}
+						const fullText = chunks.map((c) => c.text).join("\n");
+						const remainingBudget = charBudget - totalCharsUsed;
+						const truncated = fullText.length > remainingBudget;
+						const content = truncated ? fullText.slice(0, remainingBudget) : fullText;
+						const fileTags = file.tags?.map((t) => t.name).join(", ") || "none";
+						const charLabel = truncated ? `${content.length} (truncated from ${fullText.length})` : `${content.length}`;
+						sections.push(`### ${file.fileName} (ID: ${file.id})\nTags: ${fileTags}\nChunks: ${chunks.length} | Characters: ${charLabel}\n---\n` + content);
+						totalCharsUsed += content.length;
+						retrievedFiles.push(file);
+					}
+					if (retrievedFiles.length === 0) return "Found matching documents but they have no indexed content. The files may not have been processed yet.";
+					const citables = retrievedFiles.map((file, index) => {
+						const fileTags = (file.tags?.map((t) => t.name) || []).filter((t) => !t.startsWith("datalake:")).slice(0, 4).join(", ");
+						return {
+							id: file.id,
+							type: "document",
+							title: file.fileName,
+							url: `/opti?mode=datalake&article=${file.id}`,
+							description: fileTags || void 0,
+							timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+							status: "complete",
+							metadata: {
+								sourceSystem: "knowledge_base",
+								tags: file.tags?.map((t) => t.name) || [],
+								relevanceScore: 1 - index * .1
+							}
+						};
+					});
+					if (citables.length > 0) {
+						await context.statusUpdate({ promptMeta: { citables } }, "Knowledge base content retrieved");
+						context.logger.log(`📖 Knowledge Retrieve: Stored ${citables.length} citables`);
+					}
+					return `Retrieved content from ${retrievedFiles.length} of ${files.length} document(s):\n
 ` + sections.join("\n\n---\n\n");
-			} catch (error) {
-				context.logger.error("❌ Knowledge Retrieve: Error during retrieval:", error);
-				return "An error occurred while retrieving document content. Please try again.";
-			}
-		},
-		toolSchema: {
-			name: "retrieve_knowledge_content",
-			description: "Read the actual text content of knowledge base documents. Use this after search_knowledge_base to read documents by file ID, or provide tags/query to find and read documents in one step. Returns the full text content (up to the character budget) for grounding your responses in the user's curated knowledge.",
-			parameters: {
-				type: "object",
-				properties: {
-					file_id: {
-						type: "string",
-						description: "The file ID to retrieve (from search_knowledge_base results). Most efficient for single-document retrieval."
-					},
-					tags: {
-						type: "array",
-						items: { type: "string" },
-						description: "Filter documents by tags. For optimization docs, use tags like \"opti:family:scheduling\", \"opti:solver:highs\". For IonQ sales intelligence, use tags like \"ionq:vertical:pharma\", \"ionq:competitor:ibm\", \"ionq:type:product-specs\", \"ionq:offering:forte\"."
-					},
-					query: {
-						type: "string",
-						description: "Search query to find documents. Can be combined with tags for more targeted retrieval."
-					},
-					max_chars: {
-						type: "number",
-						description: "Maximum characters of content to return (default: 8000, max: 16000). Lower values for quick lookups, higher for detailed reading.",
-						minimum: 500,
-						maximum: 16e3
+				} catch (error) {
+					context.logger.error("❌ Knowledge Retrieve: Error during retrieval:", error);
+					return "An error occurred while retrieving document content. Please try again.";
+				}
+			},
+			toolSchema: {
+				name: "retrieve_knowledge_content",
+				description: "Read the actual text content of knowledge base documents. Use this after search_knowledge_base to read documents by file ID, or provide tags/query to find and read documents in one step. Returns the full text content (up to the character budget) for grounding your responses in the user's curated knowledge.",
+				parameters: {
+					type: "object",
+					properties: {
+						file_id: {
+							type: "string",
+							description: "The file ID to retrieve (from search_knowledge_base results). Most efficient for single-document retrieval."
+						},
+						tags: {
+							type: "array",
+							items: { type: "string" },
+							description: "OPTIONAL tag filter (usually unnecessary — search_knowledge_base already returns the content you need). If used, real examples: \"ionq:vertical:pharma\", \"ionq:competitor:ibm\", \"ionq:type:product-spec\"."
+						},
+						query: {
+							type: "string",
+							description: "Search query to find documents. Can be combined with tags for more targeted retrieval."
+						},
+						max_chars: {
+							type: "number",
+							description: "Maximum characters of content to return (default: 8000, max: 16000). Lower values for quick lookups, higher for detailed reading.",
+							minimum: 500,
+							maximum: 16e3
+						}
 					}
 				}
 			}
-		}
-	})
+		};
+	}
 };
 function formatResult$1(result) {
 	const lines = [
@@ -18848,6 +19934,13 @@ z.object({
 	knowledgeIds: z.array(z.string()).optional(),
 	artifactIds: z.array(z.string()).optional(),
 	agentIds: z.array(z.string()).optional(),
+	systemPromptText: z.string().optional(),
+	surface: z.string().optional(),
+	enabledTools: z.array(z.string()).optional(),
+	disabledTools: z.array(z.string()).optional(),
+	forceKnowledgeRetrieval: z.boolean().optional(),
+	retrievalTags: z.array(z.string()).optional(),
+	temperature: z.number().optional(),
 	tags: z.array(z.object({
 		name: z.string(),
 		strength: z.number()
@@ -18857,7 +19950,8 @@ z.object({
 	clonedSourceId: z.string().optional().nullable(),
 	forkedSourceId: z.string().optional().nullable(),
 	projectId: z.string().optional(),
-	lastUsedModel: z.string().optional().nullable()
+	lastUsedModel: z.string().optional().nullable(),
+	optiHashi: z.boolean().optional()
 });
 z.object({ id: z.string() });
 z.object({ id: z.string() });
@@ -23995,6 +25089,7 @@ var ServerLlmBackend = class ServerLlmBackend {
 			let eventCount = 0;
 			const accumulator = new StreamAccumulator();
 			let receivedDone = false;
+			let receivedError = false;
 			const parser = createParser({ onEvent: (event) => {
 				eventCount++;
 				streamLogger.onEvent(eventCount, event.data || "");
@@ -24015,6 +25110,7 @@ var ServerLlmBackend = class ServerLlmBackend {
 				try {
 					const parsed = JSON.parse(data);
 					if (parsed.type === "error") {
+						receivedError = true;
 						streamLogger.onCriticalEvent(eventCount, "ERROR", parsed.message || "Server error");
 						reject(new Error(parsed.message || "Server error"));
 						return;
@@ -24061,6 +25157,10 @@ var ServerLlmBackend = class ServerLlmBackend {
 				parser.feed(chunk.toString());
 			});
 			response.data.on("end", () => {
+				if (receivedError) {
+					logger.debug("[ServerLlmBackend] Stream ended after server-sent error event");
+					return;
+				}
 				if (!receivedDone) {
 					logger.warn(`[ServerLlmBackend] Stream ended without [DONE] signal. Accumulated text: ${accumulator.accumulatedLength} chars, tools: ${accumulator.toolCount}`);
 					if (!accumulator.isEmpty()) {