opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/tune-monitor/references/table-monitor.md

@@ -0,0 +1,138 @@
+# Tuning Table Monitors
+
+This reference covers type-specific tuning guidance for table monitors. Read this file after
+determining the monitor type in Phase 1.5.
+
+Table monitors cover multiple tables and metrics (freshness, volume change, unchanged size,
+schema). Each (table, metric) pair can be tuned independently.
+
+## Config fields to extract
+
+Extract these from the monitor report for your Phase 2 analysis:
+
+- Which tables and metrics the monitor covers
+- Per (table, metric) pair: current sensitivity or explicit threshold
+- Which (table, metric) pairs are firing and how often
+- The metric type for each anomaly: `last_updated_on` (freshness), `total_row_count` /
+  `total_byte_count` (volume change), `total_row_count_last_changed_on` /
+  `total_byte_count_last_changed_on` (unchanged size), or schema
+
+---
+
+## Key constraint: one recommendation per (table, metric) pair
+
+Each recommendation **MUST** target exactly one table MCON and one metric. Do NOT group multiple
+tables into a single recommendation, even if the change is identical. The apply step makes one
+tool call per recommendation.
+
+---
+
+## Correlated anomalies
+
+When multiple (table, metric) pairs fire within a short window (minutes to a few hours), they
+likely share a common cause — e.g., a delayed pipeline affects freshness across several tables,
+or a bulk load triggers volume anomalies on related tables. Before counting anomalies per pair,
+group alerts by time proximity and assess whether they stem from the same upstream event. A burst
+of correlated alerts is one noise source, not many independent ones — address the root cause
+rather than tuning each pair separately.
+
+---
+
+## Minimum anomaly threshold
+
+Only recommend tuning a (table, metric) pair if it has **3 or more anomalies** in the report.
+A pair with 1-2 anomalies is not a clear noise pattern — it could be legitimate.
+
+For pairs with only 3-4 anomalies, require **strong supporting evidence**: consistent marginal
+breaches, TSA confirming normal variation, or NOT_ACKNOWLEDGED status on all. A handful of
+anomalies alone is not enough — the pattern must clearly indicate noise.
+
+---
+
+## Tuning levers by metric
+
+### Freshness (`last_updated_on`)
+
+- **Sensitivity**: LOW / MEDIUM / HIGH. Lower when tables have known late-arriving data.
+- **Explicit threshold**: set a fixed threshold in minutes. Use when the table has a known SLA
+  (e.g., "this table updates every 6 hours -> set threshold to 420 minutes").
+- Use the delay and threshold values from the incident to judge whether the current sensitivity
+  is too tight.
+
+### Volume change (`total_row_count`, `total_byte_count`)
+
+- **Sensitivity**: LOW / MEDIUM / HIGH. Lower for tables with bursty or seasonal patterns.
+- **Explicit thresholds**: set `upper_threshold_pct` and `lower_threshold_pct` (e.g., 50 means
+  50% change). Also requires `threshold_lookback_minutes`.
+- Check the delta vs threshold in the incident — if deltas are consistently just above the auto
+  threshold, lower sensitivity. If the expected range is known, use explicit thresholds.
+
+### Unchanged size (`total_row_count_last_changed_on`, `total_byte_count_last_changed_on`)
+
+- **Sensitivity**: LOW / MEDIUM / HIGH. Lower for tables that legitimately go quiet (weekends,
+  batch jobs).
+- **Explicit threshold**: set a fixed threshold in minutes for how long the table can remain
+  unchanged before alerting.
+- Check "time since update" vs threshold in the incident — if the table regularly goes quiet
+  for known periods, set an explicit threshold above that period.
+
+### Schema anomalies
+
+**Do NOT recommend changes for schema anomalies** — they are not tunable via the
+asset-rule tool. (Schema change is a separate per-table on/off flag via
+`create_or_update_table_monitor_asset_rule` with `rule_type="schema_monitor"`,
+but that's a different intent from tuning detector sensitivity.)
+
+---
+
+## Sensitivity vs explicit thresholds
+
+For ML thresholds (`threshold_type=auto`), always try **lowering sensitivity first**. Only
+switch to explicit thresholds if:
+- The lowest sensitivity still fires on expected behavior, OR
+- The user has a clear SLA or schedule that makes a fixed threshold more appropriate
+
+---
+
+## Applying changes
+
+Table monitor tuning uses **`create_or_update_table_monitor_asset_rule`** — **not**
+`create_or_update_table_monitor`. The single tool covers all three OOTB detectors;
+pick the per-metric variant via `rule_type`:
+
+| Metric | `rule_type` arg |
+|---|---|
+| Freshness (`last_updated_on`) | `last_updated_on` |
+| Volume change (`total_row_count`) | `total_row_count` |
+| Unchanged size (`total_row_count_last_changed_on`) | `total_row_count_last_changed_on` |
+
+Each tool call targets one `(table, rule_type)` pair. Pass the MCON in the `table`
+arg (the warehouse is parsed from it). For each `rule_type`, pick **one of two
+paths**:
+
+- **AUTO sensitivity** (default lever):
+  - `rule_type="last_updated_on"`: pass `threshold_sensitivity` (`low` / `medium` / `high`).
+  - `rule_type="total_row_count"` (volume): pass `alert_conditions=[{"type": "lookback", "operator": "AUTO", "threshold_sensitivity": "low"|"medium"|"high"}]`.
+  - `rule_type="total_row_count_last_changed_on"` (UCS): pass `alert_conditions=[{"type": "threshold", "operator": "AUTO", "threshold_sensitivity": "low"|"medium"|"high"}]`.
+  - Omit `schedule_type` — the platform's existing schedule is preserved.
+- **Explicit threshold + fixed cadence**:
+  - `rule_type="last_updated_on"`: pass `freshness_threshold_minutes=<int>` (single duration).
+  - `rule_type="total_row_count"`: pass `alert_conditions=[{"type": "lookback", "operator": "OUTSIDE_RANGE", "lower_threshold": <pct>, "upper_threshold": <pct>, "threshold_lookback_minutes": <minutes>}]` — thresholds are relative percentages (e.g. -50 / 50 = ±50 %).
+  - `rule_type="total_row_count_last_changed_on"`: pass `alert_conditions=[{"type": "threshold", "operator": "GT", "threshold_value": <minutes>, "threshold_lookback_minutes": <minutes>}]` — `threshold_value` is duration in minutes.
+  - **Must** also pass `schedule_type="fixed"` plus an `interval_minutes` (or `interval_crontab`) cadence — the threshold's meaning depends on how often the check runs.
+
+1. **Always preview first** — show the user the planned changes per `(table, rule_type)` pair
+   and ask for confirmation before applying.
+2. **On confirmation**, make one tool call per recommendation.
+
+### Common mistakes
+
+- **NEVER** apply changes without showing the preview first.
+- **NEVER** group multiple tables into one recommendation — one tool call per
+  `(table, rule_type)`.
+- **NEVER** recommend tuning schema anomalies — they are not supported.
+- **NEVER** combine AUTO sensitivity with `schedule_type="fixed"` or explicit cadence
+  args — AUTO preserves the platform schedule. Conversely, **always** pass
+  `schedule_type="fixed"` + a cadence when setting an explicit threshold.
+- **IMPORTANT:** These mutations are full replacements. Pass `tags` if the current
+  config has any — omitting tags clears them.

package/bundled-skills/tune-monitor/references/validation-monitor.md

@@ -0,0 +1,132 @@
+# Tuning Validation Monitors
+
+This reference covers type-specific tuning guidance for validation monitors. Read this file after
+determining the monitor type in Phase 1.5.
+
+## Config fields to extract
+
+Extract these from the `get_monitors` config response for your Phase 2 analysis:
+
+- Alert condition tree (`alert_condition`) — a FilterGroup with UNARY, BINARY, SQL, and/or
+  nested GROUP nodes
+- Table being validated
+- Schedule interval
+- Whether conditions use simple predicates or SQL expressions
+
+---
+
+## Key constraint: limited incident detail
+
+Validation incidents only report **invalid row counts** — not what the rows contained. This
+fundamentally limits what you can recommend without troubleshooting analysis (TSA).
+
+**Without TSA:** You cannot determine _why_ rows are invalid or whether the alert condition
+itself is too broad. Only schedule changes are safe to recommend.
+
+**With TSA:** If troubleshooting analysis identifies specific values, patterns, or root causes
+for the invalid rows, you can recommend alert condition modifications.
+
+---
+
+## Schedule tuning (always safe)
+
+- If the monitor fires repeatedly for the same underlying issue (e.g., the same batch of invalid
+  rows detected on every run) → increase the schedule interval to reduce duplicate alerts.
+- If invalid rows appear only after specific ETL jobs → align the schedule to run after those
+  jobs complete.
+
+---
+
+## Alert condition modifications (requires troubleshooting analysis)
+
+**IMPORTANT:** Do NOT recommend alert condition changes unless TSA is present and identifies the
+root cause of the invalid rows. Without knowing _what_ the invalid data looks like, condition
+changes risk masking real issues.
+
+The alert condition is a FilterGroup tree. When tuning:
+
+### Add exclusions
+
+Add SQL conditions or additional predicates to exclude known-valid edge cases that trigger
+false positives:
+
+```json
+{
+  "type": "GROUP",
+  "operator": "AND",
+  "conditions": [
+    // ... existing conditions ...
+    {
+      "type": "SQL",
+      "sql": "category != 'legacy_import'"
+    }
+  ]
+}
+```
+
+### Tighten or loosen existing predicates
+
+- If a BINARY condition threshold is too tight (e.g., `greater_than 0` but 1-3 invalid rows
+  is normal) → loosen the threshold based on observed values from TSA.
+- If a UNARY null check fires on a column that is legitimately nullable for certain record
+  types → add an exclusion condition rather than removing the null check.
+
+### Produce the full FilterGroup tree
+
+When recommending changes, always output the **complete** `alert_condition` tree — not just the
+modified node. The tool replaces the full condition, not individual nodes.
+
+**NEVER** simplify or restructure the condition tree beyond the targeted change. Preserve the
+existing structure and only modify what's needed.
+
+---
+
+## What NOT to recommend without TSA
+
+- Removing conditions from the alert condition tree
+- Changing predicate logic (e.g., `null` to `not_null`, `in_set` to different values)
+- Adding new conditions based on speculation about what the invalid data might look like
+
+If TSA is absent and the monitor is noisy, say so explicitly:
+
+> This validation monitor is firing frequently, but without troubleshooting analysis I cannot
+> determine what the invalid rows contain. I can only recommend schedule changes. To enable
+> deeper tuning, run troubleshooting on recent incidents to identify the root cause.
+
+---
+
+## Applying changes
+
+Use `create_or_update_validation_monitor` to update the monitor in place.
+
+1. **Always pass `monitor_uuid=<uuid>`** so the tool updates the existing monitor rather than
+   creating a new one. Use the monitor UUID from Phase 1.
+2. **Always dry-run first** (`dry_run=True`, the default) — show the user the YAML preview
+   returned in `result.yaml`, including the full updated `alert_condition` tree, and ask for
+   confirmation before applying.
+3. **On confirmation**, call again with `dry_run=False` (and the same `monitor_uuid` plus the
+   same other parameters). The response carries the monitor's UUID in `result.monitor_uuid` and
+   a deep link in `result.instructions` — surface that to the user. `result.yaml` is `None` on
+   the live call by design.
+4. **Stale-uuid handling.** If the monitor was deleted between read and write, the tool raises a
+   clear error instructing you to retry without `monitor_uuid` (turning the intent from "update"
+   into "create"). Confirm with the user before recreating.
+
+### Common mistakes
+
+- **NEVER** omit `monitor_uuid` — this creates a duplicate monitor instead of updating.
+- **NEVER** apply changes without showing the dry-run preview first.
+- **CRITICAL: PUT semantics.** `create_or_update_validation_monitor` with `monitor_uuid` fully
+  replaces the monitor's configuration — fields you omit revert to tool defaults, they are NOT
+  left untouched. The full config from Phase 1's `get_monitors(monitor_ids=[<uuid>],
+  include_fields=["config"])` call is your source of truth: re-pass every field you want to
+  keep (the full alert_condition tree, schedule, table, audiences, notes, priority, tags, etc.)
+  alongside the ones you're changing.
+- **Diff the preview against the original.** Before running `dry_run=False`, compare the
+  rendered YAML returned in `result.yaml` against the original config — if anything you meant to
+  preserve is missing or changed, fix the call before committing.
+- **CRITICAL:** The `alert_condition` must be a dict (JSON object), never a JSON-encoded string.
+- **IMPORTANT:** Always produce the full `alert_condition` tree, not just the changed node.
+  The tool replaces the entire condition tree.
+- **NEVER** recommend condition changes without TSA evidence — schedule changes are the only
+  safe lever without it.

package/bundled-skills/turborepo-caching/SKILL.md

@@ -20,7 +20,6 @@ Production patterns for Turborepo build optimization.
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 ## Use this skill when
 

package/bundled-skills/tutorial-engineer/SKILL.md

@@ -30,7 +30,6 @@ metadata:
  - Clarify goals, constraints, and required inputs.
  - Apply relevant best practices and validate outcomes.
  - Provide actionable steps and verification.
- - If detailed examples are required, open `resources/implementation-playbook.md`.
  
  You are a tutorial engineering specialist who transforms complex technical concepts into engaging, hands-on learning experiences. Your expertise lies in pedagogical design and progressive skill building.
  

package/bundled-skills/typescript-expert/SKILL.md

@@ -27,7 +27,8 @@ You are an advanced TypeScript expert with deep, practical knowledge of type-lev
    
    ```bash
    # Core versions and configuration
-   npx tsc --version
+   # --no-install: never download. Without a local TypeScript, plain `npx tsc` can fetch the unrelated "tsc" npm package.
+   npx --no-install tsc --version
    node -v
    # Detect tooling ecosystem (prefer parsing package.json)
    node -e "const p=require('./package.json');console.log(Object.keys({...p.devDependencies,...p.dependencies}||{}).join('\n'))" 2>/dev/null | grep -E 'biome|eslint|prettier|vitest|jest|turborepo|nx' || echo "No tooling detected"
@@ -48,8 +49,8 @@ You are an advanced TypeScript expert with deep, practical knowledge of type-lev
 4. Validate thoroughly:
    ```bash
    # Fast fail approach (avoid long-lived processes)
-   npm run -s typecheck || npx tsc --noEmit
-   npm test -s || npx vitest run --reporter=basic --no-watch
+   npm run -s typecheck || npx --no-install tsc --noEmit
+   npm test -s || npx --no-install vitest run
    # Only if needed and build affects outputs/config
    npm run -s build
    ```
@@ -110,7 +111,7 @@ type Route = typeof routes[number]; // '/home' | '/about' | '/contact'
 **Type Checking Performance**
 ```bash
 # Diagnose slow type checking
-npx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:"
+npx --no-install tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:"
 
 # Common fixes for "Type instantiation is excessively deep"
 # 1. Replace type intersections with interfaces
@@ -143,8 +144,9 @@ npx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|L
 // types/ambient.d.ts
 declare module 'some-untyped-package' {
   const value: unknown;
-  export default value;
-  export = value; // if CJS interop is needed
+  export default value; // ESM package
+  // OR, for a CommonJS package, use `export = value;` instead.
+  // Do not use both: TypeScript rejects that with TS2309.
 }
 ```
 - For more details: [Declaration Files Guide](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html)
@@ -279,11 +281,11 @@ command -v tsx >/dev/null 2>&1 && npx tsx --inspect src/file.ts
 command -v ts-node >/dev/null 2>&1 && npx ts-node --inspect-brk src/file.ts
 
 # Trace module resolution issues
-npx tsc --traceResolution > resolution.log 2>&1
+npx --no-install tsc --traceResolution > resolution.log 2>&1
 grep "Module resolution" resolution.log
 
 # Debug type checking performance (use --incremental false for clean trace)
-npx tsc --generateTrace trace --incremental false
+npx --no-install tsc --generateTrace trace --incremental false
 # Analyze trace (if installed)
 command -v @typescript/analyze-trace >/dev/null 2>&1 && npx @typescript/analyze-trace trace
 

package/bundled-skills/typescript-expert/scripts/ts_diagnostic.py

@@ -10,13 +10,43 @@ import os
 import json
 from pathlib import Path
 
+TSC = ["npx", "--no-install", "tsc"]
+
 def run_cmd(args):
-    """Run a command as an argument list (no shell) and return its output."""
+    """Run a command as an argument list (no shell). Return (returncode, output)."""
     try:
-        result = subprocess.run(args, capture_output=True, text=True)
-        return result.stdout + result.stderr
-    except Exception as e:
-        return str(e)
+        result = subprocess.run(args, capture_output=True, text=True, errors="replace")
+        return result.returncode, result.stdout + result.stderr
+    except OSError as e:
+        return None, str(e)
+
+def strip_jsonc(text: str) -> str:
+    """Remove // and /* */ comments and trailing commas, which tsconfig.json allows."""
+    out, i, n = [], 0, len(text)
+    while i < n:
+        c = text[i]
+        if c == '"':  # copy a string literal unchanged
+            j = i + 1
+            while j < n and text[j] != '"':
+                j += 2 if text[j] == "\\" else 1
+            out.append(text[i:j + 1])
+            i = j + 1
+        elif text.startswith("//", i):
+            j = text.find("\n", i)
+            i = n if j < 0 else j
+        elif text.startswith("/*", i):
+            j = text.find("*/", i + 2)
+            i = n if j < 0 else j + 2
+        else:
+            if c in "}]":  # drop a trailing comma before the closing bracket
+                k = len(out) - 1
+                while k >= 0 and out[k].isspace():
+                    k -= 1
+                if k >= 0 and out[k] == ",":
+                    del out[k]
+            out.append(c)
+            i += 1
+    return "".join(out)
 
 def grep_source_count(pattern: str, exclude: str | None = None) -> tuple[int, list[str]]:
     """Count and sample lines containing ``pattern`` under ``src/``.
@@ -44,11 +74,11 @@ def check_versions():
     print("\n📦 Versions:")
     print("-" * 40)
     
-    ts_version = run_cmd(["npx", "tsc", "--version"]).strip()
-    node_version = run_cmd(["node", "-v"]).strip()
+    ts_rc, ts_version = run_cmd([*TSC, "--version"])
+    node_rc, node_version = run_cmd(["node", "-v"])
     
-    print(f"  TypeScript: {ts_version or 'Not found'}")
-    print(f"  Node.js: {node_version or 'Not found'}")
+    print(f"  TypeScript: {ts_version.strip() if ts_rc == 0 else 'Not found (no local typescript)'}")
+    print(f"  Node.js: {node_version.strip() if node_rc == 0 else 'Not found'}")
 
 def check_tsconfig():
     """Analyze tsconfig.json settings."""
@@ -61,8 +91,8 @@ def check_tsconfig():
         return
     
     try:
-        with open(tsconfig_path) as f:
-            config = json.load(f)
+        with open(tsconfig_path, encoding="utf-8") as f:
+            config = json.loads(strip_jsonc(f.read()))
         
         compiler_opts = config.get("compilerOptions", {})
         
@@ -155,14 +185,17 @@ def check_type_errors():
     print("\n🔍 Type Check:")
     print("-" * 40)
     
-    result = run_cmd(["npx", "tsc", "--noEmit"])
+    rc, result = run_cmd([*TSC, "--noEmit"])
     lines = result.splitlines()
-    if "error TS" in result:
+    if rc == 0:
+        print("  ✅ No type errors")
+    elif "error TS" in result:
         errors = result.count("error TS")
         print(f"  ❌ {errors}+ type errors found")
         print("\n".join(lines[:20])[:500])
     else:
-        print("  ✅ No type errors")
+        print(f"  ⚠️ Type check did not run (exit code {rc}). Is typescript installed locally?")
+        print("\n".join(lines[:5])[:500])
 
 def check_any_usage():
     """Check for any type usage."""
@@ -193,7 +226,7 @@ def check_performance():
     print("\n⏱️ Type Check Performance:")
     print("-" * 40)
     
-    result = run_cmd(["npx", "tsc", "--extendedDiagnostics", "--noEmit"])
+    _, result = run_cmd([*TSC, "--extendedDiagnostics", "--noEmit"])
     keys = ("Check time", "Files:", "Lines:", "Nodes:")
     lines = [line for line in result.splitlines() if any(k in line for k in keys)]
     if lines:

package/bundled-skills/ui-ux-designer/SKILL.md

@@ -21,7 +21,6 @@ date_added: '2026-02-27'
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 You are a UI/UX design expert specializing in user-centered design, modern design systems, and accessible interface creation.
 

package/bundled-skills/ui-visual-validator/SKILL.md

@@ -21,7 +21,6 @@ date_added: '2026-02-27'
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 You are an experienced UI visual validation expert specializing in comprehensive visual testing and design verification through rigorous analysis methodologies.
 

package/bundled-skills/uniprot-database/SKILL.md

@@ -8,6 +8,14 @@ risk: safe
 source: community
 date_added: "2026-09-04"
 ---
+## Supporting material availability
+
+This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:
+
+- `<support-root>/scripts/uniprot_client.py`
+
+Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.
+
 
 # UniProt Database
 

package/bundled-skills/unity-developer/SKILL.md

@@ -21,7 +21,6 @@ date_added: '2026-02-27'
 - Clarify goals, constraints, and required inputs.
 - Apply relevant best practices and validate outcomes.
 - Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
 
 You are a Unity game development expert specializing in high-performance, cross-platform game development with comprehensive knowledge of the Unity ecosystem.
 

package/bundled-skills/usage-based-pricing/SKILL.md

@@ -18,7 +18,7 @@ Read [the detailed guide](references/detailed-guide.md) before executing this sk
 
 ## When to Use
 
-Use this skill when you need design pricing models that developers understand, accept, and can predict. Trigger phrases: usage-based pricing, API pricing, metered billing, developer pricing, pricing page, cost calculator, pay as you go, pricing transparency, competitive pricing, developer billing.
+Use this skill when you need to design pricing models that developers understand, accept, and can predict. Trigger phrases: usage-based pricing, API pricing, metered billing, developer pricing, pricing page, cost calculator, pay as you go, pricing transparency, competitive pricing, developer billing.
 
 
 Design pricing models that developers understand, accept, and can predict—without surprise bills or confusing metrics.
@@ -96,9 +96,11 @@ Actual usage is unpredictable.
 
 ## Examples: Pricing That Works
 
+Provider names illustrate pricing structures, not current price/plan endorsements. Verify each current regional plan and fee schedule from its official source before comparison or quoting. Designing a model does not authorize live billing changes.
+
 ### Stripe
 
-- Per-transaction percentage (2.9% + 30¢)
+- Percentage plus fixed-fee structure; verify the current country, currency and payment-method schedule before quoting a rate
 - Aligns with customer revenue
 - Predictable and simple
 - Volume discounts for scale

package/bundled-skills/usage-based-pricing/references/detailed-guide.md

@@ -11,11 +11,13 @@ The best developer pricing is predictable, transparent, and obviously fair. Deve
 
 ## Before You Start
 
-Review the `/devmarketing-skills/skills/free-tier-strategy` skill to understand how free tiers connect to paid pricing. Your pricing model should feel like a natural extension of the free tier, not a completely different experience.
+Read the product's existing plan, free-tier rules, usage meters and constraints. The related `free-tier-strategy` guidance is optional and may not be installed; do not assume an upstream absolute directory exists.
 
 
 ## Pricing Page Clarity
 
+All monetary examples and provider comparisons below are illustrative, not current quotes or promised savings. Use supplied evidence, verified current prices and explicit units; unknown inputs remain unknown. No calculation authorizes changing a plan, charging a customer or making a compliance claim.
+
 ### Essential Pricing Page Elements
 
 1. **Price per unit, clearly stated**
@@ -186,7 +188,7 @@ Total: $54.12
 **API for usage data:**
 ```bash
 curl https://api.example.com/usage \
-  -H "Authorization: Bearer sk_live_xxx"
+  -H "Authorization: Bearer $API_TOKEN"
 
 {
   "period": "2024-03-01/2024-03-31",
@@ -243,17 +245,17 @@ For enterprise sales, provide ROI tools:
 ```
 Your company:
 - Developers: [10]
-- Hours/week on auth: [5]
+- Hours/week on auth per developer: [5]
 - Fully-loaded cost/hour: [$150]
 
-Current cost: $3,000/week = $156,000/year
+Current cost: 10 × 5 × $150 = $7,500/week = $390,000/year (52 weeks)
 
 With [Product]:
 - Integration: 20 hours one-time = $3,000
 - Annual cost: $12,000
 - Maintenance: Near zero
 
-First year savings: $141,000
+Illustrative first year savings: $390,000 - $3,000 - $12,000 = $375,000
 ```
 
 ### Pricing Justification
@@ -263,7 +265,7 @@ When prices seem high, justify with:
 2. **Reliability** - "99.99% uptime saves you from outages"
 3. **Support** - "Engineering support, not offshore scripts"
 4. **Scale** - "Handles 10x traffic without config changes"
-5. **Security** - "SOC 2, GDPR, HIPAA included"
+5. **Security** - Cite the actual control evidence and the scope/date of any independent assessment; do not call legal compliance "included"
 
 
 ## Competitive Pricing Research
@@ -402,6 +404,6 @@ Developers share horror stories:
 
 ## Related Skills
 
-- `/devmarketing-skills/skills/free-tier-strategy` - Free tier design
-- `/devmarketing-skills/skills/developer-signup-flow` - Getting to the pricing page
-- `/devmarketing-skills/skills/developer-onboarding` - Demonstrating value before price
+- `@free-tier-strategy` - Free tier design
+- `@developer-signup-flow` - Getting to the pricing page
+- `@developer-onboarding` - Demonstrating value before price

package/bundled-skills/using-agent-skills/SKILL.md

@@ -12,6 +12,9 @@ license: MIT
 license_source: https://github.com/addyosmani/agent-skills/blob/main/LICENSE
 compatibility: Portable instruction skill; no CLI, MCP server, or network access required.
 ---
+## Bundled upstream support
+
+Supporting files are included at skill-relative paths. See [UPSTREAM-NOTICE.md](UPSTREAM-NOTICE.md) for their pinned sources, licenses, hashes, and import changes.
 
 # Using Agent Skills
 
@@ -121,7 +124,7 @@ Your job is surgical precision, not unsolicited renovation.
 
 Every skill includes a verification step. A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence (passing tests, build output, runtime data).
 
-Per-skill verification is the local check. The project-wide bar that applies to *every* change, regardless of which skill is active, is the Definition of Done: tests pass, no regressions, behavior verified at runtime, docs updated. See `../../references/definition-of-done.md`. It complements each task's acceptance criteria rather than replacing them.
+Per-skill verification is the local check. The project-wide bar that applies to *every* change, regardless of which skill is active, is the Definition of Done: tests pass, no regressions, behavior verified at runtime, docs updated. See `references/definition-of-done.md`. It complements each task's acceptance criteria rather than replacing them.
 
 ## Failure Modes to Avoid
 

package/bundled-skills/using-agent-skills/UPSTREAM-LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Addy Osmani
+
+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/bundled-skills/using-agent-skills/UPSTREAM-NOTICE.md

@@ -0,0 +1,11 @@
+# Upstream helpers for using-agent-skills
+
+The files listed below were recovered from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) at commit `aeac41d4d005999432bb7312f7ff06383a91d59d`. The repository ID is `1158722119`.
+
+They retain the upstream **MIT** license reproduced in [UPSTREAM-LICENSE.txt](UPSTREAM-LICENSE.txt). This notice applies to the listed support files; it does not replace the license metadata of other catalog files. Preserve the upstream license and this attribution when redistributing them.
+
+License wording is unchanged; text-only trailing whitespace and EOF blank lines are normalized. Original license: https://github.com/addyosmani/agent-skills/blob/aeac41d4d005999432bb7312f7ff06383a91d59d/LICENSE
+
+| Local file | Original upstream path | Original Git blob SHA | Import changes |
+| --- | --- | --- | --- |
+| `references/definition-of-done.md` | `references/definition-of-done.md` | `35e39f9e15f6dd0ff4725a6e5cbce7f2aa69064a` | text-only trailing whitespace and EOF blank lines normalized |