@iowarp/clio-coder 0.4.6 → 0.4.7

package/dist/worker/entry.js

@@ -13,21 +13,25 @@ import {
   lockedSynthesisRepromptMessages,
   patchWorkerRequestPayload,
   registerCoreTools,
+  registerHarnessExtensionTools,
   resolveAgentTools,
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-6RYDAVQT.js";
-import "../chunk-JABWPKFY.js";
+} from "../chunk-CE64C5K5.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-BT7HGDOX.js";
-import "../chunk-BBV5TKE6.js";
-import "../chunk-3QKXHCGS.js";
-import "../chunk-PWWSIB2A.js";
-import "../chunk-KTFSFCVN.js";
+} from "../chunk-MBJO5VNZ.js";
+import "../chunk-JABWPKFY.js";
+import {
+  readLayeredSettings
+} from "../chunk-4MFBBY2Z.js";
+import "../chunk-CPXGJI2A.js";
+import "../chunk-MZHXENL7.js";
+import "../chunk-ZGIGW4ZG.js";
+import "../chunk-HRAKUPIH.js";
 import "../chunk-XCUDZQLX.js";
 import "../chunk-K2BLQC5E.js";
 import {
@@ -46,29 +50,28 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-P5JMBPDJ.js";
-import "../chunk-K2HL3GBL.js";
+} from "../chunk-NO7J45X6.js";
+import {
+  contextHash,
+  messageToolCalls,
+  seededWorkerMessages
+} from "../chunk-T4TY5GG3.js";
 import "../chunk-YPRSNUTC.js";
 import {
   describeCallTarget
 } from "../chunk-2GPGAE5W.js";
+import "../chunk-OH3YYA3B.js";
+import "../chunk-24S3DN22.js";
 import "../chunk-SL2RDHKO.js";
 import "../chunk-YGDMBK7O.js";
 import "../chunk-V552WL53.js";
-import "../chunk-7JSSKXG2.js";
+import "../chunk-IZYTT3CD.js";
 import "../chunk-KECNXMDE.js";
 import "../chunk-WXA2CFJO.js";
-import "../chunk-CBSKDFWL.js";
-import "../chunk-LY4N4TTL.js";
-import {
-  RESULT_CONTRACT_REPAIR_LIMIT,
-  parseWorkerResultContract,
-  resultContractRepairMessages,
-  validateResultContract
-} from "../chunk-OQM5IVJY.js";
+import "../chunk-GEVQNST4.js";
+import "../chunk-3LXJOICS.js";
 import "../chunk-L4N3DWNW.js";
-import "../chunk-WJIMKGD6.js";
-import "../chunk-GH5ZR6JP.js";
+import "../chunk-BAU36233.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -84,6 +87,9 @@ import {
   withinFrameBudget,
   workerSpecDigest
 } from "../chunk-VQD7NH7Z.js";
+import {
+  deleteInjectedCompileCacheFrom
+} from "../chunk-CKK25WN3.js";
 import "../chunk-O3VV6IVK.js";
 import {
   agentSkillToolPolicy
@@ -95,65 +101,91 @@ import {
   createLoopState,
   isSubset,
   observe
-} from "../chunk-I2K2NCZQ.js";
+} from "../chunk-BQQ5MXUC.js";
 import {
   createSafetyPolicyEngine
-} from "../chunk-IKRWLEDA.js";
-import "../chunk-NTK3WTHM.js";
+} from "../chunk-DLIYANB7.js";
+import "../chunk-24TOGHPO.js";
 import {
   FileKnowledgeBase,
   applyModelCapabilityPatch,
+  estimateInputTokensFromContext,
   loadPluginRuntimes,
   registerClioApiProviders,
   resolveModelRuntimeCapabilitiesForModel,
   resolveProviderKnowledgeBaseRoots,
+  resolveReservedOutputTokens,
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-4U4TKZFR.js";
+} from "../chunk-WT5TRMO4.js";
 import "../chunk-MCJKEGHO.js";
-import "../chunk-77CZRFTE.js";
 import {
-  classify
-} from "../chunk-LUL5Z66S.js";
-import {
-  protectedArtifactMutationBlockReason
-} from "../chunk-M6TAYK66.js";
-import "../chunk-KQ6IDQIB.js";
-import "../chunk-PZN2LQY6.js";
-import "../chunk-R2P2U3ZS.js";
-import "../chunk-NTTS3O53.js";
-import "../chunk-M4KFUXS7.js";
-import "../chunk-J2FYEQ5L.js";
+  estimateAgentContextBreakdown,
+  estimateAgentMessageTokens
+} from "../chunk-77CZRFTE.js";
+import "../chunk-BO4XV5VX.js";
+import "../chunk-VTYHHQ57.js";
 import {
   DEFAULT_AUTONOMY_LEVEL
 } from "../chunk-EM2WNQS2.js";
-import {
-  readSettings,
-  validateSettingsFile
-} from "../chunk-WNGF5AJX.js";
-import "../chunk-DVNAPPXU.js";
-import "../chunk-5CY4Q6QI.js";
 import "../chunk-FQOOGXBH.js";
 import "../chunk-UHW5V7HC.js";
 import "../chunk-B6UM3OZC.js";
 import "../chunk-MYI32N4R.js";
-import {
-  ToolNames
-} from "../chunk-EHOSNVVM.js";
 import "../chunk-KMF54VH3.js";
 import "../chunk-5A6XR3RJ.js";
 import "../chunk-EFSEIZE6.js";
 import "../chunk-B5ZTR6KZ.js";
-import "../chunk-HL26ADLH.js";
+import "../chunk-6CB2IL4N.js";
 import "../chunk-3A3CUMKA.js";
+import {
+  registerBuiltinRuntimes
+} from "../chunk-SELG4SUR.js";
+import "../chunk-KS7ETA3P.js";
+import "../chunk-6TAATXXH.js";
+import "../chunk-VNBICSS2.js";
+import {
+  getRuntimeRegistry
+} from "../chunk-SRCEQKQS.js";
+import "../chunk-TN5FW4XY.js";
+import {
+  engineStreamSimple,
+  registerFauxFromEnv
+} from "../chunk-5CMARGPF.js";
+import "../chunk-DXVMLM3Z.js";
+import "../chunk-SER7RRAE.js";
+import {
+  RESULT_CONTRACT_REPAIR_LIMIT,
+  parseWorkerResultContract,
+  resultContractRepairMessages,
+  validateResultContract
+} from "../chunk-34XHRVKG.js";
+import "../chunk-XW2UZICE.js";
+import {
+  readSettings
+} from "../chunk-4QKAITQT.js";
+import "../chunk-DVNAPPXU.js";
+import "../chunk-5EQO5NWP.js";
+import {
+  classify
+} from "../chunk-HOX4YZ2K.js";
+import {
+  protectedArtifactMutationBlockReason
+} from "../chunk-2O2LVQQK.js";
+import "../chunk-KQ6IDQIB.js";
+import "../chunk-GH5ZR6JP.js";
+import "../chunk-R2P2U3ZS.js";
+import "../chunk-NTTS3O53.js";
+import "../chunk-M4KFUXS7.js";
+import {
+  ToolNames
+} from "../chunk-WLHX3MM5.js";
+import "../chunk-GD55RTIW.js";
 import {
   readClioVersion
 } from "../chunk-E3LEPLQ2.js";
-import {
-  registerBuiltinRuntimes
-} from "../chunk-WV6TDAPN.js";
-import "../chunk-3BJGMT2D.js";
+import "../chunk-3XE4NRLF.js";
 import "../chunk-U2MSJ57E.js";
 import {
   configureGuardrails,
@@ -170,25 +202,15 @@ import "../chunk-6EXUUOSN.js";
 import {
   AI_AGENT_NAME
 } from "../chunk-ZTNFYMIO.js";
-import "../chunk-HHVJNVUJ.js";
-import "../chunk-HXHFDHB6.js";
-import "../chunk-VNBICSS2.js";
-import "../chunk-2QPI3TR3.js";
+import "../chunk-DVJL77SO.js";
 import "../chunk-TK2BMCBZ.js";
 import "../chunk-B5GGDIHT.js";
-import "../chunk-ZZFWWYLX.js";
-import {
-  getRuntimeRegistry
-} from "../chunk-SRCEQKQS.js";
-import "../chunk-TN5FW4XY.js";
 import {
-  registerFauxFromEnv
-} from "../chunk-5CMARGPF.js";
-import "../chunk-DXVMLM3Z.js";
+  safeResourceWrite
+} from "../chunk-ZZFWWYLX.js";
 import {
-  deleteInjectedCompileCacheFrom
-} from "../chunk-CKK25WN3.js";
-import "../chunk-CTTI7G3T.js";
+  clioStateDir
+} from "../chunk-CTTI7G3T.js";
 import {
   init_esm_shims
 } from "../chunk-ECBHH7LU.js";
@@ -198,6 +220,151 @@ init_esm_shims();
 
 // src/engine/worker-runtime.ts
 init_esm_shims();
+
+// src/domains/context/worker/pressure.ts
+init_esm_shims();
+var WorkerContextExhaustedError = class extends Error {
+};
+function createWorkerContextGuard(archive) {
+  const evicted = /* @__PURE__ */ new Map();
+  let calls = 0;
+  let firstInputLength = 0;
+  let lastRequestTokens = 0;
+  let anchorKey = "";
+  let anchorUsage = 0;
+  let anchorFootprint = 0;
+  return (input) => {
+    const ceiling = Math.min(
+      Math.floor(input.contextWindow * (input.threshold ?? 0.8)),
+      input.contextWindow - input.outputReserve
+    );
+    const key = (message) => contextHash(message);
+    const messages = input.messages.map((message) => evicted.get(key(message)) ?? message);
+    const breakdown = estimateAgentContextBreakdown({ systemPrompt: input.systemPrompt, tools: input.tools, messages });
+    let structural = Object.values(breakdown).reduce((sum, value) => sum + value, 0);
+    if (calls === 0) firstInputLength = input.messages.length;
+    else {
+      for (let index = messages.length - 1; index >= firstInputLength; index--) {
+        const message = messages[index];
+        if (message?.role !== "assistant" || !message.usage || message.stopReason === "error" || message.stopReason === "aborted")
+          continue;
+        const usage = message.usage;
+        const actual = usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+        const nextKey = key(message);
+        if (nextKey !== anchorKey) {
+          anchorKey = nextKey;
+          anchorUsage = Number.isFinite(actual) && actual > 0 ? actual : 0;
+          anchorFootprint = lastRequestTokens + estimateAgentMessageTokens(message);
+        }
+        break;
+      }
+    }
+    const count = () => Math.max(structural, anchorUsage > 0 ? anchorUsage + structural - anchorFootprint : 0);
+    const accepted = () => {
+      calls++;
+      lastRequestTokens = structural;
+      return messages;
+    };
+    const replace = (index, original, projected) => {
+      const saved = estimateAgentMessageTokens(original) - estimateAgentMessageTokens(projected);
+      if (saved <= 0) return;
+      evicted.set(key(original), projected);
+      messages[index] = projected;
+      structural -= saved;
+    };
+    if (count() <= ceiling) return accepted();
+    if (calls === 0)
+      throw new WorkerContextExhaustedError(
+        "worker context: initial request leaves insufficient context headroom; use a smaller splice"
+      );
+    if (input.autoEvict === false)
+      throw new WorkerContextExhaustedError("worker context: context budget exhausted with automatic eviction disabled");
+    const assistantIndices = input.messages.flatMap((message, index) => message.role === "assistant" ? [index] : []);
+    const cutoff = assistantIndices[Math.max(0, assistantIndices.length - 2)] ?? 0;
+    const toolCalls = new Map(input.messages.flatMap(messageToolCalls).map((call) => [call.id, call]));
+    for (let index = 0; index < cutoff && count() > ceiling; index++) {
+      const message = input.messages[index];
+      if (!message || evicted.has(key(message))) continue;
+      if (message.role === "assistant") {
+        const content = message.content.filter((block) => block.type !== "thinking");
+        if (content.length === 0 || content.length === message.content.length) continue;
+        const projected = { ...message, content };
+        replace(index, message, projected);
+      } else if (message.role === "toolResult" && !message.isError) {
+        const name = toolCalls.get(message.toolCallId)?.name;
+        if (!name || !["read", "grep", "find", "ls", "code_nav", "web_fetch"].includes(name)) continue;
+        if (JSON.stringify(message.content).length < 1e3) continue;
+        const ref = key(message);
+        const file = archive(ref, structuredClone(message));
+        const projected = {
+          ...message,
+          content: [
+            {
+              type: "text",
+              text: `[Worker context observation worker:${ref} evicted. Recover with context(scope="recall", ref="worker:${ref}"). Exact historical result: ${file}. Read that file if needed; reread the source for current contents.]`
+            }
+          ]
+        };
+        replace(index, message, projected);
+      }
+    }
+    if (count() > ceiling)
+      throw new WorkerContextExhaustedError(
+        "worker context: protected task context exceeds available headroom after reversible eviction"
+      );
+    return accepted();
+  };
+}
+
+// src/domains/context/worker/recall.ts
+init_esm_shims();
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+function createWorkerObservationStore() {
+  const records = /* @__PURE__ */ new Map();
+  return {
+    archive(ref, message) {
+      if (contextHash(message) !== ref) throw new Error("worker context: observation digest mismatch");
+      const file = join(clioStateDir(), "context-observations", `${ref}.json`);
+      safeResourceWrite(file, `${JSON.stringify(message)}
+`, { mode: 384 });
+      records.set(`worker:${ref}`, { file, label: message.role === "toolResult" ? message.toolName : message.role });
+      return file;
+    },
+    recall(args) {
+      if (args.ref !== void 0) {
+        const ref = typeof args.ref === "string" ? args.ref.trim() : "";
+        const record = records.get(ref);
+        if (!record) return { error: "ref is not an evicted observation from this worker run" };
+        try {
+          const body = readFileSync(record.file, "utf8");
+          if (`worker:${contextHash(JSON.parse(body))}` !== ref) return { error: "observation digest mismatch" };
+          return { body: `Historical observation ${ref}; this is not a new source read.
+${body}`, total: 1, shown: 1 };
+        } catch {
+          return { error: "persisted worker observation is unavailable or malformed" };
+        }
+      }
+      const query = typeof args.query === "string" ? args.query.trim().toLowerCase() : "";
+      const limit = typeof args.limit === "number" && Number.isSafeInteger(args.limit) ? Math.max(1, Math.min(12, args.limit)) : 8;
+      const offset = typeof args.offset === "number" && Number.isSafeInteger(args.offset) ? Math.max(0, args.offset) : 0;
+      const matches = [...records].map(([ref, item]) => `${ref} ${item.label}`).filter((line) => line.toLowerCase().includes(query));
+      const page = matches.slice(offset, offset + limit);
+      const nextOffset = offset + page.length < matches.length ? offset + page.length : void 0;
+      return {
+        body: [
+          ...page,
+          nextOffset === void 0 ? "End of this worker's evicted observations." : `More observations: offset=${nextOffset}.`
+        ].join("\n"),
+        total: matches.length,
+        shown: page.length,
+        ...nextOffset === void 0 ? {} : { nextOffset }
+      };
+    }
+  };
+}
+
+// src/engine/worker-runtime.ts
 import path from "node:path";
 
 // src/engine/claude/sdk-runtime.ts
@@ -286,7 +453,7 @@ function fallbackRejection(policy) {
     hints: []
   };
 }
-function createWorkerToolRegistry(middlewareSnapshot, safety = createWorkerSafety(), skillLoaderOptions, hookRegistrations, autonomy, onMiddlewareEffects, agentLedger) {
+function createWorkerToolRegistry(middlewareSnapshot, safety = createWorkerSafety(), skillLoaderOptions, hookRegistrations, autonomy, onMiddlewareEffects, agentLedger, workerRecall) {
   const middleware = createMiddlewareContractFromSnapshot(middlewareSnapshot ?? { version: 1, rules: [] });
   for (const registration2 of hookRegistrations ?? []) {
     middleware.registerHook(registration2);
@@ -299,6 +466,7 @@ function createWorkerToolRegistry(middlewareSnapshot, safety = createWorkerSafet
   });
   const registration = registerCoreTools(registry, {
     includeLedgerTools: true,
+    ...workerRecall ? { workerRecall } : {},
     ...agentLedger ? { agentLedger } : {},
     // A worker cannot install a skill or reach the operator who could, so
     // its skill listing carries installed (or bound) skills only; the
@@ -311,6 +479,7 @@ function createWorkerToolRegistry(middlewareSnapshot, safety = createWorkerSafet
     })
   });
   assertRegisteredBuiltinTools(registry, registration, false);
+  registerHarnessExtensionTools(registry);
   return registry;
 }
 function attestedToolSignature(input) {
@@ -1001,6 +1170,8 @@ function resolveWorkerRuntimeBudget(input) {
 }
 function startWorkerRun(input, emit) {
   assertResponseSchemaRuntime(input);
+  if (input.contextSeed && input.runtime.kind !== "http")
+    throw new Error("worker context: history seeds require a native Pi runtime");
   if (input.resultContract !== void 0) parseWorkerResultContract(input.resultContract, "WorkerSpec.resultContract");
   if (input.runtime.id === "claude-sdk") {
     return startClaudeSdkWorkerRun(input, emit);
@@ -1012,7 +1183,7 @@ function startWorkerRun(input, emit) {
     return startAntigravityWorkerRun(input, emit);
   }
   registerClioApiProviders();
-  const workerSettings = validateSettingsFile().settings;
+  const workerSettings = readLayeredSettings(input.cwd ?? process.cwd()).settings;
   setGlobalDefaultMaxOutputTokens(workerSettings.chat.maxOutputTokens);
   configureGuardrails(guardrailValuesFromSettings(workerSettings));
   const fauxModel = registerFauxFromEnv();
@@ -1073,6 +1244,7 @@ function startWorkerRun(input, emit) {
       }
     } : {}
   });
+  const observations = createWorkerObservationStore();
   const registry = createWorkerToolRegistry(
     input.middlewareSnapshot,
     safety,
@@ -1098,7 +1270,8 @@ function startWorkerRun(input, emit) {
     ],
     input.autonomy,
     (effects) => middlewareToolChoice.apply(effects),
-    input.agentLedger
+    input.agentLedger,
+    observations.recall
   );
   const contractCwd = input.cwd ?? process.cwd();
   let resultContractRepairsQueued = 0;
@@ -1181,13 +1354,46 @@ function startWorkerRun(input, emit) {
     model,
     input.runtimeResolution?.effectiveThinkingLevel ?? input.thinkingLevel
   );
+  const inheritedMessages = seededWorkerMessages(input.contextSeed);
+  const inheritedCount = inheritedMessages.length;
+  const contextGuard = createWorkerContextGuard(observations.archive);
   const options = {
+    streamFn: (currentModel, currentContext, streamOptions) => {
+      const window = input.runtimeResolution?.capabilities.contextWindow ?? currentModel.contextWindow;
+      let messages;
+      try {
+        messages = contextGuard({
+          messages: currentContext.messages,
+          systemPrompt: currentContext.systemPrompt ?? "",
+          tools: currentContext.tools ?? [],
+          contextWindow: window,
+          threshold: workerSettings.context.compaction.threshold,
+          autoEvict: workerSettings.context.compaction.auto && workerSettings.context.workingSet.enabled,
+          outputReserve: resolveReservedOutputTokens(currentModel.maxTokens, {
+            api: currentModel.api,
+            contextWindow: window,
+            inputTokens: estimateInputTokensFromContext(currentContext)
+          })
+        });
+      } catch (error) {
+        if (error instanceof WorkerContextExhaustedError) {
+          workerBoundFailure = error.message;
+          emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_context_exhausted" } });
+        }
+        throw error;
+      }
+      return engineStreamSimple(
+        currentModel,
+        { ...currentContext, messages },
+        streamOptions
+      );
+    },
     initialState: {
       systemPrompt: input.systemPrompt,
       model,
       thinkingLevel: effectiveThinkingLevel,
       tools,
-      messages: []
+      messages: inheritedMessages
     },
     onPayload: async (payload, currentModel) => {
       const middlewareChoice = middlewareToolChoice.current();
@@ -1459,12 +1665,12 @@ function startWorkerRun(input, emit) {
       await agent.waitForIdle();
       unsubscribe();
       if (workerBoundFailure !== null) {
-        return { messages: agent.state.messages, exitCode: 1 };
+        return { messages: agent.state.messages.slice(inheritedCount), exitCode: 1 };
       }
       if (permissionFailure) {
-        return { messages: agent.state.messages, exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
+        return { messages: agent.state.messages.slice(inheritedCount), exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
       }
-      const messages = agent.state.messages;
+      const messages = agent.state.messages.slice(inheritedCount);
       const errorMessage = getTerminalAgentError(messages);
       if (errorMessage !== null) {
         if (errorMessage.length > 0) {
@@ -1477,16 +1683,16 @@ function startWorkerRun(input, emit) {
     } catch (err) {
       unsubscribe();
       if (workerBoundFailure !== null) {
-        return { messages: agent.state.messages, exitCode: 1 };
+        return { messages: agent.state.messages.slice(inheritedCount), exitCode: 1 };
       }
       if (permissionFailure) {
-        return { messages: agent.state.messages, exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
+        return { messages: agent.state.messages.slice(inheritedCount), exitCode: WORKER_EXIT_PERMISSION_REQUIRED };
       }
       const msg = err instanceof Error ? err.message : String(err);
-      emit({ type: "agent_end", messages: agent.state.messages });
+      emit({ type: "agent_end", messages: agent.state.messages.slice(inheritedCount) });
       process.stderr.write(`[worker] agent error: ${msg}
 `);
-      return { messages: agent.state.messages, exitCode: 1 };
+      return { messages: agent.state.messages.slice(inheritedCount), exitCode: 1 };
     } finally {
       clearActiveEscalation();
       unsubscribePermission();
@@ -1985,6 +2191,7 @@ async function main() {
   demux.onLedgerDelta((entries) => ledgerPort.acceptDelta(entries));
   const input = {
     systemPrompt: spec.systemPrompt,
+    ...spec.contextSeed ? { contextSeed: spec.contextSeed } : {},
     dynamicPromptMessages: spec.dynamicPromptMessages ?? [],
     agentId: spec.agentId,
     task: spec.task,

package/docs/README.md

@@ -64,6 +64,9 @@ interactive session. `clio-coder doctor` is a read-only installation check;
 | Skills discovery, marketplace safety, installation, and publishing | [Skills Marketplace](guide/skills-marketplace.md) |
 | Agents, prompts, extensions, and portable share archives | [Extensions and Sharing](guide/extensions-and-sharing.md) |
 | Private resource catalogs and synchronization | [Resource Library](guide/resource-library.md) |
+| Portable domain bundles, library pins, and lifecycle | [Plugins](guide/plugins.md) |
+| Package manifests and component references | [Authoring Plugins](guide/authoring-plugins.md) |
+| Executable harness capabilities | [Harness Extensions](guide/harness-extensions.md) |
 | TUI layout, responsive behavior, colors, and interaction rules | [TUI Design](architecture/tui-design.md) |
 | Terminal panes beside a session and the files pane: install, keys, settings, doctor, troubleshooting | [Panes and the Files Pane](guide/panes-and-files.md) |
 
@@ -92,6 +95,7 @@ validation, reference data, or human scientific judgment.
 | An executable multi-node walkthrough with a reviewer gate | [Fleet Demo Runbook](process/fleet-demo-runbook.md) |
 | Capacity leases, heartbeats, locks, and node drain control | [Capacity and Scheduling](architecture/capacity-and-scheduling.md) |
 | Worker process protocol, watchdogs, steering, and exit mapping | [Worker Dispatch Mechanics](architecture/worker-dispatch-mechanics.md) |
+| Worker context inheritance, fork, and splice modes | [Worker Context](architecture/worker-context.md) |
 | Typed dispatch intent and compatibility boundaries | [Dispatch Typed Intent](architecture/dispatch-typed-intent.md) |
 | Why dispatch remains one domain and where its seams actually are | [Dispatch Architecture Rationale](architecture/dispatch-architecture-rationale.md) |
 
@@ -103,6 +107,7 @@ validation, reference data, or human scientific judgment.
 | Prompt-envelope reuse, provider tool delivery, and bounded results | [Prompt Envelope and Tools](architecture/prompt-envelope-and-tools.md) |
 | All built-in worker tools, arguments, outputs, and error examples | [Tool Usage](guide/tool-usage.md) |
 | Implementing a runtime or inference-server adapter | [Provider Adapter Cookbook](architecture/provider-adapter-cookbook.md) |
+| External coding agent discovery, inspection, and safe resource adoption | [Coding Agent Interoperability](guide/interop.md) |
 | Middleware hooks, effects, budgets, and component snapshots | [Middleware and Components](architecture/middleware-and-components.md) |
 | Process exit codes, stdout/stderr rules, JSONL, and `--help` contracts | [Exit Codes and Output](guide/exit-codes-and-output.md) |
 | Environment overrides, directory controls, and debug toggles | [Environment Variables](guide/environment-variables.md) |
@@ -126,6 +131,7 @@ repository.
 | Topic | Guide |
 | --- | --- |
 | Source layout, compile-time boundaries, domain loading, and runtime flow | [Architecture](architecture/architecture.md) |
+| Package kinds, catalog resolution, integrity, and trust | [Library Architecture](architecture/library.md) |
 | Pi framework boundary and Clio-owned policy | [Pi Boundary](architecture/pi-boundary.md) |
 | Documentation style and source-alignment workflow | [Documentation Guide](process/documentation-guide.md) |
 | Source-to-guide ownership map | [Documentation Coverage](process/documentation-coverage.md) |
@@ -172,6 +178,43 @@ local dogfooding instructions do not collide with public documentation. If the
 file exists in your checkout, read it before making changes; if it does not,
 the architecture guide and `CONTRIBUTING.md` are the public starting points.
 
+## Where Clio finds these docs when it is running in someone else's project
+
+Clio's documentation ships with Clio, not with your workspace. Everything below
+resolves from the installed package root (`resolvePackageRoot()`,
+`src/core/package-root.ts`), never from the directory you launched in.
+
+**What is indexed.** Every `.md` file under `<package-root>/docs/`, excluding
+`docs/html/`, plus root `README.md`, `CHANGELOG.md` and `CLIO-CODER.md` when each
+of those exists. The npm package ships `docs/**/*.md`, `README.md` and
+`CHANGELOG.md`; it does not ship `docs/html/` or a root `CLIO-CODER.md`, so in an
+npm install the blueprints are absent and the handbook is indexed only when you
+are running from a source checkout. The index is deterministic and needs no
+network or embedding service (`src/tools/context/docs-engine.ts`).
+
+**Searching and then reading.** `context(scope="docs", query="…")` returns
+section headings with citations such as `docs/architecture/safety-model.md`.
+Citations are **package-relative**, and this is the step that matters when the
+workspace is someone else's repository: reading `docs/architecture/safety-model.md`
+as a plain relative path reads *that project's* `docs/`, if it has one. Clio's
+own system prompt names the installed documentation directory as
+`{CLIO_DOCS_PATH}`, substituted as `join(packageRoot, "docs")`
+(`src/domains/prompts/compiler.ts`). Resolve the citation against the **package
+root**, which is that directory's parent. So when the prompt names `/pkg/docs`:
+
+- `docs/guide/foo.md` → `/pkg/docs/guide/foo.md`
+- `CHANGELOG.md` → `/pkg/CHANGELOG.md`, not `/pkg/docs/CHANGELOG.md`
+
+Do not duplicate the `docs/` segment, and do not resolve a citation against the
+workspace. Omitting `query` lists the corpus instead of searching it.
+
+**The blueprint viewer.** `clio-coder docs` serves `docs/html/` from the package
+root on `127.0.0.1:<port>`. It does not look at your current directory and does
+not check whether you are in a Git checkout: the only question is whether the
+installed package has those files. When it does not, the command prints the
+packaged Markdown path and a link to the blueprints on GitHub instead of starting
+a server.
+
 ## Interactive blueprints
 
 Every Markdown page has a dedicated visual blueprint under `docs/html/`, and

package/docs/architecture/architecture.md

@@ -26,14 +26,14 @@ src/
 
 Feature-domain directories include the following. Not every row is a loaded
 `DomainModule`: the orchestrator currently loads config, extensions, interop,
-resources, share, context, providers, toolchain, safety, prompts, agents,
-middleware, session, observability, scheduling, dispatch, and lifecycle, plus
-mux when the pane tier is active. The other rows are libraries or CLI-owned
-feature areas.
+plugins, resources, share, context, providers, toolchain, safety, prompts,
+agents, middleware, session, observability, scheduling, dispatch, and
+lifecycle, plus mux when the pane tier is active. The other rows are libraries
+or CLI-owned feature areas.
 
 | Domain | Primary source | Public surface |
 | --- | --- | --- |
-| agents | `src/domains/agents/**` | Built-in, user, and project agent recipes. |
+| agents | `src/domains/agents/**` | Built-in, plugin, user, and project agent recipes. |
 | components | `src/domains/components/**` | Component snapshots, diffs, and classification. |
 | config | `src/domains/config/**`, `src/core/config.ts` | `settings.yaml`, keybindings, hot reload. |
 | context | `src/domains/context/**` | Layered `CLIO-CODER.md` and subtree `CLIO-CODER.override.md` guidance, codewiki indexer, repository context. |
@@ -47,9 +47,10 @@ feature areas.
 | memory | `src/domains/memory/**` | Approved long-term memory, proactive task intervention. |
 | middleware | `src/domains/middleware/**` | Declarative and programmatic lifecycle hooks and budgets. |
 | observability | `src/domains/observability/**` | SQLite trace store, metrics projections, live telemetry. |
+| plugins | `src/domains/plugins/**` | Plugin discovery, catalog, and lifecycle. |
 | prompts | `src/domains/prompts/**` | Prompt fragments, system prompt envelope, template hashing. |
 | providers | `src/domains/providers/**` | Target-first runtime registry, model probing, credentials. |
-| resources | `src/domains/resources/**` | Skills loader, marketplace synchronization, prompts loader. |
+| resources | `src/domains/resources/**` | Package library, skills loader, prompts loader. |
 | safety | `src/domains/safety/**` | 10-step policy engine, path policy, zero-access rails, audit. |
 | scheduling | `src/domains/scheduling/**` | Budget ceilings, node cluster states, batch capacity checks. |
 | session | `src/domains/session/**` | Append-only JSONL transcripts, tree navigation, compaction. |
@@ -84,7 +85,7 @@ decision.
 
 Clio maintains an explicit distinction between persisted user settings (`settings.yaml`) and session-local routing state (`src/core/session-routing.ts`).
 
-1. **Decoupled Overlays**: Turn-level selections (such as active target, model override, thinking level, and scoped models cycled via Alt+J / Alt+K) apply dynamically through `applySessionRouting` without mutating `settings.yaml`.
+1. **Decoupled Overlays**: Turn-level selections (such as active target, model override, thinking level, and scoped models cycled via explicit model-cycle keys) apply dynamically through `applySessionRouting` without mutating `settings.yaml`.
 2. **Lifecycle Flow**:
    - `seedSessionRouting`: Seeds runtime fields from configuration at startup.
    - `applyRoutingPatch`: Applies surgical routing mutations (such as changing active model or target in the TUI).