oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-hwp/resources/troubleshooting.md

@@ -0,0 +1,70 @@
+# oma-hwp Troubleshooting
+
+## Diagnosing conversion issues
+
+### 1. "지원하지 않는 파일 형식" / unsupported file format
+- Verify the extension matches the content. HWP5 files should start with `D0 CF 11 E0` (OLE compound). HWPX starts with `50 4B 03 04` (ZIP).
+- Check with: `xxd "{file}" | head -1`
+- If the extension is wrong, rename and retry.
+- If the file is genuinely a different format (e.g., Word, Excel), use the appropriate skill.
+
+### 2. Encrypted or password-protected HWP
+- kordoc reports `암호화된 문서` / "encrypted document".
+- General password-locked HWP: the CLI currently has no inline password flag. Ask the user to decrypt the file first (via Hancom Office) and retry.
+- DRM "distribution-only" HWP (배포용): kordoc ports rhwp's AES-128 ECB algorithm and often succeeds. If it still fails, note as best-effort and continue with other files.
+
+### 3. Empty Markdown output
+Most likely causes:
+- HWP contains only scanned images without a text layer → needs OCR (out of scope).
+- kordoc bug on a specific document → try `bunx kordoc@latest`; if still empty, report upstream with a sample.
+
+### 4. Missing or broken tables
+- Simple tables: GFM pipe syntax.
+- Tables with `colspan` / `rowspan`: kordoc falls back to HTML `<table>`. This is expected and correct.
+- Nested tables: kordoc emits the nested `<table>` inside its parent cell. The post-processor preserves the complete balanced outer table as HTML rather than flattening it and risking structural loss.
+- If tables are completely absent, confirm the source file actually contains tables (sometimes they are images).
+- `flatten-tables.ts` scans balanced outer `<table>...</table>` blocks. If a block contains a nested table, it is kept as HTML so parent/child structure and closing tags remain intact.
+
+### 5. Hyperlinks look wrong
+kordoc sanitizes links (XSS defense). If a legitimate link is stripped, verify the original URL scheme: only `http://`, `https://`, `mailto:`, and relative paths are preserved by default.
+
+### 6. Image extraction issues
+- kordoc extracts images from ZIP entries (HWPX) and HWP5 `BinData` streams.
+- Output is typically written as `{input_basename}.assets/` next to the Markdown file.
+- If images are missing, check whether the source file truly embeds them (vs linking externally).
+
+### 7. Slow conversion / timeout on huge files
+- Use `-p` to narrow to a page/section range.
+- Split processing across page ranges and concatenate results.
+- If a specific PDF-embedded HWPX is slow, consider oma-pdf for the PDF portion.
+
+### 8. kordoc crash / stack trace
+1. Upgrade: `bunx kordoc@latest` (bust the bunx cache if needed)
+2. Capture a minimal reproducible fixture
+3. File an issue: https://github.com/chrisryugj/kordoc/issues
+4. Meanwhile, if only a subset of the document triggers the crash, use `-p` to skip it
+
+### 9. Reproducibility vs freshness tradeoff
+- `bunx kordoc@latest` always pulls latest. Fixes land fast, but outputs may drift. A bare `bunx kordoc` reuses the bunx cache and can be arbitrarily old; always include `@latest` or a pinned version.
+- For long-running projects, pin a version under `hwp:` in `.agents/oma-config.yaml` (not `config/hwp-config.yaml` — `oma update` overwrites the skill file):
+  ```yaml
+  hwp:
+    version:
+      channel: pinned
+      pinned: "4.7.3"
+  ```
+  Then invoke via `bunx kordoc@4.7.3 ...` in commands. Check the current release with `npm view kordoc version` before pinning — the example above may itself be stale.
+
+## kordoc limitations (upstream-owned)
+- Inline password entry for encrypted HWP: not yet supported.
+- OCR of scanned HWPs: out of kordoc's scope; it does not perform OCR.
+- Perfect fidelity of complex shapes / drawings: Markdown cannot represent drawing primitives; expect them to be dropped or replaced by placeholder markers.
+
+## When to route elsewhere
+| Symptom | Route to |
+|---------|----------|
+| Input is `.pdf` | `oma-pdf` |
+| Input is `.xlsx` / `.docx` | `bunx kordoc@latest` directly (skill not advertising) |
+| Need OCR of scanned documents | Out of scope; use a dedicated OCR pipeline |
+| Need to author / edit HWPX (generate, fill, seal, patch) | `bunx kordoc@latest generate|fill|seal|patch ...` directly (skill not advertising; see Scope Reminder table in `execution-protocol.md`) |
+| Need personal-data masking, notation lint, structure validation, or SVG render | `bunx kordoc@latest redact|lint|validate|render ...` directly (skill not advertising) |

package/skills/oma-hwp/resources/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["*.ts", "*.d.ts"]
+}

package/skills/oma-hwp/resources/turndown-plugin-gfm.d.ts

@@ -0,0 +1,9 @@
+declare module "turndown-plugin-gfm" {
+  import type TurndownService from "turndown";
+
+  export function tables(turndownService: TurndownService): void;
+  export function gfm(turndownService: TurndownService): void;
+  export function highlightedCodeBlock(turndownService: TurndownService): void;
+  export function strikethrough(turndownService: TurndownService): void;
+  export function taskListItems(turndownService: TurndownService): void;
+}

package/skills/oma-image/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: oma-image
+description: Generate raster images or reference-guided variations through the
+  OMA image CLI. Use for image assets or explicit vendor comparisons; pixel
+  editing uses an editor.
+---
+
+# Image Agent - Multi-Vendor Image Router
+
+## Scheduling
+
+### Goal
+Generate images and visual assets through authenticated multi-vendor routing while preserving prompt clarity, reference-guided regeneration, cost controls, and reproducible output manifests.
+
+### Intent signature
+- User asks to generate images, visual assets, illustrations, product photos, concept art, mockups, or AI art.
+- Another skill needs shared image-generation infrastructure.
+- User provides reference images for a new generated variation or asks for vendor comparison.
+
+### When to use
+
+- Generating images, visual assets, illustrations, product photos, concept art
+- Comparing output between multiple image models for the same prompt
+- Producing images from prompts within editor workflows (Claude Code, Codex, Gemini CLI)
+- Other skills needing image generation infrastructure (shared invocation)
+- Regenerating a new image that follows a supplied reference's subject, style, lighting, or composition
+
+### When NOT to use
+
+- Pixel-level editing, masking, inpainting, object removal, compositing, cropping, resizing, or format conversion -> out of scope; use an image editor or a tool that explicitly supports that operation.
+- Generating videos or audio -> out of scope
+- Inline vector art / SVG composition from structured data -> use a templating skill
+- Simple asset resizing or format conversion -> use a dedicated image library
+
+### Expected inputs
+- Image prompt or creative brief
+- Optional vendor, size, quality, count, output directory, and reference images
+- Authentication/environment state for Codex, Pollinations, or Gemini
+
+### Expected outputs
+- Generated image files under `.agents/results/images/` or requested output directory
+- `manifest.json` with prompt, vendor, model, and reproducibility metadata
+- Vendor comparison outputs when `--vendor all` is used
+
+### Dependencies
+- `oma image generate` CLI and vendor authentication
+- Codex image generation, Pollinations API, or Gemini API/CLI strategy
+- `resources/vendor-matrix.md`, `resources/prompt-tips.md`, and the `image:` section of `.agents/oma-config.yaml`
+
+### Control-flow features
+- Branches by prompt ambiguity, vendor auth, cost threshold, reference-guided regeneration support, path safety, and safety/timeout exit codes
+- Calls external vendor APIs/CLIs
+- Reads reference images and writes generated images plus manifests
+
+## Structural Flow
+
+### Entry
+1. Validate that the request contains enough subject, setting, style, usage, and aspect-ratio signal.
+2. Classify a supplied image as a reference for a newly generated variation, or as a request for unsupported pixel/mask editing.
+3. Check authentication, cost guardrails, output path, and count limits.
+
+### Transitions
+- If the subject or intended result cannot be inferred, clarify that missing input; otherwise proceed with reasonable defaults.
+- If `--vendor all` is requested, require every requested vendor to be available.
+- If the request is reference-guided regeneration and the selected vendor supports references, pass it automatically.
+- If the request requires pixel, mask, crop, resize, or format editing, stop before generation and name the unsupported operation and an appropriate editor route.
+- If estimated cost exceeds guardrail, require confirmation unless bypassed.
+
+### Failure and recovery
+- If auth is missing, report vendor-specific authentication requirement.
+- If reference support is unavailable for the selected vendor, reject with actionable guidance.
+- If local CLI is outdated, ask user to run `oma update`.
+- If generation times out or is blocked, surface exit code and provider status.
+
+### Exit
+- Success: images and manifest exist in the output directory.
+- Partial success: some vendors fail in comparison mode and failures are reported.
+- Failure: no image is produced and the route/cost/auth/safety blocker is explicit.
+
+## Logical Operations
+
+### Tools and instruments
+- `oma image generate`, `oma image doctor`, `oma image vendor list`
+- Codex, Pollinations, and Gemini provider paths
+- Prompt tips, vendor matrix, and image config
+
+### Canonical command path
+```bash
+oma image doctor
+oma image generate "<prompt>" --vendor auto --size auto --quality auto --output json
+```
+
+With reference images:
+```bash
+oma image generate --reference "<absolute-path>" --vendor codex "<prompt>"
+```
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `LOCAL_FS` | Reference images, generated images, manifests |
+| `PROCESS` | Provider CLIs and image router commands |
+| `NETWORK` | Pollinations/Gemini or provider APIs |
+| `CREDENTIALS` | Provider auth and API keys |
+
+### Preconditions
+- Prompt is sufficiently specified or user approves amplification.
+- Required vendor auth and output permissions exist.
+- Reference paths are accessible when used.
+
+### Effects and side effects
+- Creates image files and manifests.
+- May call paid or rate-limited provider APIs.
+- May read attached/reference images.
+
+### Guardrails
+
+1. **Resolve the brief**: use supplied details and reasonable creative defaults. Ask only when a missing choice materially changes the requested result. Do not require approval of an expanded prompt when generation is already authorized.
+2. **Authentication-aware dispatch**: detect which vendor CLIs are available and run only those; with `--vendor all`, every requested vendor must be available (strict). Caveat: the `antigravity` health check verifies installation only (`agy --version`) — a signed-out agy passes health and fails at generate time with agy's own error.
+3. **Cost guardrail**: confirm before executing runs whose estimated cost is ≥ `$0.20` (configurable). `--yes` / `OMA_IMAGE_YES=1` bypass. Choose generation from the requested outcome, not keyword presence. **Non-interactive contexts** (agents, CI — no TTY on stdin): the CLI cannot prompt, so a run at/over the threshold exits 1 with a message naming `--yes`. Use `--dry-run` to estimate cost. Reuse an existing budget authorization; otherwise confirm the additional spend before re-running with `-y`.
+4. **Path safety**: output paths outside `$PWD` require `--allow-external-output`.
+5. **Cancellable**: SIGINT/SIGTERM aborts in-flight provider calls and the orchestrator.
+6. **Deterministic outputs**: every run writes `manifest.json` next to the images for reproducibility.
+7. **Max `n` = 5**: wall-time bound.
+8. **Exit codes align with `oma search fetch`** (0, 1, 2=safety, 3=not-found, 4=invalid-input, 5=auth-required, 6=timeout).
+
+### Creative brief
+Use the requested subject and constraints. Infer setting, style, lighting, and aspect ratio when unspecified; preserve explicit text and reference intent. Ask only for a material unresolved choice. Read `resources/prompt-tips.md` for an unfamiliar image category.
+
+## References
+- Provider invocation, references, and output layout: `resources/invocation.md` (selected vendor or reference-image operation only).
+
+### Configuration
+
+Project-specific settings: the `image:` section of `.agents/oma-config.yaml`, which `oma update` preserves. Shipped defaults live in the CLI (`DEFAULTS` in `cli/commands/image/config.ts`) — write only the keys you change. The legacy `config/image-config.yaml` is no longer read by the CLI; migration 022 moves anything you had changed there into oma-config (and deletes the file when it was never edited).
+Env vars: `OMA_IMAGE_DEFAULT_VENDOR`, `OMA_IMAGE_DEFAULT_OUT`, `OMA_IMAGE_YES`, `POLLINATIONS_API_KEY`.
+
+- Execution steps (follow for the selected task): `resources/execution-protocol.md`
+- Vendor matrix: `resources/vendor-matrix.md`
+- Prompt tips: `resources/prompt-tips.md`
+- Checklist (run before handoff): `resources/checklist.md`
+- Context loading: `../_shared/core/context-loading.md`

package/skills/oma-image/config/image-config.yaml

@@ -0,0 +1,70 @@
+# oma-image skill configuration — NO LONGER READ BY THE CLI.
+#
+# Editing this file has no effect. Put your overrides under `image:` in
+# .agents/oma-config.yaml, which `oma update` preserves; this file is
+# overwritten. `oma update` runs migration 022, which moves anything you had
+# changed here into oma-config for you.
+#
+# The values below mirror DEFAULTS in cli/commands/image/config.ts, the source
+# of truth. They are kept only so migration 022 can tell an edited file from a
+# pristine one.
+
+default_output_dir: .agents/results/images
+default_vendor: auto
+default_size: 1024x1024
+default_quality: auto
+default_count: 1
+default_timeout_sec: 180
+
+vendors:
+  codex:
+    enabled: true
+    model: gpt-image-2
+    extra_args: []
+  antigravity:
+    # Antigravity CLI (`agy`) is an agentic CLI that drives its own image
+    # generation tool over the Gemini Code Assist subscription. The exact
+    # model agy picks internally is opaque to us, so we deliberately leave
+    # `model` empty — no fictional model hint goes into the prompt, the
+    # manifest, or the output filename. Requires `agy` on PATH.
+    enabled: true
+    model: ""
+  pollinations:
+    enabled: true
+    model: flux
+
+cost_guardrail:
+  estimate_threshold_usd: 0.20
+  per_image_usd:
+    codex:
+      gpt-image-2:
+        low: 0.02
+        medium: 0.03
+        high: 0.04
+        auto: 0.03
+    antigravity:
+      "":
+        low: 0
+        medium: 0
+        high: 0
+        auto: 0
+    # Mirrors FREE_MODELS/CREDIT_MODELS in the pollinations provider.
+    # Credit-gated models bill prepaid pollen credits, not USD, so the
+    # USD guardrail estimate stays 0 for all of them.
+    pollinations:
+      flux: { low: 0, medium: 0, high: 0, auto: 0 }
+      zimage: { low: 0, medium: 0, high: 0, auto: 0 }
+      qwen-image: { low: 0, medium: 0, high: 0, auto: 0 }
+      wan-image: { low: 0, medium: 0, high: 0, auto: 0 }
+      gptimage: { low: 0, medium: 0, high: 0, auto: 0 }
+      gptimage-large: { low: 0, medium: 0, high: 0, auto: 0 }
+      gpt-image-2: { low: 0, medium: 0, high: 0, auto: 0 }
+      klein: { low: 0, medium: 0, high: 0, auto: 0 }
+      kontext: { low: 0, medium: 0, high: 0, auto: 0 }
+
+compare:
+  folder_pattern: "{timestamp}-{shortid}-compare"
+  manifest: true
+
+naming:
+  single_folder_pattern: "{timestamp}-{shortid}"

package/skills/oma-image/resources/checklist.md

@@ -0,0 +1,18 @@
+# Checklist: before you run `oma image generate`
+
+- [ ] Prompt is specific about scene, subject, and style (see `prompt-tips.md`).
+- [ ] `--vendor` matches available authenticated CLIs. Run `oma image doctor` if unsure.
+- [ ] `-n` is ≤ 5; wall time scales with count.
+- [ ] `--output-dir` is inside the project, or you've set `--allow-external-output`.
+- [ ] Estimated cost is acceptable. Run `--dry-run` first for unfamiliar combinations.
+- [ ] Running non-interactively (agent/CI) with cost ≥ threshold? Confirm with the user first, then pass `-y` — the CLI cannot prompt without a TTY and exits 1.
+- [ ] Secrets are not in the prompt, or `--no-prompt-in-manifest` is set.
+- [ ] For `--vendor all`, every enabled vendor is healthy (strict mode exits 5 otherwise).
+
+# Checklist: after the run
+
+- [ ] `manifest.json` was written inside the run folder.
+- [ ] Each recorded run has an `ok` status or a classified error.
+- [ ] Strategy attempts are objects (not compact strings).
+- [ ] Images open without corruption.
+- [ ] If results are consumed downstream, the consumer parses `--output json` stdout rather than re-reading the manifest file.

package/skills/oma-image/resources/execution-protocol.md

@@ -0,0 +1,117 @@
+# Image Agent - Execution Protocol
+
+## Step -1: Clarify / Amplify Prompt (agent-side, before `oma image generate`)
+
+Run the **Clarification Protocol** in `SKILL.md` before shelling out.
+
+## Step 0: Parse Request
+
+1. Extract prompt and flags from the invocation.
+2. Resolve defaults from shipped code defaults → the `image:` section of `.agents/oma-config.yaml` → env vars → CLI flags (lowest to highest precedence). `config/image-config.yaml` is not consulted.
+3. Validate:
+   - `count` ∈ [1, 5]
+   - `size` is `auto` or any `WxH` passing `size-guard.ts` (each edge ∈ [16, 3840], multiples of 16, aspect ratio 1:3..3:1).
+   - `quality` ∈ {`low`, `medium`, `high`, `auto`}
+   - `vendor` ∈ {`auto`, `codex`, `pollinations`, `antigravity`, `all`} or a concrete registered name.
+   - `model` (optional): vendor-specific override passed through as-is; applies to every vendor in the run set. `antigravity` ignores it.
+   - `reference` (if any): each path exists, is a regular file ≤ 5MB, magic-byte-matches PNG/JPEG/GIF/WebP, ≤ 10 total, and duplicate paths are rejected with exit 4.
+4. If invalid: exit code 4 and a message identifying the offending field.
+
+## Step 0.5: Reference-guided regeneration
+
+When `--reference <path...>` is supplied, the operation is reference-guided regeneration: it may
+follow subject, style, lighting, or composition, but it cannot promise a pixel-preserving edit.
+Before continuing, reject pixel/mask operations (inpainting, object removal, selective replacement,
+crop, resize, or conversion) and route them to an editor or deterministic image processor.
+
+1. Validate every path via `reference-guard.ts`. On failure → exit 4.
+2. Vendor support check (only `codex` and `antigravity` support references):
+   - Explicit `--vendor <name>` / `--vendor all`: reject with exit 4 and a hint to switch vendor if any requested vendor lacks reference support.
+   - `--vendor auto`: silently drop reference-unsupported vendors from the healthy set. If no reference-supporting vendor remains: exit 4 when none is registered at all, exit 5 (with per-vendor setup hints) when some are registered but unhealthy.
+3. Pass validated absolute paths through `GenerateInput.referenceImages`:
+   - `codex` provider appends `-i <path>` per reference to `codex exec` and adds a guidance sentence to the instruction text.
+   - `antigravity` provider copies each reference into a per-run temp dir, exposes it to agy via `--add-dir <tmpdir>`, and lists the resulting paths inline in the agy prompt.
+4. Record reference paths in `manifest.json` under `reference_images` (top-level array of absolute paths).
+
+### Auto-forward attached images (MANDATORY)
+
+If the user asks for a reference-guided regeneration and a host-attached image is visible to the agent (e.g. `[Image: source: <path>]` in a Claude Code system message, Antigravity workspace upload, or explicit user-provided path), the agent MUST pass it via `--reference <path>`. Do not fall back to describing the image in prose. Do not ask the user to re-type the path. If `oma image generate --help` shows no `--reference` flag, instruct the user to run `oma update` and retry; do not silently degrade.
+
+### Host-Specific Reference Paths
+
+Agents invoking `oma image generate --reference` should surface the following host-specific locations to the user:
+
+| Host CLI | Attachment Surface | Path pattern |
+|----------|--------------------|--------------|
+| **Claude Code** | `[Image: source: ...]` in system messages | `~/.claude/image-cache/<session-uuid>/<N>.png` (undocumented, verified empirically; cache is cleared on session end) |
+| **Antigravity IDE** | Workspace upload via "Upload to Agent" | Project workspace upload dir; exact path shown in IDE file tree |
+| **Codex CLI as host** | `-i` flag attaches to LLM context only | No filesystem path exposed. User must provide an explicit path (e.g., `~/Downloads/foo.png`). In-conversation pastes cannot be forwarded. |
+| **Gemini CLI as host** | Varies by version | Prefer explicit paths over paste |
+
+Agents should prefer user-supplied explicit paths (e.g., `~/Downloads/otter.jpeg`) over host-cache paths when durability across sessions matters.
+
+## Step 1: Vendor Selection
+
+1. Call `health()` on every registered provider in parallel.
+2. Classify:
+   - `healthy`: `ok: true`
+   - `unhealthy`: `ok: false` with a hint
+3. Decide based on `--vendor`:
+   - `auto`: continue with every `healthy` provider. If zero → exit 5.
+   - `all`: every provider must be healthy. Any missing → exit 5 naming the specific vendor.
+   - `<name>`: resolve the named provider. If unhealthy → exit 5 with its hint.
+4. Log `using: <vendor(s)>` to stderr before generation.
+
+## Step 2: Cost Guardrail
+
+1. Estimate cost as `sum(per_image_usd[vendor][model][quality] × count)` over all selected vendors.
+2. If `--dry-run`: print the plan (vendors, counts, outDir, cost) and exit 0.
+3. If estimate ≥ `cost_guardrail.estimate_threshold_usd` and not `--yes`/`OMA_IMAGE_YES=1`:
+   - Interactive terminal (stdin is a TTY): prompt user on stderr: `Estimated cost $X.XX. Proceed? (y/N)`. Decline → exit 1.
+   - Non-interactive (no TTY — agents, CI): no prompt is possible; exit 1 with a message naming `--yes`/`OMA_IMAGE_YES=1`. **Calling agents**: confirm the cost with the user in-conversation (`--dry-run` prints the estimate), then re-run with `-y`. Pass `-y` only when the run fits an existing budget authorization or newly approved spend.
+
+## Step 3: Cancellation Setup
+
+1. Install `SIGINT`/`SIGTERM` handlers that call `AbortController.abort()`.
+2. Thread the signal into every provider call via `GenerateInput.signal`.
+
+## Step 4: Dispatch
+
+- **Single vendor**: run `provider.generate(input)` sequentially.
+- **Multi-vendor (`all` or `auto` with 2+ healthy)**: `Promise.allSettled` across providers.
+- Providers with sub-strategies escalate internally and record every strategy attempt (ok/skipped/failed with reason).
+- Non-retryable errors (safety-refused, invalid-input) short-circuit the escalation chain.
+
+## Step 5: Write Artifacts
+
+1. Save each image to `outDir/<vendor>[-<model>]-<runShortid>[-<n>].<ext>` — the model segment is omitted when the vendor has no caller-visible model (`antigravity`), and `<ext>` reflects the magic-byte-sniffed format (`png`/`jpg`/`webp`/`gif`), not a fixed `.png`.
+2. Build `manifest.json` with schema version 1 (see `vendor-matrix.md` for fields).
+3. If `--no-prompt-in-manifest` is set, replace `prompt` with `prompt_sha256`.
+
+## Step 6: Report
+
+1. For each run, print a one-line status to stderr:
+   - `[oma image] <vendor> ok (Xs) -> <file>`
+   - `[oma image] <vendor> failed (<kind>): <reason>`
+2. Print manifest path.
+3. For `--output json`: write `{exitCode, manifestPath, runs}` to stdout as one JSON object.
+
+## Step 7: Exit Code Aggregation
+
+- Any successful run in parallel mode → exit 0 (failures still in manifest).
+- All failures → pick the most specific exit code:
+  - `safety-refused` → 2
+  - `invalid-input` → 4
+  - `auth-required` / `not-installed` → 5
+  - `timeout` → 6
+  - otherwise → 1
+
+## On Error
+
+| Situation | Action |
+|-----------|--------|
+| No vendors authenticated | Exit 5, print `Run: oma image doctor` |
+| Specific vendor unhealthy | Exit 5 with the vendor's setup guide (URL + env var + steps, rendered by `oma image doctor`) |
+| All sub-strategies failed for a provider | Exit 1 with last classified error; include `strategy_attempts` in manifest |
+| Timeout | Exit 6, manifest records `after_ms` |
+| Cancelled (Ctrl+C/SIGTERM) | In-flight calls abort, failures are recorded as `timeout`, the manifest is written, and the command exits 6 when no provider succeeded |

package/skills/oma-image/resources/invocation.md

@@ -0,0 +1,105 @@
+# Image Invocation Reference
+
+### Vendors
+
+This skill follows oh-my-agent's CLI-first concept: whenever a vendor's native CLI can drive generation (and return raw bytes), the subprocess path is preferred over direct API keys. Direct API is only used as a fallback for vendors whose CLI can't yet emit raw image bytes.
+
+| Vendor | Strategy | Models | Trigger |
+|--------|----------|--------|---------|
+| `codex` | CLI-first via `codex exec` over ChatGPT OAuth (`codex login`), built-in `image_gen` | `gpt-image-2` | Logged in via Codex CLI (no API key) |
+| `pollinations` | Direct HTTP via `gen.pollinations.ai/v1/images/generations` (free signup for key) | Free: `flux`, `zimage`. Credit-gated: `qwen-image`, `wan-image`, `gpt-image-2`, `klein`, `kontext`, `gptimage`, `gptimage-large` | `POLLINATIONS_API_KEY` set (free at https://enter.pollinations.ai). No native CLI exists. |
+| `antigravity` | `agy -p --dangerously-skip-permissions --add-dir <outDir>` — Antigravity's agentic CLI runs over the user's Gemini Code Assist subscription. agy writes raw bytes to absolute target paths we embed in the prompt; the provider sniffs format via magic bytes and renames the file extension to match. Model selection is opaque — agy picks internally, we never name a model. | (opaque — chosen by agy) | `agy` CLI installed + signed in. No API key, no per-image charge. |
+
+> The direct Gemini path (`gemini -p` stream, `generativelanguage.googleapis.com` API) is deprecated. `agy` is the supported Gemini image route — it's free with Gemini Code Assist and doesn't require billing on AI Studio.
+
+Since `agy` 1.2.16, native image requests use the built-in `image-generator` subagent. OMA asks agy to use that route when available, with `generate_image` as the fallback for older sessions, and to wait for completion before copying the generated image bytes to the requested paths.
+
+### Invocation
+
+#### Standalone
+
+```
+/oma-image a red apple on white background
+/oma-image --vendor all --size 1536x1024 jeju coastline at sunset
+/oma-image -n 3 --quality high --output-dir ./hero "minimalist dashboard hero illustration"
+```
+
+#### Shell CLI
+
+```
+oma image generate "<prompt>" [--vendor auto|codex|pollinations|antigravity|all] [-n 1..5] \
+                             [--size WxH|auto] \
+                             [--quality low|medium|high|auto] \
+                             [--model <name>] \
+                             [--output-dir <dir>] [--allow-external-output] \
+                             [-r <path>]... \
+                             [--timeout 180] [-y] [--no-prompt-in-manifest] \
+                             [--dry-run] [--output text|json]
+oma image doctor
+oma image vendor list
+```
+
+`--model <name>` overrides the vendor's default model for this run — e.g. `--vendor pollinations --model zimage`, or a credit-gated Pollinations model like `gpt-image-2`. It applies to every vendor in the run set, so combine it with an explicit `--vendor`; `antigravity` ignores it (agy picks its model internally).
+
+#### Reference-guided regeneration (`-r`, `--reference`)
+
+Attach up to 10 reference images (PNG/JPEG/GIF/WebP, ≤ 5MB each) to guide a **newly generated** image's style, subject identity, lighting, or composition. Repeatable or comma-separated. The output is a new generation, not a pixel-preserving edit of the input.
+
+```
+oma image generate -r ~/Downloads/otter.jpeg "same otter in dramatic lighting"
+oma image generate -r a.png -r b.png "blend these two styles"
+```
+
+Supported vendors:
+
+| Vendor | Support | How |
+|--------|---------|-----|
+| `codex` (gpt-image-2) | PASS | Passes `-i <path>` to `codex exec` |
+| `antigravity` | PASS | Refs copied to a per-run temp dir, `agy --add-dir <tmpdir>` grants access, paths inlined into the prompt |
+| `pollinations` | N/A | Rejected with exit code 4 when explicitly selected (requires URL hosting; see PR #2 roadmap). Under `--vendor auto`, reference-unsupported vendors are silently dropped from the run set instead. |
+
+**Paths**: absolute or relative to `$CWD`. Host CLIs usually expose attached images via:
+- **Claude Code**: `~/.claude/image-cache/<session>/N.png` (surfaced in system messages as `[Image: source: <path>]`)
+- **Antigravity**: workspace upload directory (exact path shown in IDE)
+- **Codex CLI as host**: user must pass the filesystem path explicitly; in-conversation attachments are not forwarded
+
+#### Agent Behavior: Auto-forward Attached References (MANDATORY)
+
+When ALL of the following are true, the calling agent MUST pass the attached image via `--reference <path>` automatically. Never describe the image in prose as a workaround.
+
+1. The user asks for a new generated variation (for example, "same subject in dramatic lighting", "make a new illustration in this style", or "regenerate this at a different angle").
+2. A host-surfaced attached image is visible to the agent (e.g. a Claude Code system message with `[Image: source: <path>]`, or an Antigravity workspace upload path, or an explicit filesystem path in the user's message).
+3. The selected vendor supports references (`codex` or `antigravity`).
+
+**Required action**: invoke `oma image generate --reference <absolute-path> --vendor <codex|antigravity> "<prompt>"`. If the user didn't specify a vendor, default to `codex` (CLI-first, widest availability). Do NOT:
+
+- Fall back to prose description ("I'll describe the otter's appearance...").
+- Ask the user to re-type or re-attach the path.
+- Claim the CLI doesn't support references without first running `oma image generate --help` to verify.
+
+**If the local CLI is outdated** (`--reference` is missing from `--help`): tell the user to run `oma update` once, then retry. Do not silently degrade to prose.
+
+**If the reference path is from Claude Code's `image-cache`**: note to the user that the path is session-scoped and suggest copying the file to a durable location if they want to reuse it later. Still proceed with the generation.
+
+**Unsupported edit requests**: Do not route requests such as "remove this object", "change only the background", "paint inside this mask", "keep every pixel except", "crop", "resize", or "convert this file" through `--reference`. They need pixel/mask editing or deterministic image processing, neither of which this CLI provides. Say whether the request can instead be phrased as a reference-guided regeneration; otherwise route to an appropriate image editor or processing tool.
+
+#### Shared Infrastructure (from other skills)
+
+Other skills call `oma image generate --output json` and parse the JSON manifest from stdout.
+
+### Output Layout
+
+Filenames follow `<vendor>[-<model>]-<shortid>[-<n>].<ext>` — the model segment is omitted for `antigravity` (opaque model), the extension reflects the sniffed format (JPEG is common), and `-<n>` appears only when `-n` > 1.
+
+```
+.agents/results/images/
+├── 20260424-143052-ab12cd/                    # single-vendor run
+│   ├── pollinations-flux-ab12cd.jpg
+│   │   (or codex-gpt-image-2-ab12cd.png, antigravity-ab12cd.jpg)
+│   └── manifest.json
+└── 20260424-143122-7z9kqw-compare/            # --vendor all run
+    ├── codex-gpt-image-2-7z9kqw.png
+    ├── pollinations-flux-7z9kqw.jpg
+    ├── antigravity-7z9kqw.jpg
+    └── manifest.json
+```

package/skills/oma-image/resources/prompt-tips.md

@@ -0,0 +1,71 @@
+# Prompt Tips
+
+Good prompts are specific about scene, subject, lighting, and style. `gpt-image-2` (codex), the Gemini-family "nano-banana" models (antigravity, chosen internally by agy), and flux/zimage (pollinations) all respond well to the same structural cues.
+
+## Structure
+
+```
+Scene/backdrop → Subject → Details → Constraints
+```
+
+Example: `minimalist product photography: single white ceramic coffee cup on dark marble surface, steam rising softly, dramatic side lighting`
+
+## Do's
+
+- **Lighting**: "warm golden hour side light", "overcast diffused", "backlit with rim light"
+- **Camera**: "shallow depth of field", "aerial view", "close-up macro", "35mm film grain"
+- **Style**: "photorealistic", "oil painting", "3D render", "concept art", "isometric vector"
+- **Mood**: "serene", "dramatic", "moody", "vibrant", "washed-out"
+- **Resolution cue**: "ultra detailed", "8K", "high fidelity"
+
+## Don'ts
+
+- Avoid vague prompts like "a nice picture"; both models produce generic output.
+- Don't stack contradicting styles ("photorealistic cel-shaded 3D").
+- Skip negative prompts; none of the routed models treats them as first-class.
+
+## Examples
+
+| Category | Prompt |
+|----------|--------|
+| Product | `Elegant perfume bottle on reflective black surface, studio lighting, luxury brand catalog style` |
+| Landscape | `Aerial drone shot of Jeju coastline, turquoise water meeting volcanic rock, golden hour` |
+| Food | `Overhead flat-lay of Korean bibimbap in stone pot, steam rising, vibrant vegetables, dark wood table` |
+| Architecture | `Modern minimalist house with floor-to-ceiling windows overlooking misty mountain valley` |
+| Portrait | `Professional headshot, soft natural window light, shallow depth of field, neutral background` |
+| UI Mockup | `iPhone 15 Pro mockup showing a fitness app dashboard, clean UI, dark mode, floating on gradient background` |
+| Concept | `Lone astronaut on crater edge of Mars, looking at Earth rising on the horizon, cinematic, volumetric dust` |
+
+## Vendor Nuances
+
+- **Codex (`gpt-image-2`)**: prefers slightly longer, descriptive prompts. Quality flag `high` noticeably sharpens fine detail but doubles generation time.
+- **Antigravity (Gemini-family "nano-banana" models, chosen internally by agy)**: robust on CJK-composed scenes ("hanok", "cherry blossom"); slightly stronger on illustrated/painterly styles. Driven via the `agy` CLI's agentic loop — output is JPEG by default even if `.png` is requested (the provider sniffs magic bytes and renames the extension accordingly).
+
+## Comparing Output
+
+`--vendor all` generates the same prompt on every registered provider and writes each result (PNG or JPEG, per provider) into a `…-compare/` folder with a single `manifest.json`. Use it for A/B picking when starting a new visual style.
+
+## External Prompt Libraries (agent reference only)
+
+When the **Clarification Protocol** (see `SKILL.md`) reaches the *amplify* step, these galleries provide structural references.
+
+| Source | Vendor match | Prompts | Categories |
+|--------|--------------|---------|-----------|
+| [awesome-gpt-image-2](https://github.com/YouMind-OpenLab/awesome-gpt-image-2) | `codex` (gpt-image-2) | ~100 | Profile/Avatar · Social Post · Infographic · YouTube Thumbnail · Comic/Storyboard · Poster/Flyer · App/Web Design |
+| [awesome-nano-banana-pro-prompts](https://github.com/YouMind-OpenLab/awesome-nano-banana-pro-prompts) | `antigravity` (nano-banana-pro) | 10,000+ | Same taxonomy; 16 localized READMEs (en, ko-KR, ja-JP, zh-TW, de-DE, …) |
+
+For `pollinations` (flux / zimage), patterns from either library transfer; use the subject framing, lighting cues, and style-keyword structure, not the literal wording.
+
+**How to use (agent-side):**
+
+1. Classify the user's intent into one of the 7 categories. If no match, fall back to the *Scene/backdrop → Subject → Details → Constraints* template at the top of this file.
+2. Fetch the relevant README section via `gh api`, e.g. Korean user + nano-banana:
+   ```
+   gh api repos/YouMind-OpenLab/awesome-nano-banana-pro-prompts/contents/README_ko-KR.md \
+     --jq .content | base64 -d | less
+   ```
+   Scan headings like `### No. N: <Category> - <Title>` to locate 1–2 analogous entries.
+3. **Internalize the pattern, do not reproduce the text.** Extract lighting / framing / camera / style-keyword choices.
+4. Compose your amplified prompt by applying that pattern to the user's subject in your own wording. Preserve the requested subject and constraints; proceed under existing generation authorization unless a material decision remains.
+
+**Fallback:** If no category matches, use the structural template at the top of this file.