@iloom/cli 0.9.2 → 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,
@@ -720,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:**
 
@@ -733,6 +837,9 @@ 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:**
@@ -814,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"],
@@ -855,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"
@@ -873,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**
@@ -881,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:**
@@ -890,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**
 
@@ -945,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**
@@ -982,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
@@ -1040,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)
 ```
@@ -1047,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?"
@@ -1185,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
    {
@@ -1315,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**
@@ -1333,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:
 
@@ -1404,6 +1683,7 @@ Need more advanced configuration? I can help you set up:
   • 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
@@ -1421,6 +1701,7 @@ You can ask me questions like:
   "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.
@@ -1452,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": {
@@ -1564,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
@@ -1581,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.