@idea1/cli 1.9.0 → 1.10.0

package/README.md

@@ -27,14 +27,17 @@ idea1 next --target https://app.idea1.ai/project/items/590   # or just `idea1 ne
 # Jump straight to Agent Implementation (worktree + Claude) — the "send for implementation" path
 idea1 start-agent-implementation --target https://app.idea1.ai/project/items/590   # alias: start-project-item
 
+# Join an item in its current workflow state: its branch checked out, and a Claude session from one of the state's entry points
+idea1 join-project-item --target https://app.idea1.ai/project/items/590 --claude-entry-point launch --entry-point "Review the PR"
+
 # Dedicated transitions (each is one `next` step)
 idea1 start-dev-implementation  # or: idea1 dev
 idea1 ready-for-approval        # or: idea1 rfa
 idea1 approve-pr                # or: idea1 approve
 
 # The same two commands on a branch with no project item, e.g. an integration branch:
-# open its PR into working/release and name the approver, then (as the approver) merge it
-idea1 ready-for-approval --assignee octocat
+# open its PR into working/release and name the approver (a teammate, by email or GitHub login), then (as the approver) merge it
+idea1 ready-for-approval --assignee name@company.com
 idea1 approve-pr --target working/integration/<name>-main
 
 # From working/release: approve several items, branches or PRs at once, each in its own unattended run, in parallel
@@ -78,7 +81,7 @@ With no `--target`, a command works on the current branch when it can be the tar
 
 ```bash
 idea1 approve-pr --target <item url>,<branch>,<PR url> --yes
-idea1 ready-for-approval --target <item url>,<item url> --assignee octocat
+idea1 ready-for-approval --target <item url>,<item url> --assignee name@company.com
 idea1 next --to "Dev Implementation" --target <item url>,<item url>
 ```
 
@@ -101,7 +104,7 @@ The state names and their order are defined once, in `shared-config/workflow-sta
 
 ### How the workflow engine works
 
-An item **under workflow management** has a *workflow context* on idea1.ai: its workflow status together with the one branch on origin that carries its work — the repository and branch name, the PR target (base) branch, the dev workflow type and any stack or integration branch. An item with no context is outside workflow management and has no status. The CLI reads and records the context through the platform's MCP tools (`get_item_summary_for_branch`, `get_item_summary`, `upsert_item_workflow_context`) and, having run a transition's automation itself, records the state it reached directly with `update_item`'s `workflowStatus`; the web client works on the same context, so the two always agree, and any clone resolves a branch to its item from the platform. Locally, each clone remembers the item URL a branch was last resolved to in its git config, so ordinary branches are recognized as unmanaged instantly.
+An item **under workflow management** has a *workflow context* on idea1.ai: its workflow status together with the one branch on origin that carries its work — the repository and branch name, the PR target (base) branch, the dev workflow type and any stack or integration branch. An item with no context is outside workflow management and has no status. The CLI reads and records the context through the platform's MCP tools (`get_item_summary_for_branch`, `get_item_summary`, `upsert_item_workflow_context`) and, having run a transition's automation itself, records the state it reached directly with `update_item`'s `workflowStatus` (and `assignedToEmail`, when the state takes a teammate assignment; the team's members come from `list_team_members`); the web client works on the same context, so the two always agree, and any clone resolves a branch to its item from the platform. The branching decisions the context records (dev workflow type, stack and integration branch, branch name) are made once, when the item's branch is created, and are never asked again for an item that has one. Locally, each clone remembers the item URL a branch was last resolved to in its git config, so ordinary branches are recognized as unmanaged instantly.
 
 The branch itself carries the work. A branch's PR is therefore gated on a CI/CD run of exactly what merges, and `approve-pr` merges that run's head. When a branch is deleted on GitHub the context keeps its name and records whether the work merged; a context whose branch is gone without merging gets a new branch the next time the item enters a pre-merge state, while merged work stays merged. Branches put under workflow before the platform kept contexts carry a legacy `.idea1/<branch>.json` file, which the CLI removes from the branch before the approval gate.
 
@@ -109,22 +112,24 @@ A transition is "enter state X". Entering a state runs that state's automation (
 
 | Entering | Automation |
 |----------|-----------|
-| Build Spec in Progress … Ready for Agent Implementation | none — status only |
-| **Agent Implementation** | ensures the branch is checked out locally (worktree or main repo) — the one step that creates a checkout when the branch has none — then **launches Claude** to implement the item. This is the only transition that starts code-writing automation |
+| Build Spec in Progress … Ready for Agent Implementation | none — status only. Build Spec in Progress, Refinement - Implementation and Ready for Agent Implementation take an optional teammate assignment (see below) |
+| **Agent Implementation** | ensures the branch is checked out locally (worktree or main repo) — the one step that creates a checkout when the branch has none — then **starts a Claude session** to implement the item, from one of the state's [entry points](#prompts). This is the only transition that starts code-writing automation |
 | **Dev Implementation** | commits and pushes the agent's work from the branch's checkout (a branch with no checkout here has its work on origin), creates the PR, removes the worktree if `removeWorktreeAtState` says so |
-| **Needs Approval for Release** | requires the PR, sets its assignee (required — the approver of record) and any requested reviewers, removes a legacy workflow context file if the branch still carries one (its final commit), and removes the worktree if configured. From here on the branch stays as it is |
+| **Needs Approval for Release** | takes a required teammate assignment: the item is assigned to the teammate, who approves the PR, so the PR is assigned to their linked GitHub account. Requires the PR, sets its assignee and any requested reviewers, removes a legacy workflow context file if the branch still carries one (its final commit), and removes the worktree if configured. From here on the branch stays as it is |
 | **Approved and Merged** | verifies you are the assignee, refuses a PR that conflicts with its base, waits for the CI/CD suite, merges the PR as it stands — the merge is the approval — then deletes the branch and worktree and fast-forwards your base branch checkout |
 | Released | none — normally set by GitHub automation when the work merges to `main` |
 
 `start` begins state management, `next` advances one state, `start-agent-implementation` jumps to Agent Implementation, and `ship-local-changes` takes uncommitted base-branch work all the way to Approved and Merged — all three reduce to the same engine, so branches and items always end up consistent with the state they are in. The engine and its layers are described in `src/workflow/README.md`.
 
+**Teammate assignment.** Some states take a teammate assignment for the item on the way in (`assignmentOnEntry` in `shared-config/workflow-states.json`): optional for Build Spec in Progress, Refinement - Implementation and Ready for Agent Implementation, required for Needs Approval for Release. A transition that enters any of them asks once, before anything else happens, for the teammate (`--assignee`, one of the team's members named by their email or linked GitHub login): an optional assignment offers **None**, the default, which keeps the current assignee; the required one offers the members alone, preselecting the current assignee, and the chosen teammate must have a linked GitHub account, since they are assigned the PR. The assignment is recorded with the first such state the run enters. An item out of scope (in no project) has no assignee: an optional assignment is skipped, and entering Needs Approval for Release is refused until the item is assigned to a project. A run on several targets asks for the teammate once, for all of them.
+
 ### Who approves what
 
 A change reaches production through two merges, and **each merge is its approval**.
 
-**Into `working/release`** — the PR's **assignee** (required) is its approver. They review the code and approve it by running `idea1 approve-pr`, which waits for the full CI/CD suite and then **merges** the PR. That is not the GitHub "Approve" button, which only leaves a review behind and merges nothing. A red or unfinished suite stops the merge, and there is no override at this stage. `approve-pr` checks that the person merging is the assignee; anyone else has to confirm explicitly, and the evidence report lists that merge as an exception. Requested reviewers are optional and record nothing. GitHub records the approval as `merged_by`, with its timestamp and merge commit.
+**Into `working/release`** — the PR's **assignee** (required) is its approver: the teammate the project item is assigned to on the way into Needs Approval for Release, through their linked GitHub account. They review the code and approve it by running `idea1 approve-pr`, which waits for the full CI/CD suite and then **merges** the PR. That is not the GitHub "Approve" button, which only leaves a review behind and merges nothing. A red or unfinished suite stops the merge, and there is no override at this stage. `approve-pr` checks that the person merging is the assignee; anyone else has to confirm explicitly, and the evidence report lists that merge as an exception. Requested reviewers are optional and record nothing. GitHub records the approval as `merged_by`, with its timestamp and merge commit.
 
-**Any other branch into `working/release`** — a branch with no project item takes the same gate. `idea1 ready-for-approval` opens its PR (with the approval chain of what the branch carries as the body) and names its assignee; `idea1 approve-pr` merges it once the suite passes, with the same no-override rule, and then deletes the branch. Only the idea1.ai status writes are absent. Integration branches work this way: work items PR into `working/integration/<name>-main` and are approved there exactly as above, then the integration branch itself is carried into `working/release` with these two commands — its PR body lists every work-item PR and who approved it, and `approve-pr` refuses while any PR still targets the integration branch.
+**Any other branch into `working/release`** — a branch with no project item takes the same gate. `idea1 ready-for-approval` opens its PR (with the approval chain of what the branch carries as the body) and names its assignee — a teammate, assigned through their linked GitHub account, with no item to assign; `idea1 approve-pr` merges it once the suite passes, with the same no-override rule, and then deletes the branch. Only the idea1.ai status writes are absent. Integration branches work this way: work items PR into `working/integration/<name>-main` and are approved there exactly as above, then the integration branch itself is carried into `working/release` with these two commands — its PR body lists every work-item PR and who approved it, and `approve-pr` refuses while any PR still targets the integration branch.
 
 **Into `main`** — `idea1 release` opens the release PR **assigned to whoever ran it**: the releaser is the approver, and their merge is the recorded approval. No review is required — every change in the release was already approved above, and the release PR body lists each contained PR with who approved it. What this stage gates is the build: the required CI/CD checks must pass first. In the default `create` mode the releaser merges the PR in GitHub once the checks are green; in `merge` mode (and with `idea1 release --approve`) the CLI turns on GitHub's auto-merge as the releaser, so GitHub merges once the checks pass and records the releaser as `merged_by`, or waits for the checks with `gh` and merges here where GitHub can't auto-merge. A release approved in the Idea1 web app is merged by the Idea1 GitHub App instead; the app first posts an approval comment naming the releaser, who is the PR's assignee, and that comment is the approval of record. An emergency admin override past a red check needs an explicit confirmation and a stated reason, and is recorded as a comment on the PR before the merge.
 
@@ -145,14 +150,15 @@ idea1 s --target <url>
 - `-t, --title <title>` - Title for the new project item (only when no target is given).
 - `-P, --project <name>` - The Project to create the new item in, chosen from the team's live Projects (only when no target is given; always asked, never defaulted).
 - `-p, --source-path <path>` - Path to source directory.
-- `-n, --branch-name <name>` - Branch name (auto-generated from the item description if not provided).
+- `-n, --branch-name <name>` - Branch name (auto-generated from the item description if not provided). Asked, blank to generate one, only when the item has no branch yet.
 - `-b, --base-branch <branch>` - Base branch / PR target (default: `working/release`).
-- `-w, --workflow-type <type>` - `independent` or `integration`; you also choose any stack branch and (for integration) the integration branch. Not asked when carrying local changes, which go onto an independent branch.
+- `-w, --workflow-type <type>` - `independent` or `integration`; you also choose any stack branch and (for integration) the integration branch. These are asked only when the command gives the item its branch, never for an item whose workflow context already holds one, and an option given on the command line is not asked. Carried local changes go onto an independent branch.
 - `-c, --carry-local-changes` - Make the uncommitted changes of your base branch checkout the item's work. See [Carrying local changes](#carrying-local-changes).
 - `--approve-and-merge` - Advance the item through every state up to **Approved and Merged** without prompting. See [Carrying local changes](#carrying-local-changes).
 - `-M, --commit-message <message>` - Commit message for carried changes (default: the new item's title).
 - `-iso, --isolation <mode>` - Where to work on the branch, when changes are carried or the item is approved and merged. See [Isolation mode](#isolation-mode).
 - `-r, --reviewers <user1,user2>` - Reviewers to request on the PR with `--approve-and-merge` (never asked; optional).
+- `-a, --assignee <email or GitHub login>` - Teammate to assign the item to as it enters Build Spec in Progress (optional; asked, with **None** preselected, when the command gives the item its branch). See [Teammate assignment](#how-the-workflow-engine-works).
 
 ### Carrying local changes
 
@@ -162,11 +168,11 @@ Work sometimes starts before its project item does: you make changes in your `wo
 2. Every uncommitted change — staged or not, plus untracked files that are not ignored — is committed on top of the checkout's commit without touching the checkout, and that commit becomes the tip of the item's branch on origin. For an item with no branch, the branch is created at that commit and recorded as the item's; an item whose branch exists takes the changes only while that branch has no commits of its own and no local checkout. The base branch itself is never committed to or pushed.
 3. The branch is checked out per the isolation mode: with `main-repo`, the checkout that held the changes switches to the branch with its working tree untouched (it is the branch's tip, so the checkout is clean); with `worktree`, the branch gets a worktree and the carried changes are removed from the base branch checkout.
 
-With `--approve-and-merge`, the item is then advanced through every workflow state up to **Approved and Merged** with nothing asked on the way: no Claude session is launched at Agent Implementation, the PR is created and assigned to **you** (the person who merges is the approver of record), the CLI waits for the required CI/CD checks — the same no-override gate as `approve-pr` — and merges, then brings your local base branch up to date with the merge. On a new item it needs changes to carry. A run that stops (failing checks, say) leaves the item at the last state it reached; fix the branch and run `idea1 approve-pr`, or run the command again with `--target`, to continue.
+With `--approve-and-merge`, the item is then advanced through every workflow state up to **Approved and Merged** with nothing asked on the way: no Claude session is launched at Agent Implementation, the item and its PR are assigned to **you** — the team member whose linked GitHub account `gh` is signed in as (the person who merges is the approver of record), the CLI waits for the required CI/CD checks — the same no-override gate as `approve-pr` — and merges, then brings your local base branch up to date with the merge. On a new item it needs changes to carry. A run that stops (failing checks, say) leaves the item at the last state it reached; fix the branch and run `idea1 approve-pr`, or run the command again with `--target`, to continue.
 
 ### ship-local-changes
 
-`start --carry-local-changes --approve-and-merge` as one unattended command: create a project item, cut its branch from `working/release`, commit and push your uncommitted changes there, advance it to Needs Approval for Release with a PR assigned to you, wait for the PR's checks and merge it into `working/release`. You end on `working/release`, clean, with your changes merged. The only questions are the ones a new item needs (its title and Project) when they are not supplied.
+`start --carry-local-changes --approve-and-merge` as one unattended command: create a project item, cut its branch from `working/release`, commit and push your uncommitted changes there, advance it to Needs Approval for Release assigned to you, with a PR assigned to you, wait for the PR's checks and merge it into `working/release`. You end on `working/release`, clean, with your changes merged. The only questions are the ones a new item needs (its title and Project) when they are not supplied.
 
 ```bash
 idea1 ship-local-changes --title "Release prep" --project "Omega"
@@ -194,7 +200,7 @@ With `--to <state>` the item advances through every state up to that one in a si
 idea1 next                        # on the item's branch
 idea1 next --target <url>         # from anywhere in the repository
 idea1 next --to "Dev Implementation"   # several states at once
-idea1 next --to "Needs Approval for Release" --target <url>,<url> --assignee octocat   # several items in parallel
+idea1 next --to "Needs Approval for Release" --target <url>,<url> --assignee name@company.com   # several items in parallel
 idea1 n
 ```
 
@@ -202,7 +208,8 @@ idea1 n
 - `--target <url | branch | PR url>[,...]` - The project item(s) (default: the current branch, when it is an item's).
 - `--to <state>` - Workflow state to advance to (default: the next state).
 - `-p, --source-path <path>` - Path to source directory.
-- Any option of the state being entered (for example `--model`/`--effort` for Agent Implementation, `--assignee`/`--reviewers` for Needs Approval for Release). Options that were not supplied are prompted for when that state is reached.
+- `-a, --assignee <email or GitHub login>` - Teammate to assign the item to, when a state entered takes an assignment (asked otherwise; see [Teammate assignment](#how-the-workflow-engine-works)).
+- Any option of the state being entered (for example `--model`/`--effort` for Agent Implementation, `--reviewers` for Needs Approval for Release). Options that were not supplied are prompted for when that state is reached.
 
 **What it does:**
 1. Reads the item's workflow context from idea1.ai (picking up changes made in the web client) and fast-forwards the local checkout to origin when it is behind.
@@ -214,25 +221,35 @@ The automation is idempotent, so re-running a transition after the item was move
 
 ### start-agent-implementation
 
-Start implementing a project item: put it under workflow management if needed, move it to **Agent Implementation** (through any intermediate states, which have no automation), set up the working environment and launch Claude Code with the implementation prompt — the repository's `prompts.agentImplementation` setting (see [Prompts](#prompts)), the built-in default, or a prompt you supply with `--entry-point-prompt`. This is the command behind "Send for Implementation" in the web client; `start-project-item` remains an alias so existing team command templates keep working.
+Start implementing a project item: put it under workflow management if needed, move it to **Agent Implementation** (through any intermediate states, which have no automation), set up the working environment and start a Claude Code session from one of the state's [entry point prompts](#prompts), a prompt you supply with `--entry-point-prompt`, or no prompt. This is the command behind "Send for Implementation" in the web client; `start-project-item` remains an alias so existing team command templates keep working.
 
 ```bash
 idea1 start-agent-implementation --target <url> [options]
-idea1 implement --target <url>
+idea1 implement --target <url> --entry-point Implement
 idea1 start-project-item --target <url>     # alias
 idea1 implement --target <url> --entry-point-prompt "Read the spec in docs/spec.md and implement step 3"
 ```
 
-**Options:** all `start` options, plus the Agent Implementation options:
+**Options:** all `start` options, plus the Agent Implementation options, which are the [Claude session options](#claude-session-options) with `--claude-entry-point` defaulting to `launch`, and:
 - `-iso, --isolation <mode>` - Where to work on the branch (default: `worktree`). See [Isolation mode](#isolation-mode).
-- `-pm, --permission-mode <mode>` - Claude permission mode (default: `plan`). Valid values: `acceptEdits`, `bypassPermissions`, `default`, `delegate`, `dontAsk`, `plan`
-- `-m, --model <model>` - Claude model for the implementation session (default: `opus`). Valid values: `fable`, `opus`, `sonnet`, `haiku`
-- `-e, --effort <level>` - Claude effort level (default: `high`). Valid values: `low`, `medium`, `high`, `xhigh`, `max`
-- `-im, --claude-entry-point <mode>` - How Claude is invoked once the environment is ready (default: `launch`). Valid values: `launch` (start a new Claude session), `inline` (output a structured prompt for an already-running Claude session), `none` (do not invoke Claude)
-- `-udp, --use-default-prompt <yes|no>` - Whether to launch Claude with the repository's implementation prompt, or the built-in one when the repository sets none (default: `yes`). Answering `no` asks for the prompt to use instead.
-- `-epp, --entry-point-prompt <prompt>` - The prompt to launch Claude with, replacing the implementation prompt. Supplying it skips the "Use default prompt?" question. It is a Handlebars template like the repository's prompt, so it can use the same [variables](#prompts).
+- `-a, --assignee <email or GitHub login>` - Teammate to assign the item to on the way (optional; asked, with **None** preselected, when a state entered takes an assignment).
 
-An item already in Agent Implementation is not transitioned again: the working environment is set up (or reused) and Claude is launched. With `--claude-entry-point none` the session options (permission mode, model, effort, prompt) are not asked.
+An item already in Agent Implementation is not transitioned again: the working environment is set up (or reused) and the session is started.
+
+### Claude session options
+
+The commands that start a Claude session on an item's branch (`start-agent-implementation`, `next` entering Agent Implementation, `join-project-item`) share these options. The model, effort and permission mode choices are defined once, in `shared-config/claude-sessions.json`, and shared with the web client. With `--claude-entry-point none` none of the others are asked.
+
+- `-im, --claude-entry-point <mode>` - How Claude is invoked once the environment is ready:
+  - `launch` - start a new Claude session in this terminal.
+  - `desktop` - start the session in Claude Desktop. With no `--model` and no `--effort`, Desktop opens a new local session on the working directory with the prompt, using Desktop's own model and effort; these two are not asked for a Desktop session. With either given, Desktop is brought up and the session runs in this terminal with that model and effort (the other one at its default), set to show in Desktop through remote control.
+  - `inline` - output the prompt as structured output for the Claude session that ran the CLI.
+  - `none` - do not invoke Claude.
+- `-ep, --entry-point <name|none>` - The entry point prompt to start with: the name of one of the workflow state's entry points (offered as a choice), or `none` to start Claude with no prompt.
+- `-epp, --entry-point-prompt <template>` - A prompt to start with instead of an entry point, for this session alone. It is a Handlebars template like the repository's entry points, so it can use the same [variables](#prompts). `--entry-point` and `--entry-point-prompt` are alternatives: give one, or pick which to answer when asked.
+- `-pm, --permission-mode <mode>` - Claude permission mode (default: `plan`; not used for a Desktop session). Valid values: `acceptEdits`, `bypassPermissions`, `default`, `delegate`, `dontAsk`, `plan`
+- `-m, --model <model>` - Claude model (default: `opus`). Valid values: `fable`, `opus`, `sonnet`, `haiku`
+- `-e, --effort <level>` - Claude effort level (default: `high`). Valid values: `low`, `medium`, `high`, `xhigh`, `max`
 
 ### Isolation mode
 
@@ -245,27 +262,31 @@ Supply `-iso worktree` or `-iso main-repo` on the command line to skip the promp
 
 ### join-project-item
 
-Join an **in-progress** project item by setting up a working environment on its existing branch — for picking up work started elsewhere (e.g. on another machine, by another developer, or from the web client). It does not change the workflow state and never launches a Claude implementation session.
+Join a project item where it is: set up a working environment on its branch and, when asked, start a Claude session in the item's **current workflow state**, from one of that state's [entry point prompts](#prompts). For picking up work started elsewhere (on another machine, by another developer, or from the web client) and for working on an item at any step: writing its spec, implementing it, reviewing its PR. It does not change the workflow state. The web client's **Join** action builds this command, or opens it through an [`idea1://` link](#idea1-links).
 
 ```bash
 idea1 join-project-item --target <url>
+idea1 join-project-item --target <url> --isolation worktree --claude-entry-point launch --entry-point "Review the PR" --model opus --effort high --permission-mode plan
+idea1 join-project-item --target <url> --isolation main-repo --claude-entry-point desktop --entry-point none
 idea1 join-project-item --target <branch>
-idea1 join-project-item --target <pr url>
-idea1 j --target <branch>
+idea1 j --target <pr url>
 ```
 
 **Options:**
 - `--target <url | branch | PR url>` - **Required.** The project item (its branch is discovered automatically), the branch to join (its project item is discovered automatically), or a GitHub PR (its head branch is joined). One target only.
 - `-p, --source-path <path>` - Path to source directory.
 - `-iso, --isolation <mode>` - Where to work on the branch (default: `worktree`). See [Isolation mode](#isolation-mode).
+- The [Claude session options](#claude-session-options), with `--claude-entry-point` defaulting to `none`. The entry points offered are those of the item's current state.
+- `-a, --assignee <email or GitHub login>` - Teammate to assign the item to, when joining starts an item that has no branch yet (optional; asked then, with **None** preselected).
 
 **What it does:**
 1. Resolves the branch from the URL (or the URL from the branch) through the item's workflow context on idea1.ai.
 2. Reuses the checkout that already holds the branch, or sets one up — a git worktree, or the branch checked out in the main repository (creating a local tracking branch if it only exists on origin).
-3. Reports the item the branch implements and its state. A branch outside workflow management is joined as plain git work; `attach-project-item` puts it under workflow.
+3. Reports the item the branch implements and its state. A branch outside workflow management is joined as plain git work, with no session; `attach-project-item` puts it under workflow.
 4. Runs any setup hooks defined in `.idea1/settings.json` (newly created worktrees only).
+5. Starts the Claude session asked for, from the chosen entry point of the item's state, rendered against the item's branch context.
 
-If a project item URL is supplied but no branch exists for it yet, `join-project-item` puts the item under workflow management first (as `start` does) and then sets up the environment.
+If a project item URL is supplied but no branch exists for it yet, `join-project-item` puts the item under workflow management first (as `start` does, asking the branching choices) and then sets up the environment; the session starts in **Build Spec in Progress**.
 
 ### attach-project-item
 
@@ -284,7 +305,7 @@ idea1 a --target <url>
 - `-t, --title <title>` - Title for the new project item (only when no target is given).
 - `-p, --source-path <path>` - Path to source directory.
 - `-b, --base-branch <branch>` - Base branch / PR target for an independent feature (default: `working/release`).
-- `-w, --workflow-type <type>` - Development workflow type: `independent` or `integration`. You also choose any stack branch and (for integration) the integration branch.
+- `-w, --workflow-type <type>` - Development workflow type: `independent` or `integration`. You also choose any stack branch and (for integration) the integration branch. Asked here because attaching records a new branch on the item; an option given on the command line is not asked.
 - `-c, --carry-local-changes`, `--approve-and-merge`, `-n, --branch-name`, `-M, --commit-message`, `-iso, --isolation`, `-r, --reviewers` - As for `start`.
 
 **What it does:**
@@ -316,36 +337,36 @@ idea1 dev --target <url>,<url>
 
 ### ready-for-approval
 
-For a project item, advance the item to **Needs Approval for Release** — the same as `next --to "Needs Approval for Release"`: from an earlier state, every state in between is entered first, each with its own automation (PR creation on the way into Dev Implementation, for one), and an item already at or past it is left as it is. For any other branch (an integration branch, a branch with no project item), open the branch's PR into the base branch when it has none. Either way its job is to name the **assignee**, who will approve the change by merging it. Several targets run in parallel.
+For a project item, advance the item to **Needs Approval for Release** — the same as `next --to "Needs Approval for Release"`: from an earlier state, every state in between is entered first, each with its own automation (PR creation on the way into Dev Implementation, for one), an item already in it enters it again, so its PR gets the assignee (and reviewers) named now, and an item past it is left as it is. For any other branch (an integration branch, a branch with no project item), open the branch's PR into the base branch when it has none. Either way its job is to name the **assignee** — a teammate, by email or GitHub login — who will approve the change by merging it: a project item is assigned to that teammate, and the PR to their linked GitHub account. Several targets run in parallel.
 
 ```bash
 idea1 ready-for-approval [options]
-idea1 rfa --assignee octocat
-idea1 rfa --assignee octocat                       # on working/integration/<name>-main: opens the PR into working/release
-idea1 rfa --assignee octocat -b working/release    # a branch with no project item, naming the PR target
-idea1 rfa --assignee octocat --target <url>,<branch>   # from working/release, in parallel
+idea1 rfa --assignee name@company.com
+idea1 rfa --assignee name@company.com                       # on working/integration/<name>-main: opens the PR into working/release
+idea1 rfa --assignee name@company.com -b working/release    # a branch with no project item, naming the PR target
+idea1 rfa --assignee name@company.com --target <url>,<branch>   # from working/release, in parallel
 ```
 
 **Options:**
 - `--target <url | branch | PR url>[,...]` - The project item(s) or branch(es) (default: the current branch; asked for on the base branch)
-- `-a, --assignee <username>` - **Required.** Who approves the PR by merging it (prompted from the repository's assignable users when omitted)
+- `-a, --assignee <email or GitHub login>` - **Required.** The teammate who approves the PR by merging it, one of the team's members with a linked GitHub account (asked when omitted: for a project item, preselecting its current assignee)
 - `-r, --reviewers <user1,user2>` - Who to request a review from (multi-select when omitted). Optional, and separate from approval — the assignee is the approver
 - `-b, --base-branch <branch>` - Branches with no project item only: the branch the PR targets (default: the open PR's base, else `baseBranch`, then `working/release`)
 - `--title <title>` - Branches with no project item only: PR title when the PR has to be created (default: `Integration <name> <YYYY-MM-DD>` for an integration branch, else the branch name; prompted when omitted)
 
 **What it does for a project item:**
-1. Enters every state before Needs Approval for Release the item has yet to reach (after syncing from origin)
+1. Resolves the teammate (refusing an item out of scope, which has no assignee, and a teammate with no linked GitHub account), then enters every state before Needs Approval for Release the item has yet to reach (after syncing from origin)
 2. Ensures no uncommitted or unpushed changes in the local checkout
-3. Requires the PR to exist, then sets the assignee (the transition refuses to proceed without one) and requests any reviewers
+3. Requires the PR to exist, then sets its assignee to the teammate's GitHub login and requests any reviewers
 4. Legacy branches only: removes the `.idea1/<branch>.json` workflow context file the branch still carries and pushes — the branch's final commit, so the CI/CD suite runs once more on exactly what will merge and the target branch receives the work alone
-5. Records "Needs Approval for Release" on Idea1.ai. From here on the branch stays as it is
+5. Records "Needs Approval for Release" on Idea1.ai, assigning the item to the teammate. From here on the branch stays as it is
 6. If in a worktree and `removeWorktreeAtState` is `Needs Approval for Release` (the default) or earlier, removes the worktree
 
 **What it does for a branch with no project item:**
 1. Requires the branch on origin and, when it is checked out here, nothing uncommitted, unpushed or behind origin in that checkout; refuses the base branch itself and refuses a PR straight into `main` (that is `idea1 release`)
 2. Reuses the branch's open PR (and its base) when one exists; otherwise creates the PR into the base branch with the approval chain of what the branch carries as its body — every PR merged into the branch with its author and approver, and commits pushed straight to the branch listed as the change under review (they are not an exception: this PR is their stage-1 approval)
-3. Sets the assignee and requests any reviewers
-4. Records no workflow status — there is no project item
+3. Sets the assignee (the teammate's GitHub login) and requests any reviewers
+4. Records no workflow status and assigns no item — there is no project item
 
 ### approve-pr
 
@@ -431,6 +452,29 @@ In interactive mode the whole sequence runs as a background job (see `/jobs`); o
 - checks still running — enables auto-merge, or waits for the checks and merges where GitHub can't auto-merge
 - a check failed — stops, unless a repository admin confirms the admin override, gives a reason, and has it recorded on the PR before the merge
 
+### idea1 links
+
+The web client's **Join** action for Claude Desktop opens an `idea1://join` link, which the CLI handles on macOS and Windows. Running any `idea1` command registers the CLI as this computer's handler of `idea1://` links, for the current user — on macOS an applet at `~/Applications/Idea1 URL Handler.app`, on Windows the `HKCU\Software\Classes\idea1` key. Registration is idempotent and is redone when the CLI's version, Node or install location changes.
+
+```bash
+idea1 register-url-handler      # register now
+idea1 unregister-url-handler    # remove it, and stop registering it automatically until register-url-handler
+idea1 open-url --url "idea1://join?target=...&repo=owner/name&isolation=worktree&app=desktop&entryPoint=none"
+```
+
+`open-url` is what the handler runs. It accepts only `idea1://join` links, with exactly these parameters, and refuses any other:
+
+| Parameter | Value |
+|-----------|-------|
+| `target` | **Required.** A project item URL of the Idea1 app |
+| `repo` | **Required.** The GitHub repository the item's work is in, as `owner/name` |
+| `isolation` | **Required.** `worktree` or `main-repo` |
+| `app` | **Required.** `desktop` |
+| `entryPoint` | **Required.** An entry point name, or `none`. Only ever a name: prompt text is never accepted |
+| `model`, `effort` | Optional. A model and an effort level, as for `--model` and `--effort`; absent is Desktop's own |
+
+It opens a new terminal (Terminal on macOS, Windows Terminal or a console on Windows) in the repository's local clone, running `idea1 join-project-item --target ... --isolation ... --claude-entry-point desktop --entry-point ...` with the link's values. The clone is found in `~/.idea1/repositories.json`, which every CLI run inside a GitHub repository's clone records; for a repository the CLI has not run in yet, the terminal asks where its clone is.
+
 ## Configuration
 
 ### Configuration Hierarchy
@@ -455,7 +499,11 @@ Create `.idea1/settings.json` in your repository root to configure repo-specific
     "setup-worktree": "dev/workflow/setup-worktree.sh"
   },
   "prompts": {
-    "agentImplementation": "Implement {{projectItemUrl}} on {{branchName}}."
+    "entryPoints": {
+      "Agent Implementation": [
+        { "name": "Implement", "template": "Implement {{projectItemUrl}} on {{branchName}}." }
+      ]
+    }
   },
   "defaults": {
     "branchPrefix": "working/agent",
@@ -469,7 +517,7 @@ Create `.idea1/settings.json` in your repository root to configure repo-specific
 - `setup-worktree` - Script to run after creating a new worktree (e.g., install dependencies)
 
 **Prompts:**
-- `agentImplementation` - The prompt an Agent Implementation session starts with. See [Prompts](#prompts).
+- `entryPoints` - The entry point prompts a Claude session can start with, by workflow state. See [Prompts](#prompts).
 
 **Release:** see [Release Settings](#release-settings).
 
@@ -502,7 +550,8 @@ The optional `release` section declares the repository folders `idea1 release` (
 `settings.json`. Anything it defines overrides the committed settings for that clone
 only, which keeps developer-specific preferences out of the shared configuration.
 `hooks`, `prompts`, `defaults` and `release` are merged section by section, so overriding one
-value leaves the rest of the committed settings in place.
+value leaves the rest of the committed settings in place; `prompts.entryPoints` is merged state
+by state.
 
 ```json
 {
@@ -518,37 +567,45 @@ Every prompt the CLI gives Claude is a [Handlebars](https://handlebarsjs.com/) t
 rendered against a data model, so a repository can replace a prompt with its own template
 using the full Handlebars syntax (`{{#if}}`, `{{#each}}`, `{{else}}`, ...).
 
-`prompts.agentImplementation` is the prompt an Agent Implementation session starts with
-(`start-agent-implementation`, or `next` entering Agent Implementation). It is either the
-template itself or the file that holds it, relative to the repository root:
+A Claude session on a project item's branch (`start-agent-implementation`, `next` entering
+Agent Implementation, `join-project-item`) starts from one of the **entry point prompts** of the
+item's workflow state, chosen by name with `--entry-point`. Every state has built-in entry
+points (defined in `shared-config/workflow-states.json`, shared with the web client); for
+example, Needs Approval for Release offers "Review the PR" and "Address PR feedback".
 
-```json
-{
-  "prompts": {
-    "agentImplementation": "/df-implement-project-item {{projectItemUrl}}"
-  }
-}
-```
+`prompts.entryPoints` gives a repository its own entry points, keyed by workflow state name.
+A state's entries replace that state's built-in ones; states the setting does not name keep
+theirs. Each entry has a `name`, unique within its state (and other than `none`), and either
+the template itself or the file that holds it, relative to the repository root:
 
 ```json
 {
   "prompts": {
-    "agentImplementation": { "templateFile": ".idea1/prompts/agent-implementation.md" }
+    "entryPoints": {
+      "Agent Implementation": [
+        { "name": "Implement", "template": "/df-implement-project-item {{projectItemUrl}}" }
+      ],
+      "Needs Approval for Release": [
+        { "name": "Review the PR", "templateFile": ".idea1/prompts/review.md" }
+      ]
+    }
   }
 }
 ```
 
-Without the setting, the built-in prompt asks Claude to implement the item from its Idea1
-context. `--entry-point-prompt` replaces both for one session and is rendered the same way.
-The settings are read from the main repository, so an override in its
-`settings.local.json` applies in worktrees too.
+State names are matched as the platform's statuses are (case-insensitively, earlier state names
+included); a key that names no workflow state is an error. `--entry-point-prompt` replaces the
+entry point for one session and is rendered the same way. The settings are read from the main
+repository, so an override in its `settings.local.json` applies in worktrees too. The Idea1
+web app reads the same setting from the repository on GitHub to offer the entry points in its
+Join action.
 
 The template renders against the item and its branch:
 
 | Variable | Value |
 |----------|-------|
 | `projectItemUrl` | The project item's URL |
-| `workflowStatus` | The item's workflow state (`Agent Implementation`) |
+| `workflowStatus` | The item's workflow state, e.g. `Agent Implementation` |
 | `repositoryFullName` | The repository, as `owner/name` |
 | `branchName` | The item's branch |
 | `baseBranch` | The branch the item's PR targets (the integration branch for integration work) |
@@ -593,9 +650,9 @@ its `.idea1/settings.json`.
 
 ## How the CLI uses Claude
 
-Every use of Claude Code goes through `src/services/claude.ts`, the only module that spawns `claude`. It always passes `--model` and `--effort`: a caller that states neither gets the documented defaults (`opus`, `high` — the same defaults the implementation session offers), so a run never inherits whatever was last picked in an interactive session.
+Every use of Claude Code goes through `src/services/claude.ts`, the only module that spawns `claude`. It always passes `--model` and `--effort`: a caller that states neither gets the documented defaults (`opus`, `high` — the same defaults a Claude session on an item offers), so a run never inherits whatever was last picked in an interactive session.
 
-Access to the Idea1 cloud platform — reading a project item's summary (by item or by the branch it implements), recording the item's workflow context, setting its workflow status, creating items, listing Projects, generating a branch name — goes through `src/services/platform.ts`. Its prompts are Handlebars templates in `src/prompts/`, rendered by `src/services/template-renderer.ts` like every other prompt. Today it drives the Idea1 MCP tools through Claude on `sonnet` at `medium` effort (these are simple tool calls, not implementation sessions); that transport is the module's implementation detail and may become direct calls to the platform API. The implementation session launched on entering Agent Implementation is the one place the model and effort are the user's choice (`--model`, `--effort`).
+Access to the Idea1 cloud platform — reading a project item's summary (by item or by the branch it implements), recording the item's workflow context, setting its workflow status, creating items, listing Projects, generating a branch name — goes through `src/services/platform.ts`. Its prompts are Handlebars templates in `src/prompts/`, rendered by `src/services/template-renderer.ts` like every other prompt. Today it drives the Idea1 MCP tools through Claude on `sonnet` at `medium` effort (these are simple tool calls, not implementation sessions); that transport is the module's implementation detail and may become direct calls to the platform API. A Claude session started on an item's branch (entering Agent Implementation, or joining an item) is the one place the model and effort are the user's choice (`--model`, `--effort`); a Claude Desktop session that names neither runs with Desktop's own. Opening URLs (Claude Desktop's `claude://` links) and terminal windows goes through `src/services/os-launcher.ts`, which uses only the tools macOS and Windows provide.
 
 ## Requirements
 

package/dist/cli/named-lists.d.ts

@@ -2,7 +2,7 @@
  * Resolve a named choice list to its current choices.
  * Throws if the name is not registered or the list is empty.
  */
-export declare function resolveNamedList(name: string): Promise<Array<{
+export declare function resolveNamedList(name: string, resolved: Record<string, string>): Promise<Array<{
     label: string;
     value: string;
 }>>;

package/dist/cli/named-lists.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"named-lists.d.ts","sourceRoot":"","sources":["../../src/cli/named-lists.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAYrG"}
+{"version":3,"file":"named-lists.d.ts","sourceRoot":"","sources":["../../src/cli/named-lists.ts"],"names":[],"mappings":"AA0CA;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAYvI"}

package/dist/cli/named-lists.js

@@ -1,5 +1,9 @@
 import * as github from '../services/github.js';
 import * as platform from '../services/platform.js';
+import { WorkflowStates } from '../workflow/data/workflow-states.js';
+import { entryPointChoices } from '../workflow/engine/agent-session.js';
+import { readTarget } from '../workflow/engine/workflow-engine.js';
+import { TARGET_OPTION_NAME } from '../jobs/targets.js';
 /**
  * Registry of named choice lists. Options reference these by name via
  * CommandOption.choices, letting multiple options share the same
@@ -13,18 +17,30 @@ const registry = {
     'idea1-projects': async () => {
         const projects = await platform.listProjects();
         return projects.map(name => ({ label: name, value: name }));
+    },
+    // The entry points of a session started on entering Agent Implementation.
+    'agent-implementation-entry-points': async () => entryPointChoices(WorkflowStates.AgentImplementation),
+    // The entry points of a session started in the workflow state of the item named by --target: an
+    // item yet to be started is started in the first state.
+    'target-state-entry-points': async (resolved) => {
+        const { item } = await readTarget(resolved[TARGET_OPTION_NAME]);
+        return entryPointChoices(item?.currentState ?? WorkflowStates.BuildSpecInProgress);
+    },
+    'team-members': async () => {
+        const members = await platform.listTeamMembers();
+        return members.map(member => ({ label: member.email, value: member.email }));
     }
 };
 /**
  * Resolve a named choice list to its current choices.
  * Throws if the name is not registered or the list is empty.
  */
-export async function resolveNamedList(name) {
+export async function resolveNamedList(name, resolved) {
     const provider = registry[name];
     if (!provider) {
         throw new Error(`Unknown choice list: '${name}'`);
     }
-    const choices = await provider();
+    const choices = await provider(resolved);
     if (choices.length === 0) {
         throw new Error(`Choice list '${name}' returned no options`);
     }

package/dist/cli/named-lists.js.map

@@ -1 +1 @@
-{"version":3,"file":"named-lists.js","sourceRoot":"","sources":["../../src/cli/named-lists.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AASpD;;;;GAIG;AACH,MAAM,QAAQ,GAAmC;IAC/C,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC3B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC3B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,CAAC;QAC/C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,QAAQ,EAAE,CAAC;IACjC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"named-lists.js","sourceRoot":"","sources":["../../src/cli/named-lists.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AASxD;;;;GAIG;AACH,MAAM,QAAQ,GAAmC;IAC/C,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC3B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAClD,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAC3B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,CAAC;QAC/C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,0EAA0E;IAC1E,mCAAmC,EAAE,KAAK,IAAI,EAAE,CAAC,iBAAiB,CAAC,cAAc,CAAC,mBAAmB,CAAC;IACtG,gGAAgG;IAChG,wDAAwD;IACxD,2BAA2B,EAAE,KAAK,EAAC,QAAQ,EAAC,EAAE;QAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAChE,OAAO,iBAAiB,CAAC,IAAI,EAAE,YAAY,IAAI,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACrF,CAAC;IACD,cAAc,EAAE,KAAK,IAAI,EAAE;QACzB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,eAAe,EAAE,CAAC;QACjD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC/E,CAAC;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,QAAgC;IACnF,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,uBAAuB,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/cli/parser.d.ts

@@ -1,8 +1,9 @@
 import type { Command, CommandOption } from '../types/index.js';
 /**
- * Resolve the default value of an option (handles static and dynamic defaults)
+ * Resolve the default value of an option (handles static and dynamic defaults). A dynamic default
+ * reads the values resolved so far; help output has none.
  */
-export declare function resolveDefault(option: CommandOption): string | undefined;
+export declare function resolveDefault(option: CommandOption, resolved?: Record<string, string>): string | undefined;
 /**
  * Parse command line arguments for a given command.
  * All arguments must be named: --longName value or -shortName value.

package/dist/cli/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGhE;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAGxE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkCzF;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAsBjC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0CxD"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGhE;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,GAAG,SAAS,CAG/G;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkCzF;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAsBjC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0CxD"}

package/dist/cli/parser.js

@@ -1,12 +1,13 @@
 import chalk from 'chalk';
 import { getAllCommands } from '../commands/index.js';
 /**
- * Resolve the default value of an option (handles static and dynamic defaults)
+ * Resolve the default value of an option (handles static and dynamic defaults). A dynamic default
+ * reads the values resolved so far; help output has none.
  */
-export function resolveDefault(option) {
+export function resolveDefault(option, resolved = {}) {
     if (option.defaultValue === undefined)
         return undefined;
-    return typeof option.defaultValue === 'function' ? option.defaultValue() : option.defaultValue;
+    return typeof option.defaultValue === 'function' ? option.defaultValue(resolved) : option.defaultValue;
 }
 /**
  * Parse command line arguments for a given command.

package/dist/cli/parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/cli/parser.ts"],"names":[],"mappings":"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"}

package/dist/cli/resolver.d.ts

@@ -10,6 +10,9 @@ import type { Command } from '../types/index.js';
  * For each option (in order):
  * 0. Skip if dependsOn is defined and returns false — the option is not
  *    applicable, so it is neither prompted nor required and left unset.
+ * 0a. For a member of a mutually-exclusive group, skip it unless it is the
+ *    group's active member: the one supplied on the CLI, else the applicable
+ *    member chosen when the group is first reached.
  * 1. Skip if isFlag — flags are never prompted
  * 2. Skip if already in parsed — value was provided on CLI
  * 2a. If resolveValue exists: let it resolve the value (it may ask), and use that

package/dist/cli/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/cli/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,mBAAmB,CAAC;AAKhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA6GjC"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/cli/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAiB,MAAM,mBAAmB,CAAC;AAKhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAoHjC"}