@hasna/skills 0.5.4 → 0.5.5

package/README.md

@@ -120,6 +120,20 @@ credential has resolved, so an install with no credential names no host at all.
 `skills setup --api-url <origin>` writes the credentials file; the address is
 per-user, never per-project.
 
+The internal gateway resource contract is `/skills/v1/...`; commercial and custom
+instances retain their `/api/v1/...` routes. A full gateway `/skills/v1` base is
+accepted and normalizes to the same credential-bound instance. Select a
+customer-owned instance explicitly with `HASNA_SKILLS_API_URL=https://skills.example` and
+its own profile/credential; configuring one instance does not select the other.
+The OSS server accepts `/v1/...` aliases through the same handlers as its
+`/api/v1/...` routes, plus `/v1/auth/whoami` for existing API-key identity and
+`/v1/health` for liveness. Gateway integration is incomplete until the internal
+origin runs this version and passes authenticated live acceptance. Login and
+device authorization still use `/api/auth/...` on standalone instances; the
+internal gateway has no interactive login service, so these operations stop
+before transmitting account input or credentials. This is an explicit readiness gap, not support for
+logging into the internal service through the commercial account.
+
 The unprefixed `SKILLS_API_KEY` and `SKILLS_API_URL` spellings are still accepted
 as silent aliases one rung below the canonical names, for one release. Use the
 `HASNA_`-prefixed names. `SKILL_API_KEY` (singular) is no longer read at all.
@@ -484,17 +498,58 @@ switch instances. `HASNA_HOME` / `HASNA_CONFIG_HOME` isolate credential state;
 `HASNA_SKILLS_DIR` separately isolates corpus/configuration data. They do not
 require changing `HOME`.
 
+Private source publication uses a separate hosted contract advertised by
+`capabilities.privatePublishing`. It requires fresh email verification, an
+existing private/team skill UUID, and an explicit comparison with the observed
+current version UUID (or `--expect-empty`). Request a code with `auth signup`
+first, then enter it over stdin; do not put verification codes in shell history.
+
+```sh
+skills --profile customer publication publish ./my-skill \
+  --skill-id <skill-uuid> --expect-empty --recovery-dir "$PWD/publication-receipt" \
+  --email you@example.com --code-stdin --confirm --json
+skills --profile customer publication status --recovery-dir "$PWD/publication-receipt" \
+  --email you@example.com --code-stdin --json
+```
+
+Without an enrolled named profile, also supply the observed `--user-id` and
+`--membership-id`. `publication resume` and `publication cancel` use the same
+recovery directory, fresh verification, and `--confirm`. The directory must be
+new for `publish`, have a canonical absolute parent path, and contain no symbolic
+links. It keeps immutable archive bytes and a generated idempotency key before
+the first publication request. Preserve it after interruption: resume reconciles
+the same declaration, and an uncertain upload is never sent twice. If a process
+crashes while holding `operation.lock`, confirm it has stopped before removing
+that lock explicitly. Status and cancellation remain available when new
+publishing is disabled. Exit 2 means publication is still pending; `committed`
+means source was published. Private execution remains unavailable.
+
+The SDK exports `RemotePrivatePublicationsClient` through both the root and
+`./sdk`; `RemoteSkillsAuthClient.openPrivatePublications` creates one from fresh
+workspace verification. The shared `preparePrivatePublication`,
+`continuePrivatePublication`, `inspectPrivatePublication`, and
+`readPrivatePublicationRecovery` functions implement the same durable workflow.
+MCP exposes `publish_private_skill`, `get_private_publication`,
+`resume_private_publication`, and `cancel_private_publication` with equivalent
+explicit authority and consent. Recovery directories are local to the MCP host;
+request history may retain supplied verification codes. Tokens and signed upload
+URLs are never returned or written to the recovery directory.
+
 A paid remote run requires explicit approval. Interactive runs ask before
 submission; JSON and other noninteractive runs require `--yes`. The approved
 quote becomes the server-enforced credit ceiling. A changed price above that
-ceiling fails before admission. A compatible server must advertise bounded
+ceiling fails before admission. When the server returns `quoteReceipt`, the
+client preserves that opaque value from the approved quote without obtaining a
+replacement. The server checks its version, request and expiry binding; a refusal
+stops the submission. A compatible server must advertise bounded
 approval; older or unsupported APIs return errors, not local results. Reuse the
 same idempotency key only for an identical submission to safely recover an
 interrupted response. `runs cancel` and `runs resume` call the server's lifecycle
 operations and can be refused when the current state does not allow them.
 
-`run --remote --file input.txt ...` declares upload hashes before admission and
-uploads bytes without forwarding the account key to storage. Failed uploads
+`run --remote --file input.txt ...` quotes the owned files' names, sizes, SHA-256
+hashes and content types before approval, declares those same descriptors at
+admission, and uploads the original bytes without forwarding the account key to storage. Failed uploads
 request cancellation. Upload support must be advertised by the server.
 Downloads verify authenticated size and SHA-256 metadata before writing files;
 existing files and unsafe paths are refused. CLI/SDK downloads are bounded to
@@ -505,9 +560,11 @@ commands return external links; payment confirmation remains in the browser.
 The MCP server uses the same account, quote, run and artifact client. Agent
 hosts must launch `skills-mcp --stdio`; the standalone default is loopback HTTP.
 Configure its environment with the selected `HASNA_PROFILE` and isolated state
-paths. `run_skill` accepts `remote:true`, `maxCredits`, `idempotency_key`, and
+paths. `run_skill` accepts `remote:true`, `maxCredits`, `quoteReceipt`, `idempotency_key`, and
 optional inline `files:[{name,base64,contentType}]`. An omitted ceiling permits
-only free execution. `quote_skill` never submits a run.
+only free execution. `quote_skill` accepts the same input, args and inline files
+and never submits a run. After approval, pass its receipt unchanged to `run_skill`
+with those same values; do not automatically re-quote after a refusal.
 
 ```ts
 import { RemoteSkillsAuthClient, createRemoteSkillsClient } from "@hasna/skills/sdk";
@@ -524,6 +581,7 @@ const quote = await client.quoteRun("blog-article", {}, ["--topic", "Your topic"
 // Obtain explicit user approval of quote.pricing.costCents before this call.
 const run = await client.submitQuotedRun("blog-article", {}, ["--topic", "Your topic"], {
   maxCredits: quote.pricing.costCents,
+  quoteReceipt: quote.quoteReceipt,
   idempotencyKey: "article-001",
 });
 ```
@@ -531,7 +589,14 @@ const run = await client.submitQuotedRun("blog-article", {}, ["--topic", "Your t
 `submitRun` remains a low-level compatibility transport. New paid 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. Missing billing capabilities
+is a legacy spelling for the same credit ceiling. An optional receipt is a
+nonempty opaque string of at most 4,096 UTF-8 bytes, preserved without normalization.
+`quoteRun` accepts optional file descriptors as its fourth argument; each descriptor
+contains `name`, `sizeBytes`, `sha256`, and `contentType` and must match the later
+submission. `submitQuotedRunWithFiles` captures owned bytes and derives these
+descriptors before its asynchronous calls. Explicit receipts are never replaced;
+without one, it requests a quote and carries the returned receipt into admission.
+Missing billing capabilities
 on an internal instance are explicit unsupported responses; this package does
 not add a billing engine to the OSS server.
 
@@ -674,7 +739,7 @@ skills/                      # Public skill contracts and local OSS skills
 |---|---|---|
 | Catalog skills | 86 | `SKILLS.length` (`src/lib/registry-data/`) |
 | Categories | 17 | `CATEGORIES` (`src/lib/registry-types.ts`) |
-| MCP tools | 68 | `tools/list` against a live `buildServer()` |
+| MCP tools | 72 | `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