create-egregore 0.19.3 → 0.19.6

package/runtime/pi/bin/dashboard-data.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+# Fetches personal dashboard data: single API call + parallel git ops.
+# Usage: bash bin/dashboard-data.sh [username] [time_range]
+# Returns a single JSON object with all query results.
+#
+# time_range: P1D (today), P7D (week, default), P30D (month), P365D (all)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+TMPDIR=$(mktemp -d)
+trap "rm -rf $TMPDIR" EXIT
+
+# --- Read config ---
+API_URL=$(jq -r '.api_url // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+API_KEY=$(grep '^EGREGORE_API_KEY=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)
+ORG=$(jq -r '.org_name // "Egregore"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo "Egregore")
+DATE=$(date '+%b %d')
+
+# --- Detect user ---
+GH_USER="${1:-}"
+if [ -z "$GH_USER" ]; then
+  STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
+  if [ -f "$STATE_FILE" ]; then
+    GH_USER=$(jq -r '.github_username // empty' "$STATE_FILE" 2>/dev/null)
+  fi
+  if [ -z "$GH_USER" ]; then
+    GH_USER=$(git -C "$SCRIPT_DIR" config user.name 2>/dev/null || echo "unknown")
+  fi
+fi
+
+# --- Time range (default P7D) ---
+TIME_RANGE="${2:-P7D}"
+
+# --- Read current session ID (client-side fallback for WAL-not-yet-drained) ---
+PROJ_HASH=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
+SESSION_ID=$(cat "$HOME/.egregore/session-${PROJ_HASH}.id" 2>/dev/null || echo "")
+
+# --- Fire API call + git ops in parallel ---
+
+# Graph data: single API call (all queries run server-side)
+(
+  GRAPH_STATUS="offline"
+  GRAPH_REASON=""
+  if [ -z "$API_URL" ] || [ -z "$API_KEY" ]; then
+    GRAPH_REASON="missing_config"
+  else
+    # Keep curl's transport status separate from %{http_code}; otherwise a
+    # failed request can concatenate 000 + fallback text and look like an
+    # unexpected API response.
+    CURL_STATUS=0
+    HTTP_CODE=$(curl -s -o "$TMPDIR/dashboard_raw.json" -w "%{http_code}" \
+      "${API_URL}/api/personal/dashboard?github_username=$(printf '%s' "$GH_USER" | jq -sRr @uri)&time_range=$(printf '%s' "$TIME_RANGE" | jq -sRr @uri)&session_id=$(printf '%s' "$SESSION_ID" | jq -sRr @uri)" \
+      -H "Authorization: Bearer $API_KEY" \
+      --connect-timeout 5 --max-time 15 2>/dev/null) || CURL_STATUS=$?
+
+    if [ "$CURL_STATUS" -ne 0 ] || [ "$HTTP_CODE" = "000" ] || ! [[ "$HTTP_CODE" =~ ^[0-9][0-9][0-9]$ ]]; then
+      GRAPH_REASON="unreachable"
+    elif [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "403" ]; then
+      GRAPH_REASON="auth_error"
+    elif [ "$HTTP_CODE" -ge 500 ] 2>/dev/null; then
+      GRAPH_REASON="server_error"
+    elif [ -s "$TMPDIR/dashboard_raw.json" ] && jq -e '.me' "$TMPDIR/dashboard_raw.json" >/dev/null 2>&1; then
+      cp "$TMPDIR/dashboard_raw.json" "$TMPDIR/dashboard.json"
+      GRAPH_STATUS="connected"
+    else
+      GRAPH_REASON="invalid_response"
+    fi
+  fi
+
+  # If not connected, write status-only response
+  if [ "$GRAPH_STATUS" != "connected" ]; then
+    jq -n --arg status "$GRAPH_STATUS" --arg reason "$GRAPH_REASON" \
+      '{graph_status: $status, graph_reason: $reason}' > "$TMPDIR/dashboard.json"
+  else
+    jq --arg status "$GRAPH_STATUS" '. + {graph_status: $status}' \
+      "$TMPDIR/dashboard.json" > "$TMPDIR/dashboard_merged.json" \
+      && mv "$TMPDIR/dashboard_merged.json" "$TMPDIR/dashboard.json"
+  fi
+) &
+API_PID=$!
+
+# Git: branch + dirty status (parallel, stays client-side)
+(
+  CURRENT=$(git -C "$SCRIPT_DIR" branch --show-current 2>/dev/null || echo "unknown")
+  DIRTY="false"
+  if [ -n "$(git -C "$SCRIPT_DIR" status --porcelain 2>/dev/null | head -1)" ]; then
+    DIRTY="true"
+  fi
+  jq -n --arg branch "$CURRENT" --argjson dirty "$DIRTY" \
+    '{branch: $branch, dirty: $dirty}' > "$TMPDIR/git.json"
+) &
+GIT_PID=$!
+
+# Local sessions: parse memory files when graph is offline (parallel)
+(
+  GH_LC=$(echo "$GH_USER" | tr '[:upper:]' '[:lower:]')
+  DISPLAY_LC=""
+  if [ -f "$SCRIPT_DIR/.egregore-state.json" ]; then
+    DISPLAY_LC=$(jq -r '.display_name // empty' "$SCRIPT_DIR/.egregore-state.json" 2>/dev/null | tr '[:upper:]' '[:lower:]')
+  fi
+
+  # Compute cutoff date from time range
+  case "$TIME_RANGE" in
+    P1D)   CUTOFF=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d '1 day ago' +%Y-%m-%d 2>/dev/null || echo "2000-01-01") ;;
+    P7D)   CUTOFF=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d '7 days ago' +%Y-%m-%d 2>/dev/null || echo "2000-01-01") ;;
+    P30D)  CUTOFF=$(date -v-30d +%Y-%m-%d 2>/dev/null || date -d '30 days ago' +%Y-%m-%d 2>/dev/null || echo "2000-01-01") ;;
+    P365D) CUTOFF="2000-01-01" ;;
+    *)     CUTOFF=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d '7 days ago' +%Y-%m-%d 2>/dev/null || echo "2000-01-01") ;;
+  esac
+
+  # Scan sessions, wraps, and handoffs for this user
+  for DIR in "$SCRIPT_DIR/memory/sessions" "$SCRIPT_DIR/memory/wraps" "$SCRIPT_DIR/memory/handoffs"; do
+    [ -d "$DIR" ] || continue
+    TYPE=$(basename "$DIR")
+    find -L "$DIR" -name '*.md' -not -name 'index*' -type f 2>/dev/null | xargs ls -t 2>/dev/null | head -20 | while read -r MFILE; do
+      [ -z "$MFILE" ] && continue
+      M_AUTH=$(head -10 "$MFILE" 2>/dev/null | grep -m1 '^\*\*Author\*\*:' | sed 's/^\*\*Author\*\*:[[:space:]]*//' || true)
+      [ -z "$M_AUTH" ] && continue
+      M_AUTH_LC=$(echo "$M_AUTH" | tr '[:upper:]' '[:lower:]')
+      # Filter to this user only
+      [ "$M_AUTH_LC" != "$GH_LC" ] && { [ -z "$DISPLAY_LC" ] || [ "$M_AUTH_LC" != "$DISPLAY_LC" ]; } && continue
+      M_DATE=$(head -10 "$MFILE" 2>/dev/null | grep -m1 '^\*\*Date\*\*:' | sed 's/^\*\*Date\*\*:[[:space:]]*//' || true)
+      M_DAY="${M_DATE%%T*}"
+      [ -n "$M_DAY" ] && [ "$M_DAY" \< "$CUTOFF" ] && continue
+      M_BRANCH=$(head -10 "$MFILE" 2>/dev/null | grep -m1 '^\*\*Branch\*\*:' | sed 's/^\*\*Branch\*\*:[[:space:]]*//' || true)
+      M_DURATION=$(head -10 "$MFILE" 2>/dev/null | grep -m1 '^\*\*Duration\*\*:' | sed 's/^\*\*Duration\*\*:[[:space:]]*//' || true)
+      M_TOPIC=$(head -3 "$MFILE" 2>/dev/null | grep -m1 '^# ' | sed 's/^# [^:]*:[[:space:]]*//' || true)
+      echo "${M_DATE}|${M_TOPIC}|${M_BRANCH}|${M_DURATION}|${TYPE}"
+    done
+  done | jq -Rn '
+    [inputs | split("|") |
+      {date: .[0], topic: .[1], branch: .[2], duration: .[3], type: .[4]}
+    ] | sort_by(.date) | reverse | {
+      sessions: .,
+      session_count: length
+    }
+  ' 2>/dev/null > "$TMPDIR/local_sessions.json" || echo '{"sessions":[],"session_count":0}' > "$TMPDIR/local_sessions.json"
+) &
+LOCAL_PID=$!
+
+# --- Wait for all ---
+wait $API_PID $GIT_PID $LOCAL_PID 2>/dev/null || true
+
+# --- Read results ---
+GIT_INFO=$(cat "$TMPDIR/git.json" 2>/dev/null || echo '{"branch":"unknown","dirty":false}')
+BRANCH=$(echo "$GIT_INFO" | jq -r '.branch' 2>/dev/null || echo "unknown")
+LOCAL_SESSIONS=$(cat "$TMPDIR/local_sessions.json" 2>/dev/null || echo '{"sessions":[],"session_count":0}')
+echo "$LOCAL_SESSIONS" | jq . >/dev/null 2>&1 || LOCAL_SESSIONS='{"sessions":[],"session_count":0}'
+
+# --- Client-side current session fallback ---
+# If the graph returned no current_session (WAL hasn't drained yet),
+# inject one from the local session ID file so the TUI always renders it.
+DASHBOARD=$(cat "$TMPDIR/dashboard.json" 2>/dev/null || echo '{"graph_status":"offline"}')
+CS_ID=$(echo "$DASHBOARD" | jq -r '.current_session.id // empty' 2>/dev/null)
+if [ -z "$CS_ID" ] && [ -n "$SESSION_ID" ]; then
+  DASHBOARD=$(echo "$DASHBOARD" | jq \
+    --arg sid "$SESSION_ID" \
+    --arg branch "$BRANCH" \
+    '.current_session = {id: $sid, status: "active", topic: null, branch: $branch}' 2>/dev/null || echo "$DASHBOARD")
+fi
+
+# --- Derive time range label ---
+case "$TIME_RANGE" in
+  P1D)   RANGE_LABEL="today" ;;
+  P7D)   RANGE_LABEL="last 7 days" ;;
+  P30D)  RANGE_LABEL="last 30 days" ;;
+  P365D) RANGE_LABEL="all time" ;;
+  *)     RANGE_LABEL="last 7 days" ;;
+esac
+
+# --- Merge server response + local data ---
+echo "$DASHBOARD" | jq \
+  --arg org "$ORG" \
+  --arg date "$DATE" \
+  --arg range_label "$RANGE_LABEL" \
+  --argjson git "$GIT_INFO" \
+  --argjson local_sessions "$LOCAL_SESSIONS" \
+  '. + {org: $org, date: $date, range_label: $range_label, git: $git, local_sessions: $local_sessions}'

package/runtime/pi/bin/graph-batch.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+set -euo pipefail
+
+# Execute multiple Cypher queries in a single HTTP call.
+# Usage: graph-batch.sh '<json array of {statement, parameters} objects>'
+#
+# Example:
+#   graph-batch.sh '[{"statement":"MATCH (p:Person) RETURN p.name"},{"statement":"MATCH (q:Quest) RETURN q.id"}]'
+#
+# Returns: {"results": [{...}, {...}]}
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+if [ ! -f "$CONFIG" ]; then
+  echo "Error: egregore.json not found. Run onboarding first." >&2
+  exit 1
+fi
+
+# --- Local mode gate: bail immediately ---
+_MODE=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null)
+if [ "$_MODE" = "local" ]; then
+  echo '{"results":[]}'
+  exit 0
+fi
+
+# Load specific variables from .env if it exists (safe extraction, no arbitrary code execution)
+if [ -f "$SCRIPT_DIR/.env" ]; then
+  EGREGORE_API_URL="${EGREGORE_API_URL:-$(grep '^EGREGORE_API_URL=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)}"
+  EGREGORE_API_KEY="${EGREGORE_API_KEY:-$(grep '^EGREGORE_API_KEY=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)}"
+fi
+
+API_URL="${EGREGORE_API_URL:-$(jq -r '.api_url // empty' "$CONFIG")}"
+API_KEY="${EGREGORE_API_KEY:-}"
+
+if [ -z "$API_URL" ] || [ -z "$API_KEY" ]; then
+  # === OFFLINE MODE: No API key — return empty results (OSS/local) ===
+  echo '{"results":[]}'
+  exit 0
+fi
+
+QUERIES_JSON="${1:?Usage: graph-batch.sh '<json array of queries>'}"
+
+# Wrap the array into the batch request format
+BODY=$(jq -n --argjson queries "$QUERIES_JSON" '{queries: $queries}')
+
+RESPONSE=$(curl -s -X POST "${API_URL}/api/graph/batch" \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$BODY" \
+  --max-time 60)
+
+# Check for HTTP-level errors
+if echo "$RESPONSE" | jq -e '.detail' >/dev/null 2>&1; then
+  echo "API error:" >&2
+  echo "$RESPONSE" | jq '.detail' >&2
+  exit 1
+fi
+
+echo "$RESPONSE"

package/runtime/pi/bin/graph-op.sh

@@ -0,0 +1,431 @@
+#!/bin/bash
+set -euo pipefail
+# Named graph operations — clean interface over raw Cypher.
+# Keeps implementation details out of the TUI.
+#
+# Usage: bash bin/graph-op.sh <operation> [args...]
+#
+# Operations:
+#   mark-read <session-id>      Mark a handoff as read
+#   mark-done <session-id>      Mark a handoff as done/resolved
+#   answer-question <set-id>    Mark a question set as answered
+#   resolve-handoffs <user>     Auto-resolve read handoffs with later sessions
+#   set-topic <session-id> <topic> [branch]
+#                               Set topic (and optionally branch) on a Session node
+#   record-focus <session-id> <shown-json> <selected> [dismissed-json]
+#                               Track Focus option selection for adaptive options
+#   merge-person <keep-name> <remove-name>
+#                               Merge two Person nodes — transfers relationships from
+#                               remove-name to keep-name, stores remove-name as alias
+#   create-harvest <id> <topic> <intent> <initiator>
+#                               Create a Harvest node and link to initiator (WAL-backed)
+#   create-harvest-session <harvest-id> <session-id> <person-name> [status]
+#                               Create a HarvestSession linked to a Harvest and Person.
+#                               status defaults to 'active' (back-compat). Valid values:
+#                               pending | active | answered | complete | incorporated.
+#                               Async respondents should be created with 'pending'.
+#   record-harvest-turn <session-id> <turn> <question> <intent> [answer] [eval]
+#                               Record a question-answer turn in a HarvestSession
+#   complete-harvest <harvest-id> <artifact-path>
+#                               Mark harvest complete and link synthesis artifact
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  echo "Usage: graph-op.sh <operation> [args...]"
+  echo ""
+  echo "Named graph operations — clean interface over raw Cypher."
+  echo ""
+  echo "Operations:"
+  echo "  mark-read <sid>          Mark handoff as read"
+  echo "  mark-done <sid>          Mark handoff as done"
+  echo "  answer-question <qid>    Mark question set as answered"
+  echo "  resolve-handoffs <user>  Auto-resolve read handoffs"
+  echo "  set-topic <sid> <topic>  Set topic on a Session node"
+  echo "  merge-person <keep> <rm> Merge two Person nodes"
+  echo "  claim-handoff <sid> <ho> Link implementing session to handoff"
+  echo "  create-pr <sid> <num> <repo> <author> [title]"
+  echo "  register-artifact <id> <url> <title> <type> <author> <topics> <excerpt>"
+  echo "  create-harvest / complete-harvest / record-harvest-turn"
+  echo "  wal-status               Show WAL pending count"
+  exit 0
+fi
+
+# --- Local mode gate: bail immediately ---
+_MODE=$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+if [ "$_MODE" = "local" ]; then
+  echo '{"results":[]}'
+  exit 0
+fi
+
+GS="$SCRIPT_DIR/bin/graph.sh"
+
+OP="${1:-}"
+shift || true
+
+case "$OP" in
+
+  mark-read)
+    SID="${1:?missing session-id}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      SET s.handoffStatus = 'read', s.handoffReadDate = date()
+      RETURN s.id AS id, s.topic AS topic
+    " "$(jq -n --arg sid "$SID" '{sid: $sid}')"
+    ;;
+
+  mark-done)
+    SID="${1:?missing session-id}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      SET s.handoffStatus = 'done'
+      RETURN s.id AS id, s.topic AS topic
+    " "$(jq -n --arg sid "$SID" '{sid: $sid}')"
+    ;;
+
+  answer-question)
+    QID="${1:?missing question-set-id}"
+    bash "$GS" query "
+      MATCH (qs:QuestionSet {id: \$qid})
+      SET qs.status = 'answered'
+      RETURN qs.id AS id, qs.topic AS topic
+    " "$(jq -n --arg qid "$QID" '{qid: $qid}')"
+    ;;
+
+  resolve-handoffs)
+    USER="${1:?missing username}"
+    bash "$GS" query "
+      MATCH (s:Session)-[:HANDED_TO]->(p:Person {name: \$user})
+      WHERE s.handoffStatus = 'read'
+      WITH s, p, coalesce(s.handoffReadDate, s.date) AS sinceDate
+      MATCH (later:Session)-[:BY]->(p)
+      WHERE later.date > sinceDate
+      WITH s, count(later) AS laterSessions WHERE laterSessions > 0
+      SET s.handoffStatus = 'done'
+      RETURN s.id AS resolved
+    " "$(jq -n --arg user "$USER" '{user: $user}')"
+    ;;
+
+  set-topic)
+    SID="${1:?missing session-id}"
+    TOPIC="${2:?missing topic}"
+    BRANCH="${3:-}"
+    if [ -n "$BRANCH" ]; then
+      bash "$GS" query "
+        MATCH (s:Session {id: \$sid})
+        SET s.topic = \$topic, s.branch = \$branch
+        RETURN s.id AS id, s.topic AS topic, s.branch AS branch
+      " "$(jq -n --arg sid "$SID" --arg topic "$TOPIC" --arg branch "$BRANCH" '{sid: $sid, topic: $topic, branch: $branch}')"
+    else
+      bash "$GS" query "
+        MATCH (s:Session {id: \$sid})
+        SET s.topic = \$topic
+        RETURN s.id AS id, s.topic AS topic
+      " "$(jq -n --arg sid "$SID" --arg topic "$TOPIC" '{sid: $sid, topic: $topic}')"
+    fi
+    ;;
+
+  record-focus)
+    SID="${1:?missing session-id}"
+    SHOWN="${2:?missing shown options}"
+    SELECTED="${3:?missing selected option}"
+    DISMISSED="${4:-[]}"
+    bash "$GS" query "
+      MATCH (s:Session {id: \$sid})
+      SET s.focusShown = \$shown,
+          s.focusSelected = \$selected,
+          s.focusDismissed = \$dismissed
+      RETURN s.id AS id
+    " "$(jq -n --arg sid "$SID" --argjson shown "$SHOWN" --arg selected "$SELECTED" --argjson dismissed "$DISMISSED" '{sid: $sid, shown: $shown, selected: $selected, dismissed: $dismissed}')"
+    ;;
+
+  merge-person)
+    KEEP="${1:?missing keep-name (the Person to keep)}"
+    REMOVE="${2:?missing remove-name (the Person to absorb)}"
+    bash "$GS" query "
+      MATCH (keep:Person) WHERE toLower(keep.name) = toLower(\$keep) OR keep.github = \$keep
+      MATCH (remove:Person) WHERE toLower(remove.name) = toLower(\$remove) OR remove.github = \$remove
+      WITH keep, remove WHERE keep <> remove
+      SET keep.previousNames = coalesce(keep.previousNames, []) + remove.name
+      WITH keep, remove
+      OPTIONAL MATCH (s1)-[:BY]->(remove)
+      FOREACH (_ IN CASE WHEN s1 IS NOT NULL THEN [1] ELSE [] END | MERGE (s1)-[:BY]->(keep))
+      WITH keep, remove
+      OPTIONAL MATCH (s2)-[:HANDED_TO]->(remove)
+      FOREACH (_ IN CASE WHEN s2 IS NOT NULL THEN [1] ELSE [] END | MERGE (s2)-[:HANDED_TO]->(keep))
+      WITH keep, remove
+      OPTIONAL MATCH (m)-[:INVOLVES]->(remove)
+      FOREACH (_ IN CASE WHEN m IS NOT NULL THEN [1] ELSE [] END | MERGE (m)-[:INVOLVES]->(keep))
+      WITH keep, remove
+      OPTIONAL MATCH (a)-[:CONTRIBUTED_BY]->(remove)
+      FOREACH (_ IN CASE WHEN a IS NOT NULL THEN [1] ELSE [] END | MERGE (a)-[:CONTRIBUTED_BY]->(keep))
+      WITH keep, remove
+      OPTIONAL MATCH (i)-[:CONDUCTED_BY]->(remove)
+      FOREACH (_ IN CASE WHEN i IS NOT NULL THEN [1] ELSE [] END | MERGE (i)-[:CONDUCTED_BY]->(keep))
+      WITH keep, remove
+      OPTIONAL MATCH (remove)-[:MEMBER_OF]->(o:Org)
+      FOREACH (_ IN CASE WHEN o IS NOT NULL THEN [1] ELSE [] END | MERGE (keep)-[:MEMBER_OF]->(o))
+      WITH keep, remove
+      DETACH DELETE remove
+      RETURN keep.name AS name, keep.github AS github, keep.previousNames AS aliases
+    " "$(jq -n --arg keep "$KEEP" --arg remove "$REMOVE" '{keep: $keep, remove: $remove}')"
+    ;;
+
+  claim-handoff)
+    IMPL_SID="${1:?missing implementing-session-id}"
+    HO_SID="${2:?missing handoff-session-id}"
+    CYPHER="
+      MATCH (impl:Session {id: \$implSid}), (ho:Session {id: \$hoSid})
+      WHERE ho.handoffStatus IS NOT NULL
+      MERGE (impl)-[:IMPLEMENTS]->(ho)
+      RETURN impl.id AS implementor, ho.id AS handoff, ho.topic AS topic
+    "
+    PARAMS="$(jq -n --arg implSid "$IMPL_SID" --arg hoSid "$HO_SID" '{implSid: $implSid, hoSid: $hoSid}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    bash "$GS" query "$CYPHER" "$PARAMS"
+    ;;
+
+  create-pr)
+    SID="${1:?missing session-id}"
+    PR_NUM="${2:?missing pr-number}"
+    REPO="${3:?missing repo}"
+    AUTHOR_GH="${4:?missing author-github}"
+    TITLE="${5:-}"
+    CYPHER="
+      MERGE (pr:PR {number: toInteger(\$num), repo: \$repo})
+      ON CREATE SET pr.author = \$author, pr.status = 'open',
+        pr.createdAt = datetime(), pr.title = \$title
+      WITH pr
+      OPTIONAL MATCH (s:Session {id: \$sid})
+      FOREACH (_ IN CASE WHEN s IS NOT NULL THEN [1] ELSE [] END |
+        MERGE (s)-[:PRODUCED]->(pr))
+      RETURN pr.number AS number, pr.repo AS repo
+    "
+    PARAMS="$(jq -n --arg sid "$SID" --argjson num "$PR_NUM" --arg repo "$REPO" --arg author "$AUTHOR_GH" --arg title "$TITLE" '{sid: $sid, num: $num, repo: $repo, author: $author, title: $title}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    bash "$GS" query "$CYPHER" "$PARAMS"
+    ;;
+
+  register-artifact)
+    # Index a published (hosted) artifact as an Artifact node so the finder can
+    # retrieve it from the graph in connected mode — by content (title/topics/
+    # excerpt CONTAINS) and by relationship (who made it, which quest). The node
+    # id is the registry FILENAME STEM (date-author-slug), matching sync-graph.sh
+    # so a later /save sync upserts the same node instead of duplicating it.
+    # args: <id> <url> <title> <type> <author-handle> <topics-csv> <excerpt>
+    A_ID="${1:?missing id}"
+    A_URL="${2:?missing url}"
+    A_TITLE="${3:-}"
+    A_TYPE="${4:-artifact}"
+    A_AUTHOR="$(printf '%s' "${5:-}" | tr '[:upper:]' '[:lower:]' | awk '{print $1}')"
+    A_TOPICS_JSON="$(printf '%s' "${6:-}" | jq -Rc 'split(",") | map(gsub("^\\s+|\\s+$";"")) | map(select(length > 0))' 2>/dev/null || echo '[]')"
+    A_EXCERPT="$(printf '%s' "${7:-}" | tr '\n' ' ' | cut -c1-2000)"
+    CYPHER="
+      MERGE (a:Artifact {id: \$id})
+      ON CREATE SET a.created = datetime()
+      SET a.title = \$title, a.type = \$type, a.url = \$url,
+          a.topics = \$topics, a.excerpt = \$excerpt, a.published = true
+      WITH a
+      OPTIONAL MATCH (p:Person)
+        WHERE \$author <> '' AND (toLower(p.name) = \$author OR p.github = \$author)
+      FOREACH (_ IN CASE WHEN p IS NOT NULL THEN [1] ELSE [] END |
+        MERGE (a)-[:CONTRIBUTED_BY]->(p))
+      RETURN a.id AS id
+    "
+    PARAMS="$(jq -n --arg id "$A_ID" --arg url "$A_URL" --arg title "$A_TITLE" --arg type "$A_TYPE" \
+      --arg author "$A_AUTHOR" --argjson topics "$A_TOPICS_JSON" --arg excerpt "$A_EXCERPT" \
+      '{id: $id, url: $url, title: $title, type: $type, author: $author, topics: $topics, excerpt: $excerpt}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    bash "$GS" query "$CYPHER" "$PARAMS"
+    ;;
+
+  check-implements)
+    SID="${1:?missing session-id}"
+    bash "$GS" query "
+      MATCH (impl:Session {id: \$sid})-[:IMPLEMENTS]->(ho:Session)-[:BY]->(author:Person)
+      RETURN ho.id AS handoffId, ho.topic AS topic, author.name AS author,
+             author.github AS authorGithub
+    " "$(jq -n --arg sid "$SID" '{sid: $sid}')"
+    ;;
+
+  update-pr)
+    PR_NUM="${1:?missing pr-number}"
+    REPO="${2:?missing repo}"
+    STATUS="${3:?missing status}"
+    MERGED_AT="${4:-}"
+    if [ -n "$MERGED_AT" ]; then
+      bash "$GS" query "
+        MATCH (pr:PR {number: toInteger(\$num), repo: \$repo})
+        SET pr.status = \$status, pr.mergedAt = datetime(\$mergedAt)
+        RETURN pr.number AS number, pr.status AS status
+      " "$(jq -n --argjson num "$PR_NUM" --arg repo "$REPO" --arg status "$STATUS" --arg mergedAt "$MERGED_AT" '{num: $num, repo: $repo, status: $status, mergedAt: $mergedAt}')"
+    else
+      bash "$GS" query "
+        MATCH (pr:PR {number: toInteger(\$num), repo: \$repo})
+        SET pr.status = \$status
+        RETURN pr.number AS number, pr.status AS status
+      " "$(jq -n --argjson num "$PR_NUM" --arg repo "$REPO" --arg status "$STATUS" '{num: $num, repo: $repo, status: $status}')"
+    fi
+    ;;
+
+  my-merged-prs)
+    AUTHOR_GH="${1:?missing author-github}"
+    SINCE="${2:-}"
+    if [ -n "$SINCE" ]; then
+      bash "$GS" query "
+        MATCH (pr:PR {author: \$author})
+        WHERE pr.status = 'merged' AND pr.mergedAt >= datetime(\$since)
+        RETURN pr.number AS number, pr.repo AS repo, pr.title AS title,
+               toString(pr.mergedAt) AS mergedAt
+        ORDER BY pr.mergedAt DESC LIMIT 10
+      " "$(jq -n --arg author "$AUTHOR_GH" --arg since "${SINCE}T00:00:00Z" '{author: $author, since: $since}')"
+    else
+      bash "$GS" query "
+        MATCH (pr:PR {author: \$author})
+        WHERE pr.status = 'merged'
+        RETURN pr.number AS number, pr.repo AS repo, pr.title AS title,
+               toString(pr.mergedAt) AS mergedAt
+        ORDER BY pr.mergedAt DESC LIMIT 5
+      " "$(jq -n --arg author "$AUTHOR_GH" '{author: $author}')"
+    fi
+    ;;
+
+  my-implemented-handoffs)
+    AUTHOR_NAME="${1:?missing author-name}"
+    SINCE="${2:-}"
+    if [ -n "$SINCE" ]; then
+      bash "$GS" query "
+        MATCH (impl:Session)-[:IMPLEMENTS]->(ho:Session)-[:BY]->(author:Person)
+        WHERE toLower(author.name) = toLower(\$author)
+          AND impl.wrappedAt >= datetime(\$since)
+        MATCH (impl)-[:BY]->(implementor:Person)
+        RETURN ho.topic AS handoffTopic, implementor.name AS implementedBy,
+               toString(impl.wrappedAt) AS completedAt, impl.summary AS summary
+        ORDER BY impl.wrappedAt DESC LIMIT 10
+      " "$(jq -n --arg author "$AUTHOR_NAME" --arg since "${SINCE}T00:00:00Z" '{author: $author, since: $since}')"
+    else
+      bash "$GS" query "
+        MATCH (impl:Session)-[:IMPLEMENTS]->(ho:Session)-[:BY]->(author:Person)
+        WHERE toLower(author.name) = toLower(\$author)
+        MATCH (impl)-[:BY]->(implementor:Person)
+        RETURN ho.topic AS handoffTopic, implementor.name AS implementedBy,
+               toString(impl.wrappedAt) AS completedAt, impl.summary AS summary
+        ORDER BY impl.wrappedAt DESC LIMIT 5
+      " "$(jq -n --arg author "$AUTHOR_NAME" '{author: $author}')"
+    fi
+    ;;
+
+  wal-status)
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" status
+    ;;
+
+  create-harvest)
+    HID="${1:?missing harvest-id}"
+    TOPIC="${2:?missing topic}"
+    INTENT="${3:?missing intent}"
+    INITIATOR="${4:?missing initiator}"
+    CYPHER="
+      MERGE (h:Harvest {id: \$hid})
+      ON CREATE SET h.topic = \$topic, h.intent = \$intent,
+        h.status = 'active', h.created = datetime()
+      WITH h
+      MATCH (p:Person) WHERE toLower(p.name) = toLower(\$initiator) OR p.github = \$initiator
+      MERGE (h)-[:INITIATED_BY]->(p)
+      RETURN h.id AS id, h.topic AS topic, h.status AS status
+    "
+    PARAMS="$(jq -n --arg hid "$HID" --arg topic "$TOPIC" --arg intent "$INTENT" --arg initiator "$INITIATOR" '{hid: $hid, topic: $topic, intent: $intent, initiator: $initiator}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    bash "$GS" query "$CYPHER" "$PARAMS"
+    ;;
+
+  create-harvest-session)
+    HID="${1:?missing harvest-id}"
+    HSID="${2:?missing session-id}"
+    PERSON="${3:?missing person-name}"
+    STATUS="${4:-active}"
+    case "$STATUS" in
+      pending|active|answered|complete|incorporated) ;;
+      *) jq -n --arg s "$STATUS" '{error:("invalid status: "+$s),valid:["pending","active","answered","complete","incorporated"]}' >&2; exit 2 ;;
+    esac
+    CYPHER="
+      MATCH (h:Harvest {id: \$hid})
+      MERGE (hs:HarvestSession {id: \$hsid})
+      ON CREATE SET hs.status = \$status, hs.created = datetime()
+      MERGE (h)-[:HAS_SESSION]->(hs)
+      WITH hs
+      MATCH (p:Person) WHERE toLower(p.name) = toLower(\$person) OR p.github = \$person
+      MERGE (hs)-[:WITH]->(p)
+      RETURN hs.id AS id, hs.status AS status
+    "
+    PARAMS="$(jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" --arg status "$STATUS" '{hid: $hid, hsid: $hsid, person: $person, status: $status}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    OUT="$(bash "$GS" query "$CYPHER" "$PARAMS")"
+    if [ "$(echo "$OUT" | jq -r '.results | length' 2>/dev/null)" = "0" ]; then
+      jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" \
+        '{error:"create-harvest-session: harvest or person not found",hid:$hid,hsid:$hsid,person:$person}' >&2
+      exit 3
+    fi
+    echo "$OUT"
+    ;;
+
+  record-harvest-turn)
+    HSID="${1:?missing session-id}"
+    TURN="${2:?missing turn-number}"
+    QUESTION="${3:?missing question}"
+    QINTENT="${4:?missing question-intent}"
+    ANSWER="${5:-}"
+    EVAL="${6:-}"
+    TURN_ID="${HSID}-turn-${TURN}"
+    PARAMS=$(jq -n \
+      --arg hsid "$HSID" --arg tid "$TURN_ID" --arg turn "$TURN" \
+      --arg question "$QUESTION" --arg qintent "$QINTENT" \
+      --arg answer "$ANSWER" --arg eval "$EVAL" \
+      '{hsid:$hsid, tid:$tid, turn:$turn, question:$question, qintent:$qintent, answer:$answer, eval:$eval}')
+    if [ -n "$ANSWER" ]; then
+      bash "$GS" query "
+        MATCH (hs:HarvestSession {id: \$hsid})
+        MERGE (t:HarvestTurn {id: \$tid})
+        ON CREATE SET t.turnNumber = toInteger(\$turn), t.question = \$question,
+          t.questionIntent = \$qintent, t.created = datetime()
+        SET t.answer = \$answer, t.answeredAt = datetime()
+        SET t.evaluation = CASE WHEN \$eval <> '' THEN \$eval ELSE t.evaluation END
+        MERGE (hs)-[:HAS_TURN]->(t)
+        RETURN t.id AS id, t.turnNumber AS turnNumber
+      " "$PARAMS"
+    else
+      bash "$GS" query "
+        MATCH (hs:HarvestSession {id: \$hsid})
+        MERGE (t:HarvestTurn {id: \$tid})
+        ON CREATE SET t.turnNumber = toInteger(\$turn), t.question = \$question,
+          t.questionIntent = \$qintent, t.created = datetime()
+        MERGE (hs)-[:HAS_TURN]->(t)
+        RETURN t.id AS id, t.turnNumber AS turnNumber
+      " "$PARAMS"
+    fi
+    ;;
+
+  complete-harvest)
+    HID="${1:?missing harvest-id}"
+    ARTIFACT_PATH="${2:?missing artifact-path}"
+    bash "$GS" query "
+      MATCH (h:Harvest {id: \$hid})
+      SET h.status = 'complete', h.completedAt = datetime(), h.synthesisPath = \$path
+      WITH h
+      OPTIONAL MATCH (h)-[:HAS_SESSION]->(hs:HarvestSession)
+      WHERE hs.status <> 'complete'
+      SET hs.status = 'complete', hs.completedAt = datetime()
+      WITH h
+      MERGE (a:Artifact {id: \$hid + '-synthesis'})
+      ON CREATE SET a.type = 'harvest', a.title = h.topic, a.filePath = \$path,
+        a.created = datetime(), a.topics = coalesce([h.topic], [])
+      MERGE (h)-[:PRODUCED]->(a)
+      RETURN h.id AS id, h.status AS status, a.id AS artifact
+    " "$(jq -n --arg hid "$HID" --arg path "$ARTIFACT_PATH" '{hid: $hid, path: $path}')"
+    ;;
+
+  *)
+    echo '{"error":"unknown operation: '"$OP"'","operations":["mark-read","mark-done","answer-question","resolve-handoffs","set-topic","record-focus","merge-person","claim-handoff","check-implements","create-pr","update-pr","my-merged-prs","my-implemented-handoffs","wal-status","create-harvest","create-harvest-session","record-harvest-turn","complete-harvest"]}'
+    exit 1
+    ;;
+
+esac