feat(install): serve several sources instead of displacing them

~/.agents/skills was a single link straight at this checkout. That encoded an
assumption nobody had stated — that this checkout is the only source of skills
on the host. On flamingo it was not: Crush's directory held Anthropic's
official set, and the only way to install this library was to move that set
aside. A capability loss dressed up as a tidy-up.

The canonical location becomes a real directory of per-skill symlinks, fed by
the checkout plus anything in SKILLS_EXTRA_SOURCES. Harnesses keep their one
directory link, so the count is N + one per harness rather than N x harnesses,
which is what #23 was actually about.

The three requirements #27 named, each with a test:
- collisions are logged with both paths and the checkout wins, never resolved
  in silence;
- removing a skill from a source prunes its link;
- anything in the managed directory that is not our symlink is reported and
  left in place — the installer does not delete content it did not create.

doctor learns the same model: sources are recorded at ~/.agents/skills-sources,
a link into a configured source is healthy, a link into an unknown one is not,
and the old count check becomes a per-skill check because a per-skill layout
can lose one skill without changing any total. The pre-#27 wiring is named as
legacy rather than reported as damage. count_skills needed find -L; without it
symlinked skill directories count as zero.

Verified live on koala: migrated in place to 42 per-skill links, then a second
source added a 43rd alongside them, then a re-run without that source pruned it
back to 42. Only doctor finding throughout was the genuine stale plugin.

Closes #27
Bump-Type: minor

bin/doctor

@@ -39,12 +39,21 @@ SELF_CHECKOUT=$(CDPATH= cd -- "$SELF_DIR/.." && pwd)
 # copy doctor happens to be running from. When invoked as a plugin hook, $0
 # lives in the plugin cache, which is legitimately a second copy: judging the
 # harness links against it would flag every one of them as "outside".
+AGENTS_DIR="$HOME/.agents/skills"
+SOURCES_FILE="$(dirname -- "$AGENTS_DIR")/$(basename -- "$AGENTS_DIR")-sources"
+
 if [ -n "${DOCTOR_CHECKOUT:-}" ]; then
   CHECKOUT="$DOCTOR_CHECKOUT"
-elif [ -d "$HOME/.agents/skills" ]; then
-  # Resolve the link FIRST, then take the parent. "cd X/.." resolves ".."
-  # lexically against the link path, which lands back in ~/.agents.
-  _resolved=$(CDPATH= cd -- "$HOME/.agents/skills" 2>/dev/null && pwd -P)
+elif [ -f "$SOURCES_FILE" ]; then
+  # Since #27 the canonical location is a real directory fed by several
+  # sources, so it can no longer be resolved to a checkout. install.sh records
+  # the list; the first line is always this repo's skills/ directory.
+  CHECKOUT=$(dirname -- "$(head -n 1 "$SOURCES_FILE")")
+elif [ -L "$AGENTS_DIR" ]; then
+  # Pre-#27 wiring: one link straight at the checkout. Resolve the link FIRST,
+  # then take the parent. "cd X/.." resolves ".." lexically against the link
+  # path, which lands back in ~/.agents.
+  _resolved=$(CDPATH= cd -- "$AGENTS_DIR" 2>/dev/null && pwd -P)
   CHECKOUT=$(dirname -- "$_resolved")
 else
   CHECKOUT="$SELF_CHECKOUT"
@@ -66,9 +75,26 @@ add() {
 }
 
 # count_skills <dir> — directories containing a SKILL.md, one level down.
+# -L on purpose: since #27 the entries are per-skill symlinks, and find does
+# not descend into a symlinked directory without it.
 count_skills() {
   [ -d "$1" ] || { printf '0'; return; }
-  find "$1"/ -mindepth 2 -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' '
+  find -L "$1"/ -mindepth 2 -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' '
+}
+
+# under_known_source <physical-path> — 0 when the path lies inside a source
+# install.sh recorded, or inside the active checkout.
+under_known_source() {
+  _path=$1
+  _list="$SKILLS_DIR"
+  [ -f "$SOURCES_FILE" ] && _list="$_list
+$(cat "$SOURCES_FILE")"
+  printf '%s\n' "$_list" | while IFS= read -r _src; do
+    [ -n "$_src" ] || continue
+    _real=$(CDPATH= cd -- "$_src" 2>/dev/null && pwd -P) || continue
+    [ -n "$_real" ] || continue
+    case "$_path" in "$_real"/*|"$_real") printf 'yes'; break ;; esac
+  done | grep -q yes
 }
 
 # --- the checkout itself ----------------------------------------------------
@@ -95,10 +121,47 @@ for entry in "$SKILLS_DIR"/*; do
   fi
 done
 
+# --- the canonical directory --------------------------------------------------
+# Pre-#27 this was a symlink at the checkout. It is a real directory now, one
+# per-skill link per skill, fed by every configured source — that is what lets
+# a second library (Anthropic's official set on flamingo) coexist instead of
+# being displaced.
+if [ -L "$AGENTS_DIR" ]; then
+  add WARN legacy "$AGENTS_DIR is the pre-#27 single-link wiring — re-run install.sh to adopt the multi-source layout"
+elif [ -d "$AGENTS_DIR" ]; then
+  for entry in "$AGENTS_DIR"/*; do
+    [ -e "$entry" ] || [ -L "$entry" ] || continue
+    name=$(basename "$entry")
+
+    if [ ! -L "$entry" ]; then
+      add FAIL unmanaged "$AGENTS_DIR/$name is not a link into any source — nothing manages it and nothing updates it"
+      continue
+    fi
+    if [ ! -e "$entry" ]; then
+      add FAIL dangling "$entry -> $(readlink "$entry") (target does not exist)"
+      continue
+    fi
+
+    resolved=$(CDPATH= cd -- "$entry" 2>/dev/null && pwd -P)
+    if [ -n "$resolved" ] && ! under_known_source "$resolved"; then
+      add FAIL outside "$entry resolves to $resolved, an unknown source — it works, so nothing complains, while serving content nobody updates"
+    fi
+  done
+
+  # A per-skill layout can lose one skill without changing any total, so the
+  # invariant is per skill, not a count.
+  for dir in "$SKILLS_DIR"/*/; do
+    [ -f "$dir/SKILL.md" ] || continue
+    name=$(basename "$dir")
+    [ -L "$AGENTS_DIR/$name" ] \
+      || add FAIL missing "$name is in the checkout but has no link in $AGENTS_DIR — re-run install.sh"
+  done
+fi
+
 # --- harness wiring ---------------------------------------------------------
-# Canonical location first; Pi reads it directly and the others link to it.
+# Crush and OpenCode keep their single directory link at the canonical dir;
+# Pi reads it directly and needs no link of its own.
 for dir in \
-  "$HOME/.agents/skills" \
   "$HOME/.config/crush/skills" \
   "$HOME/.config/opencode/skills"
 do
@@ -110,32 +173,23 @@ do
   fi
 
   # A real directory where a link belongs holds content nothing manages: it
-  # cannot receive new skills and silently shadows the checkout. Distinguished
-  # from the foreign-checkout case below because the fix differs — move it
-  # aside and re-run install.sh, rather than re-point a link.
+  # cannot receive new skills and silently shadows the canonical dir. Since
+  # #27 the fix is not only "move it aside" — it can be added as an extra
+  # source instead, which is how flamingo keeps the official Anthropic set.
   if [ ! -L "$dir" ] && [ -d "$dir" ]; then
-    add FAIL unmanaged "$dir is a real directory, not a link into the checkout — it holds $(count_skills "$dir") unmanaged skill(s); move it aside and re-run install.sh"
+    add FAIL unmanaged "$dir is a real directory, not a link into the canonical dir — it holds $(count_skills "$dir") unmanaged skill(s); add it to SKILLS_EXTRA_SOURCES and re-run install.sh, or move it aside"
     continue
   fi
 
-  # Resolve to a physical path and confirm it lands inside THIS checkout.
-  # A link that resolves to a different checkout is the dangerous case: it
-  # works, so nothing complains, while serving stale content.
   resolved=$(CDPATH= cd -- "$dir" 2>/dev/null && pwd -P)
-  canonical=$(CDPATH= cd -- "$SKILLS_DIR" 2>/dev/null && pwd -P)
-  if [ -n "$resolved" ] && [ "$resolved" != "$canonical" ]; then
-    add FAIL outside "$dir resolves to $resolved, outside the active checkout $canonical"
-    continue
-  fi
-
-  got=$(count_skills "$dir")
-  if [ "$got" != "$EXPECTED" ]; then
-    add FAIL count "$dir sees $got skills, checkout has $EXPECTED"
+  canonical=$(CDPATH= cd -- "$AGENTS_DIR" 2>/dev/null && pwd -P)
+  if [ -n "$resolved" ] && [ -n "$canonical" ] && [ "$resolved" != "$canonical" ]; then
+    add FAIL outside "$dir resolves to $resolved, not the canonical $canonical"
   fi
 done
 
 # --- dangling links anywhere under the harness dirs -------------------------
-for dir in "$HOME/.agents/skills" "$HOME/.config/crush/skills" \
+for dir in "$HOME/.config/crush/skills" \
            "$HOME/.config/opencode/skills" "$HOME/.claude/skills"
 do
   [ -d "$dir" ] || continue