gentle-pi 2.6.1 → 2.6.2

package/contracts/review-provider-contract-mirror/provider-contract.lock.json

@@ -3,23 +3,24 @@
   "acquisition": "field-test-local",
   "contract_semver": "1.2.0",
   "source": {
-    "kind": "tree"
+    "kind": "archive",
+    "archive_sha256": "b0b9be7569e4544d37cbbfa17c5def56fdb66ae670584eb74f9d0ffc200e03c4"
   },
-  "tree_sha256": "9cc05e9f0cbfd22734f1a112dc6120230b22de5318401db19652b4287b7382b8",
+  "tree_sha256": "832f62d461249576f9b7e864c2d5adbb6e38a36f8a7103a28a9f2ca81f41de41",
   "entries": {
     "README.md": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085",
-    "manifest.json": "042a8925ac71929c33de2cad630bac26192ff61e255145649b3c34ba4048e923",
-    "orchestration/pi.md": "69c51944081ccff09d1cee5e24eb3a14b7b911a2e734cef8f8ea94a15b9f9d4c",
-    "schemas/lens.schema.json": "ffef79cfb763333282285ff5c795a32b5a88d840b4a8d125ce012188b04cffe1",
+    "manifest.json": "097a41ecbcf96e5f3432f3f38164ccaf440f33de82c1aa8ae956b2ba263d4d18",
+    "orchestration/pi.md": "679133e54b7fe8661050cdde51aed44ddf8e66e478c7a1b5176fe3278714a2f6",
+    "schemas/lens.schema.json": "9b8a2354a570888486015434501b66b51441a3baf5bf858635e4fff56b2e8298",
     "schemas/refuter.schema.json": "36f8267c6c3f04600b8f1cb77df70d90858611af822cc81922efd6b3502fb646",
-    "schemas/targeted-validator.schema.json": "6a8d7b331ec6f000366017e39e0476511c3b032649c42abfe865c1e9c956510e",
+    "schemas/targeted-validator.schema.json": "40e397195bdfbc6782fc3090f20c5be082e4d14d2855314f99ecb8506133eddc",
     "vectors/lens.json": "7ef0b08404645eeb5dba92aba5f8e4780667b6ec775f43ed8547ff9f2a7148c8",
     "vectors/refuter.json": "f42d71906e49c4191660b2da7e70f01f1778b23d32089005bd2d7ae9cbb73039",
     "vectors/targeted-validator.json": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
   },
   "generated": {
-    "generated/provider-capabilities.baseline.json": "0c3847e7449f095a44b92653effb68b8c8e09b8f1593b4fc6365f7a78ae99767",
-    "generated/provider-roles.baseline.json": "7a1c5ef7688f7dadef0b2c1f2a50af0a8d1fd1d58cce089ababd6e5bb7ccaefc"
+    "generated/provider-capabilities.baseline.json": "186d847f8df77024d8a2df03e2d4d664bc1951f5abc89b6b36ffe8422366234b",
+    "generated/provider-roles.baseline.json": "fd29e157884e7437c4a7f9b1e26a6f777f8d9918d8733ccd8542af12807be6b3"
   },
   "runtimes": [
     "claude-code",

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/manifest.json

@@ -22,7 +22,7 @@
       ],
       "schema": {
         "path": "schemas/lens.schema.json",
-        "sha256": "ffef79cfb763333282285ff5c795a32b5a88d840b4a8d125ce012188b04cffe1"
+        "sha256": "9b8a2354a570888486015434501b66b51441a3baf5bf858635e4fff56b2e8298"
       },
       "vector": {
         "path": "vectors/lens.json",
@@ -54,7 +54,7 @@
       ],
       "schema": {
         "path": "schemas/targeted-validator.schema.json",
-        "sha256": "6a8d7b331ec6f000366017e39e0476511c3b032649c42abfe865c1e9c956510e"
+        "sha256": "40e397195bdfbc6782fc3090f20c5be082e4d14d2855314f99ecb8506133eddc"
       },
       "vector": {
         "path": "vectors/targeted-validator.json",
@@ -67,7 +67,7 @@
       "runtime": "pi",
       "file": {
         "path": "orchestration/pi.md",
-        "sha256": "69c51944081ccff09d1cee5e24eb3a14b7b911a2e734cef8f8ea94a15b9f9d4c"
+        "sha256": "679133e54b7fe8661050cdde51aed44ddf8e66e478c7a1b5176fe3278714a2f6"
       }
     }
   ]

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/orchestration/pi.md

@@ -40,13 +40,18 @@ A `stop` ends its transition, never approves delivery. `D` means the human disab
 
 | Reason codes | Continuation |
 | --- | --- |
-| `captured_artifacts_unverifiable`, `captured_result_selection_unavailable`, `missing_authority_binding`, `corrupted_or_unverifiable_authority`, `manual_intervention_required`, `native_stop_required` | Terminal: the maintainer inspects authority/lineage, or `D`. |
+| `captured_artifacts_unverifiable`, `captured_result_selection_unavailable`, `captured_verification_evidence_invalid`, `final_verification_retry_unavailable`, `missing_authority_binding`, `corrupted_or_unverifiable_authority`, `manual_intervention_required`, `native_stop_required` | Terminal: the maintainer inspects authority/lineage, or `D`. |
 | `empty_base_diff_bootstrap_required` | Terminal: authorized empty-root bootstrap for a new target, or `D`. |
 | `lens_context_budget_exceeded` | Terminal: reduce the candidate scope and start a new transaction, or `D`. |
+| `managed_assets_outdated` | Run the `gentle-ai sync` command from the stop's `continuation`, then `S`. |
 | `staged_workspace_overlay_recovery_unavailable` | Call facade `recover` with the retained `lineageId`, or start a fresh transaction; otherwise `D`. |
 | `corrected_candidate_unavailable` | Change the correction candidate, then `S`; do not reuse the pre-correction target. |
+| `correction_repository_verification_failed` | Change the correction candidate within the same open budget, then `S`. |
+| `original_finalize_request_required` | Run the exact original-finalize replay bound to the stop. |
+| `staged_delivery_candidate_required` | Stage every reviewed path exactly as reviewed, then `S`. |
 | `recovery_scope_unchanged` | Change the target identity, then retry the facade `recover` route the stop returned. |
-| `rdd_disabled` | `--scope clone` only clears a clone-local off; the human runs `gentle-ai review mode enable --scope global`, then `S`. |
+| `unchanged_or_unverified_authority` | Change the candidate content, then start a new transaction, or `D`. |
+| `rdd_disabled` | Run the exact source-scoped `gentle-ai review mode enable` command rendered by bound facade STATUS, then `S`. |
 
 ## Delivery follows ordinary repository policy
 

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/lens.schema.json

@@ -7,10 +7,10 @@
   "required": ["subject_hash", "inspection", "findings", "evidence"],
   "properties": {
     "subject_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
-    "inspection": {"type": "object", "additionalProperties": false, "required": ["status", "paths"], "properties": {"status": {"const": "completed"}, "paths": {"type": "array", "description": "Complete unique unordered set of every changed_path_manifest.path.", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}},
+    "inspection": {"type": "object", "additionalProperties": false, "required": ["status", "paths"], "allOf": [{"if": {"properties": {"status": {"const": "unavailable"}}, "required": ["status"]}, "then": {"required": ["reason"]}}], "properties": {"status": {"type": "string", "enum": ["completed", "unavailable"], "description": "\"completed\" asserts every changed_path_manifest path was actually inspected. \"unavailable\" asserts the candidate could not be inspected at all and requires a non-empty reason; this is the typed admission-completeness signal; evidence prose is not a substitute for it."}, "paths": {"type": "array", "description": "Complete unique unordered set of every changed_path_manifest.path when status is \"completed\"; empty when status is \"unavailable\".", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reason": {"type": "string", "minLength": 1, "description": "Required and non-empty only when status is \"unavailable\": why the candidate could not be inspected."}}},
     "lens": {"type": "string", "description": "Optional selected lens binding. Omission canonicalizes to the selected subject lens.", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]},
     "findings": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["location", "severity", "claim", "proof_refs"], "allOf": [{"if": {"properties": {"severity": {"enum": ["BLOCKER", "CRITICAL"]}}, "required": ["severity"]}, "then": {"required": ["evidence_class", "causal_disposition"]}}], "properties": {"id": {"type": "string", "pattern": "^R[1-4]-[A-Za-z0-9][A-Za-z0-9._-]*$", "description": "Optional explicit ID; omit it to receive a native-assigned ID. When present it must carry the prefix bound to the selected lens, not the selection order: review-risk=R1-, review-readability=R2-, review-reliability=R3-, review-resilience=R4-."}, "lens": {"type": "string", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]}, "location": {"type": "string", "description": "One canonical repository-relative path:line or inclusive path:start-end span.", "pattern": "^.+:[1-9][0-9]*(?:-[1-9][0-9]*)?$"}, "severity": {"type": "string", "enum": ["BLOCKER", "CRITICAL", "WARNING", "SUGGESTION"]}, "claim": {"type": "string", "minLength": 1}, "proof_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}, "evidence_class": {"type": "string", "enum": ["deterministic", "inferential", "insufficient"]}, "causal_disposition": {"type": "string", "enum": ["introduced", "behavior-activated", "worsened", "pre-existing", "base-only", "unknown"]}}}},
     "evidence": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}
   },
-  "examples": [{"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "completed", "paths": ["internal/example.go"]}, "findings": [], "evidence": ["reviewed the complete candidate scope"]}]
+  "examples": [{"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "completed", "paths": ["internal/example.go"]}, "findings": [], "evidence": ["reviewed the complete candidate scope"]}, {"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "unavailable", "paths": [], "reason": "the immutable inspection command timed out before any path could be read"}, "findings": [], "evidence": ["inspection was unavailable; see inspection.reason"]}]
 }

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/targeted-validator.schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/validator/v1","title":"Gentle AI targeted validator result","type":"object","additionalProperties":false,"required":["targeted_validation_request_hash","correction_target_identity","original_criteria","correction_regression","follow_ups"],"properties":{"targeted_validation_request_hash":{"$ref":"#/$defs/sha256"},"correction_target_identity":{"$ref":"#/$defs/sha256"},"original_criteria":{"$ref":"#/$defs/check"},"correction_regression":{"$ref":"#/$defs/check"},"follow_ups":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["observation","proof_refs"],"properties":{"observation":{"type":"string"},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"check":{"type":"object","additionalProperties":false,"required":["passed","evidence"],"properties":{"passed":{"type":"boolean","description":"true means the named check passed; false means the named check failed."},"evidence":{"type":"array","minItems":1,"items":{"type":"string"}}}}},"examples":[{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}]}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/validator/v1","title":"Gentle AI targeted validator result","type":"object","additionalProperties":false,"required":["targeted_validation_request_hash","correction_target_identity","original_criteria","correction_regression","follow_ups"],"properties":{"targeted_validation_request_hash":{"$ref":"#/$defs/sha256"},"correction_target_identity":{"$ref":"#/$defs/sha256"},"original_criteria":{"$ref":"#/$defs/check"},"correction_regression":{"$ref":"#/$defs/check"},"follow_ups":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["observation","proof_refs"],"properties":{"observation":{"type":"string"},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"allOf":[{"if":{"properties":{"correction_regression":{"type":"object","properties":{"passed":{"const":false}},"required":["passed"]}},"required":["correction_regression"]},"then":{"properties":{"correction_regression":{"type":"object","properties":{"regressions":{"minItems":1}},"required":["regressions"]}}}}],"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"check":{"type":"object","additionalProperties":false,"required":["passed","evidence"],"properties":{"passed":{"type":"boolean","description":"true means the named check passed; false means the named check failed."},"evidence":{"type":"array","minItems":1,"items":{"type":"string"}},"regressions":{"type":"array","items":{"$ref":"#/$defs/regression"},"description":"Required with at least one entry when this is correction_regression and passed is false: one entry per observed regression, omitted or empty otherwise."},"inspection":{"$ref":"#/$defs/inspection"}},"allOf":[{"if":{"properties":{"inspection":{"type":"object","properties":{"status":{"const":"unavailable"}},"required":["status"]}},"required":["inspection"]},"then":{"properties":{"inspection":{"type":"object","required":["reason"]}}}}]},"inspection":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["completed","unavailable"],"description":"completed means this check's verdict came from actually reading the frozen candidate trees. unavailable means it did not, and this check produced no verdict."},"reason":{"type":"string","minLength":1,"description":"Required when status is unavailable: why the frozen candidate trees could not be read."}},"description":"Optional. Omit this field entirely when inspection completed normally -- every check that predates this field already assumed that default. Never infer unavailable from evidence wording; only this typed field marks a check inconclusive."},"regression":{"type":"object","additionalProperties":false,"required":["location","claim","proof_refs"],"properties":{"id":{"type":"string","description":"Optional explicit ID; omit it to receive a native-assigned ID."},"location":{"type":"string","description":"One canonical repository-relative path:line or inclusive path:start-end span.","pattern":"^.+:[1-9][0-9]*(?:-[1-9][0-9]*)?$"},"claim":{"type":"string","minLength":1},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}},"examples":[{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}]}

package/contracts/review-provider-contract-mirror/v1.2.0/generated/provider-capabilities.baseline.json

@@ -16,7 +16,7 @@
     {
       "runtime": "pi",
       "path": "orchestration/pi.md",
-      "sha256": "69c51944081ccff09d1cee5e24eb3a14b7b911a2e734cef8f8ea94a15b9f9d4c"
+      "sha256": "679133e54b7fe8661050cdde51aed44ddf8e66e478c7a1b5176fe3278714a2f6"
     }
   ]
 }

package/contracts/review-provider-contract-mirror/v1.2.0/generated/provider-roles.baseline.json

@@ -10,7 +10,7 @@
         "gentle-ai.provider-transport/v1"
       ],
       "schema_path": "schemas/lens.schema.json",
-      "schema_sha256": "ffef79cfb763333282285ff5c795a32b5a88d840b4a8d125ce012188b04cffe1",
+      "schema_sha256": "9b8a2354a570888486015434501b66b51441a3baf5bf858635e4fff56b2e8298",
       "vector_path": "vectors/lens.json",
       "vector_sha256": "7ef0b08404645eeb5dba92aba5f8e4780667b6ec775f43ed8547ff9f2a7148c8"
     },
@@ -34,7 +34,7 @@
         "gentle-ai.provider-transport/v1"
       ],
       "schema_path": "schemas/targeted-validator.schema.json",
-      "schema_sha256": "6a8d7b331ec6f000366017e39e0476511c3b032649c42abfe865c1e9c956510e",
+      "schema_sha256": "40e397195bdfbc6782fc3090f20c5be082e4d14d2855314f99ecb8506133eddc",
       "vector_path": "vectors/targeted-validator.json",
       "vector_sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
     }

package/docs/assets/brand/gentle-pi-banner.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="400" viewBox="0 0 1200 400" role="img" aria-labelledby="banner-title banner-desc">
+  <title id="banner-title">GENTLE-PI — Pi-native development environment</title>
+  <desc id="banner-desc">A dark plum banner with a narrow monospaced GENTLE-PI wordmark, a geometric terminal symbol without rose imagery, and the promise of clear, human-directed development.</desc>
+  <defs>
+    <linearGradient id="banner-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#120d16"/><stop offset=".55" stop-color="#251124"/><stop offset="1" stop-color="#0b0910"/></linearGradient>
+    <linearGradient id="banner-rule" x1="0" x2="1"><stop stop-color="#f095c8" stop-opacity="0"/><stop offset=".18" stop-color="#f095c8"/><stop offset=".72" stop-color="#d7a0b8"/><stop offset="1" stop-color="#f095c8" stop-opacity="0"/></linearGradient>
+    <radialGradient id="banner-glow"><stop stop-color="#f095c8" stop-opacity=".28"/><stop offset="1" stop-color="#f095c8" stop-opacity="0"/></radialGradient>
+  </defs>
+  <rect width="1200" height="400" rx="20" fill="url(#banner-bg)"/>
+  <path d="M54 74H1146M54 328H1146" stroke="url(#banner-rule)" stroke-width="2"/>
+  <path d="M58 126H540" stroke="#f095c8" stroke-opacity=".35" stroke-width="2"/>
+  <g aria-label="GENTLE-PI" fill="none" stroke="#fff7f1" stroke-width="6" stroke-linecap="square" stroke-linejoin="miter">
+    <path d="M98 144H68V206H98V182H84"/>
+    <path d="M150 144H120V206H150M120 175H145"/>
+    <path d="M172 206V144L202 206V144"/>
+    <path d="M220 144H262M241 144V206"/>
+    <path d="M284 144V206H316"/>
+    <path d="M368 144H338V206H368M338 175H363"/>
+    <path d="M390 175H432"/>
+    <path d="M454 206V144H477L486 153V170L477 179H454"/>
+    <path d="M508 144H538M523 144V206M508 206H538"/>
+  </g>
+  <text x="62" y="267" fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="30">Powerful agents. One complete workspace.</text>
+  <g transform="translate(838 74)">
+    <circle cx="142" cy="126" r="142" fill="url(#banner-glow)"/>
+    <circle cx="142" cy="126" r="105" fill="none" stroke="#f095c8" stroke-opacity=".28" stroke-width="2"/>
+    <circle cx="142" cy="126" r="76" fill="none" stroke="#f095c8" stroke-opacity=".55" stroke-width="3" stroke-dasharray="4 11"/>
+    <path d="M142 5V28M142 224V247M21 126H44M240 126H263" stroke="#f095c8" stroke-width="3" stroke-linecap="round"/>
+    <rect x="76" y="75" width="132" height="102" rx="10" fill="#120d16" stroke="#f095c8" stroke-width="3"/>
+    <path d="M103 105l22 21-22 21M143 147h38" fill="none" stroke="#fff7f1" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M91 58L106 43M193 58l-15-15M91 194l15 15M193 194l-15 15" stroke="#d7a0b8" stroke-width="3" stroke-linecap="round"/>
+  </g>
+</svg>

package/docs/assets/brand/terminal-divider.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 40" role="img" aria-labelledby="title desc">
+  <title id="title">Decorative terminal separator</title>
+  <desc id="desc">Fading pink rules frame a terminal prompt symbol.</desc>
+  <defs>
+    <linearGradient id="fade-in" x1="0" x2="1">
+      <stop offset="0" stop-color="#F095C8" stop-opacity="0"/>
+      <stop offset="1" stop-color="#F095C8" stop-opacity="0.62"/>
+    </linearGradient>
+    <linearGradient id="fade-out" x1="0" x2="1">
+      <stop offset="0" stop-color="#F095C8" stop-opacity="0.62"/>
+      <stop offset="1" stop-color="#F095C8" stop-opacity="0"/>
+    </linearGradient>
+  </defs>
+  <path d="M16 20H212" fill="none" stroke="url(#fade-in)" stroke-width="1.25"/>
+  <path d="M268 20H464" fill="none" stroke="url(#fade-out)" stroke-width="1.25"/>
+  <path d="M222 13L233 20L222 27M243 27H258" fill="none" stroke="#F095C8" stroke-linecap="square" stroke-linejoin="miter" stroke-width="1.5"/>
+</svg>

package/docs/assets/diagrams/agent-orchestration.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="700" viewBox="0 0 960 700" role="img" aria-labelledby="agents-title agents-desc">
+  <title id="agents-title">Focused agent orchestration</title>
+  <desc id="agents-desc">One responsible parent assigns focused mapping, implementation, and verification work. Observed results return through a shared lane outside the worker cards.</desc>
+  <defs>
+    <linearGradient id="agents-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0d0b12"/><stop offset="1" stop-color="#20101f"/></linearGradient>
+    <marker id="agents-task-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#f095c8"/></marker>
+    <marker id="agents-result-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#d7a0b8"/></marker>
+  </defs>
+  <rect width="960" height="700" rx="20" fill="url(#agents-bg)"/>
+  <text x="58" y="65" fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Focused agents.</text>
+  <text x="58" y="120" fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">One responsible parent.</text>
+  <rect x="270" y="178" width="420" height="132" rx="18" fill="#2a1426" stroke="#f095c8" stroke-width="3"/>
+  <g fill="#18131b" stroke="#d7a0b8" stroke-width="2"><rect x="40" y="410" width="240" height="140" rx="16"/><rect x="360" y="410" width="240" height="140" rx="16"/><rect x="680" y="410" width="240" height="140" rx="16"/></g>
+  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round" marker-end="url(#agents-task-arrow)"><path d="M340 310V350H160V410"/><path d="M480 310V410"/><path d="M620 310V350H800V410"/></g>
+  <g fill="none" stroke="#d7a0b8" stroke-width="3" stroke-linecap="round" stroke-dasharray="8 8"><path d="M160 550V580"/><path d="M480 550V580"/><path d="M800 550V580"/><path d="M160 580H800"/></g>
+  <path d="M160 580H20V244H270" fill="none" stroke="#d7a0b8" stroke-width="3" stroke-linecap="round" stroke-dasharray="8 8" marker-end="url(#agents-result-arrow)"/>
+  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle"><text x="480" y="240" fill="#fff7f1" font-size="36" font-weight="700">Parent session</text><text x="480" y="282" fill="#d7a0b8" font-size="32">Coordinates</text><g fill="#fff7f1" font-size="36" font-weight="700"><text x="160" y="487">Map</text><text x="480" y="487">Implement</text><text x="800" y="487">Verify</text></g></g>
+  <g font-family="Arial, Helvetica, sans-serif" font-size="32" font-weight="700"><path d="M58 642H126" stroke="#f095c8" stroke-width="4" stroke-linecap="round"/><text x="142" y="653" fill="#f095c8">Task</text><path d="M310 642H378" stroke="#d7a0b8" stroke-width="4" stroke-linecap="round" stroke-dasharray="9 8"/><text x="394" y="653" fill="#d7a0b8">Result</text></g>
+</svg>

package/docs/assets/diagrams/gentleman-workflow.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="590" viewBox="0 0 960 590" role="img" aria-labelledby="workflow-title workflow-desc">
+  <title id="workflow-title">el Gentleman workflow</title>
+  <desc id="workflow-desc">A human-directed sequence from intent through clarification, workflow choice, work, evidence, and a final human decision.</desc>
+  <defs>
+    <linearGradient id="workflow-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#100c15"/><stop offset="1" stop-color="#21101f"/></linearGradient>
+    <marker id="workflow-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#f095c8"/></marker>
+  </defs>
+  <rect width="960" height="590" rx="20" fill="url(#workflow-bg)"/>
+  <text x="58" y="65" fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">From intent to evidence.</text>
+  <text x="58" y="120" fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">You stay in control.</text>
+  <g fill="#1c1420" stroke="#d7a0b8" stroke-width="2"><rect x="58" y="190" width="240" height="140" rx="16"/><rect x="350" y="190" width="240" height="140" rx="16"/><rect x="642" y="190" width="240" height="140" rx="16"/><rect x="642" y="370" width="240" height="140" rx="16"/><rect x="350" y="370" width="240" height="140" rx="16"/><rect x="58" y="370" width="240" height="140" rx="16"/></g>
+  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round" marker-end="url(#workflow-arrow)"><path d="M298 260H350"/><path d="M590 260H642"/><path d="M762 330V370"/><path d="M642 440H590"/><path d="M350 440H298"/></g>
+  <g fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="36" font-weight="700" text-anchor="middle"><text x="178" y="272">Intent</text><text x="470" y="272">Clarify</text><text x="762" y="272">Workflow</text><text x="762" y="452">Work</text><text x="470" y="452">Evidence</text><text x="178" y="452">Decision</text></g>
+  <path d="M58 548H902" stroke="#f095c8" stroke-opacity=".28" stroke-width="2"/>
+</svg>

package/docs/assets/diagrams/native-review.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="570" viewBox="0 0 960 570" role="img" aria-labelledby="review-title review-desc">
+  <title id="review-title">Native review boundary</title>
+  <desc id="review-desc">A frozen candidate moves through risk-scoped review to a result. A separate, clearly bounded human decision determines repository delivery.</desc>
+  <defs>
+    <linearGradient id="review-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0d0b12"/><stop offset="1" stop-color="#241020"/></linearGradient>
+    <marker id="review-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#f095c8"/></marker>
+  </defs>
+  <rect width="960" height="570" rx="20" fill="url(#review-bg)"/>
+  <text x="58" y="65" fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Review the exact change.</text>
+  <text x="58" y="120" fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Keep delivery in your hands.</text>
+  <g fill="#1c1420" stroke="#d7a0b8" stroke-width="2"><rect x="50" y="205" width="230" height="130" rx="16"/><rect x="365" y="185" width="230" height="170" rx="16" fill="#2a1426" stroke="#f095c8" stroke-width="3"/><rect x="680" y="205" width="230" height="130" rx="16"/></g>
+  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round" marker-end="url(#review-arrow)"><path d="M280 270H365"/><path d="M595 270H680"/></g>
+  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle"><g fill="#fff7f1" font-size="36" font-weight="700"><text x="165" y="264">Candidate</text><text x="480" y="250">Review</text><text x="795" y="264">Outcome</text></g><g fill="#d7a0b8" font-size="32"><text x="165" y="309">Frozen</text><text x="480" y="300">By risk</text><text x="795" y="309">Evidence</text></g></g>
+  <rect x="120" y="415" width="720" height="94" rx="16" fill="#18121b" stroke="#d7a0b8" stroke-width="2" stroke-dasharray="8 7"/>
+  <g font-family="Arial, Helvetica, sans-serif" text-anchor="middle"><text x="480" y="452" fill="#fff7f1" font-size="36" font-weight="700">You decide what ships</text><text x="480" y="493" fill="#d7a0b8" font-size="32">Review does not publish.</text></g>
+</svg>

package/docs/assets/diagrams/sdd-cycle.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="1230" viewBox="0 0 960 1230" role="img" aria-labelledby="sdd-title sdd-desc">
+  <title id="sdd-title">Optional specification-driven development path</title>
+  <desc id="sdd-desc">An optional sequence from exploration through research, proposal, specification, design, tasks, apply, verify, sync, and archive. Research can be bypassed and TDD applies under implementation when enabled.</desc>
+  <defs>
+    <linearGradient id="sdd-bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#100c15"/><stop offset="1" stop-color="#241020"/></linearGradient>
+    <marker id="sdd-arrow" markerUnits="userSpaceOnUse" markerWidth="10" markerHeight="10" viewBox="0 0 10 10" refX="10" refY="5" orient="auto"><path d="M0 0 10 5 0 10z" fill="#f095c8"/></marker>
+  </defs>
+  <rect width="960" height="1230" rx="20" fill="url(#sdd-bg)"/>
+  <text x="60" y="65" fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="44" font-weight="700">Optional SDD path.</text>
+  <g fill="#1b1420" stroke="#d7a0b8" stroke-width="2"><rect x="60" y="170" width="360" height="132" rx="16"/><rect x="540" y="170" width="360" height="132" rx="16"/><rect x="540" y="390" width="360" height="132" rx="16"/><rect x="60" y="390" width="360" height="132" rx="16"/><rect x="60" y="610" width="360" height="132" rx="16"/><rect x="540" y="610" width="360" height="132" rx="16"/><rect x="540" y="830" width="360" height="132" rx="16"/><rect x="60" y="830" width="360" height="132" rx="16"/><rect x="60" y="1050" width="360" height="132" rx="16"/><rect x="540" y="1050" width="360" height="132" rx="16"/></g>
+  <g fill="none" stroke="#f095c8" stroke-width="3" stroke-linecap="round" marker-end="url(#sdd-arrow)"><path d="M420 236H540"/><path d="M720 302V390"/><path d="M540 456H420"/><path d="M240 522V610"/><path d="M420 676H540"/><path d="M720 742V830"/><path d="M540 896H420"/><path d="M240 962V1050"/><path d="M420 1116H540"/><path d="M240 302V365H480V426H540"/></g>
+  <g fill="#fff7f1" font-family="Arial, Helvetica, sans-serif" font-size="36" font-weight="700" text-anchor="middle"><text x="240" y="248">Explore</text><text x="720" y="228">Research</text><text x="720" y="468">Proposal</text><text x="240" y="468">Spec</text><text x="240" y="688">Design</text><text x="720" y="688">Tasks</text><text x="720" y="908">Apply</text><text x="240" y="908">Verify</text><text x="240" y="1128">Sync</text><text x="720" y="1128">Archive</text></g>
+  <g fill="#d7a0b8" font-family="Arial, Helvetica, sans-serif" font-size="32" text-anchor="middle"><text x="720" y="274">Optional</text><text x="480" y="345">Skip research</text><text x="720" y="948">TDD if enabled</text></g>
+</svg>

package/docs/gentle-shell.md

@@ -0,0 +1,151 @@
+# Gentle Shell reference
+
+Gentle Shell is the `gentle-shell` coding-agent workspace built for Pi, not a theme. The `gentle-pi` package integrates the shell bar, workspace changes, provider usage where Pi exposes it, and native agent orchestration views into a Pi session. Start with the [README](../README.md#features) for the product overview.
+
+Source map: [shell extension](../extensions/gentle-shell.ts), [shell bar](../lib/shell-bar.ts), [changes model](../lib/shell-changes.ts), [changes view](../lib/shell-changes-view.ts), [usage model](../lib/shell-usage.ts), [usage view](../lib/shell-usage-view.ts), [agents extension](../extensions/gentle-agents.ts), and [agent runner](../lib/agents-runner.ts).
+
+## v2.6.0 workspace updates
+
+The [v2.6.0 release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) makes the workspace state more durable and inspectable:
+
+- Registered worktrees survive reloads. `/gentle:changes` groups each dirty root and presents status, line counts, and lazy diffs without conflating identical paths from different worktrees.
+- Fullscreen pointer navigation and the responsive sidebar keep changes, agents, and TODO usable at changing terminal widths; cached frames avoid redrawing inactive sidebar content while live status still updates.
+- The Agents List and Details views preserve the orchestrator/session hierarchy and completion, abort, and lost-exit history. Parent-child queries and notifications have an explicit handoff path, while model, effort, and usage stay observable per task.
+- Named `/gentle:profiles` atomically route the orchestrator separately from packaged and review roles; see the [technical reference](readme-reference.md#agent-model-profiles) for the profile model.
+
+The source checkout currently prepares `gentle-pi` `2.6.2` with a package-local Gentle AI `v2.8.2` pin; this is not a claim that `2.6.2` is published.
+
+## Shell interactions and runtime behavior
+
+Gentle Shell is the Pi workspace experience provided by the `gentle-pi` package. It follows the Gentle themes: one border language, champagne titles, rose for whatever is alive.
+
+In fullscreen at 140 columns or wider, the right sidebar scrolls **✿ Gentle-Pi ✿ → Status → Changes → Agents → TODO** together. The one-line heading is horizontally centered within the usable rail width, with pink flowers and normal white text in the Gentleman themes. Colors follow the active theme; no artwork scaling or custom fonts are used. Narrow/mobile terminals and regular mode retain bottom widgets without the sidebar heading. The original rose and text logo remain in the main chat startup intro.
+
+The rail reuses its last frame until something it paints changes, so silent frames stay cheap and live session state still lands on the next frame: a model switch, a new thinking level, context growth, session cost, session name and extension statuses all refresh the Status card without a redraw of the rest of the sidebar.
+
+The status bar replaces pi's three-line footer with a single line of segments:
+
+```text
+✿ gentle-pi ⟡ ~/work/gentle-pi main ⟡ gpt-5.5 · medium ⟡ ctx ▰▰▰▰▱▱▱▱ 45% ⟡ $9.49 sub ⟡ MCP: 3 servers enabled        Release notes
+```
+
+- Context is a gauge, not a number. It turns amber at 80% and red at 95%; after compaction it shows `?%` until the next response.
+- Cost carries `sub` when the active model runs on a subscription login.
+- Statuses other extensions publish through `setStatus` are appended as trailing segments; the session name sits at the right edge.
+- On narrow terminals the session name is dropped first, then trailing segments, before the line is truncated.
+
+The prompt wraps pi's editor in a rounded frame with a petal that shows what the agent is doing:
+
+```text
+╭─ ✿ working ──────────────────────────────────────────╮
+│ type, or / for commands                              │
+╰──────────────────────────────────────────────────────╯
+```
+
+- The petal is still while pi waits, spins with a `working` label while the agent works, and turns amber with a `queued` label when messages are waiting behind the current turn. pi's own "Working" row above the editor is hidden, since the frame already says it.
+- The frame uses the theme's border color over the panel background, so the prompt reads as one panel with the cards around it; the editor's scroll indicators stay inside the frame.
+- The hint appears only while the editor is empty.
+- If another extension already installed a custom editor, Gentle Shell leaves it alone.
+
+Changes across this session's registered worktrees show up below the editor and as an aggregate `±N` next to the session branch in the bar:
+
+```text
+✎ 3 files · +42 −7 · extensions/gentle-shell.ts, lib/shell-bar.ts, tests/x.test.ts · /gentle:changes
+```
+
+- Each registered root shows **all** dirty files: plain `git diff` against HEAD plus untracked files, including edits that predate this session. There are no baselines or file-level attribution filters.
+- The canonical session cwd root is included automatically. Successful standard `read`, `write`, `edit`, `grep`, `find`, and `ls` calls register their target worktree after completion. Failed calls, shell command text, and prose never register roots. Only roots sharing the session's Git common directory are accepted.
+- For opaque shell use or worktrees used earlier, call `session_worktree_register` with `{"path":"/path/to/worktree"}`. Registration is explicit, canonicalized, and deduplicated; unrelated dirty siblings remain invisible without an ignored-roots list.
+- The root registry persists in Pi custom entries (`gentle-pi.session-worktree/v1`). Exit/resume and `/reload` restore the same session UUID; `/tree` keeps roots session-wide. New sessions, `/fork`, and `/clone` ignore inherited registrations with another UUID. Clean roots stay registered but hidden until dirty; missing/prunable roots are skipped safely. Ephemeral `--no-session` runs cannot persist across exit.
+- Counts refresh after every tool call, at the end of each turn, and every 5 seconds in the background, so edits made from nvim or another agent show up without touching pi. `GENTLE_PI_SHELL_CHANGES_WATCH_MS` changes the interval; `off` leaves only the tool-driven refresh. Outside a git repository the widget stays hidden.
+- On narrow terminals the file list is dropped before the summary is truncated.
+
+`/gentle:changes` or `alt+g` opens the framed two-pane viewer. Dirty worktrees are accordion groups in the left pane, labeled with branch and directory basename (`detached` when there is no branch). Expand groups to reveal indented changed files; multiple groups can stay expanded. The right pane previews the selected file's lazy-loaded diff, or shows the selected group's full directory and summary. Clean, bare, missing, and prunable roots remain hidden; untracked-only roots are included.
+
+- `j`/`k` or up/down traverse visible groups and files, keeping the selection in view. On a group, `enter`, space, or right arrow toggles expansion. Left arrow or backspace moves a file selection to its parent, or collapses the selected group. `ctrl+j`/`ctrl+k` or `pgdn`/`pgup` scroll the diff; `esc` or `q` closes the overlay.
+- In fullscreen mode, left-click selects a visible file and loads its diff without opening the editor. Mouse wheels scroll the file list and selected diff independently; hovering does not select or open anything.
+- Opening, pressing `r`, and the background/overlay refresh cadence scan only registered roots. Worktree discovery supplies branch labels, never registration. No changes in registered roots means no widget and an informational notice instead of an overlay.
+- While the overlay is open, git is polled every 2 seconds, so edits made from nvim, another agent, or a checkout show up in place. Expansion and selection stick to the raw worktree root and file path across refreshes; a diff reloads when its counts move.
+- `GENTLE_PI_SHELL_CHANGES_KEY` rebinds the shortcut (pi key syntax, for example `ctrl+shift+g`); `off` disables it. On macOS, `alt+g` needs the terminal to send Option as Meta.
+- On a file row, `o` (or `enter`) opens the selected file in `$VISUAL` or `$EDITOR`, with the selected worktree as the editor's working directory, and returns to pi when the editor exits. Diff lookup and caches are also scoped to that root; identical relative filenames in other worktrees cannot share a diff.
+- Untracked files are diffed against an empty file so new files show their full content.
+
+Subscription usage shows in the bar after the cost, and `/gentle:usage` opens a panel with every window per provider:
+
+```text
+✿ gentle-pi ⟡ … ⟡ $9.49 sub ⟡ codex 5h ▰▰▰▰▰▱▱▱ 62% · week 31%
+```
+
+- For Codex, usage comes from the same account usage endpoint the Codex CLI reads, using the OAuth token pi already holds. It is fetched at session start, at most every 5 minutes after a turn, and on `r` in the panel. Rate-limit headers on SSE responses are picked up too.
+- For Claude Pro/Max, usage arrives in the rate-limit headers of every response, so the 5h and weekly windows appear after the first turn.
+- The bar names the subscription it shows (`codex`, `claude`) and always follows the active model. The panel puts the active provider first, marked with the petal, and says why it has no data when it does not: API-key providers have no subscription windows, Claude reports after the first response, Codex waits for a fetch.
+- Only the plan name and the windows are kept; account details in the payload are discarded.
+- Gauges turn amber at 80% and red at 95%, like the context gauge.
+
+Gentle notices are drawn as cards: the same rounded frame as the prompt, with the left rail and the title in the tone of the notice and the rest of the frame in the theme's border color.
+
+```text
+╭─ ✿ Gentle AI · review preflight ─────────────────────────────────────╮
+│ Receipt-driven development is enabled, and this worktree holds an…   │
+╰──────────────────────────────────────────────────────────────────────╯
+```
+
+- Every call into the gentle-ai binary and every `gentle_review` tool renders as a card under the rose, `🌹︎ Gentle AI`: the rail is amber while it runs, green when it finished, red when it failed; the expand key sits in the top rule once the tool finished, and the collapsed result shows only its line count. Reviewer captures name their lens (`review capture · risk`; the group lists all four).
+- The review preflight reminder renders as a card in the transcript with the expand key in its top rule.
+- An active dev-binary override shows above the editor at startup, in amber, naming the binary and its digest, and leaves with the first prompt; an invalid override shows in red with the reason.
+- Subagents draw their own card; see Gentle Agents below.
+
+### Gentle Agents
+
+The current package requires Pi 0.85.1 or newer (development tests pin 0.85.1). Use the latest Pi release; gentle-pi does not update your installed Pi automatically. Children, including any `GENTLE_PI_AGENTS_PI` override, must emit `agent_settled`: `agent_end` records a run's output but is not completion because retries or queued continuations may follow.
+
+The `subagent_*` tools and the agents card replace the third-party subagents package (remove `npm:pi-subagents-j0k3r` from your pi packages; while it is still installed the tools stay unregistered and a warning says so at startup). Agent definitions and settings are the ones you already have: markdown agents in `~/.pi/agent/agents/`, `~/.pi/agent/subagents/`, `<cwd>/.pi/agents/`, `<cwd>/.pi/subagents/` (project beats global, `subagents/` beats `agents/`), and `subagents.json` at the global and project level (`default_model`, `default_effort`, `default_mode`, `model_profiles`, `stall_timeout_ms`, `max_concurrency`, `history_max_tasks`).
+
+Agent paths follow `GENTLE_PI_AGENT_HOME`, then `PI_CODING_AGENT_DIR`, then `~/.pi/agent` for definitions, config, history, child sessions, and transcripts. These overrides select the agent profile; they do not sandbox project or shared global resources.
+
+```text
+╭─ ❀ Agents · 1 active · 1 done ─────────────────────────────── 1m24s ╮
+│ ✓  sdd-explore  map footer data sources    gpt-5.6-terra · 34k · $0.27 · 25s │
+│ ◐  sdd-apply    write gentle-shell footer  gpt-5.6-terra · 12k · $0.09 · 41s │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+Every subagent is its own `pi --mode rpc` child process, so the terminal never runs subagent work: the host reads JSON lines, applies each one as a small delta to a bounded per-task thread, and notifies only the listeners of that task. A task-mode child's question (`ctx.ui.select`, `confirm`, `input`, `editor`) reaches you as an ordinary pi dialog; a background child's question is dismissed. Subagents have no automatic total execution timeout: a long-running child remains live while it continues emitting RPC events. A silent child still times out through the configurable `stall_timeout_ms` watchdog (default four minutes). Closing pi stops the children that are still running.
+
+- `subagent_list_agents`, `subagent_run` (`agent`, `task`, `label?`, `context?`, `workspace_root?`, `mode?` task or background), `subagent_status`, `subagent_result`, `subagent_list_tasks`, `subagent_reply` (one current-session reply to a live child query), `subagent_cancel`, `subagent_send_message` (steer a running child), `subagent_continue` (resume a finished task in its own session).
+- `subagent_run.workspace_root` selects an existing worktree in the session's Git clone. Validation happens before queueing; the child runs at that canonical root. Successful OS spawn registers the root in the originating parent session, including delayed queued launches, even without an active shell listener. Failed spawns do not register. `subagent_continue` retains the previous task's cwd; status and task details expose it.
+- A background task's result comes back to the model as a `gentle-agents.result` message, drawn as a rose card, and starts a new turn when the agent is idle; the model never polls.
+- A configured child can call `subagent_parent_message` with bounded, well-formed Unicode text. Notifications retain their existing admission semantics. A `kind: "query"` waits for one strictly correlated `subagent_reply` for at most 30 seconds; each child has at most four pending queries, and disconnect, timeout, stop, and send failure settle each request once. The current parent session alone can reply. The first admitted task-mode query ends the original tool response while its child keeps running; its eventual non-cancelled completion returns once as a follow-up only if that same session is still active. Channel closure prevents later sends and automatic retry is not provided. Peer transport, offline delivery, retries, and broadcasts are unsupported.
+- The card shows the active session's tasks only: after `/new` or `/resume` the earlier session's tasks leave it and come back with their session. Finished rows stay for one minute (three at most), and the card spends at most a quarter of the terminal (three to eight rows) on tasks; beyond that the rest fold into one `… N more · alt+a to view` line so the editor never leaves the screen. Questions and running work keep their rows first.
+- `/gentle:agents` or `alt+a` opens a full-terminal overlay. At 60+ columns, the split view shows groups/tasks beside the retained semantic thread; uppercase `F` or **Fullscreen** expands that thread. At 12–59 columns, click a current subagent directly to inspect its thread; in All sessions, first select its orchestrator. `Enter`/`Tab` also enter a narrow selection. **Back** or `Escape` returns one level, closing only at the root; **Close** or `q` closes globally without cancelling children. Selection and manual thread scrolling survive Back and resize.
+- Mouse controls take priority over keyboard hints: **Follow** (`f`), **Open session** (`o`), **Stop** (`s`, legacy `c`, owned active tasks only), and **Scope** (`a`). A compact footer's `>` cycles through actions. Scope switches between this session's direct active children and all open orchestrators, including idle ones. Open writes a markdown transcript for `$EDITOR`, not a resumed child session. `j`/`k` move through lists or scroll an expanded thread; `ctrl+j`/`ctrl+k` and Page Down/Up page the thread. In Pi fullscreen mode, the wheel scrolls the viewport under the pointer; regular terminal mode does not capture mouse input. Below 12 columns or three rows, only a bounded Close cell remains; zero-sized terminals render nothing.
+- The thread displays all retained Text, Thinking, Note, and Tool content without an additional presentation cap; existing store limits and truncation markers still apply. Only the selected task is subscribed while the overlay is open.
+- Thread entries are presented as labeled Text, Thinking, Note, or Tool blocks; tool blocks show their status and nonempty output.
+- Current scope has no orchestrator wrapper and excludes every terminal task. All sessions discovers open Pi instances sharing the same agent profile, even across repositories; it does not infer open sessions from retained tasks. Directory headings support left/right and mouse expansion, and cannot stop or open a task. Peer children and their retained threads are read-only: no local stop, editor-open, or continuation routing, and no import into the local task store.
+- Presence refresh is paged while the overlay is open. Graceful shutdown withdraws an instance; after abrupt closure its last heartbeat may remain visible for up to 15 seconds plus the time to complete the next directory refresh. A recent heartbeat is a heuristic, not proof that a process is alive. Same-profile, same-user processes share retained activity text; this is not an authorization channel.
+- `alt+s` confirms stopping the current active or queued subagents owned by the current process. `GENTLE_PI_AGENTS_STOP_KEY` rebinds it; `off` disables it.
+- Finished tasks are written to `~/.pi/agent/gentle-agents/tasks/` (one JSON per task, newest `history_max_tasks` kept, default 200) and come back on demand for `subagent_result` and `subagent_continue`, never as overlay history. Child sessions live under `~/.pi/agent/gentle-agents/sessions/`.
+- `ctrl+shift+a` collapses the card to its first row (`GENTLE_PI_AGENTS_KEY`), `GENTLE_PI_AGENTS_VIEW_KEY` rebinds the overlay, `GENTLE_PI_AGENTS_PI` overrides the pi command used for children, and `GENTLE_PI_AGENTS=0` disables the tools and the card.
+
+### Gentle Todo
+
+The `todo` tool and its card replace the third-party todo extension (remove `npm:@juicesharp/rpiv-todo` from your pi packages; sessions written by it replay into the new card).
+
+```text
+╭─ ❀ Todos · 1 of 3 ──────────────────────────────────────╮
+│ ✓ Add quiet tool rendering                              │
+│ ◐ Fix quiet tools conflict · fixing conflict            │
+│ ○ Show git bash tails                                   │
+╰─────────────────────────────────────────────────────────╯
+```
+
+Three things keep the list current, which a static tool description cannot:
+
+- `write` replaces the whole list in one call, so the model rewrites the plan instead of patching it; `add`, `update`, `clear`, and `list` remain for single moves.
+- Every turn's system prompt carries the open tasks and the rules: in_progress before starting, done right after finishing, update before ending the turn.
+- A list that goes two turns untouched while tasks stay open turns amber with `stale · N turns`, and the prompt says so, so the model brings it up to date.
+
+A finished list stays on screen for the turn it finished in and clears at the next. `ctrl+shift+t` collapses the card to the task in progress (`GENTLE_PI_TODO_KEY` rebinds it, `off` disables it); `GENTLE_PI_TODO=0` disables the tool and the card.
+
+Set `GENTLE_PI_SHELL=0` to keep pi's built-in footer and editor.
+