project-charlie/.github/copilot-instructions.md

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.