@uluops/cli 0.18.3 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to `@uluops/cli` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.19.0] - 2026-06-16
+
+### Dependencies
+
+- **Bumped `@uluops/core` 0.22.1 → 0.22.7, `@uluops/registry-sdk` 0.32.1 → 0.35.0, `@uluops/ops-sdk` 3.2.1 → 3.3.0** (all exact). Pulls in the registry-sdk `ResponseValidationError` + safety/`riskProfile`/`RetranslateResult` root exports, and the sdk-core 0.13.0 runtime fixes (`retries: 0` makes one attempt with a typed error; actionable 401 with the server reason preserved; `isApiKey()` enforces minimum length) — all via the upgraded core/SDK chain. 460 tests green against the new versions.
+
+### Added
+
+- **`ulu exec describe ... --version <v>` now fails closed** instead of silently printing the CLI version and exiting 0. Commander's program-level `-V/--version` is an immediate option that fires during parse (before any subcommand action or preAction hook), so a captive CI script that hardcoded `--version` against `describe` got the CLI version string + exit 0 rather than resolving the definition version. A pre-parse argv guard now detects this shadow and errors (exit 2) with a pointer to `--def-version` (or the `<name>@<version>` suffix). Bare `ulu --version` is untouched.
+- **`ulu auth whoami --json` now emits the inferred credential source to stderr.** The default `--json` stdout shape stays frozen (adding a field is a breaking change under the JSON Output Stability Contract), but the most-captive population — CI debugging which identity authenticated — gets the source in the same invocation via stderr instead of being forced into a second non-JSON call.
+
+### Changed
+
+- **`auth whoami` credential-source label is now "Credential Source (inferred)"** (was "Credential Source"). The label is re-derived from flags/env by mirroring sdk-core's precedence ladder, not reported by the SDK; the "(inferred)" qualifier makes that honest and prevents the label from reading as an authoritative readout that could silently drift if sdk-core's precedence changes.
+- **`exec --report` wording corrected from "mutually exclusive" to "disables tracker submission."** The relationship is asymmetric (report mode silently wins and forces no-tracking, with no hard-error guard even when `--project` is set), not a symmetric mutual-exclusion. README, option help, and the inline comment are reconciled.
+- **The "Report mode enabled — tracking disabled" notice now survives `-q`** when tracking intent is explicit (`--project` or `ULUOPS_PROJECT`). Previously `--report --project X -q` (the CI shape) got neither a tracker record nor the disclosure that explains why.
+- **`--exec-timeout` help corrected**: removed the unreachable/mislabeled "5m SDK fallback" precedence tier (exec's `--timeout` always provides a 600s/10min default, so the fallback can never be reached). Precedence now reads `--exec-timeout > definition default > --timeout (default 600s/10min)`.
+- **`ulu issues history` now ships an examples help block** (`--help`), matching the other `issues` subcommands.
+
+### Fixed
+
+- Picker-mode `--json` output (`ulu issues history --project <slug>`, kind `issue.historyList`) now has a contract-anchor test pinning its bare-array shape and DESC-by-`updatedAt` sort.
+
+### Internal
+
+- Renamed a shadowing `issues` local in the history picker action to `recentIssues` (was shadowing the outer `issues` command builder).
+- Test suite 460 cases (was 454): +2 whoami (inferred label + stderr-in-json), +5 `--version` shadow guard, +1 picker-`--json` anchor, report-notice test split into intent/no-intent paths.
+
+## [0.18.4] - 2026-06-16
+
+### Changed
+
+- `runs list`/`details`/`archive`/`update` and `issues list` now declare the project as a required positional (`<project>`) instead of optional (`[project]`), so Commander reports a clear "missing required argument" error instead of falling through to a fallback message.
+- Bumped `@uluops/core` to `0.22.1`.
+
+### Fixed
+
+- `exec` misplaced-option correction hint no longer appends a `<value>` placeholder for boolean inherited flags (e.g. `--no-tracking`, `--no-safety-warnings`); the placeholder now appears only for value-taking flags (`--project`, `--local-definitions`).
+- `resolveProject` "no project specified" error now points to the positional-argument form instead of a `--project` flag that those commands do not accept.
+- `issues list --priority` help and README now list the correct values (`critical`, `high`, `suggested`, `backlog`) — `high` was missing and the unsupported `all` was removed.
+
+### Documentation
+
+- Corrected all `exec` examples (README and command help) for the v0.16.0 argument-order change — parent options (`--project`, `--no-tracking`, `--local-definitions`) now appear before the subcommand.
+- Fixed stale help-text examples: `runs details -n`, `runs save --project`, `def list --search`, and `issues close --reason` (removed the nonexistent `--status` flag).
+- Documented previously-undocumented surfaces: `--json-envelope`, `ULUOPS_PROJECT`, `ULUOPS_MAX_CONCURRENCY`, `definitions update` options (`--change-type`, `--visibility`, `--display-name`, `--description`), `runs details -n`, `runs archive --before-date`, and `definitions list` filters (`--domain`, `--limit`, `--offset`).
+- Clarified that `runs validate` previews against the live tracker and requires auth; added `ANTHROPIC_API_KEY` to the Quick Start at point of use.
+- Documented `def get -m/--model`, `definitions create --visibility`, and the `issues list --all` shorthand; added a model-targeted render example.
+- Shell-completion setup now uses `eval "$(ulu completion <shell>)"`, matching the tool's own `--help` and generated-script guidance.
+
 ## [0.18.3] - 2026-06-15
 
 ### Added
@@ -234,9 +284,6 @@ Suite 414 → 417.  Build + typecheck + lint clean.
   - `note` events with note type, author, and a truncated content body
   A `⚠ Truncated to most recent N of M events` warning surfaces when the server applies the 1000-event ceiling.
 - **BREAKING (JSON output):** `--json ulu issues history` now emits the `IssueHistoryEnvelope` shape (`{issueId, events, totalEvents, truncated}`) instead of a flat `StatusHistory[]`. Scripts consuming `result[0]` or `Array.isArray(result)` need to switch to `result.events`. The bare-array shape was lossy on F10 (occurrences + notes were dropped on the server side, then undo destroyed status rows) so most real consumers were already getting `[]` before the fix landed.
-
-### Changed
-
 - **`ulu deps get` / `ulu deps dependents` now render the real envelope shapes** (live-tests T2 §3.5, R12). registry-sdk v0.31.0 fixed both endpoints to return real structured graphs/lists instead of the silent `{}` they used to parse to. The CLI used to defend against the broken contract with `data.nodes ?? data.flat ?? []` fallbacks; that scaffolding is gone. `deps get` now prints a flat indented list by default (each line tagged with its `(depth N)`) and accepts `--tree` to render the recursive graph as an indented tree with `[context]` labels per edge (`[invokes.agent]`, `[stage "Final Checks"]`, `[dependencies.requires]`, etc). `deps dependents` now shows `← context` arrows so operators can see which reference type each consumer uses.
 - Removed: the unused `cycleDetected` / `cycles` warning — the registry API never tracked those.
 
@@ -315,6 +362,7 @@ Suite 414 → 417.  Build + typecheck + lint clean.
 - **Warning when `--project` is omitted with tracking enabled.** `exec run`, `exec agent`, `exec command`, `exec workflow`, and `exec pipeline` now print a stderr advisory showing the project name the SDK would silently infer from `basename(resolve(target))` and pointing to `--project` or `--no-tracking`. Suppressed under `--quiet`, `--json`, when `ULUOPS_PROJECT` is set, or when the operator passes `--project` explicitly. Surfaces the phantom-project class of bug (`exec agent foo ./src` creating a project literally named `src`) without breaking the one-line ad-hoc invocation pattern. The structural fix lives in `ops-uluops-api` issue `76f1c7e6`.
 - **Inherited options now visible on `exec` subcommand help.** `ulu exec agent --help`, `ulu exec pipeline --help`, etc. now list `--project`, `--no-tracking`, `--no-safety-warnings`, `--local-definitions`, `--registry-url` as inherited from the parent `exec` command, plus a pointer to global flags. Previously these were invisible in subcommand help, leading operators to believe tracking and project-scoping weren't available on the subcommand they were looking at.
 - **Default exec timeout: 10 minutes.** `createCoreContext` now passes `timeout: 600_000` to `UluOpsClient` when `--timeout` is not specified, overriding the SDK's internal 5-minute fallback with a single predictable CLI-owned ceiling that accounts for model cold-start and long agent execution. Ops/registry HTTP timeout remains 30s. `--timeout` help text updated to reflect both defaults.
+- **`zod@4.3.6` added as a direct dependency** (exact pin, matching `@uluops/ops-sdk`'s pin) to back the new `runs update` input schema.
 
 ### Changed
 
@@ -331,10 +379,6 @@ Suite 414 → 417.  Build + typecheck + lint clean.
 
 - **`@uluops/sdk-core` no longer listed as a direct dependency.** Verified unimported in `src/`/`test/`; remains transitively available via `@uluops/ops-sdk` and `@uluops/registry-sdk`.
 
-### Added
-
-- **`zod@4.3.6` added as a direct dependency** (exact pin, matching `@uluops/ops-sdk`'s pin) to back the new `runs update` input schema.
-
 ### Internal
 
 - 20 new tests across `test/utils.test.ts` (writeFileAtomic — 6), `test/commands/exec.test.ts` (`exec pipeline` happy/prompt/JSON/error paths plus `warnIfProjectInferred` 7-case matrix — 11), and `test/commands/runs.test.ts` (Zod validation — 4). Test suite now 394 cases.

package/README.md

@@ -25,6 +25,7 @@ export ULUOPS_API_KEY=ulr_your-api-key-here
 # Create a project and save a validation run
 ulu projects create my-project
 ulu runs save --file results.json
+# → Run #1 saved for my-project (3 agents, 12 recommendations)
 
 # Browse issues
 ulu issues list my-project --status open --priority critical
@@ -32,8 +33,11 @@ ulu issues list my-project --status open --priority critical
 # Check analytics
 ulu analytics burndown --project my-project --days 30
 
-# Run a validator agent
-ulu exec agent code-validator -t ./src --model sonnet --project my-project
+# Run a validator agent (requires ANTHROPIC_API_KEY; parent options like
+# --project come BEFORE the subcommand)
+export ANTHROPIC_API_KEY=sk-ant-your-key-here
+ulu exec --project my-project agent code-validator -t ./src --model sonnet
+# → code-validator: PASS (score 92) — results tracked under my-project
 ```
 
 ## Table of Contents
@@ -151,11 +155,12 @@ The CLI resolves credentials in this order:
 
 Every command accepts these flags:
 
-```
+```text
 --api-key <key>      Override API key (env: ULUOPS_API_KEY)
 --profile <name>     Config profile to use (default: 'default')
 --timeout <ms>       Request timeout in milliseconds (default: 30000 for ops/registry, 600000 for exec)
 --json               Output raw JSON for scripting
+--json-envelope      Wrap --json output in the versioned stability envelope (same as ULU_JSON_SCHEMA=1)
 --debug              Enable debug output
 -q, --quiet          Suppress spinners and non-essential output
 -V, --version        Show CLI version
@@ -181,7 +186,7 @@ ulu auth update-profile           # Update profile (display name, bio, avatar)
 ulu auth sessions list            # List active sessions
 ulu auth sessions revoke <id>     # Revoke a session
 ulu auth api-keys list            # List API keys
-ulu auth api-keys create          # Create new API key
+ulu auth api-keys create          # Create new API key (--name, --expires <ISO date>)
 ulu auth api-keys revoke <id>     # Revoke an API key
 ```
 
@@ -191,6 +196,7 @@ ulu auth api-keys revoke <id>     # Revoke an API key
 # Register and create an API key
 ulu auth register --email user@example.com --password mypassword
 ulu auth api-keys create --name "CI Pipeline"
+ulu auth api-keys create --name "CI Pipeline" --expires 2026-12-31  # optional expiry
 # Save this key: ulr_abc123... (shown once)
 
 # Login interactively
@@ -247,12 +253,12 @@ Validation run management — save, compare, and archive pipeline results. Alias
 ulu runs list <project>           # List runs (--workflow, --limit)
 ulu runs get <runId>              # Get run by UUID
 ulu runs latest <project>         # Get latest run (--workflow)
-ulu runs details <project>        # Detailed run with agents/recommendations
-ulu runs save                     # Save run from JSON (--file or --stdin)
-ulu runs validate                 # Dry run — preview without saving
+ulu runs details <project>        # Detailed run with agents/recommendations (-n for a specific run number)
+ulu runs save                     # Save run from JSON (--file or --stdin; -p/-w override input fields)
+ulu runs validate                 # Dry run — preview against the live tracker (requires auth; -p/-w override)
 ulu runs diff <project>           # Compare two runs (--base, --compare)
-ulu runs archive <project>        # Archive old runs (--before-run, --keep-last)
-ulu runs update <project>         # Update run metadata (--number, --score, --file)
+ulu runs archive <project>        # Archive old runs (--before-run, --before-date, --keep-last, --reason)
+ulu runs update <project>         # Update run metadata (--number, --score, --passed, --file)
 ulu runs delete <runId>           # Delete a run
 ```
 
@@ -265,6 +271,9 @@ ulu runs save --file validation-results.json
 # Save from stdin (pipe from another tool)
 cat results.json | ulu runs save --stdin
 
+# Override the project or workflow type in the JSON without editing the file (handy in CI)
+ulu runs save --file results.json -p override-project -w post-implementation
+
 # Dry run to preview what would happen
 ulu runs validate --file results.json
 
@@ -279,6 +288,9 @@ ulu runs archive my-project --keep-last 10
 
 # Update token counts on a run after the fact
 ulu runs update my-project --number 5 --file token-update.json
+
+# Set the gates-passed flag on a run after the fact
+ulu runs update my-project --number 5 --passed true
 ```
 
 > **Note:** `runs update --score` is rejected on finalized runs ("Cannot rewrite averageScore"). Use the `--file` form to patch per-agent fields. Each agent entry in the file must include `name` and `decision` (any other fields like `tokens` are merged into the existing record).
@@ -326,15 +338,15 @@ Issue tracking and management. Alias: `i`.
 ```bash
 ulu issues list <project>         # List issues with filters
 ulu issues get <id>               # Get issue (--full for occurrences/notes)
-ulu issues search                 # Search across projects (--query)
-ulu issues create                 # Create user-submitted issue
+ulu issues search                 # Search across projects (--query, --projects to scope)
+ulu issues create                 # Create user-submitted issue (--failure-code, --domain link to taxonomy)
 ulu issues update <id>            # Update status (--status, --reason)
 ulu issues close <id>             # Mark as completed (--reason)
 ulu issues edit <id>              # Edit metadata (--title, --severity, etc.)
 ulu issues add-note <id>          # Add note (--message, --type)
 ulu issues history <id>                          # Show timeline by UUID
 ulu issues history <fingerprint> --project <slug> # Resolve fingerprint then show timeline
-ulu issues history --project <slug>              # Picker: list recent issues, then drill in
+ulu issues history --project <slug>              # Picker: list recent issues (--limit), then drill in
 ulu issues undo <id>              # Undo last status change
 ulu issues restore <id>           # Restore soft-deleted issue
 ulu issues bulk-update            # Bulk update statuses (--ids, --status)
@@ -348,15 +360,19 @@ ulu issues update-by-fingerprint <fp> --project <name> # Update by fingerprint
 # List open critical issues
 ulu issues list my-project --status open --priority critical
 
-# Search across all projects
+# Search across all projects (or scope to specific ones with --projects)
 ulu issues search --query "authentication" --status open
+ulu issues search --query "timeout" --projects my-app,my-api
 
-# Create an issue manually
+# Create an issue manually. Pass --failure-code and --domain to link it into
+# the failure taxonomy — without them the issue is excluded from domain/code analytics.
 ulu issues create --project my-project \
   --title "SQL injection in login" \
   --priority critical \
   --severity critical \
   --type security \
+  --failure-code SEM-VAL/H \
+  --domain SEM \
   --file-path src/auth/login.ts \
   --line 45
 
@@ -390,10 +406,12 @@ ulu issues history a1b2c3d4 --project my-project # then drill in by fingerprint
 | Flag | Values |
 |------|--------|
 | `--status` | `open`, `completed`, `deferred`, `wontfix`, `all` |
-| `--priority` | `critical`, `suggested`, `backlog`, `all` |
+| `--all` | Shorthand for `--status all` |
+| `--priority` | `critical`, `high`, `suggested`, `backlog` |
 | `--severity` | `critical`, `high`, `medium`, `low`, `info` |
 | `--agent` | Any agent name (e.g., `code-validator`) |
 | `--domain` | `STR`, `SEM`, `PRA`, `EPI` |
+| `--include-resolved` | Include resolved (completed/wontfix/deferred) issues in results |
 | `--limit` | Max results (default: 50) |
 
 ---
@@ -409,7 +427,7 @@ ulu analytics hotspots            # Files with most issues
 ulu analytics burndown            # Taxonomy burndown time series
 ulu analytics velocity            # Rate of change per failure mode
 ulu analytics discovery           # New vs recurring issues timeline
-ulu analytics matrix              # Agent-taxonomy coverage matrix
+ulu analytics matrix              # Agent-taxonomy coverage matrix (--min-issues to threshold)
 ulu analytics resolution          # Issue resolution rates by project (cross-project; no --project flag)
 ulu analytics taxonomy            # Taxonomy distribution
 ulu analytics full-taxonomy       # Full taxonomy analytics breakdown
@@ -436,6 +454,7 @@ ulu analytics discovery --project my-project --group-by week
 
 # Coverage gaps — which domains lack agent coverage?
 ulu analytics matrix --project my-project
+ulu analytics matrix --project my-project --min-issues 3  # only failure modes seen 3+ times
 
 # Reliability — which agents have high false positive rates?
 ulu analytics reliability --days 90
@@ -460,14 +479,14 @@ Displays the four failure domains (STR, SEM, PRA, EPI), their failure modes, sev
 Workflow definition management (registry API). Alias: `def`.
 
 ```bash
-ulu definitions list              # List definitions (--type, --status, --search)
-ulu definitions get <type> <name> [version]   # Get definition (--yaml, --rendered, --target, -o)
-ulu definitions create <type> <name>          # Create draft (--file)
-ulu definitions update <type> <name> <ver>    # Update draft (--file)
+ulu definitions list              # List definitions (--type, --status, --search, --domain, --visibility, --limit, --offset)
+ulu definitions get <type> <name> [version]   # Get definition (--yaml, --rendered, --target, --render-profile, --include-runtime, -m/--model, -o)
+ulu definitions create <type> <name>          # Create draft (--file, --visibility public|private)
+ulu definitions update <type> <name> <ver>    # Update draft (--file, --display-name, --description, --visibility); --change-type major|minor|patch creates a new version from a published one
 ulu definitions publish <type> <name> <ver>   # Publish definition
 ulu definitions deprecate <type> <name> <ver> # Deprecate (--reason, --successor)
 ulu definitions validate [type]               # Validate YAML (--file, type auto-detected)
-ulu definitions render [type]                 # Render YAML preview (--file, type auto-detected)
+ulu definitions render [type]                 # Render YAML preview (--file, --render-profile core|uluops-full, type auto-detected)
 ulu definitions delete <type> <name> <ver>    # Delete draft (--yes)
 ```
 
@@ -491,6 +510,9 @@ ulu def get agent code-validator --rendered
 # Render for a specific harness (claude-code, opencode, codex, gemini-cli)
 ulu def get agent code-validator --rendered --target opencode
 
+# Render for a harness with a model-specific override
+ulu def get agent code-validator --rendered --target gemini-cli -m gemini-2.5-pro
+
 # Write rendered output to file instead of stdout
 ulu def get agent code-validator --rendered -o ./code-validator.md
 
@@ -498,6 +520,9 @@ ulu def get agent code-validator --rendered -o ./code-validator.md
 ulu def validate --file my-agent.agent.yaml
 ulu def render --file my-agent.agent.yaml
 
+# Render with the full UluOps profile (platform preamble) instead of the lean core profile
+ulu def render --file my-agent.agent.yaml --render-profile uluops-full
+
 # Create, validate, and publish a new agent
 ulu def validate agent --file my-agent.yaml
 ulu def create agent my-agent --file my-agent.yaml
@@ -561,7 +586,7 @@ Definition forking and lineage.
 
 ```bash
 ulu forks list <type> <name> <version>       # List forks
-ulu forks create <type> <name> <version>     # Fork definition (--fork-name)
+ulu forks create <type> <name> <version>     # Fork definition (--fork-name, --visibility, --display-name, --description)
 ulu forks check <type> <name> <version>      # Check if forkable
 ulu forks lineage <type> <name> <version>    # Show fork ancestry chain
 ```
@@ -616,7 +641,7 @@ ulu exec command my-command ./src
 ulu exec workflow post-implementation ./
 
 # Execute a multi-stage pipeline
-ulu exec pipeline foundations ./ --project my-project
+ulu exec --project my-project pipeline foundations ./
 
 # List available definitions
 ulu exec list                          # All definitions
@@ -676,7 +701,7 @@ ulu exec describe --type pipeline                       # No name + --type → f
 | `--threshold-warn <n>` | Warning threshold score (agents) |
 | `--hash <sha256:...>` | **Optional.** Pin the expected YAML hash (from a trusted channel). Verifies the resolved definition source + config before executing; refuses on mismatch (**exit 4**). |
 | `--prompt-hash <sha256:...>` | **Optional.** Pin the expected rendered-prompt hash. Pair with `--hash` for full agent executed-prompt integrity. Both pins are opt-in — omitting them runs unverified as before. Refuses on mismatch (**exit 4**). |
-| `--report [path]` | Write a human-readable, publication-quality report to file (single agent only). With no path, defaults to `./<agent>-report-<YYYYMMDDTHHmmss>.md` in cwd. Injects a report-mode directive into the agent's prompt and disables structured-output enforcement so the model can emit prose. **Mutually exclusive with tracker submission** (implies `--no-tracking`): the schema-validated path the tracker depends on is no longer guaranteed under report mode. Run without `--report` for tracker submission. |
+| `--report [path]` | Write a human-readable, publication-quality report to file (single agent only). With no path, defaults to `./<agent>-report-<YYYYMMDDTHHmmss>.md` in cwd. Injects a report-mode directive into the agent's prompt and disables structured-output enforcement so the model can emit prose. **Disables tracker submission** (implies `--no-tracking`): the schema-validated path the tracker depends on is no longer guaranteed under report mode, so `--report` silently wins over `--project` rather than erroring. With `--project` (or `ULUOPS_PROJECT`) set, a "tracking disabled" notice prints even under `-q`. Run without `--report` for tracker submission. |
 | `-o, --output <path>` | Explicit output path for `--report` (overrides the `--report` argument and the default) |
 | `--features-list <path>` | Write structured features/recommendations to file (single agent only) |
 
@@ -697,7 +722,7 @@ ulu exec describe --type pipeline                       # No name + --type → f
 
 ```bash
 # Run code-validator with a specific model
-ulu exec agent code-validator -t . --model sonnet --project my-project
+ulu exec --project my-project agent code-validator -t . --model sonnet
 
 # Generator: tell the agent what to create
 ulu exec agent aristotle-generator -t ./src \
@@ -708,9 +733,8 @@ ulu exec agent security-analyst -t ./src \
   -p "Focus on the authentication middleware and JWT handling"
 
 # Use local definitions instead of registry
-ulu exec agent my-validator -t ./src \
-  --local-definitions ./agent-defs \
-  --project my-project
+ulu exec --project my-project --local-definitions ./agent-defs \
+  agent my-validator -t ./src
 
 # Produce a publication-quality report (cwd default destination)
 ulu exec agent wittgenstein-analyst -t ./docs --report
@@ -719,7 +743,7 @@ ulu exec agent wittgenstein-analyst -t ./docs --report
 ulu exec agent wittgenstein-analyst -t ./docs --report -o ~/my-report.md
 
 # Execute without tracking results
-ulu exec workflow ship ./packages/api --no-tracking
+ulu exec --no-tracking workflow ship ./packages/api
 
 # Inspect what a definition expects
 ulu exec describe code-validator
@@ -743,7 +767,7 @@ ulu exec agent code-validator -t ./src \
 Execution tracking for definitions.
 
 ```bash
-ulu executions record <type> <name> <version>   # Record execution (--source)
+ulu executions record <type> <name> <version>   # Record execution (--source, --run-id for idempotency)
 ulu executions stats <type> <name> <version>     # Get statistics (--window)
 ```
 
@@ -766,11 +790,11 @@ ulu translation upgrade <type> <name>            # Upgrade legacy YAML (--file)
 Generate shell completion scripts.
 
 ```bash
-# Bash
-ulu completion bash >> ~/.bashrc
+# Bash — add to ~/.bashrc
+echo 'eval "$(ulu completion bash)"' >> ~/.bashrc
 
-# Zsh
-ulu completion zsh >> ~/.zshrc
+# Zsh — add to ~/.zshrc
+echo 'eval "$(ulu completion zsh)"' >> ~/.zshrc
 
 # Fish
 ulu completion fish > ~/.config/fish/completions/ulu.fish
@@ -858,12 +882,13 @@ through the single `emitJson()` chokepoint. To change an output shape you must:
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `ULUOPS_API_KEY` | API key for authentication | - |
+| `ULUOPS_PROJECT` | Project name for `ulu exec` result tracking when `--project` is not passed (useful in CI) | - |
 | `ULUOPS_EMAIL` | Email for session auth | - |
 | `ULUOPS_PASSWORD` | Password for session auth | - |
-| `ULUOPS_BASE_URL` | API base URL (overrides the built-in default) | `https://api.uluops.ai/api/v1` (production); `http://localhost:3100/api/v1` only when `NODE_ENV=development` |
 | `ULUOPS_DEBUG` | Enable debug logging (also expands the global unhandled-error handler's output) | `false` |
 | `ULU_JSON_SCHEMA` | Set to `1` to wrap `--json` output in the versioned stability envelope | - |
 | `ANTHROPIC_API_KEY` | API key for AI model execution (required for `ulu exec` commands) | - |
+| `ULUOPS_MAX_CONCURRENCY` | Engine-wide cap on concurrent in-flight LLM calls for `ulu exec` (distinct from `exec agent -c/--concurrency`); honored by `@uluops/core` | `8` |
 | `ULUOPS_THINKING_BUDGET` | Token budget for extended thinking (optional) | - |
 
 Create a `.env` file in your project directory:

package/dist/cli.js

@@ -11,7 +11,7 @@ import { registerCompletionCommands } from './commands/completion.js';
 import { registerDefinitionCommands } from './commands/definitions.js';
 import { registerDepsCommands } from './commands/deps.js';
 // Core SDK commands
-import { registerExecCommands } from './commands/exec.js';
+import { guardShadowedVersionFlag, registerExecCommands, } from './commands/exec.js';
 import { registerExecutionCommands } from './commands/executions.js';
 import { registerForkCommands } from './commands/forks.js';
 import { registerIssueCommands } from './commands/issues.js';
@@ -106,6 +106,10 @@ registerCompletionCommands(program);
 program.action(() => {
     program.help();
 });
+// Catch the `--version` shadow trap before Commander's immediate version
+// handler fires during parse (`exec describe ... --version <v>` would otherwise
+// silently print the CLI version and exit 0).
+guardShadowedVersionFlag();
 // Parse and execute
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/commands/auth.d.ts

@@ -1,19 +1,27 @@
 import type { Command } from 'commander';
 /**
- * Resolve which credential SOURCE the SDK used, by mirroring the exact
- * precedence ladder in @uluops/sdk-core loadCredentials (explicit flag > env
- * vars > stored profile). Returns a human-readable LABEL only — never the
- * credential value — matching the codebase's no-secret-leak discipline
- * (sdk-core's loader deliberately avoids echoing credential-file content).
+ * INFER which credential source the precedence resolution would select, by
+ * re-deriving the same ladder @uluops/sdk-core loadCredentials uses (explicit
+ * flag > env vars > stored profile). This is an INFERENCE, not an observation:
+ * loadCredentials returns the resolved credential but NOT which tier it came
+ * from, so this label is reconstructed from globalOpts + env and is never
+ * reported by the SDK. It is surfaced to users as "Credential Source (inferred)"
+ * precisely so it is not mistaken for an authoritative SDK readout. Returns a
+ * human-readable LABEL only — never the credential value — matching the
+ * codebase's no-secret-leak discipline (sdk-core's loader deliberately avoids
+ * echoing credential-file content).
  *
  * `.env` files are loaded into process.env at startup (loadEnvFiles), so a
  * credential set via .env is reported as an environment variable — there is no
  * separate ".env" tier to distinguish at this layer.
  *
- * This MIRRORS sdk-core; if that precedence changes, update both. Each tier is
- * pinned by a unit test. Only reached after createOpsContext has confirmed
- * credentials resolved (requireCredentials exits otherwise), so the final
- * else-branch is necessarily the stored profile.
+ * Because this MIRRORS sdk-core rather than observing it, a precedence change in
+ * sdk-core that is not mirrored here will make the inferred label drift — the
+ * "(inferred)" qualifier is what keeps that honest until/unless loadCredentials
+ * is taught to report its resolved source. Each tier is pinned by a unit test.
+ * Only reached after createOpsContext has confirmed credentials resolved
+ * (requireCredentials exits otherwise), so the final else-branch is necessarily
+ * the stored profile.
  *
  * @internal Exported for unit testing only.
  */

package/dist/commands/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAWR;AA+ED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgnB3D"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAWR;AA+ED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAynB3D"}

package/dist/commands/auth.js

@@ -7,20 +7,28 @@ import { emitJson } from '../formatters/json.js';
 import { formatApiKeys } from '../formatters/ops.js';
 import { exitWithError, promptInput, withSpinner, writeFileAtomic, } from '../utils.js';
 /**
- * Resolve which credential SOURCE the SDK used, by mirroring the exact
- * precedence ladder in @uluops/sdk-core loadCredentials (explicit flag > env
- * vars > stored profile). Returns a human-readable LABEL only — never the
- * credential value — matching the codebase's no-secret-leak discipline
- * (sdk-core's loader deliberately avoids echoing credential-file content).
+ * INFER which credential source the precedence resolution would select, by
+ * re-deriving the same ladder @uluops/sdk-core loadCredentials uses (explicit
+ * flag > env vars > stored profile). This is an INFERENCE, not an observation:
+ * loadCredentials returns the resolved credential but NOT which tier it came
+ * from, so this label is reconstructed from globalOpts + env and is never
+ * reported by the SDK. It is surfaced to users as "Credential Source (inferred)"
+ * precisely so it is not mistaken for an authoritative SDK readout. Returns a
+ * human-readable LABEL only — never the credential value — matching the
+ * codebase's no-secret-leak discipline (sdk-core's loader deliberately avoids
+ * echoing credential-file content).
  *
  * `.env` files are loaded into process.env at startup (loadEnvFiles), so a
  * credential set via .env is reported as an environment variable — there is no
  * separate ".env" tier to distinguish at this layer.
  *
- * This MIRRORS sdk-core; if that precedence changes, update both. Each tier is
- * pinned by a unit test. Only reached after createOpsContext has confirmed
- * credentials resolved (requireCredentials exits otherwise), so the final
- * else-branch is necessarily the stored profile.
+ * Because this MIRRORS sdk-core rather than observing it, a precedence change in
+ * sdk-core that is not mirrored here will make the inferred label drift — the
+ * "(inferred)" qualifier is what keeps that honest until/unless loadCredentials
+ * is taught to report its resolved source. Each tier is pinned by a unit test.
+ * Only reached after createOpsContext has confirmed credentials resolved
+ * (requireCredentials exits otherwise), so the final else-branch is necessarily
+ * the stored profile.
  *
  * @internal Exported for unit testing only.
  */
@@ -256,10 +264,17 @@ Examples:
                 failure: 'Failed to fetch user info',
             }, () => ctx.client.auth.getMe());
             if (ctx.json) {
-                // Default --json shape is a frozen public contract (README JSON
-                // Output Stability) — do NOT add credentialSource here. The source
-                // label is a human-readable convenience only.
+                // The default --json shape is a frozen public contract (README JSON
+                // Output Stability) — adding a field to it is a breaking change, so
+                // credentialSource is deliberately NOT in the stdout payload. But the
+                // most-captive population (CI debugging which identity authenticated)
+                // needs the source without a second non-JSON invocation, so emit the
+                // inferred label to STDERR: it reaches the debugging caller in the same
+                // run while leaving the frozen stdout bytes a parser pins untouched.
                 emitJson(ctx, user, 'auth.whoami');
+                if (!ctx.quiet) {
+                    console.error(`Credential Source (inferred): ${resolveCredentialSource(globalOpts)}`);
+                }
             }
             else {
                 console.log(`Email: ${user.email}`);
@@ -270,7 +285,7 @@ Examples:
                 if (user.name)
                     console.log(`Name: ${user.name}`);
                 console.log(`Auth Type: ${ctx.client.getAuthType()}`);
-                console.log(`Credential Source: ${resolveCredentialSource(globalOpts)}`);
+                console.log(`Credential Source (inferred): ${resolveCredentialSource(globalOpts)}`);
             }
         }
         catch (error) {