@iloom/cli 0.2.0 → 0.3.0

package/dist/ProjectCapabilityDetector-34LU7JJ4.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  ProjectCapabilityDetector
+} from "./chunk-EBISESAP.js";
+import "./chunk-2ZPFJQ3B.js";
+export {
+  ProjectCapabilityDetector
+};
+//# sourceMappingURL=ProjectCapabilityDetector-34LU7JJ4.js.map

package/dist/{PromptTemplateManager-WII75TKH.js → PromptTemplateManager-A52RUAMS.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import {
   PromptTemplateManager
-} from "./chunk-PVAVNJKS.js";
+} from "./chunk-WEN5C5DM.js";
 import "./chunk-GEHQXLEI.js";
 export {
   PromptTemplateManager
 };
-//# sourceMappingURL=PromptTemplateManager-WII75TKH.js.map
+//# sourceMappingURL=PromptTemplateManager-A52RUAMS.js.map

package/dist/README.md

@@ -10,13 +10,12 @@
 </div>
 
 <div align="center">
-  <img width="327" height="328" alt="iloom-ai-logo" src="https://raw.githubusercontent.com/iloom-ai/iloom-cli/main/assets/iloom-logo.png" />
-  <div>Scale understanding, not just output.</div>
-
+  <img width="600" alt="iloom-ai-screenshot" src="https://raw.githubusercontent.com/iloom-ai/iloom-cli/main/assets/iloom-screenshot.png" />
+  <div>iloom in action: Scale understanding, not just output.</div>
 </div>
 
 #### Links to key sections
-[How It Works](#how-it-works) • [Installation](#installation) • [Commands](#commands) • [Feedback](#providing-feedback) • [Limitations](#platform--integration-support) • [Configuration](#configuration)
+[How It Works](#how-it-works) • [Installation](#installation) • [Commands](#commands) • [Nested Looms](#child-looms-nested-looms) • [Limitations](#platform--integration-support) • [Configuration](#configuration) • [Feedback](#providing-feedback)
 
 
 ## Built For Modern Tools...
@@ -313,6 +312,8 @@ iloom start <issue-number | pr-number | issue-description | branch-name>
 #                        default: Standard behavior with prompts
 #                        noReview: Skip phase approval prompts
 #                        bypassPermissions: Full automation, skip all permission prompts. Be careful!
+#   --child-loom       - Force create as child loom (skip prompt, requires parent loom)
+#   --no-child-loom    - Force create as independent loom (skip prompt)
 
 iloom finish
 # AI assisted validation, commit, merge steps, as well as loom cleanup (run this from the loom directory)
@@ -362,6 +363,100 @@ iloom enhance <issue-number>
 # Expands requirements, asks clarifying questions and adds implementation context
 ```
 
+## Child Looms (Nested Looms)
+
+Child looms let you create isolated workspaces from within an existing loom. This is useful when you need to work on a subtask, bug fix, or experiment while keeping your parent work intact.
+
+### When to Use Child Looms
+
+- **Break down complex issues**: Large features can spawn smaller issues that become child looms
+- **Fix bugs discovered during work**: Create a child loom to fix a bug without mixing commits
+- **Experiment safely**: Try different approaches in child looms without affecting parent work
+- **Handle interrupts**: Start urgent work from your current context without losing it
+
+### How Child Looms Work
+
+When you run `il start` from inside an existing loom, iloom detects the parent context and prompts you:
+
+```bash
+# Inside a loom working on issue #25
+> il start 42
+? Create as child loom of issue #25? (Y/n)
+```
+
+**Automatic inheritance:**
+- **Database branch**: Child looms branch from the parent's database state, not the main branch
+- **Base branch**: Git branch is created from the parent's branch
+- **Main branch config**: Child's `mainBranch` setting points to parent branch (for `il finish`)
+
+### CLI Flags
+
+Skip the prompt with explicit flags:
+
+```bash
+# Force child loom creation (no prompt)
+il start 42 --child-loom
+
+# Force independent loom (no prompt)
+il start 42 --no-child-loom
+```
+
+The `--child-loom` flag is ignored when not running from inside a loom.
+
+### Directory Structure
+
+Child looms are created in a dedicated subdirectory based on the parent branch name:
+
+```
+~/project-looms/
+├── feat-issue-25-auth-refactor/           # Parent loom
+├── feat-issue-25-auth-refactor-looms/     # Child looms directory
+│   ├── fix-issue-42-token-validation/     # Child loom 1
+│   └── feat-issue-43-oauth-support/       # Child loom 2
+```
+
+### Finishing Child Looms
+
+When finishing a parent loom, iloom warns about existing child looms:
+
+```bash
+> il finish
+⚠ Found 2 child loom(s) that should be cleaned up first:
+  - ~/project-looms/feat-issue-25-auth-refactor-looms/fix-issue-42-token-validation
+  - ~/project-looms/feat-issue-25-auth-refactor-looms/feat-issue-43-oauth-support
+
+To clean up child looms:
+  il cleanup 42
+  il cleanup 43
+```
+
+Child looms should typically be finished or cleaned up before finishing the parent.
+
+### Example Workflow
+
+```bash
+# Start working on a feature
+> il start 25
+# ... working on authentication refactor
+
+# Discover a bug that needs immediate attention
+> il start 42
+? Create as child loom of issue #25? Y
+# Creates child loom with parent's database state
+
+# Fix the bug in isolation
+> cd ~/project-looms/feat-issue-25-auth-refactor-looms/fix-issue-42-...
+
+# Finish the child work (merges to parent branch, not main)
+> il finish
+
+# Return to parent loom
+> cd ~/project-looms/feat-issue-25-auth-refactor
+
+# Continue feature work, then finish
+> il finish
+```
+
 ## Providing Feedback
 
 Found a bug, have a feature request, or want to contribute ideas to improve iloom CLI? Submit feedback directly from your terminal.
@@ -391,19 +486,6 @@ Your feedback helps make iloom better for everyone! Issues created through `iloo
 ### Maintenance
 
 ```bash
-iloom init
-# Interactive Claude-powered configuration wizard
-# Sets up settings.json, .gitignore, and guides you through all configuration options
-# Automatically detects multi-remote setups and helps you configure GitHub integration
-# Alias: il config
-# Run this once per project
-
-iloom contribute
-# Set up local development environment for contributing to iloom
-# Automatically forks the repository, clones it locally, configures upstream remote,
-# and runs il init to complete setup
-# Streamlines contributor onboarding with a single command
-
 iloom update
 # Update iloom-cli to the latest version
 ```
@@ -417,7 +499,7 @@ The recommended way to configure iloom:
 ```bash
 iloom init
 # or
-il config
+iloom config
 ```
 
 This Claude-powered assistant will guide you through all configuration options and automatically:
@@ -437,14 +519,18 @@ If you prefer manual configuration, iloom uses these files (highest to lowest pr
 1. **CLI arguments** - Command-line flags (e.g., `--one-shot bypassPermissions`)
 2. **`.iloom/settings.local.json`** - Local machine settings (gitignored, not committed)
 3. **`.iloom/settings.json`** - Project-wide settings (committed to repository)
-4. **Built-in defaults** - Hardcoded fallback values
+4. **`~/.config/iloom-ai/settings.json`** - Global user settings (applies to all projects)
+5. **Built-in defaults** - Hardcoded fallback values
 
-This allows teams to share project defaults via `settings.json` while individual developers maintain personal overrides in `settings.local.json`.
+This allows teams to share project defaults via `settings.json` while individual developers maintain personal overrides in `settings.local.json` or global preferences in `~/.config/iloom-ai/settings.json`.
 
 **Example Use Cases:**
-- Developer needs different `basePort` due to port conflicts
-- Local database connection strings that differ from team defaults
-- Personal preferences for `permissionMode` or component launch flags
+- **Global settings**: Default agent models or workflow permission modes that apply to all your projects
+- **Project settings**: Team defaults like `mainBranch`, database configuration, GitHub remote
+- **Local settings**: Machine-specific overrides like different `basePort` due to port conflicts, local database URLs, personal workflow preferences
+
+**Global Settings:**
+Global settings are stored in `~/.config/iloom-ai/settings.json` and apply to all iloom projects on your machine. Use these for personal preferences like default agent models or workflow permission modes. Project-specific settings (like database configuration) should remain in project config files.
 
 **Note:** The `.iloom/settings.local.json` file is automatically created and gitignored when you run `il init`.
 
@@ -453,6 +539,7 @@ This allows teams to share project defaults via `settings.json` while individual
 ```jsonc
 {
   "mainBranch": "main",
+  "sourceEnvOnStart": false,  // Source .env in terminal launches (default: false)
   "mergeBehavior": {
     "mode": "local",  // or "github-pr" for PR-based workflows
     "remote": "upstream"  // optional, defaults to issueManagement.github.remote
@@ -491,6 +578,7 @@ This allows teams to share project defaults via `settings.json` while individual
 
 ** Common configuration options:**
 - `mainBranch` - Primary branch for merging (default: "main")
+- `sourceEnvOnStart` - Source .env file when launching terminal processes (default: false)
 - `mergeBehavior.mode` - How to finish work: "local" (merge locally) or "github-pr" (create PR) (default: "local")
 - `mergeBehavior.remote` - Remote to target for PRs (optional, defaults to `issueManagement.github.remote`)
 - `capabilities.web.basePort` - Base port for dev servers (default: 3000)
@@ -507,15 +595,149 @@ Example: Issue #25 with basePort 3000 = port 3025
 
 For complete configuration reference, see [.iloom/README.md](./.iloom/README.md)
 
+### IDE Configuration
+
+Configure which IDE launches when starting a loom:
+
+```jsonc
+{
+  "ide": {
+    "type": "cursor"  // or: vscode, webstorm, sublime, intellij, windsurf
+  }
+}
+```
+
+**Supported IDEs:**
+
+| Type | Command | Notes |
+|------|---------|-------|
+| `vscode` | `code` | Default. Visual Studio Code |
+| `cursor` | `cursor` | Cursor AI editor |
+| `webstorm` | `webstorm` | JetBrains WebStorm (launches with --nosplash) |
+| `sublime` | `subl` | Sublime Text |
+| `intellij` | `idea` | JetBrains IntelliJ IDEA (launches with --nosplash) |
+| `windsurf` | `windsurf` | Windsurf editor |
+
+**Configure via CLI:** Use the existing `--set` flag:
+
+```bash
+il start 25 --set ide.type=cursor
+```
+
+**Configure during setup:** Run `il init` to configure IDE preference interactively along with other settings.
+
+**Note:** Color synchronization (title bar colors) only works with VSCode-compatible editors (vscode, cursor, windsurf). Other IDEs will launch without color theming.
+
+## Issue Tracker Integration
+
+iloom supports multiple issue tracking systems through a provider abstraction. Choose GitHub or Linear based on your team's workflow.
+
+### GitHub (Default)
+
+GitHub is the default issue tracker and requires no additional configuration beyond authentication with the `gh` CLI.
+
+**Setup:**
+```bash
+# Authenticate with GitHub CLI
+gh auth login
+
+# Start using iloom with GitHub issues
+il start 123
+il start PR-456
+```
+
+**Configuration:**
+```jsonc
+{
+  "issueManagement": {
+    "provider": "github",  // Default, can be omitted
+    "github": {
+      "remote": "origin"  // Optional, defaults to "origin"
+    }
+  }
+}
+```
+
+### Linear
+
+iloom integrates with Linear through the official `@linear/sdk`, enabling full Linear issue tracking support.
+
+**Setup:**
+
+1. Get your Linear API token from [Linear Settings → API → Personal API Keys](https://linear.app/settings/api)
+
+2. Configure iloom to use Linear:
+   ```bash
+   il init
+   # Follow prompts to:
+   # - Select Linear as your issue tracker
+   # - Enter your Linear team ID (e.g., "ENG")
+   # - Enter your Linear API token (saved securely to settings.local.json)
+   ```
+
+   Or manually configure:
+
+   Edit `.iloom/settings.local.json` (for sensitive data):
+   ```jsonc
+   {
+     "issueManagement": {
+       "provider": "linear",
+       "linear": {
+         "teamId": "ENG",  // Required: Your Linear team key
+         "apiToken": "lin_api_..."  // Required: Your Linear API token
+       }
+     }
+   }
+   ```
+
+   **Important:** The `apiToken` should be stored in `settings.local.json` (not committed to git), not in `settings.json`. The init command will automatically save it to the correct location.
+
+   Alternatively, use an environment variable:
+   ```bash
+   export LINEAR_API_TOKEN="lin_api_..."
+   ```
+
+   Settings take precedence over environment variables.
+
+**Usage:**
+
+```bash
+# Start working on a Linear issue
+il start ENG-123
+
+# Create a new Linear issue
+il start "Add user authentication"
+
+# Finish and merge
+il finish
+```
+
+**Features:**
+
+- Full CRUD operations on issues and comments via the official Linear SDK
+- MCP integration for Claude AI assistance with Linear issues
+- Automatic workspace creation with Linear issue context
+
+**Limitations:**
+
+- Linear does not have pull requests. Use `il finish` with `mergeBehavior.mode: "local"` or `"github-pr"` to merge your code.
+
+**Port Calculation:**
+
+Linear issue identifiers (e.g., ENG-123) use hash-based port calculation instead of simple numeric addition. The port is deterministically generated from the branch name, ensuring consistency across sessions.
+
 ## Requirements
 
 **Essential:**
 - Claude CLI - AI assistance with issue context preloaded
 - Node.js 16+
 - Git 2.5+ (for worktree support)
-- GitHub CLI (`gh`) - authenticated with your repository
 
-**Recommended**
+**Issue Tracker (choose one):**
+- **GitHub CLI (`gh`)** - For GitHub issue tracking (default)
+- **Linear CLI (`linearis`)** - For Linear issue tracking (install with `npm install -g linearis`)
+
+**Recommended:**
 - A Claude Max subscription - iloom uses your own subscription
 
 **Optional (auto-detected):**
@@ -544,6 +766,8 @@ This is an early stage product - platform/tech stack support is limited for now.
 
 We (Claude and I) are actively working on expanding platform and integration support. Contributions welcome!
 
+See all [`known-limitation`](https://github.com/iloom-ai/iloom-cli/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-limitation) issues for details and to [contribute](CONTRIBUTING.md) solutions.
+
 ## Installation
 
 ```bash
@@ -740,11 +964,31 @@ Other tools increase code output with minimal process change. iloom increases **
 
 ## Contributing
 
-This project follows Test-Driven Development. All code must:
-- Be written test-first with comprehensive unit tests
-- Achieve >70% code coverage
-- Include regression tests against bash script behavior
-- Use mock factories for all external dependencies
+We welcome contributions! Whether you're fixing a bug, adding a feature, or improving documentation, there are multiple ways to get involved.
+
+### Quick Start for Contributors
+
+The fastest way to get started contributing:
+
+```bash
+iloom contribute # requires the github CLI (gh)
+```
+
+This automated command handles forking, cloning, and setting up your development environment.
+
+### Finding Your First Issue
+
+New contributors should start with issues labeled [`starter-task`](https://github.com/iloom-ai/iloom-cli/issues?q=is%3Aissue+is%3Aopen+label%3Astarter-task) - these are designed to help you learn the iloom workflow and codebase while making meaningful contributions.
+
+### Full Contributing Guide
+
+For detailed information about our development process, testing requirements, and workflow, see our comprehensive [Contributing Guide](CONTRIBUTING.md).
+
+**Key highlights:**
+- Behavior-focused testing principles
+- AI-assisted development workflow using iloom itself
+- Clear PR process and code quality standards
+- Test-Driven Development with >70% coverage requirement
 
 ## License
 

package/dist/{SettingsManager-XOYCLH3D.js → SettingsManager-WHHFGSL7.js}

@@ -2,22 +2,30 @@
 import {
   AgentSettingsSchema,
   CapabilitiesSettingsSchema,
+  CapabilitiesSettingsSchemaNoDefaults,
   DatabaseProvidersSettingsSchema,
   IloomSettingsSchema,
+  IloomSettingsSchemaNoDefaults,
   NeonSettingsSchema,
   SettingsManager,
   WorkflowPermissionSchema,
-  WorkflowsSettingsSchema
-} from "./chunk-T3KEIB4D.js";
+  WorkflowPermissionSchemaNoDefaults,
+  WorkflowsSettingsSchema,
+  WorkflowsSettingsSchemaNoDefaults
+} from "./chunk-ML3NRPNB.js";
 import "./chunk-GEHQXLEI.js";
 export {
   AgentSettingsSchema,
   CapabilitiesSettingsSchema,
+  CapabilitiesSettingsSchemaNoDefaults,
   DatabaseProvidersSettingsSchema,
   IloomSettingsSchema,
+  IloomSettingsSchemaNoDefaults,
   NeonSettingsSchema,
   SettingsManager,
   WorkflowPermissionSchema,
-  WorkflowsSettingsSchema
+  WorkflowPermissionSchemaNoDefaults,
+  WorkflowsSettingsSchema,
+  WorkflowsSettingsSchemaNoDefaults
 };
-//# sourceMappingURL=SettingsManager-XOYCLH3D.js.map
+//# sourceMappingURL=SettingsManager-WHHFGSL7.js.map

package/dist/SettingsMigrationManager-AGIIIPDQ.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  SettingsMigrationManager
+} from "./chunk-KLBYVHPK.js";
+import "./chunk-JKXJ7BGL.js";
+import "./chunk-GEHQXLEI.js";
+export {
+  SettingsMigrationManager
+};
+//# sourceMappingURL=SettingsMigrationManager-AGIIIPDQ.js.map