@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/design/references/design-md.md

@@ -0,0 +1,49 @@
+# DESIGN.md: the record of the system
+
+Adapted from impeccable's `document` by Paul Bakaus (Apache-2.0), which follows the open
+`design.md` format. Rewritten and shortened.
+
+The point: the next edit, the next session and the next tool keep the look instead of drifting back
+to the model's default. Write it **after** the build, from what was actually built and measured,
+never before. A rulebook written ahead of the build gets defended against reality.
+
+## Where and when
+
+- `DESIGN.md` at the project root, committed with the code.
+- Written when a surface creates or replaces the visual system. Extending an existing surface reads
+  it and does not rewrite it.
+- If `02-DOCS/wiki/brand/` exists, `DESIGN.md` uses the brand's colours and faces and names that
+  file as its source.
+
+## Shape
+
+YAML front matter holds the tokens; the body explains them.
+
+```markdown
+---
+name: <product>
+description: <one line: the idea sentence>
+colors:
+  ground: "#…"
+  ink: "#…"
+  accent: "#…"
+  field: "#…"
+typography:
+  display: { fontFamily: "…", fontWeight: 600, letterSpacing: "-0.03em", lineHeight: 0.95 }
+  text: { fontFamily: "…", fontSize: "18px", lineHeight: 1.5 }
+rounded: { button: "0px", media: "0px" }
+spacing: { margin: "24px", section: "200px" }
+direction: { id: "<dealt id>", seed: <n> }
+---
+
+## Overview        the idea, the mode, the direction and why it was chosen
+## Colors          roles and proportions (one ground, one ink, one accent, fields)
+## Typography      the scale actually used, tracking, measure
+## Layout          grid, outer margins, section rhythm, the phone composition
+## Imagery         sources, crops, treatment, where credits live
+## Motion          the signature move and the entrance recipe
+## Components      buttons, navigation, the live thing, footer
+## Do's and Don'ts the house rules this project relies on, plus any `--allow` and its reason
+```
+
+Values come from the built CSS and the inspector's measurements, not from memory.

package/skills/shared/design/references/finish-review.md

@@ -0,0 +1,46 @@
+# The fresh review
+
+Adapted from impeccable's finish reviewer by Paul Bakaus (Apache-2.0); rewritten and shortened.
+
+The builder believes its own page. The review runs **outside** the build: a fresh subagent with no
+history of this conversation, so it does not inherit the builder's framing or optimism. Without
+subagents, step fully out of the build and run the same checks yourself, and say in the report that
+the review was not independent.
+
+## The packet
+
+Hand it only this:
+
+- the original request and the user's answers;
+- the screenshots from `.taste-skill/inspect/` at every width (the reviewer has no browser);
+- the last `inspect.mjs` result;
+- the direction sheet (`draw.mjs --show`), the idea sentence and the live thing;
+- the paths of `../engine/RUN.md` (house rules) and `../engine/references/critique.md`.
+
+## The checks, in order
+
+0. **Evidence.** Every width captured, no blank or half-loaded screenshot, content where the
+   filename says. If one fails, the answer is `recapture` and nothing else.
+1. **First screen.** Within five seconds: what is this, why does it matter, what do I do?
+2. **The idea.** Is the idea sentence visible on the page, in every section, and does it fail the
+   competitor test (would it work for the nearest competitor)?
+3. **The direction.** Was the dealt direction built, or did the build drift back to the layout the
+   model would have made anyway?
+4. **Substance.** Real pictures, full content, no screen that is mostly empty ground.
+5. **Truth.** No invented customers, quotes, numbers or logos. Sample content marked.
+6. **Floor.** The house rules in `../engine/RUN.md`, plus what screenshots show and code hides:
+   states (hover, focus, loading, empty, error), themed selection and focus rings, text that fits.
+
+## The four words
+
+The first line of the answer is exactly one of these. The word follows from the checks:
+
+- `recapture`: the evidence failed, not the page. Capture again, then a full review.
+- `rebuild`: the focal element or the direction itself is wrong. Re-derive it; patches will not do.
+- `fix`: an ordered list of material fixes, at most eight, most important first.
+- `ship`: nothing material remains.
+
+Then: `fixes` (when `fix`) and `keep`, one line naming what must not be diluted while fixing.
+Apply the fixes in one batch, run the gate again, and send the new screenshots back for a verdict
+on each fix: resolved, partial or unresolved. Two rounds at most. A partial or unresolved fix
+never becomes `ship`. Report the reviewer's word as it was given.

package/skills/shared/design/references/modes.md

@@ -0,0 +1,51 @@
+# The four modes
+
+Adapted from impeccable by Paul Bakaus (Apache-2.0); rewritten and shortened. The mode names what
+the visitor's success looks like on this surface. Pick it from the surface, never the product: a
+developer tool's landing page is Persuade, a fashion house's docs are Read.
+
+## Persuade
+
+The visitor decides and acts. The design is what they judge.
+
+- The first screen makes the offer clear and shows **the action visitors came to take, working**: a
+  flight search, open appointment slots, add to cart. A button that points somewhere else is not it.
+- The subject's world carries the page; it is never painted over it as a poster with no working parts.
+- Refuse both ends: the poster, and the stock product page (headline, subline, button, a row of
+  equal cards; or the split hero with a badge row under it).
+
+## Experience
+
+The visitor is inside the work: portfolio, gallery, showcase. The work leads from the first
+viewport and the interface recedes. Same page run as Persuade.
+
+## Operate
+
+The visitor completes a task. Someone who uses tools like this should know where everything is
+before they notice the style.
+
+- The direction lends four things only: **type, palette, density and one signature move** (service
+  health drawn as a transit map, a schedule in a timetable's column rhythm). Never the layout, the
+  navigation model or the controls.
+- Every control is the standard one the visitor already knows. No costume of a terminal, an
+  instrument bezel or ledger paper.
+- Colour does real jobs: a committed shell, state colours, data series, selection. A grey screen
+  with one accent is the category default without its polish.
+- Realistic data with units and one state worth seeing (an alert, a degraded service, an empty
+  filter). Never grey placeholder bars.
+- The bar is the cleanest product in its category; the signature move adds to that, never replaces it.
+
+The run, rules and checks for these screens: `../engine/references/app-screens.md`
+(`draw.mjs --app`, `inspect.mjs --app`).
+
+## Read
+
+The visitor understands something: docs, guide, article, changelog.
+
+- The style owns **the frame**: masthead, rail, ground, title and section openers, how code and
+  tables are set. That is where palette, type and the signature move commit fully.
+- The reading column stays calm: a reading face, real contrast, about 60–75 characters at about
+  16px. No monospace prose. Nothing performs behind the text.
+- The style never supplies the reading order or replaces the navigation with something to learn.
+- Check: can a reader tell where they are, where to go next, and read comfortably? Cover the name:
+  could this be any other product's docs? Then the frame has not taken the style yet.

package/skills/shared/digitalocean/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: digitalocean
+description: "Use when deploying or operating a workload on DigitalOcean — Droplet vs App Platform vs Functions, doctl, app spec YAML, Managed Postgres/MySQL/Valkey on the VPC, S3-compatible Spaces + CDN. NOT host-agnostic CI/CD or rollback strategy (that is `deployment`), NOT a bare Hetzner VPS (that is `hetzner`), NOT another managed PaaS (that is `railway`)."
+tags: [digitalocean, doctl, app-platform, droplets, spaces, deployment, paas, vps]
+recommends: [deployment, postgresdb, docker, domains-dns, monitoring, scaling, hetzner]
+origin: ai-hub
+---
+
+# DigitalOcean — Droplet vs App Platform, doctl, Managed DBs, Spaces
+
+You own one decision: **where on DO does this run, and how do I ship it.** Host-agnostic
+CI/CD, release gating and rollback strategy are `../deployment/SKILL.md`; authoring the
+Dockerfile is `docker`; DNS records and the registrar are `domains-dns`; a bare Hetzner box
+and its economics are `hetzner`. Pick the compute model first, then wire data and storage,
+then the ops that bite in production.
+
+```text
+workload → [Droplet | App Platform | Functions] → Managed DB (VPC private host) → Spaces (S3 + CDN)
+              raw VPS    managed PaaS   event fn        Postgres/MySQL/Valkey         object store
+```
+
+## The core decision: Droplet vs App Platform vs Functions
+
+Settle this before writing a single command. Most web apps want App Platform; reach for a
+Droplet only when you need the box itself.
+
+| Axis | Droplet (VPS) | App Platform (PaaS) | Functions |
+| --- | --- | --- | --- |
+| Control | Full root, any daemon, any port | Build+run only, no SSH | Per-invocation, no host |
+| Ops burden | You patch/secure/restart it | DO runs it, auto TLS, auto deploy | Zero infra |
+| Price floor | Per-second billing since 2026-01-01, min 60s or $0.01 | 3 static sites free; dynamic from $5/mo per service | Pay per call |
+| Scaling | Resize/clone/load-balance yourself | Set instance count + size, autoscale | Implicit |
+| Best for | Stateful daemons, cron hosts, custom networking, "give me a Linux box" | Web service / API / worker / static site from a repo | Event glue, webhooks |
+
+Rules of thumb:
+
+- **Stateless web service or API from a Git repo → App Platform.** It builds, deploys, gives
+  you TLS and a URL, and re-deploys on push. No box to patch. **Static frontend → App
+  Platform static site (free, up to 3)**; don't run a Droplet to serve HTML.
+- **You need root, a long-lived stateful daemon, custom ports, or a cron host → Droplet.**
+- **A managed Postgres/MySQL/Valkey → always the Managed Database product**, never a DB you
+  hand-install on a Droplet, unless you have a hard reason.
+
+## doctl setup
+
+`doctl` is the official DO CLI; it drives everything below.
+
+```bash
+# macOS
+brew install doctl
+# Linux: download the release tarball from github.com/digitalocean/doctl/releases, then:
+#   tar xf doctl-*.tar.gz && sudo mv doctl /usr/local/bin
+
+# Authenticate with a token from cloud.digitalocean.com/account/api/tokens
+doctl auth init                       # pastes a token, validates, stores a context
+doctl auth init --context prod        # a named context per account/env
+doctl auth switch --context prod      # switch the active context
+doctl account get                     # verify the token works
+```
+
+**Never commit the token.** It is a full-account credential. Keep it in your shell keychain,
+a secret manager, or CI secret — never in the repo, never in an app spec. Why: a leaked
+`dop_v1_…` token lets anyone create/destroy your whole account.
+
+## App Platform via app spec
+
+App Platform deploys from an **app spec** (YAML or JSON). Treat the spec as the source of
+truth, version it, and apply it with doctl.
+
+```yaml
+# .do/app.yaml — minimal web service + managed Postgres
+name: my-api
+region: nyc
+services:
+  - name: web
+    github:
+      repo: me/my-api
+      branch: main
+      deploy_on_push: true
+    instance_size_slug: apps-s-1vcpu-1gb   # ~$5/mo basic; sizes go up to dedicated
+    instance_count: 1
+    http_port: 8080
+    envs:
+      - key: NODE_ENV
+        value: production
+        scope: RUN_TIME              # RUN_TIME | BUILD_TIME | RUN_AND_BUILD_TIME
+      - key: DATABASE_URL
+        value: ${db.DATABASE_URL}    # injected from the managed DB below
+        scope: RUN_TIME
+      - key: API_SIGNING_KEY
+        value: ${API_SIGNING_KEY}
+        type: SECRET                 # encrypted at rest; never plaintext
+        scope: RUN_TIME
+databases:
+  - name: db
+    engine: PG
+    production: true
+```
+
+Lifecycle — validate, then create or update:
+
+```bash
+doctl apps spec validate .do/app.yaml          # structural lint, no deploy
+doctl apps create --spec .do/app.yaml          # first deploy; prints the app id
+doctl apps update <app-id> --spec .do/app.yaml # apply changes (and to roll back: re-apply the prior spec)
+doctl apps list                                # find the id
+```
+
+Env scoping that matters:
+
+- `type: SECRET` encrypts the value at rest and hides it in the dashboard. Use it for every
+  key, token, password. Plain `value:` is readable.
+- `scope: BUILD_TIME` for things only the build needs; `RUN_TIME` for runtime; don't leak
+  build-only secrets into the running container.
+- `${db.DATABASE_URL}` (and `${db.HOSTNAME}`, `${db.PORT}`, etc.) are auto-injected when the
+  service references a `databases:` entry — you never paste the connection string.
+
+Operate:
+
+```bash
+doctl apps logs <app-id> --type run --follow     # run | build | deploy
+doctl apps logs <app-id> <component> --type run  # one component
+```
+
+**Rollback = re-apply the previous spec** (git-revert `.do/app.yaml` and `doctl apps update`),
+or redeploy a prior deployment from the dashboard. There is no magic rollback verb — your
+git history of the spec is the rollback mechanism.
+
+For multi-component apps (web + worker + static_site + job + db, health checks, ingress
+routes, autoscaling, instance-size table, alerts) see `references/app-spec.md`.
+
+## Droplets
+
+A Droplet is a Linux VPS. Bootstrap it declaratively, lock it down with a *cloud* firewall.
+
+```bash
+doctl compute droplet create web-1 \
+  --region nyc3 --size s-1vcpu-1gb --image ubuntu-24-04-x64 \
+  --ssh-keys <fingerprint> \
+  --vpc-uuid <vpc-uuid> \
+  --user-data-file cloud-init.yaml \
+  --wait
+```
+
+- **Cloud firewall, not just `ufw`.** A cloud firewall filters at DO's edge before traffic
+  reaches the box, and applies to a tag/group of Droplets. Use it as the real perimeter;
+  host `ufw` is defense-in-depth, not the only line. Why: a misconfigured `ufw` after a
+  reboot still leaves the edge firewall protecting you.
+- **Reserved IP is free while assigned to a Droplet** (you pay only when it's unassigned).
+  Assign one so you can re-point it to a replacement Droplet without DNS changes — that's
+  your failover handle.
+- **Snapshots/backups** are your restore path; enable automated backups or snapshot before
+  risky changes.
+- **Per-second billing since 2026-01-01** (min 60s or $0.01): short-lived Droplets are cheap
+  to spin up and destroy, but a powered-off Droplet still bills for storage — destroy, don't
+  just power off, to stop charges.
+
+Cloud-init recipes, firewall inbound/outbound rule sets, snapshot cadence + restore,
+reserved-IP failover, and the VPC + private-DB layout live in `references/droplet-ops.md`.
+
+## Managed Databases
+
+Use the Managed Database product for Postgres/MySQL/Valkey — DO handles patching, failover,
+and backups.
+
+- **Provision sizing:** managed Postgres starts ~$15/mo single node; HA (primary+standby)
+  from ~$30/mo; read replicas available for read scaling.
+- **Connect over the VPC private host, not the public one.** Same-region Droplets and
+  Managed DBs talk over the VPC with no bandwidth charge and sub-ms latency, and the private
+  host keeps the DB off the public internet. Add the app's Droplet/App as a **trusted source**
+  so only it can connect.
+- **Connection pooling (PgBouncer) is built in.** Use a pool when many short-lived clients
+  (serverless, lots of App Platform instances) would otherwise exhaust connections — a
+  cluster supports up to ~21 pools / up to ~1,000 connections depending on size, and the
+  pool listens on a **separate pool port** from the raw DB port. Point your app at the pool
+  connection string, not the raw one.
+- For schema design, indexing, query tuning, migrations → that's `../postgresdb/SKILL.md`,
+  not here. This skill only provisions and wires the cluster.
+
+## Spaces (S3-compatible object storage + CDN)
+
+Spaces is S3-API-compatible object storage with a built-in CDN.
+
+- **$5/mo includes 250 GiB storage + 1 TiB outbound transfer**; inbound is free; the CDN is
+  included at no extra cost across 200+ edge locations.
+- **Spaces keys are NOT your API token.** Generate a separate Spaces access key + secret;
+  the doctl/API token does not work for S3 operations.
+- **Use any S3 SDK or `aws-cli`/`s3cmd`** against the regional endpoint:
+
+```python
+# boto3 against DO Spaces (nyc3 region/endpoint)
+import boto3
+s3 = boto3.client(
+    "s3",
+    endpoint_url="https://nyc3.digitaloceanspaces.com",
+    region_name="nyc3",
+    aws_access_key_id="<SPACES_KEY>",       # Spaces key, not the DO API token
+    aws_secret_access_key="<SPACES_SECRET>",
+)
+s3.upload_file("photo.jpg", "my-bucket", "photo.jpg", ExtraArgs={"ACL": "public-read"})
+```
+
+Serve public assets through the bucket's CDN edge URL; set **CORS** on the bucket if a
+browser fetches it cross-origin, and a **lifecycle** rule to expire/transition old objects.
+
+## Basic ops + cost gotchas
+
+- Set **alerts** on the app/DB (deploy failures, CPU, restart count) so you hear about
+  trouble before users do. App-level dashboards/alerting *strategy* is `../monitoring`.
+- **Scale** by editing `instance_count`/`instance_size_slug` in the spec and re-applying;
+  capacity *strategy* that's host-agnostic is `../scaling`.
+- **App Platform data transfer overage is $0.02/GiB**, billed separately from Droplet
+  transfer — a chatty media app can run up a bill; front heavy static assets with Spaces+CDN.
+- **An unassigned reserved IP is billed.** Release reserved IPs you're not using.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Hardcoding a `dop_v1_…` token or DB password as a plain `value:` in the app spec | Spec is in git, value is readable, full-account compromise | `type: SECRET` env, or `${db.*}` injection; token only in `doctl auth` |
+| Connecting app→DB over the public host | Public exposure + egress cost + latency | VPC private host + trusted source |
+| Running a stateful long-lived daemon as an App Platform service | Components are restartable/stateless; state is lost | Droplet (or a job/worker designed to be stateless) |
+| Sizing a dedicated `apps-d-2vcpu-4gb` (~$78/mo) for a hobby app | Paying enterprise rates for toy traffic | Start `apps-s-1vcpu-1gb` (~$5) and scale up on real metrics |
+| `ufw` on the Droplet as the only firewall | A bad reboot/config leaves the host open | Cloud firewall at the edge + host `ufw` as defense-in-depth |
+| Hand-installing Postgres on a Droplet "to save money" | You now own patching, backups, failover | Managed Database unless you have a hard reason |
+| Powering off a Droplet to stop billing | Powered-off Droplets still bill for storage | Snapshot then destroy |
+| Leaving a reserved IP unassigned | It's billed when not attached | Release it |

package/skills/shared/digitalocean/evals/README.md

@@ -0,0 +1,10 @@
+# Evals — digitalocean
+
+`cases.yaml` is a routing + capability fixture, not an auto-runner. To use it: feed each
+`should_trigger` prompt to the skill router and confirm `digitalocean` fires; feed each
+`should_not_trigger` prompt and confirm it does NOT fire but defers to the named `route_to`
+sibling. For the `capability` case, run the scenario through the agent and judge the
+resulting transcript against the `must_include` rubric — every item should be present and
+correct (doctl auth, an app spec with a service + envs, the DB wired via `${db.*}`/VPC, the
+validate→create/update flow, logs + spec-revert rollback, and a cost note). Score it by hand
+or with an LLM judge; there is no pass/fail script here.

package/skills/shared/digitalocean/evals/cases.yaml

@@ -0,0 +1,37 @@
+skill: digitalocean
+
+should_trigger:
+  - prompt: "Deploy my Node API to DigitalOcean App Platform"
+    why: Direct request to ship a service to App Platform — the skill's core compute decision and app spec flow.
+  - prompt: "Droplet or App Platform for my Rails app — which is cheaper to run?"
+    why: DO-specific compute decision (Droplet vs App Platform) with a pricing axis the decision table answers.
+  - prompt: "Write me a DigitalOcean app spec yaml that runs a web service with a managed postgres"
+    why: Asks for the checkable artifact (app spec YAML) with a ${db.*}-wired Managed Database.
+  - prompt: "Subir mi web a DigitalOcean con doctl"
+    why: Spanish trigger — deploying a site to DO via doctl is squarely this skill.
+  - prompt: "I need an S3-compatible bucket with a CDN on DigitalOcean"
+    why: Non-obvious — the user never says "Spaces", but S3-compatible object storage + CDN on DO is exactly Spaces.
+
+should_not_trigger:
+  - prompt: "Design my GitHub Actions deploy pipeline with rollback gating"
+    route_to: deployment
+    why: Host-agnostic CI/CD pipeline and rollback strategy, not where-on-DO-it-runs.
+  - prompt: "Is Hetzner cheaper than DO for a 16GB VPS?"
+    route_to: hetzner
+    why: The decision tilts to the other host's economics; Hetzner owns its own VPS sizing/pricing.
+  - prompt: "Optimize this slow Postgres query with a better index"
+    route_to: postgresdb
+    why: Database internals (query/index tuning), not provisioning a DO cluster.
+  - prompt: "Write the Dockerfile for my app"
+    route_to: docker
+    why: Containerizing the app itself; this skill consumes an image, it doesn't author one.
+
+capability:
+  - scenario: "Ship a Node web service plus a managed Postgres to App Platform from scratch."
+    must_include:
+      - "doctl auth init with an API token from cloud.digitalocean.com/account/api/tokens"
+      - "An app spec YAML with a services entry (github repo, http_port, instance_size_slug) and envs"
+      - "DB wired via ${db.DATABASE_URL} (and/or trusted source over the VPC private host)"
+      - "doctl apps spec validate, then doctl apps create --spec / doctl apps update --spec"
+      - "Logs via doctl apps logs and rollback by re-applying the prior spec"
+      - "A cost/sizing note (basic from $5/mo, $0.02/GiB transfer overage, or unassigned reserved IP charge)"

package/skills/shared/digitalocean/references/app-spec.md

@@ -0,0 +1,126 @@
+# App Platform app spec — full reference
+
+The app spec is the single source of truth for an App Platform app. Version it in
+`.do/app.yaml`, validate, then `create`/`update`. Below is a multi-component spec with the
+fields you'll actually reach for.
+
+```yaml
+name: my-platform
+region: nyc
+
+# --- HTTP service: gets a public URL + auto TLS ------------------------------
+services:
+  - name: web
+    github:
+      repo: me/my-platform
+      branch: main
+      deploy_on_push: true
+    build_command: npm ci && npm run build
+    run_command: node dist/server.js
+    instance_size_slug: apps-s-1vcpu-1gb
+    instance_count: 2
+    http_port: 8080
+    routes:
+      - path: /                       # ingress route for this component
+    health_check:
+      http_path: /healthz
+      initial_delay_seconds: 10
+      period_seconds: 10
+      failure_threshold: 3
+    autoscaling:                      # optional: scale instances on CPU
+      min_instance_count: 2
+      max_instance_count: 5
+      metrics:
+        cpu:
+          percent: 70
+    envs:
+      - key: DATABASE_URL
+        value: ${db.DATABASE_URL}
+        scope: RUN_TIME
+      - key: STRIPE_SECRET
+        value: ${STRIPE_SECRET}
+        type: SECRET
+        scope: RUN_TIME
+
+# --- background worker: no public route --------------------------------------
+workers:
+  - name: queue-worker
+    github:
+      repo: me/my-platform
+      branch: main
+      deploy_on_push: true
+    run_command: node dist/worker.js
+    instance_size_slug: apps-s-1vcpu-1gb
+    instance_count: 1
+    envs:
+      - key: DATABASE_URL
+        value: ${db.DATABASE_URL}
+        scope: RUN_TIME
+
+# --- static frontend: free (up to 3), served from the edge -------------------
+static_sites:
+  - name: marketing
+    github:
+      repo: me/my-platform-web
+      branch: main
+    build_command: npm ci && npm run build
+    output_dir: dist
+    routes:
+      - path: /site
+
+# --- one-off / pre-deploy job (e.g. migrations) ------------------------------
+jobs:
+  - name: migrate
+    kind: PRE_DEPLOY                  # PRE_DEPLOY | POST_DEPLOY | FAILED_DEPLOY
+    github:
+      repo: me/my-platform
+      branch: main
+    run_command: npm run migrate
+    instance_size_slug: apps-s-1vcpu-1gb
+    envs:
+      - key: DATABASE_URL
+        value: ${db.DATABASE_URL}
+        scope: RUN_TIME
+
+# --- managed database referenced by ${db.*} ----------------------------------
+databases:
+  - name: db
+    engine: PG                        # PG | MYSQL | REDIS (Valkey)
+    production: true
+    # or attach an existing cluster:
+    # cluster_name: my-existing-cluster
+
+# --- alerts ------------------------------------------------------------------
+alerts:
+  - rule: DEPLOYMENT_FAILED
+  - rule: DOMAIN_FAILED
+```
+
+## Env scoping
+
+| Field | Values | Use it for |
+| --- | --- | --- |
+| `scope` | `RUN_TIME`, `BUILD_TIME`, `RUN_AND_BUILD_TIME` | Keep build-only secrets out of the running container; runtime-only out of the build |
+| `type` | (default plaintext), `SECRET` | `SECRET` for every token/password/key — encrypted at rest, hidden in dashboard |
+| `value` | literal or `${...}` | `${db.DATABASE_URL}` / `${db.HOSTNAME}` from a `databases:` entry; `${OTHER_COMPONENT.HOSTNAME}` for inter-component |
+
+## Instance size slugs (common)
+
+| Slug | Class | Rough price |
+| --- | --- | --- |
+| `apps-s-1vcpu-0.5gb` / `apps-s-1vcpu-1gb` | Basic | from ~$5/mo per service |
+| `apps-s-1vcpu-2gb` | Basic | ~$25/mo |
+| `apps-d-1vcpu-2gb` / `apps-d-2vcpu-4gb` | Dedicated | ~$78/mo at the 2vcpu/4gb tier |
+
+Start at the smallest basic slug. Move to dedicated only when shared-CPU contention shows up
+in real metrics. Dynamic apps start at $5/mo per service; data-transfer overage is $0.02/GiB.
+
+## Commands
+
+```bash
+doctl apps spec validate .do/app.yaml          # offline structural lint
+doctl apps create --spec .do/app.yaml          # first deploy
+doctl apps update <app-id> --spec .do/app.yaml # apply / roll back (re-apply prior spec)
+doctl apps spec get <app-id> > .do/app.yaml    # pull the live spec back into git
+doctl apps logs <app-id> <component> --type run --follow
+```

package/skills/shared/digitalocean/references/droplet-ops.md

@@ -0,0 +1,95 @@
+# Droplet ops — cloud-init, cloud firewall, snapshots, reserved IP, VPC
+
+A Droplet is a Linux VPS you own end to end. The discipline below keeps it secure and
+recoverable. Per-second billing has applied since 2026-01-01 (min 60s or $0.01) — short-lived
+Droplets are cheap, but storage bills even when powered off, so **destroy** rather than power
+off to stop charges.
+
+## Bootstrap with cloud-init (user-data)
+
+Pass a cloud-init file so the box is configured on first boot — no manual SSH-and-poke.
+
+```yaml
+# cloud-init.yaml
+#cloud-config
+package_update: true
+packages:
+  - ufw
+  - fail2ban
+users:
+  - name: deploy
+    groups: sudo
+    shell: /bin/bash
+    ssh_authorized_keys:
+      - ssh-ed25519 AAAA... you@host
+runcmd:
+  - ufw allow OpenSSH
+  - ufw --force enable
+  - systemctl enable --now fail2ban
+```
+
+```bash
+doctl compute droplet create web-1 \
+  --region nyc3 --size s-1vcpu-1gb --image ubuntu-24-04-x64 \
+  --ssh-keys <fingerprint> --vpc-uuid <vpc-uuid> \
+  --user-data-file cloud-init.yaml --wait
+```
+
+## Cloud firewall (the real perimeter)
+
+A DO cloud firewall filters at the edge before traffic hits the box and applies to a tag, so
+new Droplets with that tag inherit it automatically. Treat host `ufw` as defense-in-depth.
+
+```bash
+doctl compute firewall create \
+  --name web-fw \
+  --tag-names web \
+  --inbound-rules "protocol:tcp,ports:22,address:<your.office.ip>/32 protocol:tcp,ports:80,address:0.0.0.0/0,address:::/0 protocol:tcp,ports:443,address:0.0.0.0/0,address:::/0" \
+  --outbound-rules "protocol:tcp,ports:all,address:0.0.0.0/0,address:::/0 protocol:udp,ports:all,address:0.0.0.0/0,address:::/0"
+```
+
+Principles:
+
+- Restrict SSH (22) to known IPs, not `0.0.0.0/0`.
+- Open only the ports the service needs (80/443 for web).
+- Keep DB ports closed at the edge entirely — the DB should be reached over the VPC, never
+  the public internet.
+
+## Snapshots & backups
+
+- Enable **automated backups** for set-and-forget restore points.
+- Take a **manual snapshot before any risky change** (kernel upgrade, migration host).
+- Restore by creating a new Droplet from the snapshot/backup image, then re-point the
+  reserved IP at it.
+
+```bash
+doctl compute droplet-action snapshot <droplet-id> --snapshot-name pre-upgrade --wait
+doctl compute snapshot list
+```
+
+## Reserved IP failover
+
+A reserved IP is **free while assigned** to a Droplet, billed when unassigned. Keep your
+public DNS pointed at the reserved IP, never at a Droplet's ephemeral IP. To fail over:
+
+```bash
+doctl compute reserved-ip-action assign <reserved-ip> <new-droplet-id>
+```
+
+Traffic moves to the replacement Droplet without touching DNS. Release reserved IPs you no
+longer use so they stop billing.
+
+## VPC + private DB layout
+
+Put app Droplets and the Managed Database in the **same VPC and region**. Then:
+
+- App → DB traffic rides the VPC private host: no bandwidth charge, sub-ms latency, off the
+  public internet.
+- Add the app Droplet (or its tag) as a **trusted source** on the DB so nothing else can
+  connect, even with the credentials.
+- The public web edge only ever sees ports 80/443 on the app Droplets; the DB has no public
+  ingress at all.
+
+In prose, the topology is: `internet → cloud firewall (80/443) → app Droplets (VPC) →
+private DB host (trusted source) → Managed Postgres`. Spaces sits outside the VPC and is
+reached over its S3 endpoint with Spaces keys.