@bodhi-ventures/aiocs 0.1.1 → 0.2.0

package/dist/cli.js

@@ -31,7 +31,7 @@ import {
   unlinkProjectSources,
   upsertSourceFromSpecFile,
   verifyCoverage
-} from "./chunk-AJ5NZDK4.js";
+} from "./chunk-M7YEYMJL.js";
 
 // src/cli.ts
 import { Command, CommanderError as CommanderError2 } from "commander";
@@ -113,6 +113,9 @@ function renderSearchResult(result) {
     `Snapshot: ${result.snapshotId}`,
     ...typeof result.score === "number" ? [`Score: ${result.score.toFixed(4)}`] : [],
     ...result.signals ? [`Signals: ${result.signals.join(", ")}`] : [],
+    ...result.pageKind ? [`Kind: ${result.pageKind}`] : [],
+    ...result.filePath ? [`Path: ${result.filePath}`] : [],
+    ...result.language ? [`Language: ${result.language}`] : [],
     `Page: ${result.pageTitle}`,
     `Section: ${result.sectionTitle}`,
     `URL: ${result.pageUrl}`,
@@ -339,6 +342,7 @@ source.command("list").action(async (_options, command) => {
       data: result,
       human: sources.length === 0 ? "No sources registered." : sources.map((item) => [
         item.id,
+        item.kind,
         item.label,
         item.isDue ? "due now" : `next due ${item.nextDueAt}`,
         `spec ${item.specPath ?? "(inline/unknown)"}`,
@@ -520,7 +524,13 @@ embeddings.command("run").description("Process queued embedding jobs immediately
 program.command("search").argument("<query>").option("--source <source-id>", "restrict search to a source", (value, current) => {
   current.push(value);
   return current;
-}, []).option("--snapshot <snapshot-id>", "search a specific snapshot").option("--all", "search across all latest snapshots").option("--project <path>", "resolve search scope as if running from this path").option("--mode <mode>", "search mode: auto, lexical, hybrid, semantic").option("--limit <count>", "maximum number of results to return").option("--offset <count>", "number of results to skip before returning matches").action(async (query, options, command) => {
+}, []).option("--snapshot <snapshot-id>", "search a specific snapshot").option("--all", "search across all latest snapshots").option("--project <path>", "resolve search scope as if running from this path").option("--path <glob>", "restrict search to file paths matching a glob", (value, current) => {
+  current.push(value);
+  return current;
+}, []).option("--language <name>", "restrict search to a language", (value, current) => {
+  current.push(value);
+  return current;
+}, []).option("--mode <mode>", "search mode: auto, lexical, hybrid, semantic").option("--limit <count>", "maximum number of results to return").option("--offset <count>", "number of results to skip before returning matches").action(async (query, options, command) => {
   await executeCommand(command, "search", async () => {
     const limit = parsePositiveIntegerOption(options.limit, "limit");
     const offset = parsePositiveIntegerOption(options.offset, "offset");
@@ -530,6 +540,8 @@ program.command("search").argument("<query>").option("--source <source-id>", "re
       ...options.snapshot ? { snapshot: options.snapshot } : {},
       ...typeof options.all !== "undefined" ? { all: options.all } : {},
       ...options.project ? { project: options.project } : {},
+      ...options.path && options.path.length > 0 ? { path: options.path } : {},
+      ...options.language && options.language.length > 0 ? { language: options.language } : {},
       ...mode ? { mode } : {},
       ...typeof limit === "number" ? { limit } : {},
       ...typeof offset === "number" ? { offset } : {}

package/dist/mcp-server.js

@@ -26,7 +26,7 @@ import {
   unlinkProjectSources,
   upsertSourceFromSpecFile,
   verifyCoverage
-} from "./chunk-AJ5NZDK4.js";
+} from "./chunk-M7YEYMJL.js";
 
 // src/mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -50,6 +50,7 @@ var doctorReportSchema = z.object({
 });
 var sourceSchema = z.object({
   id: z.string(),
+  kind: z.enum(["web", "git"]),
   label: z.string(),
   specPath: z.string().nullable(),
   nextDueAt: z.string(),
@@ -77,6 +78,9 @@ var searchResultSchema = z.object({
   pageTitle: z.string(),
   sectionTitle: z.string(),
   markdown: z.string(),
+  pageKind: z.enum(["document", "file"]),
+  filePath: z.string().nullable(),
+  language: z.string().nullable(),
   score: z.number().optional(),
   signals: z.array(z.enum(["lexical", "vector"])).optional()
 });
@@ -123,7 +127,8 @@ var canaryResultSchema = z.object({
     failCount: z.number().int().nonnegative()
   }),
   checks: z.array(z.object({
-    url: z.string(),
+    url: z.string().optional(),
+    path: z.string().optional(),
     status: z.enum(["pass", "fail"]),
     title: z.string().optional(),
     markdownLength: z.number().int().nonnegative().optional(),
@@ -142,16 +147,25 @@ var snapshotDiffSchema = z.object({
   }),
   addedPages: z.array(z.object({
     url: z.string(),
-    title: z.string()
+    title: z.string(),
+    pageKind: z.enum(["document", "file"]),
+    filePath: z.string().nullable(),
+    language: z.string().nullable()
   })),
   removedPages: z.array(z.object({
     url: z.string(),
-    title: z.string()
+    title: z.string(),
+    pageKind: z.enum(["document", "file"]),
+    filePath: z.string().nullable(),
+    language: z.string().nullable()
   })),
   changedPages: z.array(z.object({
     url: z.string(),
     beforeTitle: z.string(),
     afterTitle: z.string(),
+    pageKind: z.enum(["document", "file"]),
+    filePath: z.string().nullable(),
+    language: z.string().nullable(),
     lineSummary: z.object({
       addedLineCount: z.number().int().nonnegative(),
       removedLineCount: z.number().int().nonnegative()
@@ -256,6 +270,8 @@ var toolHandlers = {
     ...typeof args.snapshotId === "string" ? { snapshot: args.snapshotId } : {},
     ...typeof args.all === "boolean" ? { all: args.all } : {},
     ...typeof args.project === "string" ? { project: args.project } : {},
+    ...Array.isArray(args.pathPatterns) ? { path: args.pathPatterns } : {},
+    ...Array.isArray(args.languages) ? { language: args.languages } : {},
     ...typeof args.mode === "string" ? { mode: args.mode } : {},
     ...typeof args.limit === "number" ? { limit: args.limit } : {},
     ...typeof args.offset === "number" ? { offset: args.offset } : {}
@@ -507,6 +523,8 @@ registerAiocsTool(
       snapshotId: z.string().optional(),
       all: z.boolean().optional(),
       project: z.string().optional(),
+      pathPatterns: z.array(z.string()).optional(),
+      languages: z.array(z.string()).optional(),
       mode: z.enum(["auto", "lexical", "hybrid", "semantic"]).optional(),
       limit: z.number().int().positive().optional(),
       offset: z.number().int().nonnegative().optional()

package/docs/README.md

@@ -1,6 +1,6 @@
 # Docs
 
-Keep durable project documentation here.
+Keep stable, user-facing project documentation here.
 
 Good candidates:
 
@@ -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:
@@ -19,6 +26,13 @@ docs --json doctor
 docs --json init --no-fetch
 ```
 
+Register `aiocs-mcp` as a global Codex MCP server so the main agent can use it directly without shell fallback:
+
+```toml
+[mcp_servers.aiocs]
+command = "aiocs-mcp"
+```
+
 ## How Codex should use aiocs
 
 1. Prefer `aiocs` before live browsing when the requested docs may already exist locally.
@@ -27,41 +41,40 @@ docs --json init --no-fetch
 4. Check `source_list` before assuming a source is missing or stale.
 5. Default to `search mode=auto`.
 6. Use `mode=lexical` for exact identifiers, endpoint names, headings, and error strings.
-7. Prefer `refresh due <source-id>` over force `fetch <source-id>` when the source already exists.
-8. Use MCP `batch` when multiple list/search/show or search/diff/coverage steps are needed.
-9. Cite `sourceId`, `snapshotId`, and `pageUrl` when they materially improve traceability.
+7. Use `pathPatterns` and `languages` filters when the source is a repo/code source and the question is file- or language-specific.
+8. Use the `aiocs` skill for read/search flows and `aiocs-curation` only when the task requires source onboarding or refresh.
+9. Prefer `refresh due <source-id>` over force `fetch <source-id>` when the source already exists.
+10. Use MCP `batch` when multiple list/search/show or search/diff/coverage steps are needed.
+11. Cite `sourceId`, `snapshotId`, and `pageUrl` when they materially improve traceability.
 
 ## Automatic use in Codex
 
-Codex does not automatically invoke a custom subagent just because one exists. The primary automatic-use mechanism is the `aiocs` skill itself.
+Codex does not automatically invoke a custom subagent just because one exists. The primary automatic-use mechanism is the `aiocs` MCP server plus the `aiocs` skill itself.
 
-To make Codex discover `aiocs` automatically on this machine, expose the skill in the global Codex skill directory:
+To make Codex discover the read/search path automatically, expose the skills in the global Codex skill directory:
 
 ```bash
 AIOCS_REPO=/absolute/path/to/your/aiocs/checkout
 mkdir -p ~/.codex/skills
 ln -sfn "$AIOCS_REPO/skills/aiocs" ~/.codex/skills/aiocs
+ln -sfn "$AIOCS_REPO/skills/aiocs-curation" ~/.codex/skills/aiocs-curation
 ```
 
-Once that symlink exists, Codex can load the `aiocs` skill directly from the global skills catalog and prefer local docs without you explicitly calling a subagent.
+Once those symlinks exist, Codex can load `aiocs` for normal local-doc lookup and `aiocs-curation` only when the task needs source mutation or refresh.
 
 ## Subagent options
 
-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)
-- Install-ready global agent definition:
-  `ai-skills/agents/aiocs-docs-specialist.toml` from your local `ai-skills` checkout
+The repo ships a ready-to-copy specialist definition at
+[`agents/aiocs-docs-specialist.toml`](../agents/aiocs-docs-specialist.toml).
 
-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.
+It points 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:
+To expose that agent to Codex:
 
 ```bash
-AI_SKILLS_REPO=/absolute/path/to/your/ai-skills/checkout
+AIOCS_REPO=/absolute/path/to/your/aiocs/checkout
 mkdir -p ~/.codex/agents
-ln -sfn "$AI_SKILLS_REPO/agents/aiocs-docs-specialist.toml" ~/.codex/agents/aiocs-docs-specialist.toml
+ln -sfn "$AIOCS_REPO/agents/aiocs-docs-specialist.toml" ~/.codex/agents/aiocs-docs-specialist.toml
 ```
 
 ## Suggested Codex flows
@@ -78,6 +91,7 @@ Local docs lookup:
 ```bash
 docs --json source list
 docs --json search "maker flow" --source hyperliquid --mode auto
+docs --json search "WebSocketTransport" --source nktkas-hyperliquid --path "src/**" --language typescript --mode lexical
 docs --json show 42
 ```
 
@@ -114,14 +128,14 @@ If a Codex agent has access to the `aiocs-mcp` server, prefer these MCP tools ov
 - `doctor`
 - `init`
 - `source_list`
-- `source_upsert`
 - `search`
 - `show`
 - `canary`
-- `refresh_due`
 - `diff_snapshots`
 - `verify_coverage`
 - `embeddings_status`
 - `batch`
 
+Use mutating tools such as `source_upsert`, `refresh_due`, and `fetch` only through the `aiocs-curation` workflow.
+
 The CLI remains the fallback and should always be invoked with `--json` for agent use. For normal answering flows, avoid `fetch all`; use targeted due refresh or explicit user-approved force fetches.

package/docs/json-contract.md

@@ -106,8 +106,8 @@ This section documents the stable top-level `data` payload per command.
 {
   "summary": {
     "status": "healthy",
-    "checkCount": 10,
-    "passCount": 10,
+    "checkCount": 11,
+    "passCount": 11,
     "warnCount": 0,
     "failCount": 0
   },
@@ -125,6 +125,7 @@ This section documents the stable top-level `data` payload per command.
 Check ids are currently:
 
 - `catalog`
+- `git`
 - `playwright`
 - `daemon-config`
 - `source-spec-dirs`
@@ -158,9 +159,13 @@ Summary status values:
   "sources": [
     {
       "id": "hyperliquid",
+      "kind": "web",
+      "specPath": "/absolute/path/to/spec.yaml",
       "label": "Hyperliquid",
       "nextDueAt": "2026-03-26T12:00:00.000Z",
+      "isDue": false,
       "nextCanaryDueAt": "2026-03-26T06:00:00.000Z",
+      "isCanaryDue": false,
       "lastCheckedAt": "2026-03-26T10:00:00.000Z",
       "lastSuccessfulSnapshotAt": "2026-03-26T10:00:00.000Z",
       "lastSuccessfulSnapshotId": "snp_...",
@@ -256,7 +261,10 @@ Summary status values:
   "addedPages": [
     {
       "url": "https://example.dev/docs/new-page",
-      "title": "New page"
+      "title": "New page",
+      "pageKind": "document",
+      "filePath": null,
+      "language": null
     }
   ],
   "removedPages": [],
@@ -265,6 +273,9 @@ Summary status values:
       "url": "https://example.dev/docs/start",
       "beforeTitle": "Start",
       "afterTitle": "Start",
+      "pageKind": "document",
+      "filePath": null,
+      "language": null,
       "lineSummary": {
         "addedLineCount": 3,
         "removedLineCount": 2
@@ -293,6 +304,9 @@ Summary status values:
       "pageUrl": "https://example.dev/docs/maker-flow",
       "pageTitle": "Maker flow",
       "sectionTitle": "Order lifecycle",
+      "pageKind": "document",
+      "filePath": null,
+      "language": null,
       "markdown": "# Order lifecycle\n...",
       "score": 0.036,
       "signals": ["lexical", "vector"]
@@ -302,6 +316,7 @@ Summary status values:
 ```
 
 `limit` defaults to `20`. `offset` defaults to `0`.
+`pathPatterns` and `languages` narrow results for git/file sources and are also honored by MCP.
 
 `modeRequested` is the requested search mode (`auto`, `lexical`, `hybrid`, `semantic`).
 `modeUsed` is the actual executed mode after fallbacks. In `auto`, `aiocs` can degrade back to lexical if the vector layer is unavailable or incomplete for the requested scope.
@@ -445,6 +460,9 @@ Summary status values:
     "pageUrl": "https://example.dev/docs/maker-flow",
     "pageTitle": "Maker flow",
     "sectionTitle": "Order lifecycle",
+    "pageKind": "document",
+    "filePath": null,
+    "language": null,
     "markdown": "# Order lifecycle\n..."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bodhi-ventures/aiocs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Local-only documentation store, fetcher, and search CLI for AI agents.",
@@ -48,27 +48,27 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.28.0",
-    "@mozilla/readability": "^0.6.0",
+    "@modelcontextprotocol/sdk": "1.28.0",
+    "@mozilla/readability": "0.6.0",
     "@qdrant/js-client-rest": "1.17.0",
-    "better-sqlite3": "^12.4.1",
-    "commander": "^14.0.1",
-    "jsdom": "^27.0.1",
-    "playwright": "^1.57.0",
-    "turndown": "^7.2.1",
-    "turndown-plugin-gfm": "^1.0.2",
-    "yaml": "^2.8.1",
-    "zod": "^4.1.12"
+    "better-sqlite3": "12.4.1",
+    "commander": "14.0.1",
+    "jsdom": "27.0.1",
+    "playwright": "1.57.0",
+    "turndown": "7.2.1",
+    "turndown-plugin-gfm": "1.0.2",
+    "yaml": "2.8.1",
+    "zod": "4.1.12"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/jsdom": "^21.1.7",
-    "@types/node": "^24.7.2",
-    "@types/turndown": "^5.0.5",
-    "execa": "^9.6.0",
-    "tsup": "^8.5.0",
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "@types/better-sqlite3": "7.6.13",
+    "@types/jsdom": "21.1.7",
+    "@types/node": "24.7.2",
+    "@types/turndown": "5.0.5",
+    "execa": "9.6.0",
+    "tsup": "8.5.0",
+    "tsx": "4.20.6",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
   }
 }

package/skills/aiocs/SKILL.md

@@ -1,30 +1,31 @@
+---
+name: aiocs
+description: Use when authoritative local documentation lookup should come from the shared aiocs catalog under ~/.aiocs instead of live browsing.
+---
+
 # aiocs
 
-Use this skill when you need authoritative local documentation search, inspection, safe refresh, or bootstrap through the shared `aiocs` catalog under `~/.aiocs`.
+Use this skill when you need authoritative local documentation lookup through the shared `aiocs` catalog under `~/.aiocs`.
 
 ## When to use it
 
 - The user is asking about exchange or product docs that may already exist in the local `aiocs` catalog.
 - You need authoritative local docs for an exchange, SDK, or product without browsing the live site every time.
-- You want machine-readable search/show results for an AI agent.
-- You need to detect source drift or compare snapshot changes over time.
-- You want hybrid docs retrieval with lexical plus semantic/vector recall.
-- You need to bootstrap or validate `aiocs` on a new machine.
-- You want to keep the local docs catalog warm through the `aiocs` daemon or MCP server.
-- You need to back up or restore the shared catalog.
+- You need reusable reference search over a curated external git repository that already lives in `aiocs`.
+- You want machine-readable search/show/diff/coverage results for an AI agent.
+- You need hybrid docs retrieval with lexical plus semantic/vector recall.
+- You need to validate runtime health before relying on the local docs catalog.
 
 ## Trigger guidance for Codex
 
 - Prefer `aiocs` before live web browsing when the requested docs may already be in the local catalog.
 - Check `source_list` or scoped `search` before assuming a source is missing.
 - Use `aiocs` first for the bundled `hyperliquid` source and for any repo or machine that already relies on `~/.aiocs`.
-- If a source is missing, only add it when it is worth curating for future reuse.
-- Prefer `refresh due <source-id>` over force `fetch <source-id>` whenever freshness is the real goal.
-- Do not use `fetch all` as a normal answering path; reserve it for explicit user requests or maintenance flows.
+- This skill is the default read/search path. If the task requires source creation, force fetch, targeted refresh, or canary remediation, also load `aiocs-curation`.
 - Only fall back to live browsing when:
   - the source is not present in `aiocs`
   - the user explicitly wants the live site
-  - the local catalog is stale or broken and the answer cannot wait for refresh/canary remediation
+  - the local catalog is stale or broken and the answer cannot wait for curation/remediation
 - If you need multiple docs operations in MCP, use `batch` instead of many small round trips.
 
 ## Preferred interfaces
@@ -32,11 +33,14 @@ 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
 
 - Default to `search` with `mode=auto`.
 - Use `mode=lexical` for exact identifiers, section titles, endpoint names, and error strings.
+- Use `--path` / `pathPatterns` and `--language` / `languages` when searching repo/code sources.
 - Use `mode=hybrid` for conceptual questions when embeddings are healthy.
 - Use `mode=semantic` only when you explicitly want vector-only recall.
 - When citing results, include `sourceId`, `snapshotId`, and `pageUrl` when they materially help traceability.
@@ -55,12 +59,6 @@ Bootstrap managed sources from the repo bundle and `~/.aiocs/sources`:
 docs --json init --no-fetch
 ```
 
-User-managed source specs live under:
-
-```bash
-~/.aiocs/sources
-```
-
 ## Core commands
 
 Search the shared catalog:
@@ -70,6 +68,7 @@ docs --json search "maker flow" --source hyperliquid
 docs --json search "maker flow" --all
 docs --json search "maker flow" --source hyperliquid --limit 5 --offset 0
 docs --json search "maker flow" --source hyperliquid --mode hybrid
+docs --json search "WebSocketTransport" --source nktkas-hyperliquid --path "src/**" --language typescript --mode lexical
 ```
 
 Inspect a specific chunk:
@@ -78,22 +77,12 @@ Inspect a specific chunk:
 docs --json show 42
 ```
 
-Refresh the catalog:
+Inspect source availability and health:
 
 ```bash
 docs --json source list
-docs --json refresh due hyperliquid
 docs --json canary hyperliquid
 docs --json embeddings status
-docs --json embeddings backfill all
-docs --json embeddings run
-```
-
-Force fetch is still available for explicit maintenance:
-
-```bash
-docs --json fetch hyperliquid
-docs --json fetch all
 ```
 
 Inspect what changed between snapshots:
@@ -129,11 +118,8 @@ The `aiocs-mcp` server exposes the same core operations without shell parsing:
 - `version`
 - `doctor`
 - `init`
-- `source_upsert`
 - `source_list`
 - `canary`
-- `fetch`
-- `refresh_due`
 - `snapshot_list`
 - `diff_snapshots`
 - `project_link`
@@ -149,15 +135,16 @@ The `aiocs-mcp` server exposes the same core operations without shell parsing:
 - `verify_coverage`
 - `batch`
 
+Mutation-capable MCP tools such as `source_upsert`, `refresh_due`, and `fetch` belong to `aiocs-curation`.
+
 ## Recommended Codex workflow
 
-1. If runtime health or freshness is in doubt, run `doctor`.
-2. Run `source_list` to see whether the source already exists and whether it is due.
-3. If the source exists and is due, prefer `refresh due <source-id>` over force fetch.
-4. If the source is missing but likely to be reused, add a spec under `~/.aiocs/sources`, upsert it, then refresh only that source.
-5. Use `search` in `auto` mode first, then `show` for the selected chunk.
-6. Use `canary`, `diff_snapshots`, or `verify_coverage` when the question is about drift, changes, or completeness.
-7. Use `batch` when combining list/search/show or diff/coverage checks in one pass.
+1. If runtime health is in doubt, run `doctor`.
+2. Run `source_list` to see whether the source already exists.
+3. Use `search` in `auto` mode first, then `show` for the selected chunk.
+4. Use `canary`, `diff_snapshots`, or `verify_coverage` when the question is about drift, changes, or completeness.
+5. If the source is missing or stale and the next step is to mutate `aiocs`, load `aiocs-curation`.
+6. Use `batch` when combining list/search/show or diff/coverage checks in one pass.
 
 ## Operational notes
 

package/skills/aiocs-curation/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: aiocs-curation
+description: Use when aiocs sources or snapshots need mutation, such as source onboarding, targeted refresh, canary remediation, or catalog repair.
+---
+
+# aiocs-curation
+
+Use this skill when you need to add, refresh, repair, or otherwise mutate `aiocs` sources under `~/.aiocs`.
+
+## When to use it
+
+- The requested docs source is missing from the local `aiocs` catalog and is worth curating for reuse.
+- An existing source is stale and should be refreshed instead of bypassed.
+- A source spec needs to be created, updated, or upserted under `~/.aiocs/sources`.
+- A reusable external git repository should be added as a `kind: git` source under `~/.aiocs/sources`.
+- A canary is failing and the source needs remediation or targeted refetch.
+- The user explicitly wants `aiocs` maintenance, source onboarding, or catalog repair.
+
+## Trigger guidance for Codex
+
+- Load this skill when the next step requires a mutating `aiocs` operation.
+- Prefer targeted maintenance:
+  - `refresh due <source-id>` for existing sources
+  - `source_upsert` plus targeted refresh for newly curated sources
+- Avoid `fetch all` unless the user explicitly asks for broad maintenance.
+- If the source is missing, only curate it when it is likely to be reused across sessions or projects.
+- Keep the read/search path in `aiocs`; use this skill only for the curation step.
+
+## Preferred interfaces
+
+1. Prefer `aiocs-mcp` when an MCP client can use it directly.
+2. Otherwise use the CLI with the root `--json` flag.
+3. 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.
+4. Use `npx -y -p @bodhi-ventures/aiocs ...` only as a fallback when the global install is unavailable.
+
+## User-managed sources
+
+Machine-local source specs live under:
+
+```bash
+~/.aiocs/sources
+```
+
+Create or update source specs there instead of editing the bundled repo sources.
+
+## Core commands
+
+Validate the machine before curation:
+
+```bash
+docs --json doctor
+docs --json source list
+```
+
+Add or update a machine-local source:
+
+```bash
+mkdir -p ~/.aiocs/sources
+docs --json source upsert ~/.aiocs/sources/my-source.yaml
+```
+
+Refresh only what is needed:
+
+```bash
+docs --json refresh due my-source
+docs --json refresh due hyperliquid
+docs --json refresh due nktkas-hyperliquid
+docs --json fetch my-source
+docs --json canary my-source
+```
+
+Heavy maintenance remains explicit:
+
+```bash
+docs --json fetch all
+docs --json embeddings backfill all
+docs --json embeddings run
+```
+
+## MCP tools
+
+The `aiocs-mcp` server exposes the same curation operations without shell parsing:
+
+- `doctor`
+- `source_list`
+- `source_upsert`
+- `canary`
+- `fetch`
+- `refresh_due`
+- `embeddings_status`
+- `embeddings_backfill`
+- `embeddings_clear`
+- `embeddings_run`
+- `batch`
+
+## Recommended Codex workflow
+
+1. Run `doctor` or `source_list` if runtime health, presence, or freshness is unclear.
+2. If the source already exists and is due, prefer `refresh due <source-id>`.
+3. If the source is missing but worth curating, create a spec under `~/.aiocs/sources`, then `source_upsert` it.
+4. After upsert, use `refresh due <source-id>` as the safe first fetch path.
+5. Use `canary` when the site changed or extraction drift is suspected.
+6. Escalate to `fetch <source-id>` or `fetch all` only for explicit maintenance or when due-based refresh is not enough.
+
+## Operational notes
+
+- New or changed sources become due immediately after `source_upsert`.
+- `~/.aiocs/sources` and bundled repo sources behave the same once bootstrapped into the catalog.
+- Targeted refresh is the default. Broad refresh is a maintenance task, not a normal answering step.
+- Use `aiocs` for read/search flows and this skill only for catalog mutation.