@hasna/skills 0.8.10 → 0.8.11

package/README.md

@@ -314,6 +314,42 @@ pinned session. It preserves exact versions and does not extend an expired
 receipt's lifetime. Authentication, integrity and native discovery failures still
 block; they do not silently switch to a local catalog.
 
+An intentional profile change for an already running session uses a separate
+reviewed operation. `sync` and hook reinstallation do not migrate session pins:
+
+```bash
+skills sessions show <session-id> --json
+skills sessions reconcile <session-id> \
+  --from-profile <old-profile> --from-revision <old-revision> \
+  --receipt-sha256 <receipt-sha256> \
+  --selection-profile <target-profile> --profile-revision <target-revision> --json
+# Within five minutes, repeat with --apply --plan-digest <digest> \
+#   --plan-issued-at <issuedAt> --plan-expires-at <expiresAt>.
+```
+
+Reconciliation authenticates against the current target profile and refuses a
+changed target revision, authority, workspace, old receipt or plan. It archives
+the original bytes and prepared replacement under
+`selection-cache/session-reconciliations`, then replaces only the named session
+receipt atomically. Loaded instructions are retained only when their exact
+authority, workspace, version and bundle digest still match. Existing child
+sessions and project locks keep their own pins; new children inherit the newly
+reviewed parent selection. Each new child receipt privately records the exact
+parent receipt hash and monotonic generation it inherited. Parent and child locks
+are acquired in deterministic path order, and the parent is re-read immediately
+before the child commit; any changed or ABA generation refuses the child write.
+No agent process is stopped or restarted.
+
+Use the same updated Skills installation for every process writing this cache.
+Session writers coordinate with reconciliation and refuse a stale write that
+would restore an earlier pin. Reviewed reconciliation approvals bind their
+`issuedAt` and `expiresAt` into the digest and expire after five minutes; after
+that replay boundary, prepare and review a new plan. A competing writer or surviving lock fails closed;
+do not delete a lock without reviewing its owning operation. If application
+reports an incomplete outcome, inspect `sessions show` and the preserved
+operation receipt before retrying. The archive contains both original and
+prepared bytes even if the final receipt write fails.
+
 ## Profiles, station sync and rollback
 
 ```bash
@@ -702,6 +738,8 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills load <name> --selection-profile <id>` | | Load complete instructions from the verified selection |
 | `skills context <prompt> --selection-profile <id>` | | Resolve instructions matching the prompt and profile triggers |
 | `skills hook install --agent all --selection-profile <id>` | | Plan one CLI bridge plus supported native hooks; `--apply` installs it, then restart and trust the hooks |
+| `skills sessions show <id> --json` | | Inspect one session's exact profile revision and receipt hash without loading payloads |
+| `skills sessions reconcile <id> --from-profile <id> --from-revision <rev> --receipt-sha256 <sha> --selection-profile <id> --profile-revision <rev>` | | Plan an explicit migration of one live session; `--apply --plan-digest <digest> --plan-issued-at <time> --plan-expires-at <time>` (within five minutes) preserves its old receipt and applies the reviewed replacement |
 | `skills hook agents --json` | | Report maintained adapters and explicit coverage limits |
 | `skills migrate native` | | Inventory native copies; `--apply` archives managed copies, with explicit `--include-unmanaged` and `--include-vendor` retirement options |
 | `skills pull --all --selection-profile <id>` | | With CLI loading active, refresh the selected profile into the verified cache |
@@ -1107,7 +1145,7 @@ skills --profile customer billing status --json
 skills --profile customer billing usage --json
 skills --profile customer billing invoices --json
 skills --profile customer credits packs --json
-skills --profile customer credits buy <pack-id> --json
+skills --profile customer credits buy <pack-id> --idempotency-key checkout-001 --json
 skills --profile customer billing portal --json
 skills --profile customer auth keys list --email you@example.com --code <FRESH-CODE> --json
 # Request a fresh OTP, then create a separately scoped key (shown once).
@@ -1116,6 +1154,19 @@ skills --profile customer auth keys create automation --email you@example.com --
 skills --profile customer auth logout --json
 ```
 
+For credit checkouts, generate and retain a unique request key **before** calling.
+The SDK accepts `createCreditCheckout(packId, { idempotencyKey })`; MCP
+`create_credit_checkout` accepts `idempotency_key`. Success and bounded checkout
+errors retain `requestIdempotencyKey`. An omitted key is generated before the
+single POST, but an explicit saved key is needed if the client process exits
+before returning any result. Recover only on the same server, account and pack.
+No surface retries a checkout automatically. For unresolved or in-progress
+outcomes, inspect billing and explicitly reuse the same key after any indicated
+wait. Expired or fulfilled outcomes need a deliberate decision, not a fresh key
+on an automatic retry. The provider's derived `idempotencyKey` is not the request
+key. This protocol requires the configured server to honor checkout idempotency;
+older servers can return a link without proving durable recovery semantics.
+
 An origin, a full `/api/v1` base and a base with a path prefix normalize to the
 same routes. `HASNA_PROFILE=customer` selects the same profile as `--profile`.
 `HASNA_SKILLS_API_URL` (or the compatible `SKILLS_API_URL`) is an explicit URL