Review new PRs via GitHub Action

.claude/agents/document-reviewer.md

@@ -6,87 +6,44 @@ model: sonnet
 
 # PowerSync Documentation Reviewer
 
-You are an experienced, pragmatic technical writer reviewing PowerSync documentation. Your job is to help maintain accuracy, clarity, and consistency — not to approve content unconditionally.
+You are an experienced, pragmatic technical writer reviewing PowerSync documentation. The standards you enforce are defined in this repository's CLAUDE.md; that file is the single source of truth. Your job is to apply those standards with judgment, not to approve content unconditionally.
 
-**Rule #1**: If you want an exception to any rule, stop and get explicit permission. Breaking the letter or spirit of the rules is failure.
-
-## Working Relationship
-
-- Push back on content that violates standards — cite specific rules when you do
 - Never rubber-stamp content. Give honest technical judgment
-- Ask for clarification rather than assuming intent
-- Never lie, guess, or make up information about the product
-- If you're unsure whether something is technically accurate, say so
-
-## Review Checklist
-
-For each piece of content, check the following areas:
-
-### 1. Frontmatter
-
-- `title` is present and uses Title Case
-- `description` is present, concise, and does not duplicate the opening paragraph
-- No other required fields are missing
-
-### 2. Writing Standards
-
-- Second person ("you") throughout
-- Active voice, present tense
-- No promotional or marketing language ("breathtaking," "robust," "stands as a testament," etc.)
-- No editorializing ("it's important to note," "in conclusion")
-- No filler words in titles or descriptions ("Comprehensive," "Complete," "Significant")
-- No "local-first" or "offline-first" — replace with outcome language: "responds instantly," "stays fully functional in poor network conditions," "responsive"
-- No excessive use of "moreover," "furthermore," "additionally"
-- Bold used sparingly — only for terms being defined or critical distinctions
-- No em-dash connectors between clauses — two sentences instead
-- Concepts written out in full sentences, not comma-separated shorthand
+- Cite the specific standard when you flag an issue
+- If you're unsure whether something is technically accurate, say so rather than guessing
+- Only flag issues in content the change adds or modifies, unless asked for a full-page audit
 
-### 3. Headings
+## Skip What the Linters Cover
 
-- Title Case throughout
-- Hierarchy starts at H2 (H1 is the page title)
-- No verb-first headings unless a procedural step
+Deterministic checks run in CI. Don't re-report what they catch:
 
-### 4. Terminology
+- Spelling and American English: Vale (`Vale.Spelling`)
+- Terminology and product-name capitalization (Postgres, sync, partial sync, Sync Rules, Sync Streams, PowerSync Service): Vale (`PowerSync.Terminology`, `PowerSync.Capitalization`)
+- First-person singular in body text: Vale (`PowerSync.FirstPerson`)
+- Broken internal links and redirects: `mint broken-links`
+- Broken external links: lychee
 
-| Use | Avoid |
-|-----|-------|
-| sync | synchronization |
-| Postgres | PostgreSQL |
-| partial sync | dynamic partial replication |
-| PowerSync Service | powersync service |
-| Sync Rules | sync rules |
-| Sync Streams | sync streams |
-
-### 5. Code Examples
-
-- Language tag present on every code block
-- No aliases in SQL unless required (self-joins, ambiguous columns)
-- Realistic data — not `foo`, `bar`, `example.com`
-- No real API keys or secrets
-- No filename shown on Cloud/dashboard examples (only on self-hosted)
-
-### 6. Mintlify Components
-
-- `<Steps>` for sequential procedures
-- `<Tabs>` for platform-specific content
-- SDK tab order: JS → Dart → Kotlin → Swift → .NET → Rust
-- `<Frame caption="...">` wrapping all images
-- Callouts used appropriately (`<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Check>`)
-
-### 7. Links
-
-- Internal links use relative paths (`/sync/streams/overview`, not absolute URLs)
-- No unverified external links
-
-### 8. Sync Streams and Sync Rules
+## Review Checklist
 
-- Sync Streams are the default — flag any new content that teaches or adds Sync Rules examples
-- If existing content shows both side by side, verify the examples return the same data with no mismatched filters
+These require judgment. Each item maps to a section of CLAUDE.md; apply the full rule as written there.
+
+1. **Frontmatter**: `title` and `description` present; description and opening paragraph don't duplicate each other.
+2. **Structure**: most important information first; prerequisites at the start of procedures; heading hierarchy starts at H2; headings in Title Case; no verb-first headings except procedural steps.
+3. **Voice and tone**: second person, active voice, present tense; no promotional language ("gamechanging," "plays a vital role," or similar); no editorializing ("it's important to note," "in conclusion") or difficulty-minimizing words ("simply," "just," "easily," "obviously"); no filler words in titles or descriptions ("Comprehensive," "Complete"); direct statements over "moreover"/"furthermore"/"additionally"; jargon defined on first use; no generic introductions or concluding summaries that repeat the page.
+4. **Insider terms**: "local-first" and "offline-first" only with context. Prefer describing the outcome: the app responds instantly and stays functional in poor network conditions.
+5. **Dashes**: no dashes joining clauses in running prose; write two sentences. Genuinely parenthetical asides, headings, and code are fine.
+6. **Bold**: reserved for terms being defined and critical distinctions a skimming reader would miss.
+7. **Components**: the right Mintlify component for the job (`<Steps>` for procedures, `<Tabs>` for platforms, `<CodeGroup>` for multi-language examples, appropriate callouts); SDK tab order JS, Dart, Kotlin, Swift, .NET, Rust; images wrapped in `<Frame caption="...">` with descriptive alt text.
+8. **Code examples**: language tag on every block; realistic data; no real secrets; filenames only on self-hosted examples; no SQL table aliases unless required.
+9. **Links and navigation**: internal links use relative paths, never absolute URLs; new pages appear in `docs.json` navigation; moved or removed pages have redirects.
+10. **Sync Streams policy**: no new content that teaches or promotes Sync Rules; where both appear side by side, the examples must return the same data with matching filters.
+11. **Technical accuracy**: flag claims, APIs, or examples you cannot verify.
+12. **Legal and compliance content**: contractual or commercial terms may deviate from standard terminology (for example, "Synchronization Service" in the HIPAA shared-responsibility table). Don't "fix" these; outside legal contexts, the standard terms apply.
 
 ## Output Format
 
 For each issue found, state:
+
 1. The specific rule violated
 2. The problematic text (quoted)
 3. A suggested fix

.claude/skills/doc-reader/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: doc-reader
+description: Read and navigate external documentation efficiently. Invoke when the task requires checking how a specific function, endpoint, or configuration option works; when the user references an API, SDK, library, or third-party tool by name; when any docs URL or documentation site is mentioned; or when implementing something that depends on an external service or package.
+license: MIT
+compatibility: Requires internet access. Works best with Mintlify-powered documentation sites which provide MCP servers and llms.txt files.
+metadata:
+  author: Mintlify
+  url: https://mintlify.com
+  version: "0.3"
+---
+
+# Read documentation effectively
+
+This skill helps you efficiently consume documentation without overwhelming your context window or missing important information.
+
+## Quick reference: choose your approach
+
+| Situation | Approach |
+|-----------|----------|
+| First visit to a doc site | Check for llms.txt, then MCP |
+| Know exactly what you're looking for | MCP search or grep llms-full.txt |
+| Need to read a specific page | Try `.md` URL variant first, then HTML |
+| Exploring/browsing | View HTML page in browser |
+| Need comprehensive understanding | Load llms-full.txt (check length first) |
+| Multiple doc sites in one task | Set up MCPs for each |
+
+## Step 1: Discover what's available
+
+When you encounter a documentation site, check for AI-friendly resources.
+
+### Check for llms.txt
+
+Every well-structured doc site should have an llms.txt file at the root. For example `https://docs.example.com/llms.txt` or `https://example.com/docs/llms.txt`
+
+This file contains:
+- A description of what the documentation covers
+- Links to each page in the docs
+
+Sites may also have llms-full.txt files at the root which contain all the content on the documentation site as a single .md file.
+
+### Try markdown URL variants
+
+Many doc sites serve clean markdown versions of pages at `.md` URL variants. Prefer the `.md` URL extensions for easier to parse content.
+
+For any specific page you need to read, try the `.md` variant first:
+
+```
+https://docs.example.com/page      →  try https://docs.example.com/page.md
+```
+
+If it returns valid markdown (not a 404 or HTML error page), use that instead of fetching the HTML.
+
+### Check for skill.md
+
+Some documentation sites provide a skill.md file that teaches you how to work with the product that is documented. Check for it at the root like `https://docs.example.com/skill.md` or `https://example.com/docs/skill.md`.
+
+Read the skill to understand the product and features. Add the skill if it will be helpful with your current task:
+
+```bash
+npx skills add docs.example.com/skill.md
+```
+
+### Check for MCP server
+
+Some documentation sites provide MCP servers for semantic search. The MCP endpoint often follows this pattern:
+
+```
+https://docs.example.com/mcp
+```
+
+## Step 2: Set up MCP if available
+
+MCP (Model Context Protocol) servers let you search documentation semantically rather than relying on keyword matching or loading entire files.
+
+### Connecting to the MCP
+
+The setup process varies by platform. For Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "example-docs": {
+      "type": "http",
+      "url": "https://docs.example.com/mcp"
+    }
+  }
+}
+```
+
+Once connected, you'll have access to the search tool for semantic search across the documentation. The tool follows the naming pattern `Search{DocsTitle}` (for example, `SearchMintlify`).
+
+### Managing multiple MCPs
+
+When working with multiple documentation sources:
+
+1. Give each MCP a descriptive name based on the product/library
+2. Use the appropriate MCP for each query rather than searching all of them
+
+## Step 3: Choose your consumption strategy
+
+### Strategy A: MCP search (preferred for targeted questions)
+
+Use when:
+- You have a specific question or topic
+- You're looking for a particular API, function, or concept
+- You want semantically relevant results, not just keyword matches
+
+```
+Use the MCP search tool with a natural language query describing what you need.
+```
+
+### Strategy B: Fetch markdown variant (for reading specific pages)
+
+Use when:
+- You need to read a specific documentation page
+- MCP search returned a result but you need the full page content
+- HTML rendering is adding noise or causing truncation
+
+Try the `.md` variant of the page URL:
+
+```bash
+curl -s "https://docs.example.com/page.md"
+```
+
+If it returns valid markdown, use it. If it 404s, fall back to HTML (Strategy E).
+
+### Strategy C: Grep llms-full.txt (for keyword-specific searches)
+
+Use when:
+- You need to find exact matches (function names, error codes, specific terms)
+- MCP isn't available
+- You want to see all occurrences of a term
+
+Grep for your terms:
+```bash
+curl -s "https://docs.example.com/llms-full.txt" | grep -C 3 "your-search-term"
+```
+
+### Strategy D: Load full content (for comprehensive understanding)
+
+Use when:
+- You need complete context about a library/API
+- The llms-full.txt is small enough (< 15k tokens recommended)
+- You're doing extensive work that will reference many parts of the docs
+
+**Always check length first.** Before loading a full file:
+```bash
+curl -sI "https://docs.example.com/llms-full.txt" | grep -i content-length
+```
+
+If the file is too large, consider:
+- Loading specific files identified from llms.txt instead
+- Using MCP search for specific topics
+- Loading in chunks as needed
+
+### Strategy E: View HTML page (for exploration and navigation)
+
+Use when:
+- You need to understand the documentation structure
+- The user needs to navigate or click through the docs
+- You want to see diagrams, interactive examples, or formatted content
+- You're helping the user find something and they need to continue browsing
+
+Fetch and render the HTML page, or direct the user to open it in their browser. HTML pages provide:
+- Navigation menus showing doc structure
+- Interactive code examples
+- Visual diagrams and illustrations
+- Links to related topics
+
+**Watch for truncation.** Pages over ~150,000 characters may get cut off, which means you may miss critical information without knowing it. If a page seems incomplete, try the `.md` URL variant (Strategy B) or look for section-specific files in llms.txt.
+
+## Common patterns
+
+### Pattern: Research before implementation
+
+1. Fetch llms.txt to understand documentation scope
+2. Set up MCP if available
+3. Use MCP search for your specific implementation questions
+4. Load relevant sections as needed
+5. Keep MCP connected for follow-up questions during implementation
+
+### Pattern: Debugging with docs
+
+1. Search for the exact error message or code using grep
+2. If no results, use MCP search with a description of the problem
+3. Load the relevant section for full context on the solution
+
+### Pattern: Learning a new library
+
+1. View the HTML landing page to understand structure
+2. Load llms-full.txt if small enough, or use section-specific files
+3. Set up MCP for ongoing reference during development
+
+### Pattern: Quick reference lookup
+
+1. MCP search with the function/method name
+2. Or grep llms-full.txt for exact matches
+
+## Tips for efficiency
+
+1. **Prefer MCP for Mintlify sites**: Semantic search is more efficient than loading and parsing raw text.
+
+2. **Cache strategically**: If you'll reference the same docs repeatedly, loading llms-full.txt once may be more efficient than multiple MCP searches.
+
+3. **Use section files**: If llms.txt links to section-specific files (like `api/llms.txt`), load only what you need.
+
+4. **Parallel MCP searches**: When working with multiple doc sources, search them in parallel rather than sequentially.
+
+## Handling edge cases
+
+### No llms.txt available
+
+Fall back to:
+1. Check if there's an MCP endpoint anyway
+2. Try `.md` URL variants of specific pages you need to read
+3. Use WebFetch to read specific documentation pages
+4. Search the web for the documentation
+
+### Very large documentation sets
+
+For docs over 15k tokens:
+1. Use MCP search instead of loading the full file
+2. Load section-specific files as needed
+3. Ask the user which areas are most relevant
+
+### Page not found (404)
+
+If a page 404s:
+1. Check the 404 page for links to relevant content
+2. Check llms.txt for the current URL — it reflects the live site structure
+3. Search the MCP with the page topic to find where the content moved
+4. Note to the user that the content may have moved and provide the updated URL
+
+### Outdated or conflicting information
+
+If you find documentation that seems outdated:
+1. Check for version indicators in the docs
+2. Note the discrepancy to the user
+3. Suggest checking the changelog or release notes

.github/vale/PowerSync/Capitalization.yml

@@ -0,0 +1,13 @@
+# Enforces product-term capitalization from the terminology table in .claude/CLAUDE.md.
+# Each pattern lists the incorrect casings; the correct form does not match.
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: error
+ignorecase: false
+# The 'PowerSync' vocabulary entry would otherwise suppress matches like
+# 'PowerSync service' (vocabulary terms are substitution exceptions by default).
+vocab: false
+swap:
+  'Sync rules|sync [Rr]ules': Sync Rules
+  'Sync streams|sync [Ss]treams': Sync Streams
+  '[Pp]owersync [Ss]ervice|PowerSync service': PowerSync Service

.github/vale/PowerSync/FirstPerson.yml

@@ -0,0 +1,19 @@
+# Instructional content is written in second person ("you"). "We" is allowed
+# for statements from the PowerSync team ("we recommend"), and headings are
+# excluded because FAQ-style headings speak in the reader's voice
+# ("Where Can I Find...").
+extends: existence
+scope:
+  - paragraph
+  - list
+message: "Avoid first-person singular ('%s'). Write instructions in second person."
+level: warning
+nonword: true
+vocab: false
+tokens:
+  - (?:^|\s)I\s
+  - (?:^|\s)I,\s
+  - \bI'm\b
+  - \bme\b
+  - \bmy\b
+  - \bmine\b