openwriter 0.35.1 → 0.35.2

package/dist/plugins/authors-voice/skill/docs/anchor-iteration.md

@@ -0,0 +1,176 @@
+# Anchor Iteration
+
+Final-polish minion. Channels the user's voice anchors as a panel; iterates critique → rewrite → re-score until 90/100. Single minion conversation, visible iteration history. Mandatory anti-ai cleanup follow-up.
+
+Specialization of `/polish`'s pattern for writers-voice: channels the user's specific voice anchors (dynamically loaded from `voice/anchor.md` or `voice/anchor-<context>.md`), not generic advertising practitioners.
+
+Replaced the prior single-pass Anchor Critique tool. Single-pass scoring is now just "stop after iteration 1" of Anchor Iteration — same architecture, parameter difference.
+
+## Why this works
+
+AI cannot judge beats subjectively from generic prompts — no dopamine system to consult. But channeled anchors carry beat-judgment encoded in their training-data representations. Channeling Peterson reading prose surfaces Peterson's beat-trained sensibility. Multiplied across the panel, the collective weighted score reflects how the prose lands across the writer's actual voice ambition.
+
+This is the ONLY AI critic tool that can do beat-level judgment, and it works only because the anchors are real humans whose dopamine-trained sensibilities are encoded in training data. Judgment is collective and writer-specific.
+
+## Architecture: one minion, visible iteration
+
+ONE minion conversation. The minion runs the entire iteration loop internally with full visible history — each iteration's anchor critiques are part of the minion's context for the next iteration. Anchors see how their previous critiques were addressed (or weren't), which sharpens subsequent critiques.
+
+Mirrors `/polish` exactly. NOT extracted-and-rerun-cold per iteration. The loop has memory.
+
+Optional fallback: if visible iteration converges on a local optimum (rewriter anchored to original framing through visibility), retry with blind iteration (no prior history shown across iterations). Default = visible.
+
+## Inputs (only)
+
+- The prose to polish
+- The voice anchor blend (dynamically loaded from `voice/anchor.md` or `voice/anchor-<context>.md`)
+
+That's the complete input. No commitments. No beat sheet. No project context. Anchors read the prose AS-IS, like a reader encountering it cold.
+
+**Why no context:** anchors must judge the prose AS IT LANDS, not as it was intended to land. Briefing them on the project would have them judge against the brief, not against the prose. Cold reading is the point.
+
+## Personas (dynamic, inferred)
+
+Pulled from `voice/anchor.md` (or context-specific variant). Each anchor listed with a blend percentage that serves as both voice influence weight and panel vote weight.
+
+The minion infers each anchor's persona from training data — named writers are known entities to opus. System prompt does NOT enumerate per-persona profiles. `/polish` works the same way ("top 10 advertising practitioners" — no profiles needed; opus knows Hopkins, Ogilvy, Sugarman, etc.).
+
+Example book-project anchor file:
+
+```
+- 26% Jordan Peterson
+- 22% Robert Sapolsky
+- 20% Nassim Taleb
+- 18% Bryan Caplan
+- 14% Naval Ravikant
+```
+
+Minion channels each with their characteristic sensibility — Peterson for moral weight and structural rigor, Sapolsky for biological grounding and dry mechanism, Taleb for skin-in-the-game and aphoristic hardness, Caplan for clear thesis with evidence, Naval for aphoristic screenshot-worthy compression.
+
+## Process (per iteration)
+
+1. Each anchor reads the current prose AS-IS, with their characteristic sensibility
+2. Each anchor produces:
+   - SCORE 0-100 (honest read of how this lands for them)
+   - TOP CRITIQUE (ONE thing they would cut, sharpen, or restructure)
+   - STRENGTH (what's working that must be preserved)
+3. Compute collective weighted score using anchor blend percentages
+4. If collective ≥ 90/100: STOP. Mark as FINAL ITERATION. Return converged prose.
+5. If collective < 90/100: synthesize panel's critiques into a FULL REWRITE of the prose (not a sentence-level patch). Preserve named strengths.
+6. Begin next iteration with rewritten prose. Each iteration's anchors see all previous iterations and critiques in their context.
+
+ITERATION CAP: 6 iterations. If still <90 after 6, return highest-scoring iteration with note about non-convergence.
+
+## Output format
+
+Per iteration:
+
+```
+====== ITERATION N ======
+
+PROSE (current state):
+[the prose being read this iteration]
+
+ANCHOR READINGS:
+
+{Anchor Name} ({weight}%): SCORE: X/100
+  TOP CRITIQUE: ...
+  STRENGTH: ...
+
+[repeat per anchor]
+
+COLLECTIVE WEIGHTED SCORE: X/100
+
+[if < 90:]
+SYNTHESIS — what the rewrite must address:
+- ...
+
+REWRITE:
+[next iteration's prose, full text]
+
+[if ≥ 90:]
+CONVERGED. Final prose ready below.
+```
+
+After convergence (or cap):
+
+```
+====== FINAL ======
+Iterations: N
+Final score: X/100
+Convergence: YES / NO
+
+FINAL PROSE:
+[the polished prose, full text]
+```
+
+## Mandatory anti-ai follow-up
+
+Anchor iteration runs no-context. NEVER rules and presentation fingerprints are not in scope during iteration. Rewriter will introduce AI tells the original prose may have avoided.
+
+After convergence, editor MUST run an anti-ai cleanup pass against `voice/never-rules.md` and `voice/fingerprints.md`. Common scrubs:
+
+- em-dashes → commas, periods, or restructured sentences
+- semicolons → "and" or new sentences
+- contrastive negation patterns → direct positive statements
+- banned diction → plain equivalents
+- inserted parenthetical em-dashes → restructure
+
+TWO-STEP pattern. Iteration THEN anti-ai. Two passes do different jobs and should not be conflated. Skipping the anti-ai pass ships AI fingerprints into the published prose.
+
+## When to fire
+
+- Final polish of a beat or section before publishing
+- After integration of multi-minion drafts is complete and the Blinder Audit is clean
+- When prose is content-finished and needs to land at ship-level voice quality
+
+Do NOT fire on:
+
+- Rough first drafts (commitments may still be evolving — polish wastes effort)
+- Sections under structural revision (rewrite the commitments first, then polish the result)
+- Single-paragraph fragments (panel needs prose to evaluate; isolation produces weak critiques)
+
+## Editor's role
+
+1. Identifies a beat ready for final polish
+2. Fires Anchor Iteration with the prose + dynamically loaded anchor blend
+3. Receives the converged output
+4. Runs the mandatory anti-ai cleanup pass
+5. Posts the result for review or comparison
+
+The editor does NOT:
+- Inject project context into the iteration (preserves cold-reader purity)
+- Stop the iteration early (let convergence happen — the loop is the point)
+- Re-judge the panel's collective decisions (panel's authority is the entire point of the tool)
+
+## Failure modes
+
+- **Sycophantic clustering**: anchors give 85+ uniformly. Prompt explicitly bans default-middle scoring and names what 90/60/40 means for each anchor (90 = anchor would actually quote / share; 60 = competent but forgettable; 40 = anchor would put it down).
+- **Persona drift**: anchors all sound like generic helpful AI. Combat by instructing channel-faithfully — each anchor should sound like the actual writer, hostile to AI flattening.
+- **Iteration plateau**: scores stop rising after iteration 3-4. Panel has done what it can. Ship the highest iteration even if below 90, or fall back to blind iteration.
+- **Manufactured content**: rewriter may invent details to address critiques (fabricated autobiographical claims, invented statistics, manufactured anecdotes). Editor MUST scan output for invented content during anti-ai pass and verify or cut as appropriate.
+
+## Model
+
+**Opus required.** Sonnet drifts to default-helpful behavior, scores uniformly high, produces weak rewrites that don't actually address critiques. Opus channels personas with discipline and produces rewrites worth re-scoring.
+
+## Cost
+
+Single conversation, multiple turns. Per iteration: ~3-5k input tokens (prose + previous iteration history) + ~3-5k output (critiques + rewrite). Three iterations ≈ 30k total tokens. Acceptable for chapter-scale work.
+
+For short pieces (tweets, single paragraphs), Anchor Iteration is overkill. Use `/anti-ai` alone or a single Apply call with strong commitments.
+
+## Validation
+
+Tested 2026-05-18 on a 1000-word chapter beat. Three iterations:
+
+- **Iteration 1**: 77.20/100. Panel flagged: thesis buried, mechanism overclaim, no skin-in-the-game, no screenshot-worthy lines.
+- **Iteration 2**: 86.32/100. Rewrite added thesis paragraph + personal admission + mechanism hedge + sharpened closing teaser.
+- **Iteration 3**: 91.04/100. Strengthened personal admission, fixed determinist phrasing, added specific enemies, gave load-bearing line its own paragraph. Converged.
+
+Notable failure modes observed:
+
+- Rewriter manufactured an autobiographical detail (Iteration 2 invented a personal admission to satisfy a skin-in-the-game critique). Editor caught and flagged for verification during anti-ai pass.
+- Iteration introduced em-dashes across 8 paragraphs and semicolons in the opening (original prose used "and"). Mandatory anti-ai pass scrubbed all of them.
+
+The tool delivered ship-quality prose in 3 iterations. The post-iteration anti-ai pass was non-optional.

package/dist/plugins/authors-voice/skill/docs/api/import.md

@@ -0,0 +1,78 @@
+# Import Workflow
+
+## How It Works
+
+The user's writing samples are **not stored locally**. When you import a document, it is uploaded to the Author's Voice API and stored in a cloud database. The API chunks the content, indexes it for search, and uses it for voice matching when `rewrite` or `generate` is called.
+
+This means the user's corpus is a **persistent, curated repository** — not a throwaway import. Every document you add stays in the database and directly influences all future voice output. The quality of the corpus IS the quality of the voice.
+
+**Think of it like a training set:**
+- Documents tagged `Human` are the ground truth. They define the voice.
+- Documents tagged `AI` or `AI-Assisted` are penalized in retrieval — they exist for reference but don't shape the voice.
+- Wrongly tagged documents (AI content marked as Human) **corrupt the voice profile**. The system will learn AI patterns as if they were the author's patterns. This is the single worst thing that can happen to voice quality.
+- Wrong categories cause cross-contamination — email samples polluting blog voice, tweets diluting long-form style.
+
+**The agent's job during import is curation, not bulk ingestion.** Every document must be verified with the user before it enters the corpus.
+
+**Corpus size guidelines:**
+- **Minimum**: 3-5 documents, ~5,000 words — enough for basic pattern detection
+- **Good**: 10+ documents, ~15,000+ words — reliable voice profile
+- **Per category**: At least 3 documents in each category you plan to use for voice output
+- More is better, but only if it's genuinely human-written. 5 authentic documents beat 50 mixed ones.
+
+If the user doesn't have enough samples yet, tell them. A thin corpus produces a weak profile — the agent should set expectations rather than generate from insufficient data.
+
+---
+
+## Critical Rules
+
+These rules are non-negotiable. Violating them degrades voice quality.
+
+### 1. Always Tag Authenticity
+
+Voice profiles are ONLY built from Human-written content. AI-generated docs pollute the voice fingerprint.
+
+**The agent MUST follow this process:**
+1. Gather candidate documents (URLs the user provides, or raw content)
+2. Present the list to the user and ask:
+   - "Which of these did YOU write? (Human)"
+   - "Which were AI-generated or AI-assisted?"
+3. Only import docs the user confirms as Human with `"authenticity": "Human"`
+4. Tag AI/uncertain docs as `"AI"` or `"AI-Assisted"`, or skip them
+5. Ask about categories for each doc
+
+**NEVER assume a document is human-written.** Many users have a mix.
+**NEVER bulk-import without user confirmation per document.**
+
+### 2. Authenticity Labels
+- `Human` — written entirely by a human (default)
+- `AI-Assisted` — human-written with AI help
+- `AI` — generated by AI
+- `Untagged` — unknown origin
+
+### 3. Category Pollution Destroys Voice Quality
+
+Categories control which writing samples the retrieval layer pulls back. Wrong category = wrong examples = wrong voice.
+
+**Impact**: Blog posts tagged as "email" → retrieval pulls email-style samples → output sounds corporate, not blog-voice. Tweets tagged as "blog" → retrieval pulls long-form samples → output loses punchy fragments.
+
+**The agent MUST:**
+1. Ask the user what category each document belongs to during import
+2. Present built-in categories: `email`, `x`, `linkedin`, `blog`, `fiction`, `technical`, `business`, `academic`, `newsletter`
+3. If uncertain, ask the user — NEVER guess categories
+4. When calling `rewrite`, ALWAYS pass `category` to scope retrieval
+5. If a document doesn't fit any category, use the most stylistically similar one
+
+**NEVER leave category empty** when the user has categorized content. Empty category retrieves from all categories, diluting the voice signal with stylistically mixed samples.
+
+---
+
+## Import Tools Quick Reference
+
+| Tool | Use |
+|------|-----|
+| `import_from_url` | Import from any public URL (`url`, `categories[]`, `authenticity`) |
+| `bulk_import` | Import multiple docs, max 50 (global `authenticity`) |
+| `upload_content` | Upload raw markdown. Minimal payload `{docId, content}` — `profileId` optional (auto-resolves a default profile), `content` server-chunked on blank lines. |
+
+After import: run `setup_voice` to create/update the voice profile. Update `local/state.md`.

package/dist/plugins/authors-voice/skill/docs/api/protocol.md

@@ -0,0 +1,140 @@
+# Voice Emulation Protocol
+
+Two API endpoints do the voice work. The agent's job is to gather inputs,
+call the endpoint, and return the result. The server handles profile loading,
+sample retrieval, voice-guided generation, and anti-AI passes.
+
+**Do not attempt to emulate the voice yourself** — the API is the only path
+that produces reliable voice quality.
+
+- **Rewrite existing text** → `rewrite`
+- **Generate new content** → `generate` (see `/voice-generate`)
+
+## API Base
+
+```
+BASE_URL=https://api.authors-voice.com
+```
+
+All endpoints require `Authorization: Bearer $AV_API_KEY`.
+
+## rewrite — Rewrite Existing Text
+
+```bash
+curl -s -N -X POST "${BASE_URL}/api/voice/mcp" \
+  -H "Authorization: Bearer $AV_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
+    "name":"rewrite","arguments":{
+      "content":"<text to rewrite>",
+      "mode":"rewrite",
+      "category":"<x|blog|email|...>",
+      "inputType":"ai-assisted",
+      "contextBefore":"<optional>",
+      "contextAfter":"<optional>",
+      "format":"plaintext"
+    }}}'
+```
+
+**Required**: `content`, `category`.
+**Defaults**: `mode=rewrite`, `inputType=ai-assisted`, `format=plaintext`.
+
+### Modes
+
+- `rewrite` — standard voice rewrite (default)
+- `shrink` — compress while keeping voice
+- `expand` — lengthen while keeping voice
+- `custom` — pass `customInstruction` with specific directives
+
+### inputType
+
+- `human` — author's own writing. Preserve word choices and quirks; only polish flow.
+- `ai` — generic AI content. Discard phrasing entirely; rewrite from scratch using voice samples.
+- `ai-assisted` (default) — mixed. Preserve author-sounding passages; rewrite generic parts.
+
+## generate — Create New Content
+
+```bash
+curl -s -N -X POST "${BASE_URL}/api/voice/mcp" \
+  -H "Authorization: Bearer $AV_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
+    "name":"generate","arguments":{
+      "instruction":"<what to write>",
+      "category":"<x|blog|email|...>",
+      "query":"<optional topic keywords>",
+      "targetWords":500,
+      "contextBefore":"<optional>",
+      "contextAfter":"<optional>",
+      "format":"plaintext"
+    }}}'
+```
+
+**Required**: `instruction`, `category`.
+**`query`**: optional — use when the retrieval topic differs from the instruction wording. If omitted, instruction + context are used for retrieval.
+**`targetWords`**: optional; max 2000.
+
+## Voice Anchor (V1 lead signal)
+
+An anchor is reference prose the author wants to sound like. When set, it's
+injected **ahead of** sample retrieval in both `rewrite` and `generate` (and the
+OpenWriter editor path), so it's the strongest single voice lever available.
+
+Derive + persist from pasted prose:
+
+```bash
+curl -s -X POST "${BASE_URL}/api/voice/anchor/derive" \
+  -H "Authorization: Bearer $AV_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"<reference prose>","profileId":"<optional>"}'
+```
+
+Read / replace / clear the persisted anchor:
+
+```bash
+curl -s     "${BASE_URL}/api/voice/anchor" -H "Authorization: Bearer $AV_API_KEY"   # GET
+curl -s -X PUT    "${BASE_URL}/api/voice/anchor" ... # replace
+curl -s -X DELETE "${BASE_URL}/api/voice/anchor" ... # clear
+```
+
+MCP equivalent: the `set_voice_anchor` tool. `list_profiles` reports `hasAnchor`
+and `anchorAuthors` per profile so you can check anchor state without a GET.
+
+## Response Parsing
+
+The response is Server-Sent Events. Find the line starting `data: `, parse
+the JSON, and extract the text:
+
+```
+result.content[0].text
+```
+
+That text is the final voice-matched output. Return it verbatim — no
+post-processing needed.
+
+**Defensive fallback**: if the text itself parses as JSON, extract `.content`
+or `.text` from the parsed object. Most responses are plain text, but the
+wire format permits JSON envelopes.
+
+## Categories
+
+Always pass `category` — scopes retrieval to the right writing style.
+
+Built-in: `x`, `blog`, `email`, `newsletter`, `linkedin`, `technical`,
+`business`, `academic`, `fiction`.
+
+## Context
+
+When editing inside existing text, pass `contextBefore` and `contextAfter`
+as the surrounding paragraphs. Context guides flow but is **never included
+in the output**.
+
+## Errors
+
+- `401` → API key invalid. User should run `/voice-setup`.
+- `404 profile not found` → profile not built. User should run `/voice-setup`.
+- `429` → rate limit. Wait and retry.
+- Timeout (>30s) → retry once; then surface the error.
+

package/dist/plugins/authors-voice/skill/docs/api/setup.md

@@ -0,0 +1,37 @@
+# Setup — One-Time Configuration
+
+## API Key (Email OTP — Primary Method)
+
+The agent handles signup directly. No website visit needed.
+
+1. Ask the user for their email address
+2. Send `POST https://api.authors-voice.com/auth/request-code` with `{ "email": "<user's email>" }`
+3. Tell user: "Check your email for a 6-digit verification code from Author's Voice."
+4. User provides the code
+5. Send `POST https://api.authors-voice.com/auth/verify-code` with `{ "email": "<user's email>", "code": "<6 digits>" }`
+6. Response: `{ "apiKey": "av_live_...", "tenantId": "email|..." }`
+7. Save the API key to `~/.claude/skills/authors-voice/local/config.md` and set `AV_API_KEY`
+
+**Rate limits**: 5 requests/min per IP, 60s cooldown between sends, max 3 attempts per code, code expires in 10 minutes.
+
+**If email OTP fails**: Ask the user to get a key manually at [authors-voice.com/voice?tab=api-keys](https://authors-voice.com/voice?tab=api-keys).
+
+## OpenWriter Plugin
+
+Author's Voice also works inside [OpenWriter](https://openwriter.io). The plugin auto-resolves the API key from `~/.openwriter/config.json` if configured.
+
+## Base URL
+
+Defaults to production. Override with `AV_BASE_URL` env var.
+
+```bash
+AV_BASE_URL="https://api.authors-voice.com/api/voice/mcp"
+```
+
+## Seeding writing samples
+
+Import samples with `import_from_url` (any public URL), `bulk_import` (up to 50
+at once), or `upload_content` (raw markdown — minimal payload `{docId, content}`).
+Inside OpenWriter, right-click a doc in the filetree to ingest it directly
+(doc-level, manual re-sync). The Google Drive / Notion connectors were removed in
+June 2026.

package/dist/plugins/authors-voice/skill/docs/api/tools.md

@@ -0,0 +1,102 @@
+# API Reference
+
+## REST Endpoints (recommended)
+
+All endpoints require `Authorization: Bearer $AV_API_KEY`. Base URL: `https://api.authors-voice.com`
+
+### Core Skill Endpoints
+
+**Get voice profile** — full linguistic fingerprint (6 categories + sentence distribution):
+```bash
+curl -s https://api.authors-voice.com/api/voice/profiles/default \
+  -H "Authorization: Bearer $AV_API_KEY"
+# Optional: ?format=detailed for profile ID + summary
+```
+
+**Apply voice** — rewrite content in the author's voice:
+```bash
+curl -s -X POST https://api.authors-voice.com/api/voice/apply \
+  -H "Authorization: Bearer $AV_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "text to rewrite", "mode": "rewrite", "inputType": "ai", "category": "x"}'
+```
+
+### Additional REST Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/api/voice/profiles` | GET | List profiles with counts |
+| `/api/voice/profiles/:profileId` | GET | Full voice profile (use `default` for default) |
+| `/api/voice/apply` | POST | Rewrite content in author's voice |
+| `/api/voice/setup` | POST | Analyze samples and build voice profile |
+| `/api/voice/content` | GET | List writing samples (query: profileId, category) |
+| `/api/voice/content` | POST | Upload content chunks |
+| `/api/voice/content/bulk` | POST | Bulk upload documents |
+| `/api/voice/content/:docId` | PATCH | Update doc metadata |
+| `/api/voice/content/:docId` | DELETE | Delete document |
+| `/api/voice/anchor/derive` | POST | Derive a voice anchor from pasted prose |
+| `/api/voice/anchor` | GET/PUT/DELETE | Read / persist / clear the voice anchor |
+| `/api/voice/usage` | GET | Usage stats |
+
+---
+
+## MCP Protocol (alternative)
+
+For MCP-compatible clients, all tools are also available via JSON-RPC POST:
+
+```bash
+curl -s -X POST "https://api.authors-voice.com/api/voice/mcp" \
+  -H "Authorization: Bearer $AV_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{...}}}'
+```
+
+---
+
+## Available Tools (12)
+
+### Content Import (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `import_from_url` | Import from any public URL (Medium, Substack, WordPress, .md/.txt). Args: `url`, `categories[]`, `authenticity`. |
+| `bulk_import` | Import multiple docs (max 50). Each item: `{url}` or `{content, docId}` + `categories[]`. Global `authenticity`. |
+| `upload_content` | Upload raw markdown. **One-click ergonomics**: `profileId` is optional — omit it and the server auto-creates/resolves a default profile. `content` can be raw text (server chunks on blank lines) instead of pre-split `chunks[]`, so the minimal payload is `{docId, content}`. Re-uploading the same `docId` replaces (idempotent). This is the contract the OpenWriter filetree right-click ingestion posts against. |
+
+### Voice Profiles (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_profiles` | List voice profiles, categories, and document counts. Each profile also carries `hasAnchor` (bool) and `anchorAuthors` (the reference authors behind the anchor), so callers can tell which profiles carry an anchor without a per-profile GET. No args. |
+| `get_voice_profile` | Get full voice guidelines — 6 linguistic categories + sentence stats. Use before writing to understand the author's patterns. Optional `profileId`. |
+| `setup_voice` | Analyze samples → create/update voice profile. Args: `profileName`, optional `forceReanalyze`. Call after importing content. |
+
+### Voice Anchor (1 tool)
+
+| Tool | Description |
+|------|-------------|
+| `set_voice_anchor` | Derive and persist a voice anchor from pasted reference prose. The anchor is V1's lead voice signal — injected ahead of sample retrieval in `rewrite`/`generate` and the OpenWriter editor path. REST equivalents: `POST /api/voice/anchor/derive`, `GET/PUT/DELETE /api/voice/anchor`. |
+
+### Voice Application (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `rewrite` | Rewrite existing content in the author's voice. Modes: `rewrite`, `shrink`, `expand`, `custom`. Supports `contextBefore`/`contextAfter`, `inputType`, `category`. |
+| `generate` | Generate NEW content in author's voice. Args: `instruction`, optional `query` (topic for retrieval), `contextBefore`/`contextAfter`, `category`, `targetWords`. |
+
+**rewrite parameters**: `content`, `mode`, `contextBefore`, `contextAfter`, `category`, `inputType` (human/ai/ai-assisted), `targetWords` (max 2000), `format` (markdown/plaintext).
+
+**inputType** controls how aggressively the rewrite treats the input:
+- `human` — Author's own writing. Preserve word choices and quirks, only polish flow/grammar.
+- `ai` — Generic AI content. Discard phrasing entirely, rewrite from scratch using voice samples.
+- `ai-assisted` (default) — Mixed authorship. Preserve passages matching the author's voice, rewrite generic/formulaic parts.
+
+**generate note**: `query` is optional — describes what content is ABOUT for better voice retrieval. When omitted, context + instruction are used for retrieval.
+
+### Content Management (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_content` | List writing samples with chunk counts. Optional `category` filter. |
+| `update_content` | Retag a doc. Args: `docId`, `categories[]`, `authenticity`. |
+| `delete_content` | Permanently delete a doc and its chunks. Args: `docId`. |

package/dist/plugins/authors-voice/skill/docs/api/troubleshooting.md

@@ -0,0 +1,7 @@
+# Troubleshooting
+
+**"Unauthorized"** — Check `AV_API_KEY` is set and starts with `av_live_`.
+
+**"profileId query parameter is required"** — Some REST endpoints need profileId. For MCP tools, omit profileId to use the default profile.
+
+**Empty document list** — Connection is active but no documents match. Try without a query filter.