@bodhi-ventures/aiocs 0.1.0

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

@@ -0,0 +1,21 @@
+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"]

package/docs/json-contract.md

@@ -0,0 +1,524 @@
+# CLI JSON Contract
+
+`aiocs` exposes a single-document JSON envelope for every one-shot CLI command when the root `--json` flag is present.
+
+## One-shot command envelope
+
+Successful commands write exactly one JSON object to stdout:
+
+```json
+{
+  "ok": true,
+  "command": "search",
+  "data": {
+    "results": []
+  }
+}
+```
+
+Failed commands still write exactly one JSON object to stdout and exit with status `1`:
+
+```json
+{
+  "ok": false,
+  "command": "show",
+  "error": {
+    "code": "CHUNK_NOT_FOUND",
+    "message": "Chunk 42 not found"
+  }
+}
+```
+
+Envelope fields:
+
+- `ok`: `true` when the command executed and returned data, `false` when command execution failed
+- `command`: stable command identifier such as `source.list`, `refresh.due`, `doctor`, or `init`
+- `data`: command-specific payload on success
+- `error.code`: stable machine-readable failure code
+- `error.message`: stable human-readable error summary on failure
+- `error.details`: optional extra machine-readable error context
+
+## Supported one-shot commands
+
+All of these support the root-level `--json` flag:
+
+- `version`
+- `init`
+- `doctor`
+- `source upsert`
+- `source list`
+- `fetch`
+- `canary`
+- `refresh due`
+- `snapshot list`
+- `diff`
+- `project link`
+- `project unlink`
+- `backup export`
+- `backup import`
+- `embeddings status`
+- `embeddings backfill`
+- `embeddings clear`
+- `embeddings run`
+- `search`
+- `verify coverage`
+- `show`
+
+## Command payloads
+
+This section documents the stable top-level `data` payload per command.
+
+### `version`
+
+```json
+{
+  "name": "@bodhi-ventures/aiocs",
+  "version": "0.1.0"
+}
+```
+
+### `init`
+
+```json
+{
+  "sourceSpecDir": "/absolute/path/to/aiocs/sources",
+  "fetched": false,
+  "initializedSources": [
+    {
+      "sourceId": "hyperliquid",
+      "specPath": "/absolute/path/to/aiocs/sources/hyperliquid.yaml",
+      "configHash": "sha256...",
+      "configChanged": false
+    }
+  ],
+  "removedSourceIds": [],
+  "fetchResults": []
+}
+```
+
+### `doctor`
+
+```json
+{
+  "summary": {
+    "status": "healthy",
+    "checkCount": 10,
+    "passCount": 10,
+    "warnCount": 0,
+    "failCount": 0
+  },
+  "checks": [
+    {
+      "id": "catalog",
+      "status": "pass",
+      "summary": "Catalog opened successfully at ~/.aiocs/data",
+      "details": {}
+    }
+  ]
+}
+```
+
+Check ids are currently:
+
+- `catalog`
+- `playwright`
+- `daemon-config`
+- `source-spec-dirs`
+- `freshness`
+- `daemon-heartbeat`
+- `embedding-provider`
+- `vector-store`
+- `embeddings`
+- `docker`
+
+Summary status values:
+
+- `healthy`: no warnings or failures
+- `degraded`: warnings but no failures
+- `unhealthy`: at least one failed check
+
+### `source.upsert`
+
+```json
+{
+  "sourceId": "hyperliquid",
+  "configHash": "sha256...",
+  "specPath": "/absolute/path/to/spec.yaml"
+}
+```
+
+### `source.list`
+
+```json
+{
+  "sources": [
+    {
+      "id": "hyperliquid",
+      "label": "Hyperliquid",
+      "nextDueAt": "2026-03-26T12:00:00.000Z",
+      "nextCanaryDueAt": "2026-03-26T06:00:00.000Z",
+      "lastCheckedAt": "2026-03-26T10:00:00.000Z",
+      "lastSuccessfulSnapshotAt": "2026-03-26T10:00:00.000Z",
+      "lastSuccessfulSnapshotId": "snp_...",
+      "lastCanaryCheckedAt": "2026-03-26T08:00:00.000Z",
+      "lastSuccessfulCanaryAt": "2026-03-26T08:00:00.000Z",
+      "lastCanaryStatus": "pass"
+    }
+  ]
+}
+```
+
+### `fetch` and `refresh.due`
+
+```json
+{
+  "results": [
+    {
+      "sourceId": "hyperliquid",
+      "snapshotId": "snp_...",
+      "pageCount": 139,
+      "reused": false
+    }
+  ]
+}
+```
+
+### `canary`
+
+```json
+{
+  "results": [
+    {
+      "sourceId": "hyperliquid",
+      "status": "pass",
+      "checkedAt": "2026-03-26T10:00:00.000Z",
+      "summary": {
+        "checkCount": 1,
+        "passCount": 1,
+        "failCount": 0
+      },
+      "checks": [
+        {
+          "url": "https://example.dev/docs/start",
+          "status": "pass",
+          "title": "Docs Start",
+          "markdownLength": 120
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `snapshot.list`
+
+```json
+{
+  "sourceId": "hyperliquid",
+  "snapshots": [
+    {
+      "snapshotId": "snp_...",
+      "sourceId": "hyperliquid",
+      "detectedVersion": null,
+      "createdAt": "2026-03-26T10:00:00.000Z",
+      "pageCount": 139
+    }
+  ]
+}
+```
+
+### `project.link` and `project.unlink`
+
+```json
+{
+  "projectPath": "/absolute/path/to/project",
+  "sourceIds": ["hyperliquid", "lighter"]
+}
+```
+
+### `diff`
+
+```json
+{
+  "sourceId": "hyperliquid",
+  "fromSnapshotId": "snp_old",
+  "toSnapshotId": "snp_new",
+  "summary": {
+    "addedPageCount": 1,
+    "removedPageCount": 1,
+    "changedPageCount": 2,
+    "unchangedPageCount": 98
+  },
+  "addedPages": [
+    {
+      "url": "https://example.dev/docs/new-page",
+      "title": "New page"
+    }
+  ],
+  "removedPages": [],
+  "changedPages": [
+    {
+      "url": "https://example.dev/docs/start",
+      "beforeTitle": "Start",
+      "afterTitle": "Start",
+      "lineSummary": {
+        "addedLineCount": 3,
+        "removedLineCount": 2
+      }
+    }
+  ]
+}
+```
+
+### `search`
+
+```json
+{
+  "query": "maker flow",
+  "total": 42,
+  "limit": 20,
+  "offset": 0,
+  "hasMore": true,
+  "modeRequested": "auto",
+  "modeUsed": "hybrid",
+  "results": [
+    {
+      "chunkId": 42,
+      "sourceId": "hyperliquid",
+      "snapshotId": "snp_...",
+      "pageUrl": "https://example.dev/docs/maker-flow",
+      "pageTitle": "Maker flow",
+      "sectionTitle": "Order lifecycle",
+      "markdown": "# Order lifecycle\n...",
+      "score": 0.036,
+      "signals": ["lexical", "vector"]
+    }
+  ]
+}
+```
+
+`limit` defaults to `20`. `offset` defaults to `0`.
+
+`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.
+
+### `embeddings.status`
+
+```json
+{
+  "queue": {
+    "pendingJobs": 0,
+    "runningJobs": 0,
+    "failedJobs": 0
+  },
+  "sources": [
+    {
+      "sourceId": "hyperliquid",
+      "snapshotId": "snp_...",
+      "totalChunks": 420,
+      "indexedChunks": 420,
+      "pendingChunks": 0,
+      "failedChunks": 0,
+      "staleChunks": 0,
+      "coverageRatio": 1
+    }
+  ]
+}
+```
+
+### `embeddings.backfill`
+
+```json
+{
+  "queuedJobs": 5
+}
+```
+
+### `embeddings.clear`
+
+```json
+{
+  "clearedSources": ["hyperliquid", "lighter"]
+}
+```
+
+### `embeddings.run`
+
+```json
+{
+  "processedJobs": 2,
+  "succeededJobs": [
+    {
+      "sourceId": "hyperliquid",
+      "snapshotId": "snp_...",
+      "chunkCount": 420
+    }
+  ],
+  "failedJobs": []
+}
+```
+
+### `verify.coverage`
+
+```json
+{
+  "sourceId": "hyperliquid",
+  "snapshotId": "snp_...",
+  "complete": false,
+  "summary": {
+    "fileCount": 1,
+    "headingCount": 100,
+    "matchedHeadingCount": 99,
+    "missingHeadingCount": 1,
+    "matchCounts": {
+      "pageTitle": 80,
+      "sectionTitle": 15,
+      "body": 4
+    }
+  },
+  "files": [
+    {
+      "referenceFile": "/absolute/path/to/reference.md",
+      "headingCount": 100,
+      "matchedHeadingCount": 99,
+      "missingHeadingCount": 1,
+      "missingHeadings": ["Missing Heading"],
+      "matchCounts": {
+        "pageTitle": 80,
+        "sectionTitle": 15,
+        "body": 4
+      }
+    }
+  ]
+}
+```
+
+### `backup.export`
+
+```json
+{
+  "outputDir": "/absolute/path/to/backup",
+  "manifestPath": "/absolute/path/to/backup/manifest.json",
+  "manifest": {
+    "formatVersion": 1,
+    "createdAt": "2026-03-26T10:00:00.000Z",
+    "packageVersion": "0.1.0",
+    "entries": [
+      {
+        "relativePath": "data/catalog.sqlite",
+        "type": "file",
+        "size": 32768
+      }
+    ]
+  }
+}
+```
+
+### `backup.import`
+
+```json
+{
+  "inputDir": "/absolute/path/to/backup",
+  "dataDir": "/Users/example/.aiocs/data",
+  "configDir": "/Users/example/.aiocs/config",
+  "manifest": {
+    "formatVersion": 1,
+    "createdAt": "2026-03-26T10:00:00.000Z",
+    "packageVersion": "0.1.0",
+    "entries": []
+  }
+}
+```
+
+### `show`
+
+```json
+{
+  "chunk": {
+    "chunkId": 42,
+    "sourceId": "hyperliquid",
+    "snapshotId": "snp_...",
+    "pageUrl": "https://example.dev/docs/maker-flow",
+    "pageTitle": "Maker flow",
+    "sectionTitle": "Order lifecycle",
+    "markdown": "# Order lifecycle\n..."
+  }
+}
+```
+
+## Daemon event stream
+
+`docs daemon --json` is intentionally different because the process is long-running. It emits newline-delimited JSON events to stdout rather than a single envelope.
+
+Current event types:
+
+- `daemon.started`
+- `daemon.cycle.started`
+- `daemon.cycle.completed`
+- `daemon.stopped`
+
+Example:
+
+```json
+{"type":"daemon.started","intervalMinutes":60,"fetchOnStart":true,"sourceSpecDirs":["/app/sources"]}
+{"type":"daemon.cycle.started","reason":"startup","startedAt":"2026-03-26T00:00:00.000Z"}
+{"type":"daemon.cycle.completed","reason":"startup","result":{"startedAt":"2026-03-26T00:00:00.000Z","finishedAt":"2026-03-26T00:00:10.000Z","dueSourceIds":[],"bootstrapped":{"processedSpecCount":5,"removedSourceIds":[],"sources":[]},"refreshed":[],"failed":[],"embedded":[],"embeddingFailed":[]}}
+{"type":"daemon.stopped"}
+```
+
+## Error codes
+
+Current stable CLI error codes include:
+
+- `INVALID_ARGUMENT`
+- `SOURCE_NOT_FOUND`
+- `SNAPSHOT_NOT_FOUND`
+- `NO_PAGES_FETCHED`
+- `NO_PROJECT_SCOPE`
+- `CHUNK_NOT_FOUND`
+- `REFERENCE_FILE_NOT_FOUND`
+- `INVALID_REFERENCE_FILE`
+- `EMBEDDING_CONFIG_INVALID`
+- `EMBEDDING_PROVIDER_UNAVAILABLE`
+- `VECTOR_STORE_UNAVAILABLE`
+- `EMBEDDING_JOB_NOT_FOUND`
+- `INTERNAL_ERROR`
+
+## MCP relationship
+
+The `aiocs-mcp` server uses the same underlying payloads, but wraps them in a structured MCP envelope:
+
+Successful MCP tool results:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "name": "@bodhi-ventures/aiocs",
+    "version": "0.1.0"
+  }
+}
+```
+
+Failed MCP tool results:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "CHUNK_NOT_FOUND",
+    "message": "Chunk 42 not found"
+  }
+}
+```
+
+The MCP `search` tool supports the same `limit` and `offset` fields as the CLI. The MCP server also exposes:
+
+- `embeddings_status`
+- `embeddings_backfill`
+- `embeddings_clear`
+- `embeddings_run`
+- `verify_coverage`
+- `batch`
+
+`batch` returns one result object per requested operation, each with its own `ok`, `data`, or `error` fields.

package/docs/superpowers/specs/2026-03-29-tag-driven-release-pipeline-design.md

@@ -0,0 +1,135 @@
+# Tag-Driven Release Pipeline Design
+
+## Summary
+
+`aiocs` should release as the public scoped npm package `@bodhi-ventures/aiocs` through a stable, tag-driven GitHub Actions workflow. The repository remains the source of truth for versioning. Releases are created only from pushed stable tags of the form `vX.Y.Z`.
+
+The workflow must never mutate git state. It should validate the tag against `package.json`, run the full release verification stack, publish publicly to npm with provenance, and create a GitHub release from the same tag.
+
+## Goals
+
+- publish `aiocs` publicly under `@bodhi-ventures/aiocs`
+- eliminate workflow-managed version bumps, commits, and tag creation
+- remove improvised git author configuration from the release workflow
+- make the release contract deterministic and easy to reason about
+- keep CI and release validation aligned with the actual shipped package surface
+
+## Non-Goals
+
+- prerelease publishing
+- automatic releases from `main`
+- workspace/multi-package publishing
+- alternative binary distribution outside npm
+
+## Current State
+
+- `package.json` still uses the unscoped package name `aiocs`
+- the current release workflow is `workflow_dispatch`-driven
+- the workflow edits `package.json`, creates commits and tags, and configures a bot git identity
+- release automation is more complex than necessary and mixes version mutation with publishing
+
+## Chosen Design
+
+### Package Identity
+
+- rename the npm package to `@bodhi-ventures/aiocs`
+- keep the package public
+- keep CLI command names unchanged:
+  - `docs`
+  - `aiocs-mcp`
+- add explicit `publishConfig`:
+  - `access: public`
+  - `provenance: true`
+
+### Release Trigger
+
+- release workflow triggers only on pushed stable semver tags matching `v*.*.*`
+- the tag version must match `package.json.version` exactly
+- only stable releases are supported; prerelease tags are rejected
+
+### Release Workflow Behavior
+
+- check out the tagged revision
+- install dependencies and release prerequisites
+- fail fast unless all of these are true:
+  - tag matches `vX.Y.Z`
+  - `package.json.version === X.Y.Z`
+  - `package.json.name === @bodhi-ventures/aiocs`
+- run full release validation:
+  - `pnpm lint`
+  - `pnpm test`
+  - `pnpm build`
+  - `npm pack --dry-run`
+  - built CLI smoke, at minimum `node dist/cli.js --version`
+- publish to npm with the existing `NPM_TOKEN` org secret
+- create a GitHub release for the pushed tag
+- if a GitHub release already exists for that tag, do not recreate it
+
+### Rerun and Partial-Failure Policy
+
+Tag releases must be safely rerunnable.
+
+- `workflow_dispatch` is removed entirely; tag pushes are the only release trigger
+- if a rerun sees that `@bodhi-ventures/aiocs@X.Y.Z` is already published on npm, it must skip `npm publish` instead of failing
+- if a rerun sees that the GitHub release for `vX.Y.Z` already exists, it must skip release creation instead of failing
+- validation steps always run on every attempt, even when publish/release steps are skipped
+- if npm already contains `@bodhi-ventures/aiocs@X.Y.Z` but the checked-out tag does not match `package.json.version === X.Y.Z` or `package.json.name === @bodhi-ventures/aiocs`, the workflow must fail fast
+- the workflow should treat npm and GitHub release publication as independently idempotent so a partial success can be completed by rerunning the same tag job
+
+### Git Behavior
+
+- the workflow never edits files
+- the workflow never commits
+- the workflow never creates tags
+- the workflow never configures a synthetic git author
+
+Version bumps happen in normal development flow:
+
+1. update `package.json.version`
+2. commit the version bump
+3. create tag `vX.Y.Z`
+4. push commit and tag
+
+## CI Alignment
+
+CI remains the pre-release gate and should stay close to the release workflow:
+
+- install dependencies
+- install Playwright Chromium
+- run lint, tests, build, and `npm pack --dry-run`
+- validate Docker image and compose config
+- smoke test the packaged CLI surface
+
+CI should also assert package metadata consistency where useful, especially the scoped package name.
+
+## Documentation Changes
+
+Update repository docs to reflect the scoped public package and release process:
+
+- install command becomes `npm install -g @bodhi-ventures/aiocs`
+- add a short release section to the README describing the tag-based flow
+- keep the CLI-facing command examples unchanged
+
+## Risks
+
+- npm org publishing can still fail if org/package permissions are not configured correctly on npmjs
+- the first release is the highest-risk run because the scoped package has not been proven yet
+- GitHub Actions can only validate the workflow structure locally; final proof requires one live tag release
+
+## Acceptance Criteria
+
+- `package.json` is updated to `@bodhi-ventures/aiocs`
+- release workflow triggers on stable tags only
+- release workflow does not mutate git state
+- release workflow validates tag/version/name consistency before publishing
+- README/install docs reference the scoped package name
+- local verification passes on the updated tree:
+  - lint
+  - tests
+  - build
+  - `npm pack --dry-run`
+- the first real release can be executed by bumping version, pushing a `vX.Y.Z` tag, and observing npm + GitHub release creation
+
+## Follow-Up
+
+After implementation, do one real tagged stable release to prove the pipeline end to end.