# Architecture and Implementation Notes ## How it's built - **Precompiled `dist/`** — TypeScript source compiles to `dist/index.js` via `tsc` on `npm install` (the `prepare` hook). pi loads the compiled JS directly, no jiti transpile on every startup. - **TUI rendering** — All 8 tools ship custom `renderCall` / `renderResult` components. Progress view shows per-item status, spinner, elapsed time, and download progress in real time. Result view shows expanded preview with format, browser/os profile, package path, chunk count, word count + heading outline, and error details. Phase + category badge for errors. - **Phase-aware FetchError** — 26 failure codes × 10 fetch phases × 7 categories. `createFetchError()` produces frozen rich error objects. `classifyError()` maps Node errors. `buildUserFacingFetchErrorSummary()` produces agent-friendly messages. `suggestRetryTimeoutMs()` extrapolates from partial download progress. - **Reading modes** — `src/outline.ts` powers the heading-outline / frugal-preview modes; `src/multi-answer.ts` powers the multi-source cited answer (BM25 over pooled chunks); `src/debug.ts` is the central `PI_WEBAIO_DEBUG=1` tracing helper (search / strategy / cache decisions, stderr-only so the MCP stdio channel stays clean). - **CI** — 4 GitHub Actions jobs: lint+typecheck (with `npm audit` and lockfile check), test (all 51 suites, ~1207 tests), prod-install-build (simulates the real `npm install --omit=dev` path), install-test (ubuntu/windows/macos — tarball verification + entry-point loading). Auto-release on version tag with GitHub Release notes. - **Security** — 19 secret patterns (AWS, GitHub, GitLab, npm, PyPI, Slack, Stripe, Google, SendGrid, DigitalOcean, OpenAI including `sk-proj-`/`sk-svcacct-`, Anthropic, Supabase, Vercel, Cloudflare, private keys, passwords in URLs), plus output secret redaction (`src/redact.ts`). SSRF protection via DNS-pinning + fail-closed validation with a non-overridable cloud-metadata floor; blocks surface as a phase-aware `blocked_ssrf` error. Path-traversal guard in `utils.ts`. Prompt injection detection. Default GitHub CodeQL scanning.