From 0244bf70b5e749bc7e2eb913f28934509c5c20d3 Mon Sep 17 00:00:00 2001
From: Alicja Gilderdale <alicja-gilderdale@users.noreply.github.com>
Date: Tue, 21 Jul 2026 16:43:45 +0100
Subject: [PATCH] Add agent icon authoring guidance to architect

The modern CLI-authoring template picks up icon.png from the project
root during pac copilot push and encodes it as iconBase64 in the
compiled bot definition. The architect's current guidance does not
mention this convention, so architect-authored agents ship with the
generic default icon and makers have to upload one via the UI.

This change adds a dedicated 'Agent Icon' section to
agents/copilot-studio-architect.md documenting:

- the on-disk convention: icon.png at project root (not assets/)
- 192x192 PNG format
- server-side encoding as iconBase64 in botdefinition.json
- pull/push round-trip behaviour

Verified round-trip: uploaded a custom icon via the Copilot Studio UI,
pac copilot pull emitted icon.png at the project root (3.4 KB), and the
compiled botdefinition.json contained a 5,037-char iconBase64 field.
Placing icon.png under assets/ is silently ignored.
---
 agents/copilot-studio-architect.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/agents/copilot-studio-architect.md b/agents/copilot-studio-architect.md
index d62305a..1c027b2 100644
--- a/agents/copilot-studio-architect.md
+++ b/agents/copilot-studio-architect.md
@@ -152,6 +152,30 @@ configuration:
 
 Keep existing model, recognizer, authentication, channels, language, template, `displayName`, and `schemaName` unless the describer report or user explicitly requires a supported change. Supported modern model series include `GPT5Chat`, `GPT55Chat`, `Sonnet46`, and `Opus47`.
 
+## Agent Icon
+
+Copilot Studio agents surface an icon in the M365 Copilot picker, the Copilot Studio agent list, and the agent's chat surface. The default icon is a generic placeholder — customer-facing agents should ship with a custom icon.
+
+Author the icon as a PNG file at the **project root**, filename `icon.png`:
+
+```text
+<target-agent>/
+├── settings.mcs.yml
+├── agent.sync.yaml
+├── icon.png            <-- 192x192 PNG, agent icon, applied automatically on push
+├── behaviors/
+├── capabilities/
+└── .mcs/
+```
+
+Rules:
+
+- File name must be exactly `icon.png`, at the project root. Files under `assets/` are ignored by the icon-detection convention.
+- PNG format, 192x192 recommended. Larger sizes are accepted but downscaled.
+- On `pac copilot push`, the file is encoded as `iconBase64` in the compiled bot definition and applied to the agent identity server-side.
+- On `pac copilot pull`, the server serialises the current icon back to `icon.png` at the project root; do not check that file into source control if it is expected to change through the UI.
+- Do not reference the icon in `settings.mcs.yml` — as of the current schema there is no YAML property for it; the on-disk convention is the entire interface.
+
 ## Knowledge YAML
 
 Create knowledge only when the source has a concrete searchable source or local uploaded file.