smatechnologies · rweesner · Aug 4, 2026 · Jul 27, 2026
@@ -5,15 +5,15 @@ description: >
   user-facing documentation: API references, help articles, UI copy, parameter
   descriptions, setup instructions, or release notes. Enforces product voice,
   terminology, and formatting standards.
+user-invocable: true
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, WebFetch
 ---
 
-> **Last updated:** April 2026
+> **Last updated:** July 2026
 >
 > **Recent changes:**
-> - Added Always-on scope section: standards now apply to all docs/ edits regardless of explicit skill invocation
-> - Updated Document Types table to reflect correct repo paths (docs/ not docs-site/docs/)
-> - Added overview page type to Document Types table
+> - Added Resource Loading, Multi-Page Coordination, golden-examples.md
+> - Added source-verification guardrails, Parameter Descriptions, Release Notes Requirement, and link validation guidance
 
 # Technical Writer
 
@@ -29,18 +29,6 @@ When writing documentation, identify the primary audience by role. Use that role
 
 **General assumptions:** Readers are comfortable with automation and IT operations concepts (job scheduling, dependencies, agents, event-driven processing) but are NOT developers. Never expose internal class names, namespaces, or implementation details in user-facing text.
 
-## Always-on scope
-
-These standards apply to **every edit or addition to any file in `docs/`**, regardless of whether the technical-writer skill was explicitly invoked. This includes targeted edits, bug fixes, content additions, new pages, and overview pages.
-
-Before completing any write or edit operation on a `docs/` file:
-
-1. Run the pre-flight checklist (see Quality Checklist below) against every sentence or section you touched
-2. Verify that no banned terms, passive constructions, or heading case violations were introduced
-3. If creating a new page, confirm it follows the correct documentation type structure from [opcon-documentation-types.md](resources/opcon-documentation-types.md)
-
-This rule cannot be overridden by operating mode or by the absence of an explicit skill invocation. If a change would violate these standards, fix the violation before saving — do not defer it to a later review pass.
-
 ## Writing Process
 
 Before writing or reviewing any documentation page, complete these steps in order:
@@ -81,6 +69,20 @@ mode and to every documentation type.
    - What source would resolve it (e.g., "check the controller
      validation logic" or "confirm with the development team")
 
+5. **Verify UI labels and element types from source.** Before writing
+   any procedural step that references a UI element (button, menu,
+   field, tab, window), verify the element's exact label and type
+   from the source code (views, controllers, or JavaScript). Do not
+   assume element type or label from context. Common errors: calling
+   a menu item a "button," or using an approximate label instead of
+   the exact text displayed in the UI.
+
+6. **Read source code before writing.** Before writing documentation
+   for any feature, read the relevant source files to verify all
+   claims — workflows, field names, default values, UI labels, and
+   behavior. Do not write from memory, prior knowledge, or inference.
+   If the source cannot be located, flag the gap per Guardrail 3.
+
 These guardrails exist because OpCon is used for mission-critical
 automation in financial institutions. Inaccurate documentation —
 even a fabricated default value or an invented workflow step — can
@@ -95,7 +97,7 @@ When invoked, determine which mode applies:
 |---|---|---|
 | **Write** | "Write," "Create," "Draft" | Follow the full writing process. Produce complete output matching the documentation type template. |
 | **Review** | "Review," "Check," "Audit" | Compare existing content against all standards. Report violations with specific line references and suggested fixes. Do not rewrite unless asked. |
-| **Edit** | "Fix," "Update," "Change," "Revise" | Apply targeted changes. Before applying, verify the proposed change does not violate the pre-flight checklist — do not remove required structural elements (such as the procedural lead-in sentence) while fixing other issues. Preserve existing structure and content that is already compliant. Only modify what is specified or what violates standards. |
+| **Edit** | "Fix," "Update," "Change," "Revise" | Apply targeted changes. Before applying, verify the proposed change does not violate the pre-flight checklist — do not remove required structural elements (such as the procedural lead-in sentence) while fixing other issues. Preserve existing structure and content that is already compliant. Only modify what is specified or what violates standards. If the edit touches or is adjacent to documented UI labels, workflow steps, or described behavior, verify those elements from source code before applying changes to confirm the existing content is still accurate. |
 | **Consult** | "Should I," "What's the best way," "How do I" | Provide guidance by referencing the appropriate standard file. Do not produce documentation output unless asked. |
 
 ## Voice & Tone
@@ -152,6 +154,16 @@ All documentation follows the rules in [opcon-documentation-standards.md](resour
 All step-by-step instructions follow the procedural rules and pattern
 library in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md).
 
+## Parameter Descriptions
+
+User-facing parameter text follows [opcon-parameter-descriptions.md](resources/opcon-parameter-descriptions.md):
+
+- Boolean filters: "Results will include [items]."
+- Boolean toggles: "[Feature] will be [enabled/applied]."
+- Credentials: Brief clarifying note only if the name is ambiguous
+- Never include "Optional:", "Recommended:", or "Required:" prefixes (auto-rendered by the UI)
+- One sentence when possible; be specific about what changes
+
 ## API Documentation
 
 When writing API endpoint reference docs, follow [opcon-api-reference.md](resources/opcon-api-reference.md) exactly. It defines the strict per-endpoint templates (GET list, GET detail, POST JSON, POST multipart), format rules, nesting notation, type vocabulary, and source material locations. Key constraints:
@@ -170,6 +182,7 @@ When writing API endpoint reference docs, follow [opcon-api-reference.md](resour
 | [opcon-documentation-types.md](resources/opcon-documentation-types.md) | Documentation type definitions (conceptual, procedural, reference), structural templates, and combining guidance |
 | [opcon-glossary.md](resources/opcon-glossary.md) | Full terminology with definitions, "do not use" terms, and customer-facing alternatives |
 | [opcon-learner-roles.md](resources/opcon-learner-roles.md) | Audience profiles: who they are, knowledge domains, tone, scope, assumed knowledge per role |
+| [opcon-parameter-descriptions.md](resources/opcon-parameter-descriptions.md) | Patterns for plugin parameter description text |
 | [opcon-api-reference.md](resources/opcon-api-reference.md) | Strict templates for API endpoint documentation |
 | [opcon-golden-examples.md](resources/opcon-golden-examples.md) | Complete reference examples for each documentation type — quality calibration for AI output |
 
@@ -193,15 +206,17 @@ task to keep context focused and avoid unnecessary processing.
 | [opcon-documentation-types.md](resources/opcon-documentation-types.md) | Writing or reviewing a page (to identify structure). Skip for targeted edits where the page type is already clear. |
 | [opcon-golden-examples.md](resources/opcon-golden-examples.md) | Writing a new page from scratch (for quality calibration). Skip for reviews, edits, or consult mode. |
 | [opcon-api-reference.md](resources/opcon-api-reference.md) | The task involves API endpoint documentation |
+| [opcon-parameter-descriptions.md](resources/opcon-parameter-descriptions.md) | The task involves plugin parameter description text |
 
 ## Document Types
 
 | Type | Location | Standards |
 |------|----------|-----------|
 | API endpoint reference | `docs/api/reference/` | opcon-api-reference.md |
-| Help article | `docs/` | opcon-documentation-standards.md |
-| Overview page | `docs/` (named `*-overview.md`) | opcon-documentation-standards.md + opcon-documentation-types.md |
-| Release notes | `docs/release-notes.md` | opcon-documentation-standards.md (Release Notes section) |
+| Help article | `docs-site/docs/` | opcon-documentation-standards.md |
+| Release notes | `docs-site/docs/release-notes/` | opcon-documentation-standards.md (Release Notes section) |
+| Parameter descriptions | Inline in plugin C# | opcon-parameter-descriptions.md |
+| Setup instructions | Inline in plugin C# | opcon-documentation-standards.md |
 
 ## Multi-Page Coordination
 
@@ -217,6 +232,7 @@ scope gaps, duplicated content, and broken cross-references.
    - One or more procedural pages (one per distinct task)
    - Reference entries if the feature introduces new settings, fields,
      or report types
+   - A release notes entry (see [Release Notes Requirement](#release-notes-requirement) below)
 
 2. **Define scope boundaries.** For each page, state in one sentence
    what the page covers and what it intentionally excludes. If two
@@ -241,6 +257,7 @@ scope gaps, duplicated content, and broken cross-references.
 
 ### Cross-Reference Rules
 
+- **Always include a "Related topics" section** at the bottom of every page — when creating a new page, add it before finishing; when editing an existing page, review and update it as part of the task
 - Use "Related topics" sections at the bottom of each page — do not
   bury links mid-paragraph
 - Link text should match the target page's title exactly
@@ -250,6 +267,25 @@ scope gaps, duplicated content, and broken cross-references.
 - When a procedure references a prerequisite procedure, link to it
   in a prerequisite note before the steps, not within the steps
 
+## Release Notes Requirement
+
+Whenever documentation for a **new feature or improvement** is added, the release notes file must also be updated in the same task.
+
+**File:** `docs-site/docs/release-notes/whats-new.md`
+
+### How to update
+
+1. Open the release notes file and identify the correct section — **New features** for net-new capabilities, **Improvements** for enhancements to existing features.
+2. Add a bullet under the appropriate subsection heading that matches the feature area (e.g., **Job Master**, **Schedules**, **Reports**, **System Configuration**). Create the subsection heading if it does not exist.
+3. Write the bullet in this format:
+   - **[Action verb + what was added/changed].** [One to two sentences describing the value to the user and any key details.] For more information, see [page title](relative/link.md).
+4. Use present tense and customer-facing terminology. Follow the same voice and formatting rules as all other documentation.
+5. Do not summarize the feature exhaustively — the release note entry points to the full documentation page.
+
+**When to skip:** Do not add a release notes entry in these cases:
+- The change is a correction to existing documentation (typo fixes, clarifications, restructuring) with no underlying product change.
+- The documentation is new, but the feature it describes already shipped in a previous release. Writing documentation for a pre-existing, undocumented feature (such as an existing API endpoint's payload format) does not constitute a release event — the release notes for the version that introduced that feature, if any, have already been published.
+
 ## Quality Checklist
 
 Before finalizing any documentation, run the full pre-flight checklist in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md). Quick summary:
@@ -260,6 +296,7 @@ Before finalizing any documentation, run the full pre-flight checklist in [opcon
 - [ ] Action verbs follow the decision tree (Select, Go to, Press, Run, Enter, Clear)
 - [ ] No banned terms (click, execute, drop-down, icon, checkbox, hamburger, navigate to, etc.)
 - [ ] Steps are numbered, one action per step
+- [ ] Numbered lists have two or more steps — single-action procedures use prose instead
 - [ ] Result statement present where applicable
 - [ ] No procedure exceeds ~10 steps without a section break
 - [ ] No internal class names, namespaces, or implementation details exposed
@@ -268,6 +305,14 @@ Before finalizing any documentation, run the full pre-flight checklist in [opcon
 
 **Self-check:** After producing any documentation output, silently verify every item on the pre-flight checklist in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md) before presenting it. If any item fails, fix it first — do not present output that knowingly violates these standards.
 
+**Link validation:** Every internal link must point to a file that
+exists and every cross-reference must resolve. Docusaurus validates
+internal links at build time (via `onBrokenLinks` and
+`onBrokenMarkdownLinks`) and fails the build on a broken link, so any
+link that cannot resolve must be fixed before the page is committed.
+When adding or changing a link, confirm the target file exists and the
+relative path is correct.
+
 ## When Uncertain
 
 - **Unknown term:** Search [opcon-glossary.md](resources/opcon-glossary.md) first. If not found, use the term as it appears in the UI and flag it for glossary review.

@@ -225,21 +225,21 @@ These are non-negotiable. Every endpoint file must comply.
 4. **Table/JSON parity.** Every field in a Sample Response/Request must have a corresponding row in its Attributes/Body table, and vice versa. The table and the JSON must be a 1:1 match.
 5. **Nesting notation:** `field` for top-level, `parent.child` for nested objects, `items[].field` for array items, `items[].parent.child` for nested fields inside arrays.
 6. **Type column values:** `string`, `integer`, `boolean`, `number`, `string (GUID)`, `string (ISO 8601)`, `array[string]`, `array[object]`, `object`. Be specific — prefer `string (GUID)` over `string` when the value is a GUID.
-7. **Realistic sample data.** Use names, dates, and IDs plausible for a US financial institution workload automation environment. No "foo", "bar", "test", or "example.com".
+7. **Realistic sample data.** Use names, dates, and IDs plausible for a US financial institution workload automation environment. No "foo", "bar", "test", or "example.com". Use **First Bank of Valkyrie** as the sample bank name and **firstbankofvalkyrie.com** as the sample email domain.
 8. **No cross-references between files.** Each file is self-contained.
 9. **camelCase JSON keys** matching `[JsonProperty]` attributes in DTOs.
 10. **No commentary, design notes, or explanatory prose.** These are strict reference documents.
 
-## mkdocs.yml Nav Registration
+## Sidebar Registration
 
-After creating an endpoint file, add it to the `nav` section of `mkdocs.yml` in **both** locations:
+After creating an endpoint file, register it in the Docusaurus sidebar configuration (`sidebars.js`) in **both** navigation locations:
 
-1. Under `API > API Reference > {Resource Group}`
-2. Under `Reference > API Reference > {Resource Group}`
+1. Under `API` > `API Reference` > `{Resource Group}`
+2. Under `Reference` > `API Reference` > `{Resource Group}`
 
 If the resource group doesn't exist yet, create it in both locations. Group name = plural resource noun (e.g., "Jobs", "Schedules", "Agents"). Place the new group alphabetically among existing groups.
 
-Nav entry format: `{Display Name}: api/reference/{filename}.md`
+Sidebar entry format: reference the doc by its ID, `api/reference/{filename}` (no `.md` extension).
 
 ## Requirements