@hasna/skills 0.10.71 → 0.10.73

package/README.md

@@ -113,6 +113,27 @@ skills hook install --selection-profile default --json
 skills hook install --selection-profile default --apply --json
 ```
 
+`--include-vendor` resolves configured plugin discovery, so it needs a reviewed
+`--discovery-inputs` file when a configured plugin declares hooks. Without it,
+`skills migrate native --include-unmanaged` archives user and project copies
+only. Migration never archives Codex system skills (`.codex/skills/.system`),
+even with `--include-vendor`. Codex refreshes its OpenAI marketplace plugin
+caches on its own; retire those copies with a Codex `[[skills.config]]` rule
+(`name = "<plugin>:<skill>"` or the exact `path` of the `SKILL.md`, with
+`enabled = false`) rather than by archiving. The live Codex prompt hook accepts
+a name rule only for a copy with no Hasna marker, its remote install receipt, a
+refresh-safe plugin and no rule that enables it. Other checks (`skills hook
+install` reusing a saved review, `skills hook trust`) do not accept a
+hand-added name rule; for them, and for system skills, run `skills hook install
+--agent codex --discovery-inputs <file> --apply` with a fresh discovery review
+(no `--discovery-inputs` on an automatic binding; add a fresh
+`--codex-native-catalog <file>` for a plugin Skills has enrolled), which writes
+and records the disables. Run the same refresh after editing `config.toml` when
+the binding's recorded configuration witness counts the edit: on automatic
+bindings, after removing a rule that enables skills, and on reviewed bindings
+whose witness counts disable rows. A `NATIVE_SKILL_DRIFT` refusal names the
+step for each copy it lists, including that follow-up.
+
 Without `--agent`, hook installation selects configured or detected consumers:
 existing managed bridge bindings, provider-specific home configuration, or an
 installed native CLI found through PATH. Detection reads metadata and never
@@ -207,6 +228,82 @@ is recorded at `agent-hooks/codex-native-policy-acceptance.json`; user,
 repository and project copies still refuse, and format or digest checks never
 prove the runtime policy on their own.
 
+A Codex plugin refresh can deposit a new vendor skill in `~/.codex/plugins/cache`
+(for example `openai-curated-remote/sites/1.0.2-remix-b.1/skills/sites-remix`).
+Skill payloads still reach agents only through the Skills CLI, so an enabled
+vendor copy keeps blocking the Codex prompt hook. Retire it by disabling it in
+`~/.codex/config.toml`. The plugin-qualified name survives later version
+directories, so prefer it:
+
+```toml
+[[skills.config]]
+name = "sites:sites-remix"
+enabled = false
+```
+
+An exact `path = ".../sites/1.0.2-remix-b.1/skills/sites-remix/SKILL.md"` rule
+also works, but only for that version. On the live Codex prompt hook only, a
+copy is then exempt when every condition holds:
+
+- it is package-classified plugin content in `openai-bundled`, `openai-curated`
+  or `openai-curated-remote` (exact names), with Codex's remote install receipt
+  for the remote marketplace;
+- it carries no Skills or Hasna marker;
+- every cached version of its plugin passes the vendor refresh check described
+  below for membership changes, so the plugin can load nothing that the
+  inventory and this rule do not account for, and no version is a link;
+- a `[[skills.config]]` rule names its exact path or its plugin-qualified name
+  with `enabled = false`, and no matching rule enables it.
+
+A whole-plugin `[plugins."sites@openai-curated-remote"] enabled = false` table
+is not enough on its own: remote state can enable a locally disabled remote
+plugin, and a cache copy carries no proof that its plugin source is
+configuration-controlled, so the copy keeps blocking until a path or name rule
+retires it. This exemption only adds to the guard's existing ones; every copy
+that the guard already accepts, such as an exact-path disable in any plugin-cache
+marketplace or a reviewed plugin control, stays accepted on the live hook. Once
+the hook tolerates one of the witness changes below, a state the strict guard
+refuses outright, plugin-cache copies are exempt only through this vendor rule.
+
+Instead of editing by hand, `skills hook native-catalog` followed by
+`skills hook install --agent codex --codex-native-catalog <file> --apply` writes
+the same rules through the guarded install path.
+
+The hook also tolerates, with a visible `systemMessage` warning, only the
+discovery-witness changes such a refresh provably makes:
+- appended vendor disable rules or vendor plugin disables in `config.toml`,
+  accepted when removing exactly those entries or restoring a formerly enabled
+  vendor flag reproduces the reviewed digest. Candidates are tried smallest edit
+  first, at most 128; with a typed settings witness that covers any change to up
+  to two of at most eight vendor plugin tables. A change beyond the bound refuses;
+- directory membership changes under an allowlisted vendor marketplace that
+  passes the vendor refresh check: every plugin version has exactly one
+  manifest, `.codex-plugin/plugin.json`, alone in its directory, whose keys are
+  only `name`, `version`, `description`, `author`, `homepage`, `repository`,
+  `license`, `keywords`, `interface`, `skills` (the default `./skills/` only) and
+  `apps`. So hooks in any form, commands, agents, extensions, MCP servers and
+  unknown keys refuse. There is no `hooks`, `commands` or `agents` directory, no
+  `hooks.json` or `.mcp.json` (names compared without regard to case), no root,
+  `.claude-plugin` or `.cursor-plugin` manifest, no link
+  and no `SKILL.md` below a dot-named or `node_modules` directory, or nested
+  in another skill. One exception keeps
+  today's vendor plugins working: every current OpenAI vendor plugin declares
+  its connector as `apps = "./.app.json"`, so exactly that declaration is
+  allowed when `.app.json` is a regular file of at most 1 MiB, strict UTF-8, that
+  passes the same connector validation reviewed plugin controls use (one `apps`
+  object; app entries with only `id`, `category` and `required`, of the right
+  types; no duplicate keys). Any other connector path, a file that fails that
+  validation, or the file without the declaration refuses.
+
+Every other copy and change still refuses with `NATIVE_SKILL_DRIFT`, including:
+- user, project, `.system` and Hasna-marketplace copies that the guard does not
+  already exempt;
+- an enabled vendor copy whose plugin is only disabled by a whole-plugin table;
+- capability-control changes and whole-cache membership changes;
+- plugin activation, including a vendor plugin gaining `enabled = true`;
+- missing coverage and changed roots;
+- every install, trust, migrate and sync check.
+
 Native hook invocations must use their installed adapter's selection profile.
 An old client command or environment override naming another profile refuses
 before synchronization or context loading. Review the hook installation and
@@ -465,6 +562,20 @@ is bounded to 20,000 discovery entries and 4 MiB of UTF-8 path metadata before
 directory entries are retained or sorted. Unsupported special files and unsafe
 directory links are refused.
 
+Codex 0.162.1 loads `SKILL.md` files below `node_modules` inside its skill
+roots, so Codex inventory and the prompt guard walk `node_modules` in
+`~/.codex/skills`, `~/.agents/skills`, each project's `.codex/skills` and
+`.agents/skills` and configured plugin skill roots. In `~/.codex/plugins/cache`
+they walk it only where it can lie in a plugin skill root: below a version's
+default `skills` directory or a manifest-declared skills path, or as a
+marketplace, plugin or version directory named `node_modules`; an unreadable
+manifest walks every `node_modules` in its version. Dot-named directories such
+as `node_modules/.pnpm`, a plugin version's own dependencies and any
+`node_modules` outside a skill root stay unscanned, because Codex does not load
+them; other agents' roots keep skipping `node_modules`. Depth limits are
+unchanged: Codex reads six directory levels below a root, and an ordinary root
+records a skill four levels down and refuses anything deeper.
+
 Native archives persist a version 2 recovery journal before moving payloads;
 `migrate native --json --apply` returns its `receiptPath`. The journal records
 every source, archive path, expected hash, and move status, then marks successful
@@ -550,6 +661,10 @@ non-null `sha256`, Skills also requires plain byte witnesses for that plugin's
 `hooks/hooks.json` (when present) and any string `hooks` target in the
 manifest. A manifest listed as `claude-plugin-manifest-v1` (the form Skills
 writes into the stored policy) or as `path-bytes` triggers no such requirement.
+The version-root `.orphaned_at` timestamp that Claude rewrites at startup is
+bound by presence only, as `claude-plugin-orphaned-at-v1`, and is still
+strictly validated; see
+[the full scope](docs/plugin-admission.md#reviewed-plugin-hook-attestation-scope).
 For plugins outside receipt-backed admission (a `claude-plugin-registry`
 witness, see the
 [discovery transition contract](docs/plugin-admission.md#discovery-transition-contract)),
@@ -622,6 +737,25 @@ 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.
 
+The read-only `skills hook review-claude-candidate` check requires its reviewed
+discovery inputs to bind the user settings, both project settings files and
+both plugin registries. A project `.claude/settings.json` or
+`.claude/settings.local.json` that the review omits is exempt only when no other
+expected source shares its path and it is either absent, or present with exact
+preimage bytes that parse strictly as one JSON object (strict UTF-8, no
+byte-order mark, comments, trailing content or duplicate keys) and carry only
+allowlisted settings: `permissions` with `allow`, `deny`, `ask` and
+`defaultMode`, plus `outputStyle`, `model`, `theme`, `effortLevel`, `verbose`
+and `spinnerTipsEnabled`. Any discovery key (`enabledPlugins`,
+`extraKnownMarketplaces`, `additionalMarketplaces`, `skillOverrides`), `env`,
+`hooks`, `permissions.additionalDirectories` or unknown key keeps the file
+required. The allowlist is a reviewed list of settings, not a proof that Claude
+cannot discover anything from the file. This admits the permissions-only
+`~/.claude/settings.local.json` that Claude writes when it saves a permission
+rule. Each exempt file is re-checked against its exact preimage until the
+result; user settings and the registries are never exempt. See
+[prospective Claude candidate review](docs/plugin-admission.md#prospective-claude-candidate-review).
+
 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;
@@ -819,16 +953,37 @@ a skill. Cached use is explicit and expires after 24 hours. When a session
 receipt expires, the hook authenticates the current profile. If every loaded
 selection still has identical metadata and bundle digest, it archives the old
 receipt and advances that session to the current profile under an exact receipt
-precondition. Unloaded selections may be added or removed. If a loaded selection
-changed or disappeared, no instructions are delivered until the explicit
-reconciliation below. A missing cache may be recovered through authenticated context.
+precondition. Unloaded selections may be added or removed. If renewal is refused
+because the same profile moved on (a loaded selection changed or disappeared, or
+another pinned selection's policy, membership or lifecycle changed), the managed
+hook applies the explicit reconciliation planner and applier below to the
+authenticated current revision: it archives the old receipt, retains unchanged
+loaded bundles, retires changed or removed ones and delivers context for the
+prompt. The first hook context that succeeds and reaches the agent afterwards
+names each retired loaded skill once and how to reload its replacement; earlier
+instructions from those skills must not be relied on. Identity, integrity and receipt failures, an
+unavailable authority and anything the planner refuses keep their refusal;
+session write-lock contention keeps `SESSION_WRITE_BUSY`. A
+session created from a project lock (`.skills/selection.lock.json`) records
+that lock in its receipt and is never migrated automatically, whatever
+directory it later prompts from. A session without that record is not migrated
+while a lock sits in the prompt's working directory or any ancestor. A loaded
+skill whose lifecycle epoch rotated while its bytes stayed the same also keeps
+the refusal. If the migration cannot finish within the four-second renewal window,
+the hook reports `SESSION_RECONCILIATION_REQUIRED` with that reason and the next
+prompt retries. Turn this off station-wide with `skills config set
+sessionPinMigration off --global` (the key is refused without `--global`, and a
+global configuration that is a symlink, cannot be read or cannot be parsed also
+turns it off); the hook
+then keeps today's refusal until the explicit reconciliation below. A missing
+cache may be recovered through authenticated context.
 
 After verifying the native bridge and input, ordinary lifecycle hooks continue
 without skill payload on typed hosted authentication/refusal/availability failures,
 context timeouts, valid concurrent writers, context CAS conflicts, or required
 session reconciliation. They emit a fixed warning that Skills-dependent actions
 are unavailable; previously loaded instructions are not an authorization fallback.
-The hook does not rewrite a session pin or remove another writer’s lock to bypass these refusals. Explicit `skills
+Apart from the automatic migration above, the hook does not rewrite a session pin or remove another writer’s lock to bypass these refusals. Explicit `skills
 load`, `skills context`, and `skills run` still refuse unavailable or unauthorized
 instructions. Native skill tool guards still deny unmanaged payloads. Invalid
 input/receipts, integrity or authority mismatches, unknown failures, and native
@@ -908,6 +1063,209 @@ 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.
 
+### Claude installer witness CLI (`capture-claude-installer`)
+
+```text
+skills hook capture-claude-installer --request /absolute/request.json --json
+```
+
+Installers obtain Skills-owned witnesses through the configured Skills command
+instead of reimplementing them. Every request is a JSON object of at most
+64 KiB with exactly the keys of one operation: `schema`
+(`skills.claude-installer-capture/v1`), `commandPath` (the normalized absolute
+path of the configured Skills command), `operation`, and that operation's
+inputs. The command checks that `commandPath` resolves to this installed
+`@hasna/skills` CLI and runtime, before and after the operation, and prints
+one receipt on stdout with exit status 0:
+
+```json
+{
+  "schema": "skills.claude-installer-capture-result/v1",
+  "producer": {
+    "schema": "skills.cli-producer-identity/v1",
+    "configuredCommandPath": "<commandPath>",
+    "physicalLauncher": { "path": "<absolute>", "sha256": "<64 hex>" },
+    "runtimeEntry": { "path": "<absolute>", "sha256": "<64 hex>" },
+    "runtime": { "path": "<absolute>", "sha256": "<64 hex>" },
+    "package": { "name": "@hasna/skills", "version": "<x.y.z>", "manifestSha256": "<64 hex>" }
+  },
+  "operation": "<operation>",
+  "result": {}
+}
+```
+
+A refusal prints nothing on stdout, exits 1 and writes one line to stderr,
+`CODE: fixed text`, which never echoes request or file contents. The
+per-file operations (`settings`, `marketplace-registry`,
+`managed-plugin-registry`, `path-bytes`, `discovery-directories`,
+`plugin-manifest` and `candidate`) are described in
+[docs/plugin-admission.md](docs/plugin-admission.md#claude-installer-witness-cli).
+
+#### Verify the stored Claude discovery binding (`discovery-binding`)
+
+`discovery-binding` checks the Claude discovery binding stored in the Skills
+policy (`bridge.discovery.claude` in `agent-policy.json`) with the discovery
+verification the managed prompt hook runs on it: the root alias recheck,
+`verifyAgentDiscovery` and, for an automatic binding, the automatic closure
+check. It then reports every stored witness. An installer calls it once
+instead of re-capturing each stored witness. Per-file capture requires every
+file to exist, so it refuses witnesses that Skills keeps on purpose after
+Claude deletes a retired plugin-cache version; this operation reports those as
+`retained-absent`. It does not check the bridge files, hook commands or
+project-directory settings, which the hook checks separately.
+
+The request has exactly these keys:
+
+```json
+{
+  "schema": "skills.claude-installer-capture/v1",
+  "commandPath": "/home/me/.local/bin/skills",
+  "operation": "discovery-binding",
+  "policyPath": "/home/me/.hasna/skills/agent-policy.json"
+}
+```
+
+`policyPath` must equal `agent-policy.json` in the data directory the installed
+package resolves (`$HASNA_SKILLS_DIR`, default `~/.hasna/skills`), as for the
+`candidate` operation.
+
+The receipt's `result`:
+
+```json
+{
+  "schema": "skills.claude-discovery-binding-verification/v1",
+  "ok": true,
+  "policySha256": "<64 hex>",
+  "discoverySha256": "<64 hex>",
+  "agent": "claude",
+  "method": "reviewed",
+  "rootCount": 2,
+  "sources": [
+    { "index": 0, "path": "/home/me/.claude/settings.json", "hashMode": "claude-settings-v4", "format": null, "sha256": "<64 hex>", "status": "current" },
+    { "index": 3, "path": "/home/me/.claude/plugins/cache/market/plugin/1.0.0/.claude-plugin/plugin.json", "hashMode": "claude-plugin-manifest-v1", "format": null, "sha256": "<64 hex>",
+      "status": "retained-absent", "retention": { "rule": "absent-retired-claude-version", "root": "/home/me/.claude/plugins/cache/market/plugin/1.0.0", "witness": "claude-plugin-manifest-v1" } }
+  ],
+  "directories": [ { "index": 0, "path": "/home/me/.claude/plugins/cache/market/plugin/2.0.0", "status": "current" } ],
+  "failures": []
+}
+```
+
+- `policySha256` is the SHA-256 of the exact policy file bytes that were
+  verified. It is the value a prospective review request passes as
+  `skills.policySha256`. The policy is read again before the result is
+  returned; if it changed, the request is refused.
+- `discoverySha256` is `hashClaudeDiscoveryBinding` of the stored binding, the
+  same digest the `candidate` operation returns.
+- `agent`, `method` (`reviewed` or `automatic`) and `rootCount` (the number of
+  stored discovery roots) come from the stored binding.
+- `sources` has one row per stored source, in stored order. `index` is the
+  position in `bridge.discovery.claude.sources`. `path`, `hashMode`, `format`
+  and `sha256` repeat the stored values: `hashMode` is `null` for a legacy
+  full-file witness without a mode, `format` is `null` unless the source is a
+  field projection (Claude reviews also keep the automatic `json` projection of
+  `settings.json`), and a `null` `sha256` pins absence. `status` is one of:
+  - `current`: the source's own witness reproduces the stored digest now.
+  - `retained-absent`: the file was not read, because the
+    `absent-retired-claude-version` rule keeps its stored digest. The rule
+    holds when the whole version directory `retention.root`
+    (`<...>/.claude/plugins/cache/<marketplace>/<plugin>/<version>`) is absent,
+    the reviewed witnesses of `settings.json` and
+    `plugins/installed_plugins.json` are current, settings enable the plugin
+    and no settings hook names that directory, every registration of the
+    plugin is a valid user or project row for one existing sibling version in
+    the same plugin directory (with a user row among them), no registration of
+    any plugin points into or contains the absent directory, and the sibling's
+    `.claude-plugin/plugin.json` is bound and current. It applies only to
+    reviewed bindings. `retention.witness` names the retained witness class:
+    `bytes` (a full byte witness, `hashMode` `null` or `bytes`),
+    `claude-plugin-manifest-v1` or `claude-plugin-orphaned-at-v1` (the typed
+    presence witness of a version-root `.orphaned_at` marker). No other
+    witness is retained: `path-bytes`, field projections and typed settings
+    or registry witnesses stay checked. Settings and registry files are
+    never retained.
+  - `drift`, with `reason`: `MISSING` (the path is absent and the rule does
+    not retain it), `APPEARED` (the stored witness pins absence and the path
+    now exists), `CHANGED` (the path exists but its witness does not
+    reproduce the stored digest or refuses the current file, for example
+    edited settings or a symlink), `MARKER_INVALID` (a
+    `claude-plugin-orphaned-at-v1` marker exists but is not a valid Claude
+    marker; see below) or `REFUSED` (the path's presence could not be
+    determined).
+- `directories` has one row per stored directory membership witness, with
+  `status` `current`, or `drift` with `reason` `MEMBERSHIP_CHANGED` or
+  `REFUSED`.
+- `failures` lists every drifted source and directory as
+  `{ "kind": "source" | "directory", "index", "path", "reason" }`, followed by
+  `{ "kind": "binding", "reason": "DISCOVERY_REFUSED" }` whenever the hook's
+  own discovery verification refuses the binding. That covers checks no single
+  row shows, such as a changed root alias, a retired directory that reappeared
+  during verification or an invalid witness combination.
+- `ok` is `true` only when `failures` is empty: the hook's verification
+  accepts the binding, every source is `current` or `retained-absent` and
+  every directory is `current`.
+
+`ok: false` is a completed verification and still exits 0, so the caller
+reads which witnesses drifted and why. Installers must require `ok === true`.
+To bind the result, compare each `sources` row (`index`, `path`, `hashMode`,
+`format`, `sha256`) with the binding they read themselves, compare
+`discoverySha256` with the `candidate` capture and `policySha256` with the
+policy bytes they review, and repeat the call immediately before the first
+native change, because the verdict describes one moment.
+
+Claude writes `.orphaned_at` at the root of a plugin-cache version it plans to
+delete (`<...>/.claude/plugins/cache/<marketplace>/<plugin>/<version>/.orphaned_at`),
+rewrites its timestamp at each start, may replace the file, and later deletes
+the marker or the whole version. A fresh Skills discovery review binds such a
+marker as `claude-plugin-orphaned-at-v1`, a witness of its presence only, and
+`discovery-binding` reports it with that witness's own check, exactly as the
+hook does:
+
+- A rewritten timestamp or a replaced file (new inode) is `current`, provided
+  the marker is a regular, non-symlink file owned by the current user whose
+  content is exactly 13 ASCII digits without a leading zero (no byte-order
+  mark, no newline).
+- Any other content, a symlink or another owner is `drift` with
+  `MARKER_INVALID`.
+- A deleted marker whose version directory still exists is `drift` with
+  `MISSING`; the hook refuses this state too.
+- When Claude deletes the whole version directory and the registered sibling
+  version stays bound and current, the marker and every other retainable
+  witness below that directory are `retained-absent` under
+  `absent-retired-claude-version`.
+- A recreated version directory is no longer absent, so each of its witnesses
+  is checked again: a valid marker and an unchanged manifest are `current`,
+  and a missing marker is `drift` with `MISSING`.
+- Marker witnesses stored by an older review as `bytes` or `path-bytes` keep
+  their exact meaning and report `CHANGED` once Claude rewrites the marker,
+  until a fresh discovery review rebinds them as typed witnesses.
+
+Installers must not restore, copy back or rewrite `.orphaned_at` files, or any
+other witness file, to make a binding verify. A restored file has a new inode,
+which a `path-bytes` witness rejects, and it can hide a change Claude made. Act
+on the `discovery-binding` result instead. When it reports drift, the binding
+needs a fresh Skills discovery review (`skills hook install` with fresh
+`--discovery-inputs`), not a file repair.
+
+Refusal codes for this operation, besides the shared request and producer
+codes (`INVALID_REQUEST_FILE`, `INVALID_REQUEST_JSON`, `INVALID_REQUEST`,
+`INVALID_SCHEMA`, `INVALID_REQUEST_FIELDS`, `INVALID_PATH`,
+`PRODUCER_UNVERIFIED`, `PRODUCER_CHANGED` and `CAPTURE_REJECTED`):
+
+- `POLICY_PATH_MISMATCH`: `policyPath` is not the package-owned policy path.
+- `POLICY_UNAVAILABLE`: the policy file is absent.
+- `POLICY_UNREADABLE`: the policy is not a regular, bounded, valid managed
+  policy file.
+- `BINDING_UNAVAILABLE`: the policy stores no Claude discovery binding.
+- `BINDING_INVALID`: the stored binding is not a Claude binding with a
+  `reviewed` or `automatic` method, or its sources, directories or root
+  aliases do not match the binding schema.
+- `POLICY_CHANGED`: the policy changed while it was being verified.
+- `DISCOVERY_BINDING_REJECTED`: any other failure.
+
+The operation is read-only. It reads the policy and the stored witness paths
+and directories. It writes no file, cache, selection pin or policy, and it does
+not start Claude or change native state.
+
 ## Profiles, station sync and rollback
 
 ```bash
@@ -1009,7 +1367,10 @@ hosted publication access.
 `--profile` option chooses an isolated credential file; these are separate
 settings. `HASNA_SKILLS_SELECTION_PROFILE` overrides the installed selection
 profile. A project lock and an existing session keep exact versions until they
-are explicitly changed or a new session starts.
+are explicitly changed or a new session starts. The one exception is the
+managed hook's automatic migration of an expired session pin described above.
+It never applies to a session created from a project lock, and never while a
+lock sits in the prompt's working directory or an ancestor.
 
 ## Executable skills
 
@@ -1367,7 +1728,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills setup-info` | | Version, pinned skills, agent configs, paths |
 | `skills export` | | Export pinned skills as JSON |
 | `skills import <file>` | | Pin skills from a JSON export |
-| `skills config set <key> <value>` | | Set default agent, scope, output format, or API origin |
+| `skills config set <key> <value>` | | Set default agent, scope, output format, or API origin; `sessionPinMigration off --global` keeps managed hooks from migrating refused session pins (global scope only) |
 | `skills config unset <key>` | | Remove a configuration value (`skills config unset apiUrl` clears the stored service address and returns to running on this machine) |
 | `skills new <name>` | `scaffold` | Scaffold a portable skill under `~/.hasna/skills/installed/<name>` |
 | `skills port <path>` | `add` | Import an existing skill folder into the portable standard |
@@ -2746,6 +3107,17 @@ Review the plan before adding `--apply`; the original review preimage must match
 its original mode, and unrelated changes refuse. This preserves the native
 configuration, root aliases, other witnesses and active session pins.
 
+Verifying a typed Codex settings witness from `codex-settings-v1` to
+`codex-settings-v5` also accepts the one write Codex 0.162.1 makes on its own
+first TUI or desktop launch: the boolean `tui.screen_reader_detection_done`
+receipt, added, removed or flipped (V6 already omits it). No digest changes
+meaning, and verification alone records or rebinds nothing. A non-boolean receipt, any other TUI key
+(including the `animations = false` Codex adds when it detects a screen
+reader) and every other change still drift, including Codex's
+`[projects."<dir>"]` trust entries. A planned Skills write to `config.toml`
+rebinds the witness to the written document, which adopts at most that
+receipt.
+
 `claude-settings-v4` is an explicit successor to `claude-settings-v3`. It
 additionally ignores only a top-level `theme` whose value is exactly one of the
 documented built-in values (`auto`, `dark`, `light`, `dark-daltonized`,