@holt-os/holt 0.9.0 → 0.11.0

package/README.md

@@ -149,6 +149,22 @@ A brain can also be a direct provider connection: no CLI install, your own key.
 
 Options: `--out <path>` to write elsewhere, `--no-open` to skip the browser. When a wiki exists (see below), the graph auto-includes wiki pages as green nodes wired by their `[[links]]`; force it on or off with `--wiki` / `--no-wiki`. This is the graph as a view over your wiki.
 
+### Richer graph: code, docs, and communities
+
+Plain `holt graph` is unchanged: it draws this folder's memory (plus the wiki when one exists). To also see the folder's *own source and docs* as a graph, opt in with flags:
+
+- `holt graph --code` walks the folder and adds a node per source file (orange), with dependency edges from the imports it can resolve.
+- `holt graph --docs` adds a node per doc (blue: `.md` / `.mdx` / `.txt` / `.rst`), with edges from Markdown links and `[[wikilinks]]` between them.
+- `holt graph --all` does both. All three still render the memory + wiki graph too, so code, docs, and memory sit in one picture.
+
+**What gets ingested.** The walk skips `node_modules`, `.git`, `.holt`, `dist`, `build`, `.next`, `coverage`, other build/vendor dirs, and any dotfolder. It caps out at 2000 files and 400KB per file for safety, and logs what it skipped. Code files (`js`, `ts`, `jsx`, `tsx`, `mjs`, `cjs`, `py`, `go`, `rb`, `rs`, `java`, and more) become file nodes. Dependency edges are best-effort per language: for JS/TS it reads `import ... from`, `export ... from`, `require()`, and dynamic `import()`, resolving only *relative* specifiers (`./`, `../`) to files in the set (trying common extensions and `index.*`); bare/package imports (`react`, `node:fs`) are intentionally dropped. For Python it maps `import x` and `from x import ...` to local module files where they resolve. Unresolved imports are silently dropped, never fatal.
+
+**Communities.** Once code or docs are ingested, Holt runs **label propagation** (a deterministic, zero-dependency community-detection algorithm) over the whole graph and tints each node's ring by its community, so tightly-coupled files cluster visibly. (Label propagation was chosen over Louvain because it is near-linear, trivially deterministic in stable node order, and keeps the code tiny.)
+
+### God-node report: `holt graph report`
+
+`holt graph report` ingests this folder's code and docs, detects communities, and writes a `GRAPH_REPORT.md` (use `--out <path>` to write elsewhere). The report summarizes node / edge / community counts, lists the **god nodes** (highest-degree files: your core abstractions) with their community, and gives a per-community summary (size + representative files). It is safe on an empty folder (it says so, no crash). This is the graphify-grade view of a codebase, generated natively in TypeScript with zero dependencies.
+
 ## Knowledge wiki: `holt wiki`
 
 Memory has three layers, each derived from the one below it:
@@ -160,17 +176,22 @@ Memory has three layers, each derived from the one below it:
 The core rule: **wiki pages are derived and regenerable, never a sole source of truth.** Turns and facts stay authoritative. Every page records which fact ids it drew from (frontmatter `sources:`), so `holt wiki rebuild` can regenerate the whole wiki from scratch. A bad synthesis is therefore never lossy: rebuild recovers it. Pages are plain Obsidian-compatible Markdown with `[[wikilinks]]` and an `index.md`, so you can point Obsidian at `.holt/wiki` as a vault, or edit pages by hand (a rebuild will overwrite hand-edits, so keep the folder under git if you edit).
 
 ```bash
-holt wiki                     # status: maintainer, model, page count, last sync, RAM hint
+holt wiki                     # status: maintainer, model, auto-sync, page count, last sync, RAM hint
 holt wiki sync                # fold new facts into pages (route + merge)
+holt wiki auto [on|off]       # auto-sync the wiki when a session ends (wiki.autoSync)
 holt wiki rebuild             # wipe and regenerate every page from facts (asks first)
-holt wiki lint                # audit pages for contradictions, duplicates, gaps
+holt wiki lint [--fix]        # audit for contradictions, duplicates, gaps; --fix applies the fixes
 holt wiki list                # list pages (title, updated, size)
 holt wiki show <page>         # print one page
 holt wiki open                # open the wiki in your default app (Obsidian reads it natively)
 holt wiki setup               # recommend a local model for this machine's RAM
 ```
 
-**How sync works.** `holt wiki sync` gathers facts added since the last sync (a marker in `.holt/wiki/.state.json`), embeds each one locally, and routes it to the nearest existing page by cosine similarity. Related facts land on the same page; a fact that matches nothing new starts a fresh page. Facts are grouped by target page and the maintainer is called **once per changed page** (not once per fact), so it only rewrites the few pages that actually changed. Routing is always local and free, which is what keeps the maintainer's cost minimal. `holt wiki rebuild` folds every fact from scratch; `holt wiki lint` reports issues but does not rewrite (propose-only).
+**How sync works.** `holt wiki sync` gathers facts added since the last sync (a marker in `.holt/wiki/.state.json`), embeds each one locally, and routes it to the nearest existing page by cosine similarity. Related facts land on the same page; a fact that matches nothing new starts a fresh page. Facts are grouped by target page and the maintainer is called **once per changed page** (not once per fact), so it only rewrites the few pages that actually changed. Routing is always local and free, which is what keeps the maintainer's cost minimal. `holt wiki rebuild` folds every fact from scratch.
+
+**Self-maintaining (auto-sync).** Turn on `holt wiki auto on` (persists `wiki.autoSync: true` for the folder) and the wiki keeps itself current with no manual command. It syncs **after fact distillation** at the end of a `holt chat` session, and ambiently when the Claude Code **Stop** hook fires (`holt hook capture`), so newly captured facts fold straight into pages. Auto-sync is silent, best-effort, and never blocks exit: it reuses the exact same sync engine as `holt wiki sync`, so there is no behavior drift. Left off (the default), nothing changes and you sync by hand. `holt wiki auto` with no argument shows the current state; `holt wiki status` surfaces it too.
+
+**Lint that can fix.** `holt wiki lint` audits pages for contradictions, duplicates, and gaps and prints a report only (files untouched). Add `--fix` and Holt asks the maintainer to return corrected page bodies and **applies them**, rewriting the affected pages (provenance/`sources` is preserved). Because pages are derived and regenerable, applying is safe: a bad `--fix` is fully recoverable with `holt wiki rebuild`, and the command prints a git/backup nudge before writing. Only pages that actually change are rewritten.
 
 **Who maintains it (the key knob).** Synthesis is a reasoning task, and you choose who does it with `wiki.maintainer`:
 
@@ -185,18 +206,64 @@ Wiki pages also participate in recall: each page is embedded and indexed like a
 
 A skill is a folder with a `SKILL.md`: YAML frontmatter (`name`, `description`) plus Markdown instructions. Same convention as agentskills.io and Claude Code, so skills are portable both ways. Skills are prompt text only; Holt never executes their contents.
 
-Holt looks in two places (workspace wins on a name clash): `./.holt/skills/` for this folder, `~/.holt/skills/` for every folder (`--global`).
+Holt looks in three places, in precedence order (workspace shadows global shadows builtin on a name clash): `./.holt/skills/` for this folder, `~/.holt/skills/` for every folder (`--global`), and a read-only set of **built-in skills** that ship inside Holt and are available in every folder out of the box.
 
 ```
-holt skill list                       list installed skills
-holt skill show <name>                print a skill
-holt skill create <name> [--global]   scaffold a new skill
-holt skill add <src> [--global]       install from a git URL or local path
-holt skill remove <name>              delete a skill
+holt skill list                        list installed skills
+holt skill show <name>                 print a skill
+holt skill create <name> [--global]    scaffold a new skill
+holt skill search <query>              find skills in the registry
+holt skill add <src|name> [--global]   install from a git URL, path, or registry name
+holt skill publish [<name>]            prepare a skill for the registry (prints a PR entry)
+holt skill remove <name>               delete a skill
 ```
 
 In chat, run one with `/skill <name> [your input]`. Available skills are also listed to the brain each turn, so it knows what it can be asked to follow.
 
+### Built-in skills
+
+Holt ships with a small, curated set of general-purpose skills, available in every folder with no setup. They are read-only (`holt skill remove` will not delete them); to change one, create a workspace or global skill with the same name and it takes over.
+
+- **summarize**: condense a document, article, transcript, or pasted text into its key points.
+- **explain**: explain a concept, error message, or piece of jargon in plain language.
+- **action-items**: pull decisions, tasks, and owners out of messy notes or a meeting transcript.
+- **brief**: a short briefing on the state of the current folder, using recalled memory plus your input.
+- **code-review**: review a file or a diff for correctness bugs, edge cases, and simplifications.
+- **explain-code**: walk through what a file or function does and how it fits into the wider system.
+- **commit**: draft a clear commit message from staged changes or a described change.
+- **plan**: break a goal into a concrete, ordered set of steps.
+- **rewrite**: tighten and clarify a piece of text without changing its meaning.
+- **decide**: weigh a decision and give a clear recommendation.
+
+### Skill registry (`holt skill search` / `publish`)
+
+Beyond pasting URLs, Holt can discover and share skills through a **git-based registry**: a single JSON index living in a git repo. No server, no infra, in keeping with the rest of Holt.
+
+The index is a JSON document:
+
+```json
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "hello-registry",
+      "description": "A tiny demo skill.",
+      "source": "https://github.com/you/hello-registry.git",
+      "author": "you",
+      "tags": ["demo"]
+    }
+  ]
+}
+```
+
+`source` is anything `holt skill add` already accepts: a git URL (its `SKILL.md` may sit in one subfolder) or a local path. `tags` is optional. Only `name` and `source` are required per entry; malformed rows are skipped rather than failing the whole index.
+
+- **Find:** `holt skill search <query>` fetches the index and lists skills whose name, description, or tags match (case-insensitive substring, name matches first). An empty query lists everything. It prints name, author, description, and source.
+- **Install by name:** `holt skill add <name>` resolves the name in the registry to its `source`, then installs through the exact same clone/copy path as `holt skill add <url|path>`. A git URL or an existing local path is still installed directly, unchanged.
+- **Publish (zero-infra):** `holt skill publish [<name>]` validates a skill's `SKILL.md` (needs a `name` and `description`) and prints the exact JSON entry plus instructions to open a PR against the community registry repo. Holt never pushes anywhere; you add the entry via a pull request. With no name, it publishes the `SKILL.md` in the current directory.
+
+The default index is the community registry (`https://raw.githubusercontent.com/holt-os/registry/main/registry.json`). Override it with `HOLT_REGISTRY_URL` (a URL, a `file://` URL, or a plain path) to point at your own index or a local file. The fetched index is cached at `~/.holt/registry-cache.json` for one hour; `--refresh` forces a re-fetch. If no registry is reachable (for example, the community index is not live yet), search and install-by-name fail cleanly with a clear message rather than crashing.
+
 ## Use Holt from your other tools (MCP)
 
 Holt can run as an [MCP](https://modelcontextprotocol.io) server, so Claude Code, Cursor, and Codex can recall and remember from Holt's memory for the folder without leaving those tools.
@@ -402,11 +469,13 @@ holt doctor          check this machine and recommend how best to run Holt here
 holt voice           teach Holt your writing voice: add <file> | show | edit | clear
 holt write <what>    draft content in your voice with anti-AI checks (--type, --out, --fast)
 holt graph           see your memory as an interactive knowledge graph
+                     (--code / --docs / --all to ingest this folder's code + docs;
+                      "holt graph report" writes GRAPH_REPORT.md)
 holt mcp             run an MCP server so other tools use this folder's memory (holt mcp setup)
 holt hook            ambient memory for Claude Code: install | remove | status
 holt skill           manage skills: list | show | create | add | remove
 holt memory          inspect memory: holt memory [search <query> | facts | embed | clear]
-holt wiki            derived knowledge wiki: holt wiki [sync | rebuild | lint | list | show | status]
+holt wiki            derived knowledge wiki: holt wiki [sync | auto | rebuild | lint | list | show | status]
 holt setting         configure brains, API brains, and launch command
 holt login <brain>   sign in to claude, codex, or gemini
 holt version         print version