create-egregore 0.17.3 → 0.18.0

package/runtime/codex/bin/lib/permissions.sh

@@ -0,0 +1,106 @@
+# shellcheck shell=bash
+# permissions.sh — Soft-enforced admin-only access for Egregore content.
+#
+# Content can be marked admin-only via frontmatter:
+#
+#     ---
+#     admin: true
+#     ---
+#
+# Admins are listed in egregore.json under "admins": ["github1", "github2", ...].
+#
+# Two enforcement layers:
+#
+#  - Read-side (CLI listings, /view rendering) — soft, tag-not-hide:
+#    admin entries appear in /activity and /dashboard listings tagged so admins
+#    can identify them at a glance. For non-admins the title/topic/branch are
+#    replaced with an opaque "[admin]" placeholder — they see admin work
+#    exists but the topic doesn't leak. Anyone with git access still bypasses
+#    by `cat`-ing the file.
+#
+#  - Publish-side (egregore.xyz upload) — strict: publish-artifact.sh refuses
+#    to push admin-only files because egregore.xyz URLs are not auth-gated.
+#    Override with --allow-admin (set by /view after explicit user
+#    confirmation via AskUserQuestion).
+
+# Get list of admin GitHub usernames (newline-separated, lowercase)
+_get_admins() {
+  local config="${CONFIG:-${SCRIPT_DIR:-$(pwd)}/egregore.json}"
+  if [ -f "$config" ]; then
+    jq -r '.admins[]? // empty' "$config" 2>/dev/null | tr '[:upper:]' '[:lower:]'
+  fi
+}
+
+# Returns 0 if username is an admin, 1 otherwise. Empty username = not admin.
+_is_admin() {
+  local username="${1:-}"
+  [ -z "$username" ] && return 1
+  local lc
+  lc=$(printf '%s' "$username" | tr '[:upper:]' '[:lower:]')
+  _get_admins | grep -qx "$lc"
+}
+
+# Returns 0 if the file's frontmatter contains `admin: true`, 1 otherwise.
+# Tolerates whitespace and case in the value. Looks at the first ~60 lines
+# to keep the scan bounded.
+_is_admin_only_file() {
+  local path="$1"
+  [ -f "$path" ] || return 1
+  awk '
+    BEGIN { in_fm = 0; found = 0 }
+    NR == 1 && /^---[[:space:]]*$/ { in_fm = 1; next }
+    in_fm && /^---[[:space:]]*$/ { exit (found ? 0 : 1) }
+    in_fm && tolower($0) ~ /^admin:[[:space:]]*true[[:space:]]*$/ { found = 1 }
+    NR > 60 { exit (found ? 0 : 1) }
+    END { exit (found ? 0 : 1) }
+  ' "$path" 2>/dev/null
+}
+
+# Returns 0 if the file's frontmatter has the `admin:` key set at all (true or
+# false), 1 otherwise. Used by the admin-content-detector hook to skip files
+# whose admin status was already decided — including an explicit `admin: false`
+# meaning "reviewed, public on purpose". Without this, the hook would re-prompt
+# on every edit of a sensitive-keyword file the user has already cleared.
+_has_admin_decision() {
+  local path="$1"
+  [ -f "$path" ] || return 1
+  awk '
+    BEGIN { in_fm = 0; found = 0 }
+    NR == 1 && /^---[[:space:]]*$/ { in_fm = 1; next }
+    in_fm && /^---[[:space:]]*$/ { exit (found ? 0 : 1) }
+    in_fm && tolower($0) ~ /^admin:[[:space:]]*(true|false)[[:space:]]*$/ { found = 1 }
+    NR > 60 { exit (found ? 0 : 1) }
+    END { exit (found ? 0 : 1) }
+  ' "$path" 2>/dev/null
+}
+
+# Resolve current user's GitHub username (lowercase). Falls back through:
+#   $1 → .egregore-state.json → git user.name
+_current_user() {
+  local explicit="${1:-}"
+  if [ -n "$explicit" ]; then
+    printf '%s' "$explicit" | tr '[:upper:]' '[:lower:]'
+    return 0
+  fi
+  local state="${SCRIPT_DIR:-$(pwd)}/.egregore-state.json"
+  if [ -f "$state" ]; then
+    local u
+    u=$(jq -r '.github_username // empty' "$state" 2>/dev/null)
+    if [ -n "$u" ]; then
+      printf '%s' "$u" | tr '[:upper:]' '[:lower:]'
+      return 0
+    fi
+  fi
+  git config user.name 2>/dev/null | tr '[:upper:]' '[:lower:]'
+}
+
+# Returns 0 if the file's body contains sensitive keywords (fundraising, legal,
+# personnel, strategic). Used by the admin-content-detector hook to flag files
+# that probably should be admin-only but aren't yet. Whole-word match on a
+# short curated list — easy to extend without retraining intuition.
+_looks_sensitive() {
+  local path="$1"
+  [ -f "$path" ] || return 1
+  # Word-boundary regex (case-insensitive). Keep this list curated, not exhaustive.
+  grep -qiE '\b(fundrais(e|ing)|term[ -]?sheet|cap[ -]?table|valuation|runway|investor|VC[s]?|raise|seed[ -]?round|series[ -][a-d]|board[ -]prep|equity[ -]grant|stock[ -]option|RSU|salary|compensation|payroll|severance|PIP|NDA|attorney|legal[ -]hold|lawsuit|acquisition|merger|due[ -]diligence)\b' "$path"
+}

package/runtime/codex/bin/lib/time.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Cross-platform time helpers — sourced by scripts that need time formatting.
+
+# Convert ISO timestamp to epoch seconds (macOS + Linux compatible)
+# Assumes input is UTC (Z or +00:00 suffix, or bare — treated as UTC)
+_iso_to_epoch() {
+  local iso="$1"
+  local clean
+  clean=$(echo "$iso" | sed 's/Z$//; s/+00:00$//; s/\.[0-9]*//')
+  # If date-only (no T), append midnight to avoid macOS date -j filling current time
+  [[ "$clean" != *T* ]] && clean="${clean}T00:00:00"
+  # macOS → date -j, Linux → date -d
+  TZ=UTC date -j -f "%Y-%m-%dT%H:%M:%S" "$clean" "+%s" 2>/dev/null || \
+    TZ=UTC date -d "$clean" +%s 2>/dev/null || echo "0"
+}
+
+# Convert epoch to relative time string (e.g. "3h ago", "yesterday")
+# Uses calendar-day comparison for multi-day ranges (not raw delta)
+_epoch_to_relative() {
+  local epoch="$1"
+  local now="${2:-$(date +%s)}"
+  [ "$epoch" = "0" ] && echo "--" && return
+  local delta=$(( now - epoch ))
+  if [ "$delta" -lt 60 ]; then echo "just now"
+  elif [ "$delta" -lt 3600 ]; then echo "$(( delta / 60 ))m ago"
+  elif [ "$delta" -lt 86400 ]; then echo "$(( delta / 3600 ))h ago"
+  else
+    # Calendar-day based: compare local dates for accurate "yesterday" / "Xd ago"
+    local event_date today_date
+    event_date=$(date -r "$epoch" +%Y-%m-%d 2>/dev/null || \
+                 date -d "@$epoch" +%Y-%m-%d 2>/dev/null || echo "")
+    today_date=$(date +%Y-%m-%d)
+    if [ -z "$event_date" ] || [ "$event_date" = "$today_date" ]; then echo "today"
+    else
+      local today_e event_e
+      today_e=$(date -j -f "%Y-%m-%d" "$today_date" +%s 2>/dev/null || \
+                date -d "$today_date" +%s 2>/dev/null || echo "$now")
+      event_e=$(date -j -f "%Y-%m-%d" "$event_date" +%s 2>/dev/null || \
+                date -d "$event_date" +%s 2>/dev/null || echo "$epoch")
+      local days=$(( (today_e - event_e) / 86400 ))
+      [ "$days" -lt 1 ] && days=1
+      if [ "$days" -eq 1 ]; then echo "yesterday"
+      else echo "${days}d ago"
+      fi
+    fi
+  fi
+}
+
+# Millisecond timer (for latency measurement)
+_millis() {
+  if command -v gdate &>/dev/null; then
+    gdate +%s%3N
+  else
+    python3 -c "import time; print(int(time.time() * 1000))" 2>/dev/null || echo "0"
+  fi
+}

package/runtime/codex/bin/lib/worktree-links.sh

@@ -0,0 +1,54 @@
+# shellcheck shell=bash
+# worktree-links.sh - shared-state bootstrap for git worktrees.
+#
+# Claude Code worktrees are normally created through bin/worktree-create.sh,
+# which links memory/, .env, and local state from the main checkout. Portable
+# runtimes such as Codex can land in a plain git worktree, so startup and
+# agent.sh use this helper to self-heal those links before reading context.
+
+egregore_main_project_dir() {
+  local project_dir="${1:?project dir required}"
+  if [ -f "$project_dir/.git" ]; then
+    local wt_gitdir
+    wt_gitdir=$(sed 's/^gitdir: //' "$project_dir/.git" 2>/dev/null || true)
+    if [ -n "$wt_gitdir" ]; then
+      cd "$wt_gitdir/../../.." 2>/dev/null && pwd
+      return
+    fi
+  fi
+  cd "$project_dir" 2>/dev/null && pwd
+}
+
+egregore_link_shared_state() {
+  local worktree_dir="${1:?worktree dir required}"
+  local main_dir="${2:-}"
+  local file src dst resolved
+
+  [ -f "$worktree_dir/.git" ] || return 0
+  [ -n "$main_dir" ] || main_dir="$(egregore_main_project_dir "$worktree_dir")"
+  [ -n "$main_dir" ] || return 0
+  [ "$main_dir" != "$worktree_dir" ] || return 0
+
+  for file in memory .env .egregore-state.json .egregore-session-id; do
+    src="$main_dir/$file"
+    dst="$worktree_dir/$file"
+
+    if [ "$file" = "memory" ]; then
+      if [ -L "$src" ] || [ -d "$src" ]; then
+        resolved="$(realpath "$src" 2>/dev/null || true)"
+        [ -n "$resolved" ] && [ -d "$resolved" ] || continue
+        src="$resolved"
+      else
+        continue
+      fi
+    else
+      [ -f "$src" ] || continue
+    fi
+
+    if [ -L "$dst" ]; then
+      ln -sfn "$src" "$dst" 2>/dev/null || true
+    elif [ ! -e "$dst" ]; then
+      ln -s "$src" "$dst" 2>/dev/null || true
+    fi
+  done
+}

package/runtime/codex/bin/notify.sh

@@ -0,0 +1,207 @@
+#!/bin/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." >&2
+  exit 1
+fi
+
+# --- Mode detection ---
+_MODE=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null)
+
+# Public relay for local mode group messages.
+# No API key needed — rate-limited, group messages only.
+RELAY_URL="https://egregore-production-55f2.up.railway.app"
+
+# 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
+
+# Check if API mode or direct mode
+# 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:-}"
+
+if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
+  # === API MODE: Call Egregore API gateway ===
+
+  send_to_person() {
+    local name="$1"
+    local message="$2"
+
+    local response
+    response=$(curl -s -X POST "${API_URL}/api/notify/send" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n --arg to "$name" --arg message "$message" \
+        '{to: $to, message: $message}')" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "sent"' >/dev/null 2>&1; then
+      echo "Sent"
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"send","status":"sent"}' 2>/dev/null &
+    else
+      local detail
+      detail=$(echo "$response" | jq -r '.detail // .status // "unknown error"')
+      if echo "$detail" | grep -qi "forbidden\|can't initiate\|bot was blocked"; then
+        echo "Failed: DM not available. Tell $name to message the Egregore bot first (/start)."
+      else
+        echo "Failed: $detail"
+      fi
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"send","status":"failed"}' 2>/dev/null &
+    fi
+  }
+
+  send_to_group() {
+    local message="$1"
+
+    local response
+    response=$(curl -s -X POST "${API_URL}/api/notify/group" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n --arg message "$message" '{message: $message}')" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "sent"' >/dev/null 2>&1; then
+      echo "Sent"
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"group","status":"sent"}' 2>/dev/null &
+    else
+      local detail
+      detail=$(echo "$response" | jq -r '.detail // .status // "unknown error"')
+      echo "Failed: $detail"
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"group","status":"failed"}' 2>/dev/null &
+    fi
+  }
+
+  test_connection() {
+    local response
+    response=$(curl -s -X GET "${API_URL}/api/notify/test" \
+      -H "Authorization: Bearer $API_KEY" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "ok"' >/dev/null 2>&1; then
+      echo "Telegram connected via Egregore API"
+    else
+      echo "Failed to connect" >&2
+      echo "$response" >&2
+      exit 1
+    fi
+  }
+
+elif [ "$_MODE" = "local" ]; then
+  # === LOCAL MODE: Group messages via public relay, DMs not available ===
+  # Telegram config: prefer .egregore-state.json (symlinked across worktrees),
+  # fall back to egregore.json for backward compatibility.
+  STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
+
+  _read_telegram_config() {
+    local field="$1"
+    local val
+    val=$(jq -r ".$field // empty" "$STATE_FILE" 2>/dev/null)
+    [ -z "$val" ] && val=$(jq -r ".$field // empty" "$CONFIG" 2>/dev/null)
+    echo "$val"
+  }
+
+  send_to_person() {
+    echo "DMs require managed hosting. Group message sent instead."
+    send_to_group "@${1}: ${2}"
+  }
+
+  send_to_group() {
+    local message="$1"
+    local chat_id
+    chat_id=$(_read_telegram_config telegram_chat_id)
+    local group_link
+    group_link=$(_read_telegram_config telegram_group_link)
+
+    if [ -z "$chat_id" ] && [ -z "$group_link" ]; then
+      echo '{"status":"offline","reason":"no_telegram_group"}'
+      return
+    fi
+
+    local slug
+    slug=$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)
+    local org_name
+    org_name=$(jq -r '.org_name // empty' "$CONFIG" 2>/dev/null)
+
+    local response
+    response=$(curl -s -X POST "${RELAY_URL}/api/notify/relay" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n \
+        --arg chat_id "$chat_id" \
+        --arg group_link "$group_link" \
+        --arg message "$message" \
+        --arg slug "$slug" \
+        --arg org_name "$org_name" \
+        '{chat_id: $chat_id, group_link: $group_link, message: $message, slug: $slug, org_name: $org_name}')" \
+      --max-time 10 2>/dev/null)
+
+    if echo "$response" | jq -e '.status == "sent"' >/dev/null 2>&1; then
+      echo "Sent"
+    else
+      local detail
+      detail=$(echo "$response" | jq -r '.detail // .status // "relay unavailable"' 2>/dev/null)
+      echo "Failed: $detail"
+    fi
+  }
+
+  test_connection() {
+    local group_link
+    group_link=$(_read_telegram_config telegram_group_link)
+    if [ -n "$group_link" ]; then
+      echo "Telegram group configured (local mode — group messages via relay)"
+    else
+      echo "No Telegram group configured. Run /telegram-connect."
+    fi
+  }
+
+else
+  # === OFFLINE MODE: No API key, not local — skip notifications ===
+  send_to_person() { echo '{"status":"offline","reason":"no_api_key"}'; }
+  send_to_group() { echo '{"status":"offline","reason":"no_api_key"}'; }
+  test_connection() { echo '{"status":"offline","reason":"no_api_key"}'; }
+fi
+
+case "${1:-help}" in
+  send)
+    recipient="${2:?Usage: notify.sh send <name> <message>}"
+    message="${3:?Usage: notify.sh send <name> <message>}"
+    result=$(send_to_person "$recipient" "$message")
+    if [[ "$result" == Failed* ]]; then
+      send_to_group "@${recipient}: ${message}"
+      echo "DM failed, sent to group instead. ${result}"
+    else
+      echo "$result"
+    fi
+    ;;
+  group)
+    message="${2:?Usage: notify.sh group <message>}"
+    send_to_group "$message"
+    ;;
+  file)
+    echo "File upload not yet supported via API. Use direct mode." >&2
+    exit 1
+    ;;
+  test)
+    test_connection
+    ;;
+  help|*)
+    echo "Usage: notify.sh <command>"
+    echo ""
+    echo "Commands:"
+    echo "  send <name> <message>   Send DM to a person (auto-fallback to group on failure)"
+    echo "  group <message>         Send to the group chat"
+    echo "  file <path> [caption]   Send a file to the group chat"
+    echo "  test                    Test connection"
+    ;;
+esac

package/runtime/codex/bin/publish-artifact.sh

@@ -0,0 +1,187 @@
+#!/bin/bash
+set -euo pipefail
+
+# publish-artifact.sh — Generate HTML artifact + upload to API
+# Usage: publish-artifact.sh <type> <file> [--title "..."] [--author "..."] [--description "..."] [--id "..."] [--raw-html] [--no-references]
+#
+# Connected mode (API key present): publishes to /api/artifacts/publish (permanent, org-scoped)
+# OSS mode (no API key): publishes to /api/artifacts/share (ephemeral, 7-day TTL)
+#
+# --id <slug>: stable artifact ID — re-publishing with the same ID upserts the content
+#              at the same URL (e.g. egregore.xyz/view/{org}/board). Connected mode only;
+#              ignored in OSS mode. Must be 1-50 chars, alphanumeric/hyphen/underscore.
+#
+# --raw-html:  Skip the egregore-artifacts render step and upload <file> directly.
+#              Use for already-rendered HTML attachments referenced from a handoff.
+#
+# --no-references: Skip the depth-1 auto-publish of backtick-referenced memory files.
+#              Set automatically when publish-references.sh invokes us for a child,
+#              preventing recursion.
+#
+# Outputs artifact URL on success, exits silently on failure.
+# Designed for fire-and-forget use: `bash bin/publish-artifact.sh handoff file.md &`
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+# --- Parse arguments ---
+TYPE=""
+FILE=""
+TITLE=""
+AUTHOR=""
+DESCRIPTION=""
+ARTIFACT_ID=""
+RAW_HTML=0
+SKIP_REFERENCES=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --title) TITLE="$2"; shift 2 ;;
+    --author) AUTHOR="$2"; shift 2 ;;
+    --description) DESCRIPTION="$2"; shift 2 ;;
+    --id) ARTIFACT_ID="$2"; shift 2 ;;
+    --raw-html) RAW_HTML=1; shift ;;
+    --no-references) SKIP_REFERENCES=1; shift ;;
+    *)
+      if [ -z "$TYPE" ]; then
+        TYPE="$1"
+      elif [ -z "$FILE" ]; then
+        FILE="$1"
+      fi
+      shift ;;
+  esac
+done
+
+if [ -z "$TYPE" ] || [ -z "$FILE" ]; then
+  echo "Usage: publish-artifact.sh <type> <file> [--title ...] [--author ...] [--description ...] [--id ...]" >&2
+  exit 1
+fi
+
+# Validate --id format if provided (matches API regex ^[a-zA-Z0-9_-]{1,50}$)
+if [ -n "$ARTIFACT_ID" ] && ! [[ "$ARTIFACT_ID" =~ ^[a-zA-Z0-9_-]{1,50}$ ]]; then
+  echo "--id must be 1-50 chars, alphanumeric/hyphen/underscore only" >&2
+  exit 1
+fi
+
+if [ ! -f "$FILE" ]; then
+  echo "File not found: $FILE" >&2
+  exit 1
+fi
+
+# --- Load config ---
+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)}"
+  EGREGORE_USE_PUBLISHED="${EGREGORE_USE_PUBLISHED:-$(grep '^EGREGORE_USE_PUBLISHED=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)}"
+fi
+
+API_URL="${EGREGORE_API_URL:-$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)}"
+API_KEY="${EGREGORE_API_KEY:-}"
+ORG_SLUG="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
+VIEW_BASE="https://egregore.xyz/view"
+
+# Resolve "use published renderer" from env first, then egregore.json. The
+# env var lets individuals override per-shell; egregore.json lets an
+# instance (e.g. the upstream dev repo) opt in for every teammate.
+if [ -z "${EGREGORE_USE_PUBLISHED:-}" ]; then
+  CONFIG_USE_PUBLISHED="$(jq -r '.prefer_published_artifacts // empty' "$CONFIG" 2>/dev/null)"
+  if [ "$CONFIG_USE_PUBLISHED" = "true" ]; then
+    EGREGORE_USE_PUBLISHED=1
+  fi
+fi
+
+# Public relay for OSS share endpoint
+RELAY_URL="https://egregore-production-55f2.up.railway.app"
+
+# --- Prepare HTML ---
+TMP_HTML="/tmp/egregore-artifacts/publish-$$.html"
+mkdir -p /tmp/egregore-artifacts
+
+if [ "$RAW_HTML" -eq 1 ]; then
+  # Upload the file as-is (used for pre-rendered HTML attachments).
+  cp "$FILE" "$TMP_HTML" 2>/dev/null || exit 0
+else
+  # Pass --org-slug + --view-base so the renderer can emit clickable links
+  # for backtick `memory/*.{md,html}` references. Only when connected AND the
+  # slug is known — in OSS mode we leave them empty so rendering falls back
+  # to plain <code> and we don't produce dead links.
+  RENDER_ARGS=("$TYPE" "$FILE" --output "$TMP_HTML")
+  if [ -n "$API_KEY" ] && [ -n "$ORG_SLUG" ]; then
+    RENDER_ARGS+=(--org-slug "$ORG_SLUG" --view-base "$VIEW_BASE")
+  fi
+
+  # Prefer the in-repo package copy when it's present AND its dependencies
+  # have been installed — that way local edits to packages/egregore-artifacts
+  # are exercised without waiting for an npm release. Fall back to the
+  # published `npx egregore-artifacts` otherwise.
+  # Set EGREGORE_USE_PUBLISHED=1 to force the npm-published renderer even
+  # when a local install is present — useful in the upstream dev repo to
+  # dogfood what teammates and OSS users actually run.
+  LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+  if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
+    if ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>&1; then
+      exit 0
+    fi
+  else
+    if ! npx egregore-artifacts "${RENDER_ARGS[@]}" >/dev/null 2>&1; then
+      exit 0
+    fi
+  fi
+fi
+
+if [ ! -f "$TMP_HTML" ]; then
+  exit 0
+fi
+
+# Default title from filename if not provided
+if [ -z "$TITLE" ]; then
+  TITLE="$(basename "$FILE" | sed 's/\.[^.]*$//' | sed 's/[-_]/ /g')"
+fi
+
+# --- Upload ---
+RESPONSE=""
+
+if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
+  # Connected mode: permanent, org-scoped
+  RESPONSE=$(curl -s -X POST "${API_URL}/api/artifacts/publish" \
+    -H "Authorization: Bearer $API_KEY" \
+    -F "file=@${TMP_HTML}" \
+    -F "artifact_type=${TYPE}" \
+    -F "title=${TITLE}" \
+    -F "author=${AUTHOR}" \
+    -F "description=${DESCRIPTION}" \
+    -F "artifact_id=${ARTIFACT_ID}" \
+    --max-time 15 2>/dev/null) || true
+else
+  # OSS mode: ephemeral, 7-day TTL
+  RESPONSE=$(curl -s -X POST "${RELAY_URL}/api/artifacts/share" \
+    -F "file=@${TMP_HTML}" \
+    -F "artifact_type=${TYPE}" \
+    -F "title=${TITLE}" \
+    -F "author=${AUTHOR}" \
+    -F "description=${DESCRIPTION}" \
+    --max-time 15 2>/dev/null) || true
+fi
+
+# Clean up
+rm -f "$TMP_HTML"
+
+# Output URL if successful
+URL=""
+if [ -n "$RESPONSE" ]; then
+  URL=$(echo "$RESPONSE" | jq -r '.url // empty' 2>/dev/null)
+  if [ -n "$URL" ]; then
+    echo "$URL"
+  fi
+fi
+
+# Depth-1 auto-publish of backtick-referenced memory files so the clickable
+# links in the rendered parent resolve. Connected mode only; the helper exits
+# silently in OSS mode. Skipped when:
+#   - parent publish failed (no URL),
+#   - --raw-html (HTML attachments don't embed markdown refs we'd parse),
+#   - --no-references (caller explicitly opts out / recursion guard).
+if [ -n "$URL" ] && [ "$RAW_HTML" -eq 0 ] && [ "$SKIP_REFERENCES" -eq 0 ]; then
+  bash "$SCRIPT_DIR/bin/publish-references.sh" "$FILE" >/dev/null 2>&1 &
+  disown 2>/dev/null || true
+fi