@hasna/skills 0.8.9 → 0.8.11

package/README.md

@@ -92,6 +92,13 @@ before synchronization or context loading. Review the hook installation and
 restart the native client to load its current commands. Explicit `skills load`,
 `skills context`, and `skills sync` commands can still select other profiles.
 
+Reinstalling hooks without `--command` or `--selection-profile` preserves each
+agent's existing executable and profile independently, including when using
+`--agent all`. New agents use `skills` and `default`. Either explicit flag
+overrides that choice for the requested agents. The policy's shared default
+profile changes only when `--selection-profile` is supplied; older managed
+agents without a per-agent profile retain that shared default.
+
 The hook install `--include-vendor` option is retained for compatibility with
 older scripts. Hook planning always inventories and disables discovered vendor
 system skills; use `migrate native --include-vendor` when retiring their
@@ -103,6 +110,24 @@ request a selected skill in a prompt, for example `Use $pdf-generate to create
 a PDF`. The hooks supply instructions; executing the skill remains a separate
 explicit action.
 
+For Codex 0.153.0, 0.154.0, and 0.155.0, the normal installed Skills CLI can
+plan native trust for its three exact managed hook definitions:
+
+```bash
+skills hook trust --agent codex --json
+skills hook trust --agent codex --apply --plan-digest <reviewed-plan-digest> --json
+```
+
+Review the commands, current hashes, and existing trust/enable state in the
+plan. Apply refuses if the plan, package, declarations, or configuration changed.
+It enrolls the current exact definitions, including reviewed modified hooks,
+and preserves unrelated trust, settings, and comments. A private journal keeps
+the pre-write configuration; a failed write or verification requires journal
+reconciliation before retry. Unsupported versions or configuration layouts
+refuse without a configuration write. Enrollment uses a short-lived native
+app-server and makes hooks eligible for new Codex processes. Existing sessions
+retain their own configuration; use their native hook controls to refresh them.
+
 Each supported agent gets one small `skills-cli` native skill containing CLI
 instructions, without a copied catalogue. Claude's native Skill tool admits
 that bridge after other copies are retired. Prompt guards verify the owned
@@ -264,6 +289,14 @@ system configuration, process-specific overrides, and alternate agent home
 directories are outside automatic coverage and require their own integration
 review before declaring a station migrated.
 
+For reviewed Claude plugins, `skills integration plugin plan`, `admit` and
+`resolve` provide a command-source admission boundary before native discovery.
+Original packages and migrated skill/command prompts remain in private versioned
+Skills storage. Native projections retain ordinary components, and a typed
+receipt permits only verified registry/cache transitions. See
+[plugin admission](docs/plugin-admission.md) for the package, review and runtime
+contracts; these commands do not change live agent registrations or settings.
+
 If your home `.claude` or `.codex` directory intentionally links to another
 directory within your home, add `--allow-root-aliases` to hook installation and
 native migration. The plan records and rechecks the exact link and target;
@@ -281,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
@@ -348,6 +417,24 @@ user and stable station ID, so rotating a key does not create a new station.
 Consumers need `skills:read` and `stations:write`; profile publishers need
 `skills:write`. Key scopes apply even to workspace owners.
 
+`skills auth whoami --json` reports the current credential's effective
+`permissions.publish` and `permissions.profilesWrite`, alongside its account
+role and advertised scopes. Human output labels each permission `allowed`,
+`denied`, or `unknown`; JSON uses `null` for unknown access. An owner role alone
+does not grant either permission. `skills capabilities --json` and the SDK's
+`getCapabilities()` also retain the server's typed permission and scope fields.
+
+Before sending a bundle, `push` and `RemoteSkillsClient.publishSkill()` read
+fresh capabilities and stop on an explicit publication denial. `profiles set`
+similarly stops before a profile write. The refusal reports
+`SKILLS_PERMISSION_DENIED` with the affected permission and guidance to obtain
+an authorized credential; it never changes credentials or their scopes.
+Servers that omit permissions (or predate the capabilities route) retain their
+existing server-authorized write behavior, with access displayed as unknown.
+Authentication failures and malformed permission responses do not bypass the
+preflight. `push --dry-run` remains a local packing check and does not check
+hosted publication access.
+
 `--selection-profile` chooses the shared skill selection. The top-level
 `--profile` option chooses an isolated credential file; these are separate
 settings. `HASNA_SKILLS_SELECTION_PROFILE` overrides the installed selection
@@ -651,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 |
@@ -1056,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).
@@ -1065,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