diff --git a/.claude/skills/content-style/SKILL.md b/.claude/skills/content-style/SKILL.md new file mode 100644 index 0000000000..7b4c79bff2 --- /dev/null +++ b/.claude/skills/content-style/SKILL.md @@ -0,0 +1,66 @@ +--- +name: content-style +description: Write, edit, and review any public-facing or customer/prospect-facing Fleet content so it follows Fleet's writing, brand, voice, and style guidelines. Use this whenever you create or change the words in website copy (fleetdm.com), handbook pages, docs, guides, tutorials, articles, blog posts, announcements, release notes, product UI text and microcopy, GitHub issues about content, or marketing and sales enablement material, even if the user never says "style guide." Trigger on edits under website/, handbook/, docs/, articles/, and on requests like "write a blog post," "draft an announcement," "review this guide for style," "make this sound like Fleet," "tighten this up," or "clean up this copy." This skill is for authoring and editing prose for voice, brand, and style. It does not apply to writing code, tests, scripts, commit messages, or internal team chat, even when those happen to mention articles, announcements, blog posts, or UI strings. +allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git diff*), Bash(git status*) +effort: medium +--- + +# Fleet content style + +Produce and refine written content that sounds like Fleet: radically honest, technically precise, and "Mister Rogers" kind. The reader is an IT professional, client platform engineer, or security practitioner. Write to them as a helpful expert peer, never as a salesperson. + +This skill works both inside the Fleet repo and outside it. The rules below are self-contained, but when the handbook is present it is the source of truth — read it first so you always reflect the latest guidance. + +## When you start + +1. **Identify the content type and the mode.** Type drives format discipline: website copy, guide/tutorial, article/blog, announcement, docs reference, product UI text, or marketing/sales enablement. Mode is either *writing new* content or *reviewing/editing existing* content. If the type or intended placement is unclear, ask — don't guess, because format rules differ by type. + +2. **Load the canonical guidelines if they exist.** When working in a repo that contains them, read these before writing, since they may have been updated since this skill was written: + - `handbook/marketing/fleet-ai-writing-instructions.md` — the token-optimized ruleset (start here) + - `handbook/company/writing.md` — the full writing guide (headings, links, lists, numbers) + - `handbook/company/brand.md` — visual brand, naming, imagery + If they aren't present (e.g. drafting external copy), use the embedded rules below. + +3. **For marketing and sales content, align positioning.** Read `references/positioning.md` — a brief distilled from the "Implicating the pain" positioning doc and the "Fleet for IT engineers and admins" sales deck (links inside). It covers the audience's pains, the "implicate the pain" narrative method, Fleet's differentiators, and messaging do's and don'ts. Treat its proof points as needing verification: never publish a stat, customer quote, or named claim without confirming it against a public, approved source, and ask the user if you can't. + +4. **Read the full rules for anything non-trivial.** `references/style-rules.md` has the complete mechanics with examples; `references/content-types.md` has per-type format discipline and the article/guide/announcement endmatter templates. The checklist below is the fast path, not the whole story. + +## The core of Fleet's voice + +- **Plain English, short sentences, active voice.** One idea per sentence. If a sentence runs past ~20 words, split it. "Fleet manages hosts," not "Hosts are managed by Fleet." +- **Imperative mood for instructions.** "Click **Save**," not "You should click Save." +- **Clarity over cleverness.** If a sentence is clever but obscures meaning, rewrite it. The goal is for the reader to understand, not for the writer to look smart. +- **Radical honesty.** State bugs, limitations, and gaps plainly. Never use marketing spin to hide them. +- **No snark, no hype.** Treat the reader as an equal. Never condescending, edgy, or sarcastic. + +## High-frequency rules (the fast checklist) + +These are the rules content most often gets wrong. Apply them on every pass. + +- **Sentence case everywhere** — headings, subheadings, buttons, UI labels. "Host details," not "Host Details." Only proper nouns, acronyms, and self-styled names (macOS, osquery) keep their casing. +- **Commas, not em dashes.** Avoid em dashes entirely. Use a comma, a colon, or a new sentence. This is the single most common AI tell to strip. +- **Oxford comma, always.** "macOS, Windows, and Linux." +- **Bold UI elements only.** "Navigate to **Hosts**." Never bold for emphasis or to decorate. Excessive bolding is an AI tell. +- **Cut filler.** Delete "very," "really," "actually," "basically," "essentially," and "just." Use common words: "help," not "facilitate." +- **No hyperbole.** Strip "revolutionary," "game-changing," "seamless," "powerful," "robust," "unprecedented," "industry-leading," "best-in-class." +- **Fleet naming.** The product and company are **Fleet** (or Fleet Device Management) — never "FleetDM," "fleetDM," or "fleetdm" in prose. Lowercase `osquery`, `fleetctl`, `fleetd` (rewrite the sentence if one would start it). Capitalize Fleet Desktop and Orbit. +- **Preferred terms.** Use "hosts," "devices," "computers," "Fleet UI," "Fleet server." Avoid "agents" and "nodes." Prefer "device" over "endpoint." +- **No fabrication.** Never invent features, URLs, names, dates, version numbers, or CLI commands. If you don't have something you need, ask — it's better not to know than to make it up. +- **Strip AI intros.** No "In the rapidly evolving world of…," no throat-clearing. Lead with the substance. + +## Writing mode + +Draft directly in the target format and apply the rules as you write — don't write loose prose and clean it up after. Lead with the "why" before the "how." Match the format discipline for the content type (see `references/content-types.md`): guides get numbered steps, announcements lead with the news, website copy is scannable and benefit-focused, articles are conversational but professional. + +Before presenting a draft, do one self-review pass against the checklist above, reading specifically for em dashes, over-bolding, filler, hype, and sentence-case slips — these survive even careful first drafts. + +## Review / edit mode + +When the user hands you existing content (or you're editing files in a diff): + +1. Read the content and identify its type. +2. Go through it against the checklist and the full rules, noting each issue with its location. +3. Apply the fixes directly (Edit), or if the user wants a critique, report findings as a short list grouped by rule — quote the original, give the corrected version, and name the rule. Keep it specific and actionable; don't pad with praise. +4. Preserve the author's meaning and technical accuracy. Style edits must never change facts. If a sentence is factually unclear, flag it rather than rewriting it into something that might be wrong. + +When in doubt, simplify. diff --git a/.claude/skills/content-style/references/content-types.md b/.claude/skills/content-style/references/content-types.md new file mode 100644 index 0000000000..661b3c50c5 --- /dev/null +++ b/.claude/skills/content-style/references/content-types.md @@ -0,0 +1,59 @@ +# Content types and format discipline + +Each content type has its own shape. Identify the type first, then apply the matching format. All types share the voice and mechanics in `style-rules.md`. + +## Website and UI copy + +- Benefit-focused: lead with what the reader can do, not what Fleet is. +- Scannable: short sentences, bullet points, clear headers. +- Concise: remove every unnecessary word. No hype, no filler adjectives. +- Direct, specific calls to action. +- Product UI text: sentence case for labels and buttons, plain and short. Mirror the terminology already used in the UI. + +## Guides and tutorials + +- Explain the "why" of the task before the steps. +- Use numbered lists for sequential actions; one action per step. +- Imperative mood, active voice. +- Bold UI elements only (e.g. "Navigate to **Settings > Hosts**"). Never bold for emphasis. +- Surface the simple, high-level steps first; put advanced details lower down. +- Requires the article endmatter below with `category` set to `guides`. + +## Articles and blog posts + +- Conversational yet professional. Provide context — the "why," not just the "what." +- Explain jargon for the reader. +- Use `##` (H2) and `###` (H3) to break up long sections. +- Stay aligned with Fleet values; no vendor-pitch language. +- Requires the article endmatter below. + +## Announcements and release notes + +- Lead with the news in the first sentence. +- Keep it short (roughly 2-4 sentences) and factual. No hype, no build-up. +- Requires the article endmatter below with `category` set to `announcements`. + +## Docs reference pages + +- Static-noun headings ("Log destinations"), not task verbs. +- Precise and complete; favor tables and lists over prose where they're clearer. +- Full URLs for links so pages stay movable. + +## Marketing and sales enablement + +- Same honesty and anti-hype discipline as everything else — the audience is technical and tunes out spin. +- Read `references/positioning.md` for the audience pains, the "implicate the pain" narrative, Fleet's differentiators, and messaging do's and don'ts. Lead with pain then desire; keep operational speed as the throughline; never lift unverified stats, quotes, or named claims from the source docs. +- Follow the competitor and Fleet framing rules in `style-rules.md`: state facts, name specific differentiators, never editorialize. + +## Article endmatter template + +Articles, guides, and announcements end with this YAML block. Match `articleTitle` to the H1 exactly. Don't fabricate the author, username, or date — ask if you don't have them. + +``` + + + + + + +``` diff --git a/.claude/skills/content-style/references/positioning.md b/.claude/skills/content-style/references/positioning.md new file mode 100644 index 0000000000..e3978cb313 --- /dev/null +++ b/.claude/skills/content-style/references/positioning.md @@ -0,0 +1,71 @@ +# Fleet positioning and messaging brief + +Use this to align tone and framing for marketing and sales enablement content, and any copy that needs to land Fleet's value. It's distilled from two canonical sources: + +- **Implicating the pain** (positioning doc): https://docs.google.com/document/d/1h8N9Icow6g-08EZPQMnbH-bDKDbXoPy-lwlUm9DiPJA/edit +- **Fleet for IT engineers and admins** (sales deck): https://docs.google.com/presentation/d/1WTyGrmA4pSB7H8BeT14BF7peozBceToW8TK__doyQTg/edit + +> **Read this before lifting anything from it.** The positioning doc is an internal, in-progress strategy document. It contains raw language, TODOs, and specifics that are not cleared for public use (internal deal sizes, unverified stats, AI-vendor implementation details). Mine it for **framing and voice**, not for sentences, quotes, or numbers. Never publish a stat, customer quote, or claim from here without verifying it against a public, approved Fleet source. This is the same no-fabrication discipline the rest of the skill enforces. + +## Audience and their pains + +The reader is a high-agency "doer" — an IT admin or IT leader (often at a 700+ employee company), plus the CIOs, CISOs, and MacAdmins around them. They already know device management matters. They don't need to be sold on the category; they need it to be faster and easier. Their emotional core is the fear of looking slow or ineffective, and the desire to be the person who made the company faster. + +Concrete pains the docs name (useful as the "before" in any narrative): + +- **Slow to change** — afraid to "press the button"; no rollback, no peer review, no record of who changed what. +- **The last mile** — "push and pray"; rollouts stall at 75%, and the exposed 25% are often execs, legal, and finance. +- **Left behind** — pressure to use AI for real, but click-ops tools have no safe "human in the loop" path to it. +- **Roach motel** — vendor lock-in; cloud-only restrictions that clash with data-residency needs; shrinking human support. +- **Meshy tools** — separate tools, teams, and APIs per OS. "Two or more sources of truth" means no source of truth. +- **Busywork** — large chunks of team time spent gathering audit and leadership evidence, or waiting on slow scripts. +- **Off limits / stumped** — can't see into acquisitions and subsidiaries; can't easily pull current or historical data on AI usage, shadow IT, vuln exposure, or compliance posture. +- **Trust gap** — employees won't take "trust me" that IT isn't spying; buyers won't take "trust me" on a closed-source vendor. + +## The narrative method: implicate the pain + +This is the core move, and it's the opposite of a feature tour. Lead with the reader's pain, then their desire. Cost savings is justification, not desire — it's the rationalization made *after* someone already wants Fleet, so don't lead with it. + +The arc: +1. Surface the pain with concrete, lived scenarios, not abstractions. +2. Quantify and amplify it (how much time, who else is affected). +3. Bridge to a relevant outcome ("that reminds me of…"). +4. Reframe **Old IT vs. New IT**. +5. Future-pace: if you could do this tomorrow, how would you know you're better off, and who else benefits? + +The **Old IT vs. New IT** contrast is the recurring engine. Old IT: slow, afraid to change, locked in, meshy, push-and-pray, siloed. New IT: "you can just do things," freedom at every level, see reality clearly, open by design — manage devices like DevOps, with a human in the loop. The throughline is **operational speed**, tied to the AI moment: don't be left behind; be the real deal. + +The four "promised land" pillars: (1) you can just do things (access), (2) freedom at every level (flexibility), (3) see reality clearly (clarity), (4) open by design. + +## Differentiators (state them plainly, let facts do the work) + +- One source of truth across macOS, Windows, Linux, and mobile — replaces a stack of per-OS tools. +- Source-available and open by design — transparency for both employees and buyers. +- GitOps and infrastructure-as-code — version control, peer review, rollbacks, audit trail, and the safe path to AI-assisted change. +- Real-time visibility via osquery — query any device in seconds; treat the fleet as a live database. +- Clear diagnostics — see *why* a rollout or profile failed without dragging the end user onto a call. +- Deployment flexibility — on-prem or cloud, no lock-in, supports data-residency needs. +- A single modern API across every OS. +- Fast, agnostic migration — enroll through an existing MDM for instant visibility without taking over. + +## Messaging do's + +- Lead with pain, then desire. Keep speed as the throughline. +- Use sharp, concrete Old IT vs. New IT contrasts. +- Tell customer outcomes through specific scenarios, not adjectives. +- Speak to transparency — "open by design," no "trust me." +- Tie to the AI moment honestly: a human in the loop, manage devices like DevOps. +- Acknowledge real objections (migration has historically been painful) and reframe rather than dodge. + +## Messaging don'ts + +- No feature bake-offs or "harbor tour" demos divorced from pain. +- Don't lead with "replace Jamf to save money" — it frames Fleet defensively. +- Don't promise unbuilt features. Redirect to Fleet's pace and openness. +- Watch hyperbole — the source doc itself flags its own overstatements as inefficient. Specificity beats superlatives. +- Don't overclaim where Fleet isn't differentiated (e.g. end-user UX is roughly on par with incumbents today). Lean on visibility, diagnostics, speed, and openness instead. +- "Heart" arguments (no lock-in, open source for the long term) deepen conviction but rarely close on their own — use them to reinforce, not to carry the pitch. + +## Proof points + +The docs reference customer stories (e.g. Stripe, Foursquare, NVIDIA, Reddit) and supporting stats. **Do not reuse any specific number, quote, or named claim without verifying it against a public, approved source** such as a published case study on fleetdm.com. Many specifics in the positioning doc are internal or unverified. When you need a proof point and can't verify it, ask the user rather than reaching for one from here. diff --git a/.claude/skills/content-style/references/style-rules.md b/.claude/skills/content-style/references/style-rules.md new file mode 100644 index 0000000000..4da35b3f11 --- /dev/null +++ b/.claude/skills/content-style/references/style-rules.md @@ -0,0 +1,133 @@ +# Fleet style rules (full reference) + +This mirrors Fleet's canonical guidance in `handbook/company/writing.md` and `handbook/marketing/fleet-ai-writing-instructions.md`. When those files are present in the repo, they win — read them. Use this when they aren't available. + +## Contents +- [Voice and tone](#voice-and-tone) +- [Sentence structure](#sentence-structure) +- [Punctuation](#punctuation) +- [Capitalization and sentence case](#capitalization-and-sentence-case) +- [Fleet naming and terminology](#fleet-naming-and-terminology) +- [Words and phrases to avoid](#words-and-phrases-to-avoid) +- [Headings](#headings) +- [Lists](#lists) +- [Links](#links) +- [Numbers, dates, and times](#numbers-dates-and-times) +- [Code and Markdown](#code-and-markdown) +- [Competitor and Fleet framing](#competitor-and-fleet-framing) +- [Anti-AI patterns](#anti-ai-patterns) + +## Voice and tone + +Fleet's writing philosophy is "What would Mister Rogers say?" — helpful, neighborly, respectful, and honest. + +- Treat the reader (IT pros, client platform engineers, security practitioners) as an equal and an expert peer. +- No snark, condescension, edginess, or sarcasm. +- Practice radical honesty. State bugs, limitations, and mistakes plainly. Never use spin to hide technical debt. +- Clarity over cleverness. If a sentence is clever but obscures meaning, rewrite it. +- Contractions are good (they're, don't, it'll, won't). They keep the tone approachable. +- Exclamation points: use sparingly, one at a time at most. + +## Sentence structure + +- Active voice: "Fleet manages hosts," not "Hosts are managed by Fleet." +- Imperative mood for instructions: "Click **Save**," not "You should click Save." +- One idea per sentence. If a sentence exceeds ~20 words, split it. +- Short and punchy beats long and qualified. + +## Punctuation + +- **Oxford comma:** always. "macOS, Windows, and Linux." +- **Em dashes:** avoid them. Use a comma, a colon, or a new sentence. (Most common AI tell.) +- **Commas over em dashes** is the default rewrite when you see a dash. +- **Quotation marks:** place punctuation outside the quotes unless it's part of the quoted string — e.g. write "osquery", not "osquery." +- **Spacing:** exactly one space after a period. +- **Colons:** introduce a list or a phrase that adds detail. Don't use a colon when a list immediately follows a heading. +- **Hyphens:** for ranges (Monday-Friday) and compound modifiers before a noun ("three-week cadence," but "released every three weeks"). +- **Ampersands (&):** only in brand names or direct quotes; otherwise write "and." + +## Capitalization and sentence case + +- **Sentence case for all headings, subheadings, button text, and UI labels.** "Ask questions about your servers," not "Ask Questions About Your Servers." "Host details," not "Host Details." +- Capitalize only proper nouns, acronyms, and words with their own styling. + - "MDM commands" — MDM is an acronym. + - "macOS uses…" — macOS keeps its lowercase m. + - "Nudge" — proper noun, stays capitalized. + +## Fleet naming and terminology + +- **Fleet** or **Fleet Device Management** — the company and the product. Never "FleetDM," "fleetDM," or "fleetdm" in prose. +- **Fleeties** — core team members. +- **fleet / fleets** — lowercase when referring to a group of devices. +- **osquery** — always lowercase. If it would start a sentence, rewrite so it doesn't. +- **fleetctl**, **fleetd** — lowercase; rewrite if one would start a sentence. +- **Fleet Desktop**, **Fleet UI**, **Fleet server**, **Orbit** — capitalized. +- Preferred nouns: "hosts," "devices," "computers." Prefer "device" over "endpoint." A device can be a phone, desktop, laptop, VM, or server. +- **Avoid** "agents" and "nodes." +- **Disk encryption:** use "disk encryption" generally. Use "FileVault" or "BitLocker" only when specifically referring to macOS or Windows. + +## Words and phrases to avoid + +- **Filler:** very, really, actually, basically, essentially, just. +- **Corporate/formal:** facilitate (use "help"), utilize (use "use"), leverage (use "use"). +- **Hyperbole / hype:** revolutionary, game-changing, seamless, powerful, robust, unprecedented, industry-leading, best-in-class, cutting-edge, world-class. +- **Vague intensifiers and superlatives** in general — let specific facts carry the weight. + +## Headings + +- Sentence case (see above). +- No end punctuation unless the heading is a question. +- Reference topics: use a static noun. "Log destinations." +- Guides/tasks: use a task-based verb. "Configure a log destination." +- Avoid -ing verbs: "Configure a log destination," not "Configuring a log destination." +- Avoid vague verbs: "Log destinations," not "Understand log destinations." +- Don't put code in headings. +- Hierarchy: H1 page title, H2 main sections, H3 sub, H4 sub-sub. Use standard Markdown (`#`, `##`). + +## Lists + +- Unordered lists use hyphens (`-`). +- Ordered lists use numbers, for sequential actions. +- Introduce a list with a colon after a complete sentence; no colon when the list directly follows a heading. +- List items that are complete sentences get end punctuation; fragments don't. Be consistent within a list. + +## Links + +- Use full URLs rather than relative links, so content stays movable. +- Make link text meaningful. Link the descriptive words, not "here" or "click here." + +## Numbers, dates, and times + +- Spell out a number at the start of a sentence; otherwise use numerals. +- Numbers over 999 get commas (1,000, not 1000). +- Times use numerals with no space (7am, 7:30pm). Specify the time zone for a global audience. + +## Code and Markdown + +- Backticks for code, file paths, and terminal commands. +- Bold UI elements only — never bold for emphasis. Use italics for UI navigation paths (e.g. *Organization settings*) where the handbook does. +- Standard Markdown headings only. + +## Competitor and Fleet framing + +Apply the same discipline to competitors and to Fleet. Credibility comes from specificity, not superlatives. + +- State facts only. Never editorialize. Describe what a product does, not how well it does it. + - "Jamf provides macOS management capabilities" — not "Jamf provides excellent macOS management." +- Don't frame a competitor as the default or obvious choice ("gold standard," "known for its excellent…"). +- Competitor limitations must be verifiable and specific. + - "Kandji does not currently offer Linux endpoint management" — not "Kandji falls short on cross-platform support." +- State Fleet's genuine differentiators (GitOps-native workflow, open source, Linux support) plainly. Let the facts do the work. +- Write as a knowledgeable practitioner, not a salesperson. The audience tunes out vendor-pitch language. + +## Anti-AI patterns + +These survive careful drafting — read specifically for them before finishing: + +- Em dashes used as connectors. Replace with commas, colons, or new sentences. +- Over-bolding and decorative bold. Bold UI elements only. +- Throat-clearing intros: "In the rapidly evolving world of…," "In today's fast-paced…," "It's important to note that…." Cut them; lead with substance. +- Passive voice that crept in. Convert to active. +- Filler and hype words (see lists above). +- Hedging and vague qualifiers ("might potentially," "in order to" → "to"). +- Final check: "Is this the simplest way to say this? Would Fred Rogers approve of this tone?" diff --git a/.kilo/kilo.jsonc b/.kilo/kilo.jsonc new file mode 100644 index 0000000000..30c3e3f95e --- /dev/null +++ b/.kilo/kilo.jsonc @@ -0,0 +1,15 @@ +{ + // Kilo Code project configuration. + // + // Fleet's agent skills live in .claude/skills/ (shared with Claude Code). + // Registering that directory here makes Kilo Code load all of them without + // each contributor having to turn on "Claude Code Compatibility" by hand. + // + // skills.paths accepts directories that contain skill subfolders. Paths are + // resolved relative to the project root. Each subfolder must hold a SKILL.md + // whose `name` matches the folder name. + // Docs: https://kilo.ai/docs/customize/skills + "skills": { + "paths": [".claude/skills"] + } +}