legionforge-convobox 0.4.0__tar.gz

legionforge_convobox-0.4.0/.gitattributes

@@ -0,0 +1,15 @@
+* text=auto eol=lf
+
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.tour text eol=lf
+*.json text eol=lf
+*.lock text eol=lf
+*.ps1 text eol=crlf
+*.sh text eol=lf
+
+*.wav binary
+*.onnx binary

legionforge_convobox-0.4.0/.githooks/pre-push

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Pre-push privacy scrub -- scans every commit about to be uploaded, not
+# just the working tree (a clean tree is not a clean push: git push
+# uploads all ancestor commits). Reference: LegionForge/jeli's hook and
+# the 2026-07-02 stale-branch leak it was written after.
+# Enable once per clone:  git config core.hooksPath .githooks
+PATTERN='192\.168\.|10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|ssh[^ ]*@[a-zA-Z0-9]|@[a-zA-Z0-9-]+\.local|id_ed25519|id_rsa|BEGIN [A-Z ]*PRIVATE KEY'
+fail=0
+while read -r _local_ref local_sha _remote_ref remote_sha; do
+  [ "$local_sha" = "0000000000000000000000000000000000000000" ] && continue
+  if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
+    range=$(git rev-list "$local_sha" --not --remotes=origin 2>/dev/null)
+  else
+    range=$(git rev-list "$remote_sha..$local_sha" 2>/dev/null)
+  fi
+  [ -z "$range" ] && continue
+  # uv.lock excluded: package version strings match the IP regex
+  # (nvidia_curand 10.4.0.35 -- verified false positive 2026-07-19).
+  # This hook excludes itself: it necessarily contains the patterns it
+  # scans for (it blocked its own first push -- working as designed).
+  hits=$(git grep -l -E "$PATTERN" $range -- ':!uv.lock' ':!.githooks/pre-push' 2>/dev/null)
+  if [ -n "$hits" ]; then
+    echo "pre-push BLOCKED: possible private data in outgoing commits:" >&2
+    echo "$hits" >&2
+    echo "Inspect with: git grep -n -E '<pattern>' <sha> -- <file>" >&2
+    fail=1
+  fi
+done
+exit $fail

legionforge_convobox-0.4.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Every change requires JP's review -- the mechanical enforcement of
+# "agents propose, JP approves" (AGENTS.md rule 10 era). GitHub
+# auto-requests review from owners on every PR touching matched paths.
+* @jp-cruz
+# Workflow changes doubly so: they run with repo permissions.
+.github/workflows/ @jp-cruz

legionforge_convobox-0.4.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  # The SHA-pinned dev-rig reusables and actions never update themselves
+  # -- that is the trade-off of pinning; this is the standard answer.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

legionforge_convobox-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,35 @@
+## Summary
+
+Describe the change briefly.
+
+## Attribution
+
+- [ ] Human-only change
+- [ ] AI-assisted change
+
+If you check `AI-assisted change`, the CI check will require the attribution
+block below or an `AI-Attribution:` commit trailer.
+
+If AI-assisted, fill in:
+
+- Product:
+- Provider:
+- Model:
+- Scope:
+- Date:
+
+Example:
+
+```text
+Attribution: OpenAI Codex
+Provider: OpenAI
+Model: GPT-5
+Scope: src/convobox/adapters/codex.py
+Date: 2026-07-15
+```
+
+## Validation
+
+- [ ] Tests run
+- [ ] Docs updated
+- [ ] Changelog updated, if user-visible

legionforge_convobox-0.4.0/.github/workflows/ai-attribution.yml

@@ -0,0 +1,89 @@
+name: AI Attribution Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check:
+    name: Require attribution when AI-assisted
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR attribution
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const pull = context.payload.pull_request;
+            const body = pull.body || "";
+
+            const aiAssistedMarked = /-\s*\[[xX]\]\s*AI-assisted change/.test(body);
+            if (!aiAssistedMarked) {
+              core.info("PR is not marked as AI-assisted; skipping attribution enforcement.");
+              return;
+            }
+
+            // Check the PR body FIRST -- this needs no API call, so a
+            // correctly-attributed PR can never be blocked by a GitHub API
+            // outage (which is exactly what once spuriously failed a
+            // correct PR: the old code called listCommits unconditionally
+            // at the top and threw on a transient 503).
+            const bodyHasAttribution =
+              /Attribution:\s*/i.test(body) &&
+              /Provider:\s*/i.test(body) &&
+              /Model:\s*/i.test(body) &&
+              /Scope:\s*/i.test(body) &&
+              /Date:\s*/i.test(body);
+            if (bodyHasAttribution) {
+              core.info("AI attribution present in PR body.");
+              return;
+            }
+
+            // The body lacks the block -> fall back to commit trailers. This
+            // is the ONLY path that needs the API. A transient API error here
+            // must NOT hard-fail the PR on infrastructure grounds: attribution
+            // is a governance requirement, and blocking correct work during a
+            // GitHub outage is worse than the rare case of one un-attributed
+            // PR slipping through while the API is down (easily caught later).
+            let commitMessages = "";
+            try {
+              const commits = await github.paginate(
+                github.rest.pulls.listCommits,
+                {
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: pull.number,
+                  per_page: 100,
+                },
+              );
+              commitMessages = commits.map((commit) => commit.commit.message).join("\n\n");
+            } catch (error) {
+              core.warning(
+                "Could not fetch commits to check for an AI-Attribution trailer (" +
+                  (error && error.message ? error.message : String(error)) +
+                  "). Skipping the commit-trailer check rather than failing the PR on " +
+                  "an infrastructure error -- ensure attribution is present.",
+              );
+              return;
+            }
+
+            if (/AI-Attribution:/i.test(commitMessages)) {
+              core.info("AI attribution present in a commit trailer.");
+              return;
+            }
+
+            core.setFailed(
+              [
+                "This PR is marked AI-assisted but is missing the required attribution.",
+                "",
+                "Add either:",
+                "- the standard attribution block to the PR body, or",
+                "- an `AI-Attribution:` commit trailer on one or more commits.",
+                "",
+                "Required fields for the PR body block:",
+                "Attribution, Provider, Model, Scope, Date.",
+              ].join("\n"),
+            );

legionforge_convobox-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+# LegionForge dev-rig CI: test/lint/SAST/dependency-audit/SBOM/secrets.
+#
+# Consumes LegionForge/dev-rig's shared reusable workflows (shared Python CI
+# + security rig used across LegionForge projects) rather than duplicating
+# tool config here. See TESTING.md -> "CI / LegionForge dev-rig" for what
+# each job checks, why it's scoped the way it is, and how to run the same
+# checks locally before pushing.
+#
+# Pinned to a commit SHA, not a tag: LegionForge/dev-rig has cut no tagged
+# release as of this writing (confirmed via `gh api repos/LegionForge/dev-rig/tags`
+# returning empty) -- dev-rig's own README examples currently show `@main`,
+# a mutable ref this project deliberately does not consume (see
+# LegionForge/dev-rig's pipeline-hardening handoff doc: never consume
+# `@main`, use a pinned tag once one exists). SHA-pin is the correct
+# available-today choice; re-pin to a released tag once dev-rig cuts one.
+#
+# DEV_RIG_REF: 468d5a7c30f6540a472a32d8b3bea1ac381f2017 (main, 2026-07-10)
+
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests & Coverage
+    uses: LegionForge/dev-rig/.github/workflows/test.yml@468d5a7c30f6540a472a32d8b3bea1ac381f2017
+    with:
+      coverage-source: "convobox"
+      python-version: "3.12"
+
+  lint:
+    name: Lint & Type Check
+    uses: LegionForge/dev-rig/.github/workflows/lint.yml@468d5a7c30f6540a472a32d8b3bea1ac381f2017
+    with:
+      source-dirs: "src/convobox"
+      python-version: "3.12"
+      # types-PyYAML is the default already; explicit for clarity. mypy's
+      # remaining untyped third-party deps (faster-whisper, sounddevice,
+      # silero-vad -- no stub packages exist for these) are scoped out via
+      # [[tool.mypy.overrides]] in pyproject.toml, not a blanket CLI flag,
+      # so this stays real type-checking rather than a broad opt-out.
+      extra-mypy-deps: "types-PyYAML"
+
+  sast:
+    name: SAST
+    uses: LegionForge/dev-rig/.github/workflows/sast.yml@468d5a7c30f6540a472a32d8b3bea1ac381f2017
+    permissions:
+      contents: read
+      security-events: write # required for the CodeQL upload-sarif step inside sast.yml
+    with:
+      source-dirs: "src/convobox"
+      # Restored p/fastapi 2026-08-17: ConvoBox now has a real FastAPI web
+      # UI (src/convobox/web/) plus a mounted MCP HTTP server with a CSRF
+      # exemption for its own routes -- exactly the trust-boundary code
+      # p/fastapi's ruleset targets. dev-rig's default is "p/python
+      # p/fastapi"; kept p/security-audit alongside it rather than
+      # dropping back to the narrower default.
+      semgrep-configs: "p/python p/fastapi p/security-audit"
+      python-version: "3.12"
+
+  audit:
+    name: Dependency Audit
+    uses: LegionForge/dev-rig/.github/workflows/audit.yml@468d5a7c30f6540a472a32d8b3bea1ac381f2017
+    with:
+      python-version: "3.12"
+
+  sbom:
+    name: SBOM
+    uses: LegionForge/dev-rig/.github/workflows/sbom.yml@468d5a7c30f6540a472a32d8b3bea1ac381f2017
+    with:
+      python-version: "3.12"
+
+  secrets:
+    name: Secret Scanning
+    uses: LegionForge/dev-rig/.github/workflows/secrets.yml@468d5a7c30f6540a472a32d8b3bea1ac381f2017

legionforge_convobox-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish to PyPI
+
+# Triggered by pushing a version tag (e.g. git tag v0.4.0 && git push --tags).
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored in secrets.
+# Configure the trusted publisher at https://pypi.org/manage/project/legionforge-convobox/settings/
+# before pushing the first tag:
+#   Publisher: GitHub Actions
+#   Repository: LegionForge/convobox
+#   Workflow: publish.yml
+#   Environment: pypi
+#
+# PyPI distribution name is legionforge-convobox (org convention: PyPI is a
+# flat global namespace, so every LegionForge package is prefixed to avoid
+# squatting/ambiguity -- see LegionForge/convobox's own DEPENDENCY_LICENSE_AUDIT.md
+# and pyproject.toml `[project] name`). The repo name, import path, and CLI
+# commands (convobox/convobox-settings/convobox-spike) stay unprefixed.
+#
+# Template: LegionForge/llm-valet/.github/workflows/publish.yml, adapted to
+# this repo's actual Python floor (3.12, matching pyproject.toml's
+# requires-python and ci.yml's python-version -- not copied blindly from
+# llm-valet's 3.11).
+#
+# Every action below is pinned to a commit SHA, not a floating tag --
+# same discipline ci.yml already applies to dev-rig (see that file's own
+# comment on why a moved tag is a real supply-chain vector), just not
+# consistently carried over here when this file was first written.
+# pypa/gh-action-pypi-publish's `release/v1` ref is a BRANCH, not a tag --
+# more mutable than a normal version tag, not less, so pinning matters
+# even more for it. Resolved 2026-08-06:
+#   actions/checkout@v7                  -> 3d3c42e5aac5ba805825da76410c181273ba90b1
+#   actions/setup-python@v6              -> ece7cb06caefa5fff74198d8649806c4678c61a1
+#   actions/upload-artifact@v7           -> 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+#   actions/download-artifact@v8         -> 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
+#   pypa/gh-action-pypi-publish@release/v1 -> dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

legionforge_convobox-0.4.0/.gitignore

@@ -0,0 +1,72 @@
+.venv/
+.models/
+# scripts/run_convobox.py --aec-dump output (reference/mic WAV captures
+# for offline AEC analysis) -- real audio, never committed. *.wav below
+# already covers the files; this also catches the directory itself so an
+# empty/future-dated run doesn't show up as an untracked-but-visible dir.
+.aec-dumps/
+.incident-captures/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+coverage.xml
+*.egg-info/
+dist/
+build/
+.env
+*.wav
+*.log
+# Manually rotated/renamed logs kept around for a diff (e.g.
+# convobox-tui.log.old.20260726) -- *.log above only matches the
+# unrotated name.
+*.log.old*
+uat-acoustic-calibration/
+.DS_Store
+
+# Per-machine local config and its variants (copy convobox.example.yaml to
+# create one) -- these carry real device names and other per-machine
+# specifics, same rationale as convobox.yaml itself. convobox.example.yaml
+# is the one deliberately-tracked exception.
+convobox*.yaml
+!convobox.example.yaml
+# Config backups now live in a subdirectory (settings_tui.py's
+# backup_config/list_config_backups, GitHub issue #235 finding D4) rather
+# than scattered as convobox.yaml.backup-* directly in the repo root --
+# the old flat pattern is kept too so a pre-existing checkout with old-style
+# backups still has them ignored until cleaned up.
+.convobox-backups/
+convobox.yaml.backup-*
+
+# run_convobox.py's AEC delay auto-tune diagnostic sidecar (config.py's
+# write_aec_estimate/read_aec_estimate) -- runtime-measured, not config.
+*.aec-estimate.json
+
+# Personal working notes kept out of the public repo -- philosophy.md is
+# JP's running voice-dialogue log (archived separately in the vault);
+# _diag.py/_tone.py were throwaway audio probes superseded by
+# scripts/audio_devices.py. Structural protection against an accidental
+# `git add -A` sweeping them in.
+philosophy.md
+scripts/_diag.py
+scripts/_tone.py
+
+# Leading-underscore convention for repo-root scratch/throwaway files
+# (message-log dumps, one-off test artifacts) -- generalizes the same
+# pattern _diag.py/_tone.py already used above.
+/_*
+
+# Web UI and persistent history -- contains user transcripts, approvals, commands.
+# KEEP THIS unless you explicitly want to track history in a PRIVATE repo.
+# See docs/SECURITY.md for opt-in flow.
+.convobox-history/
+.convobox.db
+
+# Web server logs (may contain event data, tool inputs, responses)
+.convobox-web.log
+convobox-web-*.log
+.convobox-cache/
+
+# Private/scratch directories
+.scratch/
+.private/

legionforge_convobox-0.4.0/.gitmessage.txt

@@ -0,0 +1,14 @@
+# AI-assisted commit template
+#
+# Use this template for commits that include AI-assisted work.
+# Keep the attribution block intact and replace the placeholders.
+
+Summary:
+
+Attribution: <product>
+Provider: <provider>
+Model: <model>
+Scope: <files, feature, or commit>
+Date: <YYYY-MM-DD>
+
+AI-Attribution: <product>; provider=<provider>; model=<model>; scope=<files, feature, or commit>

legionforge_convobox-0.4.0/.tours/01-architecture-and-data-flow.tour

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "1. Architecture & Data Flow",
+  "description": "Full pipeline walkthrough, in call order: mic -> VAD -> STT -> safeword -> orchestrator -> backend adapter -> TTS -> playback. Each step calls out the data handoff (shape/dtype crossing the boundary) and any performance-relevant design decision at that point.",
+  "steps": [
+    {
+      "title": "Start here",
+      "description": "**ConvoBox pipeline, top to bottom.**\n\n```\n   mic  ->  VAD  ->  local STT  ->  safeword check  ->  orchestrator  ->  backend adapter\n                                        |                                    |\n                                   (deterministic,                    OpenCode /\n                                    no LLM)                           Claude Code / ...\n                                                                            |\n                                                                    local streaming TTS\n```\n\nThis tour follows one utterance through every stage in the order it actually happens at runtime, not file/directory order. Watch the **data handoff** called out at each step — the shape/dtype changes as audio becomes numbers becomes text becomes routing decisions becomes speech again.\n\nSee `README.md` → Architecture for the original design diagram this pipeline implements.\n\nEach step below is anchored by both a line number and a text pattern — if the code has moved since this tour was written, CodeTour re-locates the step by searching for the pattern rather than trusting a stale line number."
+    },
+    {
+      "file": "scripts/spike.py",
+      "line": 38,
+      "pattern": "with MicrophoneStream\\(sample_rate=config\\.audio\\.sample_rate",
+      "description": "**The whole chain in one line.** This is the actual measurement spike — mic → VAD → STT → logged transcript — with no backend/TTS wiring, useful as an orientation map before diving into each stage:\n\n```python\nwith MicrophoneStream(...) as mic:\n    async for utterance in segmenter.segment(mic.stream()):\n        result = transcriber.transcribe(utterance)\n```\n\n`mic.stream()` is an async generator of raw chunks → `segmenter.segment()` re-yields only complete utterances → `transcriber.transcribe()` turns one utterance into text. Every step below zooms into one of these three calls."
+    },
+    {
+      "file": "src/convobox/audio/capture.py",
+      "line": 21,
+      "pattern": "class MicrophoneStream:",
+      "description": "**Stage 1: audio capture.** `MicrophoneStream` wraps a single `sounddevice.InputStream` — continuous streaming, not record-then-stop, because segmentation into utterances is VAD's job downstream, not a fixed capture window.\n\nDeliberately **not** shelling out to platform tools (sox/arecord/powershell) — see docs/LESSONS-FROM-VOICE-OPENCODE.md for why that was a real command-injection bug in an earlier related project."
+    },
+    {
+      "file": "src/convobox/audio/capture.py",
+      "line": 42,
+      "pattern": "def _callback\\(",
+      "description": "**The real-time boundary.** `_callback` runs on PortAudio's own audio thread, not the asyncio event loop — it must be fast and non-blocking. It just copies the incoming buffer and pushes it onto a plain `queue.Queue`.\n\n**Data handoff:** raw device audio → `float32` numpy array, shape `(blocksize,)`, values in `[-1, 1]`. float32 (not int16) because both Silero VAD and faster-whisper consume float32 directly — int16 would force a conversion on every single chunk (see the module-level comment at the top of this file)."
+    },
+    {
+      "file": "src/convobox/audio/capture.py",
+      "line": 70,
+      "pattern": "async def stream\\(self\\) -> AsyncIterator",
+      "description": "**Bridging the sync callback thread to async consumers.** `stream()` is an async generator that pulls off the queue via `asyncio.to_thread(self._queue.get)` — blocking the queue-get in a worker thread so it never stalls the event loop.\n\nThe `_CLOSE_SENTINEL` pattern (defined near the top of this file) is what lets `close()` wake up a consumer parked in a blocking `get()` — this exact bridge pattern gets reused later for TTS streaming too (see step on `piper.py`)."
+    },
+    {
+      "file": "src/convobox/vad/segmenter.py",
+      "line": 23,
+      "pattern": "class UtteranceSegmenter:",
+      "description": "**Stage 2: voice activity detection.** `UtteranceSegmenter` turns a stream of float32 chunks into discrete utterances using Silero VAD.\n\nTwo deliberate design choices worth noting up front (both in the docstring): a speech run only ends after `min_silence_ms` of *confirmed* silence (tolerant of pauses/disfluencies), and emitted utterances **include** that trailing silence on purpose — it helps STT avoid clipping the last phoneme."
+    },
+    {
+      "file": "src/convobox/vad/segmenter.py",
+      "line": 51,
+      "pattern": "def feed\\(self, chunk: np\\.ndarray\\)",
+      "description": "**Data handoff: arbitrary-length chunks → fixed 512-sample windows.** Silero's ONNX model only accepts exactly 512 samples (32ms) at 16kHz. Incoming capture chunks can be any length (and in `feed()`'s own tests, deliberately unaligned to 512 to prove no samples are dropped/duplicated), so they're buffered in `self._carry` and consumed in exact windows here.\n\nReturns a **list** of utterances (not zero-or-one) because a single large chunk can span the end of one utterance and the start of another."
+    },
+    {
+      "file": "src/convobox/vad/segmenter.py",
+      "line": 87,
+      "pattern": "def _process_window\\(self, window: np\\.ndarray\\)",
+      "description": "**The core state machine — and where a real hang bug lived.** Every window gets a `prob` from the model (this call happens unconditionally, every ~32ms, even during silence — see the Performance tour for why that's not actually wasted work).\n\nA few lines down, `_EXIT_HYSTERESIS` creates three zones: confidently speech, confidently silent, and an **ambiguous band** in between. The `elif is_speech:` branch just below (not a plain `else:`) is the fix for a bug where ambiguous-band frames were treated as speech and reset the silence timer on every frame — a speaker trailing off gradually could keep an utterance open forever. See the code comment right below it for the full story, and the Review Findings tour for the verification trail."
+    },
+    {
+      "file": "src/convobox/vad/segmenter.py",
+      "line": 131,
+      "pattern": "async def segment\\(",
+      "description": "**Data handoff: windows → one concatenated utterance array.** `segment()` is the async-generator wrapper `spike.py` actually calls — consumes chunks, yields complete utterances via `feed()`, and on stream close calls `flush()` to emit anything still in progress.\n\nOutput: a single float32 numpy array (all the 512-sample windows for that utterance concatenated together) — this is exactly what `LocalTranscriber.transcribe()` expects next."
+    },
+    {
+      "file": "src/convobox/stt/transcriber.py",
+      "line": 24,
+      "pattern": "class LocalTranscriber:",
+      "description": "**Stage 3: local speech-to-text.** `LocalTranscriber` loads the faster-whisper `WhisperModel` **once**, at construction — model loading is expensive, so this class is meant to be built once and reused across every utterance for the life of the process."
+    },
+    {
+      "file": "src/convobox/stt/transcriber.py",
+      "line": 33,
+      "pattern": "def transcribe\\(self, audio: np\\.ndarray\\)",
+      "description": "**Data handoff: utterance array → `TranscriptResult`.** Input is the float32 mono 16kHz array from the segmenter (defensively re-contiguous'd a couple lines down, since faster-whisper needs a contiguous buffer).\n\nOutput bundles the transcript text **with timing as a first-class field** (`latency_ms`, `duration_s`) — not just logged internally — because this project's whole first milestone was proving real accuracy/latency numbers before committing to backend/adapter design. Real measured numbers on this hardware: **STT ~140–200ms, RTF 0.05–0.13** (8–20x faster than real-time)."
+    },
+    {
+      "file": "src/convobox/safeword/detector.py",
+      "line": 5,
+      "pattern": "deliberately a plain normalized-substring match",
+      "description": "**Stage 4: the safeword check — deliberately dumb.** This comment says it outright: a plain normalized-substring match, **no ML, no fuzzy matching, no LLM**, on purpose. A hard stop is a safety-critical abort; a human reading this file must be able to predict exactly when it fires. That auditability guarantee is worth more here than the recall a fuzzy matcher would buy.\n\nThis runs on every transcript, in the orchestrator, **before** any busy/idle routing decision — see the next step."
+    },
+    {
+      "file": "src/convobox/orchestrator/orchestrator.py",
+      "line": 40,
+      "pattern": "async def handle_transcript\\(self, transcript: str\\)",
+      "description": "**Stage 5: the routing decision.** `handle_transcript` is where a finalized transcript becomes one of three concrete actions:\n\n1. **Hard stop** — checked first, unconditionally, and wins over everything else. It also stops any in-progress TTS/playback — if the user says stop, ConvoBox shouldn't keep talking.\n2. **Interject** — backend is busy, this is a side-comment, not a fresh task.\n3. **Fresh command** — backend is idle.\n\nThe `start_event_loop()` call near the top of this method is itself a fix: see the Review Findings tour for why `is_busy()` needs that loop running to stay accurate."
+    },
+    {
+      "file": "src/convobox/adapters/base.py",
+      "line": 32,
+      "pattern": "class BackendAdapter\\(ABC\\):",
+      "description": "**The backend adapter contract.** Three implementations exist and are each verified against a live instance: `OpenCodeAdapter` (HTTP+SSE), `ClaudeCodeAdapter` (bidirectional stream-json subprocess, `src/convobox/adapters/claude_code.py`), `CodexAdapter` (app-server JSON-RPC over stdio, `src/convobox/adapters/codex.py`). The docstring draws a hard line: `send_interject` must never derail a running task, `send_hard_stop` must abort it — these are never allowed to collapse into one \"interrupt\" action.\n\nA paragraph further down is an honesty clause added after review: a hard stop's real-world guarantee is bounded by what the backend actually exposes (see the next step for the concrete case)."
+    },
+    {
+      "file": "src/convobox/adapters/opencode.py",
+      "line": 82,
+      "pattern": "async def events\\(self\\) -> AsyncGenerator",
+      "description": "**The OpenCode backend adapter: HTTP + SSE.** `events()` opens a streaming GET and yields typed `BackendEvent`s parsed from each SSE frame in real time — not buffered until the connection closes.\n\n**Data handoff:** raw SSE `data:` frames (JSON text) → typed `BackendEvent` objects (`text | tool_call | tool_result | error | done`). The `finally` block a few lines down clears `self._busy = False` on **any** exit from this generator, not just an observed DONE — a dropped connection or exception used to leave `is_busy()` stuck `True` forever. See Review Findings for the full story."
+    },
+    {
+      "file": "src/convobox/orchestrator/orchestrator.py",
+      "line": 86,
+      "pattern": "def _on_event\\(self, event: BackendEvent\\)",
+      "description": "**Backend response → speech.** `_on_event` is where a `TEXT` event from the backend gets turned into spoken audio: strip code blocks (`strip_code_for_speech`, defined at the top of this file) so raw diffs aren't read aloud, then fire synthesis as a **background task**, not awaited inline.\n\nWhy fire-and-forget: synthesis can take noticeably longer than draining the *next* backend event (e.g. a DONE right behind this TEXT), and keeping `is_busy()` fresh matters more than serializing speech with event consumption. `AudioPlayer.play()` (next stage) is itself non-blocking, so this task's only real work is the `synthesize()` await."
+    },
+    {
+      "file": "src/convobox/tts/base.py",
+      "line": 14,
+      "pattern": "def sanitize_text\\(text: str\\)",
+      "description": "**The security boundary before any synthesis happens.** `sanitize_text` strips control characters and caps length on text that originates from **untrusted LLM output**. Every concrete `TTSEngine` must call this before synthesizing — this exists directly because of a real command-injection bug in an earlier related project (`voice-opencode`), where response text was interpolated straight into a shell command. See docs/LESSONS-FROM-VOICE-OPENCODE.md."
+    },
+    {
+      "file": "src/convobox/tts/base.py",
+      "line": 42,
+      "pattern": "def synthesize_stream\\(self, text: str\\) -> AsyncIterator",
+      "description": "**Streaming is the primary interface; `synthesize()` is the convenience wrapper.** `synthesize_stream` is the abstract method concrete engines implement. `synthesize()` just below it concatenates the stream — prefer `synthesize_stream` directly when time-to-first-audio matters, since it lets a caller start playback on the first chunk instead of waiting for the whole utterance."
+    },
+    {
+      "file": "src/convobox/tts/piper.py",
+      "line": 51,
+      "pattern": "async def synthesize_stream\\(self, text: str\\)",
+      "description": "**Stage 6: local TTS, genuinely streaming.** Piper's own `synthesize()` is a **blocking sync generator**. This bridges it to async the same way `MicrophoneStream.stream()` does — a background thread pushes converted float32 chunks onto a queue, and `synthesize_stream` yields each one via `asyncio.to_thread(chunk_queue.get)` as soon as it's ready.\n\n**Data handoff:** sanitized text → a stream of float32 PCM chunks. This used to buffer the *entire* response into one list before returning anything — measured improvement from switching to real streaming: **first chunk at ~143ms vs. ~1574ms total** on a 20-sentence passage (~11x faster time-to-first-audio)."
+    },
+    {
+      "file": "src/convobox/orchestrator/orchestrator.py",
+      "line": 225,
+      "pattern": "async def _speak\\(self, text: str\\)",
+      "description": "**Final handoff: synthesized audio → speakers, genuinely streamed.** `_speak` calls `self._player.play_stream(self._tts.synthesize_stream(text), ...)` — chunks flow from Piper to the speakers as they're produced, not buffered into one array first. (This step used to describe a whole-utterance `synthesize()`/`play()` call as the current state with streaming as a \"known next step\" — that step has since landed; see the '2. Review Findings' tour for the measured before/after.)\n\nAlso worth knowing from here: `Orchestrator.__init__` takes an optional `on_event` callback (any caller can observe the raw backend event stream, e.g. the `--tui` conversation view) and an optional `tier_responses` flag (speaks only the first paragraph of a multi-paragraph response, with `has_more_to_reveal()`/`speak_more()` exposing the rest for a \"tell me more\" follow-up) — both off by default, zero behavior change unless a caller opts in."
+    },
+    {
+      "file": "src/convobox/audio/playback.py",
+      "line": 9,
+      "pattern": "class AudioPlayer:",
+      "description": "**Stage 7: playback, with barge-in.** `AudioPlayer.stop()` is what makes barge-in possible — a response can be cut off the instant the user starts speaking again, rather than waiting for playback to finish. `Orchestrator.handle_transcript`'s hard-stop path (step 12 in this tour) calls exactly this.\n\n`play()` opens a fresh `sd.OutputStream` per call rather than reusing one — a real but modest overhead (tens of ms of device-open latency per response), deliberately left as-is for now since fixing it would mean reworking a test suite that deliberately asserts today's open/close-per-call behavior. See README → Status for the full reasoning."
+    },
+    {
+      "file": "src/convobox/web/app.py",
+      "description": "**A parallel subsystem, now fully wired, live, and viewable: the web UI.** `convobox/web/` (HistoryDB in `history.py`, the FastAPI app in `app.py`, the SSE fan-out in `stream.py`, `WebEventForwarder` in `bridge.py`, and a plain HTML/JS frontend in `static/index.html`) is a SQLite-history + live-event-stream server with a real page to view it, built per `docs/WEB-UI-ARCHITECTURE.md`. `scripts/run_convobox.py`'s `run()` chains a `WebEventForwarder` into `Orchestrator`'s existing `on_event` hook (no change to `Orchestrator` itself needed -- it already had this extension point) and starts a real `uvicorn.Server` as a background asyncio task whenever `web.enabled`/`--web` is set, lazily importing fastapi/uvicorn (the optional \"web\" extra) so CLI/TUI-only users never pay for it. `create_app()` mounts `static/index.html` as a Starlette `StaticFiles` catch-all at `\"/\"` -- registered LAST, after every `/api/*` route, so registration order (not special-casing) is what keeps the frontend from shadowing the API; a dedicated test asserts exactly that. `EventBroadcaster` carries plain dicts, not `BackendEvent` objects -- found while building a demo of this feature (2026-07-26) that the original wiring only ever forwarded backend responses/tool calls, never the user's OWN recognized speech that prompted them (no `BackendEvent` exists for that), so a captured session showed replies with no visible prompt. `WebEventForwarder.forward_transcript()` closes that gap -- wired into all three of run_convobox.py's `orchestrator.handle_transcript()` call sites (the mic loop, --text mode, and queued-interjection delivery). Live-verified end to end each step of the way, most recently: a real multi-turn session (transcript -> response -> tool_call -> tool_result -> response) through the actual ClaudeCodeAdapter + Orchestrator + HistoryDB, served back out over a real running uvicorn server's real HTTP API. `web.enabled` defaults off (zero behavior change for everyone else). The control plane has since grown well past view-only: `app.py`'s `/approve` endpoint (`action: Literal[\"approve\", \"deny\", \"explain\"]`) resolves a pending tool-call approval from the browser through the same `approval_bridge` a spoken approval phrase uses, plus a live `convobox.yaml` editor, stop/resume listening, and quit-the-session -- each added and individually live-verified, not built in one pass. See `docs/WEB-UI-ARCHITECTURE.md` for the full account and `docs/WEB-UI-USAGE.md` for what a user actually sees."
+    },
+    {
+      "title": "End of tour",
+      "description": "That's the full `src/convobox/` loop: **mic → VAD → STT → safeword → orchestrator → adapter → TTS → playback**, with a hard-stop escape hatch that can short-circuit at the orchestrator regardless of where the rest of the pipeline is.\n\n**Not covered by this tour, since it lives in `scripts/run_convobox.py`'s main loop rather than `src/convobox/`**: several more pure state-machine gates sit between the safeword check and the orchestrator call in the REAL running loop -- `ListeningGate` (pause/resume: \"stop listening\" hard-stops and pauses, only the wake word resumes), `BargeInMonitor` + `QueuedInterjection` (the two-axis interrupt-preset grid: what happens to the current turn vs. the user's new words), and `ContinuePromptGate` (the response-tiering silence-timeout gate: \"continue\"/\"go on\" reveals the rest of a tiered response, silence implies done). All follow the exact same pure-state-machine shape as the classes this tour walked through, unit-tested independent of real audio/clocks -- see `docs/DESIGN-barge-in.md` and `docs/DESIGN-0.3.0-interaction-and-safety.md` for the design reasoning, not re-derived here.\n\nTwo follow-up tours: **\"2. Review Findings: Security & Performance\"** for the concrete bugs a review pass found and fixed in this exact code, and **\"3. Extension Points: Modularity & Pluggability\"** for exactly where a collaborator can plug in a new backend adapter or TTS engine (and where they deliberately can't). Command Palette → CodeTour: Start Tour."
+    }
+  ]
+}