docs: Phase 36 README + docs/wiki refresh

README.md

@@ -111,3 +111,5 @@ Non-loopback model endpoints are rejected unless `allowNonLoopback` is explicitl
 ## License
 
 MIT - see [LICENSE](LICENSE)
+
+<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

docs/wiki/Architecture.md

@@ -0,0 +1,53 @@
+# Architecture
+
+## Governance / blackboard flow
+
+`universal-refiner` (the active MCP server) intercepts a raw prompt from an AI CLI, runs it
+through context and refinement, and — via `AgenticBlackboard` (`src/core/blackboard.ts`) —
+publishes and reads shared state so concurrent agent sessions can coordinate rather than act
+on disjoint local knowledge.
+
+```mermaid
+flowchart LR
+    CLI["AI CLI\n(Claude / Cursor / Gemini)"] -->|"stdio"| PI["PromptImprover\n(universal-refiner)"]
+    subgraph Engine["Governance & Refinement Engine"]
+        Scout["Context Scout\nlanguage/framework detectors"]
+        RAG["RAG Snippets\nFlexSearch retrieval"]
+        Memory[("SQLite Memory\nLocalBrain")]
+        Semantic["Local Semantic Model\ngemma3:12b / 1b"]
+    end
+    subgraph BB["AgenticBlackboard (blackboard.json)"]
+        Intents["Active agent intents\n(agentName, toolType, expiresAt)"]
+        Logs["System logs\n(per-project)"]
+        LastRefine["Last refinement record\n(gain metric)"]
+    end
+    PI --> Scout --> RAG --> Memory --> Semantic --> PI
+    PI -->|"publish intent"| BB
+    BB -->|"read concurrent intents"| PI
+    PI --> Out["Augmented Prompt"]
+    Out -.->|"event store"| Memory
+```
+
+<!-- codex:generate-image prompt="A shared glowing chalkboard in the center of a room, with several small agent robots (labeled Claude, Cursor, Gemini) posting colored intent cards onto it and reading each other's cards before acting; one robot writes a refined prompt scroll that flows out to a waiting execution robot; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
+
+## Component breakdown
+
+- **Context Scout** — startup detectors identify language, framework, and architectural
+  signals so refinement is tailored to the current codebase (`src/detectors/project-scout.ts`).
+- **RAG Snippets** — FlexSearch-based retrieval over the local codebase injects relevant
+  examples into the refined prompt.
+- **AgenticBlackboard** — a JSON-file-backed shared store (`.refiner/blackboard.json`,
+  project-scoped, with a global fallback under `~/.refiner`) recording active agent intents
+  (`agentName`, `toolType`, `intent`, `expiresAt`), system logs, and the last refinement's
+  gain metric. A serialized write queue (`writeQueue`) and listener registry prevent
+  concurrent-write corruption when multiple CLI sessions touch the same project.
+- **LocalBrain (SQLite)** — persistent storage for reusable refinement rules, learned
+  patterns, and prompt history.
+- **Local Semantic Model** — an optional OpenAI-compatible local endpoint (`gemma3:12b`,
+  falling back to `gemma3:1b`) that produces the final refined prompt; rule-based refinement
+  continues if neither the local model nor MCP sampling is available.
+- **Governance gate** — generated lessons and templates remain pending until reviewed through
+  the MCP learning-review tools (see the root README's Local Semantic Model section) — the
+  blackboard records the intent and history that gate reviews against.
+
+<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

docs/wiki/Decisions.md

@@ -0,0 +1,27 @@
+# Decisions
+
+## ADR convention
+
+`docs/adr/README.md` establishes the convention (sequential numbering, Context/Decision/
+Consequences) but **no numbered ADR files exist in the repo yet**. Decisions to date live in
+`.planning/phases/` and the `docs/` architecture specs instead.
+
+## Phase history (`.planning/phases/`, this repo's own GSD project)
+
+| Phase | Topic |
+|---|---|
+| 01 | FS watcher |
+
+See [`docs/promptimprover-autogen-architecture-spec.md`](../promptimprover-autogen-architecture-spec.md),
+[`docs/enterprise-release-gates.md`](../enterprise-release-gates.md), and
+[`docs/operator-testing.md`](../operator-testing.md) for the broader design record beyond the
+single formal phase.
+
+## Open decisions tracked in this Phase 36 refresh
+
+- **PR #27** (`fix/dashboard-loopback-xss`) — bind dashboard to loopback and escape HTML in
+  trace rendering; open, not yet merged.
+- **PR #28** (`ci/sha-pin-and-least-privilege`) — pins third-party GitHub Actions to commit
+  SHAs and least-privilege permissions; open, not yet merged.
+
+<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

docs/wiki/Home.md

@@ -0,0 +1,32 @@
+# PromptImprover Wiki
+
+## Role in the CAS portfolio
+
+`Promptimprover` is part of the **Governance plane** of the Coding-Autopilot-System
+three-plane model (Control / Execution / Governance). It is an MCP-first prompt governance
+layer: it sits between an AI CLI and execution tools, adds repo-aware context, applies
+refinement rules, and — via its `AgenticBlackboard` — coordinates intent and history across
+concurrent agent sessions rather than treating each prompt as disposable chat.
+
+| Plane | This repo's responsibility |
+|---|---|
+| Control | *(not this repo — see `gsd-orchestrator`)* |
+| Execution | *(not this repo — see `autogen`)* |
+| Governance | Prompt refinement, cross-agent blackboard coordination, learning-review workflow |
+
+## Quickstart
+
+- [README.md](../../README.md) — Quickstart, Local Semantic Model, Proof Points
+- [Architecture](./Architecture.md) — governance/blackboard flow
+- [Operations](./Operations.md) — verified install/build/test/release-gate commands
+- [Decisions](./Decisions.md) — phase history and ADR convention
+
+## Ecosystem links
+
+Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) org:
+[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) (control plane) ·
+[autogen](https://github.com/Coding-Autopilot-System/autogen) (execution plane) ·
+[cas-contracts](https://github.com/Coding-Autopilot-System/cas-contracts) (shared schemas) ·
+[cas-evals](https://github.com/Coding-Autopilot-System/cas-evals) (evidence gate)
+
+<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->

docs/wiki/Operations.md

@@ -0,0 +1,65 @@
+# Operations
+
+## Setup
+
+```powershell
+git clone https://github.com/Coding-Autopilot-System/Promptimprover.git
+cd Promptimprover
+.\build_and_install.ps1
+```
+
+Linux/macOS:
+
+```sh
+git clone https://github.com/Coding-Autopilot-System/Promptimprover.git
+cd Promptimprover
+./build_and_install.sh
+```
+
+Both installers run a deterministic dependency install, run the full test suite, build the
+package, install it globally, and verify the `universal-refiner` command.
+
+## Build and test (`universal-refiner/`)
+
+```bash
+npm ci
+npm run build
+npm run test:coverage
+```
+
+## Full local release gate
+
+```powershell
+cd C:\PersonalRepo\portfolio\Promptimprover\universal-refiner
+npm.cmd run release:verify
+```
+
+`release:verify` chains build, coverage tests, acceptance suites (MCP, semantic fallback,
+tracked-turn, stdio-MCP), e2e (Playwright), stress/recovery/soak checks, security audit
+(production + full) and secret scanning, package dry-run, and packaged runtime startup smoke —
+per `universal-refiner/package.json`.
+
+## CI (`.github/workflows/ci.yml`, `ubuntu-latest`, working directory `universal-refiner/`)
+
+**`build-and-test`** job (15-minute timeout):
+1. `actions/checkout@v7`
+2. `actions/setup-node@v6` (Node 22)
+3. `npm ci --no-fund`
+4. `npm rebuild better-sqlite3` (native module rebuild)
+5. `npm run build`
+6. `npm run test:coverage`
+
+**`acceptance`** job (15-minute timeout, matrix `model-order: [primary, reversed]`):
+1. Same checkout/setup/install/rebuild/build steps as above
+2. Acceptance suite run against each model-order permutation
+
+A separate `.github/workflows/codeql.yml` runs CodeQL analysis (badge in the root `README.md`).
+
+## Global MCP registration doctor
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\register-global.ps1 -Check
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\register-global.ps1 -Apply
+```
+
+<!-- docs-verified: 101f63d702e5c0ab8052c8e0c67a104d8edfbddb 2026-07-08 -->