feat: recursive documentation for monorepos (#162)

.claude/settings.local.json.20260714-bak

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8788"
+  }
+}

.pi/voice-prompt-cache.json

@@ -0,0 +1,10 @@
+{
+  "contextHash": "2787abd91c056212",
+  "prompt": "I'm working on openwiki using TypeScript and JavaScript. We wire up langchain, langgraph-checkpoint-sqlite, and deepagents to orchestrate agents. The core stack pulls in anthropic, openai, openrouter, google, google-auth-library, vertex-sdk, and client-bedrock-runtime from aws for the models. I validate schemas with zod, and zod keeps our JSON payloads clean over HTTP. We parse schedules with cron-parser and cronstrue, then render results in ink and react, plus marked and tavily for content. For testing I run vitest with coverage-v8, and vitest reports to stdout and stderr. I lint using eslint, typescript-eslint, and prettier, and run tsx scripts from the CLI. Our npm commands cover build, clean, dev, start, format, lint, and typecheck, wired through GitHub Actions. I check the API, the URL, and SQL queries, then open a PR in Git after every commit.",
+  "tokenCount": 203,
+  "usedLlm": true,
+  "signalCount": 57,
+  "projectName": "openwiki",
+  "summary": "Languages: JavaScript, TypeScript │ Deps: anthropic, aws, client-bedrock-runtime, core, coverage-v8, cron-parser, cronstrue, deepagents, eslint, google +19 more │ Tools: ESLint, GitHub Actions, TypeScript │ Custom terms: client-bedrock-runtime, coverage-v8, cron-parser, google-auth-library, langgraph-checkpoint-sqlite, typescript-eslint, vertex-sdk, vitest, zod │ Prompt: LLM-generated",
+  "generatedAt": "2026-07-16T14:25:12.481Z"
+}

.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

.serena/project.yml

@@ -0,0 +1,159 @@
+# the name by which the project can be referenced within Serena/when chatting with the LLM.
+project_name: "openwiki"
+
+# list of languages for which language servers are started (LSP backend only); choose from:
+#   ada                 al                  angular             ansible             bash
+#   bsl                 clojure             cpp                 cpp_ccls            crystal
+#   csharp              csharp_omnisharp    cue                 dart                elixir
+#   elm                 erlang              fortran             fsharp              gdscript
+#   go                  groovy              haskell             haxe                hlsl
+#   html                java                json                julia               kotlin
+#   latex               lean4               lua                 luau                markdown
+#   matlab              msl                 nix                 ocaml               pascal
+#   perl                php                 php_phpactor        php_phpantom        powershell
+#   python              python_jedi         python_pyrefly      python_ty           r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   scss                solidity            svelte              swift               systemverilog
+#   terraform           toml                typescript          typescript_vts      vue
+#   yaml                zig
+#   (This list may be outdated; generated with scripts/print_language_list.py;
+#   For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py)
+# For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- typescript
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# optional shell command to run before the language backend (LSP or JetBrains) is initialised.
+# the command runs in the project root directory and is only executed if the project is trusted
+# (see trusted_project_path_patterns in the global configuration).
+# serena waits for the command to exit: a non-zero exit code is logged as an error but does not
+# abort activation. a per-project timeout (activation_command_timeout, default 180s) is the safety
+# backstop for non-terminating commands; on expiry the process is killed and activation continues.
+# example: activation_command: "npx nx run-many -t build"
+activation_command:
+
+# maximum time in seconds to wait for activation_command to complete before killing it (default 180s).
+# must be a positive number.
+activation_command_timeout: 180
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# The settings are considered only if the project is trusted (see global configuration to define trusted projects).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings
+ls_specific_settings: {}
+
+# list of workspace folder paths (LSP backend only).
+# These folders will be used to build up Serena's symbol index.
+# Paths must be within the project root and should thus be relative to the project root.
+# Furthermore, the paths should not be filtered by ignore settings.
+# Default setting: The entire project root folder (".") is considered.
+# In (large) monorepos, this can be used to index only subfolders of the project root, e.g.
+#   ls_workspace_folders:
+#     - "./subproject1"
+#     - "./subproject2"
+ls_workspace_folders: ["."]
+
+# list of additional workspace folder paths for cross-package reference support.
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries, but these folders are not indexed by Serena,
+# i.e. the respective symbols will not be found using Serena's symbol search tools.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+ls_additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

README.md

@@ -179,6 +179,89 @@ repository wiki: OpenWiki reads it for scope and priorities, but it is not
 generated documentation and is not rewritten during normal init, update, or chat
 runs unless you explicitly ask to change the brief.
 
+## Monorepos (recursive documentation)
+
+Large monorepos are hard to capture in a single wiki. OpenWiki can instead
+document each subproject in its own nested `openwiki/` sub-wiki, while the
+repository-root wiki links down to them and covers only cross-cutting concerns:
+
+```sh
+openwiki code --update --recursive
+```
+
+Subprojects are read from an `openwiki/workspaces.json` manifest at the
+repository root:
+
+```json
+{
+  "version": 1,
+  "workspaces": [{ "path": "packages/api" }, { "path": "packages/web" }],
+  "overrides": {
+    "packages/api": { "name": "API", "goal": "Optional per-subproject brief." },
+    "vendor/thirdparty": { "exclude": true },
+    "tools/custom-grouping": { "include": true, "name": "Tools" }
+  },
+  "root": { "goal": "Optional brief for the aggregating root wiki." }
+}
+```
+
+The manifest has two parts. The `workspaces` list is **managed** — it is
+regenerated from detection on every recursive run, sorted and path-only. All
+hand-authored customization lives in the `overrides` map, keyed by
+repo-relative path, and is never auto-clobbered:
+
+- `goal` / `name`: a per-subproject wiki brief and display name.
+- `exclude: true`: detection still lists the path (so it is not re-discovered as
+  new noise), but no sub-wiki is generated for it.
+- `include: true`: force-add a path detection cannot find (e.g. a custom
+  grouping). This flag is also what distinguishes a deliberate manual addition
+  from an override left behind by a deleted project.
+
+The legacy flat shape (`goal`/`name` written directly on `workspaces` entries)
+is still read: those fields are migrated into `overrides` in memory, and the
+next write emits the current shape without losing them.
+
+- **Self-maintaining discovery.** Detection re-runs on **every** recursive run
+  (it is deterministic and fast) and is merged with the existing manifest, so
+  the manifest stays current as the repo evolves: newly added projects appear
+  automatically, deleted ones drop out, and your `overrides` survive
+  regeneration. The merged manifest is written back **only when it changed** — a
+  no-op run leaves `openwiki/workspaces.json` byte-for-byte unchanged, so
+  scheduled CI runs produce no spurious manifest diff.
+- **Manual entries are preserved, stale ones are pruned.** On the first
+  self-maintaining run, any path you hand-listed that detection cannot surface
+  is kept **if its directory still exists** — it is promoted to an explicit
+  `"include": true` override (carrying any goal/name) so it is stable and
+  self-documenting. A referenced path whose directory is gone is treated as a
+  removed project and dropped; if it carried a hand-authored override, a warning
+  names the pruned path (a plain managed entry is removed quietly). An
+  `"include"` path that would overlap a detected workspace (for example an
+  ancestor of a detected leaf) is ignored with a warning rather than persisted,
+  so a stray include can never wedge future runs.
+- **Activation.** If `openwiki/workspaces.json` is present, recursive mode is
+  enabled automatically. Passing `--recursive` with no manifest triggers
+  auto-detection of common workspace layouts (pnpm/npm/yarn workspaces, Cargo,
+  Go, uv, Gradle, Maven, .NET solutions, Bazel), writes a `workspaces.json` for
+  you to review, and proceeds. Pass `--recursive=false` to force a single-repo
+  run even when a manifest exists.
+- **Layout.** Each subproject's docs live at `<subproject>/openwiki/`. The root
+  wiki gets a generated `openwiki/workspaces.md` index linking to every
+  sub-wiki; do not hand-edit it.
+- **Incremental updates.** Each subproject is evaluated independently: on
+  `--update`, a subproject's sub-wiki regenerates only when files _within that
+  subproject's own subtree_ have changed since it was last documented (tracked in
+  its own `openwiki/.last-update.json`). Unchanged subprojects are skipped
+  without a model call, so scheduled refreshes stay cheap. The root wiki
+  regenerates on every run.
+- **Known limitation — no dependency cascade.** Updates do not propagate across
+  subprojects. If a shared subproject (for example a common kernel or contracts
+  package) changes, only _that_ sub-wiki and the root wiki are refreshed — the
+  sibling subprojects that depend on it are **not** automatically regenerated,
+  even though their documented context may reference the changed code. Until
+  dependency-aware invalidation exists, force a full refresh after a significant
+  shared-code change by removing the relevant `openwiki/.last-update.json` files
+  (or running each affected subproject explicitly).
+
 On the first interactive run, OpenWiki will have you configure your inference provider, API key, and LLM. You will also be able to set a LangSmith API key to trace your OpenWiki runs to a LangSmith tracing project named "openwiki" (optional).
 
 These configuration options and secrets will be saved to `~/.openwiki/.env` on your local machine.