@bgicli/bgicli 2.2.8 → 2.2.10

package/data/skills/openai-sentry/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: "sentry"
+description: "Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`."
+---
+
+
+# Sentry (Read-only Observability)
+
+## Quick start
+
+- If not already authenticated, ask the user to provide a valid `SENTRY_AUTH_TOKEN` (read-only scopes such as `project:read`, `event:read`) or to log in and create one before running commands.
+- Set `SENTRY_AUTH_TOKEN` as an env var.
+- Optional defaults: `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_BASE_URL`.
+- Defaults: org/project `{your-org}`/`{your-project}`, time range `24h`, environment `prod`, limit 20 (max 50).
+- Always call the Sentry API (no heuristics, no caching).
+
+If the token is missing, give the user these steps:
+1. Create a Sentry auth token: https://sentry.io/settings/account/api/auth-tokens/
+2. Create a token with read-only scopes such as `project:read`, `event:read`, and `org:read`.
+3. Set `SENTRY_AUTH_TOKEN` as an environment variable in their system.
+4. Offer to guide them through setting the environment variable for their OS/shell if needed.
+- Never ask the user to paste the full token in chat. Ask them to set it locally and confirm when ready.
+
+## Core tasks (use bundled script)
+
+Use `scripts/sentry_api.py` for deterministic API calls. It handles pagination and retries once on transient errors.
+
+## Skill path (set once)
+
+```bash
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export SENTRY_API="$CODEX_HOME/skills/sentry/scripts/sentry_api.py"
+```
+
+User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
+
+### 1) List issues (ordered by most recent)
+
+```bash
+python3 "$SENTRY_API" \
+  list-issues \
+  --org {your-org} \
+  --project {your-project} \
+  --environment prod \
+  --time-range 24h \
+  --limit 20 \
+  --query "is:unresolved"
+```
+
+### 2) Resolve an issue short ID to issue ID
+
+```bash
+python3 "$SENTRY_API" \
+  list-issues \
+  --org {your-org} \
+  --project {your-project} \
+  --query "ABC-123" \
+  --limit 1
+```
+
+Use the returned `id` for issue detail or events.
+
+### 3) Issue detail
+
+```bash
+python3 "$SENTRY_API" \
+  issue-detail \
+  1234567890
+```
+
+### 4) Issue events
+
+```bash
+python3 "$SENTRY_API" \
+  issue-events \
+  1234567890 \
+  --limit 20
+```
+
+### 5) Event detail (no stack traces by default)
+
+```bash
+python3 "$SENTRY_API" \
+  event-detail \
+  --org {your-org} \
+  --project {your-project} \
+  abcdef1234567890
+```
+
+## API requirements
+
+Always use these endpoints (GET only):
+
+- List issues: `/api/0/projects/{org_slug}/{project_slug}/issues/`
+- Issue detail: `/api/0/issues/{issue_id}/`
+- Events for issue: `/api/0/issues/{issue_id}/events/`
+- Event detail: `/api/0/projects/{org_slug}/{project_slug}/events/{event_id}/`
+
+## Inputs and defaults
+
+- `org_slug`, `project_slug`: default to `{your-org}`/`{your-project}` (avoid non-prod orgs).
+- `time_range`: default `24h` (pass as `statsPeriod`).
+- `environment`: default `prod`.
+- `limit`: default 20, max 50 (paginate until limit reached).
+- `search_query`: optional `query` parameter.
+- `issue_short_id`: resolve via list-issues query first.
+
+## Output formatting rules
+
+- Issue list: show title, short_id, status, first_seen, last_seen, count, environments, top_tags; order by most recent.
+- Event detail: include culprit, timestamp, environment, release, url.
+- If no results, state explicitly.
+- Redact PII in output (emails, IPs). Do not print raw stack traces.
+- Never echo auth tokens.
+
+## Golden test inputs
+
+- Org: `{your-org}`
+- Project: `{your-project}`
+- Issue short ID: `{ABC-123}`
+
+Example prompt: “List the top 10 open issues for prod in the last 24h.”
+Expected: ordered list with titles, short IDs, counts, last seen.

package/data/skills/openai-sora/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: "sora"
+description: "Use when the user asks to generate, edit, extend, poll, list, download, or delete Sora videos, create reusable non-human Sora character references, or run local multi-video queues via the bundled CLI (`scripts/sora.py`); includes requests like: (i) generate AI video, (ii) edit this Sora clip, (iii) extend this video, (iv) create a character reference, (v) download video/thumbnail/spritesheet, and (vi) Sora batch planning; requires `OPENAI_API_KEY` and Sora API access."
+---
+
+
+# Sora Video Generation Skill
+
+Creates or manages Sora video jobs for the current project (product demos, marketing spots, cinematic shots, social clips, UI mocks). Defaults to `sora-2` with structured prompt augmentation and prefers the bundled CLI for deterministic runs. Note: `$sora` is a skill tag in prompts, not a shell command.
+
+## When to use
+- Generate a new video clip from a prompt
+- Create a reusable character reference from a short non-human source clip
+- Edit an existing generated video with a targeted prompt change
+- Extend a completed video with a continuation prompt
+- Poll status, list jobs, or download assets (video/thumbnail/spritesheet)
+- Run a local multi-job queue now, or plan a true Batch API submission for offline rendering
+
+## Decision tree
+- If the user has a short non-human reference clip they want to reuse across shots → `create-character`
+- If the user has a completed video and wants the next beat/continuation → `extend`
+- If the user has a completed video and wants a targeted change while preserving the shot → `edit`
+- If the user has a video id and wants status or assets → `status`, `poll`, or `download`
+- If the user needs many renders immediately inside Codex → `create-batch` (local fan-out, not the Batch API)
+- If the user needs many renders for offline processing or a studio pipeline → use the official Batch API flow described in `references/video-api.md`
+- Otherwise → `create` (or `create-and-poll` if they need a ready asset in one step)
+
+## Workflow
+1. Decide intent: create vs create-character vs edit vs extend vs status/download vs local queue vs official Batch API.
+2. Collect inputs: prompt, model, size, seconds, any image reference, and any character IDs.
+3. Prefer CLI augmentation flags (`--use-case`, `--scene`, `--camera`, etc.) instead of hand-writing a long structured prompt. If you already have a structured prompt file, pass `--no-augment`.
+4. Run the bundled CLI (`scripts/sora.py`) with sensible defaults. For long prompts, prefer `--prompt-file` to avoid shell-escaping issues.
+5. For async jobs, poll until terminal status (or use `create-and-poll`).
+6. Download assets (video/thumbnail/spritesheet) and save them locally before URLs expire.
+7. If the user wants continuity across many shots, create character assets first, then reference them in later `create` calls.
+8. If the user wants to iterate on a completed shot, prefer `edit`; if they want the shot to continue in time, prefer `extend`.
+9. Use one targeted change per iteration.
+
+## Authentication
+- `OPENAI_API_KEY` must be set for live API calls.
+
+If the key is missing, give the user these steps:
+1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
+2. Set `OPENAI_API_KEY` as an environment variable in their system.
+3. Offer to guide them through setting the environment variable for their OS/shell if needed.
+- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
+
+## Defaults & rules
+- Default model: `sora-2` (use `sora-2-pro` for higher fidelity).
+- Default size: `1280x720`.
+- Default seconds: `4` (allowed: `"4"`, `"8"`, `"12"`, `"16"`, `"20"`).
+- Always set size and seconds via API params; prose will not change them.
+- `sora-2-pro` is required for `1920x1080` and `1080x1920`.
+- Use up to two characters per generation.
+- Use the OpenAI Python SDK (`openai` package). If high-level SDK helpers lag the latest Sora guide, use low-level `client.post/get/delete` inside the official SDK rather than standalone HTTP code.
+- Require `OPENAI_API_KEY` before any live API call.
+- If uv cache permissions fail, set `UV_CACHE_DIR=/tmp/uv-cache`.
+- Input reference images must be jpg/png/webp and should match target size.
+- JSON `input_reference` objects use either `file_id` or `image_url`; uploaded file paths use multipart.
+- Download URLs expire after about 1 hour; copy assets to your own storage.
+- Batch-generated videos remain downloadable for up to 24 hours after the batch completes.
+- `create-batch` in `scripts/sora.py` is a local concurrent queue, not the official Batch API.
+- Prefer the bundled CLI and **never modify** `scripts/sora.py` unless the user asks.
+- Sora can generate audio; if a user requests voiceover/audio, specify it explicitly in the `Audio:` and `Dialogue:` lines and keep it short.
+
+## API limitations
+- Models are limited to `sora-2` and `sora-2-pro`.
+- API access to Sora models requires an organization-verified account.
+- Duration must be set via the `seconds` parameter and currently supports `4`, `8`, `12`, `16`, and `20`.
+- Character uploads currently work best with short `2`-`4` second non-human MP4s in `16:9` or `9:16`, at `720p`-`1080p`.
+- Extensions can add up to `20` seconds each, up to six times per source video, for a maximum total length of `120` seconds.
+- Extensions currently do not support characters or image references.
+- This skill supports editing existing generated videos by ID.
+- The official Batch API currently supports `POST /v1/videos` only, with JSON bodies rather than multipart uploads.
+- Output sizes are limited by model (see `references/video-api.md` for the supported sizes).
+- Video creation is async; you must poll for completion before downloading.
+- Rate limits apply by usage tier (do not list specific limits).
+- Content restrictions are enforced by the API (see Guardrails below).
+
+## Guardrails (must enforce)
+- Only content suitable for audiences under 18.
+- No copyrighted characters or copyrighted music.
+- No real people (including public figures).
+- Input images with human faces are rejected.
+- Character uploads in this skill are for non-human subjects only.
+
+## Prompt augmentation
+Reformat prompts into a structured, production-oriented spec. Only make implicit details explicit; do not invent new creative requirements.
+
+Template (include only relevant lines):
+```
+Use case: <where the clip will be used>
+Primary request: <user's main prompt>
+Scene/background: <location, time of day, atmosphere>
+Subject: <main subject>
+Action: <single clear action>
+Camera: <shot type, angle, motion>
+Lighting/mood: <lighting + mood>
+Color palette: <3-5 color anchors>
+Style/format: <film/animation/format cues>
+Timing/beats: <counts or beats>
+Audio: <ambient cue / music / voiceover if requested>
+Text (verbatim): "<exact text>"
+Dialogue:
+<dialogue>
+- Speaker: "Short line."
+</dialogue>
+Constraints: <must keep/must avoid>
+Avoid: <negative constraints>
+```
+
+Augmentation rules:
+- Keep it short; add only details the user already implied or provided elsewhere.
+- For edits, explicitly list invariants ("same shot, change only X").
+- For character-based shots, mention the character name verbatim in the prompt.
+- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
+- If you pass a structured prompt file to the CLI, add `--no-augment` to avoid the tool re-wrapping it.
+
+## Examples
+
+### Generation example (single shot)
+```
+Use case: product teaser
+Primary request: a close-up of a matte black camera on a pedestal
+Action: slow 30-degree orbit over 4 seconds
+Camera: 85mm, shallow depth of field, gentle handheld drift
+Lighting/mood: soft key light, subtle rim, premium studio feel
+Constraints: no logos, no text
+```
+
+### Edit example (invariants)
+```
+Primary request: same shot and framing, switch palette to teal/sand/rust with warmer backlight
+Constraints: keep the subject and camera move unchanged
+```
+
+### Character consistency example
+```
+Primary request: Mossy, a moss-covered teapot mascot, hurries through a lantern-lit market at dusk
+Camera: cinematic tracking shot, 35mm, shoulder height
+Lighting/mood: warm dusk practicals, soft haze
+Constraints: keep Mossy’s silhouette and moss texture consistent across the shot
+```
+
+## Prompting best practices (short list)
+- One main action + one camera move per shot.
+- Use counts or beats for timing ("two steps, pause, turn").
+- Keep text short and the camera locked-off for UI or on-screen text.
+- Add a brief avoid line when artifacts appear (flicker, jitter, fast motion).
+- Shorter prompts are more creative; longer prompts are more controlled.
+- Put dialogue in a dedicated block; keep lines short for 4-8s clips.
+- Mention character names verbatim when using uploaded character IDs.
+- State invariants explicitly for edits (same shot, same camera move).
+- Prefer `edit` for targeted changes and `extend` for timeline continuation.
+- Iterate with single-change follow-ups to preserve continuity.
+
+## Guidance by asset type
+Use these modules when the request is for a specific artifact. They provide targeted templates and defaults.
+- Cinematic shots: `references/cinematic-shots.md`
+- Social ads: `references/social-ads.md`
+
+## CLI + environment notes
+- CLI commands + examples: `references/cli.md`
+- API parameter quick reference: `references/video-api.md`
+- Prompting guidance: `references/prompting.md`
+- Sample prompts: `references/sample-prompts.md`
+- Troubleshooting: `references/troubleshooting.md`
+- Network/sandbox tips: `references/codex-network.md`
+
+## Reference map
+- **`references/cli.md`**: how to run create/edit/extend/create-character/poll/download/local-queue flows via `scripts/sora.py`.
+- **`references/video-api.md`**: API-level knobs (models, sizes, duration, characters, edits, extensions, official Batch API).
+- **`references/prompting.md`**: prompt structure, character continuity, editing, and extension guidance.
+- **`references/sample-prompts.md`**: copy/paste prompt recipes (examples only; no extra theory).
+- **`references/cinematic-shots.md`**: templates for filmic shots.
+- **`references/social-ads.md`**: templates for short social ad beats.
+- **`references/troubleshooting.md`**: common errors and fixes.
+- **`references/codex-network.md`**: network/approval troubleshooting.

package/data/skills/openai-speech/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: "speech"
+description: "Use when the user asks for text-to-speech narration or voiceover, accessibility reads, audio prompts, or batch speech generation via the OpenAI Audio API; run the bundled CLI (`scripts/text_to_speech.py`) with built-in voices and require `OPENAI_API_KEY` for live calls. Custom voice creation is out of scope."
+---
+
+
+# Speech Generation Skill
+
+Generate spoken audio for the current project (narration, product demo voiceover, IVR prompts, accessibility reads). Defaults to `gpt-4o-mini-tts-2025-12-15` and built-in voices, and prefers the bundled CLI for deterministic, reproducible runs.
+
+## When to use
+- Generate a single spoken clip from text
+- Generate a batch of prompts (many lines, many files)
+
+## Decision tree (single vs batch)
+- If the user provides multiple lines/prompts or wants many outputs -> **batch**
+- Else -> **single**
+
+## Workflow
+1. Decide intent: single vs batch (see decision tree above).
+2. Collect inputs up front: exact text (verbatim), desired voice, delivery style, format, and any constraints.
+3. If batch: write a temporary JSONL under tmp/ (one job per line), run once, then delete the JSONL.
+4. Augment instructions into a short labeled spec without rewriting the input text.
+5. Run the bundled CLI (`scripts/text_to_speech.py`) with sensible defaults (see references/cli.md).
+6. For important clips, validate: intelligibility, pacing, pronunciation, and adherence to constraints.
+7. Iterate with a single targeted change (voice, speed, or instructions), then re-check.
+8. Save/return final outputs and note the final text + instructions + flags used.
+
+## Temp and output conventions
+- Use `tmp/speech/` for intermediate files (for example JSONL batches); delete when done.
+- Write final artifacts under `output/speech/` when working in this repo.
+- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.
+
+## Dependencies (install if missing)
+Prefer `uv` for dependency management.
+
+Python packages:
+```
+uv pip install openai
+```
+If `uv` is unavailable:
+```
+python3 -m pip install openai
+```
+
+## Environment
+- `OPENAI_API_KEY` must be set for live API calls.
+
+If the key is missing, give the user these steps:
+1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
+2. Set `OPENAI_API_KEY` as an environment variable in their system.
+3. Offer to guide them through setting the environment variable for their OS/shell if needed.
+- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
+
+If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
+
+## Defaults & rules
+- Use `gpt-4o-mini-tts-2025-12-15` unless the user requests another model.
+- Default voice: `cedar`. If the user wants a brighter tone, prefer `marin`.
+- Built-in voices only. Custom voices are out of scope for this skill.
+- `instructions` are supported for GPT-4o mini TTS models, but not for `tts-1` or `tts-1-hd`.
+- Input length must be <= 4096 characters per request. Split longer text into chunks.
+- Enforce 50 requests/minute. The CLI caps `--rpm` at 50.
+- Require `OPENAI_API_KEY` before any live API call.
+- Provide a clear disclosure to end users that the voice is AI-generated.
+- Use the OpenAI Python SDK (`openai` package) for all API calls; do not use raw HTTP.
+- Prefer the bundled CLI (`scripts/text_to_speech.py`) over writing new one-off scripts.
+- Never modify `scripts/text_to_speech.py`. If something is missing, ask the user before doing anything else.
+
+## Instruction augmentation
+Reformat user direction into a short, labeled spec. Only make implicit details explicit; do not invent new requirements.
+
+Quick clarification (augmentation vs invention):
+- If the user says "narration for a demo", you may add implied delivery constraints (clear, steady pacing, friendly tone).
+- Do not introduce a new persona, accent, or emotional style the user did not request.
+
+Template (include only relevant lines):
+```
+Voice Affect: <overall character and texture of the voice>
+Tone: <attitude, formality, warmth>
+Pacing: <slow, steady, brisk>
+Emotion: <key emotions to convey>
+Pronunciation: <words to enunciate or emphasize>
+Pauses: <where to add intentional pauses>
+Emphasis: <key words or phrases to stress>
+Delivery: <cadence or rhythm notes>
+```
+
+Augmentation rules:
+- Keep it short; add only details the user already implied or provided elsewhere.
+- Do not rewrite the input text.
+- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
+
+## Examples
+
+### Single example (narration)
+```
+Input text: "Welcome to the demo. Today we'll show how it works."
+Instructions:
+Voice Affect: Warm and composed.
+Tone: Friendly and confident.
+Pacing: Steady and moderate.
+Emphasis: Stress "demo" and "show".
+```
+
+### Batch example (IVR prompts)
+```
+{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
+{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: Clear and neutral. Pacing: Slow.","response_format":"wav"}
+```
+
+## Instructioning best practices (short list)
+- Structure directions as: affect -> tone -> pacing -> emotion -> pronunciation/pauses -> emphasis.
+- Keep 4 to 8 short lines; avoid conflicting guidance.
+- For names/acronyms, add pronunciation hints (e.g., "enunciate A-I") or supply a phonetic spelling in the text.
+- For edits/iterations, repeat invariants (e.g., "keep pacing steady") to reduce drift.
+- Iterate with single-change follow-ups.
+
+More principles: `references/prompting.md`. Copy/paste specs: `references/sample-prompts.md`.
+
+## Guidance by use case
+Use these modules when the request is for a specific delivery style. They provide targeted defaults and templates.
+- Narration / explainer: `references/narration.md`
+- Product demo / voiceover: `references/voiceover.md`
+- IVR / phone prompts: `references/ivr.md`
+- Accessibility reads: `references/accessibility.md`
+
+## CLI + environment notes
+- CLI commands + examples: `references/cli.md`
+- API parameter quick reference: `references/audio-api.md`
+- Instruction patterns + examples: `references/voice-directions.md`
+- If network approvals / sandbox settings are getting in the way: `references/codex-network.md`
+
+## Reference map
+- **`references/cli.md`**: how to run speech generation/batches via `scripts/text_to_speech.py` (commands, flags, recipes).
+- **`references/audio-api.md`**: API parameters, limits, voice list.
+- **`references/voice-directions.md`**: instruction patterns and examples.
+- **`references/prompting.md`**: instruction best practices (structure, constraints, iteration patterns).
+- **`references/sample-prompts.md`**: copy/paste instruction recipes (examples only; no extra theory).
+- **`references/narration.md`**: templates + defaults for narration and explainers.
+- **`references/voiceover.md`**: templates + defaults for product demo voiceovers.
+- **`references/ivr.md`**: templates + defaults for IVR/phone prompts.
+- **`references/accessibility.md`**: templates + defaults for accessibility reads.
+- **`references/codex-network.md`**: environment/sandbox/network-approval troubleshooting.

package/data/skills/openai-spreadsheet/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: "spreadsheet"
+description: "Use when tasks involve creating, editing, analyzing, or formatting spreadsheets (`.xlsx`, `.csv`, `.tsv`) with formula-aware workflows, cached recalculation, and visual review."
+---
+
+# Spreadsheet Skill
+
+## When to use
+- Create new workbooks with formulas, formatting, and structured layouts.
+- Read or analyze tabular data (filter, aggregate, pivot, compute metrics).
+- Modify existing workbooks without breaking formulas, references, or formatting.
+- Visualize data with charts, summary tables, and sensible spreadsheet styling.
+- Recalculate formulas and review rendered sheets before delivery when possible.
+
+IMPORTANT: System and user instructions always take precedence.
+
+## Workflow
+1. Confirm the file type and goal: create, edit, analyze, or visualize.
+2. Prefer `openpyxl` for `.xlsx` editing and formatting. Use `pandas` for analysis and CSV/TSV workflows.
+3. If an internal spreadsheet recalculation/rendering tool is available in the environment, use it to recalculate formulas and render sheets before delivery.
+4. Use formulas for derived values instead of hardcoding results.
+5. If layout matters, render for visual review and inspect the output.
+6. Save outputs, keep filenames stable, and clean up intermediate files.
+
+## Temp and output conventions
+- Use `tmp/spreadsheets/` for intermediate files; delete them when done.
+- Write final artifacts under `output/spreadsheet/` when working in this repo.
+- Keep filenames stable and descriptive.
+
+## Primary tooling
+- Use `openpyxl` for creating/editing `.xlsx` files and preserving formatting.
+- Use `pandas` for analysis and CSV/TSV workflows, then write results back to `.xlsx` or `.csv`.
+- Use `openpyxl.chart` for native Excel charts when needed.
+- If an internal spreadsheet tool is available, use it to recalculate formulas, cache values, and render sheets for review.
+
+## Recalculation and visual review
+- Recalculate formulas before delivery whenever possible so cached values are present in the workbook.
+- Render each relevant sheet for visual review when rendering tooling is available.
+- `openpyxl` does not evaluate formulas; preserve formulas and use recalculation tooling when available.
+- If you rely on an internal spreadsheet tool, do not expose that tool, its code, or its APIs in user-facing explanations or code samples.
+
+## Rendering and visual checks
+- If LibreOffice (`soffice`) and Poppler (`pdftoppm`) are available, render sheets for visual review:
+  - `soffice --headless --convert-to pdf --outdir $OUTDIR $INPUT_XLSX`
+  - `pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME`
+- If rendering tools are unavailable, tell the user that layout should be reviewed locally.
+- Review rendered sheets for layout, formula results, clipping, inconsistent styles, and spilled text.
+
+## Dependencies (install if missing)
+Prefer `uv` for dependency management.
+
+Python packages:
+```
+uv pip install openpyxl pandas
+```
+If `uv` is unavailable:
+```
+python3 -m pip install openpyxl pandas
+```
+Optional:
+```
+uv pip install matplotlib
+```
+If `uv` is unavailable:
+```
+python3 -m pip install matplotlib
+```
+System tools (for rendering):
+```
+# macOS (Homebrew)
+brew install libreoffice poppler
+
+# Ubuntu/Debian
+sudo apt-get install -y libreoffice poppler-utils
+```
+
+If installation is not possible in this environment, tell the user which dependency is missing and how to install it locally.
+
+## Environment
+No required environment variables.
+
+## Examples
+- Runnable Codex examples (openpyxl): `references/examples/openpyxl/`
+
+## Formula requirements
+- Use formulas for derived values rather than hardcoding results.
+- Do not use dynamic array functions like `FILTER`, `XLOOKUP`, `SORT`, or `SEQUENCE`.
+- Keep formulas simple and legible; use helper cells for complex logic.
+- Avoid volatile functions like `INDIRECT` and `OFFSET` unless required.
+- Prefer cell references over magic numbers (for example, `=H6*(1+$B$3)` instead of `=H6*1.04`).
+- Use absolute (`$B$4`) or relative (`B4`) references carefully so copied formulas behave correctly.
+- If you need literal text that starts with `=`, prefix it with a single quote.
+- Guard against `#REF!`, `#DIV/0!`, `#VALUE!`, `#N/A`, and `#NAME?` errors.
+- Check for off-by-one mistakes, circular references, and incorrect ranges.
+
+## Citation requirements
+- Cite sources inside the spreadsheet using plain-text URLs.
+- For financial models, cite model inputs in cell comments.
+- For tabular data sourced externally, add a source column when each row represents a separate item.
+
+## Formatting requirements (existing formatted spreadsheets)
+- Render and inspect a provided spreadsheet before modifying it when possible.
+- Preserve existing formatting and style exactly.
+- Match styles for any newly filled cells that were previously blank.
+- Never overwrite established formatting unless the user explicitly asks for a redesign.
+
+## Formatting requirements (new or unstyled spreadsheets)
+- Use appropriate number and date formats.
+- Dates should render as dates, not plain numbers.
+- Percentages should usually default to one decimal place unless the data calls for something else.
+- Currencies should use the appropriate currency format.
+- Headers should be visually distinct from raw inputs and derived cells.
+- Use fill colors, borders, spacing, and merged cells sparingly and intentionally.
+- Set row heights and column widths so content is readable without excessive whitespace.
+- Do not apply borders around every filled cell.
+- Group related calculations and make totals simple sums of the cells above them.
+- Add whitespace to separate sections.
+- Ensure text does not spill into adjacent cells.
+- Avoid unsupported spreadsheet data-table features such as `=TABLE`.
+
+## Color conventions (if no style guidance)
+- Blue: user input
+- Black: formulas and derived values
+- Green: linked or imported values
+- Gray: static constants
+- Orange: review or caution
+- Light red: error or flag
+- Purple: control or logic
+- Teal: visualization anchors and KPI highlights
+
+## Finance-specific requirements
+- Format zeros as `-`.
+- Negative numbers should be red and in parentheses.
+- Format multiples as `5.2x`.
+- Always specify units in headers (for example, `Revenue ($mm)`).
+- Cite sources for all raw inputs in cell comments.
+- For new financial models with no user-specified style, use blue text for hardcoded inputs, black for formulas, green for internal workbook links, red for external links, and yellow fill for key assumptions that need attention.
+
+## Investment banking layouts
+If the spreadsheet is an IB-style model (LBO, DCF, 3-statement, valuation):
+- Totals should sum the range directly above.
+- Hide gridlines and use horizontal borders above totals across relevant columns.
+- Section headers should be merged cells with dark fill and white text.
+- Column labels for numeric data should be right-aligned; row labels should be left-aligned.
+- Indent submetrics under their parent line items.

package/data/skills/openai-transcribe/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: "transcribe"
+description: "Transcribe audio files to text with optional diarization and known-speaker hints. Use when a user asks to transcribe speech from audio/video, extract text from recordings, or label speakers in interviews or meetings."
+---
+
+
+# Audio Transcribe
+
+Transcribe audio using OpenAI, with optional speaker diarization when requested. Prefer the bundled CLI for deterministic, repeatable runs.
+
+## Workflow
+1. Collect inputs: audio file path(s), desired response format (text/json/diarized_json), optional language hint, and any known speaker references.
+2. Verify `OPENAI_API_KEY` is set. If missing, ask the user to set it locally (do not ask them to paste the key).
+3. Run the bundled `transcribe_diarize.py` CLI with sensible defaults (fast text transcription).
+4. Validate the output: transcription quality, speaker labels, and segment boundaries; iterate with a single targeted change if needed.
+5. Save outputs under `output/transcribe/` when working in this repo.
+
+## Decision rules
+- Default to `gpt-4o-mini-transcribe` with `--response-format text` for fast transcription.
+- If the user wants speaker labels or diarization, use `--model gpt-4o-transcribe-diarize --response-format diarized_json`.
+- If audio is longer than ~30 seconds, keep `--chunking-strategy auto`.
+- Prompting is not supported for `gpt-4o-transcribe-diarize`.
+
+## Output conventions
+- Use `output/transcribe/<job-id>/` for evaluation runs.
+- Use `--out-dir` for multiple files to avoid overwriting.
+
+## Dependencies (install if missing)
+Prefer `uv` for dependency management.
+
+```
+uv pip install openai
+```
+If `uv` is unavailable:
+```
+python3 -m pip install openai
+```
+
+## Environment
+- `OPENAI_API_KEY` must be set for live API calls.
+- If the key is missing, instruct the user to create one in the OpenAI platform UI and export it in their shell.
+- Never ask the user to paste the full key in chat.
+
+## Skill path (set once)
+
+```bash
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export TRANSCRIBE_CLI="$CODEX_HOME/skills/transcribe/scripts/transcribe_diarize.py"
+```
+
+User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
+
+## CLI quick start
+Single file (fast text default):
+```
+python3 "$TRANSCRIBE_CLI" \
+  path/to/audio.wav \
+  --out transcript.txt
+```
+
+Diarization with known speakers (up to 4):
+```
+python3 "$TRANSCRIBE_CLI" \
+  meeting.m4a \
+  --model gpt-4o-transcribe-diarize \
+  --known-speaker "Alice=refs/alice.wav" \
+  --known-speaker "Bob=refs/bob.wav" \
+  --response-format diarized_json \
+  --out-dir output/transcribe/meeting
+```
+
+Plain text output (explicit):
+```
+python3 "$TRANSCRIBE_CLI" \
+  interview.mp3 \
+  --response-format text \
+  --out interview.txt
+```
+
+## Reference map
+- `references/api.md`: supported formats, limits, response formats, and known-speaker notes.