create-egregore 0.19.12 → 0.19.15

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.' },

package/runtime/codex/bin/search.sh

@@ -0,0 +1,240 @@
+#!/bin/bash
+# Hybrid search over shared memory — powered by qmd (BM25 + vector + rerank, fully local).
+# Usage:
+#   bash bin/search.sh query "text" [-n N] [--fast|--semantic] [--all]
+#   bash bin/search.sh reindex [--embed]
+#   bash bin/search.sh status
+#
+# The memory repo is registered as a qmd collection named "{slug}-memory".
+# Every call is scoped to that collection with -c, so other qmd collections
+# on the machine are never read or modified.
+#
+# Modes:
+#   (default)   qmd query   — hybrid BM25 + vector + rerank (needs local models, ~2GB one-time download)
+#   --fast      qmd search  — BM25 keyword only, instant, no models
+#   --semantic  qmd vsearch — vector similarity only (needs embeddings: reindex --embed)
+# Hybrid/semantic fall back to BM25 automatically if models or embeddings are missing.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+export NODE_NO_WARNINGS=1
+# Do NOT set CI=1 here — it disables qmd's LLM ops (query expansion, rerank).
+
+# qmd's progress spinner can leak into stdout when it misdetects a TTY;
+# strip ANSI escapes and spinner frames from anything we return.
+_clean() {
+  sed -E $'s/\x1b\\[[0-9;?]*[A-Za-z]//g' | grep -v 'Gathering information' || true
+}
+
+SLUG=$(jq -r '.slug // "egregore"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo "egregore")
+COLLECTION="${SLUG}-memory"
+MEM_PATH="$(readlink -f "$SCRIPT_DIR/memory" 2>/dev/null || true)"
+
+QMD_VERSION="2.5.3"  # pinned — bump deliberately, never float @latest
+
+_qmd() {
+  if command -v qmd >/dev/null 2>&1; then
+    qmd "$@"
+  else
+    npx -y "@tobilu/qmd@${QMD_VERSION}" "$@"
+  fi
+}
+
+# --- Weight ladder ----------------------------------------------------------
+# Three tiers, chosen by what is already on disk — no mode ever triggers a
+# model download in a session's critical path:
+#   keyword   0 MB    BM25, works at install, forever
+#   semantic  ~334 MB embed model, fetched silently by the background warm
+#   hybrid    ~2.2 GB rerank + expansion — org opt-in (features.search_hybrid),
+#                     prefetched by the background warm, never inline
+MODELS_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/qmd/models"
+_have_embed()  { ls "$MODELS_DIR"/*embedding* >/dev/null 2>&1; }
+_have_hybrid() { ls "$MODELS_DIR"/*reranker* >/dev/null 2>&1 && ls "$MODELS_DIR"/*expansion* >/dev/null 2>&1; }
+_hybrid_opted() { [ "$(jq -r '.features.search_hybrid // false' "$SCRIPT_DIR/egregore.json" 2>/dev/null)" = "true" ]; }
+
+_ensure() {
+  if [ -z "$MEM_PATH" ] || [ ! -d "$MEM_PATH" ]; then
+    echo "memory/ not found — run bin/search.sh from an Egregore instance with a memory symlink" >&2
+    exit 1
+  fi
+  if ! _qmd collection list 2>/dev/null | grep -q "^${COLLECTION} "; then
+    _qmd collection add "$MEM_PATH" --name "$COLLECTION" >/dev/null 2>&1 || true
+  fi
+  # Incremental re-index so new handoffs/decisions are searchable immediately.
+  # NEVER swallow a failure silently: a dead path in ANY registered collection
+  # (e.g. a deleted side-project dir) crashes `qmd update` for every collection,
+  # and the index quietly stops absorbing new documents. Caught in dogfooding
+  # 2026-07-07 — results looked fine while missing three days of handoffs.
+  if ! _qmd update >/dev/null 2>&1; then
+    echo "(search: index update FAILED — results may be missing recent documents. A registered qmd collection likely points at a deleted path: run 'qmd collection list', remove the dead one, retry.)" >&2
+  fi
+  _embed_bg
+}
+
+# Keep vector embeddings warm without anyone running a manual step: fire a
+# detached, lock-guarded `qmd embed` on every query. Nothing pending → exits
+# in ~1s. First run on a machine → downloads models + embeds in the
+# background while queries fall back to keyword mode.
+_embed_bg() {
+  [ "${EGREGORE_SEARCH_NO_WARM:-0}" = "1" ] && return 0
+  local lock="${TMPDIR:-/tmp}/egregore-qmd-embed-${COLLECTION}.lock"
+  if [ -f "$lock" ]; then
+    # A crashed embed shouldn't block warming forever — expire the lock after 60 min.
+    if [ -n "$(find "$lock" -mmin +60 2>/dev/null)" ]; then rm -f "$lock"; else return 0; fi
+  fi
+  touch "$lock"
+  if ! _have_embed; then
+    echo "(first run: building the semantic index in the background — searches use keyword mode until it finishes)" >&2
+  fi
+  # Background fetch policy: `qmd embed` pulls only the ~334MB embed model
+  # (the semantic tier). The ~1.9GB hybrid pack is prefetched here ONLY when
+  # the org opted in — a session never waits on either.
+  ( ( _qmd embed >/dev/null 2>&1
+      if _hybrid_opted && ! _have_hybrid; then
+        _qmd query "warmup" -c "$COLLECTION" -n 1 >/dev/null 2>&1
+      fi
+      rm -f "$lock" ) & ) >/dev/null 2>&1
+}
+
+# Annotate results with live graph state (connected mode): each hit that the
+# graph knows (Session by filePath = handoffs; Artifact by filePath = knowledge)
+# gets one "↳ graph:" line — search finds the artifact, the graph tells you its
+# state, in a single call. Fails soft everywhere: local mode / graph offline /
+# unknown paths simply produce no annotations.
+_enrich() {
+  local results paths params out
+  results=$(cat)
+  echo "$results"
+  paths=$(echo "$results" | grep -o "qmd://${COLLECTION}/[^: ]*\.md" | sed "s|qmd://${COLLECTION}/||" | sort -u)
+  [ -z "$paths" ] && return 0
+  params=$(printf '%s\n' "$paths" | jq -R . | jq -sc '{paths: .}')
+  out=$(bash "$SCRIPT_DIR/bin/graph.sh" query "UNWIND \$paths AS fp
+    OPTIONAL MATCH (s:Session {filePath: fp})
+    OPTIONAL MATCH (a:Artifact {filePath: fp})
+    WITH fp, s, a WHERE s IS NOT NULL OR a IS NOT NULL
+    RETURN fp,
+      CASE WHEN s IS NOT NULL THEN coalesce(s.handoffStatus, s.status) ELSE null END AS sessionStatus,
+      s.handedTo AS handedTo, a.type AS artifactType,
+      CASE WHEN a IS NOT NULL THEN [q IN [(a)-[:PART_OF]->(qq:Quest) | qq.id] | q][0] ELSE null END AS quest" \
+    "$params" 2>/dev/null)
+  echo "$out" | jq -r '.values[]? | @tsv' 2>/dev/null | while IFS=$'\t' read -r fp sstat sto atype quest; do
+    local ann=""
+    [ -n "$sstat" ] && [ "$sstat" != "null" ] && ann="status: $sstat"
+    [ -n "$sto" ] && [ "$sto" != "null" ] && ann="$ann${ann:+ · }to: $sto"
+    [ -n "$atype" ] && [ "$atype" != "null" ] && ann="$ann${ann:+ · }artifact: $atype"
+    [ -n "$quest" ] && [ "$quest" != "null" ] && ann="$ann${ann:+ · }quest: $quest"
+    [ -n "$ann" ] && echo "↳ graph · $fp — $ann"
+  done
+}
+
+cmd_query() {
+  local mode="query" n=6 enrich=auto all=()
+  local -a words=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --fast) mode="search" ;;
+      --semantic) mode="vsearch" ;;
+      --enrich) enrich=1 ;;
+      --no-enrich) enrich=0 ;;
+      --all) all=(--all) ;;
+      -n) n="$2"; shift ;;
+      *) words+=("$1") ;;
+    esac
+    shift
+  done
+  # Default mode rides the weight ladder: use the heaviest tier whose models
+  # are already local. Explicit flags always win; nothing downloads inline.
+  if [ "$mode" = "query" ] && ! _have_hybrid; then
+    if _have_embed; then mode="vsearch"; else mode="search"; fi
+  fi
+  # Enrichment is managed, not a user choice: on wherever a graph exists
+  # (connected mode), silently off everywhere else. Flags only override.
+  if [ "$enrich" = "auto" ]; then
+    if [ "$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null)" != "local" ] && \
+       [ -n "$(jq -r '.api_url // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null)" ]; then
+      enrich=1
+    else
+      enrich=0
+    fi
+  fi
+  local q="${words[*]}"
+  if [ -z "$q" ]; then
+    echo "usage: bash bin/search.sh query \"text\" [-n N] [--fast|--semantic] [--all]" >&2
+    exit 1
+  fi
+  _ensure
+  local emit="cat"
+  [ "$enrich" = 1 ] && emit="_enrich"
+  local t0 out label
+  t0=$(date +%s)
+  if [ "$mode" != "search" ]; then
+    out=$(_qmd "$mode" "$q" -c "$COLLECTION" -n "$n" --format md --full-path "${all[@]}" 2>/dev/null | _clean)
+    if [ -n "$out" ] && [ "$out" != "No results found." ]; then
+      [ "$mode" = "query" ] && label="hybrid" || label="semantic"
+      _banner_and_emit "$label" "$t0" "$emit" "$q" "$out"
+      return 0
+    fi
+    echo "_(hybrid/semantic returned nothing — showing keyword results. If this persists, run: bash bin/search.sh reindex --embed)_"
+    echo ""
+  fi
+  out=$(_qmd search "$q" -c "$COLLECTION" -n "$n" --format md --full-path "${all[@]}" | _clean)
+  _banner_and_emit "keyword" "$t0" "$emit" "$q" "$out"
+}
+
+# One visible product-attribution line per search — the tell that Egregore's
+# organizational retrieval layer (not an improvised agent grep loop) answered.
+# It names the graph only when enrichment actually ran, then reports mode,
+# hit count, and latency. Colored when stdout is a terminal; plain glyph in
+# harness transcripts. Also appends to ~/.egregore/search.log (local only,
+# never uploaded) so dogfooding can measure search-first rate and latency.
+_banner_and_emit() {
+  local label="$1" t0="$2" emit="$3" q="$4" out="$5"
+  local hits dur modef product surface plural=""
+  hits=$(printf '%s\n' "$out" | grep -c '^qmd://' 2>/dev/null | tr -d ' ')
+  dur=$(( $(date +%s) - t0 ))
+  modef="$label"
+  product="Egregore"
+  surface="searching your organization’s memory"
+  if [ "$emit" = "_enrich" ] && [ "$hits" -gt 0 ]; then
+    modef="${label}+graph"
+    product="Egregore Connect"
+    surface="${surface} and relationships"
+  fi
+  [ "$hits" != "1" ] && plural="s"
+  local line="⌕ ${product} · ${surface} · ${label} · ${hits} hit${plural} · ${dur}s"
+  if [ -t 1 ]; then
+    printf '\033[1;38;5;30m%s\033[0m\n\n' "$line"
+  else
+    printf '%s\n\n' "$line"
+  fi
+  printf '%s\n' "$out" | $emit
+  mkdir -p "$HOME/.egregore" 2>/dev/null
+  echo "$(date '+%Y-%m-%d %H:%M:%S') mode=${modef} hits=${hits} dur=${dur}s q=\"$(printf '%.80s' "$q")\"" >> "$HOME/.egregore/search.log" 2>/dev/null || true
+}
+
+cmd_reindex() {
+  _ensure
+  _qmd update
+  if [ "${1:-}" = "--embed" ]; then
+    _qmd embed
+    # Hybrid pack prefetch only when the org opted in (features.search_hybrid).
+    if _hybrid_opted && ! _have_hybrid; then
+      _qmd query "warmup" -c "$COLLECTION" -n 1 >/dev/null 2>&1 || true
+    fi
+  fi
+}
+
+cmd_status() {
+  _qmd status 2>/dev/null
+  echo ""
+  echo "collection: $COLLECTION → $MEM_PATH"
+}
+
+case "${1:-}" in
+  query)   shift; cmd_query "$@" ;;
+  reindex) shift; cmd_reindex "$@" ;;
+  status)  shift; cmd_status ;;
+  *)
+    echo "usage: bash bin/search.sh {query|reindex|status}" >&2
+    exit 1
+    ;;
+esac

package/runtime/codex/manifest.json

@@ -177,6 +177,7 @@
     "bin/publish-artifact.sh",
     "bin/publish-references.sh",
     "bin/repo-state.sh",
+    "bin/search.sh",
     "bin/session-autosave.sh",
     "bin/session-log.sh",
     "bin/settings.sh",

package/runtime/pi/.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/pi/.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/pi/.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/pi/.pi/APPEND_SYSTEM.md

@@ -146,6 +146,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.

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

@@ -1,8 +1,8 @@
 {
   "generatedBy": "bin/pi-render-spec.mjs",
   "source": "AGENTS.md generated Codex spec",
-  "sourceHash": "6ad94ccc38d8",
-  "outputHash": "7a3db92a611e",
+  "sourceHash": "34a5f678b6e3",
+  "outputHash": "43cd068d78fd",
   "adaptations": [
     "Pi project trust and APPEND_SYSTEM delivery",
     "Pi tool_call branch gate",

package/runtime/pi/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/pi/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.' },