chhoumann · chhoumann · Apr 24, 2026 · Apr 23, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/docs/docs/Advanced/APIOverview.md b/docs/docs/Advanced/APIOverview.md
@@ -0,0 +1,51 @@
+---
+title: API Overview
+---
+
+Use the QuickAdd API when a workflow needs scripted input, file operations,
+formatting, model calls, or access from another plugin.
+
+If you only need to create a note or append text, start with
+[Template Choices](../Choices/TemplateChoice) or
+[Capture Choices](../Choices/CaptureChoice). Add the API when the workflow
+needs logic.
+
+## Where the API is available
+
+| Context | Access pattern | Use it for |
+| --- | --- | --- |
+| Macro user script | `params.quickAddApi` | Scripted macro steps |
+| Inline script | `this.quickAddApi` | Small transformations inside templates or captures |
+| Other plugin | `app.plugins.plugins.quickadd.api` | Calling QuickAdd from plugin code |
+| Templater script | `app.plugins.plugins.quickadd.api` | Prompting or running choices from Templater |
+
+## Common tasks
+
+| Task | Method family | Reference |
+| --- | --- | --- |
+| Ask for text, selections, dates, or grouped inputs | User input methods | [QuickAdd API Reference](../QuickAddAPI#user-input-methods) |
+| Run another choice from a script | Choice execution | [Choice Execution](../QuickAddAPI#choice-execution) |
+| Read selected text or clipboard content | Utility module | [Utility Module](../QuickAddAPI#utility-module) |
+| Format dates | Date module | [Date Module](../QuickAddAPI#date-module) |
+| Call configured AI providers | AI module | [AI Module](../QuickAddAPI#ai-module) |
+| Read field suggestions from the vault | Field suggestions module | [Field Suggestions Module](../QuickAddAPI#field-suggestions-module) |
+
+## Recommended path
+
+1. Read the [scripting overview](./ScriptingGuide) if you have not written a
+   QuickAdd script before.
+2. Copy a working pattern from the [examples overview](../Examples/).
+3. Use the [QuickAdd API reference](../QuickAddAPI) for exact signatures and
+   edge-case behavior.
+
+## Minimal macro script
+
+```javascript
+module.exports = async ({ quickAddApi }) => {
+  const title = await quickAddApi.inputPrompt("Book title");
+  return `# ${title}`;
+};
+```
+
+The returned value can be used by later macro steps or inserted through format
+syntax.
diff --git a/docs/docs/Advanced/ScriptingGuide.md b/docs/docs/Advanced/ScriptingGuide.md
@@ -0,0 +1,58 @@
+---
+title: Scripting Overview
+---
+
+QuickAdd scripts are JavaScript files that run inside Obsidian. They can prompt
+for input, call Obsidian APIs, read other plugins, and pass values back into a
+Macro choice.
+
+## Which scripting feature should I use?
+
+| Need | Use | Why |
+| --- | --- | --- |
+| A reusable script with settings | User script | Best for larger workflows and shared code |
+| A small transformation inside a template or capture | Inline script | Keeps tiny logic close to the format using it |
+| Several script and choice steps in sequence | Macro choice | Coordinates order, variables, and abort behavior |
+| A script users can configure from the QuickAdd UI | Script with settings | Lets non-coders change values without editing JavaScript |
+
+## Basic user script shape
+
+```javascript
+module.exports = async (params) => {
+  const { app, quickAddApi, variables } = params;
+  const title = await quickAddApi.inputPrompt("Title");
+
+  variables.title = title;
+  return title;
+};
+```
+
+The `params` object gives scripts access to:
+
+- `app`: the Obsidian app instance
+- `quickAddApi`: QuickAdd's prompt, utility, AI, and execution helpers
+- `variables`: values shared across macro steps
+
+## How values move through a macro
+
+1. A choice or script asks for a value.
+2. QuickAdd stores that value in `variables`.
+3. Later template, capture, and script steps can reuse it.
+4. If a prompt is cancelled, QuickAdd aborts the macro unless your script handles
+   the cancellation.
+
+Use named values like `{{VALUE:project}}` when several macro steps should share
+one prompt.
+
+## Suggested learning order
+
+1. [Macro Choices](../Choices/MacroChoice) for how macro steps are assembled.
+2. [User Scripts](../UserScripts) for complete scripting patterns.
+3. [Scripts with Settings](./scriptsWithSettings) for configurable scripts.
+4. [QuickAdd API Reference](../QuickAddAPI) for exact method details.
+
+## Debugging
+
+Use `console.log` while developing scripts, then check Obsidian's developer
+console. Keep scripts small enough that each step can be tested independently
+before adding it to a longer macro.
diff --git a/docs/docs/Choices/CaptureChoice.md b/docs/docs/Choices/CaptureChoice.md
@@ -103,7 +103,8 @@ When append-link is set to **Enabled (requires active file)** and capture runs
 from a Canvas card without a focused Markdown editor, the capture still writes
 and link insertion is skipped.
 
-A dedicated Canvas walkthrough page will return in a future update.
+For a step-by-step setup, see
+[Capture: Canvas Capture](../Examples/Capture_CanvasCapture).
 
 ### Canvas Capture FAQ
 

diff --git a/docs/docs/Examples/Capture_CanvasCapture.md b/docs/docs/Examples/Capture_CanvasCapture.md
@@ -0,0 +1,86 @@
+---
+title: "Capture: Canvas Capture"
+---
+
+Canvas capture lets a Capture choice write into a selected Canvas card or into a
+specific card in a specific `.canvas` file.
+
+## When to use this
+
+Use Canvas capture when your workflow starts in a visual board, but you still
+want QuickAdd's capture formats, variables, and hotkeys.
+
+Good fits:
+
+- Add a timestamped note to a selected brainstorming card.
+- Append a task to a project card.
+- Send repeated updates to one known Canvas card.
+
+## Capture to the selected card
+
+1. Create a Capture choice.
+2. Enable **Capture to active file**.
+3. Open a Canvas file.
+4. Select exactly one supported card.
+5. Set **Write position** to **Top of file**, **Bottom of file**, or
+   **After line...**.
+6. Run the Capture choice.
+
+Supported selected-card targets:
+
+- Text cards
+- File cards that point to Markdown files
+
+QuickAdd aborts with a notice if no card is selected, multiple cards are
+selected, or the selected card is unsupported.
+
+## Capture to a specific card
+
+1. Create a Capture choice.
+2. Turn off **Capture to active file**.
+3. Set **Capture To** to a `.canvas` file.
+4. Choose **Target canvas node**.
+5. Pick the card you want QuickAdd to write to.
+6. Set a supported write position.
+
+This is the best option for repeatable workflows where every capture should go
+to the same Canvas card.
+
+## Write position support
+
+Canvas capture supports these write positions:
+
+- **Top of file**
+- **Bottom of file**
+- **After line...**
+
+Canvas capture does not support cursor-based write positions:
+
+- **At cursor**
+- **New line above cursor**
+- **New line below cursor**
+
+If **Capture to active file** is enabled and the write position is still
+**At cursor**, QuickAdd aborts instead of writing to the wrong place.
+
+## Append-link behavior
+
+When append-link is set to **Enabled (requires active file)** and capture runs
+from a Canvas card without a focused Markdown editor, the capture still writes.
+QuickAdd skips link insertion because there is no active Markdown file to link
+from.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Capture aborts before writing | No card or multiple cards are selected | Select exactly one supported card |
+| Capture aborts with cursor-position wording | The write mode is cursor-based | Use top, bottom, or after-line placement |
+| Nothing is written to a file card | The file card points to a non-Markdown file | Use a Markdown file card or a text card |
+| The target picker is not shown | Capture target is not a `.canvas` file | Set **Capture To** to the Canvas file path |
+
+## Related docs
+
+- [Capture Choices](../Choices/CaptureChoice)
+- [Format Syntax](../FormatSyntax)
+- [Template: Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard)
diff --git a/docs/docs/Examples/index.md b/docs/docs/Examples/index.md
@@ -0,0 +1,40 @@
+---
+title: Examples
+---
+
+Use these examples when you want to copy a working pattern instead of starting
+from a blank choice.
+
+| Workflow | Choice type | Setup | Prerequisites | What it creates |
+| --- | --- | --- | --- | --- |
+| [Add Journal Entry](./Capture_AddJournalEntry) | Capture | Beginner | Daily note or journal file | A timestamped journal entry |
+| [Add a Task to a Kanban Board](./Capture_AddTaskToKanbanBoard) | Capture | Beginner | Obsidian Kanban plugin | A task in a board section |
+| [Fetch Tasks from Todoist](./Capture_FetchTasksFromTodoist) | Capture and Macro | Intermediate | Todoist API token | Imported Todoist tasks |
+| [Canvas Capture](./Capture_CanvasCapture) | Capture | Intermediate | An Obsidian Canvas file | Text added to a selected or targeted card |
+| [Add an Inbox Item](./Template_AddAnInboxItem) | Template | Beginner | Inbox folder or note | A new inbox note |
+| [Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard) | Template | Intermediate | Base template file | A note with an embedded Base dashboard |
+| [Automatic Book Notes from Readwise](./Template_AutomaticBookNotesFromReadwise) | Template and Macro | Advanced | Readwise export script | Book notes with highlights |
+| [Book Finder](./Macro_BookFinder) | Macro | Intermediate | Book lookup script | A populated book note |
+| [Movie and Series Script](./Macro_MovieAndSeriesScript) | Macro | Intermediate | TMDB API key | Media notes with metadata |
+| [Move Notes with a Tag](./Macro_MoveNotesWithATagToAFolder) | Macro | Intermediate | Tagged notes | Notes moved into a target folder |
+| [Zettelizer](./Macro_Zettelizer) | Macro | Intermediate | Headings in an existing note | New notes split from headings |
+| [Toggl Manager](./Macro_TogglManager) | Macro | Advanced | Toggl integration | Preset time entries |
+
+## Pick by goal
+
+### Capture information faster
+
+Start with [Add Journal Entry](./Capture_AddJournalEntry) if you want the
+simplest capture flow. Move to [Canvas Capture](./Capture_CanvasCapture) when
+your target is a Canvas card instead of a Markdown note.
+
+### Create structured notes
+
+Start with [Add an Inbox Item](./Template_AddAnInboxItem) for a small template.
+Use [Create an MOC Note with a Link Dashboard](./Template_CreateMOCNoteWithLinkDashboard)
+when you want a generated note to include a live Base dashboard.
+
+### Run scripted workflows
+
+Start with [Book Finder](./Macro_BookFinder) to see the common macro pattern:
+prompt for input, call a script, write a note, and open the result.
diff --git a/docs/docs/QuickAddAPI.md b/docs/docs/QuickAddAPI.md
@@ -2,6 +2,13 @@
 
 The QuickAdd API provides a powerful interface for automating tasks in Obsidian through scripts, macros, and inline scripts. The API offers methods for user interaction, file manipulation, AI integration, and more.
 
+:::tip Start with the overview
+
+If you are choosing which API surface to use, read the
+[API Overview](./Advanced/APIOverview) first. This page is the full reference.
+
+:::
+
 ## Accessing the API
 
 The API can be accessed in several ways:

diff --git a/docs/docs/UserScripts.md b/docs/docs/UserScripts.md
@@ -1,8 +1,15 @@
 # User Scripts
 
+:::tip New to scripting?
+
+Start with the [Scripting Overview](./Advanced/ScriptingGuide) for the
+decision path, then use this page as the detailed reference.
+
+:::
+
 User scripts are JavaScript files that extend QuickAdd's functionality with custom code. They can be used within macros to perform complex operations, integrate with external APIs, and automate sophisticated workflows.
 
-> 📚 **Obsidian API Reference**: This guide references the [Obsidian API](https://docs.obsidian.md/Home). Familiarize yourself with the [App](https://docs.obsidian.md/Reference/TypeScript+API/App), [Vault](https://docs.obsidian.md/Reference/TypeScript+API/Vault), and [Workspace](https://docs.obsidian.md/Reference/TypeScript+API/Workspace) modules for advanced scripting.
+> **Obsidian API Reference**: This guide references the [Obsidian API](https://docs.obsidian.md/Home). Familiarize yourself with the [App](https://docs.obsidian.md/Reference/TypeScript+API/App), [Vault](https://docs.obsidian.md/Reference/TypeScript+API/Vault), and [Workspace](https://docs.obsidian.md/Reference/TypeScript+API/Workspace) modules for advanced scripting.
 
 ## Basic Structure
 

diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -3,54 +3,65 @@ sidebar_position: 1
 title: Getting Started
 ---
 
-## Installation
+QuickAdd adds one fast command for repeatable Obsidian workflows. Use it to
+create notes from templates, capture text into existing notes, run scripts, or
+organize several choices behind one menu.
 
-**This plugin is in the community plugin browser in Obsidian**. You can search for it and install it there .
+## Install QuickAdd
 
-You can also do a [manual installation](./ManualInstallation).
+Install QuickAdd from Obsidian's Community Plugins browser, then enable it.
 
-## First steps
+If you cannot use the plugin browser, follow the
+[manual installation guide](./ManualInstallation).
 
-The first thing you'll want to do is add a new choice. A choice can be one of four types.
+## Choose the right choice type
 
--   [Template Choice](./Choices/TemplateChoice) - Insert templates into your vault. Works together with Obsidian template syntax and popular _Templater_ plugin, augmenting them and adding more options.
--   [Capture Choice](./Choices/CaptureChoice) - Quick capture your manually written information and save it. Daily notes, work log, to-read-and-watch-later list, etc.
--   [Macro Choice](./Choices/MacroChoice) - Macros to augment your workflow. Use the full power of Javascript programming language and Obsidian functions to do anything your want. E.g. [create a personal movie database](./Examples/Macro_MovieAndSeriesScript) by writing a movie name and getting the movie notes fully customized and filled with correct film's up-to-date data.
--   [Multi Choice](./Choices/MultiChoice) - Folders to better organize the previous 3 choices. Usability feature, not a new functionality.
--   [Share QuickAdd Packages](./Choices/Packages) - Bundle choices and scripts into a portable `.quickadd.json` file so you can reuse automations across vaults.
+| If you want to... | Use this | Start here |
+| --- | --- | --- |
+| Create a new note from a reusable file | Template choice | [Template Choices](./Choices/TemplateChoice) |
+| Append text to a journal, log, task list, or existing file | Capture choice | [Capture Choices](./Choices/CaptureChoice) |
+| Run one or more Obsidian commands, scripts, or choices | Macro choice | [Macro Choices](./Choices/MacroChoice) |
+| Group choices into a nested menu | Multi choice | [Multi Choices](./Choices/MultiChoice) |
+| Share configured workflows across vaults | Package | [Share QuickAdd Packages](./Choices/Packages) |
 
-In your choices, you can use [format syntax](./FormatSyntax), which is similar to the Obsidian template syntax.
+Most workflows start with either a Template choice or a Capture choice. Add a
+Macro choice when you need scripting, multiple steps, or data from another
+plugin or API.
 
-You could, for example, use `{{DATE}}` to get the current date.
+## First workflow
 
-QuickAdd also features a powerful [suggester system](./SuggesterSystem) that provides intelligent, fuzzy-search suggestions for files, tags, headings, and more.
+1. Create a Template choice or Capture choice in QuickAdd settings.
+2. Add a name you will recognize in the command palette.
+3. Configure the target file, folder, template, or capture format.
+4. Run `QuickAdd: Run QuickAdd` from the command palette.
+5. Assign a hotkey once the workflow behaves the way you want.
 
-## I want to...
+QuickAdd choices can use [format syntax](./FormatSyntax), including values like
+`{{DATE}}`, `{{VALUE}}`, and `{{FIELD:status}}`. The
+[suggester system](./SuggesterSystem) provides fuzzy search for files, tags,
+headings, and fields.
 
-### Be inspired
+## Common paths
 
-Take a look at some examples...
+### I want examples first
 
--   [Capture: Add Journal Entry](docs/Examples/Capture_AddJournalEntry.md)
--   [Macro: Log book to daily journal](docs/Examples/Macro_LogBookToDailyJournal.md)
--   [Template: Add an Inbox Item](docs/Examples/Template_AddAnInboxItem.md)
--   [Template: Create an MOC note with a link dashboard](docs/Examples/Template_CreateMOCNoteWithLinkDashboard.md)
--   [Macro: Move all notes with a tag to a certain folder](docs/Examples/Macro_MoveNotesWithATagToAFolder.md)
--   [Template: Automatically create a new book note with notes & highlights from Readwise](docs/Examples/Template_AutomaticBookNotesFromReadwise.md)
--   [Capture: Add a task to a Kanban board](docs/Examples/Capture_AddTaskToKanbanBoard.md)
--   [Macro: Easily change properties in your daily note (requires MetaEdit)](docs/Examples/Macro_ChangePropertyInDailyNotes.md)
--   [Capture: Fetch tasks from Todoist and capture to a file](docs/Examples/Capture_FetchTasksFromTodoist.md)
--   [Macro: Zettelizer - easily create new notes from headings while keeping the contents in the file](docs/Examples/Macro_Zettelizer.md)
--   [Macro: Obsidian Map View plugin helper - insert location from address](docs/Examples/Macro_AddLocationLongLatFromAddress.md)
--   [Macro: Toggl Manager - set preset Toggl Track time entries and start them from Obsidian](docs/Examples/Macro_TogglManager.md)
--   [How I Read Research Papers with Obsidian and Zotero](https://bagerbach.com/blog/how-i-read-research-papers-with-obsidian-and-zotero/)
--   [How I Import Literature Notes into Obsidian](https://bagerbach.com/blog/importing-source-notes-to-obsidian)
--   [Macro: Fetching movies and TV shows into your vault](docs/Examples/Macro_MovieAndSeriesScript.md)
+Use the [examples overview](./Examples/) to pick a complete workflow by choice
+type, difficulty, prerequisites, and outcome.
 
-### Create powerful scripts and macros to automate my workflow
+Good first examples:
 
-Take a look at the [QuickAdd API](docs/QuickAddAPI.md), [format syntax](docs/FormatSyntax.md), [inline scripts](docs/InlineScripts.md), and [macros](docs/Choices/MacroChoice.md).
+- [Capture: Add Journal Entry](./Examples/Capture_AddJournalEntry)
+- [Template: Add an Inbox Item](./Examples/Template_AddAnInboxItem)
+- [Macro: Book Finder](./Examples/Macro_BookFinder)
+- [Capture: Canvas Capture](./Examples/Capture_CanvasCapture)
 
-### Use QuickAdd even when Obsidian is minimized / in the background
+### I want to automate with scripts
 
-You got it. Take a look at [this AutoHotKey script](./Misc/AHK_OpenQuickAddFromDesktop).
+Start with the [scripting overview](./Advanced/ScriptingGuide), then move to
+[User Scripts](./UserScripts) and the [QuickAdd API reference](./QuickAddAPI)
+when you need exact method details.
+
+### I want to call QuickAdd from outside Obsidian
+
+Use [Obsidian URI](./Advanced/ObsidianUri) for URI-triggered workflows, or the
+[QuickAdd CLI](./Advanced/CLI) for shell scripts and external automation.