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.
Python ai-agentsaiopsdashboarddockerfastapihomelabincident-managementllmmonitoringopenaireactroot-cause-analysisself-hosteduptime-monitoring
chore: update CLAUDE.md rules and load the project skills
Karlo Kajba Šimanićd9e2776ea1a7
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.mdindex 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.mdsimilarity index 100%rename from .claude/skills/code-simplicity/code-simplicity.mdrename to .claude/skills/code-simplicity/SKILL.mddiff --git a/.claude/skills/minimal-diff/minimal-diff.md b/.claude/skills/minimal-diff/SKILL.mdsimilarity index 100%rename from .claude/skills/minimal-diff/minimal-diff.mdrename to .claude/skills/minimal-diff/SKILL.mddiff --git a/.claude/skills/simplify-existing-code.md/simplify-existing-code.md b/.claude/skills/simplify-existing-code/SKILL.mdsimilarity index 100%rename from .claude/skills/simplify-existing-code.md/simplify-existing-code.mdrename to .claude/skills/simplify-existing-code/SKILL.mddiff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.mdnew file mode 100644index 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 filediff --git a/.claude/skills/write-guide/SKILL.md b/.claude/skills/write-guide/SKILL.mdnew file mode 100644index 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`.