docs: update agents documentation for dashboard v2 UI and sync changes

docs-web/user/dashboard/agents.md

@@ -26,10 +26,12 @@ Each preset is a card with avatar, name, label tags, and a one-line description.
 Click **+ New agent**. The form collects:
 
 - **Name** — required, unique within the project.
-- **System instructions (markdown)** — the persona prompt. This is *appended* to a base preface that ensures the agent knows it operates inside Code UX.
-- **Memory template override** — checkbox. When enabled, you can write a custom template that controls how `<project_memory>` and `<sprint_memory>` blocks render. Otherwise the project default is used.
+- **System instructions (markdown)** — the persona prompt. This is *appended* to a base preface that ensures the agent knows it operates inside Code UX. You can also include reusable Instruction Files.
+- **Memory template override** — checkbox. When enabled, you can write a custom template that controls how `<project_memory>` and `<sprint_memory>` blocks render via `Manage Memory`. Otherwise the project default is used.
+- **Knowledge Base** — Subscribe the agent to documents from the shared library.
+- **MCP Access** — Manage the agent's MCP tools access.
 - **Labels** — comma-separated tags (e.g. `planner`, `reviewer`, `migrator`).
-- **Avatar** — auto-generated (geometric/colour seed). Click **Re-roll** to regenerate.
+- **Avatar** — auto-generated (geometric/colour seed). You can customize it deeply using the avatar customizer.
 
 Save creates the preset and broadcasts a real-time event so connected clients refresh.
 
@@ -59,6 +61,10 @@ This makes agent presets first-class repository content — you can check them i
 
 Destructive. Requires confirmation. Threads and tasks that referenced the deleted preset fall back to the project default agent.
 
+## Instruction Files
+
+Instruction files are separate markdown documents that act as reusable prompt components. You can manage them with the Instruction Files editor and include them inside agent instructions.
+
 ## Routing presets to invocation types
 
 Where Code UX *uses* a preset is governed by the **invocation routing** settings (Settings → Routing). For each routing ID you can specify which provider config and (optionally) which agent preset is used:

docs/architecture/agent-preset-foundation.md

@@ -70,11 +70,11 @@ Foundation-supported fields:
 - optional per-agent memory injection configuration
 
 The memory injection configuration is stored in sqlite as `memory_config_json` and parsed back into `AgentMemoryConfig` on reads, matching the existing JSON-column pattern used by `mcp_access_json`.
-The dashboard editor now initializes that config from the preset, exposes it through a dedicated `Manage Memory` popover, and persists the chosen filters alongside the rest of the preset payload.
+The dashboard editor now initializes that config from the preset, exposes it through a dedicated `AgentMemoryConfigPanel` (Manage Memory popover), and persists the chosen filters alongside the rest of the preset payload.
 
 Agent labels are still stored in the data model for markdown sync and built-in preset conventions, but the dashboard no longer exposes custom label editing. The Agents page displays computed route-assignment tags from effective project settings instead, including tags for built-in fallback selections on Planning agent, Worker, Project manager, and Quality assurance agent.
 
-Built-in Worker and Project manager presets seed `mcp_access_json` with `code_ux` enabled and the default `playwright` custom MCP server linked. Planning and QA presets do not receive that link by default. Existing agents with a user-edited MCP access payload keep their selections; only newly imported/generated defaults or previously unconfigured built-in Worker/Project manager records receive the seeded link.
+Built-in Worker and Project manager presets seed `mcp_access_json` with `code_ux` enabled and the default `playwright` custom MCP server linked. Planning and QA presets do not receive that link by default. Existing agents with a user-edited MCP access payload keep their selections; only newly imported/generated defaults or previously unconfigured built-in Worker/Project manager records receive the seeded link. The dashboard exposes this configuration through the `AgentMcpManageModal`. Knowledge subscriptions are additionally configurable via the `AgentKnowledgePanel`, and instruction files are managed with `InstructionFileEditorPanel`.
 
 ## Dashboard Interaction Contract
 

docs/architecture/agent-sync-and-planning-agent.md

@@ -58,7 +58,7 @@ That means:
 - when project markdown mirroring is enabled, dashboard create/update writes the agent body into a project-local markdown file
 - mirrored project files use a filesystem-safe slug format such as `planning_agent.md`
 - editing a default or home-backed agent from the dashboard creates a project-local override file instead of modifying the default/home source
-- if the linked markdown file later differs from the DB copy, the agent is marked `out_of_sync`
+- if the linked markdown file later differs from the DB copy (including changes to memory settings, avatar config, or provider/model preferences), the agent is marked `out_of_sync`
 - the dashboard can re-import one agent or bulk-sync all out-of-sync project agents back into sqlite on demand
 - the dashboard can push `.code-ux/agents/*.md` back into git, either as a local commit, a commit plus branch push, or a feature-branch pull request into the default branch
 - when opening a pull request, Code UX resolves the effective dashboard GitHub/GitLab host tokens and forwards them to the PR service so repository-host authentication stays aligned with the current project settings
@@ -95,7 +95,7 @@ The API record also exposes derived sync state:
 
 - `manual`
 - `synced`
-- `out_of_sync`
+- `out_of_sync` (triggers when name, description, markdown, avatar config, provider, model, or memory config differs between the DB and the file)
 - `missing_source`
 
 When markdown does not include `avatarConfig`, Code UX still persists a resolved avatar before writing sqlite. Built-in base roles use curated defaults, while generated or custom project agents receive a deterministic random look seeded from project, agent, and label metadata. Project Setup Agent output goes through the same resolver, so generated specialist agents get a stable avatar that is mirrored into project markdown instead of being recalculated on every dashboard load.