@jeffober/thatch 0.1.45 → 0.1.46

package/README.md

@@ -60,8 +60,8 @@ upgrades and works from read-only installs.
 
 ### NixOS / Nix
 
-This repo is a flake. Bun and the native embedding runtime are bundled, so no
-global `npm install` or `bun` on PATH is required.
+This repo is a flake. The package bundles Bun and the native embedding
+runtime, so you need no global `npm install` and no `bun` on PATH.
 
 Try it without installing:
 
@@ -69,23 +69,24 @@ Try it without installing:
 nix run github:sysread/thatch -- --version
 ```
 
-Install system-wide via the NixOS module (in your flake `configuration.nix`):
+Install options:
 
-```nix
-{
-  inputs.thatch.url = "github:sysread/thatch";
+- **NixOS module** (system-wide, all users):
 
-  # in your NixOS system's modules:
-  imports = [ inputs.thatch.nixosModules.default ];
-  programs.thatch.enable = true;   # puts `thatch` on PATH for every user
-}
-```
+  ```nix
+  {
+    inputs.thatch.url = "github:sysread/thatch";
+
+    # in your NixOS system's modules:
+    imports = [ inputs.thatch.nixosModules.default ];
+    programs.thatch.enable = true;   # puts `thatch` on PATH for every user
+  }
+  ```
 
-Or add the package yourself with the overlay
-(`nixpkgs.overlays = [ inputs.thatch.overlays.default ];` then
-`environment.systemPackages = [ pkgs.thatch ];`), or drop
-`inputs.thatch.packages.${system}.default` into a `home.packages` /
-`environment.systemPackages` list directly.
+- **Overlay**: add `nixpkgs.overlays = [ inputs.thatch.overlays.default ];`,
+  then `environment.systemPackages = [ pkgs.thatch ];`
+- **Package directly**: add `inputs.thatch.packages.${system}.default` to a
+  `home.packages` or `environment.systemPackages` list
 
 Once `thatch` is on PATH, wire it into your editor as usual:
 
@@ -94,10 +95,9 @@ cd /path/to/your/project
 thatch setup --claude --global   # or --cursor
 ```
 
-The embedding model still downloads once at first use and is cached in the
-platform's per-user cache dir (the per-platform paths above; override with
-`THATCH_MODEL_CACHE`), so it survives upgrades and works from the read-only
-Nix store.
+The embedding model still downloads once at first use. Its cache lives in the
+per-user cache dir described above, outside the read-only Nix store, so it
+survives upgrades. `THATCH_MODEL_CACHE` overrides the location.
 
 ### Other MCP-compatible harnesses
 
@@ -110,7 +110,7 @@ Nix store.
 ```
 
 Include thatch's instructions in your agent's system prompt manually; see
-[docs/dev/mcp-parity.md](docs/dev/mcp-parity.md) for the prompt text.
+[MCP parity](https://github.com/sysread/thatch/wiki/Mcp-Parity) for the prompt text.
 
 ## What's inside
 
@@ -179,7 +179,7 @@ review, review response, change and feature walkthroughs, memory verification,
 knowledge export, and writing tasks
 (PR descriptions, tickets, PR splitting).
 
-See the [user guide](docs/user/README.md) for the full tool list, CLI
+See the [user guide](https://github.com/sysread/thatch/wiki/Guide%3A-Overview) for the full tool list, CLI
 commands, configuration, environment variables, and detailed setup for each
 host.
 
@@ -230,11 +230,11 @@ embeddings, no network.
 
 ## Docs
 
-- [User guide](docs/user/README.md) -- setup, tools, configuration, CLI
-- [Development](docs/dev/README.md) -- architecture, module responsibilities
-- [MCP parity](docs/dev/mcp-parity.md) -- OpenCode plugin vs MCP feature comparison
-- [QA tests](tests/qa/) -- executable use cases (auto/ and live/ subdirs)
-- [Design docs](docs/plans/) -- design-decision snapshots and in-progress plans
+- [User guide](https://github.com/sysread/thatch/wiki/Guide%3A-Overview) -- setup, tools, configuration, CLI
+- [Development](https://github.com/sysread/thatch/wiki/Developer-Guide) -- architecture, module responsibilities
+- [MCP parity](https://github.com/sysread/thatch/wiki/Mcp-Parity) -- OpenCode plugin vs MCP feature comparison
+- [QA tests](https://github.com/sysread/thatch/tree/main/tests/qa) -- executable use cases (auto/ and live/ subdirs)
+- [Design docs](https://github.com/sysread/thatch/tree/main/docs/plans) -- design-decision snapshots and in-progress plans
 
 ## License
 

package/docs/dev/features/cicd.md

@@ -5,7 +5,7 @@ Thatch uses GitHub Actions for CI and publishing, plus a local release helper sc
 ## CI pipeline (.github/workflows/ci.yml)
 
 Runs on every push/PR to main. Three jobs:
-1. **Typecheck** — `bunx tsc -p tsconfig.check.json` (includes test files that the build's `tsconfig.json` excludes)
+1. **Typecheck** — `bunx tsc -p tsconfig.check.json` (includes src, tests, and the CI scripts in `.github/scripts`; the build's `tsconfig.json` includes only src)
 2. **Tests** — `bun test` (bun:test framework, no network, `:memory:` DB or temp dirs)
 3. **Markdownlint** — `bunx markdownlint-cli2` on `README.md` and `docs/**/*.md` (excluding `docs/plans/**`)
 
@@ -22,6 +22,14 @@ Key details:
 - npm 12 shipped a sigstore bug that broke OIDC publishing; the pin prevents it
 - The workflow deliberately sets NO `registry-url`, which would write a token-expecting `.npmrc` that preempts the OIDC exchange
 
+## Wiki pipeline (.github/workflows/wiki.yml)
+
+Triggered by pushes to main that touch `docs/**`, the workflow file, or the render script. One-way mirror of `docs/` into the GitHub wiki: renders each doc to a flat wiki page (tiered prefixes `Guide:`, bare, `Feature:`; see `.github/scripts/sync-wiki.ts`), rewrites relative md links, generates `Home.md` + `_Sidebar.md`, wipes and rewrites all wiki pages, then pushes to `sysread/thatch.wiki.git`.
+
+- Uses the `WIKI_TOKEN` Actions secret (classic PAT, `public_repo` scope) because the built-in `GITHUB_TOKEN` cannot push to wiki repos
+- Precondition: the wiki must be initialized once via the UI (GitHub does not auto-create `.wiki.git` repos)
+- `docs/plans/` and `docs/in-progress/` are excluded; duplicate or reserved page names fail the render script
+
 ## Release helper (bin/release)
 
 A bash script (`set -euo pipefail`) that bumps, checks, commits, tags, and pushes.
@@ -45,7 +53,7 @@ Steps:
 | `test` | Run the test suite (`bun test`) |
 | `test-watch` | Run tests in watch mode |
 | `coverage` | Run tests with coverage report |
-| `typecheck` | Typecheck src + tests (`bunx tsc -p tsconfig.check.json`) |
+| `typecheck` | Typecheck src + tests + `.github/scripts` (`bunx tsc -p tsconfig.check.json`) |
 | `lint-md` | Lint markdown docs (`bunx markdownlint-cli2`) |
 | `check` | The CI gate: typecheck + tests + markdownlint |
 | `release` | Bump version, commit, tag, push (args: `patch\|minor\|major`) |
@@ -60,7 +68,7 @@ Steps:
 ## Development tooling
 
 - **Bun 1.3.14** (pinned via mise)
-- **TypeScript** with `tsconfig.check.json` for typecheck (includes test files; build's `tsconfig.json` excludes them)
+- **TypeScript** with `tsconfig.check.json` for typecheck (includes src, tests, and `.github/scripts`; build's `tsconfig.json` includes only src)
 - **bun:test** framework (no network, `:memory:` DB or temp dirs, mock embeddings)
 - **markdownlint-cli2** with custom config (`.markdownlint-cli2.jsonc`): disables MD013 (line length), MD032 (blanks around lists), MD036 (emphasis as heading), MD060 (table alignment). Keeps MD040 (code-block language), MD047 (trailing newline), heading hierarchy.
 - **Zod** for tool schema validation and JSON Schema generation (`src/tool-defs.ts`)
@@ -74,10 +82,11 @@ Steps:
 
 - `.github/workflows/ci.yml` — CI pipeline
 - `.github/workflows/publish.yml` — publish pipeline (OIDC)
+- `.github/workflows/wiki.yml` + `.github/scripts/sync-wiki.ts` — wiki mirror pipeline
 - `bin/release` — release helper script
 - `mise.toml` — task definitions, tool pins, env vars
 - `.markdownlint-cli2.jsonc` — markdownlint config
-- `tsconfig.check.json` — typecheck config (includes tests)
+- `tsconfig.check.json` — typecheck config (includes src, tests, `.github/scripts`)
 
 ## Key invariants
 
@@ -86,4 +95,4 @@ Steps:
 - npm is pinned to 11.x. npm 12 shipped a sigstore bug that broke OIDC publishing.
 - The release helper checks for tagged-but-not-published state (tag exists, npm returns E404) and refuses to proceed with recovery instructions.
 - CI runs on push/PR to main. Publish runs only on `v*` tags. The release helper bridges them: tag + push triggers publish.
-- `tsconfig.check.json` includes test files for typecheck. The build's `tsconfig.json` excludes them.
+- `tsconfig.check.json` includes src, tests, and `.github/scripts` for typecheck. The build's `tsconfig.json` includes only src.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/docs/plans/nomenclater.md

@@ -1,89 +0,0 @@
-# Nomenclater
-
-## Synopsis
-
-Assigns a geeky/sci-fi name to the agent at the start of each new opencode
-session. The name is generated by a fast LLM call, cached for the session, and
-injected into the system prompt so the agent knows its name. opencode-only;
-requires plugin hooks. Pure cosmetic, no functional dependency.
-
-## Background
-
-Fnord's Nomenclater (backed by a GenServer name pool) generates whimsical names
-for sub-agents so their actions are distinguishable in logs. Jeff explicitly
-wants this for thatch: "I'd love to have this!" It builds agent identity and
-rapport, complementing the personality instructions in OPENCODE.md.
-
-The name must not change mid-conversation and must not trigger on continued
-or resumed sessions.
-
-## Session detection
-
-Same mechanism as the intuition-drives plan. See that plan for full detail.
-
-`session.created` fires only on brand-new session creation (fresh or fork). It
-does not fire when resuming an existing conversation. Detection: track
-`session.created` for top-level sessions (no `parentID`) in a `Set<string>`,
-generate the name on first `chat.message` for sessions in that set, remove
-from set after generating. Continued/resumed sessions never enter the set.
-
-## What it does
-
-```
-session.created (top-level) → add sessionID to newSessions Set
-
-chat.message (first message for sessionID in newSessions)
-  → remove from newSessions
-  → generate name via fast model → cache in Map<sessionID, name>
-
-experimental.chat.system.transform
-  → if name cached for sessionID: append "Your name for this session is <name>."
-
-session.deleted
-  → delete from name cache, newSessions set
-```
-
-Name generation uses fnord's theme list (Jargon File, Zork, Futurama,
-Discworld, D&D, Klingons, Sandman, etc.) and the same JSON-schema response
-format. One LLM call with a fast model. Themes are shuffled and 3 are selected
-per batch to avoid clustering.
-
-## Constraints
-
-- **opencode-only.** Requires plugin hook injection. The name is generated by a
-  fast LLM call and injected via `experimental.chat.system.transform`.
-- **First-message-only.** Same session-detection mechanism. The name must not
-  change mid-conversation.
-- **No persistent state needed.** The name is generated fresh per session and
-  held in a per-session map for the duration of that session. No DB writes.
-- **Must not trigger on continued sessions.** A resumed conversation keeps
-  whatever name the agent had (or had none, if the feature was added after the
-  session started). The `session.created` gate handles this.
-
-## Open question
-
-1. **Where does the name surface?** System prompt injection means the agent
-   knows its name but the user only sees it if the agent chooses to use it. Is
-   that enough, or should the name appear in the TUI somehow (e.g., a toast on
-   session start)?
-
-## Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| opencode-only | Requires plugin hooks for generation and injection |
-| One name per session, cached in memory | No DB writes; name is ephemeral, tied to session lifecycle |
-| Gated to first message of new sessions | Must not rename mid-conversation or trigger on resumed sessions |
-| Detection via session.created + chat.message | Same mechanism as the intuition-drives plan |
-
-## Dependencies
-
-### Runtime
-
-- Fast model for name generation (one LLM call per new session)
-
-### Built-in
-
-- Plugin hooks: `event` (session.created, session.deleted),
-  `chat.message`, `experimental.chat.system.transform`
-- In-process `Map` for per-session name caching