Develop

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "astro-dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 4321
+    }
+  ]
+}

AGENTS.md

@@ -13,23 +13,26 @@ The single most important thing you can do here is **write documentation that so
 
 ## 2. Writing Style & Voice (READ THIS BEFORE WRITING CONTENT)
 
-Good documentation reads like a knowledgeable colleague explaining something at your desk — not like a manual, and definitely not like ad copy. Picture the reader as someone who is in the middle of a task, slightly frustrated, and scanning for the answer. Everything below serves that reader.
+Good documentation reads like a knowledgeable colleague explaining something at your desk — not like a manual, and definitely not like ad copy. Picture the reader as someone who is in the middle of a task, slightly frustrated, and scanning for the answer. Everything below serves that reader, and it follows the same playbook as the Stripe, Google developer docs: talk to the reader directly, lead with the task, and cut anything that isn't pulling weight.
 
 ### Write to the reader, about their task
 
-- Use second person ("you"). Address the reader directly: "You'll need an API key before you start," not "Users must first obtain an API key."
-- Make the reader the subject, not the product. Write "you land on the dashboard," not "KloudMate lands you on the dashboard." Naming the product once is fine and sometimes useful, but when it's the grammatical subject of sentence after sentence, the page reads like a feature announcement instead of a guide. The reader is the one doing the task — keep them at the center. When there's no natural "you," describe the system state instead ("the **Setup checklist** drawer opens automatically").
+- Use second person. Address the reader as "you," the way the Google, Stripe, and Datadog docs do: "you" for explanations, conditions, and outcomes ("you can group alerts by service," "if you're behind a proxy," "you'll land on the dashboard"), and the imperative for steps ("Open the **Add** menu," "Run the install script"). Prefer "you" over "the user" or "they."
+- Make the reader the subject, not the product. Write "you land on the dashboard," not "KloudMate lands you on the dashboard." Naming the product once is fine and sometimes useful, but when it's the grammatical subject of sentence after sentence, the page reads like a feature announcement instead of a guide. When there's no natural "you," describe the system state instead ("the **Setup checklist** drawer opens automatically").
+- Use the imperative for procedures ("Open **Settings**," "Run the migration"), the serial (Oxford) comma, and American English spelling. This matches the Google, Stripe, and Datadog docs.
 - Lead with the goal, then the steps. Open a page by saying what the reader will accomplish and when they'd use it — not with history or background they didn't ask for.
 - Prefer active voice and present tense. "The alert fires within seconds" beats "An alert will be sent."
 - Cut the throat-clearing. Phrases like "It's worth noting that…" or "In this section, we will discuss…" add nothing. Just say the thing.
 
 ### Sound like a person, not a model
 
+- Say it plainly, and don't dramatize. Don't set up a point with a rhetorical line before delivering it, and don't dress a plain fact in drama. Lines like "Autonomous mode is the answer," "That doesn't fit here," "Only the delivery vehicle differs," or a trailing tag like "which it is" read as AI voiceover. State the fact instead: "Autonomous mode removes the per-instance UI step." Cut figurative labels ("delivery vehicle," "zero-touch level") and tacked-on editorial asides ("the standard immutable-infrastructure model"). If a sentence sounds like a product pitch or a trailer voiceover, keep the fact and drop the performance.
 - Vary your sentence length. A run of identical medium-length sentences is the clearest sign a machine wrote the page. Mix short, direct lines with longer explanatory ones.
 - Watch for repeated sentence openers, too. Three sentences in a row that start with the same word — especially the product name — turn into a drumbeat. Recast some of them so the reader, an action, or the result leads instead.
-- Contractions are good and usually better — "don't," "you'll," "it's." They match how people actually talk.
+- Contractions are good and usually better: "don't," "you'll," "it's." They match how people actually talk.
 - Be concrete. Show a real endpoint, a real value, a real error message. "Set `retention_days` to `30`" is more useful than "configure the retention setting appropriately."
 - Don't pad. If a sentence can be deleted without losing meaning, delete it.
+- Go easy on em dashes. A period, comma, or colon almost always reads cleaner, and a page peppered with them reads as machine-written.
 
 ### Words and phrases to avoid
 
@@ -40,6 +43,7 @@ These read as filler or AI boilerplate. Strike them on sight:
 - **Overused verbs:** *leverage* → use "use"; *utilize* → use "use"; *delve into* → use "cover" or "explain"; *facilitate* → use "let" or "help."
 - **Condescending qualifiers:** simply, just, easy, obviously, of course. If a step were genuinely simple, the reader wouldn't be on this page. Telling a stuck user that something is "easy" only makes them feel worse.
 - **Vague intensifiers:** very, really, quite, "a variety of," "a wide range of," "a number of."
+- **Padding and Latinate shortcuts:** drop "please" (just give the step); *e.g.* → "for example"; *i.e.* → "that is"; *via* → "through" or "with"; "in order to" → "to"; "once you" → "after you." (This mirrors the Datadog docs linter.)
 
 ### Be honest and helpful about the hard parts
 
@@ -65,7 +69,7 @@ These read as filler or AI boilerplate. Strike them on sight:
 > "KloudMate offers a powerful and seamless way to effortlessly leverage your observability data. In today's complex cloud environments, it's worth noting that users can simply configure a wide variety of robust alerting options to suit their needs."
 >
 > **Prefer:**
-> "Alerts tell you when something needs attention — an error-rate spike, a service going quiet, a budget threshold crossed. This page walks you through creating your first alert and routing it to Slack."
+> "Alerts tell you when something needs attention: an error-rate spike, a service going quiet, a budget threshold crossed. This page walks you through creating your first alert and routing it to Slack."
 
 The "prefer" version is shorter, says what the reader gets, names real scenarios, and keeps the reader (not the product) at the center. Aim for that on every page.
 
@@ -140,7 +144,7 @@ Run through this on any page you wrote or edited. It's the human-quality equival
 
 - [ ] Does the page open by telling the reader what they'll accomplish?
 - [ ] Did I read it out loud (or in my head)? Does it sound like a person, or like a template?
-- [ ] Is the reader ("you") the subject of most sentences, rather than the product? Does any product name appear as the subject several sentences in a row?
+- [ ] Is the reader ("you") the subject of the explanations, with steps in the imperative, rather than the product? Does any product name appear as the subject several sentences in a row?
 - [ ] Are there any banned words from Section 2 (powerful, seamless, leverage, simply, just…)?
 - [ ] Do the sentences vary in length, or do they all march at the same pace?
 - [ ] Will every code block actually run if pasted?

CLAUDE.md

@@ -0,0 +1,26 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository (KloudMate documentation).
+
+## Read AGENTS.md first
+
+[AGENTS.md](AGENTS.md) is the authoritative guide for this repo: project context, the writing style and voice rules (Section 2, read it before writing any content), the tech stack (Astro + Starlight), and the directory and routing structure. Follow it. The rules below are additions specific to the KloudMate agent docs (`src/content/docs/docs/kloudmate-agent/**`), not replacements.
+
+## Agent-docs terminology: plain words, no product jargon
+
+- Do not use **"baseline."** It means nothing to a reader. Use **"eBPF monitoring"** or **"ETW monitoring"** for the eBPF or ETW layer, and **"automatic monitoring"** (or "what the agent collects automatically") for the general idea. Drop the redundant article too: write "eBPF monitoring needs kernel 4.14," not "the eBPF monitoring needs…". It reads as a mass noun, and the docs already start sentences with a bare "eBPF."
+- Do not describe PHP container instrumentation as happening **"in place."** Say **"without a redeploy"** or **"directly"** — the point is that no rebuild or redeploy is needed; "default" would misdescribe it. Exception: the ASG page's "in-place upgrade" is the correct standard term for that deployment strategy, so leave it.
+
+## Phrasing: describe the system, do not assert what the reader owns
+
+AGENTS.md already says to keep the reader (not the product) as the subject, and to describe system state when there is no natural "you." One specific case to watch: do not make presumptuous ownership or management claims about the reader's setup, such as "You own the container instances" or "You own the raw YAML." Rephrase to describe the thing:
+
+- "You own the container instances" becomes "The EC2 instances are self-managed."
+- "You own the raw YAML" becomes "The raw YAML is edited directly."
+- "You manage the agent from the web interface" becomes "The agent is managed from the web interface."
+
+Give step instructions in the imperative: "Turn on the toggle," "Run the install script." The objection is only to declarative claims about the reader's environment, not to instructional voice.
+
+## Verify before you finish
+
+Run `npm run build` after content changes. Its postbuild step (`scripts/check-links.mjs`) fails on broken internal links, which catches renamed heading anchors and bad relative paths. A clean run ends with `check-links: no broken internal links found`.

scripts/validate-frontmatter.mjs

@@ -8,8 +8,9 @@
 
 import { readFileSync, readdirSync, statSync } from 'fs';
 import { join, relative } from 'path';
+import { fileURLToPath } from 'url';
 
-const DOCS_DIR = new URL('../src/content/docs', import.meta.url).pathname;
+const DOCS_DIR = fileURLToPath(new URL('../src/content/docs', import.meta.url));
 const REQUIRED_FIELDS = ['title', 'description'];
 
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;

src/content/docs/docs/alerts/create-alerts.mdx

@@ -16,10 +16,10 @@ The **Alerts** screen displays a list of all existing alert rules along with the
 
 From the **more options (⋯)** icon on any rule, you can:
 
-- **View** the rule details
-- **View State History** for the rule
 - **Edit** the rule configuration
 - **Duplicate** the rule
+- **Move to folder** to move the rule into a different [folder](../folders/)
+- **View state history** for the rule
 - **Pause Evaluation** or **Pause Notifications**
 - **Delete** the rule
 
@@ -37,7 +37,7 @@ Click the **Create Alert** button at the top-right corner of the **Alerts** scre
 
 - **From Template** — Start with a pre-configured alert for a common monitoring scenario.
 - **From Scratch** — Create a custom alert from an empty configuration.
-- **Using AI** — Describe the alert you want in plain English and let KloudMate build it for you.
+- **Using AI** — Open **KloudMate Builder** and describe the alert you want in plain English.
 
 ### From Template
 
@@ -59,6 +59,9 @@ KloudMate's assistant can automatically generate queries and thresholds based on
 
 1. In the **Create Alert** dialog, select **Using AI**.
 2. A text box appears. Describe the alert you want to create.
+
+![Using AI prompt](./images/using-ai-prompt.png)
+
 3. Click **Create Alert**. KloudMate generates the alert configuration based on your description.
 4. To review or adjust the settings, click the menu next to the alert and select **Edit**.
 
@@ -176,7 +179,7 @@ Two top-level fields and one section:
 
 The Notifications step covers how this alert flows into the grouping engine. KloudMate replaced free-form notification tags with **labels** that routing rules match on:
 
-- **Labels** are auto-derived from query dimensions, the alert rule's folder, and a small set of system keys. You don't enter them by hand.
+- **Labels** — Key/value pairs attached to every signal this alert emits. Add them with **Add label**; the list can also be left empty. Routing rules match on these labels, plus the reserved `alarm_id`, `alarm_rule_folder_id`, and per-instance query labels, to decide which channels notify and how signals are grouped.
 - **Routing** is decided by [Routing Rules](../routing-rules/) in **Alerts → Routing rules**, which match alerts by label and send them to one or more notification channels.
 - **Severity** flows through the reserved `severity` annotation from the previous step — downstream tools use it to prioritize.
 

src/content/docs/docs/apm-and-tracing/apm-views/api-monitoring.mdx

@@ -13,9 +13,7 @@ Where the [Service Map](../service-map/) shows caller-to-callee dependencies and
 
 In the left navigation, open **APM & Tracing → API Monitoring**.
 
-:::note[Screenshot placeholder]
-Add a screenshot of the API Monitoring page here (`./images/api-monitoring-1.png`): the page header, the filter bar, and the endpoints table with protocol badges, the Status column, and throughput sparklines visible.
-:::
+![API Monitoring page, showing the filter bar and the endpoints table with protocol badges, the Status column, and throughput trend sparklines.](./images/api-monitoring-1.png)
 
 Use the **time range** picker in the top-right to set the observation window. The view defaults to the last **24 hours** so the per-endpoint trend sparklines have enough history to draw.
 
@@ -64,9 +62,7 @@ To find failing endpoints quickly, sort by **Error rate**, or set the **Status**
 
 Click any row to open the endpoint drill-down in a slide-over panel. The panel is shareable — its address encodes the selected endpoint, so you can send a teammate a direct link, and closing it returns you to the list with your filters, sort, and time range intact.
 
-:::note[Screenshot placeholder]
-Add a screenshot of the endpoint drill-down here (`./images/api-monitoring-2.png`): the drawer header with protocol and method badges, the Requests / Error rate / p95 summary tiles, and the time-series charts.
-:::
+![Endpoint drill-down panel, showing the protocol and method badges, the Requests / Error rate / p95 latency summary tiles, and the throughput, error rate, latency, and status class charts.](./images/api-monitoring-2.png)
 
 At the top, summary tiles show **Requests**, **Error rate**, and **p95 latency** for the endpoint over the selected window. Below them are time-series charts:
 

src/content/docs/docs/apm-and-tracing/apm-views/service-map.mdx

@@ -4,10 +4,19 @@ description: "Use the Service Map to understand service dependencies, traffic fl
 sidebar:
   order: 3
 ---
-The **Service Map** is a visual representation of the relationships and interdependencies between services in your workspace. It is generated from tracing data and gives you a topology-level view of your architecture.
+The **Service Map** is a visual representation of the relationships and interdependencies between services in your workspace. It is built from your services' distributed traces and gives you a topology-level view of your architecture.
 
 You can use it to understand service dependencies, traffic flow, and operational health at a glance.
 
+## How the map is built
+
+The map is built from distributed traces, so both sources of tracing feed it:
+
+- **[eBPF monitoring](../../../kloudmate-agent/ebpf-observability/)** captures traces at the kernel level with no code change, so an eBPF-covered service appears on the map on its own — on VMs, hosts, and containers. (On [Kubernetes](../../../kloudmate-agent/auto-instrumentation/kubernetes/), eBPF provides the network topology instead, and traces come from the SDK.)
+- **[Auto-instrumentation](../../../kloudmate-agent/auto-instrumentation/overview/)** and the OpenTelemetry SDK produce traces from inside the application.
+
+Each service becomes a node under its `service.name`, and an edge is drawn wherever one service's trace calls another. A service needs a distinct `service.name` to appear as its own node — the agent gives an eBPF-monitored service the same name it carries once auto-instrumented, so it keeps one identity whether eBPF or the SDK is tracing it.
+
 ## Overview
 
 Click **Service Map** in the left navigation to open the map.