@hasna/skills 0.1.63 → 0.1.66

package/README.md

@@ -19,7 +19,7 @@ Requires [Bun](https://bun.sh/) 1.0+.
 # Browse skills interactively
 skills
 
-# Point the CLI at a Skills API server when you want remote runs
+# Point the CLI at a Skills API server for server-owned (premium) skill runs
 skills setup --api-url https://skills.example.com
 skills auth login --api-key "$SKILLS_API_KEY"
 
@@ -35,28 +35,41 @@ skills setup agents
 # See what a skill needs
 skills info logo-design
 
-# Premium skills run through the configured Skills API
-skills run logo-design --brief "minimal geometric owl mark"
+# Server-owned (premium) skills run through the configured Skills API
+skills run <server-owned-skill> --brief "minimal geometric owl mark"
 
-# Free/local skills can still use your own provider keys when documented
+# Every other skill runs on this machine by default, even when an API is
+# configured; local skills may use your own provider keys when documented
 skills requires brand-style-guide
 OPENAI_API_KEY=... skills run brand-style-guide ./brand-notes.md
 ```
 
 ## Server-Side Runtime Skills
 
-Premium skills run on the server. The CLI and MCP server submit them to the
-configured Skills API, create local run metadata, and then expose status and
-artifact commands. They do not fall back to bundled local execution when auth is
-missing or the server runtime is unavailable.
-
-Use `SKILLS_API_KEY` or `skills auth login --api-key` for premium server-side
+Premium skills run on the server. A skill is premium — server-owned — when its
+published contract carries the server-owned marker (`skills.runtime: "hosted"`
+or `skills.source: "remote" | "private-hosted"` in the skill's `package.json`).
+The CLI and MCP server submit server-owned skills to the configured Skills API,
+create local run metadata, and then expose status and artifact commands. They
+do not fall back to bundled local execution when auth is missing or the server
+runtime is unavailable.
+
+Routing is config-driven and local is the default: a run is sent to the API
+only when an origin is configured (`apiUrl` or `$SKILLS_API_URL`), a credential
+is present (`SKILLS_API_KEY` or the auth store), and the skill carries the
+server-owned marker. Every other skill runs on this machine, whether or not an
+API is configured. No skill in the OSS catalog is server-owned today; the
+marker arrives with skills synced from a Skills API deployment. A server-owned
+skill run without the origin or the credential fails closed with an error
+naming the missing setup — it never silently runs locally.
+
+Use `SKILLS_API_KEY` or `skills auth login --api-key` for server-side
 execution:
 
 ```bash
 skills setup --api-url https://skills.example.com
 skills auth login --api-key "$SKILLS_API_KEY"
-skills run logo-design --brief "minimal geometric owl mark"
+skills run <server-owned-skill> --brief "minimal geometric owl mark"
 skills runs status <run-id>
 skills exports download <run-id>
 ```
@@ -175,10 +188,11 @@ Stable command shapes:
   `{ "dryRun": true, "actions": [...] }` where applicable.
 - Runtime: `run --json <skill> ...` returns
   `{ "skill", "args", "exitCode", "stdout", "stderr", "error", "run" }`.
-  Premium server-side runs include `{ "contractVersion": 1, "remote": true,
-  "remoteRun", "pricing", "run", "nextActions" }` and return immediately with
+  Server-owned (premium) runs include `{ "contractVersion": 1, "remote": true,
+  "remoteRun", "run", "nextActions" }` and return immediately with
   status commands such as `skills runs status <run-id>` and
-  `skills exports download <run-id>`.
+  `skills exports download <run-id>`. Premium-catalog and pricing metadata is
+  served by the API and never ships in this package.
 - Config and schedules: `config * --json` and `schedule * --json` return
   machine-readable status objects.
 - Storage: `storage status --json` returns local `.skills` paths and optional
@@ -215,6 +229,12 @@ If the URL is an origin such as `https://your-server.example`, the CLI requests
 Authenticated registry listing and premium server-side execution use
 `SKILLS_API_KEY` or the credential saved by `skills auth login --api-key`.
 
+The typed `RemoteSkillsClient` also exposes pin, tag, and cursor-based
+incremental-sync methods (`listPins`/`pin`/`unpin`, `listTags`/`skillsByTag`,
+`listUpdatedSince`). A server that predates those routes fails closed with an
+explicit unsupported-route error — never a silent empty listing. Route table
+and version-skew contract: `docs/architecture/remote-client-pins-tags-sync.md`.
+
 For the reusable upstream contract, see
 `docs/architecture/reusable-skills-engine.md`.
 
@@ -303,8 +323,8 @@ identical either way.
 
 ```bash
 skills-server                                            # SQLite at ~/.hasna/skills/server.db
-HASNA_SKILLS_DATABASE_URL=/srv/skills/server.db skills-server
-HASNA_SKILLS_DATABASE_URL=postgres://user:pw@host/skills skills-server
+HASNA_SKILLS_DATABASE_URL=<path>/server.db skills-server
+HASNA_SKILLS_DATABASE_URL=postgres://user:CHANGEME@host/skills skills-server
 ```
 
 | `HASNA_SKILLS_DATABASE_URL` | Backend | Survives restart |
@@ -338,12 +358,19 @@ explicitly, because several replicas racing to migrate one shared database is no
 something to do implicitly:
 
 ```bash
-HASNA_SKILLS_DATABASE_URL=postgres://… skills-migrate
+HASNA_SKILLS_DATABASE_URL=postgres://user:CHANGEME@host/skills skills-migrate
 ```
 
 `skills-migrate` fails if no database is configured rather than migrating a default
 SQLite file, so it stays usable as a deploy gate.
 
+`HASNA_SKILLS_DATABASE_URL` and `DATABASE_URL` are server-only. CLI, MCP, and SDK
+clients never read them and never open a database connection: a client reaches
+the cloud only through `SKILLS_API_URL` plus an API key (the `apiKey` stored by
+`skills auth`, or `SKILLS_API_KEY`). The one exception is the repo-native storage
+sync under [Storage Boundary](#storage-boundary), an operator tool that
+intentionally reads the same variables.
+
 Three things the server will not do:
 
 - Fall back to another backend when a configured Postgres URL cannot be reached.
@@ -421,7 +448,7 @@ skills/                      # Public skill contracts and local OSS skills
 
 | Count | Value | Derived from |
 |---|---|---|
-| Catalog skills | 85 | `SKILLS.length` (`src/lib/registry-data/`) |
+| 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()` |
 
@@ -450,7 +477,8 @@ folders are never used as skill libraries.
 └── tmp/
 ```
 
-Auth stays global in `~/.hasna/skills/auth.json`. Registry and doc caches
+Auth stays global in `<app folder>/auth.json` (default
+`~/.hasna/skills/auth.json`). Registry and doc caches
 belong in `~/.cache/skills` or the Skills API, not inside project
 `.skills`.
 
@@ -473,8 +501,11 @@ bun run typecheck          # TypeScript type checking
    manifests, bin entries, docs, and SKILL.md frontmatter
 4. Run `bun test` to verify registry-wide validation passes
 
-Premium server-executed skills should add public contracts, pricing, docs, and tests
-without adding provider secrets to the OSS package.
+Server-owned (premium) skills declare the server-owned marker in their
+published contract (`skills.runtime: "hosted"` or `skills.source: "remote" |
+"private-hosted"`), ship public contracts, docs, and tests, and add no provider
+secrets and no pricing metadata to the OSS package — pricing is served by the
+API.
 
 Portable skill directories are auto-discovered from
 `~/.hasna/skills/installed/<name>/`. Skills found in either older location -
@@ -513,7 +544,15 @@ overridden folder. `skills config path` reports the config file actually in use.
 | Installed skills | `<app folder>/installed/<name>/` | yes |
 | Global config | `<app folder>/config.json` | yes |
 | Feedback database | `<app folder>/skills.db` | yes |
-| Auth | `~/.hasna/skills/auth.json` | no (resolved at startup) |
+| Auth | `<app folder>/auth.json` | yes |
+
+There is no separate local-skills-folder override, and none is needed: one
+variable relocates the whole app folder, so the corpus is always
+`<app folder>/installed`. With the default app folder that is exactly the
+migrated corpus location — the former `~/.skills` and `custom/` trees are folded
+into `<app folder>/installed` on first resolution (see "Migrating from the older
+layout"). Extension corpora are a separate concern and keep their own
+`extensionsDir` config key.
 
 ### Migrating from the older layout