create-egregore 0.18.10 → 0.18.12

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.5.24
+// egregore-launcher-version: 0.5.25
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -30,7 +30,7 @@ const https = require("node:https");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.5.24";
+const VERSION = "0.5.25";
 const REGISTRY = path.join(os.homedir(), ".egregore", "instances.json");
 const DEFAULT_FILE = path.join(os.homedir(), ".egregore", "default");
 const PUBLIC_NPX_PACKAGE = "create-egregore";
@@ -1377,8 +1377,14 @@ function renderHeroPanel({ selected, pv, width, height, countSuffix, filter, fil
 
   lines.push(emptyBoxLine(innerWidth, margin));
   if (canShowBigLogo) {
+    // Center every art line by the SAME offset (the banner's max line width),
+    // not per-line length. The lines can differ in length (trailing padding
+    // gets trimmed by editors/linters); centering each independently shifts the
+    // shorter rows sideways and the block strokes no longer line up vertically.
+    const artWidth = Math.max(...EGREGORE_ART.map((line) => line.length));
+    const artPad = " ".repeat(Math.max(0, Math.floor((bodyWidth - artWidth) / 2)));
     for (const artLine of EGREGORE_ART) {
-      const centered = " ".repeat(Math.max(0, Math.floor((bodyWidth - artLine.length) / 2))) + `${BOLD}${CYAN}${artLine}${RESET}`;
+      const centered = artPad + `${BOLD}${CYAN}${artLine}${RESET}`;
       lines.push(boxLine(centered, innerWidth, margin));
     }
   } else {

package/lib/local.js

@@ -535,6 +535,32 @@ async function maybeSetupTelegramGroup(ui, {
   return { setup: true, groupLink: storedGroupLink };
 }
 
+// Claude Code workspace cleanup: remove the Codex AGENTS.md/.codex/.agents the
+// GitHub template ships, so the agent follows CLAUDE.md rather than a competing
+// startup protocol. Founder-only (we own the repo) — commit + push the removal
+// so it persists for everyone who clones it. A Codex teammate who joins later
+// regenerates AGENTS.md via /update (bin/codex-render-spec.mjs).
+function stripCodexRuntimeForClaude(egregoreDir, ui) {
+  const targets = ["AGENTS.md", ".codex", ".agents"];
+  const present = targets.filter((t) => fs.existsSync(path.join(egregoreDir, t)));
+  if (!present.length) {
+    ui.success("Claude Code workspace — using CLAUDE.md");
+    return;
+  }
+  try {
+    execFileSync("git", ["rm", "-r", "-q", "--", ...present], { cwd: egregoreDir, stdio: "pipe" });
+    run('git commit -m "Claude Code workspace: use CLAUDE.md, drop Codex AGENTS.md/.codex"', { cwd: egregoreDir });
+    run("git push", { cwd: egregoreDir });
+    ui.success(`Claude Code workspace — using CLAUDE.md (removed ${present.join(", ")})`);
+  } catch {
+    // Best-effort: at least remove from the working tree so this session is clean.
+    for (const t of present) {
+      try { fs.rmSync(path.join(egregoreDir, t), { recursive: true, force: true }); } catch {}
+    }
+    ui.success("Claude Code workspace — using CLAUDE.md");
+  }
+}
+
 // ── Flow 1: Founder (local mode) ───────────────────────────────────
 
 async function localFounderFlow(ui, ctx = {}) {
@@ -1014,23 +1040,32 @@ async function localFounderFlow(ui, ctx = {}) {
     }
   }
 
-  const codexRuntime = installCodexRuntime(egregoreDir);
-  reportCodexRuntimeSummary(codexRuntime, ui);
-
-  // 16b. Commit the Codex runtime into the repo so it's TRACKED — symmetric
-  //      with .claude/ (which ships in the template). An untracked overlay can
-  //      be lost to later git operations, and joiners would never get it. This
-  //      way every Egregore supports BOTH assistants, persistently and for the
-  //      whole team: pick Claude Code or Codex, now or later, and it just works.
-  try {
-    const toCommit = Array.isArray(codexRuntime.files) ? [...codexRuntime.files] : [];
-    if (fs.existsSync(path.join(egregoreDir, ".agents", "skills"))) toCommit.push(".agents/skills");
-    if (toCommit.length) {
-      execFileSync("git", ["add", "--", ...toCommit], { cwd: egregoreDir, stdio: "pipe" });
-      run('git commit -m "Add Codex runtime so this Egregore supports both assistants"', { cwd: egregoreDir });
-      run("git push", { cwd: egregoreDir });
-    }
-  } catch {}
+  // 16. Runtime overlay. Codex installs commit the Codex runtime into the repo
+  //     so it's TRACKED (symmetric with .claude/). Claude installs do the
+  //     opposite: Claude Code reads CLAUDE.md, not AGENTS.md, so we strip the
+  //     Codex AGENTS.md/.codex the template ships — otherwise a fresh Claude
+  //     agent (e.g. when onboarding suppresses the greeting) wanders into
+  //     AGENTS.md's startup steps. A Codex teammate who joins later regenerates
+  //     AGENTS.md via /update.
+  if (preferredRuntime === "codex") {
+    const codexRuntime = installCodexRuntime(egregoreDir);
+    reportCodexRuntimeSummary(codexRuntime, ui);
+
+    // 16b. Commit the Codex runtime into the repo so it's TRACKED — symmetric
+    //      with .claude/ (which ships in the template). An untracked overlay can
+    //      be lost to later git operations, and joiners would never get it.
+    try {
+      const toCommit = Array.isArray(codexRuntime.files) ? [...codexRuntime.files] : [];
+      if (fs.existsSync(path.join(egregoreDir, ".agents", "skills"))) toCommit.push(".agents/skills");
+      if (toCommit.length) {
+        execFileSync("git", ["add", "--", ...toCommit], { cwd: egregoreDir, stdio: "pipe" });
+        run('git commit -m "Add Codex runtime so this Egregore supports both assistants"', { cwd: egregoreDir });
+        run("git push", { cwd: egregoreDir });
+      }
+    } catch {}
+  } else {
+    stripCodexRuntimeForClaude(egregoreDir, ui);
+  }
 
   // 17. Register instance + install launcher binary
   ui.step(5 + selectedRepos.length, totalSteps, "Registering instance...");

package/lib/setup.js

@@ -438,10 +438,16 @@ async function install(data, ui, targetDir, opts = {}) {
     } catch {}
   }
 
-  // 4d. Overlay packaged Codex support before registering or launching. This
-  // makes cloned public templates usable even before the public repo syncs.
-  const codexRuntime = installCodexRuntime(egregoreDir);
-  reportCodexRuntimeSummary(codexRuntime, ui);
+  // 4d. Overlay packaged Codex support — Codex installs only. 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 —
+  // any inherited AGENTS.md carries the runtime-precedence guard that redirects
+  // Claude back to CLAUDE.md.
+  if (preferredRuntime === "codex") {
+    const codexRuntime = installCodexRuntime(egregoreDir);
+    reportCodexRuntimeSummary(codexRuntime, ui);
+  }
 
   // 5. Register instance + install launcher binary
   ui.step(5, totalSteps, "Registering instance...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.18.10",
+  "version": "0.18.12",
   "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code or Codex.",
   "license": "MIT",
   "bin": {

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

@@ -5,7 +5,7 @@
     {
       "section": "(intro)",
       "action": "replace",
-      "sourceHash": "3992e3abfcdd",
+      "sourceHash": "a33ca691aacf",
       "note": "Reframed for Codex: names AGENTS.md as the delivery surface and the manifest; \"organizations using Claude Code\" generalized."
     },
     {
@@ -23,7 +23,7 @@
     {
       "section": "After Greeting — BRANCH ON FIRST RESPONSE",
       "action": "replace",
-      "sourceHash": "09c2618759bd",
+      "sourceHash": "c71340e68c9e",
       "note": "EnterWorktree -> bin/agent.sh branch with git checkout fallback; AskUserQuestion -> numbered options in plain text; branch-guard mapped to .codex/hooks/branch-guard.js with instruction fallback; plan-mode note dropped (no plan mode on Codex); /branch + /onboarding -> skill tokens. Handoff claiming and repoState auto-checkout kept verbatim (pure git)."
     },
     {

package/runtime/codex/AGENTS.md

@@ -1,9 +1,20 @@
 # Egregore Agent Protocol
 
+> **Runtime precedence — read this first.**
+>
+> **If you are Claude Code** (or any agent that loads `.claude/`): **stop here.**
+> Your authoritative instructions are `CLAUDE.md` and `.claude/`. Follow the
+> SessionStart greeting and the branch-on-first-message rule there. Do **not**
+> follow the startup steps below and do **not** use `bin/agent.sh` for work an
+> Egregore skill already covers. This file exists only for runtimes that cannot
+> read `CLAUDE.md`.
+>
+> **If you are Codex or another shell-only agent:** this file is yours — continue.
+
 Egregore is no longer only a Claude Code workspace. Claude Code remains the
-first-class integrated runtime through `.claude/`, but any agent that can run
-shell commands in this checkout can participate through the portable memory
-protocol.
+first-class integrated runtime through `.claude/` and `CLAUDE.md`; any other
+agent that can run shell commands in this checkout participates through the
+portable memory protocol below.
 
 ## Startup
 
@@ -35,6 +46,273 @@ write the same markdown files directly, following `docs/AGENT-PROTOCOL.md`.
 
 ## Compatibility
 
-Claude Code users can continue using `/handoff`, `/activity`, `/ask`, and
-other skills. Non-Claude agents should use `bin/agent.sh` and the file protocol.
-Both paths converge on the same `memory/` files.
+Claude Code users continue using `/handoff`, `/activity`, `/ask`, `/save`, and
+other skills — driven by `CLAUDE.md`, not this file. Non-Claude agents use
+`bin/agent.sh` and the file protocol, with the full Codex behavioral spec in the
+generated block below. Both paths converge on the same `memory/` files.
+
+<!-- BEGIN GENERATED EGREGORE CODEX SPEC — derived from CLAUDE.md by bin/codex-render-spec.mjs; do not edit by hand -->
+
+## Egregore on Codex
+
+You are a collaborator inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md (the source of truth for egregore behavior) by `bin/codex-render-spec.mjs`. The per-section adaptation manifest is `.codex/spec-manifest.json`. The thin agent protocol above this block applies to every shell-capable agent; this block is the full behavioral contract for Codex sessions.
+
+---
+
+## Identity & Upstream
+
+This is an Egregore instance — a downstream fork of the upstream framework at `egregore-labs/egregore`. The framework (`bin/`, `.claude/skills/`, `.claude/hooks/`, `.claude/context/`, `CLAUDE.md`, `skills/`) is synced from upstream on every session start and via `$update`. It is not authored in this repo.
+
+**Where changes belong:**
+- **Framework is outdated or a skill is missing:** run `$update` first. It pulls the latest from upstream.
+- **Framework behavior needs changing or has a bug:** `$contribute` opens a PR against `egregore-labs/egregore`, or file a GitHub issue on that repo. Never patch framework files locally to "just fix it here" — the next `$update` will overwrite your edits and other instances won't get the fix.
+- **Org-level work** (memory, org-specific knowledge, managed repos, `egregore.json`): `$save` to this repo.
+
+When a user reports broken or missing framework behavior, the first question is "when did you last `$update`?"
+
+---
+
+## On Launch — MANDATORY FIRST ACTION
+
+The `egregore` launcher renders the Egregore startup card (identity, handoffs, team activity) via `bin/codex-session-start.sh` before Codex starts, and installs project skills. 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, run `bash bin/codex-session-start.sh --card`.
+
+---
+
+## After Greeting — BRANCH ON FIRST RESPONSE
+
+**Mandatory behavioral rule.** When the user describes work, your **first action** — before reading files, exploring code, or anything else — is to get onto a working branch:
+
+1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
+2. Run `bin/agent.sh branch --topic "<topic>"` — it creates a work branch from `origin/develop` in a task worktree (`dev/{author}/{slug}`, or `feature/{slug}` / `bugfix/{slug}` when the topic reads as a feature or fix) and prints the worktree path. Continue all file work from that printed path.
+3. Confirm: `On {branch} (worktree).`
+
+**Fallback:** If `bin/agent.sh branch` fails, use `git checkout -b dev/{author}/{slug} origin/develop`.
+
+4. Update graph (fire-and-forget): `bash bin/graph-op.sh set-topic "$(cat .egregore-session-id 2>/dev/null)" "topic from slug" "dev/author/slug" 2>/dev/null &`
+
+### Handoff claiming
+
+If `addressed_to_user` handoffs exist and the user is picking one up, create the IMPLEMENTS link after branch creation:
+```bash
+bash bin/graph-op.sh claim-handoff "$SESSION_ID" "$HANDOFF_SESSION_ID" 2>/dev/null &
+```
+
+**Auto-checkout repos from handoff**: After claiming, check the `addressed_rich` context for `repoState`. If the handoff includes repo state (non-empty `repoState` array), check out the handoff's branches in each managed repo:
+
+```bash
+PARENT_DIR="$(cd .. && pwd)"
+# For each entry in repoState:
+REPO_DIR="$PARENT_DIR/$REPO_NAME"
+if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
+  git -C "$REPO_DIR" fetch origin "$BRANCH" --quiet 2>/dev/null
+  git -C "$REPO_DIR" checkout "$BRANCH" 2>/dev/null || \
+    git -C "$REPO_DIR" checkout -b "$BRANCH" "origin/$BRANCH" 2>/dev/null
+fi
+```
+
+Report results: `✓ Checked out {branch} in {repo1}, {repo2}`. If a branch no longer exists (PR was merged): `◐ {repo}: PR #{N} merged — on {base}`. If `repoState` is absent or empty, skip auto-checkout silently.
+
+**Exceptions** — skip branching when:
+- The user explicitly created or named a branch themselves
+- Already on a working branch AND the user's intent continues the current branch's topic
+
+**Topic pivot while on a working branch:** If the user describes work **unrelated** to the current branch's topic, treat it as a new topic and create a new branch (`bin/agent.sh branch --topic "<new topic>"`). Do NOT mix unrelated work on one branch.
+
+If on develop after two messages, create a branch immediately from whatever context you have.
+
+### Branch-guard protocol
+
+The `.codex/hooks/branch-guard.js` PreToolUse hook (enabled by the launcher via `--enable hooks`) denies writes, patches, and commits on `develop`/`main`/`master`. When it fires, choose between two paths based on how clear the topic is:
+
+- **Topic is obvious from the last turn** (user said "fix X", "add Y feature") → auto-branch silently with `bin/agent.sh branch --topic "<topic>"` (or the git checkout fallback), then continue. Say one sentence ("Creating `dev/{author}/{slug}`.") so the user isn't confused about why a new branch appeared.
+- **Topic is ambiguous** (open-ended exploration, user didn't specify what we're building yet) → ask **before** branching, in plain text with numbered options (Codex has no structured question tool):
+
+  ```text
+  Need a working branch first. Topic?
+    1. <suggested slug from context>
+    2. <alternative slug>
+    3. Other: (name it)
+  ```
+
+  Wait for the reply, then branch.
+
+If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on develop/main/master.
+
+### Onboarding exception
+
+If the startup card output contains `onboarding_needed`, invoke the `$onboarding` skill instead of greeting.
+
+---
+
+## Config Files
+
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. **Never put secrets here.**
+- **`.env`** — gitignored. Personal secrets. Local mode: `GITHUB_TOKEN` only. Connected mode: `GITHUB_TOKEN` + `EGREGORE_API_KEY`. **Never use `source .env`** — use `grep '^KEY=' .env | cut -d'=' -f2-`.
+
+In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API server only — `bin/graph.sh` and `bin/notify.sh` route through the API gateway.
+
+---
+
+## Knowledge Graph
+
+**Connected mode only.** Always use `bin/graph.sh` for Neo4j queries — never construct curl calls directly. See DEVELOPMENT.md §1 for usage examples and current schema. In local mode there is no graph; read `memory/` directly.
+
+---
+
+## 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.
+
+---
+
+---
+
+## Onboarding
+
+When `onboarding_complete` is false in `.egregore-state.json`, invoke `$onboarding`. The command is the single source of truth — do NOT run steps inline.
+
+---
+
+## Transparency Beat
+
+After the first silent bash command in any session, mention once:
+
+> I run commands directly to keep things fast — you can see everything in the session log, and change permissions in `.claude/settings.json` anytime.
+
+Never repeat it.
+
+---
+
+## Memory
+
+`memory/` is a symlink to the memory repo defined in `egregore.json`. Key directories:
+- `people/` — team directory
+- `handoffs/` — session handoffs + `index.md`
+- `knowledge/decisions/` — org decisions
+- `knowledge/patterns/` — emergent patterns
+- `infrastructure/` — service registry (URLs, names, credential locations)
+
+Always use HTTPS for git operations — `github-auth.sh` handles credential storage.
+
+---
+
+## Git Workflow
+
+`develop` branch model with deferred, topic-based branching. Users never interact with git directly.
+
+```
+main ← stable (/release)
+  develop ← integration (PRs land here)
+    dev/{author}/{topic-slug} | feature/{slug} | bugfix/{slug}
+```
+
+- **On launch**: syncs develop + memory. Does NOT create a branch.
+- **Branch creation**: MANDATORY on first work-related message (see above).
+- **Resuming**: rebase onto develop and continue.
+- **If on develop after two messages**: create branch immediately.
+- **`$save`**: pushes working branch, PR to develop. Auto-merges markdown-only PRs.
+- **Memory repo**: stays on main (separate repo, auto-merge).
+- **Never push directly to main or develop.** All changes flow through PRs.
+
+### Managed Repos
+
+Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `$save` scans all managed repos for uncommitted changes.
+
+---
+
+## Working Conventions
+
+- Check `memory/knowledge/` before starting unfamiliar work
+- Document significant decisions in `memory/knowledge/decisions/`
+- After substantial sessions, log to `memory/handoffs/` and update `index.md`
+
+---
+
+## Command Awareness
+
+Codex reserves leading `/` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching `$name` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: `$activity`, `$handoff`, `$wrap`, `$announce`, `$harvest`, `$the-spiral`, `$dashboard`, `$deep-reflect`, `$quest`, `$invite`, `$ask`, `$save`. Every other workflow has a generated adapter skill of the same name. `$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.
+
+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** — `$deep-reflect` `$archive` `$note` `$add` `$meeting` `$ingest`
+**Identity** — `$me` (view profile or set display name)
+**Coordination** — `$ask` `$quest` `$issue` `$invite` `$delete-user` `$announce`
+**Connectors** — `$telegram-connect` (Telegram group setup)
+**Git** — `$branch` `$commit` `$push` `$pr` `$save` `$review-pr` `$contribute`
+**Spirits** — `$summon` (persistent agent processes)
+**Infra** — `$setup` `$update` `$pull` `$env` `$infra` `$sync-repos` `$release` `$checkup`
+
+**Disambiguation:**
+- Knowledge: `$reflect` (share-ready) · `$note` (half-baked) · `$deep-reflect` (cross-reference) · `$archive` (AI patterns)
+- 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)
+- Questions: `$ask [person]` (async) · just ask (agent answers from context)
+- Ingestion: `$ingest meeting` · `$ingest user-interview` · `$ingest google` · ambiguous → ask which type
+- Connectors: `$telegram-connect` (Telegram group) · `$ingest` (bring content in)
+- Identity: `$me` — "who am I", "call me oz"
+- People: `$invite` (add) · `$delete-user` (remove)
+- PRs: `$pr` (create) · `$review-pr` (review)
+- Contributing: `$contribute` (upstream framework) · `$save` (org repo) · `$issue` (report bug)
+- Agents: `$summon` (design through questions) · `/loop` (quick recurring schedule)
+- Announcements: `$announce` (broadcast to group) · `$handoff` (structured to a person) · `bin/notify.sh send` (DM one person)
+
+---
+
+## Socratic Questioning (MANDATORY)
+
+**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
+
+Codex has no structured question tool — render each batch as compact numbered questions in plain text, each with 2–4 lettered options plus an `Other:` line, then STOP and wait for the user's answers. Derive 2–4 context-specific questions per batch. Iteratively deepen based on answers. Converge toward decisions. After 4–5 rounds, synthesize and propose next steps. Route insights to `$reflect`.
+
+**Rules:** Max 4 questions per batch. When choices aren't mutually exclusive, say "pick any that apply".
+
+---
+
+## Telemetry
+
+Privacy-respecting, opt-out telemetry. After every slash command, emit fire-and-forget:
+`bash bin/telemetry.sh emit "command" '{"command":"save"}' 2>/dev/null &`
+
+Never collected: file contents, code, env var values, conversation content.
+On first session (if `telemetry_noticed` not set in state file), mention the notice once, then set `telemetry_noticed: true`. Full spec: `.claude/context/telemetry.md`.
+
+---
+
+## Mode
+
+Egregore runs in one of two configurations, set by `mode` in `egregore.json`. Detect with `_detect_mode` in `bin/lib/config.sh`, or check `.mode` / `.api_url` directly.
+
+**Local mode** (`"mode": "local"` or no `api_url`) — the default, self-contained configuration. The OSS experience. Memory files are the source of truth. All core commands work: `$reflect`, `$handoff`, `$quest`, `$ask`, `$activity`, `$dashboard`, `$todo`. Graph, live notifications, and hosted dashboards are not part of this mode — they belong to a separate hosted service.
+
+**Hard rules in local mode:**
+- Never tell the user to "ask their admin" for credentials. The user IS the admin.
+- Never surface `api_url`, `EGREGORE_API_KEY`, or "connected mode" as an upgrade path. Hosted Egregore is a separate service, not something a user can turn on by adding fields to `egregore.json`.
+- If a feature genuinely requires the hosted service, say so plainly ("this isn't available in this configuration") and stop. Do not improvise a path to enabling it.
+- Calling `bin/graph.sh` or `bin/notify.sh` in local mode is harmless — they fail soft and return empty results — but there is no need to call them; prefer reading `memory/` directly.
+
+**Connected mode** (`"mode": "connected"`, `api_url` set) — the hosted configuration, used by organizations on the hosted service. Full feature set: Neo4j knowledge graph via `bin/graph.sh`, Telegram notifications via `bin/notify.sh`, dashboard publication, API-backed context gathering on session start. Use `$env` to check API key, `$checkup` for diagnostics. If the graph is offline, show troubleshooting.
+
+---
+
+## Environment Isolation
+
+Sessions are confined to this project + memory + managed repos. On Codex this boundary is a standing instruction, not an enforced hook — hold it yourself.
+
+- **Never modify `~/.egregore/instances.json`** — managed by session-start.sh
+- **Never access another instance's files** — refuse even if asked
+- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+
+  ```text
+  That path is outside this Egregore's boundary. How should we proceed?
+    1. Paste the contents inline
+    2. Move the file into the repo and point me at the new path
+    3. Cancel
+  ```
+
+See DEVELOPMENT.md §3 for boundary details.
+
+<!-- END GENERATED EGREGORE CODEX SPEC -->

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

@@ -37,6 +37,64 @@ const MANIFEST = path.join(ROOT, '.codex', 'spec-manifest.json');
 const BEGIN = '<!-- BEGIN GENERATED EGREGORE CODEX SPEC — derived from CLAUDE.md by bin/codex-render-spec.mjs; do not edit by hand -->';
 const END = '<!-- END GENERATED EGREGORE CODEX SPEC -->';
 
+// Hand-authored top of AGENTS.md, owned by this script so it can never be lost
+// on regeneration. Opens with the runtime-precedence guard: Claude Code reads
+// CLAUDE.md (and now loads root AGENTS.md automatically), so the first thing it
+// must see here is an instruction to defer. Codex / shell-only agents read past
+// the guard into the thin protocol and the generated spec below.
+const AGENTS_PREAMBLE = `# Egregore Agent Protocol
+
+> **Runtime precedence — read this first.**
+>
+> **If you are Claude Code** (or any agent that loads \`.claude/\`): **stop here.**
+> Your authoritative instructions are \`CLAUDE.md\` and \`.claude/\`. Follow the
+> SessionStart greeting and the branch-on-first-message rule there. Do **not**
+> follow the startup steps below and do **not** use \`bin/agent.sh\` for work an
+> Egregore skill already covers. This file exists only for runtimes that cannot
+> read \`CLAUDE.md\`.
+>
+> **If you are Codex or another shell-only agent:** this file is yours — continue.
+
+Egregore is no longer only a Claude Code workspace. Claude Code remains the
+first-class integrated runtime through \`.claude/\` and \`CLAUDE.md\`; any other
+agent that can run shell commands in this checkout participates through the
+portable memory protocol below.
+
+## Startup
+
+1. Read \`egregore.json\` for the instance name, GitHub owner, and managed repos.
+2. Run \`bin/agent.sh sync\` to pull the latest shared memory.
+3. Read \`memory/people/\` to learn collaborator handles.
+4. Run \`bin/agent.sh activity --for <your-handle>\` to inspect handoffs and
+   pending questions addressed to you.
+
+## Communication
+
+Use the runtime-neutral bridge instead of Claude Code slash commands:
+
+\`\`\`bash
+bin/agent.sh handoff --from alice --to bob --topic "auth review" \\
+  --body "Implemented the OAuth callback parser. Bob should review error cases."
+
+bin/agent.sh ask --from bob --to alice --topic "auth review" \\
+  --question "Should invalid state redirect to login or return 400?"
+
+bin/agent.sh answer --from alice \\
+  --question memory/knowledge/questions/2026-04-26-bob-to-alice-auth-review.md \\
+  --body "Return 400 in the API path; redirect only in browser routes."
+\`\`\`
+
+Each command writes to the existing Git-backed \`memory/\` repository and pushes
+when the memory repo has an \`origin\` remote. Agents that cannot run shell may
+write the same markdown files directly, following \`docs/AGENT-PROTOCOL.md\`.
+
+## Compatibility
+
+Claude Code users continue using \`/handoff\`, \`/activity\`, \`/ask\`, \`/save\`, and
+other skills — driven by \`CLAUDE.md\`, not this file. Non-Claude agents use
+\`bin/agent.sh\` and the file protocol, with the full Codex behavioral spec in the
+generated block below. Both paths converge on the same \`memory/\` files.`;
+
 function sha(text) {
   return crypto.createHash('sha256').update(text).digest('hex').slice(0, 12);
 }
@@ -271,13 +329,12 @@ function render() {
   return { block, manifest };
 }
 
-function spliceAgentsMd(agentsMd, block) {
-  const beginIdx = agentsMd.indexOf(BEGIN);
-  const endIdx = agentsMd.indexOf(END);
-  if (beginIdx !== -1 && endIdx !== -1) {
-    return agentsMd.slice(0, beginIdx) + block + agentsMd.slice(endIdx + END.length);
-  }
-  return `${agentsMd.replace(/\n+$/, '')}\n\n${block}\n`;
+// AGENTS.md is fully owned by this script: the guard preamble plus the generated
+// spec block. Reconstructing it deterministically (rather than splicing into the
+// existing file) guarantees the runtime-precedence guard is always present and
+// correct — it cannot be stripped by an upstream sync or a hand edit.
+function assembleAgentsMd(block) {
+  return `${AGENTS_PREAMBLE.trim()}\n\n${block}\n`;
 }
 
 const check = process.argv.includes('--check');
@@ -285,7 +342,7 @@ const { block, manifest } = render();
 const manifestJson = `${JSON.stringify({ generatedBy: 'bin/codex-render-spec.mjs', source: 'CLAUDE.md', sections: manifest }, null, 2)}\n`;
 
 const currentAgents = fs.existsSync(AGENTS_MD) ? fs.readFileSync(AGENTS_MD, 'utf-8') : '';
-const nextAgents = spliceAgentsMd(currentAgents, block);
+const nextAgents = assembleAgentsMd(block);
 
 const CODEX_DOC_BUDGET = 32 * 1024;
 if (Buffer.byteLength(nextAgents, 'utf-8') > CODEX_DOC_BUDGET) {