From f0fe50a25339f6367b6033694b48ea72bf351e32 Mon Sep 17 00:00:00 2001
From: artale <arosstale1@gmail.com>
Date: Sun, 21 Jun 2026 14:28:10 +0200
Subject: [PATCH] docs: clarify attestation proof layer positioning

---
 README.md                 |  8 ++++++--
 docs/agentic-layer-tac.md | 16 ++++++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 9ba6d31..bd2d1d7 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # Fable Agent
 
-**Harness-agnostic, model-agnostic, self-improving agent system — loops, dynamic workflows, routines.**
+**Agentic attestation infrastructure — typed receipts, safety scanners, risk gates, and guarded deploy proof for AI-generated work.**
 
-The harness, not the model. Swap any executor, any model, any provider — the system compounds regardless.
+The harness, not the model. Pi/Codex/Claude can act; fable-agent proves what happened, what verified it, what risk remains, and whether guarded deploy is allowed.
 
 ```
 node dist/index.js demo
@@ -54,6 +54,10 @@ node dist/index.js demo
 # Run a task
 node dist/index.js run "Review the auth module for security issues" --loop 5
 
+# Prove agent work before saying done
+node dist/index.js verify . --out .fable/attestations/latest.json
+node dist/index.js factory verify . --out .fable/attestations/factory-latest.json
+
 # Web search via Exa (set EXA_API_KEY in .env or export it)
 export EXA_API_KEY=your_key_here
 node dist/index.js exa search "self-improving agent systems"
diff --git a/docs/agentic-layer-tac.md b/docs/agentic-layer-tac.md
index 70bab07..475e3dc 100644
--- a/docs/agentic-layer-tac.md
+++ b/docs/agentic-layer-tac.md
@@ -3,7 +3,7 @@
 ## Golden path
 
 ```text
-idea → safety gate → ADW plan/build/test/review → verify-cycle receipt → guarded deploy decision
+idea → safety gate → ADW plan/build/test/review → agentic attestation → guarded 8099/deploy decision
 ```
 
 ## Required skills
@@ -15,6 +15,7 @@ idea → safety gate → ADW plan/build/test/review → verify-cycle receipt →
 | ADW pipeline | Plan → Build → Test → Review → Ship | documented skill available | run on one real change |
 | verifier | Prevent fake PASS | prompt rule active | every receipt includes commands/output |
 | verify-cycle | Factory/RSI/skill health proof | `factory verify-cycle` live-passed on `rsi_canary` and `apple` | non-canary degraded repair proof |
+| agentic-attestation | Prove any harness output before done | `fable-agent verify`, `factory verify`, schema `fable.verification.attestation.v1` | attach to Pi/OpenClaw loops |
 | skill-sync | Import skills without corrupting IDs | frontmatter + explicit ID parsing tested | clean generated duplicates |
 | platform-engineer | Keep MVI discipline | active principle | no dashboard/orchestrator until receipts are boring green |
 
@@ -22,7 +23,7 @@ idea → safety gate → ADW plan/build/test/review → verify-cycle receipt →
 
 - Class 1 Grade 6/7: skills, workflows, subagents, mental-model docs exist.
 - Class 2 Grade 1: factory webhook/out-loop path exists at `8099/deploy`.
-- Class 2 Grade 2: deterministic workflow proof is emerging via `verify-cycle`.
+- Class 2 Grade 2: deterministic workflow proof is emerging via `verify-cycle` and `fable.verification.attestation.v1`.
 - Class 3: not yet. Do not claim orchestrator maturity until ADW runs are receipt-backed.
 
 ## Acceptance criteria for next release
@@ -36,8 +37,19 @@ PASS real-engineering verify
 ✓ factory status ok
 ✓ deploy route 8099/deploy present
 ✓ verify-cycle receipt written
+✓ agentic attestation attached
 ```
 
+## Pi integration
+
+Pi/OpenClaw/Codex/Claude loops should call fable-agent as the proof layer before final completion:
+
+```bash
+fable-agent verify . --out .fable/attestations/latest.json
+```
+
+No final `done` without an attestation or explicit `UNVERIFIED` status. Current guarded deploy path remains `8099/deploy via git-proxy`; `8098 deploy-webhook` is legacy/stale for direct fable-agent decisions.
+
 ## Do not build yet
 
 - dashboard