Skip to content

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

add rule about conditionals

Adrian Kahaliba39671e7ef7
diff --git a/.agents/skills/docs-style/SKILL.md b/.agents/skills/docs-style/SKILL.md
index c220092369..68c3988ba0 100644
--- a/.agents/skills/docs-style/SKILL.md
+++ b/.agents/skills/docs-style/SKILL.md
@@ -22,8 +22,8 @@ shared between integration pages work.
## Before you write
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.
+feature works. If you write a draft without those facts, the draft 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
diff --git a/.agents/skills/docs-style/templates/secret-sync.mdx b/.agents/skills/docs-style/templates/secret-sync.mdx
index 3074c646e7..ae22d4b58f 100644
--- a/.agents/skills/docs-style/templates/secret-sync.mdx
+++ b/.agents/skills/docs-style/templates/secret-sync.mdx
@@ -154,7 +154,7 @@ A {Product} Secret Sync pushes secrets from Infisical into {the {Product} destin
<Warning>
{What the secrets in {Product} belong to}, so a sync can change secrets that were created outside Infisical. If you don't customize key names, the sync treats every secret in {the destination} as one it manages:
- - A {Product} secret with the same name as an Infisical secret has its value overwritten
+ - If a {Product} secret has the same name as an Infisical secret, the sync overwrites the {Product} secret's value
- If **Prevent secret deletion** is off, every {Product} secret that isn't in Infisical is deleted
With customized key names, the sync writes only names with your prefix or suffix, and deletes only {Product} secrets whose names match it.
diff --git a/CLAUDE.md b/CLAUDE.md
index c6068a85e0..97885b413b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -96,7 +96,7 @@ If the user wrote or edited the docs prose themselves, don't just accept it. Tel
The style guide covers writing for users (not implementers), Mintlify component usage, cross-referencing, page structure, the sentence-level writing rules in section 5, and the bolding and UI conventions in section 11.
-Run `make lint-docs-branch` after any change under `docs/`. It runs [Vale](https://vale.sh) over the docs and enforces the mechanical half of the style guide: sentence case in headings and frontmatter titles, product and vendor spellings, spelling against a curated vocabulary, `$` prompts in code blocks, and em dash density. See [docs/CONTRIBUTING.MD](docs/CONTRIBUTING.MD) for how to extend the vocabulary or suppress a rule. It lints only the `.mdx` files the branch touched; `make lint-docs` checks every page. The `Check docs style` GitHub workflow runs that same script, so local and CI agree by construction. Every rule except `Infisical.EmDashes` reports at error level, including `Infisical.UIActions` (click/tap where the verb should be select) and `Infisical.Contractions`, so any of their findings fails the run. `Infisical.EmDashes` reports at warning level and never changes the exit code -- read the printed output, not just the status. Note that Vale cannot see prose indented four or more spaces inside components -- roughly half of this repo -- and reports nothing about what it skipped, so a clean run does not mean a nested page was checked.
+Run `make lint-docs-branch` after any change under `docs/`. It runs [Vale](https://vale.sh) over the docs and enforces the mechanical half of the style guide: sentence case in headings and frontmatter titles, product and vendor spellings, spelling against a curated vocabulary, `$` prompts in code blocks, and em dash density. See [docs/CONTRIBUTING.MD](docs/CONTRIBUTING.MD) for how to extend the vocabulary or suppress a rule. It lints only the `.mdx` files the branch touched; `make lint-docs` checks every page. The `Check docs style` GitHub workflow runs that same script, so local and CI agree by construction. Every rule except `Infisical.EmDashes` reports at error level, including `Infisical.UIActions` (click/tap where the verb should be select) and `Infisical.Contractions`, so the run fails if either one reports a finding. `Infisical.EmDashes` reports at warning level and never changes the exit code -- read the printed output, not just the status. Note that Vale cannot see prose indented four or more spaces inside components -- roughly half of this repo -- and reports nothing about what it skipped, so a clean run does not mean a nested page was checked.
### Auth & Permissions
diff --git a/docs/CONTRIBUTING.MD b/docs/CONTRIBUTING.MD
index 55858854e5..6807d610bf 100644
--- a/docs/CONTRIBUTING.MD
+++ b/docs/CONTRIBUTING.MD
@@ -54,8 +54,8 @@ version.
Both targets call `docs/scripts/lint-docs.sh`, and so does the `Check docs style` GitHub
workflow, which runs only on pull requests that touch `docs/` and lints the files the pull
-request changed. A branch that edits the configuration itself -- `.vale.ini`, a file under
-`.vale/styles/`, `.vale-version`, or the script -- is linted in full instead, since a rule
+request changed. If a branch edits the configuration itself -- `.vale.ini`, a file under
+`.vale/styles/`, `.vale-version`, or the script -- every page is linted instead, since a rule
change reaches pages the branch never touched. Local and CI results therefore match. You can
also run `vale <path>` directly on a subset. A run fails only on errors; warnings and
suggestions are printed but do not block.
@@ -72,7 +72,7 @@ placeholders like `foo`, em dashes piling up in one paragraph, "click" and "tap"
verb should be "select", and the full forms of common contractions.
**Every rule except `Infisical.EmDashes` is at error level**, including `Infisical.UIActions`
-and `Infisical.Contractions`, so a finding from either one fails the run. `Infisical.EmDashes`
+and `Infisical.Contractions`, so the run fails if either one reports a finding. `Infisical.EmDashes`
reports at warning level: it is printed but does not change the exit code. Neither
`Infisical.UIActions` nor `Infisical.Contractions` is safe to fix with `vale --fix`. "Click" as a
noun and the deliberately formal phrasing in some reference tables both need a person, so fix
diff --git a/docs/STYLE_GUIDE.md b/docs/STYLE_GUIDE.md
index 0897821b62..fe3024db1e 100644
--- a/docs/STYLE_GUIDE.md
+++ b/docs/STYLE_GUIDE.md
@@ -37,7 +37,7 @@ Then explain the "how."
**Good:** A short opening paragraph that explains what the feature is and why it matters, followed by the steps.
-A reader who opens the page without knowing anything about the feature should understand what the page covers after the first few sentences.
+If a reader opens the page without knowing anything about the feature, the first few sentences should tell them what the page covers.
### Audience callouts
@@ -57,9 +57,9 @@ An audience callout tells readers right away whether the page is meant for them.
## 2. Write for users, not implementers
-A reader who has never seen the Infisical codebase should be able to understand every page.
+Write every page so that readers understand it even if they've never seen the Infisical codebase.
-**The test:** Would a user who has never seen the Infisical code understand this sentence? If the answer is no, rewrite the sentence.
+**The test:** If a user had never seen the Infisical code, would they understand this sentence? If the answer is no, rewrite the sentence.
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.
@@ -145,7 +145,7 @@ If a guide has more than one stage, give each stage a heading in the form `## St
</Steps>
```
-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.
+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 if you copy a guide from another guide, the copy repeats any mistakes in the older guide.
### Alternative approaches
@@ -247,7 +247,7 @@ Include a code example only when the example helps the reader understand or comp
- Use realistic values where possible (actual domain names, plausible configs)
- 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
+- Check that every endpoint in an example exists, accepts the credential the example sends (if an endpoint only accepts user sessions, it 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
```bash
@@ -318,7 +318,7 @@ If a reader has to look back to find out what "it" or "they" refers to, repeat t
### Give every transitive verb its object
-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.
+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. If the object is missing, the writer often hadn't decided that detail yet.
**Instead of:** You create the service in your Infisical dashboard, and the agent requests.
@@ -334,6 +334,20 @@ Calling something an exception, a special case, or a caveat warns the reader tha
**Write:** Folder access doesn't inherit. A role on a parent folder gives no access to the folders inside it.
+### Write conditions as "if" clauses
+
+If a sentence applies only in some cases, state the case in an "if" clause. Don't put the condition inside a made-up subject, such as "a secret that already exists" or "a reader who opens the page". With a made-up subject, the reader has to work out that the sentence is a condition, and has to read a long noun phrase before reaching the verb.
+
+**Instead of:** A secret that already exists in the schema stays owned by the role that created it.
+
+**Write:** If a secret already exists in the schema, it stays owned by the role that created it.
+
+**Instead of:** An endpoint that only accepts user sessions rejects a machine identity token.
+
+**Write:** If an endpoint only accepts user sessions, it rejects a machine identity token.
+
+A clause like "that already exists" is fine when it says which thing you mean instead of stating a condition, as in "Select the role that owns the secrets."
+
### Split mid-sentence detours
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.
@@ -400,7 +414,7 @@ If a reader can parse a sentence two ways, it makes the sentence harder to under
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 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.
+2. A first word that can be either a noun or a verb. If a sentence starts with "List endpoints", readers take the words as an instruction to list endpoints until the sentence's real verb appears. If readers don't know the term "list endpoint", they have no way to tell sooner.
**Instead of:** List endpoints in the Infisical API return one page of results per request.
@@ -414,7 +428,7 @@ Don't add asides to the reader that make a sentence friendlier without adding in
**Write:** The response includes `totalCount`, which you can use to tell when you've read every page.
-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.
+Do address the reader when the reader's situation decides whether a sentence applies to them. If you write the condition about the reader ("If you self-host Infisical"), readers can tell right away whether the sentence applies to them. If you write the same condition about an abstract noun ("On a self-hosted instance"), readers have to work out whether the condition includes them.
**Instead of:** On a self-hosted or dedicated instance, replace the host.
@@ -534,7 +548,7 @@ Use a `## Prerequisites` section before the main content, even when the list is
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 read the steps yet, so the reader can't check a prerequisite that depends on the steps.
+**Make each prerequisite something the reader can check before they start.** At the top of the page, the reader hasn't read the steps yet. If a prerequisite depends on the steps, the reader can't check it.
**Instead of:** A role with the permissions required by the endpoints called in this guide
@@ -578,7 +592,7 @@ Choose a page's structure based on what the page is for. Pages with different pu
`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.** 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.
+**Headings name the topic in words a newcomer recognizes.** Readers often scan the headings before anything else on a page. If a heading is built around a code or a term the reader doesn't know yet, the heading won't help the reader find the section they need.
**Instead of:** `## 429 response`
@@ -701,8 +715,8 @@ em dashes in one paragraph, "click" and "tap" where the verb should be "select",
forms of common contractions. Vale doesn't check the `description` frontmatter field, so check
the description yourself when you review a page.
-Every rule except the em dash rule reports at error level, so a finding from any other rule,
-including "click" and "tap" and the full forms of contractions, fails the run. The em dash rule
+Every rule except the em dash rule reports at error level, so the run fails if any other rule
+reports a problem, including "click" and "tap" and the full forms of contractions. The em dash rule
reports at warning level and doesn't change the exit code, so read the output Vale prints, not
just the exit code.