@lumpcode/cli 0.0.0

package/DOCS/lump-config.md

@@ -0,0 +1,276 @@
+# Lump configuration (`config.json` / `config.js`)
+
+Each lump lives under:
+
+```text
+.lumpcode/lumps/<lumpName>/
+├── config.json          # JSON config (recommended for beginners)
+│   or config.js         # ESM default export (dynamic logic)
+├── contextStatusRecord.json   # auto-maintained status cache
+├── history/                   # optional per-context prompt run logs (when keepHistory is true)
+└── … templates, prompt files, hook modules …
+```
+
+Preview a lump before running: `lumpcode lump-plan <lumpName>` (see [commands.md](./commands.md#ref-cmd-lump-plan)).
+
+## Required pieces
+
+Every runnable lump has **two required parts**:
+
+1. **Exactly one context source** — mutually exclusive in the JSON schema:
+
+   | Field | Form | Purpose |
+   |-------|------|---------|
+   | `contextListJson` | [JSON reference](#field-forms-conventions) (`Record<string,string>`) | Declarative templates expanded by scanning the tree |
+   | `getContextListFn` | [Function reference](#field-forms-conventions) | Fully custom context list |
+   | `contextMatchFn` | [Function reference](#field-forms-conventions) | Per-file scan → grouped contexts |
+
+2. **Exactly one prompt definition**:
+
+   | Field | Purpose |
+   |-------|---------|
+   | `prompt` | Single prompt step. Object (full item), or string shorthand (treated as inline `promptTemplate` text — **not** a file path; use `promptFn` to load from disk) |
+   | `steps` | Ordered list of steps (mix objects, strings, or dynamic functions — see [advanced-config.md](./advanced-config.md#dynamic-steps)) |
+
+Minimal shape:
+
+```json
+{
+  "contextListJson": { "FILE": "src/{NAME}.ts" },
+  "prompt": {
+    "promptTemplate": "Improve types in @{FILE}",
+    "command": "claude"
+  }
+}
+```
+
+The base branch comes from **`.lumpcode/local.json.projectBaseBranch`** by default — set `baseBranch` here only when this specific lump should run against a different branch. Workspace setup (in-place vs. on a copy) is also per machine, configured in `.lumpcode/local.json.mode` — see [local-config.md](./local-config.md).
+
+Everything else (`command` at top level when using shorthand strings, hooks, etc.) is optional — see [Optional top-level fields](#optional-top-level-fields).
+
+## Runtime: which files actually load?
+
+- The CLI loads **`config.json` or `config.js`**. If **both** exist, **`config.js` wins** (it is strictly more capable; use JSON-only when you want a static lump without dynamic hooks).
+- **`config.ts` is not supported** for lump configuration—use **`config.js`** or **`config.json`**.
+
+## Field forms (conventions)
+
+Two forms appear repeatedly in the field tables below. Each is defined here once and referenced by name throughout the docs.
+
+- **Function reference** — used for every field whose name ends with `Fn` (e.g. `branchFn`, `setupFn`, `getContextListFn`, `contextOptionsFn`, `promptFn`, `postCommandExecFn`). Accepts either:
+  - an **inline function** — only in `config.js`, or
+  - a **string path** to a `.js` file whose **default export** is the function — works in both `config.json` and `config.js`.
+
+  Relative paths resolve from the lump folder (`.lumpcode/lumps/<lumpName>/`). Modules are loaded with dynamic `import()`.
+
+- **JSON reference** — used by `contextListJson`. Accepts either:
+  - an **inline JSON object**, or
+  - a **string path** to a JSON file with the same shape
+
+### Command names
+
+`command` fields (top-level and per-prompt-item) are **not** function references. They hold the **registered name** of a command module:
+
+- **String** (e.g. `"cursor"`, `"copilot"`, `"claude"`, `"aider"`, `"my-agent"`) — resolved against `commands/<name>.js` under the project (`.lumpcode/commands/`), then the global config folder (`~/.lumpcode/commands/`), then shipped presets (`~/.lumpcode/commands/presets/`). Project-local wins over global override; global wins over preset. **`cursor`** and **`copilot`** are built-in preset names (require `cursor-agent` / `copilot` on `PATH`).
+- **Inline function** (`config.js` only) — a `CommandFn` used directly without registry lookup.
+
+Pass agent flags inside the command module's exported `command` function (`executable` + `args`), not in the `command` string. See [advanced-config.md](./advanced-config.md#custom-agent-commands).
+
+## Prompt template syntax
+
+In `promptTemplate` (and string shorthand prompts), the engine substitutes **only** braced placeholders like this:
+
+- **`{VAR}`** → literal string value of `context.variables.VAR`
+
+`VAR` must match a key from `contextListJson` (or a `variables` key returned by `getContextListFn` / `contextMatchFn`).
+
+## Optional top-level fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `baseBranch` | string | Override `local.json.projectBaseBranch` for this lump only. Set when this campaign should branch off something other than the project-wide base (e.g. a long-lived release branch). |
+| `command` | [Command name](#command-names) | Default agent command for all prompt items that don’t set their own `command` |
+| `branchFn` | [Function reference](#field-forms-conventions) | Custom branch naming; default is `lump/<lumpName>/<contextNames…>` |
+| `disabled` | boolean | When `true`, the background daemon skips this lump (`lumpcode start`); `run` still executes if invoked manually |
+| `maximumNumberOfConcurrentBranches` | number | If set (≥ 0), `run` / daemon tick **skips** when open `lump/<lumpName>/*` branches on `origin` ≥ limit (local-only branches are not counted) |
+| `numberOfContextsPerBranch` | number | How many contexts share one branch (default `1`) |
+| `lumpVariables` | object | Arbitrary JSON passed into hooks and prompt functions as `lumpVariables` |
+| `verbose` | boolean | Extra engine logging |
+| `registerCommands` | string[] | Pre-load command modules (`.lumpcode/commands/<name>.js`) before resolving dynamic `steps` |
+| `setupFn` / `teardownFn` | [Function reference](#field-forms-conventions) | Per-context lifecycle hooks |
+| `contextOptionsFn` | [Function reference](#field-forms-conventions) | **Only with `contextListJson`:** set per-context `options` (`priority`, `dependsOnContexts`) after template expansion. See [under **contextListJson**](#contextoptionsfn-only-with-contextlistjson) |
+| `keepHistory` | boolean | When `true`, append one JSON object per prompt step (after the agent command) to `.lumpcode/lumps/<lumpName>/history/<contextName>.json` |
+
+Workspace preparation (fetch/pull/branch) is generated for you from `local.json` and the resolved `baseBranch`—there are no `workspaceSetup`, `setupWorkspaceFn`, or `teardownWorkspaceFn` knobs.
+
+### Commit messages
+
+The CLI **always** uses this git commit subject for each context:
+
+```text
+LUMP: <lumpName> - <contextName>
+```
+
+This format is fixed (not configurable) so that `clean`, `context-status`, and remote status detection stay in sync.
+
+## `contextListJson`
+
+### Inline object
+
+```json
+"contextListJson": {
+  "FILE": "packages/{PKG}/src/index.ts"
+}
+```
+
+Each **key** becomes a **variable** name inside each generated context. Values are **path templates** containing:
+
+- **`{PLACEHOLDER}`** — Captures a path segment from the real file tree; all placeholders in one template row must match the **same** file path for a row to contribute to a context.
+- **`$modifier{PLACEHOLDER}`** — Same capture, but the on-disk text must equal `modifier(extractedPlaceholderValue)` (used for file naming conventions).
+
+Default modifiers shipped with the template expander:
+
+| Token | Effect |
+|-------|--------|
+| `$upperFirst` | `UpperFirst` |
+| `$camel` | `camelCase` |
+| `$kebab` | `kebab-case` |
+| `$snake` | `snake_case` |
+| `$lower` | `lowercase` |
+| `$pascal` | `PascalCase` |
+
+The **context name** is derived by concatenating every captured placeholder tuples with `-` between parts. In most cases, you will use only one placeholder.
+
+### External JSON file
+
+Pass `contextListJson` as a **JSON reference** path (a [JSON reference](#field-forms-conventions) string) instead of an inline object. The file must contain a JSON object of string templates.
+
+Use plain relative paths in templates—**prefer patterns without a leading `./`** (e.g. `"src/{NAME}.ts"`, not `"./src/{NAME}.ts"`).
+
+### `contextOptionsFn` (only with `contextListJson`)
+
+`contextListJson` alone builds `name` and `variables` only. To add **`options`** (see [types.md](./types.md#context) — `priority`, `dependsOnContexts`) to each context, set top-level **`contextOptionsFn`** as a [function reference](#field-forms-conventions).
+
+The function receives each context **before** `options` is set and may return a `Context['options']` object to merge, or `null` / `undefined` to return no options. Shape: [types.md](./types.md#contextoptionsfn).
+
+`contextOptionsFn` is **not** read when the context source is `getContextListFn` or `contextMatchFn` (those already attach `options` on the returned data).
+
+### `getContextListFn` and `contextMatchFn`
+
+Both are [function references](#field-forms-conventions). Shapes: [types.md](./types.md). Examples: [advanced-config.md](./advanced-config.md). **`contextMatchFn`** is invoked once per scanned path with `codeBasePath` (the current entry), `codeBasePaths` (the full list for that run), and `lumpVariables`. Matches that share a `contextName` are merged into one context (see [types.md § ContextMatchFn](./types.md#contextmatchfn)); use a distinct `contextName` per unit of work when you want separate contexts. Put per-context `priority` and `dependsOnContexts` on each `Context` returned from **`getContextListFn`**, or in **`contextOptions`** on **`contextMatchFn`** results.
+
+## Prompt configuration
+
+### Shorthand `prompt`
+
+`prompt` may be:
+
+1. **String** — Treated as inline **`promptTemplate`** text (with `{VAR}` substitution). This string is **never** read as a file path—use a [function reference](#field-forms-conventions) on `promptFn` to load from disk.
+2. **Object** — `LumpJsonConfigStep` fields below.
+
+### `steps` array
+
+Each element may be:
+
+- **String** — Same as shorthand template above.
+- **Object** — Full `LumpJsonConfigStep`.
+- **Function** (`config.js` only) — A function-form item that returns more items dynamically (see [advanced-config.md](./advanced-config.md#dynamic-steps)).
+
+### Per-item fields (`LumpJsonConfigStep`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `promptTemplate` | string | Optional. Inline template text — same `{VAR}` rules as [Prompt template syntax](#prompt-template-syntax). Mutually exclusive with `promptFn` on the same step. When omitted, the command receives an empty prompt string. |
+| `promptFn` | [Function reference](#field-forms-conventions) | Optional. Returns prompt text. Mutually exclusive with `promptTemplate` on the same step. |
+| `command` | [Command name](#command-names) | Required on each step unless overridden inline via `commandFn` in `config.js`; inherits top-level `command` when omitted. |
+| `postCommandExecFn` | [Function reference](#field-forms-conventions) | Hook called after the agent finishes |
+| `stepVariables` | object | JSON-serializable bag passed to promptFn/command/postCommandExecFn hooks |
+| `timeoutMillis` | number | Millis cap for the agent process |
+
+## Prompt run history (`keepHistory`)
+
+By default, Lumpcode does **not** write prompt or agent output to disk. Set **`"keepHistory": true`** on a lump (in `config.json` or `config.js`) to record each prompt step locally.
+
+### File layout
+
+When enabled, after each successful agent command the engine appends one entry to:
+
+```text
+.lumpcode/lumps/<lumpName>/history/<contextName>.json
+```
+
+There is **One file per context** — all prompt steps for that context are in the same JSON array.
+
+### Entry shape
+
+Each array element matches the input passed to **`postCommandExecFn`** (see [types.md](./types.md) and the [core README](https://github.com/lumpcode/lumpcode/blob/main/packages/core/README.md)):
+
+| Field | Description |
+|-------|-------------|
+| `commandResult` | Agent stdout/stderr combined (can be large; may contain secrets) |
+| `context` | The context object (`name`, `variables`, optional `options`) |
+| `prompt` | Resolved prompt string sent to the agent |
+| `stepIndex` | Step index at the root, or a path like `[1, 0]` for nested dynamic items |
+| `contextRunState` | Mutable bag for this context run |
+| `lumpVariables` | Lump-level variables from config |
+| `stepVariables` | Per-item variables, if set |
+| `projectRoot` | Absolute project root path |
+
+History is written **before** an optional `postCommandExecFn` on the same prompt item runs.
+
+### Git and privacy
+
+`lumpcode project-setup` appends **`.lumpcode/**/history/`** to `.gitignore` so run logs stay local. History is intended for debugging and inspection on your machine—not for sharing via git.
+
+### Example
+
+```json
+{
+  "contextListJson": { "FILE": "src/{NAME}.ts" },
+  "keepHistory": true,
+  "prompt": {
+    "promptTemplate": "Improve @{FILE}",
+    "command": "claude"
+  }
+}
+```
+
+## `contextStatusRecord.json`
+
+Auto-maintained cache of the context statuses under each lump folder. Keys are **context names**; each value:
+
+```json
+{
+  "status": "toDo | branchPushed | finished",
+  "contextName": "same-as-key",
+  "branchName": "lump/myLump/foo-bar or empty",
+  "commitMessage": "LUMP: myLump - foo-bar"
+}
+```
+
+Status semantics: [concepts.md#core-terms](./concepts.md#core-terms). Refresh with `lumpcode lump-status` or automatically after `run`.
+
+## Typed JavaScript config (optional)
+
+Install [`@lumpcode/cli-types`](https://www.npmjs.com/package/@lumpcode/cli-types) as a dev dependency and use its `defineConfig` (and other `define*` helpers) so `config.js` gets accurate TypeScript hints for every hook and field:
+
+```bash
+npm install --save-dev @lumpcode/cli-types
+```
+
+```js
+import { defineConfig } from '@lumpcode/cli-types';
+
+export default defineConfig({
+  contextListJson: { FILE: 'src/{NAME}.ts' },
+  prompt: { promptTemplate: 'Fix @{FILE}', command: 'claude' },
+});
+```
+
+## Related documentation
+
+- [concepts.md](./concepts.md) — Status lifecycle, pre-flight, daemon overview
+- [local-config.md](./local-config.md) — Per-machine `local.json` (`mode`, `projectBaseBranch`)
+- [advanced-config.md](./advanced-config.md) — Hooks, dynamic prompts, custom commands
+- [types.md](./types.md) — Callback signatures
+- [commands.md](./commands.md) — `run`, `daemon-status`, `lump-status`, `context-status`

package/DOCS/project-config.md

@@ -0,0 +1,56 @@
+# Project configuration (`.lumpcode/project.json`)
+
+When you run `lumpcode project-setup`, the CLI creates **`.lumpcode/project.json`** at the root of your git repository (next to `.lumpcode/lumps/` and `.lumpcode/commands/`). This file identifies the project for **daemon files**, **project copy** folder names, and human-readable status output.
+
+## Minimal example
+
+```json
+{
+  "projectName": "my-monorepo"
+}
+```
+
+## `projectName` rules
+
+- **Required for Lumpcode to run:** After setup, every command that needs a project identity reads **`projectName`** from this file. If `project.json` is missing, `projectName` is empty, or the value is invalid, those commands **fail** with an error that points you to `project-setup` or editing `project.json`.
+- **Allowed characters only:** Letters, digits, underscore (`_`), and hyphen (`-`). No spaces or other punctuation (pattern: `^[a-zA-Z0-9_-]+$`).
+
+**`lumpcode project-setup`** writes `projectName` for you: if you omit `--projectName`, it infers a name from **`git remote get-url origin`** (last URL segment, without `.git`) or from the **directory basename**, then normalizes it so it satisfies the rules above. If you pass **`--projectName`**, it must already satisfy the rules (no silent rewriting).
+
+## Schema (other fields optional)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `projectName` | string | **Required** for runs once the project exists; see [rules](#projectname-rules) above. Used as-is for daemon filenames under `~/.lumpcode/daemons/` and for `~/.lumpcode/project-copies/<projectName>/` when `local.json.mode` is `shared` |
+| `maximumNumberOfConcurrentBranches` | number | Default cap on simultaneously open `lump/<lumpName>/*` branches on `origin` across the project (local-only branches are not counted; a lump can override in its own config) |
+
+Where Lumpcode runs lumps (in-place vs. on a copy), which branch is treated as the project base, and whether the daemon is paused on this machine are **per-machine** settings; they live in `.lumpcode/local.json` instead. See [local-config.md](./local-config.md).
+
+## Why `.lumpcode/` lives next to `.git`
+
+Lumpcode treats a directory as a project root only when it contains both:
+
+- `.git/` — source of truth for branches, remotes, and commit history
+- `.lumpcode/` — configuration, per-lump status JSON, and optional custom `commands/*.js`
+
+Keeping both at the repo root lets you **commit** lump definitions with the same revision control as your product code.
+
+## Commit vs. `.gitignore`
+
+**Commit** when:
+
+- Your team should share lump definitions, prompts, and command wrappers
+- You want `contextStatusRecord.json` visible for review (optional—some teams prefer local-only state)
+
+**Gitignore** (or omit specific files) when:
+
+- Status files are noisy in PRs (`contextStatusRecord.json`)
+- Custom commands embed machine-specific paths or secrets
+
+## Related topics
+
+- [concepts.md](./concepts.md) — Project root, daemon files, workspace copies
+- [local-config.md](./local-config.md) — Per-machine `local.json` (`mode`, `projectBaseBranch`)
+- [get-started.md](./get-started.md) — First-time setup
+- [lump-config.md](./lump-config.md) — Per-lump `config.json`
+- [commands.md](./commands.md) — `project-setup` flags

package/DOCS/publishing.md

@@ -0,0 +1,79 @@
+# Publishing `@lumpcode/*` to npm (operators)
+
+Operator-only notes for publishing from the monorepo. End users install via `npm i -g @lumpcode/cli@beta` (see [README](../README.md)).
+
+## Packages and order
+
+Publish in dependency order:
+
+1. `@lumpcode/core`
+2. `@lumpcode/cli-types`
+3. `@lumpcode/cli`
+
+Each `package.json` includes `publishConfig.access: public` for the first scoped public publish under the `lumpcode` org.
+
+## Pre-publish verification
+
+From the monorepo root:
+
+```bash
+export ENV=prod
+export API_URL=https://api.lumpcode.com   # optional; baked into CLI bundle
+
+npm run build -w=@lumpcode/core
+npm run build -w=@lumpcode/cli-types
+npm run build:bundle -w=@lumpcode/cli
+
+npm run test -w=@lumpcode/core
+npm run test -w=@lumpcode/cli
+npm run test:e2e:node -w=@lumpcode/cli   # optional smoke
+
+npm pack -w=@lumpcode/core
+npm pack -w=@lumpcode/cli-types
+npm pack -w=@lumpcode/cli
+```
+
+Inspect tarballs: `dist/`, CLI `bin/`, `postinstall` scripts, `LICENSE`, README.
+
+Or use the helper script (build + publish):
+
+```bash
+node scripts/publish-npm-beta.mjs --dry-run   # build + pack only
+node scripts/publish-npm-beta.mjs             # build + publish with beta tag
+```
+
+## First publish (`beta` tag)
+
+```bash
+npm login
+npm whoami
+
+npm publish -w=@lumpcode/core --access public --tag beta
+npm publish -w=@lumpcode/cli-types --access public --tag beta
+npm publish -w=@lumpcode/cli --access public --tag beta
+```
+
+Beta testers:
+
+```bash
+npm i -g @lumpcode/cli@beta
+npm i -D @lumpcode/cli-types@beta
+```
+
+## Promote to `latest`
+
+When ready for default installs:
+
+```bash
+npm dist-tag add @lumpcode/core@0.0.0 latest
+npm dist-tag add @lumpcode/cli-types@0.0.0 latest
+npm dist-tag add @lumpcode/cli@0.0.0 latest
+```
+
+Replace `0.0.0` with the version you are promoting.
+
+## Notes
+
+- `repository` in `package.json` is omitted (not required for publish).
+- CLI `postinstall` binary download uses `native-binary.mjs` / `LUMPCODE_INSTALL_REPO`, separate from npm metadata.
+- `prepublishOnly` runs builds: `core` and `cli-types` → `npm run build`; `cli` → `npm run build:bundle`.

package/DOCS/types.md

@@ -0,0 +1,267 @@
+# Types for Lumpcode lump configuration
+
+This reference lists the JSON shapes and **JavaScript function signatures** you use in `config.json` / `config.js`. Types are described in TypeScript notation for clarity.
+
+Conventions:
+
+- `Maybe<T>` means `T | null | undefined`
+- `MaybePromise<T>` means `T | Promise<T>`
+- Each function signature below is a [function reference](./lump-config.md#field-forms-conventions): in `config.js` you may pass it inline, and in either format you may pass a string path to a `.js` module whose **default export** matches the signature.
+
+---
+
+## JSON data shapes
+
+### `Context`
+
+```ts
+interface Context {
+  name: string;
+  variables: Record<string, string>;
+  options?: {
+    priority?: number;
+    dependsOnContexts?: string[];
+  };
+}
+```
+
+- `name` — unique id for the unit of work; drives default commit subject suffix.
+- `variables` — string map substituted into `{VAR}` / `@{VAR}` in prompts.
+- `options.priority` — lower runs sooner.
+- `options.dependsOnContexts` — names of contexts that must be **`finished`** before this one runs.
+
+### `ContextList`
+
+```ts
+type ContextList = Context[];
+```
+
+Return type of `getContextListFn`; built internally for `contextMatchFn` and `contextListJson` (with optional `contextOptionsFn`) merges.
+
+### `ContextOptionsFn`
+
+```ts
+type ContextOptionsFn = (
+  contextWithoutOptions: Omit<Context, 'options'>,
+) => MaybePromise<Maybe<Context['options']>>;
+```
+
+- **Input** — a `Context` with `name` and `variables` only (no `options` field yet from the template expander).
+- **Return** — `null` or `undefined` to leave `options` unset; otherwise an object merged into that context (same shape as `Context['options']`).
+
+Runs only when **`contextListJson`** is the context source; ignored for `getContextListFn` and `contextMatchFn`.
+
+### `CodeBasePath`
+
+```ts
+interface CodeBasePath {
+  isDir: boolean;
+  path: string;
+}
+```
+
+Paths use `/` separators, relative to the project root. Passed to `getContextListFn` as `codeBasePaths`. `contextMatchFn` receives the current path as `codeBasePath` and the full scanned list as `codeBasePaths` on every call.
+
+### `ContextRunState`
+
+```ts
+type ContextRunState = Record<string, unknown>;
+```
+
+Mutable bag shared across prompt items for one context execution. Seed from `setupFn`; read/write in `promptFn`, `postCommandExecFn`, and dynamic `steps` functions.
+
+### `LumpVariables`
+
+```ts
+type LumpVariables = Record<string, unknown>;
+```
+
+Top-level **`lumpVariables`** object from lump config, forwarded into every hook.
+
+### `StepVariables`
+
+```ts
+type StepVariables = Record<string, unknown>;
+```
+
+Per–prompt-step bag from `stepVariables` on a prompt item.
+
+### `ContextStatus`
+
+```ts
+type ContextStatus = 'toDo' | 'branchPushed' | 'finished';
+```
+
+Semantics: [concepts.md#core-terms](./concepts.md#core-terms).
+
+### `ContextStatusRecordItem`
+
+```ts
+interface ContextStatusRecordItem {
+  status: ContextStatus;
+  contextName: string;
+  branchName: string;
+  commitMessage: string;
+}
+```
+
+### `ContextStatusRecord`
+
+```ts
+type ContextStatusRecord = Record<string, ContextStatusRecordItem>;
+```
+
+The on-disk JSON uses the same keys as `contextName`.
+
+---
+
+## Hook signatures
+
+### `GetContextListFn`
+
+```ts
+interface GetContextListFnInput {
+  codeBasePaths: CodeBasePath[];
+  lumpVariables: LumpVariables;
+}
+
+type GetContextListFn = (
+  params: GetContextListFnInput,
+) => MaybePromise<ContextList>;
+```
+
+### `ContextMatchFn`
+
+Called once per scanned `CodeBasePath`. `codeBasePath` is the current entry; `codeBasePaths` is the full list for that run (same array reference on every call).
+
+Every returned `contextName` must be unique in the final context list. Lumpcode enforces that by **merging** all matches that share a `contextName` into one `Context`: `variables` keys accumulate (same key from a later file overwrites), and `contextOptions` from a later match replace earlier ones. For one file per context, give each match a distinct `contextName` (path-based names are common—see [examples.md](./examples.md#3-test-coverage-sweep--add-a-test-next-to-every-untested-module)).
+
+```ts
+type ContextMatchFn = (params: {
+  codeBasePath: CodeBasePath;
+  codeBasePaths: CodeBasePath[];
+  lumpVariables: Record<string, unknown>;
+}) => MaybePromise<
+  Maybe<{
+    contextName: string;
+    filePathVariableName: string;
+    moreContextVariables?: Record<string, string>;
+    contextOptions?: Context['options'];
+  }>
+>;
+```
+
+### `BranchFn`
+
+```ts
+type BranchFn = (params: {
+  contextList: Context[];
+  contextRunStateList: ContextRunState[];
+  lumpVariables: LumpVariables;
+}) => MaybePromise<string>;
+```
+
+Return the **git branch name** to use for this batch.
+
+### `PromptFn`
+
+```ts
+interface PromptFnInput {
+  context: Context;
+  /** Root index or nested path for dynamic `steps` */
+  stepIndex: number | number[];
+  contextRunState: ContextRunState;
+  lumpVariables: LumpVariables;
+  stepVariables?: StepVariables;
+}
+
+type PromptFn = (params: PromptFnInput) => MaybePromise<string>;
+```
+
+### `CommandFn`
+
+```ts
+type CommandFn = ((
+  params: {
+    context: Context;
+    prompt: string;
+    stepIndex: number | number[];
+    contextRunState: ContextRunState;
+    lumpVariables: LumpVariables;
+    stepVariables?: StepVariables;
+    projectRoot: string;
+    workspacePath: string;
+  },
+) => MaybePromise<{ executable: string; args: string[] } | null | undefined | void>) & {
+  /** Set automatically when Lumpcode resolves a named command module */
+  commandName?: string;
+};
+```
+
+Return `{ executable, args }` to run a subprocess. Return `null`, `undefined`, or nothing to skip execution; `postCommandExecFn` still runs with an empty `commandResult`. `keepHistory` entries are not written for skipped commands.
+
+Lumpcode runs the agent as `executable` + `args`. Agent-specific flags and the prompt text go into `args` the way your agent expects (e.g. `executable: 'claude', args: ['-p', prompt]` or `executable: 'aider', args: ['--message', prompt]`). This is exactly what a command module at `.lumpcode/commands/<name>.js` exports as its `command`.
+
+### `PostCommandExecFn`
+
+```ts
+type PostCommandExecFn = (input: {
+  commandResult: string;
+  context: Context;
+  prompt: string;
+  stepIndex: number | number[];
+  contextRunState: ContextRunState;
+  lumpVariables: LumpVariables;
+  stepVariables?: StepVariables;
+  projectRoot: string;
+}) => MaybePromise<void>;
+```
+
+`commandResult` is the **captured stdout** (string). Parse JSON yourself if your agent returns structured text.
+
+### `SetupFn`
+
+```ts
+type SetupFn = (params: {
+  contextList: Context[];
+  lumpVariables: LumpVariables;
+  currentContextIndex: number;
+}) => MaybePromise<
+  Maybe<Partial<{ contextRunState: ContextRunState }>>
+>;
+```
+
+### `TeardownFn`
+
+```ts
+type TeardownFn = (params: {
+  lumpVariables: LumpVariables;
+  contextList: Context[];
+  contextRunState: ContextRunState;
+  currentContextIndex: number;
+}) => MaybePromise<void>;
+```
+
+### Workspace hooks
+
+There is no user-facing `setupWorkspaceFn` / `teardownWorkspaceFn` in lump config any more — the CLI generates both from the resolved workspace (per [local-config.md](./local-config.md)'s `mode`) and the lump's `baseBranch`. See [advanced-config.md](./advanced-config.md#workspace-handling) for the rationale.
+
+### Command module (`command` / `setup` / `teardown`)
+
+Custom modules under `.lumpcode/commands/<name>.js` export:
+
+```ts
+export const command: CommandFn = …;
+export const setup?: SetupFn;
+export const teardown?: TeardownFn;
+```
+
+`setup` / `teardown` use the same parameter shapes as lump-level hooks.
+
+---
+
+## Related documentation
+
+- [lump-config.md](./lump-config.md) — Where these types appear in JSON
+- [advanced-config.md](./advanced-config.md) — Hooks, dynamic prompts, custom commands
+- [concepts.md](./concepts.md) — Daemon, workspace, status lifecycle