Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

update prose and trim skill

Adrian Kahali334b78f2f56d
diff --git a/.agents/skills/docs-style/SKILL.md b/.agents/skills/docs-style/SKILL.md
index b333ab1f9f..3db2ef760b 100644
--- a/.agents/skills/docs-style/SKILL.md
+++ b/.agents/skills/docs-style/SKILL.md
@@ -1,126 +1,78 @@
---
name: docs-style
-description: Write, edit, and review Infisical documentation to the house style guide. Use whenever creating or changing any file under docs/ (.mdx pages, snippets, docs.json navigation), when asked to document a feature, write or update a guide, or review a docs diff or pull request. Covers the deterministic Vale lint plus the sentence-level review pass Vale cannot check.
+description: Write, edit, and review Infisical documentation to the house style guide. Use whenever creating or changing any file under docs/ (.mdx pages, snippets, docs.json navigation), when asked to document a feature, write or update a guide, or review a docs diff or pull request. Covers running the Vale linter and the sentence-level review that Vale can't do.
---
# Infisical docs style
-`docs/STYLE_GUIDE.md` is the source of truth. Read it before writing. This skill is the
-procedure for applying it, not a second copy of the rules.
+`docs/STYLE_GUIDE.md` holds every rule for Infisical documentation. This skill doesn't repeat
+the rules. This skill describes how to apply them.
-Two things to know up front:
-
-- `make lint-docs-branch` checks maybe a third of the guide. Everything in section 5 and
- section 11 is a judgment call, and those are the rules AI drafts break by default.
-- Vale cannot see prose indented four or more spaces inside a Mintlify component, which is
- roughly half of this repo. A clean run says nothing about a nested page.
+**Before you write or review anything, read all of `docs/STYLE_GUIDE.md` with the Read tool.**
+Don't work from a summary, a diff, or your memory of the guide. Each rule in the guide comes
+with an "Instead of" and "Write" example, and the examples show what the rule means better
+than any summary can.
## Before you write
-Ask the engineer for the facts before drafting. The product knowledge is the part only they
-have, and a draft written without it reads plausible and says nothing.
+Ask the engineer for the facts before you draft anything. Only the engineer knows how the
+feature works, and a draft written without those facts sounds plausible but tells the reader
+nothing useful.
+
+A model is useful for a page's structure: grouping and ordering the sections, and noticing a
+missing section. A model isn't good at writing the sentences. A page with a model-written
+outline and engineer-written sentences reads better than a page the model wrote entirely, so
+offer the engineer that split instead of assuming they want a full draft.
-Then use the model where it earns its place. Structure, grouping, ordering, and spotting the
-section that is missing are worth delegating. Sentences are not. A page whose outline came
-from a model and whose prose came from the engineer beats a fully generated draft every time,
-so offer that split rather than assuming a full draft is wanted.
+Check every fact against the product, not against other docs pages, because other docs pages
+are often out of date:
-Check every fact against the product, not against other docs pages, which lag behind it:
+- **UI steps:** Take button, tab, and field names and the order of screens from the running
+ product, or from the frontend source if you can't reach the running product
+- **Behavior claims:** Read the code path before you describe what the product does; if
+ another docs page seems to contradict the code, find out why before you edit either page
-- **UI steps.** Take button, tab, and field names and the order of screens from the running
- product, or from the frontend source if you can't reach it. Don't copy them from an older
- guide.
-- **Behavior claims.** Read the code path before stating what the product does, such as which
- deployments enforce a limit or which responses share a format. If another page seems to
- contradict what you found, work out why before writing either one.
+## Reviewing
-## Writing
+Review your own drafts the same way you review anyone else's. Work in the following order.
+Check the structure first, because rewriting a sentence is wasted work if the sentence is in
+the wrong section.
-Follow `docs/STYLE_GUIDE.md` sections 1 to 4 and 10 for what belongs on the page: context
-before mechanics, prerequisites in a `## Prerequisites` heading rather than a callout, the
-right component for the shape of the content, and the page structure for its type.
+**1. Run the linter.** Run `make lint-docs-branch` from the repository root. The command exits
+with an error only for error-level problems, so also read the warnings and suggestions it
+prints. `Infisical.UIActions` and `Infisical.Contractions` don't affect the exit code yet, and
+those two rules are the ones most likely to report problems.
-Then run the review pass below over your own draft before handing it over. Every rule in it
-applies to a first draft, including yours.
+Vale doesn't check text indented four or more spaces inside a Mintlify component, and about
+half of the text in this repository is indented that way. If Vale reports no problems on a
+page with nested components, the nested text still needs the checks in steps 3 and 4.
-## Reviewing
+**2. Check the structure against sections 1, 4, 7, 8, and 10 of the guide.** Headings, section
+order, and section breaks are usually fine, whether a person or a model wrote the draft. If the
+structure passes those sections, keep the structure and go to step 3.
+
+**3. Check every sentence against sections 3 and 5 of the guide.** Go through the sections one
+`###` heading at a time. Each heading names one rule, so for each heading, read every sentence
+on the page and check whether the sentence breaks that rule. Then read every sentence out loud,
+as section 5 describes.
+
+**4. Check the formatting against section 11 of the guide.** No automated check covers any
+rule in section 11, so check each rule by reading the page.
+
+Before you hand a draft back, check the draft for every mistake you've already been corrected
+on, including corrections earlier in the same conversation.
+
+**5. Report the findings, then offer to apply them.** Write one finding per line: the location
+as `path/to/file.mdx:12`, the sentence as written, the rule the sentence breaks, and your
+rewrite. Group the findings by file. Then, before you edit anything, ask once whether to apply
+the whole set of findings.
-Work in this order. Structure first, because a rewritten sentence in the wrong section is
-wasted work.
-
-**1. Run the linter.** `make lint-docs-branch` from the repository root. It exits non-zero
-only on errors, so read the printed warnings and suggestions too. `Infisical.UIActions` and
-`Infisical.Contractions` never affect the exit code yet, and they are the two rules most
-likely to have something to say.
-
-**2. Check the structure, then leave it alone.** Headings, ordering, and section breaks are
-usually sound, in a human draft and a model draft alike. Confirm the page reads top to bottom,
-that a reader landing cold is oriented in the first few sentences, and that nothing was
-inserted without connecting it to what surrounds it. Then check what the guide's sections 7,
-8, and 10 ask of structure:
-
-- Sections on the same topic sit next to each other, and each callout is in the section it applies to
-- Every heading makes sense to a reader who doesn't know the topic yet, and no group is called
- "Other"
-- Every prerequisite can be checked before the reader starts, asks for the least access that
- works, and links to where to get it
-
-If the outline holds, accept it and move on.
-
-**3. Rewrite the sentences.** This is where the work is. Take `docs/STYLE_GUIDE.md` section 5
-and check every sentence against it. In practice these catch the most:
-
-- A concept given a human verb. Nothing says, knows, understands, or wants anything.
-- Two sentences making the same point in different words. Keep the one with new information.
-- A definition that needs a second clause to explain its first.
-- A transitive verb with no object, as in "the agent requests". Read the second half of every
- long sentence on its own; a verb left with nothing to act on is usually a sentence that lost
- its tail in an edit, and it hides a detail nobody settled.
-- An abstract construction standing in for a mechanism the writer may not have known.
-- A metaphor or figurative verb ("drive a resource", "wire Infisical into your tooling", "the
- rest sit between those two"). Say literally what happens.
-- A category where the exact subject belongs ("a resource", "an instance"), or an actor nobody
- can identify ("an admin", "someone").
-- A qualifier with nothing named behind it: a default for what? built into what?
-- A coined term ("worked example") or a specialist word ("prepend", "ingress") where a common
- one exists.
-- A sentence that parses two ways: nouns stacked against the verb, or an opening word that could
- be a noun or a verb ("List endpoints return...").
-- An aside to the reader that adds tone and no information ("so you know when to stop"), or the
- reverse, a condition phrased around an abstract noun ("On a self-hosted instance") when
- "If you self-host Infisical" would say it directly.
-
-Then read every sentence out loud. If you would not say it to a colleague standing next to
-you, rewrite it. That single test catches most of the rest.
-
-**4. Check the formatting Vale cannot see.** Section 11, none of it machine-checked:
-
-- Bold on a word that is not on screen. `**Note**:`, `**important**`, or a whole bolded
- sentence is emphasis, and the prose should carry it instead. A `**Label:**` opening a list
- item is a label, and fine.
-- A button or field name in quotes or a code span rather than bold: `Click 'Submit'`,
- `` Select `SQL Database` ``. Code spans are for code, paths, keystrokes, and literal values.
-- A button or field name with no markup at all, which is the case no pattern can find.
-- A period at the end of a bullet point.
-- "Above" or "below" where a link to the section belongs.
-- A method and path written into a sentence (`POST /api/v1/...`) instead of a description
- linked to the endpoint's reference page, or an endpoint mentioned with no link at all.
-- A sentence telling the reader they can do something, with no link or steps showing how.
-
-Before you hand a draft back, check it for every pattern you've already been corrected on,
-including in this conversation. A correction that comes back a second time is the most
-avoidable mistake there is.
-
-**5. Report, then offer to apply.** One finding per line as `path/to/file.mdx:12`, the sentence
-as written, and the rewrite. Group them by file. Then ask once before editing, for the whole
-set.
-
-Do not silently rewrite an engineer's prose. Their phrasing usually reads more like a person
-talking than a replacement would, and the question worth putting to them is whether they would
-have written the sentence themselves.
+Don't rewrite an engineer's sentences without asking. An engineer's wording often sounds more
+natural than your rewrite does, so ask the engineer whether they would have written your
+version themselves.
## When Vale is wrong
-`docs/CONTRIBUTING.MD` covers adding a word to the vocabulary, enforcing a spelling, and
-suppressing a rule in place with `{/* vale Infisical.RuleName = NO */}`. Suppress a rule only
-where it is genuinely wrong about a specific line, never to quiet a page.
+`docs/CONTRIBUTING.MD` describes how to add a word to the vocabulary, enforce a spelling, and
+turn off a rule for one line with `{/* vale Infisical.RuleName = NO */}`. Turn off a rule only
+on a specific line where Vale is actually wrong, never to hide problems across a whole page.
diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md
index c05662492c..e171f2349b 100644
--- a/docs/STYLE_GUIDE.md
+++ b/docs/STYLE_GUIDE.md
@@ -4,26 +4,26 @@ This guide defines how to write user-facing documentation for Infisical.
## Quick summary
-1. **Provide context** — Explain what and why before how. Don't assume prior knowledge.
-2. **Write for users** — No implementation details. Users care about outcomes, not internals.
-3. **Cross-reference** — Link concepts that are essential for understanding.
-4. **Use Mintlify components** — Steps, Tabs, Cards, Accordions, callouts, diagrams.
-5. **Write clearly** — Plain technical English. Say exactly what you mean, with active voice, specific verbs, and sparing em dashes.
-6. **Keep pages focused** — One purpose per page.
-7. **Maintain flow** — New content should connect naturally with existing content.
-8. **State prerequisites** — Tell readers what they need before they start.
-9. **Be consistent** — Use the same terms throughout.
-10. **Structure by purpose** — Guides, concepts, overviews, and references have different shapes.
-11. **Use sentence case** — Write page titles, sidebar titles, and headings in sentence case.
-12. **Rewrite the sentences** — Say it once, in your own voice. Read every sentence out loud.
-13. **Bold is for UI** — Bold marks buttons, menus, and fields. Use "select", not "click" or "tap".
-14. **Run the linter** — `make lint-docs-branch` checks the mechanical rules in this guide.
+1. **Provide context:** Explain what a feature is and why readers would use it before explaining how to use it.
+2. **Write for users:** Describe what users can do and what happens, not how Infisical is built.
+3. **Cross-reference:** Link every concept a reader needs to know to understand the page.
+4. **Use Mintlify components:** Steps, Tabs, Cards, Accordions, callouts, and diagrams.
+5. **Write clearly:** Write plain technical English. Say exactly what you mean, with active voice, specific verbs, and few em dashes.
+6. **Keep pages focused:** Give each page one purpose.
+7. **Maintain flow:** Connect new content to the content around it.
+8. **State prerequisites:** Tell readers what they need before they start.
+9. **Be consistent:** Use the same term for the same thing on every page.
+10. **Structure by purpose:** Guides, concept pages, overviews, and reference pages each need a different structure.
+11. **Use sentence case:** Write page titles, sidebar titles, and headings in sentence case.
+12. **Rewrite the sentences:** Say each thing once, in your own words. Read every sentence out loud.
+13. **Bold is for UI:** Use bold only for buttons, menus, and fields. Use "select", not "click" or "tap".
+14. **Run the linter:** `make lint-docs-branch` checks the rules in this guide that a pattern can match.
---
## 1. Provide context for new users
-Don't assume the reader already knows what a feature is or why it matters. Every page should orient a new user before diving into details.
+Don't assume the reader already knows what a feature does or why they'd use it. Every page should explain what the feature is before it goes into details.
**Start with the "what" and "why":**
@@ -31,17 +31,17 @@ Don't assume the reader already knows what a feature is or why it matters. Every
- Why would someone use it?
- When is it relevant?
-Then move to the "how."
+Then explain the "how."
-**Bad:** Jumping straight into configuration steps without explaining what the feature does.
+**Bad:** Starting with configuration steps without explaining what the feature does.
-**Good:** A brief opening paragraph that explains what this is and why it matters, then the steps.
+**Good:** A short opening paragraph that explains what the feature is and why it matters, followed by the steps.
-If a reader lands on the page with no prior context, they should be able to understand what they're looking at within the first few sentences.
+A reader who opens the page without knowing anything about the feature should understand what the page covers after the first few sentences.
### Audience callouts
-If a page is intended for a specific audience (admins vs. end users, product admins vs. application admins), say so at the top with an `<Info>` callout:
+If a page is written for a specific audience (admins vs. end users, product admins vs. application admins), say so at the top of the page with an `<Info>` callout:
```mdx
<Info>
@@ -51,36 +51,17 @@ If a page is intended for a specific audience (admins vs. end users, product adm
</Info>
```
-This helps readers quickly know if they're in the right place.
-
-### "When to use" sections
-
-For pages that describe one approach among several (e.g., ACME vs. EST vs. SCEP), include a "When to use" section that helps readers decide if this is the right choice:
-
-```mdx
-## When to use ACME enrollment
-
-<CardGroup cols={2}>
- <Card title="Web Servers" icon="server">
- Nginx, Apache, Tomcat with Certbot.
- </Card>
- <Card title="Kubernetes" icon="settings">
- Use cert-manager to issue certificates.
- </Card>
-</CardGroup>
-```
-
-This makes it easier for readers to quickly assess whether to continue reading or look elsewhere.
+An audience callout tells readers right away whether the page is meant for them.
---
## 2. Write for users, not implementers
-Documentation should be readable and understandable by someone who has never seen our codebase.
+A reader who has never seen the Infisical codebase should be able to understand every page.
-**The test:** Would a user who has never seen our code understand this? If the answer is no, rewrite it.
+**The test:** Would a user who has never seen the Infisical code understand this sentence? If the answer is no, rewrite the sentence.
-Users care about what they can do and what happens — not how we built it. Don't expose implementation details like API endpoints, database schemas, internal service names, or "how it works under the hood" explanations.
+Describe what users can do and what happens when they do it, not how Infisical is built. Leave out implementation details such as internal API endpoints, database schemas, internal service names, and explanations of how a feature works internally.
**Exception:** Architecture docs (`*/architecture.mdx`) can explain system design.
@@ -88,9 +69,9 @@ Users care about what they can do and what happens — not how we built it. Don'
## 3. Cross-reference core concepts
-When you reference a concept that is core to understanding the page, link to its documentation. If a reader wouldn't understand the page without knowing what that concept means, link it.
+If a reader needs to know what a concept means to understand the page, link the concept to its documentation.
-Link on the first mention of a concept on the page — not every time it appears. After the first linked mention, readers know what it is and can scroll back if needed.
+Link a concept the first time the page mentions the concept, not every time. Readers who need the link again can scroll back to the first mention.
```mdx
<!-- Good: Gateway is core to understanding this page -->
@@ -106,7 +87,7 @@ Permissions are set at the folder level.
### Link instead of pointing
-Don't send readers "above" or "below". Link to the section, on this page or another, so they don't have to scroll and guess which part you mean.
+Don't refer readers to content "above" or "below". Link to the section instead, whether the section is on the same page or another page, so readers don't have to scroll to find the section you mean.
**Instead of:** These limits differ from the Infisical Cloud limits above.
@@ -114,7 +95,7 @@ Don't send readers "above" or "below". Link to the section, on this page or anot
### Say how, whenever you say someone can do something
-If a sentence tells the reader they can do something, don't leave them to guess how. Link to the instructions. If the steps are short and no page covers them, write them inline.
+If you tell the reader they can do something, link to the instructions for doing it. If no page has those instructions and the steps are short, write the steps on the page.
**Instead of:** An admin can change these limits.
@@ -122,7 +103,7 @@ If a sentence tells the reader they can do something, don't leave them to guess
### Refer to endpoints by what they do, and link them
-In prose, describe an endpoint in words and link its reference page. Keep the method and path for code blocks. Any endpoint you mention should be linked, including one you only mention in passing.
+In a sentence, describe what an endpoint does and link to the endpoint's reference page. Use the method and path only in code blocks. Link every endpoint you mention, even an endpoint you mention only in passing.
**Instead of:** Call `POST /api/v1/auth/universal-auth/login` with the client ID and client secret.
@@ -132,11 +113,11 @@ In prose, describe an endpoint in words and link its reference page. Keep the me
## 4. Use Mintlify components
-Take full advantage of Mintlify's component library rather than relying on plain markdown. Components make documentation more scannable, interactive, and easier to navigate.
+Use a Mintlify component instead of plain Markdown wherever a component fits the content. Components make pages easier to scan and navigate.
### Procedures
-Use `<Steps>` when readers need to complete a discrete, ordered procedure, especially a sequence of actions in the Infisical UI. Leave out the `title` prop; each step is the action itself:
+Use `<Steps>` for a procedure the reader completes in order, such as a sequence of actions in the Infisical UI. Leave out the `title` prop, and start each step with the action the reader takes:
```mdx
<Steps>
@@ -149,7 +130,7 @@ Use `<Steps>` when readers need to complete a discrete, ordered procedure, espec
</Steps>
```
-A guide with more than one stage uses a heading per stage, in the form `## Step 1: Configure in Infisical`, with the stage's individual actions in a `<Steps>` block under it:
+If a guide has more than one stage, give each stage a heading in the form `## Step 1: Configure in Infisical`, and put the actions for that stage in a `<Steps>` block under the heading:
```mdx
## Step 1: Create a machine identity
@@ -164,11 +145,11 @@ A guide with more than one stage uses a heading per stage, in the form `## Step
</Steps>
```
-Write the steps from the product as it is now, not from an older page that describes it. Button names, tab names, and the order of screens change, and a guide copied from another guide inherits its mistakes.
+Take button names, tab names, and the order of screens from the current product, not from an older docs page. Button names, tab names, and the order of screens change between releases, so a guide copied from another guide repeats any mistakes in the older guide.
### Alternative approaches
-Use `<Tabs>` when there are multiple ways to accomplish something:
+Use `<Tabs>` when the reader can complete a task in more than one way:
```mdx
<Tabs>
@@ -179,7 +160,7 @@ Use `<Tabs>` when there are multiple ways to accomplish something:
### Callouts
-Use callouts to highlight important information:
+Use a callout for information the reader shouldn't miss:
```mdx
<Note>Important context that applies to a specific part of the page.</Note>
@@ -188,11 +169,11 @@ Use callouts to highlight important information:
<Info>Additional context that's good to know.</Info>
```
-Don't use callouts for page-level prerequisites. Put them under a `## Prerequisites` heading instead.
+List page-level prerequisites under a `## Prerequisites` heading, not in a callout.
### Navigation
-Use `<Card>` and `<CardGroup>` to guide readers to related pages:
+Use `<Card>` and `<CardGroup>` to link to related pages:
```mdx
<CardGroup cols={2}>
@@ -207,7 +188,7 @@ Use `<Card>` and `<CardGroup>` to guide readers to related pages:
### Diagrams and visuals
-Use diagrams when explaining technical concepts with multiple connecting pieces. Visuals help readers understand relationships, data flows, and architecture far better than text alone.
+Use a diagram to explain how several components connect. A diagram shows relationships, data flows, and architecture more clearly than text alone.
**Good candidates for diagrams:**
@@ -215,20 +196,20 @@ Use diagrams when explaining technical concepts with multiple connecting pieces.
- Request/response flows
- Authentication or authorization flows
- Architecture overviews
-- Anything with multiple steps happening across different systems
+- A process with steps that run on different systems
-Mintlify supports [Mermaid diagrams](https://mermaid.js.org/) inline, or you can include images.
+You can write a diagram inline with [Mermaid](https://mermaid.js.org/) or include the diagram as an image.
### Frequently asked questions
-Use `<AccordionGroup>` with `<Accordion>` for FAQ sections. FAQs are valuable — they address common questions, edge cases, and "but what about..." scenarios without cluttering the main content.
+Use `<AccordionGroup>` with `<Accordion>` for FAQ sections. An FAQ answers common questions and covers edge cases without adding them to the main content of the page.
**Consider adding FAQs when:**
-- A feature has common gotchas or misconceptions
+- Readers commonly misunderstand how a feature behaves
- Users often ask the same questions
-- There are edge cases that don't fit the main flow
-- The "how it works" has nuances worth explaining
+- An edge case doesn't fit into the main steps
+- A feature behaves in a way that needs more explanation than the main content gives
```mdx
<AccordionGroup>
@@ -241,33 +222,33 @@ Use `<AccordionGroup>` with `<Accordion>` for FAQ sections. FAQs are valuable
</AccordionGroup>
```
-FAQs make documentation easier to scan — readers can jump straight to their question instead of hunting through paragraphs.
+An FAQ lets readers go straight to their question instead of searching through paragraphs.
### Code examples
-Include code examples only when they genuinely help understanding — not to make documentation look technical or comprehensive. A well-placed example clarifies; too many examples overwhelm.
+Include a code example only when the example helps the reader understand or complete the task, not to make the page look thorough. Too many examples make a page harder to follow.
**When to include code:**
- The syntax isn't obvious from the description alone
- Readers need something copy-pasteable to get started
-- Showing expected output helps verify success
+- Showing the expected output helps readers confirm the command worked
**When to skip code:**
-- The UI walkthrough is sufficient
-- The concept is better explained in prose
-- Adding code would just repeat what's already clear
+- The UI steps are enough on their own
+- Prose explains the concept better than code
+- The code would repeat what the text already says
**When you do include code:**
-- Make it copy-pasteable — no `$` prompts that break pasting
+- Make the code copy-pasteable (no `$` prompts, which break pasting)
- Use obvious placeholders: `<your-api-key>`, `<project-id>`, not `abc123` or `foo`
- Use realistic values where possible (actual domain names, plausible configs)
-- Show expected output when it helps readers verify they did it right
-- Keep examples minimal — show what's needed, not everything possible
+- Show the expected output when the output helps readers confirm the command worked
+- Keep examples short, showing only what the task needs
- Check that every endpoint in an example exists, accepts the credential the example sends (an endpoint that only accepts user sessions rejects a machine identity token), and has a reference page with content
-- Pick endpoints that work for every reader of the page. A getting-started example shouldn't call an endpoint that only works for one product unless the page is about that product
+- Pick endpoints that work for every reader of the page; a getting-started example shouldn't call an endpoint that only works for one product unless the page is about that product
```bash
# Good: obvious placeholder, minimal, copy-pasteable
@@ -286,30 +267,30 @@ curl -X POST https://app.infisical.com/api/v1/secrets \
### Other components
-Mintlify offers many more components — use whatever best serves the reader's understanding.
+Mintlify has more components than this section lists. Use any component that makes the content easier to understand.
---
## 5. Write clearly and directly
-Documentation should read like instructions from a knowledgeable colleague: direct, specific, and easy to follow.
+Write the way a colleague who knows the product would give you instructions: directly, specifically, and in an order you can follow.
- Prefer active voice over passive
- Use specific verbs over vague ones
- Keep sentences and paragraphs concise
-- Explain jargon on first use
+- Explain jargon the first time you use it
### Don't give human verbs to things that aren't human
-A path, a policy, or a property doesn't say, know, understand, or want anything. Name the actor and the behavior.
+A path, a policy, or a property can't say, know, understand, or want anything. Name who or what performs the action, and describe the action.
**Instead of:** A grant on `/payments` says nothing about `/payments/keys`.
-**Write:** If you have a role on `/payments`, that role does not automatically apply to `/payments/keys`.
+**Write:** If you have a role on `/payments`, that role doesn't automatically apply to `/payments/keys`.
### Say what a thing is, in one clause
-Define a field or a concept plainly. If a second clause has to explain the first, the first clause isn't doing any work.
+Define a field or a concept in one plain clause. If you need a second clause to explain the first clause, rewrite the first clause so it says what the field or concept is.
**Instead of:** The `scope` property defines the boundary within which a grant is considered valid.
@@ -317,7 +298,7 @@ Define a field or a concept plainly. If a second clause has to explain the first
### Say it once
-Cut sentences that restate the previous sentence in new words. Keep the one that carries new information.
+If a sentence repeats the previous sentence in different words, delete whichever of the two sentences adds less information.
**Instead of:** Access is granted per folder. Each folder carries its own access list. Because access is defined at the folder level, permissions on one folder do not carry over to another.
@@ -325,7 +306,7 @@ Cut sentences that restate the previous sentence in new words. Keep the one that
### Keep pronouns next to what they refer to
-If a reader has to scan backwards to work out what "it" or "they" points at, repeat the noun. Repeating a word costs less than a reparse.
+If a reader has to look back to find out what "it" or "they" refers to, repeat the noun instead. A repeated word is easier to read than a sentence the reader has to parse twice.
**Instead of:** Add the service token to the project, then open the environment settings and confirm that it is active.
@@ -337,17 +318,17 @@ If a reader has to scan backwards to work out what "it" or "they" points at, rep
### Give every transitive verb its object
-A verb like request, create, return, send, or apply has to say what. Drop the object and the reader has to guess, and the gap often marks a detail the writer had not settled yet.
+Verbs like request, create, return, send, and apply need an object that says what is requested, created, returned, sent, or applied. Without the object, the reader has to guess, and a missing object often means the writer hadn't decided that detail yet.
**Instead of:** You create the service in your Infisical dashboard, and the agent requests.
**Write:** You create the service in your Infisical dashboard, and the agent requests credentials for it.
-This usually happens to a sentence that was edited after it was written, losing its tail. Read the second half of every long sentence on its own and check that each verb in it has something to act on.
+An object usually goes missing when someone edits a sentence and cuts off the end of the sentence. Read the second half of every long sentence on its own, and check that each verb in that half has an object.
### Lead with the behavior, not a label for it
-Calling something an exception, a special case, or a caveat tells the reader to brace without telling them what for. State the behavior first.
+Calling something an exception, a special case, or a caveat warns the reader that something is different without saying what is different. Describe the behavior instead.
**Instead of:** Folder access is the exception.
@@ -355,7 +336,7 @@ Calling something an exception, a special case, or a caveat tells the reader to
### Split mid-sentence detours
-A clause wedged into the middle of a sentence makes the eye jump back to pick up the thread. Split the sentence, or move the condition to the front.
+A clause in the middle of a sentence interrupts the sentence, and the reader has to go back to find where the main clause left off. Split the sentence into two sentences, or move the clause to the start of the sentence.
**Instead of:** The menu adds temporary access and once a grant exists removes folder access.
@@ -363,7 +344,7 @@ A clause wedged into the middle of a sentence makes the eye jump back to pick up
### Name what actually happens
-Replace an abstract construction with the system, the input, and the result. Abstraction hides whether the writer knew the mechanism.
+Instead of an abstract phrase, say which system does what, with which input, and what the result is. An abstract phrase can hide the fact that the writer didn't know how the feature works.
**Instead of:** Permissions are evaluated against the resource hierarchy.
@@ -371,7 +352,7 @@ Replace an abstract construction with the system, the input, and the result. Abs
### Say exactly what you mean
-This is technical documentation. Write plain, literal English. Metaphors and figurative verbs make the reader translate the sentence before they can use it. Always say exactly what you mean outright.
+This is technical documentation. Write plain, literal English. A reader has to translate a metaphor or a figurative verb into what actually happens before they can act on the sentence. Always say exactly what you mean outright.
**Instead of:** Use the API to drive every resource and wire Infisical into your tooling.
@@ -383,7 +364,7 @@ This is technical documentation. Write plain, literal English. Metaphors and fig
### Name the exact subject
-Refer to the specific thing the sentence is about, not a broader category it belongs to. If you say "a resource" or "an instance" has to work out which one you mean.
+Name the specific thing you're describing, not a broader category that includes it. If you write "a resource" or "an instance", the reader has to work out which resource or instance you mean.
**Instead of:** A resource's version is only incremented for breaking changes.
@@ -391,7 +372,7 @@ Refer to the specific thing the sentence is about, not a broader category it bel
### Say what a qualifier refers to
-Words like "default", "built-in", "underlying", and "standard" point at something else: a default for what? built into what? If the sentence doesn't name that thing, the reader has to guess. Swapping one of these words for another doesn't fix it. Show the thing itself.
+Words like "default", "built-in", "underlying", and "standard" only make sense with the thing they refer to: a default for what? built into what? If the sentence doesn't name that thing, the reader has to guess. Replacing one of these words with another doesn't fix the sentence. Name the thing, or describe the thing directly.
**Instead of:** If you self-host Infisical, the built-in defaults apply.
@@ -399,7 +380,7 @@ Words like "default", "built-in", "underlying", and "standard" point at somethin
### Use common words
-Prefer a word any reader knows over one that only people in a particular specialty use. If a technical term is the only accurate one, explain it or link to it.
+Use a word every reader knows instead of a word only specialists use. If a technical term is the only accurate word, explain the term or link to a page that explains the term.
**Instead of:** Prepend the base URL to the path. Apply throttling at your ingress or reverse proxy.
@@ -407,7 +388,7 @@ Prefer a word any reader knows over one that only people in a particular special
### Don't invent terms
-Use the name the product, the protocol, or everyday English already has for something. A coined phrase like "worked example" or "response envelope" reads as if it's a term the reader should already know.
+Use the name that the product, the protocol, or everyday English already has for something. Made-up phrases such as "worked example" or "response envelope" are confusing.
**Instead of:** This page shows one worked example.
@@ -417,9 +398,9 @@ Use the name the product, the protocol, or everyday English already has for some
If a reader can parse a sentence two ways, it makes the sentence harder to understand and could force the reader to reread the sentence. There are two main causes for this problem:
-1. Nouns stacked against the verb. In "Any endpoint that returns a list of resources paginates", "resources paginates" reads as a unit. Don't compress a sentence until its words run into each other. A clear sentence beats a short one.
+1. A noun placed directly before the verb, so the noun and the verb read as one phrase. In "Any endpoint that returns a list of resources paginates", the words "resources paginates" read as one phrase. Don't shorten a sentence so much that its nouns and verbs end up next to each other like this. A clear sentence is better than a short one.
-2. A first word that can be a noun or a verb. A sentence opening with "List endpoints" reads as an instruction to list endpoints until the real verb arrives, and a reader who doesn't know the term "list endpoint" yet can't resolve it early.
+2. A first word that can be either a noun or a verb. A reader who sees "List endpoints" at the start of a sentence reads the words as an instruction to list endpoints until the sentence's real verb appears. A reader who doesn't know the term "list endpoint" has no way to tell sooner.
**Instead of:** List endpoints in the Infisical API return one page of results per request.
@@ -427,13 +408,13 @@ If a reader can parse a sentence two ways, it makes the sentence harder to under
### Address the reader only to add information
-Chatty asides aimed at the reader add tone and no information.
+Don't add asides to the reader that make a sentence friendlier without adding information.
**Instead of:** The response includes `totalCount`, so you know when to stop.
**Write:** The response includes `totalCount`, which you can use to tell when you've read every page.
-Do address the reader when their situation decides whether a sentence applies. A condition phrased around the reader is concrete. The same condition phrased around an abstract noun leaves them to work out whether it's them.
+Do address the reader when the reader's situation decides whether a sentence applies to them. A condition written about the reader ("If you self-host Infisical") tells readers directly whether the sentence applies to them. The same condition written about an abstract noun ("On a self-hosted instance") leaves readers to work out whether the condition includes them.
**Instead of:** On a self-hosted or dedicated instance, replace the host.
@@ -441,17 +422,17 @@ Do address the reader when their situation decides whether a sentence applies. A
### Use contractions
-Write "it's", "don't", "you'll", and "can't". Full forms read stiff and slow the sentence down for no gain.
+Write "it's", "don't", "you'll", and "can't". Full forms sound stiff and make sentences longer without adding anything.
**Instead of:** It is not possible to recover a deleted secret. You will need to create it again.
**Write:** You can't recover a deleted secret, so you'll need to create it again.
-Vale flags the common full forms as suggestions.
+Vale reports the common full forms as suggestions.
### Read it out loud
-Read every sentence out loud before you submit it. If you wouldn't say it to a colleague standing next to you, rewrite it. This one test catches most of the rules above.
+Read every sentence out loud before you submit the page. If you wouldn't say a sentence that way to a colleague standing next to you, rewrite the sentence. Most sentences that break a rule in this section also fail this test.
**Instead of:** Access removal is reflected within the propagation window.
@@ -488,28 +469,28 @@ sidebarTitle: "Docker Quickstart"
### Don't overuse em dashes
-Reach for a comma, colon, parentheses, or a full stop first. An occasional em dash is fine, but several in a paragraph, or one in most sentences, means the punctuation is doing the work that sentence structure should.
+Use a comma, a colon, parentheses, or a period before you use an em dash. An occasional em dash is fine. If a paragraph has several em dashes, or most of its sentences have one, restructure the sentences instead of adding more punctuation.
---
## 6. Keep pages focused
-Each page should have a clear, single purpose. Keep related workflows together when readers benefit from seeing them in one place. For example, an integration guide can cover several delivery methods and related configuration such as Docker Compose as long as every section serves the same integration goal.
+Give each page one purpose. Keep related workflows on the same page when readers need to see the workflows together. For example, an integration guide can cover several delivery methods and related configuration, such as Docker Compose, as long as every section helps the reader set up that integration.
-Use `<Tabs>` for alternative methods when readers choose one path. Use headings for related extensions that readers may complete after the primary workflow. Split a page when its sections serve genuinely different purposes, not merely because the page is long.
+Use `<Tabs>` for alternative methods when readers pick only one of the methods. Use headings for related tasks that readers might complete after the main workflow. Split a page when its sections have different purposes, not just because the page is long.
**Signs a page should be split:**
- Readers have to scroll past content that isn't relevant to them
- The table of contents has more than 5-6 top-level sections
-- Different audiences have unrelated goals (e.g., admins configuring infrastructure vs. end users consuming it)
+- Different audiences have unrelated goals (for example, admins configuring infrastructure vs. end users consuming it)
**Better structure:**
- One page for the concept overview
- Separate pages for each workflow or use case
- A dedicated page for reference material (configuration options, API fields)
-- Troubleshooting as its own page if it's substantial
+- A separate troubleshooting page if the troubleshooting content is long
Short, focused pages are easier to navigate, easier to link to, and easier to maintain.
@@ -517,20 +498,20 @@ Short, focused pages are easier to navigate, easier to link to, and easier to ma
## 7. Maintain flow when editing
-When adding or modifying content on an existing page, make sure it fits naturally with what comes before and after. Don't just insert content — connect it.
+When you add or change content on an existing page, make sure the new content follows from the section before it and leads into the section after it. Don't insert content without connecting the content to the text around it.
**Check that:**
-- The page still reads coherently from top to bottom
-- New sections follow logically from previous ones
-- Transitions make sense (readers shouldn't feel jarred)
-- The overall narrative or structure isn't broken
+- The page still reads in order from top to bottom
+- Each new section follows from the section before it
+- Readers can follow the move from each section to the next
+- The order of sections on the page still makes sense
-If new content doesn't fit the existing flow, consider whether it belongs on this page at all, or whether the page structure needs to be reorganized.
+If new content doesn't fit the page's existing order, decide whether the content belongs on this page, or whether the page needs to be reorganized.
### Order sections the way a reader looks for them
-Think about where a reader's eyes will go. Keep sections that cover the same topic from different angles next to each other, and put anything that applies to all of them after the whole group, not between two of its members. A callout goes in the section it applies to.
+Put each section where a reader will look for it. Keep sections that cover the same topic from different angles next to each other, and put content that applies to all of those sections after the whole group, not between two of the sections. Put each callout in the section the callout applies to.
**Instead of:** Cloud limits, then what happens when a request is rate limited, then self-hosted limits, with a note about Cloud plans at the bottom of the self-hosted section.
@@ -540,7 +521,7 @@ Think about where a reader's eyes will go. Keep sections that cover the same top
## 8. State prerequisites explicitly
-If a page assumes something is already set up — a Gateway deployed, permissions granted, a CLI installed — state it at the top. Readers shouldn't get stuck halfway through because they missed an unstated requirement.
+If a page assumes something is already set up, such as a deployed Gateway, granted permissions, or an installed CLI, list that requirement at the top of the page. Otherwise, readers can get stuck halfway through the steps because of a requirement the page didn't mention.
Use a `## Prerequisites` section before the main content, even when the list is short:
@@ -551,33 +532,33 @@ Use a `## Prerequisites` section before the main content, even when the list is
- A [Gateway](/documentation/platform/gateways/overview) that can reach your database
```
-Don't put page-level prerequisites in `<Info>` or other callouts. Reserve `<Note>` for requirement details that apply to a specific step rather than the whole page.
+Don't put page-level prerequisites in `<Info>` or other callouts. Use `<Note>` only for a requirement that applies to one step, not to the whole page.
-**Make each prerequisite something the reader can check before they start.** A reader at the top of the page hasn't seen the steps yet, so a prerequisite that depends on them is no use.
+**Make each prerequisite something the reader can check before they start.** A reader at the top of the page hasn't read the steps yet, so the reader can't check a prerequisite that depends on the steps.
**Instead of:** A role with the permissions required by the endpoints called in this guide
**Write:** A role that grants read access to secrets, such as **Viewer**
-**Ask for the least access that works, and cover the access readers actually have.** Many readers aren't organization admins. If the task also works with project-level access, say so and give that path too.
+**Ask for the least access that works, and cover the kinds of access readers actually have.** Many readers aren't organization admins. If the task also works with project-level access, say so and give the project-level steps too.
**Instead of:** An Infisical organization where you have the **Admin** role
**Write:** The [Admin role](/documentation/platform/access-controls/role-based-access-controls) on either your Infisical organization or a project in the organization
-**Link each prerequisite** to where the reader can get it or learn what it is.
+**Link each prerequisite** to a page where the reader can get the prerequisite or learn what the prerequisite is.
-**Walk readers through setup that a beginner won't have done.** If a quickstart needs a resource most first-time readers don't have yet, such as a machine identity, create it in the steps instead of listing it as a prerequisite.
+**Include setup that a beginner won't have done yet.** If a quickstart needs a resource that most first-time readers don't have yet, such as a machine identity, create the resource in the steps instead of listing it as a prerequisite.
---
## 9. Use consistent terminology
-Use the same terms throughout the documentation. Don't switch between synonyms for the same concept — it confuses readers and makes searching harder.
+Use the same term for a concept on every page. Switching between synonyms for the same concept confuses readers and makes search results less useful.
**Examples:**
-- Pick "secret" or "credential" and stick with it in context
+- Pick "secret" or "credential" and use the same word throughout a page
- Don't mix "folder" and "directory" interchangeably
- Don't call something a "project" in one place and a "workspace" in another
@@ -587,23 +568,23 @@ If Infisical has a specific term for something, use that term consistently.
## 10. Page structure
-Structure depends on what the page is for. Don't force every page into the same template.
+Choose a page's structure based on what the page is for. Pages with different purposes need different sections.
**All pages need:**
- Frontmatter with a `title` and a `description`
-- An opening that orients the reader
+- An opening that tells the reader what the page covers
-`sidebarTitle` is optional. Add one when the page title is too long for the sidebar or reads
-poorly out of context; otherwise the title is used.
+`sidebarTitle` is optional. Add a `sidebarTitle` when the page title is too long for the sidebar or
+doesn't make sense on its own in the sidebar. Without a `sidebarTitle`, the sidebar shows the page title.
-**Headings name the topic in words a newcomer recognizes.** The list of headings is often the first thing a reader scans. A code or term they don't know yet won't catch their eye.
+**Headings name the topic in words a newcomer recognizes.** Readers often scan the headings before anything else on a page. A heading built around a code or a term the reader doesn't know yet won't help the reader find the section they need.
**Instead of:** `## 429 response`
**Write:** `## Exceeding rate limits (429 response)`
-**Name groups for what they contain.** When items fall into categories, give each category a real name. "Other" tells the reader nothing, so look for what the remaining items have in common.
+**Name groups for what they contain.** When items fall into categories, give each category a name that describes its items. "Other" tells the reader nothing, so find what the remaining items have in common and name the group after that.
**Instead of:** Universal Auth, Cloud providers, Other methods
@@ -617,47 +598,46 @@ poorly out of context; otherwise the title is used.
**Concept pages:**
-- Explanation of what it is and why it matters
-- How components relate to each other
+- An explanation of what the concept is and why it matters
+- How the components relate to each other
- Links to related concepts and guides
**Overview / Landing pages:**
-- Brief intro
-- Navigation cards to sub-pages
-
-A landing page that heads a whole section has a further job: it should let a reader
-understand what the section contains without reading the sidebar. Mirror the section's
-structure on the page.
-
-- Open with one or two sentences saying what the section is for. Not a definition of the
- product, just what a reader will find here.
-- Cover every group in that section's sidebar. How much you expand each one depends on the
- group:
- - **One card for the group** when its pages are steps or reference for a single topic. The
- card points at the group's entry point and the description says what the group is for.
- Networking does this: one card for Gateways, one for Relays.
- - **A card per page** when the pages are parallel choices the reader picks between, and
- seeing all the options is the point. Self-hosting does this for deployment platforms,
- where a reader is scanning for the one they already run.
-- Give each group its own `##` heading, using the same name as the sidebar, once a section
- has enough groups that a single card group would run long. A short section can carry them
- all in one `<CardGroup>` with no headings at all.
-- Card titles should match their sidebar labels so a card and its destination read the same.
-- Put deeper explanation below the cards, not above them. Someone who arrived to navigate
- should not have to scroll past a concept page to find the links.
-- Detail that only some readers want, such as the reasoning behind a choice, belongs in an
- `<Accordion>` so it does not push the cards down the page.
-
-See `self-hosting/overview`, `documentation/platform/gateways/overview`, and
-`documentation/platform/identities/overview` for the pattern.
+- A short introduction
+- Navigation cards that link to the section's pages
+
+A landing page at the top of a docs section also needs to show readers what the section
+contains, so readers don't have to read the sidebar to find out. Organize the landing page the
+same way the section's sidebar is organized.
+
+- Start with one or two sentences about what readers will find in the section, not a
+ definition of the product
+- Cover every group in the section's sidebar, in one of two ways depending on the group:
+ - **One card for the group** when the group's pages are steps or reference material for a
+ single topic; the card links to the group's first page, and the card description says what
+ the group covers (for example, Networking has one card for Gateways and one for Relays)
+ - **A card per page** when the pages are alternatives the reader chooses between and the
+ reader needs to see every option (for example, Self-hosting has a card for each deployment
+ platform so readers can find the platform they already use)
+- If the section has enough groups that one `<CardGroup>` would be too long, give each group a
+ `##` heading with the same name the sidebar uses; a short section can put all its cards in
+ one `<CardGroup>` with no headings
+- Use each page's sidebar label as the title of the card that links to the page
+- Put longer explanations after the cards, so readers looking for a link don't have to scroll
+ past the explanations to find it
+- Put detail that only some readers want, such as the reasons behind a choice, in an
+ `<Accordion>` so the detail doesn't push the cards down the page
+
+For examples of landing pages, see `self-hosting/overview`,
+`documentation/platform/gateways/overview`, and `documentation/platform/identities/overview`.
**Reference pages:**
- Structured information (tables, field descriptions)
- Examples where helpful
-Use the structure that best serves the reader for that type of content.
+Use whichever structure makes the page's type of content easiest to read.
---
@@ -665,9 +645,9 @@ Use the structure that best serves the reader for that type of content.
### Bold is for UI, never emphasis
-Bold marks something the reader has to find on screen: a button, a menu item, a tab, or a field name. If the prose needs bold to land, rewrite the prose.
+Use bold only for something the reader has to find on screen: a button, a menu item, a tab, or a field name. If a sentence seems to need bold to make its point, rewrite the sentence.
-A bold label that opens a list item or a paragraph is a label rather than emphasis, so `**Prerequisites:**` is fine. An inline `**Note**:` prefix is not. Use a `<Note>` callout instead.
+You can bold a label at the start of a list item or a paragraph, such as `**Prerequisites:**`, because a label isn't emphasis. Don't start a sentence with a bold `**Note**:` prefix. Use a `<Note>` callout instead.
**Instead of:** This is **important**: rotation only applies to **active** secrets.
@@ -675,7 +655,7 @@ A bold label that opens a list item or a paragraph is a label rather than emphas
### Format UI labels as bold, not quotes or code
-A button, tab, or field name goes in bold. Quotes and code spans are for code, paths, keystrokes, and literal values.
+Put button, tab, and field names in bold. Use quotes and code spans only for code, paths, keystrokes, and literal values.
**Instead of:** Click 'Submit', then navigate to `Personal Settings`.
@@ -683,7 +663,7 @@ A button, tab, or field name goes in bold. Quotes and code spans are for code, p
### Select, not click or tap
-Use "select" for any interaction with a control. It covers mouse, touch, and keyboard, and assumes nothing about the reader's device. Gestures with no "select" equivalent keep their own verbs: `right-click` and `double-click`.
+Use "select" for any interaction with a control. "Select" applies to a mouse, a touchscreen, and a keyboard, so the word doesn't assume which device the reader uses. For gestures that "select" can't describe, use `right-click` and `double-click`.
**Instead of:** Click the three dot menu, then tap **Add temporary access**.
@@ -691,7 +671,7 @@ Use "select" for any interaction with a control. It covers mouse, touch, and key
### No periods at the end of bullet points
-End every bullet point without a period. Keep each bullet to one sentence or phrase. If a bullet needs two sentences, combine them with a parenthesis or a semicolon, or turn the list into a paragraph.
+End every bullet point without a period. Keep each bullet to one sentence or phrase. If a bullet needs two sentences, combine the two sentences with a parenthesis, or turn the list into a paragraph.
**Instead of:**
@@ -705,36 +685,38 @@ End every bullet point without a period. Keep each bullet to one sentence or phr
## 12. What Vale enforces
-Some of this guide is checked by [Vale](https://vale.sh). Run `make lint-docs-branch` from
-the repository root before opening a documentation pull request, or `make lint-docs` to check
-every page. The `Check docs style` CI check runs the same rules over the files the pull request
-touched.
-
-Vale cannot see prose indented inside components, which is a large share of this repo. A clean
-run is not evidence that a nested page was checked. See `docs/CONTRIBUTING.MD` for the detail.
-
-Vale covers the mechanical rules only: sentence case in headings and in the `title` and
-`sidebarTitle` fields, consistent product and vendor spellings, spelling against a curated
-vocabulary, `$` prompts in code blocks, placeholder names like `foo`, more than two em
-dashes in one paragraph, "click" and "tap" where the verb should be "select", and the full
-forms of common contractions. The `description` frontmatter field is not checked
-automatically -- watch for it in review.
-
-Two of those rules do not fail the run yet. `Infisical.UIActions` reports at warning level and
-`Infisical.Contractions` at suggestion level, because the existing pages carry several hundred
-of each and a blocking rule would fail every pull request that touches them. Both are on their
-way to error level once the corpus is clean, so fix them on the pages you touch. Read the
-printed output, not just the exit code.
-
-Nothing checks the two bolding rules in section 11. Whether a given noun is a button that
-should be bold, or prose that should not, needs a reader who knows the product.
-
-Everything else here -- providing context, writing for users, cross-referencing, choosing the
-right component, page structure, and every sentence-level rule in section 5 -- is a judgment
-call that only a reviewer can make. A clean Vale run means nothing was mechanically wrong, not
-that the page is good.
-
-Run the `docs-style` skill to get the judgment half checked as well.
-
-See `docs/CONTRIBUTING.MD` for how to invoke that skill, add a word to the vocabulary, enforce
-a new spelling, or suppress a rule where Vale is wrong.
+[Vale](https://vale.sh) checks some of the rules in this guide. Run `make lint-docs-branch` from
+the repository root before you open a documentation pull request, or run `make lint-docs` to
+check every page. The `Check docs style` CI check runs the same rules on the files a pull request
+changes.
+
+Vale doesn't check text indented inside components, and much of the text in this repository is
+indented that way. If Vale reports no problems on a page with nested components, Vale may not
+have checked the nested text. `docs/CONTRIBUTING.MD` describes this limit in more detail.
+
+Vale checks only the rules that a pattern can match: sentence case in headings and in the
+`title` and `sidebarTitle` fields, consistent product and vendor spellings, spelling against a
+list of approved words, `$` prompts in code blocks, placeholder names like `foo`, more than two
+em dashes in one paragraph, "click" and "tap" where the verb should be "select", and the full
+forms of common contractions. Vale doesn't check the `description` frontmatter field, so check
+the description yourself when you review a page.
+
+Two of those rules don't fail the run yet. `Infisical.UIActions` reports at warning level and
+`Infisical.Contractions` reports at suggestion level, because existing pages have several
+hundred violations of each rule, and making either rule an error would fail every pull request
+that edits those pages. Both rules will become errors once the existing violations are fixed,
+so fix any violations on the pages you edit. Read the output Vale prints, not just the exit
+code.
+
+No automated check covers the two bold rules in section 11. Only a reviewer who knows the
+product can tell whether a word is the name of a button that should be bold.
+
+The rest of this guide needs a reviewer's judgment: providing context, writing for users,
+cross-referencing, choosing the right component, page structure, and every sentence-level rule
+in section 5. If Vale reports no problems, the page has no mistakes that a pattern can find, but
+the page can still break every other rule in this guide.
+
+To check the rules that Vale can't, run the `docs-style` skill.
+
+For how to run the skill, add a word to the list of approved words, enforce a new spelling, or
+turn off a rule on a line where Vale is wrong, see `docs/CONTRIBUTING.MD`.