Writing Guide

AI Assist Overview

margin uses a dual-agent architecture to generate context-aware writing assistance:

  Your Request
       │
       ▼
  ┌─────────────────────┐
  │   PLANNER AGENT     │  <-- Reads manifests and reference files
  │  (Context Classifier)│      Decides what context is needed
  └─────────────────────┘
       │ Resolves relevant files
       ▼
  ┌─────────────────────┐
  │   WRITER AGENT      │  <-- Receives instruction + context
  │  (Prose Generator)  │      Produces the final output
  └─────────────────────┘
       │
       ▼
    Your Document

1. The Planner Agent looks at your workspace -- it reads manifest files (folder indexes), checks which characters, styles, and lore are relevant to your request, and assembles the right context.

2. The Writer Agent receives only the instruction, your selected text (if any), and the context prepared by the Planner. It streams the result directly into the editor.

This separation means the AI doesn't need to read every file in your workspace for every request -- the Planner filters and prioritizes context efficiently.

For a detailed walkthrough of using Edit and Chat modes, see AI Assist.

Workspace File Structure

The code auto-discovers folders and files in your workspace. Any top-level subfolder is treated as a content category. The AI reads files from these folders to ground its responses.

Expected Structure

workspace/
├── chapters/          Your manuscript content files
│   ├── CHAPTERS.md    Manifest: lists all chapter files
│   ├── chapter-1.md
│   └── chapter-2.md
├── characters/        Character profile files
│   ├── CHARACTERS.md  Manifest: lists all character files
│   ├── elara.md
│   └── kaelen.md
├── styles/            Tone/style preset files
│   ├── STYLES.md      Manifest: lists all style files
│   ├── cinematic.md
│   └── general.md
└── lore/              World-building notes (indexed automatically)
    ├── world-map.md
    └── factions.md

Any subfolder you add at the top level is automatically picked up. The name you give the folder becomes the category the Planner uses when deciding what context is relevant.

Manifest Files

Manifest files are markdown files with ALL-CAPS names that serve as indexes for folders. They tell the Planner what's available at a glance.

workspace/characters/
├── CHARACTERS.md      <-- Manifest
├── elara_vance.md
└── kaelen_rhys.md

Each manifest is a markdown file that lists the files in its folder with a brief description. For example, CHARACTERS.md:

- elara_vance.md -- Protagonist, volatile artist
- kaelen_rhys.md -- Frenemy, sarcastic and grounded
- lena_hayes.md -- Dr. Lena Hayes, calm scientist

Manifests are maintained by hand -- when you add or remove files, update the manifest to keep it in sync with the folder contents.

How the Planner Uses Manifests

When you send a request, the Planner reads all manifest files in your workspace to understand the available context. If your request mentions a character, it checks the characters manifest, finds the relevant profile, and includes it in the context sent to the Writer.

This means you don't need to manually specify which files to include -- the Planner handles it automatically based on your content.

Character Profiles

Create markdown files inside a characters/ folder in your workspace. Each file describes a character — the entire file content is sent to the AI when the profile is referenced, so structure it however makes the information clearest for both you and the model:

# Elara Vance
- **Archetype**: Determined scholar, quiet, cautious.
- **Dialogue**: Terse, direct, uses academic terms under stress.
- **Physical**: Silver hair, gray robes, carries a leather-bound logbook.

When you mention a character name in your request, the Planner automatically finds and includes their profile as context for the Writer.

Style Files

Writing style guidelines can be stored as markdown files inside a styles/ folder in your workspace. Each file is plain markdown with whatever structure works for you:

## Writer Guidelines
- Show, don't tell. Use sensory details.
- Keep descriptions heavy and atmospheric.
- Dialogue should feel natural, not expository.

Add a STYLES.md manifest in the folder to describe each file:

- cinematic -- Full cinematic scene -- narration sets the atmosphere, dialogue drives the conflict

Style files are available to the Planner as reference material, just like characters or lore. Pin them in Settings > Context if you want them included by default.

Custom Folders

Any folder you add at the top level of your workspace is automatically indexed by the Planner and included when relevant. The folder name becomes the category the Planner uses when deciding what context to reference.

Examples: lore/ (world-building notes, maps, timelines, magic systems), settings/ (locations, factions), or any other category you create.

Custom folders don't need manifests -- the Planner auto-indexes any folder contents.

Chapters

Your chapter or manuscript files go in a folder of your choice (commonly chapters/). The folder name is arbitrary — what matters is the CHAPTERS.md manifest that tells the Planner these are manuscript files.

Links stay editable: clicking a link places the cursor so you can edit it, while ⌘/Ctrl+Click follows it in a new tab.

Images

Chapters can include images — maps, mood boards, character sketches, scene references. Paste an image or an image URL, drag and drop a file into the editor, or type /image and pick Upload image from the menu to choose a file from your device — margin files it into your workspace's assets/ folder, no separate upload step, and no upload size limit. The / menu only appears at the start of an empty line, and it filters as you type — prefix matching across names and keywords finds the action without scrolling.

Pasted image URLs stay in your document as text, and margin saves a local copy into assets/ for the actual image — your document never depends on the remote server afterwards.

Images in margin are Markdown with a file behind it:

![A cat](assets/cat.png "A cute cat")

Part	Meaning
![...]	image description / alt text
assets/cat.png	workspace-relative image file
"..."	optional visible caption

Image files live in your workspace's assets/ folder and travel with it — into git, offline, anywhere.

Interact with an image by selecting it:

• Resize by dragging the edge dots; the size is remembered with the document. Hold Shift while dragging a corner dot to keep the original aspect ratio.
• Align left, center, or right from the small pill toolbar.
• Caption it with the Add a caption… line underneath the image — it appears when the image is selected. Captions travel with the image.
• Edit the source (![alt](assets/... "caption")) directly if you prefer writing Markdown by hand.

Underneath, an image is just Markdown text, so it behaves like everything else you write: it survives copy/paste, undo, and git, and the AI reads the same reference you see.

If an image breaks (renamed, moved, or deleted file), margin shows a placeholder and leaves your text untouched — see Debugging for common fixes.

AI image generation

Besides uploading, margin can imagine images from words. There are three operations and nothing else:

• Upload — file or URL into assets/, as above.
• Imagine — a prompt (plus an optional style) into a new image under assets/generated/, inserted at your cursor.
• Imagine again — an existing image plus your change description into a new file under assets/generated/; only the reference changes, so undo restores the previous image and old versions stay on disk.

Entry points:

• Type / and pick Imagine for free-form generation.
• Select text and click Imagine in the bubble menu — the selection becomes the starting prompt (your text is never deleted). Expand the bar for a larger prompt and the style picker.
• Select an image and click the pencil (✎) in its pill — the current image becomes the reference. Describe the change ("make the suit blue") and submit; empty never submits.

Providers live in Settings → Images. Margin supports OpenAI-compatible endpoints, Stability, FAL, Google Gemini, and local ComfyUI — the editor never cares which one produced the image. Use Test provider after configuring. For ComfyUI, import your own API-format workflows into two slots under ComfyUI Workflows: a text-to-image workflow for Imagine and an image edit workflow (with a LoadImage input) for Imagine again. Each slot also accepts an optional seed mapping so every run gets a fresh random seed; without one, the workflow's saved seed is reused verbatim. Your workflows are never modified — margin overlays prompt, reference, and seed onto a per-run copy.

Styles append extra direction to your prompt for the style you pick. The shipped styles (Cinematic, Illustration) can be edited, hidden (Restore brings them back), or reset to their shipped text; add your own below the list. None can never be deleted and always means no suffix.

Every run is recorded under History → Images in the assistant sidebar (newest first, refetch on open): thumbnail, prompt, timestamp, seed, and provider. Click any entry for the full details — input and output images, submitted prompt, paths — plus Copy prompt and Open-folder actions. Delete individual entries with the hover × button, like chat sessions. Generation history lives in your workspace's outputs/image_logs/ folder, per workspace like everything else.