@hasna/skills 0.3.0 → 0.5.0

package/README.md

@@ -11,7 +11,7 @@ Skills library for AI coding agents — discover, pin, and run reusable capabili
 bun install -g @hasna/skills
 ```
 
-Requires [Bun](https://bun.sh/) 1.0+.
+Requires [Bun](https://bun.sh/) 1.3+.
 
 ## Quick Start
 
@@ -124,7 +124,7 @@ The unprefixed `SKILLS_API_KEY` and `SKILLS_API_URL` spellings are still accepte
 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.
 
-**Three outcomes, and no fourth:**
+**Fail closed, and the local run is a deliberate choice:**
 
 - a credential resolves → **hosted**, against the configured URL or the gateway.
   A credential that resolves but cannot produce a usable key — a deliberate
@@ -133,14 +133,39 @@ as silent aliases one rung below the canonical names, for one release. Use the
 - no credential but a URL is configured → **loud failure**, exit non-zero. There
   is no local fallback: answering from the bundled corpus while authentication is
   unconfigured is a false green;
-- neither → **local**. Skills ships its corpus, so running on this machine is a
-  real mode; it prints one line on stderr saying so.
+- neither a credential nor a URL, and no opt-in → **loud failure**, exit
+  non-zero. Running on this machine is no longer the silence that follows a
+  missing credential: an unconfigured install fails closed, opening no local
+  database and emitting no local-fallback event, and the error names the way
+  out and where the credential should live. This holds on every data surface:
+  `list`, `search`, `categories`, `tags`, `info`, `show`, `docs`, `requires`
+  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:
+  `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
+  ignored and the run goes (or fails) hosted.
 
 The retired locations are not read: `auth.json` (in either the app directory or
 the legacy `~/.skills/`), the old fleet-env and per-machine cloud env folders
 under `~/.hasna`, and the XDG config directory. `~/.hasna` is a closed namespace
 of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 
+### Routing environment variables
+
+| Variable | Meaning |
+|---|---|
+| `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_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). |
+| `HASNA_STATION` | The Keychain account for tier 3; falls back to `hostname -s`, then `$USER`. |
+
 ## CLI Commands
 
 | Command | Alias | Description |
@@ -151,7 +176,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills unpin <name>` | | Remove a project pin |
 | `skills pins list` | | List pinned skills |
 | `skills setup --api-url <url>` | | Point the CLI at a Skills API origin for remote runs |
-| `skills setup` | | Show whether an API origin is configured; with none, skills run on this machine |
+| `skills setup` | | Show whether an API origin is configured; with none, running on this machine requires `HASNA_SKILLS_LOCAL=1` |
 | `skills setup agents` | | Register the Skills MCP server with all supported agents |
 | `skills list` | `ls` | List available skills (filter with `-c`, `--pinned`, `-t`, `--brief`) |
 | `skills search <query>` | `s` | Search by name, description, or tags |
@@ -168,6 +193,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills categories` | | List all categories with skill counts |
 | `skills tags` | | List all unique tags with occurrence counts |
 | `skills doctor` | | Check env vars, system deps, and pinned skill health |
+| `skills env-check [name]` | `check-env` | Show required environment variables; `--set KEY=VALUE` updates the project's `.env` |
 | `skills test [name]` | | Test skill readiness (env, system, npm deps) |
 | `skills outdated` | | Compare pinned vs registry versions |
 | `skills auth login --api-key <key>` | | Verify and store a Skills API key |
@@ -175,7 +201,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills billing status` | | Show server account plan and balance |
 | `skills billing checkout` | | Create a checkout session when billing is enabled |
 | `skills billing portal` | | Create a customer portal session when billing is enabled |
-| `skills credits buy <amount>` | | Create a credit-pack checkout session when billing is enabled |
+| `skills credits buy <pack-id>` | | Create a credit-pack checkout session when billing is enabled |
 | `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 |
@@ -186,6 +212,7 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills create <name>` | | Scaffold a new custom skill directory |
 | `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 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 |
@@ -198,6 +225,30 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `skills self-update` | | Update this package to the latest version |
 | `skills completion <shell>` | | Generate shell completions (bash, zsh, fish) |
 
+`self-update` asks the same Bun executable for its global bin directory after a
+successful installation. It reports success only when the `skills` command on
+your PATH resolves to that installed command and exits successfully with one
+semantic version. If discovery or verification fails, it exits nonzero and
+explains that installation may already have completed. It does not automatically
+reinstall or change your PATH.
+
+### Local environment assignments
+
+`skills env-check --set 'KEY=value'` writes one literal value to the current
+project's `.env`. Keys must match `[A-Za-z_][A-Za-z0-9_]*`. Empty values and `=`
+within a value are supported; output confirms the key and path without printing
+the value. Quote the shell argument when it contains shell metacharacters.
+
+The writer preserves unrelated lines, comments, line endings and existing file
+permissions. New files use mode `0600`. Symlinks and special files are rejected.
+Values containing control characters, newlines, all three quote delimiters, an
+odd trailing backslash, a backslash immediately before a final dollar, or a
+backslash together with both a single quote and a backtick are rejected because
+literal Bun dotenv serialization is not supported
+for those cases. Multiline or ambiguous existing assignments also
+require manual editing; refusal leaves the file unchanged. Literal round trips
+are tested with Bun 1.3.14 and 1.4.0.
+
 ### Common Options
 
 - `--json` — Output as JSON (pipeable)
@@ -255,6 +306,19 @@ Stable command shapes:
   served by the API and never ships in this package.
 - Config and schedules: `config * --json` and `schedule * --json` return
   machine-readable status objects.
+  `schedule run` exits 1 if any item fails, in human and JSON output. JSON
+  `results[].attempted` identifies items handed to the local executor; `ran`
+  counts those attempts, including failures. Missing skills, routing refusals,
+  and unsupported hosted scheduling leave that occurrence due and its history
+  unchanged. Local attempts record success/error and advance the schedule.
+  If history cannot be saved, the item reports `executionStatus` and
+  `historyError`; inspect its effects before retrying. Other due items still run.
+  No-due and `--dry-run` remain successful without consuming occurrences.
+  With `schedule run --json`, child stdout and stderr stream to stderr while
+  stdout contains only the command's JSON result. Human-mode child output is
+  unchanged. Programmatic `runSkill` callers can select `stdio: "stderr"` to
+  stream both child output channels to stderr without buffering; the existing
+  default/inherit and pipe modes retain their behavior.
 - Storage: `storage status --json` returns local `.skills` paths and optional
   repo-native remote readiness; `storage sync-plan --json` returns a no-network
   snapshot plan.
@@ -314,6 +378,16 @@ skills show my-skill
 skills port ./existing-skill
 ```
 
+New and imported local skill names use hyphens: `MyHTTPTool` becomes
+`my-http-tool`, and `my_tool.v2` becomes `my-tool-v2`. Existing installed names
+and declared command names remain readable without renaming. Already joined
+lowercase words are not split automatically; supply `--name my-skill` when importing.
+An import updates name declarations in its copied files; original source files stay unchanged.
+
+Single-folder `port` / `add` reports validation after importing. If validation
+fails, both human and JSON output exit with status 1; the imported folder remains
+available for correction. Check `valid` and `issues` in JSON before using it.
+
 The scaffold includes `SKILL.md`, `skill.json`, `AGENTS.md`, `package.json`,
 `tsconfig.json`, and `src/index.ts`. `AGENTS.md` is written for coding agents:
 after `skills new my-skill`, an agent can open that file, implement the skill,
@@ -366,16 +440,100 @@ skills mcp --register all       # Register with all supported agents
 
 ## Skills API
 
+Use a named profile for each independently operated instance. A commercial Skills instance
+and an internal instance have separate credentials, accounts,
+credits and data. Selecting one does not change another profile or the fleet
+resolver's existing defaults.
+
 ```bash
-skills setup --api-url https://skills.example.com   # only for your own instance
-skills auth login --api-key "$HASNA_SKILLS_API_KEY"
-skills billing status
+# Configure the commercial instance before signing in.
+skills --profile customer setup --api-url https://skills.example.com/api/v1 --json
+skills --profile customer auth signup --email you@example.com --json
+skills --profile customer auth login --email you@example.com --code <CODE> --json
+skills --profile customer auth whoami --json
+skills --profile customer capabilities --json
+skills --profile customer list --remote --json
+
+# Quote without spending. Put CLI flags before the skill name.
+skills --profile customer quote --json blog-article --topic "Your topic"
+skills --profile customer run --remote --yes --wait --json --idempotency-key article-001 blog-article --topic "Your topic"
+skills --profile customer runs status <run-id> --json
+skills --profile customer runs logs <run-id> --json
+skills --profile customer runs artifacts <run-id> --json
+skills --profile customer exports download <run-id> --json
+
+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 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).
+skills --profile customer auth signup --email you@example.com --json
+skills --profile customer auth keys create automation --email you@example.com --code <CODE> --scope runs:read --json
+skills --profile customer auth logout --json
 ```
 
-Account, run, log, artifact, and optional billing commands use the configured
-Skills API. The public package stores only local configuration
-and CLI credentials. Artifacts can be stored in S3 when `HASNA_SKILLS_S3_BUCKET`
-is configured.
+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
+override, not permission to send a saved key to a different instance. Stored
+keys retain their original instance binding; sign in to a separate profile to
+switch instances. `HASNA_HOME` / `HASNA_CONFIG_HOME` isolate credential state;
+`HASNA_SKILLS_DIR` separately isolates corpus/configuration data. They do not
+require changing `HOME`.
+
+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
+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
+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
+64 MiB; MCP inline artifacts and input files are limited to 1 MiB. Listing, creating and revoking API keys require fresh email OTP reauthentication; an existing
+API key cannot grant new key authority. Checkout
+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
+optional inline `files:[{name,base64,contentType}]`. An omitted ceiling permits
+only free execution. `quote_skill` never submits a run.
+
+```ts
+import { RemoteSkillsAuthClient, createRemoteSkillsClient } from "@hasna/skills/sdk";
+
+// Auth transports never write credentials; the embedding application owns storage.
+const auth = new RemoteSkillsAuthClient("https://skills.example.com/api/v1");
+await auth.requestCode("you@example.com");
+// await auth.verifyCode("you@example.com", code);
+
+// Uses the same selected profile and credential binding as CLI/MCP.
+const client = await createRemoteSkillsClient(process.env);
+if (!client) throw new Error("Configure an instance and sign in first");
+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,
+  idempotencyKey: "article-001",
+});
+```
+
+`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
+on an internal instance are explicit unsupported responses; this package does
+not add a billing engine to the OSS server.
 
 ### Server database
 
@@ -516,7 +674,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 | 37 | `tools/list` against a live `buildServer()` |
+| MCP tools | 61 | `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
@@ -634,3 +792,100 @@ hand.
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE)
+
+### Account and workspace names on a compatible server
+
+`skills account update --display-name "Ana" --email you@example.com` and
+`skills workspace update --name "Studio" --email you@example.com` request a
+fresh verification email and prompt for the code without showing its digits.
+The current API selection still determines the server. These commands require
+that server to support the additive customer-name routes; they do not enable
+membership, billing or operator administration.
+
+For automation, first request a fresh code through `skills auth login --email you@example.com --json`,
+then pipe the code from your secure input source to the same command with
+`--code-stdin --json`. Do not put verification codes in command arguments or
+shell history. JSON/noninteractive updates require `--code-stdin`. Cancelling
+an interactive prompt exits with status130 before verification.
+
+`RemoteSkillsAuthClient.updateProfile(email, code, { displayName })` and
+`updateCurrentWorkspace(email, code, { name })` use a fresh session without
+replacing saved API keys or profile selection. `RemoteSkillsClient` exposes the
+same name operations for an explicitly supplied interactive session. Servers
+retain the final permission checks; ordinary API keys may be refused. MCP tools
+`update_account_profile` and `update_workspace_name` accept a name, email and
+fresh verification code, and return only the safe updated projection.
+
+## Admin user-list authority
+
+The `./admin-contract` user-list response retains a global identity whose default
+workspace membership is absent or revoked. Its required `role` is `null` in that
+case, and its `organizationId` remains the default workspace pointer. Null grants
+no workspace authority. Consumers must handle it explicitly; an organization
+filter lists active members of that workspace. Role assignment still requires a
+concrete role and targets the default membership; a missing default membership
+does not select a different workspace automatically. Active organization rosters
+and role-mutation responses continue to require non-null roles.
+
+## Current workspace roster on a compatible server
+
+`skills workspace members --email you@example.com` requests fresh email
+verification and reads one page of the current workspace roster. The selected
+server requires a current owner/admin session; API keys and support
+impersonation do not grant roster access. It never replaces saved credentials
+or changes the selected profile.
+
+For noninteractive use, request a code with the existing auth flow, then supply
+it on stdin (never as a command argument):
+
+```sh
+skills workspace members --email you@example.com --code-stdin --limit 25 --json
+```
+
+JSON includes `organizationId`, `members`, and required `nextCursor` (null on the
+last page). Pass a returned cursor unchanged with `--cursor` to read the next
+page; limits are 1–100 with server default 50. Timestamps retain the server's
+microsecond strings. Human output also includes a continuation cursor when one
+exists. Empty pages are distinct from denied, unsupported or malformed responses,
+which fail the command.
+
+SDK callers with an authorized customer session can use
+`RemoteSkillsClient.listWorkspaceMembers({ limit, cursor })`. For fresh email
+verification, use `RemoteSkillsAuthClient.listWorkspaceMembers(email, code,
+options)`. The MCP tool `list_workspace_members` takes `email`, `code`, and
+optional `limit`/`cursor` and calls the same fresh-auth client.
+
+## Change a current workspace membership
+
+On a compatible server, use the exact `membershipId` and role from the roster:
+
+```sh
+skills workspace member role <membership-id> --role viewer --expected-role member --email you@example.com --code-stdin --json
+skills workspace member remove <membership-id> --expected-role viewer --email you@example.com --code-stdin --json
+```
+
+Both commands use fresh verification and leave saved credentials and profiles
+unchanged. Without `--code-stdin`, an interactive terminal requests and prompts
+for a new code. JSON and noninteractive calls require a previously requested
+code on stdin. The server enforces current owner/admin policy. Owners can change
+roles while retaining an owner; admins can manage another member/viewer within
+those two roles. Self-removal is unavailable.
+
+`RemoteSkillsClient.setWorkspaceMemberRole(membershipId, { role, expectedRole })`
+and `.removeWorkspaceMember(membershipId, { expectedRole })` accept an explicit
+customer session. The corresponding `RemoteSkillsAuthClient` methods take
+`email, code` before those arguments and obtain an ephemeral session. MCP tools
+`set_workspace_member_role` and `remove_workspace_member` use the same client,
+with required `membershipId`, `expectedRole`, `email`, `code`, and `role` for a
+role change. API keys and support impersonation do not grant this authority.
+
+A role result contains `{ organizationId, member, changed }`; removal contains
+`{ organizationId, membershipId, removed: true, alreadyRemoved }`. Exact server
+timestamps remain strings. An authorized already-applied role returns
+`changed: false`; retrying removal of the same tombstone returns
+`alreadyRemoved: true`. A later replacement membership has a different ID.
+Stale expected-role conflicts require a roster refresh before another action.
+The client never refreshes, changes the precondition, or retries automatically.
+Known refusals expose a fixed message and code through `RemoteWorkspaceMemberError`;
+unsupported routes remain errors. Invitations, workspace switching and leaving
+your own workspace are separate capabilities.