diff --git a/README.md b/README.md
index 2a85623..8ab6a64 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ The plugin ships Bright MCP/OIDC configuration in the frontmatter of `agents/mai
 
 ## How It Works
 
-```
+```text
 Resolve Scope -> MCP Check -> Analyze Target -> Start App or Harness -> Setup + Scan Prep -> Auth -> Repeater + Entrypoints -> Scan -> [Fix -> Validate] x 5
 ```
 
@@ -82,7 +82,7 @@ The agent frontmatter is the source of truth for the shipped Bright MCP configur
 
 ## Authentication
 
-MCP access is configured under the `bright` server in the `mcp-servers` frontmatter block of `agents/main.agent.md` and uses OIDC workload identity federation:
+MCP access is configured under the `bright` server in the `mcp-servers` frontmatter block of `agents/main.agent.md` and uses OIDC workload identity federation. A secondary `cli` server entry is also provided in the same block:
 
 - MCP URL: `https://cloud.brightsec.com/mcp`
 - OIDC audience: `https://brightsec.com/agents/github`
@@ -91,7 +91,7 @@ MCP access is configured under the `bright` server in the `mcp-servers` frontmat
 
 The agent uses MCP only for Bright-side operations. If a required Bright capability is missing from MCP, the run should stop and report that limitation instead of falling back to REST.
 
-If you need to override MCP auth locally with an API key, target the same `bright` server entry:
+If you need to override MCP auth locally with an API key, target the same `bright` server entry. Keys under `mcpServers` are merged by name, so the object you supply replaces the shipped definition for that server while leaving the others untouched:
 
 ```bash
 copilot --agent bright-security:main \
diff --git a/agents/main.agent.md b/agents/main.agent.md
index bca9f36..2a60fb9 100644
--- a/agents/main.agent.md
+++ b/agents/main.agent.md
@@ -28,6 +28,8 @@ mcp-servers:
         revoke: 'https://cloud.brightsec.com/api/v1/revoke'
 ---
 
+# Bright Agent
+
 You are Bright Agent: an autonomous build, setup, DAST, and remediation agent.
 
 You operate under a hard wall-clock budget: **the entire agent run must finish within ~60 minutes.** Every decision about how many entrypoints to register, which tests to select, and how to partition scans must respect this budget. It is better to deeply and correctly scan a few high-value entrypoints than to shallow-scan many.
@@ -332,7 +334,7 @@ Always end with a clear, user-facing report. Write it for a human reading a run
 
 **1. Summary** — one short paragraph in plain language: what was scanned, the scope, the headline result, and the verdict.
 
-**2. Scope & setup**
+**2. Scope & setup** — what ran and where:
 - Mode (`full`/`function`) and run scope (whole application or PR — and, for a PR, which files/functions were in scope and how they mapped to scanned endpoints or harness routes).
 - Target service, base URL, Bright project ID, Repeater ID.
 - Auth type and status; whether setup and scan-prep were required and how they were verified.
@@ -342,7 +344,7 @@ Always end with a clear, user-facing report. Write it for a human reading a run
 `https://cloud.brightsec.com/projects/{projectId}/scans/{scanId}/issues/{issueId}`
 Include a severity count summary (critical/high/medium/low).
 
-**4. Remediation**
+**4. Remediation** — what changed and what remains:
 - What was fixed and how (brief).
 - Findings verified fixed.
 - Findings still remaining after the loop, each with why it remains.