Harden: fix install.sh exit code + add toolchain self-test + CI

Comprehensive test pass over every implemented use case surfaced one bug:
- install.sh returned exit 1 on success — the final `[ "$MODE" = global ] && echo`
  short-circuited to non-zero when not global. Fixed with an if-block.

Improvements:
- tools/okf-selftest.sh: end-to-end self-test (init → validate clean + catch-bad →
  index → BM25 search → air-gap viz → lease acquire/conflict/release → optional
  Ollama embed+hybrid). 10 checks, exits non-zero on failure.
- .github/workflows/tools.yml: runs the self-test + an installer smoke test (asserts
  exit 0) on every change to tools/skill/installer.
- README: quickstart now shows the self-test.

Verified locally: self-test 10/10 (incl. hybrid via Ollama). All MCP tools (read,
hybrid search, propose_change PR-gated, lease-gated commit_concept) exercised through
the real protocol against the demo bundle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: supachai-j

.claude/skills/okf/SKILL.md

@@ -0,0 +1,26 @@
+# Regression-test the OKF toolchain (pure-stdlib) on every change to tools/skill/installer.
+name: tools-selftest
+on:
+  push:
+    paths: ["tools/**", "skill/**", "install.sh", ".github/workflows/tools.yml"]
+  pull_request:
+    paths: ["tools/**", "skill/**", "install.sh"]
+  workflow_dispatch:
+
+jobs:
+  selftest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: OKF toolchain self-test
+        run: bash tools/okf-selftest.sh     # embeddings/hybrid auto-skip (no Ollama in CI)
+      - name: installer smoke test (must exit 0)
+        run: |
+          ./install.sh --dir /tmp/okf-skill
+          test -f /tmp/okf-skill/okf/SKILL.md
+          test "$(ls /tmp/okf-skill/okf/scripts/*.py | wc -l)" -ge 6
+          ./install.sh --uninstall --dir /tmp/okf-skill
+          test ! -d /tmp/okf-skill/okf

.github/workflows/tools.yml

@@ -52,6 +52,7 @@ git clone https://github.com/supachai-j/open-knowledge-format-starter.git
 cd open-knowledge-format-starter
 python3 tools/okf-validate.py          # → ✓ CONFORMANT with OKF v0.1
 python3 tools/okf-viz.py               # → writes wiki/viz.html, open it in any browser
+bash    tools/okf-selftest.sh          # → exercises the whole toolchain (10 checks)
 ```
 
 1. Read **[AGENTS.md](AGENTS.md)** — governs how concepts are structured and how the agent behaves.

README.md

@@ -50,4 +50,4 @@ echo "    $SKILL_DIR/SKILL.md"
 echo "    $SKILL_DIR/scripts/  ($(ls "$SKILL_DIR/scripts"/*.py | wc -l | tr -d ' ') scripts + vendor/)"
 echo
 echo "Use it: open Claude Code and say e.g. \"init an OKF knowledge base here\" or \"/okf\"."
-[ "$MODE" = "global" ] && echo "Installed globally — available in every project."
+if [ "$MODE" = "global" ]; then echo "Installed globally — available in every project."; fi

install.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# okf-selftest.sh — exercise the whole OKF toolchain end-to-end in a temp project.
+# Pure-stdlib tools are required; embeddings/hybrid are tested only if a local Ollama
+# is reachable (otherwise skipped). Exits non-zero if any check fails. Run: bash tools/okf-selftest.sh
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+PY="${PYTHON:-python3}"
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+pass=0; fail=0
+ok()  { echo "  ✓ $1"; pass=$((pass+1)); }
+bad() { echo "  ✗ $1"; fail=$((fail+1)); }
+
+echo "OKF self-test  (tools: $HERE)"
+
+# 1. init
+$PY "$HERE/okf-init.py" "$TMP/proj" --date 2026-01-01 >/dev/null 2>&1 && [ -f "$TMP/proj/wiki/index.md" ] \
+  && ok "okf-init scaffolds a bundle" || bad "okf-init"
+W="$TMP/proj/wiki"
+
+# 2. validate — conformant
+$PY "$HERE/okf-validate.py" "$W" >/dev/null 2>&1 && ok "okf-validate passes a clean bundle" || bad "okf-validate (clean)"
+
+# 3. validate — negative (missing type must fail)
+printf '%s\n' '---' 'title: x' '---' 'no type here' > "$W/broken.md"
+if $PY "$HERE/okf-validate.py" "$W" >/dev/null 2>&1; then bad "okf-validate should FAIL on missing type"; else ok "okf-validate catches missing type"; fi
+rm -f "$W/broken.md"
+
+# 4. index + search (BM25)
+$PY "$HERE/okf-index.py" build "$W" >/dev/null 2>&1 && ok "okf-index builds" || bad "okf-index build"
+$PY "$HERE/okf-search.py" "how this knowledge base is organized" --bundle "$W" -k 1 2>/dev/null | grep -q "getting-started" \
+  && ok "okf-search (BM25) returns expected hit" || bad "okf-search (BM25)"
+
+# 5. viz — air-gap single file
+$PY "$HERE/okf-viz.py" "$W" --name selftest >/dev/null 2>&1 \
+  && [ -f "$W/viz.html" ] && ! grep -q "cdn.jsdelivr" "$W/viz.html" \
+  && ok "okf-viz emits a self-contained (no-CDN) viewer" || bad "okf-viz (air-gap)"
+
+# 6. lease lifecycle
+export OKF_LEASE_DIR="$TMP/leases"
+TOK=$($PY "$HERE/okf-lease.py" acquire t/x --owner A --ttl 60 2>/dev/null | $PY -c "import sys,json;print(json.load(sys.stdin).get('token',''))" 2>/dev/null)
+[ -n "$TOK" ] && ok "okf-lease acquire" || bad "okf-lease acquire"
+if $PY "$HERE/okf-lease.py" acquire t/x --owner B >/dev/null 2>&1; then bad "okf-lease should block a 2nd owner"; else ok "okf-lease blocks contending owner"; fi
+$PY "$HERE/okf-lease.py" release t/x --owner A --token "$TOK" >/dev/null 2>&1 && ok "okf-lease release" || bad "okf-lease release"
+
+# 7. embeddings + hybrid (optional — only if Ollama is up)
+if curl -s -m 2 http://localhost:11434/api/tags >/dev/null 2>&1; then
+  if $PY "$HERE/okf-embed.py" build "$W" >/dev/null 2>&1 \
+     && $PY "$HERE/okf-search.py" "organize knowledge" --bundle "$W" 2>/dev/null | grep -q "hybrid"; then
+    ok "okf-embed + hybrid search (Ollama)"
+  else bad "okf-embed/hybrid (Ollama reachable but failed)"; fi
+else
+  echo "  – skipped embeddings/hybrid (no Ollama on :11434)"
+fi
+
+echo "──────────────────────────────"
+echo "  $pass passed, $fail failed"
+[ "$fail" -eq 0 ]