@thebassclef/lite 1.9.3 → 1.9.5

package/dist/lite/presence/install/bassclef-sync.template.sh

@@ -292,6 +292,42 @@ _template_emit_install_postcondition() {
   fi
 }
 
+# === #1981 — sync state file writer (parity with operator hook L688-707) ===
+# Persist sync state so lib/statusline-version.sh reader can render
+# `bassclef v<X> · <sync_status>` on the adopter terminal statusline every
+# ~300ms tick. Mirrors the operator-scope write block at
+# .claude/hooks/bassclef-sync.sh L688-707. Both hooks must produce the same
+# postcondition per ADR-032 two-stage rocket.
+#
+# Fail-soft: jq missing OR write path unwritable → file simply doesn't land;
+# reader falls back to `bassclef · initializing` per lib/statusline-version.sh L83-85.
+# Never break the sync summary that follows.
+#
+# Defined ABOVE the BASSCLEF_SYNC_TEST_MODE guard so tests can source + invoke.
+#
+# Anchor luminaries — @luminary michael-nygard (bounded-time observable state),
+# @luminary michael-feathers (mirrors the operator hook exactly — characterization
+# parity), @luminary jerome-saltzer-and-michael-schroeder (complete mediation
+# across both operator + adopter paths).
+_template_write_sync_status_file() {
+  local cwd="$1"
+  local sync_status="$2"
+  local status_file="${cwd}/state/bassclef-sync-status.json"
+  local version release_tag
+  version=$(jq -r '.version // ""' "${cwd}/bassclef-version.json" 2>/dev/null || echo "")
+  release_tag=$(jq -r '.release_tag // ""' "${cwd}/bassclef-version.json" 2>/dev/null || echo "")
+  mkdir -p "$(dirname "$status_file")" 2>/dev/null || return 0
+  cat > "$status_file" 2>/dev/null <<EOF
+{
+  "version": "${version}",
+  "release_tag": "${release_tag}",
+  "sync_status": "${sync_status}",
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+  return 0
+}
+
 # === Test-mode early return (#897 Cure A) ===
 # Tests source this template to access helper functions (see
 # .claude/hooks/tests/bassclef-sync-*.test.sh). Early return under
@@ -1936,6 +1972,13 @@ if [ -f "$HOOK_SELF" ] && [ -f "$HOOK_BASSCLEF" ]; then
   esac
 fi
 
+# --- Persist sync state for statusline reader (bassclef-upstream#1981) ---
+# Mirrors operator hook L688-707. Adopters who opt in to
+# lib/statusline-version.sh at ~/.claude/settings.json read this file at every
+# prompt to render `bassclef v<X> · <sync_status>`. Written here at end-of-run;
+# sole writer for the adopter path. Fail-soft — never break sync summary.
+{ _template_write_sync_status_file "$CWD" "$SYNC_STATUS"; } 2>/dev/null || true
+
 echo ""
 echo "### BASSCLEF SUBSTRATE — SYNCED"
 echo ""

package/dist/lite/scripts/generate-lite-manifest.sh

@@ -479,13 +479,15 @@ done < <(find "$REPO_ROOT/.claude/embeddings" -type f -name '*.json' 2>/dev/null
 LIB_FILES=()
 while IFS= read -r f; do
   LIB_FILES+=("$f")
-done < <(find "$REPO_ROOT/lib" -maxdepth 1 -type f -name '*.sh' 2>/dev/null | sort)
+done < <(find "$REPO_ROOT/lib" -type f -name '*.sh' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
 # Script files (bash) — per #1392 Shape 3; adopter runtime needs scripts/bassclef-*.sh helpers
 SCRIPT_FILES=()
 while IFS= read -r f; do
   SCRIPT_FILES+=("$f")
-done < <(find "$REPO_ROOT/scripts" -maxdepth 1 -type f -name '*.sh' 2>/dev/null | sort)
+done < <(find "$REPO_ROOT/scripts" -type f -name '*.sh' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
 # Hook fragments (bash) — per goal 2026-09-16a (bassclef-upstream#1690): session-reflection.sh
 # iterates session-reflection.d/*.sh at SessionStart; fragments ship as type=hook.
@@ -506,25 +508,29 @@ done < <(find "$REPO_ROOT/.claude" -maxdepth 1 -type f -name '*.md' 2>/dev/null
 PRESENCE_TEMPLATE_SH_FILES=()
 while IFS= read -r f; do
   PRESENCE_TEMPLATE_SH_FILES+=("$f")
-done < <(find "$REPO_ROOT/presence/install" -maxdepth 1 -type f -name '*.sh' 2>/dev/null | sort)
+done < <(find "$REPO_ROOT/presence/install" -type f -name '*.sh' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
 PRESENCE_TEMPLATE_MD_FILES=()
 while IFS= read -r f; do
   PRESENCE_TEMPLATE_MD_FILES+=("$f")
-done < <(find "$REPO_ROOT/presence/install" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort)
+done < <(find "$REPO_ROOT/presence/install" -type f -name '*.md' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
 # Presence templates (jsonc) — Ship 1 (bassclef-cli#104) — configs template
 # ships so `bassclef init` can copy it to adopter's `.claude/bassclef-configs.jsonc`.
 PRESENCE_TEMPLATE_JSONC_FILES=()
 while IFS= read -r f; do
   PRESENCE_TEMPLATE_JSONC_FILES+=("$f")
-done < <(find "$REPO_ROOT/presence/install" -maxdepth 1 -type f -name '*.jsonc' 2>/dev/null | sort)
+done < <(find "$REPO_ROOT/presence/install" -type f -name '*.jsonc' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
 # Templates (md) — per #1392 Shape 3; chronicle-template + iteration-goal etc adopters copy
 TEMPLATE_FILES=()
 while IFS= read -r f; do
   TEMPLATE_FILES+=("$f")
-done < <(find "$REPO_ROOT/templates" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort)
+done < <(find "$REPO_ROOT/templates" -type f -name '*.md' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
 # Root docs (md) — per #1392 Shape 3; README + CLAUDE + AGENTS adopters read on install
 ROOT_DOC_FILES=()

package/dist/lite/scripts/interpret-input/extract-repo.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# tier: lite
+# scripts/interpret-input/extract-repo.sh — Phase C repo extractor.
+#
+# Walks a local repo directory and extracts:
+# - README excerpt (first 30 lines of README.md or equivalent)
+# - Title (first H1 in README, or repo dirname)
+# - Domain entity candidates (Prisma models + directory-pattern heuristic)
+# - Boundary objects (Next.js routes, pages, API endpoints)
+# - Actor candidates (role/auth keywords in source)
+#
+# Outputs JSON to stdout. Wrapper composes into the InputArtifact.
+#
+# Usage:
+#   bash scripts/interpret-input/extract-repo.sh <local-repo-path>
+#
+# Exit codes:
+#   0 = success (even partial extraction is success — empty arrays for missing signals)
+#   2 = bad input (missing path or not a directory)
+#
+# Pairs with: scripts/interpret-input.sh + standards/input-handler-interface.md
+
+set -u
+
+REPO_PATH="${1:-}"
+
+if [ -z "$REPO_PATH" ]; then
+  echo "extract-repo: requires <repo-path>" >&2
+  exit 2
+fi
+
+if [ ! -d "$REPO_PATH" ]; then
+  echo "extract-repo: $REPO_PATH is not a directory" >&2
+  exit 2
+fi
+
+# Use absolute path so cd doesn't break relative output
+REPO_PATH="$(cd "$REPO_PATH" && pwd)"
+cd "$REPO_PATH" || { echo "extract-repo: cannot cd to $REPO_PATH" >&2; exit 2; }
+
+# === README excerpt + title ===
+README_EXCERPT=""
+README_PATH=""
+for candidate in README.md README.MD readme.md README.rst README.txt; do
+  if [ -f "$candidate" ]; then
+    README_PATH="$candidate"
+    README_EXCERPT=$(head -30 "$candidate")
+    break
+  fi
+done
+
+TITLE=""
+if [ -n "$README_PATH" ]; then
+  TITLE=$(grep -m1 '^# ' "$README_PATH" 2>/dev/null | sed 's/^# *//')
+fi
+if [ -z "$TITLE" ]; then
+  TITLE=$(basename "$REPO_PATH")
+fi
+
+# === Entity candidates ===
+
+# Strategy 1: Prisma models
+ENTITIES_PRISMA=()
+for schema in prisma/schema.prisma prisma/*.prisma; do
+  if [ -f "$schema" ]; then
+    while IFS= read -r model_name; do
+      [ -z "$model_name" ] && continue
+      ENTITIES_PRISMA+=("$model_name")
+    done < <(grep -E '^model [A-Z][a-zA-Z]+' "$schema" 2>/dev/null | awk '{print $2}')
+  fi
+done
+
+# Strategy 2: directory-pattern entities
+# A directory containing >=3 files/subdirs of consistent shape suggests a collection.
+# The singularized dirname is a candidate entity.
+ENTITIES_DIR=()
+
+# Collect candidate dirs at depth <=4, skipping known noise
+CANDIDATE_DIRS=$(find . -maxdepth 4 -mindepth 1 -type d \
+  -not -path '*/node_modules*' \
+  -not -path '*/.git*' \
+  -not -path '*/.next*' \
+  -not -path '*/dist*' \
+  -not -path '*/build*' \
+  -not -path '*/coverage*' \
+  -not -path '*/__pycache__*' \
+  2>/dev/null)
+
+while IFS= read -r dir; do
+  [ -z "$dir" ] && continue
+  DIRNAME=$(basename "$dir")
+  case "$DIRNAME" in
+    .|..|node_modules|.git|.next|dist|build|coverage|__tests__|tests|test|src|lib|components|utils|public|static|scripts|bin|hooks) continue ;;
+  esac
+  # Only consider directories whose name suggests a collection (plural-ish)
+  case "$DIRNAME" in
+    *s|*ies)
+      # Count direct children
+      COUNT=$(find "$dir" -maxdepth 1 -mindepth 1 \
+        \( -type d -o -name '*.md' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.json' -o -name '*.yml' -o -name '*.yaml' \) \
+        2>/dev/null | wc -l | tr -d ' ')
+      if [ "$COUNT" -ge 3 ]; then
+        # Singularize: ies → y; ses/xes/zes/ches/shes → strip "es"; else strip "s"
+        case "$DIRNAME" in
+          *ies)                       SINGULAR="${DIRNAME%ies}y" ;;
+          *ses|*xes|*zes|*ches|*shes) SINGULAR="${DIRNAME%es}" ;;
+          *s)                         SINGULAR="${DIRNAME%s}" ;;
+        esac
+        # Skip too-short or too-noisy singulars
+        if [ "${#SINGULAR}" -ge 3 ]; then
+          ENTITIES_DIR+=("$SINGULAR")
+        fi
+      fi
+      ;;
+  esac
+done <<<"$CANDIDATE_DIRS"
+
+# Combine + dedupe entities
+ALL_ENTITIES=()
+SEEN=""
+for e in "${ENTITIES_PRISMA[@]:-}" "${ENTITIES_DIR[@]:-}"; do
+  [ -z "$e" ] && continue
+  case " $SEEN " in
+    *" $e "*) ;;
+    *) ALL_ENTITIES+=("$e"); SEEN="$SEEN $e" ;;
+  esac
+done
+
+# === Boundary objects (routes + pages + API endpoints) ===
+BOUNDARY_OBJECTS=()
+
+# Next.js App Router routes (app/**/page.{ts,tsx,js,jsx})
+for app_dir in app src/app; do
+  if [ -d "$app_dir" ]; then
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      # Convert path to route: app/deals/page.tsx → /deals
+      ROUTE=$(echo "$f" | sed -E "s|^./${app_dir}||" | sed 's|/page\.[a-zA-Z]*$||')
+      [ -z "$ROUTE" ] && ROUTE="/"
+      BOUNDARY_OBJECTS+=("route:$ROUTE")
+    done < <(find "./$app_dir" -maxdepth 6 \( -name 'page.tsx' -o -name 'page.ts' -o -name 'page.js' -o -name 'page.jsx' \) 2>/dev/null | head -50)
+  fi
+done
+
+# Next.js Pages Router routes (pages/**/*.{ts,tsx,js,jsx})
+for pages_dir in pages src/pages; do
+  if [ -d "$pages_dir" ]; then
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      ROUTE=$(echo "$f" | sed -E "s|^./${pages_dir}||" | sed 's/\.[a-zA-Z]*$//')
+      [ -z "$ROUTE" ] && ROUTE="/"
+      BOUNDARY_OBJECTS+=("page:$ROUTE")
+    done < <(find "./$pages_dir" -maxdepth 6 -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.js' -o -name '*.jsx' \) -not -name '_*' -not -name 'api' 2>/dev/null | head -30)
+  fi
+done
+
+# API routes
+for api_dir in app/api src/app/api pages/api src/pages/api; do
+  if [ -d "$api_dir" ]; then
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      ROUTE=$(echo "$f" | sed -E "s|^./${api_dir}||" | sed 's|/route\.[a-zA-Z]*$||' | sed 's/\.[a-zA-Z]*$//')
+      [ -z "$ROUTE" ] && ROUTE="/"
+      BOUNDARY_OBJECTS+=("api:$ROUTE")
+    done < <(find "./$api_dir" -maxdepth 6 -type f \( -name 'route.ts' -o -name 'route.tsx' -o -name 'route.js' -o -name '*.ts' \) 2>/dev/null | head -20)
+  fi
+done
+
+# === Actor candidates ===
+# Heuristic: grep role/auth keywords in source code
+ACTOR_CANDIDATES=()
+ACTOR_RAW=$(grep -rEho \
+  '\b(admin|owner|operator|viewer|editor|guest|member|customer|client|reviewer|approver|manager)\b' \
+  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.prisma' --include='*.md' \
+  --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next --exclude-dir=dist --exclude-dir=build \
+  . 2>/dev/null | tr '[:upper:]' '[:lower:]' | sort -u | head -10)
+
+while IFS= read -r kw; do
+  [ -z "$kw" ] && continue
+  ACTOR_CANDIDATES+=("$kw")
+done <<<"$ACTOR_RAW"
+
+# === Compose extracted_text prose ===
+ENTITY_LIST=$(IFS=,; echo "${ALL_ENTITIES[*]:-}")
+ACTOR_LIST=$(IFS=,; echo "${ACTOR_CANDIDATES[*]:-}")
+BOUNDARY_COUNT=${#BOUNDARY_OBJECTS[@]}
+
+EXTRACTED_TEXT="Repository: $TITLE
+Path: $REPO_PATH
+
+Detected entities (${#ALL_ENTITIES[@]}): ${ENTITY_LIST:-none}
+Detected actors (${#ACTOR_CANDIDATES[@]}): ${ACTOR_LIST:-none}
+Detected boundary objects: ${BOUNDARY_COUNT} routes/pages/api endpoints"
+
+if [ -n "$README_EXCERPT" ]; then
+  EXTRACTED_TEXT="${EXTRACTED_TEXT}
+
+README excerpt:
+${README_EXCERPT}"
+fi
+
+# === Build JSON output ===
+# Convert arrays to JSON; handle empty arrays explicitly (bash 3.x compat — no namerefs).
+if [ ${#ALL_ENTITIES[@]} -eq 0 ]; then
+  ENTITIES_JSON='[]'
+else
+  ENTITIES_JSON=$(printf '%s\n' "${ALL_ENTITIES[@]}" | jq -R . | jq -s -c '. | unique')
+fi
+
+if [ ${#ACTOR_CANDIDATES[@]} -eq 0 ]; then
+  ACTORS_JSON='[]'
+else
+  ACTORS_JSON=$(printf '%s\n' "${ACTOR_CANDIDATES[@]}" | jq -R . | jq -s -c '. | unique')
+fi
+
+if [ ${#BOUNDARY_OBJECTS[@]} -eq 0 ]; then
+  BOUNDARY_JSON='[]'
+else
+  BOUNDARY_JSON=$(printf '%s\n' "${BOUNDARY_OBJECTS[@]}" | jq -R . | jq -s -c '. | unique')
+fi
+
+# Output
+jq -n \
+  --arg extracted_text "$EXTRACTED_TEXT" \
+  --arg title "$TITLE" \
+  --arg readme_excerpt "$README_EXCERPT" \
+  --argjson entities_seen "$ENTITIES_JSON" \
+  --argjson actor_candidates "$ACTORS_JSON" \
+  --argjson boundary_objects "$BOUNDARY_JSON" \
+  '{
+    extracted_text: $extracted_text,
+    structural_hints: {
+      entities_seen: $entities_seen,
+      actor_candidates: $actor_candidates,
+      boundary_objects: $boundary_objects,
+      readme_excerpt: $readme_excerpt,
+      title: $title
+    }
+  }'

package/dist/lite/scripts/interpret-input.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# tier: lite
+# scripts/interpret-input.sh — input-handler CLI wrapper.
+#
+# Phase B: text-mode fully; other modes return stub InputArtifacts
+# (schema-valid; extracted_text="deferred to Phase C").
+#
+# Usage:
+#   bash scripts/interpret-input.sh "<source>" [--type=auto|text|url|image|repo|transcript|napkin|mixed] [--persist] [--slug=<slug>]
+#
+# Output:
+#   --persist OFF (default): InputArtifact JSON to stdout
+#   --persist ON: JSON written to docs/input-artifacts/<slug>.json; stdout = path
+#
+# Exit codes:
+#   0 = success
+#   2 = invalid input
+#   3 = jq construction failed
+#   4 = filesystem error (overwrite or mkdir)
+#   5 = repo extraction setup failed (clone error, mktemp error)
+#
+# Pairs with: standards/input-handler-interface.md + .claude/skills/interpret-input/SKILL.md
+
+set -u
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+usage() {
+  cat <<'EOF'
+/interpret-input — produce schema-validated InputArtifact from any input
+
+Usage:
+  bash scripts/interpret-input.sh "<source>" [flags]
+
+Flags:
+  --type=<type>     text|url|image|repo|transcript|napkin|mixed (default: auto)
+  --persist         write to docs/input-artifacts/<slug>.json
+  --slug=<slug>     override auto-generated slug
+  --help            show this message
+
+Auto-detection:
+  ^https?://                                → url
+  \.(png|jpg|jpeg|gif|webp|svg)$            → image
+  \.git$ or contains github.com             → repo
+  (else)                                    → text
+
+Phase B: text fully; other modes stub (extracted_text="deferred to Phase C").
+EOF
+}
+
+SOURCE=""
+TYPE="auto"
+PERSIST=0
+SLUG=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --type=*) TYPE="${1#--type=}"; shift ;;
+    --persist) PERSIST=1; shift ;;
+    --slug=*) SLUG="${1#--slug=}"; shift ;;
+    --help|-h) usage; exit 0 ;;
+    --*) echo "interpret-input: unknown flag '$1'" >&2; usage >&2; exit 2 ;;
+    *)
+      if [ -z "$SOURCE" ]; then SOURCE="$1"; shift
+      else echo "interpret-input: multiple positional sources not supported in v0" >&2; exit 2
+      fi
+      ;;
+  esac
+done
+
+if [ -z "$SOURCE" ]; then
+  echo "interpret-input: requires <source>" >&2
+  usage >&2
+  exit 2
+fi
+
+# Auto-detect type
+if [ "$TYPE" = "auto" ]; then
+  if echo "$SOURCE" | grep -qE '^https?://'; then
+    TYPE="url"
+  elif echo "$SOURCE" | grep -qiE '\.(png|jpg|jpeg|gif|webp|svg)$'; then
+    TYPE="image"
+  elif echo "$SOURCE" | grep -qE '\.git$'; then
+    TYPE="repo"
+  elif [ -d "$SOURCE" ] && [ -d "$SOURCE/.git" ]; then
+    # Local directory that's a git repo
+    TYPE="repo"
+  else
+    TYPE="text"
+  fi
+fi
+
+# Validate type against schema enum
+case "$TYPE" in
+  text|url|image|repo|transcript|napkin|mixed) ;;
+  *)
+    echo "interpret-input: unknown type '$TYPE' (must be: text|url|image|repo|transcript|napkin|mixed)" >&2
+    exit 2
+    ;;
+esac
+
+# Generate slug if not provided
+if [ -z "$SLUG" ]; then
+  TS=$(date -u +%Y-%m-%d)
+  HASH=$(printf '%s' "$SOURCE" | md5 -q 2>/dev/null \
+       || printf '%s' "$SOURCE" | md5sum 2>/dev/null | cut -c1-6 \
+       || echo "abc123")
+  HASH="${HASH:0:6}"
+  SLUG="${TS}-${TYPE}-${HASH}"
+fi
+
+# Validate slug pattern (matches schema's id pattern)
+if ! echo "$SLUG" | grep -qE '^[a-z0-9][a-z0-9-]*$'; then
+  echo "interpret-input: slug '$SLUG' does not match required pattern ^[a-z0-9][a-z0-9-]*$" >&2
+  exit 2
+fi
+
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+STRUCTURAL_HINTS='{}'
+
+case "$TYPE" in
+  text)
+    EXTRACTED_TEXT="$SOURCE"
+    EXTERNAL_URLS=$(printf '%s' "$SOURCE" | grep -oE 'https?://[^[:space:]<>"`]+' \
+      | sed 's/[.,;:)]*$//' \
+      | jq -R . | jq -s -c . 2>/dev/null || echo '[]')
+    ;;
+  repo)
+    # Phase C: walk a local repo or clone a URL, extract structural signals.
+    # Resolve source to a local path. If the source isn't a URL or an existing
+    # directory, fall back to stub mode (preserves Phase B contract for
+    # not-yet-extractable sources).
+    CLEANUP_TMP=0
+    REPO_LOCAL=""
+    if echo "$SOURCE" | grep -qE '^https?://'; then
+      TMP_DIR=$(mktemp -d 2>/dev/null) || { echo "interpret-input: mktemp failed" >&2; exit 5; }
+      if ! git clone --depth=1 --quiet "$SOURCE" "$TMP_DIR" 2>/dev/null; then
+        rm -rf "$TMP_DIR"
+        echo "interpret-input: git clone failed for $SOURCE" >&2
+        exit 5
+      fi
+      REPO_LOCAL="$TMP_DIR"
+      CLEANUP_TMP=1
+    elif [ -d "$SOURCE" ]; then
+      REPO_LOCAL="$SOURCE"
+    fi
+
+    if [ -z "$REPO_LOCAL" ]; then
+      # Source can't be resolved; return Phase B-style stub (still valid InputArtifact)
+      EXTRACTED_TEXT="deferred to Phase C"
+      STRUCTURAL_HINTS='{}'
+    else
+      EXTRACT_OUT=$(bash "$REPO_ROOT/scripts/interpret-input/extract-repo.sh" "$REPO_LOCAL" 2>/dev/null)
+      EXTRACT_RC=$?
+
+      if [ "$CLEANUP_TMP" = "1" ]; then
+        rm -rf "$TMP_DIR"
+      fi
+
+      if [ "$EXTRACT_RC" != "0" ] || [ -z "$EXTRACT_OUT" ]; then
+        EXTRACTED_TEXT="repo extraction returned no signal for $SOURCE"
+        STRUCTURAL_HINTS='{}'
+      else
+        EXTRACTED_TEXT=$(echo "$EXTRACT_OUT" | jq -r '.extracted_text')
+        STRUCTURAL_HINTS=$(echo "$EXTRACT_OUT" | jq -c '.structural_hints')
+      fi
+    fi
+    EXTERNAL_URLS='[]'
+    ;;
+  *)
+    EXTRACTED_TEXT="deferred to Phase C"
+    EXTERNAL_URLS='[]'
+    ;;
+esac
+
+ARTIFACT=$(jq -n \
+  --arg id "$SLUG" \
+  --arg type "$TYPE" \
+  --arg source "$SOURCE" \
+  --arg extracted_text "$EXTRACTED_TEXT" \
+  --arg created_at "$NOW" \
+  --argjson external_urls "$EXTERNAL_URLS" \
+  --argjson structural_hints "$STRUCTURAL_HINTS" \
+  '{
+    id: $id,
+    type: $type,
+    source: $source,
+    extracted_text: $extracted_text,
+    structural_hints: $structural_hints,
+    external_urls: $external_urls,
+    created_at: $created_at
+  }')
+
+if [ -z "$ARTIFACT" ]; then
+  echo "interpret-input: jq failed to construct InputArtifact JSON" >&2
+  exit 3
+fi
+
+if [ "$PERSIST" = "1" ]; then
+  TARGET_DIR="docs/input-artifacts"
+  TARGET_PATH="${TARGET_DIR}/${SLUG}.json"
+  if [ -f "$TARGET_PATH" ]; then
+    echo "interpret-input: $TARGET_PATH already exists; --slug=<new> to write a different one" >&2
+    exit 4
+  fi
+  mkdir -p "$TARGET_DIR" || { echo "interpret-input: mkdir $TARGET_DIR failed" >&2; exit 4; }
+  echo "$ARTIFACT" | jq . > "$TARGET_PATH" || { echo "interpret-input: write $TARGET_PATH failed" >&2; exit 4; }
+  echo "$TARGET_PATH"
+else
+  echo "$ARTIFACT" | jq .
+fi

package/dist/lite/scripts/launch/local-serve-stop.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# tier: lite
+# local-serve-stop.sh — stop a local-serve.sh server by slug
+#
+# Per bassclef#923 A2. Companion to scripts/launch/local-serve.sh.
+#
+# Usage:
+#   bash scripts/launch/local-serve-stop.sh <gallery-slug>
+#
+# If a server is running for the slug, kills the PID and removes the
+# state file. If no server is running, exits 0 silently.
+
+set -e
+
+SLUG="${1:-}"
+if [ -z "$SLUG" ]; then
+  echo "ERROR: gallery-slug required" >&2
+  echo "usage: $0 <gallery-slug>" >&2
+  exit 2
+fi
+
+STATE_DIR="${REPO_ROOT:-$(pwd)}/state/markers/local-serve"
+STATE_FILE="$STATE_DIR/${SLUG}.state"
+
+if [ ! -f "$STATE_FILE" ]; then
+  echo "local-serve-stop: no state file for $SLUG — nothing to stop" >&2
+  exit 0
+fi
+
+PID=$(awk -F= '/^pid=/{print $2}' "$STATE_FILE" 2>/dev/null)
+URL=$(awk -F= '/^url=/{print $2}' "$STATE_FILE" 2>/dev/null)
+
+if [ -n "$PID" ] && kill -0 "$PID" 2>/dev/null; then
+  kill "$PID" 2>/dev/null || true
+  echo "local-serve-stop: stopped server at $URL (pid=$PID)" >&2
+else
+  echo "local-serve-stop: state file present but PID $PID not alive — cleaning up" >&2
+fi
+
+rm -f "$STATE_FILE" "${STATE_DIR}/${SLUG}.log"
+exit 0