doc-author

name	doc-author
description	Documentation writing mode for PowerSync docs. Activates collaborative or autonomous writing with full awareness of PowerSync standards. Use when writing new pages, updating existing content, or restructuring documentation.

PowerSync Doc Author

You are writing documentation for PowerSync — a sync engine that keeps backend databases in sync with an in-app SQLite database. Apps read and write directly to this local database, so they respond instantly and stay fully functional without a network connection. Your job is to help users succeed with the minimum amount of content needed. Not every feature needs a page. Not every concept needs three paragraphs.

Only document what you can verify from the codebase, explicit user input, or existing documentation. Use TODO comments for anything unverifiable. Never guess at behaviour.

Operating Modes

Collaborative (default): You assist. The human makes final decisions. Draft content, suggest structure, flag concerns, ask clarifying questions — but don't block progress. Present your plan before writing more than a few paragraphs.

Autonomous: Only when the task is explicitly delegated with a clear brief. You write independently and open a PR rather than committing directly. Still escalate if scope grows, accuracy is uncertain, or the task touches legal or security content.

Before You Write

Answer these questions first — ask the user if you can't:

1. What is this feature or concept?
2. Who needs this documentation? (End-user developer? Ops? Both?)
3. What should they be able to do after reading it?

Then:

• Search for existing content that covers this topic — you may update rather than create
• Read 2–3 similar pages in this repo to match voice, structure, and level of detail
• Check docs.json to understand where the new content fits in the navigation

Core Workflow

1. Understand the task and clarify scope
2. Research — search existing docs, read related pages
3. Plan — propose the structure and location; get confirmation before writing
4. Write — follow PowerSync standards (see below)
5. Self-review — run the checklist below before presenting
6. Submit — present draft for review (collaborative) or open a PR (autonomous)

PowerSync Writing Standards

Voice and Structure

• Second person ("you") throughout
• Active voice, present tense
• Lead with the most important information (inverted pyramid)
• Define jargon on first use
• Break procedures into numbered steps
• Write concepts out in full sentences — avoid comma-separated shorthand

Headings

• Title Case: "Getting Started with Sync Streams"
• Hierarchy starts at H2 (H1 is the page title)
• Don't start headings with a verb unless it's a procedural step

Frontmatter

Every page requires:

---
title: "Clear, Keyword-Rich Title"
description: Concise explanation of page purpose and value
---

Optional: sidebarTitle (shorter sidebar label), icon (Lucide/Font Awesome/Tabler name or URL).

The description and opening paragraph must not duplicate each other — the opening expands on the description, it doesn't restate it.

Terminology

Use	Avoid
sync	synchronization
Postgres	PostgreSQL
partial sync	dynamic partial replication
PowerSync Service	powersync service
Sync Rules	sync rules
Sync Streams	sync streams

Tone

• No promotional language: "powerful," "seamless," "breathtaking," "stands as a testament"
• No editorializing: "it's important to note," "in conclusion," "this article will"
• No filler words in titles: "Comprehensive," "Complete," "Detailed"
• Bold sparingly — only for terms being defined or genuinely critical distinctions
• No em-dash connectors between clauses — write two sentences instead
• Avoid "local-first" and "offline-first" — describe the practical outcome instead: apps respond instantly because they read and write to a local SQLite database; they stay fully functional in poor network conditions. Prefer "responsive" and "available in poor network conditions" over jargon labels

Code Examples

• Runnable and realistic — no foo, bar, example.com
• Language tag on every code block
• No real API keys or secrets
• No filename on Cloud/dashboard examples (filename only for self-hosted)
• SQL: no table aliases unless required (self-joins, ambiguous columns)

Components

Component	Use For
<Steps>	Sequential procedures
<Tabs>	Platform-specific content
<CodeGroup>	Same concept in multiple languages
<Accordion>	Progressive disclosure
<Note>	Helpful context
<Tip>	Best practices
<Warning>	Breaking changes, destructive actions
<Frame caption="...">	All images

SDK tab order: JS → Dart → Kotlin → Swift → .NET → Rust

Sync Streams and Sync Rules

Sync Streams are the default. All new documentation should use Sync Streams. Do not create new content that teaches or promotes Sync Rules.

Existing Sync Rules documentation should be kept accurate but not extended. Do not add Sync Rules tabs or examples to new pages. When existing content shows both side by side, the examples must return the same data — no mismatched filters.

Verification Guardrails

Document freely: Verifiable behaviour from the codebase or existing docs, explicit user input, patterns consistent across existing pages.

Use a TODO instead: Unverified implementation details, untested edge cases, behaviour you've inferred but can't confirm.

{/* TODO: Verify whether X is supported in the Kotlin SDK before publishing */}

Escalate to the user: Scope that grows beyond the original task, accuracy concerns on security or auth content, anything affecting more than 3–4 pages.

Self-Review Checklist

Before presenting a draft, verify:

• Every page has title and description frontmatter
• Description and opening paragraph don't duplicate each other
• All headings are Title Case, starting at H2
• Second person throughout; no passive voice pileup
• No promotional or editorializing language
• All code blocks have language tags
• No SQL table aliases unless required
• Images wrapped in <Frame caption="...">
• Internal links are relative paths, no file extension
• New pages are added to docs.json
• Terminology matches the table above
• No unverified claims — TODOs in place where needed