feat(docs): Add umbraco-docs documentation subagent skill

.claude/skills/docs-writer/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: docs-writer
+description: Writes and reviews user-facing documentation for Umbraco.AI following the official Umbraco documentation style guide and Vale linting rules. Focuses on public APIs, extension points, and getting-started guides. Use when writing, reviewing, or improving documentation for any product in the repository.
+argument-hint: [write|review|lint] <topic or file path>
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Umbraco.AI Documentation Subagent
+
+Write and review user-facing documentation for Umbraco.AI products following the official Umbraco documentation style guide and Vale linting rules.
+
+## Documentation Philosophy
+
+**Audience**: Umbraco developers integrating AI into their sites. They know Umbraco CMS but may be new to AI concepts and this package ecosystem.
+
+**Core principles**:
+
+1. **Public APIs only** — Document what users consume: NuGet/npm packages, public interfaces, extension methods, configuration options, backoffice UI, and Management API endpoints. Never document internal services, repositories, or implementation details.
+2. **Concise over comprehensive** — Show how to use something with a minimal working example. Do not enumerate every overload, every property, or every edge case. A reader should be able to scan a page and start working within minutes.
+3. **Progressive disclosure** — Start with the common case. Mention advanced options exist and link to them, but do not front-load complexity. A getting-started guide should not read like a reference manual.
+4. **One task per page** — Each article answers one question: "How do I configure a connection?", "How do I create a custom provider?". If an article tries to answer multiple questions, split it.
+5. **Code speaks louder than prose** — A 5-line code sample with a one-sentence explanation beats three paragraphs of description. When in doubt, show the code.
+
+## Command: $ARGUMENTS
+
+Execute the requested documentation task.
+
+## Available Commands
+
+### Writing
+
+- **write \<topic\>**: Write new documentation on a topic (e.g., `write getting-started`, `write provider-api`)
+- **write \<file\>**: Create or extend a specific documentation file
+
+### Reviewing
+
+- **review \<file\>**: Review an existing file against Umbraco style rules and Vale linting
+- **review \<directory\>**: Review all markdown files in a directory
+
+### Linting
+
+- **lint \<file\>**: Check a file against all 12 Vale rules and report violations
+- **lint \<directory\>**: Lint all markdown files in a directory
+
+## Implementation Guide
+
+### Step 1: Understand the Request
+
+Determine what the user needs:
+
+1. **Writing new docs**: Gather context from the codebase first. Read source files, interfaces, and existing docs to understand what needs documenting.
+2. **Reviewing existing docs**: Read the target file(s) and check against every rule in [VALE-RULES.md](VALE-RULES.md) and [STYLE-GUIDE.md](STYLE-GUIDE.md).
+3. **Linting**: Systematically check each of the 12 Vale rules and report all violations with line numbers.
+
+### Step 2: Gather Codebase Context
+
+Before writing documentation, read the **public surface area** of the relevant code. Focus on what users install, configure, and call — not internal implementation.
+
+**What to read (public API)**:
+
+```
+# Public extension methods (the main entry point for users)
+Glob: src/**/*Extensions.cs
+Glob: src/**/*BuilderExtensions.cs
+
+# Public interfaces users interact with
+Glob: src/**/I*Service.cs (only public ones in .Core projects)
+Glob: src/**/I*Provider.cs
+
+# Configuration / options classes
+Glob: src/**/*Options.cs
+Glob: src/**/*Settings.cs
+
+# Management API controllers (REST endpoints users call)
+Glob: src/**/*Controller.cs
+
+# Frontend elements users can place in the backoffice
+Glob: Client/src/**/*.element.ts
+```
+
+**What NOT to read or document**:
+
+- Internal repositories (`I*Repository.cs`) — implementation detail
+- DbContext / migrations — users do not interact with these
+- Internal services that are not in the DI container publicly
+- Private/internal helper classes
+
+Read the product-specific `CLAUDE.md` for architectural context:
+
+```
+Read: <Product>/CLAUDE.md
+```
+
+### Step 3: Write or Review
+
+#### When Writing
+
+Follow the complete style guide in [STYLE-GUIDE.md](STYLE-GUIDE.md). Key rules:
+
+1. **Second person**: Address the reader as "you"
+2. **Present tense, active voice**: "The profile loads" not "The profile was loaded"
+3. **Sentences under 25 words**
+4. **No editorializing**: Never use "simple", "easy", "just", "obviously", etc.
+5. **Define acronyms on first use** (except common ones: API, CLI, CMS, CSS, HTML, JSON, URL, etc.)
+6. **Correct Umbraco terms**: "backoffice" (one word), "Document Type" (capitalized), "Data Type" (capitalized)
+7. **Correct tech names**: `.NET` (not "dot net"), `TypeScript` (not "typescript"), `JavaScript` (not "js")
+8. **Inclusive language**: "primary" not "master", "allowlist" not "whitelist"
+9. **Descriptive link text**: Never use "click here" or "read more"
+10. **Code samples**: Use fenced code blocks with language identifiers
+
+#### When Reviewing
+
+Check the file against every rule. Report findings grouped by severity:
+
+**Errors** (must fix):
+- Spacing: double spaces, missing space after punctuation
+- Acronyms: undefined acronyms (3-5 uppercase letters) on first use
+
+**Warnings** (should fix):
+- Heading punctuation at end of headings
+- Sentence length over 25 words
+- List items not starting with capital letter
+- Editorializing language
+- Repeated consecutive words
+- Incorrect term usage (see Terms, UmbracoTerms, Names, Brands rules)
+- Generic link text
+
+### Step 4: Validate Against Vale Rules
+
+Systematically check each of the 12 rules documented in [VALE-RULES.md](VALE-RULES.md):
+
+| # | Rule | Severity | What to Check |
+|---|------|----------|---------------|
+| 1 | HeadingsPunctuation | warning | No `.;:!?` at end of headings |
+| 2 | Spacing | error | No double spaces; space after punctuation before capitals |
+| 3 | SentenceLength | warning | Sentences under 25 words |
+| 4 | ListStart | warning | List items start with capital letter |
+| 5 | Editorializing | warning | No subjective/opinionated words |
+| 6 | Repetition | warning | No repeated consecutive words |
+| 7 | Acronyms | error | Define acronyms on first use (except ~130 common ones) |
+| 8 | Terms | warning | Use inclusive and formal alternatives |
+| 9 | UmbracoTerms | warning | Correct Umbraco product/concept casing |
+| 10 | Names | warning | Correct tech name casing |
+| 11 | Brands | warning | Correct brand name casing |
+| 12 | LinkTextClarity | warning | No "here", "click here", "read more" link text |
+
+### Step 5: Multi-Discipline Awareness
+
+This repository spans multiple technology domains. Always write from the **user's perspective** — what they install, configure, and call.
+
+#### .NET / C# Documentation
+
+- Use `csharp` as the fenced code block language
+- Focus on: NuGet package installation, `AddUmbraco*()` extension methods, configuration in `appsettings.json`, and public service interfaces
+- Show the minimal code to achieve a task — do not show every overload
+- Do not document internal DI registrations, repositories, or persistence details
+
+#### TypeScript / Lit Frontend Documentation
+
+- Use `typescript` as the fenced code block language
+- Focus on: npm package installation, custom element tag names, and key properties/events
+- Do not document internal component architecture or Lit lifecycle internals
+
+#### Management API Documentation
+
+- Document endpoints with HTTP verb, path, and a single request/response example
+- Reference the generated TypeScript client methods when relevant
+- Do not document every query parameter variation — show the common case
+
+#### Umbraco CMS Integration Documentation
+
+- Use correct Umbraco terminology (see UmbracoTerms rule)
+- Focus on: Composer setup, backoffice navigation, and configuration sections
+- Do not explain Umbraco internals the reader already knows (they are Umbraco developers)
+
+## Reference Documentation
+
+- **Vale rules (all 12)**: See [VALE-RULES.md](VALE-RULES.md) for complete rule definitions with patterns and examples
+- **Writing style guide**: See [STYLE-GUIDE.md](STYLE-GUIDE.md) for Umbraco writing conventions, formatting, and structure
+
+## Output Format
+
+### For Writing Tasks
+
+Produce the markdown content directly. Include:
+
+- A single `#` title
+- Hierarchical headings (`##`, `###`, etc.)
+- Code samples with language identifiers
+- Descriptive alt text for any images referenced
+
+### For Review Tasks
+
+Produce a structured report:
+
+```
+## Documentation Review: <filename>
+
+### Errors (must fix)
+- **Line X**: [Rule] Description of issue
+  - Suggestion: ...
+
+### Warnings (should fix)
+- **Line X**: [Rule] Description of issue
+  - Suggestion: ...
+
+### Summary
+- X errors, Y warnings
+- Overall assessment
+```
+
+### For Lint Tasks
+
+Produce a Vale-style report:
+
+```
+<filename>
+  Line X:Col Y  error    [UmbracoDocs.Spacing]     Description
+  Line X:Col Y  warning  [UmbracoDocs.Editorializing]  Description
+  ...
+
+N errors, M warnings
+```
+
+## Example Usage
+
+```bash
+# Write new documentation
+/docs-writer write getting-started-with-profiles
+
+# Review a file
+/docs-writer review Umbraco.AI/README.md
+
+# Lint a directory
+/docs-writer lint Umbraco.AI.OpenAI/
+
+# Write provider-specific docs
+/docs-writer write how-to-create-a-custom-provider
+```
+
+## Depth Calibration
+
+Use this guide to decide how much detail to include:
+
+| Content Type | Right Depth | Too Deep |
+|---|---|---|
+| Getting started | Install, configure, first working example | Every configuration option explained |
+| How-to guide | Steps to complete one task, with code | Multiple approaches compared in detail |
+| API reference | Method signature, one-line description, example | Full parameter docs for every overload |
+| Configuration | Common options with defaults, example JSON | Every option with edge cases |
+| Concepts | What it is, why it matters, how it connects | Internal architecture and design decisions |
+
+**Rule of thumb**: If a section makes the reader scroll more than twice without learning something actionable, it is too long. Move details to a linked reference page or remove them.
+
+## Tips
+
+- Always read the source code before writing about it; do not guess at API shapes
+- Focus on public interfaces — if a class is `internal`, it does not belong in user documentation
+- Cross-reference existing documentation in the repo to maintain consistency
+- For code samples, prefer the shortest example that compiles and demonstrates the feature
+- Keep paragraphs to 2-3 sentences maximum
+- Use tables for reference material (configuration options, parameters)
+- Use ordered lists only for sequential steps; unordered lists for everything else
+- When a topic has a simple path and an advanced path, document the simple path inline and link to the advanced path