@hasna/skills 0.6.3 → 0.7.2

package/README.md

@@ -15,37 +15,189 @@ Requires [Bun](https://bun.sh/) 1.3+.
 
 ## Quick Start
 
-Configure a Skills API credential using `skills auth login`. The default authority
-is `https://api.hasna.com/skills`; versioned requests use `/skills/v1`.
-Use `skills setup --api-url https://skills.example.com` for your own server.
+The fleet authority is `https://api.hasna.com/skills`; versioned requests use
+`/skills/v1`. Obtain a workspace API key through your administrator's
+provisioning process and configure it using the [credential resolution](#credentials)
+below. Check the selected identity and
+available capabilities before syncing:
+
+```bash
+skills auth whoami --json
+skills capabilities --json
+```
+
+The default authority is `https://api.hasna.com/skills`; a full `/skills/v1`
+base is also accepted. For your own compatible server, select it with
+`skills setup --api-url https://skills.example.com`, then use `skills auth login`.
+Browser/device-code and email-code login are for compatible deployments; the
+fleet gateway has no interactive login service and does not issue keys that way.
 
 A workspace administrator creates a shared profile selecting published skills by
 exact version and SHA-256 digest. Consumers sync that profile into a verified
-Skills cache, then load instructions through the CLI:
+Skills cache, then load instructions through the CLI. Replace `default` with
+your assigned profile; these examples assume it selects `pdf-generate@0.5.2`:
 
 ```bash
 skills list --json
 skills profiles show default --json
 skills sync --selection-profile default --json
-skills load release-notes
-skills context 'Prepare release notes' --json
+skills install pdf-generate@0.5.2 --selection-profile default --json
+skills load pdf-generate@0.5.2 --selection-profile default
+skills context 'Use $pdf-generate to create a PDF' --selection-profile default --json
 
-# Preview agent configuration, then install hooks with recoverable backups.
+# Preview retirement, then archive ordinary copies and vendor discovery files.
+skills migrate native --include-unmanaged --include-vendor --json
+skills migrate native --include-unmanaged --include-vendor --apply --json
+
+# Preview the available adapters, then install one bridge plus hooks per agent.
+skills hook agents --json
 skills hook install --agent all --selection-profile default --json
 skills hook install --agent all --selection-profile default --apply --json
-
-# Inventory native copies, then archive managed copies outside agent discovery.
-skills migrate native --json
-skills migrate native --apply --json
 ```
 
-Hook installation enables CLI loading on the station, denies Claude's native
-Skill tool, and disables discovered Codex native skills. It preserves unrelated
-hooks and configuration. Use `--include-vendor` to include Codex system and
-cached plugin skills. Project-local skills require a project discovery audit. Native
-exports are refused while this policy is active. Archives preserve full skill
-directories; `--include-unmanaged` explicitly includes user-authored copies.
-Archive receipts and configuration backups live under the Skills data directory.
+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
+restart the native client to load its current commands. Explicit `skills load`,
+`skills context`, and `skills sync` commands can still select other profiles.
+
+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
+discovery files.
+
+Restart the agent after applying the hooks. In Codex, review and grant normal
+trust to the installed hook definitions before starting a new session. Then
+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.
+
+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
+bridge bytes, required native configuration, and discovered home/project skill
+paths before loading context. A missing or changed bridge, newly discovered
+copy, stale plugin registration, or incomplete scan reports repair guidance and
+refuses loading. Most adapters also block the prompt; Hermes has the native
+non-blocking prompt-hook limitation described below. These are checks on configured native discovery, not
+an operating-system restriction on arbitrary file reads.
+
+Agent policies support up to 1 MiB of serialized UTF-8 JSON, with bounded agent
+and discovery collections (2,048 sources and 512 roots per agent). Installation
+validates the complete resulting policy before writing configuration or backups;
+the same limits apply when reading and guarding native context. A rejected plan
+leaves the previous policy intact.
+
+Hermes 0.20.5 uses `pre_llm_call` to add selected context and `pre_tool_call`
+with `fail_closed: true` and a small owned supervisor to guard tool calls. The
+supervisor maps Skills child failures, timeouts and missing/invalid directives
+to the native explicit block response and exit code 2. Installation edits `config.yaml`
+while preserving unrelated values/comments and creates the native
+`.no-bundled-skills` opt-out marker to prevent bundled payloads from reappearing.
+The supervisor stays in the Skills data directory and its bytes/command are
+checked before native loading. Installation leaves the native shell-hook
+allowlist unchanged: approve the two exact
+managed event/command pairs through Hermes normal hook trust and restart.
+The adapter refuses unreviewed installed plugin sources and custom Hermes
+homes/profiles, user-specific tilde expansion, and `TERMINAL_CWD` overrides.
+Nonempty `HERMES_BUNDLED_PLUGINS` and `HERMES_BUNDLED_SKILLS` overrides are
+also refused during discovery and hook checks; unset them to use the reviewed
+default source paths. Custom bundle locations need a dedicated discovery adapter.
+Retire native payloads before use. Legacy `skills-cli.md` files can shadow the
+bridge and must also be preserved and retired before proceeding. Only `skill_view(name:
+"skills-cli")` is allowed natively; author payloads with Skills CLI commands.
+Hermes itself fails open on `pre_llm_call` errors. A returned refusal is visible
+context, and the trusted pre-tool guard blocks drift and native skill fallback;
+this is not a claim that Hermes can prevent every model call after a failed
+prompt hook or guarantee refusal if the native host/supervisor itself dies. Arbitrary project/plugin paths still require a discovery audit.
+
+Reviewed discovery can also bind `directories: [{ path, sha256 }]` alongside
+its full source-file hashes. The public SDK's `captureDiscoveryDirectories(paths)`
+captures recursive, sorted path/type membership without reading plugin payloads.
+Include every directory the reviewed loader scans, including plugin version
+selection parents and Python entrypoint discovery directories. Membership hashes
+detect added, removed or changed file types; keep source hashes for reviewed bytes.
+Missing directories bind as `sha256: null`. Symlinks and special nodes refuse.
+The bounds are 64 roots, 20,000 total entries, 8 MiB of path/type metadata and
+64 levels of recursion. Capture and checks require stable directory identities;
+quiesce source writers for installation because these checks are not atomic with
+a later native import.
+
+For full binary or source-byte coverage, use the public SDK's
+`captureDiscoveryByteSources(paths)` and retain its explicit `hashMode: "bytes"`
+on each source witness. It hashes the exact file bytes, including invalid UTF-8,
+with limits of 64 MiB per file and 256 MiB across one capture or verification.
+Missing files bind as `sha256: null`; symlinks, special files and changing file
+identities refuse. Raw witnesses cannot use configuration field projections.
+Existing witnesses without `hashMode` retain their original UTF-8 decoding
+contract and 16 MiB file limit; they are not silently converted into byte hashes.
+Directory membership and file bytes are separate witnesses. Neither substitutes
+for reviewing the actual executable, import paths or loader behavior.
+
+Hermes requires directory witnesses, including when upgrading an older policy.
+For an automatic bridge with no runtime installed, rerun normal `skills hook install`
+to review and apply the new bindings. Existing native trust is preserved.
+Reviewed Hermes installations need fresh source and directory coverage in their
+`--discovery-inputs` file. Other agents may add directory witnesses to their
+reviewed bindings without changing existing source-only reviews.
+
+Hook installation preserves unrelated configuration, hooks, and plugin assets.
+It disables discovered Codex native skills; exact system-skill trees can remain
+only with their hash-bound disabled paths; migration preserves these package files. A client that restores or changes
+packaged skills requires a fresh inventory and disable plan. Native exports are
+refused while managed CLI loading is active. Migration preserves ordinary skill
+directories in private archives; `--include-unmanaged` includes user-authored
+copies, and `--include-vendor` retires vendor `SKILL.md` discovery files while
+preserving shared scripts and assets. Archive receipts and configuration backups
+live under the Skills data directory.
+
+After vendor documents are archived, inventory still scans their retained asset
+directories for newly introduced skills. Vendor container traversal allows 32
+directory levels; the ordinary native-root limit remains unchanged. Each inventory
+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.
+
+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
+completion. Interrupted operations can be inspected against that durable intent.
+On failure, recovery restores verified archives only when the original path is
+still absent. It preserves occupied paths or unverified archives, records that
+they require recovery, and continues compensating other unchanged entries.
+Keep native agents and other skill writers stopped throughout migration and
+recovery: portable directory rename cannot atomically reserve an absent target.
+Vendor file restoration uses an exclusive hard link to preserve concurrent files.
+Do not retry an interrupted operation until its journal and both paths have been
+reconciled; a failed final journal write may leave the earlier durable intent.
+
+`skills hook agents --json` reports the supported adapters and coverage limits.
+Claude and Codex have lifecycle context hooks; Gemini uses `BeforeAgent`, and
+OpenCode uses its awaited message plugin. Cursor receives selected context at
+session start and gates later prompt submission; its prompt hook does not
+inject context on the supported installed path. Other inventoried clients do
+not automatically gain a working prompt adapter.
+
+Gemini's `BeforeAgent` prompt can include the Skills policy emitted at session
+start. The hook excludes that exact leading policy from skill selection, so it
+does not displace the user's requested skill. Other hook context and user text
+remain part of the selection input.
+
+Known local plugin registrations are resolved automatically. Plugins with
+instruction-injecting hooks, unresolved runtime registrations, unsupported
+legacy command formats, and higher-precedence project discovery settings need
+separate review; a cache-only scan does not establish complete coverage. The
+advanced `--discovery-inputs <file>` option on hook installation and migration
+accepts reviewed active roots and full source-file SHA-256 witnesses. Its
+version-1 document has an `agents` array; each entry names `agent`, absolute
+`roots`, `sources` (`path` and `sha256`, or `null` for an absent file), and
+`pluginHooks: "reviewed-no-skill-injection"`. Include the agent configuration
+and every input establishing the active roots and plugin-hook behavior. A
+changed witness requires a new review. This option does not add support for an
+unknown native file format or make unreviewed plugin behavior safe. Managed
+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.
 
 If your home `.claude` or `.codex` directory intentionally links to another
 directory within your home, add `--allow-root-aliases` to hook installation and
@@ -80,9 +232,49 @@ skills sync --selection-profile default --check --json
 skills station-state station-example --json
 ```
 
+With `--selection-profile`, `sync --check` checks the selected profile and cache
+without writing, and exits nonzero on drift. `sync --station` records a receipt
+for the named station; it is not a native-folder snapshot in this mode.
+`skills install --selection-profile default` without skill names also syncs the
+whole selection.
+
+After hook installation has enabled CLI loading, pull operations obey the same
+profile. `--all` refreshes its selected versions rather than the full catalog,
+and a named pull must belong to that profile:
+
+```bash
+skills pull --all --selection-profile default --json
+skills pull pdf-generate@0.5.2 --selection-profile default --json
+```
+
+Use `sync --selection-profile default --station station-example` when you also
+need a station receipt. Native-folder migration options belong to the older
+sync mode and cannot be mixed with profile sync.
+
 Selection documents contain a `selections` array. Each entry has `slug`,
 `version`, `bundleDigest` (`sha256:` followed by 64 lowercase hex characters),
-and optional `triggers` containing `keywords`, `paths`, or `always`. Profile
+and optional `triggers` containing `keywords`, `paths`, or `always`. An optional
+`aliases` array gives a selection up to 32 reviewed kebab-case alternate names.
+Aliases cannot duplicate another alias or any canonical name in the profile.
+They resolve directly to that selection's exact version and digest in `load`,
+managed `run`/`pull`, and explicit prompt references such as `$old-name`.
+Receipts and bundle requests retain the canonical name. Aliases are scoped to
+the authority, workspace and profile revision; project/session locks preserve
+their pinned aliases. They do not create global registry entries or native
+redirect skills. Saving aliases requires an API advertising `selectionAliases`.
+Profiles support up to 4,096 exact selections. API responses and local profile,
+project and session documents share an 8 MiB UTF-8 JSON limit. Resolved profiles
+reserve space within that limit for all session-loaded keys; the API refuses an
+oversized candidate before replacing the existing profile. Saved snapshots and
+owned cache receipts use compact JSON; existing formatted receipts remain readable.
+The authenticated capabilities response advertises `profileLimits`, including
+`maxSelections`, `maxDocumentBytes`, `maxResolvedProfileBytes` and the effective
+`requestBodyLimitBytes`. Larger writes require these advertised limits. Operators
+can set `HASNA_SKILLS_REQUEST_BODY_LIMIT_BYTES=8388608` to admit larger requests;
+the default remains 1,000,000 bytes and a lower configured limit still applies.
+These limits apply to configured memory, SQLite and PostgreSQL stores;
+profile sync does not require S3 or native skill copies.
+Profile
 writes use compare-and-swap revisions. Station receipts belong to the workspace,
 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
@@ -97,11 +289,21 @@ are explicitly changed or a new session starts.
 ## Executable skills
 
 ```bash
-skills run --target cloud --input '{"title":"Example","content":"Hello"}' pdf-generate@0.5.2
-skills executions status RUN_ID --json
+skills capabilities --json
+skills run --target cloud --selection-profile default \
+  --input '{"title":"Example","content":"Hello"}' \
+  --idempotency-key YOUR_UNIQUE_JOB_KEY --wait --json pdf-generate@0.5.2
+skills executions show RUN_ID --json
+skills executions logs RUN_ID --json
+skills executions artifacts RUN_ID --json
 skills executions download RUN_ID document.pdf --output ./document.pdf
 ```
 
+Use a new idempotency key for each new job and retain it with the exact input.
+If a response is lost or polling times out, reconcile the existing execution
+before submitting again. The selected profile must include this exact version,
+and the consumer needs `runs:write` as well as `skills:read`.
+
 Cloud execution is enabled only when the deployment configures a reviewed image
 and exact bundle allowlist. The first supported lane is `pdf-generate`; arbitrary
 uploaded code is not admitted. Runs capture version, bundle digest, input digest,
@@ -240,7 +442,20 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills show <name>` | | Show bundled or portable skill details |
 | `skills docs <name>` | | Show documentation (SKILL.md > README.md > CLAUDE.md) |
 | `skills requires <name>` | | Show env vars, system deps, and npm dependencies |
+| `skills profiles show <id>` / `skills profiles set <id> --file <json>` | | Read an exact shared selection or update it with writer authorization |
+| `skills install [name@version] --selection-profile <id>` | | Cache selected immutable bundles; without names, sync the profile |
+| `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 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 |
+| `skills sync --selection-profile <id> [--check] [--station <id>]` | | Sync or check the selected profile/cache; optionally record station state |
+| `skills station-state <id>` | | Read a station's sync receipt in the authenticated workspace |
 | `skills run <name> [args]` | | Execute a skill directly |
+| `skills run --target cloud --selection-profile <id> <name@version>` | | Submit an explicitly selected cloud execution |
+| `skills executions show <id>` / `logs <id>` / `artifacts <id>` | | Inspect a cloud execution and its output |
+| `skills executions download <id> <artifact> --output <path>` | | Download and verify one cloud execution artifact |
 | `skills runs status <run-id>` | | Poll a remote skill run |
 | `skills exports download <run-id>` | | Download completed remote artifacts |
 | `skills update` | | Refresh project pin metadata |
@@ -266,10 +481,11 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `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 |
 | `skills create <name>` | | Scaffold a new custom skill directory |
+| `skills prepare <name> --version <semver>` | | Validate an edited draft and update only its manifest version/hash; `--dry-run` previews, `--kind` resolves legacy manifests without an explicit kind |
 | `skills sync --to claude` | | Disabled by design; use `skills mcp --register <agent|all>` |
 | `skills sync --from claude` | | Disabled by design; agent skill folders are not used |
-| `skills sync [names...] --check --for <agent> --source <path>` | `render` | Read-only drift census for the selected corpus, skills and agent; explicit source overrides `SKILLS_SOURCE`, then the installed cache. Unknown selections or drift exit nonzero. Without selectors, check all existing agent homes. |
-| `skills sync --station <id>` | | Per-station snapshot mode: snapshot the installed skill homes into `resources/<station>/skills` with a v3 sync-manifest (dry-run by default; `--populate` writes) |
+| `skills sync [names...] --check --for <agent> --source <path>` | `render` | Legacy native-folder mode only, without CLI loading or a selection profile: check the selected corpus and agent homes without writing. Unknown selections or drift exit nonzero. |
+| `skills sync --station <id>` | | Without CLI loading or a selection profile, legacy snapshot mode writes a v3 sync-manifest under `resources/<station>/skills` only with `--populate`; use explicit `--selection-profile` for API station receipts |
 | `skills hydrate --station <id>` | | Restore the canonical corpus cache from a reviewed per-station snapshot (dry-run by default; `--apply` writes) |
 | `skills validate <name>` | | Check a skill's directory structure |
 | `skills schedule add <skill> <cron>` | | Set up recurring skill execution |