AI features

YarnDraft offers several AI assistant features. Each needs Settings → AI tab: API key or local model (Ollama, OpenAI-compatible).

Setup

1. Cloud profiles: OpenAI, Anthropic, Gemini — API key in the system keychain.
2. Local LLM: Ollama URL, or LM Studio / other OpenAI-compatible endpoint.
3. Feature assignment: which model powers which tool (chat, copilot, flow build, etc.).

Floating AI chat

• Flow chart bottom-left — bubble icon.
• Ask about the project and narrative; sees the current canvas.
• Pin: modifier+left-click on a card (configurable in Settings) — card context is included.
• External MCP tools can be invoked with approval (if configured).

Chat history

Every conversation is saved automatically as you chat — nothing is lost when you close the panel, switch views, or restart the app:

• The clock icon in the chat header opens the history list: past conversations, newest first, with a title (taken from your first message), timestamp, message count, and the project they happened in.
• Click a past conversation to reopen it and keep chatting where you left off.
• The message-plus icon starts a new chat — the current conversation is already saved, so this just clears the panel for a fresh topic.
• Hover a history entry to reveal a trash icon and delete it permanently.
• History is stored per machine (browser/app local storage), not inside the project file — it isn't shared with collaborators and isn't included when you export or send the project to someone else. It's shared across all projects you open on this machine, up to the 50 most recent conversations.

Recent prompts

Every one-shot AI prompt field — AI flow build, AI branch, the Dialogue copilot's custom instruction, and the Entity generator — has a small clock icon next to it. Click it to see your last 20 submitted prompts for that field (newest first) and reuse one with a click; hover an entry to delete it. This is separate from the floating chat's conversation history above: it just remembers the text you typed, not a back-and-forth conversation. Same storage model as chat history — per machine, not in the project file.

AI flow build

• Toolbar: AI build (not on root canvas — open a nested flow first).
• Natural-language description → plan preview → Apply to canvas.
• @ mention: entity, variable, card, document.
• AI build only adds new cards — it never edits or deletes existing cards, and it never rewires existing edges.
• The prompt box has a recent prompts clock icon — see Recent prompts.

Continuing / extending an existing flow

AI build can extend a flow you already built (by AI or by hand) by anchoring the new cards to a spot you pick:

• Right-click a single card → Continue with AI from here — pins that card as the anchor and opens AI build. The new cards it proposes will connect to it.
• You can also pin one or more cards manually (modifier+left-click, same shortcut as the floating chat) before opening AI build.
• Whenever one or more cards are pinned, the build dialog shows an "Anchored to" panel listing them, with a small × to unpin a card before generating.

Conversations always land on a nested canvas

When a prompt calls for a back-and-forth exchange between characters, AI build writes it as a chain of one-line dialogue cards, same as it always did. The app then automatically groups any chain of 2 or more connected dialogue cards into a single scene card, moving the actual lines onto a fresh nested canvas underneath it:

• The main canvas only shows one dialogue card for the whole scene (plus your quest/logic cards) — enter it to see and edit the individual lines.
• Anything the conversation connects to on the outside (an inventory reward, a task, another card) stays wired correctly: the scene card's outgoing connection is routed through an output pin inside the nested canvas, so applying the plan still produces a fully connected flow.
• A single standalone dialogue line (not chained to another dialogue card) is left on the main canvas as-is — nesting a lone line wouldn't add clarity.
• This grouping is automatic and always on for AI-generated cards; it does not touch dialogue cards you already had on the canvas before running AI build.
• The plan review dialog shows the nested conversation's lines indented under the scene card — you can check the actual dialogue text before clicking Apply, and use Edit request / Regenerate plan if a line reads more like a title than something a character actually says. The app also flags any dialogue card left with no spoken text as a warning in that same review step.

AI branch

• Select exactly 2 cards → AI branch — generate intermediate steps that connect the two.
• Unlike a free-text AI build request, this guarantees the new cards attach to exactly the two cards you selected — the AI can't decide on its own to wire the new content to a different, earlier card in the flow.
• If the two selected cards already had a direct connection, applying the plan removes that direct edge, so the result is a real insertion between them instead of a parallel branch running alongside it.
• Use this whenever you need to insert content at a precise point in an existing chain (e.g. "add a short scene between card A and card B") — describing the insertion point in a plain AI build prompt leaves the exact wiring up to the AI's own judgment.

Dialogue copilot

• Dialogue card toolbar → wand icon.
• Generate, shorten, refine, tone, translate.
• The custom instruction field has a recent prompts clock icon — see Recent prompts.

Entity generator

• Entities view → Generate with AI — fill fields from a description.
• The description field has a recent prompts clock icon — see Recent prompts.

Simulated player — AI summary

• Optional narrative report of simulation results (separate model assignment).

Tool approval

When AI calls an MCP tool, an approval prompt appears (project may be modified).

Privacy

API keys are not stored in project files — only on your machine.