@cmodjs/core 0.1.14 → 0.2.0

package/docs/commands.md

@@ -22,12 +22,13 @@ Creates a mod in `./<name>`: a `defineMod` with one hook, one pane, and one rend
 ### cmod link
 
 ```text
-cmod link [path] [--yes]
+cmod link [path] [--yes] [--option key=value]...
 ```
 
 Loads the checkout at `path` (default: the current folder) in every new Claude Code session, in place of the installed mod. Installs the cmod plugin when Claude Code lacks it, unless the checkout is cmod itself. Then installs the checkout's packages, builds the program `cli/` declares into `~/.local/bin`, writes the folder into `CLAUDE_CODE_PLUGIN_DIRS` in the `env` block of Claude Code's `settings.json`, and runs the checkout's install step. A session that is already running loads it after `/reload-plugins`.
 
 - `--yes` approves the mod's install and uninstall commands without asking.
+- `--option key=value` sets one of the mod's options through `claude plugin configure`, once per option. It refuses a key the mod does not declare, and names the keys it does ([options.md](options.md)).
 
 ### cmod unlink
 
@@ -47,27 +48,29 @@ Runs every check this machine can run on the mod at `path` (default: the current
 
 1. Installs its packages.
 2. Checks its layout.
-3. Checks that each step runs a script.
-4. Checks its imports.
-5. Looks for prebuilt binaries outside `cli/`.
-6. Bundles the hooks module as `cmod publish` does, and names each reason a bundle fails.
-7. Validates it with Claude Code, `claude plugin validate --strict`.
-8. Type-checks it with `tsc`, with `tsconfig.json`, and then with `tests/tsconfig.json` when it exists. `cmod new` writes both: the root config leaves Bun out of `src/`, which runs inside Claude Code, and the tests config adds `bun-types`, so a test can run a real program with `Bun.spawn` or read files with `node:fs`. When `.claude-plugin/types/` is missing, as in a fresh clone or in CI, Claude Code writes it first: cmod loads the mod in one `claude -p` run with a config folder of its own and no model to reach, so the run sends nothing.
-9. Lints it with `oxlint`.
-10. Runs, with `bun test`, every test file that does not import `claude-code/testing`.
-11. Runs, with `claude plugin test`, the test files that import `claude-code/testing`. It skips this when none does.
-12. Checks its name against other plugins. Only a project plugin, in `.claude/skills/<name>/` of a repository, runs this check: it fails when an installed or linked plugin has the same name and hides the project plugin. Any other mod passes it at once.
+3. Checks that each step runs a script, and prints the permissions the person grants at install and can grant later, as the person reads them ([permissions.md](permissions.md)). It fails a `hooks/register.ts` that calls `registerPermissionCheck` without `"approve": true`.
+4. Writes the options `defineMod` declares into `.claude-plugin/plugin.json` `userConfig`, keeping the file's own formatting, so Claude Code shows them in `/config` ([options.md](options.md)). It loads `hooks/register.ts` to read them, without starting the mod.
+5. Checks its imports.
+6. Looks for prebuilt binaries outside `cli/`.
+7. Bundles the hooks module as `cmod publish` does, and names each reason a bundle fails.
+8. Validates it with Claude Code, `claude plugin validate --strict`.
+9. Type-checks it with `tsc`, with `tsconfig.json`, and then with `tests/tsconfig.json` when it exists. `cmod new` writes both: the root config leaves Bun out of `src/`, which runs inside Claude Code, and the tests config adds `bun-types`, so a test can run a real program with `Bun.spawn` or read files with `node:fs`. When `.claude-plugin/types/` is missing, as in a fresh clone or in CI, Claude Code writes it first: cmod loads the mod in one `claude -p` run with a config folder of its own and no model to reach, so the run sends nothing.
+10. Lints it with `oxlint`.
+11. Runs, with `bun test`, every test file that does not import `claude-code/testing`.
+12. Runs, with `claude plugin test`, the test files that import `claude-code/testing`. It skips this when none does.
+13. Checks its name against other plugins. Only a project plugin, in `.claude/skills/<name>/` of a repository, runs this check: it fails when an installed or linked plugin has the same name and hides the project plugin. Any other mod passes it at once.
 
 `cmod check` fetches `tsc` 7.0.2 and `oxlint` 1.86.0 into the cmod store the first time. It ends with a count of passed, failed, and skipped checks, and exits 1 when one failed.
 
 ### cmod try
 
 ```text
-cmod try <owner/repo | path>... [--yes] [--home <folder>] [-- claude arguments]
+cmod try <owner/repo | path>... [--yes] [--option key=value]... [--home <folder>] [-- claude arguments]
 ```
 
 Starts one throwaway Claude Code session with mods set up, for trying a mod by hand or testing it with an agent. Installs each mod's packages, installs the cmod plugin when Claude Code lacks it, and runs each mod's install step after asking consent. Then starts one Claude Code session with every mod loaded through `--plugin-dir`.
 
+- `--option key=value` sets one option of the mod. With several mods, write `--option <mod>.key=value`.
 - The session runs with a new home folder, so it sees only the mods named here and changes none of your Claude Code settings, mods, key bindings, or history. The folder is deleted when the session ends.
 - The session stays logged in as you, with no login screen:
   - On macOS, Claude Code reads your login from the keychain, which `cmod try` links into the new home as `~/Library/Keychains`. Deleting the home removes only the link.
@@ -87,7 +90,7 @@ Starts one throwaway Claude Code session with mods set up, for trying a mod by h
 cmod publish [path] [--dry-run]
 ```
 
-Releases the mod at `path` (default: the current folder) at the version in its `plugin.json`:
+Releases the mod at `path` (default: the current folder) at the version in its `plugin.json`. It refuses a `plugin.json` whose `userConfig` differs from the options `defineMod` declares, and says to run `cmod check` and commit `.claude-plugin/plugin.json`.
 
 1. Builds the release from the committed files, leaving out `cli/`, `.github/`, and `.claude/`. A `"files"` list in `package.json` limits the release to the paths it lists, plus the folders of the install and uninstall steps, `.claude-plugin/`, `package.json`, `tsconfig.json`, the README, and the license, the way `npm publish` reads it. `tsconfig.json` holds the JSX settings the bundle in step 2 needs. List every folder the hooks module imports from, such as `"files": ["hooks", "src", "skills"]`, because the bundle in step 2 is built from the release.
 2. Bundles the hooks module that `hooks/hooks.json` names, with the mod's source and packages, into one readable `.js` file, writes each control character in it as a `\u` escape, and points `hooks/hooks.json` at it. Anthropic's plugin directory reads a repository without installing its packages, so it can follow a mod only when all its code is in one file.
@@ -95,7 +98,7 @@ Releases the mod at `path` (default: the current folder) at the version in its `
 4. Commits the release as the `release` branch, and builds the release archive from that commit.
 5. Builds the program `cli/` declares, and writes `SHA256SUMS` for every file of the release.
 6. Writes `.claude-plugin/marketplace.json`, listing the archive and the cmod plugin.
-7. Commits that file, tags `v<version>`, pushes the tag and the `release` branch, and creates the GitHub release.
+7. Commits that file, tags `v<version>`, pushes the tag and the `release` branch, and creates the GitHub release. Its notes open with `## Breaking changes`, listing each `BREAKING CHANGE:` footer of a commit since the last `v` tag and the subject of each commit typed with `!`, such as `feat!: mod.claude replaces job.claude`, so the people who use the mod know what to change before they update. `--dry-run` prints that list.
 8. Prints the link to paste as the Repository when you submit the mod at [claude.ai/directory/manage](https://claude.ai/directory/manage), such as `https://github.com/owner/greeter/tree/release`. The portal reads the branch from the link, so the directory follows `release`.
 
 The release keeps `package.json`, so Claude Code still installs the mod's packages for its install and uninstall steps. It keeps `bun.lock` too, unless a `"files"` list leaves it out. `main` keeps the source only.
@@ -120,8 +123,8 @@ It needs, and refuses to start without:
 ### cmod install
 
 ```text
-cmod install <owner/repo | path> [name] [--yes]
-cmod install <name | name@marketplace> [--yes]
+cmod install <owner/repo | path> [name] [--yes] [--option key=value]...
+cmod install <name | name@marketplace> [--yes] [--option key=value]...
 ```
 
 Adds the plugin's marketplace to Claude Code and installs the plugin through Claude Code. A mod also gets the cmod plugin when Claude Code lacks it, and its install step runs. Any other plugin installs through Claude Code alone, and cmod keeps no record of it.
@@ -131,6 +134,7 @@ Adds the plugin's marketplace to Claude Code and installs the plugin through Cla
 - Given the name of a plugin Claude Code already holds, it runs a mod's install step again.
 - A path holds a `/`, such as `./my-mod`.
 - `--yes` approves the mod's install and uninstall commands without asking.
+- `--option key=value` sets one of the mod's options through `claude plugin configure`, once per option, so a scripted install needs no visit to `/config`. It refuses a key the mod does not declare, and names the keys it does ([options.md](options.md)).
 
 ### cmod update
 
@@ -172,7 +176,7 @@ Downloads a program for an install script: fetches the download for this machine
 
 ## Run by cmod
 
-cmod runs these two itself. A person runs them to see a step's whole log or to finish a step.
+cmod runs these itself. A person runs them to see a step's whole log, to finish a step, or to grant a permission.
 
 ### cmod setup
 
@@ -180,7 +184,7 @@ cmod runs these two itself. A person runs them to see a step's whole log or to f
 cmod setup <plugin-root> [--events] [--consent <sha256>] [--yes]
 ```
 
-Downloads the program the mod's `package.json` `cmod.program` names into `~/.local/bin`, runs the mod's install step, saves its uninstall step, and records the mod as set up. An unchanged mod runs nothing. `--events` prints one event per line for a program to read, and the mod's progress line in Claude Code reads them.
+Downloads the program the mod's `package.json` `cmod.program` names into `~/.local/bin`, runs the mod's install step, saves its uninstall step, grants the permissions its `cmod.permissions` lists, and records the mod as set up. The consent covers the scripts, the program, the keys, and the permissions together, and an update asks again only for what changed. An unchanged mod runs nothing. `--events` prints one event per line for a program to read, and the mod's progress line in Claude Code reads them.
 
 ### cmod teardown
 
@@ -188,4 +192,12 @@ Downloads the program the mod's `package.json` `cmod.program` names into `~/.loc
 cmod teardown <plugin-name> [--events]
 ```
 
-Runs a removed mod's saved uninstall step, then deletes its install record, the saved step, every version of its program, and its data folder, and forgets the scripts the person approved for it. It keeps the mod's config folder, `~/.claude/cmods/<plugin-name>`. A failed uninstall step keeps the record, so `cmod teardown` can run again.
+Runs a removed mod's saved uninstall step, then deletes its install record, the saved step, every version of its program, and its data folder, and forgets the scripts and the permissions the person approved for it. It keeps the mod's config folder, `~/.claude/cmods/<plugin-name>`. A failed uninstall step keeps the record, so `cmod teardown` can run again.
+
+### cmod permission
+
+```text
+cmod permission <mod> <name> [value] on|off
+```
+
+Turns one permission of a set-up mod on or off, such as `cmod permission ci-watch model off` or `cmod permission ci-watch network api.github.com on`. A toggle in `/mods` runs it. It refuses a permission the mod's `package.json` `cmod.permissions` does not list, and the mod sees the change before its next call, with no reload ([permissions.md](permissions.md)).

package/docs/index.md

@@ -15,7 +15,7 @@ my-mod/
 ├── .gitignore                          node_modules/ and .claude-plugin/types/
 ├── .oxlintrc.json                      leaves .claude-plugin/types/ out of the lint
 ├── hooks/hooks.json                    names hooks/register.ts as the hooks module
-├── hooks/register.ts                   registerMod(addHook, myMod), and nothing else
+├── hooks/register.ts                   registerMod(addHook, myMod, options), and nothing else
 ├── src/mod.tsx                         defineMod: the state, the setup, the hooks, the panes
 ├── src/state.ts                        the starting state
 ├── src/panes/prompts.tsx               one definePane per file
@@ -59,7 +59,12 @@ A program the mod needs lives as source in `cli/`. `cmod publish` builds it and
 | How do I define a mod, and what can `mod` call? | [mod.md](mod.md) |
 | How does a mod watch something outside Claude Code, tell Claude about it, or ask a model? | [mod.md](mod.md#mod-every) |
 | How does a mod give Claude a prompt on a schedule, like `/loop`? | [jobs.md](jobs.md#schedule) |
-| How do I keep values across prompts, sessions, and projects? How does a person change them? | [state.md](state.md) |
+| How do I keep values across prompts, sessions, and projects? | [state.md](state.md) |
+| How does a person set a token, a URL, or a setting for my mod, for themselves or their team? | [options.md](options.md) |
+| Which hosts, programs, and files may my mod reach, and how does the person grant them? | [permissions.md](permissions.md) |
+| How does my mod find files and keep its own keys on each one, such as on a Skill? | [mod.md](mod.md#mod-metadata) |
+| How does the person finish a setup step only they can do, such as signing in? | [install-steps.md](install-steps.md#steps-in-claude-code) |
+| How do I add my mod's own page to `/mods`? | [mod.md](mod.md#mod-settings) |
 | How do I react to a Claude Code event, and what can a hook answer? | [hooks.md](hooks.md) |
 | How do I draw a pane, change a row Claude Code draws, or ask the person something? | [ui.md](ui.md) |
 | How do I add a slash command, a tool, a permission rule, a check, a prompt, a schedule, a status line, or a background program? | [jobs.md](jobs.md) |
@@ -75,10 +80,13 @@ A mod imports from the files below, and every other file in this package is inte
 | Import | Exports | Docs |
 | --- | --- | --- |
 | `mod.js` | `defineMod`, `ModDefinition`, `Mod`, `JobContext`, `Job`, `ProgressStep`, `PaneHandle`, `longestMs`, `messageOf` | [mod.md](mod.md), [jobs.md](jobs.md), [ui.md](ui.md) |
-| `mod.js` | `Claude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
+| `mod.js` | `Claude`, `ModClaude`, `RoutedEvent`, `RoutedHook`, `ToolCalls` | [jobs.md](jobs.md) |
+| `mod.js` | `FileMatch`, `Metadata`, `ScrollArgs` | [mod.md](mod.md), [ui.md](ui.md) |
+| `installer.js` | `defineStep`, `Step` | [install-steps.md](install-steps.md#steps-in-claude-code) |
 | `mod.js` | `ModEvent`, `ModHook`, `HookOptions`, `HookInput`, `HookAnswer` | [hooks.md](hooks.md) |
 | `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |
-| `register.js` | `registerMod`, `registerPermissionCheck` | [mod.md](mod.md) |
+| `register.js` | `registerMod`, `registerPermissionCheck`, `registeredMod` | [mod.md](mod.md) |
+| `options.js` | `option`, `Option`, `Options`, `OptionValues`, `OptionValue`, `OptionKind`, `UserConfigField`, `userConfigOf` | [options.md](options.md) |
 | `shell.js` | `parseShell`, `ParsedShell`, `ShellCommand` | [hooks.md](hooks.md) |
 | `path.js` | `resolve`, `join`, `dirname`, `basename`, `extname`, `relative`, `isAbsolute`, `normalize` | [hooks.md](hooks.md) |
 | `testing.js` | `testMod`, `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, `TestCall` | [testing.md](testing.md) |

package/docs/install-steps.md

@@ -34,16 +34,42 @@ cmod refuses a `cmod` key that breaks these rules, with the fix in the message:
 
 ## Consent
 
-Before a step runs for the first time, cmod shows the person the commands and the keys, and asks to run them. cmod hashes the commands, the keys, and every file in each script folder, and remembers the hash the person approved. A change to any of those asks again.
+Before a step runs for the first time, cmod shows the person the commands, the keys, and the permissions, and asks to run them. cmod hashes the commands, the keys, the permissions, and every file in each script folder, and remembers the hash the person approved with each permission. A change to any of those asks again, and an added permission is the only one it asks about ([permissions.md](permissions.md)).
 
-- In Claude Code, the mod asks `<mod> runs <install> to install, runs <uninstall> when you remove it and binds shift+tab to /mode. Install it now?` with `Install` and `Not now`, naming only what the mod has. A progress line above the prompt shows the install.
+- In Claude Code, the mod opens the installer pane, `Install <mod>`, focused. It lists `<mod> wants to:`, each permission as one sentence, then `and change your computer:` with `Run <install> now, and <uninstall> when you remove it` and `Bind shift+tab to /mode`, naming only what the mod has. `Accept` (a) runs the setup, and a progress line above the prompt shows the install. `Not now` (n) and Escape decline.
 - In a session with no screen, such as `claude -p`, the mod waits and logs `<mod> waits for consent to run <install>. Run cmod install <mod> in a terminal.`
-- In a terminal, `cmod install`, `cmod link`, `cmod try`, and `cmod update` print the commands, the program, and the keys, and ask `Set up <mod>? [y/N]`. `--yes` approves without asking.
+- In a terminal, `cmod install`, `cmod link`, `cmod try`, and `cmod update` print the commands, the program, the keys, and the permissions, and ask `Set up <mod>? [y/N]`. `--yes` approves without asking.
 - `Not now` leaves the mod off and logs `<mod> is not installed. Run cmod install <mod> to install it.`
 
 The mod starts only once its install step has run ([mod.md](mod.md)).
 
-In Claude Code, the mod sets itself up through the `cmod` that PATH finds, and only through one that knows every step it has. A mod with `keys` waits for cmod 0.1.12 or later, because an older cmod skips the keys. While PATH finds an older one, the line above the prompt says `PATH finds cmod <version>, and <mod> needs cmod 0.1.12 or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.` The mod sets up as soon as a new enough cmod answers, such as the one the cmod plugin installs into `~/.local/bin` at its first start.
+In Claude Code, the mod sets itself up through the `cmod` that PATH finds, and only through one that knows every step it has. A mod with `keys` waits for cmod 0.1.12 or later, because an older cmod skips the keys, and a mod with `permissions` waits for cmod 0.2.0 or later, because an older cmod grants none of them. While PATH finds an older one, the line above the prompt says `PATH finds cmod <version>, and <mod> needs cmod 0.1.12 or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.` The mod sets up as soon as a new enough cmod answers, such as the one the cmod plugin installs into `~/.local/bin` at its first start.
+
+## Steps in Claude Code
+
+Some setup only the person can do, such as signing in to a service. A mod lists those steps in `installer`, and the installer pane shows each one after the permissions and the options, once the mod has started:
+
+```ts
+import { defineStep } from '../node_modules/@cmodjs/core/installer.js'
+
+const signIn = defineStep({
+  id: 'sign-in',
+  title: 'Sign in to GitHub',
+  render: () => <Text>Run gh auth login in a terminal, then press Next.</Text>,
+  isDone: async (mod) => (await mod.process.run(['gh', 'auth', 'status'])).exitCode === 0,
+})
+
+export const ciWatch = defineMod({ name: 'ci-watch', installer: [signIn], setup(mod) { … } })
+```
+
+```ts
+defineStep<State>(step: { id: string; title: string; render(mod, props): RenderElement; isDone(mod): boolean | Promise<boolean> }): Step<State>
+```
+
+- `id` is 1 to 64 letters, digits, `_`, or `-`. `title` is the line above the step, with `(1 of 2)`. `defineStep` throws for either one missing.
+- `render` draws the step's body, the way a pane's `render` does ([ui.md](ui.md)).
+- `isDone` says whether the step is finished. A step that is done is skipped, so the pane opens only for what is left. `Next` checks `isDone`, and shows `Finish <title> first.` while it is false. The last step's button says `Finish`.
+- `Not now` closes the pane and logs `<mod> needs one more step, starting with <title>. Run /mods <mod> to finish.` The mod keeps running. `/mods <mod>` shows `Needs setup: <title>` with a `Finish setup` button, which opens the pane on the first step left.
 
 ## Key bindings
 

package/docs/jobs.md

@@ -167,6 +167,8 @@ A `command` pattern is not a glob. cmod splits it into words the way it splits a
 
 ## permissions
 
+A `deny` rule needs no permission. An `ask` rule takes effect only with `"approve": true` in `package.json` `"cmod".permissions` ([permissions.md](permissions.md)).
+
 ```ts
 permissions<State>(rules: PermissionRules<State> | ((state: State) => PermissionRules<State>)): Job<void, State>
 
@@ -222,6 +224,8 @@ export const guard = defineMod({
 
 ## check
 
+Its command needs `"run"` with the program's name, such as `"run": ["tsc"]` ([permissions.md](permissions.md)).
+
 ```ts
 check<State>(options: { readonly after: Target | Target[]; readonly run: readonly string[]; readonly timeoutMs?: number }): Job<void, State>
 ```
@@ -247,6 +251,8 @@ export const lint = defineMod({
 
 ## prompt
 
+It needs `"prompt": true`. Without the grant it adds nothing and logs once which line to add ([permissions.md](permissions.md)).
+
 ```ts
 prompt<State>(options: {
   name: string
@@ -288,6 +294,8 @@ export const conventions = defineMod({
 
 ## schedule
 
+It needs `"prompt": true`, because each cron starts a turn ([permissions.md](permissions.md)).
+
 ```ts
 schedule<State>(entry: Schedule | ((state: State) => Schedule | undefined)): Job<void, State>
 
@@ -346,6 +354,8 @@ export const usage = defineMod({
 
 ## 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)).
+
 ```ts
 program(options: { readonly command: readonly string[]; readonly environment?: Record<string, string> }): Job<Program>
 
@@ -394,17 +404,20 @@ A `Job` is a function. `mod.use` calls it with a `JobContext` and returns what i
 ```ts
 type JobContext<State> = {
   readonly mod: Mod<State>
-  readonly claude: Claude
-  on<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
   announce(feature: string): void
   reserveName(kind: string, name: string, taken: string): void
   readonly toolCalls: ToolCalls
 }
 ```
 
-- `claude` reaches Claude Code itself. [The claude members](#the-claude-members) lists each one.
-- `claude.store` is where cmod saves `mod.state`, under keys that start with `<mod>.`, such as `<mod>.<key>`. A job of your own never writes those keys, or it changes the mod's state behind cmod's back.
-- `on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.scroll`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. A job with a handler on `tool.check` or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+A job reaches Claude Code through `mod.claude`, the same member every hook has:
+
+- `mod.claude` holds Claude Code's own calls. [The claude members](#the-claude-members) lists each one. Each call checks the permission it needs, as `mod`'s own members do ([permissions.md](permissions.md)).
+- `mod.claude.store` is where cmod saves `mod.state`, under keys that start with `<mod>.`, such as `<mod>.<key>`. A job of your own never writes those keys, or it changes the mod's state behind cmod's back.
+- `mod.claude.on` adds a Claude Code hook-module handler, `(e, next) => …`, on a `classic.<ModEvent>` event or on `tool.check`, `tool.call`, `prompt.submit`, `prompt.context`, `command.run`, `session.measure`, `skill.prompt`, `ui.render`, `ui.press`, `ui.scroll`, `ui.close`, or `cmod.call`. The handler calls `next(e)` to pass the event on. cmod checks what it answers against the person's grants, part by part ([permissions.md](permissions.md#when-a-hook-answer-has-no-grant)). A job with a handler on `tool.check` or `classic.PermissionRequest` needs `registerPermissionCheck` in `hooks/register.ts` ([mod.md](mod.md)).
+
+The context adds what only a job needs:
+
 - `announce` adds a phrase to the list cmod logs when the mod first starts.
 - `reserveName` throws `taken` when the mod already reserved that `kind` and `name`. A job calls it to refuse a duplicate.
 - `toolCalls.agentOf(toolUseId)` resolves `{ agentId?, agentType? }`, the subagent behind a call.
@@ -413,9 +426,9 @@ type JobContext<State> = {
 ```ts
 import { defineMod, type Job } from '../node_modules/@cmodjs/core/mod.js'
 
-const clock: Job<{ now(): Promise<number> }> = ({ claude, announce }) => {
+const clock: Job<{ now(): Promise<number> }> = ({ mod, announce }) => {
   announce('a clock')
-  return { now: () => claude.clock.now() }
+  return { now: () => mod.claude.clock.now() }
 }
 
 export const timer = defineMod({
@@ -433,7 +446,9 @@ export const timer = defineMod({
 
 `mod.js` exports the types `Claude`, `RoutedEvent`, `RoutedHook`, and `ToolCalls`, so a job of your own names them in its own helpers, such as `(claude: Claude, calls: ToolCalls): RoutedHook<'command.run'> => …`.
 
-Each member calls the member of the same name in Claude Code's hooks API, `$`, with the same arguments. The `env` members read `$.env.get` instead.
+Each member calls the member of the same name in Claude Code's hooks API, `$`, with the same arguments. The `env` members read `$.env.get` instead. `mod.claude.on` adds a handler, as [Write a job of your own](#write-a-job-of-your-own) shows.
+
+A member that does what a permission covers checks it first and rejects with the fix: `process` needs `run`, `http.fetch` needs `network`, `fs.write` outside the project and the data folder needs `files` or, for Claude Code's own settings files, `config`, `fs.read` of a transcript needs `conversation`, `session.messages` needs `conversation`, `session.append` and `prompt.submit` need `prompt`, `model.complete` needs `model`, `agent.spawn` needs `agents`, `config.set` needs `config`, and `tool.call` needs `tools`, except `CronCreate`, which needs `prompt`, and `CronList` and `CronDelete`, which need nothing ([permissions.md](permissions.md)).
 
 | Member | What it does |
 | --- | --- |
@@ -454,7 +469,8 @@ Each member calls the member of the same name in Claude Code's hooks API, `$`, w
 | `process.spawn(request)` | Starts a program and streams its output. `mod.process.spawn` is built on it. |
 | `fs.read`, `fs.write`, `fs.list`, `fs.exists`, `fs.stat` | What `mod.fs` calls. A relative path is under the session's working folder. |
 | `http.fetch(url, init?)` | What `mod.http.fetch` calls. |
-| `settings.read(args?)` | What `mod.settings.read` calls. |
+| `settings.read(args?)` | Reads Claude Code's own `settings.json` files. Without `{ source }` it answers every source merged. `user`, `project`, `local`, `flag`, and `policy` each answer one. |
+| `config.list()`, `config.set({ key, value })` | Lists the rows `/config` shows, and changes one, such as `<mod>.<option>`. `set` needs `config`. |
 | `store.get`, `store.set`, `store.delete`, `store.keys` | The plugin's key-value store, where cmod also keeps `mod.state`. |
 | `clock.now()` | Resolves milliseconds since the epoch. |
 | `clock.after(ms, fn)` | Calls `fn` once after `ms` milliseconds, and returns `{ cancel() }`. |

package/docs/mod.md

@@ -5,21 +5,25 @@
 ## defineMod
 
 ```ts
-defineMod<State, Name>(definition: ModDefinition<State, Name>): ModDefinition<State, Name>
+defineMod<State, Name, Options>(definition: ModDefinition<State, Name, Options>): ModDefinition<State, Name, Options>
 ```
 
 ```ts
-type ModDefinition<State, Name> = {
+type ModDefinition<State, Name, Options> = {
   readonly name: Name
   readonly state?: State
+  readonly options?: Options
   readonly api?: { … }
-  setup(mod: Mod<State>): void | Promise<void>
+  readonly installer?: readonly Step<State>[]
+  setup(mod: Mod<State, Options>): void | Promise<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 `state.json` files 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.
+- `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.
+- `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 hooks, panes, slot renders, and jobs. It may be `async`.
 
 ```tsx
@@ -41,14 +45,15 @@ export const greeter = defineMod({
 
 ## When setup runs
 
-Claude Code loads the mod at the start of each session. cmod then checks that the mod is set up. A mod with an install step that has not run waits for the person's consent and the install first ([install-steps.md](install-steps.md)). Then cmod loads the saved state, runs `setup`, and marks as open each of the mod's panes that Claude Code already shows.
+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 version starts, cmod shows the toast `<name> is ready` and logs `<name> added <what setup added>`, such as `the my-mod pane, a render of AbovePrompt and a hook on UserPromptSubmit`.
 
 When a step fails, the mod does not start. Its progress line above the prompt names the failure and the fix:
 
 - `<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 or a `state.json` fails.
+- `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.
 - `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.
 - `it decides permissions on <events>, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod` when `setup` adds a hook on `PermissionRequest`, or a job that decides permissions, and `register.ts` does not register the permission check.
@@ -60,43 +65,45 @@ Each of these says `Fix it, then run /reload-plugins.`
 `hooks/hooks.json` names `hooks/register.ts` as the plugin's hooks module. `register.ts` calls `registerMod` and does nothing else:
 
 ```ts
-import type { On } from 'claude-code'
+import type { On, PluginOptions } from 'claude-code'
 import { registerMod } from '../node_modules/@cmodjs/core/register.js'
 import { greeter } from '../src/mod.js'
 
-export function register(addHook: On): void {
-  registerMod(addHook, greeter)
+export function register(addHook: On, options: PluginOptions): void {
+  registerMod(addHook, greeter, options)
 }
 ```
 
 ```ts
-registerMod<State>(addHook: On, definition: ModDefinition<State>): void
+registerMod<State, Options>(addHook: On, definition: ModDefinition<State, string, Options>, options: PluginOptions): void
 registerPermissionCheck(addHook: On): void
+registeredMod(): ModDefinition | undefined
 ```
 
-`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. A `PreToolUse` hook runs on `tool.call`, which `registerMod` registers ([hooks.md](hooks.md)). It leaves out Claude Code's permission check, the events `tool.check` and `PermissionRequest`.
+`registerMod` registers one handler per Claude Code event the mod can use, and routes each event to the mod. `options` is what Claude Code passes `register`: the values of the mod's options ([options.md](options.md)). `registeredMod` returns the definition `registerMod` got, for `cmod check` to read the mod's options without starting it. A `PreToolUse` hook runs on `tool.call`, which `registerMod` registers ([hooks.md](hooks.md)). It leaves out Claude Code's permission check, the events `tool.check` and `PermissionRequest`.
 
 A mod that decides permissions calls `registerPermissionCheck` after `registerMod`. That covers a `PreToolUse` hook that answers `permissionDecision: 'allow'` or `'ask'`, a hook on `PermissionRequest`, the `permissions` job, and a job of your own on `tool.check`:
 
 ```ts
-export function register(addHook: On): void {
-  registerMod(addHook, guard)
+export function register(addHook: On, options: PluginOptions): void {
+  registerMod(addHook, guard, options)
   registerPermissionCheck(addHook)
 }
 ```
 
-A mod without it has no part in Claude Code's permission check, so the plugin directory reads it as one that never answers a permission. A mod that decides permissions without it does not start, and its progress line names the line to add.
+Such a mod also declares `"approve": true` in its `package.json` `"cmod".permissions`, so the person grants it at install. `cmod check` adds the line when it is missing, and without the grant cmod drops every allow or ask the mod answers, so Claude Code decides those calls itself ([permissions.md](permissions.md)). A mod without `registerPermissionCheck` has no part in Claude Code's permission check, so the plugin directory reads it as one that never answers a permission. A mod that decides permissions without it does not start, and its progress line names the line to add.
 
 Keep `register.ts` this small. Claude Code checks a hooks module before it loads it, and refuses some shapes, such as a `$` passed to a function in another module. The plugin directory reads the bundled module too, and flags it when the name of `register`'s first parameter is declared anywhere else in the bundle. `@cmodjs/core` declares `on` as the method `mod.on`, so name that parameter `addHook`. Declare `register` as a function, as here: `cmod publish` bundles the hooks module into one file, and Claude Code refuses a bundled `register` that is not one.
 
 ## What `mod` can call
 
-`setup` gets `mod`, of type `Mod<State>`. Every hook, render, and job gets the same `mod`.
+`setup` gets `mod`, of type `Mod<State, Options>`. Every hook, render, and job gets the same `mod`.
 
 ```ts
-type Mod<State> = {
+type Mod<State, Options> = {
   readonly name: string
   readonly state: Readonly<State>
+  readonly options: OptionValues<Options>
   readonly dataFolder: string
   readonly projectRoot: string
   readonly cwd: string
@@ -105,13 +112,16 @@ type Mod<State> = {
   every(ms, hook): Timer
   readonly ui: { pane, render, toast, progress, ask, scroll }
   readonly process: { run, spawn }
-  readonly fs: { read, write, list, exists, stat }
+  readonly fs: { read, write, list, exists, stat, find }
+  readonly metadata: { read, update }
   readonly http: { fetch }
-  readonly settings: { read }
+  readonly settings: { page, open }
   readonly session: { messages, append, submit }
   readonly agent: { spawn }
   readonly model: { complete }
+  readonly permissions: { has }
   readonly dependencies: CmodDependencies
+  readonly claude: ModClaude
 }
 ```
 
@@ -119,6 +129,7 @@ type Mod<State> = {
 | --- | --- | --- |
 | `name` | The mod's name from `defineMod`. | |
 | `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) |
 | `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) |
 | `projectRoot` | The project the session works in. It follows `/cd`. | |
 | `cwd` | The session's working folder. It follows a `cd` in a Bash or PowerShell call, and `/cd`. | |
@@ -127,13 +138,16 @@ type Mod<State> = {
 | `every` | Runs a function every so many milliseconds while the session runs. | below |
 | `ui` | Panes, slot renders, toasts, progress lines, questions, and scrolling. | [ui.md](ui.md) |
 | `process` | Runs a program. | below |
-| `fs` | Reads, writes, and looks up files. | below |
+| `fs` | Reads, writes, looks up, and finds files. | below |
+| `metadata` | Reads and changes the mod's keys in one file's metadata. | below |
 | `http` | Fetches a URL. | below |
-| `settings` | Reads Claude Code's settings. | below |
+| `settings` | Adds the mod's own pages to `/mods`, and opens them. | below |
 | `session` | Reads the conversation or a subagent's, adds a note Claude reads, and asks Claude for a turn. | below |
 | `agent` | Starts a subagent. | below |
 | `model` | Asks a model one question, outside the conversation. | below |
+| `permissions` | Says whether the person has a permission turned on. `process`, `fs.write`, `metadata.update`, `http`, `session`, `agent`, `model`, and `claude` each check theirs. | [permissions.md](permissions.md) |
 | `dependencies` | Calls the methods of other mods. | [dependencies.md](dependencies.md) |
+| `claude` | Claude Code's own calls and events, for what `mod` has no member for. | [jobs.md](jobs.md#the-claude-members) |
 
 ### mod.every
 
@@ -195,6 +209,7 @@ mod.fs.write(path: string, text: string): Promise<void>
 mod.fs.list(path?: string): Promise<FsEntry[]>
 mod.fs.exists(path: string): Promise<boolean>
 mod.fs.stat(path: string, options?: { resolve: boolean }): Promise<FsStat>
+mod.fs.find(glob: string | readonly string[]): Promise<readonly FileMatch[]>
 ```
 
 - A relative path is under the session's working folder. An absolute path is used as given. Text is UTF-8.
@@ -204,7 +219,64 @@ mod.fs.stat(path: string, options?: { resolve: boolean }): Promise<FsStat>
 - `exists` answers whether the path leads to a file or a folder.
 - `stat` answers `{ kind, size, mtimeMs, isLink }` of 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.
 
-A file the mod ships is under the plugin's folder. `mod` has no member that names that folder, so a job of your own reads it from `claude.plugin.root` ([jobs.md](jobs.md#the-claude-members)). A file the mod keeps for itself belongs in `mod.dataFolder`.
+A file the mod ships is under the plugin's folder, `mod.claude.plugin.root` ([jobs.md](jobs.md#the-claude-members)). A file the mod keeps for itself belongs in `mod.dataFolder`.
+
+`find` answers every file a glob matches, each with its metadata, so a mod finds the Skills, agents, scripts, or notes it acts on in one call:
+
+```ts
+type FileMatch = { readonly path: string; readonly name?: string; readonly metadata: Readonly<Record<string, string>>; readonly error?: string }
+```
+
+- A glob starting with `~/.claude` starts at Claude Code's config folder, `CLAUDE_CONFIG_DIR` when it is set. One starting with `~/` starts at home, one starting with `/` is absolute, and any other starts at the project root. Several globs answer each file once.
+- `path` is absolute. `name` is a Markdown file's frontmatter `name`. `metadata` holds the mod's own keys, bare, as `mod.metadata.read` answers them.
+- `find` follows symbolic links into the folders they point at, once each. It skips `.git` and `node_modules` unless the glob names them.
+- A file whose metadata cmod cannot read comes back with empty `metadata` and an `error` naming the line, and cmod logs it once.
+- cmod keeps what it read of each file until the file's modified time or size changes.
+
+```ts
+const skills = await mod.fs.find(['~/.claude/skills/*/SKILL.md', '.claude/skills/*/SKILL.md'])
+const planning = skills.filter((skill) => skill.metadata['modes']?.split(' ').includes('plan'))
+```
+
+### mod.metadata
+
+```ts
+mod.metadata.read(path: string): Promise<Readonly<Record<string, string>>>
+mod.metadata.update(path: string, change: (metadata: Record<string, string>) => void): Promise<void>
+```
+
+Metadata is a file's own set of string keys, kept in the file, so it moves and is committed with the file. Each mod reads and writes its own keys only: the file stores them as `<mod>.<key>`, and the mod sees them bare. A value is one line of text, and a list is one space-separated string.
+
+Where a file keeps its metadata depends on its kind:
+
+```markdown
+---
+name: plan
+metadata:
+  modes.modes: plan build
+---
+```
+
+```sh
+#!/bin/sh
+# /// metadata
+# modes.modes: plan build
+# ///
+```
+
+- A Markdown file keeps it in its frontmatter, under `metadata:`.
+- A `.sh`, `.py`, `.ts`, `.js`, `.yaml`, or `.toml` file keeps it in a `/// metadata` comment block after any shebang, in the file's own comment, `#` or `//`, the way PEP 723 keeps a Python script's dependencies.
+- Any other file keeps it in a sidecar, `<file>.meta`.
+
+`update` hands `change` the mod's current keys, and writes what `change` leaves. It changes only the metadata block, keeps other mods' keys, writes nothing when nothing changed, and removes an empty block. It writes through a symbolic link to the file it points at. Writing a file outside the project and the mod's data folder needs the `files` permission, as `mod.fs.write` does ([permissions.md](permissions.md)). A key is letters, digits, `_`, `.`, and `-`, and `update` rejects any other key and a value with a line break.
+
+```ts
+await mod.metadata.update('.claude/skills/plan/SKILL.md', (metadata) => {
+  metadata['modes'] = 'plan build'
+})
+```
+
+`cmod check` reads the metadata of every file the mod ships, and fails one cmod cannot read.
 
 ### mod.http
 
@@ -218,35 +290,29 @@ mod.http.fetch(url: string, init?: HttpInit): Promise<HttpResponse>
 ### mod.settings
 
 ```ts
-mod.settings.read(args?: { source?: 'user' | 'project' | 'local' | 'flag' | 'policy' }): Promise<Settings>
+mod.settings.page(page: Pane<State>): void
+mod.settings.open(pageId?: string): Promise<void>
 ```
 
-Without a `source` it answers the settings Claude Code runs under, every source merged. With a `source` it answers that one source: `user` is `~/.claude/settings.json`, `project` is `.claude/settings.json`, and `local` is `.claude/settings.local.json`. The answer is keyed as a `settings.json` is, such as `permissions`, `env`, and `enabledPlugins`.
+`/mods` shows each mod's options, permissions, and keys. `page` adds a page of the mod's own to its entry there, drawn as any pane is ([ui.md](ui.md)). `open` opens that page, or with no id opens the mod's entry in `/mods`. `open` rejects for an id `page` did not add.
 
-```ts
-import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
-
-export const pluginCount = defineMod({
-  name: 'plugin-count',
-  setup(mod) {
-    mod.on('SessionStart', async () => {
-      const enabled = (await mod.settings.read({ source: 'user' }))['enabledPlugins'] as Record<string, unknown> | undefined
-      mod.ui.toast(`${Object.keys(enabled ?? {}).length} plugins are enabled`)
-    })
-  },
-})
+```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') }))
 ```
 
+Claude Code's own `settings.json` files are read with `mod.claude.settings.read`, such as `(await mod.claude.settings.read({ source: 'user' }))['enabledPlugins']` ([jobs.md](jobs.md#the-claude-members)).
+
 ### mod.session
 
 ```ts
 mod.session.messages(): Promise<SessionMessage[]>
-mod.session.messages(args: { agentId?: string; as?: 'api' }): Promise<…>
+mod.session.messages(args: { agentId: string }): Promise<SessionMessage[] | { deny: string }>
 mod.session.append(text: string): Promise<void>
 mod.session.submit(text: string): Promise<void>
 ```
 
-`messages` reads the main conversation, one `{ role, text, toolUses, toolResults }` entry per message. A message has no id of its own, and each tool use carries its `tool_use_id`. `{ agentId }` reads that subagent's conversation instead, the id a `SubagentStart` or `SubagentStop` hook gets as `agent_id`, and answers `{ deny }` when the session cannot read it, so `Array.isArray` tells the two apart. `{ as: 'api' }` reads it in the Messages API form, `{ role, content }` with the content blocks whole.
+`messages` reads the main conversation, one `{ role, text, toolUses, toolResults }` entry per message. A message has no id of its own, and each tool use carries its `tool_use_id`. `{ agentId }` reads that subagent's conversation instead, the id a `SubagentStart` or `SubagentStop` hook gets as `agent_id`, and answers `{ deny }` when the session cannot read it, so `Array.isArray` tells the two apart. The Messages API form, `{ role, content }` with the content blocks whole, is `mod.claude.session.messages({ as: 'api' })`.
 
 ```ts
 mod.on('SubagentStop', async ({ agent_id }) => {