@gradial/aci 0.1.52-rc.29 → 0.1.52-rc.34-e2e.1

package/templates/common/.agents/skills/dam-delivery/SKILL.md

@@ -1,228 +1,217 @@
 ---
 name: dam-delivery
-description: Mint and use signed DAM delivery URLs for on-demand image transforms, and manage public permanent URLs (permalinks) for CMS fields and email. Use when a page or server function needs a resized, cropped, or format-converted image at render time, when choosing between pre-baked derivatives and dynamic transforms, when an image URL must be pasted somewhere that cannot call a mint API (Contentful-class CMS fields, Marketo/SFMC email), or when a delivery URL returns 403/404 unexpectedly.
+description: Build and use public DAM asset links (`/dam/{assetId}`) with on-the-fly image shaping (resize, crop, format, quality). Use when a page, a CMS field, or an email needs a URL for an approved DAM asset, when choosing between a compiled content link and a shaped public link, when making an asset public or taking it down, or when a `/dam/…` URL answers 301, 403, or 404 unexpectedly.
 ---
 
-# DAM Delivery — Signed Transform URLs
+# DAM Delivery — Public Asset Links
 
-The DAM serves parameterized image transforms (resize, crop, quality,
-webp/avif) through signed URLs under `/dam/i/{assetId}/…`. The API mints
-them; clients can neither construct nor alter them — every URL is
-HMAC-signed server-side over a closed, validated parameter contract.
-
-## The One Rule: URLs Are Render-Time Artifacts
-
-Delivery URLs **expire** (24h maximum by default) and are **banned from
-published payloads**. The publish validator rejects any payload containing
-the `/dam/i/` path marker, exactly as it rejects raw `dam/blobs` pointers.
-
-- **DO** mint at render time: SSR handlers, server functions, API-backed
-  routes, previews.
-- **DO NOT** bake minted URLs into content JSON, compiled payloads, or
-  anything that gets published — a frozen release would carry URLs that
-  permanently 404 within a day.
-- For content baked into releases, keep using the pre-baked derivative
-  pipeline (`imageSlots` in contracts → `dam/derivatives/…` URLs via
-  `imageAttrs()`/`Picture`). Delivery URLs complement it; they do not
-  replace it.
-
-## Minting
-
-One endpoint mints single or batch; the request is always an array of
-parameter sets and one signed URL comes back per set, in order.
+Every approved DAM asset has one public address on the site's own domain:
 
 ```
-POST /v1/dam/assets/{assetId}/delivery-urls
-{
-  "requests": [
-    { "width": 800, "height": 600, "fit": "fill", "gravity": "noea",
-      "quality": 90, "dpr": 2, "format": "avif" },
-    { "width": 400 }
-  ]
-}
+https://{site}/dam/{assetId}
 ```
 
-Response — exactly one of `url`/`error` per item:
+Add a query to shape an image on the fly:
 
-```json
-{
-  "results": [
-    { "url": "/dam/i/ast_…/…", "expiresAt": "2026-08-16T12:00:00Z" },
-    { "error": { "status": 400, "code": "dam.delivery.invalid_param",
-                 "message": "width must be 1-4096", "details": { "param": "width" } } }
-  ]
-}
 ```
-
-Asset-level failures (asset not found, unavailable, permission denied)
-fail the whole request; parameter failures are per-item so one bad set
-cannot sink its siblings. Batches cap at 100 parameter sets.
-
-CLI equivalents:
-
-```bash
-# Single mint from flags
-aci dam delivery-url ast_2E9qL0001aBcDeF --width 800 --height 600 \
-  --fit fill --gravity noea --quality 90 --format avif --dpr 2
-
-# Batch from a JSON array (prints one URL<TAB>expiresAt line per mint)
-aci dam delivery-url ast_2E9qL0001aBcDeF \
-  --params '[{"width":400},{"width":800,"dpr":2}]'
+https://{site}/dam/{assetId}?w=640&h=384&fit=crop&fm=jpg&q=80
 ```
 
-## The Parameter Contract (Closed)
+The link is built from the asset ID alone. Nothing is minted or signed and
+nothing expires, so the same link can sit in a page, a CMS field, or an
+email for years. It always serves the newest approved public version of
+the asset.
 
-Everything outside this table is rejected. Full ranges, interactions, and
-error codes: `references/parameter-contract.md`.
+## Retired — Do Not Use
 
-| Param | Values | Default | Notes |
-| --- | --- | --- | --- |
-| `width`, `height` | 1–4096 | none | `width·dpr` and `height·dpr` must each stay ≤ 4096 |
-| `fit` | `fit` \| `fill` | `fit` | requires `width` or `height` |
-| `gravity` | `ce`, `no`, `so`, `ea`, `we`, `noea`, `nowe`, `soea`, `sowe`, or `fp:{x}:{y}` (x,y ∈ [0,1]) | `ce` | non-default gravity requires `fit: "fill"` |
-| `quality` | 1–100 | 82 | |
-| `dpr` | 1–3 | 1 | multiplies output dimensions |
-| `format` | `webp` \| `avif` \| `jpeg` \| `png` | `webp` | becomes the URL extension |
-
-Special cases:
-
-- **SVG** is passthrough-only: only the empty parameter set `{}` is
-  accepted; any transform param is rejected.
-- **Non-image assets** are never served through `/dam/i/*`; use the
-  download endpoints instead.
-- Oversized blobs (over the origin's 200 MB streaming envelope) refuse to
-  mint with `dam.delivery.source_too_large`.
-
-## Expiry Semantics
-
-- Every URL carries a signed expiry; `expiresAt` in the response is that
-  instant. After it, the URL 404s at the origin and cached copies die at
-  the CDN.
-- The bound is quantized (default 1h): identical requests minted within
-  the same quantum return **byte-equal URLs**, so re-minting per render is
-  cheap and cache-friendly. Effective lifetime is between `maxTTL − 1h`
-  and `maxTTL` (default 24h).
-- A version whose scheduled expiry revokes delivery gets URLs that expire
-  exactly at that boundary, which may be much sooner. Never assume a
-  fixed TTL — read `expiresAt`.
-- Re-mint instead of caching URLs long-term. Caching a minted URL for the
-  duration of one render/request is fine.
-
-## Availability: Why Mints Get Denied
-
-Minting serves **only the latest approved, publishable version** and fails
-closed. Expect typed errors (HTTP 422 unless noted):
-
-| Code | Meaning |
-| --- | --- |
-| `dam.asset.no_approved_version` | draft-only, embargoed, expired, or usage-restricted versions — nothing publishable |
-| `dam.asset.not_active` | archived or deleted |
-| `dam.asset.legal_hold` | under legal hold |
-| `dam.asset.blocked` | asset-wide publication block (usage restriction) |
-| `dam.permission_denied` | caller lacks download permission (403) |
-| `dam.delivery.not_image` | non-image MIME |
-
-There is no fallback to unapproved versions anywhere. Approval changes URL
-identity (new blob → new URLs on next mint); already-minted URLs keep
-serving what they named until they expire.
+Earlier SDK releases documented two delivery lanes that no longer exist.
+If you meet any of these in old content, notes, or code, replace them with
+the link above. They are not served and they do not redirect.
 
-## Public Permanent URLs (Permalinks)
+| Retired | Now |
+| --- | --- |
+| Signed URLs under `/dam/i/…`, `POST /v1/dam/assets/{assetId}/delivery-urls`, `aci dam delivery-url` | Build `/dam/{assetId}?…` yourself; there is nothing to mint |
+| Permalinks under `/dam/a/…`, `GET /v1/dam/assets/{assetId}/permalinks`, recipe URLs | `/dam/{assetId}?…` |
+| The `lifecycle.publicDelivery` flag | Approving a version makes it public (see below) |
+| `width`, `height`, `gravity`, `dpr`, `quality`, `format` | `w`, `h`, `fit`, `fm`, `q` |
 
-Assets flagged `lifecycle.publicDelivery` also serve through a **permanent,
-public URL** — Sanity-style, deterministic from the assetId alone, no mint
-API in the loop:
+## The Link
 
 ```
-https://{site}/dam/a/{assetId}?w=640&h=384&fit=crop&fm=jpg&q=80
+/dam/{assetId}[/{slug}][?w=…&h=…&fit=…&fm=…&q=…]
 ```
 
-It always resolves to the **current approved version** (approve a new
-version and pasted URLs pick it up within ~30s, no re-paste), and it dies
-within the revocation budget (≤ 30s for fresh resolution) on embargo,
-expiry, archive, or unpublish. Transform parameters are
-client-constructable but **validated and quantized** at the edge — `w`/`h`
-snap down to a fixed ladder, `q` to steps of 5 — and unknown parameter
-names (`utm_*`, `mkt_tok`, any ESP decoration) are **stripped, never
-errors**, so tracking-decorated links keep working. Invalid *values* of
-the contract params (`fm=bmp`, `w=abc`) are a 400: author error fails
-loudly. Full grammar, quantization ladder, and Sanity-style examples:
+- **`assetId`** is a raw 27-character ID made of digits and letters
+  (`0-9A-Za-z`), with no prefix. IDs that start with `ast_` are retired
+  and rejected; per ADR 0043 they are replaced by the breaking migration,
+  with no compatibility period.
+- **`slug`** is optional and cosmetic: `/dam/{assetId}/spring-sale.jpg`
+  answers with a permanent redirect to `/dam/{assetId}`, keeping the query.
+  Use it when a tool insists on a URL that ends in a file extension. The
+  slug is never checked against anything, and its extension does not pick
+  the format.
+- The CLI prints the path for an ID. It is a formatter only: it makes no
+  API call and does not tell you whether the asset is public.
+
+  ```bash
+  aci dam permalink 2E9qL0001aBcDeFgHiJkLmNoPqR
+  # /dam/2E9qL0001aBcDeFgHiJkLmNoPqR
+  ```
+
+The route is served by the deployed site's hosting edge. The site's own
+dev server (`npm run dev`) serves `/dam/…` links for assets seeded in the
+local `.content/dam/` tree; anything else answers 404 there — test it
+against the deployed domain.
+
+## Shaping an Image
+
+Five query parameters, and only these. Full rules and worked examples:
 `references/permalink-grammar.md`.
 
-**When to use which lane:**
-
-- **Signed delivery URLs** (`/dam/i/*`, above): everything that renders
-  server-side and can re-mint — SSR, server functions, previews.
-- **Permalinks** (`/dam/a/*`): places where a URL is pasted once and must
-  live for years with no code in the loop — CMS fields, Marketo/SFMC
-  email. Requires the asset to be flagged public.
-
-### Getting the URL
+| Param | Values | Default | Notes |
+| --- | --- | --- | --- |
+| `w`, `h` | whole numbers | none | 1–4096, honored exactly — no snapping or size ladder |
+| `fit` | `max` \| `crop` | `max` | `max` fits inside the box; `crop` fills it and needs both `w` and `h` |
+| `fm` | `webp` \| `avif` \| `jpg` \| `png` | `webp` | the format is always this parameter, never the browser's `Accept` header |
+| `q` | 5–100 | 80 | snapped down to steps of 5 |
+
+Three things to know before writing a link:
+
+- **Any one parameter turns shaping on, and the rest take their
+  defaults.** `?w=640` serves WebP at quality 80, not the original format.
+  To keep a JPEG a JPEG, say `fm=jpg`.
+- **No parameters means the original.** `/dam/{assetId}` streams the
+  approved file byte for byte.
+- **Nothing is rejected.** Unknown parameter names (`utm_*`, `mkt_tok`,
+  cache busters) are dropped. Out-of-range or unrecognised values are
+  snapped to an allowed one, sizes and quality always downward: `w=333`
+  serves 256, `q=77` serves 75, `fm=gif` serves WebP. Do not expect
+  pixel-exact sizes off the ladder. A `w`, `h`, or `q` that is not a
+  whole number (`w=abc`, `q=high`) is treated as if it had been left out,
+  so a typo never shrinks an image or lowers its quality.
+
+The edge settles every link on one canonical form: the parameters in the
+order `w`, `h`, `fit`, `fm`, `q`, after snapping, with `fit`, `fm`, and
+`q` always present. A link written any other way still works. A request
+already on `/dam/{assetId}` with a noncanonical query is answered with one
+permanent redirect to the canonical link (sites hosted on CloudFront tidy
+the query without a visible redirect). A request carrying a slug and a
+noncanonical query can redirect twice: once to drop the slug, once to
+canonicalize the query. Write the canonical form when you control the URL
+and you skip those hops.
+
+Shaping only applies to JPEG, PNG, WebP, and AVIF originals. Everything
+else, SVG included, is served only as a file download, never displayed
+inline. On AWS CloudFront this holds only once the hosting fix (PR #709)
+has rolled out to the tenant; until then that lane may serve SVG or HTML
+inline. See the reference for the size limits.
+
+## What Makes a Link Serve
+
+Approving a version is the "make public" act. There is no separate flag.
 
 ```
-GET /v1/dam/assets/{assetId}/permalinks
-```
-
-Returns the base permalink and per-recipe URLs (path + absolute URL), the
-grammar constants (width ladder, quality step, defaults), the
-`publicDelivery` flag state, and a `warning` field (below). CLI:
-
-```bash
-aci dam permalink ast_2E9qL0001aBcDeF               # base URL
-aci dam permalink ast_2E9qL0001aBcDeF --recipe email-hero
+POST /v1/dam/assets/{assetId}/lifecycle
+{ "action": "approve", "versionId": "…", "expectedHead": "…" }
 ```
 
-The permalink path is deterministic, so the endpoint answers even before
-the flag is flipped — check `publicDelivery` to know whether it resolves.
+Read `effects` in the response to see what happened:
 
-### Flipping the Flag
-
-`publicDelivery` is patched through the governance plane:
-
-```
-PATCH /v1/dam/assets/{assetId}/governance
-{ "expectedHead": "…", "lifecycle": { "publicDelivery": true } }
-```
-
-Flipping **on** is a "make public" act and passes the eligibility gate
-against the version the permalink would serve. A refusal is a typed 400,
-code `dam.delivery.public_flip_denied`, with `details.reason` carrying the
-gate's own reason — e.g. `no_approved_version`, `not_image`, a
-`block_new_usage` restriction, a publication-less license, or an expiry
-the lane cannot enforce. Fix the governance fact; do not retry blind.
-Flipping **off** is a plain patch and kills public serving within the
-revocation budget.
-
-### Doctrine for Email and CMS (the two rules)
-
-1. **Paste the permalink; never let the ESP import the bytes.** Many email
-   tools offer to "import" or "copy" images to their own CDN — refuse. An
-   imported copy escapes governance and revocation forever; the permalink
-   is the governed pointer, and it is precisely the ≤ 30s revocation
-   budget that makes it safe to paste.
-2. **Assets needing `block_new_usage` semantics do not get flagged
-   public.** The permalink lane cannot tell an old placement from a new
-   one, so `block_new_usage` cannot be enforced there — the flip gate
-   refuses such assets at authoring time. Use `unpublish` or
-   `block_all_usage` expiry actions (the lane enforces those boundaries
-   exactly), or keep the asset on the signed lane. If `block_new_usage`
-   governance lands on an *already-public* asset, the permalink keeps
-   serving and the permalinks API surfaces
-   `warning: "block_new_usage_in_force"` — treat that warning as "review
-   this asset's public status now".
-
-Email format tip: Outlook desktop cannot render WebP — use `fm=jpg` or
-`fm=png` in email permalinks.
+| Effect | Meaning |
+| --- | --- |
+| `live_published` | the link now serves this version |
+| `public_admission_vetoed:<cause>` | the version is approved but **not public**: it carries an expiry date, an embargo still in force, a usage block, or a license that does not allow publication. The link keeps serving the previous public version, if there is one |
+| `live_plane_unconfigured` | a local or dev stack with no delivery wired; nothing was made public |
+
+On the asset record (`GET /v1/dam/assets/{assetId}`), a public version
+shows `deliveryTier: "public"` in its governance, and a refused one shows
+`tierAdmissionVeto`.
+
+- **A newer approved version takes over the same link.** Nothing needs
+  re-pasting.
+- **To take a link down**, `demote` the version (the link falls back to
+  the previous public version, or stops serving if there is none) or
+  `archive` the asset. Both use the same lifecycle endpoint.
+- **Governance that would have blocked the approval cannot be added while
+  a version is public.** A patch adding an expiry date, an embargo, a
+  usage block, or a license without publication is refused with a
+  conflict that tells you to demote first.
+- **Changes take up to five minutes to show everywhere.** Responses are
+  `Cache-Control: public, max-age=300`, so a new version or a take-down
+  can lag by that long in browsers and CDN caches. On AWS CloudFront,
+  cached copies can currently outlive that window — the image pipeline
+  sets a one-year TTL and the distribution permits it — until the hosting
+  lane is corrected; the five minutes holds for Vercel and Cloudflare. Do
+  not treat a public link as instantly revocable, and do not re-cache it
+  for longer downstream.
+
+## Compiled Content Link or a Public Link?
+
+- **Images a page renders from content: use the compiled live link.**
+  Author a `dam.assetRef` (asset id + alt); the compiler emits the
+  versionless permalink and the SDK asset component builds the `srcset`
+  from the slot's declared widths at render time. Declare `imageSlots` in
+  the contract and render with `imageAttrs()` or `Picture`; you never
+  construct a URL. There is no pre-baked derivative pipeline — publish
+  stages no asset bytes.
+- **A URL that lives outside the build: use the public link.** A field in
+  an external CMS, an email, a social card, a partner page, or a one-off
+  size that no slot declares.
+
+The difference that matters: a compiled link follows approval and take-down
+through each publish, while a public link follows them on its own, within
+the five-minute window.
+
+Published content may carry `/dam/{assetId}` links. The publish check
+rejects a payload that contains a raw source path (`dam/blobs/…`) or a
+retired `/dam/a/` or `/dam/i/` path.
+
+## Email and External CMS Fields
+
+1. **Paste the link; never let the tool import the bytes.** Many email
+   tools offer to "import" or "copy" images to their own CDN. Refuse. An
+   imported copy escapes approval and take-down forever; the link is the
+   governed pointer.
+2. **Always set `fm=jpg` or `fm=png` in email.** The default is WebP, and
+   Outlook desktop cannot render WebP.
+3. **Use the slug form when a tool wants a file extension:**
+   `/dam/{assetId}/spring-sale.jpg?w=640&fm=jpg`.
+4. **`block_new_usage` does not take a public link down.** The link cannot
+   tell an old placement from a new one, so an asset under that
+   restriction keeps serving where it is already pasted. To stop serving,
+   demote or archive.
+
+## When a Link Does Not Serve
+
+Errors are never cached (`no-store`) on Vercel and Cloudflare. On AWS
+CloudFront, 403 and 5xx responses may be cached by the distribution for up
+to about ten seconds regardless of `no-store`. Exact codes differ slightly
+between hosting providers, so treat any 4xx as "not served".
+
+| You see | Why | Do |
+| --- | --- | --- |
+| 301 | a slug was dropped or the query was put in canonical form | follow it; write the canonical link next time |
+| 403 | the asset has no public version (never approved, approval vetoed, demoted, archived, or expired), or the ID is malformed | check `effects` from the approve call and `deliveryTier` on the asset record |
+| 404 | a retired `/dam/a/…` or `/dam/i/…` path, DAM delivery is not enabled for this site, or you are on the local dev server | rewrite the link; ask the operator to enable DAM delivery |
+| 413 | the original is too large to shape | drop the query to get the original, or upload a smaller master |
+| 415 | shaping was asked of a non-image original | drop the query |
+| 503 | delivery could not read its own state and refused rather than guess | retry; if it persists, it is an operator issue |
+| A download instead of an image | the original is not JPEG, PNG, WebP, or AVIF | by design; render SVGs through the site's own image pipeline |
 
 ## Draft Previews (Management Surfaces Only)
 
-Drafts are reachable only by naming their version — authenticated, never
-CDN-cached, never via `/dam/i/*`:
+The public link never serves a draft. A draft or rejected version is
+reachable only by an authenticated caller with read permission on the
+asset, and only by naming the exact version:
 
 ```
-GET /v1/dam/assets/{assetId}/versions/{versionId}/preview?width=512
-GET /v1/dam/assets/{assetId}/versions/{versionId}/download
+GET /v1/dam/assets/{assetId}/versions/{versionId}/preview
 ```
 
-The preview takes the same transform parameters as query strings and
-streams the transformed image with `Cache-Control: private, no-store`.
-Use these for editorial UIs; never for site rendering.
+It answers `302` to a short-lived signed URL: for JPEG, PNG, GIF, and WebP
+up to 20 MiB, a WebP of that version downsampled at upload (longest edge
+1024 px, never upscaled); for SVG, formats the server does not decode
+(HEIC, AVIF, TIFF, BMP), or a version whose preview is not generated yet,
+the original. Follow the redirect without forwarding your bearer token. It
+takes no shaping parameters. Use it for editorial UIs and thumbnails,
+never for site rendering.