feat(runtime): add flow-aware execution runtime

docs/docs/Advanced/CLI.md

@@ -39,6 +39,51 @@ Check which inputs are still missing before a non-interactive run.
 obsidian vault=dev quickadd:check choice="Daily log"
 ```
 
+The check command is flow-aware. For macros, it follows nested Template and Capture choices, reports missing inputs for the whole flow, and includes diagnostics in the JSON response:
+
+- `diagnostics`: runtime, nested-choice, and integration capability notes.
+- `flow.choices`: choices included in the check, with path and depth.
+- `missingFlags`: CLI flags you can pass to satisfy unresolved inputs.
+
+Example response shape:
+
+```json
+{
+  "ok": false,
+  "command": "quickadd:check",
+  "requiredInputCount": 1,
+  "missingInputCount": 1,
+  "missingFlags": ["value-project=<value>"],
+  "diagnostics": [
+    {
+      "severity": "error",
+      "code": "missing-required-inputs",
+      "source": "runtime",
+      "message": "1 required input(s) are missing for this flow."
+    }
+  ],
+  "flow": {
+    "choiceCount": 2,
+    "choices": [
+      {
+        "id": "macro-choice-id",
+        "name": "Daily log",
+        "type": "Macro",
+        "path": "Daily log",
+        "depth": 0
+      },
+      {
+        "id": "capture-choice-id",
+        "name": "Capture project",
+        "type": "Capture",
+        "path": "Daily log / Capture project",
+        "depth": 1
+      }
+    ]
+  }
+}
+```
+
 ## Passing variables
 
 QuickAdd CLI supports three variable patterns:

docs/docs/Advanced/onePageInputs.md

@@ -21,6 +21,7 @@ This feature is currently in Beta.
 - `{{VALUE|type:multiline}}` and `{{VALUE:name|type:multiline}}` render as textareas in the one-page modal.
 - Capture target file when capturing to a folder or tag.
 - Script-declared inputs (from user scripts inside macros), if provided.
+- Nested Template/Capture choices inside macros are included in flow-aware CLI checks, so missing inputs can be reported before a non-interactive macro run.
 
 ## Date UX
 - Date fields support natural language (e.g., “today”, “next friday”).
@@ -178,6 +179,16 @@ Behavior:
 
 ---
 
+## CLI diagnostics
+
+`quickadd:check` uses the same requirement parsing as one-page inputs, then adds flow diagnostics for macros and nested choices. The JSON response includes:
+
+- `missing` and `missingFlags` for unresolved inputs.
+- `diagnostics` for flow/runtime information, missing nested choices, and integration capability notes.
+- `flow.choices`, showing which choices were included in the flow check.
+
+This is read-only: it does not execute choices or run user scripts beyond the existing static metadata inspection used for declared `quickadd.inputs`.
+
 ## Notes
 - Macro support is best-effort: user scripts can declare inputs via `quickadd.inputs`.
 - Preflight may import user script modules to statically read `quickadd.inputs`. This can execute module top-level code.

docs/docs/Choices/CaptureChoice.md

@@ -45,6 +45,17 @@ If you have a tag called `#people`, and you type `#people` in the _Capture To_ f
 
 ## Capture Options
 
+Capture runs participate in the shared QuickAdd flow runtime. When a Capture choice is launched from a macro or nested choice, it reuses the same variable map and origin tab as the parent flow.
+
+QuickAdd preserves capture write ordering to avoid data loss:
+
+- Existing-file captures still use the merge guard before modifying the file.
+- Missing insert-after targets abort before the file is modified, unless you enabled creating the missing line.
+- Structured YAML/template-property post-processing runs only after a successful write.
+- Creating a file from a template suppresses Templater's on-create trigger and renders the whole file once.
+- Creating a file without a template waits for Templater's on-create trigger only when that trigger is enabled.
+- Whole-file Templater rendering after capture remains opt-in via the Templater after-capture setting.
+
 -   _Create file if it doesn't exist_ will do as the name implies - you can also create the file from a template, if you specify the template (the input box will appear below the setting).
 -   _Task_ will format your captured text as a task.
 -   _Use editor selection as default value_ controls whether the current editor selection is used as `{{VALUE}}`. Choose **Follow global setting**, **Use selection**, or **Ignore selection** (global default lives in Settings > Input). This does not affect `{{SELECTED}}`.

docs/docs/Choices/MacroChoice.md

@@ -52,6 +52,7 @@ In the Macro Builder, you can add different types of commands:
 4. **Nested Choice** - Execute another QuickAdd choice
    - Reuse existing templates, captures, or other macros
    - Create modular workflows
+   - Nested choices share the parent macro's runtime context, variables, and origin tab
 5. **Wait** - Add delays between commands
    - Useful when commands need time to complete
    - Specified in milliseconds
@@ -249,7 +250,13 @@ module.exports = async (params) => {
 
 ## Variables and Data Flow
 
-Variables allow you to pass data between commands in a macro:
+Variables allow you to pass data between commands in a macro. A macro run now uses one shared flow context from the first command through all nested choices. That means:
+
+- Variables set by one command are visible to later commands.
+- Nested Template, Capture, and Macro choices reuse the same variable map.
+- Nested choices reuse the macro's original leaf/tab for file-opening behavior, so later file opens stay anchored to the run that started the macro.
+- If a nested choice aborts, the macro stops and later commands are skipped.
+
 
 ### Setting Variables in Scripts
 
@@ -508,6 +515,7 @@ Macros automatically stop execution in the following situations:
 - A message is logged explaining why the macro stopped
 - For user cancellations and explicit aborts, no error dialog is shown
 - For script errors, the full error with stack trace is preserved for debugging
+- Nested choice aborts propagate back to the parent macro and stop the remaining macro commands
 
 ## Best Practices
 

docs/docs/QuickAddAPI.md

@@ -381,6 +381,8 @@ console.log("Enabled features:", features);
 ### `executeChoice(choiceName: string, variables?: {[key: string]: any}): Promise<void>`
 Executes another QuickAdd choice programmatically.
 
+When called from a macro or script that already has variables, QuickAdd snapshots the current variable map, applies the variables you pass for the child choice, runs that choice, and then restores the snapshot. This prevents `executeChoice()` from clearing unrelated variables owned by the surrounding flow.
+
 **Parameters:**
 - `choiceName`: Name of the choice to execute
 - `variables`: (Optional) Variables to pass to the choice

src/IChoiceExecutor.ts

@@ -1,9 +1,14 @@
 import type IChoice from "./types/choices/IChoice";
 import type { MacroAbortError } from "./errors/MacroAbortError";
+import type {
+	ChoiceExecutionContext,
+	ChoiceExecutionResult,
+} from "./engine/runtime";
 
 export interface IChoiceExecutor {
-	execute(choice: IChoice): Promise<void>;
+	execute(choice: IChoice): Promise<ChoiceExecutionResult>;
 	variables: Map<string, unknown>;
+	getExecutionContext?(): ChoiceExecutionContext | null;
 	/**
 	 * Records that the most recent choice execution aborted so orchestrators can react.
 	 * Engines that handle cancellations without throwing should call this immediately after