@cmodjs/core 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @cmodjs/core
 
-The library Claude Code mods import. CMod is the Claude Mod Manager: it installs, tries, builds, checks, and publishes Claude Code mods, which are plugins with hooks, panes, commands, tools, permissions, and an install step that runs with your consent.
+The library every Claude Mod Manager mod imports. Claude Mod Manager (CMod) installs, tries, builds, checks, and publishes Claude Code mods: plugins with hooks, panes, slash commands, tools, permission rules, and an install step that runs with your consent.
 
 ```sh
 npm i -g @cmodjs/cli
@@ -9,4 +9,8 @@ cmod new my-mod
 
 `cmod new` writes a mod that depends on this package. A mod imports it by path, such as `../node_modules/@cmodjs/core/mod.js`, because Claude Code loads a plugin's own files only.
 
-The guide and the CMod plugin live at [github.com/heyJordanParker/cmod](https://github.com/heyJordanParker/cmod).
+## Docs
+
+This package ships its docs in `docs/`, so a mod's `node_modules/@cmodjs/core/docs/index.md` is the map of the docs for the version it installed. The same docs are on GitHub at [core/docs](https://github.com/heyJordanParker/cmod/blob/main/core/docs/index.md).
+
+The CMod plugin and the `cmod` source live at [github.com/heyJordanParker/cmod](https://github.com/heyJordanParker/cmod).

package/docs/commands.md

@@ -0,0 +1,175 @@
+# cmod commands
+
+The `cmod` command of Claude Mod Manager (CMod) builds, checks, and publishes mods, and installs them. `npm i -g @cmodjs/cli` puts it on `PATH`. `cmod <command> --help` prints a command's arguments, and `cmod --version` prints the version.
+
+Each command below restates what `cmod <command> --help` prints, for a mod author. The help text is the full word.
+
+## Build a mod
+
+### cmod new
+
+```text
+cmod new <name> [--project]
+```
+
+Creates a mod in `./<name>`: a `defineMod` with one hook, one pane, and one render of the band above the prompt, a Skill, and a test. Then installs its packages.
+
+- `<name>` is lowercase letters, digits, and `-`, starting with a letter.
+- `--project` creates a project-scope plugin in `./.claude/skills/<name>/` of the repository in the current folder, which loads for everyone who trusts the repository. Run it in the repository's root.
+- `CMOD_CORE` sets the `@cmodjs/core` dependency it writes. By default it writes `^<the version of this cmod>`. To build against an unreleased `@cmodjs/core`, point it at a packed tarball, such as `file:/path/to/cmodjs-core-<version>.tgz`. Only a `.tgz` works: a folder installs as links into that folder, and `claude plugin validate --strict` refuses the mod.
+- When the packages fail to install, it deletes the new folder.
+
+### cmod link
+
+```text
+cmod link [path] [--yes]
+```
+
+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.
+
+### cmod unlink
+
+```text
+cmod unlink [path]
+```
+
+Stops loading the checkout at `path` (default: the current folder) in new Claude Code sessions. Removes the folder from `CLAUDE_CODE_PLUGIN_DIRS` in Claude Code's `settings.json`, runs the checkout's uninstall step, and removes the program `cmod link` built into `~/.local/bin`.
+
+### cmod check
+
+```text
+cmod check [path]
+```
+
+Runs every check this machine can run on the mod at `path` (default: the current folder), each failure with its fix:
+
+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.
+6. Validates it with Claude Code, `claude plugin validate --strict`.
+7. Type-checks it with `tsc`. It skips this until `.claude-plugin/types/` exists, which Claude Code writes the first time a session loads the mod: run `cmod link`, start `claude` once, then run `cmod check` again.
+8. Lints it with `oxlint`.
+9. Runs, with `bun test`, every test file that does not import `claude-code/testing`.
+10. Runs, with `claude plugin test`, the test files that import `claude-code/testing`. It skips this when none does.
+11. 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] [-- claude arguments]
+```
+
+Starts one throwaway Claude Code session with a mod set up. Installs the mod's packages, installs the CMod plugin when Claude Code lacks it, and runs the mod's install step after asking consent. Then starts one Claude Code session with the mod loaded through `--plugin-dir`.
+
+- Unlike `cmod link`, it builds no program from `cli/`. A mod whose `package.json` `cmod.program` names a program downloads it from the GitHub release of the mod's version, so it fails until `cmod publish` has released that version.
+
+- When the session ends, even when its terminal closes, it runs the mod's uninstall step and deletes its record, data folder, approval, and program, so the mod stays uninstalled. A checkout already set up from the same folder keeps its setup.
+- A GitHub mod is cloned into a temporary folder, which is deleted too.
+- A mod another folder has set up is refused, so `cmod try` never replaces an installed copy.
+- Arguments after `--` go to `claude`, such as `-- -p "hello"`.
+
+### cmod publish
+
+```text
+cmod publish [path] [--dry-run]
+```
+
+Releases the mod at `path` (default: the current folder) at the version in its `plugin.json`:
+
+1. Builds the release archive from the committed files with `git archive`, leaving out `cli/`.
+2. Builds the program `cli/` declares.
+3. Writes `SHA256SUMS` for every file of the release.
+4. Writes `.claude-plugin/marketplace.json`, listing the archive and the CMod plugin.
+5. Commits that file, tags `v<version>`, pushes, and creates the GitHub release.
+
+It needs, and refuses to start without:
+
+- the mod's folder as the root of a git repository with at least one commit, because `git archive` builds from `HEAD`
+- an `origin` remote on GitHub
+- a `package.json` with no dependency on a `file:` or `link:` path, which no user has
+- a `"program"` in the `cmod` key of `package.json` that names the program `cli/` declares, when `cli/` declares one
+- the network, to hash the CMod plugin release it lists, unless the mod is CMod itself
+- for a real publish, a working tree with no uncommitted changes, a `v<version>` tag that does not exist yet, a `git push` to `origin` that succeeds, and the `gh` command, which creates the GitHub release
+
+`--dry-run` builds and writes everything, and pushes nothing. It allows uncommitted changes and an existing tag, and builds from the last commit.
+
+## Install mods
+
+### cmod install
+
+```text
+cmod install <owner/repo | path> [name] [--yes]
+cmod install <name | name@marketplace> [--yes]
+```
+
+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.
+
+- When the marketplace lists several plugins, name the one to install after it.
+- Given `name@marketplace` of a marketplace Claude Code has added, it installs that plugin.
+- 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.
+
+### cmod update
+
+```text
+cmod update [name] [--yes]
+```
+
+Updates the named plugin, or every plugin Claude Code has installed, through Claude Code, then runs the install step of each mod whose version or scripts changed. A linked plugin is skipped, because saving its files updates it. When Claude Code fails to update a plugin, `cmod update` names it, updates the rest, and exits 1. A running session loads the new version after `/reload-plugins`.
+
+- `--yes` approves changed install and uninstall commands without asking.
+
+### cmod remove
+
+```text
+cmod remove <name>
+```
+
+Uninstalls the plugin through Claude Code. When CMod set the plugin up as a mod, it then runs the uninstall step CMod saved and removes what CMod set up.
+
+### cmod list
+
+```text
+cmod list
+```
+
+Lists every plugin Claude Code has installed or linked, with its version. A mod shows whether CMod set it up, and any other plugin shows whether Claude Code enabled it. It also lists every mod Claude Code removed whose uninstall step has not run yet.
+
+- The `cmod` commands count a plugin as a mod only when its `package.json` has a `cmod` step key or CMod holds an install record for it. A mod made with `cmod new` has neither until its first Claude Code session sets it up, so until then `cmod list` shows it as `enabled`, like any other plugin.
+
+## Run in an install script
+
+### cmod download
+
+```text
+cmod download <program> <machine> <url> <sha256> [<machine> <url> <sha256> …]
+```
+
+Downloads a program for an install script: fetches the download for this machine, checks its SHA-256, unpacks it, and moves `<program>` to `$CMOD_DATA/bin/<program>`. [install-steps.md](install-steps.md) explains it.
+
+## 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 setup
+
+```text
+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.
+
+### cmod teardown
+
+```text
+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.

package/docs/dependencies.md

@@ -0,0 +1,102 @@
+# Call another mod
+
+A mod offers methods to other mods in `api`. Another mod lists it as a dependency and calls those methods through `mod.dependencies`, typed from the provider's own types file.
+
+## Offer methods: api
+
+Each method of `api` gets the caller's input and the provider's own `mod`, and returns its result or a promise of it. Inputs and results cross from one plugin to another, so keep them plain JSON data.
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const tracer = defineMod({
+  name: 'tracer',
+  api: {
+    signatures: async ({ path }: { path: string }, mod) =>
+      (await mod.fs.read(path)).split('\n').flatMap((text, index) => {
+        const name = /^export function (\w+)/.exec(text)?.[1]
+        return name === undefined ? [] : [{ name, line: index + 1 }]
+      }),
+  },
+  setup() {},
+})
+```
+
+## Type the methods: CmodDependencies
+
+The provider types its `api` in `types/index.d.ts`, and its `.claude-plugin/plugin.json` names that file as `"types": "./types/index.d.ts"`. The file adds the mod to `CmodDependencies`, which the Claude Mod Manager (CMod) plugin declares on the `claude-code` module:
+
+```ts
+export type TracerSignature = { name: string; line: number }
+
+export type Tracer = {
+  signatures(input: { path: string }): Promise<TracerSignature[]>
+}
+
+declare module 'claude-code' {
+  interface CmodDependencies {
+    tracer: Tracer
+  }
+}
+```
+
+- Each method takes one input and returns a promise.
+- Once the name is in `CmodDependencies`, `tsc` checks the provider's own `api` against it, so a method that returns another shape fails `cmod check`.
+- A types file augments only `'claude-code'`. Claude Code refuses a types file that augments any other module.
+
+## Call the methods: mod.dependencies
+
+A mod that calls tracer lists it in its own `.claude-plugin/plugin.json`, and Claude Code installs it with the mod:
+
+```json
+"dependencies": ["cmod", "tracer"]
+```
+
+Claude Code then lays tracer's types file beside the mod's own types, so the call is typed:
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+import { slashCommand } from '../node_modules/@cmodjs/core/jobs/slash-command.js'
+
+export const outline = defineMod({
+  name: 'outline',
+  setup(mod) {
+    mod.use(
+      slashCommand({
+        name: 'outline',
+        description: 'List the functions a file exports',
+        reply: async ({ args }, mod) => {
+          const signatures = await mod.dependencies.tracer.signatures({ path: args })
+          return signatures.map(({ name, line }) => `${name}:${line}`).join('\n')
+        },
+      }),
+    )
+  },
+})
+```
+
+## When a call fails
+
+A call that cannot answer rejects with one of these messages:
+
+```text
+tracer is not installed. Run cmod install tracer.
+tracer is installing. Try again when it's ready.
+tracer has no method signatures.
+tracer: <the message of the error the method threw>
+```
+
+- `tracer is not installed` covers a provider whose code did not load, one the person declined to install, and one whose install failed.
+- `tracer is installing` covers a provider that is still running its install step.
+- When tracer is disabled, Claude Code unloads the mod that lists it, with its own error: `Dependency "tracer" is disabled — enable it or remove the dependency`.
+- A call runs inside the deadline of the job that makes it ([jobs.md](jobs.md)), and 30 seconds anywhere else. Past the deadline of a job, the call fails with `mod.dependencies.tracer.signatures passed the 30 s deadline of slashCommand`, naming the job. Anywhere else it fails with `mod.dependencies.tracer.signatures passed its 30 s deadline`.
+
+```ts
+notInstalled(name: string): string
+```
+
+`notInstalled`, exported from `mod.js`, returns the first message for a mod name: `<name> is not installed. Run cmod install <name>.` A test uses it to expect that message.
+
+## Test the calls
+
+`testMod(outline, { dependencies: { tracer: { signatures: async () => [] } } })` answers tracer's methods with the functions given. A call to a mod the test does not fake fails with `tracer is not installed. Run cmod install tracer.` [testing.md](testing.md) covers it.

package/docs/hooks.md

@@ -0,0 +1,156 @@
+# Hooks
+
+`mod.on` runs a function when Claude Code raises an event, such as a prompt or a tool call. The function reads the event's input and may answer to change what Claude Code does next.
+
+## mod.on
+
+```ts
+mod.on<E extends ModEvent>(event: E, hook: ModHook<E>): void
+
+type ModHook<E> = (input: HookInputs[E]) => HookAnswer | void | Promise<HookAnswer | void>
+```
+
+Add hooks in `setup`. Each `mod.on` adds one more hook. Several hooks on one event all run.
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const safeDelete = defineMod({
+  name: 'safe-delete',
+  setup(mod) {
+    mod.on('PreToolUse', (input) => {
+      const command = input.tool_input['command']
+      if (input.tool_name !== 'Bash' || typeof command !== 'string' || !command.startsWith('rm ')) return
+      return { hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput: { ...input.tool_input, command: command.replace(/^rm /, 'trash ') } } }
+    })
+  },
+})
+```
+
+## Every ModEvent
+
+`ModEvent` names the 17 events a mod hooks. The input of each is the hook input a `settings.json` hook reads for that event, typed as `ClassicHookInputs['<event>']` in the `claude-code` module, with the changes this table names.
+
+| Event | Input changes |
+| --- | --- |
+| `SessionStart` | none |
+| `SessionEnd` | none |
+| `UserPromptSubmit` | none |
+| `InstructionsLoaded` | none |
+| `PreToolUse` | Claude Mod Manager (CMod) builds the input: `session_id`, `cwd`, `hook_event_name`, `tool_name`, `tool_input`, `tool_use_id`, `agent_id` inside a subagent, `agent_type` inside a subagent or when the session started as an agent, and `files`. It has no `transcript_path` and no `permission_mode`. |
+| `PermissionRequest` | none |
+| `PermissionDenied` | none |
+| `PostToolUse` | adds `files` |
+| `PostToolUseFailure` | adds `files` |
+| `PostToolBatch` | none |
+| `SubagentStart` | none |
+| `SubagentStop` | none |
+| `Notification` | none |
+| `PreCompact` | none |
+| `Stop` | none |
+| `StopFailure` | none |
+| `CwdChanged` | no `transcript_path` |
+
+CMod raises `CwdChanged` itself, never Claude Code. It raises it when the working folder changes: after `/cd`, after a Bash or PowerShell call, and at a prompt. `mod.cwd` and `mod.projectRoot` already hold the new folder when the hook runs.
+
+## files: what a tool call reads and changes
+
+The input of `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` has `files: { read: string[]; changed: string[] }`, absolute paths that CMod works out from the call:
+
+- `Read` reads its `file_path`. `Edit`, `Write`, and `NotebookEdit` change their path.
+- `Grep` counts its `path`, or the working folder when it names none, and `Glob` counts its `pattern` joined to its `path`. Since `read` lists only files, a `Grep` of a folder and every `Glob` usually leave `read` empty.
+- A `Bash` command reads and changes the files its commands name, such as `cat a.ts > b.ts`. A path that holds a shell expansion, such as `$HOME`, is left out.
+- `read` lists only paths that are files now. `changed` lists every path the call writes, whether it exists or not.
+- When CMod cannot work the files out, both lists are empty, and the reason goes to Claude Code's debug log.
+
+## HookAnswer: what a hook can answer
+
+Return nothing to leave the event as it is. Return a `HookAnswer` to change it. The fields are the ones a `settings.json` hook writes as JSON:
+
+```ts
+type HookAnswer = {
+  continue?: boolean
+  stopReason?: string
+  suppressOutput?: boolean
+  systemMessage?: string
+  decision?: 'block'
+  reason?: string
+  hookSpecificOutput?: {
+    hookEventName?: ModEvent
+    additionalContext?: string
+    permissionDecision?: 'allow' | 'deny' | 'ask'
+    permissionDecisionReason?: string
+    updatedInput?: Record<string, unknown>
+    sessionTitle?: string
+    suppressOriginalPrompt?: boolean
+    initialUserMessage?: string
+    watchPaths?: string[]
+    reloadSkills?: boolean
+    decision?: PermissionRequestDecision
+    updatedToolOutput?: unknown
+    updatedMCPToolOutput?: unknown
+    retry?: boolean
+  }
+}
+```
+
+- `continue: false` stops the session after the event, and `stopReason` is the text Claude Code shows. `PreToolUse` takes neither.
+- `decision: 'block'` with a `reason` blocks the event. On `PreToolUse` it denies the call with the reason. On `Stop` it keeps Claude going with the reason.
+- `systemMessage` shows the text to the person as a log line.
+- CMod ignores `suppressOutput`.
+- `hookSpecificOutput.hookEventName` is optional. When set, it must be the event's own name.
+
+Each event reads only some `hookSpecificOutput` fields:
+
+| Event | `hookSpecificOutput` fields it reads |
+| --- | --- |
+| `SessionStart` | `additionalContext`, `initialUserMessage`, `sessionTitle`, `watchPaths`, `reloadSkills` |
+| `UserPromptSubmit` | `additionalContext`, `sessionTitle`, `suppressOriginalPrompt` |
+| `PreToolUse` | `additionalContext`, `permissionDecision`, `permissionDecisionReason`, `updatedInput` |
+| `PermissionRequest` | `decision` |
+| `PermissionDenied` | `retry` |
+| `PostToolUse` | `additionalContext`, `updatedToolOutput`, `updatedMCPToolOutput` |
+| `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, `Stop` | `additionalContext` |
+| `SessionEnd`, `InstructionsLoaded`, `Notification`, `PreCompact`, `StopFailure`, `CwdChanged` | none |
+
+A field the event does not read is an error: `it answered hookSpecificOutput.<field>, which <event> does not read. Remove it from the answer.` A flag set to `false`, such as `retry: false`, counts as unset.
+
+## How answers combine
+
+Every mod's hooks and Claude Code's own `settings.json` hooks answer the same event.
+
+- `additionalContext` from every hook reaches Claude, each in turn.
+- On `PreToolUse` the strictest decision wins: `deny` over `ask` over `allow`. A mod's `allow` never overrides a `deny` from another hook.
+- For every other field, the mod's answer replaces the answer of the hooks beneath it.
+
+```ts
+import { defineMod } from '../node_modules/@cmodjs/core/mod.js'
+
+export const keepGoing = defineMod({
+  name: 'keep-going',
+  state: { session: { hasCheckedTests: false } },
+  setup(mod) {
+    mod.on('Stop', () => {
+      if (mod.state.session.hasCheckedTests) return
+      mod.state.session.hasCheckedTests = true
+      return { decision: 'block', reason: 'Run the tests before you stop.' }
+    })
+  },
+})
+```
+
+## When a hook fails
+
+A hook that throws, rejects, or answers a field its event does not read fails:
+
+- On `PreToolUse` the call is denied with `<mod>: the PreToolUse hook failed: <error>`.
+- On `PermissionRequest` the request is denied with `<mod>: the PermissionRequest hook failed: <error>`.
+- On every other event CMod logs `<mod>: the <event> hook failed: <error>`, and the event goes on as if the hook answered nothing.
+
+## The first SessionStart
+
+A mod that is still installing when the session starts misses Claude Code's `SessionStart`. CMod holds `SessionStart` up to 9 seconds for the mod to start. When the mod starts later, CMod runs its `SessionStart` hooks then, and Claude Code no longer reads their answer.
+
+## Test a hook
+
+`tested.fire(event, input)` runs the mod's hooks on an event and returns the combined answer. It fills `session_id`, `transcript_path`, `cwd`, `hook_event_name`, and `tool_use_id`, so a test gives only the event's own fields. [testing.md](testing.md) covers it.

package/docs/index.md

@@ -0,0 +1,101 @@
+# Claude Mod Manager docs
+
+These are the docs of the `@cmodjs/core` version installed beside them. Read them before you write mod code. They match this version, and memory of another version does not.
+
+## What a mod is
+
+A mod is a Claude Code plugin built with `@cmodjs/core`. Claude Mod Manager (CMod) installs mods, runs their install and uninstall steps with the person's consent, and builds and publishes new ones. The `cmod` command does that work in a terminal.
+
+`cmod new my-mod` writes this layout:
+
+```text
+my-mod/
+├── .claude-plugin/plugin.json          name, version, and "dependencies": ["cmod"]
+├── .claude/CLAUDE.md                   facts for coding agents, starting with these docs
+├── .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                   connect(on, myMod), 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
+├── src/components/prompt-count.tsx     what the panes and slot renders draw with
+├── skills/my-mod/SKILL.md              a Skill the mod ships
+├── tests/mod.test.ts                   testMod tests, run with bun test
+├── package.json                        depends on @cmodjs/core
+└── tsconfig.json                       extends .claude-plugin/types/tsconfig.json, with the JSX options
+```
+
+`cmod new --project` writes the same files, less `.claude/CLAUDE.md`, into `.claude/skills/<name>/` of the repository.
+
+The template is a working example to replace. It counts the prompts of the session in `state.session.prompts`, shows the count in a pane titled with the mod's name and above the prompt, and tests both. Replace the counter, the pane, the component, the Skill, and the tests with the mod's own.
+
+A mod imports `@cmodjs/core` by path, such as `../node_modules/@cmodjs/core/mod.js`, because Claude Code loads a plugin's own files only. Types such as `RenderElement` and `Register` come from the `claude-code` module.
+
+## Type-check after the first session
+
+Claude Code writes `.claude-plugin/types/` the first time a session loads the mod. That folder holds the `tsconfig.json` the mod's own extends, the `claude-code` module, and the `h` JSX global. Until it exists, `tsc` fails, and `cmod check` skips its type check. Run `cmod link`, start `claude` once, then type-check. A project plugin needs no link: start `claude` in its repository and trust it.
+
+## Where a mod runs
+
+Mod code runs inside Claude Code's hooks environment, not in Node or Bun. It has no Node or Bun modules, no DOM, and no `import()`. `mod.fs` reaches files, `mod.process` runs programs, and `mod.http` reaches the network ([mod.md](mod.md)). A job of your own also reaches the plugin's folder through `claude.plugin.root` and timers through `claude.clock` ([jobs.md](jobs.md)).
+
+`cmod check` fails a mod that breaks this:
+
+- a file in `src/` that imports a Node module, `bun`, or a `bun:` module. Tests in `tests/` run under `bun test` and may import `bun:test`.
+- a file that imports from `cli/`, which the release leaves out
+- `devDependencies` in `package.json`. Claude Code installs them for every person, so move each into `dependencies` or drop it.
+- a `bin/` or `target/` folder at the mod's root
+- a prebuilt binary in the mod, outside `cli/`, `node_modules/`, `.git/`, `target/`, `.target/`, and `.claude-plugin/types/`
+
+A program the mod needs lives as source in `cli/`. `cmod publish` builds it and attaches the builds to the release ([install-steps.md](install-steps.md)).
+
+## Which file answers which question
+
+| Question | File |
+| --- | --- |
+| How do I define a mod, and what can `mod` call? | [mod.md](mod.md) |
+| How do I keep values across prompts, sessions, and projects? How does a person change them? | [state.md](state.md) |
+| 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 status line, or a background program? | [jobs.md](jobs.md) |
+| How does one mod call another? | [dependencies.md](dependencies.md) |
+| How does a mod change the machine, ship a program, or clean up after itself? | [install-steps.md](install-steps.md) |
+| How do I test a mod without Claude Code? | [testing.md](testing.md) |
+| Which `cmod` command links, checks, tries, or publishes a mod? | [commands.md](commands.md) |
+
+## The Public API
+
+A mod imports from the files below, and every other file in this package is internal. A few of their exports serve the library itself, and their docs say so, such as `drawWith` in [ui.md](ui.md).
+
+| Import | Exports | Docs |
+| --- | --- | --- |
+| `mod.js` | `defineMod`, `ModDefinition`, `Mod`, `PartContext`, `Part`, `ProgressStep`, `PaneHandle`, `longestMs`, `messageOf` | [mod.md](mod.md), [jobs.md](jobs.md), [ui.md](ui.md) |
+| `mod.js` | `ModEvent`, `ModHook`, `HookAnswer` | [hooks.md](hooks.md) |
+| `mod.js` | `notInstalled` | [dependencies.md](dependencies.md) |
+| `connect.js` | `connect` | [mod.md](mod.md) |
+| `testing.js` | `testMod`, `TestOptions`, `TestInput`, `TestedMod`, `Fakes`, `Shown`, `TestCall` | [testing.md](testing.md) |
+| `ui/define-pane.js` | `definePane`, `Pane` | [ui.md](ui.md) |
+| `ui/elements.js` | `Box`, `Text`, `Button`, `Link`, `Code`, `Markdown`, `Input`, `Select`, `Image`, `drawWith` | [ui.md](ui.md) |
+| `ui/slots.js` | `slots`, `Slot`, `SlotProps` | [ui.md](ui.md) |
+| `ui/markdown.js` | `markdownSlots`, `markdownBlocks`, `MarkdownKind`, `MarkdownReader`, `MarkdownPiece` | [ui.md](ui.md) |
+| `jobs/slash-command.js` | `slashCommand`, `Reply` | [jobs.md](jobs.md) |
+| `jobs/tool.js` | `tool` | [jobs.md](jobs.md) |
+| `jobs/permissions.js` | `permissions`, `Rule`, `PermissionRules`, `Target`, `CommandCall`, `FileCall`, `FetchCall`, `ToolCall` | [jobs.md](jobs.md) |
+| `jobs/check.js` | `check` | [jobs.md](jobs.md) |
+| `jobs/prompt.js` | `prompt` | [jobs.md](jobs.md) |
+| `jobs/status-line.js` | `statusLine`, `Usage` | [jobs.md](jobs.md) |
+| `jobs/program.js` | `program`, `Program` | [jobs.md](jobs.md) |
+| `jobs/part-context.js` | `afterCall`, `modWithin`, `modOf`, `workspaceReader`, `targetWords` | [jobs.md](jobs.md) |
+| `jobs/permissions/match-target.js` | `targetOf`, `matchTarget`, `folderInScope`, `Target`, `TargetKey`, `TargetOf`, `TargetCalls`, `MatchedCall` | [jobs.md](jobs.md) |
+| `jobs/permissions/decide-permission.js` | `decidePermission`, `stricterVerdict`, `Rule`, `PermissionRules`, `Decision`, `Verdict` | [jobs.md](jobs.md) |
+| `jobs/permissions/find-project-scope.js` | `findProjectScope`, `ProjectScope`, `Workspace` | [jobs.md](jobs.md) |
+
+`jobs/permissions.js` and `jobs/permissions/decide-permission.js` each export a `Rule` and a `PermissionRules`, and the two pairs differ:
+
+- The `jobs/permissions.js` pair takes the mod's state type. Its `when` gets a `Mod<State>`, so `Rule<State>` is `decide-permission.js`'s `Rule<Mod<State>>`. A mod writes its rules with this pair.
+- The `decide-permission.js` pair takes the type of `when`'s second argument itself, for code that decides permissions without a mod.
+
+## Check your work
+
+Run `cmod check` in the mod's folder. It installs the packages, checks the layout and the imports, validates the mod with Claude Code, type-checks it once `.claude-plugin/types/` exists, lints it, and runs its tests. Each failure names its fix. [commands.md](commands.md) lists every step.