@bodhi-ventures/aiocs 0.1.2 → 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
@@ -110,10 +111,21 @@ GitHub Actions publishes `@bodhi-ventures/aiocs` publicly to npm and creates the
 
 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`.
@@ -170,6 +182,7 @@ Search and inspect results:
 
 ```bash
 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
@@ -194,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:
@@ -409,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: