(MOT-4292) feat(openwiki): add openwiki worker

.github/workflows/create-tag.yml

@@ -38,6 +38,7 @@ on:
           - memory
           - memory-consolidate
           - opencode
+          - openwiki
           - pi
           - provider-anthropic
           - provider-claude-code

.github/workflows/release.yml

@@ -32,6 +32,7 @@ on:
       - 'memory/v*'
       - 'memory-consolidate/v*'
       - 'opencode/v*'
+      - 'openwiki/v*'
       - 'pi/v*'
       - 'provider-anthropic/v*'
       - 'provider-claude-code/v*'

README.md

@@ -77,6 +77,7 @@ npx skills add iii-hq/iii --all
 | [`browser`](browser/) | Rust | Interactive Chromium sessions over CDP with console/network capture, a11y-tree snapshots with actionable refs, viewable screenshots, and DevTools element picking for the console UI. |
 | [`worktree`](worktree/) | Rust | Git worktree lifecycle for parallel agents — `worktree::*` mint, claim, and track isolated worktrees per repo, emit six lifecycle trigger types, and land branches back through a per-repo FIFO queue (rebase, test gate, ff-only merge). |
 | [`github`](github/) | Rust | GitHub CLI (`gh`) as an iii worker — typed `github::pr/issue/repo/run/workflow/release/search::*` functions plus `github::exec` argv passthrough and `github::api` for any GitHub REST endpoint. |
+| [`openwiki`](openwiki/) | Node | Source-grounded markdown wiki for any git repository — a lead agent plans the index and writer sub-agents store cited pages via `openwiki::write-page`, with router and heuristic fallback tiers, incremental refresh from git diffs on a per-wiki cron schedule, and a browser UI + JSON API under `/openwiki`. |
 
 ## SDK
 

iii-permissions.yaml

@@ -167,6 +167,14 @@ rules:
   # github: internal hot-reload hook — invoked only by the engine's
   # configuration:updated trigger dispatch, never agent-callable.
   - '!github::on-config-change'
+  # openwiki: internal trigger targets. cron::refresh-due is the per-wiki cron
+  # target; on-turn-started/completed are harness trigger-bridge targets whose
+  # direct call could forge generation progress. The hot-reload hook follows
+  # the same pattern as the other on-config-change denies.
+  - '!openwiki::cron::refresh-due'
+  - '!openwiki::on-turn-started'
+  - '!openwiki::on-turn-completed'
+  - '!openwiki::on-config-change'
 
   # Read-only / introspection (extend below for your tools).
   - state::get

openwiki/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.DS_Store

openwiki/README.md

@@ -0,0 +1,118 @@
+# openwiki
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/iii-hq/workers/main/openwiki/assets/openwiki-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/iii-hq/workers/main/openwiki/assets/openwiki-light.png">
+    <img alt="OpenWiki browser UI" src="https://raw.githubusercontent.com/iii-hq/workers/main/openwiki/assets/openwiki-light.png" width="100%">
+  </picture>
+</p>
+
+Builds and maintains a source-grounded, interlinked markdown wiki for a code
+repository, and serves a browser UI to read and search it. Point it at a git
+repo: an agent reads the source, plans a hierarchical index, writes one cited
+page per topic, and keeps the wiki current from git diffs on a per-wiki
+schedule. Pages persist in iii-state; the engine serves the UI and JSON API
+under `/openwiki`.
+
+## Install
+
+```bash
+iii worker add openwiki
+```
+
+This pulls `state`, `cron`, and `llm-router` transitively. Add a model provider
+through the console's onboarding (anthropic, openai, codex, ...) and pages are
+model-written; the provider credential lives in the `llm-router` config, never
+in this worker.
+
+For the best tier, agent-orchestrated pages written by one sub-agent per page
+with line citations, add the harness stack as well:
+
+```bash
+iii worker add harness
+```
+
+`harness` transitively pulls `session-manager`, `context-manager`, `shell`
+(jailed git for clone/diff), and the model providers. openwiki degrades
+gracefully when a worker is absent:
+
+| Present | Pages are |
+|---|---|
+| `harness` + a configured provider | agent-orchestrated, line-cited (best) |
+| `llm-router` only | model-written from pre-selected files |
+| neither | heuristic, built from file headers, always works |
+
+## Quickstart
+
+Open the browser UI on the engine's HTTP port:
+
+```text
+http://localhost:3111/openwiki
+```
+
+Or drive it from the CLI:
+
+```bash
+iii trigger openwiki::generate --json '{"repo_url":"https://github.com/owner/repo"}'
+# -> { "wiki_id": "<wiki_id>", "status": "started" }
+
+iii trigger openwiki::status --json '{"id":"<wiki_id>"}'    # poll until phase = ready
+iii trigger openwiki::page   --json '{"id":"<wiki_id>","slug":"overview"}'
+iii trigger openwiki::search --json '{"id":"<wiki_id>","q":"config"}'
+```
+
+`openwiki::refresh { id }` is incremental: it pulls the clone, diffs against
+the recorded commit, and regenerates only the pages whose source changed.
+`openwiki::set-schedule { id, schedule }` puts that refresh on a per-wiki
+cadence (`off` | `3h` | `6h` | `12h` | `daily` | `weekly` | a cron string); a
+content-hash gate keeps an unchanged repo from churning the wiki.
+
+The full function catalogue (generation, scoped source readers for writer
+sub-agents, cited Q&A via `openwiki::ask`, Mermaid diagrams, `AGENTS.md`
+export, lint) is one `iii worker info openwiki` away. HTTP triggers mirror the
+read/generate functions under `/openwiki/api/*`, generation progress streams
+live over SSE, and page citations deep-link to source at the pinned commit.
+
+openwiki also registers `openwiki::read-wiki-structure`,
+`openwiki::read-wiki-contents`, and `openwiki::ask-question`, which the
+[mcp](https://github.com/iii-hq/workers/tree/main/mcp) worker advertises to any
+MCP client:
+
+```bash
+iii worker add mcp
+```
+
+## How generation works
+
+1. Clone the repo (through the `shell` worker, with a local `git` fallback),
+   inventory its files, and record the commit so citations deep-link to exact
+   source.
+2. A lead agent explores the clone through openwiki's scoped readers
+   (`openwiki::src::read` / `src::list` / `src::grep`) and plans a
+   reading-ordered index. The model decides how many pages the repo needs and
+   follows the repo's own docs index (`llms.txt`, a `docs/` tree) when present.
+3. The lead spawns one writer sub-agent per page in parallel. Each writer reads
+   its focused files and stores its finished page with `openwiki::write-page`;
+   openwiki turns citations into pinned-commit source links and rejects a page
+   that comes back too thin.
+4. Pages stream into the UI as each writer lands; the lead submits only the
+   table of contents.
+
+## Configuration
+
+- **Model**: pick one in the browser UI's generate form (populated from the
+  router's live catalog, grouped by provider), pass `model` to
+  `openwiki::generate`, or set `OPENWIKI_MODEL`. Any model the router
+  advertises works. Default `claude-haiku-4-5-20251001`.
+- **`refresh_default`**: the auto-refresh cadence new wikis start with (`off`
+  by default; each wiki overrides it in the UI). Editable in the console like
+  the other openwiki config, or seed it with `OPENWIKI_REFRESH_DEFAULT`.
+- **`OPENWIKI_DATA`**: wiki store and clone directory (default
+  `/tmp/openwiki-data`). Must resolve inside the shell worker's
+  `fs.host_roots` when git runs through `shell`.
+- **`OPENWIKI_MAX_PARALLEL`**: concurrent page writers (default `3`).
+
+## License
+
+Apache-2.0

openwiki/biome.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "root": false,
+  "vcs": { "enabled": false, "clientKind": "git" },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["**", "!!**/dist", "!!**/node_modules"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "off"
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "warn",
+        "noAssignInExpressions": "off"
+      },
+      "style": {
+        "useNodejsImportProtocol": "error"
+      },
+      "complexity": {
+        "noForEach": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "trailingCommas": "all",
+      "semicolons": "always"
+    }
+  }
+}

openwiki/iii.worker.yaml

@@ -0,0 +1,18 @@
+iii: v1
+name: openwiki
+language: javascript
+deploy: bundle
+manifest: package.json
+tags: [wiki, documentation, docs, markdown, knowledge-base, repo]
+description: Source-grounded markdown wiki for any git repository — openwiki::* functions generate, search, and incrementally refresh categorized pages with pinned-commit line citations, and the engine serves a browser UI + JSON API under /openwiki.
+
+runtime:
+  kind: javascript
+
+scripts:
+  start: node ./index.mjs
+
+dependencies:
+  state: "^0.21.2"
+  cron: "^0.21.0"
+  llm-router: "^1.0.0"

openwiki/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "openwiki",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Source-grounded markdown wiki for code repositories, as an iii worker: generated and refreshed from the repo itself, with a browser UI and JSON API under /openwiki.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.18.2",
+  "scripts": {
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "check": "node --check src/index.mjs",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "node --test",
+    "start": "node src/index.mjs"
+  },
+  "dependencies": {
+    "iii-sdk": "^0.21.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.10",
+    "esbuild": "^0.25.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}