create-egregore 0.19.8 → 0.19.12

package/runtime/pi/.pi/APPEND_SYSTEM.md

@@ -23,6 +23,24 @@ When a user reports broken or missing framework behavior, the first question is
 
 ---
 
+## Cross-Runtime Compatibility
+
+Framework behavior must work across Claude Code, Codex, and Pi Egregores. Put
+shared mechanics in runtime-neutral `bin/` scripts; keep `.claude/`, `.codex/`,
+and `.pi/` as thin adapters to those mechanics. When changing startup, session
+lifecycle, capture, skills, or commands, trace all three runtime entry points
+and add or update a parity test. Do not call a framework change complete based
+on one runtime alone. Regenerate derived Codex and Pi specifications or runtime
+bundles whenever their sources change.
+
+---
+
+## Voice
+
+Egregore's voice is governed by `.claude/rules/voice-bedrock.md` (always loaded). Register-specific skills: `egregore-voice` (external), `product-voice` (internal UX), `character-v4` (encounters), `alpha-openers` (outreach). See voice-bedrock for the full register map.
+
+---
+
 ## On Launch — MANDATORY FIRST ACTION
 
 The project-local Pi extension renders the Egregore startup card (identity, handoffs, team activity) inside Pi via `bin/pi-session-start.sh`. This works for direct `pi` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Pi, run `bash bin/pi-session-start.sh --card`.
@@ -73,19 +91,22 @@ If on develop after two messages, create a branch immediately from whatever cont
 
 ### Branch-guard protocol
 
-The `.pi/extensions/egregore.ts` `tool_call` gate (loaded after Pi project trust) denies writes, patches, and commits on `develop`/`main`/`master`. When it fires, choose between two paths based on how clear the topic is:
+The `.pi/extensions/egregore.ts` `tool_call` gate (loaded after Pi project trust) protects project writes on `develop`/`main`/`master`. Its block message is operational guidance, not a reason to interrupt the user with routine Git choices:
 
-- **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 (Pi has no built-in structured question tool):
+- **Topic is clear** (the user said "fix X", "add Y feature") → run `bin/agent.sh branch --topic "<topic>"` automatically, continue in the printed worktree, and say one short sentence so the branch change is visible. Do not ask the user to approve routine branching.
+- **Topic is genuinely ambiguous** → ask only for the topic, using compact numbered options:
 
   ```text
-  Need a working branch first. Topic?
+  What should I call this work?
     1. <suggested slug from context>
     2. <alternative slug>
     3. Other: (name it)
   ```
 
   Wait for the reply, then branch.
+- **The user explicitly requested the protected branch** → that request is consent. Record it with `echo '{branch}' > .egregore-branch-consent`, then retry. Never create the marker merely to silence the hook.
+
+Memory, managed-repo, and runtime-state writes should bypass the project guard. If one triggers it, correct the operation target/context instead of asking for protected-branch consent.
 
 If Pi project resources are disabled, follow the same discipline as a standing instruction: never write or commit on develop/main/master.
 
@@ -97,7 +118,7 @@ If the startup card output contains `onboarding_needed`, invoke the `/onboarding
 
 ## 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.**
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. Optional `boundary { posture, read[], locked }` sets the org's isolation posture (see Environment Isolation). **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.
@@ -106,7 +127,22 @@ In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API
 
 ## 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.
+**Connected mode only.** For the following intents, the named read must be the
+first retrieval action. Run the exact command with its safe default limit before
+opening files, running broad grep, inspecting `graph-op.sh`, or writing Cypher:
+
+- current work addressed to someone → `bash bin/graph-op.sh open-handoffs "<user>"`
+- unanswered questions for someone → `bash bin/graph-op.sh pending-questions "<user>"`
+- handoff → implementation → branch/PR/direction → `bash bin/graph-op.sh lineage "<topic>"`
+- company/person/topic across meetings → `bash bin/graph-op.sh meeting-history "<entity-or-topic>"`
+
+A question about calls, meetings, transcripts, demos, or how a conversation
+evolved is always `meeting-history` intent when it names a company, person, or
+topic—even when it does not ask for "current" or "live" state. Pass the shortest
+discriminative entity or topic (for example, `meeting-history "42CAP"`), not the
+whole question.
+
+Run `catalog` only when the route is unclear. Named reads return bounded stable fields and exact canonical `evidencePath` pointers; open only the returned files needed to answer. When a read reports partial coverage, use `unprojectedPaths` rather than claiming those files are represented in the graph. Use `bin/graph.sh` for unsupported Neo4j queries and never construct curl calls directly. See DEVELOPMENT.md §1 for the schema. In local mode there is no graph; read `memory/` directly.
 
 ---
 
@@ -171,6 +207,10 @@ main ← stable (/release)
 - **Memory repo**: stays on main (separate repo, auto-merge).
 - **Never push directly to main or develop.** All changes flow through PRs.
 
+### Pull request format (all harnesses)
+
+Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
+
 ### 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.
@@ -239,17 +279,20 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 ## Environment Isolation
 
-Sessions are confined to this project + memory + managed repos. On Pi this boundary is a standing instruction, not an enforced hook — hold it yourself.
+Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Pi the 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:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
+- When a request needs soft-tier consent, 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
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   ```
 
-See DEVELOPMENT.md §3 for boundary details.
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; `locked: true` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md` for the design decisions.

package/runtime/pi/.pi/extensions/egregore.ts

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { isMutatingBash } from "../../bin/pi-branch-policy.mjs";
+import { isMutatingBash, isRuntimeStatePath, mutatesOnlyRuntimeState } from "../../bin/pi-branch-policy.mjs";
 import {
+  captureSessionEnd,
   createHandoff,
   parseViewRequest,
   publishScroll,
@@ -47,6 +48,32 @@ function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+function nearestExistingDirectory(candidate) {
+  let cursor = resolve(candidate);
+  try {
+    if (existsSync(cursor) && !statSync(cursor).isDirectory()) cursor = dirname(cursor);
+  } catch {}
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return cursor;
+}
+
+async function gitContext(pi, candidate) {
+  const probe = nearestExistingDirectory(candidate);
+  const topResult = await pi.exec("git", ["-C", probe, "rev-parse", "--show-toplevel"], { timeout: 5000 });
+  const top = String(topResult.stdout || "").trim();
+  if (!top) return null;
+  const commonResult = await pi.exec("git", ["-C", top, "rev-parse", "--git-common-dir"], { timeout: 5000 });
+  const commonRaw = String(commonResult.stdout || "").trim();
+  return {
+    top: resolve(top),
+    common: resolve(top, commonRaw || ".git"),
+  };
+}
+
 export default function egregore(pi) {
   const root = process.cwd();
   const skillsDir = join(root, ".codex", "skills");
@@ -297,6 +324,18 @@ export default function egregore(pi) {
     }
   });
 
+  pi.on("session_shutdown", async (event, ctx) => {
+    // Reload keeps the same logical session alive. Every other graceful
+    // shutdown is Pi's equivalent of Claude Code's SessionEnd hook.
+    if (event?.reason === "reload") return;
+    try {
+      await captureSessionEnd(pi, root, ctx.sessionManager.getSessionFile(), undefined);
+    } catch {
+      // Loss-prevention capture must never prevent Pi from exiting. The
+      // attendant remains the fallback for interrupted or failed shutdowns.
+    }
+  });
+
   pi.on("agent_settled", async (_event, ctx) => {
     if (!activeWorkflow || !ctx.hasUI) return;
     activeWorkflow = "";
@@ -305,20 +344,71 @@ export default function egregore(pi) {
   });
 
   pi.on("tool_call", async (event, ctx) => {
-    const mutates = event.toolName === "write" || event.toolName === "edit" ||
-      (event.toolName === "bash" && isMutatingBash(String(event.input?.command || "")));
+    const isFileWrite = event.toolName === "write" || event.toolName === "edit";
+    const command = String(event.input?.command || "");
+    const mutates = isFileWrite || (event.toolName === "bash" && isMutatingBash(command));
     if (!mutates) return;
 
-    const result = await pi.exec("git", ["-C", ctx.cwd, "branch", "--show-current"], { timeout: 5000 });
+    // Resolve the branch in the git context the write actually lands in.
+    // Task worktrees from `bin/agent.sh branch` live outside ctx.cwd but sit
+    // on a task branch, so checking ctx.cwd alone blocks legitimate worktree
+    // edits whenever the session checkout itself is on develop. Memory and
+    // managed repos have a different Git common dir and are outside this guard.
+    const hub = await gitContext(pi, ctx.cwd);
+    if (event.toolName === "bash" && mutatesOnlyRuntimeState(command, hub?.top || ctx.cwd)) return;
+    let operation = hub;
+    if (isFileWrite) {
+      const targetPath = String(event.input?.path || "");
+      const abs = isAbsolute(targetPath) ? targetPath : join(ctx.cwd, targetPath);
+      if (hub && isRuntimeStatePath(abs, hub.top)) return;
+      operation = await gitContext(pi, abs);
+      if (!operation && hub) {
+        const rel = relative(hub.top, abs);
+        if (rel.startsWith("..") || isAbsolute(rel)) return;
+      }
+    } else {
+      // bash: `git -C PATH` or a leading `cd DIR &&` retargets the command
+      // away from ctx.cwd — resolve the branch where it actually runs so
+      // worktree commits (git -C $WT commit) aren't misjudged by the session
+      // checkout's branch.
+      const gitC = command.match(/(?:^|[;&|]\s*)git\s+-C\s+("[^"]*"|'[^']*'|\S+)/);
+      const cdAnd = command.match(/^\s*cd\s+("[^"]*"|'[^']*'|\S+)\s*&&/);
+      const raw = (gitC && gitC[1]) || (cdAnd && cdAnd[1]);
+      if (raw) {
+        const target = raw.replace(/^['"]|['"]$/g, "");
+        const abs = isAbsolute(target) ? target : join(ctx.cwd, target);
+        operation = await gitContext(pi, abs);
+      }
+    }
+
+    if (hub && operation && operation.common !== hub.common) return;
+    const gitDir = operation?.top || hub?.top || ctx.cwd;
+    const result = await pi.exec("git", ["-C", gitDir, "branch", "--show-current"], { timeout: 5000 });
     const branch = String(result.stdout || "").trim();
     if (!PROTECTED_BRANCHES.has(branch)) return;
 
-    const consentFile = join(ctx.cwd, ".egregore-branch-consent");
+    // The documented escape hatch must itself be runnable: recording consent
+    // (echo 'develop' into .egregore-branch-consent) contains a redirect and
+    // would otherwise be blocked by this very gate.
+    if (event.toolName === "bash") {
+      const consentCmd = new RegExp(
+        "^\\s*echo\\s+['\"]?" + branch + "['\"]?\\s*>\\s*\\.egregore-branch-consent\\s*$"
+      );
+      if (consentCmd.test(String(event.input?.command || "").trim())) return;
+    }
+
+    const consentFile = join(gitDir, ".egregore-branch-consent");
     if (existsSync(consentFile) && readFileSync(consentFile, "utf8").trim() === branch) return;
 
     return {
       block: true,
-      reason: `Protected branch (${branch}). Create a task worktree first with: bin/agent.sh branch --topic "<work topic>". Only if the user explicitly authorizes writing on ${branch}, record it with: echo '${branch}' > .egregore-branch-consent`,
+      reason: [
+        `Protected branch (${branch}). Move project work to a task branch before writing.`,
+        `If the work topic is clear, run bin/agent.sh branch --topic "<work topic>" automatically and continue in the printed worktree; do not ask for routine Git permission.`,
+        `Ask only when the topic is genuinely ambiguous.`,
+        `Only when the user explicitly requested ${branch}, record consent with: echo '${branch}' > .egregore-branch-consent`,
+        "Memory, managed-repo, and runtime-state writes should bypass this project guard.",
+      ].join("\n"),
     };
   });
 }

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

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

package/runtime/pi/AGENTS.md

@@ -35,7 +35,8 @@ Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 ```bash
 bin/agent.sh branch --topic "auth review"
-bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review" \
+  --pr-body "$PR_BODY"   # body per .claude/context/pr-format.md (auto-skeleton if omitted)
 bin/agent.sh wrap --from alice --topic "auth review" \
   --summary "Implemented the OAuth callback parser and documented follow-ups." \
   --body "Open threads: review error cases and browser redirects."
@@ -96,6 +97,24 @@ When a user reports broken or missing framework behavior, the first question is
 
 ---
 
+## Cross-Runtime Compatibility
+
+Framework behavior must work across Claude Code, Codex, and Pi Egregores. Put
+shared mechanics in runtime-neutral `bin/` scripts; keep `.claude/`, `.codex/`,
+and `.pi/` as thin adapters to those mechanics. When changing startup, session
+lifecycle, capture, skills, or commands, trace all three runtime entry points
+and add or update a parity test. Do not call a framework change complete based
+on one runtime alone. Regenerate derived Codex and Pi specifications or runtime
+bundles whenever their sources change.
+
+---
+
+## Voice
+
+Egregore's voice is governed by `.claude/rules/voice-bedrock.md` (always loaded). Register-specific skills: `egregore-voice` (external), `product-voice` (internal UX), `character-v4` (encounters), `alpha-openers` (outreach). See voice-bedrock for the full register map.
+
+---
+
 ## On Launch — MANDATORY FIRST ACTION
 
 The `egregore` launcher renders the Egregore startup card (identity, team momentum, and pending work) 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`.
@@ -146,19 +165,22 @@ If on develop after two messages, create a branch immediately from whatever cont
 
 ### 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:
+The `.codex/hooks/branch-guard.js` PreToolUse hook (enabled by the launcher via `--enable hooks`) protects project writes on `develop`/`main`/`master`. Its block message is operational guidance, not a reason to interrupt the user with routine Git choices:
 
-- **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):
+- **Topic is clear** (the user said "fix X", "add Y feature") → run `bin/agent.sh branch --topic "<topic>"` automatically, continue in the printed worktree, and say one short sentence so the branch change is visible. Do not ask the user to approve routine branching.
+- **Topic is genuinely ambiguous** → ask only for the topic, using compact numbered options:
 
   ```text
-  Need a working branch first. Topic?
+  What should I call this work?
     1. <suggested slug from context>
     2. <alternative slug>
     3. Other: (name it)
   ```
 
   Wait for the reply, then branch.
+- **The user explicitly requested the protected branch** → that request is consent. Record it with `echo '{branch}' > .egregore-branch-consent`, then retry. Never create the marker merely to silence the hook.
+
+Memory, managed-repo, and runtime-state writes should bypass the project guard. If one triggers it, correct the operation target/context instead of asking for protected-branch consent.
 
 If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on develop/main/master.
 
@@ -170,7 +192,7 @@ If the startup card output contains `onboarding_needed`, invoke the `$onboarding
 
 ## 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.**
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. Optional `boundary { posture, read[], locked }` sets the org's isolation posture (see Environment Isolation). **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.
@@ -179,7 +201,22 @@ In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API
 
 ## 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.
+**Connected mode only.** For the following intents, the named read must be the
+first retrieval action. Run the exact command with its safe default limit before
+opening files, running broad grep, inspecting `graph-op.sh`, or writing Cypher:
+
+- current work addressed to someone → `bash bin/graph-op.sh open-handoffs "<user>"`
+- unanswered questions for someone → `bash bin/graph-op.sh pending-questions "<user>"`
+- handoff → implementation → branch/PR/direction → `bash bin/graph-op.sh lineage "<topic>"`
+- company/person/topic across meetings → `bash bin/graph-op.sh meeting-history "<entity-or-topic>"`
+
+A question about calls, meetings, transcripts, demos, or how a conversation
+evolved is always `meeting-history` intent when it names a company, person, or
+topic—even when it does not ask for "current" or "live" state. Pass the shortest
+discriminative entity or topic (for example, `meeting-history "42CAP"`), not the
+whole question.
+
+Run `catalog` only when the route is unclear. Named reads return bounded stable fields and exact canonical `evidencePath` pointers; open only the returned files needed to answer. When a read reports partial coverage, use `unprojectedPaths` rather than claiming those files are represented in the graph. Use `bin/graph.sh` for unsupported Neo4j queries and never construct curl calls directly. See DEVELOPMENT.md §1 for the schema. In local mode there is no graph; read `memory/` directly.
 
 ---
 
@@ -244,6 +281,10 @@ main ← stable (/release)
 - **Memory repo**: stays on main (separate repo, auto-merge).
 - **Never push directly to main or develop.** All changes flow through PRs.
 
+### Pull request format (all harnesses)
+
+Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
+
 ### 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.
@@ -268,13 +309,13 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 **Knowledge** — `$search` `$deep-reflect` `$archive` `$note` `$add` `$meeting` `$ingest` `$scroll`
 **Identity** — `$me` (view profile or set display name)
 **Coordination** — `$ask` `$quest` `$issue` `$invite` `$delete-user` `$announce`
-**Connectors** — `$telegram-connect` (Telegram group setup)
+**Connectors** — `$telegram-connect` (Telegram group setup) `$teams-connect` (Microsoft Teams channel 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)
+- 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 **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)
@@ -282,8 +323,8 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 - 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)
+- Ingestion: `$ingest <file-or-folder>` (org-scoped corpus intake) · `$ingest meeting` · `$ingest user-interview` · `$ingest google` · ambiguous → ask which type
+- Connectors: `$telegram-connect` (Telegram group) · `$teams-connect` (MS Teams channel) · `$ingest` (bring content in)
 - Identity: `$me` — "who am I", "call me oz"
 - People: `$invite` (add) · `$delete-user` (remove)
 - PRs: `$pr` (create) · `$review-pr` (review)
@@ -332,19 +373,22 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 ## 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.
+Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the 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:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
+- When a request needs soft-tier consent, 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
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   ```
 
-See DEVELOPMENT.md §3 for boundary details.
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; `locked: true` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md` for the design decisions.
 
 <!-- END GENERATED EGREGORE CODEX SPEC -->

package/runtime/pi/bin/activity-data.sh

@@ -9,7 +9,7 @@ trap "rm -rf $TMPDIR" EXIT
 
 # --- Read config ---
 API_URL=$(jq -r '.api_url // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
-API_KEY=$(grep '^EGREGORE_API_KEY=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2-)
+API_KEY="${EGREGORE_API_KEY:-$(grep '^EGREGORE_API_KEY=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2-)}"
 ORG=$(jq -r '.org_name // "Egregore"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo "Egregore")
 DATE=$(date '+%b %d')