@swarmclawai/swarmclaw 1.2.1 → 1.2.3

package/README.md

@@ -190,6 +190,22 @@ The building blocks are the same: **agents, tools, memory, delegation, schedules
 
 ## Release Notes
 
+### v1.2.3 Highlights
+
+- **Standalone asset staging repair**: `swarmclaw server` now copies `.next/static` and `public/` into the Next.js standalone runtime after the first build, preventing blank UI loads and 503s for CSS, JS, and image assets.
+- **OpenClaw SSH port fix**: remote OpenClaw deploys now preserve well-known SSH ports like `22` instead of clamping them to `1024`.
+- **OpenClaw image source fix**: generated remote deploy bundles and default upgrade actions now use the official `ghcr.io/openclaw/openclaw:latest` image instead of the missing Docker Hub shorthand.
+- **Standalone self-healing**: server startup now repairs older incomplete standalone bundles by staging missing runtime assets before launching `server.js`.
+
+### v1.2.2 Highlights
+
+- **Modular chat execution pipeline**: decomposed the monolithic chat-execution module into 6 focused stages (preflight, preparation, stream execution, partial persistence, finalization, types) for maintainability and testability.
+- **Repository pattern adoption**: extracted ~15 repository modules from `storage.ts`, giving each domain (agents, sessions, missions, credentials, tasks, etc.) its own data-access layer.
+- **Runtime state encapsulation**: moved process-local state (active sessions, dev servers) from storage into `runtime-state.ts` with proper HMR singleton usage.
+- **Streaming state improvements**: stable assistant render IDs, better live-row display logic, and smoother streaming phase transitions in the chat UI.
+- **8 new skills**: coding-agent, github, nano-banana-pro, nano-pdf, openai-image-gen, resourceful-problem-solving, skill-creator, summarize.
+- **Lint baseline improvements**: reduced lint violations from 414 to 396 (-18).
+
 ### v1.2.1 Highlights
 
 - **System health endpoint**: new `/api/system/status` route returns lightweight health summary for external monitoring and uptime checks.
@@ -217,91 +233,6 @@ The building blocks are the same: **agents, tools, memory, delegation, schedules
 - **Playwright proxy hardening**: improved stdio pipe handling for dev server restarts.
 - **Scheduler and run ledger fixes**: improved scheduler reliability and run ledger state tracking.
 
-### v1.1.8 Highlights
-
-- **Agent live status**: real-time `/agents/:id/status` endpoint exposes goal, progress, and plan steps; org chart detail panel consumes it via `useAgentLiveStatus` hook.
-- **Learned skills lifecycle**: promote, dismiss, and delete learned skills via `/learned-skills/:id`; `/skill-review-counts` provides badge counts for the skills workspace.
-- **Gemini CLI provider**: Google Gemini CLI joins the provider roster alongside claude-cli and codex-cli, with shared CLI utilities factored into `cli-utils.ts`.
-- **Peer query & team context tools**: new session tools let agents query peers and access team context during conversations.
-- **Team resolution**: dedicated `team-resolution.ts` module resolves agent teams for delegation routing.
-- **Org chart activity feed**: timeline feed component and delegation bubble visualization for the org chart view.
-- **Skills workspace improvements**: expanded skills management UI with review-ready badges.
-- **Cost trend chart**: new dashboard component for cost visualization.
-- **Streaming fix**: text no longer gets stuck on the thinking indicator.
-- **Delegation normalization**: `delegationEnabled` now derived from agent role, removed from starter kit templates.
-- **Chat execution refinements**: improved continuation limits, post-stream finalization, and stream continuation.
-- **Memory and storage improvements**: memory tier management, consolidation enhancements, and storage cache updates.
-- **WebSocket and provider health**: improved WS client handling, delegation edge state, and provider health monitoring.
-
-### v1.1.7 Highlights
-
-- **Projects page redesign**: tabbed navigation (Overview, Work, Operations, Activity) with health grid, sortable task list, and timeline feed.
-- **Delegation visualization**: live org chart edges show active delegations with status, direction, and message popover on click.
-- **Credential self-service**: agents can check whether a credential exists and request missing ones from humans with structured messages, signup URLs, and durable wait.
-- **Main loop state persistence**: autonomous operation state now survives server restarts via on-disk persistence.
-- **Internal metadata stripping**: classification JSON and loop detection messages no longer leak into streamed agent output.
-- **Response completeness evaluator**: LLM-based detection of incomplete agent responses triggers continuation nudges.
-- **Coordinator delegation nudging**: coordinators that make 3+ direct tool calls get prompted to delegate to workers.
-- **Inspector panel overhaul**: new dashboard/config/files tabs absorb model switcher and workspace controls from chat header.
-- **Streaming phase indicators**: agent chat list shows queued, tool-in-use, responding, and reconnecting states.
-- **Shell safety**: agents can no longer kill SwarmClaw's own process or port.
-- **Worker-only providers**: CLI-backed providers (claude-cli, codex-cli, etc.) properly restricted from coordinator/heartbeat roles.
-- **HTTP tool removed**: the built-in HTTP session tool was removed from the standard toolkit.
-
-### v1.1.6 Highlights
-
-- **Org chart view**: visual agent hierarchy with drag-and-drop reparenting, team grouping, and context-menu actions for managing agent relationships directly from the canvas.
-- **Dashboard API**: server-side metrics endpoint with cost tracking, usage aggregation, and budget warning thresholds for operator visibility.
-- **Subagent lifecycle overhaul**: state-machine lineage tracking, `delegationDepth` limits, auto-announce on spawn, and cleaner parent-child session management.
-- **Chat execution refactor**: composable prompt sections replace monolithic prompt building, continuation evaluator consolidation, and extracted stream-continuation logic for maintainability.
-- **Per-agent cost attribution**: token costs are tracked and attributed per agent, enabling budget controls and cost reporting at the agent level.
-- **Capability-based task routing**: tasks can match agents by declared capabilities, not just explicit assignment, enabling smarter automatic dispatch.
-- **Bulk agent operations**: new `/api/agents/bulk` endpoint for batch updates across multiple agents in a single request.
-- **Document revisions API**: version history for documents with `/api/documents/[id]/revisions` endpoint.
-- **Store loader consolidation**: async loaders now use `createLoader()` and `setIfChanged` to eliminate redundant re-renders from polling.
-
-### v1.1.4 Highlights
-
-- **Orchestrator agents return as a first-class autonomy mode**: eligible agents can now run scheduled orchestrator wake cycles with their own mission, governance policy, wake interval, cycle cap, Autonomy-desk controls, and setup/editor support.
-- **Runtime durability is much harder to knock over**: the task queue now supports parallel execution with restart-safe swarm state, orphaned running-task recovery, stuck-task idle timeout detection, and provider-health persistence across daemon restarts.
-- **Recovery and safety paths are tighter**: provider errors are classified for smarter failover, unavailable agents defer work instead of burning it, supervisor blocks can create executable notifications, and agent budget limits now gate task execution before work starts.
-- **Temporary session rooms are easier to inspect**: chatrooms now split persistent rooms from temporary session-style rooms so orchestrator or structured-session conversations can stay visible without polluting the normal room list.
-
-### v1.1.3 Highlights
-
-- **Release integrity repair**: `build:ci` no longer trips over the langgraph checkpoint duplicate-column path, which restores clean build validation for the release line.
-- **Storage writes are safer**: credential and agent saves were tightened to upsert-only behavior and bulk-delete safety guards so tests or scripts cannot accidentally wipe live state.
-- **Plugin-to-extension cleanup finished**: remaining rename residue in scripts and tests was cleaned up so packaging and release tooling stay aligned with the current extensions model.
-- **Safe body parsing utility**: shared `safeParseBody()` replaces scattered `await req.json()` try/catch blocks across API routes.
-
-### v1.1.2 Highlights
-
-- **Structured Sessions expanded into richer orchestration**: ProtocolRun-based sessions now support dependency-aware step graphs, reusable step outputs, and a broader advanced execution model on the same durable runtime instead of bringing back a separate orchestrator.
-- **Explicit Ollama local/cloud routing**: agents and sessions now persist the user-selected Ollama mode directly, so local Ollama no longer flips to cloud because of model naming or leftover credentials.
-- **Chat and runtime regression hardening**: live-streamed inline media, stale streaming cleanup, exact-output handling, and chat rendering bugs were tightened again, including the recent message-row and avatar rendering regressions.
-- **Nebius and DeepInfra as built-in providers**: both are now first-class providers with setup wizard entries, model discovery, and pre-configured defaults instead of requiring the custom provider workaround.
-- **`stream_options` resilience**: the OpenAI-compatible streaming handler now retries without `stream_options` if a provider rejects it with 400, fixing connectivity for strict endpoints.
-
-### v1.1.1 Highlights
-
-- **Structured Sessions are now contextual**: start bounded structured runs from direct chats, chatrooms, tasks, missions, or schedules, including a new chatroom `/breakout` command that spins up a focused session from the current room with auto-filled participants and kickoff context.
-- **ProtocolRun orchestration matured**: structured sessions now run on the same durable engine for step-based branching, repeat loops, parallel branches, and explicit joins instead of growing a separate orchestration subsystem.
-- **Live-agent runtime hardening**: exact-output contracts, memory preflight behavior, same-channel delivery rendering, inline media, and grounded runtime inspection were all tightened through live-agent validation before release.
-
-### v1.1.0 Highlights
-
-- **Mission controller and Missions UI**: SwarmClaw now tracks durable multi-step objectives as missions with status, phase, linked tasks, queued turns, recent runs, event history, and operator actions from the new **Missions** surface.
-- **Autonomy safety desk and run replay**: the new **Autonomy Control** page adds estop visibility, resume policy controls, incident review, and run replay backed by durable run history rather than transient in-memory state.
-- **Durable queued follow-ups**: direct chat and connector follow-up turns now use a backend queue so queued work survives reloads, drains in order, and stays attached to the right mission/session context.
-- **Chat execution and UX hardening**: streamed handoff, memory writes, inline media, queue state, and tool-policy fallback behavior were cleaned up so agents are less noisy, less brittle, and easier to follow in real chats.
-
-### v1.0.9 Highlights
-
-- **Quieter chat and inbox replies**: chat-origin and connector turns now suppress more hidden control text, stop replaying connector-tool output as normal assistant prose, and avoid extra empty follow-up chatter after successful tool work.
-- **Sender-aware direct inbox replies**: direct connector sessions can honor stored sender display names and reply-medium preferences, including voice-note-first replies when the connector supports binary media and the agent has a configured voice.
-- **Cleaner connector delivery reconciliation**: connector delivery markers now track what was actually sent, response previews prefer the delivered transcript, and task/connector followups resolve local output files more reliably.
-- **Memory-write followthrough hardening**: successful memory store/update turns terminate more cleanly, which reduces unnecessary post-tool loops while still allowing a natural acknowledgement when the user needs one.
-
 ## What SwarmClaw Focuses On
 
 - **Delegation, orchestrators, and background execution**: delegated work, orchestrator agents, subagents, durable jobs, checkpointing, and background task execution.

package/bin/server-cmd.js

@@ -47,6 +47,10 @@ function ensureDir(dir) {
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
 }
 
+function resolveStandaloneRuntimeDir(serverJs) {
+  return path.dirname(serverJs)
+}
+
 function log(msg) {
   process.stdout.write(`[swarmclaw] ${msg}\n`)
 }
@@ -206,6 +210,51 @@ function symlinkDir(targetPath, linkPath) {
   fs.symlinkSync(targetPath, linkPath, process.platform === 'win32' ? 'junction' : 'dir')
 }
 
+function syncStandaloneRuntimeAssets({
+  sourceRoot,
+  runtimeDir,
+  force = false,
+} = {}) {
+  const assets = [
+    {
+      key: 'staticCopied',
+      sourcePath: path.join(sourceRoot, '.next', 'static'),
+      targetPath: path.join(runtimeDir, '.next', 'static'),
+      optional: false,
+    },
+    {
+      key: 'publicCopied',
+      sourcePath: path.join(sourceRoot, 'public'),
+      targetPath: path.join(runtimeDir, 'public'),
+      optional: true,
+    },
+  ]
+
+  const result = {
+    staticCopied: false,
+    publicCopied: false,
+  }
+
+  for (const asset of assets) {
+    if (!fs.existsSync(asset.sourcePath)) {
+      if (!asset.optional) result[asset.key] = false
+      continue
+    }
+    if (!force && fs.existsSync(asset.targetPath)) continue
+
+    ensureDir(path.dirname(asset.targetPath))
+    fs.rmSync(asset.targetPath, { recursive: true, force: true })
+    fs.cpSync(asset.sourcePath, asset.targetPath, {
+      recursive: true,
+      force: true,
+      dereference: true,
+    })
+    result[asset.key] = true
+  }
+
+  return result
+}
+
 function prepareBuildWorkspace({ pkgRoot = PKG_ROOT, buildRoot = resolvePackageBuildRoot(pkgRoot), nodeModulesDir } = {}) {
   copyBuildWorkspaceContents(pkgRoot, buildRoot)
   symlinkDir(nodeModulesDir, path.join(buildRoot, 'node_modules'))
@@ -285,6 +334,15 @@ function runBuild({ pkgRoot = PKG_ROOT } = {}) {
     },
   })
 
+  const standalone = locateStandaloneServer({ pkgRoot: buildRoot })
+  if (standalone) {
+    syncStandaloneRuntimeAssets({
+      sourceRoot: buildRoot,
+      runtimeDir: resolveStandaloneRuntimeDir(standalone.serverJs),
+      force: true,
+    })
+  }
+
   log('Build complete.')
 }
 
@@ -306,10 +364,12 @@ async function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
     logError('Standalone server.js not found in the installed package. Try running: swarmclaw server --build')
     process.exit(1)
   }
-  const { root: runtimeRoot, serverJs } = standalone
+  const { root: buildRoot, serverJs } = standalone
+  const runtimeRoot = resolveStandaloneRuntimeDir(serverJs)
 
   ensureDir(SWARMCLAW_HOME)
   ensureDir(DATA_DIR)
+  syncStandaloneRuntimeAssets({ sourceRoot: buildRoot, runtimeDir: runtimeRoot })
 
   const port = opts.port || '3456'
   const wsPort = opts.wsPort || String(Number(port) + 1)
@@ -328,6 +388,7 @@ async function startServer(opts, { pkgRoot = PKG_ROOT } = {}) {
 
   log(`Starting server on ${host}:${port} (WebSocket: ${wsPort})...`)
   log(`Package root: ${pkgRoot}`)
+  log(`Build root: ${buildRoot}`)
   log(`Runtime root: ${runtimeRoot}`)
   log(`Home: ${SWARMCLAW_HOME}`)
   log(`Data directory: ${DATA_DIR}`)
@@ -545,6 +606,8 @@ module.exports = {
   resolveReadyCheckHost,
   resolveStandaloneCandidateRoots,
   resolveStandaloneBase,
+  resolveStandaloneRuntimeDir,
   runBuild,
+  syncStandaloneRuntimeAssets,
   waitForPortReady,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Self-hosted AI runtime for OpenClaw, delegation, autonomy, runtime skills, crypto wallets, and chat platform connectors.",
   "license": "MIT",
   "publishConfig": {
@@ -30,7 +30,7 @@
   },
   "files": [
     "bin/",
-    "bundled-skills/",
+    "skills/",
     "src/",
     "public/",
     "Dockerfile.sandbox-browser",

package/skills/coding-agent/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: coding-agent
+description: 'Delegate coding tasks to external coding agents (Claude Code, Codex, Pi, OpenCode) via shell. Use when: (1) building new features or apps in a separate project, (2) reviewing PRs, (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit directly), reading code (use read/file tools), or work inside the SwarmClaw workspace itself.'
+metadata:
+  {
+    "openclaw": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } },
+  }
+---
+
+# Coding Agent
+
+Delegate coding tasks to external coding agents via shell tools.
+
+## Agent Execution Modes
+
+### Claude Code (recommended)
+
+Use `--print --permission-mode bypassPermissions` for non-interactive execution:
+
+```bash
+cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task here'
+```
+
+For background execution, use the shell tool's background mode.
+
+**Do NOT use PTY mode with Claude Code** — `--print` mode keeps full tool access and avoids interactive confirmation dialogs.
+
+### Codex
+
+Codex requires a git repository and PTY mode:
+
+```bash
+# Quick one-shot (auto-approves changes)
+cd /path/to/project && codex exec --full-auto 'Build a dark mode toggle'
+
+# Codex refuses to run outside a git directory. For scratch work:
+SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt"
+```
+
+### Pi Coding Agent
+
+```bash
+# Install: npm install -g @mariozechner/pi-coding-agent
+cd /path/to/project && pi 'Your task'
+
+# Non-interactive mode
+pi -p 'Summarize src/'
+
+# Different provider/model
+pi --provider openai --model gpt-4o-mini -p 'Your task'
+```
+
+### OpenCode
+
+```bash
+cd /path/to/project && opencode run 'Your task'
+```
+
+## PR Reviews
+
+Clone to a temp folder or use git worktree — never review PRs in the SwarmClaw project directory:
+
+```bash
+# Clone to temp for safe review
+REVIEW_DIR=$(mktemp -d)
+git clone https://github.com/user/repo.git $REVIEW_DIR
+cd $REVIEW_DIR && gh pr checkout 130
+codex review --base origin/main
+
+# Or use git worktree
+git worktree add /tmp/pr-130-review pr-130-branch
+cd /tmp/pr-130-review && codex review --base main
+```
+
+## Parallel Issue Fixing
+
+Use git worktrees to fix multiple issues in parallel:
+
+```bash
+# Create worktrees
+git worktree add -b fix/issue-78 /tmp/issue-78 main
+git worktree add -b fix/issue-99 /tmp/issue-99 main
+
+# Launch agents (use background shell execution)
+cd /tmp/issue-78 && codex --yolo 'Fix issue #78: <description>. Commit when done.'
+cd /tmp/issue-99 && codex --yolo 'Fix issue #99: <description>. Commit when done.'
+
+# Create PRs after
+cd /tmp/issue-78 && git push -u origin fix/issue-78
+gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
+
+# Cleanup
+git worktree remove /tmp/issue-78
+git worktree remove /tmp/issue-99
+```
+
+## Rules
+
+1. **Use the right execution mode per agent**: Claude Code uses `--print` (no PTY); Codex/Pi/OpenCode may need interactive terminal.
+2. **Respect tool choice** — if the user asks for Codex, use Codex. Don't silently switch agents.
+3. **Be patient** — don't kill sessions because they seem slow.
+4. **Monitor progress** — check output periodically without interfering.
+5. **Never run coding agents inside the SwarmClaw project directory** — use a separate project directory or temp folder.
+
+## Progress Updates
+
+When spawning coding agents in the background:
+
+- Send a short message when you start (what's running, where).
+- Update only when something changes (milestone, error, completion).
+- If you kill a session, say so immediately and explain why.

package/skills/github/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: github
+description: "GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues, (3) listing/filtering PRs or issues, (4) viewing run logs. NOT for: local git operations (use git directly), non-GitHub repos, or cloning (use git clone)."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🐙",
+        "requires": { "bins": ["gh"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+            {
+              "id": "apt",
+              "kind": "apt",
+              "package": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (apt)",
+            },
+          ],
+      },
+  }
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub repositories, issues, PRs, and CI.
+
+## Setup
+
+```bash
+# Authenticate (one-time)
+gh auth login
+
+# Verify
+gh auth status
+```
+
+## Common Commands
+
+### Pull Requests
+
+```bash
+# List PRs
+gh pr list --repo owner/repo
+
+# Check CI status
+gh pr checks 55 --repo owner/repo
+
+# View PR details
+gh pr view 55 --repo owner/repo
+
+# Create PR
+gh pr create --title "feat: add feature" --body "Description"
+
+# Merge PR
+gh pr merge 55 --squash --repo owner/repo
+```
+
+### Issues
+
+```bash
+# List issues
+gh issue list --repo owner/repo --state open
+
+# Create issue
+gh issue create --title "Bug: something broken" --body "Details..."
+
+# Close issue
+gh issue close 42 --repo owner/repo
+```
+
+### CI/Workflow Runs
+
+```bash
+# List recent runs
+gh run list --repo owner/repo --limit 10
+
+# View specific run
+gh run view <run-id> --repo owner/repo
+
+# View failed step logs only
+gh run view <run-id> --repo owner/repo --log-failed
+
+# Re-run failed jobs
+gh run rerun <run-id> --failed --repo owner/repo
+```
+
+### API Queries
+
+```bash
+# Get PR with specific fields
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+
+# List all labels
+gh api repos/owner/repo/labels --jq '.[].name'
+
+# Get repo stats
+gh api repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output with `--jq` filtering:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+gh pr list --json number,title,state,mergeable --jq '.[] | select(.mergeable == "MERGEABLE")'
+```
+
+## Templates
+
+### PR Review Summary
+
+```bash
+PR=55 REPO=owner/repo
+echo "## PR #$PR Summary"
+gh pr view $PR --repo $REPO --json title,body,author,additions,deletions,changedFiles \
+  --jq '"**\(.title)** by @\(.author.login)\n\n\(.body)\n\n+\(.additions) -\(.deletions) across \(.changedFiles) files"'
+gh pr checks $PR --repo $REPO
+```
+
+### Issue Triage
+
+```bash
+gh issue list --repo owner/repo --state open --json number,title,labels,createdAt \
+  --jq '.[] | "[\(.number)] \(.title) - \([.labels[].name] | join(", ")) (\(.createdAt[:10]))"'
+```
+
+## Notes
+
+- Always specify `--repo owner/repo` when not in a git directory.
+- Use URLs directly: `gh pr view https://github.com/owner/repo/pull/55`
+- Rate limits apply; use `gh api --cache 1h` for repeated queries.

package/skills/nano-banana-pro/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image (Nano Banana Pro). Use when asked to create, generate, or edit images and a Gemini API key is available. Supports text-to-image generation, single-image editing, and multi-image composition (up to 14 images).
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🍌",
+        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"] },
+        "primaryEnv": "GEMINI_API_KEY",
+        "install":
+          [
+            {
+              "id": "uv-brew",
+              "kind": "brew",
+              "formula": "uv",
+              "bins": ["uv"],
+              "label": "Install uv (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Nano Banana Pro (Gemini 3 Pro Image)
+
+Use the bundled script to generate or edit images.
+
+## Generate
+
+```bash
+uv run {baseDir}/scripts/generate_image.py --prompt "your image description" --filename "output.png" --resolution 1K
+```
+
+## Edit (Single Image)
+
+```bash
+uv run {baseDir}/scripts/generate_image.py --prompt "edit instructions" --filename "output.png" -i "/path/in.png" --resolution 2K
+```
+
+## Multi-Image Composition (up to 14 images)
+
+```bash
+uv run {baseDir}/scripts/generate_image.py --prompt "combine these into one scene" --filename "output.png" -i img1.png -i img2.png -i img3.png
+```
+
+## API Key
+
+Set `GEMINI_API_KEY` as an environment variable, or pass `--api-key <KEY>` to the script.
+
+## Aspect Ratio (optional)
+
+```bash
+uv run {baseDir}/scripts/generate_image.py --prompt "portrait photo" --filename "output.png" --aspect-ratio 9:16
+```
+
+## Notes
+
+- Resolutions: `1K` (default), `2K`, `4K`.
+- Aspect ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. Without `--aspect-ratio`, the model picks freely.
+- Use timestamps in filenames for uniqueness: `yyyy-mm-dd-hh-mm-ss-name.png`.
+- Do not read the image back into context; report the saved path only.