skilldrop-cli 0.2.0

package/skills/figma-diagrams/scripts/list_comments.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""List comments on a Figma file.
+
+Usage:
+    python list_comments.py <FILE_KEY_OR_URL>
+"""
+
+from __future__ import annotations
+
+import sys
+
+from _figma_client import extract_file_key, get
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 1:
+        sys.stderr.write("usage: list_comments.py <FILE_KEY_OR_URL>\n")
+        return 2
+    file_key = extract_file_key(argv[0])
+    data = get(f"/v1/files/{file_key}/comments")
+    comments = data.get("comments", [])
+    if not comments:
+        print("(no comments)")
+        return 0
+    for c in comments:
+        author = c.get("user", {}).get("handle", "<unknown>")
+        ts = c.get("created_at", "")
+        msg = c.get("message", "").strip().replace("\n", " ")
+        resolved = " [resolved]" if c.get("resolved_at") else ""
+        print(f"- {ts}  @{author}{resolved}: {msg}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/skills/figma-diagrams/scripts/post_comment.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Post a comment on a Figma file.
+
+Usage:
+    python post_comment.py <FILE_KEY_OR_URL> "<message>" [--node-id NODE_ID]
+
+If --node-id is given, the comment is pinned to the centroid of that node.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from _figma_client import extract_file_key, get, post
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("file", help="Figma file URL or bare file key")
+    ap.add_argument("message", help="Comment text")
+    ap.add_argument("--node-id", help="Node ID to pin the comment to (e.g. 1:23)")
+    args = ap.parse_args(argv)
+
+    file_key = extract_file_key(args.file)
+
+    body: dict = {"message": args.message}
+
+    if args.node_id:
+        nodes = get(f"/v1/files/{file_key}/nodes", params={"ids": args.node_id})
+        node = nodes.get("nodes", {}).get(args.node_id, {}).get("document", {})
+        box = node.get("absoluteBoundingBox")
+        if not box:
+            sys.stderr.write(
+                f"error: could not resolve node {args.node_id} in file {file_key}\n"
+            )
+            return 1
+        body["client_meta"] = {
+            "node_id": args.node_id,
+            "node_offset": {
+                "x": box["width"] / 2,
+                "y": box["height"] / 2,
+            },
+        }
+
+    resp = post(f"/v1/files/{file_key}/comments", body)
+    print(f"posted: comment_id={resp.get('id')}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/skills/figma-diagrams/templates/figjam-import.json

@@ -0,0 +1,20 @@
+{
+  "_comment": "Example spec consumable by a FigJam plugin that turns it into shapes + connectors. Pair this with a tiny Figma plugin (or use a community plugin that accepts this shape) to materialize the diagram. Not a Figma REST API call — REST cannot create nodes.",
+  "title": "Three-tier web app on AWS",
+  "nodes": [
+    { "id": "n_internet", "label": "Internet",  "shape": "ELLIPSE",   "x": 0,    "y": 0   },
+    { "id": "n_alb",      "label": "ALB",       "shape": "RECTANGLE", "x": 200,  "y": 0   },
+    { "id": "n_web",      "label": "ECS web",   "shape": "RECTANGLE", "x": 400,  "y": -60 },
+    { "id": "n_worker",   "label": "ECS worker","shape": "RECTANGLE", "x": 400,  "y":  60 },
+    { "id": "n_rds",      "label": "RDS",       "shape": "CYLINDER",  "x": 640,  "y":  0  },
+    { "id": "n_sqs",      "label": "SQS",       "shape": "PARALLELOGRAM", "x": 400, "y": 200 }
+  ],
+  "edges": [
+    { "from": "n_internet", "to": "n_alb",    "label": "HTTPS" },
+    { "from": "n_alb",      "to": "n_web",    "label": "HTTP"  },
+    { "from": "n_web",      "to": "n_rds",    "label": "SQL"   },
+    { "from": "n_web",      "to": "n_sqs",    "label": "enqueue" },
+    { "from": "n_sqs",      "to": "n_worker", "label": "dequeue" },
+    { "from": "n_worker",   "to": "n_rds",    "label": "SQL"   }
+  ]
+}

package/skills/guide-builder/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: guide-builder
+description: Turn raw notes, specs, or design material into an easy-to-follow guide, auto-styled to the content — a setup/quickstart, a design walkthrough, or an API/event-schema reference. Use when the user wants setup or getting-started instructions, an onboarding walkthrough of how a system works, or developer reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).
+---
+
+# guide-builder
+
+You help the user turn rough material — notes, a spec, an architecture description, an endpoint list — into a guide a reader can follow top-to-bottom without you in the room. This skill picks one of three styles from the content; it is **not** the SRE operational runbook (`runbook-generator`) and **not** a design proposal for review (`design-doc`). It explains and instructs; it does not propose or page.
+
+## How to respond
+
+1. **Detect the style first, and say which you picked.** Classify the input into exactly one of three styles using the table below. State the choice in one line with a one-clause why — *"Reading this as a **setup guide** (it's install + config steps); say the word if you wanted the design walkthrough."* — so the user can redirect before you draft.
+
+   | Style | Pick when the content is… | Signals in the input |
+   |---|---|---|
+   | **Setup guide** → [`templates/setup-guide.md`](templates/setup-guide.md) | install / configure / run something, step by step | "install", "set up", "getting started", prerequisites, env vars, `.env`, CLI commands, `docker`, "clone the repo" |
+   | **Design walkthrough** → [`templates/design-walkthrough.md`](templates/design-walkthrough.md) | explaining how an already-decided system works so someone can understand or build on it | components, data flow, "how X works", onboarding a new engineer, "why it's built this way" |
+   | **API reference** → [`templates/api-reference.md`](templates/api-reference.md) | contracts other developers code against | endpoints, request/response shapes, OpenAPI, event names, payload schemas, status codes, webhooks, Kafka/SNS topics, JSON Schema |
+
+2. **Handle mixed content by picking the dominant style, not blending.** If the input spans two styles (e.g. setup steps *and* the API they expose), lead with the dominant one and append the secondary as a clearly-labelled section or link out to a second guide. Only ask the user which to lead with if it's a genuine 50/50.
+
+3. **Gather only what the chosen style can't do without.** Don't run a generic intake. Cap at 2 questions, pick defaults for the rest:
+   - **Setup guide** needs the *target end state* ("running locally" vs "deployed to staging") and the *prerequisites baseline*. Without an end state, a setup guide has no finish line.
+   - **Design walkthrough** needs *who it's for* (new hire vs adjacent team) and *what they should be able to do after reading*.
+   - **API reference** needs the *transport + auth model* and *versioning scheme*. Without auth, the examples are unrunnable.
+
+   If the source is genuinely too thin, say so once and draft with gaps flagged as `> ⚠️ NEEDS INPUT: …` — don't invent.
+
+4. **Fill the matching template.** Each template is ordered the way a reader actually consumes it. Don't reorder sections to match the input's order; reorder the input to match the reader's path.
+
+5. **Apply the universal easy-to-follow rules** (these are the spine of every style):
+   - **One action per step.** Number them. No compound step hiding three commands behind one number.
+   - **Every step ends in a check.** "You should see `Listening on :3000`." A step with no success signal can't tell the reader whether to continue or stop.
+   - **Commands are complete and paste-able.** Real flags, not pseudocode. Placeholders are unmistakable (`<YOUR_API_KEY>`, never `your-key-here` buried mid-line) and listed once up front.
+   - **Lead each section with the outcome, not the backstory.** "By the end of this section the service answers on localhost." The "why" belongs in a walkthrough, not a quickstart.
+   - **Front-load the happy path.** Push edge cases, troubleshooting, and teardown to the end.
+
+## Useful references in this skill
+
+- [`templates/setup-guide.md`](templates/setup-guide.md) — install/configure/run, prerequisites → verify → troubleshooting.
+- [`templates/design-walkthrough.md`](templates/design-walkthrough.md) — mental model → components → flow → key decisions → where the code lives.
+- [`templates/api-reference.md`](templates/api-reference.md) — conventions → per-endpoint/event contracts → error catalog → changelog.
+- [`examples/local-setup-guide.md`](examples/local-setup-guide.md) — raw notes → a finished setup guide, showing the detection call and the verify-after-every-step discipline.
+
+## Quality bar
+
+- **A reader who follows top-to-bottom reaches the stated end state without leaving the doc for missing info.** Unstated prerequisites are the #1 failure — hunt them down.
+- **Every command block has an expected result or a verification step.** A command with no "how do I know it worked" is incomplete.
+- **Placeholders are unmistakable and listed once up front.** `<YOUR_API_KEY>`, not a real-looking string the reader pastes verbatim and wonders why it fails.
+- **No forward references that break linear reading.** "See step 7" before step 7 means the order is wrong, or it needs a link.
+- **API reference: every field has type + required/optional + a one-line meaning; every endpoint has ≥1 full example request and response, including at least one error response.**
+- **The detected style is stated up front with a one-line why,** so the user can redirect in one message instead of getting the wrong artifact.
+
+## When to use this skill
+
+- ✅ "Write setup instructions for getting our service running locally."
+- ✅ "Turn this architecture description into an onboarding walkthrough for new engineers."
+- ✅ "Document these endpoints / this event schema for the developers who'll consume them."
+- ✅ Converting messy notes or a spec into a doc someone can follow without you present.
+
+## When NOT to use this skill
+
+- ❌ SRE operational runbook — incidents, on-call escalation, deploy/rollback, SLOs → `runbook-generator`.
+- ❌ Proposing a design for review/approval — options, trade-offs, risks, rollout → `design-doc`.
+- ❌ Compressing a long doc for an exec audience → `exec-summary`.
+- ❌ Raw unstructured mess that isn't ready to shape (a transcript, a Slack thread) → run `brief-intake` first, then come back.
+
+## Anti-patterns to avoid
+
+- ❌ Compound steps. "Install deps, configure the DB, and run migrations" as one numbered step — split into three.
+- ❌ Commands with no expected output. The reader can't tell success from a silent failure.
+- ❌ Backstory before the first actionable step in a setup guide. Save the "why" for a walkthrough.
+- ❌ Documenting an API in prose ("it returns the user object") instead of a typed schema + example payload.
+- ❌ Blending two styles into one undifferentiated doc. Pick the dominant style; link or append the rest.
+- ❌ Optimistic examples that omit the error/failure responses an API consumer is required to handle.
+- ❌ Reinventing `runbook-generator` (incident playbooks, on-call) or `design-doc` (alternatives, approval) — stay in the explain-and-follow lane.

package/skills/guide-builder/examples/local-setup-guide.md

@@ -0,0 +1,127 @@
+# Example: raw notes → setup guide
+
+Shows the two things that make this skill earn its keep: the **style-detection call up front**, and the **verify-after-every-step** discipline that turns notes into something a stranger can follow.
+
+---
+
+## Input (what the user pasted)
+
+> need a getting-started doc for `widget-api`. it's a Go service, needs Postgres 15. clone, copy the env file (need a STRIPE_KEY from the dashboard), `make deps`, bring up postgres with docker, `make migrate`, then `make run`. it serves on 8080. there's a `/healthz`. people keep forgetting to start postgres first and then complain migrate hangs.
+
+## The skill's first line back (style detection)
+
+> Reading this as a **setup guide** — it's clone → configure → run with a defined finish line (`/healthz` answering). Two things I'm filling with defaults; correct me if wrong: end state is **running locally** (not deployed), and the prerequisite baseline assumes Go and Docker are already installed. Drafting now.
+
+## Output
+
+---
+
+# widget-api — Setup guide
+
+**Goal:** Run `widget-api` locally against a Dockerized Postgres and get a healthy response from `/healthz`.
+**Time:** ~10 minutes
+**You'll have at the end:** the API serving on `localhost:8080` with migrations applied.
+
+## Placeholders used in this guide
+
+| Placeholder | What to put | Where to get it |
+|---|---|---|
+| `<STRIPE_KEY>` | Stripe secret key for the test mode | Stripe Dashboard → Developers → API keys |
+
+## Prerequisites
+
+| Need | Version | Check it | If missing |
+|---|---|---|---|
+| Go | `>= 1.22` | `go version` | https://go.dev/dl |
+| Docker | any recent | `docker --version` | https://docs.docker.com/get-docker |
+| Postgres image | 15 | (pulled in step 3) | — |
+
+## Steps
+
+### 1. Clone the repo and enter it
+
+```bash
+git clone git@github.com:example/widget-api.git && cd widget-api
+```
+
+**You should see:** a `Makefile` in the directory — `ls Makefile`.
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+# then set in .env:
+#   STRIPE_KEY=<STRIPE_KEY>
+```
+
+**You should see:** no placeholders left — `grep '<' .env` returns nothing.
+
+### 3. Start Postgres (do this before migrating)
+
+```bash
+docker compose up -d postgres
+```
+
+**You should see:** `docker compose ps` lists `postgres` as `healthy`. Wait for `healthy` before the next step — migrating against a not-yet-ready Postgres is what makes `make migrate` appear to hang.
+
+### 4. Install Go dependencies
+
+```bash
+make deps
+```
+
+**You should see:** `go mod download` completes with no errors.
+
+### 5. Run migrations
+
+```bash
+make migrate
+```
+
+**You should see:** `migrations applied: N` and a return to the prompt within a few seconds.
+
+### 6. Start the service
+
+```bash
+make run
+```
+
+**You should see:** `widget-api listening on :8080`.
+
+## Verify it works
+
+```bash
+curl -s localhost:8080/healthz
+```
+
+**Expected:** `{"status":"ok","db":"connected"}`
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `make migrate` hangs | Postgres not `healthy` yet | Re-check step 3; wait for `healthy`, then retry |
+| `connection refused :5432` | Postgres container not up | `docker compose up -d postgres` |
+| `/healthz` returns `db:"down"` | migrations not applied | run step 5 |
+
+## Teardown
+
+```bash
+docker compose down -v
+```
+
+Removes the Postgres container and its volume. Your `.env` is left intact.
+
+## Next steps
+
+- Run the tests: `make test`
+- Reference for the endpoints this service exposes: generate one with `/guide-builder` in **API reference** style.
+
+---
+
+### Why this passes the quality bar
+
+- **Every step ends in a check** — the reader never guesses whether to continue.
+- **The one gotcha from the notes** ("people forget to start postgres") became step 3's check *and* the first troubleshooting row, instead of buried prose.
+- **The single placeholder is listed once up front**, not left as a surprise mid-command.
+- **One end-to-end verify** (`/healthz`) proves the whole chain, not just the last command.

package/skills/guide-builder/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "guide-builder",
+  "version": "0.1.0",
+  "description": "Turn raw notes, specs, or design material into an easy-to-follow guide, auto-styled to the content — a setup/quickstart, a design walkthrough, or an API/event-schema reference. Use when the user wants setup or getting-started instructions, an onboarding walkthrough of how a system works, or developer reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["brief-intake", "design-doc", "exec-summary", "runbook-generator"],
+  "tags": ["guide", "setup", "documentation", "api-reference", "onboarding", "walkthrough"],
+  "model": { "tier": "standard", "rationale": "Shapes notes into a styled guide. Generation, not adversarial review." }
+}

package/skills/guide-builder/templates/api-reference.md

@@ -0,0 +1,120 @@
+# {API / event stream name} — Developer reference
+
+**Base URL:** `{https://api.example.com/v1}`
+**Auth:** {e.g. "Bearer token in `Authorization` header; obtain via …"}
+**Versioning:** {e.g. "URL-path `/v1`; breaking changes ship a new path. See Changelog."}
+**Content type:** `application/json` unless stated.
+
+## Conventions
+
+These apply to every endpoint/event below — read once, don't repeat per item.
+
+- **Errors** return this shape:
+  ```json
+  { "error": { "code": "string", "message": "human-readable", "details": {} } }
+  ```
+- **Pagination:** {e.g. "cursor-based: pass `?cursor=`; response includes `next_cursor` (null on last page)"}
+- **Idempotency:** {e.g. "mutating calls accept an `Idempotency-Key` header; replays within 24h return the original result"}
+- **Rate limits:** {e.g. "600 req/min/token; `429` with `Retry-After` when exceeded"}
+- **Timestamps:** ISO 8601 UTC (`2026-05-26T14:30:00Z`).
+
+---
+
+## Endpoints
+
+### `{METHOD} /{path}` — {one-line purpose}
+
+{One sentence on when a consumer calls this.}
+
+**Auth:** {required scope/role, or "none"}
+
+**Path / query params**
+
+| Param | In | Type | Required | Description |
+|---|---|---|---|---|
+| `{id}` | path | string | yes | {…} |
+| `{limit}` | query | integer | no | {default, max} |
+
+**Request body**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `{field}` | string | yes | {…} |
+| `{field}` | integer | no | {default} |
+
+```json
+{ "field": "value", "field2": 42 }
+```
+
+**Response `200`**
+
+| Field | Type | Description |
+|---|---|---|
+| `{id}` | string | {…} |
+| `{status}` | enum(`a`,`b`) | {…} |
+
+```json
+{ "id": "abc_123", "status": "a", "created_at": "2026-05-26T14:30:00Z" }
+```
+
+**Errors**
+
+| Status | `error.code` | When |
+|---|---|---|
+| `400` | `invalid_request` | {…} |
+| `404` | `not_found` | {…} |
+| `409` | `conflict` | {…} |
+
+```json
+{ "error": { "code": "not_found", "message": "No resource with id abc_123" } }
+```
+
+---
+
+## Events / messages
+
+For each event a consumer subscribes to.
+
+### `{event.name}` — {one-line: what happened}
+
+- **Emitted when:** {the trigger}
+- **Transport:** {e.g. "Kafka topic `orders.v1`" / "webhook POST to your callback URL" / "SNS topic ARN …"}
+- **Delivery:** {e.g. "at-least-once; consumers MUST be idempotent on `event_id`"}
+- **Ordering:** {e.g. "ordered per `partition_key = order_id`; no global order"}
+
+**Payload**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `event_id` | string (uuid) | yes | dedup key |
+| `occurred_at` | string (ISO 8601) | yes | when the fact happened (not when delivered) |
+| `data.{field}` | string | yes | {…} |
+
+```json
+{
+  "event_id": "evt_01HX...",
+  "type": "{event.name}",
+  "occurred_at": "2026-05-26T14:30:00Z",
+  "data": { "order_id": "ord_123", "amount_cents": 4999 }
+}
+```
+
+**Consumer notes:** {what a subscriber must handle — out-of-order arrival, schema evolution, poison messages}
+
+---
+
+## Error code catalog
+
+| `error.code` | Meaning | Consumer action |
+|---|---|---|
+| `invalid_request` | malformed input | fix and retry; don't blind-retry |
+| `rate_limited` | over quota | back off per `Retry-After` |
+| `conflict` | idempotency or state clash | inspect existing resource |
+| {…} | … | … |
+
+## Changelog
+
+| Version / date | Change | Breaking? |
+|---|---|---|
+| `v1` — {YYYY-MM-DD} | initial | — |
+| {…} | … | yes/no |

package/skills/guide-builder/templates/design-walkthrough.md

@@ -0,0 +1,72 @@
+# {System / feature} — How it works
+
+**Who this is for:** {e.g. "an engineer joining the payments team" / "an adjacent team integrating with us"}
+**After reading, you'll be able to:** {concrete capability — "trace a checkout request end-to-end and know which service owns each step"}
+**Status:** describes the system as built on {YYYY-MM-DD}. For *why we chose this design*, see {link to ADRs / design-doc}.
+
+## The mental model
+
+{One paragraph or one diagram. The single idea a reader must hold to understand everything below — e.g. "Every write goes through the command bus; reads come straight from a denormalized view. Nothing reads the write tables directly."}
+
+```
+{Optional ASCII or Mermaid sketch — or link to an architecture-diagrams output. Keep it to the load-bearing boxes and arrows, not every box.}
+```
+
+## Components
+
+What each piece does and why it exists — not how to deploy it.
+
+| Component | Responsibility | Why it's separate |
+|---|---|---|
+| {name} | {one line — what it owns} | {what would break if it were merged into its neighbour} |
+| {…} | … | … |
+
+## How a {request / event / job} flows through
+
+Trace one representative path step by step. This is the heart of the walkthrough.
+
+1. **{Entry point}** — {what happens, which component, what data} → `{file or module:fn}`
+2. **{Next hop}** — {…} → `{file:fn}`
+3. **{…}** — {…}
+4. **{Result}** — {what the caller gets back / what side effect lands}
+
+> Trace it yourself: {how to watch this flow live — a log query, a trace ID, a debug endpoint}.
+
+## Key design decisions (and why)
+
+The non-obvious choices a reader will otherwise undo by accident.
+
+- **{Decision}** — {why; what was rejected}. {Link to the ADR if one exists.}
+- **{Decision}** — {…}
+
+## Data & state
+
+- **Source of truth:** {where the canonical data lives}
+- **Derived / cached:** {what's a projection of it, and how it's kept in sync}
+- **What's NOT persisted:** {e.g. "session state is in memory; a restart drops it — by design"}
+
+## Where the code lives
+
+| Concern | Path | Notes |
+|---|---|---|
+| {entry points / routes} | `{path}` | {…} |
+| {core logic} | `{path}` | start here when reading |
+| {data layer} | `{path}` | … |
+| {tests worth reading first} | `{path}` | the integration tests document the contract |
+
+## Making common changes
+
+How to do the things a new contributor will need in week one.
+
+- **Add a {new endpoint / event / field}:** {the 2–4 places to touch, in order}
+- **Change {common thing}:** {…}
+
+## Gotchas / sharp edges
+
+- ⚠️ {Non-obvious constraint that will bite — "the queue is at-least-once; handlers must be idempotent"}
+- ⚠️ {…}
+
+## Glossary
+
+- **{Term}** — {definition in this system's context, not the generic one}
+- **{Term}** — {…}

package/skills/guide-builder/templates/setup-guide.md

@@ -0,0 +1,109 @@
+# {Project / component} — Setup guide
+
+**Goal:** {one sentence — the end state, e.g. "Run the API locally with a seeded database and answer a request on `localhost:3000`."}
+**Time:** ~{N} minutes
+**You'll have at the end:** {concrete artifact — "a running server, a seeded DB, and a passing health check"}
+
+## Placeholders used in this guide
+
+Replace these everywhere they appear. Nothing else is a placeholder.
+
+| Placeholder | What to put | Where to get it |
+|---|---|---|
+| `<YOUR_API_KEY>` | {what it is} | {where to obtain it} |
+| `<DB_PASSWORD>` | {what it is} | {…} |
+
+## Prerequisites
+
+Check each before starting — a failed setup is almost always a missing prerequisite.
+
+| Need | Version | Check it | If missing |
+|---|---|---|---|
+| {Node / Python / Docker / …} | `>= {x.y}` | `node --version` | {install link / command} |
+| {…} | … | `…` | … |
+
+## Steps
+
+### 1. {Imperative — e.g. "Clone the repo and enter it"}
+
+```bash
+git clone {repo-url} && cd {repo-dir}
+```
+
+**You should see:** {what success looks like — e.g. "a `package.json` in the directory: `ls package.json`"}
+
+### 2. {Imperative — e.g. "Install dependencies"}
+
+```bash
+{exact command — e.g. `npm ci`}
+```
+
+**You should see:** {e.g. "`added 412 packages` with no errors"}
+
+### 3. {Imperative — e.g. "Configure environment"}
+
+```bash
+cp .env.example .env
+# then set:
+#   API_KEY=<YOUR_API_KEY>
+#   DB_PASSWORD=<DB_PASSWORD>
+```
+
+**You should see:** {e.g. "`.env` exists and has no remaining `<…>` placeholders: `grep '<' .env` returns nothing"}
+
+### 4. {Imperative — e.g. "Start dependencies"}
+
+```bash
+{e.g. `docker compose up -d postgres`}
+```
+
+**You should see:** {e.g. "`docker compose ps` shows postgres as `healthy`"}
+
+### 5. {Imperative — e.g. "Run migrations and seed"}
+
+```bash
+{e.g. `npm run db:migrate && npm run db:seed`}
+```
+
+**You should see:** {e.g. "`Migrations complete (3 applied)` and `Seeded 12 rows`"}
+
+### 6. {Imperative — e.g. "Start the service"}
+
+```bash
+{e.g. `npm run dev`}
+```
+
+**You should see:** {e.g. "`Listening on http://localhost:3000`"}
+
+## Verify it works
+
+One end-to-end check that proves the whole setup, not just the last step.
+
+```bash
+{e.g. `curl -s localhost:3000/health`}
+```
+
+**Expected:** {e.g. `{"status":"ok","db":"connected"}`}
+
+If you get this, you're done.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| {exact error text} | {what's actually wrong} | {command or step to fix} |
+| `ECONNREFUSED ...:5432` | Postgres not up yet | Re-run step 4; wait for `healthy` |
+| {…} | … | … |
+
+## Teardown
+
+```bash
+{e.g. `docker compose down -v`}
+```
+
+Removes {what — "containers and the local volume; your `.env` is left intact"}.
+
+## Next steps
+
+- {Where to go now — "Run the test suite: `npm test`"}
+- {Link to the design walkthrough or API reference for this project, if one exists}