@bodhi-ventures/aiocs 0.1.1 → 0.2.0

package/README.md

@@ -5,6 +5,7 @@ Local-only documentation fetch, versioning, and search CLI for AI agents.
 ## What it does
 
 - fetches docs from websites with Playwright
+- snapshots curated external git repositories as shared local reference sources
 - supports authenticated sources via environment-backed headers and cookies
 - runs lightweight canaries to detect source drift before full refreshes
 - normalizes them into Markdown
@@ -30,25 +31,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 +57,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,12 +109,23 @@ 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).
+
+Canonical Codex setup:
+
+- register `aiocs-mcp` in `~/.codex/config.toml`
+- link `skills/aiocs` into `~/.codex/skills/aiocs`
+- link `skills/aiocs-curation` into `~/.codex/skills/aiocs-curation`
+- keep the optional specialist subagent linked only as a fallback for heavier docs workflows
 
 ## Managed sources
 
-The open-source repo bundles `hyperliquid` in `sources/`. Additional machine-local source specs
-belong in `~/.aiocs/sources`.
+The open-source repo bundles both web and git sources in `sources/`:
+
+- `hyperliquid` for the public docs site
+- `nktkas-hyperliquid` for the `nktkas/hyperliquid` GitHub repository
+
+Additional machine-local source specs belong in `~/.aiocs/sources`.
 
 `docs init` bootstraps both managed locations, so source behavior is the same regardless of
 whether a spec lives in the repo or in `~/.aiocs/sources`.
@@ -140,50 +151,51 @@ 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 "WebSocketTransport" --source nktkas-hyperliquid --path "src/**" --language typescript
+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.
@@ -195,6 +207,34 @@ For agents, the intended decision order is:
 3. if the source is missing but worth reusing, add a spec under `~/.aiocs/sources`, then upsert and refresh only that source
 4. avoid `fetch all` unless the user explicitly asks or the daemon is doing maintenance
 
+### Git repo sources
+
+`aiocs` supports first-class `kind: git` sources for curated external repositories that should be
+reused across multiple local projects.
+
+Example:
+
+```yaml
+kind: git
+id: nktkas-hyperliquid
+label: nktkas/hyperliquid Repo
+repo:
+  url: https://github.com/nktkas/hyperliquid.git
+  ref: main
+  include:
+    - README.md
+    - docs/**
+    - src/**
+  exclude:
+    - .github/**
+    - dist/**
+schedule:
+  everyHours: 24
+```
+
+Git source snapshots are commit-based, stored under the shared local catalog, and searchable with
+the same project linking, diffing, canary, and hybrid search flows as website docs.
+
 ### Hybrid search
 
 `aiocs` keeps SQLite FTS5/BM25 as the canonical lexical index and adds an optional hybrid layer:
@@ -279,22 +319,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 +361,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 +392,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 +408,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
 ```
 
@@ -405,7 +450,7 @@ The repo ships two GitHub Actions workflows:
 - [ci.yml](./.github/workflows/ci.yml): validation for lint, tests, build, pack, and Docker smoke coverage
 - [release.yml](./.github/workflows/release.yml): tag-driven stable release flow that validates the tagged package state, publishes to npm, and creates a GitHub release
 
-The release workflow is triggered only by pushed stable tags matching `vX.Y.Z` and expects `NPM_TOKEN` in repository secrets. The release job is retryable: if `@bodhi-ventures/aiocs@X.Y.Z` already exists on npm or the GitHub release already exists for `vX.Y.Z`, the workflow skips the completed publication step and finishes the remaining one.
+The release workflow is triggered only by pushed stable tags matching `vX.Y.Z` and expects an npm publish token in GitHub repository secrets. The release job is retryable: if `@bodhi-ventures/aiocs@X.Y.Z` already exists on npm or the GitHub release already exists for `vX.Y.Z`, the workflow skips the completed publication step and finishes the remaining one.
 
 Successful MCP results use an envelope: