Release

CLAUDE.md

@@ -6,6 +6,41 @@ Guidance for Claude Code when working in this repository (KloudMate documentatio
 
 [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.
 
+## Writing style: kill these AI tells (all docs, self-check before you finish)
+
+AGENTS.md §2 is the full voice guide — read it before writing. This section is the focused checklist of tells that keep slipping into drafts and getting flagged. Self-review every page against it and fix the hits **before** handing it over. The user should not have to point these out again.
+
+Write the way Stripe, Datadog, and Google developer docs actually read: lead with the task or the outcome, keep each section to a few tight sentences, stay in second person with imperative steps, and use concrete verbs with real values. For a concrete model, [Datadog's Step Functions overview](https://docs.datadoghq.com/serverless/step_functions/) opens by stating what the service is and what the product adds, uses outcome-led headings ("Monitor the overall health…", "Reduce Step Function debugging time…"), keeps every section to 2–3 sentences, names concrete outcomes ("identify what states are problematic or have a high latency"), and never announces a count or calls a screen "a summary of activity."
+
+### Structural tells — state the fact, don't announce it
+
+The pattern the user flags most: **announcing a quantity + a vague nominalization + a balanced "…and they…" clause**, instead of just stating the fact. State the concrete thing; drop the count when the list right below already shows it; use an active verb instead of "is a … of."
+
+| Don't write | Why it reads as AI | Write instead |
+|---|---|---|
+| "Two levels of data are available, and they need different amounts of setup:" | count + vague nominal + balanced "and they" clause | "Some of this works the moment you connect an account. The rest needs execution logging:" |
+| "The tab has three parts:" · "they need two things:" · "Check two things:" | announcing a count the list below already shows | "The tab shows:" · "Check both of these:" |
+| "The Overview tab is a workspace-wide summary of execution activity." | copula + nominalization ("is a summary of activity") | "The Overview tab summarizes the last 24 hours of executions." |
+| "Both workflow types are supported." | flat passive announcement | "KloudMate supports both Standard and Express workflows." |
+| "…with three tabs: Executions, Metrics, Configuration." | needless count | "…with tabs for Executions, Metrics, and Configuration." |
+
+### Tone (AGENTS.md §2 has the full word lists; these are the repeat offenders)
+
+- **Em dashes for asides** → period, comma, colon, or parentheses.
+- **No drama or voiceover:** rhetorical build-ups ("X is the answer"), trailing tags ("…, which it is"), figurative labels ("delivery vehicle"), cutesy asides ("the same treatment for your Lambda functions"). Write the plain fact.
+- **No reflexive benefit-tails:** don't glue "…, so you can [vague upside]" onto every sentence. Keep it only when the cause and effect is real and specific.
+- **No hype or filler:** powerful, seamless, robust, effortless; leverage/utilize → use, via → with, "in order to" → to, "simply/just/easily".
+
+### Do this
+
+- Open with what the reader accomplishes, not background or history.
+- Verb-led headings for task sections ("Turn on execution logging"); noun headings that name a screen are fine for reference sections ("The State machines table").
+- Vary sentence length and openers. Don't start three sentences in a row the same way, especially with the product name.
+- Be concrete: real labels and values (`level ALL`, `/aws/vendedlogs/states/<name>`), a real error string.
+- Close a section with the next step (a link to setup, Explore, or Alerts).
+
+When asked to review for these, rewrite the offending lines — don't just list them.
+
 ## 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."

astro.config.mjs

@@ -74,6 +74,9 @@ export default defineConfig({
       customCss: ['./src/styles/brand.css'],
       components: {
         Header: './src/components/Header.astro',
+        // Wraps starlight-llm-actions' Page Actions dropdown in
+        // `data-pagefind-ignore` so its menu labels stay out of the search index.
+        PageTitle: './src/components/PageTitle.astro',
         Sidebar: './src/components/Sidebar.astro',
       },
       sidebar: [

src/components/PageTitle.astro

@@ -0,0 +1,58 @@
+---
+/**
+ * Replaces the `PageTitle` override that starlight-llm-actions injects, so the
+ * Page Actions dropdown can be wrapped in `data-pagefind-ignore`.
+ *
+ * Starlight puts `data-pagefind-body` on `<main>`, and the dropdown renders
+ * inside it, directly after the `<h1>`. Without the wrapper, Pagefind indexes
+ * the menu's labels ("Copy page", "View as Markdown", "Open in Claude", …) as
+ * the first ~380 characters of every page, so they lead the search excerpts and
+ * every page matches a search for those words.
+ *
+ * The plugin detects a user `PageTitle` override, skips its own injection, and
+ * logs a build warning pointing at exactly this pattern. Note that the skipped
+ * override is also where the plugin renders its optional `printNotice` banner;
+ * that option isn't configured here, so nothing is lost, but adding it later
+ * means porting the banner markup into this file.
+ *
+ * The `<h1>` stays outside the ignored subtree on purpose: Starlight sets no
+ * `data-pagefind-meta="title"`, so Pagefind takes each search result's title
+ * from the first indexed `<h1>`.
+ */
+import Default from '@astrojs/starlight/components/PageTitle.astro';
+import PageActions from 'starlight-llm-actions/components/PageActions.astro';
+---
+
+<div class="starlight-llm-actions-row">
+  <Default {...Astro.props}><slot /></Default>
+  <div class="sl-llm-actions-pagefind-ignore" data-pagefind-ignore>
+    <PageActions />
+  </div>
+</div>
+
+<style>
+  /* Mirrors the layout of the plugin's own PageTitle override. */
+  .starlight-llm-actions-row {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.75rem;
+    margin-bottom: 1.5rem;
+  }
+
+  .starlight-llm-actions-row :global(h1) {
+    flex: 1;
+    min-width: 0;
+  }
+
+  /* The wrapper exists only to carry `data-pagefind-ignore`; `display: contents`
+   * keeps the dropdown itself as the flex item, as it is upstream. */
+  .sl-llm-actions-pagefind-ignore {
+    display: contents;
+  }
+
+  @media print {
+    .starlight-llm-actions-row {
+      display: block;
+    }
+  }
+</style>