Enhancements 2026-10-13 (unified)

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
     "name": "genesis-tools",
-    "version": "1.0.114",
+    "version": "1.0.118",
     "description": "Plugins for GenesisTools CLI development and management",
     "owner": {
         "name": "genesiscz",
@@ -11,7 +11,7 @@
         {
             "name": "genesis-tools",
             "description": "Skills and utilities for working with GenesisTools CLI toolkit. Provides guidance for discovering, executing, and troubleshooting genesis tools with integrated workflow support.",
-            "version": "1.0.114",
+            "version": "1.0.118",
             "author": {
                 "name": "GenesisTools"
             },
@@ -26,8 +26,8 @@
         },
         {
             "name": "genesis-tools-mods",
-            "description": "Claude Code mods for GenesisTools: draws the whole diff of a Bash call whose diff-hook message was cut, with Claude Code's own diff element, under the call's row, and compacts an idle session before its 1-hour prompt cache expires. Install with: tools agents hooks mods install --write.",
-            "version": "1.5.2",
+            "description": "Claude Code mods for GenesisTools, each switched by mods.<feature> in the hooks file: the whole diff of a cut diff-hook message under the call's row, the subagent's model on its rows and beside its type in the agents panel (mods.agentRow, through Claude Code's subagentStatusLine), idle compaction before the prompt cache expires, /decisions, links in the streamed reply, a git and PR band with /mod-git, [ask] on tool rows, live spinner progress, a prompt cache countdown across sessions, /tmp usage, a live agents band, and a ledger of what hooks inject with repeat dedupe; the git, agents and hooks parts open sidebars (/mod-git, /mod-agents, /mod-hooks). Every mod but the full diff and idle compaction starts off: tools agents hooks mods enable <name|all> --write. Install with: tools agents hooks mods install --write.",
+            "version": "1.16.0",
             "author": {
                 "name": "GenesisTools"
             },

.claude/rules/agent-transcripts.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - "src/agents/**"
+  - "src/question/**"
+  - "src/hub/**"
+  - "src/claude/**"
+  - "src/codex/**"
+  - "src/grok/**"
+  - "src/ai-spend/**"
+  - "src/genesis-tools-mcp/**"
+  - "src/utils/agent-sessions/**"
+  - "src/utils/ai/transcripts/**"
+  - "src/utils/session-transcript/**"
+  - "src/utils/cmux/**"
+  - "src/utils/claude/**"
+  - "plugins/**"
+---
+
+# Reading a coding agent's transcript (Claude, Codex, Grok)
+
+Loaded by Claude Code when you read, write or edit a file in a folder that reads agent sessions. Martin's rule
+(2026-10-25): every fact read from a session transcript is a member of the provider interface, implemented by every
+provider, so a new provider is a list of members to fill in and no feature parses a transcript format itself.
+
+- **The interface is `NativeSessionReader`** (`src/utils/agent-sessions/types.ts`), reached through
+  `ProviderPlugin.codingAgent` and `resolveHistoryProvider(kind)` (`src/utils/agent-sessions/provider.ts`).
+  Claude, Codex and Grok implement it in `src/utils/agent-sessions/readers/<provider>.ts`. Never add another
+  provider registry or a `switch (harness)` over transcript formats in a tool.
+- **A new transcript capability is a REQUIRED member**, implemented by all three readers in the same change. The
+  compiler then names every provider (and test fake) that lacks it. When a provider cannot answer, its member says
+  so in code and in a comment (Grok's chat history carries no timestamps, so its `readBackward` is bounded by
+  content and bytes, never by time). An optional member lets the next provider forget it; do not add one for a
+  capability features rely on.
+- **Members today:** `discover`, `read`, `readMetadata`, `scan`, `readRecords`, `readStatistics`, and
+  `readBackward` (the newest entries, from the end back to the entry a caller's `until` accepts; added 2026-10-25
+  for the decision Stop hook's chat answers). A hook or tool reaches it with `readSessionBackward({ kind,
+  transcriptPath, until })` (`src/utils/agent-sessions/session-backward.ts`).
+- **What a feature gets is normalized**: `NativeHistoryEntry` (role, text, timestamp, tool, paths). Logic over it
+  (decision answers in `src/question/lib/decisions/chat-answers.ts`, a reply's decision blocks) is provider-neutral
+  and never names a JSONL field such as `"type":"assistant"`, `response_item`, `continued-in` or `chat_history`.
+- **Legacy parsers still exist** (about 20 folders read transcript rows directly: the decision hook's `finalReply`,
+  `src/claude/lib/usage/session-rows.ts` for `continued-in`, `src/utils/ai/transcripts/`). Do not copy them. When a
+  change touches one, move the fact it reads into a reader member first.
+- **Lint enforces it**: `no-transcript-format-outside-readers` in `scripts/ci/lint-rules.ts` fails a transcript record
+  type or field literal (`"continued-in"`, `"turn_context"`, `'"type":"user"'`, …) outside the readers. The files that
+  still do it are listed in `scripts/ci/transcript-format-ratchet.ts`; a file only ever leaves that list.
+- **Four more lints guard the same seam** (2026-10-25), each with a list in `scripts/ci/` that only shrinks:
+  - `no-hand-built-claude-home`, `no-hand-built-codex-grok-home` (`native-home-ratchet.ts`): a path into
+    `~/.claude`, `~/.codex`, `~/.grok` or their env overrides goes through `nativeHome(kind)` or
+    `nativeSessionRoots(kind)` in `src/utils/providers/session-paths.ts`.
+  - `no-harness-name-branch` (`harness-ratchet.ts`): `x.harness === "codex"` or a `case "grok":` in a tool is a
+    provider member instead.
+  - `no-hook-payload-read`: a hook payload field (`transcript_path`, `tool_input`, …) is read in
+    `src/agents/lib/hooks/payload.ts` only; add a typed `HookPayload` field there.
+  - `no-agent-name-in-command-match`: finding a running agent by its command line goes through
+    `src/utils/process/classify.ts`.
+- **A reader that caps or skips records says so in the log.** A byte cap, a timeout or a skipped row that hides
+  newer records logs the path, the cap and what was missed, so a frozen age or a missing prompt is found from
+  `~/.genesis-tools/logs/` and not by a user.

.claude/rules/ai.md

@@ -28,7 +28,7 @@ Everything AI lives under `src/utils/ai/` + `src/utils/security/`, in layers tha
 
 **Codex account ownership:** `src/utils/ai/openai/account-binding.ts` is the shared subscription binding for native terminals, workers, usage and SDK requests. Keep immutable account/workspace identity across refresh and renames. Vault grants have one refresh owner; native auth-file references are read-only. Diagnostics use `AiConfigStore.readOnly()` for metadata too, because ordinary `load()` may run migrations. Native app-server authentication uses external tokens with ephemeral credential storage; never swap the shared home's auth file.
 
-**Native CLI history:** extend `ProviderPlugin.codingAgent` and the readers/index under `src/utils/agent-sessions/`; do not add another provider registry. This derived history index is separate from app-owned `src/utils/ai/session/` conversations. Session identity includes provider, native ID and canonical source home. Import through the provider's native API with source-preserving provenance; never manufacture native SQLite rows or infer historical account ownership from today's login.
+**Native CLI history:** extend `ProviderPlugin.codingAgent` and the readers/index under `src/utils/agent-sessions/`; do not add another provider registry. Every fact a feature reads from a transcript is a required `NativeSessionReader` member that all three providers implement: `.claude/rules/agent-transcripts.md`. This derived history index is separate from app-owned `src/utils/ai/session/` conversations. Session identity includes provider, native ID and canonical source home. Import through the provider's native API with source-preserving provenance; never manufacture native SQLite rows or infer historical account ownership from today's login.
 
 **Cost math is `src/utils/ai/llm-cost.ts` only**: `calculateCallCostUsd` (prices cache reads and writes at their own rates) and `estimateLlmCallCostUsd`. No rate table belongs there, or anywhere new.
 

.claude/rules/genesis-links.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+  - "plugins/**"
+---
+
+# Links to GenesisTools apps, and code that needs GenesisTools
+
+Loaded by Claude Code when you read, write or edit TypeScript under `src/` or any file under `plugins/`.
+
+A `https://<link host>/…` link (genesis.tools here) opens something only when all of these hold on the Mac that
+clicks it: GenesisTools.app is installed, macOS gives https links to it, the router config has a route for that
+path, and the app or command the route names is there (Genesis Markdown for `/md/`, the `tools` CLI and cmux for
+`/claude/find/`). Miss one and the click goes to the browser, onto a page that does not exist. A `genesis-md://` or
+`genesis-tools://` link needs its app. Never write such a link without the check below.
+
+- **`tools genesis-tools probe`** answers it for this Mac: the CLI, the app, the router, Genesis Markdown, cmux, and
+  for each link kind (`md`, `finder`, `hub`, `claude-find`) whether a click opens it, by the real router config.
+  `probe md finder` exits 1 when one of them is missing and prints the fix command; `--url <url>` checks one link;
+  `--json` is for code. It reads only.
+- **In `src/`**: build a link with `routerLink()` (`src/utils/browser-router/router-link.ts`), which gives the
+  fallback with a coded reason when the link would be dead. The lint rule `no-raw-genesis-link` fails a literal
+  anywhere else. Code that needs the whole picture calls `probeGenesisTools()` or `linkState(url, facts)` from
+  `src/utils/genesis-tools/probe.ts`.
+- **In a plugin**: the marketplace installs a plugin without the GenesisTools checkout, so `tools` itself may be
+  missing, and a plugin file cannot import `src/`. The mods plugin asks `plugins/genesis-tools-mods/hooks/genesis.ts`:
+  it runs `tools genesis-tools probe --json` once per 30 minutes (a failed spawn means no CLI, so no links and no
+  `tools` commands), builds every link from the probe's link host, and returns undefined for a kind that does not
+  open. A feature that runs `tools …` checks `(await genesisProbe(host)).tools` first and shows no control that
+  would run it. Something that needs no router does it directly: a Finder reveal is `open -R <path>`.
+- **The fallback is part of the feature.** No md link: a note gets `cursor://file<path>:<line>` or its plain path.
+  No finder link: a folder stays text (a plain folder path opens nothing useful). No hub or decision link: the SHA
+  or the `❓ DECISION n` stays text.
+- **A new link kind** is an entry in `LinkTargets` (`src/utils/app-links/targets.ts`) and its routing in
+  `router-link.ts`, a router preset that writes its route (`src/utils/browser-router/presets.ts`), and a kind in
+  `GENESIS_LINK_KINDS` (`src/utils/genesis-tools/probe.ts`) plus the plugin's `LINK_KINDS`. `finder` (2026-10-23)
+  was only a hand-made route on one Mac until it got its preset.
+- **Ask Launch Services, not Spotlight, whether an app is installed.** `appPathForBundleId()`
+  (`src/utils/macos/launch-services.ts`) is the lookup `open -b` and a scheme click use. On 2026-10-23 `mdfind
+  kMDItemCFBundleIdentifier == …` found no app on a Mac with indexing on, so the genesis-md preset read "needs app"
+  while Genesis Markdown opened every link.

.claude/rules/markdown-viewer.md

@@ -18,7 +18,7 @@ day of review (PRs #499, #501).
   `open -g -n ~/Applications/GenesisTools.app --args --markdown <file> --no-focus`.
 - Genesis Markdown.app (GenesisPlayground) builds against this checkout's GenesisKit:
   `GENESIS_KIT_PATH=<GenesisTools>/src/macos/GenesisKit bun scripts/install.ts` in `GenesisPlayground/Genesis/apps/Genesis`.
-  It relaunches the viewer only when it was open. Its `swift build` needs `--disable-build-manifest-caching` too.
+  It starts the viewer after every install, in the background (`open -g`, with its saved tabs), open before or not. Its `swift build` needs `--disable-build-manifest-caching` too.
 - The diff page (`src/macos/GenesisTools/web/diff-viewer`) is bundled by `buildDiffViewer` in
   `src/macos/lib/permissions/app.ts`; both installs call it.
 
@@ -58,7 +58,8 @@ day of review (PRs #499, #501).
   the window before, `NSWindowController.init(window:)` drops it.
 
 ## Martin's UX calls for this viewer (2026-10-13)
-- Lists of changes fold untracked files by folder, page, and stay lazy; counts are meaningful.
+- Lists of changes fold untracked files by folder and build only the rows on screen (an AppKit table; no pages and
+  no "Show more" since 2026-10-25); counts are meaningful.
 - Diffs: left strips for whole added or removed blocks, word marks inside changed lines, no row backgrounds; `+`
   green, `−` red. Commit choosers are popovers with details, built when opened. Tabs: `GenSegmentedTabs`, animated.
 - A pane never goes blank between two contents: the old one stays until the new one has rendered.

.claude/rules/models.md

@@ -36,6 +36,13 @@ These read the catalog and need no edit of their own:
 - **The OpenRouter snapshot**: `src/utils/ai/catalog/data/openrouter-snapshot.json`, refreshed with `bun scripts/ai/update-openrouter-snapshot.ts`. A diff there is a price change; read it before you commit.
 - **The handoff-to skill rankings**: `plugins/genesis-tools/skills/handoff-to/SKILL.md` and `references/codex.md`. Changing them bumps the plugin version (`.claude/rules/plugins.md`).
 
+## Lint
+
+Three lint rules keep model facts in the owners above, each with a list in `scripts/ci/model-facts-ratchet.ts` that
+only shrinks (2026-10-25): `no-model-id-literal-outside-catalog` (a whole literal that is a model id), `no-model-price-table`
+(`opus: { input: … }`) and `no-effort-vocabulary-list` (an array or union of effort words). A list of efforts for one
+provider is `effortRange(from, to)` or a filter of `REASONING_EFFORTS` (`src/utils/ai/catalog/efforts.ts`).
+
 ## Checklist for a new model or a price change
 
 1. Read the vendor's own page, not a blog: the model page (`platform.claude.com/docs/en/models/<model>`, `developers.openai.com/api/docs/models/<id>`, `docs.x.ai/developers/<model>`) and the vendor pricing page. Note the date you read it in the code comment.

.claude/rules/opinionated-settings.md

@@ -0,0 +1,45 @@
+---
+paths:
+  - "src/macos/**/*.swift"
+  - "**/*.tsx"
+  - "src/*/ui/**"
+  - "src/dashboard/**"
+  - "src/dev-dashboard/**"
+  - "src/hub/lib/widget/**"
+  - "src/notify/**"
+---
+
+# Opinionated behavior gets a setting
+
+Loaded by Claude Code when you read, write or edit native or web UI code, the widget's wire schema, or notifications.
+
+Martin's rule (2026-10-23): when a UI change picks one way where a reasonable user could want another, the choice
+is a setting with that way as its default. You decide the default and ship the setting in the same change; do not
+ask first, and do not ship the behavior hard-coded.
+
+## Opinionated means
+
+- **Interruptions**: a sound, which sound per kind of event, a popup, a panel that opens or expands by itself, a
+  notification, a focus steal.
+- **Attention cues**: a flash, a pulse, a badge, their length and their colour; "flash the thing that caused it" is
+  the expected default, and its duration is the setting.
+- **Placement and order**: where a composer or toolbar sits (top or bottom), list order, which filter a list opens
+  with, what a list shows (only what needs you, or everything active).
+- **Hover behavior**: a tooltip or a preview on hover, hover delays, whether hover opens anything at all.
+- **Timings**: auto-collapse delays, how long a popup stays.
+
+Not opinionated: a bug fix, a layout that was wrong, a missing hover effect, accessibility labels, performance.
+Those are fixed, not made optional.
+
+## How
+
+- One preference per choice, stored where its surface already stores preferences (the widget: the zod schema in
+  `src/hub/lib/widget/types.ts` plus `WidgetPreferences` in GenesisKit `WidgetWireModels.swift`; a native window:
+  its settings store). An enum over a boolean when a third way is plausible ("auto" | "always" | "never").
+- The control goes on the settings page of that surface, in the card the behavior belongs to, with a one-line detail
+  that says what it does. A sound picker has a play button. A list that has a filter in place gets a settings
+  shortcut that opens the page at its card (`<page>#<anchor>`, `.nativeSettingsAnchor`), which flashes the card's border.
+- The default is your best judgment of what Martin asked for; the option you did not pick stays reachable.
+- A shared component's look change keeps the old look as a named option (the `AttentionPulse` presets: the border
+  flash is the default, the filled flash stays as `.filledFlash`).
+- Say in the reply which settings you added and their defaults.

.claude/rules/plugins.md

@@ -10,6 +10,19 @@ Loaded by Claude Code when you read, write or edit a file under `plugins/` or `.
 
 - **A runtime plugin file is standalone.** The harness copies `plugins/**` out of this checkout, so no runtime plugin file imports `@genesiscz/*` or `@app/*`; inline what it needs or import a sibling file. `bun scripts/ci/check-plugin-standalone.ts` fails CI on a violation. Plain `JSON` is allowed in `plugins/**`.
 - **A change users should get bumps the version** in `plugins/genesis-tools/.claude-plugin/plugin.json` and in `.claude-plugin/marketplace.json`, which holds it twice (top level and the plugin entry).
+- **The mods plugin (`plugins/genesis-tools-mods/`) hot-reloads in every running session** that has its folder in
+  `CLAUDE_CODE_PLUGIN_DIRS` (the shell, or the `env` block of `~/.claude/settings.json`): Claude Code 2.1.296 watches
+  that folder in each interactive session (`CLAUDE_CODE_PLUGIN_DIR_WATCH`, on by default in a terminal) and reloads
+  the mods when a file is saved, so do not ask the user to run `/reload-plugins` after an edit. Proof that a save
+  reached the sessions: new `"why":"start"` lines in `~/.genesis-tools/agents/mods-log/git.jsonl` within seconds,
+  one per session (2026-10-23, 18:44). Each save reloads every session, a half-finished edit too: on 2026-10-23 a
+  session drew four git rows for a moment, because `git-band.tsx` already read a setting that `settings.ts` did not
+  have yet. Finish the files of one change before you save the one that depends on them.
+- **Never start slow work from a mods `ui.render` hook.** The engine aborts a render's in-flight `$` calls when a newer
+  render of the same view replaces it (`$.process.run(...) aborted`), and the band redraws every second while a live
+  time shows. On 2026-10-23 the first `tools genesis-tools probe` ran from a render, was aborted, and the plugin kept
+  "no link opens" for 30 minutes in every session. Start such work from `session.start` or a timer
+  (`primeGenesisProbe`), let a render only read the result, and never remember a result that came from an abort.
 - **Skills load live from this working tree** when the session's folder is the marketplace folder (this repo). Any other folder gets the version-keyed cache: `claude plugin update genesis-tools@genesis-tools` refreshes it, and `/reload-plugins` re-reads it in the middle of a session.
 - **Codex runs this plugin too, hooks included**, from its own version-keyed cache (`~/.codex/plugins/cache/genesis-tools/genesis-tools/<version>/`, one per Codex home). An edit reaches Codex only after `codex plugin add genesis-tools@genesis-tools` in each home (`CODEX_HOME=<home> codex plugin add …`). A hook decides the harness from its payload, never from the environment (`hooks/harness.ts`).
 - **A hook runs on every matching tool call.** Keep it to one `bun` start (about 35 ms) and exit early when it has nothing to say. A PostToolUse payload from a subagent carries `agent_id`; key per-agent state on it.