From 85d3788c8ac54ee7f7e6bfb7fc6e94435d08160c Mon Sep 17 00:00:00 2001
From: artale <arosstale1@gmail.com>
Date: Sun, 21 Jun 2026 13:44:46 +0200
Subject: [PATCH] docs: add pi harness integration contract

---
 docs/pi-integration.md | 72 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 docs/pi-integration.md

diff --git a/docs/pi-integration.md b/docs/pi-integration.md
new file mode 100644
index 0000000..f0f19c4
--- /dev/null
+++ b/docs/pi-integration.md
@@ -0,0 +1,72 @@
+# Pi Integration
+
+## Thesis
+
+```text
+Pi makes agents act.
+fable-agent proves what happened.
+git-proxy deploys through 8099/deploy.
+```
+
+Pi is the minimalist harness: loop, tools, TUI, branching, hot reload, and human-steered iteration.
+fable-agent is the proof layer: typed attestations, safety scanners, risk gates, and guarded deploy receipts.
+
+## Command contract
+
+After Pi, Codex, Claude Code, OpenClaw, or another harness changes code, run:
+
+```bash
+fable-agent verify . --out .fable/attestations/latest.json
+```
+
+Factory-aware alias:
+
+```bash
+fable-agent factory verify . --out .fable/attestations/factory-latest.json
+```
+
+A harness may only claim `done` when it has either:
+
+1. attached an attestation with `verification_status` and residual risk, or
+2. said `UNVERIFIED` clearly.
+
+## Attestation fields that matter
+
+```json
+{
+  "schema": "fable.verification.attestation.v1",
+  "verification_status": "verified|partial|failed|unverified",
+  "risk_findings": [],
+  "human_review": { "required": false, "reasons": [] },
+  "deploy_route": "8099/deploy via git-proxy",
+  "unverified_claims": []
+}
+```
+
+## Pi prompt snippet
+
+```text
+Before you say done, run:
+
+fable-agent verify . --out .fable/attestations/latest.json
+
+Summarize verification_status, human_review.required, risk_findings, and unverified_claims.
+If you cannot run it, say UNVERIFIED and explain why.
+```
+
+## Verified vs memory
+
+- Current guarded deploy path for fable-agent decisions: `8099/deploy via git-proxy`.
+- `8098 deploy-webhook` exists, but direct use is legacy/stale for fable-agent decisions.
+- Factory inventory, RSI cron, and container counts may come from memory; live receipts are stronger.
+- `rsi_canary` degraded→patched→recovered is proven by receipt.
+- Non-canary degraded repair is not proven until a degraded-skill recovery receipt exists.
+
+## What not to build
+
+- Pi clone
+- new orchestrator
+- dashboard
+- marketplace
+- generic self-healing claims
+- direct `8098` deploy assumptions