@hasna/skills 0.1.62 → 0.1.64

package/README.md

@@ -189,9 +189,11 @@ Stable command shapes:
 
 ## Remote Registry
 
-Local bundled skills remain the default for discovery. This is not a mode you
-select: pointing browse/search commands at a server's registry is one fact, an
-API base URL being set. To set it:
+The npm package ships no bundled skill corpus. Discovery reads the local corpus
+cache (`~/.hasna/skills/installed`, filled by `skills pull`) and, when an API
+base URL is set, the server's registry. This is not a mode you select: pointing
+browse/search commands at a server's registry is one fact, an API base URL being
+set. To set it:
 
 ```bash
 export SKILLS_API_URL=https://your-server.example
@@ -213,6 +215,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`.
 
@@ -301,8 +309,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 |
@@ -336,12 +344,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.
@@ -419,7 +434,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()` |
 
@@ -432,9 +447,11 @@ checked.
 
 ## Project Runtime State
 
-Skills are discovered from the configured server registry or bundled OSS
-registry. Project folders and agent-native skill folders are never used as skill
-libraries.
+Skills are discovered from the configured server registry or the local corpus
+cache (`~/.hasna/skills/installed`, filled by `skills pull`; a checkout can be
+named explicitly with `skills sync --source <path>` or `$SKILLS_SOURCE`). The
+npm package ships no bundled corpus. Project folders and agent-native skill
+folders are never used as skill libraries.
 
 `.skills/` is runtime/output state only:
 
@@ -446,7 +463,8 @@ 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`.
 
@@ -509,7 +527,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