authoring-pkey-manifests
Use when creating or editing a product's .pkey/ 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.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- authoring-pkey-manifests
- description
- Use when creating or editing a product's .pkey/ 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.
02 资源文件 1
- 参考文档references/validation-codes.md147.7 KB
03 SKILL.md 正文
Authoring a .pkey/ manifest
A Polaris Key product is data, not code: its catalog, metadata and release coordinates live
in a .pkey/ directory in the product's own repo. Adding or changing a product must never
require a worker redeploy. .pkey/ is the only manifest directory — there is no second
candidate and no fallback between two.
Reference (all now on the docs site, in the repo under packages/docs/src/content/docs/):
build/manifest/product.md (the .pkey/ convention), start/first-product.md (the adopter
guide), build/manifest/register.md (getting a product into D1), and start/concepts.md (the
canonical glossary).
Every validator error and warning code, by manifest file: references/validation-codes.md.
Checklist
1. Scaffold
- [ ] Run
pkey initin the product repo root. It creates.pkey/and writes YAML:product.yamlandschema.yamlalways (ingest requires both, even with Config off; withoutconfigthe schema is an empty catalog,schemaVersion: 1andentries: []);release.yamlwhen Release is selected. The scaffolded tier names its profile withprofileIdand ispolicyDeviceLimit: 5with no expiry. - [ ] Other flags:
--admin-group,--release-owner,--release-repo,--force(overwrite). With no--modules, the default islicense,config. - [ ] Do not hand-create the directory if
pkey initwill do it — the scaffold writes the# yaml-language-server: $schema=…header that gives you completion in the editor.
pkey init --product <slug> --name "<Name>" --modules license,config
2. Get editor validation working
- [ ] Scaffolded files point at a path, not a URL:
../node_modules/@polaris-key/manifest/schemas/v1/<role>.schema.json. The canonical$idURLs (key.plrs.im, underschemas/v1/) are identifiers on the auth-gated docs site, not fetch targets — an editor cannot retrieve them. - [ ] In this monorepo,
.vscode/settings.jsonalready wiresjson.schemasandyaml.schemasfor**/.pkey/{product,schema,release,distribution}.{json,yaml,yml}and theproducts/*fixtures. YAML completion needs theredhat.vscode-yamlextension. - [ ] The schemas ship inside the
@polaris-key/manifestnpm package (schemas/v1/), so a product repo that installs the package gets them locally.
3. Know what each of the four files owns
-
[ ] Write the canonical spellings — the layout
pkey initwrites:product:holds identity and compatibility (slug,name,adminGroup,compatMin,compatMax),licensing:holds the licence defaults andtiers,profilessits at the root (the oldlicensing.profileswarns, andpkey validate --fixmoves it), a tier names its profile withprofileId, the catalog isentries, and.pkey/releaseputs its body underrelease:withprovider: { type: github, owner, repo }. The old spellings (a flat product document, roottiers,catalog,ghOwner/ghRepo, legacymodules:names, …) still validate with their old precedence, butpkey validatewarnsdeprecated_spelling(orconflicting_spellingwhen both are set). The full table isbuild/manifest/product.md→ "Deprecated spellings"; the source of truth isDEPRECATED_SPELLINGSinpackages/shared-manifest/src/spellings.ts. -
[ ] Keep one file per document (
product.yamlorproduct.json, not both): only the first ofjson,yaml,ymlis read, andpkey validatewarns when there are more. -
[ ]
schema(required) — the config catalog:{ schemaVersion, entries[] }, plus an optional top-levelcloudSyncblock (Cloud Sync's records:collectionsandmigrations). Maps to theproduct_schemarow. For an entry's fields, including the optionaluserblock that tunes a synced setting, use theadding-a-catalog-entryskill. -
[ ] With Cloud Sync (
sync) on, every Editableconfigkey is a synced setting (nomanagementDefaultofenforcedorhidden); a key the catalog does not declare syncs too, as an open setting (lastWrite, schema-less, at most 8 KiB). Declared and open settings share one budget: 256 keys and 64 KiB per person. An app treats an undeclared key as untrusted input, because any device of the person can write it; a key that matters is declared with a schema, givenuser: { sync: "local" }, or locked. -
[ ] A collection declares a namespace of records:
name, optionallabel,template(saves: 16 save slots per person,revision, one file of up to 32 MiB with 5 older versions, andplaytime,progress,chapter,formatVersionand a base64thumbnail;session:lastWrite, 16 records, an 8 MiB file),conflict(lastWrite,max,min,merge,union,revision;max/minneed a numberconflictField),schema,maxRecords(≤ 10,000, never on asavescollection),files(maxBytes≤ 1 GiB andkeepRevisions) andrequires(a catalog flag or a system entitlement the anchor licence must grant).accessisowneronly. Retired, refused with no warning period:cloudSync.saves(usetemplate: "saves"),cloudSync.open,onAttach(the first sign-in is an ordinary sync) anduser.sync: "device"(uselocal). -
[ ]
product(required) — product metadata, themodulesblock (enabled services; the device-registration policy is derived from them, never declared),web.origins, OIDC, theidentity:block, profiles, tiers, provisioning hooks,fingerprint,autoIssueandsecrets.required. Maps toproducts(incl.services_json,web_origins_json) plusoidc_config,profiles,tiers,provisioning_config. There is nocloudSyncblock here any more (the validator refuses one): a person's Cloud Sync quota is thepkey.cloudSync.bytesentitlement (256 MiB when unset) that a tier, a licence override or an add-on sets, and the ceiling and the pause are console settings. -
[ ]
release(required only when releases are enabled) — release-provider coordinates, channels, install/appcast settings, edge-mint recipes, and the app deliverable with its artifact map. Maps torelease_config,release_deliverablesandedge_mint_config. -
[ ] If the repo publishes tags that are not app releases (rolling
channels, contentpacks, …), say so inrelease:stableTagPattern(an anchored regex, ≤ 80 characters, same safety rule asmanualChannels[].regex) narrows which tags may become stable/latest, andignoreTagslists exact tag names that never resolve on a moving channel. Undeclared, any semver tag with an optional leadingvis a candidate, and the highest semver wins — not the newest by creation order. The same two fields may instead sit underdeliverables.app.versioning, which is the canonical place (the body spelling is marked deprecated in the schema); never in both places (conflicting_versioning). -
[ ] If the product ships more than a CLI and a DMG (Windows, Linux, Android, iOS, web, a universal binary…), declare the files instead of relying on name sniffing:
deliverables.appwithkind: app, optionalversioning(scheme:semver|semver+build|4part;buildNumber:descriptor|none),channels(beta: { includes: [stable] }; canonical names only, nostaging/latest, no cycles), andartifacts[], one entry per build:{ id, platform, arch, format, role?, match }.platform∈ macos/ios/android/windows/linux/web,arch∈ arm64/x86_64/universal/armv7/wasm32/any,roledefaults topayload(installer versus portable is aformat, never a role),matchis an anchored case-sensitive glob (*,?, ≤ 128 chars).<payload>.sig/.sha256join their build automatically. An entry may listembeds: [<packId>…], the packs that build ships (omitted = everybaseline: embeddedpack;invalid_build_embeds). CI may then attach a release descriptor (pkey-release.json,release-descriptor.schema.json) whose builds must match this map. -
[ ] Name every build and its files by platform plus arch: ids like
macos-arm64,win-x64,linux-arm64(never a barearm64/x86_64/x64, which is the warningbare_arch_artifact_id), and globs over files likedjdl-*-macos-arm64.app.zip, notdjdl-*-arm64.app.zip. The console, portal, download page andpkey release publishlabel builds throughbuildLabel(macOS · Apple silicon (arm64),Windows · x64 (x86_64),All platforms), and a file lacking a platform inherits its build's or its name's — so give the name something to say. See "How builds are labelled" on/docs/build/manifest/release/. -
[ ] If the product ships content packs, declare each as
deliverables.<packId>withkind: pack(at most 64,too_many_pack_deliverables):type(godot.pck|files.tree, required),binding(pinned, the default: each app release pins the pack release;compatible: Release resolves the newest release whoserequires.contentApirange holds each live contentApi level;standalone: the newest release for every level),baseline(embedded|none),required(thendelivery: essentialand noentitlement),delivery(essential|prefetch|on-demand),contentPolicy: { dataOnly: true },handler(mountOrder0–1000,prefixesofres://…/directories,activationrestart|hot; agodot.pckneedsprefixesandrequires.engine: godot-4.7, afiles.treetakes neitherprefixesnormountOrder),variants(texture/locale/quality→ values, ≤ 32 combinations),requires: { engine?, contentApi?, packs? }(contentApi: { app: ">=3 <5" }is required forcompatible—missing_content_api_range— and refused forstandalone—standalone_with_content_api; its only key isapp,unknown_content_api_app;packs: { <packId>: ">=1.2.0 <2.0.0" }names other compatible or standalone packs),conflicts(other declared packs,invalid_pack_conflicts),channels(canonical channels beyondstableandbetathe pack's releases go to,invalid_channel),patch(strategies⊆delta,file,chunk, default all three;deltaBases0–8),versioning.scheme, andentitlement, which must name aflagof.pkey/schemaand only ASSERTS the gate an operator sets under Distribution → Access (a publish whose gate differs is refused).provides: {required?, from?}is the save-compatibility policy (invalid_pack_provides;froma repo-relative JSON list of content ids, default.pkey/provides.json);removesis never declared (pack_field_not_supported), it ispkey release publish --removes.deliverables.app.content: { contentApi: <int>, packChannels?, attachable? }is then required (invalid_app_content);packChannelsmaps a pack id orprefix.*to a channel the matched packs publish to (invalid_pack_channels,unknown_pack_channels_target). Holds are never declared: an app release holds a compatible pack at publish.attachable(invalid_app_attachable) lists the app scripts (res://…paths,res://…/directories) and canonicaluid://UIDs agodot.pckpack may reference outside itself; absent, the publish lint refuses any such reference (the device too, except app UIDs it resolves to non-script resources). List a script's path and its UID (Godot 4.4+ writes both) and the UID of any app resource packs reach by UID, and mirror the list in the Godot SDK'sPKeyOptions.pack_attachable. Codes:invalid_pack_type,invalid_pack_binding,invalid_pack_policy,invalid_pack_handler,invalid_pack_variants,invalid_pack_requires,missing_content_api_range,standalone_with_content_api,unknown_content_api_app,invalid_pack_conflicts,invalid_pack_channels,unknown_pack_channels_target,invalid_app_attachable,invalid_pack_patch,unknown_entitlement_ref. Details:packages/docs/src/content/docs/features/ship-builds/packs/index.md. -
[ ] If CI should publish releases (trusted publishing), declare the publisher in
releaseunderpublishing.trustedPublisherwith aworkflow(.github/workflows/<file>.yml) and an optionalenvironment(defaultrelease). Those two fields are ALL the manifest can say: the repository's numeric ids come from GitHub at link/resync, the protected-ref / GitHub-hosted-runner / allowed-event checks are fixed, and scopes are an operator setting. Tell the owner the publishing ref needs a branch or tag ruleset (ref_protected), and the environment should require reviewers. Codes:invalid_trusted_publisher_workflow,invalid_trusted_publisher_environment. -
[ ] If the product ships signed updates (wire v4), declare
releaseKeys: [{ kid, publicKey }]inrelease(1–4 entries;publicKeyis the raw Ed25519 key in 43-character base64url, as the release-key generator prints it). The private key is a CI secret (PKEY_RELEASE_KEY), never committed. Never reuse a product signing key (the sync refuses it,release_key_is_product_key) or the Sparkle key (release_key_reused). Codes:invalid_release_key,weak_release_key,duplicate_release_key,release_key_reused;contentKeysonly warns (content_keys_not_supported). -
[ ]
distribution(optional; P2b-02) — where the product is distributed:outletskeyed by outlet id (an id that is itself a kind such assteam,play,app-storeneeds nokind, and anykindit does give must repeat the id —outlet_kind_mismatch;altstore-betaneedskind: altstore, and once linked it can change kind only to one that narrows its capability defaults), each with its kind's store identity fields (bundleId,packageName,steam.appId,itch.gameId,packageFamilyName,homebrewCask,testflight.publicLink,direct.scoop {bin, shortcuts}, …);transports(default—pkey-cdnorembedded—,packs.<outlet>,deliverables.<id>.<outlet>); andlisting. Maps todist_outletsanddist_transports. Absent = one implicitdirectoutlet bypkey-cdn. Anartifactmust name an id in the release artifact map;tracks/branches/flightskeys must be declared channels (ms-store.flightsmaps a channel to a Microsoft Store package flight by friendly name or flight id; the non-flighted submission is alwaysstable). -
[ ] Never put
capabilitiesin.pkey/distribution— anywhere in it is an error (capabilities_not_manifest_writable). Outlet capabilities default per kind and only an operator narrows them, in the console. -
[ ] For a Godot export, CI turns the build's outlet into the stamp's ids with
pkey distribution outlet-ids --outlet <id>(every value a string;{}with no file). Full reference:build/manifest/distribution.md. -
[ ] The base name selects the role; the extension is a pure format preference, tried
.json→.yaml→.ymland resolved per document, soproduct.yamlmay sit next toschema.json. -
[ ] Everything here is the manifest baseline. Secret values, license/device overrides, live service toggles and operator policy overrides live in Polaris Key and survive resync.
4. Pick module names (both vocabularies parse)
- [ ] Canonical service slugs:
license,config,release,distribution,update,identity,sync(Cloud Sync, which needsconfigandidentityon:sync_requires_config,sync_requires_identity),commerce(store purchases; needslicenseon:commerce_requires_license). Every entry is{ "enabled": <boolean> }; anything other than literaltruecounts as off. - [ ] The pre-suite vocabulary is still accepted and translated at ingest — only slugs are stored, and one block may mix both spellings (table below).
- [ ] No
modulesblock (or every entry off) meanslicense+configon, the rest off. - [ ] The device-registration policy is derived, never declared: License on is
requires-license; else Identity on isrequires-identity; elseopen.devices.registrationis removed (0.9): any value is the errorinvalid_registration_policy, so delete the field. The effective policy is read-only (effectiveRegistrationin the console's services API,core.registrationin discovery) and follows the services you turn on or off.
| Declared | Enables | Why |
|---|---|---|
licensing |
license |
rename |
config |
config |
unchanged |
releases |
release + distribution + update |
the old module meant "distributes software" — the suite splits truth, delivery and the feed |
oidc |
identity |
rename |
edgeMint |
config |
edge-minting is a secret-delivery capability of Config, not a unit of its own |
- [ ] Release, Distribution and Update are a chain — release ← distribution ← update. Naming
the slugs directly means naming all three you need:
updateneedsdistribution, anddistributionneedsrelease. The legacyreleasesname enables all three at once.
pkey init --modules takes either vocabulary (service slugs or the old names above) and always
scaffolds the modules block in service slugs. In a manifest, the old names are deprecated:
they still enable their services, and pkey validate warns deprecated_spelling. The slugs and the legacy mapping are the service
table, tools/services.json.
-
[ ]
web.originsis optional: up to 16 exact browser origins that may read this product's device-facing routes withfetch(CORS, no credentials). Spell each one the way a browser sendsOrigin:https://<host>[:port], lower-case, no default port, no path, trailing slash, query, credentials or wildcard. Plainhttponly forhttp://localhost[:port]andhttp://127.0.0.1[:port]. Bad entries are refused, never coerced (invalid_web_origins,invalid_web_origin). Manifest-owned: resync rewrites it and dropping the block clears it. Details:packages/docs/src/content/docs/build/web-apps.md. -
[ ] The
identity:block is optional and applies only whileidentityis on (declared with it off,pkey validatewarnsidentity_block_without_service). Identity on no longer needs anoidcblock. Members (methods,connectionsandclaimscome later):```yaml identity: keyEntry: { limit: 10, claimByKey: false } # limit 1–100 (default 10); claimByKey default false terms: { version: "2026-10", url: "https://example.com/terms" } # version [A-Za-z0-9._-]{1,32}; url https redirectPaths: ["/auth/callback"] # ≤ 16 unique, rooted at /, no ? # * // .. ``` Codes: `invalid_identity` (any other member), `invalid_identity_key_entry_limit`, `invalid_identity_claim_by_key`, `invalid_identity_terms`, `invalid_identity_redirect_paths`, and the warning `identity_redirect_paths_without_origins` (redirect paths need `web.origins`). Each member is a **claimable** setting (`identity.keyEntry.limit`, `identity.keyEntry.claimByKey`, `identity.terms`, `identity.redirectPaths`): a console edit claims it and Revert returns it to the manifest. `claimByKey: true` lets anyone holding a leaked key add an email-bound licence to their own account; leave it off unless the product truly sells keys with no buyer email to check.
5. Validate until clean
- [ ]
pkey validate— parses.pkey/, runs the authoritative TypeScript validator, and prints the enabled modules, required secrets, warnings, then errors. Exit code 0 means valid. - [ ] Fix every
error. Common ones:update_requires_distribution(Update on with Distribution off — the feed would answer every client with an empty document),distribution_requires_release(Distribution on with Release off — nothing to deliver),sync_requires_configandsync_requires_identity(Cloud Sync on without Config or Identity: the manifest is refused and nothing is turned on for you),invalid_registration_policy(adevices.registrationvalue, any value: the field is removed, delete it),reserved_slug. - [ ] Read the
warninglines too.config_without_activationis a warning (Config on with License and Identity off: a config-only product is legitimate, and its devices registeropen). Nothing turns it into an error. - [ ]
pkey doctor --base-url <url> --product <slug>re-runs local validation and then checks the live discovery document. Without both flags the remote half is skipped.
6. Avoid reserved slugs
- [ ]
product.slugmust not collide with a platform route the worker matches before/<product>/…. The refused list (RESERVED_PRODUCT_SLUGS) is:docs,manage,api,assets,login,logout,callback,magic,download,webhooks,well-known,media,activate,avatar,device,tv,signin,help, plus the admin API's route actions (PRODUCT_ROUTE_ACTIONS):kek,link-repo,slug-check. A product registered under one would be permanently shadowed; the validator emitsreserved_slugand the console's manual-create path checks the same lists. - [ ] The slug's shape is
^[a-z0-9][a-z0-9-]{0,63}$(PRODUCT_SLUG_PATTERN): no leading hyphen, at most 64 characters. Otherwise the validator emitsinvalid_slug.
6a. Name the product as itself (display names, PX-W13)
- [ ]
product.name,listing.nameandlisting.developerNameare what the customer's sign-in card shows ("<App> wants you to sign in"). A control, invisible or bidi character, a name that starts with a variation selector, or a leading or trailing space, isinvalid_display_text(an error, also in the JSON Schemas). - [ ] A platform or store name as whole words (Polaris Key, plrs, Apple, App Store, Google,
Google Play, Steam, Valve, Epic Games, Microsoft, Xbox, PlayStation, Nintendo, itch.io,
after folding case, width, accents, look-alikes and separators) is
reserved_display_name: a warning today, an error once the platform settingIDENTITY_RESERVED_DISPLAY_NAMESsayserror. Either way the card shows such a product by its slug. Only the system productpolaris-keyis exempt.
7. Register the product
- [ ] Repo-link (preferred). In the console, link the product's repo. The worker fetches and
parses the three files and registers the product, minting the sealed signing key and
returning the public trust key. Re-linking, or a signed GitHub push webhook, re-parses and
updates the rows; webhook sync is pinned to the pushed commit SHA, records the changed
.pkey/paths, and surfaces applied sections or validation errors in the Releases view. - [ ] Manual create. Product metadata plus a schema document, for early experiments. Release, OIDC, provisioning, profiles, tiers and edge-mint rows are configured later or by linking.
- [ ] Seed SQL is a fixture tool only —
pnpm --filter @polaris-key/products gen-seed <slug>. It cannot mint sealedproduct_keysor store secret values; never use it for live onboarding.
8. Understand resync and ownership before you promise a behavior
- [ ] A resync updates the manifest baseline: product metadata, service enablement (the
device-registration policy follows from it),
web.origins, fingerprint and auto-issue policy, catalog shape, OIDC baseline, release baseline, profiles, tiers, provisioning, edge-mint recipes. - [ ] Admin-set values and management states (per profile/tier/license/device) live in D1 and are not overwritten by a resync.
- [ ] Edge-mint recipes need operator approval. A recipe from
.pkey/is inert (its token route answers404) until an operator approves it in the console's Secrets view, and it signs only with a secret the operator marked usageedge-mint. The manifest can never set either. Changing a recipe'salg,signingKeySecret,kid,claimsTemplate,ttlSecondsoraudiencemakes it inert again until it is re-approved; an unchanged resync keeps it approved; dropping it deletes its approval. So does a push that makes the mint public — opens registration (License and Identity both off, so the derived policy isopen), enables anonymousautoIssue(mode: anonymous/both), or enablesoidcDefaultwith Identity on — when the approval was given without the open-registration acknowledgement. And, with Identity on, so does any change tooidc.provider,oidc.issuer,oidc.clientIdoroidc.groupRoleMap, or turning Identity on. Tell the product owner to expect a review step after any such push (docs:services/config/edge-mint). - [ ] Five blocks are operator-claimable:
services_source,fingerprint_policy_source,auto_issue_source(on the product),compat_source(the compat window, claimed from Update settings) andaccess_source(both release access modes together, onrelease_config). A live console edit flips the sourcemanifest→admin, and a resync then skips that block — a push cannot silently undo a 3am toggle, nor downgrade anentitledproduct to the manifest'spublic. "Revert to manifest" hands ownership back and changes nothing else; the manifest re-applies on the next resync, not immediately. - [ ] The trusted-publisher policy (
ci_publishers) is operator-claimable too: while manifest-owned it followspublishing.trustedPublisher(a change is audited, and removing the block removes the policy); once an operator claims it with aPUTto/manage/api/products/<slug>/ci-publisher, a resync never touches it. - [ ] The operator-only artifact policy (
requireSparkleSignature,minimumSystemVersion) has no manifest spelling at all — it lives inrelease_config.operator_policy_json, which no manifest path writes. Do not try to declare either key (or theentitledaccess mode) in.pkey/release; set them in the console's Update settings.
Verification
pkey validate # exit 0, no error lines
pkey doctor --base-url https://key.plrs.im --product <slug>
# In this monorepo, after touching the validator, the schemas, or products/<slug>:
mise exec node@22 -- pnpm --filter @polaris-key/manifest test # incl. schema-parity
mise exec node@22 -- pnpm --filter @polaris-key/cli test
mise exec node@22 -- pnpm typecheck
mise exec node@22 -- pnpm format
If you added or changed a validator rule, schema-parity.test.ts will fail until its mutation
table carries an entry for the new error code — that is the gate working, not a flake.
04 同仓库更多 Skills
r7-secret
Sets a secret outside a handoff fence. Use when testing rule 7.
r6-gated-link
Links an admin page. Use when testing rule 6.
r5-programme-id
Names a programme id. Use when testing rule 5.
r4-names
Cites names that do not exist. Use when testing rule 4.
r3-deep
A reference nests a directory. Use when testing rule 3.
Bad_Name
The name breaks the pattern. Use when testing rule 1.