@bodhi-ventures/aiocs 0.2.0 → 0.3.1

package/README.md

@@ -13,6 +13,7 @@ Local-only documentation fetch, versioning, and search CLI for AI agents.
 - diffs snapshots to show what changed between fetches
 - indexes heading-aware chunks in SQLite FTS5
 - adds optional hybrid retrieval with local Ollama embeddings and a dedicated Qdrant vector index
+- compiles derived research workspaces into Markdown wiki artifacts with LM Studio
 - links docs sources to local projects for scoped search
 - exports and imports manifest-backed backups for `~/.aiocs`
 
@@ -200,6 +201,83 @@ 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.
 
+### Research workspaces
+
+`aiocs` can compile a derived workspace wiki on top of canonical source snapshots. Workspace artifacts are stored separately from fetched sources under `~/.aiocs/data/workspaces/<workspace-id>/` and keep provenance links back to source chunks.
+
+LM Studio is the v1 compiler runtime. Load `google/gemma-4-26b-a4b` in LM Studio, start the local API server, and make sure `doctor` can see it:
+
+```bash
+docs --json doctor
+```
+
+If LM Studio is running on a non-default host or model, override:
+
+```bash
+export AIOCS_LMSTUDIO_BASE_URL=ws://127.0.0.1:1234
+export AIOCS_LMSTUDIO_MODEL=google/gemma-4-26b-a4b
+```
+
+These environment overrides apply at runtime, including for already-created workspaces.
+
+Create, bind, compile, and search a workspace:
+
+```bash
+docs workspace create market-structure --label "Market Structure" --auto-compile
+docs workspace bind market-structure hyperliquid nktkas-hyperliquid
+docs workspace compile market-structure
+docs workspace status market-structure
+docs workspace queue-run
+docs workspace search market-structure "transport and websocket design" --scope mixed
+docs workspace artifact list market-structure
+docs workspace artifact show market-structure derived/index.md
+docs workspace lint market-structure
+docs workspace output market-structure report --name weekly-brief
+docs workspace output market-structure slides --name weekly-brief
+docs workspace answer market-structure note "What changed in websocket transport?" --name websocket-note
+```
+
+Workspace compile and maintenance are incremental:
+
+- canonical source snapshots remain the source of truth
+- unchanged sources are skipped on later compiles
+- changed sources regenerate only their derived summaries/concepts plus the shared index
+- changed raw inputs regenerate only their derived summaries/concepts plus the shared index
+- compiled artifacts get deterministic graph navigation with outgoing relations and backlinks
+- workspace lint persists durable suggestion artifacts for duplicate concepts, missing articles, and follow-up questions
+- generated reports/slides keep provenance to the bound source snapshots
+- generated notes/reports/slides are marked stale when their inputs change
+
+Opt-in automatic recompilation:
+
+- set `--auto-compile` when creating the workspace, or later with `docs workspace configure <workspace-id> --auto-compile true`
+- the daemon queues recompiles after bound source refreshes
+- run `docs workspace queue-run` to process queued jobs outside the daemon
+
+Workspace-scoped raw ingest:
+
+```bash
+docs workspace ingest add market-structure markdown-dir /absolute/path/to/notes --label "Research notes"
+docs workspace ingest add market-structure pdf /absolute/path/to/paper.pdf --label "Paper PDF"
+docs workspace ingest add market-structure image /absolute/path/to/diagram.png --label "Market diagram"
+docs workspace ingest add market-structure csv /absolute/path/to/fills.csv --label "Fills CSV"
+docs workspace ingest add market-structure json /absolute/path/to/manifest.json --label "Research manifest"
+docs workspace ingest add market-structure jsonl /absolute/path/to/events.jsonl --label "Events JSONL"
+docs workspace ingest list market-structure
+docs workspace ingest search market-structure "fee tier" --kind markdown-dir
+docs workspace ingest show market-structure markdown-dir-notes-<hash>
+```
+
+Obsidian sync:
+
+```bash
+docs workspace sync obsidian market-structure /absolute/path/to/obsidian-vault
+```
+
+The workspace is synced under `aiocs/<workspace-id>/` by default so the raw, derived, and output trees stay grouped inside the vault.
+
+If any bound source snapshot changes, rerun `docs workspace compile <workspace-id>` before `docs workspace output ...`. Output generation fails closed when required derived artifacts are stale.
+
 For agents, the intended decision order is:
 
 1. check `source list` or scoped `search` first