[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77KXMN65HBKAQZDER9D8JDX":3,"skill-same:01M77KXMN65HBKAQZDER9D8JDX":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M77KXMN65HBKAQZDER9D8JDX","authoring-pkey-manifests",null,"Use when creating or editing a product's .pkey\u002F manifest (product, schema, release, distribution) — scaffolding with pkey init, wiring editor schema support, choosing module names, validating until clean, and registering or resyncing the product in the console.","vladzaharia\u002Fpolaris-key","vladzaharia","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F79390?v=4","01M77KX2HEVKT2TK6WQ2V7WEGG","Vlad Zaharia","01M77KX2J6W3MV6A5N08VTS8AR",0,"MIT","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-kit\u002Fskills\u002Fauthoring-pkey-manifests\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: authoring-pkey-manifests\ndescription: Use when creating or editing a product's .pkey\u002F manifest (product, schema, release, distribution) — scaffolding with pkey init, wiring editor schema support, choosing module names, validating until clean, and registering or resyncing the product in the console.\n---\n\n# Authoring a `.pkey\u002F` manifest\n\nA Polaris Key product is **data, not code**: its catalog, metadata and release coordinates live\nin a `.pkey\u002F` directory in the product's own repo. Adding or changing a product must never\nrequire a worker redeploy. `.pkey\u002F` is the **only** manifest directory — there is no second\ncandidate and no fallback between two.\n\nReference (all now on the docs site, in the repo under `packages\u002Fdocs\u002Fsrc\u002Fcontent\u002Fdocs\u002F`):\n`build\u002Fmanifest\u002Fproduct.md` (the `.pkey\u002F` convention), `start\u002Ffirst-product.md` (the adopter\nguide), `build\u002Fmanifest\u002Fregister.md` (getting a product into D1), and `start\u002Fconcepts.md` (the\ncanonical glossary).\n\nEvery validator error and warning code, by manifest file: [references\u002Fvalidation-codes.md](references\u002Fvalidation-codes.md).\n\n## Checklist\n\n### 1. Scaffold\n\n- [ ] Run `pkey init` in the product repo root. It creates `.pkey\u002F` and writes YAML:\n      `product.yaml` and `schema.yaml` always (ingest requires both, even with Config off; without\n      `config` the schema is an empty catalog, `schemaVersion: 1` and `entries: []`); `release.yaml`\n      when Release is selected. The scaffolded tier names its profile with `profileId` and is\n      `policyDeviceLimit: 5` with no expiry.\n- [ ] Other flags: `--admin-group`, `--release-owner`, `--release-repo`, `--force` (overwrite).\n      With no `--modules`, the default is `license,config`.\n- [ ] Do **not** hand-create the directory if `pkey init` will do it — the scaffold writes the\n      `# yaml-language-server: $schema=…` header that gives you completion in the editor.\n\n```sh\npkey init --product \u003Cslug> --name \"\u003CName>\" --modules license,config\n```\n\n### 2. Get editor validation working\n\n- [ ] Scaffolded files point at a **path**, not a URL:\n      `..\u002Fnode_modules\u002F@polaris-key\u002Fmanifest\u002Fschemas\u002Fv1\u002F\u003Crole>.schema.json`. The canonical `$id`\n      URLs (`key.plrs.im`, under `schemas\u002Fv1\u002F`) are identifiers on the auth-gated docs site,\n      not fetch targets — an editor cannot retrieve them.\n- [ ] In this monorepo, `.vscode\u002Fsettings.json` already wires `json.schemas` and `yaml.schemas`\n      for `**\u002F.pkey\u002F{product,schema,release,distribution}.{json,yaml,yml}` and the `products\u002F*`\n      fixtures. YAML\n      completion needs the `redhat.vscode-yaml` extension.\n- [ ] The schemas ship inside the `@polaris-key\u002Fmanifest` npm package (`schemas\u002Fv1\u002F`), so a\n      product repo that installs the package gets them locally.\n\n### 3. Know what each of the four files owns\n\n- [ ] **Write the canonical spellings** — the layout `pkey init` writes: `product:` holds\n      identity and compatibility (`slug`, `name`, `adminGroup`, `compatMin`, `compatMax`),\n      `licensing:` holds the licence defaults and `tiers`, `profiles` sits at the root (the\n      old `licensing.profiles` warns, and `pkey validate --fix` moves it), a tier names its profile\n      with `profileId`, the catalog is `entries`, and `.pkey\u002Frelease` puts its body under\n      `release:` with `provider: { type: github, owner, repo }`. The old spellings (a flat product\n      document, root `tiers`, `catalog`, `ghOwner`\u002F`ghRepo`, legacy `modules:` names, …) still\n      validate with their old precedence, but `pkey validate` warns `deprecated_spelling` (or\n      `conflicting_spelling` when both are set). The full table is\n      `build\u002Fmanifest\u002Fproduct.md` → \"Deprecated spellings\"; the source of truth is\n      `DEPRECATED_SPELLINGS` in `packages\u002Fshared-manifest\u002Fsrc\u002Fspellings.ts`.\n- [ ] Keep **one file per document** (`product.yaml` or `product.json`, not both): only the first\n      of `json`, `yaml`, `yml` is read, and `pkey validate` warns when there are more.\n\n- [ ] **`schema`** (required) — the config catalog: `{ schemaVersion, entries[] }`, plus an\n      optional top-level `cloudSync` block (Cloud Sync's records: `collections` and\n      `migrations`). Maps to the `product_schema` row. For an entry's fields, including the\n      optional `user` block that tunes a synced setting, use the `adding-a-catalog-entry` skill.\n- [ ] With Cloud Sync (`sync`) on, **every Editable `config` key is a synced setting** (no\n      `managementDefault` of `enforced` or `hidden`); a key the catalog does not declare syncs too,\n      as an **open setting** (`lastWrite`, schema-less, at most 8 KiB). Declared and open settings\n      share one budget: 256 keys and 64 KiB per person. An app treats an undeclared key as\n      untrusted input, because any device of the person can write it; a key that matters is\n      declared with a schema, given `user: { sync: \"local\" }`, or locked.\n- [ ] A **collection** declares a namespace of records: `name`, optional `label`, `template`\n      (`saves`: 16 save slots per person, `revision`, one file of up to 32 MiB with 5 older\n      versions, and `playtime`, `progress`, `chapter`, `formatVersion` and a base64 `thumbnail`;\n      `session`: `lastWrite`, 16 records, an 8 MiB file), `conflict` (`lastWrite`, `max`, `min`,\n      `merge`, `union`, `revision`; `max`\u002F`min` need a number `conflictField`), `schema`,\n      `maxRecords` (≤ 10,000, never on a `saves` collection), `files` (`maxBytes` ≤ 1 GiB and\n      `keepRevisions`) and `requires` (a catalog flag or a system entitlement the anchor licence\n      must grant). `access` is `owner` only. Retired, refused with no warning period:\n      `cloudSync.saves` (use `template: \"saves\"`), `cloudSync.open`, `onAttach` (the first\n      sign-in is an ordinary sync) and `user.sync: \"device\"` (use `local`).\n- [ ] **`product`** (required) — product metadata, the `modules` block (enabled services; the\n      device-registration policy is derived from them, never declared), `web.origins`, OIDC, the\n      `identity:` block, profiles, tiers, provisioning hooks, `fingerprint`, `autoIssue` and\n      `secrets.required`. Maps to `products`\n      (incl. `services_json`,\n      `web_origins_json`) plus\n      `oidc_config`, `profiles`, `tiers`, `provisioning_config`. There is no `cloudSync` block\n      here any more (the validator refuses one): a person's Cloud Sync quota is the\n      `pkey.cloudSync.bytes` entitlement (256 MiB when unset) that a tier, a licence override or\n      an add-on sets, and the ceiling and the pause are console settings.\n- [ ] **`release`** (required only when releases are enabled) — release-provider coordinates,\n      channels, install\u002Fappcast settings, edge-mint recipes, and the app deliverable with its\n      artifact map. Maps to `release_config`, `release_deliverables` and `edge_mint_config`.\n- [ ] If the repo publishes tags that are not app releases (rolling `channels`, content `packs`,\n      …), say so in `release`: `stableTagPattern` (an anchored regex, ≤ 80 characters, same\n      safety rule as `manualChannels[].regex`) narrows which tags may become stable\u002Flatest, and\n      `ignoreTags` lists exact tag names that never resolve on a moving channel. Undeclared, any\n      semver tag with an optional leading `v` is a candidate, and the highest semver wins — not\n      the newest by creation order. The same two fields may instead sit under\n      `deliverables.app.versioning`, which is the canonical place (the body spelling is marked\n      deprecated in the schema); never in both places (`conflicting_versioning`).\n- [ ] If the product ships more than a CLI and a DMG (Windows, Linux, Android, iOS, web, a\n      universal binary…), declare the files instead of relying on name sniffing:\n      `deliverables.app` with `kind: app`, optional `versioning` (`scheme`: `semver` |\n      `semver+build` | `4part`; `buildNumber`: `descriptor` | `none`), `channels`\n      (`beta: { includes: [stable] }`; canonical names only, no `staging`\u002F`latest`, no cycles),\n      and `artifacts[]`, one entry per build: `{ id, platform, arch, format, role?, match }`.\n      `platform` ∈ macos\u002Fios\u002Fandroid\u002Fwindows\u002Flinux\u002Fweb, `arch` ∈\n      arm64\u002Fx86_64\u002Funiversal\u002Farmv7\u002Fwasm32\u002Fany, `role` defaults to `payload` (installer versus\n      portable is a `format`, never a role), `match` is an anchored case-sensitive glob (`*`,\n      `?`, ≤ 128 chars). `\u003Cpayload>.sig`\u002F`.sha256` join their build automatically. An entry\n      may list `embeds: [\u003CpackId>…]`, the packs that build ships (omitted = every\n      `baseline: embedded` pack; `invalid_build_embeds`). CI may then attach a release\n      descriptor (`pkey-release.json`, `release-descriptor.schema.json`) whose builds must\n      match this map.\n- [ ] Name every build and its files by **platform plus arch**: ids like `macos-arm64`,\n      `win-x64`, `linux-arm64` (never a bare `arm64`\u002F`x86_64`\u002F`x64`, which is the warning\n      `bare_arch_artifact_id`), and globs over files like `djdl-*-macos-arm64.app.zip`, not\n      `djdl-*-arm64.app.zip`. The console, portal, download page and `pkey release publish`\n      label builds through `buildLabel` (`macOS · Apple silicon (arm64)`,\n      `Windows · x64 (x86_64)`, `All platforms`), and a file lacking a platform inherits its\n      build's or its name's — so give the name something to say. See \"How builds are\n      labelled\" on `\u002Fdocs\u002Fbuild\u002Fmanifest\u002Frelease\u002F`.\n- [ ] If the product ships content packs, declare each as `deliverables.\u003CpackId>` with\n      `kind: pack` (at most 64, `too_many_pack_deliverables`): `type`\n      (`godot.pck` | `files.tree`, required), `binding` (`pinned`, the default: each app release\n      pins the pack release; `compatible`: Release resolves the newest release whose\n      `requires.contentApi` range holds each live contentApi level; `standalone`: the newest\n      release for every level), `baseline`\n      (`embedded` | `none`), `required` (then `delivery: essential` and no `entitlement`),\n      `delivery` (`essential` | `prefetch` | `on-demand`), `contentPolicy: { dataOnly: true }`,\n      `handler` (`mountOrder` 0–1000, `prefixes` of `res:\u002F\u002F…\u002F` directories, `activation`\n      `restart` | `hot`; a `godot.pck` needs `prefixes` and `requires.engine: godot-4.7`, a\n      `files.tree` takes neither `prefixes` nor `mountOrder`), `variants` (`texture` \u002F\n      `locale` \u002F `quality` → values, ≤ 32 combinations),\n      `requires: { engine?, contentApi?, packs? }` (`contentApi: { app: \">=3 \u003C5\" }` is\n      required for `compatible`\n      — `missing_content_api_range` — and refused for `standalone` —\n      `standalone_with_content_api`; its only key is `app`, `unknown_content_api_app`;\n      `packs: { \u003CpackId>: \">=1.2.0 \u003C2.0.0\" }` names other compatible or standalone packs),\n      `conflicts` (other declared packs, `invalid_pack_conflicts`), `channels` (canonical\n      channels beyond `stable` and `beta` the pack's releases go to, `invalid_channel`), `patch`\n      (`strategies` ⊆ `delta`, `file`, `chunk`, default all three; `deltaBases` 0–8), `versioning.scheme`, and\n      `entitlement`, which must name a `flag` of `.pkey\u002Fschema` and only ASSERTS the gate an\n      operator sets under Distribution → Access (a publish whose gate differs is refused).\n      `provides: {required?, from?}` is the save-compatibility policy (`invalid_pack_provides`;\n      `from` a repo-relative JSON list of content ids, default `.pkey\u002Fprovides.json`); `removes`\n      is never declared (`pack_field_not_supported`), it is `pkey release publish --removes`.\n      `deliverables.app.content: { contentApi: \u003Cint>, packChannels?, attachable? }` is then required\n      (`invalid_app_content`); `packChannels` maps a pack id or `prefix.*` to a channel the\n      matched packs publish to (`invalid_pack_channels`, `unknown_pack_channels_target`). Holds\n      are never declared: an app release holds a compatible pack at publish. `attachable`\n      (`invalid_app_attachable`) lists the app scripts (`res:\u002F\u002F…` paths, `res:\u002F\u002F…\u002F`\n      directories) and canonical `uid:\u002F\u002F` UIDs a `godot.pck` pack may reference outside itself;\n      absent, the publish lint refuses any such reference (the device too, except app UIDs it\n      resolves to non-script resources). List a script's path and its UID (Godot 4.4+ writes\n      both) and the UID of any app resource packs reach by UID, and mirror the list in the Godot\n      SDK's `PKeyOptions.pack_attachable`.\n      Codes: `invalid_pack_type`, `invalid_pack_binding`, `invalid_pack_policy`,\n      `invalid_pack_handler`, `invalid_pack_variants`, `invalid_pack_requires`,\n      `missing_content_api_range`, `standalone_with_content_api`, `unknown_content_api_app`,\n      `invalid_pack_conflicts`, `invalid_pack_channels`, `unknown_pack_channels_target`,\n      `invalid_app_attachable`,\n      `invalid_pack_patch`, `unknown_entitlement_ref`. Details:\n      `packages\u002Fdocs\u002Fsrc\u002Fcontent\u002Fdocs\u002Ffeatures\u002Fship-builds\u002Fpacks\u002Findex.md`.\n- [ ] If CI should publish releases (trusted publishing), declare the publisher in\n      `release` under `publishing.trustedPublisher` with a `workflow`\n      (`.github\u002Fworkflows\u002F\u003Cfile>.yml`) and an optional `environment` (default `release`). Those\n      two fields are ALL the manifest can say: the repository's numeric ids come from GitHub at\n      link\u002Fresync, the protected-ref \u002F GitHub-hosted-runner \u002F allowed-event checks are fixed,\n      and scopes are an operator setting. Tell the owner the publishing ref needs a branch or\n      **tag ruleset** (`ref_protected`), and the environment should require reviewers. Codes:\n      `invalid_trusted_publisher_workflow`, `invalid_trusted_publisher_environment`.\n- [ ] If the product ships signed updates (wire v4), declare `releaseKeys: [{ kid, publicKey }]`\n      in `release` (1–4 entries; `publicKey` is the raw Ed25519 key in 43-character base64url,\n      as the release-key generator prints it). The private key is a CI secret\n      (`PKEY_RELEASE_KEY`), never committed. Never reuse a product signing key (the sync refuses\n      it, `release_key_is_product_key`) or the Sparkle key (`release_key_reused`). Codes:\n      `invalid_release_key`, `weak_release_key`, `duplicate_release_key`, `release_key_reused`;\n      `contentKeys` only warns (`content_keys_not_supported`).\n- [ ] **`distribution`** (optional; P2b-02) — where the product is distributed: `outlets` keyed\n      by outlet id (an id that is itself a kind such as `steam`, `play`, `app-store` needs no\n      `kind`, and any `kind` it does give must repeat the id — `outlet_kind_mismatch`;\n      `altstore-beta` needs `kind: altstore`, and once linked it can change kind only to one\n      that narrows its capability defaults), each with its kind's store identity\n      fields (`bundleId`, `packageName`, `steam.appId`, `itch.gameId`, `packageFamilyName`,\n      `homebrewCask`, `testflight.publicLink`, `direct.scoop {bin, shortcuts}`, …); `transports` (`default` — `pkey-cdn` or `embedded` —, `packs.\u003Coutlet>`,\n      `deliverables.\u003Cid>.\u003Coutlet>`); and `listing`. Maps to `dist_outlets` and `dist_transports`.\n      Absent = one implicit `direct` outlet by `pkey-cdn`. An `artifact` must name an id in the\n      release artifact map; `tracks`\u002F`branches`\u002F`flights` keys must be declared channels\n      (`ms-store.flights` maps a channel to a Microsoft Store package flight by friendly name or\n      flight id; the non-flighted submission is always `stable`).\n- [ ] **Never** put `capabilities` in `.pkey\u002Fdistribution` — anywhere in it is an error\n      (`capabilities_not_manifest_writable`). Outlet capabilities default per kind and only an\n      operator narrows them, in the console.\n- [ ] For a Godot export, CI turns the build's outlet into the stamp's ids with\n      `pkey distribution outlet-ids --outlet \u003Cid>` (every value a string; `{}` with no file).\n      Full reference: `build\u002Fmanifest\u002Fdistribution.md`.\n- [ ] The base name selects the role; the extension is a pure format preference, tried\n      `.json` → `.yaml` → `.yml` and resolved **per document**, so `product.yaml` may sit next to\n      `schema.json`.\n- [ ] Everything here is the **manifest baseline**. Secret values, license\u002Fdevice overrides, live\n      service toggles and operator policy overrides live in Polaris Key and survive resync.\n\n### 4. Pick module names (both vocabularies parse)\n\n- [ ] Canonical service slugs: `license`, `config`, `release`, `distribution`, `update`,\n      `identity`, `sync` (Cloud Sync, which needs `config` and `identity` on:\n      `sync_requires_config`, `sync_requires_identity`), `commerce` (store purchases; needs\n      `license` on: `commerce_requires_license`). Every entry\n      is `{ \"enabled\": \u003Cboolean> }`; anything other than literal `true` counts as off.\n- [ ] The pre-suite vocabulary is still accepted and translated at ingest — only slugs are\n      stored, and one block may mix both spellings (table below).\n- [ ] No `modules` block (or every entry off) means `license` + `config` on, the rest off.\n- [ ] The device-registration policy is **derived, never declared**: License on is\n      `requires-license`; else Identity on is `requires-identity`; else `open`. `devices.registration`\n      is removed (0.9): any value is the error `invalid_registration_policy`, so delete the field.\n      The effective policy is read-only (`effectiveRegistration` in the console's services API,\n      `core.registration` in discovery) and follows the services you turn on or off.\n\n| Declared    | Enables                               | Why                                                                                         |\n| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `licensing` | `license`                             | rename                                                                                      |\n| `config`    | `config`                              | unchanged                                                                                   |\n| `releases`  | `release` + `distribution` + `update` | the old module meant \"distributes software\" — the suite splits truth, delivery and the feed |\n| `oidc`      | `identity`                            | rename                                                                                      |\n| `edgeMint`  | `config`                              | edge-minting is a secret-**delivery** capability of Config, not a unit of its own           |\n\n- [ ] Release, Distribution and Update are a chain — **release ← distribution ← update**. Naming\n      the slugs directly means naming all three you need: `update` needs `distribution`, and\n      `distribution` needs `release`. The legacy `releases` name enables all three at once.\n\n`pkey init --modules` takes either vocabulary (service slugs or the old names above) and always\nscaffolds the `modules` block in service slugs. In a manifest, the old names are deprecated:\nthey still enable their services, and `pkey validate` warns `deprecated_spelling`. The slugs and the legacy mapping are the service\ntable, `tools\u002Fservices.json`.\n\n- [ ] `web.origins` is optional: up to 16 exact browser origins that may read this product's\n      device-facing routes with `fetch` (CORS, no credentials). Spell each one the way a browser\n      sends `Origin`: `https:\u002F\u002F\u003Chost>[:port]`, lower-case, no default port, no path, trailing\n      slash, query, credentials or wildcard. Plain `http` only for `http:\u002F\u002Flocalhost[:port]` and\n      `http:\u002F\u002F127.0.0.1[:port]`. Bad entries are refused, never coerced (`invalid_web_origins`,\n      `invalid_web_origin`). Manifest-owned: resync rewrites it and dropping the block clears it.\n      Details: `packages\u002Fdocs\u002Fsrc\u002Fcontent\u002Fdocs\u002Fbuild\u002Fweb-apps.md`.\n- [ ] The `identity:` block is optional and applies only while `identity` is on (declared with\n      it off, `pkey validate` warns `identity_block_without_service`). Identity on no longer\n      needs an `oidc` block. Members (`methods`, `connections` and `claims` come later):\n\n      ```yaml\n      identity:\n        keyEntry: { limit: 10, claimByKey: false } # limit 1–100 (default 10); claimByKey default false\n        terms: { version: \"2026-10\", url: \"https:\u002F\u002Fexample.com\u002Fterms\" } # version [A-Za-z0-9._-]{1,32}; url https\n        redirectPaths: [\"\u002Fauth\u002Fcallback\"] # ≤ 16 unique, rooted at \u002F, no ? # * \u002F\u002F ..\n      ```\n\n      Codes: `invalid_identity` (any other member), `invalid_identity_key_entry_limit`,\n      `invalid_identity_claim_by_key`, `invalid_identity_terms`, `invalid_identity_redirect_paths`,\n      and the warning `identity_redirect_paths_without_origins` (redirect paths need `web.origins`).\n      Each member is a **claimable** setting (`identity.keyEntry.limit`,\n      `identity.keyEntry.claimByKey`, `identity.terms`, `identity.redirectPaths`): a console edit\n      claims it and Revert returns it to the manifest. `claimByKey: true` lets anyone holding a\n      leaked key add an email-bound licence to their own account; leave it off unless the product\n      truly sells keys with no buyer email to check.\n\n### 5. Validate until clean\n\n- [ ] `pkey validate` — parses `.pkey\u002F`, runs the authoritative TypeScript validator, and prints\n      the enabled modules, required secrets, warnings, then errors. Exit code 0 means valid.\n- [ ] Fix every `error`. Common ones: `update_requires_distribution` (Update on with Distribution\n      off — the feed would answer every client with an empty document),\n      `distribution_requires_release` (Distribution on with Release off — nothing to deliver),\n      `sync_requires_config` and `sync_requires_identity` (Cloud Sync on without Config or\n      Identity: the manifest is refused and nothing is turned on for you),\n      `invalid_registration_policy` (a `devices.registration` value, any value: the field is\n      removed, delete it), `reserved_slug`.\n- [ ] Read the `warning` lines too. `config_without_activation` is a warning (Config on with\n      License and Identity off: a config-only product is legitimate, and its devices register\n      `open`). Nothing turns it into an error.\n- [ ] `pkey doctor --base-url \u003Curl> --product \u003Cslug>` re-runs local validation and then checks the\n      live discovery document. Without both flags the remote half is skipped.\n\n### 6. Avoid reserved slugs\n\n- [ ] `product.slug` must not collide with a platform route the worker matches before\n      `\u002F\u003Cproduct>\u002F…`. The refused list (`RESERVED_PRODUCT_SLUGS`) is: `docs`, `manage`, `api`,\n      `assets`, `login`, `logout`, `callback`, `magic`, `download`, `webhooks`, `well-known`, `media`,\n      `activate`, `avatar`, `device`, `tv`, `signin`, `help`, plus the admin API's route actions (`PRODUCT_ROUTE_ACTIONS`): `kek`,\n      `link-repo`, `slug-check`.\n      A product registered under one would be permanently shadowed; the validator emits\n      `reserved_slug` and the console's manual-create path checks the same lists.\n- [ ] The slug's shape is `^[a-z0-9][a-z0-9-]{0,63}$` (`PRODUCT_SLUG_PATTERN`): no leading hyphen,\n      at most 64 characters. Otherwise the validator emits `invalid_slug`.\n\n### 6a. Name the product as itself (display names, PX-W13)\n\n- [ ] `product.name`, `listing.name` and `listing.developerName` are what the customer's sign-in\n      card shows (\"\u003CApp> wants you to sign in\"). A control, invisible or bidi character, a name\n      that starts with a variation selector, or a leading or trailing space, is\n      `invalid_display_text` (an error, also in the JSON Schemas).\n- [ ] A platform or store name as whole words (Polaris Key, plrs, Apple, App Store, Google,\n      Google Play, Steam, Valve, Epic Games, Microsoft, Xbox, PlayStation, Nintendo, itch.io,\n      after folding case, width, accents, look-alikes and separators) is `reserved_display_name`:\n      a warning today, an error once the platform setting `IDENTITY_RESERVED_DISPLAY_NAMES` says\n      `error`. Either way the card shows such a product by its slug. Only the system product\n      `polaris-key` is exempt.\n\n### 7. Register the product\n\n- [ ] **Repo-link (preferred).** In the console, link the product's repo. The worker fetches and\n      parses the three files and registers the product, minting the sealed signing key and\n      returning the public trust key. Re-linking, or a signed GitHub push webhook, re-parses and\n      updates the rows; webhook sync is pinned to the pushed commit SHA, records the changed\n      `.pkey\u002F` paths, and surfaces applied sections or validation errors in the Releases view.\n- [ ] **Manual create.** Product metadata plus a schema document, for early experiments. Release,\n      OIDC, provisioning, profiles, tiers and edge-mint rows are configured later or by linking.\n- [ ] **Seed SQL is a fixture tool only** —\n      `pnpm --filter @polaris-key\u002Fproducts gen-seed \u003Cslug>`. It cannot mint sealed `product_keys`\n      or store secret values; never use it for live onboarding.\n\n### 8. Understand resync and ownership before you promise a behavior\n\n- [ ] A resync updates the **manifest baseline**: product metadata, service enablement (the\n      device-registration policy follows from it), `web.origins`, fingerprint and auto-issue\n      policy, catalog shape, OIDC baseline, release baseline, profiles, tiers, provisioning,\n      edge-mint recipes.\n- [ ] Admin-set **values and management states** (per profile\u002Ftier\u002Flicense\u002Fdevice) live in D1 and\n      are **not** overwritten by a resync.\n- [ ] **Edge-mint recipes need operator approval.** A recipe from `.pkey\u002F` is inert (its token\n      route answers `404`) until an operator approves it in the console's Secrets view, and it\n      signs only with a secret the operator marked usage `edge-mint`. The manifest can never set\n      either. Changing a recipe's `alg`, `signingKeySecret`, `kid`, `claimsTemplate`,\n      `ttlSeconds` or `audience` makes it inert again until it is re-approved; an unchanged\n      resync keeps it approved; dropping it deletes its approval. So does a push that makes the\n      mint public — opens registration (License and Identity both off, so the derived policy is `open`),\n      enables anonymous `autoIssue` (`mode: anonymous`\u002F`both`), or enables `oidcDefault` with\n      Identity on — when the approval was given without the open-registration acknowledgement.\n      And, with Identity on, so does any change to `oidc.provider`, `oidc.issuer`,\n      `oidc.clientId` or `oidc.groupRoleMap`, or turning Identity on. Tell the product owner to\n      expect a review step after any such push (docs: `services\u002Fconfig\u002Fedge-mint`).\n- [ ] Five blocks are operator-claimable: `services_source`, `fingerprint_policy_source`,\n      `auto_issue_source` (on the product), `compat_source` (the compat window, claimed from\n      Update settings) and `access_source` (both release access modes together, on\n      `release_config`). A live console edit flips the source `manifest` → `admin`, and a\n      resync then **skips** that block — a push cannot silently undo a 3am toggle, nor\n      downgrade an `entitled` product to the manifest's `public`. \"Revert to manifest\" hands\n      ownership back and changes nothing else; the manifest re-applies on the **next** resync,\n      not immediately.\n- [ ] The trusted-publisher policy (`ci_publishers`) is operator-claimable too: while\n      manifest-owned it follows `publishing.trustedPublisher` (a change is audited, and removing\n      the block removes the policy); once an operator claims it with a `PUT` to\n      `\u002Fmanage\u002Fapi\u002Fproducts\u002F\u003Cslug>\u002Fci-publisher`, a resync never touches it.\n- [ ] The operator-only artifact policy (`requireSparkleSignature`, `minimumSystemVersion`)\n      has **no manifest spelling at all** — it lives in `release_config.operator_policy_json`,\n      which no manifest path writes. Do not try to declare either key (or the `entitled` access\n      mode) in `.pkey\u002Frelease`; set them in the console's Update settings.\n\n## Verification\n\n```sh\npkey validate                                     # exit 0, no error lines\npkey doctor --base-url https:\u002F\u002Fkey.plrs.im --product \u003Cslug>\n\n# In this monorepo, after touching the validator, the schemas, or products\u002F\u003Cslug>:\nmise exec node@22 -- pnpm --filter @polaris-key\u002Fmanifest test   # incl. schema-parity\nmise exec node@22 -- pnpm --filter @polaris-key\u002Fcli test\nmise exec node@22 -- pnpm typecheck\nmise exec node@22 -- pnpm format\n```\n\nIf you added or changed a validator rule, `schema-parity.test.ts` will fail until its mutation\ntable carries an entry for the new error code — that is the gate working, not a flake.\n","# Authoring a `.pkey\u002F` manifest\n\nA Polaris Key product is **data, not code**: its catalog, metadata and release coordinates live\nin a `.pkey\u002F` directory in the product's own repo. Adding or changing a product must never\nrequire a worker redeploy. `.pkey\u002F` is the **only** manifest directory — there is no second\ncandidate and no fallback between two.\n\nReference (all now on the docs site, in the repo under `packages\u002Fdocs\u002Fsrc\u002Fcontent\u002Fdocs\u002F`):\n`build\u002Fmanifest\u002Fproduct.md` (the `.pkey\u002F` convention), `start\u002Ffirst-product.md` (the adopter\nguide), `build\u002Fmanifest\u002Fregister.md` (getting a product into D1), and `start\u002Fconcepts.md` (the\ncanonical glossary).\n\nEvery validator error and warning code, by manifest file: [references\u002Fvalidation-codes.md](references\u002Fvalidation-codes.md).\n\n## Checklist\n\n### 1. Scaffold\n\n- [ ] Run `pkey init` in the product repo root. It creates `.pkey\u002F` and writes YAML:\n      `product.yaml` and `schema.yaml` always (ingest requires both, even with Config off; without\n      `config` the schema is an empty catalog, `schemaVersion: 1` and `entries: []`); `release.yaml`\n      when Release is selected. The scaffolded tier names its profile with `profileId` and is\n      `policyDeviceLimit: 5` with no expiry.\n- [ ] Other flags: `--admin-group`, `--release-owner`, `--release-repo`, `--force` (overwrite).\n      With no `--modules`, the default is `license,config`.\n- [ ] Do **not** hand-create the directory if `pkey init` will do it — the scaffold writes the\n      `# yaml-language-server: $schema=…` header that gives you completion in the editor.\n\n```sh\npkey init --product \u003Cslug> --name \"\u003CName>\" --modules license,config\n```\n\n### 2. Get editor validation working\n\n- [ ] Scaffolded files point at a **path**, not a URL:\n      `..\u002Fnode_modules\u002F@polaris-key\u002Fmanifest\u002Fschemas\u002Fv1\u002F\u003Crole>.schema.json`. The canonical `$id`\n      URLs (`key.plrs.im`, under `schemas\u002Fv1\u002F`) are identifiers on the auth-gated docs site,\n      not fetch targets — an editor cannot retrieve them.\n- [ ] In this monorepo, `.vscode\u002Fsettings.json` already wires `json.schemas` and `yaml.schemas`\n      for `**\u002F.pkey\u002F{product,schema,release,distribution}.{json,yaml,yml}` and the `products\u002F*`\n      fixtures. YAML\n      completion needs the `redhat.vscode-yaml` extension.\n- [ ] The schemas ship inside the `@polaris-key\u002Fmanifest` npm package (`schemas\u002Fv1\u002F`), so a\n      product repo that installs the package gets them locally.\n\n### 3. Know what each of the four files owns\n\n- [ ] **Write the canonical spellings** — the layout `pkey init` writes: `product:` holds\n      identity and compatibility (`slug`, `name`, `adminGroup`, `compatMin`, `compatMax`),\n      `licensing:` holds the licence defaults and `tiers`, `profiles` sits at the root (the\n      old `licensing.profiles` warns, and `pkey validate --fix` moves it), a tier names its profile\n      with `profileId`, the catalog is `entries`, and `.pkey\u002Frelease` puts its body under\n      `release:` with `provider: { type: github, owner, repo }`. The old spellings (a flat product\n      document, root `tiers`, `catalog`, `ghOwner`\u002F`ghRepo`, legacy `modules:` names, …) still\n      validate with their old precedence, but `pkey validate` warns `deprecated_spelling` (or\n      `conflicting_spelling` when both are set). The full table is\n      `build\u002Fmanifest\u002Fproduct.md` → \"Deprecated spellings\"; the source of truth is\n      `DEPRECATED_SPELLINGS` in `packages\u002Fshared-manifest\u002Fsrc\u002Fspellings.ts`.\n- [ ] Keep **one file per document** (`product.yaml` or `product.json`, not both): only the first\n      of `json`, `yaml`, `yml` is read, and `pkey validate` warns when there are more.\n\n- [ ] **`schema`** (required) — the config catalog: `{ schemaVersion, entries[] }`, plus an\n      optional top-level `cloudSync` block (Cloud Sync's records: `collections` and\n      `migrations`). Maps to the `product_schema` row. For an entry's fields, including the\n      optional `user` block that tunes a synced setting, use the `adding-a-catalog-entry` skill.\n- [ ] With Cloud Sync (`sync`) on, **every Editable `config` key is a synced setting** (no\n      `managementDefault` of `enforced` or `hidden`); a key the catalog does not declare syncs too,\n      as an **open setting** (`lastWrite`, schema-less, at most 8 KiB). Declared and open settings\n      share one budget: 256 keys and 64 KiB per person. An app treats an undeclared key as\n      untrusted input, because any device of the person can write it; a key that matters is\n      declared with a schema, given `user: { sync: \"local\" }`, or locked.\n- [ ] A **collection** declares a namespace of records: `name`, optional `label`, `template`\n      (`saves`: 16 save slots per person, `revision`, one file of up to 32 MiB with 5 older\n      versions, and `playtime`, `progress`, `chapter`, `formatVersion` and a base64 `thumbnail`;\n      `session`: `lastWrite`, 16 records, an 8 MiB file), `conflict` (`lastWrite`, `max`, `min`,\n      `merge`, `union`, `revision`; `max`\u002F`min` need a number `conflictField`), `schema`,\n      `maxRecords` (≤ 10,000, never on a `saves` collection), `files` (`maxBytes` ≤ 1 GiB and\n      `keepRevisions`) and `requires` (a catalog flag or a system entitlement the anchor licence\n      must grant). `access` is `owner` only. Retired, refused with no warning period:\n      `cloudSync.saves` (use `template: \"saves\"`), `cloudSync.open`, `onAttach` (the first\n      sign-in is an ordinary sync) and `user.sync: \"device\"` (use `local`).\n- [ ] **`product`** (required) — product metadata, the `modules` block (enabled services; the\n      device-registration policy is derived from them, never declared), `web.origins`, OIDC, the\n      `identity:` block, profiles, tiers, provisioning hooks, `fingerprint`, `autoIssue` and\n      `secrets.required`. Maps to `products`\n      (incl. `services_json`,\n      `web_origins_json`) plus\n      `oidc_config`, `profiles`, `tiers`, `provisioning_config`. There is no `cloudSync` block\n      here any more (the validator refuses one): a person's Cloud Sync quota is the\n      `pkey.cloudSync.bytes` entitlement (256 MiB when unset) that a tier, a licence override or\n      an add-on sets, and the ceiling and the pause are console settings.\n- [ ] **`release`** (required only when releases are enabled) — release-provider coordinates,\n      channels, install\u002Fappcast settings, edge-mint recipes, and the app deliverable with its\n      artifact map. Maps to `release_config`, `release_deliverables` and `edge_mint_config`.\n- [ ] If the repo publishes tags that are not app releases (rolling `channels`, content `packs`,\n      …), say so in `release`: `stableTagPattern` (an anchored regex, ≤ 80 characters, same\n      safety rule as `manualChannels[].regex`) narrows which tags may become stable\u002Flatest, and\n      `ignoreTags` lists exact tag names that never resolve on a moving channel. Undeclared, any\n      semver tag with an optional leading `v` is a candidate, and the highest semver wins — not\n      the newest by creation order. The same two fields may instead sit under\n      `deliverables.app.versioning`, which is the canonical place (the body spelling is marked\n      deprecated in the schema); never in both places (`conflicting_versioning`).\n- [ ] If the product ships more than a CLI and a DMG (Windows, Linux, Android, iOS, web, a\n      universal binary…), declare the files instead of relying on name sniffing:\n      `deliverables.app` with `kind: app`, optional `versioning` (`scheme`: `semver` |\n      `semver+build` | `4part`; `buildNumber`: `descriptor` | `none`), `channels`\n      (`beta: { includes: [stable] }`; canonical names only, no `staging`\u002F`latest`, no cycles),\n      and `artifacts[]`, one entry per build: `{ id, platform, arch, format, role?, match }`.\n      `platform` ∈ macos\u002Fios\u002Fandroid\u002Fwindows\u002Flinux\u002Fweb, `arch` ∈\n      arm64\u002Fx86_64\u002Funiversal\u002Farmv7\u002Fwasm32\u002Fany, `role` defaults to `payload` (installer versus\n      portable is a `format`, never a role), `match` is an anchored case-sensitive glob (`*`,\n      `?`, ≤ 128 chars). `\u003Cpayload>.sig`\u002F`.sha256` join their build automatically. An entry\n      may list `embeds: [\u003CpackId>…]`, the packs that build ships (omitted = every\n      `baseline: embedded` pack; `invalid_build_embeds`). CI may then attach a release\n      descriptor (`pkey-release.json`, `release-descriptor.schema.json`) whose builds must\n      match this map.\n- [ ] Name every build and its files by **platform plus arch**: ids like `macos-arm64`,\n      `win-x64`, `linux-arm64` (never a bare `arm64`\u002F`x86_64`\u002F`x64`, which is the warning\n      `bare_arch_artifact_id`), and globs over files like `djdl-*-macos-arm64.app.zip`, not\n      `djdl-*-arm64.app.zip`. The console, portal, download page and `pkey release publish`\n      label builds through `buildLabel` (`macOS · Apple silicon (arm64)`,\n      `Windows · x64 (x86_64)`, `All platforms`), and a file lacking a platform inherits its\n      build's or its name's — so give the name something to say. See \"How builds are\n      labelled\" on `\u002Fdocs\u002Fbuild\u002Fmanifest\u002Frelease\u002F`.\n- [ ] If the product ships content packs, declare each as `deliverables.\u003CpackId>` with\n      `kind: pack` (at most 64, `too_many_pack_deliverables`): `type`\n      (`godot.pck` | `files.tree`, required), `binding` (`pinned`, the default: each app release\n      pins the pack release; `compatible`: Release resolves the newest release whose\n      `requires.contentApi` range holds each live contentApi level; `standalone`: the newest\n      release for every level), `baseline`\n      (`embedded` | `none`), `required` (then `delivery: essential` and no `entitlement`),\n      `delivery` (`essential` | `prefetch` | `on-demand`), `contentPolicy: { dataOnly: true }`,\n      `handler` (`mountOrder` 0–1000, `prefixes` of `res:\u002F\u002F…\u002F` directories, `activation`\n      `restart` | `hot`; a `godot.pck` needs `prefixes` and `requires.engine: godot-4.7`, a\n      `files.tree` takes neither `prefixes` nor `mountOrder`), `variants` (`texture` \u002F\n      `locale` \u002F `quality` → values, ≤ 32 combinations),\n      `requires: { engine?, contentApi?, packs? }` (`contentApi: { app: \">=3 \u003C5\" }` is\n      required for `compatible`\n      — `missing_content_api_range` — and refused for `standalone` —\n      `standalone_with_content_api`; its only key is `app`, `unknown_content_api_app`;\n      `packs: { \u003CpackId>: \">=1.2.0 \u003C2.0.0\" }` names other compatible or standalone packs),\n      `conflicts` (other declared packs, `invalid_pack_conflicts`), `channels` (canonical\n      channels beyond `stable` and `beta` the pack's releases go to, `invalid_channel`), `patch`\n      (`strategies` ⊆ `delta`, `file`, `chunk`, default all three; `deltaBases` 0–8), `versioning.scheme`, and\n      `entitlement`, which must name a `flag` of `.pkey\u002Fschema` and only ASSERTS the gate an\n      operator sets under Distribution → Access (a publish whose gate differs is refused).\n      `provides: {required?, from?}` is the save-compatibility policy (`invalid_pack_provides`;\n      `from` a repo-relative JSON list of content ids, default `.pkey\u002Fprovides.json`); `removes`\n      is never declared (`pack_field_not_supported`), it is `pkey release publish --removes`.\n      `deliverables.app.content: { contentApi: \u003Cint>, packChannels?, attachable? }` is then required\n      (`invalid_app_content`); `packChannels` maps a pack id or `prefix.*` to a channel the\n      matched packs publish to (`invalid_pack_channels`, `unknown_pack_channels_target`). Holds\n      are never declared: an app release holds a compatible pack at publish. `attachable`\n      (`invalid_app_attachable`) lists the app scripts (`res:\u002F\u002F…` paths, `res:\u002F\u002F…\u002F`\n      directories) and canonical `uid:\u002F\u002F` UIDs a `godot.pck` pack may reference outside itself;\n      absent, the publish lint refuses any such reference (the device too, except app UIDs it\n      resolves to non-script resources). List a script's path and its UID (Godot 4.4+ writes\n      both) and the UID of any app resource packs reach by UID, and mirror the list in the Godot\n      SDK's `PKeyOptions.pack_attachable`.\n      Codes: `invalid_pack_type`, `invalid_pack_binding`, `invalid_pack_policy`,\n      `invalid_pack_handler`, `invalid_pack_variants`, `invalid_pack_requires`,\n      `missing_content_api_range`, `standalone_with_content_api`, `unknown_content_api_app`,\n      `invalid_pack_conflicts`, `invalid_pack_channels`, `unknown_pack_channels_target`,\n      `invalid_app_attachable`,\n      `invalid_pack_patch`, `unknown_entitlement_ref`. Details:\n      `packages\u002Fdocs\u002Fsrc\u002Fcontent\u002Fdocs\u002Ffeatures\u002Fship-builds\u002Fpacks\u002Findex.md`.\n- [ ] If CI should publish releases (trusted publishing), declare the publisher in\n      `release` under `publishing.trustedPublisher` with a `workflow`\n      (`.github\u002Fworkflows\u002F\u003Cfile>.yml`) and an optional `environment` (default `release`). Those\n      two fields are ALL the manifest can say: the repository's numeric ids come from GitHub at\n      link\u002Fresync, the protected-ref \u002F GitHub-hosted-runner \u002F allowed-event checks are fixed,\n      and scopes are an operator setting. Tell the owner the publishing ref needs a branch or\n      **tag ruleset** (`ref_protected`), and the environment should require reviewers. Codes:\n      `invalid_trusted_publisher_workflow`, `invalid_trusted_publisher_environment`.\n- [ ] If the product ships signed updates (wire v4), declare `releaseKeys: [{ kid, publicKey }]`\n      in `release` (1–4 entries; `publicKey` is the raw Ed25519 key in 43-character base64url,\n      as the release-key generator prints it). The private key is a CI secret\n      (`PKEY_RELEASE_KEY`), never committed. Never reuse a product signing key (the sync refuses\n      it, `release_key_is_product_key`) or the Sparkle key (`release_key_reused`). Codes:\n      `invalid_release_key`, `weak_release_key`, `duplicate_release_key`, `release_key_reused`;\n      `contentKeys` only warns (`content_keys_not_supported`).\n- [ ] **`distribution`** (optional; P2b-02) — where the product is distributed: `outlets` keyed\n      by outlet id (an id that is itself a kind such as `steam`, `play`, `app-store` needs no\n      `kind`, and any `kind` it does give must repeat the id — `outlet_kind_mismatch`;\n      `altstore-beta` needs `kind: altstore`, and once linked it can change kind only to one\n      that narrows its capability defaults), each with its kind's store identity\n      fields (`bundleId`, `packageName`, `steam.appId`, `itch.gameId`, `packageFamilyName`,\n      `homebrewCask`, `testflight.publicLink`, `direct.scoop {bin, shortcuts}`, …); `transports` (`default` — `pkey-cdn` or `embedded` —, `packs.\u003Coutlet>`,\n      `deliverables.\u003Cid>.\u003Coutlet>`); and `listing`. Maps to `dist_outlets` and `dist_transports`.\n      Absent = one implicit `direct` outlet by `pkey-cdn`. An `artifact` must name an id in the\n      release artifact map; `tracks`\u002F`branches`\u002F`flights` keys must be declared channels\n      (`ms-store.flights` maps a channel to a Microsoft Store package flight by friendly name or\n      flight id; the non-flighted submission is always `stable`).\n- [ ] **Never** put `capabilities` in `.pkey\u002Fdistribution` — anywhere in it is an error\n      (`capabilities_not_manifest_writable`). Outlet capabilities default per kind and only an\n      operator narrows them, in the console.\n- [ ] For a Godot export, CI turns the build's outlet into the stamp's ids with\n      `pkey distribution outlet-ids --outlet \u003Cid>` (every value a string; `{}` with no file).\n      Full reference: `build\u002Fmanifest\u002Fdistribution.md`.\n- [ ] The base name selects the role; the extension is a pure format preference, tried\n      `.json` → `.yaml` → `.yml` and resolved **per document**, so `product.yaml` may sit next to\n      `schema.json`.\n- [ ] Everything here is the **manifest baseline**. Secret values, license\u002Fdevice overrides, live\n      service toggles and operator policy overrides live in Polaris Key and survive resync.\n\n### 4. Pick module names (both vocabularies parse)\n\n- [ ] Canonical service slugs: `license`, `config`, `release`, `distribution`, `update`,\n      `identity`, `sync` (Cloud Sync, which needs `config` and `identity` on:\n      `sync_requires_config`, `sync_requires_identity`), `commerce` (store purchases; needs\n      `license` on: `commerce_requires_license`). Every entry\n      is `{ \"enabled\": \u003Cboolean> }`; anything other than literal `true` counts as off.\n- [ ] The pre-suite vocabulary is still accepted and translated at ingest — only slugs are\n      stored, and one block may mix both spellings (table below).\n- [ ] No `modules` block (or every entry off) means `license` + `config` on, the rest off.\n- [ ] The device-registration policy is **derived, never declared**: License on is\n      `requires-license`; else Identity on is `requires-identity`; else `open`. `devices.registration`\n      is removed (0.9): any value is the error `invalid_registration_policy`, so delete the field.\n      The effective policy is read-only (`effectiveRegistration` in the console's services API,\n      `core.registration` in discovery) and follows the services you turn on or off.\n\n| Declared    | Enables                               | Why                                                                                         |\n| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `licensing` | `license`                             | rename                                                                                      |\n| `config`    | `config`                              | unchanged                                                                                   |\n| `releases`  | `release` + `distribution` + `update` | the old module meant \"distributes software\" — the suite splits truth, delivery and the feed |\n| `oidc`      | `identity`                            | rename                                                                                      |\n| `edgeMint`  | `config`                              | edge-minting is a secret-**delivery** capability of Config, not a unit of its own           |\n\n- [ ] Release, Distribution and Update are a chain — **release ← distribution ← update**. Naming\n      the slugs directly means naming all three you need: `update` needs `distribution`, and\n      `distribution` needs `release`. The legacy `releases` name enables all three at once.\n\n`pkey init --modules` takes either vocabulary (service slugs or the old names above) and always\nscaffolds the `modules` block in service slugs. In a manifest, the old names are deprecated:\nthey still enable their services, and `pkey validate` warns `deprecated_spelling`. The slugs and the legacy mapping are the service\ntable, `tools\u002Fservices.json`.\n\n- [ ] `web.origins` is optional: up to 16 exact browser origins that may read this product's\n      device-facing routes with `fetch` (CORS, no credentials). Spell each one the way a browser\n      sends `Origin`: `https:\u002F\u002F\u003Chost>[:port]`, lower-case, no default port, no path, trailing\n      slash, query, credentials or wildcard. Plain `http` only for `http:\u002F\u002Flocalhost[:port]` and\n      `http:\u002F\u002F127.0.0.1[:port]`. Bad entries are refused, never coerced (`invalid_web_origins`,\n      `invalid_web_origin`). Manifest-owned: resync rewrites it and dropping the block clears it.\n      Details: `packages\u002Fdocs\u002Fsrc\u002Fcontent\u002Fdocs\u002Fbuild\u002Fweb-apps.md`.\n- [ ] The `identity:` block is optional and applies only while `identity` is on (declared with\n      it off, `pkey validate` warns `identity_block_without_service`). Identity on no longer\n      needs an `oidc` block. Members (`methods`, `connections` and `claims` come later):\n\n      ```yaml\n      identity:\n        keyEntry: { limit: 10, claimByKey: false } # limit 1–100 (default 10); claimByKey default false\n        terms: { version: \"2026-10\", url: \"https:\u002F\u002Fexample.com\u002Fterms\" } # version [A-Za-z0-9._-]{1,32}; url https\n        redirectPaths: [\"\u002Fauth\u002Fcallback\"] # ≤ 16 unique, rooted at \u002F, no ? # * \u002F\u002F ..\n      ```\n\n      Codes: `invalid_identity` (any other member), `invalid_identity_key_entry_limit`,\n      `invalid_identity_claim_by_key`, `invalid_identity_terms`, `invalid_identity_redirect_paths`,\n      and the warning `identity_redirect_paths_without_origins` (redirect paths need `web.origins`).\n      Each member is a **claimable** setting (`identity.keyEntry.limit`,\n      `identity.keyEntry.claimByKey`, `identity.terms`, `identity.redirectPaths`): a console edit\n      claims it and Revert returns it to the manifest. `claimByKey: true` lets anyone holding a\n      leaked key add an email-bound licence to their own account; leave it off unless the product\n      truly sells keys with no buyer email to check.\n\n### 5. Validate until clean\n\n- [ ] `pkey validate` — parses `.pkey\u002F`, runs the authoritative TypeScript validator, and prints\n      the enabled modules, required secrets, warnings, then errors. Exit code 0 means valid.\n- [ ] Fix every `error`. Common ones: `update_requires_distribution` (Update on with Distribution\n      off — the feed would answer every client with an empty document),\n      `distribution_requires_release` (Distribution on with Release off — nothing to deliver),\n      `sync_requires_config` and `sync_requires_identity` (Cloud Sync on without Config or\n      Identity: the manifest is refused and nothing is turned on for you),\n      `invalid_registration_policy` (a `devices.registration` value, any value: the field is\n      removed, delete it), `reserved_slug`.\n- [ ] Read the `warning` lines too. `config_without_activation` is a warning (Config on with\n      License and Identity off: a config-only product is legitimate, and its devices register\n      `open`). Nothing turns it into an error.\n- [ ] `pkey doctor --base-url \u003Curl> --product \u003Cslug>` re-runs local validation and then checks the\n      live discovery document. Without both flags the remote half is skipped.\n\n### 6. Avoid reserved slugs\n\n- [ ] `product.slug` must not collide with a platform route the worker matches before\n      `\u002F\u003Cproduct>\u002F…`. The refused list (`RESERVED_PRODUCT_SLUGS`) is: `docs`, `manage`, `api`,\n      `assets`, `login`, `logout`, `callback`, `magic`, `download`, `webhooks`, `well-known`, `media`,\n      `activate`, `avatar`, `device`, `tv`, `signin`, `help`, plus the admin API's route actions (`PRODUCT_ROUTE_ACTIONS`): `kek`,\n      `link-repo`, `slug-check`.\n      A product registered under one would be permanently shadowed; the validator emits\n      `reserved_slug` and the console's manual-create path checks the same lists.\n- [ ] The slug's shape is `^[a-z0-9][a-z0-9-]{0,63}$` (`PRODUCT_SLUG_PATTERN`): no leading hyphen,\n      at most 64 characters. Otherwise the validator emits `invalid_slug`.\n\n### 6a. Name the product as itself (display names, PX-W13)\n\n- [ ] `product.name`, `listing.name` and `listing.developerName` are what the customer's sign-in\n      card shows (\"\u003CApp> wants you to sign in\"). A control, invisible or bidi character, a name\n      that starts with a variation selector, or a leading or trailing space, is\n      `invalid_display_text` (an error, also in the JSON Schemas).\n- [ ] A platform or store name as whole words (Polaris Key, plrs, Apple, App Store, Google,\n      Google Play, Steam, Valve, Epic Games, Microsoft, Xbox, PlayStation, Nintendo, itch.io,\n      after folding case, width, accents, look-alikes and separators) is `reserved_display_name`:\n      a warning today, an error once the platform setting `IDENTITY_RESERVED_DISPLAY_NAMES` says\n      `error`. Either way the card shows such a product by its slug. Only the system product\n      `polaris-key` is exempt.\n\n### 7. Register the product\n\n- [ ] **Repo-link (preferred).** In the console, link the product's repo. The worker fetches and\n      parses the three files and registers the product, minting the sealed signing key and\n      returning the public trust key. Re-linking, or a signed GitHub push webhook, re-parses and\n      updates the rows; webhook sync is pinned to the pushed commit SHA, records the changed\n      `.pkey\u002F` paths, and surfaces applied sections or validation errors in the Releases view.\n- [ ] **Manual create.** Product metadata plus a schema document, for early experiments. Release,\n      OIDC, provisioning, profiles, tiers and edge-mint rows are configured later or by linking.\n- [ ] **Seed SQL is a fixture tool only** —\n      `pnpm --filter @polaris-key\u002Fproducts gen-seed \u003Cslug>`. It cannot mint sealed `product_keys`\n      or store secret values; never use it for live onboarding.\n\n### 8. Understand resync and ownership before you promise a behavior\n\n- [ ] A resync updates the **manifest baseline**: product metadata, service enablement (the\n      device-registration policy follows from it), `web.origins`, fingerprint and auto-issue\n      policy, catalog shape, OIDC baseline, release baseline, profiles, tiers, provisioning,\n      edge-mint recipes.\n- [ ] Admin-set **values and management states** (per profile\u002Ftier\u002Flicense\u002Fdevice) live in D1 and\n      are **not** overwritten by a resync.\n- [ ] **Edge-mint recipes need operator approval.** A recipe from `.pkey\u002F` is inert (its token\n      route answers `404`) until an operator approves it in the console's Secrets view, and it\n      signs only with a secret the operator marked usage `edge-mint`. The manifest can never set\n      either. Changing a recipe's `alg`, `signingKeySecret`, `kid`, `claimsTemplate`,\n      `ttlSeconds` or `audience` makes it inert again until it is re-approved; an unchanged\n      resync keeps it approved; dropping it deletes its approval. So does a push that makes the\n      mint public — opens registration (License and Identity both off, so the derived policy is `open`),\n      enables anonymous `autoIssue` (`mode: anonymous`\u002F`both`), or enables `oidcDefault` with\n      Identity on — when the approval was given without the open-registration acknowledgement.\n      And, with Identity on, so does any change to `oidc.provider`, `oidc.issuer`,\n      `oidc.clientId` or `oidc.groupRoleMap`, or turning Identity on. Tell the product owner to\n      expect a review step after any such push (docs: `services\u002Fconfig\u002Fedge-mint`).\n- [ ] Five blocks are operator-claimable: `services_source`, `fingerprint_policy_source`,\n      `auto_issue_source` (on the product), `compat_source` (the compat window, claimed from\n      Update settings) and `access_source` (both release access modes together, on\n      `release_config`). A live console edit flips the source `manifest` → `admin`, and a\n      resync then **skips** that block — a push cannot silently undo a 3am toggle, nor\n      downgrade an `entitled` product to the manifest's `public`. \"Revert to manifest\" hands\n      ownership back and changes nothing else; the manifest re-applies on the **next** resync,\n      not immediately.\n- [ ] The trusted-publisher policy (`ci_publishers`) is operator-claimable too: while\n      manifest-owned it follows `publishing.trustedPublisher` (a change is audited, and removing\n      the block removes the policy); once an operator claims it with a `PUT` to\n      `\u002Fmanage\u002Fapi\u002Fproducts\u002F\u003Cslug>\u002Fci-publisher`, a resync never touches it.\n- [ ] The operator-only artifact policy (`requireSparkleSignature`, `minimumSystemVersion`)\n      has **no manifest spelling at all** — it lives in `release_config.operator_policy_json`,\n      which no manifest path writes. Do not try to declare either key (or the `entitled` access\n      mode) in `.pkey\u002Frelease`; set them in the console's Update settings.\n\n## Verification\n\n```sh\npkey validate                                     # exit 0, no error lines\npkey doctor --base-url https:\u002F\u002Fkey.plrs.im --product \u003Cslug>\n\n# In this monorepo, after touching the validator, the schemas, or products\u002F\u003Cslug>:\nmise exec node@22 -- pnpm --filter @polaris-key\u002Fmanifest test   # incl. schema-parity\nmise exec node@22 -- pnpm --filter @polaris-key\u002Fcli test\nmise exec node@22 -- pnpm typecheck\nmise exec node@22 -- pnpm format\n```\n\nIf you added or changed a validator rule, `schema-parity.test.ts` will fail until its mutation\ntable carries an entry for the new error code — that is the gate working, not a flake.\n",{"name":5,"description":7},"main","653956a45d68cd6e3669d7a8482ef154b5b8373d","packages\u002Fagent-kit\u002Fskills\u002Fauthoring-pkey-manifests","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key","https:\u002F\u002Fgithub.com\u002Fvladzaharia","https:\u002F\u002Fvlad.gg","2026-11-14 10:31:35",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add vladzaharia\u002Fpolaris-key --skill authoring-pkey-manifests",{"tool":37,"command":38},"bunx","bunx skills add vladzaharia\u002Fpolaris-key --skill authoring-pkey-manifests",{"tool":40,"command":41},"pnpm","pnpm dlx skills add vladzaharia\u002Fpolaris-key --skill authoring-pkey-manifests","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-kit\u002Fskills\u002Fauthoring-pkey-manifests\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fvalidation-codes.md","REFERENCE","参考文档",151259,"https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-kit\u002Fskills\u002Fauthoring-pkey-manifests\u002Freferences\u002Fvalidation-codes.md",[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M77KYBX8FSRNXMKPRECZWM88","r7-secret","Sets a secret outside a handoff fence. Use when testing rule 7.","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Ftools\u002Ffixtures\u002Fskills\u002Fr7-secret\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M77KY8JAWQKSF3VJGFVSW539","r6-gated-link","Links an admin page. Use when testing rule 6.","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Ftools\u002Ffixtures\u002Fskills\u002Fr6-gated-link\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M77KY5A9SHYY73C7G1TVGCF9","r5-programme-id","Names a programme id. Use when testing rule 5.","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Ftools\u002Ffixtures\u002Fskills\u002Fr5-programme-id\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M77KY2JHMYJXKETK8XR1BEN9","r4-names","Cites names that do not exist. Use when testing rule 4.","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Ftools\u002Ffixtures\u002Fskills\u002Fr4-names\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M77KY17XDV8GD735M5F7TZ14","r3-deep","A reference nests a directory. Use when testing rule 3.","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Ftools\u002Ffixtures\u002Fskills\u002Fr3-deep\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M77KXYNWD7YKCQV2H7AHAKEY","Bad_Name","The name breaks the pattern. Use when testing rule 1.","https:\u002F\u002Fgithub.com\u002Fvladzaharia\u002Fpolaris-key\u002Fblob\u002Fmain\u002Ftools\u002Ffixtures\u002Fskills\u002Fr1-name\u002FSKILL.md",[],[]]