docs(repo): add technical writing guide

AGENTS.md

@@ -3,9 +3,14 @@
 ## Commit convention
 
 Use Conventional Commits for all commit messages.
-Before writing a commit message, please read [[docs/conventional-commits]].
+Before writing a commit message, read `docs/conventional-commits.md`.
 Do not add agent attribution or co-author trailers.
 
+## Technical writing
+
+Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
+Use the nearest project dictionary for project-specific domain language.
+
 ## Gotchas
 
 - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory.

docs/dictionary.md

@@ -0,0 +1,34 @@
+# Dictionary
+
+This dictionary records repository-wide language decisions for repository prose.
+It applies to comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation.
+
+ASD-STE100 Simplified Technical English partly informs these rules.
+This repository uses those ideas as a local style discipline.
+It does not claim formal ASD-STE100 compliance.
+
+Use `USE` for approved terms.
+Use `AVOID` for terms that do not belong in repository prose.
+Use `REPLACE` for terms that have a preferred substitute.
+
+| Term | Decision | Replacement | Meaning |
+| :--- | :--- | :--- | :--- |
+| `i.e.` | REPLACE | `that is` | Latin abbreviation. Unclear to non-native speakers. |
+| `e.g.` | REPLACE | `for example` | Latin abbreviation. |
+| `etc.` | REPLACE | `and so forth`, `and others` | Latin abbreviation. Vague and non-exhaustive. |
+| `vs.` / `versus` | REPLACE | `compared to`, `against` | Latin abbreviation. |
+| `via` | REPLACE | `by using`, `through`, `with` | Latin term. Prefer direct prepositions. |
+| `ad hoc` | REPLACE | `one-off`, `for this case` | Latin term. Prefer direct wording. |
+| `simply` | AVOID |  | Subjective filler. Code and concepts are not inherently simple. |
+| `just` | AVOID |  | Minimizing filler word. |
+| `obviously` | AVOID |  | Subjective qualifier. |
+| `clearly` | AVOID |  | Subjective qualifier. |
+| `easily` | AVOID |  | Subjective qualifier. |
+| `properly` | REPLACE | `correctly`, or specify exact behavior | Vague and subjective. State the exact condition. |
+| `as necessary` | REPLACE | specify exact condition | Ambiguous. Define the condition explicitly. |
+| `very` / `quite` | AVOID |  | Empty intensifiers. |
+| `basically` | AVOID |  | Conversational filler. |
+| `actually` | AVOID |  | Conversational filler. |
+| `really` | AVOID |  | Empty intensifier. |
+| `furthermore` / `moreover` | REPLACE | `also`, `and` | Overly formal transitional filler. |
+| repository root | USE |  | The Git work tree root. Use it to resolve repository-relative paths. |

docs/technical-writing.md

@@ -0,0 +1,113 @@
+# Technical Writing
+
+This guide defines writing rules for comments, user-facing descriptions, commit prose, pull-request prose, and Markdown documentation.
+These rules apply throughout this repository.
+
+ASD-STE100 Simplified Technical English partly informs these rules.
+This repository uses those ideas as a local style discipline.
+It does not claim formal ASD-STE100 compliance.
+
+Read the dictionaries with this guide.
+In this guide, “the repository dictionary” means `docs/dictionary.md` at the repository root.
+The repository dictionary defines repository-wide language decisions for all prose.
+A project dictionary lives at `<project>/docs/dictionary.md`.
+Use the nearest project dictionary between the edited file and the repository root.
+Project dictionaries define domain-specific language decisions for their subtree.
+In this guide, “the dictionaries” means the repository dictionary and the project dictionary together.
+
+## Structural Conciseness and Grammar Rules
+
+- **Clear and concise style:** Use direct, concise writing.
+  Use simple present tense for factual descriptions.
+  Do not use uncertainty words such as `could`, `might`, and `should` unless uncertainty is the subject.
+  Use each domain word with the meaning assigned in the dictionaries.
+  Avoid: `The tool should usually handle the input correctly.`
+  Use: `The tool validates the input.`
+- **Avoid jargon and inflated language:** Use common technical words.
+  Avoid unnecessary jargon in three categories:
+  1. Linguistic and grammatical meta-jargon.
+     Avoid: `modal auxiliaries`
+     Use: `uncertain words`
+  2. Inflated corporate phrasing.
+     Avoid: `utilize`
+     Use: `use`
+     Avoid: `commence`
+     Use: `start`
+  3. Unapproved domain inventions.
+     Do not use project-specific terms unless the dictionary defines them.
+     General technical words do not need dictionary entries.
+     Add a common word to the dictionary when it has a project-specific meaning.
+     If a term is vague or overloaded, choose one precise term.
+     List avoided alternatives in the dictionary.
+  Choose the simplest word that accurately communicates the meaning.
+- **Sentence length limits:** Code comments, user-facing descriptions, and procedural instructions have a 20-word limit.
+  Descriptive Markdown paragraphs have a 25-word limit.
+  Do not put multiple sentences on one physical line.
+  Wrap a sentence across multiple physical lines when readability requires it.
+  Split long sentences into multiple concise sentences.
+  Avoid: `The command configures the service with the generated settings and restarts it after the file changes.`
+  Use: `The command configures the service with the generated settings.`
+  Use: `It restarts the service after the file changes.`
+- **Active voice:** Always use active voice.
+  The subject must perform the action.
+  Do not use passive voice.
+  Avoid: `Stale entries are invalidated by the cache.`
+  Use: `The cache invalidates stale entries.`
+- **Imperative mood:** Procedural instructions and task steps must start with an imperative verb.
+  Summary fragments for declarations use third-person singular.
+  Avoid: `The token should be validated before use.`
+  Use for a task step: `Validate the token before use.`
+  Use for a declaration summary: `Validates the token before use.`
+- **Noun clusters:** Do not write more than three consecutive nouns without a preposition or hyphen.
+  Avoid: `session cache entry lookup`
+  Use: `lookup of session cache entries`
+- **One idea per sentence:** Express only one instruction or core concept per sentence.
+  Do not combine multiple operations in one compound sentence.
+  Avoid: `Validate the input and restart the service when validation succeeds.`
+  Use: `Validate the input.`
+  Use: `Restart the service when validation succeeds.`
+- **Code token exemption:** Text in Markdown backticks, URLs, and code blocks counts as one word.
+  Sentence-length limits and noun-cluster limits do not apply to these tokens.
+  Example: `curl --fail --silent https://example.com/health` counts as one word.
+- **Cause and time precision:** Use `because` for causality.
+  Use `since` only for passage of time.
+  Use `as` only for simultaneous action.
+  Avoid: `Since the token is expired, validation fails.`
+  Use: `Because the token is expired, validation fails.`
+
+## In-Code Documentation Conventions
+
+- **Declaration coverage and exemptions:** Document public interfaces, configuration options, fields, and non-trivial public methods.
+  Omit comments on obvious declarations when the name and context are self-explanatory.
+  Avoid: `Enable this option.`
+  Use: `Enables automatic cleanup after a successful run.`
+- **Declaration non-redundancy:** Comments must explain purpose, preconditions, invariants, or non-obvious consequences.
+  Do not repeat information that the name, type, path, or parameter list already conveys.
+  Avoid: `The timeout option sets the timeout.`
+  Use: `Controls how long the command waits before it reports failure.`
+- **Multi-line declaration comments:** Start multi-line declaration comments with one summary sentence.
+  Put a blank line between the summary and detail paragraphs.
+  Use detail paragraphs for preconditions, invariants, examples, and non-obvious consequences.
+  Avoid:
+
+  ```text
+  The caller must load the signing key before calling this method.
+  Validates the token and returns false for expired tokens.
+  ```
+
+  Use:
+
+  ```text
+  Validates the token.
+
+  The caller must load the signing key before calling this method.
+  Expired tokens return false instead of an error.
+  ```
+- **Code symbol references:** Enclose identifiers, paths, commands, option names, and file names in Markdown backticks.
+  Avoid: Run npm test before editing package.json.
+  Use: Run `npm test` before editing `package.json`.
+- **Boolean descriptions:** Start boolean descriptions with the behavior verb.
+  Use `True if` only when the value reports state instead of enabling behavior.
+  Avoid: `Flag that specifies whether retries are enabled.`
+  Use: `Enables retry behavior.`
+  Use for state: `True if the token is expired.`