From 418ad0634c1574b81a5dd4e5c57aa4bad1510729 Mon Sep 17 00:00:00 2001
From: Stefan Imhoff <gpg@kogakure.8shield.net>
Date: Thu, 28 Aug 2025 12:20:31 +0200
Subject: [PATCH] docs: add AGENTS.md with build and style guidelines

---
 AGENTS.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1fe09d9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,22 @@
+AGENTS Guidelines
+
+1. Install: pnpm i (Node via .nvmrc / .tool-versions). Dev: pnpm dev. Build: pnpm build. Preview: pnpm preview. No test suite defined (add if needed); run single script via pnpm <script>.
+2. Lint: npx eslint . (autoset by lint-staged). Format: npx prettier --write . Pre-commit runs lint-staged -> prettier then eslint fix per .lintstagedrc.json.
+3. Tech: Astro + React + TS, Tailwind, MDX. Use ESM ("type":"module"). Prefer .astro for pages/layouts; isolated React (.tsx) only when interactivity or charts needed.
+4. Imports: Rely on Prettier organize-imports & tailwind plugin; no manual sorting. Group: std libs, external deps, internal (absolute/relative). Omit file extensions except for non-code assets. Avoid deep relative chains; create utility barrels if scaling (>3 siblings).
+5. Formatting: Prettier enforced; tabs (width 4) except MD/MDX/YAML (2 spaces). Single quotes in code, double in MD/YAML. 100 char print width. Trailing commas es5. LF endings.
+6. Types: Strict TS (see tsconfig). Always type exported function params/return if not inferred. Use readonly, const assertions, narrow early. Prefer union types + discriminants over enums unless exhaustive mapping.
+7. Components: PascalCase for React/Astro components; files match component. One default export per component file. Hooks (if added) camelCase prefixed use.
+8. Variables/functions: camelCase, const by default. UPPER_CASE only for true constants. Avoid Hungarian notation.
+9. Content collections: Use defined schemas in src/schema/\* for validation; extend there rather than ad hoc field access. Central site/meta config in data/site.ts.
+10. CSS: Tailwind utility-first; extract repeated patterns via @apply in scoped layer components or create small Astro components.
+11. Errors: Fail fast; throw Error with descriptive message; no silent catch. Wrap external IO (fs/network) with try/catch and rethrow enriched context.
+12. Date/time: Use utils/date.ts helpers. Avoid new Date(...) formatting inline.
+13. Performance: Prefer static generation; use React only when necessary. Avoid moment for new code (consider Intl APIs) but keep legacy until refactor.
+14. Images: Use provided conversion scripts (pnpm webp, og:generate, icons:generate). Do not commit large unoptimized assets.
+15. Accessibility: Use semantic HTML in Astro; add alt text; a11y lint via eslint-plugin-jsx-a11y (applies to .tsx portions).
+16. Markdown/MDX: Frontmatter validated; writing style not enforced here; keep line length flexible (formatter handles wrapping).
+17. Commit hygiene: Small, focused commits; pre-commit will block formatting issues. Run full lint before large refactors.
+18. Adding posts: Use plop (pnpm plop) generators where available instead of manual copy to ensure schema alignment.
+19. Secrets: Do not hardcode keys; if env vars needed add to env.d.ts and .env (not committed) and reference import.meta.env.
+20. Automation: Husky pre-commit + lint-staged only; extend by adding new hooks if necessary (keep fast <5s).