Writing Dashboard

A writing dashboard plugin that integrates AI-powered chapter generation, micro-editing, and character management into your writing workflow.

Quick start (recommended)

1. Install and enable Writing dashboard.
2. Open Settings → Writing dashboard (plugin settings).
3. Choose an API provider, paste your API key, and select a model.
4. Set Book main file using the file tree picker (select your active manuscript note from the dropdown).
5. Optional but recommended: set Story bible path.
6. Open the dashboard:
   • Ribbon icon: Open dashboard
   • Command palette: Open dashboard

Where to get API keys

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/settings/keys
• Google Gemini: https://aistudio.google.com/app/apikey
• OpenRouter: https://openrouter.ai/keys

Features

🎯 Writing modes

1. Generate chapter - Generate new chapters using your slate method, pulling from:

   • Retrieved context (whole vault) - RAG retrieval from all indexed files
   • Story Bible + Extractions
   • Sliding Window - Last 20,000 words of your active manuscript (extracted automatically)
   • Your Scene Summary + Rewrite Instructions
   • Target word range (Min/Max)

   Important: The plugin only sends the last 20,000 words of your active manuscript (sliding window) to the AI, not full book files. Continuity is maintained through RAG retrieval from your whole vault.

2. Micro Edit - Refine specific passages with:

   • Selected text analysis
   • Your grievances and directives
   • Full context awareness (characters, canon, style)
   • Surrounding context - Automatically includes 500 words before and after for seamless narrative flow
   • Single refined alternative output

3. Character Update - Extract and update character notes (dedicated "Characters" tab):

   • Own Tab: Character Update has its own dedicated tab in the dashboard for easy access
   • Manual extraction from pasted narrative text
   • Timestamped updates with word/character counts
   • Voice evidence, traits, relationships, arc progression
   • Automatic character folder management
   • AI Backend Choice: Use Ollama (local) or Cloud API for character extraction
   • Bulk backfill (Process Entire Book) with improved recall:
     • Pick which file to process (Book 1 / Book 2 / any note)
     • Splits by H1 chapter headings (# )
     • 2-pass pipeline (roster pass + per-chapter extraction)

4. Continuity check - Scan a draft against canon and context:

   • Flags violations (knowledge state, timeline, POV drift, naming)
   • Includes evidence quotes and suggested patches (copy/paste)

📁 Vault Integration

• Full vault browser with folder structure
• Read/write access to all Obsidian files
• Automatic path detection
• Configurable file paths

🛠️ Semantic Index Management

The plugin provides dedicated tools for maintaining your local semantic index:

• Re-index Vault: Manually trigger a full rescan and re-embedding of your vault.
• Clear Index: Wipe the local vector cache to fix corrupted states or start fresh.
• Live Progress: The Re-index button shows dynamic progress ("Indexing 12/39...") and is disabled during indexing.
• Persistent Status: Settings display "📊 Index Status: X chunks across Y files" so you always know your index health.
• Circuit Breaker: If embedding repeatedly fails, the plugin pauses for 15 seconds to prevent infinite spinning.
• Robust Processing: Automatically handles long contiguous strings (like logs or base64) by splitting them into digestible chunks for the embedding model, preventing API "400 Bad Request" errors.
• Ollama Integration: Uses your local Ollama instance (defaulting to nomic-embed-text) for high-quality, private semantic embeddings.
• Bidirectional Model Matching: Recognizes models whether you use nomic-embed-text or nomic-embed-text:latest.

🧠 Under the Hood (Advanced Architecture)

1. RAM-Aware Context Control

The plugin automatically prevents system freezes by deriving safe context limits from your hardware:

• First-Run Setup: On first install, a modal asks "How much RAM does this machine have?" (8/16/24/32/64/128 GB)
• Safety Tables: Conservative limits for each RAM + Model size combination. A 70B model is blocked on 16GB RAM; a 7B model gets generous context.
• Risk Profiles: Choose between Safe (conservative), Moderate (balanced), or Aggressive (maximum performance, higher freeze risk)
• Dynamic Derivation: derivedCap = min(BASE × MULTIPLIER, PROFILE_CAP, model's actual num_ctx)
• Slider Control: Settings include a context window slider within your safe range
• Model Verification: Query Ollama to get the model's actual context limit

2. Rolling Window Refinement

For Local AI (Ollama), the plugin treats the generation field as a Living Document:

• 3-Chunk Juggling: Maintains a rolling buffer of the last ~1500 words to ensure narrative cohesion.
• Live Patching: The AI background "Stitcher" pass polishes transitions in real-time. You'll see text "settle" into its final form with a subtle highlight.
• Consolidated Single-Model Architecture: Optimized for 16GB-32GB RAM machines. All text tasks (Writing, Auditing, Stitching) use your primary Smart Model with specialized task profiles (Temp 0.7 for writing, Temp 0.1 for mechanical logic). This eliminates the 30-60 second latency penalty of VRAM swapping between different models.
• Hardware Optimization: Uses KV Cache Grafting and a stable prefix to keep Ollama "warm" between different tasks.
• Multi-Segment Generation: Fixed 700-token output reserve per segment allows more context per call. A 16k context window can effectively access 100k+ tokens through RAG-refreshed multi-segment generation.

3. Narrative Integrity Gates

Five layers of protection ensure the AI never breaks your story:

• Hash Gate: Rejects AI edits if you've manually changed the paragraph in the meantime.
• User-Dirty Protection: Once you edit a paragraph, the AI is strictly forbidden from auto-patching it.
• LockMap Gate: Protects proper nouns, character names, and dates from being altered.
• Tuple Gate: Prevents the introduction of contradictory facts or "hallucinated" canon.
• Budget Gate: Limits the amount of change the background pass can make, preventing "runaway" edits.

4. 2-Pass Character Extraction

The "Process Entire Book" feature uses a sophisticated pipeline:

• Pass 1 (Roster Discovery): Scans the manuscript to build a global list of names and resolve aliases.
• Pass 2 (Extraction): Re-scans each chapter with the roster in mind to ensure accurate, non-duplicate character notes.

5. Hybrid Retrieval & Diversity (MMR)

The RAG engine uses Reciprocal Rank Fusion (RRF) to combine keyword (BM25) and semantic results, followed by Maximal Marginal Relevance (MMR) to filter out redundant context snippets.

6. Shared Brain (Inter-Plugin Communication)

GWriter can share its embedding index with the StoryBoard plugin:

• Handshake Protocol: Plugins exchange compatibility info via .obsidian/embeddings/handshake/
• Shared Index: When compatible, both plugins read/write to /Embeddings/shared-index/
• Locking: Prevents simultaneous writes with heartbeat-based lock system
• Auto-Discovery: In "Auto" mode, GWriter detects StoryBoard's presence and shares automatically
• Storage Modes: Isolated (private), Auto (shared if compatible), or Manual (user-specified path)

✨ Key Highlights

• Fully Self-Contained - No Python backend required! Everything runs within Obsidian
• Multi-Provider Support - Works with OpenAI, Anthropic (Claude), Google Gemini, OpenRouter, and local Ollama
• RAM-Aware Safety - Automatically derives safe context limits based on your hardware (8GB-128GB+), preventing system freezes
• Local AI Optimized - Use a single Smart Model (e.g., Llama 3.2) for all text tasks and a specialized Embedding Model (e.g., Nomic) for lightning-fast semantic indexing.
• Smart Context Integration - Automatically pulls from your Story Bible, Extractions, sliding window (last 20k words), and Character notes via RAG retrieval
• Efficient Context Usage - Only sends the last 20,000 words of your active manuscript to the AI, not full book files. Full continuity comes from RAG retrieval.
• Multi-Segment Generation - Even with a 16k context window, GWriter can produce 10,000+ word chapters through RAG-refreshed multi-segment generation
• Surrounding Context - Micro-edit mode includes 500 words before/after selected text for better narrative continuity
• Prompt Size Warning - Estimates prompt size and warns if you exceed your configured context limit
• Setup Wizard - First-run wizard to create default vault structure (Book-Main.md, Story Bible, Characters folder, etc.)
• Hybrid retrieval (local RAG) - Combines BM25 lexical ranking, local Ollama embeddings, and diversity selection to inject relevant context without a server
• Shared Brain - Share embedding index with StoryBoard plugin for cross-plugin context awareness
• File Chunking - Manually chunk large files into 500-word segments for processing
• Developer Tools - Built-in stress test for comprehensive plugin diagnostics, including adversarial word handling and safety gate verification.

Architecture

Self-Contained Plugin

• Pure Obsidian Plugin - TypeScript/React UI
• Direct AI API Integration - Makes API calls directly from the plugin
• No Backend Required - Everything runs within Obsidian

Note: The backend/ folder contains legacy Python code that is no longer required. The plugin now handles all AI processing internally.

Setup Instructions

Prerequisites

• Obsidian installed
• An AI API key from one of the supported providers:
  • OpenAI (GPT-4, GPT-3.5, etc.)
  • Anthropic (Claude 3 Opus, Claude 3 Sonnet, etc.)
  • Google Gemini (for example: gemini-2.5-pro, gemini-2.5-flash, gemini-1.5-pro)
  • OpenRouter (multi-provider gateway)

Installation

Option 1: From Obsidian Community Plugins (Recommended)

1. Open Obsidian Settings
2. Go to Community Plugins
3. Turn off Safe Mode (if enabled)
4. Click Browse and search for "Writing Dashboard"
5. Click Install
6. Enable the plugin

Option 2: Manual Installation

1. Download the latest release from GitHub Releases
2. Extract the obsidian-plugin folder
3. Copy it to your vault's .obsidian/plugins/ directory
4. Rename it to writing-dashboard
5. Restart Obsidian
6. Go to Settings → Community Plugins → Enable "Writing Dashboard"

Option 3: Install from GitHub URL

1. In Obsidian: Settings → Community Plugins → Browse
2. Click "..." (three dots) → "Install from URL"
3. Enter: https://github.com/JHarp199345/Gwriter
4. Obsidian will find the plugin in the obsidian-plugin folder

First-Run Setup

On first run, the plugin will automatically show a Setup Wizard to help you create the default vault structure. You can also manually trigger it:

1. Open Obsidian settings → Writing dashboard
2. Click "Run setup wizard" button
3. Or use Command Palette: "Run setup wizard"

The wizard lets you:

• Create default files: Book-Main.md, Book - Story Bible.md, Memory - Sliding Window.md
• Create the Characters/ folder with a template
• All files/folders are only created if they don't already exist (won't overwrite)

Configuration

1. Open Obsidian settings → Writing dashboard

2. Configure:

   • API Key: Your AI API key (OpenAI, Anthropic, or Gemini)
   • API Provider: Choose your provider (openai, anthropic, gemini, or openrouter)
   • Model: examples: gpt-4o, claude-3-5-sonnet, gemini-2.5-pro
   • Vault Path: Auto-detected, but can be overridden
   • Character Folder: Use the folder tree picker to select or create a folder (default: Characters)
   • Book main file: Use the file tree picker to select your active manuscript (supports files at root or in folders)
   • Story Bible Path: Use the file tree picker to select your story bible file
   • Generation Logs Folder: Optional folder for logging generation runs (excluded from retrieval)

   Memory & Performance (for local AI):

   • RAM Tier: Select your machine's RAM (8/16/24/32/64/128 GB) - asked on first run
   • Risk Profile: Safe (conservative) / Moderate / Aggressive
   • Context Window: Slider within your safe range
   • Verify Model: Query Ollama for actual model context limit

   Embedding Storage Mode:

   • Isolated: Private index (default)
   • Auto: Share with StoryBoard if installed and compatible
   • Manual: Specify custom path

   Note: The sliding window is automatically extracted from your book main file (last 20,000 words), so no separate sliding window path is needed.

Note: model names change frequently. The plugin does not hardcode model availability; it sends the model id you enter to your chosen provider.

Usage

Opening the Dashboard

• Click the book icon in the ribbon
• Or use Command Palette (Cmd+P / Ctrl+P): "Open dashboard"

Chapter Generation

1. Select Chapter Generate mode (bottom-right dropdown)
2. Write your Scene Summary / Directions
3. Review/edit Rewrite Instructions (defaults are auto-filled; includes a Reset button)
4. Set a target word range (Min → Max). For an exact target, set Min=Max.
5. Optional: click Preview prompt to see the exact prompt that will be sent.
6. Click Generate chapter
7. Review output and copy to clipboard

Notes:

• The dashboard shows word/character counters for Scene Summary, Rewrite Instructions, and Generated Output.
• The dashboard may warn you if the prompt is estimated to exceed your configured context window.

Micro Editing

1. Select Micro Edit mode
2. Paste the problematic passage in "Selected Text"
3. Enter your grievances/directives in "Grievances and directives"
4. Optional: click Preview prompt to see the exact prompt that will be sent.
5. Click Generate edit
6. The plugin automatically includes 500 words before and after your selection for context
7. Copy the refined alternative and paste into your manuscript

The dashboard displays your current book file path at the top of the main workspace for quick reference.

Examples you can paste into grievances/directives:

• Character A has no knowledge of Event X yet; remove any references that imply they do. Keep the scene outcome the same.
• Fix POV leaks: this is Character B POV only.
• Tone is too modern; make it tighter and more tense, matching surrounding chapters.
• Continuity: the injury is on the left arm, not the right.

Character Updates

1. Select Character Update mode
2. Paste character-relevant text in "Selected Text"
3. Optional: click Preview prompt to see the exact extraction prompt.
4. Click Update characters

Continuity check

1. Select Continuity check mode
2. Paste the draft to check (defaults to the last generated output when empty)
3. Optional: adjust focus toggles (Knowledge, Timeline, POV, Naming)
4. Optional: click Preview prompt
5. Click Run continuity check

Per-mode fields

Each mode keeps its own saved inputs (per vault). Switching modes does not overwrite other mode fields.

Bulk character backfill:

1. Select Character Update mode
2. Click Select file to process and choose the manuscript you want to scan
3. Click Process Entire Book
4. The plugin performs a 2-pass scan (roster + per-chapter extraction) and updates character notes

File Chunking

Manually chunk large files into smaller segments:

1. Select Character Update mode
2. Select text in your editor OR select a file to process
3. Click Chunk Selected File
4. The plugin creates a [FILENAME]-Chunked/ folder with numbered chunk files (e.g., Book-Main-CHUNK-001.md)
5. Each chunk is approximately 500 words with overlap for context

File Structure

Gwriter/ ├── backend/ # Legacy Python backend (no longer required) │ ├── main.py │ ├── requirements.txt │ └── services/ │ └── obsidian-plugin/ # The actual plugin ├── main.js # Built plugin (for installation) ├── main.ts # Source code ├── manifest.json # Plugin manifest ├── package.json ├── styles.css ├── README.md # Plugin-specific README ├── services/ │ ├── AIClient.ts # Direct AI API calls │ ├── PromptEngine.ts # Prompt building │ ├── ContextAggregator.ts # Vault file reading │ ├── CharacterExtractor.ts # Character parsing │ └── VaultService.ts # File operations └── ui/ ├── DashboardView.ts ├── DashboardComponent.tsx ├── VaultBrowser.tsx ├── EditorPanel.tsx ├── DirectorNotes.tsx ├── ModeSelector.tsx └── SettingsTab.ts

Character Notes Format

Character notes are stored in markdown with timestamped updates:

CharacterName

January 15, 2024 - 2:30 PM - Update

Voice Evidence: [quoted dialogue]

New Traits:

Relationships:

• OtherCharacter: [relationship change]

Arc Progression: [what changed]

Spoiler Notes: [sensitive information]

Retrieval (whole vault)

This plugin includes whole-vault retrieval to keep prompts relevant without manual curation. This is how the plugin maintains continuity across large manuscripts - instead of sending full book files, it retrieves relevant chunks from your entire vault.

Default: Local Retrieval (Hash + BM25)

By default, the plugin uses fast, local, deterministic retrieval:

• Hash-based embeddings: Lightweight hashed bag-of-words for semantic matching
• BM25: Lexical search engine scoring for keyword relevance
• Hybrid fusion: Combines both using reciprocal rank fusion (RRF) and diversity selection (MMR)
• No API keys required: Works entirely offline

Optional: External Embedding API (Hybrid)

For higher-quality semantic retrieval, you can optionally use an external embedding API:

• Supported providers: OpenAI, Cohere, Google Gemini
• Hybrid approach: External embeddings + local BM25, combined with RRF
• Default models:
  • OpenAI: text-embedding-3-small
  • Cohere: embed-english-v3.0
  • Google Gemini: gemini-embedding-001
• Batch embeddings: Google Gemini supports batch endpoint for efficiency
• Fallback: Automatically falls back to local retrieval if API fails

Optional: Smart Connections Context

If you have the Smart Connections plugin installed, you can optionally include its context:

• Via Bases: Reads Smart Connections Bases files automatically
• Via copied note: Reads a specific note containing Smart Connections context
• Best-effort: Never required - retrieval works perfectly without it

Configuration

• You can exclude non-story folders in Settings → Writing dashboard → Retrieval.
• You can use retrieval profiles to include only specific folders (for example: story-only vs research-heavy).
• Semantic retrieval builds a local index in the background (the dashboard shows index status).
• The plugin only sends the last 20,000 words of your active manuscript (sliding window) to the AI, relying on RAG retrieval for full continuity.

Vault structure (what each folder/file is for)

These paths are configurable in settings. The names below are recommended defaults.

• Characters/
  • One note per character (auto-updated by Character update).
• Book main file (your manuscript note)
  • The active manuscript you're currently writing.
  • Used to extract the sliding window (last 20,000 words) for immediate context.
  • Continuity with previous books/chapters comes from RAG retrieval, not full file loads.
• Story bible path
  • Canon rules, arcs, timelines, constraints.
  • When you save updated story bibles, they're automatically saved to Story bibles/ folder with timestamps.
  • The plugin auto-updates the active story bible path when you save new versions.
• Extractions path (optional)
  • Any distilled notes/summaries/constraints you want included in prompts.
• <Manuscript>-Chunked/ (created automatically)
  • Chunked copy of a manuscript note (used by the plugin's chunking and bulk workflows).
• Story bibles/ (created automatically when saving story bible updates)
  • Versioned story bible files (e.g., Story bible - 2024-12-20.md)
  • The plugin automatically uses the latest version when configured.

Publishing

You can export a professional EPUB directly from the plugin:

1. Open the command palette and run Export to epub.
2. Default mode: compile your Book main path split by H1 (#) chapter headings.
3. Optional: select TOC note mode if each chapter is a separate note.
4. Choose title/author/language, optional front matter, and an optional license template.
5. Output defaults to Exports/ in your vault.

Typography:

• Default styling targets Literata.
• To guarantee the font, enable Embed custom fonts and select your font files.

Font licensing note: only embed fonts you have the rights to redistribute.

Privacy notes

Your text is sent only to the AI provider you configured when you click generate/extraction buttons. No backend server is required for this plugin.

Troubleshooting

API Key Issues

• Ensure your API key is correctly entered in settings
• Verify the API key is valid and has credits/quota
• Check that the model name matches your provider:
  • OpenAI: gpt-4o, gpt-4o-mini, etc.
  • Anthropic: claude-3-5-sonnet, claude-3-5-haiku, etc.
  • Gemini: gemini-2.5-pro, gemini-2.5-flash, etc.
  • OpenRouter: provider-prefixed model ids like openai/gpt-4o or google/gemini-2.5-pro

API Errors

• Verify your API key is correct
• Check your API provider account for rate limits
• Ensure the model name is correct for your provider
• Check your internet connection

File Not Found Errors

• Verify file paths in settings match your vault structure
• Ensure files exist at the specified paths
• Check vault path is correct
• Make sure file names match exactly (case-sensitive on Mac/Linux)

Embedding/Indexing Issues

• Check Ollama Status - Ensure Ollama is running (ollama serve) and the embedding model (e.g., nomic-embed-text) is pulled.
• BM25 retrieval still works - Even if embeddings fail, the plugin uses BM25 (text-based) retrieval which works reliably.
• Check index status - Go to Settings → Writing dashboard → Retrieval to see indexing status.
• Manual Management - Use the Re-index Vault or Clear Index buttons in settings to fix corrupted states.
• Run stress test - Use the Developer Tools stress test (Settings → Writing dashboard → Developer Tools) to get detailed diagnostics.

System Freezes / Performance Issues

• Check RAM Tier - Ensure your RAM tier is set correctly in Settings → Memory & Performance.
• Model Too Large - If generation causes freezes, the model may be too large for your RAM. The plugin blocks known-dangerous combinations (e.g., 70B on 16GB RAM).
• Use Safe Profile - Switch from Aggressive to Safe risk profile for more conservative context limits.
• Lower Context Slider - Move the context window slider lower (toward 50% of max) for more headroom.
• Verify Model Context - Click "Verify" in Memory & Performance to query the model's actual limit from Ollama.
• Close Other Apps - Large language models need RAM for both weights and KV cache. Close memory-heavy applications.

Keyboard Not Working in Text Areas

• This was fixed in v0.1.0. If you experience issues, try:
  • Clicking in the text area again
  • Restarting Obsidian
  • Updating to the latest version

Developer Tools

The plugin includes a comprehensive stress test for diagnostics:

1. Go to Settings → Writing dashboard → Developer Tools
2. Click "Start Stress Test"
3. The test will:
   • Create temporary test files
   • Test all plugin operations (indexing, retrieval, AI calls, character extraction)
   • Generate a detailed log with error diagnostics
   • Clean up all temporary files automatically
4. The log is saved as a note in your vault: Stress Test Log - [timestamp].md

This is especially useful for diagnosing embedding/indexing issues.

Development

Plugin Development

cd obsidian-plugin

Install dependencies

npm install

Watch mode (auto-rebuilds on changes)

npm run dev

Production build

npm run build

Building for Release

cd obsidian-plugin
npm run build
# main.js will be created/updated

Contributing

Contributions are welcome! Please feel free to:

• Open issues for bugs or feature requests
• Submit pull requests
• Share feedback and suggestions

License

MIT License - Free to use and modify

Support

For issues, feature requests, or questions:

• Open an issue on GitHub
• Check the plugin README for detailed usage

---

Note: The Python backend in the backend/ folder is legacy code and is no longer required. The plugin is now fully self-contained and makes AI API calls directly from within Obsidian.