create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/bin/graph-projection.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Explicit management boundary for the optional derived graph projection.
+# Usage: bash bin/graph-projection.sh {status|verify|rebuild} [--enable]
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+COMMAND="${1:-status}"
+shift || true
+ENABLED=false
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --enable) ENABLED=true ;;
+    --help|-h)
+      echo "Usage: graph-projection.sh {status|verify|rebuild} [--enable]"
+      exit 0
+      ;;
+    *) echo "Unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+case "$COMMAND" in
+  status|verify|rebuild) ;;
+  --help|-h)
+    echo "Usage: graph-projection.sh {status|verify|rebuild} [--enable]"
+    exit 0
+    ;;
+  *) echo "Usage: graph-projection.sh {status|verify|rebuild} [--enable]" >&2; exit 2 ;;
+esac
+
+RUNTIME_PYTHONPATH="$ROOT"
+if [ -n "${PYTHONPATH:-}" ]; then
+  RUNTIME_PYTHONPATH="$RUNTIME_PYTHONPATH:$PYTHONPATH"
+fi
+
+GRAPH_OVERRIDE=0
+[ "$ENABLED" = "true" ] && GRAPH_OVERRIDE=1
+ROOT="$ROOT" ENABLED="$ENABLED" COMMAND="$COMMAND" \
+EGREGORE_GRAPH_PROJECTION="$GRAPH_OVERRIDE" PYTHONPATH="$RUNTIME_PYTHONPATH" \
+python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+from egregore_runtime.graph import graph_projection
+
+projection = graph_projection(
+    Path(os.environ["ROOT"]), enabled=os.environ["ENABLED"] == "true"
+)
+command = os.environ["COMMAND"]
+health = projection.rebuild() if command == "rebuild" else projection.verify()
+print(json.dumps(health.to_dict(), sort_keys=True))
+PY

package/runtime/claude/bin/graph-wal.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+# Graph Write-Ahead Log — resilient graph writes with local buffer.
+# Mirrors bin/telemetry.sh architecture.
+#
+# Subcommands:
+#   append <cypher> <params_json>   Append entry to local JSONL buffer (no network)
+#   drain                           Execute pending entries via graph-batch.sh
+#   status                          Show pending count + file size as JSON
+#
+# Storage: ~/.egregore/graph-wal.jsonl
+# Buffer guard: 2MB max, auto-truncate to last 200 entries if exceeded.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  echo "Usage: graph-wal.sh <command>"
+  echo ""
+  echo "Graph Write-Ahead Log — resilient graph writes with local buffer."
+  echo ""
+  echo "Commands:"
+  echo "  append <cypher> <params>  Append entry to WAL (no network)"
+  echo "  drain                     Execute pending entries via graph-batch"
+  echo "  status                    Show pending count + file size (JSON)"
+  exit 0
+fi
+
+# Do not accumulate a shadow write backlog while the optional projection is
+# quarantined. Canonical Markdown/Git remains the complete source of truth.
+# shellcheck source=bin/lib/config.sh
+source "$SCRIPT_DIR/bin/lib/config.sh"
+if ! _graph_projection_enabled; then
+  case "${1:-status}" in
+    status) echo '{"pending":0,"bytes":0,"status":"disabled","reason":"graph_projection_disabled"}' ;;
+    *) echo '{"status":"disabled","reason":"graph_projection_disabled"}' ;;
+  esac
+  exit 0
+fi
+
+WAL_DIR="$HOME/.egregore"
+# WAL file is per-instance to prevent cross-org data leakage on multi-instance machines
+PROJ_HASH=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
+WAL_FILE="$WAL_DIR/graph-wal-${PROJ_HASH}.jsonl"
+MAX_BUFFER_BYTES=2097152  # 2MB
+MAX_ENTRIES_AFTER_TRUNCATE=200
+LOCK_DIR="$WAL_DIR/graph-wal-${PROJ_HASH}.lock"
+LOCK_ATTEMPTS="${GRAPH_WAL_LOCK_ATTEMPTS:-50}"
+
+# --- Cross-platform file locking via mkdir (atomic on all POSIX systems) ---
+_lock() {
+  local attempts=0
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    attempts=$((attempts + 1))
+    if [ "$attempts" -gt "$LOCK_ATTEMPTS" ]; then
+      # Stale lock — check if holder PID is alive
+      local holder_pid
+      holder_pid=$(cat "$LOCK_DIR/pid" 2>/dev/null || echo "")
+      if [ -n "$holder_pid" ] && ! kill -0 "$holder_pid" 2>/dev/null; then
+        rm -rf "$LOCK_DIR" 2>/dev/null
+        continue
+      fi
+      echo "graph-wal: lock timeout after ${LOCK_ATTEMPTS} attempt(s)" >&2
+      return 1
+    fi
+    sleep 0.1
+  done
+  echo $$ > "$LOCK_DIR/pid" 2>/dev/null
+}
+
+_unlock() {
+  rm -rf "$LOCK_DIR" 2>/dev/null
+}
+
+trap '_unlock' EXIT
+
+# --- Resolve session ID (same pattern as telemetry.sh) ---
+_resolve_session_id() {
+  if [ -n "${EGREGORE_SESSION_ID:-}" ]; then
+    echo "$EGREGORE_SESSION_ID"
+    return
+  fi
+  local proj_hash
+  proj_hash=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
+  local sid_file="$WAL_DIR/session-${proj_hash}.id"
+  if [ -f "$sid_file" ]; then
+    cat "$sid_file" 2>/dev/null || echo "unknown"
+  else
+    echo "unknown"
+  fi
+}
+
+# --- append: O(1) local write, no network ---
+cmd_append() {
+  local cypher="${1:?Usage: graph-wal.sh append <cypher> <params_json>}"
+  local params="${2:-"{}"}"
+
+  mkdir -p "$WAL_DIR"
+
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local sid
+  sid=$(_resolve_session_id)
+
+  # Build JSON line
+  local line
+  line=$(jq -n -c \
+    --arg ts "$ts" \
+    --arg sid "$sid" \
+    --arg cypher "$cypher" \
+    --argjson params "$params" \
+    '{ts: $ts, sid: $sid, cypher: $cypher, params: $params}')
+
+  # Append under lock — if lock fails, append anyway (durability > mutual exclusion)
+  local _locked=true
+  _lock || _locked=false
+  echo "$line" >> "$WAL_FILE"
+
+  # Buffer guard: truncate to last N entries if file exceeds max size
+  # Only safe under lock — tail+mv is not atomic and races with concurrent writers
+  if [ "$_locked" = "true" ] && [ -f "$WAL_FILE" ]; then
+    local size
+    size=$(wc -c < "$WAL_FILE" 2>/dev/null | tr -d ' ')
+    if [ "$size" -gt "$MAX_BUFFER_BYTES" ] 2>/dev/null; then
+      local total_entries
+      total_entries=$(wc -l < "$WAL_FILE" 2>/dev/null | tr -d ' ')
+      local dropped=$((total_entries - MAX_ENTRIES_AFTER_TRUNCATE))
+      if [ "$dropped" -gt 0 ]; then
+        echo "graph-wal: buffer exceeded ${MAX_BUFFER_BYTES} bytes. Dropping $dropped oldest entries (keeping $MAX_ENTRIES_AFTER_TRUNCATE)." >&2
+      fi
+      local tmp="$WAL_FILE.truncate.$$"
+      tail -n "$MAX_ENTRIES_AFTER_TRUNCATE" "$WAL_FILE" > "$tmp" 2>/dev/null \
+        && mv "$tmp" "$WAL_FILE" \
+        || rm -f "$tmp"
+    fi
+  fi
+  [ "$_locked" = "true" ] && _unlock
+}
+
+# --- drain: execute pending entries via graph-batch.sh ---
+cmd_drain() {
+  if [ ! -f "$WAL_FILE" ] || [ ! -s "$WAL_FILE" ]; then
+    return 0
+  fi
+
+  # Atomic rotate under lock: move to temp file so new appends don't conflict
+  _lock || return 0
+  local drain_file="$WAL_FILE.drain.$$"
+  mv "$WAL_FILE" "$drain_file" 2>/dev/null || { _unlock; return 0; }
+  _unlock
+
+  local total
+  total=$(wc -l < "$drain_file" 2>/dev/null | tr -d ' ')
+  local batch_size=20
+  local offset=0
+  local all_ok=true
+
+  while [ "$offset" -lt "$total" ]; do
+    # Extract batch of entries (offset+1 through offset+batch_size)
+    local batch_lines
+    batch_lines=$(tail -n "+$((offset + 1))" "$drain_file" | head -n "$batch_size")
+
+    # Build batch JSON array: [{statement, parameters}, ...]
+    local batch_json
+    batch_json=$(echo "$batch_lines" | jq -s '[.[] | {statement: .cypher, parameters: .params}]' 2>/dev/null)
+
+    if [ -z "$batch_json" ] || [ "$batch_json" = "[]" ]; then
+      offset=$((offset + batch_size))
+      continue
+    fi
+
+    # Execute via graph-batch.sh
+    if bash "$SCRIPT_DIR/bin/graph-batch.sh" "$batch_json" >/dev/null 2>&1; then
+      offset=$((offset + batch_size))
+    else
+      all_ok=false
+      break
+    fi
+  done
+
+  if [ "$all_ok" = "true" ]; then
+    # All batches succeeded — remove drain file
+    rm -f "$drain_file"
+  else
+    # Failure — merge unprocessed entries back
+    # Extract remaining entries (from offset+1 to end)
+    local remaining
+    remaining=$(tail -n "+$((offset + 1))" "$drain_file" 2>/dev/null)
+
+    if [ -n "$remaining" ]; then
+      _lock || { echo "$remaining" > "$WAL_FILE" 2>/dev/null; rm -f "$drain_file"; return 1; }
+      if [ -f "$WAL_FILE" ]; then
+        # New entries were written while draining; prepend remaining
+        local merge_file="$WAL_FILE.merge.$$"
+        { echo "$remaining"; cat "$WAL_FILE"; } > "$merge_file" 2>/dev/null \
+          && mv "$merge_file" "$WAL_FILE" \
+          && rm -f "$drain_file" \
+          || rm -f "$merge_file"
+      else
+        echo "$remaining" > "$WAL_FILE"
+        rm -f "$drain_file"
+      fi
+      _unlock
+    else
+      rm -f "$drain_file"
+    fi
+  fi
+}
+
+# --- status: pending count + file size as JSON ---
+cmd_status() {
+  if [ -f "$WAL_FILE" ] && [ -s "$WAL_FILE" ]; then
+    local count size
+    count=$(wc -l < "$WAL_FILE" 2>/dev/null | tr -d ' ')
+    size=$(wc -c < "$WAL_FILE" 2>/dev/null | tr -d ' ')
+    jq -n --argjson pending "$count" --argjson bytes "$size" '{pending: $pending, bytes: $bytes}'
+  else
+    echo '{"pending":0,"bytes":0}'
+  fi
+}
+
+# --- Main dispatch ---
+case "${1:-status}" in
+  append)
+    shift
+    cmd_append "$@"
+    ;;
+  drain)
+    cmd_drain
+    ;;
+  status)
+    cmd_status
+    ;;
+  *)
+    echo "Usage: graph-wal.sh <command>"
+    echo ""
+    echo "Commands:"
+    echo "  append <cypher> <params>  Append entry to WAL (no network)"
+    echo "  drain                     Execute pending entries"
+    echo "  status                    Show pending count + file size"
+    ;;
+esac

package/runtime/claude/bin/graph.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+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
+
+# Optional compatibility projection. A dogfood instance can quarantine every
+# graph path without changing its Connected control-plane mode.
+# shellcheck source=bin/lib/config.sh
+source "$SCRIPT_DIR/bin/lib/config.sh"
+if ! _graph_projection_enabled; then
+  case "${1:-}" in
+    query)  echo '{"results":[],"status":"disabled","reason":"graph_projection_disabled"}' ;;
+    schema) echo '{}' ;;
+    test)   echo '{"status":"disabled","reason":"graph_projection_disabled"}' ;;
+    *)      echo '{"results":[],"status":"disabled","reason":"graph_projection_disabled"}' ;;
+  esac
+  exit 0
+fi
+
+# --- Runtime cutover gate --------------------------------------------------
+# Once the Runtime/QMD MVP is activated, graph retrieval is not used by this
+# Runtime: background callers (attendant cache warm, greeting enrichment,
+# search enrichment) get silence with no network and no telemetry — observed
+# live as a wall of graph_query telemetry events from the attendant on an
+# upgraded instance. An explicitly requested projection read passes through
+# by setting EGREGORE_GRAPH_EXPLICIT=1 (bin/graph-op.sh named reads do).
+if [ "${EGREGORE_GRAPH_EXPLICIT:-0}" != "1" ]; then
+  _CUT_ORG=$(jq -r '.org_id // empty' "$CONFIG" 2>/dev/null)
+  if [ -n "$_CUT_ORG" ]; then
+    _CUT_MAIN="$SCRIPT_DIR"
+    if [ -f "$SCRIPT_DIR/.git" ]; then
+      _CUT_GD=$(sed -n 's/^gitdir: //p' "$SCRIPT_DIR/.git" 2>/dev/null)
+      case "$_CUT_GD" in */.git/worktrees/*) _CUT_MAIN="${_CUT_GD%/.git/worktrees/*}" ;; esac
+    fi
+    _CUT_MAIN=$(cd "$_CUT_MAIN" 2>/dev/null && pwd -P || printf '%s' "$SCRIPT_DIR")
+    _CUT_KEY=$(printf '%s|%s' "$_CUT_ORG" "$_CUT_MAIN" | shasum -a 256 2>/dev/null | cut -c1-16)
+    _CUT_REC="${EGREGORE_UPGRADE_ROOT:-$HOME/.egregore/runtime/upgrade}/${_CUT_KEY}/active.json"
+    if [ -f "$_CUT_REC" ] && [ "$(jq -r '.retrieval // empty' "$_CUT_REC" 2>/dev/null)" = "runtime-qmd" ]; then
+      case "${1:-}" in
+        query)  echo '{"results":[],"status":"disabled","reason":"runtime_qmd_active"}' ;;
+        schema) echo '{}' ;;
+        test)   echo '{"status":"disabled","reason":"runtime_qmd_active"}' ;;
+        *)      echo '{"results":[],"status":"disabled","reason":"runtime_qmd_active"}' ;;
+      esac
+      exit 0
+    fi
+  fi
+fi
+
+# --- Local mode gate: bail immediately, no .env sourcing, no network ---
+_MODE=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null)
+if [ "$_MODE" = "local" ]; then
+  case "${1:-}" in
+    query)  echo '{"results":[]}';;
+    schema) echo '{}';;
+    test)   echo '{"status":"offline","reason":"local_mode"}';;
+    *)      echo '{"results":[]}';;
+  esac
+  exit 0
+fi
+
+# Load specific variables from .env if it exists (safe extraction, no arbitrary code execution).
+# A worktree missing its .env symlink resolves through worktree-links.sh, which
+# self-heals the link and falls back to the main checkout's .env.
+_ENV_FILE="$SCRIPT_DIR/.env"
+if [ ! -f "$_ENV_FILE" ] && [ -f "$SCRIPT_DIR/bin/lib/worktree-links.sh" ]; then
+  # shellcheck source=bin/lib/worktree-links.sh
+  source "$SCRIPT_DIR/bin/lib/worktree-links.sh" 2>/dev/null || true
+  _ENV_FILE="$(egregore_env_file "$SCRIPT_DIR" 2>/dev/null || true)"
+fi
+if [ -n "$_ENV_FILE" ] && [ -f "$_ENV_FILE" ]; then
+  EGREGORE_API_URL="${EGREGORE_API_URL:-$(grep '^EGREGORE_API_URL=' "$_ENV_FILE" 2>/dev/null | cut -d'=' -f2- || true)}"
+  EGREGORE_API_KEY="${EGREGORE_API_KEY:-$(grep '^EGREGORE_API_KEY=' "$_ENV_FILE" 2>/dev/null | cut -d'=' -f2- || true)}"
+fi
+
+# api_url comes from egregore.json (committed, non-secret)
+# api_key comes from .env only (EGREGORE_API_KEY) — never from egregore.json
+API_URL="${EGREGORE_API_URL:-$(jq -r '.api_url // empty' "$CONFIG")}"
+API_KEY="${EGREGORE_API_KEY:-}"
+
+# --- Millisecond timer (macOS + Linux compatible) ---
+_millis() {
+  if command -v gdate &>/dev/null; then
+    gdate +%s%3N
+  else
+    # macOS date doesn't support %N — use python3 fallback
+    python3 -c "import time; print(int(time.time() * 1000))" 2>/dev/null || echo "0"
+  fi
+}
+
+# --- Optional read-through cache (opt-in via EGREGORE_GRAPH_CACHE_TTL) ---
+# Read-only queries can be served from a local cache that bin/attendant.sh
+# keeps warm in the background, so callers on the launch path (session-start
+# greeting) pay zero network round-trips when warm. TTL in seconds; unset/0
+# disables. Mutating queries are never cached.
+_CACHE_TTL="${EGREGORE_GRAPH_CACHE_TTL:-0}"
+# Key the cache by the MAIN checkout so worktree sessions hit the same warm
+# cache the attendant maintains (its replay uses the same derivation).
+# Worktrees have .git as a FILE pointing into the main repo's .git/worktrees/.
+# api_url + slug are part of the key so entries never cross tenants when the
+# same checkout is repointed at a different org/API (cache entries are keyed
+# only by query+params below, so the directory must carry the tenant).
+_CACHE_ROOT="$SCRIPT_DIR"
+if [ -f "$SCRIPT_DIR/.git" ]; then
+  _WT_GITDIR=$(sed 's/^gitdir: //' "$SCRIPT_DIR/.git" 2>/dev/null || true)
+  if [ -n "$_WT_GITDIR" ]; then
+    _CACHE_ROOT=$(cd "$_WT_GITDIR/../../.." 2>/dev/null && pwd || echo "$SCRIPT_DIR")
+  fi
+fi
+# The scope is a non-secret fingerprint of the EFFECTIVE endpoint + credential
+# (already resolved above: process env → .env → committed api_url). Committed
+# config alone is not enough — an EGREGORE_API_URL/KEY override or a swapped
+# .env can point this checkout at a different tenant than egregore.json names,
+# and the entry key below carries only query+params. cksum output is a CRC,
+# not a reversible or usable credential.
+_CACHE_SCOPE=$(echo -n "${API_URL:-}|${API_KEY:-}" | cksum | cut -d' ' -f1)
+_CACHE_DIR="$HOME/.egregore/graph-cache/$(echo -n "${_CACHE_ROOT}|${_CACHE_SCOPE}" | cksum | cut -d' ' -f1)"
+
+_cache_key() {
+  echo -n "$1|${2:-}" | cksum | cut -d' ' -f1
+}
+
+_is_read_query() {
+  ! echo "$1" | grep -qiE '\b(MERGE|CREATE|SET|DELETE|DETACH|REMOVE)\b'
+}
+
+if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
+  # === API MODE: Call Egregore API gateway ===
+
+  run_query() {
+    local cypher="$1"
+    local params
+    if [ -n "${2:-}" ]; then
+      params="$2"
+    else
+      params="{}"
+    fi
+
+    local cache_file=""
+    if [ "$_CACHE_TTL" != "0" ] && _is_read_query "$cypher"; then
+      cache_file="$_CACHE_DIR/$(_cache_key "$cypher" "$params").json"
+      if [ -f "$cache_file" ]; then
+        local now cts
+        now=$(date +%s)
+        cts=$(jq -r '.ts // 0' "$cache_file" 2>/dev/null || echo 0)
+        if [ $(( now - cts )) -lt "$_CACHE_TTL" ]; then
+          jq -c '.result' "$cache_file" 2>/dev/null && return 0
+        fi
+      fi
+    fi
+
+    local body
+    body=$(jq -n --arg stmt "$cypher" --argjson params "$params" \
+      '{statement: $stmt, parameters: $params}')
+
+    local start_ms
+    start_ms=$(_millis)
+
+    local response
+    response=$(curl -s -X POST "${API_URL}/api/graph/query" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "$body" \
+      --max-time 30)
+
+    local end_ms
+    end_ms=$(_millis)
+    local latency_ms=$(( end_ms - start_ms ))
+
+    # 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
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "error" \
+        "$(jq -n --arg source "graph" --arg error_code "api_error" --argjson latency "$latency_ms" \
+          '{source: $source, error_code: $error_code, latency_ms: $latency}')" 2>/dev/null &
+      exit 1
+    fi
+
+    # Emit latency telemetry (fire-and-forget)
+    bash "$SCRIPT_DIR/bin/telemetry.sh" emit "graph_query" \
+      "$(jq -n --argjson latency "$latency_ms" '{latency_ms: $latency}')" 2>/dev/null &
+
+    # Store for the attendant to keep warm (query+params travel with the result)
+    if [ -n "$cache_file" ]; then
+      mkdir -p "$_CACHE_DIR" 2>/dev/null
+      jq -n --arg q "$cypher" --argjson p "$params" --argjson ts "$(date +%s)" --argjson r "$response" \
+        '{query: $q, params: $p, ts: $ts, result: $r}' > "$cache_file" 2>/dev/null || true
+    fi
+
+    echo "$response"
+  }
+
+  get_schema() {
+    local response
+    response=$(curl -s -X GET "${API_URL}/api/graph/schema" \
+      -H "Authorization: Bearer $API_KEY" \
+      --max-time 30)
+    echo "$response" | jq .
+  }
+
+  test_connection() {
+    local response
+    response=$(curl -s -X GET "${API_URL}/api/graph/test" \
+      -H "Authorization: Bearer $API_KEY" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "ok"' >/dev/null 2>&1; then
+      echo "Connected to Egregore API at $API_URL"
+    else
+      echo "Failed to connect to Egregore API at $API_URL" >&2
+      echo "$response" >&2
+      exit 1
+    fi
+  }
+
+elif [ -n "$API_URL" ]; then
+  # === CONNECTED CONFIG, MISSING KEY ===
+  # api_url is configured, so the org expects a live graph, but no API key was
+  # found. Faking '{"results":[]}' here made a missing credential (e.g. a
+  # worktree without its .env symlink) indistinguishable from an empty graph —
+  # fail loudly instead. `test` keeps its offline JSON contract: dashboards,
+  # render-card, and startup-check consume it.
+  _missing_credentials() {
+    {
+      echo "Error: api_url is configured but EGREGORE_API_KEY is empty (looked in: ${_ENV_FILE:-$SCRIPT_DIR/.env})."
+      echo "  If this is a worktree, its .env symlink may be missing. Run /env to configure."
+    } >&2
+    exit 1
+  }
+  run_query() { _missing_credentials; }
+  get_schema() { _missing_credentials; }
+  test_connection() { echo '{"status":"offline","reason":"no_api_key"}'; }
+
+else
+  # === OFFLINE MODE: no api_url configured (OSS/unconfigured) ===
+  run_query() { echo '{"results":[]}'; }
+  get_schema() { echo '{}'; }
+  test_connection() { echo '{"status":"offline","reason":"no_api_key"}'; }
+fi
+
+case "${1:-help}" in
+  query)
+    shift
+    run_query "$@"
+    ;;
+  schema)
+    get_schema
+    ;;
+  test)
+    test_connection
+    ;;
+  help|*)
+    echo "Usage: graph.sh <command>"
+    echo ""
+    echo "Commands:"
+    echo "  query <cypher> [params_json]  Run a Cypher query"
+    echo "  schema                        Show graph schema"
+    echo "  test                          Test connection"
+    ;;
+esac