@hasna/skills 0.10.1 → 0.10.2

package/README.md

@@ -488,6 +488,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 +1493,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