docs: sharpen portfolio proof

Author: Aitomates

README.md

@@ -1,4 +1,4 @@
-# Promptimprover
+# PromptImprover
 
 [![CI](https://github.com/Coding-Autopilot-System/Promptimprover/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Coding-Autopilot-System/Promptimprover/actions/workflows/ci.yml)
 [![Node 22](https://img.shields.io/badge/node-22-brightgreen)](https://nodejs.org/)
@@ -7,21 +7,43 @@
 Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) ecosystem:
 [gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) | [autogen](https://github.com/Coding-Autopilot-System/autogen)
 
-Promptimprover is an MCP server middleware that intercepts and refines every AI prompt before code generation — applying project context, coding standards, and compounding memory.
+PromptImprover is an MCP-first prompt governance layer for engineering workflows. It sits between an AI client and execution tools, adds repo-aware context, applies prompt refinement rules, and records evidence that can be used to improve future runs.
+
+This repository is strongest as a portfolio demonstration of three ideas:
+
+- prompt governance before code execution
+- MCP-based integration instead of editor-specific glue
+- evidence-backed refinement using history, tests, and repo context
+
+## What It Demonstrates
+
+- **MCP integration**: the active implementation is the `universal-refiner` package, a TypeScript MCP server for cross-CLI prompt refinement
+- **Governance pipeline**: prompts can be captured, classified, refined, and linked to execution outcomes instead of being treated as disposable chat
+- **Repo-aware context**: detectors, memory, and retrieval components adapt refinement to the current codebase
+- **Proof-oriented design**: tests and architecture docs emphasize traceability, learning, and operational visibility rather than prompt rewriting alone
 
 ## Features
 
-- **RAG neural snippets** — FlexSearch-based retrieval over the local codebase; injects relevant code examples into every prompt
-- **Compounding memory** — SQLite-backed pattern store accumulates project-specific rules and standards learned over time
-- **Auto-heal middleware** — background file watcher triggers commit ingestion and lesson extraction; keeps context current without manual intervention
-- **Context-aware project scouting** — NodeDetector, PythonDetector, and ArchitecturalScout identify tech stack and patterns at startup
+- **RAG snippets**: FlexSearch-based retrieval over the local codebase to inject relevant examples into prompt refinement
+- **Persistent memory**: SQLite-backed storage for reusable rules, learned patterns, and prompt history
+- **Context scouting**: detectors identify language, framework, and architectural signals at startup
+- **Operational traceability**: history, timelines, and prompt-to-outcome correlation are first-class design goals
+
+## Current Scope vs. Roadmap
 
-## Architecture
+The repo contains both implemented components and forward-looking architecture.
+
+- **Implemented now**: the `universal-refiner` MCP server, Gemini-oriented packaging, tests, and install/build scripts
+- **Designed for later expansion**: broader routing, portal, and evidence workflows described in the architecture spec
+
+That distinction matters because this repo is about credible system direction, not vague AI middleware claims.
+
+## Architecture Snapshot
 
 ```mermaid
 flowchart LR
-    CLI["AI CLI\n(Claude / Cursor)"] -->|"stdio"| PI["Promptimprover\n(prompt-refiner)"]
-    subgraph internal["Promptimprover Engine"]
+    CLI["AI CLI\n(Claude / Cursor)"] -->|"stdio"| PI["PromptImprover\n(prompt-refiner)"]
+    subgraph internal["PromptImprover Engine"]
         RAG["RAG Snippets\n(FlexSearch)"]
         Memory["SQLite Memory\n(LocalBrain)"]
         AutoHeal["Auto-Heal\n(BackgroundService)"]
@@ -32,6 +54,13 @@ flowchart LR
     internal --> Out["Augmented Prompt"]
 ```
 
+## Proof Points
+
+- [Portfolio proof notes](./docs/portfolio-proof.md)
+- [Architecture spec](./docs/promptimprover-autogen-architecture-spec.md)
+- [`universal-refiner/package.json`](./universal-refiner/package.json)
+- [`universal-refiner/tests`](./universal-refiner/tests)
+
 ## Quickstart
 
 ```powershell
@@ -44,4 +73,4 @@ Add `prompt-refiner` to your MCP client configuration. See the [Setup Guide](htt
 
 ## License
 
-MIT — see [LICENSE](LICENSE)
+MIT - see [LICENSE](LICENSE)

docs/portfolio-proof.md

@@ -0,0 +1,19 @@
+# Portfolio Proof Notes
+
+This repo is best read as an enterprise-oriented MCP and prompt-governance prototype, not as a generic prompt helper.
+
+## Present-State Evidence
+
+- `universal-refiner/package.json` defines the active package as `gemini-prompt-refiner` and describes it as cross-CLI prompt refinement using an MCP server.
+- `universal-refiner/tests/` contains targeted Vitest coverage for detectors, history, lessons, memory, snippets, predictive refinement, timeline behavior, and server behavior.
+- `build_and_install.ps1` installs the `universal-refiner` package globally as `prompt-refiner`, showing the intended operator entry point.
+
+## Governance Signal
+
+- The root `context.md` makes traceability and post-change verification explicit project mandates.
+- `universal-refiner/AGENTS.md` requires MCP-first workflow for non-trivial repo work and treats prompt activity as durable operational history.
+- The architecture spec defines prompts as governed artifacts that should be captured, classified, routed, and linked to outcomes.
+
+## Roadmap Boundary
+
+The strongest implemented proof is the MCP refinement server and its tests. Broader portal, dispatch, and evidence workflows are documented direction in [promptimprover-autogen-architecture-spec.md](./promptimprover-autogen-architecture-spec.md), not all fully realized product surface today.