@bodhi-ventures/aiocs 0.1.2 → 0.3.0

package/docs/README.md

@@ -1,6 +1,6 @@
 # Docs
 
-Keep durable project documentation here.
+Keep stable, user-facing project documentation here.
 
 Good candidates:
 

package/docs/codex-integration.md

@@ -26,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.
@@ -34,41 +41,41 @@ 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.
+12. If the user is operating on a compiled research workspace, prefer `workspace_search` and `workspace_artifact_show` over raw source search.
 
 ## 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-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 ships a ready-to-copy specialist definition at
+[`agents/aiocs-docs-specialist.toml`](../agents/aiocs-docs-specialist.toml).
 
-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.
+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
@@ -85,6 +92,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
 ```
 
@@ -106,6 +114,27 @@ docs --json diff hyperliquid
 docs --json verify coverage hyperliquid /absolute/path/to/reference.md
 ```
 
+Research workspaces:
+
+```bash
+docs --json workspace create market-structure --label "Market Structure" --auto-compile
+docs --json workspace bind market-structure hyperliquid nktkas-hyperliquid
+docs --json workspace compile market-structure
+docs --json workspace queue-run
+docs --json workspace search market-structure "transport design" --scope mixed
+docs --json workspace artifact show market-structure derived/index.md
+docs --json workspace lint market-structure
+docs --json workspace output market-structure report --name weekly-brief
+docs --json workspace answer market-structure note "What changed in websocket transport?" --name websocket-note
+docs --json workspace ingest add market-structure markdown-dir /absolute/path/to/notes --label "Research notes"
+docs --json workspace ingest add market-structure csv /absolute/path/to/fills.csv --label "Fills CSV"
+docs --json workspace ingest add market-structure json /absolute/path/to/manifest.json --label "Research manifest"
+docs --json workspace ingest add market-structure jsonl /absolute/path/to/events.jsonl --label "Events JSONL"
+docs --json workspace sync obsidian market-structure /absolute/path/to/vault
+```
+
+If bound source snapshots have changed since the last compile, rerun `workspace compile` before `workspace output`. The output path now fails closed on stale derived artifacts instead of synthesizing reports from outdated summaries.
+
 Catalog maintenance:
 
 ```bash
@@ -121,14 +150,32 @@ 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`
+- `workspace_list`
+- `workspace_status`
+- `workspace_search`
+- `workspace_ingest_list`
+- `workspace_ingest_search`
+- `workspace_artifact_list`
+- `workspace_artifact_show`
+- `workspace_lint`
 - `batch`
 
+Use mutating tools such as `source_upsert`, `refresh_due`, `fetch`, `workspace_create`, `workspace_bind`, `workspace_compile`, and `workspace_output` only through the `aiocs-curation` workflow.
+
+## LM Studio requirement for workspaces
+
+Workspace compilation and output generation use LM Studio in v1. Codex should assume:
+
+- provider: LM Studio
+- model: `google/gemma-4-26b-a4b`
+- default API endpoint: `ws://127.0.0.1:1234`
+
+If `doctor` reports the `lmstudio` check as `warn` or `fail`, Codex should not claim workspace compilation is available until LM Studio is running and the configured model is loaded.
+
 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

@@ -54,6 +54,26 @@ All of these support the root-level `--json` flag:
 - `diff`
 - `project link`
 - `project unlink`
+- `workspace create`
+- `workspace configure`
+- `workspace list`
+- `workspace bind`
+- `workspace unbind`
+- `workspace compile`
+- `workspace queue-run`
+- `workspace status`
+- `workspace search`
+- `workspace ingest add`
+- `workspace ingest list`
+- `workspace ingest show`
+- `workspace ingest search`
+- `workspace ingest remove`
+- `workspace artifact list`
+- `workspace artifact show`
+- `workspace lint`
+- `workspace output`
+- `workspace answer`
+- `workspace sync obsidian`
 - `backup export`
 - `backup import`
 - `embeddings status`
@@ -106,8 +126,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,11 +145,13 @@ This section documents the stable top-level `data` payload per command.
 Check ids are currently:
 
 - `catalog`
+- `git`
 - `playwright`
 - `daemon-config`
 - `source-spec-dirs`
 - `freshness`
 - `daemon-heartbeat`
+- `lmstudio`
 - `embedding-provider`
 - `vector-store`
 - `embeddings`
@@ -158,9 +180,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_...",
@@ -240,6 +266,405 @@ Summary status values:
 }
 ```
 
+### Workspace commands
+
+Workspace commands manage derived wiki artifacts backed by canonical source snapshots and LM Studio compilation.
+
+#### `workspace.create`
+
+```json
+{
+  "workspace": {
+    "id": "market-structure",
+    "label": "Market Structure",
+    "compilerProfile": {
+      "provider": "lmstudio",
+      "model": "google/gemma-4-26b-a4b",
+      "temperature": 0.1,
+      "topP": 0.9,
+      "maxInputChars": 12000,
+      "maxOutputTokens": 4096,
+      "concurrency": 1
+    },
+    "defaultOutputFormats": ["report", "slides"]
+  }
+}
+```
+
+#### `workspace.list`
+
+```json
+{
+  "workspaces": [
+    {
+      "id": "market-structure",
+      "label": "Market Structure",
+      "bindingCount": 2,
+      "artifactCount": 5,
+      "lastCompileStatus": "success"
+    }
+  ]
+}
+```
+
+#### `workspace.bind` and `workspace.unbind`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "sourceIds": ["hyperliquid", "nktkas-hyperliquid"]
+}
+```
+
+#### `workspace.configure`
+
+```json
+{
+  "workspace": {
+    "id": "market-structure",
+    "label": "Market Structure",
+    "autoCompileEnabled": true
+  }
+}
+```
+
+#### `workspace.compile`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "skipped": false,
+  "sourceFingerprint": "sha256...",
+  "changedSourceIds": ["hyperliquid"],
+  "changedRawInputIds": [],
+  "updatedArtifactPaths": [
+    "derived/sources/hyperliquid/summary.md",
+    "derived/concepts/hyperliquid.md",
+    "derived/index.md"
+  ],
+  "artifactCount": 3,
+  "compileRunId": "wrkcmp_..."
+}
+```
+
+#### `workspace.queue-run`
+
+```json
+{
+  "processedJobs": 1,
+  "succeededJobs": [
+    {
+      "workspaceId": "market-structure",
+      "sourceFingerprint": "sha256...",
+      "changedSourceIds": ["hyperliquid"],
+      "changedRawInputIds": []
+    }
+  ],
+  "failedJobs": []
+}
+```
+
+#### `workspace.status`
+
+```json
+{
+  "workspace": {
+    "id": "market-structure",
+    "label": "Market Structure",
+    "autoCompileEnabled": true
+  },
+  "bindings": [
+    {
+      "workspaceId": "market-structure",
+      "sourceId": "hyperliquid",
+      "createdAt": "2026-04-03T10:00:00.000Z"
+    }
+  ],
+  "artifacts": [
+    {
+      "workspaceId": "market-structure",
+      "path": "derived/index.md",
+      "kind": "index",
+      "stale": false,
+      "chunkCount": 3
+    }
+  ],
+  "compileJob": {
+    "workspaceId": "market-structure",
+    "status": "pending",
+    "requestedSourceIds": ["hyperliquid"],
+    "requestedRawInputIds": [],
+    "requestedFingerprint": null
+  },
+  "rawInputs": [],
+  "syncTargets": [],
+  "questionRuns": [],
+  "links": [],
+  "graph": {
+    "linkCount": 4,
+    "brokenLinkCount": 0,
+    "orphanArtifactCount": 0,
+    "backlinkCount": 4,
+    "relationCounts": {
+      "explicit_link": 0,
+      "derived_from": 1,
+      "mentions": 1,
+      "related_to": 2,
+      "expands": 1,
+      "index_entry": 2,
+      "summary_of": 1,
+      "concept_of": 1,
+      "output_depends_on": 0
+    },
+    "mostLinkedArtifacts": [
+      {
+        "artifactPath": "derived/index.md",
+        "incomingCount": 0,
+        "outgoingCount": 2
+      }
+    ]
+  },
+  "lintSummary": {
+    "status": "pass",
+    "findingCount": 0,
+    "staleArtifactCount": 0,
+    "missingProvenanceCount": 0,
+    "missingArtifactCount": 0,
+    "brokenLinkCount": 0,
+    "orphanArtifactCount": 0,
+    "suggestedConceptCount": 0,
+    "duplicateConceptCandidateCount": 0,
+    "missingArticleCandidateCount": 0,
+    "followUpQuestionCount": 0
+  },
+  "health": {
+    "status": "healthy",
+    "staleArtifactCount": 0,
+    "pendingCompileJobs": 0,
+    "failedCompileJobs": 0,
+    "brokenLinkCount": 0,
+    "orphanArtifactCount": 0,
+    "rawInputCount": 0,
+    "lintFindingCount": 0,
+    "duplicateConceptCandidateCount": 0,
+    "missingArticleCandidateCount": 0,
+    "followUpQuestionCount": 0
+  },
+  "compileRuns": [
+    {
+      "id": "wrkcmp_...",
+      "status": "success"
+    }
+  ]
+}
+```
+
+#### `workspace.ingest.*`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "rawInput": {
+    "id": "csv-fills-abc123def0",
+    "workspaceId": "market-structure",
+    "kind": "csv",
+    "label": "Fills CSV",
+    "sourcePath": "/absolute/path/to/fills.csv",
+    "storagePath": "raw/csv-fills-abc123def0/fills.csv",
+    "extractedTextPath": "raw/csv-fills-abc123def0/fills.csv.txt",
+    "contentHash": "sha256...",
+    "chunkCount": 12
+  }
+}
+```
+
+Raw-input search returns:
+
+```json
+{
+  "workspaceId": "market-structure",
+  "query": "fee tier",
+  "total": 1,
+  "limit": 10,
+  "offset": 0,
+  "hasMore": false,
+  "results": [
+    {
+      "rawInputId": "csv-fills-abc123def0",
+      "kind": "csv",
+      "label": "Fills CSV",
+      "sectionTitle": "Fills CSV rows 1-2",
+      "markdown": "...",
+      "filePath": "fills.csv",
+      "score": 0.42
+    }
+  ]
+}
+```
+
+#### `workspace.search`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "query": "transport design",
+  "scope": "mixed",
+  "limit": 10,
+  "offset": 0,
+  "hasMore": false,
+  "modeRequested": "auto",
+  "modeUsed": "hybrid",
+  "total": 2,
+  "results": [
+    {
+      "kind": "source",
+      "scope": "source",
+      "chunkId": 42,
+      "sourceId": "nktkas-hyperliquid",
+      "snapshotId": "snp_...",
+      "pageUrl": "file://src/transports/websocket.ts",
+      "pageTitle": "src/transports/websocket.ts",
+      "sectionTitle": "WebSocketTransport",
+      "markdown": "...",
+      "pageKind": "file",
+      "filePath": "src/transports/websocket.ts",
+      "language": "typescript",
+      "score": 0.91,
+      "signals": ["lexical", "vector"]
+    },
+    {
+      "kind": "derived",
+      "scope": "derived",
+      "artifactPath": "derived/concepts/nktkas-hyperliquid.md",
+      "artifactKind": "concept",
+      "sectionTitle": "Transport design",
+      "markdown": "...",
+      "stale": false,
+      "score": 0.74
+    }
+  ]
+}
+```
+
+#### `workspace.artifact.list`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "artifacts": [
+    {
+      "workspaceId": "market-structure",
+      "path": "derived/index.md",
+      "kind": "index",
+      "stale": false,
+      "chunkCount": 3
+    }
+  ]
+}
+```
+
+#### `workspace.artifact.show`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "artifact": {
+    "workspaceId": "market-structure",
+    "path": "derived/index.md",
+    "kind": "index",
+    "stale": false
+  },
+  "content": "# Workspace Index\n...",
+  "provenance": [
+    {
+      "workspaceId": "market-structure",
+      "path": "derived/index.md",
+      "sourceId": "hyperliquid",
+      "snapshotId": "snp_...",
+      "chunkIds": [42, 43]
+    }
+  ],
+  "rawInputProvenance": []
+}
+```
+
+#### `workspace.lint`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "summary": {
+    "status": "warn",
+    "findingCount": 1,
+    "staleArtifactCount": 1,
+    "missingProvenanceCount": 0,
+    "missingArtifactCount": 0,
+    "brokenLinkCount": 0,
+    "orphanArtifactCount": 0,
+    "suggestedConceptCount": 0,
+    "duplicateConceptCandidateCount": 1,
+    "missingArticleCandidateCount": 1,
+    "followUpQuestionCount": 2
+  },
+  "findings": [
+    {
+      "kind": "stale-artifact",
+      "severity": "warn",
+      "summary": "Artifact provenance points at an older snapshot.",
+      "artifactPath": "derived/sources/hyperliquid/summary.md"
+    },
+    {
+      "kind": "follow-up-question-suggestion",
+      "severity": "warn",
+      "summary": "What important workflows, caveats, or open questions remain unresolved for derived/concepts/hyperliquid.md?",
+      "artifactPath": "derived/concepts/hyperliquid.md"
+    }
+  ],
+  "suggestionsArtifactPath": "outputs/suggestions/lint.md"
+}
+```
+
+#### `workspace.output`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "format": "report",
+  "path": "outputs/reports/weekly-brief.md",
+  "artifactCount": 8
+}
+```
+
+#### `workspace.answer`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "format": "note",
+  "path": "derived/notes/websocket-note.md",
+  "artifactCount": 9,
+  "questionRun": {
+    "id": "wrkq_...",
+    "workspaceId": "market-structure",
+    "question": "What changed in websocket transport?",
+    "format": "note",
+    "artifactPath": "derived/notes/websocket-note.md",
+    "status": "success"
+  }
+}
+```
+
+#### `workspace.sync.obsidian`
+
+```json
+{
+  "workspaceId": "market-structure",
+  "vaultPath": "/absolute/path/to/vault",
+  "targetPath": "/absolute/path/to/vault/aiocs/market-structure",
+  "exportSubdir": "aiocs/market-structure"
+}
+```
+
 ### `diff`
 
 ```json
@@ -256,7 +681,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 +693,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 +724,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 +736,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 +880,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..."
   }
 }
@@ -476,6 +914,11 @@ Current stable CLI error codes include:
 
 - `INVALID_ARGUMENT`
 - `SOURCE_NOT_FOUND`
+- `WORKSPACE_NOT_FOUND`
+- `WORKSPACE_ARTIFACT_NOT_FOUND`
+- `WORKSPACE_ARTIFACTS_STALE`
+- `WORKSPACE_COMPILER_CONFIG_INVALID`
+- `WORKSPACE_COMPILER_UNAVAILABLE`
 - `SNAPSHOT_NOT_FOUND`
 - `NO_PAGES_FETCHED`
 - `NO_PROJECT_SCOPE`