Add doc-edit skill

skills/doc-edit/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: doc-edit
+description: >
+  Apply NetFoundry's writing style guide (casing, headings, tone, word choice, punctuation, Diátaxis structure)
+  to any documentation, how-to guide, reference page, tutorial, blog post, or UI copy in this repo. Use this
+  skill whenever drafting new Markdown/MDX content for the docs site, editing an existing doc page, reviewing
+  a doc PR or diff for style, or when the user asks to "check this against our style guide," "clean up this
+  doc," "write a how-to," "review this page," or anything touching heading casing, list formatting, em dashes,
+  "sign in" vs "log in," acronyms, or screenshot sizing. Trigger even if the user doesn't say "style guide"
+  explicitly — any writing or editing of user-facing docs in this repo should go through this checklist.
+---
+
+# NetFoundry style guide
+
+NetFoundry docs are a direct reflection of the brand's intelligence and reliability. Consistent tone, voice, and
+style make docs easier to read, faster to scan, and more trustworthy. This skill packages that style guide as a
+checklist to apply while **writing** new content and while **reviewing** existing content in this repo.
+## How to use this skill
+
+- **Writing a new page:** work through "Structure and organization" first to pick the right Diátaxis category,
+  then apply the rest of the checklist as you draft, not as a cleanup pass afterward.
+- **Reviewing or editing a page/PR:** read the page once for structure and tone, then do a second pass checking
+  the mechanical rules (casing, punctuation, word choice) line by line. Flag violations with the specific rule,
+  not just "this reads oddly."
+- **Fast-scan checklist:** before signing off on any doc, confirm each of these is true. If any is unclear, jump
+  to the matching section below for the full rule.
+  - [ ] Headings use sentence-style casing.
+  - [ ] Only one H1, and it matches `sidebar_label` in frontmatter (or is intentionally shortened for nav).
+  - [ ] How-to titles/headings are imperative ("Create a certificate"), not gerunds ("Creating a certificate").
+  - [ ] No em dashes (`—` immediately adjacent to text); if unavoidable, spaced.
+  - [ ] "Sign in," not "log in." "Zero trust," no hyphen.
+  - [ ] Acronyms spelled out on first use.
+  - [ ] UI elements are **bold**; code/paths/CLI input are in `backticks`.
+  - [ ] Fenced code blocks have a language flag.
+  - [ ] Screenshots are 600-700px wide max.
+  - [ ] No "please," no stray ampersands.
+
+## Structure and organization: pick the right category first
+
+This repo follows the [Diátaxis](https://diataxis.fr/) framework. Before writing a word, decide which of these
+four categories the page belongs to. Diátaxis rules a lot of the style decisions below (heading mood, tone,
+how much explanation to include), so getting this right first saves rework.
+
+| Category | Answers | Goal | Tone |
+|---|---|---|---|
+| **How-to guide** | How do I do X? | Help the user achieve a specific goal via steps | Prescriptive; assumes some existing knowledge, doesn't explain concepts, just commands actions |
+| **Reference** | What is X? | Describe tools, APIs, systems for look-up | Dictionary/catalog style, not meant to be read start to finish |
+| **Explanation / conceptual** | Why does X exist? / Why is X this way? | Build understanding of background and theory | Connects concepts, gives the "why," doesn't tell the user what to do |
+| **Tutorial** | How do I get started? | Teach by doing, via a simple practical project | Shortest path to success; teaching, not explaining |
+
+Not every page will be a clean fit; use judgment.
+
+**Table of contents for a new product/section**, in order: `intro.md` (landing page/overview) → `get-started.md`
+(the single most important how-to: get up and running) → then how-to guides, reference topics, tutorials, and
+support/troubleshooting topics as the content grows. The exact top-level buckets can vary by product.
+
+## Headings
+
+- Use [ATX headings](https://github.github.com/gfm/#atx-headings) (`#`, `##`, ...) with a blank line after each one.
+- Exactly one H1 per topic.
+- The H1 and the sidebar label (`sidebar_label` in frontmatter) should match. If they must differ, shorten the
+  sidebar label rather than the H1. It's fine for the label to be shorter when space is tight in the nav, or
+  when it would otherwise repeat the parent category's name (e.g. "Overview" under a category that already
+  names the topic).
+- **How-to titles and headings: imperative verb phrases.** "Create a certificate," "Install an agent." Gerunds
+  ("Creating a certificate") read as passive and are only acceptable in conceptual topics, never in how-tos or
+  reference.
+- **Sidebar category/bucket labels: noun phrases, not verbs.** "Deployments," "Identity providers,"
+  "Topologies." Save imperative phrases for leaf how-to pages that actually walk through a task — a category
+  label isn't a task.
+
+### Sentence-style casing
+
+Capitalize only the first word and proper nouns. When unsure, use lowercase. This is deliberate, not just a
+preference: it reads faster, scans better, feels more conversational, and is easier to apply consistently than
+title case. Applies to headings, sidebar labels, and UI element names you're describing.
+
+- Right: "Configure a posture check"
+- Wrong: "Configure a Posture Check" / "Configure A Posture Check"
+
+## Voice and tone
+
+- Active voice, especially in how-tos: "Click **Create**" not "The **Create** button should be clicked."
+- Everyday language: direct, conversational, contractions welcome. Use technical terms accurately, but skip
+  jargon or slang that would confuse a non-expert reader.
+- Plain sentence structure. Precise technical terms, no literary flourishes, no cleverness.
+- Avoid pronouns generally, but use "you" and "your" for the reader — never "the user."
+
+## Lists
+
+- Lean toward no periods on short bullets, but any bullet with a complete sentence (especially multiple
+  sentences) gets periods. Pick one convention per list and stay consistent within it.
+- Don't mix full-sentence bullets with 1-2 word bullets in the same list — it reads unevenly. If some items need
+  a sentence, expand the short ones to match, or restructure.
+
+### Indentation
+
+| Element | Indent | Why |
+|---|---|---|
+| Bulleted lists | 2 spaces for nested items | Minimal nesting width, per Markdown convention |
+| YAML files | 2 spaces | Industry standard |
+| Numbered lists | 4 spaces for nested items | Needed for correct rendering in most Markdown parsers |
+
+## Code, text, and UI elements
+
+- **Bold** for UI elements, and for terms being defined in a list.
+- *Italic* for emphasis.
+- `Backticks` for code phrases, file paths, variables, CLI input, and other non-English tokens.
+- Fenced code blocks always get a language flag (` ```bash `, ` ```yaml `, and so on) — never a bare fence.
+- Don't write "the button." Name it: "Click **Next**."
+- The verb for UI interaction is *click* for buttons/links/checkboxes, *select* for dropdowns.
+
+## Images and screenshots
+
+A large share of readers are on mobile. Keep screenshots at 600-700px wide max — shrink the browser window
+before capturing. To verify a page renders well on mobile, either check it on a phone, or use Chrome DevTools:
+open DevTools (F12 or Ctrl+Shift+I / Cmd+Option+I), toggle the device toolbar (phone/tablet icon), then pick a
+device preset or enter a width like 414px.
+
+## Word choices
+
+- No "please." No ampersands, unless one appears in a UI label or a proper noun.
+- **"Sign in," not "log in."** Signing in means actively entering a system and verifying identity; "log"
+  historically means creating a record. This also matches most modern tech-doc style guides.
+  - Adjective form is one hyphenated word: "the sign-in page." Verb form is two words: "sign in to your account."
+- **Acronyms:** spell out on first mention with the acronym in parentheses, then use only the acronym after
+  that. Example: "zero trust network access (ZTNA)," then "ZTNA" from then on.
+- **"Zero trust," no hyphen** — even as a compound adjective ("zero trust network access"). This is a
+  NetFoundry branding call that deliberately overrides the usual compound-adjective hyphenation rule. Don't
+  touch file paths, slugs, or code tokens that already contain a hyphenated `zero-trust` — that's a different
+  namespace, not prose.
+
+## Punctuation
+
+- Hyphenate compound adjectives ("well-known issue," "browser-based client") — except "zero trust," see above.
+- **Avoid em dashes in new writing.** Prefer rewriting as two sentences, or a colon (to introduce/define) or a
+  comma (for an aside) instead. If an em dash is genuinely the best tool, space it: `word — word`, never
+  `word—word`. When reviewing existing text, an unspaced em dash (`word—word`) is a real violation to fix; a
+  correctly spaced em dash (`word — word`) already meets the fallback rule, so treat it as a style nit at most,
+  not a required fix.
+- Colons introduce or define; don't use them where a comma or period would do.
+- Oxford commas, always.
+- **Slashes:** no spaces joining single words (`Debian/Ubuntu`, `TCP/UDP`, `on/off`). Spaces joining multi-word
+  phrases (`New York / New Jersey`). When both sides are code phrases, space them too, even if each side is one
+  token — it keeps the pair wrappable in tables: `` `FOO` / `BAR` ``, not `` `FOO`/`BAR` ``.
+
+## Admonitions
+
+Use Docusaurus admonitions (`:::tip`, `:::note`, `:::caution`, and so on) instead of inline "Note:" text.
+Reserve a bare "Note:" prefix for places an admonition block can't go, like inside a table cell or a list item,
+and even there look for a way to avoid it first.
+
+## Spacing
+
+- One space after a period, not two.
+- A blank line between headings and paragraphs, and before/after tables and lists.
+- 120-character line limit on body text in Markdown files. In VS Code: Settings → search `editor ruler` → add
+  `120` to `settings.json`.
+
+## Applying this during a review
+
+When reviewing a diff or an existing page, call out violations with the specific rule broken, and propose the
+fix inline rather than just flagging the problem — for example: "Heading uses title case ('Configure Your
+Network') — should be sentence case: 'Configure your network'." Group findings by section so the author can
+work through them in the order they appear in the file.