skilldrop-cli 0.16.21 → 0.16.22

package/bin/skilldrop.js

@@ -485,14 +485,16 @@ function scanSkill(cat, s) {
     try { body = fs.readFileSync(file, "utf8"); } catch (e) { continue; }
     const rules = isScript ? SCRIPT_RULES : PROSE_RULES;
     // Eval fixtures are benchmark input: a sample repo, a risky script for a reviewer to catch.
-    // The skill never runs or follows them, so they are listed, not raised.
-    const fixture = rel.split(path.sep).join("/").startsWith("evals/files/");
+    // Example inputs are the material a worked example was made from. The skill never runs or
+    // follows either, so they are listed, not raised.
+    const relPosix = rel.split(path.sep).join("/");
+    const fixture = relPosix.startsWith("evals/files/") || relPosix.startsWith("examples/inputs/");
     body.split(/\r?\n/).forEach((line, i) => {
       if (line.length > 400) return; // minified/data line — not reviewable prose or code
       for (const r of rules) {
         if (r.re.test(line))
           findings.push({ sev: fixture ? "⚪" : r.sev, id: r.id, fixture,
-                          why: fixture ? `in an eval fixture, which the skill never runs: ${r.why}` : r.why,
+                          why: fixture ? `in ${relPosix.startsWith("examples/") ? "an example's input" : "an eval fixture"}, which the skill never runs: ${r.why}` : r.why,
                           owasp: r.owasp, file: rel, line: i + 1, text: line.trim().slice(0, 120) });
       }
     });

package/catalogue.json

@@ -28,6 +28,7 @@
         "design-doc",
         "architecture-diagrams",
         "reverse-architecture",
+        "interactive-diagram",
         "figma-diagrams",
         "api-contract-draft",
         "data-contract",

package/model-routing.json

@@ -278,6 +278,10 @@
       "tier": "standard",
       "rationale": "Structured synthesis from a content list into groups, labels and a nav model against fixed IA practice. Grouping needs judgment, but the method and the validation plan bound it."
     },
+    "interactive-diagram": {
+      "tier": "standard",
+      "rationale": "Tracing a path through code and citing each part is careful reading, not adversarial judgement; the layout and the checks are done by the script."
+    },
     "job-fit-analysis": {
       "tier": "standard",
       "rationale": "Matches a posting's requirements to resume lines and reports the gaps. The rule is mechanical: no line in the resume, no credit."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.21",
+  "version": "0.16.22",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/solution-architect/skills/interactive-diagram/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: interactive-diagram
+description: Turn a codebase, a system description, a process or a database schema into one self-contained interactive HTML diagram (architecture, workflow, data flow, lifecycle, ERD or sequence) where every box and arrow cites the file and line or the words it came from, anything inferred is drawn dashed as an assumption, and each cited line is checked against the repository before the page is written. Laid out automatically, opens offline with no CDN, and exports SVG, PNG and Mermaid. Use when the user asks to "visualize", "map" or "make an interactive diagram of" a repo, a request path, a pipeline, an approval process or a set of tables, or wants a diagram they can click through and share as one file.
+---
+
+# interactive-diagram
+
+**The rule: nothing goes on the map that the material doesn't show.** A diagram is trusted
+more than prose, so an invented box misleads more than an invented sentence. Asked to draw a
+repo, the agent's habit is to draw the system such repos usually have: a load balancer, an
+auth service, the Kafka the README says is planned. Here every part and every connection
+either cites where it came from (`src/api.py:40-52`, or the person's own words) or is drawn
+dashed and listed as an assumption. The script checks each cited file and line before it
+writes the page, and refuses a spec that cites a line that isn't there.
+
+Two things follow:
+
+- **One question per map.** Draw what answers the question asked ("what happens when an order
+  is placed"), not every module in the repo. A part that doesn't help answer it stays off,
+  and the reply says in one line what was left out.
+- **You write the meaning; the script does the layout.** Never write coordinates. List the
+  parts and connections in the order a reader meets them, and the script places them, routes
+  every arrow around the boxes, and draws groups as boxes that don't overlap.
+
+## How to respond
+
+1. **Name the question and pick the type.** One sentence: what will the reader understand
+   after looking? Then the type:
+
+   | Type | For |
+   |---|---|
+   | `architecture` | What a system is made of and what talks to what |
+   | `dataflow` | Where data or money or documents go, stage by stage |
+   | `workflow` | A process with steps, decisions and hand-offs, technical or everyday |
+   | `lifecycle` | The states something moves through and what moves it |
+   | `erd` | Tables, their columns and keys, and how they reference each other |
+   | `sequence` | Who calls whom, in order, for one request or exchange |
+
+2. **Gather the facts, with where each came from.**
+   - **A repository:** trace the one path the question is about. Read the entry point, follow
+     the calls, and for each part and each arrow note the file and lines that show it. Add a
+     few characters from those lines after `#` (`src/api.py:12#stripe.PaymentIntent`) so a
+     wrong line number is caught. Config and README files show intent, not behaviour: a
+     service the README mentions but no code calls is left off, or drawn as an assumption with
+     the README as its only evidence and said so in the reply.
+   - **A description:** cite the person's words: `"user: anything over ten days goes to HR"`.
+   - **Something you believe but can't point to** (who calls the API, what the worker does
+     next): `"assumed": true`. It is drawn dashed and listed. Leave it off if it doesn't help
+     answer the question.
+
+3. **Write the spec** as JSON next to where the page will go. The full shape, every kind and
+   the ERD and sequence fields are in [`reference.md`](reference.md). The essentials:
+
+   ```json
+   {"type": "architecture", "title": "What a checkout request touches",
+    "question": "What happens when a shopper checks out?",
+    "summary": "One or two sentences: the takeaway a reader should leave with.",
+    "groups": [{"id": "vpc", "label": "Private VPC"}],
+    "nodes": [{"id": "api", "label": "Checkout API", "kind": "service", "group": "vpc",
+               "note": "FastAPI", "evidence": ["src/api.py:8-14#def checkout"]}],
+    "edges": [{"from": "api", "to": "db", "label": "insert order", "evidence": ["src/api.py:13"]}],
+    "story": [{"text": "The API checks the cache first.", "edges": ["e2"]}]}
+   ```
+
+   Labels are a few words; detail goes in `note` (shown on the box) or `detail` (shown when
+   clicked). Add a `story` of three to seven steps when the map has a main path worth walking.
+
+4. **Build it.** With a repository, always pass `--repo-root` so the citations are checked:
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/build_diagram.py" diagram.json -o diagram.html --repo-root .
+   # Other IDEs (from the skill folder)
+   python3 scripts/build_diagram.py diagram.json -o diagram.html --repo-root .
+   ```
+
+   Errors list the item, what is wrong and the fix, and nothing is written until they're gone.
+   Fix the spec, never the evidence: a citation the check can't find is wrong, so find the
+   right lines or mark the item assumed. Add `--mermaid diagram.mmd` for a version to paste
+   into a README, and `--compare old.json` to show what a change adds, removes and alters.
+
+5. **Reply with the map first.** The first line is the link to the HTML file and what it
+   shows. Then the takeaway in one or two sentences, then one line each for what is drawn as
+   an assumption and what was left out, and last how many citations were checked. Keep the
+   spec beside the page so the map can be rebuilt after the code changes. No recap of
+   commands or layout.
+
+6. **When the script can't run** (no `python3`), give the Mermaid version in the reply, with
+   assumptions marked, and say that the interactive page needs Python 3.
+
+This is a non-interactive skill: don't stop to ask. With too little to draw from, draw what
+you have, mark the rest as assumptions, and say in the reply what would settle them.
+
+**Sharing:** the page shows the cited lines when a part is clicked. Files that hold secrets
+(`.env`, keys, credential files) are never shown and secret-looking lines are masked, but
+don't cite them in the first place, and read the page before it leaves the team.
+
+## Quality bar
+
+- **Every part and connection cites its source or is drawn as an assumption.** No exceptions
+  for the "obvious" ones.
+- **Every file citation was checked** against the repository, with the count in the reply.
+- **Nothing on the map comes only from a README, a plan or what such systems usually have.**
+- **The map answers one stated question,** and what was left out is said.
+- **One HTML file that works offline:** no CDN, no external fonts, no network requests.
+- **The reply opens with the link and the takeaway,** not with how it was made.
+
+## When to use this skill
+
+- ✅ "Map what happens when an order is placed in this repo, as something I can click through"
+- ✅ "Turn this description of our approval process into an interactive flowchart for the team"
+- ✅ "Give me an interactive ERD of schema.sql"
+- ✅ "Show what this branch changes in the architecture" (two specs and `--compare`)
+
+## When NOT to use this skill
+
+- ❌ A Mermaid, PlantUML or C4 diagram to paste into a doc — use `architecture-diagrams`
+- ❌ An as-is architecture write-up in C4 levels from infrastructure files — use `reverse-architecture`
+- ❌ Fixing or rendering an existing Mermaid diagram — use `mermaid-render`
+- ❌ Charts of numbers, dashboards or metrics — this draws structure, not data
+
+## Anti-patterns to avoid
+
+- ❌ **The usual architecture.** A load balancer, CDN or auth service drawn because systems
+  like this have one.
+- ❌ **README as evidence of behaviour.** "We use Kafka" in a README is a plan until code
+  calls it.
+- ❌ **Deleting evidence to pass the check.** A failed citation means the line is wrong or
+  the part is an assumption.
+- ❌ **Everything in the repo.** Forty boxes answer no question.
+- ❌ **Hand-placed coordinates** or a hand-written SVG instead of the script.
+- ❌ **A page that loads a library from a CDN.** It breaks offline and leaks the viewer's IP.

package/packs/solution-architect/skills/interactive-diagram/evals/eval_queries.json

@@ -0,0 +1,12 @@
+[
+  {"query": "Make an interactive diagram of what happens when someone places an order in this repo", "should_trigger": true},
+  {"query": "Visualize our request flow as an HTML page I can click around and send to the team", "should_trigger": true},
+  {"query": "Turn this description of our purchase approval process into an interactive flowchart", "should_trigger": true},
+  {"query": "Give me an explorable ERD of schema.sql as a single HTML file", "should_trigger": true},
+  {"query": "Map how this service talks to the database and the queue, with links back to the code", "should_trigger": true},
+  {"query": "Show what this branch changes in the architecture compared with main, as an interactive diagram", "should_trigger": true},
+  {"query": "Write a Mermaid C4 container diagram for the design doc from this description", "should_trigger": false},
+  {"query": "My mermaid flowchart says parse error on line 3, can you fix it and export a PNG", "should_trigger": false},
+  {"query": "Reverse-engineer the as-is architecture from our Terraform and write it up in C4 levels", "should_trigger": false},
+  {"query": "Build a dashboard chart of weekly signups from this CSV", "should_trigger": false}
+]

package/packs/solution-architect/skills/interactive-diagram/evals/evals.json

@@ -0,0 +1,74 @@
+{
+  "skill_name": "interactive-diagram",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "This is the Larder repo. I'm onboarding two new developers next week. Can you make an interactive diagram, one HTML file I can send them, of what happens when a customer places an order?",
+      "assertions": [
+        "An HTML file is written that works on its own offline: it loads no script, stylesheet or font from a CDN or any http(s) URL",
+        "The diagram shows the order path the code shows: the web checkout posting to the API's POST /orders, the API validating and inserting into Postgres, pushing an email job onto the Redis 'emails' list, and the worker popping it and posting to the mailer service",
+        "Kafka does not appear as part of the order path; if it is mentioned at all, it is described as planned in the README and not in the code",
+        "No payment step or payment provider appears in the order path (the README says payment is taken in the shop on collection)",
+        "It does not add parts the repo does not contain, such as a load balancer, CDN, auth service, cache or separate analytics service",
+        "The parts or connections in the diagram, or the page's text, name the files they come from (for example api/app.py, worker/worker.py, web/checkout.js, docker-compose.yml)",
+        "Anything drawn that the code does not show (for example who hosts the mailer, or what happens after the email is sent) is marked as an assumption, or left off",
+        "The reply opens with where the file is and what the diagram shows, in a few sentences, without a long account of how it was built"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Can you turn this into an interactive flowchart I can share with the team as a single file? Here's how expense claims work at our office: you fill in a claim in the finance portal and attach the receipts. Your line manager approves it. If it's over £500 it also needs the finance director. Finance then checks the receipts match and pays it in the next payroll run. Claims older than 90 days are rejected automatically when you submit them.",
+      "assertions": [
+        "An HTML file is written that works on its own offline, loading nothing from a CDN or any http(s) URL",
+        "The flow includes, in order: submit in the finance portal with receipts, the automatic rejection of claims older than 90 days, line manager approval, the over £500 decision leading to finance director approval, finance checking receipts, and payment in the next payroll run",
+        "The over £500 rule and the 90-day rule are drawn as decisions or branches, not as plain steps",
+        "What happens when the line manager or finance director declines, or when receipts don't match, is not stated in the description, so it is either left off or visibly marked as an assumption, never drawn as a definite step",
+        "It adds no steps, roles, systems or thresholds the description does not contain (for example no budget-holder step, no expense card, no second threshold)",
+        "The reply is short: where the file is, what it shows, and which paths were not covered by the description"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I need an interactive ERD of schema.sql for the team wiki - something people can click on to see the columns. One self-contained HTML file.",
+      "assertions": [
+        "An HTML file is written that works on its own offline, loading nothing from a CDN or any http(s) URL",
+        "All five tables appear (clinics, practitioners, patients, appointments, appointment_notes) with every column the schema defines and no column it does not",
+        "The four foreign keys are drawn as relationships with the right direction: practitioners to clinics, appointments to practitioners, appointments to patients, appointment_notes to appointments",
+        "booked_by_user_id is shown as a column but no relationship is drawn for it to a users or staff table as if it existed; if it is mentioned, the reply or page says it has no table in this schema",
+        "Primary keys and foreign keys are marked on their columns, and appointment_notes.appointment_id is shown as both",
+        "appointment_notes to appointments is shown as one-to-one or at most one note per appointment, not one-to-many",
+        "It invents no tables, columns, indexes or constraints that schema.sql does not contain"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-10-18",
+      "prompt": "This is castbox-media, the backend for our podcast hosting platform. I need to explain to the new on-call engineer what actually happens when a creator's episode upload finishes and the storage webhook hits us, up to the point where we stop being in control. Make me an interactive diagram of that path I can click through and send them as one file.",
+      "assertions": [
+        "Writes one self-contained HTML file that opens offline: no <script src>, <link href>, @import or font URL pointing at http(s), and the diagram's code and styles are inline",
+        "Shows the path in order: the object store's webhook to POST /webhooks/storage (src/server.js), handleStorageWebhook checking the x-storage-signature HMAC and the object.finalized event type (src/handlers/storageWebhook.js), the episodes row set to 'uploaded' in PostgreSQL, a 'transcribe-episode' job added to the Redis/BullMQ 'media' queue, the worker (src/worker.js) running transcribeEpisode (src/jobs/transcribeEpisode.js), submitTranscription POSTing to the transcription API's /v2/jobs (src/clients/transcription.js), the episode set to 'transcribing' with its transcription_job_id, and the processing email sent over SMTP via src/mailer.js",
+        "Shows at least one of the branches the code takes: bad signature returns 401, non-finalized events return 204 and are ignored, an unknown or already-taken upload_key is ignored, the email only goes out when notify_on_processing is true, or the episode is marked 'failed' after the 3 attempts are used up",
+        "Boxes and arrows cite the source file (and line where given) they came from, and every cited file is one that exists in the repo",
+        "Does not draw transcoding, the search indexing or the CDN purge as steps on this path: the README and config/default.json mention them but no code on the upload path calls them (search is only used by the nightly 'nightly-reindex' job, and transcoding and CDN purge appear in no code). If shown at all, they are marked as not called or as claims from the README",
+        "Keeps the other paths out of the main flow: the GET /feeds/:showId.xml RSS route and the 03:00 nightly-reindex job are either absent or clearly marked as separate from the upload path",
+        "Does not present what the transcription service does after accepting the job as fact: the callback to /webhooks/transcription is dashed, marked as an assumption or left out, and the reply or diagram notes that src/server.js registers no /webhooks/transcription route, so nothing in this repo receives the result or moves the episode to 'published'",
+        "The reply opens with where the HTML file is and the main takeaway (for example that the app's part ends once the job is submitted and the email sent, and the transcript callback has no handler), not with a long account of how the diagram was made"
+      ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-18",
+      "prompt": "Can you make an interactive sequence diagram of how a repair request goes through at Fernhill Housing Co-op? I want to show it to our board next week as one file they can open. Here's how it works as far as I know:\n\nA tenant phones the contact centre or fills in the web form to report a repair. The contact centre logs it in our housing management system (HMS) and gives the tenant a reference number. Every weekday morning the repairs coordinator goes through the new jobs in HMS, decides the priority (emergency = attend within 24 hours, routine = within 20 working days) and assigns it to one of our two contractors by emailing them the job sheet. The contractor rings the tenant to book a visit, then does the work. After the visit the contractor marks the job complete in their own portal. At the end of each month the contractor sends us an invoice listing the jobs they finished, and finance closes those jobs in HMS when they pay the invoice.\n\nIf the contractor needs to order parts I'm honestly not sure what happens, I think they tell the coordinator? We used to post the tenant a confirmation letter when a job was closed but we stopped doing that in 2025. There's also the annual gas safety check programme but that's a different process, leave it out.",
+      "assertions": [
+        "Writes one self-contained HTML file that opens offline: no <script src>, <link href>, @import or font URL pointing at http(s), and the diagram's code and styles are inline",
+        "It is a sequence diagram with at least these participants: tenant, contact centre, HMS, repairs coordinator, contractor and finance (the contractor's portal may be its own participant or part of the contractor)",
+        "The messages run in this order: tenant reports by phone or web form; contact centre logs the job in HMS and gives the tenant a reference number; the coordinator reviews new jobs each weekday morning, sets the priority (emergency 24 hours, routine 20 working days) and emails the job sheet to a contractor; the contractor rings the tenant to book and does the visit; the contractor marks the job complete in its own portal; the contractor sends a monthly invoice to finance; finance closes the jobs in HMS on payment",
+        "The parts-ordering step is drawn dashed or labelled as an assumption or unconfirmed (the user said they are not sure), not as a solid confirmed message",
+        "The posted confirmation letter does not appear as a current step (absent, or shown only as stopped in 2025), and the gas safety check programme does not appear",
+        "Points out at least one hand-off gap the description reveals: nothing tells the tenant the repair is finished or closed; HMS only learns a job is done when finance pays the monthly invoice, so jobs stay open in HMS for weeks; or an emergency reported after the morning review waits until the next weekday morning before the coordinator sees it",
+        "Each message carries or cites the words from the user's description it came from, and the diagram adds no participants or systems the user did not describe (for example no SMS service, CRM, scheduling tool or tenant app)",
+        "The reply opens with where the HTML file is and the main takeaway (such as the gap found), not with a long account of how the diagram was made"
+      ]
+    }
+  ]
+}

package/packs/solution-architect/skills/interactive-diagram/evals/files/1/README.md

@@ -0,0 +1,11 @@
+# Larder
+
+Grocery ordering for small shops. Customers order on the web, the shop gets an email.
+
+## Architecture
+
+- `web/` - the storefront
+- `api/` - order API (Flask)
+- `worker/` - sends confirmation emails
+- Order events go to Kafka so analytics can consume them (planned for Q3).
+- Payments are taken in the shop on collection, not online.

package/packs/solution-architect/skills/interactive-diagram/evals/files/1/api/app.py

@@ -0,0 +1,43 @@
+import json
+import os
+
+import psycopg
+import redis
+from flask import Flask, jsonify, request
+
+app = Flask(__name__)
+db = psycopg.connect(os.environ["DATABASE_URL"])
+queue = redis.Redis.from_url(os.environ["REDIS_URL"])
+
+
+def validate(order):
+    if not order.get("items"):
+        return "an order needs at least one item"
+    if not order.get("email"):
+        return "an order needs an email for the confirmation"
+
+
+@app.post("/orders")
+def place_order():
+    order = request.get_json()
+    problem = validate(order)
+    if problem:
+        # the first rule the order breaks, in words the storefront can show
+        return jsonify(error=problem), 400
+    with db.cursor() as cur:
+        cur.execute(
+            "insert into orders (shop_id, email, items) values (%s, %s, %s) returning id",
+            (order["shop_id"], order["email"], json.dumps(order["items"])),
+        )
+        order_id = cur.fetchone()[0]
+    db.commit()
+    queue.lpush("emails", json.dumps({"order_id": order_id, "to": order["email"]}))
+    return jsonify(id=order_id), 201
+
+
+@app.get("/orders/<int:order_id>")
+def get_order(order_id):
+    with db.cursor() as cur:
+        cur.execute("select id, status from orders where id = %s", (order_id,))
+        row = cur.fetchone()
+    return jsonify(id=row[0], status=row[1]) if row else ("", 404)

package/packs/solution-architect/skills/interactive-diagram/evals/files/1/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  web:
+    build: ./web
+    ports: ["8080:80"]
+  api:
+    build: ./api
+    environment:
+      DATABASE_URL: postgresql://larder@db/larder
+      REDIS_URL: redis://queue:6379/0
+    depends_on: [db, queue]
+  worker:
+    build: ./worker
+    environment:
+      REDIS_URL: redis://queue:6379/0
+      MAILER_URL: https://api.mailer.example/v1/send
+    depends_on: [queue]
+  db:
+    image: postgres:16
+  queue:
+    image: redis:7

package/packs/solution-architect/skills/interactive-diagram/evals/files/1/web/checkout.js

@@ -0,0 +1,9 @@
+export async function placeOrder(cart, email, shopId) {
+  const res = await fetch("/api/orders", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ items: cart.items, email, shop_id: shopId }),
+  });
+  if (!res.ok) throw new Error((await res.json()).error);
+  return (await res.json()).id;
+}

package/packs/solution-architect/skills/interactive-diagram/evals/files/1/worker/worker.py

@@ -0,0 +1,23 @@
+import json
+import os
+
+import redis
+import requests
+
+queue = redis.Redis.from_url(os.environ["REDIS_URL"])
+MAILER_URL = os.environ["MAILER_URL"]
+
+
+def run():
+    while True:
+        _, raw = queue.brpop("emails")
+        job = json.loads(raw)
+        requests.post(MAILER_URL, json={
+            "to": job["to"],
+            "template": "order-confirmation",
+            "data": {"order_id": job["order_id"]},
+        }, timeout=10)
+
+
+if __name__ == "__main__":
+    run()

package/packs/solution-architect/skills/interactive-diagram/evals/files/3/schema.sql

@@ -0,0 +1,35 @@
+-- Clinic bookings
+create table clinics (
+  id          serial primary key,
+  name        text not null,
+  timezone    text not null default 'Europe/London'
+);
+
+create table practitioners (
+  id          serial primary key,
+  clinic_id   integer not null references clinics(id),
+  full_name   text not null,
+  role        text not null check (role in ('physio', 'osteo', 'massage'))
+);
+
+create table patients (
+  id          serial primary key,
+  email       text unique not null,
+  phone       text
+);
+
+create table appointments (
+  id               serial primary key,
+  practitioner_id  integer not null references practitioners(id),
+  patient_id       integer not null references patients(id),
+  starts_at        timestamptz not null,
+  minutes          integer not null default 45,
+  status           text not null default 'booked',
+  booked_by_user_id integer  -- staff login id from the old system; no table here
+);
+
+create table appointment_notes (
+  appointment_id   integer primary key references appointments(id),
+  body             text not null,
+  written_at       timestamptz not null default now()
+);

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/README.md

@@ -0,0 +1,26 @@
+# castbox-media
+
+Backend for the Hollowbrook Podcast Network's hosting platform.
+
+## What it does
+
+When a creator finishes uploading an episode, the object store sends us a
+webhook. We then transcode and transcribe the audio, index the transcript in
+search so listeners can find episodes by what was said, and purge the CDN so
+the new episode shows up in the RSS feed straight away. The creator gets an
+email when processing starts.
+
+## Stack
+
+- Node 20, Express (API) and BullMQ (background jobs)
+- PostgreSQL (`episodes`, `shows`, `creators`)
+- Redis (job queue)
+- Transcription vendor HTTP API (api.transcribe.example.test)
+- Search service (search.internal.test)
+- CDN in front of the RSS feeds (cdn.example.test)
+- SMTP relay for creator emails
+
+## Running
+
+    npm run api      # node src/server.js
+    npm run worker   # node src/worker.js

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/config/default.json

@@ -0,0 +1,29 @@
+{
+  "publicUrl": "https://media.hollowbrook.example.test",
+  "port": 8080,
+  "databaseUrl": "postgres://castbox:changeme@db.internal.test:5432/castbox",
+  "redisUrl": "redis://cache.internal.test:6379/0",
+  "storage": {
+    "bucket": "hollowbrook-uploads",
+    "publicBaseUrl": "https://uploads.example.test",
+    "webhookSecret": "PLACEHOLDER_WEBHOOK_SECRET"
+  },
+  "transcription": {
+    "baseUrl": "https://api.transcribe.example.test",
+    "apiKey": "PLACEHOLDER_TRANSCRIBE_KEY",
+    "language": "en"
+  },
+  "search": {
+    "url": "http://search.internal.test:7700",
+    "index": "episodes"
+  },
+  "cdn": {
+    "purgeUrl": "https://cdn.example.test/api/purge",
+    "token": "PLACEHOLDER_CDN_TOKEN"
+  },
+  "smtp": {
+    "host": "smtp.internal.test",
+    "port": 587,
+    "from": "studio@hollowbrook.example.test"
+  }
+}

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/src/clients/transcription.js

@@ -0,0 +1,25 @@
+const config = require('../../config/default.json');
+
+async function submitTranscription(audioUrl, episodeId) {
+  const response = await fetch(`${config.transcription.baseUrl}/v2/jobs`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${config.transcription.apiKey}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      media_url: audioUrl,
+      language: config.transcription.language,
+      reference: String(episodeId),
+      callback_url: `${config.publicUrl}/webhooks/transcription`,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`transcription submit failed: ${response.status}`);
+  }
+  const body = await response.json();
+  return body.job_id;
+}
+
+module.exports = { submitTranscription };

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/src/db.js

@@ -0,0 +1,16 @@
+const { Pool } = require('pg');
+const IORedis = require('ioredis');
+const { Queue } = require('bullmq');
+const config = require('../config/default.json');
+
+const pool = new Pool({ connectionString: config.databaseUrl });
+const connection = new IORedis(config.redisUrl, { maxRetriesPerRequest: null });
+
+const mediaQueue = new Queue('media', { connection });
+
+async function query(text, params) {
+  const result = await pool.query(text, params);
+  return result.rows;
+}
+
+module.exports = { query, mediaQueue, connection };

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/src/handlers/storageWebhook.js

@@ -0,0 +1,43 @@
+const crypto = require('crypto');
+const config = require('../../config/default.json');
+const { query, mediaQueue } = require('../db');
+
+function validSignature(rawBody, header) {
+  if (!header) return false;
+  const expected = crypto
+    .createHmac('sha256', config.storage.webhookSecret)
+    .update(rawBody)
+    .digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
+}
+
+async function handleStorageWebhook(req, res) {
+  if (!validSignature(req.body, req.get('x-storage-signature'))) {
+    return res.status(401).json({ error: 'bad signature' });
+  }
+
+  const event = JSON.parse(req.body.toString('utf8'));
+  if (event.type !== 'object.finalized') {
+    // Deletes, metadata updates etc. are acknowledged and ignored.
+    return res.status(204).end();
+  }
+
+  const [episode] = await query(
+    "UPDATE episodes SET status = 'uploaded', audio_url = $1 WHERE upload_key = $2 AND status = 'awaiting_upload' RETURNING id",
+    [`${config.storage.publicBaseUrl}/${event.object.key}`, event.object.key]
+  );
+  if (!episode) {
+    // Unknown key, or a retried webhook for an episode we already took.
+    return res.status(200).json({ ignored: true });
+  }
+
+  await mediaQueue.add(
+    'transcribe-episode',
+    { episodeId: episode.id },
+    { attempts: 3, backoff: { type: 'exponential', delay: 30000 } }
+  );
+
+  return res.status(202).json({ queued: episode.id });
+}
+
+module.exports = { handleStorageWebhook };

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/src/jobs/transcribeEpisode.js

@@ -0,0 +1,28 @@
+const { query } = require('../db');
+const { submitTranscription } = require('../clients/transcription');
+const { sendProcessingEmail } = require('../mailer');
+
+async function transcribeEpisode(job) {
+  const [episode] = await query(
+    `SELECT e.id, e.title, e.audio_url, c.email, c.notify_on_processing
+       FROM episodes e
+       JOIN shows s ON s.id = e.show_id
+       JOIN creators c ON c.id = s.creator_id
+      WHERE e.id = $1`,
+    [job.data.episodeId]
+  );
+  if (!episode) return;
+
+  const transcriptionJobId = await submitTranscription(episode.audio_url, episode.id);
+
+  await query(
+    "UPDATE episodes SET status = 'transcribing', transcription_job_id = $1 WHERE id = $2",
+    [transcriptionJobId, episode.id]
+  );
+
+  if (episode.notify_on_processing) {
+    await sendProcessingEmail(episode.email, episode.title);
+  }
+}
+
+module.exports = { transcribeEpisode };

package/packs/solution-architect/skills/interactive-diagram/evals/files/4/src/mailer.js

@@ -0,0 +1,18 @@
+const nodemailer = require('nodemailer');
+const config = require('../config/default.json');
+
+const transport = nodemailer.createTransport({
+  host: config.smtp.host,
+  port: config.smtp.port,
+});
+
+async function sendProcessingEmail(to, episodeTitle) {
+  await transport.sendMail({
+    from: config.smtp.from,
+    to,
+    subject: `"${episodeTitle}" is processing`,
+    text: `We've received "${episodeTitle}" and started processing it. We'll publish it once the transcript is ready.`,
+  });
+}
+
+module.exports = { sendProcessingEmail };