pyrrhon 0.1.0__tar.gz

pyrrhon-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Database
+*.db
+
+# Docs
+/docs
+
+# Distribution / packaging
+# build/, dist/ and lib/ are anchored with a leading slash on purpose. A
+# gitignore pattern without one matches at every depth, so a bare `lib/`
+# also swallowed web/lib/utils.ts -- the shadcn `cn()` helper that most of
+# the site's components import. That builds fine locally, where the file is
+# on disk, and fails the deploy with "Can't resolve '@/lib/utils'". These
+# are Python build artifacts, and they only ever appear at the repo root.
+.Python
+/build/
+develop-eggs/
+/dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+.gstack/

pyrrhon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prabhjot Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyrrhon-0.1.0/PKG-INFO

@@ -0,0 +1,448 @@
+Metadata-Version: 2.5
+Name: pyrrhon
+Version: 0.1.0
+Summary: A voice-first senior-engineer agent for understanding and designing software.
+Project-URL: Homepage, https://github.com/prabhjot0109/Pyrrhon
+Project-URL: Source, https://github.com/prabhjot0109/Pyrrhon
+Project-URL: Issues, https://github.com/prabhjot0109/Pyrrhon/issues
+Project-URL: Changelog, https://github.com/prabhjot0109/Pyrrhon/releases
+Author: Prabhjot Singh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,code-comprehension,codebase,grounding,llm,terminal,tui,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: <3.14,>=3.12
+Requires-Dist: ddgs>=9.14.4
+Requires-Dist: google-genai>=2.10.0
+Requires-Dist: html2text>=2025.4.15
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: huggingface-hub>=1.22.0
+Requires-Dist: mcp<2,>=1.10
+Requires-Dist: openai>=2.44.0
+Requires-Dist: pipecat-ai[assemblyai,cartesia,deepgram,elevenlabs,gladia,google,groq,inworld,local,openai,rime,rnnoise,silero]>=1.7.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=14.3.1
+Requires-Dist: soundfile>=0.14.0
+Requires-Dist: textual>=8.2.8
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: tree-sitter-language-pack>=1.12.2
+Requires-Dist: tree-sitter<0.26,>=0.25.2
+Provides-Extra: kokoro
+Requires-Dist: pipecat-ai[kokoro]>=1.7.0; extra == 'kokoro'
+Provides-Extra: local-voice
+Requires-Dist: pipecat-ai[kokoro,local-smart-turn,moonshine,piper,whisper]>=1.7.0; extra == 'local-voice'
+Provides-Extra: moonshine
+Requires-Dist: pipecat-ai[moonshine]>=1.7.0; extra == 'moonshine'
+Provides-Extra: piper
+Requires-Dist: pipecat-ai[piper]>=1.7.0; extra == 'piper'
+Provides-Extra: smart-turn
+Requires-Dist: pipecat-ai[local-smart-turn]>=1.7.0; extra == 'smart-turn'
+Provides-Extra: whisper
+Requires-Dist: pipecat-ai[whisper]>=1.7.0; extra == 'whisper'
+Description-Content-Type: text/markdown
+
+# Pyrrhon
+
+**A voice-first engineering agent for your terminal.** You talk to it, it talks
+back, and every claim it makes about your code cites a real `file:line` — or it
+says it does not know. You can interrupt it mid-sentence.
+
+[![CI](https://github.com/prabhjot0109/Pyrrhon/actions/workflows/ci.yml/badge.svg)](https://github.com/prabhjot0109/Pyrrhon/actions/workflows/ci.yml)
+[![Python 3.12 | 3.13](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Named for Pyrrho the skeptic: suspend judgment, question assumptions, never
+bluff. Pyrrhon does two things.
+
+**Understand a codebase you didn't write.** Ask how a feature works, where to
+add something, or what changed last week. Every answer cites a real location or
+admits ignorance — it will not invent a path to sound complete — and the
+terminal shows the code while you talk.
+
+**Design a system you're about to build.** It interrogates the idea the way a
+senior architect would ("your data looks relational, so what do you expect
+Mongo to buy you over Postgres?"), then writes the spec once the reasoning holds
+up: `PRD.md`, `HLD.md`, `LLD.md`, `api.md`, `database.md`, `risks.md`.
+
+---
+
+## Status
+
+Pre-1.0, and honest about which parts are which.
+
+| | |
+|---|---|
+| **Built and tested** | The agent harness, the grounding gate, both channels, the voice pipeline, session persistence, plugins, MCP. ~1260 tests, no API key required. |
+| **Measured** | Latency (M10), the tool policy (a fifth of tool rounds removed), context handling under a real 8k-token ceiling. |
+| **Not yet measured** | Answer quality on a repo neither author wrote. Two stranger repos are frozen with 34 hand-derived cases in [`evals/strangers/`](evals/strangers/), waiting on a funded provider key. |
+| **Deliberately absent** | Any tool that writes outside `.pyrrhon/`. Speech-to-speech (it would bypass the grounding gate). |
+
+Pyrrhon is a *teaching* agent, not an editing one. It reads your repo and
+explains it. It does not change your code, and there is no plan for it to.
+
+## Install
+
+Python 3.12 or 3.13. Not 3.14 yet — `pyaudio`, which the voice stack pulls in,
+ships no wheel for it, and a version cap turns that into one clear sentence
+instead of a compiler error.
+
+```bash
+uv tool install pyrrhon      # recommended: isolated, with `pyrrhon` on PATH
+pipx install pyrrhon         # same idea without uv
+pip install pyrrhon          # into the current environment
+```
+
+One command installs everything, every speech provider included. Nothing in the
+provider menu needs a second install step. The cost is a ~1.2 GB environment,
+because on-device turn detection and the local speech engines bring their own
+model runtimes. Text and TUI never import the audio stack at runtime, and
+`--voice` degrades to text with a readable reason if it cannot start.
+
+To work on Pyrrhon itself:
+
+```bash
+git clone https://github.com/prabhjot0109/Pyrrhon && cd Pyrrhon
+uv sync
+```
+
+## Quickstart
+
+```bash
+pyrrhon --setup                      # pick a provider, paste a key
+pyrrhon /path/to/some/repo           # ask it anything
+```
+
+One LLM key is enough. Groq is the default:
+
+```bash
+export GROQ_API_KEY=gsk_...          # PowerShell: $env:GROQ_API_KEY = "gsk_..."
+```
+
+Keys from the wizard are stored owner-only in `~/.pyrrhon/credentials.toml`,
+never in project config, and environment variables always win. `/settings`
+shows what is configured and where each value came from.
+
+## Usage
+
+### Channels
+
+```bash
+pyrrhon .                            # Textual TUI (default)
+pyrrhon --text .                     # plain-text REPL
+pyrrhon --voice .                    # TUI with the voice pipeline on
+```
+
+Voice needs a key for whichever STT/TTS providers you pick and nothing else.
+Inside the TUI, `/voice on|off` toggles it. Start talking whenever, interrupt
+whenever: barge-in rewrites history to exactly what you heard.
+
+### Sessions
+
+A walkthrough of a large codebase takes days, so sessions survive the night.
+
+```bash
+pyrrhon --continue .                 # resume this repo's most recent session
+pyrrhon --resume 20260901 .          # a specific one; a leading prefix is enough
+pyrrhon --no-save .                  # keep nothing
+```
+
+Only the questions and answers are saved — never tool output, and never a line
+number. A resumed session therefore has to reopen a file before it can cite
+one, which is the grounding rule enforced by the shape of the data rather than
+by asking the model nicely.
+
+### Headless
+
+```bash
+pyrrhon --print "how does the retry path work?" .
+echo "where is the cache invalidated?" | pyrrhon -p --json .
+```
+
+The answer goes to stdout and nothing else does; progress goes to stderr, and
+`--json` adds the citations and the turn's trace as data. Exit code is non-zero
+when the turn failed.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `/help`, `/exit` | The command table; leave. Type `/` or press `ctrl+p` to search live. |
+| `/mode design` | Switch to Act 2. `/mode understand` switches back. |
+| `/model fast groq/llama-3.3-70b-versatile` | Repoint a model slot for this session. |
+| `/code`, `ctrl+o` | Open the last citation: `/code` in VS Code, `ctrl+o` in `$VISUAL`/`$EDITOR` at the line. |
+| `/covered` | What this session has established so far. |
+| `/clear`, `/compact` | Fresh thread, same window; or summarize now and say by how much. |
+| `/cost` | Tokens and requests spent this session, and the ceilings it knows about. |
+| `/export [path]` | The walkthrough as markdown, with its citations. |
+| `/sessions` | What `--resume` can pick up. |
+| `/settings`, `/mcp`, `/plugins` | Configuration, MCP servers, loaded plugins. |
+| `/voice on\|off`, `/debug-history` | Toggle speech; dump the raw conversation. |
+
+## Configuration
+
+Settings merge from `~/.pyrrhon/config.toml`, then `<repo>/.pyrrhon.toml`, where
+the repo wins. All of it is optional.
+
+```toml
+[fast]                                  # every turn
+provider = "groq"
+model = "llama-3.3-70b-versatile"
+
+[deep]                                  # think_deeper escalation only
+provider = "openai"
+model = "o4-mini"
+
+[fallbacks]
+fast = ["cerebras", "openrouter/meta-llama/llama-3.3-70b-instruct"]
+
+[context]
+budget_tokens = 32000                   # before old turns are summarized
+keep_last_messages = 8                  # recent messages always kept verbatim
+
+[providers.myllm]                       # any OpenAI-compatible endpoint
+base_url = "http://localhost:8000/v1"
+api_key_env = "MYLLM_KEY"
+
+[mcp_servers.docs]                      # MCP tools join the agent's toolset
+command = "docs-mcp"                    # stdio, or: url = "http://..." for HTTP
+```
+
+Built-in providers are `groq`, `openai`, `anthropic`, `gemini`, `deepseek`,
+`cerebras`, `openrouter`, and `huggingface`, each needing only its `*_API_KEY`
+environment variable (Hugging Face uses `HF_TOKEN`). Two keyless local providers
+ship as well: `ollama` and `lmstudio`. No model ids are hardcoded anywhere —
+they rot faster than anything else here, so you name the model.
+
+Drop markdown **soul files** into `~/.pyrrhon/` or `<repo>/.pyrrhon/` to give
+Pyrrhon standing context about you or the repo. `/init` scaffolds one.
+
+### Voice providers
+
+```toml
+[voice]
+stt_provider = "groq"
+tts_provider = "cartesia"       # openai is the default
+tts_voice = "<voice-id>"        # provider-specific: an OpenAI/Groq name, a Gemini voice, a Cartesia/ElevenLabs id
+tts_model = "sonic-2"           # optional
+turn_detection = "smart"        # semantic end-of-turn; "vad" is the fixed-silence fallback
+idle_timeout_sec = 0            # seconds of your silence before it re-engages; 0 is off
+```
+
+| Task | Cloud (API key) | Local (keyless) |
+|---|---|---|
+| **LLM** | Groq, OpenAI, Anthropic, Gemini, DeepSeek, Cerebras, OpenRouter, Hugging Face | Ollama, LM Studio |
+| **STT** | Groq Whisper, OpenAI, Deepgram, Cartesia, AssemblyAI, Gladia, Gemini, Hugging Face | whisper-local (faster-whisper, any HF id), Moonshine |
+| **TTS** | OpenAI, Groq, Cartesia, ElevenLabs, Deepgram Aura, Rime, Inworld, Gemini, Hugging Face | Piper (in-process), Kokoro |
+
+OpenAI TTS is the zero-setup default. For real-time conversation, Cartesia and
+ElevenLabs are noticeably snappier — roughly 100–300 ms to first audio against
+400 ms and up. A fully local, keyless stack works too: `whisper-local`, `piper`,
+and Ollama or LM Studio.
+
+**Pyrrhon will offer you a provider it cannot currently run. It will never imply
+that it can.** `/settings stt|tts` labels every row with what it would take:
+
+```
+/settings tts
+  piper          [ready]  free, on-device, no key and no server
+  groq           [ready]  hosted TTS on your Groq key; needs an explicit voice id
+  openai         [ready, unverified]  no extra key if you already use OpenAI
+  cartesia       [needs CARTESIA_API_KEY]  lowest latency; needs a voice id from your account
+  kokoro         [install: uv add "pipecat-ai[kokoro]"]  free, on-device, ONNX
+```
+
+`ready, unverified` is the honest one: installed and keyed, but nobody has
+pushed a real utterance through it. A row earns plain `ready` only after
+`pytest tests/test_voice_live.py -m live` has actually made it speak.
+
+Gemini Live speech-to-speech is deliberately absent. It generates speech
+directly from audio, which skips the agent loop and the grounding gate. Gemini
+participates as LLM, STT, and TTS instead, each behind the gate.
+
+## Security model
+
+Pyrrhon is built so a voice agent cannot damage your repo even when the model is
+wrong.
+
+- **Read-only by construction.** The only write tool is `write_spec`, which
+  accepts exactly six filenames and writes only under `docs/design/`. Everything
+  else Pyrrhon writes lives under `.pyrrhon/`.
+- **No shell.** Git access is three read-only subcommands (`log`, `blame`,
+  `show`) run as argv lists, so there is no command string to inject into. Paths
+  are resolved and rejected if they escape the repo.
+- **Grounded speech.** Every `file:line` is checked against the real repo before
+  it is spoken. Unverifiable claims are stripped; real-but-unopened ones are
+  downgraded to a bare path with a hedge.
+- **Keys out of the repo.** Owner-only in `~/.pyrrhon/credentials.toml`, with
+  environment variables taking precedence.
+
+`tests/test_safety.py` and `tests/test_repo_trust_boundary.py` pin these, and
+the tool belt itself is a reviewed set encoded as a test.
+
+### What a cloned repo may and may not do
+
+A repo you have never read is untrusted input. Its `.pyrrhon.toml` and
+`.pyrrhon/` directory are that stranger's *suggestions*, so keys are split by
+what each one can actually do.
+
+| Repo supplies | Effect |
+|---|---|
+| `[voice]` (except `tts_url`), `[model]`, `[context]` | Applied. Cosmetic knobs. |
+| `[fast]`, `[deep]`, `[fallbacks]` naming a builtin or *your* provider | Applied. A repo may suggest `groq/llama-3.3`. |
+| `[mcp_servers.*]` | **Needs consent.** It launches a program. |
+| `[providers.*]` | **Needs consent.** It decides where your prompts and API key go. |
+| `voice.tts_url` | **Needs consent.** Piper HTTP mode POSTs everything Pyrrhon says to that URL. |
+| `[fast]`/`[deep]`/`[fallbacks]` naming a provider *the repo itself defined* | **Needs consent.** Same key redirection, one indirection away. |
+| `.pyrrhon/*.md` (soul files) | **Needs consent.** They enter the system prompt, so an ungated one can tell Pyrrhon to stop citing sources. |
+| `.pyrrhon/plugins/*` with tools or commands | **Needs consent.** It is Python that Pyrrhon would import and run. |
+
+Everything needing consent is collected into one startup prompt. Declining is
+not fatal: the session opens with whatever permissions it already has.
+
+Consent is recorded in `<repo>/.pyrrhon/trusted` and bound to the value's
+**content**, not its name. Approving `mcp_servers.indexer = "node ./build.js"`
+approves that command; if the repo later changes it, you are asked again.
+Editing an approved soul file re-prompts for the same reason. Your own
+`~/.pyrrhon/config.toml` is never gated, and files Pyrrhon writes itself
+self-grant.
+
+For automation, `pyrrhon --trust-repo` grants everything without prompting — it
+runs programs the repo chose, so use it only where you already trust the repo. A
+run with no interactive terminal (piped stdin, CI) refuses silently rather than
+hanging or auto-approving.
+
+## How it works
+
+Headless core, thin channels. `pyrrhon/core/` imports no channel; channels
+subscribe to one typed event stream and render it however they like.
+
+```mermaid
+flowchart TB
+    subgraph ch["Channels — thin, swappable"]
+        TUI["TUI (Textual)"]
+        REPL["Text REPL (rich)"]
+        HL["Headless (--print)"]
+        VOICE["Voice (Pipecat)"]
+    end
+
+    EV(["Event stream — one dispatch table<br/>SpeechChunk · Citation · ToolCall* · AskUser ·<br/>Transcription · TruncateSpeech · TurnFinished"])
+
+    subgraph core["pyrrhon/core — headless"]
+        SESSION["Session · cancellable turns, modes, transcript"]
+        LOOP["Agent loop · LLM ⇄ tools, streaming, recovery"]
+        POLICY["Turn policy · what this turn may spend"]
+        CTX["Context ladder · elide → summarize, learned limits"]
+        GATE["Grounding gate · promote / hedge / strip"]
+        LEDGER["Evidence ledger · what a tool actually showed"]
+        TOOLS["Tool belt · read · search · symbols · git · web ·<br/>explore · think_deeper"]
+    end
+
+    BOOT["pyrrhon/bootstrap.py — the one composition root<br/>settings · trust gate · plugins · MCP · prompts"]
+
+    TUI <--> EV
+    REPL <--> EV
+    HL <--> EV
+    VOICE <--> EV
+    EV <--> SESSION
+    SESSION --> LOOP
+    LOOP --> POLICY
+    LOOP --> CTX
+    LOOP --> TOOLS
+    LOOP --> GATE
+    TOOLS --> LEDGER
+    LEDGER --> GATE
+    BOOT --> LOOP
+```
+
+Four invariants hold across the codebase.
+
+**Grounding is mandatory, and verification is separate from delivery.** The gate
+sorts every reference three ways: observed becomes a citation, real-but-unopened
+is downgraded to a bare path with a hedge, unverified is stripped. The screen
+shows `path:line`; the voice never speaks it, because "loop dot py colon one
+nine three" is unusable to a listener.
+
+**A location is admissible only from a tool result in *this* turn.** Not from
+memory of an earlier turn, not from a summary, not from a persisted transcript.
+The file may have changed, and a stale in-range line passes every check the gate
+makes.
+
+**Real-time discipline holds everywhere in `core/`.** Nothing blocking runs
+inline in an `async def`; it goes through `asyncio.to_thread`, so audio never
+glitches while a tool reads disk.
+
+**There is one composition point.** `pyrrhon/bootstrap.py` assembles the LLM,
+tools, prompt, MCP servers, and plugins. Nothing else constructs an `Agent`.
+
+For the full internals — how one turn actually flows, why each subsystem is
+shaped the way it is, and where to look when something breaks —
+[CLAUDE.md](CLAUDE.md) carries the decision record for every subsystem, written
+as the working reference rather than as marketing.
+
+## Plugins
+
+A plugin is a folder with a `plugin.toml`, dropped into `~/.pyrrhon/plugins/`
+for global scope or `<repo>/.pyrrhon/plugins/` for one repo.
+
+```toml
+name = "hello-reviewer"
+version = "0.1.0"
+
+[contributes]
+prompts = ["prompts/*.md"]      # appended to the system prompt
+tools = "tools.py:get_tools"    # Python entry point returning list[Tool]
+```
+
+Plugins contribute prompts, tools, slash commands, LLM providers, and MCP
+servers. All of it is additive, so a plugin never overrides your config or the
+built-ins. Prompts and config load from anywhere, but repo-level plugin *code*
+runs only after a one-time consent prompt. A broken plugin is skipped with one
+warning instead of crashing the session, and `/plugins` shows what loaded. See
+the worked example in
+[`tests/fixtures/plugins/hello-reviewer/`](tests/fixtures/plugins/hello-reviewer/).
+
+## Development
+
+```bash
+uv run pytest                                   # full suite, ~90s, no API keys
+uv run pytest tests/test_session.py::test_name  # one test
+uv run ruff check . && uv run mypy pyrrhon/core # both gate CI
+```
+
+Evals need a real provider key and are not part of `pytest` — the suite tests
+the *runners*, the runners test the *agent*.
+
+```bash
+uv run python -m pyrrhon.evals.strangers        # fetch the frozen stranger repos
+uv run python -m pyrrhon.evals.grounding evals/grounding.yaml
+uv run python -m pyrrhon.evals.design evals/design.yaml --repo .
+```
+
+Both runners take `--model provider/model` to override the fast slot for one
+run, and the grounding runner **exits non-zero and refuses to certify a score
+when any turn ended in an error** — a set of "must admit ignorance" cases passes
+perfectly when nothing answers at all.
+
+| Path | What lives there |
+|---|---|
+| `pyrrhon/core/` | The headless agent. Imports nothing from outer layers. |
+| `pyrrhon/bootstrap.py` | Composition root: builds the Agent, runs the trust gate. |
+| `pyrrhon/channels.py` | The event-to-renderer dispatch table shared by channels. |
+| `pyrrhon/repl.py`, `pyrrhon/tui/`, `pyrrhon/voice/`, `pyrrhon/headless.py` | The four channels. |
+| `pyrrhon/commands/` | Slash commands, registered by decorator. |
+| `pyrrhon/config/`, `pyrrhon/plugins/` | Settings, credentials, trust, plugin loader. |
+| `pyrrhon/evals/` | The grounding and design harnesses, and the frozen stranger repos. |
+
+[CLAUDE.md](CLAUDE.md) is the working reference: the layering rule, the decision
+record behind each subsystem, and how to add a tool, event, command, or provider.
+
+## License
+
+MIT. See [LICENSE](LICENSE).