Guidance for AI coding agents working in this repository. Human contributors should read docs/CONTRIBUTING.md; this file is the single source of truth for agents.
A personal homelab and DevOps knowledge base: Markdown cheat sheets with quick-scan command tables for tools, platforms and concepts. There is no build step for the sheets themselves: the repository is Markdown plus small checker scripts and CI config. site/ holds the Hugo site that publishes them (see site/SITE.md).
- One folder per theme (
linux/,docker/,kubernetes/,networking/,tools/,apps/, and others; new themed folders such assecurity/orbackup/appear over time). One sheet per file. README.md: intro and the generated sheet index, grouped by folder.docs/CONTRIBUTING.mdanddocs/_template.md: house style and a starting template. Folder choice guide is in CONTRIBUTING.scripts/check-links.py: link, anchor and file checker.scripts/gen-index.py: generates theREADME.mdindex (--checkin CI)..github/PULL_REQUEST_TEMPLATE.mdand.github/PULL_REQUEST_TEMPLATE/: default PR template plusnew-sheet.mdandupdate-sheet.md(select with?template=). Fill in the matching one in PR descriptions..github/ISSUE_TEMPLATE/: issue forms (request-sheet.yml,report-error.yml) andconfig.yml(blank issues disabled). Keep the folder dropdown inrequest-sheet.ymlin step with the folders listed in CONTRIBUTING..github/workflows/external-links.ymland.lychee.toml: weekly external link check (lychee), opens one "Broken external links" issue. Not run on PRs.scripts/check-ips.pyand.ip-allowlist: flags real-looking public IPv4 addresses..github/workflows/secret-scan.ymlruns it plus gitleaks in CI.scripts/check-freshness.py,.freshness-ignore-revsand.github/workflows/freshness.yml: monthly report of sheets untouched for over 12 months (one "Stale sheets to re-verify" issue). List mechanical bulk-edit commits in.freshness-ignore-revs. The same script also supplies the dates shown on the website.site/and.github/workflows/pages.yml: the Hugo site (seesite/SITE.md).site/scripts/prepare-content.pyimportsscripts/check-freshness.py(last_touched,load_ignored,is_stale) for each sheet's "Updated" date and stale chip, so keep those names and signatures stable..markdownlint-cli2.yaml,.github/workflows/lint.yml: CI checks.
- First line
# Title, then a one or two sentence intro, then optionalDocumentation:andProject:link lines. ##sections. Commands inCOMMAND | DESCRIPTIONtables with the command in backticks (escape literal pipes as\|).- Multi-line commands and config in fenced blocks with a language tag.
- Placeholders in ALL CAPS or
<ANGLE_BRACKETS>. - Cross-link with relative Markdown links including
.md(e.g.[Docker](../docker/docker.md)), link text is the target's H1. Never use[[wikilinks]]. - Kebab-case file names. No empty or title-only files.
- British English, terse.
- Never invent commands, flags, options or defaults. Verify against the official documentation (or by running the command) before writing it.
- Mark anything you could not verify as unverified in the sheet, and say so in the PR description.
- No secrets, tokens, real IP addresses, internal hostnames or personal domains. Use placeholders,
example.comand documentation ranges (192.0.2.0/24,198.51.100.0/24,203.0.113.0/24). - Keep every relative link and
#anchorvalid. When you rename or delete a sheet, fix the links that point to it. - When you add a sheet, regenerate the
README.mdindex (python3 scripts/gen-index.py), and update any site or content list the repository keeps, in the same PR. ([params.sectionDescriptions]and[params.sectionGlyphs]insite/hugo.tomlare optional per-folder extras for the home page.) - Edit only what the task requires. Do not reformat unrelated sheets.
- Run all three checks before opening a PR and fix what they report in the content, not by loosening the config:
python3 scripts/check-links.pypython3 scripts/gen-index.py --checknpx markdownlint-cli2 "**/*.md"python3 scripts/check-ips.py
- Work on a branch and open a pull request. Never push to
master. Do not change repository settings or branch protection. - Do not edit
renovate.jsonor the shared preset it extends. - Keep temporary files outside the repository.