rsc-universal 0.1.1

package/skills/tiktok-api/references/metrics-and-publish.md

@@ -0,0 +1,127 @@
+# Publish call bodies + the metric catalog split by API
+
+Copy-paste request shapes for the full publish flow and the exact field split between
+Display (counters) and Business (rich insights).
+
+## Publish — FILE_UPLOAD init
+
+```json
+POST https://open.tiktokapis.com/v2/post/publish/video/init/
+Authorization: Bearer <access_token>
+Content-Type: application/json; charset=UTF-8
+
+{
+  "post_info": {
+    "title": "caption text #fyp",
+    "privacy_level": "SELF_ONLY",
+    "disable_comment": false,
+    "disable_duet": false,
+    "disable_stitch": false
+  },
+  "source_info": {
+    "source": "FILE_UPLOAD",
+    "video_size": 10485760,
+    "chunk_size": 10485760,
+    "total_chunk_count": 1
+  }
+}
+```
+
+Response `data` carries `publish_id` and `upload_url`.
+
+### Chunk math (the part people get wrong)
+
+- Chunk size **min 5 MB, max 64 MB**; the **final** chunk may run up to **128 MB**.
+- **1–1000 chunks** total, uploaded **sequentially**.
+- A file **under 5 MB is a single chunk** whose `chunk_size` equals the file size and
+  `total_chunk_count` is 1.
+- Each `PUT` to `upload_url` carries `Content-Range: bytes {first}-{last}/{total}` and
+  returns **206** (more to send) or **201** (final chunk accepted).
+
+```python
+# the PUT loop, expanded
+with open(path, "rb") as f:
+    for i in range(total_chunk_count):
+        first = i * chunk_size
+        blob = f.read(chunk_size)
+        last = first + len(blob) - 1
+        r = requests.put(upload_url, data=blob, headers={
+            "Content-Type": "video/mp4",
+            "Content-Range": f"bytes {first}-{last}/{video_size}",
+        })
+        assert r.status_code in (206, 201), (r.status_code, r.text)
+```
+
+## Publish — PULL_FROM_URL init
+
+Requires a **verified** domain/URL-prefix (see oauth-setup.md §6), HTTPS, no redirects.
+
+```json
+POST https://open.tiktokapis.com/v2/post/publish/video/init/
+
+{
+  "post_info": { "title": "caption #fyp", "privacy_level": "SELF_ONLY" },
+  "source_info": {
+    "source": "PULL_FROM_URL",
+    "video_url": "https://verified.example.com/clips/clip.mp4"
+  }
+}
+```
+
+No chunk PUT needed — TikTok fetches the file itself. Then poll status as usual.
+
+## Upload to draft (inbox)
+
+For "let the user finish/post it in-app," swap the endpoint to
+`https://open.tiktokapis.com/v2/post/publish/inbox/video/init/` with scope
+`video.upload`. Same `source_info`/chunk rules; the video lands in the user's drafts.
+
+## Status poll
+
+```json
+POST https://open.tiktokapis.com/v2/post/publish/status/fetch/
+{ "publish_id": "<publish_id>" }
+```
+
+`data.status` walks through `PROCESSING_UPLOAD` / `SEND_TO_USER_INBOX` →
+`PUBLISH_COMPLETE` or `FAILED`. Poll on a sleep, never a tight loop —
+**6 requests/minute per user token** or you hit `rate_limit_exceeded`.
+
+## Metric catalog — which API returns what
+
+### Display API — `POST /v2/video/query/` (counters only)
+
+Pass `fields` as a query param; filter by `video_ids` (**≤20 per request**). Scope
+`video.list`. Returns ONLY:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Video id |
+| `title` | Caption/title |
+| `view_count` | Total views |
+| `like_count` | Likes |
+| `comment_count` | Comments |
+| `share_count` | Shares |
+| `duration` | Video length (s) |
+| `create_time` | Post timestamp |
+
+There is **no watch-time, completion, or impression-source field here.** Asking for one
+returns nothing — that is the wrong-API assumption `verify.sh` flags.
+
+### Business Account API — video list + insights (the rich metrics)
+
+The engagement signal lives only here:
+
+| Field | Meaning |
+| --- | --- |
+| `average_time_watched` | Mean seconds watched per view |
+| `total_time_watched` | Aggregate watch time |
+| `full_video_watched_rate` | Completion rate (watched to the end) |
+| `impression_sources` | Traffic breakdown: For You / Following / personal profile / search / sound |
+| `audience_countries` | Top viewer geographies |
+
+### Lag caveat
+
+Business insight metrics **lag 24–48h** and can differ from the in-app numbers. A pull
+within ~2 days of posting is **provisional** — log it, then watch it settle across
+later pulls (this is exactly why the wiki log appends instead of overwriting).

package/skills/tiktok-api/references/oauth-setup.md

@@ -0,0 +1,105 @@
+# OAuth v2 setup, scopes, audit gate, and token lifecycle
+
+Everything needed to go from "no app" to "an authed, self-refreshing TikTok client."
+There is **no official TikTok SDK** — all calls are raw REST.
+
+## 1. Register the app and enable products
+
+1. Create a developer app in the TikTok for Developers portal.
+2. Add **products** the job needs — each is a separate toggle:
+   - **Login Kit** — the OAuth v2 flow (required for everything).
+   - **Content Posting API** — to publish/upload video.
+   - **Display API** — to read your own profile + basic video counters.
+3. **Business insights are separate.** Watch time, completion, and impression sources
+   come from the **TikTok API for Business**, enabled through the business portal /
+   business account access — not the standard developer-app product toggles.
+4. Set an exact **redirect URI** (must match byte-for-byte at authorize + exchange time).
+
+## 2. The three gates (the part that surprises people)
+
+| Gate | Controls | How you pass it |
+| --- | --- | --- |
+| Content Posting **audit** | Public posting for arbitrary users | Submit app for review; until then **SELF_ONLY + test users only** |
+| Display **scope** | Reading your own video counts | Request `video.list`; user authorizes it |
+| Business **portal** access | Watch time / completion / impression sources | Enable business account access separately |
+
+Unaudited apps can only post **privately** (`privacy_level: "SELF_ONLY"`) and only to a
+limited set of registered test users. This is the #1 "works in dev, breaks in prod"
+failure — public posting for real users requires the audit to pass first.
+
+## 3. Scope catalog
+
+| Scope | Grants |
+| --- | --- |
+| `user.info.basic` | open_id, display name, avatar |
+| `video.list` | Read your own videos + basic counters (Display API) |
+| `video.publish` | Direct Post to the public feed (audit-gated) |
+| `video.upload` | Upload to drafts/inbox for the user to finalize |
+
+Request least privilege. A read-only daily-pull cron needs only `video.list`
+(+ `user.info.basic`); add `video.publish` only on the path that actually posts.
+
+## 4. Authorize → exchange
+
+Send the user to the authorize URL:
+
+```text
+https://www.tiktok.com/v2/auth/authorize/
+  ?client_key=<CLIENT_KEY>
+  &scope=video.publish,video.list,user.info.basic
+  &response_type=code
+  &redirect_uri=<EXACT_REDIRECT_URI>
+  &state=<csrf_token>
+  &code_challenge=<S256>&code_challenge_method=S256   # PKCE recommended
+```
+
+Exchange the returned `code` for tokens:
+
+```python
+import requests, os
+r = requests.post("https://open.tiktokapis.com/v2/oauth/token/", data={
+    "client_key": os.environ["TIKTOK_CLIENT_KEY"],
+    "client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
+    "grant_type": "authorization_code",
+    "code": code,
+    "redirect_uri": REDIRECT_URI,
+    "code_verifier": pkce_verifier,        # if you used PKCE
+}, headers={"Content-Type": "application/x-www-form-urlencoded"})
+tok = r.json()
+# { access_token, expires_in: 86400, refresh_token, refresh_expires_in: 31536000, open_id, scope }
+```
+
+## 5. Token lifecycle — the load-bearing rule
+
+- **Access token: 24 hours** (`expires_in: 86400`).
+- **Refresh token: 365 days** (`refresh_expires_in: 31536000`); refresh needs no
+  user re-consent and **rotates** the refresh token each time.
+
+Therefore:
+
+- A daily cron MUST refresh the access token **every run** (see the `access_token()`
+  helper in SKILL.md §2) and **persist the new refresh_token** returned each time.
+- An account left idle past **365 days** silently dies at the refresh-token boundary —
+  the only fix is re-running the OAuth consent flow.
+
+## 6. PULL_FROM_URL domain verification
+
+`PULL_FROM_URL` publishing requires the source domain or URL-prefix to be verified in
+the portal before any init succeeds:
+
+- Add the domain/URL-prefix in the portal; complete **DNS TXT signature** or
+  **URL-prefix** verification.
+- The source URL must be **HTTPS**, **no redirects**, and download within the
+  **1-hour** timeout.
+- An unverified domain returns `url_ownership_unverified` on every init.
+
+## 7. Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `scope_not_authorized` | Scope not granted or app not approved for it | Re-consent with the scope; check app approval |
+| `access_token_invalid` | 24h access token expired or wrong token | Refresh before the call; never hardcode |
+| Only `SELF_ONLY` posts succeed | App not audited | Submit for audit; use test users meanwhile |
+| `url_ownership_unverified` | PULL_FROM_URL domain not verified | Verify domain/URL-prefix (DNS TXT) |
+| Refresh returns an error after long idle | 365-day refresh token expired | Re-run the authorize → exchange flow |
+| Redirect mismatch at exchange | `redirect_uri` differs from the registered one | Match it byte-for-byte |

package/skills/tiktok-api/references/wiki-schema.md

@@ -0,0 +1,85 @@
+# Wiki schema for `02-DOCS/wiki/shortform/`
+
+How a TikTok pull becomes durable, queryable account history the shortform siblings
+read. The rule that matters: **append, never overwrite.** A snapshot that replaces
+yesterday's destroys the trend — and erases the 24–48h metric settling you only see
+across pulls.
+
+## File tree
+
+```text
+02-DOCS/wiki/shortform/
+  index.md                       # rolling pointer: latest snapshot per platform + open questions
+  tiktok-account-2026-06-02.md   # dated account snapshot, one file per pull
+  tiktok-account-2026-06-09.md
+  videos/
+    tiktok-<video_id>.md         # per-video running log, newest entry on top
+```
+
+### Why the `tiktok-` prefix
+
+The `shortform/` wiki may also hold Instagram and YouTube pulls (sibling transport
+skills write here too). Platform-namespacing the filenames keeps cross-platform pulls
+from colliding and lets a sibling grep `tiktok-*` for just this account.
+
+## Account snapshot entry (one file per pull)
+
+```markdown
+---
+date: 2026-06-02
+range: 2026-05-26..2026-06-01
+account: <open_id>
+platform: tiktok
+source: display-api + business-account-api
+provisional: true            # set while inside the 24–48h metric-lag window
+---
+## KPIs
+views: 52,140 | likes: 3,902 | comments: 211 | shares: 488
+
+## Watch
+full_video_watched_rate: 28.4% | avg_time_watched: 6.1s | total_time_watched: 88h
+
+## Impression sources (top 3)
+For You 71% · Personal profile 14% · Search 7%
+
+## What changed since last pull
+completion +3.1pts after the tighter cold-open; FYP share up 5pts.
+```
+
+## Per-video running log (`videos/tiktok-<id>.md`)
+
+Newest entry on top, so a glance shows the latest. Each pull **prepends** a block —
+this is where the 24–48h settling becomes visible (the same video's
+`full_video_watched_rate` will drift between pulls).
+
+```markdown
+# tiktok-7399... — "cold open hook test"
+posted: 2026-05-28 | duration: 21s
+
+## 2026-06-02 (final-ish)
+views 52,140 | completion 28.4% | avg_watched 6.1s | FYP 71%
+
+## 2026-05-29 (provisional, <48h)
+views 18,900 | completion 24.1% | avg_watched 5.3s | FYP 64%
+```
+
+## index.md
+
+A thin pointer, not a data dump:
+
+```markdown
+# shortform wiki — index
+- tiktok: latest snapshot → tiktok-account-2026-06-02.md
+- open questions:
+  - is the cold-open change holding completion above 27%? (watch next 2 pulls)
+```
+
+## Rules
+
+- **Append, never overwrite.** New pull → new dated snapshot file + prepended per-video
+  block. Never edit a past snapshot in place.
+- **Mark provisional pulls.** Set `provisional: true` (or a label) while inside the
+  24–48h lag window; the next pull supersedes it without deleting it.
+- **Namespace by platform.** `tiktok-` prefix on every file so IG/YouTube pulls coexist.
+- **Numbers only, no interpretation.** "What changed" is a factual delta line, not a
+  recommendation — what to *do* about it belongs to `shortform-strategy`.

package/skills/tiktok-api/scripts/verify.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# verify.sh — static, no-network preflight linter for TikTok API integration code.
+# Read-only. Flags the patterns this skill bans. Exits 0 on a clean/empty target,
+# non-zero with file:line on any hit.
+#
+# Usage: scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+hits=0
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify.sh: target '$TARGET' is not a directory" >&2
+  exit 2
+fi
+
+report() { echo "FAIL [$1] $2"; hits=$((hits + 1)); }
+
+# Files we scan: source + config, skipping vendored/build/VCS dirs. (bash 3.2 compatible)
+FILES=()
+while IFS= read -r _f; do
+  [ -n "$_f" ] && FILES+=("$_f")
+done < <(
+  find "$TARGET" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/dist/*' \
+       -o -path '*/build/*' -o -path '*/.venv/*' -o -path '*/venv/*' \) -prune -o \
+    -type f \( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.mjs' \
+       -o -name '*.json' -o -name '*.env' -o -name '*.yaml' -o -name '*.yml' \) -print 2>/dev/null
+)
+
+# (1) Committed TikTok secrets: a tracked token file containing a refresh_token.
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  if grep -lqs 'refresh_token' "$f" 2>/dev/null; then
+    report "tracked-token" "$f: token file contains a refresh_token — do not commit it (gitignore it)"
+  fi
+done < <(find "$TARGET" \( -path '*/.git/*' \) -prune -o -type f \
+           \( -name '*tiktok*token*.json' -o -name 'tiktok_token.json' -o -name 'token*.json' \) -print 2>/dev/null)
+
+# Per-file content scans.
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  [ -f "$f" ] || continue
+
+  # (1b) Hardcoded client_secret literal in source.
+  while IFS= read -r line; do
+    report "client-secret" "$f:$line client_secret assigned a literal — load from env/secret store"
+  done < <(grep -niE 'client_secret[[:space:]]*[:=][[:space:]]*["'"'"'][A-Za-z0-9_-]{8,}' "$f" 2>/dev/null \
+            | grep -viE 'os\.environ|process\.env|getenv|<|placeholder|your_|example|xxxx' | cut -d: -f1)
+
+  # (2) Hardcoded access_token / Bearer literal instead of a refreshable credential object.
+  while IFS= read -r line; do
+    report "hardcoded-token" "$f:$line hardcoded access_token/Bearer literal — use a refreshable credential (24h expiry)"
+  done < <(grep -niE 'access_token[[:space:]]*[:=][[:space:]]*["'"'"'][A-Za-z0-9._-]{12,}|Bearer[[:space:]]+[A-Za-z0-9._-]{20,}' "$f" 2>/dev/null \
+            | grep -viE 'os\.environ|process\.env|getenv|access_token\(\)|\{|\$|f"|`|<|your_|example|placeholder' | cut -d: -f1)
+
+  # Code-structure checks only meaningful in source files, not config/prose.
+  case "$f" in
+    *.py|*.js|*.ts|*.mjs) ;;
+    *) continue ;;
+  esac
+
+  # (3) FILE_UPLOAD publish path with no Content-Range chunked PUT and no status poll.
+  if grep -qsE 'post/publish/.*init/' "$f" 2>/dev/null && grep -qs 'FILE_UPLOAD' "$f" 2>/dev/null; then
+    if ! grep -qsE 'Content-Range' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'FILE_UPLOAD' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-chunked-put" "$f:${ln:-1} FILE_UPLOAD init but no Content-Range chunked PUT (transfer step missing)"
+    fi
+    if ! grep -qsE 'status/fetch|publish_id' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'FILE_UPLOAD' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-status-poll" "$f:${ln:-1} publish init but no status/fetch poll on publish_id (async result unconfirmed)"
+    fi
+  fi
+
+  # (4) Wrong-API assumption: reading watch-time/completion fields off the Display video/query response.
+  if grep -qsE 'video/query' "$f" 2>/dev/null; then
+    while IFS= read -r line; do
+      report "wrong-api" "$f:$line watch-time/completion field near Display video/query — those come from the Business API, not Display"
+    done < <(grep -nE 'average_time_watched|full_video_watched_rate|total_time_watched|impression_sources' "$f" 2>/dev/null | cut -d: -f1)
+  fi
+
+  # (5) Publish/status calls with no backoff/throttle helper around the 6/min cap.
+  if grep -qsE 'post/publish/.*(init|status/fetch)' "$f" 2>/dev/null; then
+    if ! grep -qsiE 'sleep|backoff|retry|throttle|rate.?limit|time\.sleep|setTimeout' "$f" 2>/dev/null; then
+      ln=$(grep -nE 'post/publish/' "$f" 2>/dev/null | head -1 | cut -d: -f1)
+      report "no-throttle" "$f:${ln:-1} publish/status calls with no sleep/backoff/throttle (6 req/min cap → rate_limit_exceeded)"
+    fi
+  fi
+done
+
+if [ "$hits" -gt 0 ]; then
+  echo "verify.sh: $hits issue(s) found" >&2
+  exit 1
+fi
+echo "OK: no banned TikTok-API patterns found in '$TARGET'"
+exit 0

package/skills/together-fireworks/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: together-fireworks
+description: "Use when calling hosted open-model inference on Together AI or Fireworks AI — pointing the OpenAI SDK at api.together.ai or api.fireworks.ai, picking an open model (Llama, DeepSeek, Qwen, GPT-OSS) and what it costs, or cutting the bill with batch inference. Triggers: 'call DeepSeek/Llama on Together', 'wire the OpenAI SDK to Fireworks', 'why is my model name 404ing', 'which open-source model and how much per million tokens', 'halve my LLM bill with batch', 'move off GPT-4 to a cheaper open-weights endpoint', 'serverless vs dedicated for sustained QPS', '¿qué modelo open source uso y cuánto cuesta?', 'abaratar la factura de inferència'. NOT renting raw GPUs to self-host weights (that is runpod), NOT running a model locally with zero marginal cost (that is ollama)."
+tags: [llm, inference, together-ai, fireworks-ai, openai-compatible, open-models, batch, cost]
+recommends: [runpod, modal, ollama, huggingface, fal, cost-tracking, llm-pipeline, prompt-engineering, embeddings-search]
+origin: risco
+---
+
+# together-fireworks
+
+You run open-weight LLMs on two neutral, OpenAI-compatible hosts: **Together AI** and **Fireworks AI**. Neither trains the flagship models — they host open weights (Llama, DeepSeek, Qwen, GPT-OSS, Kimi, Mistral) behind a billed-per-token endpoint. No GPU to provision, no server to babysit. You pay for tokens.
+
+Both speak the OpenAI wire protocol. So the entire mental model is: **same SDK, change three things — `base_url`, `api_key`, and the model id.** That is why these two providers live in one skill: the working knowledge (connect, pick a model, batch for 50% off, do the cost math) is ~90% shared. The only real differences are the base URL string and the model-id naming scheme. Learn both at once.
+
+This skill is *where the tokens come from*. Designing the prompt is `../prompt-engineering/SKILL.md`; chaining calls into a workflow is `../llm-pipeline/SKILL.md`; tracking spend across many providers as a discipline is `../cost-tracking/SKILL.md`. Here you only do the per-model math and the endpoint plumbing.
+
+## The two endpoints (memorize these)
+
+| Provider | `base_url` | Model id shape | Examples (illustrative — confirm on the serverless catalog) |
+|---|---|---|---|
+| Together | `https://api.together.ai/v1` | `<vendor>/<model>` | `openai/gpt-oss-20b`, `meta-llama/Llama-3.3-70B-Instruct-Turbo`, `deepseek-ai/DeepSeek-V4-Pro` |
+| Fireworks | `https://api.fireworks.ai/inference/v1` | `accounts/fireworks/models/<name>` | `accounts/fireworks/models/gpt-oss-20b`, `accounts/fireworks/models/llama-v3p1-8b-instruct` |
+
+The example ids show the *shape* of a valid id, not a guaranteed-live id — the catalog churns and casing matters. Before you ship any id, confirm the exact string on the provider's own catalog (docs.together.ai/docs/serverless-models, docs.fireworks.ai/serverless/pricing). A plausible-looking id that is not in the catalog 404s exactly like a typo, so an unconfirmed id is a bug, not a default.
+
+The #1 failure is a bare model name. `model="llama-3.3-70b"` returns **404 model not found** on both — the id MUST carry its namespace prefix.
+
+## Connect in 30 seconds
+
+Use the official `openai` SDK. Do not install a provider-specific client unless you need a provider-only feature (Together's native Batch API, below).
+
+```python
+import os
+from openai import OpenAI
+
+# Together
+together = OpenAI(
+    base_url="https://api.together.ai/v1",
+    api_key=os.environ["TOGETHER_API_KEY"],   # never a string literal
+)
+r = together.chat.completions.create(
+    model="openai/gpt-oss-20b",               # namespaced — vendor/model
+    messages=[{"role": "user", "content": "Classify: spam or ham?"}],
+)
+
+# Fireworks — same SDK, three things change
+fireworks = OpenAI(
+    base_url="https://api.fireworks.ai/inference/v1",
+    api_key=os.environ["FIREWORKS_API_KEY"],
+)
+r = fireworks.chat.completions.create(
+    model="accounts/fireworks/models/gpt-oss-120b",  # accounts/fireworks/models/<name>
+    messages=[{"role": "user", "content": "Explain this stack trace."}],
+)
+```
+
+```javascript
+import OpenAI from "openai";
+
+const fireworks = new OpenAI({
+  baseURL: "https://api.fireworks.ai/inference/v1",
+  apiKey: process.env.FIREWORKS_API_KEY,
+});
+
+const r = await fireworks.chat.completions.create({
+  model: "accounts/fireworks/models/llama-v3p1-8b-instruct", // namespaced
+  messages: [{ role: "user", content: "Summarize in one line." }],
+});
+```
+
+- **Bad → Good (model id):** `model="gpt-oss-120b"` → `model="openai/gpt-oss-120b"` (Together) or `model="accounts/fireworks/models/gpt-oss-120b"` (Fireworks). Why: the compat layer routes by the full namespaced id; a bare name has no route → 404.
+- **Bad → Good (base_url):** `base_url="https://api.openai.com/v1"` with a Together key → auth error / wrong models. Why: a Together/Fireworks key only authenticates against its own host.
+- **Bad → Good (key):** `api_key="sk-..."` literal → `api_key=os.environ["TOGETHER_API_KEY"]`. Why: a committed key is a leaked key.
+
+`client.embeddings.create()` works identically on both for embedding models — same surface, just swap the model id.
+
+## Pick the model
+
+Match the task to the smallest model that clears the quality bar. Every $/1M figure below is **per 1M tokens, input/output, USD**, read directly off each **provider's own pricing page** on 2026-06-02 (Together: together.ai/pricing; Fireworks: docs.fireworks.ai/serverless/pricing) — never a tracker. Confirm the exact id string and rate at that page before you ship; casing and suffixes (`-Turbo`, `-Lite`) are load-bearing, and a plausible id absent from the catalog 404s like a typo.
+
+Rows tagged **(projected)** are current-generation flagships whose id and price move fast and that you may not recognize from older training data — the number is the page's figure on 2026-06-02, but re-read the page before you quote one. Untagged rows are long-lived ids with stable pricing; the worked examples and defaults below lean on these on purpose.
+
+| Task | Together id + $/1M (in/out) | Fireworks id + $/1M (in/out) |
+|---|---|---|
+| Cheap classify / extract / tag | `openai/gpt-oss-20b` — $0.05 / $0.20 | `accounts/fireworks/models/gpt-oss-20b` — $0.07 / $0.30 |
+| Small instruct | `meta-llama/Meta-Llama-3-8B-Instruct-Lite` — $0.14 / $0.14 | `accounts/fireworks/models/llama-v3p1-8b-instruct` — 4B–16B tier, $0.20 |
+| General chat | `meta-llama/Llama-3.3-70B-Instruct-Turbo` — $1.04 / $1.04 | `accounts/fireworks/models/gpt-oss-120b` — $0.15 / $0.60 |
+| Reasoning / hard tasks | `deepseek-ai/DeepSeek-V4-Pro` — $2.10 / $4.40 *(projected)* | `accounts/fireworks/models/deepseek-v4-pro` — $1.74 / $3.48 *(projected)* |
+| Cheaper reasoning | `Qwen/Qwen3.6-Plus` — $0.50 / $3.00 (watch output) *(projected)* | `accounts/fireworks/models/deepseek-v4-flash` — $0.14 / $0.28 *(projected)*; `kimi-k2p6` — $0.95 / $4.00 *(projected)* |
+| Long context (≥512K) | `Qwen/Qwen3.6-Plus` (1M ctx) *(projected)*; `deepseek-ai/DeepSeek-V4-Pro` (512K serverless) *(projected)* | size/MoE tier — see fallback below |
+| Embeddings | `intfloat/multilingual-e5-large-instruct` — $0.02 / 1M input | embeddings — $0.008–$0.10 / 1M input (by param count) |
+
+Rules:
+- **Output tokens cost 3–7× input.** A reasoning model that thinks for 2k tokens before answering is the expensive part — budget on output, not input. Qwen3.6-Plus is the trap: $0.50 in but $3.00 out.
+- **Fireworks size-tiered fallback** (published on docs.fireworks.ai/serverless/pricing, applies to any model with no named price): <4B $0.10, 4B–16B $0.20, >16B (dense) $0.90, MoE ≤56B $0.50, MoE 56.1B–176B $1.20 per 1M. Use the matching tier to estimate a model not in the named list — these are the provider's own published numbers, so they hold up in a quote (still confirm the specific model's tier).
+- **Default to the cheap small model and only escalate when an eval shows it fails.** Most "we need DeepSeek V4-Pro" is a gpt-oss-20b job in disguise.
+
+Fuller catalog and embedding/fine-tuning numbers: `references/models-and-pricing.md`.
+
+## Serverless vs Batch vs Dedicated
+
+| Serving mode | Use when | The economics |
+|---|---|---|
+| **Serverless** (default) | Real-time, user-facing, bursty, low/spiky volume | Pay per token, no commitment, cold-tolerant |
+| **Batch** | Offline job, no latency need, > ~1k requests | **~50% off** serverless on both providers |
+| **Dedicated** GPU | Sustained high QPS, fixed latency SLA, huge volume | Pay for the GPU-hour; pays off only above a high, steady load |
+
+Decision: **real-time → serverless. Big offline job (eval, synthetic data, bulk classify) → batch. Sustained heavy traffic with an SLA → dedicated.**
+
+> **Gotcha — Together batch is NOT the OpenAI Batch endpoint.** Together's OpenAI-compat layer does **not** expose `/v1/batches`. Use Together's **native Batch API**: upload a JSONL file, default **24h** window, up to **50,000 requests/file**, up to **50% off**, separate rate-limit pool. Pointing the OpenAI Batch client at Together fails. Fireworks instead exposes Batch as a serving *path* through the one API (Serverless 2.0: Standard / Priority / Batch), batch = 50% of serverless. See `references/batch-and-tuning.md`.
+
+Two more Fireworks multipliers worth knowing:
+- **Cached input tokens default to 50%** of input price (text/vision models) — repeated prefixes get cheaper automatically.
+- **Priority serving ≈ 1.5× Standard.** Priority is opt-in, not the default; do not budget at Priority rates unless you set it.
+
+## Cost & latency math
+
+Per request:
+
+```text
+cost = (in_tokens * in_price_per_1M + out_tokens * out_price_per_1M) / 1_000_000
+```
+
+Apply the multipliers: cached input → `in_price * 0.5` on the cached portion; Priority → `* 1.5`; Batch → `total * 0.5`.
+
+Worked example — 1,000,000 input + 500,000 output tokens, one shot. Both anchors are **stable** ids (gpt-oss, Llama 3.3 70B), so the arithmetic stays checkable even after the flagship rows churn:
+
+- **GPT-OSS 20B on Together**, serverless: `(1M*0.05 + 0.5M*0.20)/1e6 = $0.05 + $0.10 = $0.15`.
+- **GPT-OSS 120B on Together**, serverless: `(1M*0.15 + 0.5M*0.60)/1e6 = $0.15 + $0.30 = $0.45` — 3× the 20B for the bigger open GPT-OSS.
+- **Llama 3.3 70B on Together**, serverless: `(1M*1.04 + 0.5M*1.04)/1e6 = $1.04 + $0.52 = $1.56` — ~10× the 20B for general chat.
+- Same Llama 3.3 70B job **as batch**: `$1.56 * 0.5 = $0.78`.
+- Escalating to a *(projected)* reasoning flagship (e.g. DeepSeek V4-Pro at $2.10/$4.40 on the 2026-06-02 page) lands near `$4.30` serverless / `$2.15` batch — ~29× the 20B — but re-read the page before you commit to that number.
+
+So for a large offline run the lever is *model choice first* (up to ~29×), *batch second* (2×). Pick the smallest model that passes the eval AND batch it. Realtime is only worth its premium when a human is waiting.
+
+## Write provider-agnostic code
+
+Drive `base_url` and `model` from env so you can switch providers (or arbitrage price) without touching code. Why: these are commodity endpoints — portability is leverage.
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    base_url=os.environ["LLM_BASE_URL"],   # together or fireworks URL
+    api_key=os.environ["LLM_API_KEY"],
+)
+model = os.environ["LLM_MODEL"]            # the namespaced id for that provider
+```
+
+Equivalent ids for the same underlying model:
+
+| Model | Together id | Fireworks id |
+|---|---|---|
+| Llama 3.1 8B Instruct | `meta-llama/Llama-3.1-8B-Instruct-Turbo` | `accounts/fireworks/models/llama-v3p1-8b-instruct` |
+| DeepSeek V4-Pro | `deepseek-ai/DeepSeek-V4-Pro` | `accounts/fireworks/models/deepseek-v4-pro` |
+| GPT-OSS 20B | `openai/gpt-oss-20b` | `accounts/fireworks/models/gpt-oss-20b` |
+
+Keep the id mapping in config, not in `if provider == ...` branches scattered through the code.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Bare model name (`llama-3.3-70b`) | 404 model not found — the route needs the namespace | Use the full `<vendor>/...` or `accounts/fireworks/models/...` id |
+| Together/Fireworks key against `api.openai.com` | Auth fails / wrong model set; key only works on its own host | Set the matching `base_url` for the key you hold |
+| Hardcoded API key string literal | Committed key = leaked key | `os.environ[...]` / `process.env.*` only |
+| Pointing the OpenAI Batch client at Together | Compat layer has no `/v1/batches` | Together native Batch API (JSONL upload, 24h, 50k/file) |
+| Serverless for a 200k-row offline eval | Pays full price for work with no latency need | Batch it — ~50% off on both |
+| Budgeting at Priority rates | Priority ≈ 1.5× and is opt-in, not default | Price at Standard unless you explicitly enable Priority |
+| Reaching for DeepSeek V4-Pro by reflex | ~20–30× the cost of a 20B model that may pass the eval | Start at the cheap small model; escalate only on eval failure |
+| Quoting a price/id from an aggregator | Trackers lag and mis-list — e.g. DeepSeek-V3.1 shown as live on Together when it is not on the serverless catalog | Cite together.ai/pricing or docs.fireworks.ai; confirm the id on the serverless catalog before quoting |
+| Treating these like free/local | They bill per token; ollama is the zero-marginal-cost path | If cost must be zero and weights run on your box → `../ollama/SKILL.md` |
+| Renting GPUs to "save money" then idling them | A serverless token endpoint has no idle cost | Self-host only at sustained scale → `../runpod/SKILL.md` |
+
+## References
+
+- `references/models-and-pricing.md` — fuller per-provider model + pricing tables, embeddings, fine-tuning costs, with a re-check note.
+- `references/batch-and-tuning.md` — Together native Batch API JSONL shape + upload/poll/download flow and limits; Fireworks batch path; dedicated deployment notes.
+
+Validate any inference snippet/config with `scripts/verify.sh <file-or-dir>` — a static, no-network lint for the right base URLs, namespaced model ids, and env-var keys.

package/skills/together-fireworks/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — together-fireworks
+
+`cases.yaml` holds three things: `should_trigger` (prompts that must route into this skill, including the non-obvious "404 model not found" namespace bug and Spanish/Catalan phrasings), `should_not_trigger` (prompts that belong to a named sibling — `runpod`, `ollama`, `fal`, `huggingface`, `prompt-engineering`, `rag` — for the self-host / local / media / hub / prompt-design / pipeline boundaries), and one `capability` scenario with a `must_include` rubric. There is no automated runner here: route each trigger prompt through your skill-selection harness and confirm it lands (or doesn't) as labelled, then have an agent run the capability scenario and hand-score the output — every `must_include` line should be present (correct base_url + namespaced id, batch + 50% discount, the cost formula with dated numbers, the Together-native-Batch-API note). To structurally check any inference snippet the skill produces, run `../scripts/verify.sh <file-or-dir>`; a clean rubric pass plus a clean verify run is the bar.

package/skills/together-fireworks/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: together-fireworks
+
+should_trigger:
+  - prompt: "Wire up the OpenAI SDK to call DeepSeek on Together AI."
+    why: Core job — point the OpenAI SDK at api.together.ai with the right base_url and namespaced model id.
+  - prompt: "My Fireworks call returns 404 model not found, here's my code."
+    why: Non-obvious — the classic bare-model-name bug; the fix is the accounts/fireworks/models/ namespace, squarely this skill.
+  - prompt: "Cut our open-model inference bill in half for a 200k-row classification job."
+    why: Batch-discount trigger — offline volume + cost; routes to the 50%-off batch decision, not generic cost tracking.
+  - prompt: "¿Qué modelo open source uso en Fireworks y cuánto me cuesta por millón de tokens?"
+    why: Spanish + model choice + per-1M cost — the pick-the-model decision table is this skill.
+  - prompt: "We're on GPT-4 but want a cheaper open-weights endpoint, same code if possible."
+    why: Migration trigger — OpenAI-compatible host means change base_url + key + model id only.
+  - prompt: "Should I use serverless or dedicated on Fireworks for 50 QPS sustained?"
+    why: Serving-mode decision (serverless vs batch vs dedicated) is a core section of this skill.
+  - prompt: "Abaratar la factura d'inferència fent servir batch a Together."
+    why: Catalan + the Together-native-Batch-API gotcha — not the OpenAI Batch endpoint.
+
+should_not_trigger:
+  - prompt: "Spin up an A100 pod and run vLLM myself."
+    route_to: runpod
+    why: Raw GPU self-host — you manage the box; this skill is a per-token hosted endpoint.
+  - prompt: "Run Llama locally on my Mac with no API cost."
+    route_to: ollama
+    why: Local/offline, zero marginal cost; together-fireworks is cloud pay-per-token.
+  - prompt: "Generate images with FLUX on a hosted endpoint."
+    route_to: fal
+    why: Media generation, not text/chat/embeddings LLM inference.
+  - prompt: "Deploy a model from the Hugging Face hub as an inference endpoint."
+    route_to: huggingface
+    why: HF hub + HF Inference Endpoints, a different host with its own ids.
+  - prompt: "Help me write a better system prompt for my chatbot."
+    route_to: prompt-engineering
+    why: Prompt design, not the hosting endpoint where tokens are billed.
+  - prompt: "Build the retrieval + reranking pipeline for my docs."
+    route_to: rag
+    why: A pipeline built on top of inference, not the inference endpoint itself.
+
+capability:
+  - scenario: >
+      A user has a 500,000-document text classification job, no real-time latency
+      requirement, and a tight budget. Recommend a provider, a model with its exact
+      id, a serving mode, and estimate the cost.
+    must_include:
+      - Picks batch inference and states it is ~50% off serverless on both providers.
+      - Names a cheap small model with a concrete namespaced id from a stable (non-projected) row (e.g. openai/gpt-oss-20b on Together, or a Fireworks <4B/4B-16B tier id) — not a fast-moving flagship.
+      - Applies the cost formula (in_tokens*in_price + out_tokens*out_price)/1e6 with the $/1M numbers as read off the provider page on 2026-06-02 and the 0.5 batch multiplier; any flagship/(projected) figure is flagged "re-read the page before quoting".
+      - Uses the correct base_url and a namespaced model id (no bare model name).
+      - Notes that Together uses its native Batch API (JSONL upload), not the OpenAI /v1/batches endpoint.
+      - Prioritizes model choice (cheap small model) over serving mode as the bigger cost lever.