@bodhi-ventures/aiocs 0.1.1 → 0.1.2

package/README.md

@@ -30,25 +30,24 @@ For testing or local overrides, set:
 ```bash
 npm install -g @bodhi-ventures/aiocs
 docs --version
+docs --help
+command -v aiocs-mcp
 ```
 
-For repository development:
+Zero-install fallback:
 
 ```bash
-pnpm install
-pnpm build
+npx -y -p @bodhi-ventures/aiocs docs --version
+npx -y -p @bodhi-ventures/aiocs aiocs-mcp
 ```
 
-Run the CLI during development with:
+For repository development only:
 
 ```bash
+pnpm install
+pnpm build
 pnpm dev -- --help
-```
-
-Or after build:
-
-```bash
-./dist/cli.js --help
+pnpm dev:mcp
 ```
 
 For AI agents, prefer the root-level `--json` flag for one-shot commands:
@@ -57,9 +56,9 @@ For AI agents, prefer the root-level `--json` flag for one-shot commands:
 docs --json version
 docs --json doctor
 docs --json init --no-fetch
-pnpm dev -- --json source list
-pnpm dev -- --json search "maker flow" --source hyperliquid
-pnpm dev -- --json show 42
+docs --json source list
+docs --json search "maker flow" --source hyperliquid
+docs --json show 42
 ```
 
 `--json` emits exactly one JSON document to stdout with this envelope:
@@ -109,7 +108,7 @@ GitHub Actions publishes `@bodhi-ventures/aiocs` publicly to npm and creates the
 
 ## Codex integration
 
-For Codex-first setup, automatic-use guidance, MCP recommendations, and subagent examples, see [docs/codex-integration.md](./docs/codex-integration.md).
+For Codex-first setup, automatic-use guidance, MCP recommendations, and agent definitions, see [docs/codex-integration.md](./docs/codex-integration.md).
 
 ## Managed sources
 
@@ -140,50 +139,50 @@ Register a source:
 ```bash
 mkdir -p ~/.aiocs/sources
 cp /path/to/source.yaml ~/.aiocs/sources/my-source.yaml
-pnpm dev -- source upsert ~/.aiocs/sources/my-source.yaml
-pnpm dev -- source upsert /path/to/source.yaml
-pnpm dev -- source list
+docs source upsert ~/.aiocs/sources/my-source.yaml
+docs source upsert /path/to/source.yaml
+docs source list
 ```
 
 Fetch and snapshot docs:
 
 ```bash
-pnpm dev -- refresh due hyperliquid
-pnpm dev -- snapshot list hyperliquid
-pnpm dev -- refresh due
+docs refresh due hyperliquid
+docs snapshot list hyperliquid
+docs refresh due
 ```
 
 Force fetch remains available for explicit maintenance:
 
 ```bash
-pnpm dev -- fetch hyperliquid
-pnpm dev -- fetch all
+docs fetch hyperliquid
+docs fetch all
 ```
 
 Link docs to a local project:
 
 ```bash
-pnpm dev -- project link /absolute/path/to/project hyperliquid lighter
-pnpm dev -- project unlink /absolute/path/to/project lighter
+docs project link /absolute/path/to/project hyperliquid lighter
+docs project unlink /absolute/path/to/project lighter
 ```
 
 Search and inspect results:
 
 ```bash
-pnpm dev -- search "maker flow" --source hyperliquid
-pnpm dev -- search "maker flow" --source hyperliquid --mode lexical
-pnpm dev -- search "maker flow" --source hyperliquid --mode hybrid
-pnpm dev -- search "maker flow" --source hyperliquid --mode semantic
-pnpm dev -- search "maker flow" --all
-pnpm dev -- search "maker flow" --source hyperliquid --limit 5 --offset 0
-pnpm dev -- show 42
-pnpm dev -- canary hyperliquid
-pnpm dev -- diff hyperliquid
-pnpm dev -- embeddings status
-pnpm dev -- embeddings backfill all
-pnpm dev -- embeddings run
-pnpm dev -- backup export /absolute/path/to/backup
-pnpm dev -- verify coverage hyperliquid /absolute/path/to/reference.md
+docs search "maker flow" --source hyperliquid
+docs search "maker flow" --source hyperliquid --mode lexical
+docs search "maker flow" --source hyperliquid --mode hybrid
+docs search "maker flow" --source hyperliquid --mode semantic
+docs search "maker flow" --all
+docs search "maker flow" --source hyperliquid --limit 5 --offset 0
+docs show 42
+docs canary hyperliquid
+docs diff hyperliquid
+docs embeddings status
+docs embeddings backfill all
+docs embeddings run
+docs backup export /absolute/path/to/backup
+docs verify coverage hyperliquid /absolute/path/to/reference.md
 ```
 
 When `docs search` runs inside a linked project, it automatically scopes to that project's linked sources unless `--source` or `--all` is provided.
@@ -279,22 +278,22 @@ All one-shot commands support `--json`:
 Representative examples:
 
 ```bash
-pnpm dev -- --json doctor
-pnpm dev -- --json init --no-fetch
-pnpm dev -- --json source list
-pnpm dev -- --json source upsert sources/hyperliquid.yaml
-pnpm dev -- --json refresh due hyperliquid
-pnpm dev -- --json canary hyperliquid
-pnpm dev -- --json refresh due
-pnpm dev -- --json diff hyperliquid
-pnpm dev -- --json embeddings status
-pnpm dev -- --json embeddings backfill all
-pnpm dev -- --json embeddings clear hyperliquid
-pnpm dev -- --json embeddings run
-pnpm dev -- --json project link /absolute/path/to/project hyperliquid lighter
-pnpm dev -- --json snapshot list hyperliquid
-pnpm dev -- --json backup export /absolute/path/to/backup
-pnpm dev -- --json verify coverage hyperliquid /absolute/path/to/reference.md
+docs --json doctor
+docs --json init --no-fetch
+docs --json source list
+docs --json source upsert sources/hyperliquid.yaml
+docs --json refresh due hyperliquid
+docs --json canary hyperliquid
+docs --json refresh due
+docs --json diff hyperliquid
+docs --json embeddings status
+docs --json embeddings backfill all
+docs --json embeddings clear hyperliquid
+docs --json embeddings run
+docs --json project link /absolute/path/to/project hyperliquid lighter
+docs --json snapshot list hyperliquid
+docs --json backup export /absolute/path/to/backup
+docs --json verify coverage hyperliquid /absolute/path/to/reference.md
 ```
 
 For multi-result commands like `fetch`, `refresh due`, and `search`, `data` contains structured collections rather than line-by-line output:
@@ -321,8 +320,7 @@ For multi-result commands like `fetch`, `refresh due`, and `search`, `data` cont
 `aiocs` ships a first-class long-running refresh process:
 
 ```bash
-pnpm dev -- daemon
-./dist/cli.js daemon
+docs daemon
 ```
 
 The daemon bootstraps source specs from the configured directories, refreshes due sources, sleeps for the configured interval, and repeats.
@@ -353,7 +351,7 @@ For local agents, the daemon keeps the shared catalog under `~/.aiocs` warm whil
 `docs daemon --json` is intentionally different from one-shot commands. Because it is long-running, it emits one JSON event per line:
 
 ```bash
-./dist/cli.js --json daemon
+docs --json daemon
 ```
 
 Example event stream:
@@ -369,7 +367,13 @@ Example event stream:
 `aiocs` also ships an MCP server binary for tool-native agent integrations:
 
 ```bash
+command -v aiocs-mcp
 aiocs-mcp
+```
+
+For repository development only:
+
+```bash
 pnpm dev:mcp
 ```
 

package/dist/{chunk-AJ5NZDK4.js → chunk-CZ6C4YUX.js}

@@ -43,9 +43,108 @@ function toAiocsError(error) {
   return new AiocsError(AIOCS_ERROR_CODES.internalError, String(error));
 }
 
-// src/catalog/catalog.ts
+// src/runtime/paths.ts
+import { homedir } from "os";
+import { join as join2, relative, resolve, sep } from "path";
 import { mkdirSync } from "fs";
-import { join, resolve as resolve2 } from "path";
+
+// src/runtime/bundled-sources.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+function findPackageRoot(startDir) {
+  let currentDir = startDir;
+  while (true) {
+    if (existsSync(join(currentDir, "package.json")) && existsSync(join(currentDir, "sources"))) {
+      return currentDir;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      throw new Error(`Could not locate aiocs package root from ${startDir}`);
+    }
+    currentDir = parentDir;
+  }
+}
+function getBundledSourcesDir() {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  const packageRoot = findPackageRoot(dirname(currentFilePath));
+  return join(packageRoot, "sources");
+}
+
+// src/runtime/paths.ts
+var PORTABLE_USER_SOURCES_PREFIX = "~/.aiocs/sources";
+var PORTABLE_BUNDLED_SOURCES_PREFIX = "aiocs://bundled";
+var CONTAINER_USER_SOURCES_DIR = "/root/.aiocs/sources";
+var CONTAINER_BUNDLED_SOURCES_DIR = "/app/sources";
+function expandTilde(path) {
+  if (path === "~") {
+    return homedir();
+  }
+  if (path.startsWith("~/")) {
+    return join2(homedir(), path.slice(2));
+  }
+  return path;
+}
+function getAiocsDataDir(env = process.env) {
+  const override = env.AIOCS_DATA_DIR;
+  if (override) {
+    mkdirSync(expandTilde(override), { recursive: true });
+    return expandTilde(override);
+  }
+  const target = join2(homedir(), ".aiocs", "data");
+  mkdirSync(target, { recursive: true });
+  return target;
+}
+function getAiocsConfigDir(env = process.env) {
+  const override = env.AIOCS_CONFIG_DIR;
+  if (override) {
+    mkdirSync(expandTilde(override), { recursive: true });
+    return expandTilde(override);
+  }
+  const target = join2(homedir(), ".aiocs", "config");
+  mkdirSync(target, { recursive: true });
+  return target;
+}
+function getAiocsSourcesDir(env = process.env) {
+  const override = env.AIOCS_SOURCES_DIR;
+  if (override) {
+    mkdirSync(expandTilde(override), { recursive: true });
+    return expandTilde(override);
+  }
+  const target = join2(homedir(), ".aiocs", "sources");
+  mkdirSync(target, { recursive: true });
+  return target;
+}
+function isWithinRoot(candidatePath, rootPath) {
+  return candidatePath === rootPath || candidatePath.startsWith(`${rootPath}${sep}`);
+}
+function toPortablePath(prefix, rootPath, candidatePath) {
+  const relativePath = relative(rootPath, candidatePath).split(sep).join("/");
+  return relativePath ? `${prefix}/${relativePath}` : prefix;
+}
+function canonicalizeManagedSpecPath(specPath, env = process.env) {
+  if (specPath === PORTABLE_USER_SOURCES_PREFIX || specPath.startsWith(`${PORTABLE_USER_SOURCES_PREFIX}/`) || specPath === PORTABLE_BUNDLED_SOURCES_PREFIX || specPath.startsWith(`${PORTABLE_BUNDLED_SOURCES_PREFIX}/`)) {
+    return specPath;
+  }
+  const resolvedPath = resolve(specPath);
+  const userRoots = [resolve(getAiocsSourcesDir(env)), CONTAINER_USER_SOURCES_DIR];
+  for (const rootPath of userRoots) {
+    if (isWithinRoot(resolvedPath, rootPath)) {
+      return toPortablePath(PORTABLE_USER_SOURCES_PREFIX, rootPath, resolvedPath);
+    }
+  }
+  const bundledRoots = [resolve(getBundledSourcesDir()), CONTAINER_BUNDLED_SOURCES_DIR];
+  for (const rootPath of bundledRoots) {
+    if (isWithinRoot(resolvedPath, rootPath)) {
+      return toPortablePath(PORTABLE_BUNDLED_SOURCES_PREFIX, rootPath, resolvedPath);
+    }
+  }
+  return resolvedPath;
+}
+
+// src/catalog/catalog.ts
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join3, resolve as resolve3 } from "path";
 import { randomUUID } from "crypto";
 import Database from "better-sqlite3";
 
@@ -152,12 +251,12 @@ function buildSnapshotFingerprint(input) {
 
 // src/catalog/project-scope.ts
 import { realpathSync } from "fs";
-import { resolve } from "path";
+import { resolve as resolve2 } from "path";
 function isWithin(candidate, root) {
   return candidate === root || candidate.startsWith(`${root}/`);
 }
 function canonicalizeProjectPath(path) {
-  const resolved = resolve(path);
+  const resolved = resolve2(path);
   try {
     return realpathSync.native(resolved);
   } catch {
@@ -511,9 +610,9 @@ function assertPaginationValue(value, field, fallback) {
   return value;
 }
 function openCatalog(options) {
-  const dataDir = resolve2(options.dataDir);
-  mkdirSync(dataDir, { recursive: true });
-  const db = new Database(join(dataDir, "catalog.sqlite"));
+  const dataDir = resolve3(options.dataDir);
+  mkdirSync2(dataDir, { recursive: true });
+  const db = new Database(join3(dataDir, "catalog.sqlite"));
   initSchema(db);
   const listProjectLinks = () => {
     const rows = db.prepare("SELECT project_path, source_id FROM project_links ORDER BY project_path, source_id").all();
@@ -788,7 +887,7 @@ function openCatalog(options) {
       const timestamp = nowIso();
       const configHash = sha256(stableStringify(spec));
       const existing = db.prepare("SELECT id, created_at, next_due_at, next_canary_due_at, config_hash FROM sources WHERE id = ?").get(spec.id);
-      const resolvedSpecPath = options2?.specPath ? resolve2(options2.specPath) : null;
+      const resolvedSpecPath = options2?.specPath ? canonicalizeManagedSpecPath(options2.specPath) : null;
       const nextDueAt = !existing ? timestamp : existing.config_hash === configHash ? existing.next_due_at : timestamp;
       const canaryConfig = resolveSourceCanary(spec);
       const nextCanaryDueAt = !existing ? timestamp : existing.config_hash === configHash ? existing.next_canary_due_at ?? addHoursIso(canaryConfig.everyHours) : timestamp;
@@ -851,7 +950,7 @@ function openCatalog(options) {
       return rows.map((row) => ({
         id: row.id,
         label: row.label,
-        specPath: row.spec_path,
+        specPath: row.spec_path ? canonicalizeManagedSpecPath(row.spec_path) : null,
         nextDueAt: row.next_due_at,
         isDue: Date.parse(row.next_due_at) <= Date.now(),
         nextCanaryDueAt: row.next_canary_due_at,
@@ -1086,8 +1185,9 @@ function openCatalog(options) {
         return [];
       }
       const activeSourceKeys = new Set(
-        input.activeSources.map((source) => `${source.sourceId}::${resolve2(source.specPath)}`)
+        input.activeSources.map((source) => `${source.sourceId}::${canonicalizeManagedSpecPath(source.specPath)}`)
       );
+      const normalizedManagedRoots = input.managedRoots.map((managedRoot) => canonicalizeManagedSpecPath(managedRoot));
       const rows = db.prepare(`
         SELECT id, spec_path
         FROM sources
@@ -1098,8 +1198,8 @@ function openCatalog(options) {
         if (!row.spec_path) {
           return false;
         }
-        const normalizedSpecPath = resolve2(row.spec_path);
-        return input.managedRoots.some(
+        const normalizedSpecPath = canonicalizeManagedSpecPath(row.spec_path);
+        return normalizedManagedRoots.some(
           (managedRoot) => normalizedSpecPath === managedRoot || normalizedSpecPath.startsWith(`${managedRoot}/`)
         ) && !activeSourceKeys.has(`${row.id}::${normalizedSpecPath}`);
       }).map((row) => row.id);
@@ -1718,57 +1818,14 @@ function openCatalog(options) {
   };
 }
 
-// src/runtime/paths.ts
-import { homedir } from "os";
-import { join as join2 } from "path";
-import { mkdirSync as mkdirSync2 } from "fs";
-function expandTilde(path) {
-  if (path === "~") {
-    return homedir();
-  }
-  if (path.startsWith("~/")) {
-    return join2(homedir(), path.slice(2));
-  }
-  return path;
-}
-function getAiocsDataDir(env = process.env) {
-  const override = env.AIOCS_DATA_DIR;
-  if (override) {
-    mkdirSync2(expandTilde(override), { recursive: true });
-    return expandTilde(override);
-  }
-  const target = join2(homedir(), ".aiocs", "data");
-  mkdirSync2(target, { recursive: true });
-  return target;
-}
-function getAiocsConfigDir(env = process.env) {
-  const override = env.AIOCS_CONFIG_DIR;
-  if (override) {
-    mkdirSync2(expandTilde(override), { recursive: true });
-    return expandTilde(override);
-  }
-  const target = join2(homedir(), ".aiocs", "config");
-  mkdirSync2(target, { recursive: true });
-  return target;
-}
-function getAiocsSourcesDir(env = process.env) {
-  const override = env.AIOCS_SOURCES_DIR;
-  if (override) {
-    mkdirSync2(expandTilde(override), { recursive: true });
-    return expandTilde(override);
-  }
-  const target = join2(homedir(), ".aiocs", "sources");
-  mkdirSync2(target, { recursive: true });
-  return target;
-}
-
 // src/daemon.ts
-import { resolve as resolve4 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { resolve as resolve5 } from "path";
 import { setTimeout as sleep2 } from "timers/promises";
 
 // src/fetch/fetch-source.ts
 import { mkdirSync as mkdirSync3, writeFileSync } from "fs";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 import { setTimeout as sleep } from "timers/promises";
 import { chromium } from "playwright";
 
@@ -2051,11 +2108,11 @@ async function extractRawMarkdownPage(url, response) {
   };
 }
 function persistSnapshotPages(input, snapshotId, pages) {
-  const snapshotDir = join3(input.dataDir, "sources", input.sourceId, "snapshots", snapshotId, "pages");
+  const snapshotDir = join4(input.dataDir, "sources", input.sourceId, "snapshots", snapshotId, "pages");
   mkdirSync3(snapshotDir, { recursive: true });
   pages.forEach((page, index) => {
     const filename = `${String(index + 1).padStart(3, "0")}-${slugify(page.title)}.md`;
-    writeFileSync(join3(snapshotDir, filename), page.markdown, "utf8");
+    writeFileSync(join4(snapshotDir, filename), page.markdown, "utf8");
   });
 }
 function resolveEnvValue(name, env) {
@@ -2404,6 +2461,30 @@ function getEmbeddingModelKey(config) {
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
 }
+function normalizeEmbeddingWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function truncateEmbeddingText(value, maxChars) {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const slice = value.slice(0, maxChars);
+  const lastWhitespace = slice.lastIndexOf(" ");
+  if (lastWhitespace >= Math.floor(maxChars * 0.8)) {
+    return slice.slice(0, lastWhitespace).trim();
+  }
+  return slice.trim();
+}
+function prepareTextForEmbedding(markdown, maxChars) {
+  const withoutComments = markdown.replace(/<!--[\s\S]*?-->/g, " ");
+  const withoutImages = withoutComments.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, "$1");
+  const withoutLinks = withoutImages.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1");
+  const withoutHtml = withoutLinks.replace(/<[^>]+>/g, " ");
+  const withoutCodeFenceMarkers = withoutHtml.replace(/```[^\n]*\n/g, "\n").replace(/```/g, "\n");
+  const withoutInlineCodeTicks = withoutCodeFenceMarkers.replace(/`([^`]+)`/g, "$1");
+  const normalized = normalizeEmbeddingWhitespace(withoutInlineCodeTicks);
+  return truncateEmbeddingText(normalized, maxChars);
+}
 async function parseJsonResponse(response) {
   const text = await response.text();
   if (!text) {
@@ -2422,6 +2503,7 @@ async function embedTexts(config, texts) {
   if (texts.length === 0) {
     return [];
   }
+  const preparedTexts = texts.map((text) => prepareTextForEmbedding(text, config.ollamaMaxInputChars));
   const response = await fetch(`${normalizeBaseUrl(config.ollamaBaseUrl)}/api/embed`, {
     method: "POST",
     headers: {
@@ -2430,7 +2512,7 @@ async function embedTexts(config, texts) {
     signal: AbortSignal.timeout(config.ollamaTimeoutMs),
     body: JSON.stringify({
       model: config.ollamaEmbeddingModel,
-      input: texts
+      input: preparedTexts
     })
   }).catch((error) => {
     throw new AiocsError(
@@ -2823,29 +2905,6 @@ async function processEmbeddingJobs(input) {
   };
 }
 
-// src/runtime/bundled-sources.ts
-import { existsSync } from "fs";
-import { dirname, join as join4 } from "path";
-import { fileURLToPath } from "url";
-function findPackageRoot(startDir) {
-  let currentDir = startDir;
-  while (true) {
-    if (existsSync(join4(currentDir, "package.json")) && existsSync(join4(currentDir, "sources"))) {
-      return currentDir;
-    }
-    const parentDir = dirname(currentDir);
-    if (parentDir === currentDir) {
-      throw new Error(`Could not locate aiocs package root from ${startDir}`);
-    }
-    currentDir = parentDir;
-  }
-}
-function getBundledSourcesDir() {
-  const currentFilePath = fileURLToPath(import.meta.url);
-  const packageRoot = findPackageRoot(dirname(currentFilePath));
-  return join4(packageRoot, "sources");
-}
-
 // src/runtime/hybrid-config.ts
 function parsePositiveInteger(value, field, fallback) {
   if (typeof value === "undefined" || value.trim() === "") {
@@ -2888,7 +2947,8 @@ function getHybridRuntimeConfig(env = process.env) {
     embeddingProvider: "ollama",
     ollamaBaseUrl: env.AIOCS_OLLAMA_BASE_URL ?? "http://127.0.0.1:11434",
     ollamaEmbeddingModel: env.AIOCS_OLLAMA_EMBEDDING_MODEL ?? "nomic-embed-text",
-    ollamaTimeoutMs: parsePositiveInteger(env.AIOCS_OLLAMA_TIMEOUT_MS, "AIOCS_OLLAMA_TIMEOUT_MS", 1e3),
+    ollamaTimeoutMs: parsePositiveInteger(env.AIOCS_OLLAMA_TIMEOUT_MS, "AIOCS_OLLAMA_TIMEOUT_MS", 1e4),
+    ollamaMaxInputChars: parsePositiveInteger(env.AIOCS_OLLAMA_MAX_INPUT_CHARS, "AIOCS_OLLAMA_MAX_INPUT_CHARS", 4e3),
     embeddingBatchSize: parsePositiveInteger(env.AIOCS_EMBEDDING_BATCH_SIZE, "AIOCS_EMBEDDING_BATCH_SIZE", 32),
     embeddingJobsPerCycle: parsePositiveInteger(env.AIOCS_EMBEDDING_JOB_LIMIT_PER_CYCLE, "AIOCS_EMBEDDING_JOB_LIMIT_PER_CYCLE", 2),
     lexicalCandidateWindow: parsePositiveInteger(env.AIOCS_LEXICAL_CANDIDATE_WINDOW, "AIOCS_LEXICAL_CANDIDATE_WINDOW", 40),
@@ -2900,13 +2960,13 @@ function getHybridRuntimeConfig(env = process.env) {
 // src/spec/source-spec-files.ts
 import { access, readdir } from "fs/promises";
 import { constants as fsConstants } from "fs";
-import { extname as extname2, join as join5, resolve as resolve3 } from "path";
+import { extname as extname2, join as join5, resolve as resolve4 } from "path";
 var SOURCE_SPEC_EXTENSIONS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
 function uniqueResolvedPaths(paths) {
   const seen = /* @__PURE__ */ new Set();
   const unique = [];
   for (const rawPath of paths) {
-    const normalized = resolve3(rawPath);
+    const normalized = resolve4(rawPath);
     if (seen.has(normalized)) {
       continue;
     }
@@ -2973,10 +3033,11 @@ function parseBoolean(raw, variableName) {
 function parseDaemonConfig(env, options = {}) {
   const intervalMinutes = env.AIOCS_DAEMON_INTERVAL_MINUTES ? parsePositiveInteger2(env.AIOCS_DAEMON_INTERVAL_MINUTES, "AIOCS_DAEMON_INTERVAL_MINUTES") : DEFAULT_INTERVAL_MINUTES;
   const fetchOnStart = env.AIOCS_DAEMON_FETCH_ON_START ? parseBoolean(env.AIOCS_DAEMON_FETCH_ON_START, "AIOCS_DAEMON_FETCH_ON_START") : true;
+  const defaultContainerSourceDir = options.containerSourceDir ?? (existsSync2(DEFAULT_CONTAINER_SOURCE_DIR) ? DEFAULT_CONTAINER_SOURCE_DIR : void 0);
   const defaultSourceDirs = uniqueResolvedPaths([
     options.bundledSourceDir ?? getBundledSourcesDir(),
     options.userSourceDir ?? getAiocsSourcesDir(env),
-    options.containerSourceDir ?? DEFAULT_CONTAINER_SOURCE_DIR
+    ...defaultContainerSourceDir ? [defaultContainerSourceDir] : []
   ]);
   const sourceSpecDirs = env.AIOCS_SOURCE_SPEC_DIRS ? uniqueResolvedPaths(
     env.AIOCS_SOURCE_SPEC_DIRS.split(",").map((entry) => entry.trim()).filter(Boolean)
@@ -3023,7 +3084,7 @@ async function bootstrapSourceSpecs(input) {
     throw new Error(`No source spec files found in configured directories: ${normalizedSourceSpecDirs.join(", ")}`);
   }
   const removedSourceIds = input.catalog.removeManagedSources({
-    managedRoots: existingDirs.map((sourceSpecDir) => resolve4(sourceSpecDir)),
+    managedRoots: existingDirs.map((sourceSpecDir) => resolve5(sourceSpecDir)),
     activeSources: sources.map((source) => ({
       sourceId: source.sourceId,
       specPath: source.specPath
@@ -3208,7 +3269,7 @@ async function startDaemon(input) {
 // package.json
 var package_default = {
   name: "@bodhi-ventures/aiocs",
-  version: "0.1.1",
+  version: "0.1.2",
   license: "MIT",
   type: "module",
   description: "Local-only documentation store, fetcher, and search CLI for AI agents.",
@@ -3287,11 +3348,11 @@ var packageVersion = package_default.version;
 var packageDescription = package_default.description;
 
 // src/services.ts
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 
 // src/backup.ts
 import { cp, mkdir, readdir as readdir2, readFile as readFile2, rename, rm, stat, writeFile } from "fs/promises";
-import { basename, dirname as dirname2, join as join6, resolve as resolve5 } from "path";
+import { basename, dirname as dirname2, join as join6, resolve as resolve6 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 import Database2 from "better-sqlite3";
 var CATALOG_DB_FILENAME = "catalog.sqlite";
@@ -3427,9 +3488,9 @@ async function prepareReplacementTarget(backupDir, targetDir) {
   return stagingDir;
 }
 async function exportBackup(input) {
-  const dataDir = resolve5(input.dataDir);
-  const outputDir = resolve5(input.outputDir);
-  const configDir = input.configDir ? resolve5(input.configDir) : void 0;
+  const dataDir = resolve6(input.dataDir);
+  const outputDir = resolve6(input.outputDir);
+  const configDir = input.configDir ? resolve6(input.configDir) : void 0;
   await assertSourceDirExists(dataDir);
   if (!await isDirectoryEmpty(outputDir)) {
     if (!input.replaceExisting) {
@@ -3465,9 +3526,9 @@ async function exportBackup(input) {
   };
 }
 async function importBackup(input) {
-  const inputDir = resolve5(input.inputDir);
-  const dataDir = resolve5(input.dataDir);
-  const configDir = input.configDir ? resolve5(input.configDir) : void 0;
+  const inputDir = resolve6(input.inputDir);
+  const dataDir = resolve6(input.dataDir);
+  const configDir = input.configDir ? resolve6(input.configDir) : void 0;
   const { manifest, backupDataDir, backupConfigDir } = await loadValidatedBackupPayload(inputDir);
   if (!await isDirectoryEmpty(dataDir)) {
     if (!input.replaceExisting) {
@@ -3511,7 +3572,7 @@ async function importBackup(input) {
 
 // src/coverage.ts
 import { readFile as readFile3 } from "fs/promises";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 function normalizeText(value) {
   return value.replace(/[`*_~]+/g, "").replace(/\s+/g, " ").trim().toLowerCase();
 }
@@ -3560,7 +3621,7 @@ async function verifyCoverageAgainstReferences(corpus, referenceFiles) {
     body: 0
   };
   for (const referenceFile of referenceFiles) {
-    const resolvedReferenceFile = resolve6(referenceFile);
+    const resolvedReferenceFile = resolve7(referenceFile);
     let raw;
     try {
       raw = await readFile3(resolvedReferenceFile, "utf8");
@@ -4226,7 +4287,7 @@ function withCatalog(run) {
   return Promise.resolve(run(ctx)).finally(() => ctx.catalog.close());
 }
 async function upsertSourceFromSpecFile(specFile) {
-  const specPath = resolve7(specFile);
+  const specPath = resolve8(specFile);
   const spec = await loadSourceSpec(specPath);
   const result = await withCatalog(({ catalog }) => catalog.upsertSource(spec, { specPath }));
   return {
@@ -4322,7 +4383,7 @@ async function diffSnapshotsForSource(input) {
   return withCatalog(({ catalog }) => catalog.diffSnapshots(input));
 }
 async function linkProjectSources(projectPath, sourceIds) {
-  const resolvedProjectPath = resolve7(projectPath);
+  const resolvedProjectPath = resolve8(projectPath);
   await withCatalog(({ catalog }) => {
     catalog.linkProject(resolvedProjectPath, sourceIds);
   });
@@ -4332,7 +4393,7 @@ async function linkProjectSources(projectPath, sourceIds) {
   };
 }
 async function unlinkProjectSources(projectPath, sourceIds) {
-  const resolvedProjectPath = resolve7(projectPath);
+  const resolvedProjectPath = resolve8(projectPath);
   await withCatalog(({ catalog }) => {
     catalog.unlinkProject(resolvedProjectPath, sourceIds);
   });
@@ -4342,7 +4403,7 @@ async function unlinkProjectSources(projectPath, sourceIds) {
   };
 }
 async function searchCatalog(query, options) {
-  const cwd = options.project ? resolve7(options.project) : process.cwd();
+  const cwd = options.project ? resolve8(options.project) : process.cwd();
   const explicitSources = options.source.length > 0;
   const results = await withCatalog(({ catalog }) => {
     const hybridConfig = getHybridRuntimeConfig();
@@ -4508,9 +4569,9 @@ export {
   AIOCS_ERROR_CODES,
   AiocsError,
   toAiocsError,
-  openCatalog,
   getAiocsDataDir,
   getAiocsConfigDir,
+  openCatalog,
   parseDaemonConfig,
   startDaemon,
   packageName,

package/dist/cli.js

@@ -31,7 +31,7 @@ import {
   unlinkProjectSources,
   upsertSourceFromSpecFile,
   verifyCoverage
-} from "./chunk-AJ5NZDK4.js";
+} from "./chunk-CZ6C4YUX.js";
 
 // src/cli.ts
 import { Command, CommanderError as CommanderError2 } from "commander";

package/dist/mcp-server.js

@@ -26,7 +26,7 @@ import {
   unlinkProjectSources,
   upsertSourceFromSpecFile,
   verifyCoverage
-} from "./chunk-AJ5NZDK4.js";
+} from "./chunk-CZ6C4YUX.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/docs/README.md

@@ -9,4 +9,4 @@ Good candidates:
 - operational runbooks
 - decisions worth preserving across sessions
 - Codex integration guidance in `codex-integration.md`
-- reusable agent examples under `examples/codex-agents/`
+- reusable repo-managed agent definitions under `../agents/`

package/docs/codex-integration.md

@@ -9,7 +9,14 @@ Install the CLI and MCP binary globally:
 ```bash
 npm install -g @bodhi-ventures/aiocs
 docs --version
-aiocs-mcp
+command -v aiocs-mcp
+```
+
+If global install is unavailable, use `npx` only as a fallback:
+
+```bash
+npx -y -p @bodhi-ventures/aiocs docs --version
+npx -y -p @bodhi-ventures/aiocs aiocs-mcp
 ```
 
 The `aiocs-mcp` process is an MCP stdio server, so running it directly will wait for MCP clients instead of printing interactive help. The useful validation commands are:
@@ -49,12 +56,12 @@ Once that symlink exists, Codex can load the `aiocs` skill directly from the glo
 
 There are two supported subagent patterns:
 
-- Repo example for development and debugging:
-  [`docs/examples/codex-agents/aiocs-docs-specialist.example.toml`](examples/codex-agents/aiocs-docs-specialist.example.toml)
+- Repo-managed agent definition:
+  [`agents/aiocs-docs-specialist.toml`](../agents/aiocs-docs-specialist.toml)
 - Install-ready global agent definition:
   `ai-skills/agents/aiocs-docs-specialist.toml` from your local `ai-skills` checkout
 
-The repo example is intentionally development-oriented and uses a checkout-local MCP command. The global agent points at the globally installed `aiocs-mcp` binary.
+The repo-managed agent definition and the install-ready global agent both point at the globally installed `aiocs-mcp` binary so Codex uses the published package by default.
 
 To expose the install-ready global agent to Codex on this machine:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bodhi-ventures/aiocs",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "type": "module",
   "description": "Local-only documentation store, fetcher, and search CLI for AI agents.",

package/skills/aiocs/SKILL.md

@@ -32,6 +32,8 @@ Use this skill when you need authoritative local documentation search, inspectio
 1. Prefer `aiocs-mcp` when an MCP client can use it directly.
 2. Otherwise use the CLI with the root `--json` flag.
 3. Avoid parsing human-formatted CLI output unless there is no alternative.
+4. Assume `docs` and `aiocs-mcp` come from the globally installed `@bodhi-ventures/aiocs` package unless the user explicitly asks for a checkout-local development build.
+5. Use `npx -y -p @bodhi-ventures/aiocs ...` only as a fallback when the global install is unavailable.
 
 ## Search defaults for agents
 

package/docs/examples/codex-agents/aiocs-docs-specialist.example.toml

@@ -1,21 +0,0 @@
-name = "aiocs_docs_specialist"
-description = "Development example specialist for local aiocs documentation search, drift checks, diffs, and health verification through a checkout-local MCP server."
-model = "gpt-5.4-mini"
-model_reasoning_effort = "high"
-sandbox_mode = "read-only"
-nickname_candidates = ["Index", "Ledger", "Compass"]
-developer_instructions = """
-Use aiocs as the first stop for local documentation work.
-Prefer aiocs before live browsing when the requested docs may already exist in the local catalog.
-Check source presence and freshness with source_list before assuming docs are missing or stale.
-Default to search mode auto, switch to lexical for exact identifiers, prefer refresh_due for targeted freshness checks, and use batch when multiple aiocs tool calls are needed in one task.
-If the parent agent explicitly asks for aiocs write operations and a source is missing but likely to be reused, add a spec under ~/.aiocs/sources, upsert it, then refresh only that source.
-Avoid fetch all unless the parent agent explicitly asks for broad maintenance.
-When returning results, include sourceId, snapshotId, and pageUrl when they materially improve traceability.
-Do not edit aiocs source specs, catalog contents, or daemon configuration unless the parent agent explicitly asks for it.
-If aiocs health is in doubt, run doctor before assuming the catalog is broken.
-"""
-
-[mcp_servers.aiocs]
-command = "pnpm"
-args = ["--dir", "/absolute/path/to/aiocs", "dev:mcp"]