🛠️ Update various documentation, scripts, and configuration templates to enhance clarity, functionality, and maintainability across the project

docs/architecture.md

@@ -13,6 +13,9 @@ Git-based after a resource is published.
 - `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
 
@@ -29,6 +32,14 @@ Bootstrap prefers linking default discovery paths back to this repository:
 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:
@@ -38,3 +49,11 @@ There are only two supported creation paths:
 
 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

docs/audit-workflow.md

@@ -0,0 +1,127 @@
+# Audit Workflow
+
+## Purpose
+
+The audit workflow reviews the last 30 days of persisted local Copilot
+artifacts and produces a shortlist of reusable patterns worth promoting into the
+shared Copilot resource repository.
+
+## Current Scope
+
+- macOS first
+- read-only audit execution
+- file-based review interface
+- local per-machine audit history stored inside the repo checkout but excluded
+  from git
+
+## Command
+
+```bash
+resources/scripts/audit-copilot-usage.sh --days 30
+```
+
+The runner excludes the current `copilot-resources` repo root from workspace
+indexing by default so you do not review patterns that already live in the
+shared repository.
+
+Optional filters:
+
+```bash
+resources/scripts/audit-copilot-usage.sh --days 14 --workspace copilot-resources
+```
+
+```bash
+resources/scripts/audit-copilot-usage.sh --days 30 --include-sources publish-log,repo-memories
+```
+
+```bash
+resources/scripts/audit-copilot-usage.sh --days 30 --exclude-workspace /path/to/another/repo
+```
+
+## Storage Model
+
+Audit runs are written under:
+
+```text
+.local/audits/<machine-id>/<timestamp>/
+```
+
+The runner creates the machine directory automatically on first use. The entire
+`.local/` tree is git-ignored so each machine can keep its own audit history
+without creating commit noise.
+
+## Inputs
+
+The first implementation reads from these local sources when they exist:
+
+- VS Code workspace transcripts under `~/Library/Application Support/Code/User/workspaceStorage/*/GitHub.copilot-chat/transcripts/`
+- Repo memories under `.../GitHub.copilot-chat/memory-tool/memories/repo/`
+- Shared resource publish history under `~/.copilot-resources-state/publish-log.tsv`
+
+## Outputs
+
+- `audit-summary.md` — high-level inventory and top candidates
+- `workspace-index.tsv` — workspaceStorage hash to workspace path mapping for the run
+- `candidates-report.tsv` — scored candidate list with source references plus transcript prompt-cost proxy columns such as `token_cost_signal`, `avg_prompt_chars`, and `repeated_prompt_chars`
+- `selection-manifest.tsv` — editable approval surface with `decision`, `review_note`, `detail_file`, and the same transcript prompt-cost proxy columns used during triage
+- `pattern-details/*.md` — per-candidate evidence bundles used during review, including purpose, expected benefit, audit context, score rationale, and caveats
+
+Transcript prompt-cost fields are character-count proxies derived from persisted
+user message text. They help surface repeated long prompts that are likely to be
+more expensive, but they are not exact billing-token measurements.
+
+## Selection Interface
+
+Use `selection-manifest.tsv` as the review surface and `pattern-details/*.md` as
+the one-by-one evidence bundle for each candidate.
+
+Inside Copilot, use the shared `review-audit-candidates` prompt to work through
+pending rows one at a time. That prompt should ask for a decision with buttons,
+capture optional freeform review notes, explain why the candidate exists and
+why it scored as it did, and update `selection-manifest.tsv` after each answer.
+
+Recommended decision states:
+
+- `promote-skill`
+- `promote-instruction`
+- `promote-agent`
+- `promote-hook`
+- `promote-script`
+- `promote-prompt`
+- `template-only`
+- `docs-only`
+- `discard`
+- `needs-sanitization`
+
+## Promotion Rule
+
+If a candidate cannot be explained as a portable skill, instruction, prompt
+adapter, agent behavior, hook, script, or template, it should stay in audit
+notes and not be promoted into the shared repo.
+
+## Follow-on Draft Generation
+
+After the manifest has approved rows, generate next-step artifacts with:
+
+```bash
+resources/scripts/prepare-audit-promotions.sh
+```
+
+Or target a specific run:
+
+```bash
+resources/scripts/prepare-audit-promotions.sh --audit-dir .local/audits/<machine-id>/<timestamp>
+```
+
+The command reads approved rows from `selection-manifest.tsv` and writes:
+
+- `draft-resources/` for straightforward prompt, instruction, agent, and skill drafts
+- `staging-notes/` for approved rows that still need manual design work
+- `promotion-summary.md` to summarize what was generated
+
+## Limits
+
+- This audits persisted local artifacts only.
+- It does not capture every inline completion or transient UI suggestion.
+- Windows parity is deferred until the macOS workflow and report format are
+  proven.

docs/authoring.md

@@ -10,6 +10,18 @@
 - Use an agent for a reusable persona with tool restrictions or handoffs.
 - Use a hook only when the behavior must be deterministic and enforced in code.
 
+## Keep Shared Resources Cheap
+
+- Reuse an existing shared resource before creating a new one.
+- Choose the cheapest sufficient primitive for the job instead of defaulting to
+  a long prompt.
+- Keep frontmatter, descriptions, and embedded examples concise.
+- Prefer targeted inputs such as a file, symbol, or command over broad repo
+  scans.
+- State the default output budget when the resource is meant to stay brief.
+- Say when the resource should not be used so it does not become a generic,
+  expensive fallback.
+
 ## Supported Creation Paths
 
 ### Repo-first

docs/git-bootstrap-hygiene.md

@@ -0,0 +1,59 @@
+# Git Bootstrap Hygiene
+
+## Purpose
+
+This guidance helps when a repository is being created, normalized, or cleaned
+up early in its life so temporary local material does not leak into shared Git
+history and the first committed shape of the repo is intentional.
+
+## Why This Matters
+
+Early repository mistakes tend to persist. Temporary import trees, scratch
+directories, local caches, and vendor copies are easy to commit accidentally
+when ignore rules and branch decisions are still unsettled. A small amount of
+bootstrap hygiene keeps those mistakes out of long-term history.
+
+## Core Guidance
+
+- Identify scratch, cache, vendor-copy, and other temporary paths before the
+  first shared commit and keep them untracked unless there is an explicit
+  decision to promote them.
+- Confirm the intended default branch before the first shared commit. Use the
+  project's branch policy when one exists; otherwise use a consistent default
+  such as `main`.
+- Make the first tracked commit only after the repository's ignore rules and
+  basic bootstrap layout reflect the intended long-term structure.
+- If temporary content later becomes real project content, move or regenerate it
+  into the correct tracked location instead of committing the original scratch
+  tree as-is.
+- Keep repo-specific exceptions in repo-local setup notes or docs instead of
+  putting one-off paths, hashes, or names into shared guidance.
+
+## Good Outcomes
+
+- The initial history starts from an intentional branch and file layout.
+- Local-only material stays local until it is deliberately promoted.
+- Repositories keep fewer one-off cleanup commits related to accidental early
+  tracking.
+- Shared guidance stays reusable because repo-specific details remain local.
+
+## What This Is Not
+
+- It is not a replacement for project-specific setup documentation.
+- It does not tell a team which branch policy to adopt; it only says to choose
+  that policy intentionally before the first shared commit.
+- It does not forbid generated or vendor content from being tracked when a
+  project intentionally relies on that model.
+
+## Typical Signals That This Guidance Applies
+
+- A repository is brand new and the first commit has not happened yet.
+- A local import or migration dropped temporary files into the repo root.
+- Scratch or cache directories are present and the ignore rules are not settled.
+- The team is still deciding how bootstrap files and initial layout should look.
+
+## Local Exceptions
+
+When a repository intentionally tracks generated assets, mirrored vendor code,
+or unusual bootstrap files, document that exception in the repo's own setup or
+contributing docs instead of weakening the shared rule for every other project.

docs/operations.md

@@ -21,3 +21,25 @@ install/verify.ps1
 ```
 
 Scheduled sync will be added on top of the same update and verify entrypoints.
+
+## Audit
+
+```bash
+resources/scripts/audit-copilot-usage.sh --days 30
+```
+
+The audit workflow is macOS-first in this iteration. It writes per-machine audit
+history under `.local/audits/<machine-id>/` in the repo checkout and keeps that
+runtime state out of git.
+
+After a run is generated, use the `review-audit-candidates` prompt in Copilot
+to work through `selection-manifest.tsv` one candidate at a time.
+
+When rows are approved, generate draft resources or staging notes with:
+
+```bash
+resources/scripts/prepare-audit-promotions.sh
+```
+
+See `docs/audit-workflow.md` for the report format, selection manifest, and
+promotion rules.

docs/review-standards.md

@@ -8,3 +8,15 @@ A new shared resource should be reviewed for:
 - Security implications, especially for hooks and scripts
 - Clear purpose and expected usage
 - Duplication with existing resources
+- Cheapest sufficient primitive for the intended workflow
+- Justified context size, including whether long examples or repeated guidance
+	can be moved into docs or scripts instead
+- An intentional default output budget instead of open-ended verbosity
+- Clear limits on when the resource should not be used
+
+Audit candidates should also be reviewed for:
+
+- Clear provenance back to an audit summary or selection manifest
+- Portable fit as a skill, instruction, prompt adapter, agent, hook, script, or template
+- Absence of secrets, machine-specific paths, or repo-specific assumptions
+- A justified decision when the right outcome is `template-only`, `docs-only`, or `discard`

docs/setup.md

@@ -17,7 +17,9 @@ install/bootstrap.ps1
 - Creates a canonical path at `~/.copilot-resources`
 - Links default discovery locations back to this repository
 - Merges only the managed Copilot-related VS Code settings into the user settings file
+- Generates managed VS Code and Copilot CLI MCP config files from the tracked templates in `config/mcp/`
 - Writes a managed Copilot CLI environment fragment and sources it from the shell or PowerShell profile
+- Creates `.local/mcp.local.jsonc` from the tracked example if the machine-local MCP override file does not exist yet
 - Writes a local install-state file outside the repository
 
 ## Optional Settings
@@ -31,3 +33,32 @@ possible.
 Bootstrap also writes a managed Copilot CLI environment file into the local
 state directory and adds a small managed source block to the active shell or
 PowerShell profile instead of replacing the whole profile.
+
+Bootstrap generates user-level MCP config as well:
+
+- VS Code user `mcp.json`
+- Copilot CLI user `~/.copilot/mcp-config.json`
+
+Those files are rendered from the tracked templates in `config/mcp/` and merged
+in place so unmanaged MCP server entries are preserved. Managed MCP servers that
+are no longer desired are removed.
+
+Machine-local MCP inputs live in `.local/mcp.local.jsonc`. The tracked example
+file starts with Gitea disabled. Enable it per machine by editing that local
+file and providing:
+
+- `servers.gitea.enabled: true`
+- `servers.gitea.serverUrl`
+- `servers.gitea.token`
+
+Current managed MCP behavior:
+
+- VS Code gets Playwright, Filesystem, and optional Gitea
+- Copilot CLI gets Filesystem and optional Gitea
+- Copilot CLI Playwright is intentionally omitted because it already ships as a built-in MCP server
+
+`install/update.sh` and `install/update.ps1` rerun bootstrap after `git pull`,
+so managed MCP config changes propagate on update.
+
+For generic Git repository bootstrap hygiene outside the installation flow of
+this shared resources repo, see `docs/git-bootstrap-hygiene.md`.

docs/troubleshooting.md

@@ -15,6 +15,22 @@ Treat hot reload as likely but not guaranteed. If needed:
 - restart the Copilot CLI session
 - reopen VS Code
 
+## Session Start Hook Permission Denied
+
+If you see `/bin/sh: .../report-hook-event.sh: Permission denied` when a Copilot
+session starts:
+
+- Pull the latest repo changes and rerun `install/update.sh`.
+- If you need to refresh links and generated config without pulling, rerun
+	`install/bootstrap.sh`.
+- Run `install/verify.sh --quick` and resolve any missing managed files it
+	reports.
+- Start a new Copilot session and confirm
+	`~/.copilot-resources-state/hook-events.log` receives a new JSON line.
+
+The shared hook now invokes the shell script through `bash`, so the session
+start hook no longer depends on the script file itself being executable.
+
 ## Publish Refused To Overwrite
 
 The publish scripts stop on collisions by default. Use a new name or rerun with