dotfiles

Shell, editor and terminal configuration, the tools that go with them, and
szecret, an age-based secret manager whose store lives elsewhere.

History restarts here. What came before was not written to be read by
anyone else, and carried machine names, addresses and an encrypted secret
store; it is kept privately instead. What is left is meant to be safe on
any machine, including one whose owner is not me: see CLAUDE.md for the
rule it is written to.

1 files changed, 127 insertions, 0 deletions

diff --git a/skills/google-style-guide/reference/grammar.md b/skills/google-style-guide/reference/grammar.md
new file mode 100644
index 0000000..fc7aa0c
--- /dev/null
+++ b/skills/google-style-guide/reference/grammar.md
@@ -0,0 +1,127 @@
+# Grammar and mechanics detail
+
+Detail for: articles, contractions, pluralization, possessives, prepositions,
+pronouns, tense, sentence structure, reference verbs, anthropomorphism, italics.
+Source: developers.google.com/style (Articles, Contractions, Pluralization,
+Possessives, Prepositions, Pronouns, Tense, Sentence structure, Reference verbs,
+Anthropomorphism, Italics for terms).
+
+## Articles (a, an, the)
+
+- Always include articles — never drop them for brevity, including in headings.
+  - Recommended: Create **a** VM instance — Not: Create VM instance
+- Use `a` when the next word starts with a consonant **sound**, regardless of
+  spelling. For abbreviations whose pronunciation varies, choose the article to
+  match the common pronunciation (e.g., "an SQL database" if you pronounce it
+  "ess-queue-ell", "a SQL database" if you say "sequel").
+
+## Contractions
+
+- Use contractions, especially negations: *isn't*, *don't*, *can't*. Readers
+  can miss the word *not* when scanning.
+- Don't invent nonstandard contractions (*guides're*, *browser's* for "browser
+  is") or three-word contractions (*mightn't've*).
+- To emphasize a negation you can use formatting, e.g. "is **_not_**".
+
+## Pluralization
+
+- Make subject and verb agree, especially with long or complex subjects:
+  - Recommended: "The number of entries listed in the directory **is** accurate."
+  - Recommended: "The request payload and header information **are** logged."
+- In product names, don't pluralize (they're proper nouns): "use Project
+  IDs" — check the word list for specific entries.
+- For plural of code elements, don't inflect the code name; add a noun instead
+  ("multiple `config` files", not "multiple configs").
+- Don't use parentheses for optional plurals ("file(s)") — see word list
+  nuance; in general rewrite instead.
+
+## Possessives
+
+- Singular nouns (including ones ending in s): add `'s` — "each vector's
+  record".
+- Plural nouns ending in s: add only `'`: "the developers' guide".
+- Don't form possessives from product, feature, or company names when
+  describing their function; use the name as a modifier or rephrase with *of*:
+  - Recommended: "the Cloud Console menu" — Not recommended: "Cloud Console's menu"
+- Trademarks: never form a possessive. "Chromebook" → "Chromebook's features"
+  is wrong.
+- Code items: avoid possessives entirely; "the value of the `ADDRESS` constant",
+  not "`ADDRESS`'s value".
+
+## Prepositions
+
+- Include prepositions that increase clarity, omit unnecessary ones, and don't
+  clutter sentences.
+  - Recommended: "the client library documentation **for** the language you're
+    interacting with"
+  - Not recommended: "...the language with which you're interacting."
+- In cross-references use *about*, not *on*: "For more information about
+  indexes, see ..."
+
+## Pronouns
+
+- Ensure a pronoun clearly refers to its antecedent; if ambiguous, repeat the
+  noun.
+  - Recommended: "If you type text in the field, the text doesn't change."
+  - Not recommended: "...it doesn't change."
+- After a demonstrative (`this`/`these`/`that`), include a noun: "Set this
+  value to true", not "Set this to true".
+- Gender-neutral: use singular *they*; never *he/she*, *(s)he*, or generic *he*.
+- Use second person (*you*) for the reader; first person (*I* in FAQs, *we* for
+  the organization) only in specific contexts.
+- `that` for restrictive clauses, `which` (with comma) for nonrestrictive:
+  "the option that you selected", "the option, which is deprecated, ...".
+
+## Tense
+
+- Present tense for general behavior: "The server sends an acknowledgment",
+  not "will send".
+- Future tense (*will*) only to flag a genuinely future action: "The file will
+  be archived the next time the backup process runs."
+- Don't use future tense for how a feature will work after a future release
+  (write it as current behavior instead — see `reference/strategy.md`).
+- Avoid hypothetical *would*: "If you send an unsubscribe message, the server
+  removes you from the list" — not "You can send... The server would then...".
+
+## Sentence structure
+
+- Put conditions before instructions, and the most important information first.
+  - Recommended: "If your app is located in one of the following regions, ..."
+  - Not recommended: "...if your app is located in one of the following regions." (buried at the end)
+- Use "For more information, see [link]." rather than "See [link] for more
+  information."
+- "To delete the entire document, click Delete." rather than "Click Delete if
+  you want to delete the entire document."
+- Keep sentences short, vary the openings.
+
+## Reference verbs (API descriptions)
+
+- In API reference descriptions, the first verb matches the reference style:
+  says *creates*/*returns* (describes what the method does) vs *create*/*return*
+  (imperative instruction). Follow the existing style of the reference:
+  - "tasks.insert: Creates a new task on the specified task list."
+- Use a parallel, consistent form throughout a reference.
+
+## Anthropomorphism
+
+- Don't have software or objects do human actions: *see, think, feel, want,
+  believe, tell, assume*, etc.
+  - Recommended: "A Delimiter object specifies where to split a string."
+  - Not recommended: "A Delimiter object tells the splitter where a string
+    should be broken."
+  - Recommended: "The PC detects a new device."
+  - Not recommended: "The PC sees a new device."
+- Exception: standard idioms in technical vocabulary are fine when the product
+  uses them (e.g., "the server returns a 404", "the API expects a JSON body").
+
+## Italics for terms (words as words)
+
+- **New terms**: italicize on first mention when defining immediately. Don't
+  use bold or quotes: "A *Clos* network is a kind of multistage circuit
+  switching network."
+- **Words as words**: italicize when referring to the word itself: "Use the
+  word *and* instead." Don't use bold or quotation marks.
+- **Titles of full-length works**: italics (*The Chicago Manual of Style*).
+  Short works get quotation marks.
+- Don't use italics for emphasis in running text; prefer plain words or
+  reordering.
\ No newline at end of file