@hasna/skills 0.7.3 → 0.8.1

package/README.md

@@ -13,6 +13,21 @@ bun install -g @hasna/skills
 
 Requires [Bun](https://bun.sh/) 1.3+.
 
+## Private skill catalogs
+
+The public package provides the CLI, API, SDK, hooks, and runtime. A skill's
+instructions and executable bundle belong to the organization that publishes
+them. API reads require authentication and use that organization's catalog,
+including tag filters, versions, and downloads. An empty account starts empty;
+neither a repository checkout nor files on the server machine supply defaults.
+Server startup and upgrades never import a bundled catalog.
+
+Each operator can use their own compatible server and storage. S3 is optional:
+the server supports durable SQLite or PostgreSQL and database-backed bundles
+when no S3 bucket is configured. Publishing through an authenticated account
+does not publish to GitHub or npm. Keep private source documents and executable
+payloads outside public software repositories.
+
 ## Quick Start
 
 The fleet authority is `https://api.hasna.com/skills`; versioned requests use
@@ -377,6 +392,20 @@ to be installed in the process. Every way that fetch can fail (SDK absent, vault
 unreachable, item missing or empty) is terminal and exits non-zero; a pointer
 never falls through to another tier, and never to the local corpus.
 
+For a durable reference without a raw Skills key, the same
+`HASNA_SKILLS_API_KEY_REF` field can be stored in the owner-only canonical or
+selected-profile credentials file, alongside its `HASNA_SKILLS_API_URL` and
+`HASNA_SKILLS_BOUND_API_URL`. Do not keep a literal API key in that file too.
+The file retains its existing priority, and the reference remains bound to its
+recorded Skills instance. Secrets needs its own working bootstrap provider;
+this setup does not unlock a Keychain or copy a Secrets bootstrap credential.
+If the file changes during a vault lookup, the request is refused.
+
+An explicit `skills auth login` replaces a stored reference with the newly
+authenticated key. `skills auth logout` removes the app's file reference, not
+the vault item or Secrets' credential. Changing the service URL preserves the
+reference's previous instance binding.
+
 **The service address, in the same shape:**
 
 `HASNA_SKILLS_API_URL` → the Keychain item `hasna.credentials.skills.api-url` →
@@ -421,8 +450,8 @@ as silent aliases one rung below the canonical names, for one release. Use the
   and the bare `skills` listing all exit 1; `skills-mcp` exits 1 at startup
   before answering `initialize` or binding a port, and each MCP data tool
   answers `AUTH_REQUIRED` on its own;
-- the explicit local opt-in → **local**. Skills ships its corpus, so running on
-  this machine is a real mode — but it must be asked for:
+- the explicit local opt-in → **local**, using only owned drafts and the verified
+  local cache. An empty installation has no skills. Opt in with:
   `HASNA_SKILLS_LOCAL=1` (alias `SKILLS_LOCAL=1`). It prints one line saying
   "local mode" on stderr. A configured environment always outranks the opt-in:
   with an authority or credential in the environment, `HASNA_SKILLS_LOCAL` is
@@ -439,7 +468,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 |---|---|
 | `HASNA_SKILLS_API_KEY` | The API key (tier 5 of the ladder). The silent alias `SKILLS_API_KEY` is accepted for one release. |
 | `HASNA_SKILLS_API_URL` | The Skills API origin (HTTPS, or loopback HTTP). The silent alias `SKILLS_API_URL` is accepted for one release. |
-| `HASNA_SKILLS_LOCAL` | Explicit unhosted opt-in: run on this machine against the bundled corpus when no authority is configured. Any non-blank value (`1`). Alias `SKILLS_LOCAL`. Ignored whenever an authority or credential variable IS set. |
+| `HASNA_SKILLS_LOCAL` | Explicit unhosted opt-in: run on this machine against owned drafts and the verified cache when no authority is configured. Any non-blank value (`1`). Alias `SKILLS_LOCAL`. Ignored whenever an authority or credential variable IS set. |
 | `HASNA_SKILLS_API_KEY_OVERRIDE` | Deliberate tier-2 key that outranks every store. |
 | `HASNA_SKILLS_API_KEY_REF` | Deliberate tier-2 vault-item pointer (resolved through `@hasna/secrets`). |
 | `HASNA_PROFILE` | Selects an isolated `credentials-<profile>` file (tier 1). |
@@ -460,7 +489,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills list` | `ls` | List available skills (filter with `-c`, `--pinned`, `-t`, `--brief`) |
 | `skills search <query>` | `s` | Search by name, description, or tags |
 | `skills info <name>` | | Show metadata, env vars, and system dependencies |
-| `skills show <name>` | | Show bundled or portable skill details |
+| `skills show <name>` | | Show account or owned 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 |
@@ -480,7 +509,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `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 |
-| `skills diff <name>` | | Compare pin metadata against the bundled registry |
+| `skills diff <name>` | | Compare pin metadata against the active registry |
 | `skills init` | | Generate `.env.example` and update `.gitignore` for pinned skills |
 | `skills categories` | | List all categories with skill counts |
 | `skills tags` | | List all unique tags with occurrence counts |
@@ -620,11 +649,9 @@ Stable command shapes:
 
 ## Remote Registry
 
-The npm package ships no bundled skill corpus. Discovery reads the local corpus
-cache (`~/.hasna/skills/installed`, filled by `skills pull`) and, when a
-credential resolves, the server's registry. This is not a mode you select:
-whether browse/search commands read a server's registry is one fact, whether a
-credential resolves (see [Credentials](#credentials)). To point at your own
+The npm package ships no skill corpus. Authenticated discovery reads the
+account catalog. Explicit local mode reads owned drafts and verified downloads.
+A failed hosted read never substitutes local content. To point at your own
 instance:
 
 ```bash
@@ -657,6 +684,118 @@ and version-skew contract: `docs/architecture/remote-client-pins-tags-sync.md`.
 For the reusable upstream contract, see
 `docs/architecture/reusable-skills-engine.md`.
 
+### Recurring consent SDK
+
+The SDK exposes `previewRecurringConsent`, `getRecurringDraft`,
+`activateRecurringConsent`, `listRecurringConsents`, `getRecurringConsent`,
+`listRecurringOccurrences` and `revokeRecurringConsent`. These require a server
+that explicitly advertises the version-1 recurring capability; an unavailable
+server raises `RemoteRecurringUnavailableError`. This client does not create
+local schedules or enable a server policy. Use `createRemoteSkillsClient` for the
+existing selected-profile/API binding, or construct `RemoteSkillsClient` with an
+explicit bearer and API URL. Each operation captures that connection and all
+inputs before asynchronous work. An optional final `RemoteWorkspaceContext`
+restricts it to an observed user and membership; profile files are unchanged.
+
+`RecurringRequest` carries explicit cadence, lifetime, runtime limits and credit
+and occurrence ceilings. A preview returns immutable terms, their hash, the
+original quote and approval deadline; its quote states that admission reprices.
+Draft retrieval retains those values even after expiry and never refreshes the
+deadline. Activation requires the original draft ID and `RecurringActivation`:
+`contractVersion: 1`, its exact `acceptedTermsSha256`, the literal acceptance
+`authorize-recurring-credit-use`, and a caller-owned idempotency key. The client
+reads the stored draft before submitting; the server independently requires
+current fresh human authority. Client metadata cannot grant that authority.
+Read operations require `schedules:read`, while preview and revocation require
+`schedules:manage`; API keys cannot activate a grant. Consent read/history/revoke
+preserve tenant-wide control, including retained grants from other deployments.
+
+`RemoteRecurringUnconfirmedError` means a dispatched mutation could have
+committed. Keep its original server/account, inputs, terms hash and request key;
+explicitly reconcile that same identity with current authority. The client never
+retries a POST, creates a replacement key or asserts rollback. After uncertain
+revocation, inspect the original consent and occurrences; revocation does not
+promise cancellation of an already authorized attempt. Exact domain not-found
+responses return `null` only for draft/consent reads. Malformed or oversized
+responses fail closed. Pages accept 1–100 items and an opaque cursor; a large
+terms page can exceed the 64-MiB response bound, so request a smaller page
+explicitly. JSON input is limited to 1 MiB and 64 nesting levels. Dashboard
+approval and server enablement remain separate from these client interfaces.
+
+### Recurring consent from the terminal or MCP
+
+`skills recurring` uses the same hosted SDK methods. Existing `skills schedule`
+commands retain their local metadata and one-shot behavior. A compatible server
+must already support recurring consent; these commands install no server policy,
+daemon or default key scopes. Read/draft/history require `schedules:read`, and
+preview/revocation require `schedules:manage`.
+
+| Command | MCP tool |
+| --- | --- |
+| `recurring preview --request <file>` | `preview_recurring_consent` |
+| `recurring draft <draft-id>` | `get_recurring_draft` |
+| `recurring activate <draft-id>` | `activate_recurring_consent` |
+| `recurring list` / `recurring get <consent-id>` | `list_recurring_consents` / `get_recurring_consent` |
+| `recurring occurrences <consent-id>` | `list_recurring_occurrences` |
+| `recurring revoke <consent-id> --confirm` | `revoke_recurring_consent` |
+| `recurring recover --recovery-dir <original-directory>` | `recover_recurring_consent` |
+| `recurring verification <draft-id> --email <email> --confirm` | `request_recurring_verification` |
+
+Use the CLI's existing `--profile <name>` before the command, or the MCP host's
+explicitly configured connection. Fresh approval needs an enrolled workspace
+profile or both observed `--user-id` and `--membership-id`; those IDs restrict
+current authority. The target, profile and credential are captured before prompts
+and checked again before changes. No operation switches or overwrites saved
+credentials. A normal API-key login alone cannot activate recurring spend.
+Before requesting or verifying a code, the client checks the selected key's
+current account email, trimming whitespace and ignoring case as the server does.
+A different email is refused before the login endpoint can create an account.
+
+The request file contains every explicit `RecurringRequest` field, including
+JSON input/args, runtime and connector limits, cadence/start/expiry/grace, UTC-day
+period, finish-authorized-attempt policy, all three credit ceilings and both
+occurrence ceilings. No policy values are inferred. Preview and draft retrieval
+show the original server terms/hash, quote, first due instants and approval
+deadline. They create no run or credit reservation. Each grant adds its own
+budget; an occurrence reprices within the approved limits.
+
+To activate, provide `--accepted-terms <original-sha256>`,
+`--idempotency-key <original-key>`, `--recovery-dir <new-absolute-directory>`,
+`--email <email>` and `--confirm`. A terminal displays the complete immutable
+draft and requires typing `authorize-recurring-credit-use`, then requests a
+fresh code and reads it masked. For JSON or noninteractive use, also supply
+`--acceptance authorize-recurring-credit-use --code-stdin`; request the code
+first with `recurring verification`. Do not put the code or session in argv.
+Cancellation/EOF does not grant consent. The server independently verifies fresh,
+eligible, non-impersonated human authority and the original terms.
+
+MCP activation takes the same original draft, approval object, recovery directory
+and explicit `confirm: true`, plus account email and a fresh code. The MCP host
+may retain supplied code arguments in its history; the masked terminal flow
+avoids that disclosure. No tool returns or stores the resulting session. A tool
+confirmation boolean or API key never substitutes for verified human approval.
+
+Activation and revocation require a new recovery directory under an existing
+canonical parent. It is created privately and contains the original server,
+profile, account/membership, draft/hash/approval key or consent ID and attempt
+state. It contains no bearer, OTP or raw input payload. Preserve it after errors;
+unknown mutation outcomes exit 2 in the CLI and set MCP `isError` with
+`outcomeUnknown: true`. Read-only `recover` never resubmits. Explicit
+`recover --confirm` reuses the original activation key/terms and fresh approval,
+or the same revoked consent; it never creates a replacement request. An expired
+draft or lost current authority does not resolve an earlier unknown outcome.
+Aliased, replaced, malformed or locked recovery directories refuse changes.
+
+List/history expose one page (1–100 items, default 20) and the unchanged opaque
+cursor. Consent output includes period/total reserved and settled credits,
+admitted counts, ceilings, deployment and next due time; history includes stable
+occurrence/run IDs, outcomes, refusal reasons and allocation state. All hosts
+read the same server identities. Revocation reports residual authorized exposure
+and does not promise cancellation/refund of an already authorized attempt.
+Cancellation is separate. A lost preview response has no draft lookup key:
+report that uncertainty and explicitly choose any new preview, without silently
+turning it into an activation.
+
 ## Portable Skills
 
 Portable skills live under `~/.hasna/skills/installed/<name>/` and follow the
@@ -872,7 +1011,14 @@ const run = await client.submitQuotedRun("blog-article", {}, ["--topic", "Your t
 });
 ```
 
-`submitRun` remains a low-level compatibility transport. New paid integrations
+`submitRun` remains a compatibility transport for servers implementing the legacy
+submission protocol. This OSS server returns HTTP 410 (`LEGACY_EXECUTION_RETIRED`)
+for unversioned submissions and never queues or executes them. Use a selected,
+immutable executable version through `skills run <name>@<version> --target cloud`;
+see [versioned cloud execution](docs/architecture/cloud-execution-runtime.md).
+Historical run reads, logs, artifacts, and cancellation remain available.
+
+On servers that implement paid submission, new integrations
 should use `submitQuotedRun` or `submitQuotedRunWithFiles` so capability and
 approval checks run before submission. Credit counts are integers; `maxCostCents`
 is a legacy spelling for the same credit ceiling. An optional receipt is a
@@ -1002,8 +1148,8 @@ src/
 ├── cli/index.tsx           # Commander.js CLI + Ink TUI
 ├── mcp/index.ts            # MCP server (stdio)
 ├── lib/
-│   ├── registry-data/       # The catalogue entries themselves, one file per category
-│   ├── registry.ts          # Registry API over registry-data: search, categories, tags
+│   ├── registry-data/       # Empty compatibility export; no catalog content
+│   ├── registry.ts          # Discovery over owned cache and explicit sources
 │   ├── installer.ts         # Project pins and disabled source-copy paths
 │   ├── project-state.ts     # .skills/project.json preferences
 │   ├── run-state.ts         # .skills/runs and .skills/exports metadata
@@ -1013,19 +1159,15 @@ src/
 │   └── utils.ts             # normalizeSkillName()
 ├── index.ts                 # Library re-exports (npm package entry)
 └── *.test.ts                # Test files
-
-skills/                      # Public skill contracts and local OSS skills
-├── _common/                 # Shared utilities
-└── */                       # Local skills include src/; server-executed skills expose metadata/contracts
 ```
 
 ### Derived counts
 
 | Count | Value | Derived from |
 |---|---|---|
-| Catalog skills | 86 | `SKILLS.length` (`src/lib/registry-data/`) |
+| Catalog skills | 0 | `SKILLS.length` (`src/lib/registry-data/`) |
 | Categories | 17 | `CATEGORIES` (`src/lib/registry-types.ts`) |
-| MCP tools | 72 | `tools/list` against a live `buildServer()` |
+| MCP tools | 81 | `tools/list` against a live `buildServer()` |
 
 Every number in this table is re-derived from the source tree on each test run by
 `src/lib/readme-derived-counts.test.ts`, so a drifted figure fails a test rather