apple signing ensure with automatic signing only adds capabilities (no profiles or certificates; the dry run says so) and lists unused storebound profiles with the exact delete command, never run; every capability write is read back (lag retries, timeout) and fails with the API answers when one did not stick; apple status, signing status and validate compare the App ID, apple.signing.capabilities and the iOS project's entitlements (CODE_SIGN_ENTITLEMENTS too) and name what is missing where; api writes outside a terminal say TTY by design and name the dedicated command; pitfalls 64-66; tests

skills/build-and-sign/SKILL.md

@@ -20,15 +20,24 @@ when the owner said so for this run). The MCP server offers only `apple_signing_
    capabilities it has vs `apple.signing.capabilities`, the distribution certificates of the team and whether this
    Mac holds a private key for one (a key file in `.storebound/signing/` or an identity in the keychain), App Store
    profiles per bundle id (app + `apple.signing.extraBundleIds` for extensions) and whether Xcode has them installed.
+   It also compares three places a capability must be and names what is missing where: the App ID, the config's
+   `apple.signing.capabilities` and the iOS project's `.entitlements` (`aps-environment` = PUSH_NOTIFICATIONS,
+   `com.apple.developer.game-center` = GAME_CENTER, associated domains, Sign in with Apple, iCloud, app groups, ...;
+   an entitlements file must also be set in CODE_SIGN_ENTITLEMENTS). `apple status` and `validate` warn on the same.
 2. **Pick the style.** `apple.signing.style`:
    - `automatic` (default): `xcodebuild -allowProvisioningUpdates` with the API key creates and fetches what it needs.
-     Nothing to do in step 3 unless capabilities are missing. Easiest for one developer on one Mac.
+     `ensure` only adds missing capabilities to the App ID: it never creates certificates or profiles (Xcode owns
+     them; its managed profile is renewed with the new capabilities at the next archive). Easiest for one developer.
    - `manual`: certificate and profiles from step 3, named in ExportOptions.plist. Best for CI and teams; set the app
      target to manual signing with the installed profile in Xcode (Signing & Capabilities) once.
 3. **Ensure.** `storebound apple signing ensure --dry`, show it, then without `--dry` after a yes:
-   - adds missing capabilities (never removes one; extra ones are only reported). Adding a capability makes existing
-     profiles invalid: `ensure` creates new ones in the same run.
-   - creates an Apple Distribution certificate only when no valid one has its key on this machine. The RSA key is made
+   - adds missing capabilities (never removes one; extra ones are only reported), then reads the App ID back (a few
+     tries, about 45 s at most) and fails with the API's answers when one did not stick. Never report a capability
+     as added from the POST alone. With manual signing, adding one makes existing profiles stale: `ensure` creates
+     new ones in the same run.
+   - lists provisioning profiles storebound made that nothing uses ("storebound <bundle id> App Store <date>"), with
+     the exact delete command; deleting them is the owner's call, storebound never runs it.
+   - manual signing only from here on. Creates an Apple Distribution certificate only when no valid one has its key on this machine. The RSA key is made
      locally, kept 0600 in `.storebound/signing/<id>.key` next to `<id>.cer`; it is never printed and never leaves the
      machine. `--keychain` imports both into the login keychain (or `--keychain <path>`) so xcodebuild can sign.
      Back the key up (encrypted). Apple allows 3 distribution certificates per team: at the limit, revoking one is

skills/store-pitfalls/SKILL.md

@@ -740,3 +740,30 @@ that fails without the fix (see CONTRIBUTING.md).
   "price changes on existing products (held)" section. `apple iap` never changes an existing schedule.
 - **Guard:** `allowPriceChanges` / `heldSection` (cli/lib/price-gate.ts), `tests/price-gate.test.ts` (TTY and non-TTY:
   a "y" creates the new product and holds the live price; the flag's question names each change).
+
+## 64. `signing ensure` made a manual App Store profile for an automatic-signing app
+- **Do:** with `apple.signing.style: automatic` (the default), `apple signing ensure` only keeps the App ID and its
+  capabilities in step. It never creates certificates or profiles: Xcode owns them (`xcodebuild
+  -allowProvisioningUpdates` with the API key) and renews its managed profile when the capabilities change. The dry
+  run says so. Profiles storebound made that nothing uses ("storebound <bundle id> App Store <date>") are listed by
+  name with the exact `storebound api apple profiles_deleteInstance --param id=<id> --yes` command; deleting them is
+  the owner's call, never run by storebound.
+- **Guard:** `ensureScope`, `unusedStoreboundProfiles` (cli/lib/signing.ts), `tests/signing-capabilities.test.ts`.
+
+## 65. A capability add "succeeded" but the App ID kept only IN_APP_PURCHASE
+- **Do:** never report a capability as added from the POST answer. `signing ensure` reads the App ID back after any
+  capability write (a few tries with growing waits, about 45 s at most) and fails with the API's answers when one is
+  missing. The capability names were right (CapabilityType: PUSH_NOTIFICATIONS, GAME_CENTER); what an App ID shows
+  and what a build may use are different things: a provisioning profile keeps the entitlements of the moment it was
+  made, and an app whose project has no `.entitlements` (or one not set in CODE_SIGN_ENTITLEMENTS) ships without
+  the capability whatever the App ID says. `apple status`, `apple signing status` and `validate` compare the App ID,
+  `apple.signing.capabilities` and the project's entitlements and name what is missing where.
+- **Guard:** `verifyCapabilities`, `compareCapabilities`, `ENTITLEMENT_CAPABILITIES` (cli/lib/signing.ts),
+  `checkCapabilitiesStuck` (cli/apple/signing.ts), `tests/signing-capabilities.test.ts` (live-shape
+  bundleIdCapabilities answers, lag, a write that never sticks).
+
+## 66. `storebound api apple ... --body f.json --yes` only dry-ran from an agent
+- **Do:** expected: writes through `storebound api` are sent only from an interactive terminal, by design. Use the
+  dedicated command the message names (bundle id capabilities: `apple signing ensure`; IAPs: `apple iap`; listing:
+  `apple listing`, ...), which runs anywhere with its own dry run and read-back.
+- **Guard:** `dedicatedCommand` (cli/api/gate.ts), `tests/signing-capabilities.test.ts`.