@hasna/skills 0.10.1 → 0.10.3

package/README.md

@@ -453,17 +453,22 @@ during installation. A successful update does not reload an existing session.
 At session start, the hook authenticates and refreshes the profile. Prompt hooks
 select complete skill instructions from that verified cache using explicit
 `$skill` references, profile keywords, paths and always-required selections.
-A session retains its selected versions; compaction restores loaded instructions,
+A session retains its loaded selections; compaction restores loaded instructions,
 and subagents inherit the parent's selection. Instructions that exceed the
 context budget produce an explicit `skills load` command. A hook never executes
-a skill. Cached use is explicit and expires after 24 hours. When cached context
-expires or is missing, the hook makes one authenticated API attempt for the same
-pinned session. It preserves exact versions and does not extend an expired
-receipt's lifetime. Authentication, integrity and native discovery failures still
-block; they do not silently switch to a local catalog.
-
-An intentional profile change for an already running session uses a separate
-reviewed operation. `sync` and hook reinstallation do not migrate session pins:
+a skill. Cached use is explicit and expires after 24 hours. When a session
+receipt expires, the hook authenticates the current profile. If every loaded
+selection still has identical metadata and bundle digest, it archives the old
+receipt and advances that session to the current profile under an exact receipt
+precondition. Unloaded selections may be added or removed. If a loaded selection
+changed or disappeared, the hook blocks and requires the explicit reconciliation
+below. A missing cache may be recovered through authenticated context.
+Authentication, integrity and native discovery failures still block; they do
+not silently switch to a local catalog.
+
+An intentional change to a loaded selection or profile identity for an already
+running session uses a separate reviewed operation. `sync` and hook
+reinstallation do not migrate session pins:
 
 ```bash
 skills sessions show <session-id> --json
@@ -488,6 +493,30 @@ are acquired in deterministic path order, and the parent is re-read immediately
 before the child commit; any changed or ABA generation refuses the child write.
 No agent process is stopped or restarted.
 
+Session write locks created by current releases include the host, boot and
+process start identity (plus the Linux PID namespace). After 30 seconds, a
+later writer can archive one only when that identity proves the writer is gone
+on this same host. The exact lock bytes and a metadata record remain under
+`selection-cache/session-lock-recoveries`; the session receipt is not changed
+by recovery. A live, recent, malformed or different-host lock still blocks the
+write. A recovery guard serializes competing recoverers.
+
+Older PID-only locks require a local review because they do not identify their
+host. On the host that created the lock, inspect the receipt and lock, verify
+the recorded PID belongs to no live writer, then apply the exact reviewed lock:
+
+```bash
+skills sessions recover-lock <session-id> --json
+skills sessions recover-lock <session-id> --apply \
+  --review-digest <review-digest> --confirm-local-host --json
+```
+
+The second command rechecks the lock, receipt, age and PID before archiving.
+Keep the archive path returned by the command. If the review changes or the
+writer cannot be proven gone, leave the lock in place; do not remove the
+session receipt or stop a running agent. A surviving recovery guard also
+requires separate review before another recovery attempt.
+
 Use the same updated Skills installation for every process writing this cache.
 Session writers coordinate with reconciliation and refuse a stale write that
 would restore an earlier pin. Reviewed reconciliation approvals bind their
@@ -1469,7 +1498,15 @@ The server supports SQLite and Postgres. The database is an adapter choice, not
 different product: the schema, the organization scoping, and the run lifecycle are
 identical either way.
 
+Set `SKILLS_PUBLIC_BASE_URL` to this server's public API origin before starting
+`skills-serve` or embedding its SDK handler. The server uses that authority in
+profile receipts; its socket address cannot establish the public URL. For a
+local-only instance, use the loopback origin shown below. A deployed independent
+instance should use its own HTTPS origin. Without an explicit public URL, the
+server refuses to start before opening storage.
+
 ```bash
+export SKILLS_PUBLIC_BASE_URL=http://127.0.0.1:8787
 skills-serve                                              # SQLite at ~/.hasna/skills/server.db
 HASNA_SKILLS_DATABASE_URL=<path>/server.db skills-serve
 HASNA_SKILLS_DATABASE_URL=postgres://user:CHANGEME@host/skills skills-serve