@hasna/skills 0.9.20 → 0.10.0

package/README.md

@@ -30,23 +30,61 @@ payloads outside public software repositories.
 
 ## Quick Start
 
-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
+bun install -g @hasna/skills
+skills login
+```
+
+`skills login` opens your browser to sign in to https://skills.md and stores an
+API key for this machine in `~/.hasna/skills/config/credentials` (owner-only),
+together with the server it belongs to. On a terminal it then offers to register
+Skills with your coding agents (`skills setup agents`). Check who you are with
+`skills whoami`.
+
+`skills logout` signs out the active profile. It deletes the key that
+`skills login` stored, then revokes it on the server that issued it when login
+minted it (a key you added with `--api-key` is only deleted, unless you pass
+`--revoke`). It exits 0 only when you are signed out. It exits non-zero, naming
+the reason, when revocation did not complete or is not supported (it then says
+where to revoke the key by hand), when another credential is still active (an
+environment variable, the Keychain or another selected profile, which it never
+changes), when the profile holds a credential `skills login` did not store
+(left in place), or when the local deletion failed.
+
+- No browser on this machine: `skills login --device` prints a code to approve
+  on another device, then `skills login --poll` finishes the same sign-in.
+- An API key you already have: `printenv MY_SKILLS_KEY | skills login --api-key`
+  reads it from stdin, verifies it and stores it. Nothing is echoed.
+- An email code instead of the browser: `skills login --email you@example.com`.
+- Running `skills` in a terminal opens the interactive browser. It also works
+  signed out and has the same account commands: `/login`, `/logout`, `/whoami`.
+
+### Your own server
+
+The software is open source and every command works against your own compatible
+Skills server. Sign in to it with
+`skills login --url https://skills.example.com`; the URL is stored with the key,
+so later commands use that server without flags. `HASNA_SKILLS_API_URL` selects
+a server for one shell. `skills setup --api-url <origin>` records a server
+without signing in.
+
+### Fleet stations
+
+Stations provisioned with a fleet key keep using the internal gateway
+`https://api.hasna.com/skills`; versioned requests use `/skills/v1`. A key with
+no recorded URL (the Keychain item, `HASNA_SKILLS_API_KEY` alone, or an older
+credentials file) always stays on that gateway and is never sent anywhere else.
+The gateway has no interactive login service, so on such a station
+`skills login` says so, sends nothing, and names the credential to unset first.
+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 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. Replace `default` with
@@ -739,7 +777,7 @@ Tier 5 sits below disk on purpose. A wrapper that injects `HASNA_SKILLS_API_KEY`
 into one child process re-reads its store every time and cannot go stale; a shell
 `export` can, and after a key rotation the file on disk is the correct one.
 
-`skills auth login` writes tier 4. A tier an operator set on purpose (1 and 2)
+`skills login` (also `skills auth login`) writes tier 4. A tier an operator set on purpose (1 and 2)
 never falls through to another identity: if it cannot be honoured, the command
 fails rather than acting as a different principal.
 
@@ -759,19 +797,37 @@ 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.
+An explicit `skills login` replaces a stored reference with the newly
+authenticated key. `skills logout` does not remove a stored reference: it
+did not come from `skills login`, so logout leaves it in place, names the file
+and exits non-zero. Remove the reference from the file to sign that profile
+out; the vault item and Secrets' credential are never touched. 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` →
 `~/.hasna/skills/config/credentials` → the fleet gateway
 `https://api.hasna.com/skills`. The gateway default applies only once a
-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.
+credential has resolved, so a data command from an install with no credential
+names no host at all. Signing in is the one exception: with no URL and no
+credential anywhere, `skills login` signs in to https://skills.md and records
+that URL beside the new key. A credential that already resolves keeps its own
+server, for data and for signing in. A URL that `skills login` wrote is removed
+again by `skills logout` together with the key; a URL you configured with
+`skills setup --api-url <origin>` stays. That command writes the credentials
+file; the address is per-user, never per-project.
+
+**Which credential may go to which server.** A stored credential goes only to
+the server it was stored for: the credentials-file or profile key to its
+recorded server (the internal gateway when it recorded none), the Keychain key
+to the Keychain `api-url` beside it (else the gateway). A credential that
+records no server of its own (`HASNA_SKILLS_API_KEY`,
+`HASNA_SKILLS_API_KEY_OVERRIDE`, an environment `HASNA_SKILLS_API_KEY_REF`, or
+an explicit argument) goes only to the internal gateway or to a URL from the
+environment (`HASNA_SKILLS_API_URL`), never to a URL from the credentials file
+or the Keychain. Any other combination is refused before anything is sent. Set
+`HASNA_SKILLS_API_URL` alongside such a credential for your own server.
 
 The internal gateway resource contract is `/skills/v1/...`; commercial and custom
 instances retain their `/api/v1/...` routes. A full gateway `/skills/v1` base is
@@ -877,8 +933,10 @@ of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
 | `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 |
-| `skills auth login` | | Sign in to a compatible API with browser/device-code auth or email code |
+| `skills login` | | Sign in in the browser (https://skills.md unless a server is configured); `--device`, `--email`, `--api-key` (stdin) and `--url <origin>` select other flows and servers |
+| `skills logout` | | Sign out the active profile: delete the key `skills login` stored and revoke it on its server when login minted it; `--revoke` also revokes a key you added, `--no-revoke` revokes nothing (and exits non-zero if a minted key is left live) |
+| `skills whoami` | | Show the signed-in account and where its credential came from |
+| `skills auth login` / `auth logout` / `auth whoami` | | The same commands under `auth`; `auth login --membership-id` enrolls a workspace profile |
 | `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 |