sofia-cli 0.1.1

package/specs/005-ai-search-deploy/data-model.md

@@ -0,0 +1,130 @@
+# Data Model: AI Foundry Search Service Deployment
+
+**Feature**: 005-ai-search-deploy  
+**Date**: 2026-03-01
+
+## Entities
+
+### 1. FoundryDeploymentConfig
+
+Configuration for the Bicep deployment. Captured as Bicep parameters and passed via the deployment script.
+
+| Field | Type | Required | Default | Constraints | Notes |
+|-------|------|----------|---------|-------------|-------|
+| `subscriptionId` | string | yes | — | Valid Azure subscription GUID | From `az account show` or user input |
+| `resourceGroupName` | string | yes | — | 1-90 chars, alphanumeric + `-_.()`  | Auto-created if missing (FR-002) |
+| `location` | string | no | `swedencentral` | Valid Azure region with Agent Service | FR-004 |
+| `accountName` | string | no | `sofia-foundry` | 2-64 chars, `^[a-zA-Z0-9][a-zA-Z0-9_.-]*$` | Used to derive `customSubDomainName` |
+| `projectName` | string | no | `sofia-project` | 2-64 chars | Child of account |
+| `modelDeploymentName` | string | no | `gpt-4.1-mini` | Valid model deployment name | FR-012 |
+| `modelName` | string | no | `gpt-4.1-mini` | Must support `web_search_preview` | See research.md R3 |
+| `modelVersion` | string | no | `2025-04-14` | Valid model version | Pinned for reproducibility |
+| `modelSkuName` | string | no | `GlobalStandard` | `GlobalStandard` or `Standard` | GlobalStandard for broadest availability |
+| `modelSkuCapacity` | int | no | `1` | ≥1 (TPM in thousands) | Sufficient for workshop usage |
+
+### 2. FoundryDeploymentOutput
+
+Output produced by the deployment script. Used to configure the sofIA CLI.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `projectEndpoint` | string | Foundry project endpoint URL (e.g., `https://<name>.services.ai.azure.com/api/projects/<project>`) |
+| `modelDeploymentName` | string | Model deployment name (e.g., `gpt-4.1-mini`) |
+| `resourceGroupName` | string | Resource group containing the deployment (for teardown) |
+| `accountName` | string | Foundry account name |
+
+### 3. WebSearchConfig (updated)
+
+Runtime configuration for the `web.search` Copilot SDK tool. Replaces the current `WebSearchConfig` interface in `src/mcp/webSearch.ts`.
+
+| Field | Type | Required | Source | Notes |
+|-------|------|----------|--------|-------|
+| `projectEndpoint` | string | yes | `FOUNDRY_PROJECT_ENDPOINT` env var | Replaces `endpoint` |
+| `modelDeploymentName` | string | yes | `FOUNDRY_MODEL_DEPLOYMENT_NAME` env var | New field |
+
+**Removed fields** (from current `WebSearchConfig`):
+- `endpoint` → replaced by `projectEndpoint`
+- `apiKey` → eliminated (using `DefaultAzureCredential`)
+- `fetchFn` → eliminated (using SDK, not raw fetch)
+
+### 4. AgentSession
+
+Internal state for the ephemeral web search agent, managed within `webSearch.ts`. Not persisted — exists only in memory during a CLI session.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `client` | `AIProjectClient` | yes | Created once per session |
+| `openAIClient` | OpenAI client ref | yes | From `client.getOpenAIClient()` |
+| `agentName` | string | yes | Agent name (e.g., `sofia-web-search`) |
+| `agentVersion` | string | yes | Version returned by `createVersion()` |
+| `conversationId` | string | yes | Thread/conversation for message exchange |
+| `initialized` | boolean | yes | Tracks lazy initialization state |
+
+**State transitions**:
+```
+[Uninitialized] → (first web.search call) → [Initialized] → (session end / error) → [Cleaned Up]
+```
+
+- **Uninitialized → Initialized**: On first `web.search` call, creates `AIProjectClient`, agent, and conversation.
+- **Initialized → Cleaned Up**: On `destroyWebSearchSession()` call or `process.beforeExit`, deletes conversation and agent version.
+- If cleanup fails, log warning but do not throw — stale agents will be cleaned up manually or by TTL.
+
+### 5. WebSearchResult (unchanged)
+
+The existing `WebSearchResult` interface remains structurally identical but gains citation data from `url_citation` annotations.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `results` | `WebSearchResultItem[]` | yes | Structured search results |
+| `sources` | `string[]` | no | Deduplicated citation URLs (FR-014) |
+| `degraded` | boolean | no | `true` if Foundry unavailable/error |
+| `error` | string | no | Error message when degraded |
+
+### 6. WebSearchResultItem (updated)
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `title` | string | yes | Page title (extracted from citation or response) |
+| `url` | string | yes | Source URL from `url_citation` annotation |
+| `snippet` | string | yes | Relevant text excerpt |
+
+### 7. LegacyEnvVarError
+
+Not a data model entity but a specific error condition (FR-016).
+
+| Condition | Action |
+|-----------|--------|
+| `SOFIA_FOUNDRY_AGENT_ENDPOINT` is set | Emit error: "Legacy env var detected. Migrate to FOUNDRY_PROJECT_ENDPOINT. See docs/environment.md" |
+| `SOFIA_FOUNDRY_AGENT_KEY` is set | Emit error: "Legacy env var detected. API key auth is no longer used. See docs/environment.md" |
+
+Checked during preflight (`preflight.ts`). Fails the preflight check with `required: true`.
+
+## Relationships
+
+```
+FoundryDeploymentConfig ──(deploys to)──> Azure Resources
+                                              │
+                                              ├── Foundry Account
+                                              │     ├── Model Deployment
+                                              │     └── Account Capability Host
+                                              └── Foundry Project
+                                                    └── Project Capability Host
+
+FoundryDeploymentOutput ──(configures)──> WebSearchConfig (runtime)
+                                              │
+                                              └── AgentSession (lazy, in-memory)
+                                                    │
+                                                    ├── AIProjectClient
+                                                    ├── Agent (ephemeral)
+                                                    └── Conversation
+                                                          │
+                                                          └── WebSearchResult + citations
+```
+
+## Validation Rules
+
+1. **`projectEndpoint`** must match pattern: `https://*.services.ai.azure.com/api/projects/*`
+2. **`modelDeploymentName`** must be non-empty string, no whitespace
+3. **Legacy env vars**: Presence of `SOFIA_FOUNDRY_AGENT_ENDPOINT` or `SOFIA_FOUNDRY_AGENT_KEY` is a hard error (FR-016)
+4. **Bicep parameters**: `accountName` must be unique within the resource group; `customSubDomainName` must be globally unique
+5. **Agent cleanup**: Must attempt cleanup even on error; log warnings but do not throw on cleanup failure

package/specs/005-ai-search-deploy/plan.md

@@ -0,0 +1,93 @@
+# Implementation Plan: AI Foundry Search Service Deployment
+
+**Branch**: `005-ai-search-deploy` | **Date**: 2026-03-01 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/005-ai-search-deploy/spec.md`
+
+## Summary
+
+Provide one-command deployment of Azure AI Foundry infrastructure (account, project, model deployment) via Bicep + shell script, and migrate the sofIA CLI's `web.search` tool from raw HTTP + API key (`SOFIA_FOUNDRY_AGENT_ENDPOINT`/`SOFIA_FOUNDRY_AGENT_KEY`) to the `@azure/ai-projects` SDK with `DefaultAzureCredential` auth and ephemeral `web_search_preview` agents. Includes teardown, prerequisite validation, and clean-break migration from legacy env vars.
+
+## Technical Context
+
+**Language/Version**: Node.js 20 LTS + TypeScript 5.3, Bash (deployment scripts), Bicep (IaC)  
+**Primary Dependencies**: `@github/copilot-sdk ^0.1.28`, `@azure/ai-projects` (new), `@azure/identity` (new), `dotenv` (new), `zod ^4.3.6`  
+**Storage**: N/A (stateless infrastructure provisioning; session state handled by existing `SessionStore`)  
+**Testing**: Vitest 4.x (unit + integration), TDD Red→Green→Review per constitution  
+**Target Platform**: CLI — Linux, macOS, Windows (WSL/Git Bash); Azure for infrastructure deployment  
+**Project Type**: CLI tool + Infrastructure-as-Code  
+**Performance Goals**: Web search query returns grounded results with citations within 10 seconds (SC-003)  
+**Constraints**: Deploy completes in <15 minutes (SC-001); teardown in <10 minutes (SC-004); agent lifecycle is ephemeral (created/deleted per CLI session)  
+**Scale/Scope**: Workshop/PoC usage — small number of queries per session; single resource group deployment
+
+## 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**: ✅ PASS — Deploys the web search backend that enables real-time company/industry research during the Discover phase (Step 1). Directly ties to the workshop's core value: grounding ideation in real-world context.
+- **Secure-by-default**: ✅ PASS — Migrates from API key auth (`SOFIA_FOUNDRY_AGENT_KEY`) to `DefaultAzureCredential` (least privilege, no secrets in env vars). Legacy key vars trigger an error, not silent fallback. Logger redaction remains.
+- **Node.js + TypeScript**: ✅ PASS — CLI integration uses `@azure/ai-projects` + `@azure/identity` TypeScript SDKs. Bicep + Bash for infrastructure only (not runtime code).
+- **MCP-first**: ⚠️ EXCEPTION — The Foundry Agent Service does not expose an MCP server; the `@azure/ai-projects` SDK is the only supported integration surface. The tool is still registered as a Copilot SDK tool (`web.search`) and used by MCP-aware phases. Documented in Complexity Tracking.
+- **Test-first (NON-NEGOTIABLE)**: ✅ PASS — All SDK integration code must follow Red→Green→Review. Unit tests for config validation, credential detection, and migration error. Integration tests with fakes for agent create/query/delete lifecycle. Bash deployment script validated via dry-run tests.
+- **CLI transparency**: ✅ PASS — Deployment script streams progress (`az deployment` output, prerequisite check results, resource provisioning status). CLI surfaces web search availability/degradation to user. Teardown confirms resource deletion.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/005-ai-search-deploy/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+│   └── web-search-tool.md
+└── tasks.md             # Phase 2 output (created by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+infra/                          # NEW — Infrastructure-as-Code
+├── main.bicep                  # Subscription-scoped entry point (resource group + module)
+├── resources.bicep             # Resource-group-scoped module (account, model, project, capability hosts)
+├── main.bicepparam             # Default parameters (swedencentral, gpt-4.1-mini)
+├── deploy.sh                   # One-command deployment script (FR-002), writes .env (FR-018)
+└── teardown.sh                 # Resource group deletion (FR-007)
+
+src/
+├── mcp/
+│   └── webSearch.ts            # MODIFIED — Migrate from raw HTTP + API key
+│                               #   to @azure/ai-projects SDK + DefaultAzureCredential
+│                               #   + ephemeral agent lifecycle (create/query/delete)
+├── cli/
+│   ├── envLoader.ts            # NEW — Loads .env file at startup via dotenv (FR-017)
+│   ├── index.ts                # MODIFIED — Calls loadEnvFile() at startup
+│   └── preflight.ts            # MODIFIED — Add legacy env var detection check (FR-016)
+├── shared/
+│   └── copilotClient.ts        # UNCHANGED — ToolDefinition interface still used
+└── develop/
+    └── mcpContextEnricher.ts   # MODIFIED — Update isWebSearchConfigured() import
+
+docs/
+└── environment.md              # MODIFIED — Update env var documentation
+
+tests/
+├── unit/
+│   ├── webSearch.spec.ts       # NEW — Config validation, credential auth, migration error
+│   └── infraDeploy.spec.ts     # NEW — Deploy script parameter validation (dry-run)
+└── integration/
+    └── webSearchAgent.spec.ts  # NEW — Ephemeral agent lifecycle with fakes
+```
+
+**Structure Decision**: Single project layout (Option 1) with a new `infra/` directory at the repository root for Bicep templates and deployment scripts. This follows Azure conventions and keeps infrastructure separate from application code. The `src/mcp/webSearch.ts` module is modified in-place (not moved) since it already has the correct responsibility boundary.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation                                                     | Why Needed                                                                                                                                                                                 | Simpler Alternative Rejected Because                                                                               |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| MCP-first exception: direct SDK call to Foundry Agent Service | Azure AI Foundry Agent Service has no MCP server; `@azure/ai-projects` is the only supported client SDK. The tool is still exposed as a Copilot SDK tool and consumed by MCP-aware phases. | No MCP adapter exists for this service. Writing a custom MCP proxy would add complexity with no ecosystem benefit. |

package/specs/005-ai-search-deploy/quickstart.md

@@ -0,0 +1,96 @@
+# Quickstart: AI Foundry Search Service Deployment
+
+**Feature**: 005-ai-search-deploy  
+**Date**: 2026-03-01
+
+## Prerequisites
+
+- **Azure CLI** installed and logged in (`az login`)
+- **Azure subscription** with Owner or Contributor permissions
+- **Node.js 20+** for running the sofIA CLI
+- **Bash shell** (Linux, macOS, or Windows WSL/Git Bash)
+
+## 1. Deploy the Infrastructure
+
+```bash
+# From the repository root (uses your current az CLI subscription)
+./infra/deploy.sh --resource-group sofia-workshop-rg
+```
+
+This provisions:
+
+- Azure AI Foundry account with SystemAssigned managed identity
+- Model deployment (`gpt-4.1-mini` by default)
+- Foundry project with Agent Service capability enabled
+
+**Customize** (optional):
+
+```bash
+./infra/deploy.sh \
+  --resource-group sofia-workshop-rg \
+  --subscription <id> \
+  --location eastus \
+  --account-name my-foundry \
+  --model gpt-4o-mini
+```
+
+## 2. Configure sofIA
+
+After deployment, the script automatically writes the required environment variables to a `.env` file in the workspace root:
+
+```bash
+FOUNDRY_PROJECT_ENDPOINT="https://sofia-foundry-abc123.services.ai.azure.com/api/projects/sofia-project"
+FOUNDRY_MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
+```
+
+The sofIA CLI loads this `.env` file automatically at startup — no manual configuration needed.
+
+> **Note**: No API key needed. sofIA authenticates using your Azure login credentials (`az login`).
+
+## 3. Verify Web Search
+
+Start a sofIA workshop session:
+
+```bash
+sofia workshop --new-session
+```
+
+During the **Discover** phase, describe a real company. sofIA will automatically invoke the `web.search` tool to research the company, its competitors, and industry trends. Search results include clickable source URLs.
+
+## 4. Teardown (When Done)
+
+```bash
+./infra/teardown.sh --resource-group sofia-workshop-rg
+```
+
+This deletes the resource group and all contained Azure resources to stop billing.
+
+## Migrating from Legacy Configuration
+
+If you previously used `SOFIA_FOUNDRY_AGENT_ENDPOINT` / `SOFIA_FOUNDRY_AGENT_KEY`:
+
+1. **Remove** the old variables from your environment
+2. **Set** the new variables (`FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_DEPLOYMENT_NAME`)
+3. **Ensure** you are logged in via `az login`
+
+The CLI will display an error if it detects the old variables, guiding you through the migration.
+
+## Troubleshooting
+
+| Symptom                                  | Cause                                | Fix                                                                                                       |
+| ---------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| "Web search not configured"              | Env vars not set                     | Set `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME`                                        |
+| "Azure authentication failed"            | Not logged in or token expired       | Run `az login`                                                                                            |
+| "Legacy web search env vars detected"    | Old `SOFIA_FOUNDRY_*` vars still set | Remove them, set new vars                                                                                 |
+| Deploy fails: "subscription not found"   | Wrong subscription selected          | Run `az account set --subscription <id>`                                                                  |
+| Deploy fails: "insufficient permissions" | Not Owner/Contributor                | Ask an admin to grant access                                                                              |
+| Web search returns no results            | Model didn't use web search          | This is normal — the model decides when to search                                                         |
+| "Web search disabled at subscription"    | Admin blocked the tool               | Run `az feature unregister --name OpenAI.BlockedTools.web_search --namespace Microsoft.CognitiveServices` |
+
+## Cost Expectations
+
+- **Foundry account**: Free (billing is per-usage)
+- **Model deployment**: Pay-per-token for `gpt-4.1-mini` queries
+- **Grounding with Bing Search**: Usage-based ([pricing](https://www.microsoft.com/bing/apis/grounding-pricing))
+- **Typical workshop**: A few dozen web search queries — minimal cost
+- **Teardown immediately after workshop** to avoid idle resource charges

package/specs/005-ai-search-deploy/research.md

@@ -0,0 +1,187 @@
+# Research: AI Foundry Search Service Deployment
+
+**Feature**: 005-ai-search-deploy  
+**Date**: 2026-03-01  
+**Status**: Complete — all NEEDS CLARIFICATION items resolved
+
+## R1: Azure AI Foundry Bicep Resource Types
+
+**Decision**: Use `Microsoft.CognitiveServices` resource provider (API version `2025-06-01`) with 5 resources for the basic agent setup.
+
+**Rationale**: The basic (Microsoft-managed) setup minimizes complexity — no BYO Storage, Key Vault, Cosmos DB, or AI Search needed. Microsoft manages these behind the scenes. This aligns with FR-008 (basic agent setup) and the workshop/PoC use case.
+
+**Required Resources**:
+
+| # | Bicep Resource Type | Purpose |
+|---|---------------------|---------|
+| 1 | `Microsoft.CognitiveServices/accounts` (kind: `AIServices`) | Foundry account with `allowProjectManagement: true` and `customSubDomainName` |
+| 2 | `Microsoft.CognitiveServices/accounts/deployments` | Model deployment (default: `gpt-4.1-mini`, version `2025-04-14`, SKU `GlobalStandard`) |
+| 3 | `Microsoft.CognitiveServices/accounts/projects` | Foundry project — provides the endpoint URL |
+| 4 | `Microsoft.CognitiveServices/accounts/capabilityHosts` | Account-level capability host (`capabilityHostKind: 'Agents'`) |
+| 5 | `Microsoft.CognitiveServices/accounts/projects/capabilityHosts` | Project-level capability host (basic setup = empty connections) |
+
+**Alternatives considered**:
+- **Azure Verified Module (`br/public:avm/ptn/ai-ml/ai-foundry`)**: Less transparent, harder to document each resource per FR-011. Rejected for PoC simplicity.
+- **Standard agent setup (BYO resources)**: Requires Cosmos DB, Storage, Key Vault, AI Search, multiple role assignments. Over-engineered for workshop scenario.
+
+**Gotchas**:
+- `customSubDomainName` is mandatory and must be globally unique — generate with a suffix (e.g., `sofia-<uniqueString>`)
+- `allowProjectManagement: true` is required for child projects
+- Capability hosts cannot be updated after creation; must delete and recreate
+- Account capability host must be created before project capability host (`dependsOn`)
+- Model deployment must exist before the account capability host references it
+
+## R2: Model Deployment Configuration
+
+**Decision**: Default to `gpt-4.1-mini` with `GlobalStandard` SKU, version `2025-04-14`.
+
+**Rationale**: `gpt-4.1-mini` supports `web_search_preview` and is cost-effective for workshop scenarios. `GlobalStandard` SKU routes to the nearest available region, providing the broadest availability. The spec (FR-012) explicitly requires `gpt-4.1-mini` as default.
+
+**Alternatives considered**:
+- **`gpt-4.1`**: More capable but higher cost. Unnecessary for web search query routing.
+- **`gpt-4o-mini`**: Also supported but `gpt-4.1-mini` is newer and matches the spec decision.
+- **`Standard` SKU**: Regional-only deployment; model must be available in the exact account region. More restrictive than `GlobalStandard`.
+
+## R3: `web_search_preview` Region and Model Support
+
+**Decision**: No region restrictions — `web_search_preview` is available in all 23 Agent Service regions, including `swedencentral`.
+
+**Rationale**: Research confirms web search is universally available across all Agent Service regions. No deployment script region validation needed beyond basic AI Services availability.
+
+**Supported model families**: gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o3, o4-mini, o3-mini, o1, gpt-5. Notably NOT supported: DeepSeek, Llama, Grok.
+
+## R4: @azure/ai-projects SDK Integration Pattern
+
+**Decision**: Use `@azure/ai-projects@beta` (v2.x preview) with `AIProjectClient`, `agents.createVersion()`, and OpenAI-style `responses.create()` pattern.
+
+**Rationale**: This is the current official SDK documented at learn.microsoft.com for the Foundry Agent Service. It replaces the older `@azure/ai-agents` package and provides a unified API for agent lifecycle management.
+
+**Key API Pattern**:
+
+```typescript
+import { DefaultAzureCredential } from "@azure/identity";
+import { AIProjectClient } from "@azure/ai-projects";
+
+// 1. Create client
+const project = new AIProjectClient(endpoint, new DefaultAzureCredential());
+const openAIClient = await project.getOpenAIClient();
+
+// 2. Create ephemeral agent with web search
+const agent = await project.agents.createVersion("sofia-web-search", {
+  kind: "prompt",
+  model: deploymentName,
+  instructions: "You are a web search assistant...",
+  tools: [{ type: "web_search_preview" }],
+});
+
+// 3. Create conversation, send message, get response
+const conversation = await openAIClient.conversations.create();
+const response = await openAIClient.responses.create(
+  { conversation: conversation.id, input: query },
+  { body: { agent: { name: agent.name, type: "agent_reference" } } },
+);
+
+// 4. Extract citations
+for (const item of response.output) {
+  if (item.type === "message") {
+    for (const content of item.content) {
+      if (content.type === "output_text" && content.annotations) {
+        for (const annotation of content.annotations) {
+          if (annotation.type === "url_citation") {
+            // { url, start_index, end_index }
+          }
+        }
+      }
+    }
+  }
+}
+
+// 5. Cleanup
+await openAIClient.conversations.delete(conversation.id);
+await project.agents.deleteVersion(agent.name, agent.version);
+```
+
+**Alternatives considered**:
+- **`@azure/ai-agents` (classic API)**: Older `AgentsClient` with threads/runs pattern. Still works but being superseded by `AIProjectClient`.
+- **Raw HTTP POST (current pattern)**: Requires manual token management, no built-in credential chain. Rejected for security and maintainability.
+
+## R5: Authentication Migration
+
+**Decision**: Replace API key auth (`SOFIA_FOUNDRY_AGENT_KEY`) with `DefaultAzureCredential` from `@azure/identity`.
+
+**Rationale**: `DefaultAzureCredential` provides a credential chain that automatically discovers the best available credential (Azure CLI → Managed Identity → Environment). Eliminates secrets from environment variables. Aligns with FR-013 and the secure-by-default constitution principle.
+
+**Credential chain order** (what `DefaultAzureCredential` tries):
+1. `EnvironmentCredential` (`AZURE_CLIENT_ID` + `AZURE_TENANT_ID` + `AZURE_CLIENT_SECRET`)
+2. `WorkloadIdentityCredential` (Kubernetes)
+3. `ManagedIdentityCredential` (Azure-hosted)
+4. `AzureDeveloperCliCredential` (`azd auth login`)
+5. `AzureCliCredential` (`az login`)
+6. `AzurePowerShellCredential` (`Connect-AzAccount`)
+
+**Required RBAC role**: `Azure AI User` at the Foundry project scope.
+
+**Environment variables (new)**:
+- `FOUNDRY_PROJECT_ENDPOINT` — e.g. `https://<name>.services.ai.azure.com/api/projects/<project>`
+- `FOUNDRY_MODEL_DEPLOYMENT_NAME` — e.g. `gpt-4.1-mini`
+
+**Migration behavior** (FR-016): If legacy `SOFIA_FOUNDRY_AGENT_ENDPOINT` or `SOFIA_FOUNDRY_AGENT_KEY` are detected, CLI emits an error message with migration instructions. Old vars are never used.
+
+## R6: Deployment Script Design
+
+**Decision**: Bash script (`deploy.sh`) wrapping `az deployment sub create` for subscription-level Bicep deployment, with prerequisite validation.
+
+**Rationale**: Bash is portable across Linux, macOS, and WSL/Git Bash (FR-010). Subscription-level deployment is needed because the script auto-creates the resource group (FR-002). `az deployment sub create` handles this natively.
+
+**Script flow**:
+1. Validate prerequisites: `az` CLI installed, user logged in, subscription accessible
+2. Accept parameters: subscription ID, resource group name, region (default: `swedencentral`), account name, model (default: `gpt-4.1-mini`)
+3. Generate unique subdomain name from account name
+4. Run `az deployment sub create` with Bicep template
+5. Query outputs: project endpoint URL, model deployment name
+6. Print configuration instructions for `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL_DEPLOYMENT_NAME`
+
+**Teardown script** (`teardown.sh`):
+1. Accept resource group name
+2. Validate resource group exists (informational exit if not)
+3. Run `az group delete --yes --no-wait` for non-blocking deletion
+
+## R7: Copilot SDK Tool Registration
+
+**Decision**: Keep the existing `web.search` tool name and `ToolDefinition` interface. The handler function internally calls the Foundry Agent Service SDK instead of raw HTTP.
+
+**Rationale**: The Copilot SDK tool contract (tool name, parameters, handler signature) is unchanged — only the implementation behind `createWebSearchTool()` changes. This maintains backward compatibility with prompt references (`discover.md`, `develop.md`) and the `mcpContextEnricher.ts` integration.
+
+**Integration pattern**: The `createWebSearchTool()` factory creates the `AIProjectClient` and an ephemeral agent on first call. The agent and conversation are reused for the session lifetime. On session end (or error), the agent and conversation are cleaned up.
+
+**Alternatives considered**:
+- **Create agent per query**: Too expensive — agent creation has latency. Rejected.
+- **Persistent agent (not deleted)**: Would accumulate agents in the Foundry project. Rejected per FR-015 (ephemeral lifecycle).
+- **Lazy initialization**: Agent created on first `web.search` call, not on session start. This avoids agent creation overhead when web search is never invoked. **This is the chosen pattern** — create lazily, delete on session end.
+
+## R8: Ephemeral Agent Lifecycle
+
+**Decision**: Lazy creation on first web search call, automatic deletion on process exit or session end.
+
+**Rationale**: Creating the agent at session start adds unnecessary latency if web search is never used. Creating on first call amortizes the cost and ensures cleanup happens reliably.
+
+**Implementation**:
+- `webSearch.ts` maintains a module-level `AgentSession` (agent ID, conversation ID, client references)
+- First call to `web.search` handler triggers `AgentSession.initialize()` — creates agent + conversation
+- Subsequent calls reuse the same agent and conversation
+- `AgentSession.cleanup()` deletes the conversation and agent version
+- Register cleanup via `process.on('beforeExit', ...)` and expose a `destroyWebSearchSession()` for explicit cleanup from the workshop command
+
+## R9: New Dependencies Impact
+
+**Decision**: Add `@azure/ai-projects@beta` and `@azure/identity` as production dependencies.
+
+**Impact assessment**:
+- `@azure/identity` is well-maintained (v4.13.0+), widely used, no known security issues
+- `@azure/ai-projects@beta` is in preview — API may change. Pin to a specific beta version for stability
+- Both are tree-shakeable ESM packages
+- No conflicting peer dependencies with existing packages (`commander`, `zod`, `pino`, etc.)
+- TypeScript types are included in both packages
+
+**Alternatives considered**:
+- **Optional dependencies**: Would complicate the build. Since web search is a core workshop tool, these should be required dependencies.