@iloom/cli 0.9.1 → 0.10.0

package/dist/prompts/init-prompt.txt

@@ -325,6 +325,47 @@ The following JSON Schema defines valid iloom settings:
                       "review": {
                         "type": "boolean",
                         "description": "Whether artifacts from this agent should be reviewed before posting (defaults to false)"
+                      },
+                      "agents": {
+                        "type": "object",
+                        "additionalProperties": {
+                          "type": "object",
+                          "properties": {
+                            "model": {
+                              "type": "string",
+                              "enum": [
+                                "sonnet",
+                                "opus",
+                                "haiku"
+                              ],
+                              "description": "Claude model shorthand: sonnet, opus, or haiku"
+                            },
+                            "enabled": {
+                              "type": "boolean",
+                              "description": "Whether this agent is enabled. Defaults to true."
+                            },
+                            "providers": {
+                              "type": "object",
+                              "additionalProperties": {
+                                "type": "string"
+                              },
+                              "propertyNames": {
+                                "enum": [
+                                  "claude",
+                                  "gemini",
+                                  "codex"
+                                ]
+                              },
+                              "description": "Map of review providers to model names. Keys: claude, gemini, codex. Values: model name strings (e.g., \"sonnet\", \"gemini-3-pro-preview\", \"gpt-5.2-codex\")"
+                            },
+                            "review": {
+                              "type": "boolean",
+                              "description": "Whether artifacts from this agent should be reviewed before posting (defaults to false)"
+                            }
+                          },
+                          "additionalProperties": false
+                        },
+                        "description": "Nested per-agent model overrides for swarm mode. Configure under agents.iloom-swarm-worker.agents.<agent-name>.model to set a different model for phase agents when running inside swarm workers. Fallback chain: swarm-specific agent model > explicit swarm worker model > base agent model. Only meaningful under the iloom-swarm-worker agent entry."
                       }
                     },
                     "additionalProperties": false
@@ -336,7 +377,7 @@ The following JSON Schema defines valid iloom settings:
               "type": "null"
             }
           ],
-          "description": "Per-agent configuration overrides. Available agents: iloom-issue-analyzer (analyzes issues), iloom-issue-planner (creates implementation plans), iloom-issue-analyze-and-plan (combined analysis and planning), iloom-issue-complexity-evaluator (evaluates complexity), iloom-issue-enhancer (enhances issue descriptions), iloom-issue-implementer (implements code changes), iloom-code-reviewer (reviews code changes against requirements), iloom-artifact-reviewer (reviews artifacts before posting)"
+          "description": "Per-agent configuration overrides. Available agents: iloom-issue-analyzer (analyzes issues), iloom-issue-planner (creates implementation plans), iloom-issue-analyze-and-plan (combined analysis and planning), iloom-issue-complexity-evaluator (evaluates complexity), iloom-issue-enhancer (enhances issue descriptions), iloom-issue-implementer (implements code changes), iloom-code-reviewer (reviews code changes against requirements), iloom-artifact-reviewer (reviews artifacts before posting), iloom-swarm-worker (swarm worker agent, dynamically generated). The iloom-swarm-worker agent supports a nested \"agents\" sub-record for configuring phase agent models specifically in swarm mode."
         },
         "spin": {
           "type": "object",
@@ -413,17 +454,6 @@ The following JSON Schema defines valid iloom settings:
         "capabilities": {
           "type": "object",
           "properties": {
-            "capabilities": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "enum": [
-                  "cli",
-                  "web"
-                ]
-              },
-              "description": "Explicitly declared project capabilities (auto-detected if not specified)"
-            },
             "web": {
               "type": "object",
               "properties": {
@@ -434,7 +464,8 @@ The following JSON Schema defines valid iloom settings:
                   "description": "Base port for web workspace port calculations (default: 3000)"
                 }
               },
-              "additionalProperties": false
+              "additionalProperties": false,
+              "description": "Web dev server settings. To declare a project as a web project, add \"web\" to the capabilities array in .iloom/package.iloom.json or .iloom/package.iloom.local.json."
             },
             "database": {
               "type": "object",
@@ -489,10 +520,11 @@ The following JSON Schema defines valid iloom settings:
               "type": "string",
               "enum": [
                 "github",
-                "linear"
+                "linear",
+                "jira"
               ],
               "default": "github",
-              "description": "Issue tracker provider (github, linear)"
+              "description": "Issue tracker provider (github, linear, jira)"
             },
             "github": {
               "type": "object",
@@ -529,6 +561,69 @@ The following JSON Schema defines valid iloom settings:
                 "teamId"
               ],
               "additionalProperties": false
+            },
+            "jira": {
+              "type": "object",
+              "properties": {
+                "host": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Jira instance URL (e.g., \"https://yourcompany.atlassian.net\")"
+                },
+                "username": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Jira username or email address"
+                },
+                "apiToken": {
+                  "type": "string",
+                  "description": "Jira API token. SECURITY: Store in settings.local.json only, never commit to source control. Generate at: https://id.atlassian.com/manage-profile/security/api-tokens"
+                },
+                "projectKey": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Jira project key (e.g., \"PROJ\", \"ENG\")"
+                },
+                "boardId": {
+                  "type": "string",
+                  "description": "Jira board ID for sprint/workflow operations (optional)"
+                },
+                "transitionMappings": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  },
+                  "description": "Map iloom states to Jira transition names (e.g., {\"In Review\": \"Start Review\"})"
+                },
+                "defaultIssueType": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "Task",
+                  "description": "Default Jira issue type name for creating issues (e.g., \"Task\", \"Story\", \"Bug\")"
+                },
+                "defaultSubtaskType": {
+                  "type": "string",
+                  "minLength": 1,
+                  "default": "Subtask",
+                  "description": "Default Jira issue type name for creating subtasks/child issues (e.g., \"Subtask\", \"Sub-task\")"
+                },
+                "doneStatuses": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "default": [
+                    "Done"
+                  ],
+                  "description": "Status names to exclude from issue lists (e.g., [\"Done\", \"Closed\", \"Verify\"])"
+                }
+              },
+              "required": [
+                "host",
+                "username",
+                "projectKey"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false,
@@ -552,6 +647,11 @@ The following JSON Schema defines valid iloom settings:
             "autoCommitPush": {
               "type": "boolean",
               "description": "Auto-commit and push after code review in draft PR mode. Defaults to true when mode is github-draft-pr."
+            },
+            "openBrowserOnFinish": {
+              "type": "boolean",
+              "default": true,
+              "description": "Open the PR in the default browser after finishing in github-pr or github-draft-pr mode. Use --no-browser flag to override."
             }
           },
           "additionalProperties": false,
@@ -604,6 +704,21 @@ The following JSON Schema defines valid iloom settings:
           ],
           "default": "upstreamOnly",
           "description": "Controls when iloom attribution appears in session summaries. \"off\" - never show attribution. \"upstreamOnly\" - only show for contributions to external repositories (e.g., open source). \"on\" - always show attribution."
+        },
+        "git": {
+          "type": "object",
+          "properties": {
+            "commitTimeout": {
+              "type": "number",
+              "minimum": 1000,
+              "maximum": 600000,
+              "default": 60000,
+              "description": "Timeout in milliseconds for git commit operations. Increase for long-running pre-commit hooks."
+            }
+          },
+          "additionalProperties": false,
+          "default": {},
+          "description": "Git operation settings"
         }
       },
       "additionalProperties": false
@@ -698,7 +813,6 @@ Parse both settings.json and settings.local.json. Merge them with local taking p
 
 Extract these current values if they exist:
 - `currentMainBranch` from `mainBranch` field (default: "main")
-- `currentWorktreePrefix` from `worktreePrefix` field (default: null which means use default - NOTE: "" does not mean default)
 - `currentPermissionMode` from `workflows.issue.permissionMode` field (default: "acceptEdits")
 - `currentBasePort` from `capabilities.web.basePort` field (default: 3000)
 - `currentMergeMode` from `mergeBehavior.mode` field (default: "local")
@@ -706,6 +820,10 @@ Extract these current values if they exist:
 - `currentIssueProvider` from `issueManagement.provider` field (default: "github")
 - `currentLinearTeamId` from `issueManagement.linear.teamId` field (if Linear is provider)
 - `currentGitHubRemote` from `issueManagement.github.remote` field (if GitHub is provider and multiple remotes)
+- `currentJiraHost` from `issueManagement.jira.host` field (if Jira is provider)
+- `currentJiraUsername` from `issueManagement.jira.username` field (if Jira is provider)
+- `currentJiraProjectKey` from `issueManagement.jira.projectKey` field (if Jira is provider)
+- `currentJiraBoardId` from `issueManagement.jira.boardId` field (if Jira is provider, optional)
 
 **If configuration already exists, display current configuration summary:**
 
@@ -713,13 +831,15 @@ Extract these current values if they exist:
 Current Configuration:
 ━━━━━━━━━━━━━━━━━━━━━
 Main Branch: [currentMainBranch or "main (default)"]
-Worktree Prefix: [currentWorktreePrefix or "default (repo-name-looms)"]
 Permission Mode (Issues): [currentPermissionMode or "acceptEdits (default)"]
 Base Port: [currentBasePort or "3000 (default)"]
 IDE: [currentIdeType or "vscode (default)"]
 Issue Tracker: [currentIssueProvider or "github (default)"]
 Linear Team ID: [currentLinearTeamId] (only if currentIssueProvider == linear)
 {{#if MULTIPLE_REMOTES}}GitHub Remote: [currentGitHubRemote] (only if currentIssueProvider == github){{/if}}
+Jira Host: [currentJiraHost] (only if currentIssueProvider == jira)
+Jira Project Key: [currentJiraProjectKey] (only if currentIssueProvider == jira)
+Jira Board ID: [currentJiraBoardId] (only if currentIssueProvider == jira and boardId is set)
 ```
 
 **Then ask the user what they want to do:**
@@ -758,18 +878,7 @@ Use AskUserQuestion to ask ALL local development settings questions **IN A SINGL
    - Validation: Non-empty string
    - Store answer as: `mainBranch`
 
-2. **Worktree Prefix**
-   - Question format: "What prefix should iloom use for worktree directories?{{#if currentWorktreePrefix}} (Currently: [currentWorktreePrefix]){{/if}} Leave empty to use default (<repo-name>-looms)."
-   - Options (as examples):
-     - Use default prefix (recommened)
-     - "looms" - Simple 'looms-' prefix
-     - Empty - each loom will be a sibling of this directory
-   - Default: currentWorktreePrefix or default (NOTE: empty does NOT mean use default)
-   - Validation: If not empty, only alphanumeric characters, hyphens, underscores, and forward slashes allowed
-   - Store answer as: `worktreePrefix`
-   - Note: If user specifies default, omit this field from settings, it they say empty, add an empty string to the settings
-
-3. **Permission Mode for Issue Workflows**
+2. **Permission Mode for Issue Workflows**
    - Question format: "What permission mode should Claude use when working on issues?{{#if currentPermissionMode}} (Currently: [currentPermissionMode]){{/if}}"
    - Options:
      - "default" - Use Claude Code's default behavior
@@ -780,7 +889,7 @@ Use AskUserQuestion to ask ALL local development settings questions **IN A SINGL
    - Validation: Must be one of: default, plan, acceptEdits, bypassPermissions
    - Store answer as: `workflows.issue.permissionMode` - NOTE: this is a personal preference - recommend it be stored in the gitignored local settings file.
 
-4. **Base Port**
+3. **Base Port**
    - Question format: "What base port should web development servers use?{{#if currentBasePort}} (Currently: [currentBasePort]){{/if}}"
    - Options (as examples):
      - "3000" - Common Node.js default
@@ -812,7 +921,69 @@ The agent will:
 4. Create `.iloom/package.iloom.json` with the detected configuration
 5. Detect and set project capabilities (cli, web) based on the framework
 
-**File Format:**
+**package.iloom.json Schema:**
+```json
+{
+  "$ref": "#/definitions/PackageIloom",
+  "definitions": {
+    "PackageIloom": {
+      "type": "object",
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "cli",
+              "web"
+            ]
+          },
+          "description": "Project capabilities - \"cli\" for command-line tools (enables CLI isolation), \"web\" for web applications (enables port assignment and dev server)"
+        },
+        "scripts": {
+          "type": "object",
+          "properties": {
+            "install": {
+              "type": "string",
+              "description": "Install command (e.g., \"bundle install\", \"poetry install\")"
+            },
+            "build": {
+              "type": "string",
+              "description": "Build/compile command"
+            },
+            "test": {
+              "type": "string",
+              "description": "Test suite command"
+            },
+            "dev": {
+              "type": "string",
+              "description": "Dev server command"
+            },
+            "lint": {
+              "type": "string",
+              "description": "Linting command"
+            },
+            "typecheck": {
+              "type": "string",
+              "description": "Type checking command"
+            },
+            "compile": {
+              "type": "string",
+              "description": "Compilation command (preferred over typecheck if both exist)"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Custom shell commands for project operations. These are raw shell commands, not npm script names."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}
+```
+
+**File Format Example:**
 ```json
 {
   "capabilities": ["cli"],
@@ -853,7 +1024,16 @@ If the framework detector did not set capabilities, or if you need to ask the us
   - "web" - Web application with dev server
   - "both" - Both CLI and web capabilities
   - "neither" - Library or other project type
-- Update `.iloom/package.iloom.json` with the appropriate `capabilities` array.
+
+**Choose where to save package.iloom configuration:**
+
+After determining the configuration, ask the user where to save it:
+- **Project** (`package.iloom.json`) - Shared with team, committed to git
+- **Local** (`package.iloom.local.json`) - Local only, gitignored, never committed
+
+Default to **Local** if fork was detected (origin + upstream remotes). Otherwise default to **Project**.
+
+Write the capabilities and scripts to the chosen file.
 
 **When to infer capabilities:**
 - Flask/Django/FastAPI/Rails/Actix/Rocket detected -> include "web"
@@ -871,7 +1051,7 @@ This phase configures external tooling integrations. Use AskUserQuestion to gath
 **Step 1: Issue Tracker Provider**
 
 {{#if MULTIPLE_REMOTES}}
-Since this repository has multiple git remotes, GitHub Issues is suggested as the default since it integrates with your existing GitHub workflow. However, you can choose Linear if that's your team's issue tracker.
+Since this repository has multiple git remotes, GitHub Issues is suggested as the default since it integrates with your existing GitHub workflow. However, you can choose Linear or Jira if that's your team's issue tracker.
 {{/if}}
 
 1. **Issue Tracker Provider**
@@ -879,8 +1059,9 @@ Since this repository has multiple git remotes, GitHub Issues is suggested as th
    - Options:
      - "github" - GitHub Issues (default)
      - "linear" - Linear Issues
+     - "jira" - Jira Cloud
    - Default: currentIssueProvider or "github"
-   - Validation: Must be one of: github, linear
+   - Validation: Must be one of: github, linear, jira
    - Store answer as: `issueManagement.provider`
 
 **Note on Provider + Merge Mode Combinations:**
@@ -888,6 +1069,8 @@ Since this repository has multiple git remotes, GitHub Issues is suggested as th
 - GitHub Issues + github-pr or github-draft-pr: Requires authorized GitHub CLI (`gh`)
 - Linear Issues + local merge: Requires Linear API token only
 - Linear Issues + github-pr or github-draft-pr: Requires BOTH Linear API token AND authorized GitHub CLI (`gh`)
+- Jira Cloud + local merge: Requires Jira credentials (host, username, API token) only
+- Jira Cloud + github-pr or github-draft-pr: Requires BOTH Jira credentials AND authorized GitHub CLI (`gh`)
 
 **Step 2: Provider-Specific Configuration**
 
@@ -943,6 +1126,59 @@ This repository has multiple git remotes detected. iloom needs to know which rem
    - **CRITICAL SECURITY REQUIREMENT:** This value MUST ALWAYS be saved to `settings.local.json`, NEVER to `settings.json`, regardless of which file the user selected for other settings. This token must never be committed to source control.
    - Context: Get your API token from Linear Settings → API → Personal API Keys (https://linear.app/settings/api)
 
+**If Jira was selected:**
+
+2. **Jira Host URL** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira instance URL?{{#if currentJiraHost}} (Currently: [currentJiraHost]){{/if}}"
+   - Options (as examples):
+     - "https://yourcompany.atlassian.net" - Jira Cloud instance
+   - Default: currentJiraHost or NO DEFAULT (required if Jira is selected)
+   - Validation: Non-empty string, must be a valid URL. If the user provides a value without `https://`, automatically prepend `https://` (e.g., `yourcompany.atlassian.net` becomes `https://yourcompany.atlassian.net`). Strip any trailing slashes.
+   - Store answer as: `issueManagement.jira.host`
+   - Context: This is your Jira Cloud instance URL (e.g., "https://yourcompany.atlassian.net")
+
+3. **Jira Username/Email** (only ask if issue provider is "jira")
+   - Question format: "What is your Atlassian account email?{{#if currentJiraUsername}} (Currently: [currentJiraUsername]){{/if}}"
+   - Default: currentJiraUsername or NO DEFAULT (required if Jira is selected)
+   - Validation: Non-empty string
+   - Store answer as: `issueManagement.jira.username`
+   - **CRITICAL SECURITY REQUIREMENT:** This value MUST ALWAYS be saved to `settings.local.json`, NEVER to `settings.json`, regardless of which file the user selected for other settings. This is personal account information that should not be committed to source control.
+   - Context: This is the email address associated with your Atlassian account
+
+4. **Jira API Token** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira API token? (Currently: 'set' or 'unset' - do not print)"
+   - Options:
+     - I have it now - use the "Type something" option to enter it
+     - I'll come back to it
+   - Default: currentJiraApiToken or NO DEFAULT
+   - Validation: Non-empty string
+   - Guidance: Choose "Type something" to enter it
+   - Store answer as: `issueManagement.jira.apiToken`
+   - **CRITICAL SECURITY REQUIREMENT:** This value MUST ALWAYS be saved to `settings.local.json`, NEVER to `settings.json`, regardless of which file the user selected for other settings. This token must never be committed to source control.
+   - Context: Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens
+
+5. **Jira Project Key** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira project key?{{#if currentJiraProjectKey}} (Currently: [currentJiraProjectKey]){{/if}}"
+   - Options (as examples):
+     - "PROJ" - Project team
+     - "ENG" - Engineering team
+   - Default: currentJiraProjectKey or NO DEFAULT (required if Jira is selected)
+   - Validation: Non-empty string, typically uppercase letters
+   - Store answer as: `issueManagement.jira.projectKey`
+   - Context: This is the project key prefix shown in your Jira issue IDs (e.g., "PROJ" in "PROJ-123")
+
+6. **Jira Board ID** (only ask if issue provider is "jira")
+   - Question format: "What is your Jira board ID? (optional, used for sprint filtering){{#if currentJiraBoardId}} (Currently: [currentJiraBoardId]){{/if}}"
+   - Options:
+     - Skip - Don't configure board ID now
+     - Enter board ID - use the "Type something" option to enter it
+   - Default: currentJiraBoardId or SKIP (optional)
+   - Validation: If provided, must be a numeric string
+   - Store answer as: `issueManagement.jira.boardId`
+   - Context: The board ID can be found in the URL when viewing a Jira board (e.g., `/board/42`). This is optional and used for sprint-based filtering with `il issues --sprint`.
+
+   **Note:** Advanced Jira settings like `transitionMappings`, `doneStatuses`, `defaultIssueType`, and `defaultSubtaskType` can be configured later by editing the settings files directly. Mention this to the user.
+
 **Step 3: IDE Selection**
 
 4. **IDE Selection**
@@ -980,7 +1216,7 @@ This repository has multiple git remotes detected. iloom needs to know which rem
 
 **Implementation Details:**
 - Ask Step 1 first to determine provider
-- Then ask Step 2 based on the provider selected (includes Linear API Token if Linear was selected)
+- Then ask Step 2 based on the provider selected (includes Linear API Token if Linear was selected, or Jira credentials if Jira was selected)
 - Ask Step 3 (IDE) for all users
 - Ask Step 4 (Merge Mode) only if multiple remotes detected OR user requests advanced config
 - Set multiSelect: false for all questions
@@ -1030,7 +1266,6 @@ Configuration Summary:
 
 Local Development Settings (Phase 1):
   Main Branch: [value]
-  Worktree Prefix: [value or "default (repo-name-looms)"]
   Permission Mode (Issues): [value]
   Base Port: [value]
 
@@ -1039,6 +1274,10 @@ Tooling Configuration (Phase 2):
   Linear Team ID: [value] (only if issue tracker is Linear)
   Linear API Token: [configured/not configured] (only if issue tracker is Linear - never show actual token)
   {{#if MULTIPLE_REMOTES}}GitHub Remote: [value] (only if issue tracker is GitHub){{/if}}
+  Jira Host: [value] (only if issue tracker is Jira)
+  Jira Project Key: [value] (only if issue tracker is Jira)
+  Jira Board ID: [value or "not configured"] (only if issue tracker is Jira)
+  Jira API Token: [configured/not configured] (only if issue tracker is Jira - never show actual token)
   IDE: [value or "vscode (default)"]
   Merge Mode: [value] (only if configured)
 ```
@@ -1046,6 +1285,7 @@ Tooling Configuration (Phase 2):
 **Note**:
 - Include the GitHub Remote line in the summary ONLY if it was configured in Phase 2 (multiple remotes and GitHub selected)
 - Include Linear Team ID ONLY if Linear was selected as the issue tracker provider
+- Include Jira Host, Project Key, Board ID, and API Token ONLY if Jira was selected as the issue tracker provider
 - Include Merge Mode ONLY if it was asked and configured (multiple remotes or advanced config)
 
 Then ask: "Does this configuration look correct?"
@@ -1184,6 +1424,46 @@ When both settings.json and settings.local.json exist, you MUST prevent duplicat
    }
    ```
 
+   **For Jira:**
+
+   In settings.json (committed):
+   ```json
+   {
+     "issueManagement": {
+       "provider": "jira",
+       "jira": {
+         "host": "<user's Jira host URL>",
+         "projectKey": "<user's project key>"
+       }
+     }
+   }
+   ```
+
+   In settings.local.json (gitignored - MUST be separate from settings.json):
+   ```json
+   {
+     "issueManagement": {
+       "jira": {
+         "username": "<user's Atlassian email>",
+         "apiToken": "<user's API token>"
+       }
+     }
+   }
+   ```
+
+   If a boardId was provided, add it to settings.json alongside host and projectKey:
+   ```json
+   {
+     "issueManagement": {
+       "jira": {
+         "boardId": "<user's board ID>"
+       }
+     }
+   }
+   ```
+
+   **CRITICAL:** The `username` and `apiToken` fields MUST be saved to `settings.local.json`, never to `settings.json`. The `host`, `projectKey`, and `boardId` fields are safe to commit in `settings.json`.
+
 6. **Add mergeBehavior ONLY if mode is not "local":**
    ```json
    {
@@ -1314,16 +1594,16 @@ Would you like to commit these changes?
   - Yes - Commit iloom configuration changes (strongly recommended)
   - No - Skip committing (not recommended)
 
-⚠️  WARNING: If you don't commit settings.json, iloom will not work correctly in new looms.
+⚠️  WARNING: If you don't commit settings.json and package.iloom.json, iloom will not work correctly in new looms.
     Looms are created from committed code, so your configuration won't be available.
-    (Local files like settings.local.json and .env are copied automatically - but settings.json must be committed.)
+    (Local files like settings.local.json, package.iloom.local.json, and .env are copied automatically - but shared files must be committed.)
 ```
 
 **CRITICAL RULES:**
-- **ONLY commit iloom-related files**: .iloom/settings.json, .gitignore
+- **ONLY commit iloom-related files**: .iloom/settings.json, .iloom/package.iloom.json, .gitignore
 - **NEVER stage or commit unrelated files** - even if they appear in `git status`
 - **If the commit fails, you must then subsequently request to use --no-verify flag** to bypass pre-commit hooks that might fail due to unrelated codebase state
-- **Do NOT commit settings.local.json** - it should be gitignored, not committed
+- **Do NOT commit local-only files** - settings.local.json and package.iloom.local.json should be gitignored, not committed
 - **YOU MAY NEED TO EDIT/UPDATE MORE THAN ONE FILE if the user is changing something like API Keys (local only), permissionsMode (local only), IDE (recommened global) as well as shared settings.
 
 **Step 3: If user says yes, commit the changes**
@@ -1332,10 +1612,10 @@ VERIFY YOU'RE NOT BUNDLING ALL CHANGES IN ONE FILE DESPITE GUIDANCE TO SPLIT ACC
 
 Stage ONLY the iloom-related files that should be committed:
 ```bash
-git add .iloom/settings.json .gitignore 2>/dev/null || true
+git add .iloom/settings.json .iloom/package.iloom.json .gitignore 2>/dev/null || true
 ```
 
-Note: Do NOT add .iloom/settings.local.json - it's meant to be local-only.
+Note: Do NOT add local-only files (.iloom/settings.local.json, .iloom/package.iloom.local.json) - they should be gitignored, not committed.
 
 Then commit:
 
@@ -1398,18 +1678,30 @@ Here's how to get started:
   • Run `iloom finish` when you're done working to merge changes and clean up
 
 Need more advanced configuration? I can help you set up:
+  • Merge Behavior - Choose between local merge, GitHub PR, or draft PR workflows
+  • Copy Gitignored Files - Automatically copy local databases, test fixtures, or other gitignored files to new looms
+  • Multi-Provider Code Review - Get code reviews from Gemini or Codex alongside Claude
+  • Plan Configuration - Use different AI providers for planning and plan review
   • Agent Models - Use different Claude models for different tasks
+  • Swarm Agent Models - Configure different models for agents when running in swarm mode
   • Database Settings - Configure database branching for isolated development
+  • Skip Pre-Commit Hooks - Bypass slow or failing hooks during commit and finish workflows
   • Workflow Behavior - Control permissions, IDE launching, dev servers, and terminal behavior
   • Protected Branches - Prevent iloom from creating worktrees for certain branches
   • Custom Scripts - Override package.json scripts with custom commands
 
 You can ask me questions like:
+  "How do I set up GitHub PR mode instead of local merge?"
+  "How do I copy my local SQLite database to new looms?"
+  "Can I get code reviews from Gemini as well as Claude?"
+  "How do I use Codex for planning?"
   "Is it possible to have the analysis agent use a different model?"
   "How do I configure database branching?"
+  "How do I skip pre-commit hooks?"
   "Can I disable the IDE from launching automatically?"
   "How do I protect my main branch from worktree creation?"
   "What models are available for the different agents?"
+  "How do I use different models for swarm workers vs normal mode?"
   "How do I use custom build/test commands instead of package.json scripts?"
 
 Just ask any of these questions and I'll help you modify your settings.
@@ -1441,6 +1733,35 @@ When configuring agents, use these model identifiers:
    }
    ```
 
+   **Swarm-Specific Phase Agent Models:**
+
+   In swarm mode, you can configure different models for phase agents (analyzer, planner, implementer, etc.) than in normal mode:
+
+   ```json
+   "agents": {
+     "iloom-issue-implementer": {
+       "model": "opus"
+     },
+     "iloom-swarm-worker": {
+       "model": "opus",
+       "agents": {
+         "iloom-issue-implementer": {
+           "model": "sonnet"
+         },
+         "iloom-issue-planner": {
+           "model": "haiku"
+         }
+       }
+     }
+   }
+   ```
+
+   Fallback chain in swarm mode:
+   1. `agents.iloom-swarm-worker.agents.<agent>.model` (swarm-specific per-agent)
+   2. `agents.iloom-swarm-worker.model` (blanket swarm worker model)
+   3. `agents.<agent>.model` (base per-agent model)
+   4. Agent default from its definition file
+
 2. **Database Environment Variable:**
    ```json
    "capabilities": {
@@ -1462,19 +1783,26 @@ When configuring agents, use these model identifiers:
    }
    ```
 
-4. **Protected Branches:**
+4. **Copy Gitignored Files:**
+   ```json
+   "copyGitIgnoredPatterns": ["*.db", "data/*.sqlite", "tmp/fixtures/**"]
+   ```
+
+   Glob patterns for gitignored files that should be copied to new looms. Useful for local databases, large test fixtures, or generated files that are too big to commit. Note: `.env` files and iloom/claude local settings are automatically copied and don't need to be listed here.
+
+5. **Protected Branches:**
    ```json
    "protectedBranches": ["main", "production", "release/*"]
    ```
 
-5. **IDE Configuration:**
+6. **IDE Configuration:**
    ```json
    "ide": {
      "type": "cursor"
    }
    ```
 
-6. **Code Review with Multiple Providers:**
+7. **Code Review with Multiple Providers:**
    ```json
    "agents": {
      "iloom-code-reviewer": {
@@ -1488,7 +1816,7 @@ When configuring agents, use these model identifiers:
 
    This configures the code reviewer to use both Claude and Gemini for reviews. Multiple providers can be configured to get reviews from different AI models.
 
-7. **Custom Script Configuration (package.iloom.json):**
+8. **Custom Script Configuration (package.iloom.json):**
 
    If users want to override or supplement npm scripts with custom commands, help them create `.iloom/package.iloom.json`:
    ```json
@@ -1546,6 +1874,15 @@ When configuring agents, use these model identifiers:
    - Your local environment needs different commands than the team standard
    - You want to add debug flags or local-only tooling without affecting others
 
+## Telemetry
+
+iloom collects anonymous usage data to improve the product. If the user asks about telemetry or data collection during setup:
+
+- **CLI telemetry**: Managed via `il telemetry off` (disable) and `il telemetry on` (re-enable). Run `il telemetry status` to check current state.
+- **VS Code extension telemetry**: If the user also uses the iloom VS Code extension, its telemetry is managed separately via VS Code settings (`iloom.telemetry.enabled`). Disabling CLI telemetry does NOT affect the extension, and vice versa.
+- **What's collected**: Only anonymous usage events (commands run, errors). No personal information, repo names, or code.
+- **Distinct ID**: A random UUID stored in `~/.config/iloom-ai/telemetry.json`, shared between CLI and VS Code extension.
+
 ## Important Notes
 
 - **Validate ALL inputs** against the schema before writing files
@@ -1554,7 +1891,7 @@ When configuring agents, use these model identifiers:
 - **For existing users** - Ask what they want to do (modify, add advanced config, start fresh, or exit) instead of forcing them through the entire flow
 - **For new users** - Skip directly to Phase 1 (Local Development Settings) and proceed through Phase 2 (Tooling Configuration)
 - **ALWAYS use the question formats** specified in Phase 1 and Phase 2 that include "(Currently: [value])" when current values exist
-- **Phase 1 = Local dev settings** (main branch, worktree prefix, permission mode, base port)
+- **Phase 1 = Local dev settings** (main branch, permission mode, base port)
 - **Phase 2 = Tooling integrations** (issue tracker provider, provider-specific config, IDE, merge mode)
 - **Keep configuration minimal** - only include non-default values
 - **Honor recommendations/requirements of where to save certain settings - this may mean you have to create/update multiple settings files. (e.g when adding API keys for permissions mode settings)
@@ -1563,3 +1900,5 @@ When configuring agents, use these model identifiers:
 - **CRITICAL: PREVENT DUPLICATION** - When writing settings.local.json, ONLY include settings that differ from settings.json. If a setting has the same value in both files, it MUST be removed from the local file. Local should only contain overrides, never duplicates.
 - **Deep comparison required** - When comparing settings for duplication, compare nested objects deeply (e.g., capabilities.web.basePort), not just top-level keys
 - **Empty local is OK** - If all local settings match shared settings after deduplication, an empty settings.local.json file is perfectly valid (or the user may choose not to create it at all)
+- **ALWAYS ask where to save package.iloom configuration** - When creating or modifying package.iloom.json outside of the guided wizard flow, always ask the user whether to save to `package.iloom.json` (shared, committed) or `package.iloom.local.json` (local, gitignored) before writing. Apply the same fork detection logic — if origin + upstream remotes are detected, default to the local variant.
+- **ALWAYS offer to commit after writing shared files** - Whenever you create or modify a committable file (settings.json, package.iloom.json, .gitignore), offer to commit it — even outside the guided wizard flow. Looms are created from committed code, so uncommitted shared configuration won't be available in new looms. Follow the same commit rules from Phase 7: only stage iloom-related files, never stage local-only files.