image icon) | Opens the **Project Images** dialog to manage all visual assets for this project. (See [Project Images](06_project_images.md).) |
+| **Images** ( image icon) | Opens the **Project Images** dialog to manage all visual assets for this project. (See [Project Images](09_project_images.md).) |
| **Settings** (
) | Opens the Settings dialog (same as clicking the logo). |
-| **Appearance** (
Type icon) | Opens the Appearance popup to adjust the visual theme, font size, and line width. (See [Appearance and Display](08_appearance_and_display.md).) |
-| **Debug Logs** (bug icon) | Opens the LLM Debug Logs overlay — a developer-focused view of all AI requests and responses. (See [Appearance and Display](08_appearance_and_display.md#debug-logs).) |
+| **Appearance** ( Type icon) | Opens the Appearance popup to adjust the visual theme, font size, and line width. (See [Appearance and Display](10_appearance_and_display.md).) |
+| **Debug Logs** (bug icon) | Opens the LLM Debug Logs overlay — a developer-focused view of all AI requests and responses. (See [Appearance and Display](10_appearance_and_display.md#debug-logs).) |
| **Hide / AI** (panel icon) | Toggles the right Chat Assistant panel open or closed. The current label flips between **Hide** (chevron-right) and **AI** (chevron-left) depending on the panel state. |
---
diff --git a/docs/user_manual/02_projects_and_settings.md b/docs/user_manual/02_projects_and_settings.md
index bff17ad4..8471e50a 100644
--- a/docs/user_manual/02_projects_and_settings.md
+++ b/docs/user_manual/02_projects_and_settings.md
@@ -27,11 +27,11 @@ The Projects tab lists every project stored on this machine and lets you create,
Three buttons sit above the project list:
-| Button | Icon | Action |
-| --------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Refresh** | 
↺ | Rescans the projects folder from disk — useful if you have added or removed project folders manually. |
-| **Import** | ↑ Upload | Opens a file picker that accepts `.zip` files. AugmentedQuill will unpack the archive and add the project to your list. This is the matching action to the Export button on each project row. |
-| **New Project** | 
| Opens the **Create Project** dialog (see below). |
+| Button | Icon | Action |
+| --------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Refresh** | 
| Rescans the projects folder from disk — useful if you have added or removed project folders manually. |
+| **Import** | ↑ Upload | Opens a file picker that accepts `.zip` files. AugmentedQuill will unpack the archive and add the project to your list. This is the matching action to the Export button on each project row. |
+| **New Project** | | Opens the **Create Project** dialog (see below). |
### Project Cards
@@ -305,10 +305,6 @@ Click **Save & Close** at the bottom of the Settings dialog to write your machin
---
-Next up: Explore [The Writing Interface](03_writing_interface.md).
-
----
-
## Multiple Languages (GUI vs Project)
AugmentedQuill supports distinct languages for its interface (GUI) and your story content.
@@ -325,3 +321,7 @@ The story language dictates the spellchecking and grammar tools used by your cho
1. When creating a **New Project**, select the language in the project dialog.
2. OR, open the **Project Settings** (by clicking your story title in the corner or typing in the Project tab) and change the language dropdown.
3. Chat fields, Editors, and Images will automatically adapt their spellchecker to the project's saved language.
+
+---
+
+Next up: Explore [The Writing Interface](03_writing_interface.md).
diff --git a/docs/user_manual/03_writing_interface.md b/docs/user_manual/03_writing_interface.md
index e0f207a4..b87bd98b 100644
--- a/docs/user_manual/03_writing_interface.md
+++ b/docs/user_manual/03_writing_interface.md
@@ -28,7 +28,7 @@ You can switch modes at any time without losing data; the underlying markdown fi
### Dropping Images Into the Editor
-Drag an image file (PNG, JPEG, GIF, WEBP) and drop it onto the editor paper area. A highlighted drop zone appears while the image is being dragged over. On release, the image uploads to the server and an inline markdown image tag (``) is inserted at the current cursor position. You can manage all project images from the **Project Images** dialog (see [Project Images](06_project_images.md)).
+Drag an image file (PNG, JPEG, GIF, WEBP) and drop it onto the editor paper area. A highlighted drop zone appears while the image is being dragged over. On release, the image uploads to the server and an inline markdown image tag (``) is inserted at the current cursor position. You can manage all project images from the **Project Images** dialog (see [Project Images](09_project_images.md)).
---
@@ -225,7 +225,7 @@ These controls update the planning layer around a chapter rather than the prose
- The suggestion pane always shows the last set of continuations, so you can keep requesting more or hit `Dismiss` once you are satisfied.
- Even when AI actions are running, you can keep typing because the UI disables only the relevant button and leaves the rest of the editor responsive.
- Switch between Raw, MD, and Visual modes freely — the underlying file is the same markdown source regardless of which view you use.
-- Press **Ctrl+F** (or **Cmd+F** on macOS) at any time — or click the **
Search** icon in the top-right header — to open the project-wide **Search and Replace** dialog. See [Search and Replace](12_search_and_replace.md) for the full guide.
+- Press **Ctrl+F** (or **Cmd+F** on macOS) at any time — or click the ** Search** icon in the top-right header — to open the project-wide **Search and Replace** dialog. See [Search and Replace](08_search_and_replace.md) for the full guide.
---
diff --git a/docs/user_manual/04_chapters_and_books.md b/docs/user_manual/04_chapters_and_books.md
index 51bbe736..212720e3 100644
--- a/docs/user_manual/04_chapters_and_books.md
+++ b/docs/user_manual/04_chapters_and_books.md
@@ -57,7 +57,7 @@ The Metadata Editor is a full-screen or sidebar panel that opens whenever you cl
- The text area holds the public description that appears in the sidebar card and is sent to every AI call that involves this chapter or story.
- When the summary is empty, an **AI Write** button (
) asks the 
**EDITING** model to draft a summary from the chapter content.
-- Once a summary exists, the button becomes **AI Update** () which updates the existing text, and an adjacent **AI Rewrite** (
) button regenerates it from scratch — useful when the story direction has changed.
+- Once a summary exists, the button becomes **AI Update** () which updates the existing text, and an adjacent **AI Rewrite** () button regenerates it from scratch — useful when the story direction has changed.
**Notes tab:**
diff --git a/docs/user_manual/05_sourcebook.md b/docs/user_manual/05_sourcebook.md
index 574b770e..7233f864 100644
--- a/docs/user_manual/05_sourcebook.md
+++ b/docs/user_manual/05_sourcebook.md
@@ -93,7 +93,7 @@ The Image Picker is a sub-modal that appears when you click **Manage Images** in
- A count below the grid shows how many images are currently selected.
- Click **Done** (✓) to close the picker and apply the selection to the entry.
-Images shown here are managed in the [Project Images](06_project_images.md) dialog. You can upload new images there and they will appear in this picker immediately.
+Images shown here are managed in the [Project Images](09_project_images.md) dialog. You can upload new images there and they will appear in this picker immediately.
---
@@ -118,4 +118,4 @@ Mouse-over tooltips on the **Auto** control, spinner, and disabled checkboxes ex
---
-Next up: Manage your project's visual assets in [Project Images](06_project_images.md).
+Next up: Apply everything you've learned in the [Tutorial: Writing Your First Story](06_tutorial_first_story.md).
diff --git a/docs/user_manual/06_project_images.md b/docs/user_manual/06_project_images.md
index 0b1ce0f9..6dc34bb8 100644
--- a/docs/user_manual/06_project_images.md
+++ b/docs/user_manual/06_project_images.md
@@ -94,4 +94,4 @@ Paste the copied prompt into your preferred image generation tool (Stable Diffus
---
-Next up: Discover your AI writing partner in [The AI Chat Assistant](07_ai_chat_assistant.md).
+Next up: Customize the look and feel in [Appearance and Display](08_appearance_and_display.md).
diff --git a/docs/user_manual/06_tutorial_first_story.md b/docs/user_manual/06_tutorial_first_story.md
new file mode 100644
index 00000000..ed314074
--- /dev/null
+++ b/docs/user_manual/06_tutorial_first_story.md
@@ -0,0 +1,145 @@
+# Tutorial: Writing Your First Story
+
+Welcome to the tutorial! In this guide, we won't just look at which buttons to click; we'll walk through the actual process of crafting a compelling story using AugmentedQuill. We will also show you how to perform each step manually or by using the AI Chat Assistant.
+
+Before you begin drafting prose, keep the default rhythm in mind: notes first, then title and style tags, then the story summary, then Sourcebook work, then chapter notes and conflicts, and only then full prose generation. You can always circle back and refine earlier metadata when the story evolves.
+
+## Step 1: The Spark of an Idea
+
+Every story starts with a concept. Before you write a single word of prose, you need to know what your story is about.
+
+**Manually:**
+
+1. Open AugmentedQuill and click the **Settings** icon in the top navigation bar.
+2. In the **Projects** tab, click **New Project**. Name it "The Lost Heirloom".
+3. Close the Settings dialog. In the left sidebar, find the **Story Metadata** section.
+
+**Using Chat:**
+
+1. Open the **[AI Chat Assistant](07_ai_chat_assistant.md)** in the right sidebar.
+2. Type: _"Create a new project called 'The Lost Heirloom'."_
+
+### Writing Advice: The Core Conflict
+
+A story without conflict is just a sequence of events. Conflict is the engine that drives the narrative forward. It can be internal (a character battling their own fears) or external (a character battling a villain or nature).
+
+**Manually:**
+In the **Story Metadata** section, write a brief summary that highlights the conflict.
+_Example:_ "Elara, a cautious librarian, discovers a map to a lost family heirloom. She must overcome her fear of the outside world and race against a ruthless treasure hunter to find it before it falls into the wrong hands."
+
+**Using Chat:**
+Type: _"Update the story summary to: Elara, a cautious librarian, discovers a map to a lost family heirloom. She must overcome her fear of the outside world and race against a ruthless treasure hunter to find it before it falls into the wrong hands."_
+
+## Step 2: Populating the World
+
+Before writing, it helps to know who is in the story and where it takes place.
+
+**Manually:**
+
+1. Navigate to the **[Sourcebook](05_sourcebook.md)** in the left sidebar.
+2. Create a **Character** entry for your protagonist (e.g., Elara). Fill in her physical description, but more importantly, her _motivations_ and _flaws_.
+3. Create a **Character** entry for your antagonist.
+4. Create a **Location** entry for the starting point of your story (e.g., The Grand Library).
+
+**Using Chat:**
+
+1. Type: _"Create a character profile in the Sourcebook for Elara. She is a cautious librarian who is secretly brave but afraid of the outside world."_
+2. Type: _"Create a character profile for the antagonist, a ruthless treasure hunter named Silas."_
+3. Type: _"Create a location entry for The Grand Library, an ancient building filled with dusty tomes and hidden secrets."_
+
+
+
+## Step 3: Outlining with the AI
+
+If you aren't sure how to get from the beginning to the end, the AI can help.
+
+1. Open the **[AI Chat Assistant](07_ai_chat_assistant.md)**.
+2. Type: _"I have a story about a librarian named Elara looking for a lost heirloom. Can you help me outline the first three chapters? Keep in mind she is very cautious."_
+3. The AI will generate an outline. You can ask it to tweak things: _"Make Chapter 2 more action-packed."_
+
+## Step 4: Writing the First Chapter
+
+Now it's time to write.
+
+**Manually:**
+
+1. Go to the **[Chapters](04_chapters_and_books.md)** panel in the left sidebar and click **Add Chapter**. Name it "Chapter 1".
+2. Select the chapter to open it in the Editor.
+
+**Using Chat:**
+
+1. Type: _"Create a new chapter called 'Chapter 1'."_
+
+### Writing Advice: Start with Action or Intrigue
+
+Don't start with a long description of the weather or the character's morning routine. Start at a moment of change.
+
+_Example:_ Instead of "Elara woke up and went to work," start with "The ancient book practically burned Elara's fingers as she pulled it from the restricted section."
+
+3. Start writing your scene in the Editor.
+
+## Step 5: Using AI to Enhance Your Prose
+
+As you write, you might hit a wall. Let's say you need to describe the antagonist entering the library, but you can't find the right words.
+
+**Using the Chapter AI:**
+
+1. Click the **Rewrite** (
) button in the header to have the AI regenerate the entire chapter body with better prose. This is a great "reset" option early in the writing process.
+2. To extend the chapter with a new scene, click **Extend** () and the AI will continue writing from where you left off.
+3. For smaller suggestions at the paragraph level, click **Suggest next paragraph** at the bottom of the editor. Use the mode selector on the right: choose **Guided** for stronger context-guided continuation, **Instructed** for explicit next-paragraph continuation, or **Pure** for continuation from only the current chapter text.
+
+The suggestion cards appear — click any card to insert that text, or press `Escape` to dismiss.
+
+**Using Chat:**
+
+1. Open the **[AI Chat Assistant](07_ai_chat_assistant.md)** in the right sidebar.
+2. Type: _"I just wrote 'The bad guy walked in and looked mean.' Can you rewrite this to be more intimidating and descriptive? Remember he is a ruthless treasure hunter named Silas."_
+3. Review the result. Depending on the task, CHAT may either return revised wording for review or use the EDITING workflow to update the chapter directly.
+
+`[SCREENSHOT: The suggestion footer open with continuation cards based on the current chapter context]`
+
+## Step 6: Adding Visual References
+
+Visual references help both you and the AI stay consistent with how characters and places look.
+
+1. Click the **Images** icon in the header to open the [Project Images](09_project_images.md) dialog.
+2. Click **Create Placeholder** and name it "Elara — character portrait".
+3. Fill in the **Description** field with a text description: "A cautious young librarian with dark eyes, ink-stained fingers, and reading glasses perched on her nose."
+4. Click **Create prompt** (
) to have the AI generate an image-generation prompt you can use in an external art tool.
+5. Once you have the actual image, click **Replace** on the placeholder card to upload it.
+6. Open the Elara entry in the Sourcebook and click **Manage Images** to link the portrait to her character profile.
+
+`[SCREENSHOT: Project Images dialog showing the Elara placeholder card with the generated prompt popup open]`
+
+## Step 7: Pacing and Review
+
+Once you finish the chapter, it's time to review.
+
+### Writing Advice: Pacing
+
+Pacing is how fast or slow the story feels. Action scenes should have shorter sentences and paragraphs to feel fast. Emotional or descriptive scenes can be longer and more flowing.
+
+1. Open the **AI Chat Assistant**.
+2. Type: _"Please review Chapter 1. How is the pacing? Is the conflict clear?"_
+3. The AI will analyze your text and provide constructive feedback.
+
+## Step 8: Set Up Your Writing Environment
+
+Before your next long writing session, take a moment to tune the appearance to your preferences.
+
+1. Click the **Appearance** button in the header.
+2. Try **Mixed** or **Dark** design mode if you prefer less eye strain.
+3. Adjust **Font Size** and **Line Width** until the page feels comfortable for a long session.
+4. See [Appearance and Display](10_appearance_and_display.md) for all available settings.
+
+---
+
+## Conclusion
+
+Congratulations! You have set up a project, built your world in the Sourcebook, outlined with the AI, written your first chapter, added visual references to your project images, and reviewed the pacing of your prose.
+
+Remember, AugmentedQuill is a tool to enhance _your_ creativity. The story is always yours. Keep writing, keep experimenting, and let your imagination run wild!
+
+---
+
+Next up: Learn how to use your AI writing partner in [The AI Chat Assistant](07_ai_chat_assistant.md).
diff --git a/docs/user_manual/07_ai_chat_assistant.md b/docs/user_manual/07_ai_chat_assistant.md
index 2aef3b5d..22636dbc 100644
--- a/docs/user_manual/07_ai_chat_assistant.md
+++ b/docs/user_manual/07_ai_chat_assistant.md
@@ -65,12 +65,12 @@ Clicking the Chat Settings button reveals a panel below the header where you can
At the bottom of the chat panel is a two-part composer area:
-| Element | Description |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Message textarea** | Auto-growing text input. Press **Enter** to send, **Shift+Enter** to insert a newline without sending. |
-| **Send** button (round, 
) | Submits the message. Disabled while the AI is generating a response. |
-| **Stop generation** (red 
, dashed border) | Appears while the AI is generating. Click it to immediately abort the streaming response. The partial response remains visible in the message list. |
-| **Regenerate last response** ( dashed border button) | Re-runs the last AI request from scratch and replaces the previous response. Useful when the output was unsatisfactory. |
+| Element | Description |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Message textarea** | Auto-growing text input. Press **Enter** to send, **Shift+Enter** to insert a newline without sending. |
+| **Send** button (round, ) | Submits the message. Disabled while the AI is generating a response. |
+| **Stop generation** (red , dashed border) | Appears while the AI is generating. Click it to immediately abort the streaming response. The partial response remains visible in the message list. |
+| **Regenerate last response** ( dashed border button) | Re-runs the last AI request from scratch and replaces the previous response. Useful when the output was unsatisfactory. |
---
@@ -210,4 +210,4 @@ When those actions involve prose, CHAT should orchestrate them instead of writin
---
-Next up: Customize the look and feel in [Appearance and Display](08_appearance_and_display.md).
+Next up: Find and replace text across your project in [Search and Replace](08_search_and_replace.md).
diff --git a/docs/user_manual/08_appearance_and_display.md b/docs/user_manual/08_appearance_and_display.md
index 112635c1..3c604be9 100644
--- a/docs/user_manual/08_appearance_and_display.md
+++ b/docs/user_manual/08_appearance_and_display.md
@@ -59,11 +59,11 @@ The toolbar at the top of the dialog offers two ways to inspect logs:
### Toolbar Actions
-| Button | Description |
-| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| **Refresh** () | Re-fetches the log data from the server. Use this if you have been running requests in another browser tab. |
-| **Clear** (
) | Deletes all stored log entries after confirmation. |
-| **Close** () | Closes the dialog. |
+| Button | Description |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Refresh** () | Re-fetches the log data from the server. Use this if you have been running requests in another browser tab. |
+| **Clear** () | Deletes all stored log entries after confirmation. |
+| **Close** () | Closes the dialog. |
### LLM Raw Log Verbosity
@@ -94,4 +94,4 @@ JSON objects and arrays are collapsible — click the chevron next to any key to
---
-Next up: Apply everything you've learned in the [Tutorial: Writing Your First Story](09_tutorial_first_story.md).
+Next up: Read a strategic overview of the writing process in [Writing Your Story: A Practical Roadmap](10_writing_a_story.md).
diff --git a/docs/user_manual/12_search_and_replace.md b/docs/user_manual/08_search_and_replace.md
similarity index 94%
rename from docs/user_manual/12_search_and_replace.md
rename to docs/user_manual/08_search_and_replace.md
index 365d4b10..24381d7d 100644
--- a/docs/user_manual/12_search_and_replace.md
+++ b/docs/user_manual/08_search_and_replace.md
@@ -107,11 +107,11 @@ This is especially useful when a character is renamed and you want the name upda
## Using Search & Replace via AI Chat
-The AI assistant has two built-in tools for search and replace that you can invoke conversationally:
+The AI assistant exposes search/replace through a single manager tool that you can invoke conversationally:
-### `search_in_project`
+### `search_and_replace` (action=`search`)
-Ask the AI to find text and it will use the **`search_in_project`** tool:
+Ask the AI to find text and it will use **`search_and_replace`** with `action="search"`:
> _"Find all mentions of Elena in my chapters."_
> _"Search for the word 'sword' across everything."_
@@ -119,7 +119,7 @@ Ask the AI to find text and it will use the **`search_in_project`** tool:
The tool returns a list of matches grouped by section, which the AI formats into a readable reply.
-### `replace_in_project`
+### `search_and_replace` (action=`replace`)
Ask the AI to rename a character or fix a recurring phrase:
@@ -141,3 +141,7 @@ The tool runs a global replace and reports how many occurrences were changed and
| Find name variants of Elara | Phonetic enabled, All scope | `Elara` |
| Rename a character across all chapters | Replace All, All Chapters scope | old name → new name |
| Check if any chapter summary lacks a date | Metadata scope | `[0-9]{4}` |
+
+---
+
+Next up: Manage your project's visual assets in [Project Images](09_project_images.md).
diff --git a/docs/user_manual/09_project_images.md b/docs/user_manual/09_project_images.md
new file mode 100644
index 00000000..28d30a07
--- /dev/null
+++ b/docs/user_manual/09_project_images.md
@@ -0,0 +1,97 @@
+# Project Images
+
+The **Project Images** dialog is where you manage all visual assets attached to a story — reference artwork, character portraits, location sketches, or any images you want the AI to describe or use in prompts. Open it from the header by clicking the Image icon on the right side of the top bar.
+
+`[SCREENSHOT: The Project Images dialog showing the settings accordion, the action bar with three buttons, and an image grid with cards]`
+
+---
+
+## Project Image Settings
+
+At the top of the dialog is a collapsible **Project Image Settings** accordion. Click the header row (or the chevron icon) to expand or collapse it.
+
+| Setting | Description |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Global Style** | A free-text field for a style that should apply to all AI-generated image prompts in this project (e.g. "watercolor painting", "dark fantasy digital art", "pencil sketch"). When you generate prompts for images, this style description is automatically included. |
+| **Additional Information** | A textarea for extra hints, negative prompts, or LoRA trigger words that should be appended to every generated prompt. Useful for model-specific instructions (e.g. "no anime style, no text in image"). |
+
+---
+
+## Action Bar
+
+Below the settings section is a row of three action buttons:
+
+| Button | Icon | Description |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Generate Placeholder Prompts** | | Scans the project for all placeholder image slots (images that have a title/description but no uploaded file) and generates an AI image-generation prompt for each one in a single batch. Uses the 
CHAT model and incorporates the Global Style and Additional Information settings. |
+| **Create Placeholder** | | Adds a new named placeholder slot to the image grid. A placeholder has a title and description but no image file yet — use it to plan artwork you intend to generate or commission later. |
+| **Upload New Image** | ↑ Upload | Opens the system file picker. Accepts PNG, JPEG, GIF, and WEBP files. The uploaded image appears immediately in the grid. |
+
+You can also drag and drop an image file directly anywhere onto the dialog to upload it.
+
+---
+
+## Image Grid
+
+Uploaded and placeholder images are shown in a responsive grid (1–4 columns depending on screen width). Each image card contains:
+
+`[SCREENSHOT: A single image card showing the thumbnail, title input, description textarea, and action buttons]`
+
+### Thumbnail Area
+
+- **Click the thumbnail** to open the full-size **Lightbox** view (see below).
+- **Replace** button ( appears on hover): Opens the file picker to swap the image file while keeping the same title and description.
+- **Drag-and-drop**: Drag an image file onto a card to replace it.
+
+### Title and Description
+
+| Field | Description |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Title** text input | An editable name for this image (e.g. "Elara — Chapter 3"). Shown below the thumbnail and used when inserting the image into the editor. |
+| **Description** textarea | A resizable text area for a written description of the image. The AI uses this description when referencing the image in prompts or chat. |
+| **Save** button (
appears when unsaved changes exist) | Writes the title and description to disk. Changes to the text fields are not auto-saved — you must click Save to persist them. |
+
+### Per-Image Actions
+
+Four small action buttons appear below the description:
+
+| Button | Icon | Description |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Insert** | ✎ TextCursor | Inserts a markdown image reference (``) at the current editor cursor position, embedding this image inline in the chapter you are editing. |
+| **Generate / Update description** | | Asks the AI to generate a written description for this image (requires a multimodal / Vision-capable model to be assigned to the CHAT role). If a description already exists, it is updated. |
+| **Create prompt** | | Generates an image-generation prompt for this specific image. The prompt is shown in the **Generated Prompt popup** (see below) and can be copied to your clipboard. |
+| **Delete** | | Permanently deletes the image file from the project after a confirmation prompt. |
+
+---
+
+## Lightbox
+
+Clicking a thumbnail opens the **Lightbox** — a full-screen overlay showing the image at maximum size (up to 90 % of the screen width and height). The filename and description appear as a caption below the image. Click the **✕** () button or the backdrop to close it.
+
+---
+
+## Generated Prompt Popup
+
+When you click **Create prompt** on an image card, a popup panel appears showing the AI-generated image-generation prompt. The prompt streams in word by word so you can see it being written.
+
+| Control | Description |
+| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| **Close** () | Closes the popup without copying. |
+| **Output text area** | Read-only display of the generated prompt. Updates in real time while streaming. |
+| **Generating…** indicator | A spinner shown while the generation is still in progress. |
+| **Copy to Clipboard** () | Copies the full prompt text. The button label changes to "Copied!" for two seconds as confirmation. |
+
+Paste the copied prompt into your preferred image generation tool (Stable Diffusion, Midjourney, DALL-E, etc.) to create the artwork.
+
+---
+
+## Tips for Best Results
+
+- Fill in **Title** and **Description** for every image before generating prompts — the richer the description, the more accurate the generated prompt.
+- Use the **Global Style** field to keep a consistent art style across all generated prompts for the project.
+- **Placeholders** are powerful for planning: create them and name them (e.g. "Cover art — night scene") before you have the final images, then generate prompts later when you are ready.
+- Link images to Sourcebook entries (via the [Sourcebook Image Picker](05_sourcebook.md#image-picker)) so the AI knows which visual reference belongs to which character or location.
+
+---
+
+Next up: Customize the look and feel in [Appearance and Display](10_appearance_and_display.md).
diff --git a/docs/user_manual/09_tutorial_first_story.md b/docs/user_manual/09_tutorial_first_story.md
index 96c018b3..9375c56b 100644
--- a/docs/user_manual/09_tutorial_first_story.md
+++ b/docs/user_manual/09_tutorial_first_story.md
@@ -98,7 +98,7 @@ The suggestion cards appear — click any card to insert that text, or press `Es
`[SCREENSHOT: The suggestion footer open with continuation cards based on the current chapter context]`
-## Step 5b: Adding Visual References
+## Step 6: Adding Visual References
Visual references help both you and the AI stay consistent with how characters and places look.
@@ -111,7 +111,7 @@ Visual references help both you and the AI stay consistent with how characters a
`[SCREENSHOT: Project Images dialog showing the Elara placeholder card with the generated prompt popup open]`
-## Step 6: Pacing and Review
+## Step 7: Pacing and Review
Once you finish the chapter, it's time to review.
@@ -123,7 +123,7 @@ Pacing is how fast or slow the story feels. Action scenes should have shorter se
2. Type: _"Please review Chapter 1. How is the pacing? Is the conflict clear?"_
3. The AI will analyze your text and provide constructive feedback.
-## Step 7: Set Up Your Writing Environment
+## Step 8: Set Up Your Writing Environment
Before your next long writing session, take a moment to tune the appearance to your preferences.
@@ -140,4 +140,6 @@ Congratulations! You have set up a project, built your world in the Sourcebook,
Remember, AugmentedQuill is a tool to enhance _your_ creativity. The story is always yours. Keep writing, keep experimenting, and let your imagination run wild!
-_Return to the [User Manual index](index.md) to explore any topic in more depth._
+---
+
+Next up: Learn how to use your AI writing partner in [The AI Chat Assistant](07_ai_chat_assistant.md).
diff --git a/docs/user_manual/10_appearance_and_display.md b/docs/user_manual/10_appearance_and_display.md
new file mode 100644
index 00000000..c8397b7d
--- /dev/null
+++ b/docs/user_manual/10_appearance_and_display.md
@@ -0,0 +1,97 @@
+# Appearance and Display
+
+AugmentedQuill gives you fine-grained control over how the writing environment looks and feels. The **Appearance popup** lets you adjust the visual theme, typography, and panel sizes. The **Debug Logs** overlay (for advanced users) lets you inspect every AI request your session has made.
+
+---
+
+## Appearance Popup
+
+Click the **Appearance** button (the "Aa" / Type icon) on the right side of the top header bar and a dropdown panel appears below it.
+
+`[SCREENSHOT: The Appearance popup open, showing the Design Mode toggle and the five sliders]`
+
+### Design Mode
+
+A three-segment toggle at the top of the popup controls the overall color theme:
+
+| Option | Description |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Light** | The editor paper is bright white and all panels use a light color scheme. Best for daylight or well-lit rooms. |
+| **Mixed** | The editor paper stays light but the surrounding panels (sidebar, header, chat pane) use darker tones. A good balance for long writing sessions. |
+| **Dark** | All panels and the editor use dark backgrounds. Best for low-light environments or writers who prefer less screen glare. |
+
+The mode takes effect immediately across the entire application.
+
+### Appearance Sliders
+
+Five range sliders below the Design Mode toggle let you tune the reading and writing environment to your preferences. All changes are applied instantly as you drag.
+
+| Slider | Range | Default | Effect |
+| ----------------- | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Brightness** | 50 – 100 | 100 | Controls the brightness of the editor paper area. Lower values create a slightly off-white page that is easier on the eyes during long sessions. |
+| **Contrast** | 50 – 100 | 100 | Controls the contrast of the text against the background. Reducing this slightly can soften harsh black-on-white text. |
+| **Font Size** | 12 – 32 px | 16 px | Sets the base font size of the editor text. Increase for comfortable reading on large monitors; decrease to see more text at once. |
+| **Line Width** | 40 – 100 ch | 70 ch | Sets the maximum width of the editor column, measured in characters. Narrower lines (50–65 ch) are considered easier to read for long-form prose; wider lines let you see more text per line. |
+| **Sidebar Width** | 200 – 600 px (step 10) | 320 px | Controls the width of the left sidebar (and the right chat panel). Increase this if your project has long chapter titles or many Sourcebook entries that need more horizontal space. |
+
+### Closing the Popup
+
+Click the **✕** () button in the top-right corner of the popup, or click anywhere outside it, to close the Appearance panel. All changes are preserved automatically.
+
+---
+
+## Debug Logs
+
+The **Debug Logs** dialog is a developer-focused tool that shows a full transcript of every AI request AugmentedQuill has sent during the current session. It is useful for diagnosing unexpected AI behavior, verifying what context is being sent, or comparing request and response data.
+
+Open it by clicking the **Bug** icon on the right side of the top header bar.
+
+`[SCREENSHOT: Debug Logs dialog showing the aggregated view with a list of request entries, one expanded to show the request and response JSON]`
+
+### View Modes
+
+The toolbar at the top of the dialog offers two ways to inspect logs:
+
+| Mode | Icon | Description |
+| -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **Aggregated** | Layers icon | Shows each request as a clean summary: the full assembled response text and any tool calls. Best for quickly reading what the AI said. |
+| **Chunks** | List icon | Shows every raw JSON streaming chunk received from the API. Best for deep debugging of streaming issues or token usage. |
+
+### Toolbar Actions
+
+| Button | Description |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Refresh** () | Re-fetches the log data from the server. Use this if you have been running requests in another browser tab. |
+| **Clear** () | Deletes all stored log entries after confirmation. |
+| **Close** () | Closes the dialog. |
+
+### LLM Raw Log Verbosity
+
+The backend writes raw LLM interaction data to `data/logs/llm_raw.log` when `AUGQ_LLM_DUMP=1` is set in your environment. You can adjust the verbosity using `AUGQ_LLM_DUMP_LEVEL`:
+
+- `compact` (default): writes one entry per communication with minimal request/response payload, streaming data is summarized into `chunk_count` and `full_content_summary` with truncated chunks.
+- `normal`: writes one entry per communication with reduced payload, includes streaming chunk previews (up to 20 truncated items) and non-streaming response text up to 400 characters.
+- `debug`: includes full request/response objects and full streaming chunks, useful only for deep network and protocol debugging.
+
+The compact mode is recommended for normal use because it keeps log files readable while preserving every communication event.
+
+### Log Entries
+
+Each entry in the log list is a collapsible row. The collapsed row shows:
+
+- An **HTTP method badge** (POST in green, other methods in blue).
+- A **model type badge** indicating which role made the call: EDITING (purple), 
WRITING (blue), or CHAT (orange).
+- The **API endpoint name** (e.g. `/api/v1/chat/completions`).
+- The **HTTP status code** (200 in green, errors in red).
+- **Start and end timestamps** with elapsed time.
+
+Click a row to expand it. The expanded view shows two collapsible sections:
+
+- **Request**: An interactive JSON tree showing the full payload sent to the model, including the system prompt, user messages, tool definitions, and any image attachments.
+- **Response**: An interactive JSON tree showing the raw response (Chunks mode) or the assembled text and tool call results (Aggregated mode).
+
+JSON objects and arrays are collapsible — click the chevron next to any key to expand or collapse that branch. This makes it easy to navigate large payloads without scrolling through thousands of lines.
+
+---
+
+Next up: Read a strategic overview of the writing process in [Writing Your Story: A Practical Roadmap](11_writing_a_story.md).
diff --git a/docs/user_manual/10_writing_a_story.md b/docs/user_manual/10_writing_a_story.md
index 87a47cf2..dd4200dd 100644
--- a/docs/user_manual/10_writing_a_story.md
+++ b/docs/user_manual/10_writing_a_story.md
@@ -223,3 +223,7 @@ Writing a novel is a big commitment. These percentages are rough estimates of **
- **Phase 5 (Polishing): 10%**
> 🧠 Tip: If you’re using AugmentedQuill, the AI tools are designed to help you trim time from the Drafting and Editing phases, but the biggest gains come from having a solid plan and clear story goals.
+
+---
+
+Next up: Plan advanced story structure in [Scenes, Annotations, and Structural Improvements](13_scenes_and_annotations.md).
diff --git a/docs/user_manual/11_writing_a_story.md b/docs/user_manual/11_writing_a_story.md
new file mode 100644
index 00000000..9369323c
--- /dev/null
+++ b/docs/user_manual/11_writing_a_story.md
@@ -0,0 +1,229 @@
+# Writing Your Story: A Practical Roadmap
+
+Writing a long-form story (novel, serial, or campaign) is a marathon, not a sprint. This chapter walks through the common phases of getting from a flicker of an idea to a polished manuscript, and where AugmentedQuill can help you stay productive, organized, and creatively focused.
+
+> ⚠️ **No tool can write your story for you.** What AugmentedQuill does is make the parts of writing that are repetitive, thorny, or easy to procrastinate on feel less painful, so you can spend more of your energy on the parts that matter most: _the story itself_.
+
+---
+
+## Phase 1: The Seed (Ideation & Conceptualization)
+
+Before you write a single chapter, you need a clear idea of what your story is about.
+
+### 1. Brainstorm Core Concepts
+
+Ask yourself:
+
+- What genre am I writing? (fantasy, mystery, romance, etc.)
+- What are the big themes (loss, power, redemption, freedom)?
+- What is the core “what if?” question that drives the story?
+
+#### AugmentedQuill Tip
+
+Use the **AI Chat Assistant** (see [The AI Chat Assistant](07_ai_chat_assistant.md)) to brainstorm ideas, list trope variations, or quickly compare different high-level concepts.
+
+### 2. Write a Logline (Elevator Pitch)
+
+Try to distill the story into 1–2 sentences:
+
+> “A [protagonist] must [goal] before [stakes].”
+
+This logline becomes the compass you return to whenever your plot feels like it’s drifting.
+
+#### AugmentedQuill Tip
+
+Write your logline in the **Story Notes** (Story Metadata notes). Notes are included in every AI generation request, so keeping the logline there ensures the model always remembers the core goal and stakes.
+
+### 3. Define the Conflict
+
+Conflict is the engine of story. Put it on paper:
+
+- What does the protagonist want?
+- What is blocking them?
+- What happens if they fail?
+
+Make the stakes personal and tangible (lose a home, fail a mission, break a relationship).
+
+#### AugmentedQuill Tip
+
+Start by writing the overall conflict in your **Story Notes** (Story Metadata notes). Once it’s clear, add the most important pieces into Sourcebook character entries (e.g., the antagonist’s goals, the protagonist’s stakes, and key relationship tensions) so the AI has them on-hand when generating or rewriting text.
+
+---
+
+## Phase 2: The Blueprint (Planning & Outlining)
+
+Even writers who prefer “pantsing” usually benefit from some planning. A little structure up front can save huge amounts of rewriting later.
+
+### 4. Character Creation
+
+Build your core cast:
+
+- **Protagonist**: What do they want? What are they afraid of?
+- **Antagonist**: What do they stand for? Why are they opposed to the protagonist?
+- **Supporting cast**: Who helps and who hurts, and why?
+
+Give them flaws, desires, and arcs (how they change over the story).
+
+#### AugmentedQuill Tip
+
+Use the **Sourcebook** to keep character profiles, relationship notes, and recurring details. When you ask the AI to extend or rewrite, AugmentedQuill includes this context so the model stays consistent.
+
+### 5. World-Building
+
+Establish the setting and the rules that matter for your story:
+
+- What is the world like (city, wilderness, space ship)?
+- Are there special systems (magic, technology, factions)?
+- How does society work and what tensions are in play?
+
+#### AugmentedQuill Tip
+
+For complex settings, create one or more Sourcebook entries for “World,” “Magic Rules,” “Culture,” etc. This keeps reference material handy and ensures the AI uses the same details across chapters.
+
+### 6. Choose a Plot Structure
+
+Pick a framework to hang your story on. Common choices:
+
+- **Three-Act Structure** (Setup → Confrontation → Resolution)
+- **The Hero's Journey** (Call → Trials → Return)
+- **Save the Cat!** (Beat sheet approach)
+
+Mapping major beats (inciting incident, midpoint, climax) helps you maintain momentum and avoid wandering. Record your structure in the **Story Notes** so it stays visible to the AI and is easy to reference as you revise.
+
+### 7. Create a Chapter Outline
+
+Start by jotting rough chapter sketches in the **book notes** and the **chapter notes** (Metadata) for each entry. These notes are easy to revise as your story evolves, and they are sent to the AI on every generation call, helping keep the narrative consistent.
+
+Once your rough sketches feel like they hang together, distill them into the chapter summary field (the “summary” in each chapter’s metadata). That summary is what the AI uses as a guide when you ask it to generate or continue a chapter.
+
+#### AugmentedQuill Tip
+
+Use **Chapters and Books** (see [Chapters and Books](04_chapters_and_books.md)) to manage your outline. The notes area is your scratchpad; the summary field is the polished version that the AI uses to stay on-track.
+
+---
+
+## Phase 3: The Execution (Drafting)
+
+This is where you actually put words on the page.
+
+### 8. Set a Writing Schedule & Goal
+
+Decide on a realistic daily or weekly target (e.g., 500 words a day, one chapter a week) and stick to it. Small, consistent progress is almost always better than sporadic bursts.
+
+### 9. Write the “Vomit Draft” (First Draft)
+
+The main goal is momentum. Don’t polish as you go.
+
+- If you get stuck on a detail, drop a placeholder like `[NAME]` or `[PLACEHOLDER]` and move on.
+- Let the first draft be rough; you’ll fix it later.
+
+#### AugmentedQuill Tip
+
+Use the **Extend** and **Suggest** buttons in the editor to keep your momentum. They’re designed to help you overcome writer’s block by generating the next sentence, paragraph, or chunk of text based on your current chapter and the project context.
+
+### 10. Manage Chapter Pacing
+
+A good chapter usually has:
+
+- A small goal (what the character is trying to achieve in this scene)
+- A conflict or obstacle
+- A hook or decision that leads into the next chapter
+
+If a chapter stalls, it’s often because the internal goal isn’t clear.
+
+---
+
+## Phase 4: The Refinement (Editing & Revising)
+
+Once the draft exists, the real work begins.
+
+### 11. Step Away
+
+Put the manuscript aside for at least 2–4 weeks. Fresh eyes make it easier to spot structural problems.
+
+### 12. The Developmental Edit (Big Picture)
+
+Read the whole draft and look for:
+
+- Plot holes or inconsistencies
+- Slow pacing or “dead air” scenes
+- Characters acting out of character
+
+This stage may require rewriting entire chapters or re-ordering scenes.
+
+#### AugmentedQuill Tip
+
+Use the **AI Chat Assistant** to ask questions like “What are the biggest plot holes in this outline?” or “What motivations should a protagonist have in Act 2?” It can act as a sounding board as you revise.
+
+### 13. The Line Edit (Flow & Voice)
+
+Now focus on sentence-level quality:
+
+- Improve word choice
+- Cut redundant phrases
+- Make dialogue sound natural
+
+#### AugmentedQuill Tip
+
+In AugmentedQuill, the **Chat** model usually invokes the **EDITING** model behind the scenes when you ask it to polish or rewrite text. Use the AI Write / Update / Rewrite buttons in the chapter metadata to let the chat assistant call the editing model to improve summaries or rewrite a paragraph with a different tone or voice.
+
+### 14. Beta Readers
+
+Share your draft with a few trusted readers and ask for specific feedback:
+
+- Where did you get bored?
+- Which characters did you care about?
+- What confused you?
+
+Collect the feedback and decide what to act on.
+
+### 15. Revise Again
+
+Apply the useful feedback and tighten the manuscript. Revision is where a good story usually becomes a great one.
+
+---
+
+## Phase 5: The Final Polish (Finishing Touches)
+
+The story is solid; now make it clean and presentable.
+
+> Note: At the time of writing, AugmentedQuill does not have a comprehensive keyboard shortcut guide and relies primarily on UI interactions.
+
+### 16. Copyediting & Proofreading
+
+Hunt down typos, grammar issues, and formatting problems. This is tedious, but it makes a big difference.
+
+#### AugmentedQuill Tip
+
+Use the **AI Chat Assistant** or the **EDITING model** to proofread a passage, fix punctuation, or suggest cleaner phrasing.
+
+### 17. Final Formatting
+
+Ensure your chapters have clear headings, consistent spacing, and clean markdown. If you plan to export to other formats, check that the structure is compatible with your chosen toolchain.
+
+### 18. Decide Your Path
+
+Choose how you’ll share your work:
+
+- **Traditional publishing:** Write a query letter and synopsis, research agents, and prepare submission materials.
+- **Self-publishing:** Design a cover, format for e-readers, and upload to platforms like Kindle Direct Publishing.
+- **Export an eBook:** AugmentedQuill can compile your project into an `.epub` file via the Projects tab Export (EPUB) action, giving you a ready-to-share eBook.
+- **Web serialization:** Post chapters on platforms like Wattpad, RoyalRoad, or your own site.
+
+---
+
+## Rough Effort Breakdown (What to Expect)
+
+Writing a novel is a big commitment. These percentages are rough estimates of **active working time** (not calendar time):
+
+- **Phase 1 (Ideation): 5%**
+- **Phase 2 (Planning): 15%**
+- **Phase 3 (Drafting): 40%**
+- **Phase 4 (Editing): 30%**
+- **Phase 5 (Polishing): 10%**
+
+> 🧠 Tip: If you’re using AugmentedQuill, the AI tools are designed to help you trim time from the Drafting and Editing phases, but the biggest gains come from having a solid plan and clear story goals.
+
+---
+
+Next up: Plan advanced story structure in [Scenes, Annotations, and Structural Improvements](12_scenes_and_annotations.md).
diff --git a/docs/user_manual/12_scenes_and_annotations.md b/docs/user_manual/12_scenes_and_annotations.md
new file mode 100644
index 00000000..5d234256
--- /dev/null
+++ b/docs/user_manual/12_scenes_and_annotations.md
@@ -0,0 +1,295 @@
+# Scenes, Annotations, and Structural Improvements
+
+> **Introduced in:** v0.9+
+
+This chapter covers the major new features: the **Scenes** system (for planning and structuring stories at the narrative-unit level), **inline Annotations** (for notes attached to specific prose), the **Convergence Map** (for time-travel and multi-timeline stories), and various other structural improvements.
+
+---
+
+## Table of Contents
+
+1. [What Are Scenes?](#what-are-scenes)
+2. [Workspace Modes](#workspace-modes)
+3. [The Scenes Views](#the-scenes-views)
+ - [Narrative View](#narrative-view)
+ - [Pinboard View](#pinboard-view)
+ - [Convergence Map](#convergence-map)
+4. [Creating and Managing Scenes](#creating-and-managing-scenes)
+ - [Scene Properties](#scene-properties)
+ - [Causal Ordering](#causal-ordering)
+ - [Scene Beats](#scene-beats)
+5. [The Scene Editor Dialog](#the-scene-editor-dialog)
+6. [Inline Annotations](#inline-annotations)
+7. [Scene Sourcebook Tags](#scene-sourcebook-tags)
+8. [Sidebar Enhancements](#sidebar-enhancements)
+9. [Search and Replace in Scenes](#search-and-replace-in-scenes)
+10. [AI Chat Integration](#ai-chat-integration)
+11. [Diff Review Improvements](#diff-review-improvements)
+12. [Sourcebook Time Travel Features](#sourcebook-time-travel-features)
+13. [View State Persistence](#view-state-persistence)
+
+---
+
+## What Are Scenes?
+
+A **Scene** is a narrative unit — a building block of your story that may span part of a chapter, an entire chapter, or remain unlinked from any prose (planning-only). Scenes allow you to:
+
+- Plan your story's structure **before writing** any prose.
+- Track **causal relationships** between story events (what causes what).
+- Attach **sourcebook characters** to each scene.
+- Assign **temporal** (date/time) and **location** metadata.
+- Organize scenes into **timelines** for time-travel or parallel narratives.
+- Visualize your story through multiple lenses: narrative order, free-form pinboard, or a convergence map with character arc snakes.
+
+### Narrative Units vs. Prose
+
+A scene is a **planning unit**, not a prose unit. Multiple scenes can exist within a single chapter, a scene can span multiple chapters, or a scene can exist purely as a plan without any prose attached. This separation lets you outline your story's structure independently of your actual writing.
+
+---
+
+## Workspace Modes
+
+Click the **workspace mode buttons** in the top header bar to switch between layouts:
+
+| Mode | Icon | What you see |
+| ---------- | ---------- | ------------------------------------------------------------ |
+| **Page** | `FileText` | Traditional editor + left sidebar + right chat panel |
+| **Scenes** | `BookOpen` | Editor is replaced by the full Scenes panel |
+| **Split** | `Columns` | Editor on the left, Scenes panel on the right — side by side |
+
+---
+
+## The Scenes Views
+
+Once you're in **Scenes** or **Split** mode, use the segmented buttons labelled **Pinboard**, **Narrative**, **Chronological**, and **Convergence Map** to switch between view types.
+
+### Narrative View
+
+The **Narrative View** (default) displays all scenes as a vertical list. Divider lines appear at chapter and book boundaries so you can see how scenes map onto your story structure.
+
+- Scenes without any linked prose are collected at the bottom.
+- **Click** any scene card to select it and highlight its prose in the editor.
+- **Drag and drop** a scene card to reorder it (this adjusts the causal relationships).
+- Multi-select: **Ctrl+click** to toggle individual scenes, **Shift+click** for range selection.
+
+### Pinboard View
+
+The **Pinboard View** provides an infinite canvas where you can freely position scene cards.
+
+- **Pan:** Middle-mouse button drag, or **Alt+drag** on the background.
+- **Zoom:** Scroll wheel.
+- **Move cards:** Drag any card to reposition it.
+- **Multi-card drag:** Drag one selected card to move all selected cards together.
+- **Link scenes:** **Alt+drag** from one card toward another to draw a causal arrow — a ghost arrow preview appears as you drag.
+- **Lasso select:** Drag on empty space to draw a selection rectangle.
+- Same multi-select shortcuts as Narrative View (**Ctrl+click**, **Shift+click**).
+
+### Convergence Map
+
+The **Convergence Map** is designed for **time-travel stories**. It shows scenes sorted by their in-story time, with one coloured snake path per sourcebook character drawn behind the cards.
+
+- Each character or sourcebook entry gets its own **coloured lane** at the top.
+- The snake shows the character's **experience order** through the story.
+- Time-travel jumps appear as **U-turns** in the snake path.
+- Scene cards are positioned by chronological story time, not narrative order.
+- Click a character's lane button to highlight their path.
+
+---
+
+## Creating and Managing Scenes
+
+### Creating a Scene
+
+You can create scenes in several ways:
+
+1. **AI Chat:** Ask the assistant to create a new scene (e.g., _"Create a new scene where Elena meets the stranger."_)
+2. **Detect Boundaries:** Ask the AI to analyse your existing prose and **automatically detect scene boundaries**, creating linked scenes from the result.
+3. **Write a Scene:** Ask the AI to write prose for a specific scene, optionally within a particular chapter.
+
+### Scene Properties
+
+Each scene card displays key information. You can edit all properties in the Scene Editor Dialog.
+
+| Property | Description |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **Summary** | A one-line description of what happens in the scene. |
+| **Status** | One of: Active, Draft, Completed, Paused, or Cut. |
+| **Location** | Where the scene takes place (free text). |
+| **Time / Scene Time** | When the scene takes place (date and time). |
+| **Timeline** | Which timeline this scene belongs to. Default is "main"; for time-travel branches, you can create custom timeline IDs. |
+| **Color Tag** | A coloured border for visual organization — choose from red, orange, yellow, green, teal, blue, purple, or pink. |
+| **Active Characters** | Characters who are present and active in the scene. |
+| **Passive Characters** | Characters who are present but not directly acting. |
+| **Causes** | Which other scenes this one is caused by (determines narrative order). |
+
+### Causal Ordering
+
+Scenes are ordered by their **causal relationships**, not by arbitrary numbers. Each scene lists what it depends on, forming a cause-and-effect chain.
+
+- The system automatically detects **ordering violations** — scenes that should logically come before the scenes that cause them — and shows an **`AlertTriangle` icon** on the card.
+- **Temporal violations** are also flagged: if a scene's time is _before_ the scene that causes it, you'll see a **`Clock3` icon**.
+
+### Scene Beats
+
+Each scene can contain **Beats** — smaller sub-units of action within the scene. Beats help you break down a scene into its key moments (e.g., "Elena arrives", "The argument begins", "The stranger leaves") and can each link to their own section of prose.
+
+---
+
+## The Scene Editor Dialog
+
+**Double-click** any scene card, or ask the AI to edit a scene, to open the **Scene Editor Dialog**. This provides a full form where you can:
+
+- Edit the **summary**, **location**, **time**, and **status**.
+- Manage **Active** and **Passive character** lists.
+- Assign a **color tag** for visual organization.
+- Adjust the **pinboard position** (X/Y coordinates).
+- View and edit **causal relationships** (which scenes this one follows or precedes).
+- Set a **date/time** value by clicking the clock button to open the date/time picker.
+
+---
+
+## Inline Annotations
+
+**Annotations** let you attach notes, comments, or reminders to specific ranges of text. They appear as coloured highlights in the editor.
+
+### Adding an Annotation
+
+1. **Select** the text you want to annotate in the editor.
+2. Press **Ctrl+Shift+A** (Windows/Linux) or **Cmd+Shift+A** (macOS) — or click the **`MessageSquare` icon** in the editor toolbar.
+3. Type your comment in the dialog and confirm.
+
+### Managing Annotations
+
+Open the **Annotation Sidebar** (click the **`MessageSquarePlus` icon** in the right-side panel area). It lists all annotations for the current chapter:
+
+- **Click** an annotation entry to scroll the editor to it and highlight the annotated range.
+- Use the **`Pencil` icon** to edit a comment.
+- Use the **`Trash2` icon** to delete an annotation.
+- The list refreshes automatically when you switch chapters.
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+| ---------------------------------- | ---------------------------------- |
+| **Ctrl+Shift+A** / **Cmd+Shift+A** | Create annotation on selected text |
+| **Escape** | Close the annotation dialog |
+
+---
+
+## Scene Sourcebook Tags
+
+Characters and sourcebook entries can now carry a **birth or origin date**. When you attach such an entry to a scene, the system can display the character's **age** at the time of the scene, computed from their origin date and the scene's time.
+
+### Per-Scene Personal Datetime Overrides
+
+For time-travel stories, each character tag on a scene can optionally override the character's personal "now" for that specific scene. This allows the same character to appear multiple times in one scene (e.g., a time traveller meeting their younger self) — each instance can show a different age.
+
+---
+
+## Sidebar Enhancements
+
+The left sidebar (containing Story, Chapters, and Sourcebook sections) received several improvements:
+
+- **Resizable sections** — Drag the **`GripHorizontal` icon** (grip lines) between sections to resize them.
+- **Section focus** — Click the **`Maximize2` icon** in a section's header to focus that section (it expands fully, collapsing others). Click the **`Minimize2` icon** to return to the multi-section view.
+- **Scene tree in chapters** — Expand a chapter node to see its assigned scenes listed underneath in a compact tree view, using the **`ChevronRight` / `ChevronDown` icons** to expand and collapse.
+- **Drag scenes onto chapters** — Drag a scene card from the scenes panel and drop it onto a chapter in the sidebar to link them.
+- **Desktop behaviour** — On wide screens, selecting a chapter no longer closes the sidebar.
+
+---
+
+## Search and Replace in Scenes
+
+The Search & Replace system (accessible via the AI chat or the search panel) can now search inside scene metadata:
+
+- **Scene summaries** — Find and replace text in scene descriptions.
+- **Scene locations** — Search or replace location names across all scenes.
+- **Scene times** — Find temporal values.
+- **Timeline IDs** — Search timeline identifiers.
+- **Character lists** — Find or replace character names in active/passive lists.
+
+---
+
+## AI Chat Integration
+
+### Scene Chat Tools
+
+The AI assistant can help you manage scenes conversationally. Just ask in natural language:
+
+> _"Create a new scene where Elena discovers the hidden letter."_
+>
+> _"List all scenes involving Marcus."_
+>
+> _"Move the market scene after the forest scene."_
+>
+> _"Write the prose for scene 5 inside chapter 3."_
+>
+> _"Detect scene boundaries in my current chapter."_
+
+New tools available to the assistant include:
+
+| What you can ask for | What the AI does |
+| -------------------- | ------------------------------------------------------- |
+| Create a scene | Adds a new scene with summary, location, and characters |
+| Update a scene | Changes summary, time, location, status, etc. |
+| Delete a scene | Removes a scene and its markers from prose |
+| List scenes | Shows all scenes with their summaries and status |
+| Get scene details | Shows all properties of a single scene |
+| Reorder scenes | Adjusts causal relationships to change narrative order |
+| Link scene to prose | Attaches a scene to a specific content scope |
+| Write scene prose | Generates prose content for a scene via the Writing LLM |
+| Detect boundaries | Analyses existing prose and auto-creates linked scenes |
+
+### Project Creation Confirmation
+
+When the AI creates a new project, you'll be asked to **confirm** if the project name wasn't specified upfront.
+
+### Chat Session Preservation
+
+When you switch to a different project, your current chat session is automatically saved and associated with that project. When you return, the conversation picks up where you left off.
+
+### Context Usage Display
+
+The chat header now shows two context usage meters: your local estimation and the **server-reported usage** (as a percentage of the model's context window), so you know how close you are to the model's token limit.
+
+---
+
+## Diff Review Improvements
+
+When the editor shows highlighted changes (e.g., after an AI rewrite or undo), several new tools help you review and accept or reject changes.
+
+### Floating Accept/Reject Toolbar
+
+Hover over any diff-highlighted section in the editor — a small toolbar appears with:
+
+- **`Check` icon** — Accept this individual change
+- **`X` icon** — Reject this change (revert to the original)
+- **`CheckCheck` icon** — Accept all changes (shown when multiple diffs exist)
+
+### Block Mode for Large Rewrites
+
+When the AI substantially rewrites a section, the diff switches to **block mode**: the old and new versions are shown side by side as whole blocks, making it easier to review large changes compared to word-level inline highlighting.
+
+---
+
+## Sourcebook Time Travel Features
+
+Sourcebook entries now support a **Time Travel** category with additional fields for managing temporal stories.
+
+### New Sourcebook Fields
+
+When editing a sourcebook entry of the "Time Travel" category, you'll see these additional fields:
+
+| Field | What it's for |
+| -------------------------- | ------------------------------------------------------------------------------------ |
+| **Origin Date** | Birth or creation date of the entry — used to compute a character's age at any scene |
+| **Destination Date/Time** | For time-travel entries: the absolute date/time the character travels to |
+| **Destination (Relative)** | A relative description (e.g., "1000 years in the past") |
+| **Creates New Timeline** | Check this if the entry creates a branching timeline |
+| **Timeline ID** | A stable identifier for this timeline (auto-filled for branches) |
+
+### Relation Scoping to Scenes
+
+## Sourcebook relations are now scoped to individual **scenes** instead of whole chapters. When you define a relationship between entries (e.g., "Elena knows Marcus"), you can specify which scene the relationship starts and ends at, giving you finer control over relationship timelines.
+
+Next up: Find help in [Troubleshooting & FAQ](13_troubleshooting.md).
diff --git a/docs/user_manual/11_troubleshooting.md b/docs/user_manual/13_troubleshooting.md
similarity index 100%
rename from docs/user_manual/11_troubleshooting.md
rename to docs/user_manual/13_troubleshooting.md
diff --git a/docs/user_manual/index.md b/docs/user_manual/index.md
index e2d5d090..27c58420 100644
--- a/docs/user_manual/index.md
+++ b/docs/user_manual/index.md
@@ -9,10 +9,11 @@ Welcome to AugmentedQuill, your AI-assisted prose writing companion. This manual
3. [The Writing Interface](03_writing_interface.md)
4. [Chapters and Books](04_chapters_and_books.md)
5. [The Sourcebook](05_sourcebook.md)
-6. [Project Images](06_project_images.md)
+6. [Tutorial: Writing Your First Story](06_tutorial_first_story.md)
7. [The AI Chat Assistant](07_ai_chat_assistant.md)
-8. [Appearance and Display](08_appearance_and_display.md)
-9. [Tutorial: Writing Your First Story](09_tutorial_first_story.md)
-10. [Writing Your Story: A Practical Roadmap](10_writing_a_story.md)
-11. [Troubleshooting & FAQ](11_troubleshooting.md)
-12. [Search and Replace](12_search_and_replace.md)
+8. [Search and Replace](08_search_and_replace.md)
+9. [Project Images](09_project_images.md)
+10. [Appearance and Display](10_appearance_and_display.md)
+11. [Writing Your Story: A Practical Roadmap](11_writing_a_story.md)
+12. [Scenes, Annotations, and Structural Improvements](12_scenes_and_annotations.md)
+13. [Troubleshooting & FAQ](13_troubleshooting.md)
diff --git a/openapi.json b/openapi.json
index 3e6c7206..0c62f28a 100644
--- a/openapi.json
+++ b/openapi.json
@@ -1771,7 +1771,7 @@
"post": {
"tags": ["Story", "Story"],
"summary": "Api Story Sourcebook Relevance",
- "description": "Ask the WRITING model which sourcebook entries are relevant.\n\nThis is a lightweight helper used by the frontend to keep checkboxes\nin sync. It is deliberately separate from the prose suggestion call so\nthat we can run it in the background on every text change.",
+ "description": "Return scene-derived sourcebook entries relevant to the active prose end.\n\nThis runs in the background while the user types, so it must stay\ndeterministic, cheap, and free of LLM latency.",
"operationId": "api_story_sourcebook_relevance_api_v1_projects__project_name__story_sourcebook_relevance_post",
"parameters": [
{
@@ -2066,6 +2066,58 @@
}
}
},
+ "/api/v1/projects/{project_name}/chapters/{chap_id}/rewrite-and-relink": {
+ "post": {
+ "tags": ["Story", "Story"],
+ "summary": "Api Chapter Rewrite And Relink",
+ "description": "Atomically rewrite a chapter and auto-link scenes in one transaction.\n\nThis endpoint streams the generated content and persists it,\nthen performs scene auto-linking on the resulting text.",
+ "operationId": "api_chapter_rewrite_and_relink_api_v1_projects__project_name__chapters__chap_id__rewrite_and_relink_post",
+ "parameters": [
+ {
+ "name": "chap_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "integer",
+ "title": "Chap Id"
+ }
+ },
+ {
+ "name": "project_name",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "Directory name of the project",
+ "title": "Project Name"
+ },
+ "description": "Directory name of the project"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "title": "Response Api Chapter Rewrite And Relink Api V1 Projects Project Name Chapters Chap Id Rewrite And Relink Post"
+ }
+ }
+ }
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"/api/v1/projects/{project_name}/story/title": {
"post": {
"tags": ["Story", "Story"],
@@ -3512,97 +3564,1991 @@
}
}
},
- "/api/v1/health": {
+ "/api/v1/projects/{project_name}/scenes": {
"get": {
- "summary": "