Skip to content

Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.

chore: update CLAUDE.md rules and load the project skills

Karlo Kajba Šimanićd9e2776ea1a7
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 151d0c0..e82c537 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -18,7 +18,7 @@ infradeck: a self-hosted dashboard for monitoring homelab machines. One machine
<!-- TODO: replace with the real commands -->
- Dev stack: `docker compose up`
- Backend tests: `pytest tests/`
-- Frontend tests + lint: `cd src/frontend && npm test && npx oxlint`
+- Frontend tests + lint: `cd src/frontend && node --test && npx oxlint`
- New migration: `alembic revision --autogenerate -m "<message>"` (review the generated file before applying)
# Workflow
@@ -36,14 +36,17 @@ infradeck: a self-hosted dashboard for monitoring homelab machines. One machine
# Hard rules
- `src/collector/` stays standard library only. Never add third-party packages there.
-- Never push directly to `main`, never force-push shared branches, never merge PRs.
-- Never close, reopen or relabel issues manually.
+- Never push directly to `main`, never force-push shared branches, never merge PRs without approval.
+- Never close, reopen or relabel issues manually or without approval.
- Anything sent to an LLM provider from `src/agent/` goes through `masking.py` first.
# Git & GitHub
- One issue = one branch = one PR. Branch: `<type>/<issue-number>-<short-desc>` (e.g. `fix/42-login-redirect`).
- Commits: Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:` …).
- PR description: summary of changes, how it was verified, and `Fixes #<n>`. If the issue is only partly solved, use `Refs #<n>` and list what's left.
+- Open issues may be edited. Never edit a closed issue; if closed work needs a
+ follow-up or new scope, open a new issue and reference the old one (`Related: #<number>`).
+- Always check if there are new issues that can be resolved/closed after commiting and pushing changes.
# Security
- Validate all external input (body, params, headers, files) with Pydantic models / explicit checks.
diff --git a/.claude/skills/code-simplicity/code-simplicity.md b/.claude/skills/code-simplicity/SKILL.md
similarity index 100%
rename from .claude/skills/code-simplicity/code-simplicity.md
rename to .claude/skills/code-simplicity/SKILL.md
diff --git a/.claude/skills/minimal-diff/minimal-diff.md b/.claude/skills/minimal-diff/SKILL.md
similarity index 100%
rename from .claude/skills/minimal-diff/minimal-diff.md
rename to .claude/skills/minimal-diff/SKILL.md
diff --git a/.claude/skills/simplify-existing-code.md/simplify-existing-code.md b/.claude/skills/simplify-existing-code/SKILL.md
similarity index 100%
rename from .claude/skills/simplify-existing-code.md/simplify-existing-code.md
rename to .claude/skills/simplify-existing-code/SKILL.md
diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md
new file mode 100644
index 0000000..84e8f7c
--- /dev/null
+++ b/.claude/skills/write-docs/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: write-docs
+description: Write or update explanatory documentation for infradeck — how a component, feature or design works and why it was built that way (architecture, data flow, design decisions). Not for step-by-step instructions like deployment or setup guides (use write-guide).
+---
+
+# Write documentation
+
+Documentation explains how something works and why. The reader wants to understand the system well enough to change it, debug it or decide about it. Step-by-step instructions belong in a guide (write-guide), not here.
+
+## Before writing
+- **Read the code first.** Every claim must come from the code, config or an existing doc you checked, never from what a typical FastAPI/React project would do. If something can't be confirmed, ask me or mark it `TODO: verify`; don't guess.
+- **Check what exists.** Look in `docs/` and `floorplan/`. Update the existing page instead of creating a parallel one. A new file goes in `docs/` with a short kebab-case name (`incident-agent.md`).
+- **Know the reader.** Default: a developer who knows the stack but not this codebase. If the page is for self-hosting users, say so and leave out internals they don't need.
+## Structure
+Use only the sections the topic needs:
+1. **What it is**: one or two sentences: what this part does and where it sits in the system.
+2. **How it works**: the flow in the order it actually happens: what triggers it, which components take part (with file paths), what data moves between them, where state is kept (Postgres, Redis, memory).
+3. **Why it's built this way**: the decisions that aren't obvious from the code, with the reason and the trade-off. ("Collectors are stdlib-only so they install on any host without pip and keep the signed image small.") If the reason isn't known, ask me rather than inventing one.
+4. **Limits and gotchas**: what it doesn't do, known edge cases, what breaks if you change X.
+5. **Related**: links to code, other docs, guides.
+A diagram (Mermaid) is worth adding only when three or more components exchange data. Otherwise prose is clearer.
+
+## Style
+- Lead with the point. No introductions ("In this document we will…"), no summaries that repeat the page, no filler ("It's important to note that…", "simply", "easily").
+- Every sentence must tell the reader something they wouldn't know otherwise. If deleting a sentence loses nothing, delete it.
+- Short paragraphs; one idea each. Use lists for parallel items, prose for reasoning, since "why" needs connected sentences, not bullets.
+- Concrete over abstract: name the file, function, table, Redis key or endpoint. Use real examples from the codebase.
+- Same term for the same thing throughout (don't alternate "collector", "agent" and "probe"; note that "agent" already means the incident agent).
+- Don't document what the code says plainly (every parameter, every field). Document what you can't see from one file: flow, contracts, reasons.
+- Never put real secrets, tokens, hostnames or IPs in examples; use obvious placeholders (`<your-domain>`, `example.com`).
+- English, Markdown.
+## Before handing over
+- Re-check every file path, name and command against the repo.
+- Read it once as the target reader: can they explain how it works and why after one read? Cut anything that doesn't help with that.
+- Tell me what you couldn't verify, and which other docs may now be outdated.
\ No newline at end of file
diff --git a/.claude/skills/write-guide/SKILL.md b/.claude/skills/write-guide/SKILL.md
new file mode 100644
index 0000000..eb8340e
--- /dev/null
+++ b/.claude/skills/write-guide/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: write-guide
+description: Write or update a step-by-step guide for infradeck — deploying the system, installing a collector, setting up or enabling a feature (TLS, Traefik/Caddy, the incident agent, notifications), upgrading, backup and restore. Not for explaining how something works internally (use write-docs).
+---
+
+# Write a guide
+
+A guide gets a reader from a starting state to a working result. They follow it while doing the task, often in a terminal, sometimes when something is already broken. Explanations of internals belong in docs (write-docs); link to them instead.
+
+## Before writing
+- **Take everything from the repo.** Commands, file names, environment variables, ports, defaults and image names come from `compose.yml`, `docker-compose.server.yml`, `docker/`, `example.env`, config code and existing docs. Never invent a flag or variable. If something can't be confirmed, ask me or mark it `TODO: verify`.
+- **Run what you can.** If a step can be run in this environment, run it and use the real output. Say which steps you couldn't test.
+- **Check what exists.** Update an existing guide in `docs/` rather than adding a parallel one. New guides go in `docs/` with a task-based kebab-case name (`deploy-server.md`, `install-collector.md`).
+- **Pin down the reader and the setup.** Default reader: a homelab user comfortable with Linux and Docker, new to infradeck. Name the setups the guide covers (single LAN, multi-site/VPS, behind Traefik or Caddy) and don't mix them in one path; branch clearly or write separate guides.
+## Structure
+1. **Title**: the task, as an action: "Deploy the infradeck server", "Enable the incident agent".
+2. **Result**: one sentence: what works when you're done.
+3. **Before you start**: requirements: OS, Docker/Compose versions, open ports, DNS, access, and anything that must already be done (link to that guide).
+4. **Steps**: numbered. Each step:
+ - one action, with the exact command or file change in a code block;
+ - where it runs (which machine: dashboard server or collector host) when that isn't obvious;
+ - values the reader must replace, as `<placeholder>`, with what to put there;
+ - one line of why, only when the step looks odd or skipping it would hurt;
+ - how to tell it worked (expected output, a URL that responds, a log line).
+5. **Verify**: the end-to-end check that the result works.
+6. **Troubleshooting**: only real, likely failures: symptom → cause → fix. No generic "check your logs".
+7. **Undo / roll back**: for upgrades, migrations and anything that changes data or exposes services.
+8. **Next**: one or two links (related guide, the docs page explaining it).
+## Style
+- Imperative and direct: "Run", "Open", "Set". No filler ("simply", "just", "easily", "In this guide we will…").
+- One way to do it. If there are alternatives, pick the recommended one and mention the other in one line or a separate guide.
+- Complete, copy-pasteable commands: no `...` inside commands, no prompts (`$`) in the code block, outputs in a separate block.
+- Show full file contents or a clear diff for config changes, plus the file's path.
+- Warnings go right before the step they apply to, not at the top or bottom: deleting data, exposing a port to the internet, disabling TLS verification, storing secrets.
+- Never real secrets, tokens, hostnames or IPs; placeholders only. Tell the reader where secrets belong (`.env`, never committed).
+- Security defaults stay on. Don't write steps that weaken them (CORS `*`, `--insecure`, disabled TLS verification) as a shortcut. If the user truly needs it, explain the risk in place.
+- English, Markdown.
+## Before handing over
+- Walk through the guide in order as the reader: is any step relying on something not yet done or not mentioned?
+- Re-check every command, path, variable and port against the repo.
+- Tell me which steps you ran, which you couldn't, and what is marked `TODO: verify`.