@damiangilgonzalez/harness 1.3.7

package/skills/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: risco
+---
+
+# 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/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/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/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/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.

package/skills/digitalocean/scripts/verify.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# verify.sh — offline structural lint for DigitalOcean App Platform app specs.
+#
+# Read-only. Finds candidate app specs and checks they are parseable YAML with the
+# required App Platform top-level keys. Inline-secret literals are WARNINGS, not failures.
+# Exits 0 on a clean/empty target (no spec found is fine — nothing to lint).
+# Exits non-zero only when a found spec is unparseable YAML or missing required keys.
+#
+# Usage:
+#   scripts/verify.sh [path-to-spec-or-dir]   # default: current directory
+set -euo pipefail
+
+target="${1:-.}"
+fail=0
+checked=0
+
+# --- find candidate specs ----------------------------------------------------
+candidates=()
+if [ -f "$target" ]; then
+  candidates+=("$target")
+elif [ -d "$target" ]; then
+  while IFS= read -r f; do candidates+=("$f"); done < <(
+    {
+      [ -f "$target/.do/app.yaml" ] && printf '%s\n' "$target/.do/app.yaml"
+      find "$target" -type f \
+        \( -iname '*app*spec*.yml' -o -iname '*app*spec*.yaml' -o -path '*/.do/app.yaml' -o -path '*/.do/app.yml' \) \
+        2>/dev/null
+    } | sort -u
+  )
+else
+  echo "verify: target not found: $target" >&2
+  exit 0   # nothing to lint -> clean
+fi
+
+if [ "${#candidates[@]}" -eq 0 ]; then
+  echo "verify: no App Platform app spec found under '$target' — nothing to lint."
+  exit 0
+fi
+
+# --- pick a YAML parser -------------------------------------------------------
+yaml_ok() {  # $1=file -> 0 if parseable
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$1" <<'PY' 2>/dev/null
+import sys, yaml
+yaml.safe_load(open(sys.argv[1]))
+PY
+    return $?
+  elif command -v yq >/dev/null 2>&1; then
+    yq eval '.' "$1" >/dev/null 2>&1
+    return $?
+  fi
+  return 2  # no parser
+}
+
+have_key() {  # $1=file $2=key -> 0 if top-level key present (best-effort grep)
+  grep -Eq "^[[:space:]]*${2}:" "$1"
+}
+
+parser_warned=0
+
+for spec in "${candidates[@]}"; do
+  checked=$((checked + 1))
+  echo "verify: checking $spec"
+
+  yaml_ok "$spec"
+  rc=$?
+  if [ "$rc" -eq 2 ]; then
+    if [ "$parser_warned" -eq 0 ]; then
+      echo "  WARN: no python3/yq found — skipping YAML parse, doing key + secret grep only"
+      parser_warned=1
+    fi
+  elif [ "$rc" -ne 0 ]; then
+    echo "  FAIL: not parseable YAML"
+    fail=1
+    continue
+  fi
+
+  # required: name
+  if ! have_key "$spec" name; then
+    echo "  FAIL: missing required top-level key 'name'"
+    fail=1
+  fi
+
+  # required: at least one component type
+  if ! grep -Eq "^[[:space:]]*(services|static_sites|workers|jobs|functions):" "$spec"; then
+    echo "  FAIL: needs at least one of services|static_sites|workers|jobs|functions"
+    fail=1
+  fi
+
+  # warn: inline secret literals not behind a SECRET-typed env
+  if grep -Eqi 'dop_v1_[a-f0-9]|(password|secret|api[_-]?key|token)[[:space:]]*[:=][[:space:]]*["'\'']?[A-Za-z0-9/_+-]{12,}' "$spec"; then
+    echo "  WARN: a token/secret-looking literal appears inline — use 'type: SECRET' or \${...} injection"
+  fi
+done
+
+# --- optional doctl hint ------------------------------------------------------
+if command -v doctl >/dev/null 2>&1; then
+  echo "verify: doctl detected — for an authoritative check run: doctl apps spec validate <spec>"
+fi
+
+echo "verify: checked $checked spec(s)."
+exit "$fail"