pi-openappa 0.2.0 → 0.3.0

package/README.md

@@ -14,92 +14,118 @@ pi event ◀── enforce  ◀── decision  ◀─────────
 
 ## Requirements
 
-- The `appa` binary on `PATH`: `curl -fsSL https://openappa.com/install.sh | sh`
-  (the extension installs it automatically when missing) — version 0.31.x
-  verified; see `docs/wire-notes.md` for the recorded contract
+- The `appa` binary on `PATH` ([install](https://openappa.com)) — version
+  0.31.x verified; see `docs/wire-notes.md` for the recorded contract
 - An APPA runtime listening on loopback (default `127.0.0.1:8787`)
-- A policy (`appa.toml`) that declares the tools your sessions may use
+- A policy (`appa.toml`) that declares the tools your sessions may use —
+  `/appa init` writes a starter one, or copy `templates/appa.toml`
 
 ## Install
 
 ```sh
-pi install npm:pi-openappa        # published on npm; indexed by the Pi gallery
+pi install npm:pi-openappa        # once published
 pi install ./pi-openappa          # from a checkout
 ```
 
-## Smoke test
-
-Ship and verify in one pass:
-
-```sh
-just deploy                        # sync the lockfile, run checks, npm publish
-just remove                        # drop a local-checkout install, if present
-pi install npm:pi-openappa         # install the published package
-pi                                 # any session: protection on, appa auto-installs
-appa --version                     # OK — the runtime is on PATH
-```
-
-`pi install` only registers the package — extension code runs when a session
-starts, so `appa` appears after that first session, not before.
-
 ## Protect sessions
 
-Protection is **on by default**: every Pi session is guarded unless you opt
-out. Opt-outs, most specific first:
+Protection is opt-in, in one of three ways:
 
-- **Per launch:** `APPA_GATE=0 pi` (and `APPA_GATE=1 pi` to force it on).
-- **Per project:** create `<project>/.pi/no-openappa` — sessions started in
-  that directory run unguarded.
-- **Globally:** `/appa off` once (marker `~/.config/pi-openappa/off`) — every
-  session everywhere runs unguarded until `/appa on`.
-
-The project marker `<project>/.pi/openappa` names that project's policy
-(absolute or cwd-relative) and re-enables protection even when globally off;
-empty content falls back to `APPA_CONFIG` or APPA's default:
+- **Project-scoped (recommended):** create `<project>/.pi/openappa` — sessions
+  started in that directory are protected, sessions elsewhere are not. The
+  marker's optional content names that project's policy (absolute or
+  cwd-relative); empty content falls back to `APPA_CONFIG` or APPA's default:
 
   ```sh
   cd your-project && mkdir -p .pi && echo "appa.toml" > .pi/openappa
   ```
 
-A protected session brings the runtime up on its own: `session_start` invokes
-`appa hook --ensure-runtime`, passing `--config "$APPA_CONFIG"` when set and
-otherwise letting APPA use its own default policy (`~/.config/appa/appa.toml`).
-Protected sessions therefore need zero manual server management. A custom
+- **Built-in:** run `/appa on` once — every Pi session everywhere is
+  protected. `/appa off` disables.
+- **Per launch:** `APPA_GATE=1 pi` (the `clappa`-style launcher route).
+
+A gated session brings the runtime up on its own: `session_start` sends
+`appa hook --ensure-runtime` (passing `--config` when a policy is resolved),
+but **does not wait for it** — the boot runs on a serialized background lane,
+so a cold runtime, a first-run install, or a slow start never sits in Pi's
+session-start path. Ordering is preserved: the SessionStart payload always
+lands before the first `PreToolUse`, and a runtime that cannot answer fails
+that first call closed with the reason (silence never means yes). A custom
 `APPA_RUNTIME_URL` names a runtime that is *yours* to start — the hook
 refuses with exactly that reason instead of guessing.
 
-When the default `appa` is missing from `PATH`, a protected session installs
-it itself — once, with a UI notice — by running the same official script
-(`curl -fsSL https://openappa.com/install.sh | sh`), then retries starting
-the runtime. Sessions that name a custom `APPA_HOOK_BIN` are never
-auto-installed.
-
-While protected, a runtime that cannot answer blocks the call and the reason
-is returned to the model — **silence never means yes**; `/appa off` always
-works, even with every tool call blocked. One exception: with **no policy
-anywhere** (`APPA_CONFIG`, marker content, and `~/.config/appa/appa.toml` all
-absent) and no runtime answering, the session runs **unprotected** with one
-startup warning naming the fixes — an unconfigured guard must not lock you
-out of your own machine. A named policy that fails stays fail-closed.
-Opted-out sessions never invoke the hook.
+While gated, a runtime that cannot answer blocks the call and the reason is
+returned to the model — **silence never means yes**. If no policy exists the
+startup warning names the exact outs; `/appa off` always works, even with
+every tool call blocked. Ungated sessions never invoke the hook.
 
 ## Configuration
 
-| Variable | Default | Meaning |
+| Source | Default | Meaning |
 |---|---|---|
-| `APPA_GATE` | unset | `1` forces protection on for this launch; `0` forces it off |
-| `.pi/openappa` | absent | Project marker: names that project's policy and forces protection on |
-| `.pi/no-openappa` | absent | Project opt-out: sessions started there run unguarded |
+| `APPA_GATE` | unset | `1` protects this session (read once at launch) |
+| `.pi/openappa` | absent | Project marker: gates sessions started in that directory; optional content = policy path |
+| `~/.config/pi-openappa/settings.json` | absent | File settings: `config`, `runtimeUrl`, `hookBin`, `hookTimeoutMs`; env always wins, project markers beat `config` |
 | `APPA_RUNTIME_URL` | `http://127.0.0.1:8787` | Runtime endpoint (loopback only) |
 | `APPA_CONFIG` | unset | `appa.toml` the session auto-starts the runtime with |
 | `APPA_HOOK_BIN` | `appa` | Hook binary to invoke |
-| `APPA_INSTALL_CMD` | `curl -fsSL https://openappa.com/install.sh \| sh` | Auto-install command for a missing default `appa` (pin a mirror or offline copy) |
 | `APPA_HOOK_TIMEOUT_MS` | `15000` | Kill the hook after this long; the call is then blocked |
-| `APPA_INSTALL_TIMEOUT_MS` | `120000` | Kill a stuck auto-install after this long |
 
-`/appa` reports protection, opt-out state, and runtime health; `/appa off`
-disables protection globally (marker `~/.config/pi-openappa/off`) and
-`/appa on` re-enables it, taking effect immediately including the
+Policy resolution order: `APPA_CONFIG`, then the project marker's content,
+then `settings.json`'s `config`, then APPA's own default
+(`~/.config/appa/appa.toml`).
+
+## Starter policy: `/appa init`
+
+`templates/appa.toml` is a complete, self-contained policy written for Pi.
+It gates **flows, not tools**: sources mark data, sinks check it.
+
+| When a session carries… | it is refused at… |
+|---|---|
+| web text (`curl`/`wget`, `web_explore`, context7) | editing any existing file except docs/openspec/`*.md` (research lands in docs, it doesn't rewrite code); writing tests, devops (Makefile, justfile, scripts, CI, Dockerfile), infra (terraform, k8s, helm…), or credential-shaped paths; `git push` / `gh …`; `mem_save`/`mem_update` (poisoned memory must not persist) |
+| `.env`/credentials (read or commanded) | web tools (a secret-narrowed session cannot prove a query shareable) — trusted docs domains carved out for `curl`; bash output returns masked via `redact-secrets` |
+| anything | editing appa's own policy files |
+| nothing (clean session) | nowhere — reads, edits, tests, commits, pushes all flow |
+
+An undeclared tool is refused before it runs (deny-by-default; a `*`
+wildcard requires an annotator, so refusing is the only annotator-free
+stance — the commented `builtin = "llm"` block shows the classifier
+upgrade). Selectors use **Pi argument names** (`Read(path:…)`, not Claude
+Code's `file_path` — the stock battery's never match a Pi call), and the
+policy is **static rules only**: nothing host-coupled, nothing that can be
+unreachable. Taint lives in the trajectory label and only narrows — the
+manual reset is a **new session** (resume/fork inherit it; there is no
+`/untaint` by design).
+
+Install it one of three ways:
+
+```sh
+/appa init               # inside Pi: writes ~/.config/appa/appa.toml (+ settings.json)
+/appa init project       # writes ./appa.toml and the .pi/openappa marker
+cp templates/appa.toml ~/.config/appa/appa.toml   # from a checkout
+```
+
+`init` never clobbers: rerun with `--force` to overwrite. Subcommands
+autocomplete (`on`, `off`, `init`, `init project`, `status`).
+
+### Policy-as-code
+
+The policy is tested like code — no runtime needed, only the `appa` CLI:
+
+```sh
+just policy-check      # templates/appa.toml loads
+just policy-coverage   # every known Pi tool declared (Day E: refusals fail)
+just policy-test       # replay the usage-day traces (Days A–D, F)
+```
+
+`traces/*.appa` are line-based replays (`<canonical-tool> {` / one `arg:`
+JSON value per line / `}` / `expect allow|withhold|deny`); calls in one
+file share a trajectory, so taint accumulates exactly as live. All three
+gates run in `just check`.
+
+`/appa` reports protection, always-on state, and runtime health; `/appa on`
+and `/appa off` toggle always-on protection (marker:
+`~/.config/pi-openappa/always-on`), taking effect immediately including the
 current session.
 
 ## Event mapping
@@ -130,14 +156,7 @@ policies declare them verbatim.
 - **Subagents**: spawning is mediated as a plain tool call (deny blocks the
   spawn). Child trajectories are not linked into the parent's label chain
   yet; a gated child Pi process opens its own root trajectory.
-- **On by default**: installing this extension guards every session and may
-  download and run openappa.com's install script once on first run. The
-  opt-outs above and `APPA_INSTALL_CMD` are the escapes.
-- **Auto-install is `curl \| sh`**: a protected session with the default
-  binary missing downloads and runs the script with user privileges, at most
-  once per session start. Pre-install `appa` or pin `APPA_INSTALL_CMD` to
-  avoid it.
-- The adapter never starts a runtime for opted-out sessions; auto-start needs
+- The adapter never starts a runtime for ungated sessions; auto-start needs
   either `APPA_CONFIG` or an installed APPA deployment.
 - OpenAPPA is Preview & RFC: wire surfaces may break without shims. The
   entire wire contract lives in `src/hook-client.ts` and `src/adapter.ts`

package/extensions/index.ts

@@ -3,12 +3,16 @@
  *
  * Thin by design: translate Pi events to `appa hook` invocations and enforce
  * the answer. No policy logic lives here; the APPA runtime owns every
- * decision. Protection is opt-in per session (APPA_GATE=1 at launch) and
- * fail-closed while gated: if the runtime cannot answer, the call is blocked.
+ * decision. Protection is opt-in per session (APPA_GATE=1 at launch, a
+ * project marker, or always-on) and fail-closed while gated: if the runtime
+ * cannot answer, the call is blocked.
  *
  * Wire facts and constraints: docs/wire-notes.md
  */
 
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   parseCallDecision,
@@ -20,13 +24,14 @@ import {
   stopPayload,
   toolResponseFrom,
 } from "../src/adapter.ts";
-import { invokeAppaHook, resolveHookBin, type HookOutcome } from "../src/hook-client.ts";
-import { installAppa, type InstallOutcome } from "../src/installer.ts";
+import type { InvokeOptions } from "../src/hook-client.ts";
+import { invokeAppaHook } from "../src/hook-client.ts";
 import {
-  appaDefaultPolicyExists,
+  appaDefaultConfigPath,
   captureGate,
   checkHealth,
-  setGloballyOff,
+  setAlwaysOn,
+  settingsPath,
   type GateState,
 } from "../src/gate.ts";
 
@@ -35,12 +40,18 @@ interface TextPart {
   text: string;
 }
 
+/** The starter policy `/appa init` writes (templates/appa.toml in this package). */
+function templateToml(): string {
+  return readFileSync(
+    fileURLToPath(new URL("../templates/appa.toml", import.meta.url)),
+    "utf8",
+  );
+}
+
 export default function (pi: ExtensionAPI): void {
   /** Launch-fixed protection state; null until the session starts. */
   let gate: GateState | null = null;
   let sessionId = "";
-  /** No policy anywhere and nothing answered: this session runs unprotected. */
-  let unprotected = false;
   /**
    * toolCallId → the exact `input` object sent in the PreToolUse payload.
    * PostToolUse must echo it byte-identically or the runtime withholds the
@@ -48,101 +59,78 @@ export default function (pi: ExtensionAPI): void {
    */
   const pendingInputs = new Map<string, Record<string, unknown>>();
 
-  const gated = (): boolean => gate?.gated === true && !unprotected;
+  /**
+   * Serialized hook lane. Every `appa hook` invocation for this session runs
+   * through here in order, so the SessionStart payload (with
+   * `--ensure-runtime`) always lands before the first PreToolUse even though
+   * session_start does not wait for it. Startup stays off the fast-start
+   * lane: the runtime boot cost is paid by whichever tool call needs the
+   * runtime first, and a runtime that cannot answer fails that call closed
+   * with the reason — never a slower session start.
+   */
+  let lane: Promise<unknown> = Promise.resolve();
+  const enqueue = <T>(run: () => Promise<T>): Promise<T> => {
+    const outcome = lane.then(run, run);
+    lane = outcome.then(
+      () => undefined,
+      () => undefined,
+    );
+    return outcome;
+  };
+
+  const gated = (): boolean => gate?.gated === true;
+
+  const hookOptions = (state: GateState, extra: InvokeOptions = {}): InvokeOptions => {
+    const options: InvokeOptions = { ...extra };
+    if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
+    return options;
+  };
 
   pi.on("session_start", async (event, ctx) => {
     gate = captureGate(process.env, ctx.cwd);
     sessionId = ctx.sessionManager.getSessionId();
-    if (!gate.gated) return;
-    unprotected = false;
-
-    const payload = sessionStartPayload(sessionId, event.reason, ctx.cwd);
-    const options = {
-      ensureRuntime: true,
-      ...(gate.config !== undefined ? { config: gate.config } : {}),
-    };
-    const notify = (message: string, kind: "info" | "warning"): void => {
-      if (ctx.hasUI) ctx.ui.notify(message, kind);
-    };
-    let outcome = await invokeAppaHook(payload, options);
-    let warnedAlready = false;
-    // A missing default `appa` is self-provisioned: run the official install
-    // script once, then retry bringing the runtime up. Custom APPA_HOOK_BINs
-    // are the user's own and never auto-installed.
-    if (outcome.binaryMissing && resolveHookBin(process.env) === "appa") {
-      notify(
-        "`appa` was not found — installing the OpenAPPA runtime " +
-          "(https://openappa.com/install.sh)…",
-        "info",
+    if (!gated()) return;
+    const state = gate;
+    const options: InvokeOptions = { ensureRuntime: true };
+    if (state.config !== undefined) options.config = state.config;
+    if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
+    // Backgrounded on purpose (see `lane`): a cold runtime boot — or a first
+    // run that still has to install or update the runtime — must not sit in
+    // Pi's session-start path. Failure surfaces as a warning when it settles.
+    void enqueue(async () => {
+      const outcome = await invokeAppaHook(
+        sessionStartPayload(sessionId, event.reason, ctx.cwd),
+        options,
       );
-      const install = await installAppa();
-      if (install.exitCode !== 0) {
-        warnedAlready = true;
-        notify(
-          `OpenAPPA auto-install failed: ${outcomeTail(install)}. ` +
-            "Tool calls stay blocked; install `appa` manually (see the README) or run /appa off.",
+      if (outcome.exitCode !== 0 && ctx.hasUI) {
+        const remedy =
+          options.config === undefined
+            ? " Provide a policy (this project's .pi/openappa, /appa init, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
+            : "";
+        ctx.ui.notify(
+          `OpenAPPA gated but the runtime did not answer (${state.runtimeUrl}): ` +
+            `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
+          "Tool calls will be blocked until it answers.",
           "warning",
         );
-      } else {
-        const retry = await invokeAppaHook(payload, options);
-        if (retry.binaryMissing) {
-          warnedAlready = true;
-          notify(
-            "OpenAPPA auto-install finished but `appa` is still not on PATH. " +
-              `Installer output: ${outcomeTail(install)} — restart the session once PATH has it.`,
-            "warning",
-          );
-        }
-        outcome = retry;
-      }
-    }
-    if (outcome.exitCode !== 0) {
-      // No policy anywhere and nothing answering: run this session
-      // unprotected with one warning instead of fail-closed (the configured
-      // default). A named policy that fails stays fail-closed below.
-      if (
-        resolveHookBin(process.env) === "appa" &&
-        gate.config === undefined &&
-        !appaDefaultPolicyExists(process.env) &&
-        !(await checkHealth(gate.runtimeUrl)).ok
-      ) {
-        unprotected = true;
-        if (!warnedAlready) {
-          notify(
-            "OpenAPPA is on by default, but no policy exists (APPA_CONFIG, " +
-              ".pi/openappa, or ~/.config/appa/appa.toml) and no runtime answers " +
-              `at ${gate.runtimeUrl} — this session runs unprotected. ` +
-              "Write a policy, or run /appa off.",
-            "warning",
-          );
-        }
-        return;
       }
-      if (ctx.hasUI && !warnedAlready) {
-      const remedy =
-        gate.config === undefined
-          ? " Provide a policy (this project's .pi/openappa, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
-          : "";
-      ctx.ui.notify(
-        `OpenAPPA gated but the runtime did not answer (${gate.runtimeUrl}): ` +
-          `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
-          "Tool calls will be blocked until it answers.",
-        "warning",
-      );
-      }
-    }
+    });
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
     if (!gated()) return;
     // The prompt event establishes the turn boundary; it does not gate.
-    await invokeAppaHook(promptPayload(sessionId, event.prompt, ctx.cwd));
+    await enqueue(() =>
+      invokeAppaHook(promptPayload(sessionId, event.prompt, ctx.cwd), hookOptions(gate!)),
+    );
   });
 
   pi.on("tool_call", async (event, ctx) => {
     if (!gated()) return;
     const payload = preToolUsePayload(sessionId, event.toolName, event.input, ctx.cwd);
-    const outcome = await invokeAppaHook(payload);
+    const outcome = await enqueue(() =>
+      invokeAppaHook(payload, hookOptions(gate!)),
+    );
     const decision = parseCallDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
     if (decision.type === "deny") {
       return { block: true, reason: `appa: ${decision.reason}` };
@@ -167,7 +155,9 @@ export default function (pi: ExtensionAPI): void {
       response,
       ctx.cwd,
     );
-    const outcome = await invokeAppaHook(payload);
+    const outcome = await enqueue(() =>
+      invokeAppaHook(payload, hookOptions(gate!)),
+    );
     const decision = parseResultDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
     if (decision.type === "pass") {
       return undefined;
@@ -181,7 +171,9 @@ export default function (pi: ExtensionAPI): void {
   pi.on("turn_end", async () => {
     if (!gated()) return;
     // Turn completion is reported, never gated (matching --turn-end).
-    await invokeAppaHook(stopPayload(sessionId), { turnEnd: true });
+    await enqueue(() =>
+      invokeAppaHook(stopPayload(sessionId), hookOptions(gate!, { turnEnd: true })),
+    );
   });
 
   pi.on("session_shutdown", () => {
@@ -189,41 +181,69 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("appa", {
-    description: "Show OpenAPPA status; `appa on|off` toggles protection globally",
+    description:
+      "OpenAPPA guard: status, `appa on|off` always-on, `appa init [project]` writes a starter policy",
+    getArgumentCompletions: (argumentPrefix) => {
+      const items = [
+        {
+          value: "on",
+          label: "on",
+          description: "Protect every future Pi session (always-on marker)",
+        },
+        { value: "off", label: "off", description: "Disable always-on protection" },
+        {
+          value: "init",
+          label: "init",
+          description: "Write the starter policy to ~/.config/appa/appa.toml",
+        },
+        {
+          value: "init project",
+          label: "init project",
+          description: "Write ./appa.toml plus the .pi/openappa project marker",
+        },
+        { value: "status", label: "status", description: "Show protection and runtime health" },
+      ];
+      const prefix = argumentPrefix.trim();
+      const hits = prefix === "" ? items : items.filter((item) => item.value.startsWith(prefix));
+      return hits.length > 0 ? hits : null;
+    },
     handler: async (args, ctx) => {
-      const arg = args.trim();
+      const tokens = args.trim().split(/\s+/).filter((token) => token !== "");
+      const arg = tokens[0] ?? "";
+
       if (arg === "on" || arg === "off") {
-        setGloballyOff(process.env, arg === "off");
+        setAlwaysOn(process.env, arg === "on");
         gate = captureGate(process.env, ctx.cwd);
         if (ctx.hasUI) {
           ctx.ui.notify(
             arg === "on"
-              ? "OpenAPPA protection re-enabled: on by default for every session."
-              : "OpenAPPA protection disabled globally (/appa on re-enables).",
+              ? "OpenAPPA always-on enabled: every future Pi session is protected."
+              : "OpenAPPA always-on disabled.",
             "info",
           );
         }
         return;
       }
+
+      if (arg === "init") {
+        const scope = tokens[1] === "project" ? "project" : "user";
+        const force = tokens.includes("--force");
+        await runInit(scope, force, ctx);
+        return;
+      }
+
       const state = gate ?? captureGate(process.env, ctx.cwd);
       const mode =
         state.source === "project"
           ? "project (.pi/openappa)"
-          : state.source === "env-on"
+          : state.source === "env"
             ? "launch (APPA_GATE=1)"
-            : state.source === "env-off"
-              ? "launch opt-out (APPA_GATE=0)"
-              : state.source === "project-off"
-                ? "project opt-out (.pi/no-openappa)"
-                : state.source === "global-off"
-                  ? "global opt-out (/appa on re-enables)"
-                  : "on by default (/appa off disables)";
+            : state.source === "always-on"
+              ? "always-on (/appa off to disable)"
+              : "off — /appa on enables it for every session";
       const lines: string[] = [];
       lines.push(state.gated ? `Protection: ON (session ${sessionId || "not started"})` : `Protection: off — ${mode}`);
-      if (unprotected) {
-        lines.push("Session: unprotected — no policy found; see the startup warning.");
-      }
-      if (state.gated && !unprotected) lines.push(`Mode: ${mode}`);
+      if (state.gated) lines.push(`Mode: ${mode}`);
       if (state.config !== undefined) lines.push(`Policy: ${state.config}`);
       lines.push(`Runtime: ${state.runtimeUrl}`);
       const health = await checkHealth(state.runtimeUrl);
@@ -237,13 +257,59 @@ export default function (pi: ExtensionAPI): void {
       }
     },
   });
-}
 
-/** Last ~200 chars of installer output, whitespace-normalized, for notices. */
-function outcomeTail(outcome: InstallOutcome): string {
-  const text = `${outcome.stderr} ${outcome.stdout}`.trim().replace(/\s+/g, " ");
-  if (text === "") return "(no output)";
-  return text.length > 200 ? `…${text.slice(-200)}` : text;
+  /** `/appa init` — write the starter policy (and settings) without clobbering. */
+  async function runInit(
+    scope: "user" | "project",
+    force: boolean,
+    ctx: { cwd: string; hasUI: boolean; ui: { notify: (message: string, type?: "info" | "warning" | "error") => void } },
+  ): Promise<void> {
+    const notify = (message: string, type: "info" | "warning" | "error" = "info") => {
+      if (ctx.hasUI) ctx.ui.notify(message, type);
+    };
+    try {
+      if (scope === "project") {
+        const policy = join(ctx.cwd, "appa.toml");
+        const marker = join(ctx.cwd, ".pi", "openappa");
+        if (existsSync(policy) && !force) {
+          notify(`${policy} already exists; rerun with --force to overwrite it.`, "warning");
+          return;
+        }
+        mkdirSync(dirname(policy), { recursive: true });
+        writeFileSync(policy, templateToml());
+        if (!existsSync(marker)) {
+          mkdirSync(dirname(marker), { recursive: true });
+          writeFileSync(marker, "appa.toml\n");
+        }
+        notify(
+          `Wrote ${policy} and the .pi/openappa marker. Sessions started in this directory are protected; new sessions pick the policy up (trajectories keep the policy they opened with).`,
+        );
+        return;
+      }
+      const policy = appaDefaultConfigPath(process.env);
+      if (existsSync(policy) && !force) {
+        notify(
+          `${policy} already exists; rerun with --force to overwrite it, or /appa init project for one project.`,
+          "warning",
+        );
+        return;
+      }
+      mkdirSync(dirname(policy), { recursive: true });
+      writeFileSync(policy, templateToml());
+      const settings = settingsPath(process.env);
+      const lines: string[] = [`Wrote the starter policy to ${policy}.`];
+      if (!existsSync(settings)) {
+        mkdirSync(dirname(settings), { recursive: true });
+        writeFileSync(settings, `${JSON.stringify({ config: policy }, null, 2)}\n`);
+        lines.push(`Wrote ${settings} pointing at it.`);
+      }
+      lines.push("Protect sessions with /appa on, APPA_GATE=1, or /appa init project.");
+      notify(lines.join(" "));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      notify(`/appa init failed: ${detail}`, "error");
+    }
+  }
 }
 
 function joinContent(content: ReadonlyArray<unknown>): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openappa",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Thin OpenAPPA guard extension for Pi: gates tool calls through the APPA runtime. No policy logic lives here.",
   "keywords": [
     "pi-package",
@@ -19,6 +19,13 @@
   "homepage": "https://github.com/aemonge-dev/pi-openappa#readme",
   "bugs": "https://github.com/aemonge-dev/pi-openappa/issues",
   "type": "module",
+  "files": [
+    "extensions/",
+    "src/",
+    "templates/",
+    "traces/",
+    "docs/"
+  ],
   "pi": {
     "extensions": ["./extensions/index.ts"]
   },