Home
--- templateEngineOverride: njk --- Meridian's Mystery Mill

THE MANUAL

Return to Factory

Writer's Studio Wiki

The ultimate documentation for Writer's Studio - A distraction-free, hierarchical writing environment

Overview

Writer's Studio is not just a note-taking app - it's a complete writing studio environment designed specifically for authors, journalists, and content creators who need deep focus and professional-grade tools. Unlike traditional note-taking applications that encourage fragmented ideas, Writer's Studio focuses on structured document management, seamless export workflows, and features dedicated to the writing process.

What Makes Writer's Studio Unique

  • Anti-Note-Taking Philosophy: Designed for long-form writing, not fragmented notes
  • Hierarchical Structure: Infinite nested folders and documents
  • Professional Export: EPUB, PDF, and Markdown generation
  • Story Wizard AI: Advanced narrative engine with RAG-powered consistency using ChromaDB
  • Multi-Agent MCP System: Modular AI system for web browsing, file operations, and more
  • Audio Integration: Built-in audio playback, transcription, and fast AI voice (Kokoro)
  • Visual Storytelling: Cover images, images, and media embedding

Key Features

📚 Binder & Organization

Hierarchical Structure

Organize your writing into an unlimited tree of Folders and Text documents. Create project structures that match your creative process with infinite nesting depth.

Drag & Drop Reordering

Easily restructure your project by dragging items in the Binder. Move entire sections, reorder chapters, or reorganize your entire project in seconds.

Document Duplication

Quickly clone existing documents or entire folder structures to experiment with different versions without risking your original work.

Search & Replace

Global search across your entire project with batch replace functionality. Instantly find and update content across all documents.

Custom Icons

Personalize your workspace by assigning unique icons to folders and documents. Create visual cues that help you navigate complex projects.

✍️ Writing Experience

Distraction-Free Editor

Clean, minimalist interface with no clutter. Focus on what matters - your words.

Focus Mode

Highlight only the current paragraph or section. Eliminate distractions by hiding everything else.

Teleprompter Mode

Scrolling text display with adjustable speed for reading drafts or presenting work.

Inspector Panel

Manage metadata alongside your writing:

  • Status: Draft, Revised, Final
  • Synopsis: Brief overview of the document
  • Research Notes: Keep reference materials linked
  • Cover Images: Upload images for EPUB covers
  • Audio Files: Upload audio for blog posts or podcasts

History Manager

Comprehensive Undo/Redo stack protects your work from accidental changes.

Auto-Save

Every change is automatically saved to the local SQLite database. No more lost work.

Dark Mode

Toggle between light and dark themes for comfortable writing at any time of day.

HTML Source Toggle

View and edit the raw HTML source of your documents directly in the editor (via the ℹ️ icon).

Markdown to HTML Conversion

Instantly transform Markdown text into clean, structured HTML (via the </> icon). Supports tables, lists, blockquotes, code blocks, and complex inline formatting.

🔄 Import & Export

Scrivener Import

Import entire .scriv projects (via .scrivx file). Automatically parses your Binder structure, synopses, and notes from Scrivener.

EPUB Support

Export: Generate production-ready EPUB files directly from your project tree
Open/Reader: Built-in EPUB reader to view external files
Cover Images: Uses folder cover images for EPUB covers

Project Backup

Export your entire project as JSON backup, or export as a single Markdown file for sharing.

Audio Integration

Upload MP3 and WAV files directly to documents. Audio is automatically managed during publishing and embedded via a custom player.

Automated Post Importer

Import Markdown blog posts directly into the Studio with automatic metadata mapping (YAML front-matter), asset ingestion (Base64 embedding), and template stripping.

🧙‍♂️ Story Wizard & Prose Generator

The Story Wizard is an AI-powered narrative engine that transforms high-level outlines into immersive prose using a two-stage generation process:

  • Beat Architect: Breaks a scene synopsis into 4 distinct, logical narrative beats.
  • Prose Expansion: Expands each beat into ~300+ words of immersive narrative.
  • Story Bible (RAG): Uses ChromaDB to maintain strict consistency with character profiles and style guides.
  • Humanization Protocol: Enforces constraints to avoid "AI-sounding" text and maintain specific pacing styles.

Installation & Setup

Prerequisites

  • Node.js (LTS recommended)
  • npm
  • Python 3.10+ (for MCP agents)
  • Conda (Anaconda or Miniconda - optional but recommended)

Quick Start

  1. Install Dependencies
    cd writer-studio
    npm install
  2. Initialize Database
    node init_db.js
  3. Start the Application
    ./start_app.sh
  4. Access the App
    Local: http://localhost:3000
    Remote: Secure Tailscale URL provided by startup script

Technology Stack

Component Technology
Backend Node.js + Express
Database SQLite3 (writing_app.db)
Frontend Vanilla JavaScript (ES6 Modules)
Styling Vanilla CSS with Dark Mode
AI Memory ChromaDB
AI Voice FastKoko (Kokoro-82M)
AI Chat OpenAI
Workflow n8n Automation
Remote Access Tailscale Proxy
Browsing Playwright
Protocol Model Context Protocol (MCP)
Static Site Eleventy (11ty)

Key Files

File Description
server.js Main Express server handling API routes, database operations, and EPUB generation
db.js SQLite database connection and helper methods
public/js/writer_v2.js Core frontend logic: state management, API calls, event handling
public/index.html Main application entry point
mcp_file_server.py Sandboxed file operations server
manager.py Central orchestrator for multi-agent system
transcriber.py Audio-to-text using MLX-Whisper

Multi-Agent MCP System

Writer's Studio includes a sophisticated multi-agent AI system built on the Model Context Protocol (MCP).

manager.py
(Orchestrator)
central brain orchestrates tasks and connects to all sub-agents
├──► model-agent.py
├──► webagent_mpc.py
├──► agent-flow.py
├──► mcp_file_server.py
├──► eleventy_mcp.py
└──► transcriber.py
model-agent
Model registry
webagent
Browser automation, tests
agent-flow
n8n workflow triggers
file_server
File operations
eleventy_mcp
Site management
transcriber
Audio transcription

Components

Component File Role
Manager manager.py Central brain orchestrates tasks and connects to all sub-agents
Model Agent model-agent.py Manages model registry, API keys, and context windows
WebAgent webagent_mpc.py Browser automation with Playwright, test runner, YouTube subtitles
Agent Flow agent-flow.py Triggers external n8n workflows
File Server mcp_file_server.py Safe filesystem access within jail directory
Transcriber transcriber.py Audio-to-text using MLX-Whisper

Available Tools

Browser Automation

browser_navigate, browser_click, browser_type
browser_screenshot, browser_run_code
browser_console_messages

Test Automation

discover_tests, run_playwright_test, run_test_by_name
smart_heal_test - Auto-fix failing tests
smart_generate_test - Generate tests from descriptions
smart_plan_test - Plan comprehensive test suites

File Operations (Sandboxed)

fs_list_directory, fs_read_file, fs_write_file
fs_delete_file, fs_move_file, fs_find_file

Media & Content

transcribe_audio - Local audio transcription
get_youtube_subtitles - Download YouTube subtitles
fs_search_transcripts - Search through transcripts

Eleventy / Site

create_post, list_all_posts, remove_post
publish_site - Trigger Eleventy build

Writer Tools

read_active_document, edit_active_document, open_document
prose_stats - Analyze word count, readability, and banned words
restart_speech - Restart the remote Kokoro speech engine
restart_server - Restart the entire application suite (detached process)
generate_qr_code - Generate QR codes for sharing links

AI Models

Dynamic model switching with runtime model propagation to all sub-agents.
Support for Ollama and OpenAI-compatible APIs.

API Reference

Document Management

Method Endpoint Description
GET /api/documents Fetch all documents
GET /api/documents/:id Get single document
POST /api/documents Create new document
PUT /api/documents/:id Update document
DELETE /api/documents/:id Delete document
POST /api/documents/batch-delete Delete multiple documents
POST /api/documents/batch-stats Calculate word counts
GET /api/documents/search?q=term Search documents
POST /api/documents/replace Search and replace

Import, Export & Backup

Method Endpoint Description
GET /api/export Export project as JSON backup
POST /api/restore Restore from JSON backup
GET /api/export/epub?rootId=id Generate EPUB file
POST /api/documents/import Import parsed data

Story Wizard & AI

Method Endpoint Description
POST /api/wizard/run Start AI generation (streamed)
POST /api/wizard/save Save generated story
GET /api/wizard/files List wizard templates/stories
DELETE /api/wizard/files/:filename Delete story file
POST /api/wizard/generate Generate story concept
GET /api/config/models List available AI models
ALL /api/manager/* Proxy to MCP Manager Agent

System Configuration

Method Endpoint Description
GET /api/config Get server configuration

🧪 Plugin API Testing

The Writer's Studio includes a robust Playwright-based test suite specifically designed to test the inter-agent JSON-RPC communication bridge (the plugin_host.py MCP Server) without causing unintended side effects (like actually moving emails or editing live documents).

The Test Suite (transcripts/tests/plugin_api_test.spec.ts)

This test suite performs a realistic, integration-level API test by directly spawning the plugin_host.py backend and communicating with it via standard input/output (STDIO), exactly as the AI Manager Agent does in production.

It tests all 22+ plugins, including:

  • Email Actions: fetch_email, read_email, flag_spam, move_email
  • Document Actions: open_document, edit_active_document
  • Build Automations: build_jeff, make_epub_jeff, syncronize_project

How It Works (The MOCK_PLUGINS Architecture)

To make the tests 100% realistic while remaining completely safe, the system uses a bypass flag architecture:

  1. Spawning the Server: The Playwright beforeAll hook uses Node's child_process.spawn to launch python3 plugin_host.py, injecting a special environment variable: MOCK_PLUGINS=true.
  2. Schema Validation: When the test sends a JSON-RPC request, the plugin_host fully processes the request. It parses the plugin's python file, extracts the docstring schema, and maps the JSON arguments to positional command-line arguments.
  3. Safe Interception: Instead of using subprocess.run to execute the underlying code (which would modify the user's system), plugin_host.py intercepts the call immediately prior to execution because it detects the MOCK_PLUGINS=true flag.
  4. Mock Response: It safely returns a standardized [MOCK_RESPONSE] string back through the STDIO pipe.

Why This Matters

This approach ensures we are testing the actual server code and argument parsing logic rather than relying on tautological (self-fulfilling) mocks. If a plugin's argument schema changes or if the JSON-RPC implementation breaks, this test suite will fail, providing high confidence in the stability of the Multi-Agent API without risking user data.

Examples

Creating a New Project

  1. Start Writer's Studio
  2. Create a root Folder for your project
  3. Add Text documents as chapters or sections
  4. Use the Binder to organize your structure
  5. Add metadata via the Inspector panel
  6. Export to EPUB when ready

Using the Story Wizard

  1. Click the 🧙‍♂️ icon to open the Wizard panel
  2. Select your AI model (local or cloud)
  3. Define genre, tone, and structural directives
  4. Configure your character profiles
  5. Set up your chapter synopses
  6. Click Run Wizard to generate content
  7. Generated content appears in a new folder

Browser Automation with WebAgent

In interactive mode with the Manager:

> browser_navigate https://example.com
> browser_screenshot
> browser_click e15
> browser_type "search query" e20

Audio Transcription

  1. Place audio file in transcripts/ directory
  2. In Manager interactive mode:
> transcribe audio document myfile.mp3

The system will automatically locate and transcribe the file.

Deployment Workflow

  1. Sync files:
    ./resync_project.sh
  2. SSH to server:
    ssh [email protected]
  3. Update dependencies:
    cd ~/writer-studio
    npm install

Support & Contact

For issues or questions, contact: [email protected] (reference error IDs if applicable)