rigjs 3.0.33 → 4.0.2

package/doc/architecture/README.md

@@ -0,0 +1,139 @@
+# rig — Architecture (planning notes)
+
+> Status: Draft v0 — 2026-05-17. Author: Bo Wang.
+> Audience: future contributors + Claude Code when working in this repo.
+> Scope: not exhaustive — captures the *shape* of rig as it grows beyond the original "yarn-workspaces + git" multi-repo tool.
+
+---
+
+## 0. What rig is, and is becoming
+
+Originally: a thin CLI on top of `yarn workspaces + git` that lets you share code between projects without publishing to a registry (`rig init / add / dev / install / build / deploy / publish / sync / tag`). See `README.md` for that side of the story.
+
+Now: rig is becoming the user's personal "outer brain" CLI — a single entry point for *non-application* automation that lives across all the user's projects. The first two extensions:
+
+1. **`rig wiki *`** — Karpathy-style LLM Wiki ops over registered project directories, with a launchd daemon for periodic ingest/lint. See `wiki.md`.
+2. **`rig fc *`** — Aliyun Function Compute deploy commands (planned, not yet specced). See `fc.md` (placeholder; written when work starts).
+
+Both groups follow the same shape — local config in `~/.rig/`, per-project opt-in via `package.rig.json5`, optional background daemon, **macOS only** for v1.
+
+---
+
+## 1. Top-level command tree
+
+```
+rig
+├── (existing: pkg/workspace ops)
+│   ├── init / add / dev / install / preinstall / postinstall
+│   ├── build / deploy / publish / sync / tag
+│   ├── check / info / env
+│   └── -v / --version
+│
+├── wiki                         # see wiki.md
+│   ├── init [<path>]
+│   ├── register [<path>] [--name <n>]
+│   ├── unregister <name|path>
+│   ├── list
+│   ├── scan     [--wiki <n> | --all | <path>]
+│   ├── fetch    <url>  [--wiki <n>]
+│   ├── ingest   <path> [--wiki <n>] [--dry-run]
+│   ├── query    "..."  [--wiki <n>]
+│   ├── lint              [--wiki <n> | --all]
+│   ├── index            [--wiki <n> | --all]   # qmd-only; no-op + warn otherwise
+│   ├── install-skill / uninstall-skill         # symlink built-in Claude skill
+│   ├── agent  list | use <claude|codex|pi>
+│   └── daemon start | stop | status | logs [-f] | install | uninstall
+│
+└── fc                           # planned — Aliyun Function Compute (TBD)
+```
+
+Naming convention for new groups: `rig <noun> <verb>`. Single-verb top-level commands are grandfathered for the original pkg ops only.
+
+---
+
+## 2. Directory layout
+
+### 2.1 Code layout (this repo)
+```
+lib/
+├── rig/             # entry point (commander wiring)
+├── <pkg-cmd>/       # existing: init, add, dev, install, build, deploy, ...
+├── wiki/            # NEW — see wiki.md
+│   ├── index.ts     # `rig wiki` commander subtree
+│   ├── paths.ts platform.ts config.ts db.ts qmd.ts
+│   ├── init.ts register.ts unregister.ts list.ts
+│   ├── scan.ts fetch.ts ingest.ts query.ts lint.ts indexCmd.ts
+│   ├── installSkill.ts uninstallSkill.ts
+│   ├── agent/
+│   │   ├── index.ts list.ts use.ts
+│   │   ├── types.ts claude.ts codex.ts pi.ts
+│   └── daemon/
+│       ├── index.ts start.ts stop.ts status.ts logs.ts
+│       ├── install.ts uninstall.ts runner.ts
+├── fc/              # placeholder
+├── classes/ utils/  # existing
+```
+
+### 2.2 User-side layout (`~/.rig/`)
+```
+~/.rig/
+├── config.json5             # default agent, paths, feature flags
+├── wiki.config.json5        # registered wikis + per-wiki schedule overrides
+├── state.db                 # SQLite (better-sqlite3) — sha cache, last_run, ingest_log, FTS5 fallback
+├── locks/                   # flock-based per-wiki advisory locks
+├── logs/
+│   ├── wiki-daemon.log
+│   └── wikis/<wiki-name>/<op>-YYYY-MM-DD.log
+└── cache/                   # scratch + agent sandbox copies
+```
+
+rig never writes outside `~/.rig/`, `~/Library/LaunchAgents/` (only `daemon install`), and the user's CWD.
+
+### 2.3 Per-project layout
+A project opts into `rig wiki` by either:
+- Running `rig wiki register` from its root (auto-detects `harness/llm-wiki/` or asks for a path), or
+- Adding a `wiki` block to its `package.rig.json5`.
+
+The per-project wiki dir follows the layout from `wiki.md §2` — `purpose.md / schema.md / index.md / overview.md / log.md / reviews.md / raw/ / wiki/{sources,entities,concepts,synthesis,queries}/`.
+
+---
+
+## 3. Cross-cutting concerns
+
+| Topic | Decision |
+|---|---|
+| Config format | JSON5 (matches rig conventions) |
+| Config merge order | built-in < `~/.rig/config.json5` < `~/.rig/wiki.config.json5` < project `package.rig.json5` < CLI flag |
+| Human output | `lib/print` (ora + chalk) |
+| Machine output | `--json` flag on all `wiki` subcommands; daemon writes JSONL |
+| Platform | **macOS only** for v1 (arm64 + x64). Linux/Windows: explicit error and exit |
+| Daemon | macOS `launchd` user agent; Linux deferred to P5 |
+| Agent | Requires one of `claude` / `codex` / `pi` on PATH for `ingest/query/lint`; v1 ships Claude only |
+| qmd | Optional; auto-detected; functional fallback when absent |
+| Safety | All writes diffed first; `raw/ / purpose.md / schema.md` never edited by rig (enforced in code) |
+| Local DB | `better-sqlite3@12.10.0` pinned — see `wiki.md §13` |
+| Node | `engines.node = ">=22 <27"` (driven by better-sqlite3 prebuilds) |
+
+---
+
+## 4. Roadmap
+
+| Phase | Scope | State |
+|---|---|---|
+| P1 | `rig wiki init/register/list/scan/fetch/ingest/query/lint`, manual only, Claude adapter, qmd-aware | scaffolding now |
+| P2 | `rig wiki daemon *` (launchd), per-wiki schedule, JSONL logs | after P1 runs ~2 weeks |
+| P3 | Codex + pi-agent adapters; `rig wiki agent use <…>` switch | when a second agent is actually needed |
+| P4 | `rig fc *` (Aliyun Function Compute) | independent track |
+| P5 | Linux daemon, better logs UI | after macOS daemon is stable |
+
+Out of scope (intentionally): web/desktop UI for wiki browsing (Obsidian + VSCode are enough); cross-machine wiki sync (git's job); cross-machine daemon coordination (each box runs its own).
+
+---
+
+## 5. Related docs
+
+- `wiki.md` — full `rig wiki` design (commands, config, daemon, SQLite schema).
+- `agents.md` — agent-CLI adapter interface + Claude/Codex/pi notes.
+- `fc.md` — placeholder for future Aliyun FC work.
+
+User-facing docs stay in `README.md` / `README_CN.md`. Files here capture design intent, not how-to.

package/doc/architecture/agents.md

@@ -0,0 +1,180 @@
+# rig wiki — Agent adapter
+
+> Status: Draft v0 — 2026-05-17.
+> v1 implementation: Claude Code only. Codex / pi-agent are speced as stubs so the interface is forward-compatible.
+
+---
+
+## 1. Single interface
+
+`lib/wiki/agent/types.ts`:
+
+```ts
+export type AgentName = 'claude' | 'codex' | 'pi';
+
+export interface AgentAdapter {
+  name: AgentName;
+
+  /** Returns whether the CLI is on PATH and which version. */
+  detect(): Promise<{ installed: boolean; version?: string; path?: string }>;
+
+  /**
+   * One-shot non-interactive run.
+   * The host has already copied the wiki dir into `cwd` (a sandbox).
+   * The adapter spawns the CLI, waits for completion, returns stdout/stderr.
+   * The host then diffs sandbox vs original to extract writes.
+   */
+  run(opts: AgentRunOpts): Promise<AgentRunResult>;
+}
+
+export interface AgentRunOpts {
+  prompt: string;                              // user-facing instruction
+  systemPrompt?: string;                       // appended to the agent's system prompt
+  files?: string[];                            // extra files to inject (read-only)
+  cwd: string;                                 // sandbox path
+  allowWrite: boolean;                         // ingest=true, query/lint=false
+  tools?: ('webfetch' | 'qmd' | 'bash')[];     // tool whitelist hint
+  timeoutMs?: number;                          // hard kill after this
+}
+
+export interface AgentRunResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  exitCode: number;
+}
+```
+
+The **host** (not the adapter) handles the diff-vs-original step. That keeps adapters small and means we don't trust any agent's "I wrote these files" report.
+
+---
+
+## 2. Sandbox-copy-and-diff flow
+
+For any operation that may write:
+
+```
+1. host: mkdir ~/.rig/cache/sandbox/<wiki>/<run-id>/
+2. host: copy <wiki-dir> → sandbox  (excluding raw/, purpose.md, schema.md — read-only)
+3. host: write read-only injection files (purpose.md, schema.md, etc.) into sandbox/.rig-readonly/
+4. host: adapter.run({ cwd: sandbox, allowWrite: true, ... })
+5. host: diff sandbox vs <wiki-dir> using `diff -urN`
+6. host: filter diff (reject any patch touching raw/, purpose.md, schema.md)
+7. host: present diff to user (or apply directly in daemon `--apply` mode)
+8. host: rm -rf sandbox
+```
+
+Rationale: all three target agents (Claude, Codex, pi) have different permission models; this flow normalizes them. Even a fully unrestricted agent can't corrupt the real wiki because step 6 throws away forbidden patches.
+
+---
+
+## 3. Claude Code adapter (v1 — only implementation)
+
+`lib/wiki/agent/claude.ts`:
+
+```ts
+spawn('claude', [
+  '-p',                                    // print mode (non-interactive)
+  '--system-prompt', systemPrompt,
+  ...allowedToolsFlags(opts.allowWrite, opts.tools),
+  opts.prompt
+], { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'], timeout: opts.timeoutMs });
+```
+
+Allowed-tools whitelist (passed via `--allowedTools`):
+- `query` / `lint`: `Read, Bash(qmd:*)`
+- `ingest`: `Read, Write, Edit, Bash(qmd:*)`
+- `fetch`: `Read, Write, WebFetch`
+
+System prompt prepended (host always wraps adapter's `systemPrompt`):
+```
+You are the executor for `rig wiki <op>`.
+You MUST follow <wiki>/schema.md exactly.
+You MUST NOT edit raw/, purpose.md, schema.md. Host enforces this and will reject any such patch.
+Output is consumed by a CLI; keep stdout to status updates only. Persist actual content by writing files.
+```
+
+Version check: parse `claude --version`. Require Claude Code >= 2.0 (tools API stable).
+
+Why no direct Anthropic API:
+- Requires an API key + billing setup that not every machine has.
+- Different protocol; we'd reinvent the tool plumbing Claude Code already gives us.
+- Claude Code is already the user's daily driver — its config (`~/.claude/settings.json`) is the source of truth for credentials and MCP servers.
+
+---
+
+## 4. Codex adapter (stub)
+
+Target: OpenAI's `codex` CLI (the `Codex` agent, not the IDE plugin).
+
+Expected invocation (v1 stub, not implemented):
+```ts
+spawn('codex', [
+  'exec', '--no-tui',
+  '--cwd', opts.cwd,
+  // codex permission model TBD — likely needs --readonly when !allowWrite
+  opts.prompt
+], { ... });
+```
+
+Open questions before P3 ships this:
+- Does codex have a `--allowed-tools`-equivalent flag, or only coarse `--readonly` / full access?
+- What does codex print as its "I'm done" signal? Does `--no-tui` exist?
+- Does codex respect external `cwd` or insist on its own workspace?
+
+Until those are answered, the adapter `detect()` returns installed but `run()` throws `not-implemented`.
+
+---
+
+## 5. pi-agent adapter (stub)
+
+Target: Personal-Intelligence-style agent CLI. Exact upstream TBD (Bo to specify).
+
+Expected invocation pattern:
+```ts
+// many pi-agent CLIs take prompt-file to avoid argv-length limits
+const tmpFile = await writeTmp(opts.prompt);
+spawn('pi', ['run', '--prompt-file', tmpFile, '--cwd', opts.cwd], { ... });
+```
+
+Same "open questions" caveat as Codex. Stub `detect()` returns installed when `which pi` succeeds; `run()` throws `not-implemented`.
+
+---
+
+## 6. Choosing the agent
+
+| Operation | Recommended | Why |
+|---|---|---|
+| `ingest` | Claude | long context, stable tool calls, v1 default |
+| `query` | any | whichever is on the box |
+| `lint` | Claude or Codex | both do structured scans well |
+| `fetch` | any with WebFetch | falls back to `curl` + Readability if absent |
+
+Default agent: `~/.rig/config.json5` → `wiki.defaultAgent` (initially `'claude'`).
+Per-invocation override: `--agent <name>` flag.
+
+---
+
+## 7. Detection registry
+
+`lib/wiki/agent/index.ts` exports a single registry:
+
+```ts
+import { ClaudeAdapter } from './claude';
+import { CodexAdapter } from './codex';
+import { PiAdapter } from './pi';
+export const adapters: AgentAdapter[] = [
+  new ClaudeAdapter(),
+  new CodexAdapter(),
+  new PiAdapter(),
+];
+export function getAdapter(name: AgentName) {
+  const a = adapters.find(x => x.name === name);
+  if (!a) throw new Error(`unknown agent: ${name}`);
+  return a;
+}
+```
+
+`rig wiki agent list` iterates `adapters`, calls `detect()`, prints a table.
+`rig wiki agent use <name>` rejects names whose adapter `run()` is `not-implemented`.

package/doc/architecture/fc.md

@@ -0,0 +1,17 @@
+# rig fc — Aliyun Function Compute (placeholder)
+
+> Status: Not started — 2026-05-17. Bo intends to add `rig fc *` subcommands for deploying / managing Aliyun Function Compute services. This file is a placeholder so the architecture tree is complete.
+
+Spec will be written when work begins. Expected shape (subject to revision):
+
+```
+rig fc init                       # write fc.rig.json5 in current project
+rig fc deploy [--env <name>]      # build + upload + invoke deploy
+rig fc invoke <fn> [--params ...]
+rig fc logs <fn> [-f]
+rig fc list
+rig fc rollback <fn> <version>
+```
+
+Auth: `~/.rig/config.json5` `fc:` block (Aliyun AK/SK or RAM credentials).
+Per-project config: `<project>/fc.rig.json5` listing functions, runtime, triggers.

package/doc/architecture/wiki.md

@@ -0,0 +1,278 @@
+# rig wiki — Design
+
+> Status: Draft v0 — 2026-05-17.
+> Source spec: see `harness/llm-wiki/llm-wiki solution.md` §1–§13 in the Maestro repo (it remains the requirements doc; this file is the rig-side implementation contract).
+
+---
+
+## 1. Goal
+
+Bring Karpathy-style LLM Wiki ops to *any* project on this machine, with a single CLI entry point and an optional launchd daemon for periodic ingest/lint. `rig` is the host; per-project wikis live in each project's own tree (default: `harness/llm-wiki/`).
+
+---
+
+## 2. Per-wiki directory layout (the projects rig acts on)
+
+```
+<project>/<wiki>/                 # default: harness/llm-wiki
+├── purpose.md       # scope (human-only, LLM read-only)
+├── schema.md        # structure rules (human-only, LLM read-only)
+├── index.md         # catalog (LLM-maintained)
+├── overview.md      # narrative summary (LLM-maintained)
+├── log.md           # append-only op log (LLM appends)
+├── reviews.md       # uncertain items LLM flagged (LLM appends, human resolves)
+├── raw/             # external immutable source material (LLM read-only)
+└── wiki/            # LLM-authored
+    ├── sources/     # one page per raw/<source>
+    ├── entities/    # people, orgs, products, places
+    ├── concepts/    # abstract ideas
+    ├── synthesis/   # cross-source integration
+    └── queries/     # archived Q&A worth keeping
+```
+
+Filenames are kebab-case; `wiki/**` no dates in names; `raw/**` keeps `YYYY-MM-DD-` prefix.
+
+Frontmatter for every `wiki/**` page:
+```yaml
+---
+type: source | entity | concept | synthesis | query
+sources: [<source-slug>, ...]
+source-sha: <sha>            # source pages only
+source-path: raw/... | <relpath-in-project>
+ingested-at: <ISO>
+last-updated: <ISO>
+---
+```
+
+Hard rules enforced by rig:
+- Never edit `raw/`, `purpose.md`, `schema.md`.
+- `raw/` file sha drift = `RAW DRIFT` error, not a re-ingest trigger.
+- Living-doc paths (`include` glob) sha drift = `MODIFIED`, proposes re-ingest.
+
+---
+
+## 3. Commands
+
+> All commands accept `--json` (machine output) and `--wiki <name>` (target a registered wiki). With neither, the command resolves the wiki by walking up from CWD; failing that, errors out.
+
+### `rig wiki init [<path>]`
+Bootstrap a fresh wiki dir under `<path>` (default CWD):
+- creates `purpose.md`, `schema.md` from templates
+- creates empty `index.md`, `overview.md`, `log.md`, `reviews.md`
+- creates `raw/` and the five `wiki/<subdir>/` dirs (each with `.gitkeep`)
+- does **not** register; for that, run `rig wiki register`
+
+### `rig wiki register [<path>] [--name <n>] [--force]`
+Append/replace an entry in `~/.rig/wiki.config.json5`:
+```json5
+{ name, path, project, include, exclude, schedule, ingestRules }
+```
+- `--name` default: project `package.json` name, fallback to path basename
+- if project has a `package.rig.json5`, also writes a `wiki:` block back to it (bidirectional)
+- duplicates rejected unless `--force`
+
+### `rig wiki unregister <name|path>`
+Remove from `~/.rig/wiki.config.json5`. Disk wiki content untouched.
+
+### `rig wiki list`
+Table of registered wikis with page counts + last scan/ingest/lint times. Banner row: detected agent CLI, qmd status, daemon state.
+
+### `rig wiki scan [--wiki <n> | --all | <path>]`
+Walk `include` globs + `raw/`. Diff file sha vs `state.db.source_sha`. Output four-state report (NEW / MODIFIED / DELETED / RAW DRIFT / UNCHANGED). No agent calls.
+
+### `rig wiki fetch <url> [--wiki <n>]`
+Agent-as-fetcher: verbatim download → `raw/YYYY-MM-DD-<slug>.md` + frontmatter (`source-url`, `fetched-at`, `fetcher`, `content-sha`). Never summarizes — that's `ingest`'s job.
+
+### `rig wiki ingest <path> [--wiki <n>] [--dry-run]`
+Two-step CoT (`analysis` → `generation`) inside an agent sandbox (copy-on-write `~/.rig/cache/sandbox/<wiki>/<run-id>/`):
+1. inject `purpose.md` + `schema.md` + `overview.md` + `index.md` + source → analysis output (entities/concepts/contradictions/reviews)
+2. feed analysis back → agent writes `wiki/sources/<slug>.md` + updates related entity/concept pages + `index.md` + `overview.md` + `log.md` + (if any) `reviews.md`
+3. host diffs sandbox vs original → `--dry-run` prints diff; otherwise prompts to apply
+4. on apply: trigger incremental `qmd embed` (if qmd installed)
+
+### `rig wiki query "..." [--wiki <n>]`
+With qmd: `qmd query --json` → top-k → agent synthesizes answer with `[[wikilink]]` citations.
+Without qmd: inject `purpose.md` + `index.md` + `overview.md` + heuristically-picked pages.
+
+### `rig wiki lint [--wiki <n> | --all]`
+Health check — contradictions, orphans, stale claims, broken `sources[]` refs, reviews.md backlog. Output: `<wiki>/lint-report-YYYY-MM-DD.md` (gitignored by default). Severe findings → non-zero exit.
+
+### `rig wiki index [--wiki <n> | --all]`
+Equivalent to `qmd collection add ... && qmd embed`. If qmd not installed: warn and no-op (exit 0; qmd is optional).
+
+### `rig wiki install-skill / uninstall-skill`
+Symlink rig's bundled Claude skill (`.claude/skills/rig-wiki/`) into `~/.claude/skills/rig-wiki/`. Lets every machine that has `rig` installed get the slash command without manual copy.
+
+### `rig wiki agent list | use <name>`
+- `list`: prints which agent CLIs are on PATH (claude/codex/pi), their versions, and which is default.
+- `use <name>`: writes `wiki.defaultAgent` in `~/.rig/config.json5`. v1 only accepts `claude`.
+
+### `rig wiki daemon start | stop | status | logs [-f] | install | uninstall`
+See §5.
+
+---
+
+## 4. Config files
+
+### `~/.rig/config.json5`
+```json5
+{
+  wiki: {
+    defaultAgent: 'claude',
+    qmd: { enabled: 'auto' },      // 'auto' | 'on' | 'off'
+    logRotateMB: 50
+  }
+}
+```
+
+### `~/.rig/wiki.config.json5`
+```json5
+{
+  defaults: {
+    schedule: { scan: '0 */6 * * *', lint: '0 3 * * *', ingest: null }
+  },
+  wikis: [
+    {
+      name: 'maestro',
+      path: '/abs/path/.../harness/llm-wiki',
+      project: '/abs/path/.../maestro',
+      include: ['harness/dev/**', 'harness/projects/**'],
+      exclude: ['harness/llm-wiki/**'],
+      schedule: { scan: '0 */6 * * *', lint: '0 3 * * *' },
+      ingestRules: [
+        { match: 'raw/**/*.md', mode: 'auto-on-new' },
+        { match: 'harness/dev/**/*.md', mode: 'propose-only' }
+      ]
+    }
+  ]
+}
+```
+
+### Project `package.rig.json5` (`wiki` block)
+```json5
+{
+  wiki: {
+    name: 'maestro',
+    path: 'harness/llm-wiki',
+    include: ['harness/dev/**'],
+    exclude: ['harness/llm-wiki/**']
+  }
+}
+```
+
+Merge order: built-in defaults < `~/.rig/config.json5` < `~/.rig/wiki.config.json5` < project `package.rig.json5` < CLI flag.
+
+---
+
+## 5. Daemon (macOS launchd)
+
+`rig wiki daemon install` writes `~/Library/LaunchAgents/ai.flashhand.rig.wiki.plist` and bootstraps via `launchctl bootstrap gui/<uid> <plist>`.
+
+Plist (template):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>ai.flashhand.rig.wiki</string>
+  <key>ProgramArguments</key><array>
+    <string>/usr/local/bin/node</string>
+    <string>{{RIG_BUILT_INDEX}}</string>
+    <string>wiki</string><string>daemon</string><string>runner</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>{{HOME}}/.rig/logs/wiki-daemon.log</string>
+  <key>StandardErrorPath</key><string>{{HOME}}/.rig/logs/wiki-daemon.log</string>
+</dict></plist>
+```
+
+Runner loop:
+- read `~/.rig/wiki.config.json5`, register `cron` jobs per wiki for `schedule.scan` / `schedule.lint`
+- on tick: run subcommand internally (no fork), write JSONL to `~/.rig/logs/wikis/<wiki>/<op>-YYYY-MM-DD.log`
+- `ingestRules.mode === 'auto-on-new'` matches on the latest scan → `ingest --apply` (only when sandbox-diff is sub-policy)
+- `propose-only` matches → write `<wiki>/proposals/<source>.diff` for human review
+- never retry; never backfill missed runs
+
+Control commands:
+- `daemon start/stop`: `launchctl bootstrap` / `bootout`
+- `daemon status`: parse `launchctl print gui/<uid>/ai.flashhand.rig.wiki`
+- `daemon logs [-f]`: tail `~/.rig/logs/wiki-daemon.log`
+- `daemon install/uninstall`: write/remove plist
+
+---
+
+## 6. Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 10 | scan found RAW DRIFT |
+| 11 | lint found severe items |
+| 20 | agent CLI missing or version too low |
+| 21 | qmd required (only with `--require-qmd`) but absent |
+| 30 | config file corrupt |
+| 31 | wiki lock contention (another rig process holds the lock) |
+| 32 | not on macOS |
+| 1 | other error |
+
+`--json` output shape: `{ ok: boolean, code: number, data?: any, error?: { message, hint } }`.
+
+---
+
+## 7. SQLite schema (`~/.rig/state.db`)
+
+Single file via `better-sqlite3@12.10.0`. WAL mode. Migrations are idempotent on every open.
+
+```sql
+CREATE TABLE IF NOT EXISTS source_sha (
+  wiki TEXT NOT NULL, path TEXT NOT NULL,
+  sha TEXT NOT NULL, mtime INTEGER NOT NULL,
+  PRIMARY KEY (wiki, path)
+);
+CREATE TABLE IF NOT EXISTS last_run (
+  wiki TEXT NOT NULL, op TEXT NOT NULL,
+  ts INTEGER NOT NULL, exit_code INTEGER NOT NULL,
+  PRIMARY KEY (wiki, op)
+);
+CREATE TABLE IF NOT EXISTS ingest_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  wiki TEXT NOT NULL, source_path TEXT NOT NULL,
+  ts INTEGER NOT NULL, diff_hash TEXT NOT NULL,
+  applied INTEGER NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS pages_fts5 USING fts5(
+  wiki, slug, body, tokenize='unicode61 remove_diacritics 2'
+);
+```
+
+Cross-process locks are **not** SQLite locks — they're `fcntl` flocks on `~/.rig/locks/<wiki>.lock`. Failure to acquire = exit `31`.
+
+---
+
+## 8. qmd integration
+
+Auto-detect via `which qmd` at startup.
+
+With qmd:
+- `query`: `qmd query --json "..."` (auto-runs `qmd mcp` daemon)
+- `ingest` end-step: `qmd embed --collection <wiki>` (incremental)
+- `lint`: walk via `qmd ls --collection <wiki>`
+
+Without qmd:
+- `query` falls back to feeding `index.md + overview.md + heuristic` to the agent
+- `index` is a no-op + warn
+- `pages_fts5` (in `state.db`) is populated on every ingest as a degraded local search backend; used by qmd-less `query`
+
+---
+
+## 9. Agent integration
+
+See `agents.md`. Single `AgentAdapter` interface; v1 implements Claude Code only. All adapters run inside a sandbox-copy of the wiki dir, then the host diffs the sandbox against the original to detect/apply writes.
+
+---
+
+## 10. Built-in Claude skill (`.claude/skills/rig-wiki/`)
+
+Ships inside the rig npm tarball (`package.json` `files` includes `.claude/skills/**`). User runs `rig wiki install-skill` once per machine — symlinks `<rigjs-install>/.claude/skills/rig-wiki` to `~/.claude/skills/rig-wiki`. Claude Code picks it up next session.
+
+The skill itself is a thin wrapper: its instructions tell Claude when to invoke which `rig wiki *` command. It does not duplicate the wiki logic.

package/lib/crew/ask.ts

@@ -0,0 +1,24 @@
+import fs from 'fs';
+import print from '../print';
+import { requireCrew } from './config';
+import { appendLog, rootPath } from './vault';
+import crewBoard from './board';
+
+interface AskOpts { crew?: string; }
+
+export default function crewAsk(messageParts: string[] | string | undefined, opts: AskOpts): void {
+  const crew = requireCrew(opts.crew);
+  const message = Array.isArray(messageParts) ? messageParts.join(' ') : (messageParts || '');
+  if (!message.trim()) {
+    print.info('no message supplied; running a lightweight Lead tick.');
+    print.info('MVP Lead tick only refreshes status. LLM delegation will be added in a later phase.');
+    crewBoard({ crew: crew.name });
+    return;
+  }
+  const file = rootPath(crew, 'Current-Goal.md');
+  fs.appendFileSync(file, `\n- ${new Date().toISOString()} ${message.trim()}\n`, 'utf8');
+  appendLog(crew, `Lead input: ${message.trim()}`);
+  print.succeed(`added goal input to ${file}`);
+  crewBoard({ crew: crew.name });
+}
+