@cmodjs/core 3.1.0 → 4.0.1

package/docs/jobs.md

@@ -1,6 +1,6 @@
 # Jobs
 
-A job is a ready-made feature of a mod: a slash command, a tool, permission rules, a check, a prompt, a status line, or a background program. Add each in `setup` with `mod.use`.
+A job is a ready-made feature of a mod: a slash command, a tool, permission rules, a check, a prompt, a schedule, or a background program. Add each in `setup` with `mod.use`.
 
 ```ts
 mod.use<Handle>(job: Job<Handle, State>): Handle
@@ -10,7 +10,7 @@ type Job<Handle, State> = (context: JobContext<State>) => Handle
 
 Each job function, such as `slashCommand(options)`, returns a `Job`. `mod.use` runs the job and returns its handle. A job that has nothing to hand back returns `void`.
 
-A job's bad options throw at one of two times. `check`, `permissions`, `prompt`, and `schedule` check their options when the job function is called. `slashCommand`, `tool`, `statusLine`, and `program` check theirs when the job runs, at `mod.use`, so the error surfaces as `its setup function threw: …`.
+A job's bad options throw at one of two times. `check`, `permissions`, `prompt`, and `schedule` check their options when the job function is called. `slashCommand`, `tool`, and `program` check theirs when the job runs, at `mod.use`, so the error surfaces as `its setup function threw: …`.
 
 | Job | Import | Adds |
 | --- | --- | --- |
@@ -20,7 +20,6 @@ A job's bad options throw at one of two times. `check`, `permissions`, `prompt`,
 | `check` | `jobs/check.js` | A command that runs after matching calls, and reports a failure to Claude |
 | `prompt` | `jobs/prompt.js` | Text Claude reads: kept current with the mod's state, before matching prompts, or after matching calls |
 | `schedule` | `jobs/schedule.js` | A prompt Claude Code sends Claude on a cron schedule, kept current with the mod's state |
-| `statusLine` | `jobs/status-line.js` | A status line |
 | `program` | `jobs/program.js` | A background program the mod talks to over HTTP |
 
 Each job announces itself. The first time a version starts, Claude Mod Manager (cmod) logs what the mod added, such as `tasks added /tasks, the open_ticket tool and 2 permission rules.`
@@ -34,7 +33,6 @@ A job gives each function it calls a deadline. The whole function must answer wi
 | `slashCommand`'s `reply` | 30 s | The command shows `/<name> failed: /<name> passed the 30 s deadline of slashCommand`. |
 | `tool`'s `execute` | 30 s | The call is denied with `The <name> tool failed: the <name> tool passed the 30 s deadline of tool`. |
 | `prompt`'s `prompt` | 5 s | The prompt adds nothing, and the reason goes to Claude Code's debug log. |
-| `statusLine`'s `text` | 2 s | The status line keeps its last text, and the reason goes to Claude Code's debug log. |
 | `permissions`' `when` | 2 s | The rule matches, and its reason adds `Its when check failed: it passed the 2 s deadline of permissions`. |
 | `check`'s `run` | `timeoutMs`, 60 s by default, 10 minutes at most | The call's result says the command passed the deadline. |
 
@@ -51,21 +49,19 @@ slashCommand<State>(options: {
   readonly argumentHint?: string
   readonly immediate?: true
   readonly reply: (input: { args: string; positionals: string[] }, mod: Mod<State>) => CommandReply | void | Promise<CommandReply | void>
-}): Job<Disposable, State>
+}): Job<SlashCommand, State>
 
 type CommandReply = string | { text?: string; context?: string } | undefined
+type SlashCommand = { readonly name: string; remove(): void }
 ```
 
 - `name` is the command without the slash: 1 to 64 letters, digits, `_`, or `-`. The person types `/<name>`. Another name throws `<mod>: "<name>" is not a slash command name.`
 - `description` is the line the typeahead and `/help` show.
 - `argumentHint` is drawn dim after the name, such as `[path]`.
 - `immediate: true` runs the command at once while Claude is still working. Without it, the command waits for the turn to end.
-- A command lasts for the session. Adding a command with a name the session already has replaces it, and Claude Code has no call that removes one, so a command whose source is gone answers that it no longer applies. `dispose()` on the handle stops the mod answering the command.
-- A key the mod binds in its `package.json` `"cmod": { "keys": { "shift+tab": "/mode" } }` runs the command ([install-steps.md](install-steps.md#key-bindings)). The command of a key takes `immediate: true`, so the key works while Claude works, and a `reply` that returns `undefined`, so a press adds no row to the conversation. It changes `mod.state`, and a pane or band that shows the state is how the person sees the press. cmod logs `<mod>: <key> runs /<name>, which waits for Claude's turn to end and adds a row to the conversation. Give /<name> immediate: true.` for a key whose command lacks it.
-
-```ts
-mod.use(slashCommand({ name: 'mode', description: 'Switch to the next mode', immediate: true, reply: (_input, mod) => void (mod.state.session.mode = next(mod.state.session.mode)) }))
-```
+- A command lasts for the session. Adding a command with a name the session already has replaces it, and Claude Code has no call that removes one, so a command whose source is gone answers that it no longer applies. `remove()` on the handle stops the mod answering the command.
+- A command's `reply` runs inside the person's own input, so a page or pane it opens shows at any width ([ui.md](ui.md#the-sidebar-and-its-pages)).
+- A key combo is a hotkey, not a command ([mod.md](mod.md#hotkeys)).
 - `reply` gets `args` and `positionals`. `args` is everything after the name as Claude Code passes it, and `''` for a bare `/<name>`. cmod hands it on unchanged. `positionals` is that text split into words the way a shell splits them, so extra spaces never reach it. `tested.type('/todo  milk')` drops the spaces after the name.
 - A `string` reply, or `text`, shows as the command's output. `context` is text Claude reads after the output, and the person never sees. `undefined` shows nothing.
 - A `reply` that throws shows `/<name> failed: <error>`.
@@ -103,10 +99,12 @@ tool<Schema, State>(options: {
   readonly description: string
   readonly inputSchema?: Schema
   readonly execute: (input: FromSchema<Schema>, mod: Mod<State>) => unknown
-}): Job<Disposable & { readonly name: string }, State>
+}): Job<Tool, State>
+
+type Tool = { readonly name: string; remove(): void }
 ```
 
-- `name` is 1 to 64 letters, digits, `_`, or `-`. Claude sees the tool as `mcp__<plugin name>__<name>`, and the handle's `name` is that full name. `dispose()` on the handle stops the mod answering the tool.
+- `name` is 1 to 64 letters, digits, `_`, or `-`. Claude sees the tool as `mcp__<plugin name>__<name>`, and the handle's `name` is that full name. `remove()` on the handle stops the mod answering the tool.
 - `description` tells Claude what the tool does.
 - `inputSchema` is a JSON Schema with `type: 'object'`. It types `execute`'s `input`, so write it inline. cmod checks each call's input against it, draft 2020-12, and denies an input that does not fit with the list of its errors. Its properties cannot be named `tool`, `tool_use_id`, `consent`, or `agentId`, which Claude Code keeps for itself.
 - `execute` returns the result Claude reads. A `string` and an array of content blocks go to Claude as they are. Any other value goes as JSON. `undefined` returns nothing.
@@ -321,35 +319,6 @@ export const loop = defineMod({
 })
 ```
 
-## statusLine
-
-```ts
-statusLine<State>(options: {
-  readonly text: (usage: Usage, mod: Mod<State>) => string | undefined | Promise<string | undefined>
-  readonly interval?: number
-}): Job<void, State>
-
-type Usage = { model: string; context: { tokens?: number; window: number; percent?: number }; cost?: { usd: number } }
-```
-
-- `text` returns the status line's text, or `undefined` to clear it.
-- cmod calls `text` when the mod starts, every `interval` milliseconds (10000 by default), and whenever Claude Code measures the session. It sends the text only when it changed.
-- A `text` that throws keeps the last text, and the error goes to Claude Code's debug log.
-- A mod has one status line. A second `statusLine` throws: join the texts in one.
-- An `interval` below 1 throws.
-
-```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
-import { statusLine } from '../node_modules/@cmodjs/core/jobs/status-line.js'
-
-export const usage = defineMod({
-  name: 'usage',
-  setup(mod) {
-    mod.use(statusLine({ text: ({ model, context }) => `${model} ${context.percent ?? 0}%` }))
-  },
-})
-```
-
 ## program
 
 It needs `"run"` with the program's name. Without the grant the program stops at once and names the line to add ([permissions.md](permissions.md)).
@@ -403,29 +372,33 @@ A `Job` is a function. `mod.use` calls it with a `JobContext` and returns what i
 type JobContext<State> = {
   readonly mod: Mod<State>
   announce(feature: string): void
-  reserveName(type: string, name: string, taken: string): Disposable
+  reserveName(type: string, name: string, taken: string): Reservation
 }
+
+type Reservation = { remove(): void }
 ```
 
-- `mod` is the mod that uses the job. A job builds on `mod.every`, `mod.ui`, and the imports from `mod.js`, such as the methods of `sessions`, as `setup` does ([mod.md](mod.md)).
+- `mod` is the mod that uses the job. A job builds on `mod.every`, the `add` calls of `mod`, and the imports from `mod.js`, such as the methods of `sessions`, as `setup` does ([mod.md](mod.md)).
 - `announce` adds a phrase to the list cmod logs when the mod first starts.
-- `reserveName` throws `taken` when the mod already reserved that `type` and `name`, so a job refuses a duplicate. `dispose()` on what it returns frees the name again.
+- `reserveName` throws `taken` when the mod already reserved that `type` and `name`, so a job refuses a duplicate. `remove()` on what it returns frees the name again.
 
-A job that hands back a feature the mod turns off returns a `Disposable`, as `slashCommand` and `tool` do:
+A job that hands back a feature the mod turns off returns a handle with `remove()`, as `slashCommand` and `tool` do:
 
 ```ts
-import { defineMod, sessions, type Disposable, type Job } from '../node_modules/@cmodjs/core/mod.js'
+import { defineMod, sessions, type Job } from '../node_modules/@cmodjs/core/mod.js'
+
+type EditCounter = { count(): number; remove(): void }
 
-const editCounter = (tool: string): Job<Disposable & { readonly count: () => number }> => ({ mod, announce, reserveName }) => {
+const editCounter = (tool: string): Job<EditCounter> => ({ mod, announce, reserveName }) => {
   const reserved = reserveName('editCounter', tool, `${mod.name}: edits of ${tool} are already counted.`)
   let edits = 0
   const listening = sessions.current.onToolCall({ name: tool }, () => void (edits += 1))
   announce(`a count of ${tool} calls`)
   return {
     count: () => edits,
-    dispose() {
-      listening.dispose()
-      reserved.dispose()
+    remove() {
+      listening.remove()
+      reserved.remove()
     },
   }
 }
@@ -434,7 +407,7 @@ export const counter = defineMod({
   name: 'counter',
   setup(mod) {
     const writes = mod.use(editCounter('Write'))
-    sessions.current.onTurnEnd(() => mod.ui.toast(`${writes.count()} files written so far`))
+    sessions.current.onTurnEnd(() => mod.toast(`${writes.count()} files written so far`))
   },
 })
 ```

package/docs/mod.md

@@ -1,30 +1,30 @@
 # Define a mod
 
-`defineMod` describes a mod: its name, its state, the methods it offers other mods, and the `setup` function that attaches everything to Claude Code. `registerMod` registers the definition with Claude Code.
+`defineMod` describes a mod: its name, its state, its options, its hotkeys, and the `setup` function that adds everything to Claude Code and returns the methods it offers other mods. `registerMod` registers the definition with Claude Code.
 
 ## defineMod
 
 ```ts
-defineMod<State, Name, Options>(definition: ModDefinition<State, Name, Options>): ModDefinition<State, Name, Options>
+defineMod<State, Name, Options, Hotkeys>(definition: ModDefinition<State, Name, Options, Hotkeys>): ModDefinition<State, Name, Options, Hotkeys>
 ```
 
 ```ts
-type ModDefinition<State, Name, Options> = {
+type ModDefinition<State, Name, Options, Hotkeys> = {
   readonly name: Name
   readonly state?: State
   readonly options?: Options
-  readonly api?: { … }
+  readonly hotkeys?: Hotkeys
   readonly installer?: readonly Step<State>[]
-  setup(mod: Mod<State, Options>): unknown
+  setup(mod: Mod<State, Options, Hotkeys>): Api | void | Promise<Api | void>
 }
 ```
 
 - `name` is the mod's name. Use the `name` in `.claude-plugin/plugin.json`. Claude Mod Manager (cmod) keys the saved state and the options by this name, and the data folder and the Skill overrides by the plugin's name, so the two must match. `defineMod` throws `defineMod: the mod needs a name, such as the name in .claude-plugin/plugin.json.` for a blank name.
 - `state` holds the starting values, grouped by how long they last. [state.md](state.md) explains the groups.
 - `options` declares what a person sets, such as a token, and types `mod.options`. [options.md](options.md) explains them.
-- `api` holds the methods other mods call. [dependencies.md](dependencies.md) explains it.
+- `hotkeys` declares the key combos the mod listens for, each with a title and a default combo the person can change ([Hotkeys](#hotkeys)).
 - `installer` lists the steps the person finishes in Claude Code after the permissions and the options, such as signing in. [install-steps.md](install-steps.md#steps-in-claude-code) explains them.
-- `setup` runs once when the mod starts. It adds listeners, panes, renders, and jobs. It may be `async`.
+- `setup` runs once when the mod starts. It adds listeners, pages, panes, widgets, styles, and jobs. It may be `async`. What it returns is the mod's API: an object of methods other mods call. Return nothing for a mod that offers none. [dependencies.md](dependencies.md) explains it.
 
 ```tsx
 import { defineMod, sessions } from '../node_modules/@cmodjs/core/mod.js'
@@ -37,7 +37,7 @@ export const greeter = defineMod({
     sessions.current.onPrompt(() => {
       if (mod.state.session.isGreeted) return
       mod.state.session.isGreeted = true
-      mod.ui.toast(`Hello from ${mod.name}`)
+      mod.toast(`Hello from ${mod.name}`)
     })
   },
 })
@@ -47,15 +47,17 @@ export const greeter = defineMod({
 
 Claude Code loads the mod at the start of each session. cmod then checks that the mod is set up. A mod the person has not accepted yet opens the installer pane, `Install <name>`, which lists its permissions and the changes it makes to the computer, and waits for Accept ([install-steps.md](install-steps.md)). An option with no default and no value is asked on the next page of the same pane. Then cmod loads the saved state, runs `setup`, marks as open each of the mod's panes that Claude Code already shows, and opens the pane again for each `installer` step the mod declares that is not done.
 
-The first time a mod starts on a machine, cmod shows the toast `Installed` under its name. Opened, it lists the mod's `plugin.json` `description`, what setup added, such as `Adds the my-mod pane, a render of AbovePrompt and /deploy.`, what its install step set up, and each permission the person allowed, with a Settings button for `/mods <name>`. The first time a new version starts, the toast is `Updated to <version>`: the first three changes of that version's `CHANGELOG.md` section, the version the machine ran before, and a Changelog button ([Release notes](#release-notes)). A mod with no changelog lists what it adds now and no longer adds instead. A new session, `/reload-plugins`, and a version the machine already ran show no toast.
+The first time a mod starts on a machine, cmod shows the toast `Installed` under its name. Opened, it lists the mod's `plugin.json` `description`, what setup added, such as `Adds the my-mod pane, the Branch widget and /deploy.`, what its install step set up, and each permission the person allowed, with a Settings button that opens Settings at the mod. The first time a new version starts, the toast is `Updated to <version>`: the first three changes of that version's `CHANGELOG.md` section, the version the machine ran before, and a Changelog button ([Release notes](#release-notes)). A mod with no changelog lists what it adds now and no longer adds instead. A new session, `/reload-plugins`, and a version the machine already ran show no toast.
 
 When a step fails, or the person declines the install, the mod stays stopped. Once another session sets it up, the mod starts at the next prompt of every session it stopped in, with no `/reload-plugins`.
 
+A mod that loads while a session runs, such as after `/reload-plugins` or `/plugin install`, hears no SessionStart from Claude Code. cmod runs its `onSessionStart` and `beforeSessionStart` listeners before the next prompt instead, once, with the source `resume`.
+
 When a step fails, the mod does not start. An error toast above the prompt names the failure, with the fix under it:
 
 - `<mod>: state.<group> is not a lifetime. …` or `<mod>: state.<group> is not an object of values. …` when the declared state is not valid ([state.md](state.md)).
 - `its state did not load: <error>` when reading the saved values fails.
-- `it needs <titles>` when the person chose Not now on an option with no default, or no one can answer, as in `claude -p` ([options.md](options.md)). This one says `Set it in /config.` instead, and Claude Code reloads the mod once the value is set.
+- `it needs <titles>` when the person chose Not now on an option with no default, or no one can answer, as in `claude -p` ([options.md](options.md)). This one says `Retry asks for it.`, and `Retry` opens the question again.
 - `its setup function threw: <error>` when `setup` throws or rejects.
 - `its open panes did not load: <error>` when Claude Code cannot list the open panes.
 - `the details of its session did not load: <error>` when Claude Code cannot name the session's id, model, or start time.
@@ -98,7 +100,7 @@ A mod's `CHANGELOG.md`, at its root, holds what changed in each version, written
 ```
 
 - `cmod publish` releases the version's section as the GitHub release's notes, and refuses a version with no section ([commands.md](commands.md#cmod-publish)). Every release ships the file.
-- The Updated toast shows the first three changes of the new version's section, and its Changelog button opens `/mods <name> changelog`, the whole file with the installed version at the top of the view.
+- The Updated toast shows the first three changes of the new version's section, and its Changelog button opens the mod's Changelog in Settings, the whole file with the installed version at the top of the view.
 - A linked checkout whose version has no section yet shows its `[Unreleased]` section, so the notes show as soon as the version moves.
 - `cmod new` writes the file with an `[Unreleased]` and a `[0.1.0]` section.
 
@@ -141,82 +143,87 @@ Keep `register.ts` this small. Claude Code checks a hooks module before it loads
 
 ## mod: this mod
 
-`setup` gets `mod`, of type `Mod<State, Options>`. Every listener, render, and job gets the same `mod`. `mod` holds what belongs to this mod: its name, its folders, its values, its grants, and what it adds to Claude Code.
+`setup` gets `mod`, of type `Mod<State, Options, Hotkeys>`. Every listener, render, and job gets the same `mod`. `mod` holds what belongs to this mod: its name, its folders, its values, its grants, its hotkeys, and what it adds to Claude Code.
 
 ```ts
-type Mod<State, Options> = {
+type Mod<State, Options, Hotkeys> = {
   readonly name: string
   readonly folder: string
   readonly dataFolder: string
   readonly state: Readonly<State>
   readonly options: OptionValues<Options>
   readonly permissions: Permissions
-  every(ms, listener): Disposable
-  after(ms, listener): Disposable
+  readonly hotkeys: { readonly [name in keyof Hotkeys]: Hotkey }
+  every(ms, listener): Timer
+  after(ms, listener): Timer
   use(job): Handle
-  log(text): void
-  readonly ui: { pane, render, toast, ask, copy, scroll, notice }
-  readonly settings: { page, open }
+  log(text, options?): void
+  readonly sidebar: { add(page): Page }
+  readonly settings: { add(page): Page; open(): Promise<void> }
+  readonly panes: { add(pane): Pane }
+  readonly widgets: { add(widget): Widget }
+  readonly styles: { add(style): Style }
+  readonly toast: Toast
+  ask(question, options?): Promise<string>
   readonly dependencies: CmodDependencies
 }
 ```
 
-| Member | What it is | Docs |
-| --- | --- | --- |
-| `name` | The mod's name from `defineMod`. | |
-| `folder` | The plugin's own folder, where the files the mod ships live. | |
-| `dataFolder` | The mod's own folder in the cmod store: `$XDG_DATA_HOME/cmod/data/<plugin name>`, or `~/.local/share/cmod/data/<plugin name>` when `XDG_DATA_HOME` is not set. The install step gets the same folder as `CMOD_DATA`. cmod deletes it when the mod is removed. | [install-steps.md](install-steps.md) |
-| `state` | The mod's values. Assign to a key to change it. | [state.md](state.md) |
-| `options` | The values a person set for the mod's options, typed from their declaration. Read-only. | [options.md](options.md) |
-| `permissions` | Says whether the person granted each permission. | [permissions.md](permissions.md) |
-| `every` and `after` | Run a listener on a timer while the session runs. | below |
-| `use` | Adds a job, such as a slash command or a tool, and returns its handle. | [jobs.md](jobs.md) |
-| `log` | Writes a line, under the mod's name, to Claude Code's debug log. | below |
-| `ui` | Panes, renders at a place Claude Code draws, toasts, questions, the clipboard, scrolling, and a line under a permission dialog. | [ui.md](ui.md) |
-| `settings` | Adds the mod's own pages to `/mods`, and opens them. | below |
-| `dependencies` | Calls the methods of other mods. | [dependencies.md](dependencies.md) |
+- `name` is the mod's name from `defineMod`.
+- `folder` is the plugin's own folder, where the files the mod ships live.
+- `dataFolder` is the mod's own folder in the cmod store: `$XDG_DATA_HOME/cmod/data/<plugin name>`, or `~/.local/share/cmod/data/<plugin name>` when `XDG_DATA_HOME` is not set. The install step gets the same folder as `CMOD_DATA`. cmod deletes it when the mod is removed ([install-steps.md](install-steps.md)).
+- `state` holds the mod's values. Assign to a key to change it ([state.md](state.md)).
+- `options` holds the values a person set for the mod's options, typed from their declaration. Read-only ([options.md](options.md)).
+- `permissions` says whether the person granted each permission ([permissions.md](permissions.md)).
+- `hotkeys` holds each hotkey `defineMod` declared ([Hotkeys](#hotkeys)).
+- `every` and `after` run a listener on a timer while the session runs.
+- `use` adds a job, such as a slash command or a tool, and returns its handle ([jobs.md](jobs.md)).
+- `log` writes a line, under the mod's name, to Claude Code's debug log.
+- `sidebar`, `settings`, `panes`, `widgets`, and `styles` add the mod's pages, panes, widgets, and styles. `toast` shows a short message and `ask` asks a question ([ui.md](ui.md)).
+- `dependencies` calls the methods of other mods ([dependencies.md](dependencies.md)).
 
 Everything that is Claude Code's or the computer's rather than the mod's is an import from `mod.js`, so a function in any file calls it without being handed `mod`:
 
 ```ts
-import { commands, config, fs, http, metadata, model, process, sessions, settings } from '../node_modules/@cmodjs/core/mod.js'
+import { clipboard, commands, config, fs, http, metadata, model, process, sessions, settings } from '../node_modules/@cmodjs/core/mod.js'
 ```
 
-| Import | What it is | Docs |
-| --- | --- | --- |
-| `sessions` | The conversations: the one the mod runs in, every other one, and search across them. Everything that happens in a session, from a prompt to a permission dialog, is a method on it. | [session.md](session.md) |
-| `commands` | Every slash command: lists them, runs one, and hears or changes each run. | below |
-| `settings` | Claude Code's `settings.json` files: the person's, the project's, and the project's local one. | below |
-| `config` | The rows of Claude Code's `/config` menu. | below |
-| `model` | Asks a model one question, outside the conversation. | below |
-| `fs` | Reads, writes, lists, and finds files. | below |
-| `metadata` | Reads and changes the mod's keys in one file's metadata. | below |
-| `process` | Runs a program. | below |
-| `http` | Fetches a URL. | below |
+- `sessions` is the conversations: the one the mod runs in, every other one, and search across them. Everything that happens in a session, from a prompt to a permission dialog, is a method on it ([session.md](session.md)).
+- `commands` is every slash command: it lists them, runs one, and hears or changes each run.
+- `settings` is Claude Code's `settings.json` files: the person's, the project's, and the project's local one.
+- `config` is the rows of Claude Code's `/config` menu.
+- `model` asks a model one question, outside the conversation.
+- `fs` reads, writes, lists, finds, and watches files.
+- `metadata` reads and changes the mod's keys in one file's metadata.
+- `process` runs a program.
+- `http` fetches a URL.
+- `clipboard` puts text on the person's clipboard ([ui.md](ui.md#toasts)).
 
 Each import works once the mod has started, in `setup` and anything it adds. Each one checks the permission it needs, and rejects with the line to add or the grant to turn on when the person has not granted it ([permissions.md](permissions.md)).
 
-### Disposable
+### Take back what the mod added
 
-`mod.every`, `mod.after`, `mod.ui.render`, and every `on` and `before` method each return a `Disposable`. `dispose()` takes back what the call added, so a mod turns a feature off and on while it runs. Everything a mod adds is taken back when the mod stops, so a mod that keeps a feature for the whole session ignores the `Disposable`.
+Every `add` call, every `on` and `before` method, `fs.onChange`, `settings.beforeFileChange`, and `hotkey.onPress` return a part or a `Subscription`, and each has `remove()`, which takes back what the call added. So a mod turns a feature off and on while it runs. Everything a mod adds is taken back when the mod stops, so a mod that keeps a feature for the whole session ignores what the call returns.
 
 ```ts
-type Disposable = { dispose(): void }
+type Subscription = { remove(): void }
 ```
 
 ```ts
 const watching = sessions.current.onToolCall({ name: 'Edit' }, () => void (mod.state.session.edits += 1))
-mod.use(slashCommand({ name: 'stop-counting', description: 'Stop counting edits', reply: () => watching.dispose() }))
+mod.use(slashCommand({ name: 'stop-counting', description: 'Stop counting edits', reply: () => watching.remove() }))
 ```
 
 ### mod.every and mod.after
 
 ```ts
-mod.every(ms: number, listener: () => unknown): Disposable
-mod.after(ms: number, listener: () => unknown): Disposable
+mod.every(ms: number, listener: () => unknown): Timer
+mod.after(ms: number, listener: () => unknown): Timer
+
+type Timer = { readonly isRunning: boolean; stop(): void }
 ```
 
-`every` runs `listener` every `ms` milliseconds until the session ends or the mod disposes it. A tick that comes while the last run is still going is skipped, so a slow run never stacks up. `after` runs `listener` once, `ms` milliseconds from now, unless the mod disposes it first. A run that throws shows the error toast `The every <ms> ms timer failed`, or `The after <ms> ms timer failed`, and the next tick of an `every` runs again. `ms` is a whole number above 0 and at most `2147483647`, and any other `ms` stops `setup` with `<mod>: mod.every is <ms>. Give a whole number of milliseconds above 0 and at most 2147483647.`
+`every` runs `listener` every `ms` milliseconds until the session ends or the mod calls `stop()`. A tick that comes while the last run is still going is skipped, so a slow run never stacks up. `after` runs `listener` once, `ms` milliseconds from now, unless the mod calls `stop()` first. `isRunning` is true until the timer stops, and an `after` timer stops once it ran. A run that throws shows the error toast `The every <ms> ms timer failed`, or `The after <ms> ms timer failed`, and the next tick of an `every` runs again. `ms` is a whole number above 0 and at most `2147483647`, and any other `ms` stops `setup` with `<mod>: mod.every is <ms>. Give a whole number of milliseconds above 0 and at most 2147483647.`
 
 A watch that reacts on its own is `every` plus `mod.state` plus a `prompt` with no trigger: `every` checks the outside world, writes what it found to `mod.state`, and the panes and the prompt follow the state ([jobs.md](jobs.md#prompt)).
 
@@ -237,18 +244,39 @@ mod.log(text: string, options?: { to?: 'debug' | 'transcript' }): void
 
 With `{ to: 'transcript' }`, the line shows dim in the conversation, where the person reads it and Claude never does, such as "Formatted 3 files" after a turn.
 
-### mod.settings
+### Hotkeys
+
+A hotkey is a key combo the mod listens for, such as `alt+shift+p` to show a page. The mod declares each one with a title and a default combo, and the person changes the combo in Settings, under the mod, Hotkeys, the way VS Code handles an extension's keybindings.
 
 ```ts
-mod.settings.page(page: Pane<State>): void
-mod.settings.open(pageId?: string): Promise<void>
+hotkeys?: { readonly [name: string]: { readonly title: string; readonly default: Combo } }
+
+type Hotkey = {
+  readonly title: string
+  readonly combo: Combo | undefined
+  onPress(listener: () => unknown): Subscription
+}
 ```
 
-`/mods` shows each mod's description, options, permissions, keys, and changelog, and turns a mod off or removes it. `page` adds a page of the mod's own to its entry there, drawn as any pane is ([ui.md](ui.md)). The id `changelog` is taken by the Changelog page, so `page` refuses it. `open` opens that page, or with no id opens the mod's entry in `/mods`. `open` rejects for an id `page` did not add.
+- A name is letters, digits, and `_`, starting with a letter. `title` is the label Settings shows beside the combo.
+- A combo is one or two of `ctrl`, `alt`, `shift`, and `meta`, in that order, then a key: a letter, a digit, `f1` to `f12`, `tab`, `enter`, `escape`, `space`, `backspace`, `delete`, an arrow, `home`, `end`, `pageup`, `pagedown`, or a mark such as `/`. `ctrl+q`, `alt+shift+p`, and `ctrl+shift+k` are combos.
+- `defineMod` throws for a name, a title, or a combo that is not one, and for two hotkeys with one default.
+- `cmod check` writes the hotkeys into `package.json` `"cmod".hotkeys`, and `cmod publish` refuses a mod whose `package.json` differs from `defineMod`. The install question lists each combo, and `cmod setup` binds it in Claude Code's `keybindings.json`. A combo the person already bound to something else keeps their binding, and the hotkey has no combo until they pick one in Settings.
+- `combo` is the combo bound when the mod started, or `undefined` when `keybindings.json` binds none to the hotkey, such as when another binding kept the default.
+- `onPress` runs `listener` each time the person presses the combo. A page or pane the listener opens shows at any width, because the press is the person's own ([ui.md](ui.md#the-sidebar-and-its-pages)).
+- `tested.hotkey(name)` presses a hotkey in a test ([testing.md](testing.md)).
 
 ```tsx
-mod.settings.page(definePane({ id: 'runs', title: 'Runs', render: (current) => <Text>{current.state.session.lastRun}</Text> }))
-mod.use(slashCommand({ name: 'ci-runs', description: 'Show the CI runs', reply: () => void mod.settings.open('runs') }))
+export const notes = defineMod({
+  name: 'notes',
+  hotkeys: {
+    toggle: { title: 'Show or hide the notes', default: 'alt+shift+n' },
+  },
+  setup(mod) {
+    const page = mod.sidebar.add(notesPage)
+    mod.hotkeys.toggle.onPress(() => page.toggle({ focus: true }))
+  },
+})
 ```
 
 ## commands: slash commands
@@ -256,8 +284,8 @@ mod.use(slashCommand({ name: 'ci-runs', description: 'Show the CI runs', reply:
 ```ts
 commands.list(): Promise<CommandInfo[]>
 commands.run(name: string, args?: string): Promise<{ text?: string; note?: string }>
-commands.beforeRun(matcher?, listener: (run: CommandRun) => Answer | void, options?): Disposable
-commands.onRun(matcher?, listener: (run: CommandRun) => unknown, options?): Disposable
+commands.beforeRun(matcher?, listener: (run: CommandRun) => Answer | void, options?): Subscription
+commands.onRun(matcher?, listener: (run: CommandRun) => unknown, options?): Subscription
 
 type CommandInfo = { name: string; description: string; source: 'builtin' | 'plugin' | 'user' | 'mcp'; plugin?: string }
 type CommandRun = { name: string; args: string; source?: 'builtin' | 'plugin' | 'user' | 'mcp'; from: Sender; session: string; cwd: string }
@@ -285,7 +313,7 @@ settings.project.read(): Promise<Settings>
 settings.project.update(values: Readonly<Record<string, unknown>>): Promise<void>
 settings.local.read(): Promise<Settings>
 settings.local.update(values: Readonly<Record<string, unknown>>): Promise<void>
-settings.beforeFileChange(matcher?, listener: (change: SettingsFileChange) => { refuse: string } | void): Disposable
+settings.beforeFileChange(matcher?, listener: (change: SettingsFileChange) => { refuse: string } | void): Subscription
 ```
 
 `settings.user` is the person's own `~/.claude/settings.json`, `settings.project` is the project's `.claude/settings.json`, and `settings.local` is the project's `.claude/settings.local.json`.
@@ -385,7 +413,7 @@ fs.list(path?: string): Promise<Entry[]>
 fs.exists(path: string): Promise<boolean>
 fs.stat(path: string, options?: { resolve: boolean }): Promise<Stat>
 fs.find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
-fs.onChange({ path: string | readonly string[] }, listener: (change: FileChange) => unknown): Disposable
+fs.onChange({ path: string | readonly string[] }, listener: (change: FileChange) => unknown): Subscription
 ```
 
 ```ts
@@ -400,10 +428,10 @@ type Stat = { isFile: boolean; isFolder: boolean; isLink: boolean; size: number;
 - `list` lists a folder, the working folder without a path. A symbolic link is neither a file nor a folder, with `isLink` true. `modifiedAt` is the time it last changed, in milliseconds since 1970.
 - `exists` answers whether the path leads to a file or a folder.
 - `stat` answers what the path leads to, following a symbolic link, and rejects a missing path. With `{ resolve: true }` it also answers `realPath`: the absolute path, every symbolic link followed.
-- `onChange` hears each file Claude Code sees change, appear, or go at a path or under a folder. Claude Code reads the paths it watches when a session starts, so `onChange` works only in `setup`, and a call later throws. A relative path is under the project. `path` takes strings only, unlike other matchers, because the paths go to Claude Code as they are:
+- `onChange` hears each file that changes, appears, or goes at a path or under a folder, the mod's own saves included. cmod checks the paths twice a second, and at most 2000 files under one call's folders. A call over more stops, with an error toast that names its paths. It works from `setup` or any time later, and for a path that does not exist yet. A relative path is under the session's working folder. `path` takes strings only, unlike other matchers:
 
 ```ts
-fs.onChange({ path: `${mod.dataFolder}/history` }, ({ path, type }) => mod.ui.toast(`${path}: ${type}`))
+fs.onChange({ path: `${mod.dataFolder}/history` }, ({ path, type }) => mod.toast(`${path}: ${type}`))
 ```
 
 A file the mod ships is under `mod.folder`. A file the mod keeps for itself belongs in `mod.dataFolder`.
@@ -494,7 +522,7 @@ export const notes = defineMod({
   setup(mod) {
     sessions.current.onTurnEnd(async () => {
       await fs.write(`${mod.dataFolder}/last-stop.txt`, new Date().toISOString()).catch((error: unknown) => {
-        mod.ui.toast.error('Could not save the last stop', { description: messageOf(error) })
+        mod.toast.error('Could not save the last stop', { description: messageOf(error) })
       })
     })
   },
@@ -528,7 +556,7 @@ import { sessions } from '../node_modules/@cmodjs/core/mod.js'
 
 sessions.current.onToolCall({ name: 'Bash' }, (call) => {
   for (const { argv, folder } of parseShell(String(call.input['command'])).commands) {
-    if (basename(argv[0]) === 'trace') mod.ui.toast(`trace runs in ${resolve(call.cwd, folder)}`)
+    if (basename(argv[0]) === 'trace') mod.toast(`trace runs in ${resolve(call.cwd, folder)}`)
   }
 })
 ```

package/docs/options.md

@@ -18,7 +18,7 @@ export const ciWatch = defineMod({
     branch: option.text({ title: 'Branch', description: 'The branch to watch', default: 'main' }),
   },
   setup(mod) {
-    mod.ui.toast(`Watching ${mod.options.branch} every ${mod.options.every} minutes`)
+    mod.toast(`Watching ${mod.options.branch} every ${mod.options.every} minutes`)
   },
 })
 ```
@@ -49,7 +49,7 @@ Each value is, in order of precedence:
 3. The value the person set in `/config`.
 4. The `default` in the declaration.
 
-An option with no default and no value is asked before `setup` runs, on a page of the installer pane: one field per option, each saved to `/config` through `cmod option` as the person submits it. A secret is set in `/config` itself, where Claude Code keeps it in the keychain, and the page says so. When the person chooses Not now, or no one can answer, as in `claude -p`, the mod does not start: its error toast says `it needs <title>` and `Set it in /config.`, and Claude Code reloads the mod once the value is set.
+An option with no default and no value is asked before `setup` runs, on a page of the installer pane: one field per option, each saved to `/config` through `cmod option` as the person submits it. A secret is set in `/config` itself, where Claude Code keeps it in the keychain, and the page says so. When the person chooses Not now, or no one can answer, as in `claude -p`, the mod does not start: its error toast says `it needs <title>` and `Retry asks for it.`, and `Retry` opens the question again. A secret has an `Open /config` button, because Claude Code keeps secrets in /config and the keychain.
 
 `cmod install`, `cmod link`, and `cmod try` set options from the terminal with `--option key=value`, once per option ([commands.md](commands.md)).
 

package/docs/permissions.md

@@ -1,6 +1,6 @@
 # Permissions
 
-A mod declares what it does beyond drawing and listening: the hosts it connects to, the programs it runs, the files it changes outside its project, and whether it reads the conversation, adds text Claude reads, asks a model, starts tasks, uses Claude's tools, changes Claude Code's settings, or approves tool calls. The person sees each permission as one sentence when they install the mod, turns each one on or off in `/mods`, and cmod checks every call and every answer against what they granted.
+A mod declares what it does beyond drawing and listening: the hosts it connects to, the programs it runs, the files it changes outside its project, and whether it reads the conversation, adds text Claude reads, asks a model, starts tasks, uses Claude's tools, changes Claude Code's settings, or approves tool calls. The person sees each permission as one sentence when they install the mod, turns each one on or off in Settings, and cmod checks every call and every answer against what they granted.
 
 Permissions bind every mod built on `@cmodjs/core`, and the plugin directory reads them from `package.json`. They are a contract, not a sandbox: a Claude Code plugin can skip cmod and call Claude Code directly.
 
@@ -35,9 +35,9 @@ Anthropic's plugin directory does not list a mod that can approve Claude's tool
 
 ## What the person sees
 
-The install opens the installer pane in Claude Code and lists every permission in `permissions`, with the install step, the program, and the keys. An update asks again only when it adds a permission, and lists only the new ones. Removing the mod revokes everything it was granted.
+The install opens the installer pane in Claude Code and lists every permission in `permissions`, with the install step, the program, and the hotkeys. An update asks again only when it adds a permission, and lists only the new ones. Removing the mod revokes everything it was granted.
 
-`/mods <mod>` lists the same permissions as toggles. A toggle runs `cmod permission <mod> <name> [value] on|off`, and the mod sees the change before its next call, with no reload.
+Settings lists the same permissions as toggles, under the mod, Permissions. A toggle runs `cmod permission <mod> <name> [value] on|off`, and the mod sees the change before its next call, with no reload.
 
 `cmod check` prints the sentences, so you read what the person will see:
 
@@ -76,7 +76,7 @@ if (mod.permissions.run.allows('gh')) mod.every(60_000, refreshRuns)
 The call rejects, and the error names the fix:
 
 - An undeclared call names the line to add: `ci-watch calls http.fetch(https://api.github.com/repos), which needs "permissions": { "network": ["api.github.com"] } in package.json "cmod".`
-- A declared call the person turned off names where to turn it on: `ci-watch calls model.complete without your grant to "Ask a model, which uses your plan". Turn it on in /mods ci-watch.`
+- A declared call the person turned off names where to turn it on: `ci-watch calls model.complete without your grant to "Ask a model, which uses your plan". Turn it on in Settings.` The error toast that shows it has a `Settings` button that opens the mod's Permissions.
 - A `program` job without its grant stops at once with the same line, with no restarts.
 
 ## When a before answer has no grant