docs: pi 0.84.3 runtime mechanics, isolation baseline, personality layering, gateway patterns

Establishes this repository as the authoritative source for Pi agent
configuration across scenarios, starting with the documentation layer.

Key verified findings (probe harness included, zero model tokens):

- The skills section of the system prompt is emitted only when an active tool
  named 'read' exists (system-prompt.js:59,113). Therefore --no-tools silently
  makes every SKILL.md unreachable and --skill a no-op.
- registerTool accepts a plain JSON Schema object, so tool definitions can be
  served from a backend instead of duplicated in TypeScript.
- An extension can shadow a built-in tool by name, which is how a dedicated
  agent gets a path-restricted 'read' while still satisfying the rule above.
- .pi/SYSTEM.md replaces pi's coding-assistant prompt, but the replacement
  branch contributes neither the tool list nor the guidelines.
- Without --no-skills/--no-extensions, user-global resources leak into every
  scenario; probed leak was find-skills, modsearch, summarize.

Measured effect of the full baseline: system prompt 2619 -> 960 characters,
coding-assistant framing and pi-docs paths removed, skill finally reachable.

Secrets are guarded by scripts/verify-no-secrets.sh, installed as a pre-commit
hook. Backups deliberately live outside the repository.

docs/evidence/probe-harness/.pi/SYSTEM.md

@@ -0,0 +1,2 @@
+CURATOR_SYSTEM_MARKER
+你是一个测试用的专用 agent，不是编码助手。

docs/evidence/probe-harness/.pi/skills/probe-skill/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: probe-skill
+description: PROBE_SKILL_MARKER - a probe skill used only to verify that pi surfaces the skills section in the system prompt under a given flag combination.
+---
+
+# Probe Skill Body
+PROBE_SKILL_BODY_MARKER

docs/evidence/probe-harness/AGENTS.md.sample

@@ -0,0 +1,2 @@
+# Probe Workspace
+AGENTS_MARKER_PRESENT

docs/evidence/probe-harness/collect-evidence.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+run() { L="$1"; shift; echo "### $L"; echo '```'; echo "flags: $*"; printf '{"id":"1","type":"get_state"}\n' | timeout 60 /home/claw/.npm-global/bin/pi --mode rpc --no-session --no-extensions -e /tmp/pi-probe/probe-ext.ts --no-prompt-templates --no-themes --provider zenmux --model openai/gpt-5.6-luna "$@" 2>&1 >/dev/null | grep -E "^PROBE_"; echo '```'; echo; }
+run "C · Curator 现状 (--no-tools)" --no-tools
+run "A · --no-builtin-tools，无隔离旗标" --no-builtin-tools
+run "F · +--no-skills --skill" --no-builtin-tools --no-skills --skill /tmp/pi-probe/.pi/skills/probe-skill
+run "I · 目标最终组合 (+.pi/SYSTEM.md +--approve)" --no-builtin-tools --no-skills --skill /tmp/pi-probe/.pi/skills/probe-skill --approve

docs/evidence/probe-harness/probe-ext.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Probe 1: does registerTool accept a PLAIN JSON Schema object (not TypeBox)?
+const plainJsonSchema = {
+  type: "object",
+  properties: { q: { type: "string", description: "probe query" } },
+  required: ["q"],
+} as any;
+
+export default function probe(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "probe_plain_schema",
+    label: "Probe Plain Schema",
+    description: "Probe tool declared with a raw JSON Schema object.",
+    promptSnippet: "probe_plain_schema: raw JSON Schema probe",
+    parameters: plainJsonSchema,
+    async execute() {
+      return { content: [{ type: "text" as const, text: "PROBE_PLAIN_OK" }], details: {} };
+    },
+  });
+
+  // Probe 2: override the builtin `read`
+  pi.registerTool({
+    name: "read",
+    label: "Restricted Read",
+    description: "RESTRICTED_READ_OVERRIDE probe.",
+    promptSnippet: "read: restricted read override",
+    parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } as any,
+    async execute(_id, params: any) {
+      return { content: [{ type: "text" as const, text: `RESTRICTED_READ_CALLED ${params.path}` }], details: {} };
+    },
+  });
+
+  pi.on("session_start", async (_e, ctx) => {
+    const all = pi.getAllTools().map((t) => `${t.name}[${(t as any).sourceInfo?.source ?? "?"}]`);
+    const active = pi.getActiveTools();
+    const sp = ctx.getSystemPrompt?.() ?? "";
+    console.error("PROBE_ALL_TOOLS=" + JSON.stringify(all));
+    console.error("PROBE_ACTIVE_TOOLS=" + JSON.stringify(active));
+    console.error("PROBE_SP_HAS_SKILLS=" + String(sp.includes("available_skills")));
+    console.error("PROBE_SP_HAS_PROBE_SKILL=" + String(sp.includes("PROBE_SKILL_MARKER")));
+    console.error("PROBE_SP_HAS_AGENTS=" + String(sp.includes("AGENTS_MARKER_PRESENT")));
+    console.error("PROBE_SP_HAS_CODING_ASSISTANT=" + String(sp.includes("expert coding assistant")));
+    console.error("PROBE_SP_HAS_SYSTEM_MD=" + String(sp.includes("CURATOR_SYSTEM_MARKER")));
+    console.error("PROBE_SP_HAS_PI_DOCS=" + String(sp.includes("Pi documentation")));
+    console.error("PROBE_SP_LEN=" + String(sp.length));
+    const names = [...sp.matchAll(/<name>([^<]+)<\/name>/g)].map(m=>m[1]);
+    console.error("PROBE_SKILLNAMES=" + JSON.stringify(names));
+  });
+}