feat(skills): add registry doctor diagnostics and docs

docs/plans/2026-02-16-clawhub-registry-checklist.md

@@ -95,11 +95,11 @@ Tests:
 
 Checklist:
 
-- [ ] Update `README.md` skills section with registry usage.
-- [ ] Update `docs/security/SAFE_PERSONAL_AGENT.md` with registry trust model.
-- [ ] Add doctor diagnostics:
-  - [ ] registry source reachable/parsible
-  - [ ] clear warning when registry disabled/unconfigured
+- [x] Update `README.md` skills section with registry usage.
+- [x] Update `docs/security/SAFE_PERSONAL_AGENT.md` with registry trust model.
+- [x] Add doctor diagnostics:
+  - [x] registry source reachable/parsible
+  - [x] clear warning when registry disabled/unconfigured
 
 Acceptance:
 
@@ -107,17 +107,17 @@ Acceptance:
 
 Tests:
 
-- [ ] Doctor tests for registry health reporting.
+- [x] Doctor tests for registry health reporting.
 
 ## Security Guardrails
 
-- [ ] Registry metadata is never treated as trusted code.
-- [ ] Skill scanner remains mandatory before skill becomes available.
-- [ ] Prompt injection and symlink/binary checks still gate registry-installed skills.
-- [ ] Secrets are never accepted from registry metadata.
+- [x] Registry metadata is never treated as trusted code.
+- [x] Skill scanner remains mandatory before skill becomes available.
+- [x] Prompt injection and symlink/binary checks still gate registry-installed skills.
+- [x] Secrets are never accepted from registry metadata.
 
 ## Final Validation
 
-- [ ] `pnpm typecheck`
+- [x] `pnpm typecheck`
 - [ ] `pnpm test:run`
 - [ ] Update `docs/plans/state.json` to `completed` with summary + test status once all phases land.

docs/plans/state.json

@@ -216,7 +216,7 @@
       "status": "in_progress",
       "date": "2026-02-16",
       "updated": "2026-02-16",
-      "summary": "Completed Phase 3 install-by-registry-id flow: added `flynn skills install --registry-id` with registry lookup and source-type resolution (local/git/archive), non-local confirmation guard, temp materialization path, and dedicated registry install audit events while preserving existing scanner/install safety gates.",
+      "summary": "Completed Phase 4 docs + runtime visibility for ClawHub registry: added config-backed registry source (`skills.registry_source`), doctor diagnostics for registry configured/reachable/parsable state, README usage guidance, and security trust-model documentation. Registry install flow now also falls back to config registry source.",
       "files_created": [
         "docs/plans/2026-02-16-clawhub-registry-checklist.md",
         "src/skills/registrySource.ts",
@@ -228,10 +228,17 @@
         "src/cli/skills.test.ts",
         "src/audit/types.ts",
         "src/audit/logger.ts",
+        "src/cli/doctor.ts",
+        "src/cli/doctor.test.ts",
+        "src/config/schema.ts",
+        "src/config/schema.test.ts",
+        "README.md",
+        "docs/security/SAFE_PERSONAL_AGENT.md",
+        "config/default.yaml",
         "docs/plans/2026-02-16-clawhub-registry-checklist.md",
         "docs/plans/state.json"
       ],
-      "test_status": "pnpm test:run src/skills/registrySource.test.ts src/cli/skills.test.ts + pnpm typecheck passing"
+      "test_status": "pnpm test:run src/skills/registrySource.test.ts src/cli/skills.test.ts src/cli/doctor.test.ts src/config/schema.test.ts + pnpm typecheck passing; full pnpm test:run currently fails on unrelated src/channels/whatsapp/adapter.test.ts assertions (13 failures)"
     },
     "credential-system-v2-api-and-oauth": {
       "file": "2026-02-15-credential-system-v2-api-and-oauth-checklist.md",
@@ -2772,7 +2779,7 @@
     "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram",
     "native_audio_support": "completed — smart routing for native audio (Gemini/OpenAI/GitHub) vs Whisper transcription fallback",
     "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening",
-    "next_up": "ClawHub registry Phase 4: docs + runtime visibility (README/security docs and doctor registry diagnostics)"
+    "next_up": "Stabilize unrelated WhatsApp adapter test failures in full suite, then run full validation and close ClawHub registry milestone"
   },
   "soul_md_and_cron_create": {
     "date": "2026-02-11",

docs/security/SAFE_PERSONAL_AGENT.md

@@ -69,6 +69,18 @@ Skills without `permissions` still load, but:
 - If a skill is activated (via routing) and it has no `permissions` block, **it has no tool access**.
 - This is deliberate: skills should be auditable capability packages.
 
+## Registry Trust Model (ClawHub / Community Catalogs)
+
+Registry catalogs are discovery metadata, not trusted code.
+
+- Flynn supports registry discovery and install-by-id via `flynn skills registry *` and `flynn skills install --registry-id`.
+- Registry metadata fields such as `publisher`, `homepage`, and `sha256` are treated as **declared/unverified**.
+- Non-local registry sources require explicit operator confirmation (`--confirm`) during install.
+- Resolved sources (local/git/archive) are still routed through the same skill scanner and installer safety gates.
+- Registry-driven installs emit dedicated audit events (`skills.registry_install`) including registry id/source and outcome.
+
+Operationally: treat a registry as a candidate index. Trust is established by your own review and scanner outcomes, not by catalog claims alone.
+
 ## Runtime Enforcement
 
 Enforcement happens in two places: