feat(pi): ctx setup pi - Pi coding-agent CLI integration

.context/LEARNINGS.md

@@ -15,6 +15,26 @@ DO NOT UPDATE FOR:
 -->
 
 
+## [2026-08-23-204632] Windows git over HTTPS fails with SEC_E_NO_CREDENTIALS unless the openssl backend is pinned
+
+**Context**: During the pi integration, every `git fetch`/`ls-remote` over an https remote on this Windows machine failed with `schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS (0x8009030e)` - git's default TLS (schannel) has no usable credential state here. `gh` (own TLS stack) worked fine, and SSH keys were rejected, so the failure looked like a credentials/remote problem.
+
+**Lesson**: git's schannel backend and the Windows credential manager can be broken independently of the remote; the fix is a per-invocation backend override, not key/credential surgery.
+
+**Application**: On this machine, run every git https remote operation as `git -c http.sslBackend=openssl <cmd>` (git 2.51 supports it). Diagnose with `gh api` first to rule out remote-side auth before touching keys.
+
+---
+
+## [2026-08-23-204632] zensical site rebuilds are non-reproducible off the canonical toolchain (entity-escape drift)
+
+**Context**: Rebuilding site/ locally with the pinned zensical 0.0.51 (fresh venv, Python 3.10) produced 120 files of pure escape drift (`&#39;` vs literal `'` inside highlighted code blocks) against the committed artifacts; pinning pygments older did not help.
+
+**Lesson**: The zensical pin only pins the generator, not its transitive deps (markdown/pygments/jinja resolution drifts), so committed site/ output is not reproducible on arbitrary machines; the drift is user-invisible (entities render identically) but is pure diff churn that flips back on the next canonical build.
+
+**Application**: After a local `zensical build`, run `git diff --ignore-cr-at-eol --numstat site/` and inspect representative hunks BEFORE committing; if the delta is escape drift rather than real content, revert site/ (`git checkout -- site/`, remove new untracked pages) and defer the rebuild to the canonical build machine; record the deferral in the task notes.
+
+---
+
 ## [2026-07-25-124457] Using the proprietary sibling repo as design evidence leaks its internals into tracked files
 
 **Context**: While deciding the pd-m4 add-path shape, I read the sibling repo's convention file to settle the question, then quoted its guide text and attributed the decision to it in a tracked plan file. An unrelated build warning prompted the sweep that caught it.

.context/TASKS.md

@@ -3072,3 +3072,83 @@ E5[T15–20] E6[T21–23] = 23.
 - [ ] [E5] Tests: health fixtures, heavy root + theme file, both-fire ordering, convention measure, boundary/disable, surface parity (T15–T20). Plan: specs/plans/pd-m5.md #priority:medium #session:951e1535 #branch:design/pd-m5-triggers #added:2026-07-25
 
 - [ ] [E6] Sync + gates: copilot skill sync, measurement gate (T22), milestone gate (T21–T23). Plan: specs/plans/pd-m5.md #priority:medium #session:951e1535 #branch:design/pd-m5-triggers #added:2026-07-25
+
+## Phase PI — Pi CLI Integration
+
+Spec: `specs/pi-cli-integration.md`
+Branch: `feat/pi-cli-integration` (based on upstream main ce5a8328, 2026-08-23)
+
+Pi (earendil-works/pi, pi.dev) is a self-extensible coding-agent CLI with a
+TypeScript extension system, Agent Skills support, native AGENTS.md, and — by
+design — no MCP. Integration follows the OpenCode blueprint: Go setup package +
+embedded TS shim + bundled skills + shared AGENTS.md template.
+
+- [ ] Read `specs/pi-cli-integration.md` before starting any PI task.
+  #added:2026-08-23-151000
+- [x] PI.1: Embedded assets — `internal/assets/integrations/pi/extension/ctx.ts`
+  (thin shim: before_agent_start branch-scan packet injection,
+  session_start warm-up cache, session_compact cache drop, tool_result
+  post-commit / check-task-completion with isError gating, agent_settled
+  check-persistence; hook-JSON envelope on piped stdin) and
+  `internal/assets/integrations/pi/skills/` (same 10-skill set as
+  OpenCode; embed.go directives added) #added:2026-08-23-151000
+  #completed:2026-08-23
+- [x] PI.2: Accessors + constants — `internal/assets/read/agent/pi.go`
+  (PiExtension, PiSkills) and `internal/config/hook` pi path constants
+  (+ asset.go DirIntegrationsPi*) #added:2026-08-23-151000
+  #completed:2026-08-23
+- [x] PI.3: `internal/cli/setup/core/pi/` package — pi.go, extension.go,
+  skill.go, validate.go + deploy_test.go/testmain_test.go modeled on the
+  opencode suite (all 4 tests green) #added:2026-08-23-151000
+  #completed:2026-08-23
+- [x] PI.4: CLI wiring — `case cfgHook.ToolPi` branch in setup root.Run()
+  (run.go + doc.go); supporting text: hooks.yaml hook.pi + supported-tools line,
+  write.yaml write.hook-pi-*, config/embed/text DescKeys, write/setup InfoPi*
+  (TestDescKeyYAMLLinkage green; no new Use* constant, no new subcommand)
+  #added:2026-08-23-151000 #completed:2026-08-23
+- [x] PI.5: Docs — pi entry in supported-tools reference (integrations.md +
+  setup.md + multi-tool-setup.md) + pi quickstart guide (docs/home/pi.md +
+  zensical nav). NOTE: site/ HTML rebuild deferred — this machine's zensical
+  0.0.51 venv renders entity-escape drift (120 files, ' vs ') vs the
+  committed artifacts (unpinned zensical transitive deps); rebuild on the
+  canonical build machine and stage site/ with a follow-up commit
+  #added:2026-08-23-151000 #completed:2026-08-23
+- [x] PI.6: Validation — go build ./... + golangci-lint (0 issues) + targeted
+  go test green; full-suite delta vs clean main verified: zero new failures
+  (20 failing packages, all pre-existing Windows-environment: CRLF render
+  drift, .exe exec, audit path exemptions). Scratch project: init +
+  dry-run + --write + idempotent re-run + tamper-refresh (byte-identical to
+  embedded) + unknown-tool list all verified with a freshly built binary.
+  Live pi: extension loads clean (A/B run with/without .pi identical);
+  full LLM round-trip blocked by local pi provider config (gx10-spark/*
+  unreachable from this environment) — left for a working-provider machine
+  #added:2026-08-23-151000 #completed:2026-08-23
+- [x] PI.7: CI type-check for the pi extension — tools/typecheck/pi/
+  (tsconfig + package.json + lockfile with @earendil-works/pi-coding-agent
+  0.84.2 types, tsc --noEmit PASSING locally) + typecheck-pi-extension job in
+  .github/workflows/ci.yml (mirrors tools/typecheck/opencode/). Decisions
+  locked 2026-08-23: display:true, CI typecheck in scope
+  #added:2026-08-23-151000 #completed:2026-08-23
+- [ ] Bug (review finding, pre-existing): OpenCode plugin lifecycle legs lack
+  the hook-JSON stdin envelope — `ctx system post-commit` from
+  internal/assets/integrations/opencode/plugin/index.ts bails silently in
+  FullPreamble (no envelope fed via BunShell), so the post-commit nudge is
+  likely dead; check-task-completion/check-persistence run but key per-session
+  state to IDUnknown. Spec: specs/pi-cli-integration.md "Hook envelope
+  requirement" section documents the correct envelope shape; fix the opencode
+  plugin the same way (or add envelope flags on the Go side) #priority:medium
+  #added:2026-08-23-151000
+- [ ] PI.8 (audit follow-ups, non-blocking): from the fable-5 effort-max
+  branch audit (2026-08-23, verdict ship-ready after MAJOR 1, which is
+  fixed on-branch): (a) post-compaction re-warm runs `ctx agent` inline on
+  the prompt path (up to 15s) — consider re-warming inside the
+  session_compact handler instead; (b) embedded assets are not EOL-pinned
+  (no .gitattributes; Windows builds embed CRLF skills vs LF on CI —
+  cross-binary refresh flapping; add `internal/assets/** text eol=lf`
+  pin, repo-wide pre-existing hazard); (c) hook nudge stdout is discarded —
+  Pi's tool_result handlers can return {content} to append the nudge to the
+  tool result and reach the LLM (OpenCode parity chose .quiet(); design
+  decision, not a bug); (d) tools/typecheck/pi/tsconfig.json could mirror
+  the opencode twin's explicit `paths` mapping for @earendil-works/pi-coding-agent
+  (resolution works today via node_modules probing; hardening only)
+  #priority:low #added:2026-08-23-221600

.github/workflows/ci.yml

@@ -89,6 +89,28 @@ jobs:
         working-directory: tools/typecheck/opencode
         run: npx tsc --noEmit
 
+  typecheck-pi-extension:
+    name: Typecheck Pi extension
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: tools/typecheck/pi/package-lock.json
+
+      - name: Install dependencies
+        working-directory: tools/typecheck/pi
+        run: npm ci
+
+      - name: Type-check embedded extension
+        working-directory: tools/typecheck/pi
+        run: npx tsc --noEmit
+
   vscode-extension:
     name: VS Code extension build + typecheck
     runs-on: ubuntu-latest

.gitignore

@@ -86,6 +86,7 @@ editors/vscode/*.vsix
 
 # Type-check tooling for embedded plugins
 tools/typecheck/opencode/node_modules/
+tools/typecheck/pi/node_modules/
 
 # Some ideas are best kept hidden.
 ideas

docs/cli/setup.md

@@ -36,6 +36,7 @@ ctx setup <tool> [flags]
 | `aider`       | Aider CLI                                    |
 | `copilot`     | GitHub Copilot                               |
 | `opencode`    | OpenCode (terminal-first AI coding agent)    |
+| `pi`          | Pi coding-agent CLI (pi.dev)                 |
 | `windsurf`    | Windsurf IDE                                 |
 
 !!! note "Claude Code Uses the Plugin System"
@@ -59,4 +60,7 @@ ctx setup cline --write
 
 # Generate OpenCode plugin, skills, AGENTS.md, and global MCP config
 ctx setup opencode --write
+
+# Generate Pi extension, skills, and AGENTS.md
+ctx setup pi --write
 ```

docs/home/pi.md

@@ -0,0 +1,156 @@
+---
+#   /    ctx:                         https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+title: "ctx for Pi"
+icon: lucide/terminal
+---
+
+![ctx](../images/ctx-banner.png)
+
+## The Problem
+
+Every Pi session starts from zero. You re-explain your architecture,
+the agent repeats mistakes it made yesterday, and decisions get
+rediscovered instead of remembered.
+
+**Without `ctx`:**
+
+```
+> "Add the validation middleware we discussed"
+
+I don't have context about previous discussions. Could you describe
+what validation middleware you're referring to?
+```
+
+**With `ctx`:**
+
+```
+> "Add the validation middleware we discussed"
+
+Yes. From the Jan 15 session. You decided on Zod schemas at the
+route level (DECISIONS.md #12), and the pattern is in
+CONVENTIONS.md. I'll follow the existing middleware in
+src/middleware/auth.ts as a reference.
+```
+
+That's the whole pitch: **your AI remembers**.
+
+## Setup (One Command)
+
+Install the `ctx` binary first ([installation docs](getting-started.md#installation)),
+then run from your project root:
+
+```bash
+ctx setup pi --write && ctx init
+```
+
+This does two things:
+
+1. **`ctx setup pi --write`**: generates the project-local Pi
+   extension, skills, and `AGENTS.md`.
+2. **`ctx init`**: creates the `.context/` directory with template
+   files.
+
+### What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `.pi/extensions/ctx.ts` | Lifecycle extension (hooks into `ctx system` commands) |
+| `AGENTS.md` | Agent instructions (Pi reads this natively) |
+| `.pi/skills/ctx-*/SKILL.md` | `ctx` skills, available as `/skill:ctx-*` commands |
+
+The extension is a single file with no runtime dependencies; no
+`npm install` needed. Pi loads it automatically on launch.
+
+> **Trust note:** Pi loads project-local `.pi/` files only after the
+> project is trusted. The first `pi` launch in a new project prompts
+> for trust; answer yes for the integration to activate.
+
+> **Launch from the project root:** the extension resolves `.context/`
+> relative to Pi's working directory, so start `pi` from the project
+> root for the agent-side `ctx` commands to resolve.
+
+## What Happens Automatically
+
+The extension wires Pi lifecycle events to `ctx`. You don't need to
+do anything; it just works.
+
+| Event | What fires | What it does |
+|-------|-----------|--------------|
+| Session start | `session_start` | Warms the ctx agent packet off the prompt path |
+| First prompt / after compaction | `before_agent_start` | Injects the packet as a persistent message when no ctx-injected message exists after the most recent compaction |
+| After `git commit` | `tool_result` (bash) | Runs `ctx system post-commit` to capture context state (failed commits are ignored) |
+| After file edit | `tool_result` (edit/write) | Runs `ctx system check-task-completion` to detect silent task completions |
+| Agent settled | `agent_settled` | Runs `ctx system check-persistence` |
+
+The compaction behavior matters most. When Pi compresses your context
+window (`/compact` or auto-compaction), the injected packet ages past
+the kept window and is folded into the lossy summary. The extension
+re-injects a fresh packet on the next prompt so the agent keeps
+breadcrumbs back to your `.context/` directory and its file inventory.
+
+Pi intentionally has no built-in MCP, so there is no MCP server to
+register; the extension is the lifecycle channel.
+
+### What Is *Not* Included
+
+Dangerous-command blocking is Claude Code-specific and is not part of
+the Pi integration.
+
+## Skills
+
+The bundled skills are available as `/skill:*` commands:
+
+| Command | When to use |
+|---------|-------------|
+| `/skill:ctx-remember` | "Do you remember?"; reads tasks, decisions, learnings, and recent journal entries. Returns a structured readback. |
+| `/skill:ctx-status` | Context summary at a glance: file count, token estimate, recent activity. |
+| `/skill:ctx-wrap-up` | End-of-session ceremony. Captures learnings, decisions, conventions, and outstanding tasks to `.context/` files. |
+| `/skill:ctx-agent` | Load full context packet on demand |
+
+The KB editorial pipeline ships too: `/skill:ctx-kb-ingest`,
+`/skill:ctx-kb-ask`, `/skill:ctx-kb-note`, `/skill:ctx-kb-ground`,
+`/skill:ctx-kb-site-review`.
+
+You don't need to use these often. The extension handles most context
+loading automatically. These are for when you want explicit control.
+
+## Refreshing the Integration
+
+If you re-run `ctx setup pi --write` (e.g., after updating `ctx`), the
+extension and skills are refreshed in place. Pi auto-discovered
+extensions can be hot-reloaded with `/reload`; a restart always works.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Extension installed but nothing fires | Project not trusted | Trust the project when prompted; check `defaultProjectTrust` in Pi settings |
+| `ctx` commands resolve to the wrong project | Pi launched outside the project root | Launch `pi` from the project root |
+| Extension not loading at all | Wrong location | Verify the extension is at `.pi/extensions/ctx.ts` (flat top-level file) |
+
+## Verify It Works
+
+Start a new Pi session and ask:
+
+```
+Do you remember?
+```
+
+The agent should cite specific context: current tasks, recent
+decisions, or previous session topics. If it says "I don't have
+memory" or "Let me check," something went wrong; check that the
+extension installed correctly and `.context/` has files in it.
+
+## What's Next
+
+- [Your First Session](first-session.md): step-by-step walkthrough
+  from `ctx init` to verified recall.
+- [Common Workflows](common-workflows.md): day-to-day commands for
+  tracking context, checking health, and browsing history.
+- [Context Files](context-files.md): what lives in `.context/` and
+  how each file is used.

docs/operations/integrations.md

@@ -605,6 +605,55 @@ ctx status
 
 ---
 
+## Pi
+
+Pi (earendil-works/pi, pi.dev) is a self-extensible coding-agent CLI.
+By design it has no built-in MCP, so `ctx` integrates via a thin
+TypeScript extension, Agent-Skills-standard skills, and `AGENTS.md`
+instructions. All logic stays in the `ctx` binary via `ctx system`
+subcommands.
+
+### Setup
+
+```bash
+# Generate Pi extension, skills, and AGENTS.md
+ctx setup pi --write
+
+# Initialize context
+ctx init
+```
+
+### What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `.pi/extensions/ctx.ts` | Lifecycle extension (hooks to `ctx system`) |
+| `AGENTS.md` | Agent instructions (read natively) |
+| `.pi/skills/ctx-*/SKILL.md` | `ctx` skills (invoke as `/skill:ctx-*`) |
+
+Project-local `.pi/` files load only after the project is trusted;
+the first `pi` launch in a new project prompts for trust.
+
+### How It Works
+
+The extension wires Pi lifecycle events to `ctx system`:
+
+- **`session_start`**: warms the ctx agent packet off the prompt path.
+- **`before_agent_start`**: injects the packet as a persistent message
+  when no ctx-injected message exists after the most recent compaction
+  (fresh sessions inject on the first turn; re-injection after
+  compaction is a breadcrumb into `.context/`).
+- **`tool_result` (bash, on `git commit`, not `isError`)**: runs
+  `ctx system post-commit`.
+- **`tool_result` (edit/write, not `isError`)**: runs
+  `ctx system check-task-completion`.
+- **`agent_settled`**: runs `ctx system check-persistence`.
+
+The extension is a single file with no runtime dependencies; no
+`npm install` needed. Pi loads it automatically on launch.
+
+---
+
 ## Windsurf IDE
 
 Windsurf supports custom instructions and file-based context.