@laitszkin/apollo-toolkit 2.0.0

package/specs-to-project-docs/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: specs-to-project-docs
+description: Turn a project's accumulated spec files into standardized project documentation and README content. Use when users want to consolidate `spec.md`/`tasks.md`/`checklist.md` files into maintainable docs covering installation and deployment, configuration, external service setup, architecture, feature introductions, and developer onboarding context.
+---
+
+# Specs To Project Docs
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
+- Execution: Inventory all relevant specs first, reconcile them with the current repository, then generate or update standardized docs from the provided templates.
+- Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the same standard structure, and call out unknowns explicitly instead of inventing missing setup details.
+- Output: Produce a concise `README.md` plus a categorized project-doc set, then remove superseded spec files after the conversion is complete.
+
+## Goal
+
+Convert scattered planning artifacts into stable, standardized project documentation that helps operators and developers quickly open the exact document they need for setup, configuration, architecture, feature understanding, or development onboarding.
+
+## Workflow
+
+### 1) Inventory documentation sources
+
+- Find all relevant planning files such as `docs/plans/**/spec.md`, `tasks.md`, and `checklist.md`.
+- Read existing `README*`, deployment scripts, manifests, env examples, infra files, CI configs, and representative source modules.
+- Build a source map for setup commands, environments, external services, module boundaries, and implemented features.
+
+### 2) Reconcile spec claims with the current repository
+
+- Treat source priority as:
+  1. current code, config, and deployment files
+  2. current tests and automation scripts
+  3. recent specs that still match the implementation
+  4. existing docs
+- When specs disagree with the codebase, keep the codebase truth and note the mismatch while updating docs.
+- Merge repeated or overlapping feature descriptions into one stable capability summary.
+
+### 3) Standardize existing project docs into categorized outputs
+
+- If the project already has `README.md`, handbooks, setup guides, architecture docs, or runbooks, rewrite or reorganize them so they follow this skill's standardized split-document structure instead of leaving mixed formats in place.
+- Use `references/templates/readme.md` for the concise project introduction.
+- Use `references/templates/docs-index.md` for the project documentation index and reference list.
+- Use the category templates to split content by topic so readers can open only what they need.
+- Default target outputs:
+  - `README.md`
+  - `docs/README.md`
+  - `docs/getting-started.md`
+  - `docs/configuration.md`
+  - `docs/architecture.md`
+  - `docs/features.md`
+  - `docs/developer-guide.md`
+- If the repository already uses different doc paths, preserve the established locations only when the resulting documents still match the same categorized sections and remain easy to maintain.
+
+### 4) Fill the required documentation sections
+
+Ensure the split project docs cover all of the following:
+- how to install and deploy the project
+- how to configure the project
+- external services, required credentials, and API key acquisition tutorials when applicable
+- project architecture and key module boundaries
+- project feature introductions and user-facing flows
+- project context developers should understand before making changes
+
+### 5) Write the configuration and external-service guidance carefully
+
+- List each env var, config file, or secret only when supported by repository evidence.
+- For every external service, document:
+  - why the service is needed
+  - which local config or env vars are required
+  - how to create or locate the credential
+  - where to place the credential locally or in deployment
+  - any safe-development notes such as sandbox/test-mode usage
+- If the repository does not show how to obtain a credential, say so explicitly and point to the service's official setup page rather than guessing steps.
+
+### 6) Keep README short and the doc set navigable
+
+- `README.md` should stay short: project intro, quick install/deploy, major features, and key doc links.
+- `docs/README.md` should act as the reference list for the categorized docs.
+- Each category doc should stay focused on one topic instead of acting like another monolithic handbook.
+- Remove template placeholders and stale planning language before finishing.
+
+### 7) Remove superseded spec files after successful conversion
+
+- After the standardized project docs are complete and verified, delete the old source spec files that were converted.
+- Remove the full spec directory when it only exists to hold the consumed `spec.md`, `tasks.md`, and `checklist.md` files.
+- Do not delete any spec file that is still actively needed for unfinished implementation work or explicit archival requirements.
+- If a repository needs historical retention, move the source specs into a clearly marked archive path instead of leaving them mixed with active docs.
+
+## Working Rules
+
+- Prefer the user's language unless the repository clearly uses another documentation language.
+- Keep examples executable and commands copyable.
+- Do not copy speculative roadmap items from specs into the main docs as if they already exist.
+- When a section cannot be completed from evidence, keep an explicit `Unknown` or `TBD (missing repository evidence)` marker.
+- The final repository state should not keep both standardized docs and redundant active spec files for the same completed scope.
+
+## References
+
+- `references/templates/readme.md`: concise project overview template.
+- `references/templates/docs-index.md`: categorized project-doc index and reference list template.
+- `references/templates/getting-started.md`: installation and deployment template.
+- `references/templates/configuration.md`: configuration and external-service template.
+- `references/templates/architecture.md`: architecture template.
+- `references/templates/features.md`: feature guide template.
+- `references/templates/developer-guide.md`: development onboarding template.

package/specs-to-project-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "specs-to-project-docs"
+  short_description: "Convert project specs into standardized categorized project docs"
+  default_prompt: "Use $specs-to-project-docs to inventory the project's spec.md/tasks.md/checklist.md files, reconcile them with the current repository, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then remove or archive superseded source specs after successful conversion."

package/specs-to-project-docs/references/templates/architecture.md

@@ -0,0 +1,29 @@
+# Architecture
+
+## 1. High-Level Structure
+
+- Entry points: [CLI/server/app/worker]
+- Major modules: [module names and responsibilities]
+- Data flow summary: [request/event/job flow]
+- Integration boundaries: [DB/API/queue/filesystem]
+
+## 2. Directory Guide
+
+| Path | Responsibility |
+| --- | --- |
+| `[path]` | [What lives here] |
+| `[path]` | [What lives here] |
+
+## 3. Key Flows
+
+### [Flow Name]
+- Trigger: [route/command/job]
+- Main steps: [step summary]
+- Dependencies: [internal/external]
+- Failure boundaries: [where failures surface]
+
+## 4. Operational Notes
+
+- State/storage model: [DB/files/cache/queue]
+- Concurrency or ordering concerns: [if any]
+- Observability entrypoints: [logs/metrics/traces/dashboards]

package/specs-to-project-docs/references/templates/configuration.md

@@ -0,0 +1,29 @@
+# Configuration
+
+## 1. Environment Variables And Config Files
+
+| Key / File | Required | Purpose | Example / Default | Evidence |
+| --- | --- | --- | --- | --- |
+| `[ENV_KEY]` | `[Yes/No]` | [What it controls] | [Example or default] | [File path] |
+| `[config/file]` | `[Yes/No]` | [Why it matters] | [Example or default] | [File path] |
+
+## 2. External Services And Credential Setup
+
+### [Service Name]
+
+- Purpose: [Why this service exists in the project]
+- Required keys/config: `[ENV_KEY]`, `[CONFIG_KEY]`
+- Official setup entry: [Link or exact console path if known]
+- Acquisition steps:
+  1. [Create or open the relevant account/project]
+  2. [Generate/find the credential]
+  3. [Store it in the local/deployment config]
+  4. [Verify connectivity]
+- Development notes: [sandbox/test mode, rate limit, fake data, or `Unknown`]
+- Evidence: [file path or spec path]
+
+## 3. Safety Notes
+
+- Secret handling: [where secrets should live]
+- Local overrides: [env file / config layering / secret manager]
+- Common misconfiguration symptoms: [brief list]

package/specs-to-project-docs/references/templates/developer-guide.md

@@ -0,0 +1,33 @@
+# Developer Guide
+
+## 1. Domain Concepts To Know
+
+- [Business rule, glossary term, permission model, lifecycle concept]
+- [Business rule, glossary term, permission model, lifecycle concept]
+
+## 2. Change Hotspots
+
+- Critical modules: [paths or module names]
+- External dependency touchpoints: [APIs/services/jobs]
+- Data integrity or migration risks: [if any]
+- Concurrency / idempotency concerns: [if any]
+
+## 3. Testing Expectations
+
+- Required test layers: [unit / integration / E2E / property-based]
+- Mock/fake expectations: [where external dependencies should be isolated]
+- High-value regression areas: [bug-prone workflows]
+
+## 4. Debugging Entry Points
+
+- Logs: [paths / commands / tools]
+- Local reproduction commands: [commands]
+- Dashboards or observability tools: [if any]
+- Common failure signals: [errors / symptoms]
+
+## 5. Documentation Maintenance Notes
+
+- Specs reviewed: [list of spec directories/files]
+- Existing docs updated: [paths]
+- Major conflicts resolved: [spec vs code decisions]
+- Remaining unknowns: [list or `None`]

package/specs-to-project-docs/references/templates/docs-index.md

@@ -0,0 +1,39 @@
+# [Project Name] Documentation
+
+## Start Here
+
+- Project overview: `README.md`
+- Setup and deployment: `docs/getting-started.md`
+- Configuration and external services: `docs/configuration.md`
+- Architecture: `docs/architecture.md`
+- Features and workflows: `docs/features.md`
+- Developer guide: `docs/developer-guide.md`
+
+## Document Guide
+
+### Getting Started
+- Audience: [operators / developers / both]
+- Covers: installation, prerequisites, local run, deployment flow
+
+### Configuration
+- Audience: [operators / developers / both]
+- Covers: env vars, config files, secrets, external services, API key setup
+
+### Architecture
+- Audience: [developers / maintainers]
+- Covers: system boundaries, module responsibilities, data flow, key directories
+
+### Features
+- Audience: [users / support / developers]
+- Covers: major workflows, entrypoints, user value, important edge cases
+
+### Developer Guide
+- Audience: [developers / maintainers]
+- Covers: domain concepts, risk hotspots, testing expectations, debugging entrypoints
+
+## Reference List
+
+- Source specs reviewed: [list of spec directories/files]
+- Existing docs updated: [paths]
+- Important code/config references: [paths]
+- Remaining unknowns: [list or `None`]

package/specs-to-project-docs/references/templates/features.md

@@ -0,0 +1,25 @@
+# Features
+
+## 1. Feature Summary
+
+- Supported user workflows: [short list]
+- Primary entrypoints: [routes/pages/commands/jobs]
+- Notable limitations or guardrails: [if any]
+
+## 2. Feature Details
+
+### [Feature or Workflow Name]
+
+- User value: [Why it matters]
+- Trigger or entrypoint: [route/command/page/job]
+- Core flow: [happy path summary]
+- Edge or failure notes: [important caveats]
+- Evidence: [spec/code/doc path]
+
+### [Feature or Workflow Name]
+
+- User value: [Why it matters]
+- Trigger or entrypoint: [route/command/page/job]
+- Core flow: [happy path summary]
+- Edge or failure notes: [important caveats]
+- Evidence: [spec/code/doc path]

package/specs-to-project-docs/references/templates/getting-started.md

@@ -0,0 +1,38 @@
+# Getting Started
+
+## 1. Purpose
+
+- Project purpose: [What the project exists to do]
+- Primary users: [Who uses it]
+- Supported environments: [local / staging / production / other]
+
+## 2. Prerequisites
+
+- Runtime/tooling: [Node/Python/Docker/etc.]
+- Accounts/services needed: [if any]
+- Local dependencies: [database, queue, browser, etc.]
+
+## 3. Installation
+
+```bash
+[Clone / install / bootstrap commands]
+```
+
+## 4. Local Run
+
+```bash
+[Run or dev server commands]
+```
+
+## 5. Deployment
+
+- Deployment targets: [where it deploys]
+- Deployment command or pipeline: [command / CI job / script]
+- Required pre-deploy checks: [tests, migrations, approvals]
+- Rollback notes: [how rollback works or `Unknown`]
+
+## 6. Verification
+
+- Smoke checks: [command / URL / workflow]
+- Expected signals: [log, page, API response, artifact]
+- Evidence: [file path or command path]

package/specs-to-project-docs/references/templates/readme.md

@@ -0,0 +1,49 @@
+# [Project Name]
+
+[One-paragraph project introduction: what the project does, who it is for, and the core value it provides.]
+
+## Highlights
+
+- [Primary feature or workflow]
+- [Primary feature or workflow]
+- [Primary feature or workflow]
+
+## Quick Start
+
+### Install
+
+```bash
+[Install command or setup sequence]
+```
+
+### Configure
+
+- [Required env var or config file]
+- [Required env var or config file]
+
+### Run or Deploy
+
+```bash
+[Local run command or deployment command]
+```
+
+## Documentation
+
+- Project docs index: `docs/README.md`
+- Setup and deployment: `docs/getting-started.md`
+- Configuration: `docs/configuration.md`
+- Architecture: `docs/architecture.md`
+- Features: `docs/features.md`
+- Developer guide: `docs/developer-guide.md`
+
+## Main Features
+
+### [Feature Area 1]
+[Short explanation of the user-facing value and the main flow.]
+
+### [Feature Area 2]
+[Short explanation of the user-facing value and the main flow.]
+
+## Notes
+
+- [Any important limitation, prerequisite, or safety note]

package/systematic-debug/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/systematic-debug/README.md

@@ -0,0 +1,81 @@
+# Systematic Debug Skill
+
+## Brief Introduction
+
+An agent skill for Codex/Claude workflows that applies a test-first debugging process: understand the issue, inspect code paths, reproduce all plausible causes with tests, and fix until all related tests pass.
+
+This skill is designed to avoid speculative fixes and ensure each bug hypothesis is validated through reproducible test evidence.
+
+## Problems this skill solves
+
+Use this skill when:
+
+- An issue is reported but root cause is not obvious
+- Multiple code paths may explain the same failure
+- You need evidence-backed fixes with reproducible tests
+- You want to reduce regressions from guess-based changes
+
+## Invocation rule
+
+This skill should be invoked by default for any program-problem request, such as:
+
+- bug reports, regressions, or "feature not working"
+- runtime errors, exceptions, crashes, or HTTP 4xx/5xx failures
+- failing or flaky tests
+- intermittent or hard-to-reproduce incorrect behavior
+- any observed-vs-expected mismatch (for example: "it should do X but did Y")
+
+It should also auto-invoke when mismatch evidence is detected during normal task execution (logs, test failures, runtime output), even if debugging was not explicitly requested.
+
+## Core method
+
+This skill follows a fixed workflow:
+
+1. **Understand and inspect**: interpret expected vs observed behavior, inspect relevant code, and list all plausible causes.
+2. **Reproduce with tests**: create or extend tests to reproduce each plausible cause.
+3. **Diagnose and confirm**: use reproduction evidence to confirm the true root cause and rule out non-causes.
+4. **Fix and validate**: apply focused fixes and iterate until all reproduction tests pass.
+
+## Design principles
+
+- **Evidence first**: every cause should be validated by tests.
+- **Comprehensive hypotheses**: do not stop at the first guess.
+- **Minimal change**: keep fixes targeted to confirmed failures.
+- **Clear traceability**: map fixes to specific failing-then-passing tests.
+
+## Typical deliverables
+
+For each debugging task, provide:
+
+- Plausible root-cause list and related code paths
+- Reproduction tests for each plausible cause
+- Fix summary tied to test outcomes
+- Final confirmation that all related tests pass
+
+## Example: one full debugging cycle
+
+### User issue
+
+> "Checkout occasionally fails with a 500 error when applying coupons."
+
+### Agent execution (condensed)
+
+1. Identify plausible causes in coupon validation, pricing calculation, and external discount service handling.
+2. Add tests to reproduce each cause under matching edge conditions.
+3. Implement fixes for failing cases and rerun tests.
+4. Confirm all previously failing reproduction tests now pass.
+
+### Expected output
+
+- Root-cause hypothesis list with code references
+- Reproduction tests and initial failing results
+- Fix summary and passing test results
+- Final validation statement
+
+## Repository layout
+
+- `SKILL.md`: skill definition and workflow rules
+
+## License
+
+This project is licensed under [MIT License](LICENSE).

package/systematic-debug/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: systematic-debug
+description: "Systematic debugging workflow for program issues: understand observed vs expected behavior, inspect codebase paths, reproduce all plausible causes with tests, diagnose the real root cause, and complete a validated fix. Auto-invoke whenever behavior does not match expectations (even if the user did not explicitly request debugging), including bugs, errors, crashes, regressions, flaky behavior, and failing tests."
+---
+
+# Systematic Debug
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: not applicable.
+
+## Standards
+
+- Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause.
+- Execution: Inspect the relevant paths, reproduce every plausible cause with tests, diagnose the real cause, then apply the minimal fix.
+- Quality: Keep scope focused on the bug, prefer existing test patterns, and explicitly rule out hypotheses that could not be reproduced.
+- Output: Deliver the plausible-cause list, reproduction tests, validated fix summary, and passing-test confirmation.
+
+## Core Principles
+
+- Gather facts from user reports and code behavior before changing implementation.
+- Cover all plausible causes with reproducible tests instead of guessing a single cause.
+- Keep fixes minimal, focused, and validated by passing tests.
+
+## Trigger Conditions
+
+Use this skill by default whenever the request indicates a program problem, including:
+
+- bug, defect, regression, broken behavior
+- error, exception, crash, 4xx/5xx failure
+- failing/flaky tests, intermittent failures, unstable behavior
+- "why is this not working" style troubleshooting requests
+- explicit or implicit observed-vs-expected mismatch ("it should do X but does Y")
+
+Also auto-invoke this skill when mismatch evidence appears during normal execution (logs, test output, runtime output), even if the original request was not phrased as a debugging task.
+
+## Required Workflow
+
+1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, and build a list of plausible root causes.
+2. **Reproduce with tests**: Write or extend tests that reproduce every plausible cause.
+3. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause and explicitly rule out non-causes.
+4. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests pass.
+
+## Implementation Guidelines
+
+- Read related modules end-to-end before editing.
+- Prefer existing test patterns and fixtures over creating new frameworks.
+- Keep the scope to bug reproduction and resolution; avoid unrelated refactors.
+- If a hypothesized cause cannot be reproduced, document why and deprioritize it explicitly.
+
+## Deliverables
+
+- Plausible root-cause list tied to concrete code paths
+- Reproduction tests for each plausible cause
+- Fix summary mapped to failing-then-passing tests
+- Final confirmation that all related tests pass

package/systematic-debug/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Systematic Debug"
+  short_description: "Diagnose bugs with reproduction tests before fixing"
+  default_prompt: "Use $systematic-debug to understand expected vs observed behavior, inspect relevant code paths, write or extend tests for every plausible cause, confirm the true root cause from reproduction evidence, apply the smallest focused fix, and validate with passing tests."

package/text-to-short-video/.env.example

@@ -0,0 +1,36 @@
+# Text to Short Video environment template
+#
+# Usage:
+# 1) Copy this file to /Users/tszkinlai/.codex/skills/text-to-short-video/.env
+# 2) Fill required keys
+
+# ====================================
+# API connection (required)
+# ====================================
+# OpenAI-compatible API base URL (must include /v1)
+OPENAI_API_URL="https://api.openai.com/v1"
+
+# API key for the video API
+OPENAI_API_KEY=""
+
+# ====================================
+# Video generation defaults (optional)
+# ====================================
+# Provider model id used for /videos/generations
+OPENAI_VIDEO_MODEL="video-model-id"
+
+# Keep output in 30-60 seconds unless user requests otherwise
+OPENAI_VIDEO_DURATION_SECONDS="50"
+
+# Use either size or aspect ratio based on provider support
+OPENAI_VIDEO_SIZE="1080x1920"
+OPENAI_VIDEO_ASPECT_RATIO="9:16"
+
+# Polling interval for async generation job status
+OPENAI_VIDEO_POLL_SECONDS="5"
+
+# ====================================
+# Final video render size for optional post-processing
+# ====================================
+TEXT_TO_SHORT_VIDEO_WIDTH="1080"
+TEXT_TO_SHORT_VIDEO_HEIGHT="1920"

package/text-to-short-video/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tszkinlai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/text-to-short-video/README.md

@@ -0,0 +1,82 @@
+# text-to-short-video
+
+A Codex skill that converts articles, scripts, chapters, or notes into 30-60 second short videos (API-only workflow).
+
+This skill will:
+
+- Extract a short-video prompt from input text (or use a user-locked prompt directly)
+- Use `roles.json` to keep character consistency (existing roles only update `description`)
+- Call an OpenAI-compatible video generation API directly
+- Poll job status until completion and download MP4 output
+- Apply optional aspect-ratio/size post-processing when needed
+
+## Dependency skills
+
+No mandatory dependencies.
+
+> This skill does not use `openai-text-to-image-storyboard` or `remotion-best-practices`.
+
+## Character consistency (`roles.json`)
+
+- Role file path is fixed: `<project_dir>/pictures/<content_name>/roles.json`
+- JSON schema uses a `characters` array with fields:
+  - `id`
+  - `name`
+  - `appearance`
+  - `outfit`
+  - `description`
+- To preserve consistency: existing roles may only update `description`; do not rewrite `id/name/appearance/outfit`
+
+## Environment setup
+
+1. Copy env template:
+
+```bash
+cp /Users/tszkinlai/.codex/skills/text-to-short-video/.env.example \
+   /Users/tszkinlai/.codex/skills/text-to-short-video/.env
+```
+
+2. Required values:
+
+- `OPENAI_API_URL`
+- `OPENAI_API_KEY`
+
+3. Optional values:
+
+- `OPENAI_VIDEO_MODEL`
+- `OPENAI_VIDEO_DURATION_SECONDS`
+- `OPENAI_VIDEO_ASPECT_RATIO`
+- `OPENAI_VIDEO_SIZE`
+- `OPENAI_VIDEO_POLL_SECONDS`
+- `TEXT_TO_SHORT_VIDEO_WIDTH`
+- `TEXT_TO_SHORT_VIDEO_HEIGHT`
+
+## Aspect-ratio correction (optional post-processing)
+
+If API-generated video ratio/size does not match the target, run:
+
+```bash
+python /Users/tszkinlai/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
+  --input-video "<downloaded_video_path>" \
+  --output-video "<final_output_video_path>" \
+  --env-file /Users/tszkinlai/.codex/skills/text-to-short-video/.env \
+  --force
+```
+
+## Repository layout
+
+```text
+text-to-short-video/
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── .env.example
+├── agents/
+│   └── openai.yaml
+└── scripts/
+    └── enforce_video_aspect_ratio.py
+```
+
+## License
+
+This project is licensed under [MIT License](./LICENSE).