@lumpcode/cli 0.0.0

package/DOCS/examples.md

@@ -0,0 +1,244 @@
+# Example lumps
+
+Seven common shapes for a lump, each a complete, drop-in `.lumpcode/lumps/<name>/config.json` (or `config.js`). Mix and match: a campaign can use `contextMatchFn` for discovery and a multi-step `steps` workflow; a ticket queue can include `setupFn` to install deps before the agent runs; a sweep can add `branchFn` to follow your team’s naming convention.
+
+Deep references: [concepts.md](./concepts.md), [lump-config.md](./lump-config.md), [advanced-config.md](./advanced-config.md), [types.md](./types.md).
+
+---
+
+## 0. Smoke test — one context, minimal prompt
+
+*When to use:* right after `lumpcode lump-create` to confirm login, remotes, agent command, and marker commits before you invest in a real campaign.
+
+Uses a single fixed path every repo already has (`README.md`). Adjust `FILE` if your project root has no `README.md`.
+
+`.lumpcode/lumps/smokeTest/config.json`:
+
+```json
+{
+  "contextListJson": {
+    "FILE": "README.md"
+  },
+  "prompt": {
+    "promptTemplate": "Reply with exactly one line: smoke OK for @{FILE}. Do not edit any file.",
+    "command": "claude"
+  }
+}
+```
+
+(`baseBranch` defaults to `projectBaseBranch` from `.lumpcode/local.json`; add it on a lump only to override.)
+
+Run once: `lumpcode run smokeTest`, then `git log --remotes --grep '^LUMP:' --oneline` and `lumpcode lump-status --lumpName smokeTest`.
+
+## 1. Framework migration campaign — React → Vue, one component per branch
+
+*When to use:* large UI migration with one reviewable PR per component.
+
+A classic refactoring lump: discover every component folder, do a multi-step migration, ship one PR per component.
+
+```json
+{
+  "command": "claude",
+  "contextListJson": {
+    "FOLDER": "src/components/{COMPONENT_NAME}/",
+    "TYPES":  "src/components/{COMPONENT_NAME}/{COMPONENT_NAME}.types.ts",
+    "TEST":   "src/components/{COMPONENT_NAME}/{COMPONENT_NAME}.test.ts",
+    "COMPONENT": "src/components/{COMPONENT_NAME}/$upperFirst{COMPONENT_NAME}.tsx"
+  },
+  "steps": [
+    "Read @{COMPONENT}, @{TYPES}, and @{TEST}. Produce a short migration plan and save it to src/components_vue/{COMPONENT_NAME}/migration-plan.md (no source changes yet).",
+    "Following the plan at src/components_vue/{COMPONENT_NAME}/migration-plan.md, port @{COMPONENT} to a Vue 3 <script setup> component at src/components_vue/{COMPONENT_NAME}/{COMPONENT_NAME}.vue. Keep behavior identical.",
+    "Port @{TEST} to Vitest + @vue/test-utils, saved to src/components_vue/{COMPONENT_NAME}/{COMPONENT_NAME}.test.ts. Run the tests and fix anything that breaks."
+  ]
+}
+```
+
+Lumpcode commits each context as `LUMP: reactToVue - <ComponentName>` on `lump/reactToVue/<ComponentName>` and pushes. Already-migrated components are skipped automatically on subsequent runs.
+
+## 2. Feature ticket queue — strict dependency order
+
+*When to use:* ordered backlog where later work must wait until earlier tickets are merged to the base branch.
+
+Treat a JSON ticket file as the source of truth and let `dependsOnContexts` enforce order. Subsequent tickets only become eligible once their dependency’s commit is on `origin/<projectBaseBranch>` (i.e. merged).
+
+`.lumpcode/lumps/userProfile/config.json`:
+
+```json
+{
+  "command": "claude",
+  "getContextListFn": "./tickets.js",
+  "numberOfContextsPerBranch": 1,
+  "prompt": {
+    "promptTemplate": "Implement ticket {TICKET_ID}: {TITLE}\n\nAcceptance criteria:\n{ACCEPTANCE}\n\nLikely files:\n{FILE_HINT}"
+  }
+}
+```
+
+`.lumpcode/lumps/userProfile/tickets.js`:
+
+```js
+export default function getContextListFn() {
+  return [
+    {
+      name: "01-schema",
+      variables: {
+        TICKET_ID: "PROF-1",
+        TITLE: "Add `user_profile` table + Prisma model",
+        ACCEPTANCE: "- migration runs cleanly\n- model has bio, avatarUrl, createdAt",
+        FILE_HINT: "prisma/schema.prisma, migrations/",
+      },
+      options: { priority: 1 },
+    },
+    {
+      name: "02-api",
+      variables: {
+        TICKET_ID: "PROF-2",
+        TITLE: "Expose GET/PATCH /me/profile",
+        ACCEPTANCE: "- zod-validated body\n- returns 401 when unauth",
+        FILE_HINT: "apps/api/src/routes/profile.ts",
+      },
+      options: { priority: 2, dependsOnContexts: ["01-schema"] },
+    },
+    {
+      name: "03-ui",
+      variables: {
+        TICKET_ID: "PROF-3",
+        TITLE: "Profile edit page in the web app",
+        ACCEPTANCE: "- form validates on submit\n- toast on success",
+        FILE_HINT: "apps/web/src/pages/profile.tsx",
+      },
+      options: { priority: 3, dependsOnContexts: ["02-api"] },
+    },
+  ];
+}
+```
+
+Pair this with `lumpcode start`: each tick the daemon picks up the next eligible ticket (skipping those whose dependency is still `toDo` or `branchPushed`), opens a PR, and stops until you merge.
+
+## 3. Test coverage sweep — add a test next to every untested module
+
+*When to use:* repo-wide test gaps where simple path patterns are not enough—encode skip logic in code.
+
+Use `contextMatchFn` so the matcher itself decides what to skip. Each call receives `codeBasePath` (the current entry) and `codeBasePaths` (the full scanned list) when you need repo-wide context.
+
+`.lumpcode/lumps/addTests/config.json`:
+
+```json
+{
+  "command": "claude",
+  "contextMatchFn": "./match.js",
+  "maximumNumberOfConcurrentBranches": 5,
+  "prompt": {
+    "promptTemplate": "Write a thorough Vitest suite for the module at @{SOURCE}. Save it next to it as a `.test.ts` file. Aim for branch coverage on exported functions."
+  }
+}
+```
+
+`.lumpcode/lumps/addTests/match.js`:
+
+```js
+import fs from 'node:fs';
+export default function match({ codeBasePath }) {
+  const { isDir, path } = codeBasePath;
+  if (isDir) return null;
+  if (!path.endsWith('.ts') || path.endsWith('.test.ts') || path.endsWith('.d.ts')) return null;
+  if (!path.startsWith('src/')) return null;
+  const testPath = path.replace(/\.ts$/, '.test.ts');
+  if (fs.existsSync(testPath)) return null;
+  return {
+    contextName: path.replaceAll('/', '_').replace(/\.ts$/, ''),
+    filePathVariableName: 'SOURCE',
+  };
+}
+```
+
+`maximumNumberOfConcurrentBranches: 5` keeps no more than five test PRs in flight; the daemon waits for review before queuing more.
+
+## 4. Codemod-style API sweep — replace a deprecated import everywhere it appears
+
+*When to use:* many small mechanical edits across files; optionally batch several files per branch.
+
+Each file that imports `lodash` becomes one context. Lumpcode handles the branch-per-file housekeeping.
+
+`.lumpcode/lumps/lodashToEs/config.json`:
+
+```json
+{
+  "command": "claude",
+  "contextMatchFn": "./match.js",
+  "numberOfContextsPerBranch": 10,
+  "prompt": {
+    "promptTemplate": "Rewrite @{FILE} to remove `lodash`. Replace usages with native ES equivalents (Array methods, Object.fromEntries, structuredClone, etc.). Keep behavior identical and update the imports."
+  }
+}
+```
+
+`.lumpcode/lumps/lodashToEs/match.js`:
+
+```js
+import fs from 'node:fs';
+export default function match({ codeBasePath }) {
+  const { isDir, path } = codeBasePath;
+  if (isDir || !/\.(ts|tsx|js|jsx)$/.test(path)) return null;
+  const src = fs.readFileSync(path, 'utf8');
+  if (!/from ['"]lodash/.test(src)) return null;
+  return { contextName: path.replaceAll('/', '_'), filePathVariableName: 'FILE' };
+}
+```
+
+`numberOfContextsPerBranch: 10` groups ten files per PR so reviewers don’t drown in tiny diffs.
+
+## 5. Documentation generation — one README per package
+
+*When to use:* monorepos where each package should get consistent README content from `package.json` and entrypoints.
+
+Run over `packages/*/` and produce or refresh each package README from real source.
+
+```json
+{
+  "command": "claude",
+  "contextListJson": {
+    "PKG_FOLDER":  "packages/{PKG}/",
+    "PKG_JSON":    "packages/{PKG}/package.json",
+    "PKG_ENTRY":   "packages/{PKG}/src/index.ts"
+  },
+  "steps": [
+    "Read @{PKG_JSON} and @{PKG_ENTRY} (and other relevant files in @{PKG_FOLDER}). Write or rewrite packages/{PKG}/README.md covering: install, quick example, top exports, and links to deeper docs. Keep it under 200 lines."
+  ]
+}
+```
+
+## 6. Conditional follow-up — only do step B if step A says so
+
+*When to use:* optional second agent pass based on the first answer (saves cost when no follow-up is needed).
+
+Mix a static prompt with a function-form prompt item to short-circuit work when nothing is needed. Requires a JS config so the function can be inline.
+
+`.lumpcode/lumps/maybeBumpDeps/config.js`:
+
+```js
+export default {
+  command: 'claude',
+  contextListJson: { PKG_JSON: 'packages/{PKG}/package.json' },
+  steps: [
+    {
+      promptTemplate:
+        "Inspect @{PKG_JSON}. If any direct dependency is more than two majors behind latest, reply exactly NEEDS_BUMP. Otherwise reply OK.",
+      postCommandExecFn: ({ commandResult, contextRunState }) => {
+        contextRunState.needsBump = commandResult.includes('NEEDS_BUMP');
+      },
+    },
+    ({ contextRunState }) =>
+      contextRunState.needsBump
+        ? [
+            {
+              promptTemplate:
+                "Bump outdated direct dependencies in @{PKG_JSON} to their latest minor (no majors). Run the package's tests and fix obvious breakage.",
+            },
+          ]
+        : [],
+  ],
+};
+```
+
+The second item is a **function** that returns either a one-step array or an empty one—Lumpcode skips the upgrade prompt entirely when the analysis says it isn’t needed, so you don’t pay for an agent run per package that’s already current.

package/DOCS/get-started.md

@@ -0,0 +1,222 @@
+# Getting started with the Lumpcode CLI
+
+Follow this guide in order to get started with your first `lumpcode run`. Links at each step point to more detail if you want it.
+
+---
+
+## Prerequisites
+
+Install and prepare the following:
+
+1. **Lumpcode account** — Create one at [lumpcode.com](https://lumpcode.com); you’ll use it to log in.
+2. **Lumpcode CLI** on your `PATH` — Installers vary by OS (Homebrew `brew install lumpcode`, curl one-liners, Windows downloads, or `npm install -g @lumpcode/cli` on Node 22+). The npm install uses a native binary when available for your platform and otherwise runs with Node automatically. For installation details: [README.md § Install](../README.md#install).
+3. **Git** repository with **`origin`** reachable for fetch/push. The **`projectBaseBranch`** you'll declare in `.lumpcode/local.json` (typically `main`) must **already exist on `origin`** (e.g. `origin/main`): Lumpcode pulls it during pre-flight and reads it via `origin/<projectBaseBranch>` for status.
+4. **CLI coding agent** installed and runnable. Lumpcode invokes the **`command`** you set in lump config by resolving a command module in this order: `.lumpcode/commands/<name>.js` (project), then `~/.lumpcode/commands/<name>.js` (global override), then shipped presets at `~/.lumpcode/commands/presets/<name>.js`. Built-in preset names **`cursor`** and **`copilot`** work out of the box when `cursor-agent` or `copilot` is on `PATH`; other agents (e.g. **`claude`**, **`aider`**) need a custom module until more presets ship.
+
+---
+
+## Terms you need for this tutorial
+
+| Term | Meaning |
+|------|---------|
+| **Project** | A folder with git that contains both `.git/` and `.lumpcode/` (the CLI adds `.lumpcode/` once you initialize). |
+| **Lump** | One automated coding campaign living under `.lumpcode/lumps/<lumpName>/` (context discovery + prompt + agent command). |
+| **Context** | One unit of work inside a lump (e.g. one file or one component). Each context has a **name** and **variables** filled into your prompt. |
+| **Marker commit** | The commit subject for one context is always **`LUMP: <lumpName> - <contextName>`** on the remote. Lumpcode uses that to know what is already done. |
+| **Resumable** | Re-running `lumpcode run` or a daemon tick skips contexts that already have a matching marker on the remote. |
+
+More details, diagrams and context status values (`toDo`, `branchPushed`, `finished`): [concepts.md](./concepts.md).
+
+---
+
+## Step 0: Open a git project
+
+```bash
+cd /path/to/your/repo
+git status   # remotes should be set up and accessible
+```
+
+You only need **`.git/`** here. The next steps create **`.lumpcode/`** in this same directory. After that, this folder is your **Lumpcode project root**.
+
+---
+
+## Step 1: Log in
+
+```bash
+lumpcode login
+```
+
+Use your Lumpcode email and password when prompted. The CLI saves the session to `~/.lumpcode/auth.json` and skips prompting if you are already logged in. For non-interactive use and flags, see [commands.md § `lumpcode login`](./commands.md#ref-cmd-login).
+
+---
+
+## Step 2: Initialize the Lumpcode project
+
+From the repository root:
+
+```bash
+lumpcode project-setup
+```
+
+This creates:
+
+```text
+.lumpcode/
+├── project.json      # project name and optional project-wide settings (commit this)
+├── local.json        # per-machine mode + projectBaseBranch (gitignored)
+├── lumps/            # one folder per lump
+└── commands/         # optional custom agent command modules (.js)
+```
+
+**`project.json`** stores **`projectName`**: letters, digits, `_`, and `-` only. If you omit **`--projectName`**, `project-setup` infers a name from **`origin`** or the directory basename and normalizes it to those rules. That same value is used for daemon files and for `~/.lumpcode/project-copies/<projectName>/` when `local.json.mode` is `shared`—Lumpcode does not rename or “slug” it at runtime.
+
+**`local.json`** is per machine and gitignored. The default is:
+
+```json
+{
+  "mode": "shared",
+  "projectBaseBranch": "main"
+}
+```
+
+Keep `shared` on your workstation (Lumpcode never touches your checkout — it runs in a separate copy). Edit it to `"dedicated"` on a server / daemon machine that you don't develop on. Full reference: [local-config.md](./local-config.md).
+
+Optional flags:
+
+- `--projectPath <dir>` — Initialize another directory (default: current working directory).
+- `--projectName <name>` — Stored verbatim; must already satisfy the character rules (see [project-config.md](./project-config.md#projectname-rules)).
+- `--mode <shared|dedicated>` — Initial `local.json.mode` (default `shared`).
+- `--projectBaseBranch <branch>` — Initial `local.json.projectBaseBranch` (default `main`).
+
+Extra fields (`maximumNumberOfConcurrentBranches`, …): [project-config.md](./project-config.md).
+
+---
+
+## Step 3: Create a lump
+
+```bash
+lumpcode lump-create myFirstLump
+```
+
+By default this writes **`.lumpcode/lumps/myFirstLump/config.json`** with a small starter config. For **`config.js`** instead:
+
+```bash
+lumpcode lump-create myFirstLump --config js
+```
+
+`lump-create` gives you one path template plus `@{FILE}` in the prompt; Step 4 is where you reshape that for your campaign.
+
+---
+
+## Step 4: Define contexts
+
+`contextListJson` maps variable names to path **templates** (e.g. `{NAME}`, `{COMPONENT_NAME}`). Lumpcode scans the repo and keeps only combinations where **every** template resolves to a real path; each map **key** is a **`{VAR}`** in `promptTemplate`, or **`@{VAR}`** with a leading `@` for agents that treat `@path` as file context. Substitution rules: [lump-config.md § Prompt template syntax](./lump-config.md#prompt-template-syntax).
+
+**Why two examples:** Lumpcode excels at **the same shaped change** across many files—first a **minimal** stub (one `{NAME}` pattern under `src/`, one generic improvement prompt); then a **repeat-per-component** pattern: hypothetical **React** `.tsx` files laid out **one folder per component**, where every discovered context runs the **same migration ask** (**Vue 3 `<script setup>`**). The stacks are illustrative only so you see multi-path contexts and **`$upperFirst{…}`**; replace paths, prompts, and `command` with your real migration or refactor.
+
+Minimal stub (`lump-create` defaults look like this—adjust `FILE`/prompt):
+
+```json
+{
+  "$schema": "https://lumpcode.com/schemas/lumpConfig.schema.json",
+  "contextListJson": {
+    "FILE": "src/{NAME}.ts"
+  },
+  "prompt": {
+    "promptTemplate": "Improve the code at @{FILE}.",
+    "command": "claude"
+  }
+}
+```
+
+Repeat-per-component variant (multiple paths must exist per context—the prompt is identical in spirit every time Lumpcode discovers the next matched folder/file set):
+
+```json
+{
+  "contextListJson": {
+    "FOLDER": "src/components/{COMPONENT_NAME}/",
+    "COMPONENT": "src/components/{COMPONENT_NAME}/$upperFirst{COMPONENT_NAME}.tsx"
+  },
+  "prompt": {
+    "promptTemplate": "Migrate the component at @{COMPONENT} (folder @{FOLDER}) to Vue 3 <script setup>.",
+    "command": "claude"
+  }
+}
+```
+
+The base branch comes from `.lumpcode/local.json.projectBaseBranch`. Add a per-lump `"baseBranch": "release/2.0"` only if this campaign needs to branch off something else.
+
+Transforms (e.g. `$upperFirst{…}`) and **`contextOptionsFn`** for `priority` / `dependsOnContexts`: [lump-config.md § contextListJson](./lump-config.md#contextlistjson). Fully custom sourcing: **`getContextListFn`** / **`contextMatchFn`** ([lump-config.md](./lump-config.md), [advanced-config.md](./advanced-config.md)).
+
+---
+
+## Step 5: Run once
+
+```bash
+lumpcode run myFirstLump
+```
+
+In one tick, Lumpcode first runs **pre-flight** (pulls `projectBaseBranch` from `local.json` in the resolved workspace), then picks the next context(s); prepares the work branch `lump/myFirstLump/…`; runs your agent; commits with the **`LUMP: myFirstLump - <contextName>`** marker (see Terms above); pushes to **`origin`**; refreshes **`contextStatusRecord.json`**; and finally switches the workspace back to `projectBaseBranch`.
+
+**Workspace:** `local.json.mode` decides where the run happens — `shared` uses **`~/.lumpcode/project-copies/<projectName>/`** (a copy of your repo); `dedicated` uses **this checkout** in place (destructive reset). [concepts.md § Pre-flight and modes](./concepts.md#pre-flight-and-modes) · [local-config.md](./local-config.md)
+
+**Sanity checks:**
+
+```bash
+git fetch origin
+git log --remotes --grep '^LUMP:' --oneline
+lumpcode lump-status --lumpName myFirstLump
+```
+
+Do **not** confuse **`lump-status`** (context rows from git) with **`daemon-status`** (scheduler process)—[commands.md](./commands.md#three-commands-that-mention-status).
+
+---
+
+## Step 6: Run continuously (optional)
+
+From the same repository root:
+
+```bash
+lumpcode start
+```
+
+By default **`start`** launches a **detached** background process on a cron schedule (**every 5 minutes**), loops **every lump** under `.lumpcode/lumps/` that has a loadable **`config.json`** or **`config.js`**, and **skips** lumps marked **`"disabled": true`** in their config.
+
+| If you… | Prefer |
+|---------|--------|
+| Want **one lump**, **one batch**, then return to the shell | **`lumpcode run myFirstLump`** |
+| Leave a machine running and tick **all lumps** on a timer | **`lumpcode start`** |
+
+**Common flags:** `lumpcode start --foreground` (block in this terminal instead of detaching). `lumpcode start --cronSetup '*/10 * * * *'` changes the schedule. **`lumpcode daemon-status`** shows PID and log paths; **`lumpcode daemon-log`** tails the log (follows live by default; **`--noFollow`** to print and exit); **`lumpcode stop`** / **`lumpcode restart`** control the daemon. Metadata files live under **`~/.lumpcode/daemons/`** (PID, log, `cronSetup` in meta JSON).
+
+Trade-offs and **`maximumNumberOfConcurrentBranches`**: [concepts.md § When to use run vs start](./concepts.md#when-to-use-run-vs-start-daemon).
+
+---
+
+## Where your work lives
+
+| Artifact | Location |
+|----------|----------|
+| Lump configs | `.lumpcode/lumps/<lumpName>/` |
+| Per-machine mode + projectBaseBranch | `.lumpcode/local.json` (gitignored) |
+| Context status cache | `.lumpcode/lumps/<lumpName>/contextStatusRecord.json` |
+| Prompt run history (optional, `keepHistory: true`) | `.lumpcode/lumps/<lumpName>/history/<contextName>.json` (gitignored) |
+| Default work branch names | `lump/<lumpName>/<context…>` (local + `origin`) |
+| Isolated repo copy (when `local.json.mode` is `shared`) | `~/.lumpcode/project-copies/<projectName>/` |
+| Background daemon PID / logs | `~/.lumpcode/daemons/` |
+
+Commit `.lumpcode/` if you want lump definitions and status tracked in git; omit secrets and machine-only paths from shared configs.
+
+---
+
+## Next steps
+
+You have now your first working lump ! Browse when you need more depth:
+
+- [concepts.md](./concepts.md) — Lifecycle diagrams and workspace details
+- [commands.md](./commands.md) — Every subcommand and flag
+- [local-config.md](./local-config.md) — `.lumpcode/local.json` (`mode`, `projectBaseBranch`)
+- [lump-config.md](./lump-config.md) — All lump config keys
+- [advanced-config.md](./advanced-config.md) — Hooks, dynamic `steps`, custom commands
+- [types.md](./types.md) — Hook parameter shapes
+- [examples.md](./examples.md) — Short smoke-test style recipes

package/DOCS/local-config.md

@@ -0,0 +1,80 @@
+# Local configuration (`.lumpcode/local.json`)
+
+`.lumpcode/local.json` is a **per-machine**, **gitignored** file that tells Lumpcode where and how to run lumps from the current checkout. **Every command that runs a lump (`run`, `start`) requires it**—Lumpcode hard-fails if it is missing or invalid.
+
+`lumpcode project-setup` scaffolds the file with safe defaults and appends it to `.gitignore` so it never makes it into commits or shared branches.
+
+## Minimal example
+
+```json
+{
+  "mode": "shared",
+  "projectBaseBranch": "main",
+  "workspaceStrategy": "checkout"
+}
+```
+
+## Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mode` | `"shared"` \| `"dedicated"` | How Lumpcode treats the current checkout. See [Modes](#modes) below. |
+| `projectBaseBranch` | string | Branch Lumpcode pulls (and resets to) before any lump runs. Also the default `baseBranch` for lumps that don't set their own. Status checks (`finished`) compare against `origin/<projectBaseBranch>`. |
+| `workspaceStrategy` | `"checkout"` \| `"worktree"` | How each lump run prepares git inside the [execution workspace](concepts.md#three-workspaces). Default: `"checkout"`. See [Workspace strategies](#workspace-strategies). |
+| `disabled` | boolean | When `true`, the background daemon (`lumpcode start`) skips every lump on this machine without stopping the scheduler. Manual `lumpcode run` is unaffected. |
+
+`mode` and `projectBaseBranch` are **required**. `workspaceStrategy` and `disabled` are optional (`workspaceStrategy` defaults to `"checkout"` when omitted). Unknown fields are rejected.
+
+## Modes
+
+### `shared` (default)
+
+You use this clone for your **day-to-day work**. Lumpcode never touches it; every run happens in a **separate copy** at `~/.lumpcode/project-copies/<projectName>/`. The copy is created once and kept up to date by pre-flight on subsequent runs.
+
+```text
+~/your-repo/             ← your editor / git client; untouched by Lumpcode
+~/.lumpcode/
+└── project-copies/<projectName>/   ← Lumpcode runs here
+```
+
+Pick `shared` on **workstations**.
+
+### `dedicated`
+
+The clone is **owned by Lumpcode** (typical for a daemon machine on a small server). Lumpcode runs in place: pre-flight does `git fetch && git switch <projectBaseBranch> && git reset --hard origin/<projectBaseBranch>` in the checkout itself. **This wipes any uncommitted local changes.** Do not pick `dedicated` for a clone you also edit.
+
+Pick `dedicated` on **machines you don't develop on**, including `lumpcode start` daemons.
+
+## Workspace strategies
+
+### `checkout` (default)
+
+Each lump run switches the main worktree to a fresh `lump/<lumpName>/…` branch (fetch, reset, pull `baseBranch`, then `git switch -c`). When the lump finishes, the workspace switches back to `projectBaseBranch`.
+
+### `worktree`
+
+Each lump run uses a **linked git worktree** under `.lumpcode/worktrees/<branch>/` inside the execution workspace (the project copy in `shared` mode, the checkout in `dedicated`). The main worktree stays on `projectBaseBranch` while the agent runs inside the worktree (the **branch workspace**). Worktree paths mirror branch segments (e.g. branch `lump/migrate-vue/Button.tsx` → `.lumpcode/worktrees/lump/migrate-vue/Button.tsx`). `project-setup` gitignores `.lumpcode/worktrees/`. `lumpcode clean` removes worktrees when it deletes lump branches.
+
+Pick `worktree` when you want the base branch checked out in the main tree during runs, or when planning parallel lump execution later.
+
+## Pre-flight
+
+Before every `run` and every daemon tick, Lumpcode runs a **pre-flight** that:
+
+1. Resolves the execution workspace from `mode` (project copy in `shared`, the checkout itself in `dedicated`).
+2. In that workspace: `git fetch --all && git switch <projectBaseBranch> && git reset --hard origin/<projectBaseBranch> && git pull origin <projectBaseBranch>`.
+
+If pre-flight fails, `run` reports a `commandFailure` and the daemon **skips the tick** (logged to the daemon log) and tries again on the next schedule.
+
+After pre-flight, each lump runs its own per-lump git flow on the execution workspace (see [Workspace strategies](#workspace-strategies)): fetch/pull of the lump's `baseBranch` (defaults to `projectBaseBranch`), then either a checkout branch or a worktree branch workspace. After the lump finishes, checkout mode switches back to `projectBaseBranch`; worktree mode removes the linked worktree while leaving the main tree on `projectBaseBranch`.
+
+## Commit vs. gitignore
+
+`.lumpcode/local.json` is **gitignored**. `project-setup` writes the entry to `.gitignore` for you. Each machine gets its own `local.json`; you should never share it through git.
+
+## Related topics
+
+- [project-config.md](./project-config.md) — `project.json`, project name rules
+- [lump-config.md](./lump-config.md) — Per-lump `config.json` / `config.js`, optional `baseBranch` override
+- [commands.md](./commands.md) — `run` / `start` and other subcommands
+- [concepts.md](./concepts.md) — Pre-flight, lifecycle, daemon overview