diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..cae789e
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,45 @@
+# Copilot instructions
+
+## Repository context
+
+- Project Charlie is the current-state documentation and shared deployment automation repo for the Charlie homelab.
+- Stack repos live at `https://gitea.alexandru.macocian.me/Charlie/<stack>`.
+- Source/image and operator-tool repos live at `https://gitea.alexandru.macocian.me/amacocian/<repo>`.
+- Sherlock is `amacocian/sherlock`, not `Charlie/sherlock`.
+- Working trees deploy to `/mnt/nas/stacks/<stack>` and runtime data lives under `/mnt/nas/data/<stack>`.
+
+## Instruction structure
+
+- Use this file for LLM-facing directives.
+- Keep project docs factual: current state, ownership, links, diagrams, inventory, and next work.
+- Do not put agent behavior rules in README or docs unless they are documenting real project state.
+
+## Documentation style
+
+- Be brief. Prefer tables, short lists, and compact Mermaid diagrams.
+- Link online Gitea resources; do not use local workstation paths as links.
+- Do not copy workflow bodies, shell recipes, code snippets, or implementation details into docs; Mermaid diagrams are fine.
+- Do not preserve history or reasoning in docs; Git history has that.
+- Explain what exists and where it lives, not how every piece is implemented.
+
+## Architecture guardrails
+
+- Normal stack deploys use `Charlie/project-charlie/.gitea/workflows/deploy-stack.yml`.
+- Source/image repos use `build-image.yml`; stack repos pin produced image tags.
+- Do not add `deploy.sh` patterns.
+- Target hosts are selected by workflow `host`, not by reusable-workflow runner labels.
+- Runtime state must stay outside stack Git working trees.
+- Shared stacks may need serialized deploy jobs when NFS working trees or plaintext secret paths collide.
+
+## Secrets and access
+
+- Never commit plaintext secrets.
+- Stack secrets belong under `secrets/` as SOPS ciphertext.
+- Host decryption uses `/etc/charlie/age.key`; public recipients are documented in `docs/hosts.md`.
+- PATs are identity- and scope-specific; keep repo and registry credentials separate.
+
+## Validation
+
+- For docs-only changes, scan for local workstation links and accidental copied code blocks other than Mermaid diagrams.
+- For workflow changes, inspect the referenced Gitea Actions workflow/action files and preserve the absolute-URL auth pattern.
+- For inventory changes, verify against the relevant stack repo workflow or compose files.
diff --git a/README.md b/README.md
index ce8ecd8..8617734 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # Project Charlie
 
 Current source of truth for the Charlie homelab deployment model, fleet
-inventory, and agent-facing next work.
+inventory, and next work.
 
 | Area                | Location                                                      |
 | ------------------- | ------------------------------------------------------------- |
@@ -30,5 +30,3 @@ inventory, and agent-facing next work.
   observability.
 - Sherlock is the operator MCP/agent wrapper and now lives in
   `amacocian/sherlock`.
-- This repo should stay brief: current state, links, tables, and agent-facing
-  context only.
diff --git a/docs/conventions.md b/docs/conventions.md
index ea296b5..537239a 100644
--- a/docs/conventions.md
+++ b/docs/conventions.md
@@ -9,4 +9,3 @@
 | Runtime data      | `/mnt/nas/data/<stack>` only; never inside the git working tree.              |
 | Secrets           | SOPS files under `secrets/`; plaintext ignored and deploy-time only.          |
 | Images            | Compose pins concrete tags or digests. No `:latest` in stack repos.           |
-| Docs              | State, references, tables, lists. No copied workflow bodies or shell recipes. |
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 8f1ee25..e192925 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -1,18 +1,16 @@
 # Next work
 
-Project Charlie is mostly in steady state. Next work is agent-facing: prompts,
-skills, and MCP context.
+Project Charlie is mostly in steady state. Next work is prompts, skills, and
+MCP context.
 
 ## Prompting and skills
 
 | Work item               | Target                                                                                                |
 | ----------------------- | ----------------------------------------------------------------------------------------------------- |
-| Repository instructions | Add concise agent rules for Charlie docs, stack repos, and deployment safety.                         |
 | Skill pack              | Create Charlie skills for stack deploys, Sherlock/MCP use, observability triage, and secret rotation. |
-| MCP context             | Document Gitea, Grafana, and Gssh tool boundaries through Sherlock.                                   |
+| MCP context             | Document Gitea, Grafana, and Gssh tool boundaries through Sherlock.                                  |
 | Prompt library          | Store reusable prompts for stack changes, incidents, CVE triage, and host work.                       |
 | Validation checklist    | Define the minimal checks for docs-only, stack, workflow, and secret changes.                         |
-| Link policy             | Link online resources only; no local workstation paths in docs.                                       |
 
 ## Platform follow-ups