97 lines
5.4 KiB
Markdown
97 lines
5.4 KiB
Markdown
# 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`.
|
|
- Working trees deploy to `/mnt/nas/stacks/<stack>` and runtime data lives under
|
|
`/mnt/nas/data/<stack>`.
|
|
|
|
## Project docs
|
|
|
|
- Start with the [docs map][toc] for stable project context.
|
|
- Troubleshooting guides will live under `tsg/` with their own [TOC][tsg-toc].
|
|
- When asked for help with a problem, issue, outage, symptom, broken service,
|
|
failure, or error, check the [TSG TOC][tsg-toc] before probing live systems or
|
|
stack repos. If a matching TSG exists, follow it first.
|
|
|
|
| Need | Doc |
|
|
| --------------------------------- | ------------------------------------------------------------------------- |
|
|
| Architecture and deployment model | [topology], [strategy], [layout] |
|
|
| Fleet and stack ownership | [hosts], [inventory], [onboarding] |
|
|
| Access and secrets | [identity], [secrets], [cert issuer][cert-issuer] |
|
|
| Automation and operations | [automation], [runners], [vulnerability scanning][vulnerability-scanning] |
|
|
| Conventions and next work | [conventions], [next work][next-work] |
|
|
|
|
## 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.
|
|
- In TSG TOCs, keep issue titles and symptom keywords at 50 characters or less.
|
|
Symptoms must be keywords only. Keep tables narrow. Do not use inline HTML.
|
|
Keep skills in the table using aligned continuation rows with blank ID, issue,
|
|
and symptoms cells; use reference-style skill links.
|
|
|
|
## 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.
|
|
|
|
[automation]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/automation.md
|
|
[cert-issuer]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/cert-issuer.md
|
|
[conventions]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/conventions.md
|
|
[hosts]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/hosts.md
|
|
[identity]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/identity.md
|
|
[inventory]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/inventory.md
|
|
[layout]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/layout.md
|
|
[next-work]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/roadmap.md
|
|
[onboarding]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/onboarding.md
|
|
[runners]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/runners.md
|
|
[secrets]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/secrets.md
|
|
[strategy]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/strategy.md
|
|
[toc]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/toc.md
|
|
[tsg-toc]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/tsg/toc.md
|
|
[topology]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/topology.md
|
|
[vulnerability-scanning]: https://gitea.alexandru.macocian.me/Charlie/project-charlie/src/branch/main/docs/vulnerability-scanning.md
|