opencode-skills-collection 3.1.7 → 3.1.9

package/bundled-skills/.antigravity-install-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "updatedAt": "2026-06-26T02:05:23.006Z",
+  "updatedAt": "2026-06-28T02:10:47.668Z",
   "entries": [
     "00-andruia-consultant",
     "007",
@@ -57,6 +57,7 @@
     "ai-dev-jobs-mcp",
     "ai-engineer",
     "ai-engineering-toolkit",
+    "ai-loop",
     "ai-md",
     "ai-ml",
     "ai-native-cli",
@@ -128,6 +129,7 @@
     "architecture-decision-records",
     "architecture-patterns",
     "arm-cortex-expert",
+    "arrowspace",
     "article-illustrations",
     "asana-automation",
     "ask-matt",
@@ -456,6 +458,7 @@
     "create-pr",
     "cred-omega",
     "crewai",
+    "cron-doctor",
     "crossframe",
     "crossframe-casebook",
     "crossframe-critical",
@@ -740,6 +743,7 @@
     "geminiignore-finops",
     "geo-fundamentals",
     "geoffrey-hinton",
+    "gh-image",
     "gh-review-requests",
     "gha-security-review",
     "git-advanced-workflows",
@@ -751,6 +755,7 @@
     "git-pushing",
     "github",
     "github-actions-advanced",
+    "github-actions-debugger",
     "github-actions-templates",
     "github-automation",
     "github-issue-creator",
@@ -1182,6 +1187,7 @@
     "pptx-official",
     "pr-merge-champion",
     "pr-writer",
+    "premium-3d-website",
     "price-psychology-strategist",
     "pricing-strategy",
     "prisma-expert",
@@ -1426,6 +1432,7 @@
     "sql-injection-testing",
     "sql-optimization-patterns",
     "sql-pro",
+    "sql-sentinel",
     "sqlmap-database-pentesting",
     "square-automation",
     "squirrel",
@@ -1517,6 +1524,7 @@
     "test-fixing",
     "testing-patterns",
     "testing-qa",
+    "the-honoured-one",
     "theme-factory",
     "threat-mitigation-mapping",
     "threat-modeling-expert",
@@ -1626,6 +1634,7 @@
     "web-design-guidelines",
     "web-media-getter",
     "web-performance-optimization",
+    "web-project-brainstorming",
     "web-scraper",
     "web-security-testing",
     "web3-testing",

package/bundled-skills/ai-loop/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ai-loop
+description: Runs a bounded spec-build-review development loop with explicit scope, stop conditions, and human approval gates for risky or ambiguous work.
+category: workflow
+risk: safe
+source: community
+date_added: "2026-06-27"
+tags: [agent-workflow, specification, implementation, review, verification, feedback-loop]
+tools: [claude, cursor, codex, gemini]
+---
+
+# AI-Loop Skill
+
+## Overview
+
+The `ai-loop` skill structures a bounded development cycle for agentic workflows. By dividing the process into distinct planning (Spec), implementation (Build), and validation (Review) phases, it helps an agent build and correct scoped code changes while keeping requirements, risk gates, and stop conditions explicit.
+
+## When to Use This Skill
+
+- Use when you need a feature built from scratch or heavily modified, and you want the agent to handle the lifecycle (specification, implementation, and verification) inside one clearly bounded workflow.
+- Use when working with isolated components, modules, or features that have well-defined scopes and constraints.
+- Use when the user asks for a complete development pass but the work still has clear success criteria, a reasonable verification path, and no unresolved safety or product decisions.
+
+## How It Works
+
+This skill executes a controlled development loop composed of three phases: Spec, Build, and Review. When invoked, the agent moves through those phases until the scoped requirements pass verification, a stop condition is reached, or human approval is needed.
+
+Before starting, define:
+
+- The maximum number of build-review iterations.
+- The verification commands or manual checks that count as evidence.
+- The actions that require explicit approval, such as destructive commands, production changes, external service writes, or broad architectural pivots.
+
+### Phase 1: Spec (Planning)
+
+1. Interview the user about the feature or app they want to build. Ask one focused question at a time until you fully understand the goal, the must-have requirements, the constraints, and what "done" looks like.
+2. **Do not start building yet.**
+3. When you have enough information, write a clear, detailed specification and save it to `specs/<feature-name>.md`.
+4. The spec must include:
+   - The objective
+   - The exact requirements
+   - Edge cases to handle
+   - A concrete definition of done that someone could check the build against
+   - The iteration budget, verification commands, and approval gates.
+
+### Phase 2: Build (Implementation)
+
+1. Read the spec you just created in `specs/<feature-name>.md`.
+2. Build exactly what it describes.
+3. **Do not add features**, do not refactor unrelated code, and do not invent requirements that aren't in the spec.
+4. Focus strictly on fulfilling the spec. List which spec requirements you covered so the review step can check them.
+
+### Phase 3: Review (Verification)
+
+1. Compare your implementation against `specs/<feature-name>.md`.
+2. Go requirement by requirement and verify if it was met. List every gap, bug, or missing piece, naming the exact spec item each one fails.
+3. If anything fails and the iteration budget is not exhausted, write the specific fixes needed and **loop back to Phase 2 (Build)** to address them.
+4. Stop and ask for human input when the next fix would change the spec, exceed the iteration budget, require risky operations, or depend on product decisions not captured in the spec.
+5. Only pass the build and conclude the skill execution when every requirement in the spec is fully met and the declared verification evidence has passed.
+
+## Examples
+
+### Example 1: Creating a Basic Statistics Helper
+
+**User:**
+> I want to add a utility for calculating basic statistics (mean, median, mode) of an array of numbers.
+
+**Agent (Phase 1 - Spec):**
+> I can help with that. To get started, what programming language should this statistics calculator be implemented in? Also, how should empty arrays or invalid inputs be handled?
+
+**User:**
+> JavaScript. If the array is empty, return null. If there are non-numbers, ignore them.
+
+**Agent (Phase 1 - Spec):**
+> Thank you. I have created the specification file at `specs/stats-calculator.md` with the requirements we discussed. Now, I will start implementing it.
+
+**Agent (Phase 2 - Build):**
+> *(Creates `stats_calculator.js` and implements `mean`, `median`, and `mode` matching the spec exactly)*
+> I have finished implementing the calculator. I will now verify the implementation.
+
+**Agent (Phase 3 - Review):**
+> Checking implementation against `specs/stats-calculator.md`:
+> - Requirement: mean calculation -> PASS
+> - Requirement: median calculation -> PASS
+> - Requirement: mode calculation -> PASS
+> - Requirement: empty array returns null -> PASS
+> - Requirement: non-numbers are ignored -> FAIL (I noticed `mode` doesn't filter out non-numbers).
+>
+> I will now loop back to Phase 2 to fix the `mode` function.
+
+**Agent (Phase 2 - Build Loop-Back):**
+> *(Fixes `mode` to filter out non-numbers)*
+> I have updated the implementation. Let's re-verify.
+
+**Agent (Phase 3 - Review):**
+> - Requirement: mode filters non-numbers -> PASS
+> 
+> All requirements passed! The statistics calculator is complete and verified.
+
+## Best Practices
+
+- ✅ Do ask clarifying questions one at a time to avoid overwhelming the user during the planning phase.
+- ✅ Do document edge cases explicitly in `specs/<feature-name>.md` before writing any code.
+- ✅ Do stick strictly to the approved specification during the build phase.
+- ✅ Do cap the loop with a small iteration budget and report exactly what remains if the budget is exhausted.
+- ✅ Do pause for explicit approval before destructive, production, credentialed, or externally visible actions.
+- ❌ Don't implement extra features or perform unrelated refactorings that aren't specified.
+- ❌ Don't skip the review phase or pass it without verifying every single requirement.
+- ❌ Don't keep retrying the same failing fix without new evidence or a changed approach.
+
+## Limitations
+
+- This skill requires sufficient context about the feature to be provided during the Spec phase.
+- It is best suited for isolated features or tasks with clear boundaries, rather than open-ended architectural refactoring.
+- The review phase relies on the agent's self-assessment against the generated spec; manual review is still recommended for critical systems.
+- It is not a replacement for human approval on security-sensitive, destructive, production, compliance, or externally visible changes.
+- It should stop rather than continue if requirements conflict, tests cannot run, or verification depends on unavailable credentials or systems.
+
+## Security & Safety Notes
+
+- Be cautious when running or testing code generated during the Build phase. Always run tests in a safe, sandboxed environment.
+- Avoid executing arbitrary shell commands provided directly by the user without validating their safety.
+- Make sure no hardcoded secrets, keys, or credentials are added to the code or specifications.
+- Treat production deploys, data migrations, payment flows, credential changes, and external write actions as approval-gated work.
+
+## Common Pitfalls
+
+- **Problem:** The agent tries to build a huge system all at once, leading to an overcomplicated spec and incomplete implementation.
+  **Solution:** Keep the scope of `ai-loop` to small, modular features. Break larger systems into multiple independent loops.
+- **Problem:** The spec is vague, causing the build phase to rely on assumptions.
+  **Solution:** Spend extra time in the planning phase asking targeted questions to pin down requirements.
+
+## Related Skills
+
+- `@plan-writing` - For writing more detailed implementation plans for larger projects.
+- `@ask-questions-if-underspecified` - For standard guidelines on interviewing the user.

package/bundled-skills/arrowspace/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: arrowspace
+description: "Spectral vector search using graph Laplacian eigenstructure. Use when cosine/L2 similarity misses latent structure in your embeddings."
+category: data
+risk: safe
+source: community
+source_repo: Genefold/arrowspace-skills
+source_type: community
+date_added: "2026-06-25"
+author: Genefold AI
+license: Apache-2.0
+license_source: "https://github.com/Genefold/arrowspace-skills/blob/main/LICENSE"
+tags: [vector-search, spectral-analysis, graph-laplacian, embeddings, lambda-tau]
+tools: [claude, cursor, codex, gemini, opencode]
+---
+
+# ArrowSpace
+
+Spectral vector search that augments nearest-neighbour search with graph Laplacian features. Computes a Laplacian over the item graph and uses the Rayleigh quotient to produce a λτ (lambda-tau) score per item, enabling search that respects both semantic similarity and structural role.
+
+## When to Use This Skill
+
+- Cosine or L2 similarity misses latent structure in your embeddings
+- You want graph-based retrieval with spectral awareness
+- You need to characterise the spectral properties of an embedding space
+- You are building RAG pipelines where contextual role matters alongside semantic content
+
+## How It Works
+
+### Step 1: Install and import
+
+```bash
+pip install arrowspace
+```
+
+```python
+from arrowspace import ArrowSpaceBuilder
+import numpy as np
+```
+
+### Step 2: Prepare your data
+
+Pass an (N, d) float64 NumPy array of embedding vectors:
+
+```python
+items = np.array([[0.1, 0.2, 0.3],
+                  [0.0, 0.5, 0.1],
+                  [0.9, 0.1, 0.0]], dtype=np.float64)
+```
+
+### Step 3: Configure graph parameters
+
+```python
+graph_params = {"eps": 0.2, "k": 6, "topk": 3, "p": 2.0, "sigma": 1.0}
+builder = ArrowSpaceBuilder(items, graph_params=graph_params)
+aspace = builder.build()
+```
+
+### Step 4: Query
+
+```python
+lambdas = aspace.lambdas()           # array indexed by insertion order
+sorted_res = aspace.lambdas_sorted()  # (score, index) pairs ascending
+```
+
+Higher λτ values indicate items that are both semantically close and structurally central.
+
+## Examples
+
+### Example 1: Basic spectral retrieval
+
+```python
+items = np.random.randn(100, 64).astype(np.float64)
+builder = ArrowSpaceBuilder(items, graph_params={"eps": 0.5, "k": 10, "topk": 5, "p": 2.0, "sigma": None})
+aspace = builder.build()
+scores = aspace.lambdas()
+top_indices = np.argsort(scores)[-5:]
+```
+
+### Example 2: Compare spectral vs cosine ranking
+
+```python
+from sklearn.metrics.pairwise import cosine_similarity
+cos_sim = cosine_similarity(items)
+cosine_order = np.argsort(cos_sim[0])[::-1]
+spectral_order = np.argsort(aspace.lambdas())[::-1]
+```
+
+## Best Practices
+
+- ✅ Normalise embeddings to unit norm before passing to ArrowSpace
+- ✅ Start with eps proportional to 1/sqrt(dim) and tune from there
+- ✅ Use k between 3 and 25 depending on dataset size (rule: N/50)
+- ✅ Set sigma=None to auto-select kernel width from distance distribution
+- ❌ Don't use with fewer than 10 items (graph structure is not meaningful)
+- ❌ Don't use for real-time streaming data (ArrowSpace is batch-oriented)
+
+## Limitations
+
+- This skill does not replace environment-specific validation, testing, or expert review.
+- ArrowSpace is batch-oriented and not designed for real-time indexing of streaming data.
+
+## Common Pitfalls
+
+- **Problem:** eps is too small, producing a disconnected graph
+  **Solution:** Increase eps, or set it proportional to 1/sqrt(embedding_dim)
+
+- **Problem:** k is too large, producing a dense graph with washed-out spectral features
+  **Solution:** Keep k ≤ 25 for most datasets
+
+## Related Skills
+
+- `vector-database-engineer` — General vector database expertise
+- `embedding-strategies` — Embedding model selection and chunking
+- `similarity-search-patterns` — Semantic search implementation patterns
+- `hybrid-search-implementation` — Combined semantic + keyword search

package/bundled-skills/cron-doctor/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: cron-doctor
+description: "Diagnose and validate cron expressions before they ship. Catches the five silent death-traps: impossible dates that never fire, OR-semantics that fire too often, midnight spikes, uneven step drift, and leap-year February 29."
+category: devops
+risk: safe
+source: community
+source_repo: takeaseatventure/devops-skills
+source_type: community
+date_added: "2026-06-26"
+author: takeaseat
+tags: [cron, crontab, scheduling, devops, debugging, kubernetes, validation]
+tools: [claude, cursor, codex, gemini, opencode]
+license: "MIT"
+license_source: "https://github.com/takeaseatventure/devops-skills/blob/main/LICENSE"
+---
+
+# cron-doctor
+
+## Overview
+
+Cron is deceptively error-prone. The failure mode is **silent** — a syntactically
+valid expression that simply never fires, or fires far more often than intended.
+`0 0 30 2 *` parses cleanly and then sits dead forever (February has no 30th).
+`0 0 1,15 * 1` looks like "1st and 15th if Monday" but actually means "1st, 15th,
+**OR** every Monday" — ~6 fires/month instead of ~2.
+
+This skill teaches an agent to catch those before they reach production. It comes
+with a zero-dependency validation engine (`scripts/cron-engine.js`, no install
+needed) that parses, describes, deep-validates, and computes next fire times.
+
+## When to Use This Skill
+
+- Use when a user writes, edits, reviews, or deploys a cron expression — in a
+  crontab, a Kubernetes `CronJob`, a GitHub Actions `schedule`, an Airflow DAG,
+  a Celery beat schedule, a systemd timer, or any scheduled task.
+- Use when debugging a job that "didn't fire" or "fired at the wrong time."
+- Use when a user asks "what does this cron expression mean?" or "when will this
+  run next?" or "how often does this run per year?"
+- Use when reviewing a CI/CD pipeline or infrastructure config that contains a
+  `schedule` field.
+- Use when a user pastes a 5-field cron expression and asks for a sanity check.
+
+## How It Works
+
+### Step 1: Parse the expression
+
+Split on whitespace into 5 fields: minute, hour, day-of-month, month, day-of-week.
+Confirm valid ranges:
+
+| Field | Position | Range | Notes |
+|-------|----------|-------|-------|
+| minute | 1 | 0–59 | |
+| hour | 2 | 0–23 | |
+| day-of-month | 3 | 1–31 | |
+| month | 4 | 1–12 | names (JAN–DEC) accepted |
+| day-of-week | 5 | 0–7 | 0 and 7 both = Sunday; names (SUN–SAT) accepted |
+
+### Step 2: Describe it in plain English
+
+State what the user *thinks* it does vs. what it *actually* does. Be explicit
+about OR-vs-AND semantics for day-of-month + day-of-week (see death-trap #2).
+
+### Step 3: Run the trap checklist
+
+Check the five death-traps below and flag any that apply.
+
+### Step 4: Calculate next runs and annual fire count
+
+Compute the next 5 fire times as concrete dates so the user can verify the
+schedule behaves as expected. Estimate annual fire count — a schedule that fires
+365×/year vs. 12×/year is a ~30× cost and load difference.
+
+## The Five Cron Death-Traps
+
+These are the bugs that pass `crontab -l` validation but break in production.
+
+### 1. Impossible dates — the "never fires" bug
+
+```
+0 0 30 2 *
+```
+
+**Valid syntax. Never fires.** February has no 30th. This schedule is a dead job
+that silently sits forever. The same applies to day 31 in any 30-day month:
+`0 0 31 4 *`, `0 0 31 6 *`, `0 0 31 9 *`, `0 0 31 11 *`.
+
+**Fix:** use `0 0 28-31 * *` and check for end-of-month in the script, or use `L`
+(last day) syntax if your scheduler supports it.
+
+### 2. OR-semantics — the "fires too often" bug
+
+```
+0 0 1,15 * 1
+```
+
+**Does NOT mean** "midnight on the 1st and 15th if it's Monday."
+**Does mean** "midnight on the 1st, the 15th, **OR** every Monday." That's ~6
+fires/month instead of ~2.
+
+This is the single most misunderstood cron rule. When **both** day-of-month AND
+day-of-week are restricted (neither is `*`), cron uses OR logic, not AND.
+
+**Fix:** if you need "1st and 15th only if Monday," run daily and check in the
+script:
+
+```bash
+0 0 * * 1 [ "$(date +%d)" = "01" -o "$(date +%d)" = "15" ] && your-command
+```
+
+### 3. Midnight spike — the "everything at once" bug
+
+```
+0 0 * * *
+```
+
+Every job scheduled at `0 0` competes for resources at exactly 00:00. Database
+backups, log rotations, cert renewals, report generation — all fire simultaneously.
+This causes load spikes, connection-pool exhaustion, and cascading timeouts.
+
+**Fix:** stagger jobs across the hour. Use `17 2 * * *` or `43 3 * * *` instead of
+`0 0`. Jitter is your friend.
+
+### 4. Uneven steps — the "drift" bug
+
+```
+*/7 * * * *
+```
+
+**Does NOT mean** "every 7 minutes evenly." It means "every 7 minutes starting at
+0, then resets at 60." So: 0, 7, 14, 21, 28, 35, 42, 49, 56 — then 0 again
+(a 4-minute gap). The intervals drift: 7,7,7,7,7,7,7,7,**4**.
+
+**Fix:** 60 is not divisible by 7. Use step values that divide 60 evenly: `*/5`,
+`*/10`, `*/15`, `*/20`, `*/30`. If you truly need every-7-minutes, use a loop with
+`sleep 420`.
+
+### 5. Leap-year February 29 — the "annual surprise"
+
+```
+0 0 29 2 *
+```
+
+Fires only on leap years — February 29, 2024 / 2028 / 2032… If someone writes this
+expecting "end of February," they'll be confused for 3 out of every 4 years.
+
+**Fix:** use `0 0 28 2 *` and handle the 29th case in the script if needed.
+
+## Using the validation script
+
+This skill ships a zero-dependency engine at `scripts/cron-engine.js` (Node.js, no
+`npm install` needed). You can use it programmatically or from the CLI:
+
+```javascript
+// Programmatic — Node.js, zero dependencies
+const { describe, validate, nextRuns, formatNextRuns } = require('./scripts/cron-engine.js');
+
+// Parse + describe -> returns { text, error, parsed }
+const d = describe('0 0 30 2 *');
+console.log(d.text);   // "At 00:00, on day-of-month 30 in in FEB"
+
+// Deep validation -> catches the traps
+const result = validate('0 0 30 2 *');
+console.log(result.valid);              // true (syntax is valid)
+console.log(result.observations);       // includes the "never fires" insight
+console.log(result.suggestions);        // e.g. "Midnight is a common spike..."
+
+// Next 5 fire times -> returns Date[]
+const runs = nextRuns('0 9 * * 1-5', new Date(), 5);
+console.log(formatNextRuns(runs, new Date())); // [{ date, relative, formatted }, ...]
+```
+
+```bash
+# CLI (via the bundled wrapper)
+node scripts/cli.js describe "*/5 * * * *"
+node scripts/cli.js validate "0 0 30 2 *"
+node scripts/cli.js next "0 9 * * 1-5" 5
+```
+
+## Common cron presets
+
+| Expression | Description | Use case |
+|-----------|-------------|----------|
+| `*/5 * * * *` | Every 5 minutes | Health checks, polling |
+| `0 * * * *` | Every hour | Hourly aggregation |
+| `0 */2 * * *` | Every 2 hours | Semi-frequent sync |
+| `0 9 * * 1-5` | 9am Mon–Fri | Business-hours task |
+| `0 2 * * *` | 2am daily | Off-peak batch (avoid midnight) |
+| `0 0 * * 0` | Midnight Sunday | Weekly maintenance |
+| `0 0 1 * *` | Midnight 1st of month | Monthly report |
+| `0 0 1 1 *` | Midnight Jan 1st | Annual task |
+
+## Best Practices
+
+- ✅ Always provide the plain-English description AND run the trap checklist.
+- ✅ Stagger midnight jobs to avoid the spike.
+- ✅ Prefer step values that divide 60 evenly (`*/5`, `*/15`, `*/30`).
+- ✅ Add a comment above every crontab line explaining intent.
+- ✅ Set an explicit timezone (`CRON_TZ`) on schedulers that support it.
+- ❌ Don't trust `crontab -l` validation — it only checks syntax, not semantics.
+- ❌ Don't restrict both day-of-month and day-of-week without confirming OR-logic.
+- ❌ Don't schedule everything at `0 0`.
+
+## Common Pitfalls
+
+- **Problem:** "My cron job isn't running."
+  **Solution:** Check for an impossible date (trap #1) and confirm the daemon is
+  running (`service cron status` / `systemctl status crond`). Verify the file
+  ends with a newline and has correct ownership.
+
+- **Problem:** "My job runs far more often than expected."
+  **Solution:** You hit OR-semantics (trap #2). If both day-of-month and
+  day-of-week are set, cron ORs them. Move one to `*` or guard in-script.
+
+- **Problem:** "Intervals are uneven — sometimes 7 min, sometimes 4."
+  **Solution:** Step value doesn't divide 60 evenly (trap #4). Use a divisor of 60.
+
+- **Problem:** "My job works locally but not in the cluster."
+  **Solution:** Timezone mismatch. Kubernetes `CronJob` and GitHub Actions default
+  to UTC. Confirm `timeZone` / `TZ` is set as intended.
+
+## Limitations
+
+- This skill targets standard 5-field cron as implemented by Vixie cron, systemd
+  timers, Kubernetes `CronJob`, GitHub Actions `schedule`, and most libraries. It
+  does **not** validate Quartz 6/7-field expressions with seconds/years, nor
+  non-standard `@reboot` / `L` / `#` extensions without a note.
+- Estimated annual fire counts assume a non-leap reference year; February 29
+  schedules (trap #5) are flagged explicitly.
+- This skill does not replace environment-specific validation, testing, or expert
+  review. Stop and ask for clarification if required inputs, permissions, or
+  safety boundaries are missing.
+
+## Related Skills
+
+- `docker-expert` — when the cron job runs inside a container and the issue is the
+  container/entrypoint rather than the schedule.
+- `kubernetes-deployment` — when validating a `CronJob` manifest's `spec.schedule`
+  field alongside the broader resource config.
+
+## Security & Safety Notes
+
+This skill is read-only and `risk: safe`. The validation script performs no file
+writes, network calls, or mutations — it only parses and computes. It is safe to
+run against any cron expression without preconditions.

package/bundled-skills/cron-doctor/scripts/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+
+// Minimal CLI wrapper for cron-engine.js. Zero dependencies.
+// Usage:
+//   node cli.js describe "<cron>"
+//   node cli.js validate "<cron>"
+//   node cli.js next "<cron>" [count]
+
+const cron = require('./cron-engine.js');
+const expr = process.argv[3];
+const cmd = process.argv[2];
+
+if (!cmd || !expr) {
+  console.error('Usage: node cli.js <describe|validate|next> "<cron-expr>" [count]');
+  console.error('Examples:');
+  console.error('  node cli.js describe "*/5 * * * *"');
+  console.error('  node cli.js validate "0 0 30 2 *"');
+  console.error('  node cli.js next "0 9 * * 1-5" 5');
+  process.exit(2);
+}
+
+function safe(fn) {
+  try {
+    fn();
+  } catch (e) {
+    console.error('Error: ' + (e.message || e));
+    process.exit(1);
+  }
+}
+
+switch (cmd) {
+  case 'describe':
+    safe(() => {
+      const d = cron.describe(expr);
+      console.log(d.text || d.description || JSON.stringify(d));
+    });
+    break;
+
+  case 'validate':
+    safe(() => {
+      const r = cron.validate(expr);
+      console.log('valid: ' + r.valid);
+      if (r.description) console.log('description: ' + r.description);
+      if (r.warnings && r.warnings.length) {
+        console.log('warnings:');
+        r.warnings.forEach((w) => console.log('  - ' + w));
+      }
+      if (r.observations && r.observations.length) {
+        console.log('observations:');
+        r.observations.forEach((o) => console.log('  [' + (o.level || 'info') + '] ' + o.message));
+      }
+      if (r.suggestions && r.suggestions.length) {
+        console.log('suggestions:');
+        r.suggestions.forEach((s) => console.log('  [' + (s.level || 'info') + '] ' + s.message));
+      }
+    });
+    break;
+
+  case 'next':
+    safe(() => {
+      const count = parseInt(process.argv[4] || '5', 10);
+      const runs = cron.nextRuns(expr, new Date(), count);
+      const formatted = cron.formatNextRuns(runs, new Date());
+      formatted.forEach((f) =>
+        console.log(f.relative + '\t' + f.formatted + '\t' + f.date.toString())
+      );
+    });
+    break;
+
+  default:
+    console.error('Unknown command: ' + cmd);
+    console.error('Commands: describe, validate, next');
+    process.exit(2);
+}