# Architecture

## Overview

This repository is the canonical source of truth for shared Copilot resources.
It separates reusable workflows from tool-specific adapters and keeps propagation
Git-based after a resource is published.

## Layers

- `resources/skills/`: portable workflows for VS Code, Copilot CLI, and cloud agents
- `resources/prompts/`: VS Code slash-command adapters
- `resources/instructions/`: shared instruction packs
- `resources/agents/`: shared custom agents for local chat and overlays
- `resources/hooks/`: shared hook definitions
- `config/mcp/`: tracked MCP templates and example machine-local overrides
- `install/merge-managed-mcp-config.mjs`: managed MCP merge and prune logic for user config files
- `install/mcp/`: wrapper scripts for MCP servers that need runtime adaptation
- `templates/repo-overlay/`: files that can be copied into another repository for
  repository-scoped behavior

## Discovery Model

Bootstrap prefers linking default discovery paths back to this repository:

- `~/.copilot/skills` -> `resources/skills`
- `~/.copilot/agents` -> `resources/agents`
- `~/.copilot/instructions` -> `resources/instructions`
- `~/.copilot/hooks` -> `resources/hooks`
- VS Code user prompts directory -> `resources/prompts`

This keeps the repository authoritative while still using default discovery
locations whenever possible.

For MCP, bootstrap uses generated user-level config instead of links:

- VS Code user `mcp.json`
- Copilot CLI user `~/.copilot/mcp-config.json`

Those generated files come from tracked templates plus machine-local data in
`.local/mcp.local.jsonc`.

## Propagation Model

There are only two supported creation paths:

- repo-first
- local-first followed by publish-to-repo

Once a resource lands in the repository, commit and push it. Other systems pick
it up through `install/update.*` or future scheduled sync.

Managed MCP propagation follows the same rule, but with a split between shared
and local inputs:

- Shared defaults and server definitions are tracked in the repo
- Machine-local secrets and enablement stay in `.local/`
- `install/update.*` pulls the repo and reruns bootstrap so the generated MCP
  files refresh from the latest templates on every machine