@thebassclef/lite 1.9.9 → 1.9.11

package/dist/lite/lib/capability-probe.sh

@@ -44,8 +44,46 @@ probe_gh_auth() {
 }
 
 probe_mcp_playwright() {
-  # V1 heuristic — env var contract. V2 may read tool inventory.
+  # Fast path — explicit opt-in via env var. Adopters who want to force the
+  # probe TRUE set CLAUDE_MCP_PLAYWRIGHT=1 in their shell init. Documented at
+  # docs/use-cases/UC-lib-capability-probe-mcp-fallback.md.
   [ -n "${CLAUDE_MCP_PLAYWRIGHT:-}" ] && return 0
+
+  # Fallback — look for a Playwright MCP server in known MCP config files.
+  # jq is required for parsing. When absent, the probe fails soft to 1.
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "probe_mcp_playwright: jq not found; env-var fast path only" >&2
+    return 1
+  fi
+
+  local project_dir="${CLAUDE_PROJECT_DIR:-.}"
+  local home_dir="${HOME:-}"
+
+  # Check paths in precedence order. First hit wins.
+  _probe_mcp_json_has_playwright "${project_dir}/.mcp.json"              && return 0
+  _probe_mcp_json_has_playwright "${project_dir}/.claude/settings.json"  && return 0
+  if [ -n "$home_dir" ]; then
+    _probe_mcp_json_has_playwright "${home_dir}/.claude/settings.json"   && return 0
+    _probe_mcp_json_has_playwright "${home_dir}/.claude.json"            && return 0
+  fi
+  return 1
+}
+
+# _probe_mcp_json_has_playwright <path>
+# Returns 0 when the JSON file names a Playwright MCP server. Checks two
+# shapes:
+#   1. Top-level "playwright" key (used by `.mcp.json` on some adopters)
+#   2. Nested "mcpServers.playwright" (used by `settings.json` + `~/.claude.json`)
+# Fail-soft on missing file + malformed JSON — returns 1 silently.
+# Per bassclef-upstream Finding #6 (#2036): `local path` is a zsh-magic variable
+# name — ties to $PATH when sourced from zsh. Renamed to `local p`.
+_probe_mcp_json_has_playwright() {
+  local p="$1"
+  [ -f "$p" ] || return 1
+  # Shape 1 — top-level playwright
+  jq -e '.playwright // empty' "$p" >/dev/null 2>&1 && return 0
+  # Shape 2 — nested mcpServers.playwright
+  jq -e '.mcpServers.playwright // empty' "$p" >/dev/null 2>&1 && return 0
   return 1
 }
 

package/dist/lite/lib/composer-preflight.sh

@@ -178,10 +178,14 @@ composer_preflight_check() {
     echo "check_5_recommendation="
     pass=$((pass + 1))
   elif [ -f "$repo_skill" ] || [ -L "$repo_skill" ]; then
-    echo "check_5_status=warn"
-    echo "check_5_message=Skill at repo-level only ($repo_skill); user-level symlink missing — harness may not pick up (bassclef#271)"
-    echo "check_5_recommendation=Run bassclef-sync.sh to create user-level symlink OR restart Claude session"
-    warn=$((warn + 1))
+    # Per cli#321 — Claude Code's harness loads project .claude/skills/
+    # directly; user-level symlinks are not required. Repo-level IS a
+    # valid discovery path. Previously flagged as WARN, trained adopters
+    # to ignore warnings. Now PASS with informational message.
+    echo "check_5_status=pass"
+    echo "check_5_message=Skill resolves at repo-level: $repo_skill (harness loads project .claude/skills directly)"
+    echo "check_5_recommendation="
+    pass=$((pass + 1))
   elif [ -n "${BASSCLEF_DIR:-}" ] && [ -f "$bassclef_skill" ]; then
     echo "check_5_status=warn"
     echo "check_5_message=Skill at bassclef only; consumer-side links missing — substrate sync incomplete"
@@ -265,6 +269,18 @@ composer_preflight_check() {
       echo "check_6_message=hosting_platform=none + --no-launch (variants-only run)"
       echo "check_6_recommendation="
       pass=$((pass + 1))
+    elif [ "$skill_name" = "build" ]; then
+      # cli#309 cure — /build has no --no-launch flag and its Phase 7 deploy
+      # is a documented stub (see .claude/skills/build/SKILL.md Phase 7). Warn
+      # (not fail) so dispatch proceeds; Phase 7 will emit a TODO rather than
+      # run a real deploy. Adopter can set a real hosting_platform when ready
+      # to use Phase 7 live.
+      # Anchor: @luminary tony-hoare (postcondition per skill) +
+      # @luminary michael-nygard (fail-soft when it does not matter).
+      echo "check_6_status=warn"
+      echo "check_6_message=hosting_platform=none — /build Phase 7 deploy is a stub; dispatch proceeds, deploy emits TODO instead of running"
+      echo "check_6_recommendation=Set hosting_platform to a deploy provider (amplify) when ready to live-deploy; see .claude/skills/build/SKILL.md Phase 7"
+      warn=$((warn + 1))
     else
       echo "check_6_status=fail"
       echo "check_6_message=hosting_platform=none — composer would generate variants that can't launch"

package/dist/lite/lib/install-written-paths.sh

@@ -0,0 +1,369 @@
+#!/bin/bash
+# tier: lite
+# Install-written-paths manifest + accessor lib.
+#
+# Records paths written by bassclef install writers so discipline hooks
+# can skip them. Per bassclef-upstream#2036 Finding #8 structural cure
+# (Kunal Slot 1). See docs/decompositions/2026-10-03-install-written-paths-manifest.md
+# for design + patterns applied (Repository + Deep Module + Null Object + Guard Clause).
+#
+# @pattern patterns/code/fowler/repository.md
+# @pattern patterns/code/ousterhout/deep-module.md
+#
+# Public API (5 verbs):
+#   install_written_paths_register <path> <writer>
+#   is_install_written_path <path>
+#   install_written_paths_rename <old-path> <new-path>
+#   install_written_paths_rebuild
+#   install_written_paths_verify
+#
+# Override: SKIP_INSTALL_WRITTEN_PATHS=1 — is_install_written_path returns 1 (false)
+# so hooks fire discipline normally (don't skip).
+#
+# Variable naming: internal locals use `tgt` (target path), `arg_*` prefix,
+# or `_iwp_*` namespace to avoid shadowing shell builtins. Reserved names
+# like `PATH`, `CDPATH`, `FPATH`, `MANPATH` are not used as locals per
+# shell-portability discipline (zsh treats lowercase `path` as array-tied
+# to PATH; renaming avoids the kill).
+
+set -u
+
+# ---- Constants ----
+
+_IWP_SCHEMA_VERSION="1.0.0"
+
+_IWP_WRITERS="bassclef-hook-connect bassclef-sync-template bassclef-sync-dispatcher schedule-auto-save bassclef-init-npm"
+
+# ---- Internal helpers ----
+
+_iwp_manifest_path() {
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  echo "$root/state/install-written-paths.json"
+}
+
+_iwp_log() {
+  if command -v trace_log >/dev/null 2>&1; then
+    trace_log "install-written-paths" "$*"
+  fi
+}
+
+_iwp_sha256() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo ""
+    return 1
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" 2>/dev/null | awk '{print "sha256:" $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file" 2>/dev/null | awk '{print "sha256:" $1}'
+  else
+    echo ""
+    return 1
+  fi
+}
+
+_iwp_valid_writer() {
+  local w="$1"
+  for valid in $_IWP_WRITERS; do
+    [ "$w" = "$valid" ] && return 0
+  done
+  return 1
+}
+
+_iwp_validate_path() {
+  local p="$1"
+  # Reject path traversal (any component equal to .. OR path exactly ..)
+  case "$p" in
+    *../*|..) return 1 ;;
+  esac
+  # Reject absolute paths outside $CLAUDE_PROJECT_DIR
+  case "$p" in
+    /*)
+      local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+      case "$p" in
+        "$root"/*) ;;
+        *) return 1 ;;
+      esac
+      ;;
+  esac
+  return 0
+}
+
+_iwp_ensure_manifest() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  if [ ! -f "$mpath" ]; then
+    mkdir -p "$(dirname "$mpath")"
+    cat > "$mpath" <<EOF
+{
+  "schema_version": "$_IWP_SCHEMA_VERSION",
+  "entries": []
+}
+EOF
+  fi
+}
+
+_iwp_manifest_valid() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  [ -f "$mpath" ] || return 1
+  jq -e . "$mpath" >/dev/null 2>&1 || return 1
+  return 0
+}
+
+# ---- Public API ----
+
+# install_written_paths_register <path> <writer>
+# Records a path as install-written. Idempotent on path.
+# Returns 0 on success, 1 on validation failure.
+install_written_paths_register() {
+  local tgt="${1:-}"
+  local writer="${2:-}"
+
+  if [ -z "$tgt" ] || [ -z "$writer" ]; then
+    echo "install-written-paths: register requires <path> <writer>" >&2
+    return 1
+  fi
+
+  if ! _iwp_validate_path "$tgt"; then
+    echo "install-written-paths: path '$tgt' rejected (traversal or outside project)" >&2
+    _iwp_log "register-rejected path=$tgt reason=traversal"
+    return 1
+  fi
+
+  if ! _iwp_valid_writer "$writer"; then
+    echo "install-written-paths: writer '$writer' not in allowed enum" >&2
+    _iwp_log "register-rejected path=$tgt writer=$writer reason=unknown-writer"
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available; cannot register" >&2
+    return 1
+  fi
+
+  _iwp_ensure_manifest
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_tgt
+  case "$tgt" in
+    /*) full_tgt="$tgt" ;;
+    *) full_tgt="$root/$tgt" ;;
+  esac
+
+  local hash
+  hash=$(_iwp_sha256 "$full_tgt")
+  if [ -z "$hash" ]; then
+    echo "install-written-paths: unable to compute hash for '$full_tgt'" >&2
+    return 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Use flock to serialize writes; fall back to no-lock on BSD without flock
+  local tmp
+  tmp=$(mktemp "$mpath.tmp.XXXXXX")
+
+  if command -v flock >/dev/null 2>&1; then
+    (
+      flock -x 9
+      jq --arg path "$tgt" --arg writer "$writer" --arg ts "$now" --arg hash "$hash" \
+        '.entries |= (map(select(.path != $path)) + [{"path": $path, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+        "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+    ) 9>"$mpath.lock"
+  else
+    jq --arg path "$tgt" --arg writer "$writer" --arg ts "$now" --arg hash "$hash" \
+      '.entries |= (map(select(.path != $path)) + [{"path": $path, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+      "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+  fi
+
+  rm -f "$tmp" 2>/dev/null || true
+  _iwp_log "register path=$tgt writer=$writer"
+  return 0
+}
+
+# is_install_written_path <path>
+# Returns 0 (true) when path in manifest AND content hash matches.
+# Returns 1 (false) otherwise.
+# Override: SKIP_INSTALL_WRITTEN_PATHS=1 forces return 1 (hooks fire normally).
+is_install_written_path() {
+  if [ -n "${SKIP_INSTALL_WRITTEN_PATHS:-}" ]; then
+    _iwp_log "check override SKIP_INSTALL_WRITTEN_PATHS=1 path=${1:-}"
+    return 1
+  fi
+
+  local tgt="${1:-}"
+  if [ -z "$tgt" ]; then
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  # Fail-soft: manifest missing or malformed → not install-written
+  if ! _iwp_manifest_valid; then
+    _iwp_log "check path=$tgt result=false reason=no-manifest-or-malformed"
+    [ -f "$mpath" ] && echo "install-written-paths: manifest malformed; treating as not-install-written" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    _iwp_log "check path=$tgt result=false reason=no-jq"
+    return 1
+  fi
+
+  # Look up entry
+  local recorded_hash
+  recorded_hash=$(jq -r --arg path "$tgt" '.entries[] | select(.path == $path) | .content_hash' "$mpath" 2>/dev/null)
+  if [ -z "$recorded_hash" ] || [ "$recorded_hash" = "null" ]; then
+    _iwp_log "check path=$tgt result=false reason=not-in-manifest"
+    return 1
+  fi
+
+  # Compute current hash
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_tgt
+  case "$tgt" in
+    /*) full_tgt="$tgt" ;;
+    *) full_tgt="$root/$tgt" ;;
+  esac
+
+  if [ ! -f "$full_tgt" ]; then
+    _iwp_log "check path=$tgt result=false reason=file-missing"
+    return 1
+  fi
+
+  local current_hash
+  current_hash=$(_iwp_sha256 "$full_tgt")
+  if [ -z "$current_hash" ]; then
+    _iwp_log "check path=$tgt result=false reason=hash-fail"
+    return 1
+  fi
+
+  if [ "$recorded_hash" = "$current_hash" ]; then
+    _iwp_log "check path=$tgt result=true reason=match"
+    return 0
+  else
+    _iwp_log "check path=$tgt result=false reason=hash-mismatch"
+    return 1
+  fi
+}
+
+# install_written_paths_rename <old-path> <new-path>
+# Moves entry; preserves writer; bumps written_at.
+install_written_paths_rename() {
+  local old="${1:-}"
+  local new="${2:-}"
+
+  if [ -z "$old" ] || [ -z "$new" ]; then
+    echo "install-written-paths: rename requires <old-path> <new-path>" >&2
+    return 1
+  fi
+
+  if ! _iwp_validate_path "$new"; then
+    echo "install-written-paths: new path '$new' rejected" >&2
+    return 1
+  fi
+
+  if ! _iwp_manifest_valid; then
+    echo "install-written-paths: manifest missing or malformed" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available" >&2
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  # Check old exists
+  local writer
+  writer=$(jq -r --arg path "$old" '.entries[] | select(.path == $path) | .writer' "$mpath" 2>/dev/null)
+  if [ -z "$writer" ] || [ "$writer" = "null" ]; then
+    echo "install-written-paths: '$old' not in manifest" >&2
+    return 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Compute hash from new location if it exists; else keep old hash
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_new
+  case "$new" in
+    /*) full_new="$new" ;;
+    *) full_new="$root/$new" ;;
+  esac
+
+  local new_hash
+  if [ -f "$full_new" ]; then
+    new_hash=$(_iwp_sha256 "$full_new")
+  else
+    new_hash=$(jq -r --arg path "$old" '.entries[] | select(.path == $path) | .content_hash' "$mpath")
+  fi
+
+  local tmp
+  tmp=$(mktemp "$mpath.tmp.XXXXXX")
+
+  jq --arg old "$old" --arg new "$new" --arg writer "$writer" --arg ts "$now" --arg hash "$new_hash" \
+    '.entries |= (map(select(.path != $old)) + [{"path": $new, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+    "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+
+  rm -f "$tmp" 2>/dev/null || true
+  _iwp_log "rename old=$old new=$new"
+  return 0
+}
+
+# install_written_paths_rebuild
+# Regenerates the manifest. V1: creates empty manifest when missing.
+# Future: walks install writers' known output locations.
+install_written_paths_rebuild() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  if [ -f "$mpath" ] && _iwp_manifest_valid; then
+    return 0
+  fi
+  rm -f "$mpath" 2>/dev/null || true
+  _iwp_ensure_manifest
+  _iwp_log "rebuild manifest=$mpath"
+  return 0
+}
+
+# install_written_paths_verify
+# Returns 0 on well-formed manifest, 1 on schema violation.
+install_written_paths_verify() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  if [ ! -f "$mpath" ]; then
+    echo "install-written-paths: manifest file missing at $mpath" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available" >&2
+    return 1
+  fi
+
+  if ! jq -e . "$mpath" >/dev/null 2>&1; then
+    echo "install-written-paths: manifest JSON malformed" >&2
+    return 1
+  fi
+
+  # Basic shape check — required top-level keys present
+  local has_version has_entries
+  has_version=$(jq -r 'has("schema_version")' "$mpath" 2>/dev/null)
+  has_entries=$(jq -r 'has("entries")' "$mpath" 2>/dev/null)
+  if [ "$has_version" != "true" ] || [ "$has_entries" != "true" ]; then
+    echo "install-written-paths: manifest missing required keys" >&2
+    return 1
+  fi
+
+  return 0
+}

package/dist/lite/lib/last-block.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/last-block.sh — persist and read BLOCK banners.
+#
+# Per @luminary john-ousterhout deep module: three narrow functions hide
+# the plaintext marker format. Callers persist, read, and list without
+# touching file layout.
+#
+# Exposed functions:
+#   record_last_block <hook> <severity> <message>   — write a marker
+#   read_last_block [<hook>]                        — read one marker (newest if no arg)
+#   list_last_blocks                                — list every marker newest first
+#
+# Marker format (plaintext, grep-friendly):
+#   hook: <hook-name>
+#   severity: blocking|advisory|info
+#   fired_at: <ISO-8601 UTC>
+#   session: <session-id or "unknown">
+#   ---
+#   <verbatim banner text, truncated to 8KB with [truncated] marker>
+#
+# Fail-soft: every write path returns 0 even on failure; stderr WARN
+# describes the problem. Per @luminary michael-nygard — a persistence lib
+# must never crash its caller.
+#
+# Per bassclef-upstream#2036 Finding #10 + UC-skill-last-block.md.
+
+# Resolve the marker directory. Caller overrides via LAST_BLOCK_DIR for
+# tests. Default is state/markers/last-block/ under CLAUDE_PROJECT_DIR
+# (fallback to current dir when unset).
+_last_block_dir() {
+  if [ -n "${LAST_BLOCK_DIR:-}" ]; then
+    echo "$LAST_BLOCK_DIR"
+  else
+    echo "${CLAUDE_PROJECT_DIR:-.}/state/markers/last-block"
+  fi
+}
+
+# record_last_block <hook> <severity> <message>
+# Writes a marker. Fail-soft on every error (returns 0; WARN to stderr).
+record_last_block() {
+  local hook="${1:-unknown}"
+  local severity="${2:-blocking}"
+  local message="${3:-}"
+  local dir
+  dir="$(_last_block_dir)"
+
+  # mkdir -p fail-soft — read-only disk, permission denied, etc.
+  if ! mkdir -p "$dir" 2>/dev/null; then
+    echo "record_last_block: cannot create '$dir' — marker not written" >&2
+    return 0
+  fi
+
+  # Truncate banner text to 8192 bytes to bound marker size.
+  local max_bytes=8192
+  local truncated=""
+  local body_bytes
+  body_bytes=$(printf '%s' "$message" | wc -c | tr -d ' ')
+  if [ "$body_bytes" -gt "$max_bytes" ]; then
+    message="$(printf '%s' "$message" | head -c "$max_bytes")"
+    truncated=$'\n[truncated — original was '"$body_bytes"' bytes]'
+  fi
+
+  local ts
+  ts="$(date -u +'%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo 'unknown')"
+  local session_id="${CLAUDE_SESSION_ID:-unknown}"
+  local marker="$dir/${hook}.marker"
+  local tmp="${marker}.tmp.$$"
+
+  {
+    printf 'hook: %s\n' "$hook"
+    printf 'severity: %s\n' "$severity"
+    printf 'fired_at: %s\n' "$ts"
+    printf 'session: %s\n' "$session_id"
+    printf '%s\n' '---'
+    printf '%s%s\n' "$message" "$truncated"
+  } > "$tmp" 2>/dev/null || {
+    echo "record_last_block: write to '$tmp' failed — marker not written" >&2
+    rm -f "$tmp" 2>/dev/null
+    return 0
+  }
+
+  if ! mv "$tmp" "$marker" 2>/dev/null; then
+    echo "record_last_block: rename to '$marker' failed — marker not written" >&2
+    rm -f "$tmp" 2>/dev/null
+    return 0
+  fi
+
+  return 0
+}
+
+# read_last_block [<hook>]
+# Prints a marker's banner. With a hook arg, reads that marker. With no
+# args, reads the newest marker by mtime. Returns 1 when no marker found.
+read_last_block() {
+  local dir
+  dir="$(_last_block_dir)"
+
+  if [ ! -d "$dir" ]; then
+    echo "no block recorded (no markers directory at $dir)" >&2
+    return 1
+  fi
+
+  local marker
+  if [ $# -ge 1 ] && [ -n "$1" ]; then
+    marker="$dir/${1}.marker"
+    if [ ! -f "$marker" ]; then
+      echo "no block recorded for '$1'" >&2
+      return 1
+    fi
+  else
+    # Newest by mtime. ls -t is intentional (sort-by-mtime is its purpose).
+    # shellcheck disable=SC2012
+    marker="$(ls -t "$dir"/*.marker 2>/dev/null | head -1)"
+    if [ -z "$marker" ]; then
+      echo "no block recorded this session or prior" >&2
+      return 1
+    fi
+  fi
+
+  cat "$marker"
+  return 0
+}
+
+# list_last_blocks
+# Lists every marker newest first — one line per marker with hook name,
+# severity, timestamp. Returns 1 when the directory is empty or absent.
+list_last_blocks() {
+  local dir
+  dir="$(_last_block_dir)"
+
+  if [ ! -d "$dir" ]; then
+    echo "no blocks recorded (no markers directory at $dir)" >&2
+    return 1
+  fi
+
+  local markers
+  # shellcheck disable=SC2012
+  markers="$(ls -t "$dir"/*.marker 2>/dev/null)"
+  if [ -z "$markers" ]; then
+    echo "no blocks recorded (directory empty)" >&2
+    return 1
+  fi
+
+  local m hook severity fired_at
+  echo "$markers" | while IFS= read -r m; do
+    hook="$(awk -F': ' '/^hook:/{print $2; exit}' "$m" 2>/dev/null)"
+    severity="$(awk -F': ' '/^severity:/{print $2; exit}' "$m" 2>/dev/null)"
+    fired_at="$(awk -F': ' '/^fired_at:/{print $2; exit}' "$m" 2>/dev/null)"
+    printf '%s\t%s\t%s\n' "$hook" "$severity" "$fired_at"
+  done
+  return 0
+}

package/dist/lite/lib/luminary-pick.sh

@@ -25,7 +25,7 @@
 #
 # Usage from a caller SKILL body:
 #
-#   source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+#   source "${BASSCLEF_DIR:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}/lib/luminary-pick.sh"
 #   CATALOG=$(luminary_pick_catalog)
 #   # then Claude reasons over $CATALOG + intent, writes JSON in-turn
 #
@@ -44,22 +44,44 @@ set -euo pipefail
 # Sort: alphabetical by slug.
 # Return: 0 on success (including empty catalog); non-zero if dir missing.
 luminary_pick_catalog() {
-  local basedir="${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}"
+  # Resolve basedir: BASSCLEF_DIR → CLAUDE_PROJECT_DIR → git root → pwd.
+  # cli#313 — the former fallback $HOME/src/sunj-labs/bassclef was the
+  # engineering team's own home path and failed for every adopter.
+  local basedir="${BASSCLEF_DIR:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
   local catalog_dir="${basedir}/state/luminary-implementations"
+  local lite_catalog="${basedir}/.claude/luminaries"
 
-  if [ ! -d "$catalog_dir" ]; then
-    echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir" >&2
-    return 2
+  if [ -d "$catalog_dir" ]; then
+    (
+      shopt -s nullglob
+      set +e
+      for f in "$catalog_dir"/*.json; do
+        jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
+      done | sort -u
+    )
+    return 0
   fi
 
-  (
-    shopt -s nullglob
-    set +e
-    for f in "$catalog_dir"/*.json; do
-      jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
-    done | sort -u
-  )
-  return 0
+  # Lite-tier fallback (cli#313): read frontmatter from .claude/luminaries/*.md.
+  # Every tier ships this directory; state/luminary-implementations/ is upstream-only.
+  if [ -d "$lite_catalog" ]; then
+    (
+      shopt -s nullglob
+      set +e
+      for f in "$lite_catalog"/*.md; do
+        local slug domain name
+        slug=$(awk '/^slug:[[:space:]]/{sub(/^slug:[[:space:]]*/,""); print; exit}' "$f")
+        domain=$(awk '/^primary_domain:[[:space:]]/{sub(/^primary_domain:[[:space:]]*/,""); print; exit}' "$f")
+        name=$(awk '/^name:[[:space:]]/{sub(/^name:[[:space:]]*/,""); print; exit}' "$f")
+        [ -z "$slug" ] && continue
+        echo "${slug} (${domain:-unknown}) — ${name:-$slug}"
+      done | sort -u
+    )
+    return 0
+  fi
+
+  echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir (and no .claude/luminaries/ fallback at $lite_catalog)" >&2
+  return 2
 }
 
 # Grace-window stub preserving the old function signature.