create-egregore 0.19.13 → 0.19.15

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.19.13
+// egregore-launcher-version: 0.19.15
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -33,7 +33,7 @@ const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.19.13";
+const VERSION = "0.19.15";
 const REGISTRY = path.join(os.homedir(), ".egregore", "instances.json");
 const DEFAULT_FILE = path.join(os.homedir(), ".egregore", "default");
 const UPDATE_CACHE_FILE = path.join(os.homedir(), ".egregore", "update-check.json");
@@ -701,6 +701,24 @@ function installCodexSkills(egregoreDir) {
   }
 }
 
+function claudeLaunchArgs(egregoreDir) {
+  const args = ["start"];
+  const memoryLink = path.join(egregoreDir, "memory");
+  try {
+    const memoryDir = fs.realpathSync(memoryLink);
+    if (fs.statSync(memoryDir).isDirectory()) {
+      // Egregore memory is intentionally a sibling Git repository. Declare it
+      // as part of Claude's workspace so auto mode does not classify normal
+      // organizational recall as an unexplained cross-project read.
+      args.push("--add-dir", memoryDir);
+    }
+  } catch {
+    // A missing/dangling memory link is diagnosed by session startup. Do not
+    // prevent the harness from opening.
+  }
+  return args;
+}
+
 function runtimeLaunchArgs(runtime, egregoreDir) {
   if (runtime === "codex") {
     return [
@@ -711,7 +729,7 @@ function runtimeLaunchArgs(runtime, egregoreDir) {
     ];
   }
   if (runtime === "pi") return piTrustArgs();
-  return ["start"];
+  return claudeLaunchArgs(egregoreDir);
 }
 
 async function launch(inst, runtimeOverride) {
@@ -1098,14 +1116,14 @@ function cmdCliUpdate(latest) {
     { encoding: "utf-8", stdio: ["inherit", "pipe", "pipe"], env: { ...process.env } },
   );
   if (result.status !== 0) {
-    console.log(`\r  [1/2] ${YELLOW}!${RESET} Install failed`);
+    console.log(`\r${ANSI.clearLine}  [1/2] ${YELLOW}!${RESET} Install failed`);
     const detail = String(result.stderr || result.stdout || "").trim().split("\n").filter(Boolean).pop();
     if (detail) console.error(`        ${DIM}${detail}${RESET}`);
     console.error(`        Retry: npx -y ${PUBLIC_NPX_PACKAGE}@${latest} --refresh-launcher\n`);
     process.exitCode = 1;
     return;
   }
-  console.log(`\r  [1/2] ${GREEN}✓${RESET} CLI ${latest} installed`);
+  console.log(`\r${ANSI.clearLine}  [1/2] ${GREEN}✓${RESET} CLI ${latest} installed`);
 
   if (process.env.EGREGORE_UPDATE_NO_RELAUNCH === "1") {
     console.log(`  [2/2] ${GREEN}✓${RESET} Ready for the next launch\n`);
@@ -1250,12 +1268,42 @@ async function cmdConnect(args) {
 
   let intentId = activation.intent_id || "";
   let connectUrl = activation.connect_url || "";
-  if (!intentId || !["checkout_pending", "entitled", "backfilling"].includes(activation.status)) {
+  let ticketExpiresAt = Number(activation.connect_ticket_expires_at || 0) * 1000;
+  const resumable = ["created", "checkout_pending", "entitled", "provisioning", "backfilling"].includes(
+    activation.status,
+  );
+  if (
+    intentId &&
+    resumable &&
+    (!activation.connect_ticket || !ticketExpiresAt || ticketExpiresAt <= Date.now() + 60_000)
+  ) {
+    const refreshed = await connectedApiRequest(
+      githubToken,
+      "POST",
+      `/api/billing/connect/${encodeURIComponent(intentId)}/ticket`,
+      {},
+    );
+    if (refreshed.status !== 200) {
+      die(`could not refresh Connected link: ${connectError(refreshed, `HTTP ${refreshed.status}`)}`);
+    }
+    connectUrl = refreshed.data.connect_url;
+    ticketExpiresAt = Number(refreshed.data.connect_ticket_expires_at || 0) * 1000;
+    persistConnectState(inst, {
+      connect_ticket: refreshed.data.connect_ticket,
+      connect_ticket_expires_at: refreshed.data.connect_ticket_expires_at,
+      connect_url: connectUrl,
+      status: refreshed.data.status || activation.status,
+    });
+  }
+  if (
+    !intentId ||
+    !resumable
+  ) {
     console.log(`  [1/5] ${DIM}Creating connection intent…${RESET}`);
     const checkout = await connectedApiRequest(
       githubToken,
       "POST",
-      "/api/billing/checkout",
+      "/api/billing/connect-intents",
       {
         org_slug: cfg.slug || inst.slug,
         plan: "connect",
@@ -1275,9 +1323,10 @@ async function cmdConnect(args) {
     connectUrl = checkout.data.connect_url;
     persistConnectState(inst, {
       intent_id: intentId,
-      checkout_session_id: checkout.data.checkout_session_id,
+      connect_ticket: checkout.data.connect_ticket,
+      connect_ticket_expires_at: checkout.data.connect_ticket_expires_at,
       connect_url: connectUrl,
-      status: "checkout_pending",
+      status: checkout.data.status || "created",
     });
     console.log(`  [1/5] ${GREEN}✓${RESET} Connection intent`);
   } else {
@@ -1369,12 +1418,17 @@ async function cmdConnect(args) {
   let backfillSummary = { replayed: true };
   try { backfillSummary = JSON.parse((sync.stdout || "").trim()); } catch {}
 
-  const complete = await connectedApiRequest(
-    githubToken,
-    "POST",
-    `/api/billing/connect/${encodeURIComponent(intentId)}/complete`,
-    { backfill_summary: backfillSummary },
-  );
+  let complete;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    complete = await connectedApiRequest(
+      githubToken,
+      "POST",
+      `/api/billing/connect/${encodeURIComponent(intentId)}/complete`,
+      { backfill_summary: backfillSummary },
+    );
+    if (complete.status === 200 || complete.status !== 0) break;
+    await sleep(250 * (attempt + 1));
+  }
   if (complete.status !== 200) {
     die(`graph replay finished, but activation could not be finalized: ${connectError(complete, `HTTP ${complete.status}`)}`);
   }
@@ -1839,6 +1893,11 @@ function renderHeroPanel({ selected, pv, width, height, countSuffix, filter, fil
   const top = `${margin}${DIM}┌${"─".repeat(2)}${label}${"─".repeat(Math.max(0, innerWidth - label.length - 2))}┐${RESET}`;
   const bottom = `${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`;
   const mid = `${margin}${DIM}├${"─".repeat(innerWidth)}┤${RESET}`;
+  const updateBand = cliUpdate?.available
+    ? (colorOn
+      ? `${margin}${DIM}│${RESET}${E(43)}${E(30)}${pad(`  CLI UPDATE AVAILABLE · ${cliUpdate.current} → ${cliUpdate.latest} · ${E(1)}U${E(22)} INSTALL`, innerWidth)}${RESET}${DIM}│${RESET}`
+      : `${margin}│${pad(`  CLI UPDATE AVAILABLE · ${cliUpdate.current} → ${cliUpdate.latest} · U INSTALL`, innerWidth)}│`)
+    : null;
   const lines = [top];
 
   const title = selected ? `${selected.slug || selected.name || "egregore"}` : "egregore";
@@ -1879,20 +1938,10 @@ function renderHeroPanel({ selected, pv, width, height, countSuffix, filter, fil
     lines.push(boxLine(`${BOLD}${CYAN}EGREGORE${RESET} ${DIM}v${VERSION} · ${countSuffix} · ${filterText}${RESET}`, innerWidth, margin));
   }
   lines.push(emptyBoxLine(innerWidth, margin));
-  lines.push(mid);
+  lines.push(updateBand || mid);
   lines.push(boxLine(`${BOLD}${title}${RESET} ${DIM}· ${org} · ${runtime} · ${countSuffix} · ${filterText}${RESET}`, innerWidth, margin));
   lines.push(boxLine(`${DIM}skills${RESET} ${skillStatus}`, innerWidth, margin));
-  if (cliUpdate?.available) {
-    lines.push(boxLine(
-      `${YELLOW}→ CLI update ${cliUpdate.latest} available${RESET} ${DIM}· installed ${cliUpdate.current} · ${RESET}${BOLD}U${RESET}${DIM} install${RESET}`,
-      innerWidth,
-      margin,
-    ));
-  } else {
-    // Reserve the status row so the list never jumps when the async version
-    // check resolves and reveals an available release.
-    lines.push(emptyBoxLine(innerWidth, margin));
-  }
+  lines.push(emptyBoxLine(innerWidth, margin));
 
   const sigilWidth = Math.max(...EGREGORE_SIGIL.map((line) => line.length));
   const twoColumn = bodyWidth >= 68;

package/assets/egregore-launcher.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# egregore-launcher-version: 0.4.9
+# egregore-launcher-version: 0.4.10
 # egregore — launch an Egregore instance in Claude Code.
 # Reads ~/.egregore/instances.json for the registry of installed egregores.
 #
@@ -22,7 +22,7 @@
 
 set -u
 
-VERSION="0.4.9"
+VERSION="0.4.10"
 REGISTRY="${HOME}/.egregore/instances.json"
 DEFAULT_FILE="${HOME}/.egregore/default"
 
@@ -93,7 +93,11 @@ launch() {
     printf '  %s→%s launching %s%s%s ...\n\n' "$DIM" "$RESET" "$BOLD" "$target_slug" "$RESET"
   fi
   cd "$target_path" || die "Could not cd into $target_path"
-  exec claude start
+  local -a claude_args=("start")
+  if [ -d "$target_path/memory" ]; then
+    claude_args+=("--add-dir" "$target_path/memory")
+  fi
+  exec claude "${claude_args[@]}"
 }
 
 cmd_ls() {

package/lib/setup.js

@@ -426,6 +426,15 @@ async function install(data, ui, targetDir, opts = {}) {
     ui.success("Linked");
   }
 
+  // The connected config is required infrastructure, not an optional overlay.
+  // A setup race once left develop behind main, so a newly-created work branch
+  // could lose egregore.json even though the default branch contained it.
+  // Recover that exact file from origin/main when possible, then validate it
+  // before writing credentials or registering a launcher.
+  if (api_key || data.api_url) {
+    ensureConnectedConfig(egregoreDir, data, ui);
+  }
+
   // 4. Write .env (secrets only — never committed to git)
   ui.step(4, totalSteps, "Writing credentials...");
   const envPath = path.join(egregoreDir, ".env");
@@ -450,19 +459,7 @@ async function install(data, ui, targetDir, opts = {}) {
   fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
   try { ensurePersonOnboardingWitness(memoryDir, state); } catch {}
 
-  // 4c. Ensure mode is set in egregore.json (connected mode for API-based setup)
-  const configPath = path.join(egregoreDir, "egregore.json");
-  if (fs.existsSync(configPath)) {
-    try {
-      const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-      if (!config.mode) {
-        config.mode = "connected";
-        fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-      }
-    } catch {}
-  }
-
-  // 4d. Overlay the selected shell-runtime support. Claude Code reads
+  // 4c. Overlay the selected shell-runtime support. Claude Code reads
   // CLAUDE.md, not AGENTS.md; overlaying the Codex AGENTS.md/.codex into a Claude
   // workspace gives a wandering agent a competing startup protocol (the
   // xenocracy onboarding regression). Claude joiners keep the cloned repo as-is —
@@ -584,6 +581,74 @@ async function install(data, ui, targetDir, opts = {}) {
   await launchOrInstruct(path.join(base, forkDirName), alias, ui, opts);
 }
 
+/**
+ * Require and validate the connected instance configuration.
+ *
+ * If the current branch is missing egregore.json, restore it from origin/main
+ * without changing branches or disturbing existing work. A missing/invalid
+ * remote config aborts setup before credentials and launcher registration.
+ */
+function ensureConnectedConfig(repoDir, data, ui) {
+  const configPath = path.join(repoDir, "egregore.json");
+
+  if (!fs.existsSync(configPath)) {
+    try {
+      execFileSync(
+        "git",
+        ["-C", repoDir, "fetch", "origin", "+main:refs/remotes/origin/main"],
+        {
+          stdio: "pipe", encoding: "utf-8", timeout: 30000,
+        },
+      );
+      const remoteConfig = execFileSync(
+        "git",
+        ["-C", repoDir, "show", "origin/main:egregore.json"],
+        { stdio: "pipe", encoding: "utf-8", timeout: 10000 },
+      );
+      JSON.parse(remoteConfig);
+      fs.writeFileSync(configPath, remoteConfig.endsWith("\n") ? remoteConfig : `${remoteConfig}\n`);
+      if (ui && typeof ui.warn === "function") {
+        ui.warn("Restored missing egregore.json from origin/main");
+      }
+    } catch {
+      throw new Error(
+        "Connected setup is incomplete: egregore.json is missing from this checkout and origin/main. Retry setup from egregore.xyz/setup."
+      );
+    }
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  } catch {
+    throw new Error("Connected setup is incomplete: egregore.json is not valid JSON.");
+  }
+
+  const required = ["org_name", "github_org", "memory_repo", "api_url", "slug"];
+  const missing = required.filter((key) => !config[key]);
+  if (missing.length) {
+    throw new Error(
+      `Connected setup is incomplete: egregore.json is missing ${missing.join(", ")}. Retry setup from egregore.xyz/setup.`
+    );
+  }
+  if (data.slug && config.slug !== data.slug) {
+    throw new Error(
+      `Connected setup mismatch: expected org ${data.slug}, but egregore.json belongs to ${config.slug}.`
+    );
+  }
+  if (data.github_org && config.github_org.toLowerCase() !== data.github_org.toLowerCase()) {
+    throw new Error(
+      `Connected setup mismatch: expected GitHub owner ${data.github_org}, but egregore.json uses ${config.github_org}.`
+    );
+  }
+
+  if (config.mode !== "connected") {
+    config.mode = "connected";
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  }
+  return config;
+}
+
 /**
  * Ensure a cloned repo has a develop branch. Creates from default branch and pushes if missing.
  * Idempotent — safe to call on repos that already have develop.
@@ -752,6 +817,20 @@ function piTrustArgs() {
   }
 }
 
+function claudeLaunchArgs(egregoreDir) {
+  const args = ["start"];
+  const memoryLink = path.join(egregoreDir, "memory");
+  try {
+    const memoryDir = fs.realpathSync(memoryLink);
+    if (fs.statSync(memoryDir).isDirectory()) {
+      args.push("--add-dir", memoryDir);
+    }
+  } catch {
+    // Session startup owns the actionable missing-memory diagnostic.
+  }
+  return args;
+}
+
 function runtimeLaunchArgs(runtime, egregoreDir) {
   if (normalizeRuntime(runtime) === "codex") {
     return [
@@ -762,7 +841,7 @@ function runtimeLaunchArgs(runtime, egregoreDir) {
     ];
   }
   if (normalizeRuntime(runtime) === "pi") return piTrustArgs();
-  return ["start"];
+  return claudeLaunchArgs(egregoreDir);
 }
 
 function startSpinner(label) {
@@ -1353,5 +1432,6 @@ module.exports = {
   assistantInstallCommand,
   initMemoryDirs,
   ensureDevelop,
+  ensureConnectedConfig,
   run,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.19.13",
+  "version": "0.19.15",
   "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {
@@ -12,7 +12,7 @@
   "scripts": {
     "build:runtime": "node scripts/build-runtime-bundle.mjs && node scripts/build-pi-runtime-bundle.mjs",
     "build:pi-runtime": "node scripts/build-pi-runtime-bundle.mjs",
-    "test": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/context.test.js test/parse-join-target.test.js test/skip-repos.test.js test/onboarding-shortcircuit.test.js test/welcome-screen.test.js test/runtime-selection.test.js test/command-generation.test.js test/auth-gh.test.js test/gauntlet-fixes.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/scroll-repro.test.js test/launcher-refocus-redraw.test.js test/multiselect-remote-search.test.js test/back-navigation.test.js test/manifest-form.test.js test/launcher-delete.test.js test/launcher-connect.test.js test/launcher-update.test.js",
+    "test": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/context.test.js test/parse-join-target.test.js test/skip-repos.test.js test/onboarding-shortcircuit.test.js test/welcome-screen.test.js test/runtime-selection.test.js test/command-generation.test.js test/auth-gh.test.js test/gauntlet-fixes.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/scroll-repro.test.js test/launcher-refocus-redraw.test.js test/multiselect-remote-search.test.js test/back-navigation.test.js test/manifest-form.test.js test/launcher-delete.test.js test/launcher-connect.test.js test/launcher-update.test.js test/connected-config.test.js",
     "test:e2e": "node --test test/e2e-local.test.js",
     "test:all": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/"
   },

package/runtime/codex/.codex/hooks/search-hint.js

@@ -4,7 +4,7 @@
 //
 // Mirror of .claude/hooks/search-hint.sh: when the user's prompt is
 // recall-shaped ("find the handoff about…", "did we decide…"), inject a
-// routing hint toward `bin/agent.sh search` — one ranked call over
+// routing hint toward `bash bin/search.sh query` — one ranked call over
 // memory/ — instead of improvised ls/grep/graph exploration.
 //
 // Advisory only, never blocks, rate-limited once per session, exits 0.
@@ -43,6 +43,8 @@ const RECALL = new RegExp(
     "\\bwho worked on\\b",
     "\\bdidn.?t (someone|we) already\\b",
     "\\bwas there (a|any) (handoff|decision|discussion|meeting)\\b",
+    "\\b(our|company|org|organization|team)\\b.*\\b(pricing|price|tiers?|plans?|paid|free|strategy|policy|positioning|ownership|decision)\\b",
+    "\\b(pricing|price|tiers?|plans?|paid|free)\\b.*\\b(our|company|org|organization|team)\\b",
   ].join("|"),
   "i"
 );
@@ -59,7 +61,7 @@ process.stdout.write(JSON.stringify({
   hookSpecificOutput: {
     hookEventName: "UserPromptSubmit",
     additionalContext:
-      "Routing hint: this prompt asks for recall from org memory. FIRST action: `bin/agent.sh search \"<the concept, not the literal sentence>\"` — one ranked call over all of memory/ (hybrid keyword+semantic; graph-state annotations attach automatically in connected mode). Read the top hits and cite paths. Do NOT improvise ls/grep/graph exploration first — hand-written graph queries against invented labels (e.g. :Handoff — handoffs are :Session nodes) return empty. Full spec: the search skill.",
+      "Routing hint: this prompt asks for recall from org memory. FIRST action: `bash bin/search.sh query \"<the concept, not the literal sentence>\"` — one ranked call over all of memory/ (hybrid keyword+semantic; graph-state annotations attach automatically in connected mode). Read the top hits and cite paths. Do NOT improvise ls/grep/graph exploration first — hand-written graph queries against invented labels (e.g. :Handoff — handoffs are :Session nodes) return empty. Full spec: the search skill.",
   },
 }) + "\n");
 process.exit(0);

package/runtime/codex/.codex/skills/search/SKILL.md

@@ -11,12 +11,35 @@ search before answering from conversation context alone.
 
 ## Flow
 
-1. Run the search:
+1. Organizational recall must begin with the Egregore search entry point in
+   step 2. Do not resolve `memory/` to its sibling Git repository, change into
+   that absolute path, or improvise raw grep/listing as the first retrieval
+   action. Use direct file reads or grep only on evidence paths returned by the
+   ranked search.
+
+   Before any shell, file-read, grep, or other retrieval tool call, send exactly
+   one standalone commentary line:
+
+   - local/filesystem-only:
+     `⌕ Egregore · searching your organization’s memory`
+   - connected mode with automatic graph enrichment:
+     `⌕ Egregore Connect · searching your organization’s memory and relationships`
+
+   Send the line verbatim. Do not replace it with generic narration such as
+   “I’ll search org memory.” It must be visible before the tool call; captured
+   command output does not satisfy this requirement. Emit it once even when the
+   retrieval needs multiple queries or source reads.
+
+2. Run the search:
 
 ```bash
-bin/agent.sh search "your query" -n 6
+bash bin/search.sh query "your query" -n 6
 ```
 
+- The command also prints the attribution as a direct-shell fallback. That
+  captured banner is diagnostic redundancy, not the user-visible product beat.
+  If the answer instead begins with a graph-only named read, follow the same
+  global Egregore Retrieval Beat before that query.
 - Default is hybrid (BM25 + vector + rerank); it falls back to keyword
   search automatically when local models aren't built, with a note.
 - `--fast` — keyword only (BM25), instant. Use for exact terms: names,
@@ -27,15 +50,15 @@ bin/agent.sh search "your query" -n 6
   state lines (status, recipient, artifact type, quest) with no flag.
   `--no-enrich` skips it when speed matters; local mode never attempts it.
 
-2. Search the *concept*, not the user's literal sentence. If the first query
+3. Search the *concept*, not the user's literal sentence. If the first query
    returns weak scores, run a second with different wording — one
    keyword-ish, one conceptual.
 
-3. Results are snippets with `memory/...` file paths. Read the source file
+4. Results are snippets with `memory/...` file paths. Read the source file
    for anything you will cite or act on — snippets truncate, and memory
    files carry dates, authors, and caveats that change the answer.
 
-4. Answer directly, citing file paths. If results are empty or weak, say so
+5. Answer directly, citing file paths. If results are empty or weak, say so
    plainly — "nothing in memory on X" is a real answer. Do not present
    conversation-context guesses as memory.
 

package/runtime/codex/.codex/spec-manifest.json

@@ -50,6 +50,12 @@
       "sourceHash": "b5d9a149f1a6",
       "note": "Kept verbatim — bin/graph.sh is runtime-neutral."
     },
+    {
+      "section": "Egregore Retrieval Beat",
+      "action": "keep",
+      "sourceHash": "0c4d4715fb13",
+      "note": "Kept verbatim — product attribution applies across runtimes."
+    },
     {
       "section": "Notifications",
       "action": "keep",
@@ -95,7 +101,7 @@
     {
       "section": "Command Awareness",
       "action": "keep",
-      "sourceHash": "ce5eb3015427",
+      "sourceHash": "a020fc5d9b98",
       "note": "Prepended the Codex command surface (skill tokens, native vs adapter split, $save abstraction); disambiguation map kept with /x -> $x token rendering. Tokens with no Codex skill (e.g. /loop, a Claude Code harness feature) are left as-is."
     },
     {

package/runtime/codex/AGENTS.md

@@ -220,6 +220,53 @@ Run `catalog` only when the route is unclear. Named reads return bounded stable
 
 ---
 
+## Egregore Retrieval Beat
+
+Egregore's organizational search is a product surface, not indistinguishable
+agent tool use. For each user-directed lookup of organizational knowledge,
+show exactly one visible attribution line:
+
+- memory-only retrieval:
+  `⌕ Egregore · searching your organization’s memory`
+- retrieval that actually queries the connected graph:
+  `⌕ Egregore Connect · searching your organization’s memory and relationships`
+
+**Visibility is the contract.** Emit the applicable line verbatim as a
+standalone assistant message before the first Bash, Grep, Glob, Read, or other
+retrieval tool call. Shell/tool output does not satisfy this requirement:
+Claude Code and other harnesses may collapse it. Do not paraphrase the line or
+replace it with generic narration such as “I’ll search org memory.”
+
+Use the memory form for local/filesystem-only organizational retrieval. Use the
+Connect form when the retrieval route will query the connected graph, including
+automatic graph enrichment in `bin/search.sh query`, a graph-only named read,
+or exploratory Cypher. Emit once for the whole retrieval episode, not once per
+hop. The banner printed by `bin/search.sh` remains a direct-shell fallback and
+does not replace the assistant-visible beat.
+
+**Routing is part of the contract.** For organizational history, decisions,
+handoffs, meetings, people, pricing, strategy, or other shared-memory content,
+the first retrieval action is:
+
+```bash
+bash bin/search.sh query "<concept>" -n 6
+```
+
+Do not start by resolving `memory/` to its sibling repository, changing
+directory into that absolute path, or improvising `grep`/`ls` over it. The
+search entry point owns keyword/semantic selection and automatically attaches
+graph state in connected mode. Read or grep the returned `memory/...` source
+paths only after the ranked call when verification needs the full document.
+Native Grep/Glob remain the right first action for repository code, filenames,
+and exact error strings—not organizational recall.
+
+Do not emit the beat for native repository/code search, Git inspection, startup
+context hydration, graph writes, ingestion projection, background sync,
+maintenance, or command-internal queries that are not answering a user lookup.
+Never name `Egregore Connect` unless a graph read will actually run.
+
+---
+
 ## Notifications
 
 **Connected mode only.** Always use `bin/notify.sh` for Telegram notifications — never construct API calls directly. See DEVELOPMENT.md §1 for usage examples. In local mode there are no live notifications.
@@ -306,7 +353,7 @@ Codex reserves leading `/` for built-ins, so Egregore workflows are **skills**,
 Invoke commands from user intent — don't wait for the slash. Each command file has a `## When to invoke` section. Load it for the full spec.
 
 **Core loop** — `$activity` `$dashboard` `$handoff` `$wrap` `$save` `$reflect` `$todo`
-**Knowledge** — `$search` `$deep-reflect` `$archive` `$note` `$add` `$meeting` `$ingest` `$scroll`
+**Knowledge** — `$search` `$deep-reflect` `$archive` `$note` `$add` `$meeting` `$ingest` `$scroll` `$mock`
 **Identity** — `$me` (view profile or set display name)
 **Coordination** — `$ask` `$quest` `$issue` `$invite` `$delete-user` `$announce`
 **Connectors** — `$telegram-connect` (Telegram group setup) `$teams-connect` (Microsoft Teams channel setup)
@@ -316,9 +363,9 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 
 **Disambiguation:**
 - Knowledge: `$reflect` (share-ready) · `$note` (half-baked) · `$deep-reflect` (deep research over memory — questions AND cross-referencing) · `$archive` (AI patterns)
-- Finding things — the retrieval layers: **Grep/ls** (Claude Code / Codex file ops — always available, OSS) · **`bin/graph.sh`** (indexed relevance + relationships/status — paid). Use grep proactively; the graph deepens it when connected. (Semantic `$search` is dormant — evals showed it only pays off on massive unstructured data.)
+- Finding things — **organizational recall starts with `bash bin/search.sh query`** (ranked filesystem retrieval in OSS; automatic relationship/status enrichment in Connect). Use `bin/graph.sh` named reads first only for a pure relationship/status traversal. Use Grep/Glob first for repository code, filenames, and exact error strings—not shared-memory recall. Do not `cd` into the sibling memory repository.
 - Finding **something you generated** (a scroll, handoff, emissary, decision, any hosted egregore.xyz link): `bash bin/artifacts.sh find <query>`. Every generative surface already records into memory — hosted artifacts self-register into `memory/artifacts/` at publish (and the record is committed+pushed, so it's findable from *any* session, not just the one that made it); handoffs land in `memory/handoffs/`, emissaries in `memory/handoffs/outbound/`, decisions/findings/patterns in `memory/knowledge/`. The finder searches **all** of them, ranks title/topic matches above passing body mentions, tags each hit by type (`[document]`/`[handoff]`/`[emissary]`/`[decision]`), and surfaces the shareable URL. Findable by **content, not just name**, across all three layers — grep-first for OSS, folding in search + graph when available. *"bring me the artifact where I laid out our GTM plan"* → this.
-- Artifacts with questions: `$scroll` (living paper + embedded harvest, updates in place) · `$view` (static render) · `$harvest` (elicitation, no published face)
+- Artifacts with questions: `$scroll` (living paper + embedded harvest, updates in place) · `$view` (static render) · `$harvest` (elicitation, no published face) · `$mock` (pre-build walkthrough of decided design — gauge per stop, verdict copy-back)
 - Status: `$dashboard` (personal) · `$activity` (org-wide)
 - Ending: `$wrap` (personal closure) · `$handoff` (notes for others) · `$save` (still working)
 - Tasks: `$todo` (personal) · `$quest` (team exploration) · `$issue` (something broken)

package/runtime/codex/bin/codex-render-spec.mjs

@@ -301,6 +301,7 @@ const RULES = {
   },
   'Config Files': { action: 'keep', note: 'Kept verbatim — shell facts, runtime-neutral.' },
   'Knowledge Graph': { action: 'keep', note: 'Kept verbatim — bin/graph.sh is runtime-neutral.' },
+  'Egregore Retrieval Beat': { action: 'keep', note: 'Kept verbatim — product attribution applies across runtimes.' },
   'Notifications': { action: 'keep', note: 'Kept verbatim — bin/notify.sh is runtime-neutral.' },
   'Onboarding': { action: 'keep', note: 'Kept; /onboarding rendered as $onboarding.' },
   'Transparency Beat': { action: 'keep', note: 'Kept verbatim.' },