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

package/runtime/claude/bin/prime-render-spec.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Derive Prime Agent's project-local system appendix from the generated Codex
+// protocol. CLAUDE.md remains canonical:
+// CLAUDE.md -> AGENTS.md -> .prime/agent/APPEND_SYSTEM.md.
+// The second hop deliberately reuses the reviewed shell-runtime translation,
+// then adapts only the harness surfaces that differ between Codex and Prime.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = path.join(ROOT, "AGENTS.md");
+const OUTPUT = path.join(ROOT, ".prime", "agent", "APPEND_SYSTEM.md");
+const MANIFEST = path.join(ROOT, ".prime", "agent", "spec-manifest.json");
+const CODEX_BEGIN = "<!-- BEGIN GENERATED EGREGORE CODEX SPEC";
+const CODEX_END = "<!-- END GENERATED EGREGORE CODEX SPEC -->";
+
+function hash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function extractSpec(source) {
+  const begin = source.indexOf(CODEX_BEGIN);
+  const contentStart = source.indexOf("\n", begin);
+  const end = source.indexOf(CODEX_END, contentStart);
+  if (begin < 0 || contentStart < 0 || end < 0) {
+    throw new Error("AGENTS.md does not contain the generated Codex spec");
+  }
+  return source.slice(contentStart + 1, end).trim();
+}
+
+function replaceSection(markdown, heading, body) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  return `${markdown.slice(0, start)}${marker}\n\n${body}${markdown.slice(end)}`;
+}
+
+// Keep an inherited section and put runtime-specific framing in front of it.
+// Command Awareness is the case that matters: the canonical category rows and
+// disambiguation map live in CLAUDE.md, and a full replace here silently
+// shipped a truncated copy that drifted for months. The Codex spec opens the
+// section with its own skills-not-slash-commands paragraph, which is wrong for
+// a runtime that does have slash commands, so that one paragraph is dropped.
+function prependToSection(markdown, heading, body, dropLeadParagraphStartingWith) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  let inherited = markdown.slice(start + marker.length, end).trim();
+  if (dropLeadParagraphStartingWith) {
+    if (!inherited.startsWith(dropLeadParagraphStartingWith)) {
+      throw new Error(`prime-render-spec: "${heading}" no longer opens with "${dropLeadParagraphStartingWith}" — the Codex wording moved; update this adaptation`);
+    }
+    inherited = inherited.slice(inherited.indexOf("\n\n") + 2).trim();
+  }
+  return replaceSection(markdown, heading, `${body}\n\n${inherited}`);
+}
+
+const CODEX_COMMAND_LEAD = "Codex reserves leading";
+
+function adapt(sourceSpec) {
+  // Anchored replacements: every `from` string MUST exist in the generated
+  // Codex spec — a missing anchor no-ops silently and drops Prime-specific
+  // wording (see the tool_call gate incident). Fail the render loudly instead.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Prime Agent"],
+    ["Codex-native", "Prime-native"],
+    ["Codex sessions", "Prime Agent sessions"],
+    ["On Codex", "On Prime Agent"],
+    ["Codex has no", "Prime Agent has no built-in"],
+    ["bin/codex-session-start.sh", "bin/prime-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".prime/agent/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded from the project-local extension)"],
+    ["If this Codex build does not support hooks", "If Prime Agent project extensions are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.prime/agent/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`prime-render-spec: anchor not found in generated Codex spec: "${from}" — the Codex wording moved; update this replacement`);
+    }
+    text = text.replaceAll(from, to);
+  }
+  text = text
+    .replace(/`\$([a-z][a-z0-9-]*)/g, "`/$1")
+    .replace(/\$([a-z][a-z0-9-]*)/g, "/$1");
+
+  text = replaceSection(text, "Egregore on Prime Agent", `You are Prime Agent running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Prime Agent resources, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This appendix is generated from the reviewed shell-runtime translation of \`CLAUDE.md\`, the behavioral source of truth. Prime Agent loads it through \`.prime/agent/APPEND_SYSTEM.md\`. Egregore workflows are shared from \`.codex/skills/\` through the Agent Skills standard (via \`.agents/skills\` and project settings) and exposed as familiar slash commands by \`.prime/agent/extensions/egregore.ts\`.
+
+Your subagent mechanism (\`rlm(...)\`) spawns Prime Agent child sessions, not Egregore Loom lanes. Ignore Loom routing preambles inside shared skills: run those workflows inline.`);
+
+  text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Prime Agent extension renders the Egregore startup card (identity, handoffs, team activity) inside the session via \`bin/prime-session-start.sh\`. This works for direct \`prime-agent\` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Prime Agent, run \`bash bin/prime-session-start.sh --card\`.`);
+
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Prime Agent slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.prime/agent/extensions/egregore.ts\`; the duplicate \`/skill:name\` listings are disabled so each workflow appears once. Natural-language requests work normally — and are the route for any workflow whose name collides with a Prime Agent built-in: **say "update egregore" rather than typing \`/update\`**, which is Prime Agent's own self-updater. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
+
+Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Prime Agent, run referenced \`bin/\` scripts through the IPython kernel (or the bash tool when active), use ordinary shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no UI question surface is available.
+
+The \`egregore\` Python-backed skill exposes the mechanics as kernel functions — \`import egregore\`, then \`egregore.search(query)\`, \`egregore.activity()\`, \`egregore.handoff(to, topic, body)\`, \`egregore.save(message, topic)\`, \`egregore.branch(topic)\`, \`egregore.notify_plan(recipient, message)\`. Prefer these over re-deriving \`bin/\` CLI usage by reading scripts. \`notify_plan\` is proposal-only: approval and dispatch always pass through the explicit human Send / Edit / Cancel checkpoint.
+
+"Get the latest changes" inside a session means \`/reload\` — it re-reads instructions, context files, skills, and extensions from disk. Never \`git pull\`, \`git reset\`, or \`git checkout\` the working branch to pick up updates. When pivoting topics inside a worktree that carries unmerged branch work, create the new branch from the current HEAD, not \`origin/{base}\` — branching from the configured base in such a worktree removes the unmerged files from disk.
+
+Kernel shell escapes can be time-capped by the harness. Egregore \`bin/\` scripts that sync git state or query the connected graph legitimately run 10–120 seconds: run them with a generous timeout (a \`%%bash\` cell, or the longest limit the harness exposes). If a command dies suspiciously fast (~5s) with partial output, treat it as a timeout — rerun once with a longer limit or render the workflow's designed one-line fallback. Never debug data plumbing inside a product workflow. Connected mode works normally here: graph reads and \`bin/search.sh\` enrichment use the instance's configured credentials, and when graph data is degraded say so in one plain line rather than narrating connectivity theories.`, CODEX_COMMAND_LEAD);
+
+  return `# Egregore on Prime Agent\n\nThis file is generated by \`bin/prime-render-spec.mjs\`; do not edit it by hand.\n\n${text}\n`;
+}
+
+const check = process.argv.includes("--check");
+const source = fs.readFileSync(SOURCE, "utf8");
+const sourceSpec = extractSpec(source);
+const rendered = adapt(sourceSpec);
+const manifest = `${JSON.stringify({
+  generatedBy: "bin/prime-render-spec.mjs",
+  source: "AGENTS.md generated Codex spec",
+  sourceHash: hash(sourceSpec),
+  outputHash: hash(rendered),
+  adaptations: [
+    "Prime Agent APPEND_SYSTEM delivery from .prime/agent/",
+    "Prime Agent tool_call branch gate incl. ipython classification",
+    "Prime Agent slash-command extension over shared portable skills",
+    "rlm() subagents are not Loom lanes; Loom preambles run inline",
+  ],
+}, null, 2)}\n`;
+
+if (check) {
+  const currentOutput = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
+  const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, "utf8") : "";
+  if (currentOutput !== rendered || currentManifest !== manifest) {
+    console.error("prime spec out of date — run: bash bin/node-run.sh bin/prime-render-spec.mjs");
+    process.exit(1);
+  }
+  console.log("prime spec up to date");
+} else {
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, rendered);
+  fs.writeFileSync(MANIFEST, manifest);
+  console.log(`prime spec rendered: .prime/agent/APPEND_SYSTEM.md (${Buffer.byteLength(rendered)} bytes)`);
+}

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

@@ -0,0 +1,324 @@
+#!/usr/bin/env 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 on a PUBLIC, UNAUTHENTICATED
+#   relay (ephemeral, 7-day TTL). OFF unless the instance opted in — see
+#   "Public-relay opt-in" below and `bin/settings.sh relay on`.
+#
+# --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 soft failure.
+# Designed for fire-and-forget use: `bash bin/publish-artifact.sh handoff file.md &`
+#
+# Exit codes: 0 ok (or soft failure — no URL on stdout) · 1 usage/validation
+#             3 hosting turned off (features.publishing=false)
+#             4 nothing uploaded — public relay not enabled and no org API key,
+#               or egregore.json is missing/unreadable (fail closed)
+#             5 renderer/fidelity validation failed (nothing uploaded)
+
+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
+ALLOW_ADMIN=0
+PAIR=""
+VERIFY_FIDELITY=0
+FIDELITY_SOURCE=""
+
+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 ;;
+    --pair) PAIR="$2"; shift 2 ;;
+    --verify-fidelity) VERIFY_FIDELITY=1; shift ;;
+    --source) FIDELITY_SOURCE="$2"; shift 2 ;;
+    --raw-html) RAW_HTML=1; shift ;;
+    --allow-admin) ALLOW_ADMIN=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
+
+# A config we cannot parse is a config we cannot trust. Every routing decision
+# below — authenticated org upload vs. public relay, hosting on vs. off — is
+# read out of this file, so an unreadable one means we cannot tell those apart.
+if [ ! -f "$CONFIG" ] || ! jq -e 'type == "object"' "$CONFIG" >/dev/null 2>&1; then
+  echo "Not published — nothing left this machine." >&2
+  echo "egregore.json is missing or unreadable, so there is no way to tell an authenticated org upload from a public one." >&2
+  exit 4
+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. Unauthenticated: anything posted here is
+# readable by anyone holding the URL, for 7 days, with nothing in front of it.
+RELAY_URL="https://egregore-production-55f2.up.railway.app"
+
+# --- Artifact hosting off-switch (compliance / privacy) ---
+# An instance can disable ALL egregore.xyz publishing via `bin/settings.sh hosting off`
+# (sets features.publishing=false). Absent/true means ON, so existing instances are
+# unaffected. We bail BEFORE any render or upload so "off" truly does nothing and costs
+# nothing. Exit 3 is distinct from usage errors; fire-and-forget callers ignore it.
+# NOTE: test `!= false`, not jq's `// "true"` — `//` treats an explicit `false` as empty
+# and would return the default, silently defeating the off-switch.
+PUBLISHING_ENABLED="$(jq -r 'if .features.publishing == false then "false" else "true" end' "$CONFIG" 2>/dev/null || echo "true")"
+if [ "$PUBLISHING_ENABLED" = "false" ]; then
+  echo "Artifact hosting is off for this egregore (features.publishing=false); nothing uploaded." >&2
+  echo "Turn it on with: bin/settings.sh hosting on   (or: egregore settings → Hosting)." >&2
+  exit 3
+fi
+
+# --- Public-relay opt-in (privacy) ---
+# Without BOTH an api_url and an org API key there is exactly one upload route
+# left: the unauthenticated public relay below. Content must not leave the
+# machine for that route unless a person explicitly enabled it. The gate sits
+# before rendering so the default path generates and uploads nothing.
+#
+# NOTE: use an explicit `== true` test, never jq's `// false`: `//` treats an
+# explicit false like null and silently replaces it with the default.
+if [ -z "$API_URL" ] || [ -z "$API_KEY" ]; then
+  PUBLIC_RELAY_ENABLED="$(jq -r 'if .features.public_relay == true then "true" else "false" end' "$CONFIG" 2>/dev/null || echo "false")"
+  if [ "$PUBLIC_RELAY_ENABLED" != "true" ]; then
+    echo "Not published — nothing left this machine." >&2
+    echo "Without an org API key the only sharing route is a public relay: no auth, anyone with the link can read it, expires after 7 days. It is off unless you turn it on." >&2
+    echo "Turn it on with: bin/settings.sh relay on" >&2
+    exit 4
+  fi
+fi
+
+# --- Admin-content gate (the refusal documented in bin/lib/permissions.sh) --
+# `admin: true` sources — including backtick-referenced memory files — are
+# refused before any render or upload. An authorized admin (stable identity,
+# github.username alias against egregore.json admins) may proceed only with
+# the explicit --allow-admin confirmation, which is separate from and never
+# replaces normal publication approval. This protects the Egregore surface;
+# repository members can still read raw Git files.
+# shellcheck source=bin/lib/permissions.sh
+source "$SCRIPT_DIR/bin/lib/permissions.sh"
+ADMIN_MARKED=()
+if _is_admin_only_file "$FILE"; then
+  ADMIN_MARKED+=("$FILE")
+fi
+if [ "$RAW_HTML" -eq 0 ]; then
+  while IFS= read -r ref; do
+    [ -z "$ref" ] && continue
+    rel="${ref#\`}"
+    rel="${rel%\`}"
+    if [ -f "$SCRIPT_DIR/$rel" ] && _is_admin_only_file "$SCRIPT_DIR/$rel"; then
+      ADMIN_MARKED+=("$rel")
+    fi
+  done < <(grep -Eo '`memory/[^`[:space:]]+\.(md|html)`' "$FILE" 2>/dev/null | sort -u)
+fi
+if [ "${#ADMIN_MARKED[@]}" -gt 0 ]; then
+  IS_ADMIN="false"
+  ADMIN_JSON=$(cd "$SCRIPT_DIR" && EGREGORE_ROOT="$SCRIPT_DIR" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.harness_cli admin-status 2>/dev/null) || true
+  IS_ADMIN=$(printf '%s' "$ADMIN_JSON" | jq -r '.admin // false' 2>/dev/null || echo "false")
+  if [ "$IS_ADMIN" != "true" ]; then
+    echo "publish refused: admin-marked content cannot be published by a non-admin member:" >&2
+    printf '  %s\n' "${ADMIN_MARKED[@]}" >&2
+    echo "(--allow-admin is available to organization admins only)" >&2
+    exit 5
+  fi
+  if [ "$ALLOW_ADMIN" -ne 1 ]; then
+    echo "publish refused: this content is admin-marked:" >&2
+    printf '  %s\n' "${ADMIN_MARKED[@]}" >&2
+    echo "re-run with --allow-admin to confirm publishing admin-marked content" >&2
+    echo "(this confirmation is separate from normal publication approval)" >&2
+    exit 5
+  fi
+fi
+
+# --- 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
+  # Palette family (meridian default | agronomic | sovereign). Role-token driven,
+  # so it themes any composed artifact with no extra CSS.
+  if [ -n "$PAIR" ]; then
+    RENDER_ARGS+=(--pair "$PAIR")
+  fi
+  if [ "$VERIFY_FIDELITY" -eq 1 ]; then
+    RENDER_ARGS+=(--verify-fidelity)
+    if [ "$TYPE" = "composed" ]; then
+      [ -n "$FIDELITY_SOURCE" ] || {
+        echo "Handoff fidelity check requires --source <canonical-handoff.md>" >&2
+        exit 1
+      }
+      RENDER_ARGS+=(--source "$FIDELITY_SOURCE")
+    fi
+  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"
+  RENDER_ERROR="/tmp/egregore-artifacts/render-error-$$.log"
+  if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
+    if ! bash "$SCRIPT_DIR/bin/node-run.sh" "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+      sed -n '1,4p' "$RENDER_ERROR" >&2
+      rm -f "$RENDER_ERROR"
+      exit 5
+    fi
+  else
+    # Installed published renderer only — never npx/@latest: a hidden
+    # registry fetch of a floating version is not an acceptable renderer.
+    PUBLISHED_CLI="$(command -v egregore-artifacts || true)"
+    if [ -z "$PUBLISHED_CLI" ]; then
+      echo "no artifact renderer available: the checked-out packages/egregore-artifacts is unusable and no installed egregore-artifacts was found" >&2
+      exit 5
+    fi
+    if ! bash "$SCRIPT_DIR/bin/node-run.sh" "$PUBLISHED_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+      sed -n '1,4p' "$RENDER_ERROR" >&2
+      rm -f "$RENDER_ERROR"
+      exit 5
+    fi
+  fi
+  rm -f "$RENDER_ERROR"
+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"
+    # Register in the local artifact registry (memory/artifacts/) so this hosted
+    # artifact is findable by CONTENT, not just name — grep/ls (Claude Code /
+    # Codex, OSS), and search + graph (paid). Never fatal to the publish.
+    bash "$SCRIPT_DIR/bin/artifact-register.sh" \
+      --id "$ARTIFACT_ID" --url "$URL" --type "$TYPE" --title "$TITLE" \
+      --author "$AUTHOR" --source "$FILE" --description "$DESCRIPTION" \
+      >/dev/null 2>&1 || true
+  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

package/runtime/claude/bin/publish-references.sh

@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# publish-references.sh — Depth-1 auto-publish for referenced memory files.
+#
+# Usage: publish-references.sh <source-markdown-file>
+#
+# Reads the source markdown, extracts backtick-wrapped references to
+# `memory/**/*.{md,html}` paths, and publishes each one in parallel with a
+# deterministic artifact id (see bin/lib/artifact-id.sh). The deterministic id
+# means the rendered parent view can construct a predictable link to each
+# referenced file *before* this script finishes — so even a slight delay
+# produces clickable links that resolve once the referenced publish completes.
+#
+# Connected mode only. Skips silently if EGREGORE_API_KEY is missing, because
+# the OSS relay ignores artifact ids and would assign random slugs.
+#
+# Fire-and-forget: silent on errors, does not block the caller, bounded
+# parallelism via EGREGORE_REF_PUBLISH_PARALLELISM (default 8).
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SOURCE_FILE="${1:-}"
+
+[ -n "$SOURCE_FILE" ] || exit 0
+[ -f "$SOURCE_FILE" ] || exit 0
+
+# --- Connected-mode check ---
+API_KEY="${EGREGORE_API_KEY:-}"
+if [ -z "$API_KEY" ] && [ -f "$SCRIPT_DIR/.env" ]; then
+  API_KEY="$(grep '^EGREGORE_API_KEY=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)"
+fi
+[ -n "$API_KEY" ] || exit 0
+
+# --- Helpers ---
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/bin/lib/artifact-id.sh"
+
+PARALLELISM="${EGREGORE_REF_PUBLISH_PARALLELISM:-8}"
+
+GIT_ROOT="$(git -C "$(dirname "$SOURCE_FILE")" rev-parse --show-toplevel 2>/dev/null || echo "$SCRIPT_DIR")"
+
+# Absolute, symlink-resolved path of the source file. Used below to compare
+# each resolved ref against the source and skip self-references. Using
+# symlink-resolved absolute paths means `memory/` as a symlink into a sibling
+# repo (and macOS's `/var` → `/private/var`) compare correctly — basename
+# comparison alone would falsely skip unrelated files that happen to share
+# a filename (e.g. date-prefixed handoffs, README.md, index.md).
+SOURCE_ABS="$(cd "$(dirname "$SOURCE_FILE")" 2>/dev/null && pwd -P)/$(basename "$SOURCE_FILE")"
+
+# Infer artifact type from path — mirrors egregore-artifacts/bin/cli.js inferType.
+infer_type() {
+  local fp="$1"
+  case "$fp" in
+    */quests/*)   echo "quest" ;;
+    */handoffs/*) echo "handoff" ;;
+    *)            echo "document" ;;
+  esac
+}
+
+# Resolve a backtick-referenced path to a real file on disk.
+resolve_ref() {
+  local ref="$1"
+  local src_dir
+  src_dir="$(dirname "$SOURCE_FILE")"
+  # Candidates: source file's repo-root resolution, then git root, then cwd.
+  local candidates=(
+    "$src_dir/../../$ref"
+    "$GIT_ROOT/$ref"
+    "$ref"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if [ -f "$c" ]; then
+      printf '%s' "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+publish_one() {
+  local ref="$1"
+  local resolved
+  resolved="$(resolve_ref "$ref")" || return 0
+  [ -n "$resolved" ] || return 0
+
+  # Self-ref guard: skip refs that resolve to the source file itself.
+  # Compared as symlink-resolved absolute paths so symlinked memory layouts
+  # (and unrelated files with the same basename) are handled correctly.
+  local resolved_abs
+  resolved_abs="$(cd "$(dirname "$resolved")" 2>/dev/null && pwd -P)/$(basename "$resolved")"
+  if [ "$resolved_abs" = "$SOURCE_ABS" ]; then
+    return 0
+  fi
+
+  local id
+  id="$(artifact_id_from_path "$ref")" || return 0
+  [ -n "$id" ] || return 0
+
+  case "$ref" in
+    *.md)
+      local type
+      type="$(infer_type "$ref")"
+      bash "$SCRIPT_DIR/bin/publish-artifact.sh" "$type" "$resolved" --id "$id" --no-references >/dev/null 2>&1 || true
+      ;;
+    *.html)
+      bash "$SCRIPT_DIR/bin/publish-artifact.sh" document "$resolved" --id "$id" --raw-html --no-references >/dev/null 2>&1 || true
+      ;;
+  esac
+}
+
+# --- Extract refs, dedupe, publish in parallel ---
+# grep -Eo prints each match on its own line; sed strips the surrounding
+# backticks; sort -u dedupes. No dependency on GNU grep -P.
+REFS="$(grep -Eo '`memory/[^`[:space:]]+\.(md|html)`' "$SOURCE_FILE" 2>/dev/null \
+  | sed 's/^`//; s/`$//' \
+  | sort -u)"
+
+[ -n "$REFS" ] || exit 0
+
+# Bounded parallelism — cap concurrent jobs at PARALLELISM.
+# On bash ≥ 4 (`wait -n`) this is rolling parallelism. On bash 3.2 (macOS
+# default /bin/bash), `wait -n` is unsupported and the `|| wait` fallback
+# drains the whole batch before spawning the next — effectively batch-parallel
+# of size PARALLELISM. Correct in both cases, just slower on bash 3.2.
+active=0
+while IFS= read -r ref; do
+  [ -n "$ref" ] || continue
+  # Self-reference filtering happens inside publish_one, after the ref is
+  # resolved to an absolute path — see the SOURCE_ABS check there.
+  publish_one "$ref" &
+  active=$((active + 1))
+  if [ "$active" -ge "$PARALLELISM" ]; then
+    if wait -n 2>/dev/null; then
+      active=$((active - 1))
+    else
+      wait
+      active=0
+    fi
+  fi
+done <<< "$REFS"
+
+wait 2>/dev/null || true
+exit 0

package/runtime/claude/bin/quest.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="$ROOT"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -m egregore_runtime.quest_cli "$@"

package/runtime/claude/bin/question.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Runtime-neutral shell adapter for canonical asynchronous questions.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+exec python3 -m egregore_runtime.question_cli "$@"