perf: replace synchronous I/O with async I/O and fix documentation linting

Co-authored-by: AbstergoSweden <249910473+AbstergoSweden@users.noreply.github.com>

Author: google-labs-jules[bot]

docs/ABOUT.md

@@ -6,7 +6,9 @@
 
 ## What is VY Prompt Master?
 
-**VY Prompt Master** is a prompt engineering framework designed for [Vy (Vercept)](https://vercept.com/) – an AI-powered macOS automation agent. It transforms high-level user task descriptions into detailed, executable YAML specifications that Vy can safely and predictably carry out.
+**VY Prompt Master** is a prompt engineering framework designed for [Vy (Vercept)](https://vercept.com/)
+– an AI-powered macOS automation agent. It transforms high-level user task descriptions into detailed,
+executable YAML specifications that Vy can safely and predictably carry out.
 
 ---
 
@@ -19,7 +21,8 @@ Modern AI agents can perform complex computer tasks, but without proper structur
 - **Debugging difficulties** – Hard to trace what went wrong
 - **Hallucination** – Claiming completion without verification
 
-VY Prompt Master solves these problems by enforcing a rigorous specification format where every action is:
+VY Prompt Master solves these problems by enforcing a rigorous specification format where every
+action is:
 
 - **Grounded in UI** – Tied to visible elements, not abstract concepts
 - **Verified** – Every action has observable success criteria

docs/AGENTS.md

@@ -1,34 +1,47 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
+
 - The repository is flat (no nested directories) and is primarily YAML and Markdown content.
-- Core personas/frameworks: `VY-Prompt-Engineering-Persona*.yaml`, `VY-Meta-Prompt.yaml`, `VY-Unified-Framework-v3.yaml`.
-- Task specs and examples: `vy_task*.yaml` for task definitions, `test_prompt*.yaml` for sample prompts.
-- Schema and docs: `vy-prompt-schema.json` and `Schema Overview.md` describe required fields and validation rules.
-- Supporting references: `knowledge *.txt`, `Response*.yml`, and `backup*.md` preserve research notes and prior outputs.
+- Core personas/frameworks: `VY-Prompt-Engineering-Persona*.yaml`, `VY-Meta-Prompt.yaml`,
+  `VY-Unified-Framework-v3.yaml`.
+- Task specs and examples: `vy_task*.yaml` for task definitions, `test_prompt*.yaml` for
+  sample prompts.
+- Schema and docs: `vy-prompt-schema.json` and `Schema Overview.md` describe required fields
+  and validation rules.
+- Supporting references: `knowledge *.txt`, `Response*.yml`, and `backup*.md` preserve research
+  notes and prior outputs.
 
 ## Build, Test, and Development Commands
+
 - There is no build or runtime step; this is a content repository.
 - Schema validation (convert YAML to JSON first) can be done with:
   `npx ajv validate -s vy-prompt-schema.json -d my-prompt.json`
 - For editor validation, add: `# yaml-language-server: $schema=./vy-prompt-schema.json`.
 
 ## Coding Style & Naming Conventions
+
 - Use 2-space indentation in YAML; avoid tabs and trailing whitespace.
 - Prefer `snake_case` keys and ids (e.g., `fallback_paths`, `inputs_missing`).
 - `step_id` naming pattern: `step_001_short_name`; input/assumption ids match `[a-z][a-z0-9_]*`.
-- For action steps, follow the `locate` → `confirm_target` → `act` → `verify_outcome` pattern and include `fallback_paths` and `safety_gate`.
+- For action steps, follow the `locate` → `confirm_target` → `act` → `verify_outcome` pattern and
+  include `fallback_paths` and `safety_gate`.
 
 ## Testing Guidelines
+
 - No automated tests are present; schema validation is the primary check.
 - Verify required top-level keys and that every step includes all required fields.
 - Use `test_prompt*.yaml` as regression references when adding or refactoring patterns.
 
 ## Commit & Pull Request Guidelines
+
 - This folder is not a Git repo, so there is no established commit history to mirror.
 - If you initialize Git, use short imperative commit messages (e.g., "Add schema validation note").
-- In PRs, include a brief description, list of changed prompt files, and validation evidence or manual review notes.
+- In PRs, include a brief description, list of changed prompt files, and validation evidence or
+  manual review notes.
 
 ## Security & Configuration Tips
+
 - Treat `.env` as local-only; do not paste secrets into docs or examples.
-- Avoid adding operational instructions that violate the safety boundaries documented in the persona files.
+- Avoid adding operational instructions that violate the safety boundaries documented in the
+  persona files.

docs/QUICK-REFERENCE.md

@@ -1,6 +1,7 @@
 # VY Meta Prompt - Quick Reference Guide
 
 ## Overview
+
 The **VY Meta Prompt** is a unified framework that consolidates all VY (Vercept) automation best practices into a single, streamlined specification for generating safe, deterministic, and robust UI automation prompts.
 
 **Version:** 2.0  
@@ -12,7 +13,8 @@ The **VY Meta Prompt** is a unified framework that consolidates all VY (Vercept)
 ## Quick Start: 5-Phase Workflow
 
 ### Phase 1: Intake & Classification
-```
+
+```text
 1. Receive user task description
 2. Classify via policy_router: allowed / disallowed / ambiguous / high_risk_irreversible
 3. Route appropriately:
@@ -23,7 +25,8 @@ The **VY Meta Prompt** is a unified framework that consolidates all VY (Vercept)
 ```
 
 ### Phase 2: Planning
-```
+
+```text
 1. Draft 2-3 internal approaches
 2. Evaluate: safety, reliability, reversibility, efficiency
 3. Decompose into UI action primitives (8-field steps)
@@ -32,7 +35,8 @@ The **VY Meta Prompt** is a unified framework that consolidates all VY (Vercept)
 ```
 
 ### Phase 3: Specification Generation
-```
+
+```text
 1. Use the standardized template structure
 2. Include all required keys (identity, purpose, context, inputs, task, constraints, output_format, self_check)
 3. Add assumption_ledger for non-blocking unknowns
@@ -42,7 +46,8 @@ The **VY Meta Prompt** is a unified framework that consolidates all VY (Vercept)
 ```
 
 ### Phase 4: Validation
-```
+
+```text
 Run all four validation categories:
 
 ✓ Schema Tests: All required keys present, correct types
@@ -54,7 +59,8 @@ Execute self_check questions (all 10 must pass)
 ```
 
 ### Phase 5: Output
-```
+
+```text
 If inputs_missing → output ONLY inputs_missing YAML list
 If validation fails → return to planning with issues
 If validation passes → emit pure YAML only (no preamble, commentary, code fences)
@@ -93,7 +99,8 @@ Every step **MUST** include these fields:
 
 ## Critical Rules
 
-### ✅ DO:
+### ✅ DO
+
 - **ALWAYS** use locate→confirm→act→verify pattern
 - **ALWAYS** provide fallback paths for critical steps
 - **ALWAYS** document assumptions in assumption_ledger
@@ -103,7 +110,8 @@ Every step **MUST** include these fields:
 - **ALWAYS** use unique UI identifiers (button text, field labels)
 - **ALWAYS** capture observable evidence for verification
 
-### ❌ NEVER:
+### ❌ NEVER
+
 - **NEVER** claim tool access ("I clicked X") - only instruct ("VY should click X")
 - **NEVER** use vague references ("the button", "the field")
 - **NEVER** skip verify_outcome steps
@@ -119,13 +127,15 @@ Every step **MUST** include these fields:
 ## Platform-Specific Conventions
 
 ### macOS
+
 - **Keyboard:** Use Command (cmd) key, NOT Control (ctrl)
 - **Launch Apps:** Use `open_application` tool, NOT clicking Dock
 - **File Operations:** Use Finder integration tools
 - **Sliders:** Use percentage positioning (e.g., "slider at 45%")
 - **Paths:** Use tilde (~) for home directory
 
 ### Web Automation
+
 - **Navigation:** Use `open_url` tool, NOT typing in address bar
 - **Google:** Use `google_search` tool directly
 - **Forms:** ALWAYS erase pre-existing text before typing
@@ -139,30 +149,38 @@ Every step **MUST** include these fields:
 ## Failure Playbooks
 
 ### 1. ui_not_found
+
 **Detection:** Element not found after 2 attempts  
 **Response:**
+
 1. Execute fallback_paths in priority order
 2. Attempt search within app/menu
 3. Reposition mouse and retry
 4. Capture screenshot → request user clarification
 
 ### 2. unexpected_modal
+
 **Detection:** Modal interrupts workflow  
 **Response:**
+
 1. Identify title and button labels
 2. Prefer cancel/close unless required
 3. If destructive wording → require user confirmation
 
 ### 3. auth_blocked
+
 **Detection:** Login prompt or session expiration  
 **Response:**
+
 1. Halt automation immediately
 2. Request manual login: "Authentication required. Please log in manually to proceed."
 3. Resume from last checkpoint after confirmation
 
 ### 4. verification_failed
+
 **Detection:** verify_outcome not met  
 **Response:**
+
 1. Wait 250ms and retry
 2. Check for modals/notifications
 3. Re-locate element
@@ -173,24 +191,29 @@ Every step **MUST** include these fields:
 ## Validation Tests Checklist
 
 ### Schema Tests
-- [ ] All 8 required keys present (identity, purpose, context, inputs, task, constraints, output_format, self_check)
+
+- [ ] All 8 required keys present (identity, purpose, context, inputs, task, constraints,
+  output_format, self_check)
 - [ ] No unknown top-level keys
 - [ ] Correct data types (lists for steps, strings for identity, etc.)
 
 ### UI Tests
+
 - [ ] Every action step has locate + confirm_target + verify_outcome
 - [ ] locate uses unique identifiers (button text, field label, etc.)
 - [ ] All irreversible steps have safety_gate == irreversible_requires_confirmation
 - [ ] Platform conventions followed (macOS shortcuts)
 - [ ] Critical steps have fallback paths
 
 ### Safety Tests
+
 - [ ] No bypass/jailbreak/evasion content
 - [ ] No credential harvesting or secret collection
 - [ ] Manual authentication specified if needed
 - [ ] User confirmation required for destructive actions
 
 ### Determinism Tests
+
 - [ ] No claims of completed actions (only instructions)
 - [ ] No vague verbs ('handle it', 'process it')
 - [ ] Concrete actions with exact parameters
@@ -211,6 +234,7 @@ assumptions:
 ```
 
 **Mandatory Assumptions:**
+
 - vy_local_agent_presence
 - vy_ui_grounding_capability
 - macOS_environment_conventions
@@ -230,6 +254,7 @@ evidence_ledger:
 ```
 
 **Capture Timing:**
+
 - Before critical UI state changes
 - After every verify_outcome step
 - Before user confirmation prompts
@@ -256,6 +281,7 @@ evidence_ledger:
 **Determinism:** Avoid ambiguous language, use enumerated steps and observable evidence
 
 ### ✅ Valid Output
+
 ```yaml
 ---
 identity: "VY Task Executor"
@@ -264,6 +290,7 @@ purpose: "Extract data from website"
 ```
 
 ### ❌ Invalid Output
+
 ```yaml
 # DON'T: Include preamble
 Here is the prompt specification:
@@ -280,6 +307,7 @@ identity: "VY Task Executor"
 ## Common Patterns
 
 ### Multi-Phase Workflow
+
 ```yaml
 task:
   goal: "Complete complex data entry task"
@@ -297,6 +325,7 @@ task:
 ```
 
 ### Conditional Branching
+
 ```yaml
 - step_id: "decision_001"
   intent: "Check if user is logged in"