@civitai/app-sdk 0.51.2 → 0.53.0

package/README.md

@@ -446,7 +446,7 @@ The starters in `civitai/civitai-app-starters` wire this into framework-specific
 
 ## Choosing a workflow step type
 
-The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (50 in total).
+The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (51 in total).
 
 The catalog is pinned to the orchestrator's published OpenAPI spec two ways — an offline unit test against a transcribed copy of the spec's `WorkflowStepTemplate` discriminator mapping, and a CI job (`pnpm check:catalogs`) that re-fetches the live spec and diffs it. If a `$type` is listed here, the orchestrator accepts it.
 
@@ -521,15 +521,15 @@ What it exports:
 
 | Export | What |
 |---|---|
-| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 50 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
+| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 51 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
 | `WorkflowStepTemplateFor<'videoGen'>` | One step's template. |
 | `WorkflowStepInputFor<'videoGen'>` | One step's `input` shape, without needing the generated `*Input` name. |
 | `AnyWorkflowStepTemplate` | Discriminated union of all 47 mapped templates — `Extract<…, { $type: 'comfy' }>` and exhaustive `switch` work. `@civitai/client`'s base `WorkflowStepTemplate` has `$type` as a bare `string`, so it narrows nothing. |
 | `TypedWorkflowTemplate` | The submit envelope with `steps` narrowed to that union. Pass it straight to `submitWorkflow` / `estimateWorkflow`. |
 
-> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with no generated template in the pinned `@civitai/client` are `imageScanning`, `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
+> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with no generated template in the pinned `@civitai/client` are `imageScanning`, `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
 >
-> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (50, 47, 3, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
+> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (51, 47, 4, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
 
 The generated `*StepTemplate` and `*Input` types are **not** re-exported individually. Using this subpath already requires `@civitai/client` installed, so if you want one by name, import it straight from there — `import type { TextToImageStepTemplate } from '@civitai/client'`.
 
@@ -566,7 +566,7 @@ A `$type` having a type here says nothing about whether you may submit it.
 
 Several of the 47 exist to serve Civitai's own pipelines rather than third-party apps — `modelPickleScan`, `xGuardModeration`, `training`, `comfyNodepackSnapshot`, `qwenImageBench`, the `model*`/`media*` hashing and classification steps. They're in the consumer spec, so they're typed here. They are not an invitation.
 
-Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 50 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
+Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 51 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
 
 ## Public vs. confidential clients
 

package/dist/blocks/index.d.ts

@@ -77,5 +77,5 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/scopes.d.ts

@@ -24,6 +24,8 @@ export declare const BLOCK_SCOPES: {
     readonly COLLECTIONS_WRITE_SELF: "collections:write:self";
     readonly COLLECTIONS_READ_PRIVATE: "collections:read:private";
     readonly POSTS_WRITE_SELF: "posts:write:self";
+    readonly GOODS_READ_SELF: "goods:read:self";
+    readonly GOODS_PURCHASE_SELF: "goods:purchase:self";
 };
 export type BlockScopeKey = keyof typeof BLOCK_SCOPES;
 export type BlockScope = (typeof BLOCK_SCOPES)[BlockScopeKey];

package/dist/blocks/scopes.js

@@ -48,6 +48,20 @@ export const BLOCK_SCOPES = {
     // per-post confirm rendering the SERVER'S resolution of the request, and the
     // server re-runs every guard.
     POSTS_WRITE_SELF: 'posts:write:self',
+    // goods:* — the DIGITAL GOODS rail (civitai/civitai#5171): the platform sells
+    // a manifest-declared entitlement to the viewer for Buzz, on the app's behalf.
+    // These were live on the SERVER and in the canonical schema while absent here,
+    // so `defineBlock` rejected both and no app scaffolded from this repo could
+    // DECLARE them — the hooks that call them were unreachable. Found by the
+    // round-0 reachability question on app-starters#489.
+    //
+    // `goods:read:self` is CONSENT-EXEMPT by design: the read is scoped
+    // server-side to the calling app's own appBlockId, so it can only ever return
+    // what that app itself sold and there is no third-party data to consent to.
+    // `goods:purchase:self` is CONSENT-GATED — money out of the viewer's balance
+    // always needs an explicit grant. Do not collapse the two.
+    GOODS_READ_SELF: 'goods:read:self',
+    GOODS_PURCHASE_SELF: 'goods:purchase:self',
 };
 /**
  * Format helper for the block-scope shape — 3 OR 4 colon-separated lowercase

package/dist/blocks/types.d.ts

@@ -1402,6 +1402,40 @@ export interface ManifestPreview {
     description: string;
     screenshots?: string[];
 }
+/**
+ * One entry of a manifest's `goods[]`. Mirrors the canonical schema exactly;
+ * `id`, `title` and `priceBuzz` are required there and so are they here.
+ *
+ * 🔴 DECLARED BEFORE `BlockManifestV1`'S DOCBLOCK ON PURPOSE. Inserting an
+ * interface BETWEEN a docblock and the declaration it documents does not just
+ * look untidy — `tsc` emits both comments onto THIS interface in
+ * `dist/blocks/types.d.ts` and leaves `BlockManifestV1` undocumented, so the
+ * published types told a reader that "only `blockId`, `version`, `name`,
+ * `contentRating` and `scopes` are required" about a type with three fields and
+ * different requirements. Keep any new sibling above this comment or below
+ * `BlockManifestV1`.
+ */
+export interface BlockManifestGood {
+    /** Lowercase alphanumeric with `-`/`_`, at most 64 chars. Colon-free, because it is composed into a redis key and a ledger external id. */
+    id: string;
+    /** At most 80 chars. */
+    title: string;
+    /** At most 500 chars. */
+    description?: string;
+    /**
+     * Whole Buzz, minimum 2 — at a price of 1 the owner's floored 70% share is
+     * ZERO, so the app would sell an item and earn nothing from it, permanently.
+     */
+    priceBuzz: number;
+    /**
+     * What the entitlement grants. `app_unlock` marks a one-time unlock of the app
+     * itself; it is RECORDED identically today and the platform does not yet act
+     * on it, so declaring it buys nothing unless you intend that later behaviour.
+     */
+    kind?: 'good' | 'app_unlock';
+    /** Opaque app payload, carried verbatim onto the entitlement. Never interpreted by the platform. */
+    payload?: Record<string, unknown>;
+}
 /**
  * v1 manifest shape. Mirrors `schemas/app-block/v1.json` — keep them in sync.
  *
@@ -1452,6 +1486,23 @@ export interface BlockManifestV1 {
      * with the canonical schema's `scopeJustifications` (civitai #3195).
      */
     scopeJustifications?: Record<string, string>;
+    /**
+     * Optional DIGITAL GOODS catalog — entitlements the platform sells to a viewer
+     * for Buzz on this app's behalf. Manifest-governed and REVIEW-GATED: the
+     * catalog a moderator approves is the catalog that can be sold, and changing a
+     * price means shipping a new version and being re-reviewed.
+     *
+     * Declaring goods is not by itself permission to sell — the manifest must also
+     * carry `goods:purchase:self` in `scopes`.
+     *
+     * 🔴 THE TYPE WAS ABSENT WHILE THE SCHEMA PROPERTY EXISTED, so `defineBlock`'s
+     * documented inline-literal form rejected a `goods` declaration with TS2353
+     * even though Ajv accepted the same manifest from a JSON file. Nothing could
+     * catch that: there is a vendored-schema↔`BLOCK_SCOPES` cross-check but no
+     * schema-properties↔interface-keys check, and the repo's manifest tests cast.
+     * Kept in lockstep with the canonical schema's `goods`.
+     */
+    goods?: BlockManifestGood[];
     /** Optional; the canonical declares no required sub-field. */
     iframe?: ManifestIframe;
     /** Full-page surface descriptor (W10). */

package/dist/manifest/index.d.ts

@@ -15,5 +15,5 @@
 export { defineBlock, SCHEMA_DIVERGENCES, KNOWN_GAPS, loadCanonicalSchema } from './defineBlock.js';
 export type { DefineBlockConfig } from './defineBlock.js';
 export { BlockManifestError } from '../blocks/manifestError.js';
-export type { BlockManifest, BlockManifestV1 } from '../blocks/types.js';
+export type { BlockManifest, BlockManifestGood, BlockManifestV1 } from '../blocks/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/orchestrator/index.d.ts

@@ -130,6 +130,8 @@ export declare const WORKFLOW_STEP_TYPES: {
      * `maxDuration` is an upper bound; generation can stop earlier.
      */
     readonly yuE2: "Generate a song from style and lyrics with YuE2";
+    /** Music or a standalone sound effect from a text prompt. */
+    readonly soniloAudioGen: "Music or a sound effect from a text prompt (Sonilo)";
     /** Speech-to-text transcription. */
     readonly transcription: "Speech-to-text transcription";
     /** Generate captions from audio. */

package/dist/orchestrator/index.js

@@ -134,6 +134,8 @@ export const WORKFLOW_STEP_TYPES = {
      * `maxDuration` is an upper bound; generation can stop earlier.
      */
     yuE2: 'Generate a song from style and lyrics with YuE2',
+    /** Music or a standalone sound effect from a text prompt. */
+    soniloAudioGen: 'Music or a sound effect from a text prompt (Sonilo)',
     /** Speech-to-text transcription. */
     transcription: 'Speech-to-text transcription',
     /** Generate captions from audio. */

package/dist/orchestrator/steps.d.ts

@@ -3,7 +3,7 @@
  * own generated client (`@civitai/client`).
  *
  * The sibling `@civitai/app-sdk/orchestrator` module gives you the *catalog*
- * (`WORKFLOW_STEP_TYPES` — 50 `$type` names and what each one does) and the
+ * (`WORKFLOW_STEP_TYPES` — 51 `$type` names and what each one does) and the
  * fetch helpers (`submitWorkflow`, `estimateWorkflow`, …), but its body
  * builders take `input: unknown`. This module is the missing half: the actual
  * per-step input shapes, tracked against the orchestrator's OpenAPI spec by
@@ -70,7 +70,7 @@
  * consumer spec, so they are typed here. They are not an invitation.
  *
  * ⚠️ `WORKFLOW_STEP_TYPES` does NOT mark most of them. Counted at this commit:
- * of its 50 entries, exactly TWO sit under its "Platform internals" heading —
+ * of its 51 entries, exactly TWO sit under its "Platform internals" heading —
  * `comfyNodepackSnapshot` and `qwenImageBench`. `training`, `webScrape`,
  * `xGuardModeration`, `modelPickleScan` and the `model*` / `media*` steps are
  * ordinary documented entries under ordinary headings, and `webScrape` carries
@@ -89,9 +89,9 @@
  * (#315) without anything going red. The measured state, derived rather than
  * typed:
  *
- * `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with
+ * `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with
  * no generated template in the pinned `@civitai/client` are `imageScanning`,
- * `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
+ * `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
  * error for each of them.
  *
  * That gap is EXPECTED and is not a defect in either surface. The catalog
@@ -300,7 +300,7 @@ interface StepTemplateMap {
     xGuardModeration: XGuardModerationStepTemplate;
 }
 /**
- * `$type` → its step-template type, for 47 of the catalog's 50 step types.
+ * `$type` → its step-template type, for 47 of the catalog's 51 step types.
  *
  * Keyed by the WIRE name rather than the generated type name, because the wire
  * name is what you actually have in hand and the generator does not always

package/dist/orchestrator/steps.js

@@ -3,7 +3,7 @@
  * own generated client (`@civitai/client`).
  *
  * The sibling `@civitai/app-sdk/orchestrator` module gives you the *catalog*
- * (`WORKFLOW_STEP_TYPES` — 50 `$type` names and what each one does) and the
+ * (`WORKFLOW_STEP_TYPES` — 51 `$type` names and what each one does) and the
  * fetch helpers (`submitWorkflow`, `estimateWorkflow`, …), but its body
  * builders take `input: unknown`. This module is the missing half: the actual
  * per-step input shapes, tracked against the orchestrator's OpenAPI spec by
@@ -70,7 +70,7 @@
  * consumer spec, so they are typed here. They are not an invitation.
  *
  * ⚠️ `WORKFLOW_STEP_TYPES` does NOT mark most of them. Counted at this commit:
- * of its 50 entries, exactly TWO sit under its "Platform internals" heading —
+ * of its 51 entries, exactly TWO sit under its "Platform internals" heading —
  * `comfyNodepackSnapshot` and `qwenImageBench`. `training`, `webScrape`,
  * `xGuardModeration`, `modelPickleScan` and the `model*` / `media*` steps are
  * ordinary documented entries under ordinary headings, and `webScrape` carries
@@ -89,9 +89,9 @@
  * (#315) without anything going red. The measured state, derived rather than
  * typed:
  *
- * `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with
+ * `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with
  * no generated template in the pinned `@civitai/client` are `imageScanning`,
- * `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
+ * `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
  * error for each of them.
  *
  * That gap is EXPECTED and is not a defect in either surface. The catalog

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.51.2",
+  "version": "0.53.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",

package/schemas/app-block/v1.json

@@ -99,13 +99,15 @@
           "collections:read:self",
           "collections:write:self",
           "collections:read:private",
-          "posts:write:self"
+          "posts:write:self",
+          "goods:read:self",
+          "goods:purchase:self"
         ]
       }
     },
     "scopeJustifications": {
       "type": "object",
-      "description": "Per-scope justification: a map of scope-id → free-text rationale explaining WHY the app needs that permission, shown to the moderator during review. REQUIRED for SENSITIVE scopes — any declared scope that can spend or read the viewer's Buzz, read the viewer's private data, or write data other users see (e.g. `ai:write:budgeted`, `social:tip:self`, `buzz:read:self`, `collections:read:private`, `apps:storage:shared:write`, `posts:write:self`) MUST carry a non-empty justification here, or the manifest is rejected at submit time. OPTIONAL for non-sensitive scopes — omit those and the manifest stays valid. Every key MUST be a scope also present in `scopes` (justifications for scopes you don't request are rejected). Each value is a non-empty string of at most 500 characters. The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here). NOTE: the justification captures the developer's STATED rationale only; the platform does not verify the truth of the claims.",
+      "description": "Per-scope justification: a map of scope-id → free-text rationale explaining WHY the app needs that permission, shown to the moderator during review. REQUIRED for SENSITIVE scopes — any declared scope that can spend or read the viewer's Buzz, read the viewer's private data, or write data other users see (e.g. `ai:write:budgeted`, `social:tip:self`, `goods:purchase:self`, `buzz:read:self`, `collections:read:private`, `apps:storage:shared:write`, `posts:write:self`) MUST carry a non-empty justification here, or the manifest is rejected at submit time. OPTIONAL for non-sensitive scopes — omit those and the manifest stays valid. Every key MUST be a scope also present in `scopes` (justifications for scopes you don't request are rejected). Each value is a non-empty string of at most 500 characters. The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here). NOTE: the justification captures the developer's STATED rationale only; the platform does not verify the truth of the claims.",
       "additionalProperties": {
         "type": "string",
         "minLength": 1,
@@ -221,6 +223,51 @@
         }
       }
     },
+    "goods": {
+      "type": "array",
+      "description": "Optional DIGITAL GOODS catalog — entitlements the platform sells to a viewer on your app's behalf, for Buzz. Manifest-governed and REVIEW-GATED: the catalog a moderator approves is the catalog that can be sold, and changing a price means shipping a new version and being re-reviewed. The platform owns the ledger (who bought what, when, at what price, and its refund state); the good's MEANING is your app's business — read the viewer's entitlements from GET /api/v1/blocks/entitlements and keep the semantics in your own app storage. Declaring goods does not by itself let you sell: the app must also declare the `goods:purchase:self` scope (and `goods:read:self` to read entitlements back), and the viewer must consent. Sales split platform 30% / app owner 70%, paid immediately. Kept in lockstep with the bounds in src/shared/constants/block-goods.constants.ts (a drift-guard test enforces equality); the imperative validator in that same module is authoritative.",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "priceBuzz"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable identifier for this good, unique within the manifest. This is what a purchase and an entitlement are keyed by, so changing it in a later version orphans every entitlement already granted under the old id. Lowercase letters, digits, - and _, starting with a letter or digit.",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[a-z0-9][a-z0-9_-]*$"
+          },
+          "title": {
+            "type": "string",
+            "description": "Human-readable name shown to the viewer at purchase. Non-empty; the server measures the TRIMMED length, so this maxLength is never more permissive than the server.",
+            "minLength": 1,
+            "maxLength": 80
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional one-paragraph explanation of what the viewer gets.",
+            "maxLength": 500
+          },
+          "priceBuzz": {
+            "type": "integer",
+            "description": "Price in whole Buzz. Buzz has no sub-unit, so this must be a whole number, and the minimum is 2 rather than 1 because the app owner's 70% share is floored — a 1 Buzz item would earn its owner nothing, permanently. Capped so a single purchase can never drain an account; a viewer also has a daily ceiling across every app they have installed, so a purchase can be refused with a clean 4xx even at a legal price. Both bounds are kept in lockstep with BLOCK_GOOD_MIN_PRICE_BUZZ / BLOCK_GOOD_MAX_PRICE_BUZZ in src/shared/constants/block-goods.constants.ts by a drift-guard test.",
+            "minimum": 2,
+            "maximum": 50000
+          },
+          "kind": {
+            "type": "string",
+            "description": "What the entitlement grants, from the platform's point of view. \"good\" (the default) is an ordinary in-app purchase the platform records and does not interpret. \"app_unlock\" marks a one-time unlock of the app itself; it is RECORDED IDENTICALLY today and the platform does NOT yet act on it — the paid-app access gate is a later change that reads this value. Declaring it now buys nothing, so leave it unset unless you intend that later behaviour.",
+            "enum": ["good", "app_unlock"]
+          },
+          "payload": {
+            "type": "object",
+            "description": "Optional OPAQUE payload copied verbatim onto the entitlement at purchase and handed back to your app unchanged. The platform never reads or interprets it. It is manifest-sourced rather than client-supplied precisely so that what an entitlement carries is something a moderator saw. Must serialize to at most 2048 bytes."
+          }
+        }
+      }
+    },
     "targets": {
       "type": "array",
       "description": "Model-page slot targets. Each target's slotId must be a known registered model slot (not the page slot). Optional for page-only apps.",