sofia-cli 0.1.1

package/specs/001-cli-workshop-rebuild/plan.md

@@ -0,0 +1,361 @@
+# Implementation Plan: sofIA Unified Build-From-Scratch CLI
+
+**Branch**: `001-cli-workshop-rebuild` | **Date**: 2026-02-26 | **Spec**: ./spec.md  
+**Input**: Feature specification from `specs/001-cli-workshop-rebuild/spec.md`
+
+**Plan outputs created by this workflow**:
+
+- Phase 0: ./research.md
+- Phase 1: ./data-model.md, ./quickstart.md, ./contracts/*
+
+## Summary
+
+Build a Node.js + TypeScript GitHub Copilot SDK CLI that runs the governed workshop lifecycle for Discover → Ideate → Design → Select → Plan and captures PoC requirements for Develop, with explicit phase decision gates, repo-local session persistence, robust recovery, and deterministic automated testability (including PTY-based interactive harness). Concrete PoC repository generation and the Ralph loop are implemented in a separate feature (002-poc-generation) that consumes the session data produced here.
+
+Transparency UX: provide a user-visible **reasoning/rationale view** as structured summaries (why we’re asking, what we inferred, what trade-offs we made), plus an **activity/telemetry stream** (phase state, tool usage, progress, retries) and an optional debug log.
+
+Note: even though the constitution no longer forbids it, this plan does **not** include displaying raw hidden model chain-of-thought; instead it provides explicit, reviewable rationale summaries and intermediate artifacts.
+
+## Technical Context
+
+**Language/Version**: Node.js 20 LTS + TypeScript 5.x  
+**Primary Dependencies**: `@github/copilot-sdk`, `commander` (CLI), `@inquirer/prompts` (menus), `zod` (schemas), `pino` (logs), `ora` (spinners/activity), `marked` + `marked-terminal` (Markdown→ANSI), `chalk` (color), `cli-table3` (tables)  
+**Storage**: Repo-local files: `./.sofia/sessions/<sessionId>.json`, export bundles in `./exports/<sessionId>/`  
+**Testing**: Vitest (unit/integration), `node-pty` (interactive E2E harness), deterministic fakes for Copilot SDK sessions  
+**Target Platform**: macOS/Linux/Windows terminals (TTY and non-TTY); Node runtime only  
+**Project Type**: CLI application + library modules (agents/orchestration)  
+**Performance Goals**: First streamed output token ≤ 3 seconds in correctly configured environments; avoid blocking render loops  
+**Constraints**: No raw SDK JSON to users; no hidden chain-of-thought display; no implicit phase transitions; repo-local persistence; graceful MCP/tool degradation; interactive must be fully automatable via PTY; stdout must remain JSON-only in `--json` mode  
+**Scale/Scope**: Single-user/local facilitator runs; session sizes dominated by turn history + artifacts; support multiple sessions per repo
+
+## CLI Rendering (Markdown, color, tables)
+
+Goal: when possible, workshop outputs are authored in Markdown and rendered to the terminal in a readable, colorful format (headings, lists, code blocks, links, and tables at minimum).
+
+Rendering rules:
+
+- If `process.stdout.isTTY` and not `--json`, render Markdown to ANSI using `marked` + `marked-terminal`.
+- **Streaming responses**: LLM text is rendered as formatted markdown incrementally during streaming using `marked` + `marked-terminal`. Each text chunk is processed through the renderer as it arrives, producing ANSI-formatted output in real time. Minor rendering artifacts from partial markdown (e.g., split headings, incomplete tables) are acceptable for responsiveness.
+- Render tables using `cli-table3` for consistent borders/column widths (used for structured outputs like status, BXT scores; not for inline streaming).
+- If non-TTY or `--json`, do not emit ANSI/spinners; output plain text (or raw Markdown when plain text would lose meaning).
+- Keep activity/telemetry on stderr so stdout can remain clean for scripting.
+
+### Visual Feedback & Activity Indicators (FR-043a/b/c)
+
+The CLI provides continuous visual feedback during all operations via `ora` spinners and inline status summaries:
+
+1. **"Thinking..." spinner**: Displayed during all silent gaps — after user input before LLM first token, and between tool results and next text output. Cleared when text streaming begins.
+2. **Tool-specific spinner**: When the LLM triggers a tool call, the "Thinking..." spinner transitions to a contextual message (e.g., "⠋ Calling WorkIQ...", "⠋ Searching documentation..."). Cleared when the tool completes.
+3. **Tool result summaries**: After each tool call completes, a one-line summary is printed below the spinner area (e.g., "✓ WorkIQ: Found 12 relevant processes"). These summaries remain visible in the output stream.
+4. **`--debug` verbose tool output**: When `--debug` is specified, tool summaries expand to include arguments and full result details (multi-line). This reuses the existing `--debug` flag — no separate `--verbose` flag.
+5. **Non-TTY/JSON suppression**: Spinners and tool summaries are suppressed in non-TTY and `--json` mode. Tool activity is written to stderr or the debug log only.
+
+Spinner lifecycle in the ConversationLoop `streamResponse()` method:
+
+```
+User input → Start "Thinking..." spinner
+  → ToolCall event  → Transition spinner to "⠋ <toolName>..."
+  → ToolResult event → Stop spinner, print "✓ <toolName>: <summary>"
+                       → Restart "Thinking..." spinner (if more processing expected)
+  → TextDelta event → Stop spinner, stream rendered markdown
+  → Response complete → Ensure spinner stopped
+```
+
+Implementation approach:
+
+- Create `src/shared/activitySpinner.ts` module wrapping `ora` with methods: `startThinking()`, `startToolCall(toolName)`, `completeToolCall(toolName, summary)`, `stop()`, and `isActive()`.
+- The spinner module respects `isTTY` and `isJsonMode` from the IO context.
+- `ConversationLoop.streamResponse()` manages spinner lifecycle based on event types.
+- `LoopIO` interface gains `writeToolSummary(toolName: string, summary: string, debug?: { args: Record<string, unknown>; result: unknown }): void` method.
+- In `--debug` mode, `writeToolSummary()` expands the summary with args and full result details.
+
+## Existing Assets: Prompts + Discovery Cards Dataset
+
+This repository already contains two critical inputs that the implementation must build on.
+
+### Original prompts (seed material)
+
+- Location: `src/originalPrompts/`
+- Files:
+
+  - `facilitator_persona.md`
+  - `design_thinking_persona.md`
+  - `design_thinking.md`
+  - `guardrails.md`
+  - `document_generator_persona.md`
+  - `document_generator_example.md`
+
+Plan requirement:
+
+- Create canonical runtime prompts under `src/prompts/` by adapting/modularizing these files (shared guardrails + per-step instructions + output schemas).
+- Keep `src/originalPrompts/` intact as a historical reference; do not treat it as the runtime source of truth.
+
+### Discovery Cards dataset (authoritative data)
+
+- Dataset: `src/shared/data/cards.json`
+- Loader (already implemented): `src/shared/data/cardsLoader.ts` (Zod validation + cached load + search)
+
+Plan requirement:
+
+- Use this dataset in the relevant workshop steps (Explore Cards, scoring, mapping cards→workflow steps, ideation support).
+- Provide CLI affordances to browse categories, list cards, and search cards by keyword in interactive mode.
+
+## MCP Integration: Runtime Wiring (Copilot SDK + MCP)
+
+This repo’s MCP servers are configured for the development environment in `.vscode/mcp.json` and include:
+
+- stdio servers (invoked via `npx`): `workiq`, `azure`, `context7`, `playwright`
+- HTTP servers: `github` (`https://api.githubcopilot.com/mcp/`), `microsoftdocs/mcp` (`https://learn.microsoft.com/api/mcp`)
+
+Plan requirement:
+
+- Implement an `McpManager` module that:
+  - loads and validates `.vscode/mcp.json` (plus optional environment-variable overrides)
+  - connects to stdio servers via the MCP TypeScript SDK `Client` + `StdioClientTransport`
+  - connects to HTTP servers via `Client` + `StreamableHTTPClientTransport`
+  - lists tools (`client.listTools()`) and exposes them to the Copilot SDK as callable tools (namespaced as `mcp.<server>.<tool>`)
+  - classifies and surfaces errors (auth/connection/timeout/tool) without leaking secrets
+
+Note: `.vscode/mcp.json` is a VS Code convention; the CLI must not assume Copilot SDK will auto-load it. The CLI loads it explicitly to reuse the same server inventory.
+
+## Discovery Phase: Web Research via Copilot SDK tool-calling
+
+The Discover phase requires web research “when possible”. To ensure this works in the CLI:
+
+- Provide a first-class tool `web.search` (invoked via Copilot SDK tool-calling).
+- Implement `web.search` by calling an Azure AI Foundry agent that has **Bing Search tools** configured (per “Grounding agents with Bing Search tools in Microsoft Foundry”).
+  - Configure the Foundry agent endpoint and key via environment variables (for example: `SOFIA_FOUNDRY_AGENT_ENDPOINT`, `SOFIA_FOUNDRY_AGENT_KEY`).
+  - The CLI MUST NOT log or persist these secrets; they are read at startup and used only for HTTPS calls to the agent.
+  - If the Foundry agent is not configured or returns a hard failure, degrade gracefully to a “guided research” prompt that asks the facilitator to paste links/notes.
+
+Output contract:
+
+- `web.search` returns structured results (title, url, snippet/summary) plus an optional `sources` list for auditability, derived from the Foundry agent’s Bing Search tool output.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+Default gates for this repository (sofIA Copilot CLI) — derived from `.specify/memory/constitution.md`:
+
+- **Outcome-first discovery**: plan ties work to a measurable business/user outcome.
+- **Secure-by-default**: least privilege, no secrets/PII in logs or prompts.
+- **Node.js + TypeScript**: aligns with GitHub Copilot SDK patterns used here.
+- **MCP-first**: prefer MCP tools over ad-hoc HTTP when available.
+- **Test-first (NON-NEGOTIABLE)**: new behavior is implemented via Red → Green → Review.
+- **CLI transparency**: long-running steps stream progress; failures include recovery options.
+
+If any gate cannot be met, document the exception under **Complexity Tracking** with rationale.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-cli-workshop-rebuild/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── cli/                  # command routing, menus, IO adapters
+├── loop/                 # ConversationLoop abstraction + streaming renderer
+├── sessions/             # session model, persistence, backtracking, exports
+├── phases/               # discover/ideate/design/select/plan, plus a Develop boundary module for PoC intent capture and delegation to feature 002
+├── mcp/                  # wrappers for WorkIQ/Context7/MicrosoftDocs/GitHub MCP
+├── logging/              # redaction + pino setup + log file routing
+├── prompts/               # canonical runtime prompts (derived from src/originalPrompts)
+└── shared/               # shared schemas, types, card dataset loader, utilities
+
+src/originalPrompts/       # existing seed prompts (kept for reference; not runtime source of truth)
+
+tests/
+├── unit/
+├── integration/
+└── e2e/                  # PTY-driven interactive harness tests
+
+.sofia/                   # repo-local state (gitignored): sessions, temp artifacts
+exports/                  # repo-local exports (gitignored): customer artifact bundles
+```
+
+**Structure Decision**: Single Node.js/TypeScript CLI project at repository root with layered modules for CLI UX, conversation loop, phase orchestration, persistence, and MCP integrations.
+
+## Agent Design: Step/Phase Coverage
+
+The agent set is derived from the existing personas/prompts and covers the workshop pipeline end-to-end:
+
+- Facilitator orchestrator (primary)
+
+  - Seed: `src/originalPrompts/facilitator_persona.md`
+  - Responsibilities: governed progression/decision gates, delegation to step specialists, persistence of summaries + artifacts.
+
+- Step specialists (per phase/step)
+
+  - Seeds: `design_thinking_persona.md` + `design_thinking.md`, plus `guardrails.md` included everywhere.
+  - Output contracts: each step emits structured data for the session model (see `data-model.md`) and Markdown artifacts for export.
+
+- Document generator
+
+  - Seed: `document_generator_persona.md` + `document_generator_example.md`
+  - Responsibilities: produce customer-ready workshop report/artifacts from session state.
+
+- Discovery Cards support
+
+  - Data source: `src/shared/data/cards.json` via `cardsLoader.ts`
+  - Responsibilities: present cards, support scoring, map cards to workflow steps, seed ideation prompts with relevant cards.
+
+## Phase 7: New Capabilities (Session Naming, Default Command, Auto-Start)
+
+These additions address three new requirements clarified in Session 2026-02-27 (see spec.md Clarifications).
+
+### 7a. Session Naming (FR-023a)
+
+**Goal**: Auto-generate a short, human-readable session name after the first Discover exchange when `businessContext` is first captured.
+
+**Design**:
+
+- Add optional `name?: string` field to `workshopSessionSchema` in `src/shared/schemas/session.ts`.
+- Update Discover phase system prompt to instruct the LLM to include a `sessionName` field in its structured JSON output alongside `businessContext`.
+- Add `extractSessionName(response: string): string | null` extractor in `src/phases/phaseExtractors.ts`, parsing `sessionName` from the same JSON block used by `extractBusinessContext`.
+- Update Discover handler's `extractResult()` to call `extractSessionName()` and set `session.name` when a name is found.
+- Update `statusCommand.ts` to display the session name in table and JSON output.
+- Update `workshopCommand.ts` to display the session name in menu/resume flows.
+
+**Constraints**: Name is auto-generated; no user confirmation required. If the LLM omits `sessionName`, the session continues unnamed (no error).
+
+### 7b. Default Workshop Command (FR-004 updated)
+
+**Goal**: Running `sofia` with no subcommand starts the workshop flow (main menu). Workshop options (`--new-session`, `--phase`, `--retry`) promoted to top-level. `sofia workshop` kept as alias. `status` and `export` remain explicit subcommands.
+
+**Design**:
+
+- Restructure `src/cli/index.ts`:
+  - Move workshop options (`--new-session`, `--phase`, `--retry`) to `program` (top-level).
+  - Set a default action on `program` that invokes the workshop flow when no subcommand is given.
+  - Keep `program.command('workshop')` as an alias (same handler).
+  - `status` and `export` remain explicit subcommands.
+  - `--help` shows all workshop options at the top level.
+
+**Constraints**: Must not break existing `sofia workshop`, `sofia status`, or `sofia export` commands. Direct command mode (`--session` + `--phase`) must continue working at top level.
+
+### 7c. Auto-Start Conversation (FR-015a)
+
+**Goal**: When a conversation phase starts (new or resumed), the ConversationLoop sends an initial message to the LLM before waiting for user input. The LLM introduces the phase and asks the first question. On resume, it summarizes progress and asks the next question.
+
+**Design**:
+
+- Add `initialMessage?: string` option to `ConversationLoopOptions`.
+- Modify `ConversationLoop.run()`:
+  - If `initialMessage` is provided, send it as a system/user message to the LLM before entering the `readInput()` loop.
+  - Stream and render the LLM response as the opening greeting.
+  - Record the initial exchange in turn history.
+  - If no first token arrives within 10 seconds, treat as transient failure and apply retry logic.
+- Add `getInitialMessage(session: WorkshopSession): string` method to the `PhaseHandler` interface.
+  - For new sessions: generates a prompt like "Introduce the [phase] phase and ask the first question."
+  - For resumed sessions: generates a prompt like "Summarize progress so far and ask the next question."
+- Wire `getInitialMessage()` into `workshopCommand.ts` so it's passed to `ConversationLoop` at phase start.
+- All phase handler factories must implement `getInitialMessage()`.
+
+**Timeout**: 10 seconds for first token of auto-start greeting (per clarification).
+
+## Post-Design Constitution Re-check (Phase 1)
+
+- User-visible transparency is provided via rationale summaries + intermediate artifacts + activity/telemetry (not raw hidden chain-of-thought).
+- Interactive mode never auto-advances phases; explicit decision gate required.
+- Testability is a first-class deliverable: unit + integration + PTY E2E harness.
+
+## Post-Design Constitution Re-check (Phase 7 additions)
+
+- **Outcome-first**: Session naming improves facilitator UX (identify sessions at a glance). Default command reduces friction. Auto-start eliminates dead air.
+- **Secure-by-default**: No new secrets introduced; session name is derived from business context already in the session.
+- **Test-first**: All new behavior requires failing tests before implementation (TDD).
+- **CLI transparency**: Auto-start greeting makes the system proactive and informative.
+
+## Phase 8: Visual Feedback & Streaming Markdown (FR-009a, FR-043a/b/c)
+
+These additions address requirements clarified in Session 2026-02-27 regarding visual feedback during internal operations and incremental markdown rendering.
+
+### 8a. Incremental Streaming Markdown Rendering (FR-009a)
+
+**Goal**: Render LLM streaming text through `marked` + `marked-terminal` incrementally during streaming, so users see formatted markdown (headings, bold, code blocks, lists) in real time rather than raw markdown syntax.
+
+**Design**:
+
+- Update `ConversationLoop.streamResponse()` to pass each `TextDelta` chunk through `renderMarkdown()` before writing to `io.write()`.
+- Update `renderMarkdown()` to handle incremental rendering: process chunks through `marked` + `marked-terminal` as they arrive. Accept minor artifacts from partial markdown (split headings, incomplete tables).
+- Ensure the full response is still captured as raw markdown for session persistence (turn history stores raw markdown, not ANSI).
+- In non-TTY/JSON mode, chunks are written raw (no ANSI rendering), preserving existing behavior.
+
+**Files touched**: `src/loop/conversationLoop.ts`, `src/shared/markdownRenderer.ts`
+
+### 8b. Activity Spinner Module (FR-043a, FR-043c)
+
+**Goal**: Provide a unified spinner module wrapping `ora` that manages "Thinking..." and tool-specific spinners with proper lifecycle management.
+
+**Design**:
+
+- Create `src/shared/activitySpinner.ts` with an `ActivitySpinner` class:
+  - `startThinking()`: Display "Thinking..." spinner. No-op if non-TTY/JSON.
+  - `startToolCall(toolName: string)`: Transition to "⠋ <toolName>..." spinner. If already spinning, update text in-place.
+  - `completeToolCall(toolName: string, summary: string)`: Stop spinner, print "✓ <toolName>: <summary>" line.
+  - `stop()`: Stop any active spinner.
+  - `isActive(): boolean`: Check if a spinner is currently running.
+- Constructor accepts `{ isTTY: boolean; isJsonMode: boolean; debugMode: boolean }` — all spinner operations are no-ops when not TTY or in JSON mode.
+- The spinner writes to stderr to avoid polluting stdout.
+
+**Files touched**: `src/shared/activitySpinner.ts` (new)
+
+### 8c. Tool Call Summaries & Debug Verbose Output (FR-043b)
+
+**Goal**: After each tool call completes, display a one-line summary. In `--debug` mode, expand with full arguments and result details.
+
+**Design**:
+
+- Add `writeToolSummary(toolName: string, summary: string, debug?: { args: Record<string, unknown>; result: unknown }): void` method to `LoopIO` interface.
+- Implement in `createLoopIO()` in `src/cli/ioContext.ts`:
+  - Default: prints `✓ <toolName>: <summary>` to stderr.
+  - `--debug`: additionally prints formatted JSON of args and result below the summary.
+  - Non-TTY/JSON: omit from stdout; write to stderr or debug log only.
+- Update `ConversationLoop.streamResponse()` to call `io.writeToolSummary()` when a `ToolResult` event is received, constructing the summary from the event data.
+
+**Files touched**: `src/loop/conversationLoop.ts`, `src/cli/ioContext.ts`
+
+### 8d. ConversationLoop Spinner Integration (FR-043a/b/c combined)
+
+**Goal**: Wire the `ActivitySpinner` into `ConversationLoop.streamResponse()` to manage the full spinner lifecycle across thinking, tool calls, and text streaming.
+
+**Design**:
+
+- `ConversationLoop` constructor accepts an `ActivitySpinner` instance (injected via options or created from IO context).
+- In `streamResponse()`, manage spinner state based on event types:
+  1. Before sending message: call `spinner.startThinking()`.
+  2. On `ToolCall` event: call `spinner.startToolCall(event.toolName)`.
+  3. On `ToolResult` event: call `spinner.completeToolCall(event.toolName, summarize(event.result))`, then `spinner.startThinking()` if more events expected.
+  4. On first `TextDelta` event: call `spinner.stop()` (clear spinner, start streaming text).
+  5. On response complete: call `spinner.stop()` (safety net).
+- Expose `spinner` option in `ConversationLoopOptions` to allow injection for testing (pass a no-op spinner in tests).
+
+**Files touched**: `src/loop/conversationLoop.ts`
+
+### Post-Design Constitution Re-check (Phase 8)
+
+- **Outcome-first**: Visual feedback eliminates "dead terminal" anxiety — users always know the system is working. Markdown rendering improves readability of LLM outputs.
+- **CLI transparency**: Spinners, tool summaries, and thinking indicators make internal operations visible without exposing raw SDK internals.
+- **Test-first**: All new behavior requires failing tests before implementation (TDD). Spinner can be tested via a fake/mock `ora` or by verifying event-driven callbacks.
+- **Secure-by-default**: Tool summaries in default mode show no sensitive data. `--debug` verbose output is opt-in and goes to stderr.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+| --------- | ---------- | ----------------------------------- |
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

package/specs/001-cli-workshop-rebuild/quickstart.md

@@ -0,0 +1,83 @@
+# Quickstart: sofIA CLI workshop rebuild
+
+## Prerequisites
+
+- Node.js 20 LTS
+- npm
+
+## Setup
+
+```bash
+npm install
+```
+
+## Run (interactive)
+
+```bash
+# Start an interactive workshop (tsx, no build required)
+npm run start -- workshop
+
+# Start a new session directly
+npm run start -- workshop --new-session
+```
+
+## Run (non-interactive / automation)
+
+```bash
+# Session status as JSON
+npm run start -- status --session <id> --json
+
+# Direct command mode: run a specific phase
+npm run start -- workshop --session <id> --phase Discover --non-interactive
+
+# With retry for transient failures
+npm run start -- workshop --session <id> --phase Ideate --retry 3 --non-interactive
+```
+
+## Run (built mode)
+
+```bash
+# Build TypeScript first
+npm run build
+
+# Then use the compiled output
+npm run sofia -- workshop
+npm run sofia -- status --session <id> --json
+```
+
+## Storage
+
+- Session files: `.sofia/sessions/<sessionId>.json`
+- Exports: `./exports/<sessionId>/`
+
+## Testing
+
+```bash
+# Full suite (unit + integration + e2e)
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# Integration tests only
+npm run test:integration
+
+# Interactive E2E (PTY)
+npm run test:e2e
+```
+
+## Debug logs
+
+```bash
+npm run start -- workshop --debug --log-file .sofia/logs/dev.log
+```
+
+## Environment variables (optional)
+
+| Variable | Purpose |
+|----------|---------|
+| `SOFIA_FOUNDRY_AGENT_ENDPOINT` | Azure AI Foundry Bing Search agent endpoint |
+| `SOFIA_FOUNDRY_AGENT_KEY` | API key for the Foundry agent |
+
+See [docs/environment.md](../../docs/environment.md) for details.
+

package/specs/001-cli-workshop-rebuild/research.md

@@ -0,0 +1,116 @@
+# Research: sofIA Unified Build-From-Scratch CLI
+
+**Feature**: ./spec.md
+**Plan**: ./plan.md
+**Date**: 2026-02-26
+
+This document resolves technical choices for implementing the spec in Node.js/TypeScript with the GitHub Copilot SDK, focusing on testability, recoverability, and CLI-first UX.
+
+## Decisions
+
+### 1) CLI command framework
+
+- Decision: Use `commander` for command parsing and help output.
+- Rationale: Widely used, stable, good help/version/option ergonomics; plays well with non-TTY and JSON output constraints.
+- Alternatives considered:
+  - `yargs`: strong but heavier and less aligned with our simple command surface.
+  - `oclif`: powerful but more framework-heavy than needed for early MVP.
+
+### 2) Interactive menus (TTY)
+
+- Decision: Use `@inquirer/prompts` for menu-driven interactive flows.
+- Rationale: Modern UX for prompts, consistent behavior in Node environments, easy to stub in tests via input adapters.
+- Alternatives considered:
+  - `@clack/prompts`: very nice UX, but inquirer’s ecosystem is broader and easier to standardize.
+  - Full-screen TUI frameworks (Ink/Blessed): rejected because the spec’s out-of-scope forbids rich terminal UI, and they complicate PTY automation.
+
+### 3) Reasoning transparency (“LLM thoughts”) UX
+
+- Decision: Provide a **rationale view** made of structured, user-readable summaries (intent, assumptions, trade-offs, and what evidence/tools were used) plus an **Activity Stream** (tool usage, phase state, progress) and optional debug logs.
+- Rationale: Users get transparency and auditability without relying on hidden model chain-of-thought; also keeps the CLI deterministic and safe.
+- Alternatives considered:
+  - Full-screen TUI panes: rejected (spec out-of-scope for rich terminal UI and complicates PTY automation).
+  - Dumping raw hidden chain-of-thought: rejected (not needed for transparency; better handled as explicit summaries + artifacts).
+
+### 4) Markdown rendering in the CLI
+
+- Decision: Render Markdown to ANSI when possible (TTY, non-JSON) with color and table support.
+- Rationale: Workshop artifacts are naturally Markdown; rendering improves readability while preserving exports as Markdown.
+- Proposed libraries: `marked` + `marked-terminal`, `chalk`, `cli-table3`.
+
+### 5) Streaming output rendering
+
+- Decision: Implement a streaming renderer that writes incremental text to stdout immediately and supports a dedicated activity channel.
+- Rationale: Required by spec (no full-buffer output; TTFT ≤ 3s). Enables deterministic tests by asserting event ordering and output boundaries.
+- Alternatives considered:
+  - Buffer until completion: violates TTFT and streaming requirements.
+
+### 6) Session persistence format and location
+
+- Decision: Repo-local persistence at `./.sofia/sessions/<sessionId>.json` (single JSON per session), persisted after every user turn.
+- Rationale: Matches clarified requirements; easiest to diff/debug, easiest to test; ensures recoverability across crashes.
+- Alternatives considered:
+  - JSONL turns log: good for append-only, but spec preference is single JSON file.
+  - SQLite: robust but unnecessary complexity for MVP.
+
+### 7) Export format
+
+- Decision: Default export to `./exports/<sessionId>/` containing phase Markdown artifacts + `summary.json`.
+- Rationale: Human-friendly outputs for customers + machine-readable index for tooling.
+- Alternatives considered:
+  - ZIP: introduces archive edge cases and harder diff/review.
+
+### 8) Testing stack
+
+- Decision: Use Vitest for unit/integration and `node-pty` for interactive E2E harness.
+- Rationale: Deterministic, fast, good TypeScript support; PTY harness satisfies “interactive-only manual verification is insufficient”.
+- Alternatives considered:
+  - Jest: fine, but Vitest is faster and TypeScript-friendly.
+  - Only integration tests without PTY: violates spec.
+
+### 9) Copilot SDK simulation for tests
+
+- Decision: Wrap Copilot SDK interactions behind a small interface (`CopilotClient` / `ConversationSession` abstraction) with deterministic fakes for tests.
+- Rationale: Avoid flaky network/LLM dependence; allow tests to assert control-flow and output contracts.
+- Alternatives considered:
+  - Live Copilot calls in tests: non-deterministic and brittle.
+
+### 10) Logging
+
+- Decision: Use `pino` with a `--log-file <path>` (and/or `--debug`) option to enable full internal trace logs. Ensure strict redaction.
+- Rationale: Speeds debugging; meets observability requirements; keeps user output clean.
+- Alternatives considered:
+  - Console-only logs: risks mixing telemetry into stdout; harder to persist.
+
+### 11) Internal event model (streaming + tools)
+
+- Decision: Define a stable internal event model for streaming (`TextDelta`, `Activity`, `ToolCall`, `ToolResult`, `PhaseChanged`, `Error`) and adapt whatever Copilot SDK emits into these events.
+- Rationale: Keeps the CLI deterministic and testable even if underlying SDK event shapes change; enables fakes to drive the `ConversationLoop` in tests.
+- Alternatives considered:
+  - Binding tests directly to SDK event shapes: couples tests to external library details and increases brittleness.
+
+### 12) `status` output contract
+
+- Decision: `sofia status --json` outputs `{ sessionId, phase, status, updatedAt, nextAction }` as the stable minimum.
+- Rationale: Enables scripting and CI checks; human mode stays concise.
+- Alternatives considered:
+  - Dumping full session JSON: violates “no raw SDK JSON / no overwhelming output” intent and risks leaking sensitive fields.
+
+### 13) MCP availability and degradation strategy
+
+- Decision: Treat all MCP integrations as optional at runtime; when unavailable, fall back to guided prompts + local scaffolding, while preserving the governed phase flow.
+- Rationale: Matches clarified requirement to keep working when GitHub MCP is down; keeps workshop usable offline/limited.
+- Alternatives considered:
+  - Hard-failing on missing MCP servers: breaks workshop continuity and violates graceful degradation.
+
+### 14) MCP runtime wiring (how the CLI uses MCP)
+
+- Decision: Load MCP server inventory from `.vscode/mcp.json` at runtime and connect using the MCP TypeScript SDK (`Client` + transports).
+- Rationale: Reuses the repo’s canonical MCP server list (WorkIQ, GitHub MCP, Microsoft Learn MCP, Context7, Playwright, Azure MCP) and keeps integrations consistent.
+- Implementation note: use `StdioClientTransport` for `command` servers (npx-based) and `StreamableHTTPClientTransport` for remote HTTP MCP servers.
+
+### 15) Web research in Discover (web search)
+
+- Decision: Provide a `web.search` tool callable by the Copilot SDK; implement it by calling an Azure AI Foundry agent with Bing Search tools configured.
+- Rationale: Uses a first-party, well-supported Bing Search integration as recommended for grounding agents; keeps the CLI thin and lets the Foundry agent orchestrate search.
+- Degradation: if the Foundry agent is not configured or fails, fall back to guided prompts requesting user-provided links/notes.