openwriter 0.35.1 → 0.36.0

package/dist/plugins/authors-voice/skill/catalog/post-write-audit.md

@@ -0,0 +1,105 @@
+# Post-Write Audit
+
+> Distribution-level statistical checks the orchestrator runs against the minion's returned prose. Sits between step 6 (NEVER scan) and step 7 (integration) of the Apply Protocol. Catches statistical fingerprints the minion's prompt can't reasonably prevent without cognitively overloading the writing pass.
+
+## When this runs
+
+After step 6 (NEVER-violations scan + brief-error patching), before step 7 (integration). The orchestrator reads this file, applies each check to the minion's output, and surgically rewrites the smallest span that brings the failing metric back into range.
+
+## Why this layer exists
+
+The minion writes prose. The orchestrator polices distribution and lexicon. Anything mechanically detectable after the fact lives here, not in the writing-pass prompt — the minion's cognitive budget should go to channeling the anchor and hitting the commitments, not tracking 60 micro-bans.
+
+Two enforcement points still exist for the bans the minion DOES need to see (contrastive negation, sentence-opener repetition, em-dashes, etc.) — those live in `voice/never-rules.md` and get scanned at step 6. This audit is for the slop that's cheaper to scrub than to prevent.
+
+## Remediation principle
+
+For each failing check, rewrite the **smallest local span** that fixes the metric. Do not regenerate. Do not reach for stylistic improvement. The minion's voice IS the result — the audit only nudges the statistics.
+
+If a failing span is load-bearing (a specific image, a coined term, a structural beat the brief demanded), leave it. Audit findings are advisory at the boundary case. The minion's intent wins ties.
+
+Aim for the lightest touch: 5-10 small substitutions across a typical draft brings rates back in line. Heavier rewrites mean the audit is being misused.
+
+## Distribution checks
+
+### 1. Sentence-opener repetition
+
+**What to measure:** walk the output sentence by sentence. For each window of 3 consecutive sentences, check whether all three start with the same first word.
+
+**Threshold:** flag if >30% of windows trigger.
+
+**Why this number:** human writing sits at ~17% (DFT 2026 — mostly from intentional list structures like "How does X?... How does Y?... How does Z?"). SFT models at T=0.7 hit 53.3%. The 30% line cleanly separates human from AI.
+
+**Action:** locate the offending windows. For each, rewrite the second OR third sentence to start with a different word. If the window forms an intentional list, leave it — list structure is the human use case the 17% baseline reflects.
+
+### 2. Sentence-initial "The" frequency
+
+**What to measure:** percentage of sentences that begin with the word "The."
+
+**Threshold:** flag if >15% of all sentences.
+
+**Why this number:** "The" at sentence start is over-used by ~90% in SFT output vs human writing (DFT 2026, 14B SFT model). The +90% inflation puts AI rates well above the natural human range.
+
+**Action:** locate sentences starting with "The." Rewrite a portion to start with a different determiner ("A", "An", "These"), a pronoun, a prepositional phrase, or a different subject. Five to seven swaps across a typical paragraph is usually sufficient.
+
+### 3. Function-word over-use
+
+**What to read for:** the AI distribution-distance signal lives mostly in function words, not fancy diction. Top-10 tokens account for 87.2% of L2 distribution distance in SFT output (DFT 2026). Watch for:
+
+| Token | SFT inflation vs human |
+|---|---|
+| `is` | +44% |
+| `was` | +49% |
+| `are` | +31% |
+| `that` | +25% |
+| `a` | +15% |
+| `to` | +11% |
+| `.` (period) | +19% |
+
+**Heuristic check (no exact threshold):** scan the draft for clusters of short copular sentences ("X is Y. Z is W. P is Q.") and high period density (many short sentences in a row). Both are signatures of function-word inflation.
+
+**Action:** when noticed, merge two short copular sentences into one with a participial or relative clause; vary sentence structure to use action verbs instead of "is/was"; combine short sentences to drop period count. Three to five rewrites across a paragraph usually levels the distribution.
+
+### 4. Sentence-length variance
+
+**What to measure:** compute standard deviation of sentence length (in words) across the output. If the user has a `voice/stats.md`, compare to the user's own σ. Otherwise compare to baseline σ ≥ 8 words.
+
+**Threshold:** flag if σ < 6 words (low variance — uniform sentence length is an AI signature).
+
+**Action:** locate runs of similar-length sentences. Merge two short ones into a longer compound, or split a medium one. The goal is to restore length variance, not hit a specific number.
+
+## Lexical watch list
+
+Mechanical word-level scrubs. The minion doesn't see these — the audit handles them on the way out.
+
+### GPT-5 specific over-used tokens (DFT 2026)
+
+When the minion is a GPT-5-class model, these tokens are inflated vs human writing. Scan for them:
+
+| Token | Inflation vs human | Human baseline |
+|---|---|---|
+| `corridors` | +45.2% | 0.1% |
+| `norms` | +43.1% | 0.1% |
+| `align` / `aligns` / `alignment` | +36.0% | 0.2% |
+| `metrics` | +27.2% | 0.2% |
+| `engagement` | +26.5% | 0.2% |
+| `targeted` | +5.1% | 1.6% |
+| `identity` | +5.0% | 1.0% |
+| `trust` | +4.9% | 1.2% |
+
+**Action:** swap to a context-appropriate alternative when the word appears in surplus (3+ uses in a short piece, OR any use in a context where the word feels generic). If the user's corpus contains the word at signature frequency (in `voice/stats.md` or `voice/never-rules.md` exempts), leave it — they own that word.
+
+### Named-character defaults
+
+AI defaults to specific generated names in fiction. Known examples:
+
+- `Elara Voss` — documented in OpenAI's "goblin problem"
+- Add new defaults as documented.
+
+**Action:** if found in fiction output without explicit user specification, rename to something contextually appropriate or to a name the user has used in their corpus.
+
+## Source
+
+Distribution thresholds and over-use rates from "Fixing LLM Writing with Distribution Fine-Tuning," Rosmine 2026 (https://rosmine.ai/2026/05/18/fixing-llm-writing-with-distribution-fine-tuning/). Token over-use rates measured against 14B SFT vs human fineweb baseline. Sentence-opener repetition methodology: percent of texts containing 3+ consecutive sentences starting with the same first word.
+
+This file is a living checklist. New research that surfaces measurable thresholds for AI-vs-human writing belongs here, not in `voice/never-rules.md` — the writing pass stays lean.

package/dist/plugins/authors-voice/skill/docs/analysis.md

@@ -0,0 +1,31 @@
+# Analysis Protocol
+
+Regenerates the voice files from the corpus. Run any time the corpus changes (new samples added, samples removed, samples revised). Loaded only when triggered — not in context during normal writing sessions.
+
+## Protocol
+
+1. **Read inputs.** Concatenate every file in `voice/corpus/` (strip frontmatter). Count words. Read `catalog/ai-tells.md`, `catalog/fingerprints.md`, `catalog/hurdle.md`.
+
+2. **Compute deterministic tally** (best effort — counts may drift ±1 on long corpora):
+   - **Sentence distribution**: split on `[.!?]\s`, compute short/medium/long/very-long percentages, average length. Set `short_max` (25th-pct, clamped [6,12]) and `long_min` (75th-pct, clamped [18,28]). Do NOT emit a sentence-length cap in the apply directive — the corpus distribution carries the right ceiling and an arbitrary cap suppresses signature long sentences.
+   - **Punctuation density per 1k words** for em/en dash, colon, semicolon, question, exclamation, ellipsis, paren, bracket, straight/curly quotes. Categorize as `never` / `rare` / `low` / `strong`.
+   - **AI-tell tally**: count each item from `catalog/ai-tells.md`. Apply hurdle from `catalog/hurdle.md`: passes hurdle → preserve; fails → emit NEVER rule; below-hurdle but present → log to `below_hurdle`.
+   - **Fingerprints**: apply each detector from `catalog/fingerprints.md` with its decision rule.
+
+3. **Determine tier** by word count: <300 = 0 Empty; 300-999 = 1 Anchor; 1000-4999 = 2 Preliminary; 5000-19999 = 3 Full Coverage; ≥20000 = 4 AV-Grade. See `docs/tiers.md` for what unlocks at each tier.
+
+4. **Write `voice/stats.md`** — corpus stats, sentence distribution table, punctuation density table.
+
+5. **Write `voice/never-rules.md`** — preserve `## Manual Additions` section verbatim (anchored to start-of-line; the literal also appears in the intro blockquote — naive search will mis-grab it).
+
+6. **Write `voice/fingerprints.md`** — preserve `## Manual Overrides` section, same caution.
+
+7. **Write `voice/status.md`** — tier, words, active features, locked features, next milestone, file list, below-hurdle detections.
+
+8. **Report** — new tier, what changed in NEVER rules, what's locked next.
+
+For corpora >10k words, count in passes (words → phrases → transitions) rather than tracking 60 counters at once.
+
+## Adding Samples Later
+
+User says "add this to my voice profile" or pastes new writing. Append to next `voice/corpus/sample-NNN.md`, re-run Analysis Protocol, report tier change if any.

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.