siesa-agents 2.1.36 → 2.1.37

package/bmad-core/tasks/create-user-guide.md

@@ -1,605 +0,0 @@
-<!-- Powered by BMAD" Core -->
-
-# Create User Guide Task
-
-## Purpose
-
-To generate a comprehensive, user-facing guide that explains how to use the system from an end-user perspective. This guide should be written in clear, non-technical language and focus on practical usage instructions, workflows, and common scenarios. Unlike technical documentation (README, architecture docs), this guide is intended for the final user of the application.
-
-## Prerequisites
-
-- PRD documents exist in `docs/prd/`
-- Core workflows are defined in `docs/architecture/core-workflows.md`
-- The system has functional features ready for end-user documentation
-
-## Language Requirements
-
-**IMPORTANT:** When executing this task, the agent **MUST** interact with the user in **Spanish**, regardless of the language used in previous conversations. All questions, clarifications, and status updates should be in Spanish.
-
-**Output Languages:** This task produces user guides in TWO languages:
-- **Spanish** (`es/`) - Primary version
-- **English** (`en/`) - Translated version
-
-Both versions must have identical content and structure, differing only in language.
-
----
-
-## SEQUENTIAL Task Execution (Do not proceed until current Task is complete)
-
-### 1. Load Core Configuration and Gather Context
-
-#### 1.1 Load Configuration
-
-- Load `.bmad-core/core-config.yaml` from the project root
-- If the file does not exist, ask the user for the documentation output location (default: `docs/user-guide/`)
-- Extract key configurations: `prd.*`, `architecture.*`
-
-#### 1.2 Identify Target Audience
-
-Ask the user to clarify the target audience (in Spanish):
-
-- "¿Cuál es la audiencia principal para esta guía de usuario?"
-  - Usuarios finales (clientes que usan la aplicación)
-  - Administradores (usuarios que gestionan el sistema)
-  - Ambos (usuarios finales y administradores)
-  - Consumidores de API (desarrolladores que integran con el sistema)
-
-#### 1.3 Check for Existing User Guides
-
-Before proceeding, check for existing user guide files:
-
-1. Scan the documentation directory (default: `docs/`) for existing user guides:
-   - `docs/user-guide.md`
-   - `docs/user-guide/*.md`
-   - `docs/user-guide/es/*.md` (Spanish guides)
-   - `docs/user-guide/en/*.md` (English guides)
-   - `docs/user-guide-*.md` (e.g., `user-guide-admin.md`, `user-guide-enduser.md`)
-   - Any files matching pattern `*user*guide*.md`
-
-2. If existing user guides are found, present them to the user (in Spanish):
-   - "He encontrado las siguientes guías de usuario existentes: [listar archivos con su audiencia objetivo si es identificable]"
-   - Preguntar: "¿Cómo desea proceder?"
-     - **Crear una nueva guía separada** - Crear una nueva guía con un nombre distintivo para la audiencia seleccionada
-     - **Actualizar una guía existente** - Modificar una de las guías existentes (especificar cuál)
-     - **Reemplazar una guía existente** - Sobrescribir una guía existente (requiere confirmación explícita)
-     - **Cancelar** - Detener y revisar la documentación existente primero
-
-3. If user chooses to create a new separate guide:
-   - **Automatically select** the filename based on target audience (do NOT ask for confirmation):
-     - End users: `user-guide/es/enduser-guide.md` + `user-guide/en/enduser-guide.md`
-     - Administrators: `user-guide/es/admin-guide.md` + `user-guide/en/admin-guide.md`
-     - API consumers: `user-guide/es/api-guide.md` + `user-guide/en/api-guide.md`
-     - Mixed: `user-guide/es/complete-guide.md` + `user-guide/en/complete-guide.md`
-   - Inform the user of the selected filename: "Se utilizará el nombre de archivo: [filename]"
-
-4. If user chooses to replace an existing guide:
-   - Require explicit confirmation (in Spanish): "¿Está seguro de que desea reemplazar [filename]? Esta acción no se puede deshacer. (sí/no)"
-   - Only proceed with explicit "sí" or "yes" confirmation
-
-5. Record the chosen action and target filename for use in step 7
-
-### 2. Gather Product Information
-
-#### 2.1 Identify Available Epics and Select Scope
-
-Before reading documentation, identify and present available epics to the user:
-
-1. Scan the `docs/prd/` directory for epic files (e.g., `epic-1.md`, `epic-2.md`, etc.)
-
-2. Present the list of available epics to the user (in Spanish):
-   - "He encontrado las siguientes épicas en el proyecto:"
-   - List each epic with its number and title (extracted from the file)
-   - Example format:
-     ```
-     - Epic 1: [Título del épico]
-     - Epic 2: [Título del épico]
-     - Epic 3: [Título del épico]
-     ...
-     ```
-
-3. Ask the user which epics to include (in Spanish):
-   - "¿Cuáles épicas desea incluir en la guía de usuario? Puede seleccionar:"
-     - **Todas las épicas** - Incluir todas las funcionalidades documentadas
-     - **Épicas específicas** - Seleccionar épicas individuales (proporcionar números separados por comas, ej: 1, 3, 5)
-     - **Excluir épicas específicas** - Incluir todos excepto las especificadas
-
-4. Record the selected epics for use in subsequent steps
-   - Only read and document features from the selected epics
-   - Stories from non-selected epics should be ignored
-
-#### 2.2 Review PRD Documents
-
-Based on `prdSharded` from config and the **selected epics from step 2.1**, locate and read PRD documents to understand:
-
-- **Product Overview**: Goals, background, and purpose from `docs/prd/goals-and-background-context.md`
-- **Requirements**: Functional requirements from `docs/prd/requirements.md`
-- **User Interface**: UI design goals from `docs/prd/user-interface-design-goals.md`
-- **Epic Definitions**: Feature sets from **selected epic files only** (as determined in step 2.1)
-
-Extract:
-- System purpose and value proposition (in user terms)
-- Key features and capabilities
-- User roles and permissions
-- Primary use cases
-
-#### 2.2 Review Core Workflows
-
-Read `docs/architecture/core-workflows.md` to understand:
-
-- Primary user journeys
-- Step-by-step processes users will follow
-- Decision points and branching paths
-- Expected outcomes for each workflow
-
-#### 2.3 Review UI Components (if applicable)
-
-If frontend exists, review `docs/architecture/components.md` to understand:
-
-- Available screens and pages
-- Navigation structure
-- Key UI elements users will interact with
-
-### 3. Elicit Additional Information
-
-Present findings to the user and ask clarifying questions (in Spanish):
-
-1. "Basándome en las épicas seleccionadas ([listar épicas]), he identificado estas funcionalidades principales: [lista]. ¿Hay alguna funcionalidad que deba excluirse de la guía de usuario?"
-2. "¿Hay escenarios o casos de uso específicos que sean particularmente importantes de documentar?"
-3. "¿Cuál es el nivel de competencia técnica esperado de sus usuarios?" (Novato / Intermedio / Mixto)
-4. "¿Hay limitaciones conocidas o advertencias que los usuarios deban conocer?"
-5. "¿Debería incluir la guía secciones de solución de problemas?"
-
-### 4. Structure the User Guide
-
-Create the user guide with the following structure:
-
-```markdown
-# [Product Name] User Guide
-
-## Introduction
-- What is [Product Name]?
-- Who is this guide for?
-- How to use this guide
-
-## Getting Started
-- Prerequisites (what users need before starting)
-- First-time setup (if applicable)
-- Accessing the system
-- Overview of the interface
-
-## Core Concepts
-- Key terminology
-- Understanding [main concepts relevant to the product]
-- User roles and permissions (if applicable)
-
-## Features and How to Use Them
-
-### [Feature 1]
-- What it does
-- **Diagram**: [Feature diagram showing key components/flow]
-- [Screenshot: FEATURE_NAME - Brief description of what to capture]
-- Step-by-step instructions
-- Tips and best practices
-- Common scenarios
-
-### [Feature 2]
-...
-
-## Common Workflows
-
-### [Workflow 1: e.g., "Managing Your First Application"]
-- **Workflow Diagram**: [Flowchart or sequence diagram showing the complete workflow]
-- [Screenshot: WORKFLOW_STEP_1 - Description of key step to capture]
-1. Step-by-step walkthrough
-   - [Screenshot: WORKFLOW_STEP_N - Description for each key step]
-2. Expected results
-3. What to do if something goes wrong
-
-### [Workflow 2]
-...
-
-## Troubleshooting (if requested)
-- Common issues and solutions
-- Error messages and what they mean
-- When to contact support
-
-## FAQ
-- Frequently asked questions based on requirements
-
-## Glossary
-- Terms and definitions
-
-## Appendix (if needed)
-- Quick reference tables
-- Keyboard shortcuts
-- Additional resources
-
-## Screenshot Index
-
-This section lists all screenshots that need to be added to this guide. Once a screenshot is added, update the corresponding placeholder with the actual image.
-
-| ID | Location | Description | Status |
-|----|----------|-------------|--------|
-| FEATURE_NAME_1 | Section X.X | Brief description of what the screenshot should show | Pending |
-| WORKFLOW_STEP_1 | Section Y.Y | Brief description of the workflow step to capture | Pending |
-| ... | ... | ... | ... |
-
-**Instructions for adding screenshots:**
-1. Capture the screenshot as described in the "Description" column
-2. Save the image in `docs/user-guide/[lang]/images/` with the ID as filename (e.g., `FEATURE_NAME_1.png`)
-3. Replace the placeholder `[Screenshot: ID]` with `![Description](./images/ID.png)`
-4. Update the "Status" column to "Added"
-```
-
-### 5. Generate User Guide Content
-
-#### 5.1 Writing Guidelines
-
-When writing content, follow these principles:
-
-- **Use plain language**: Avoid technical jargon; explain concepts in terms users understand
-- **Be task-oriented**: Focus on what users want to accomplish, not how the system works internally
-- **Use active voice**: "Click the Submit button" not "The Submit button should be clicked"
-- **Include visual cues**: Reference UI elements by their labels (bold text for buttons, menus)
-- **Provide context**: Explain WHY users might want to do something, not just HOW
-- **Use numbered steps**: For sequential instructions, use numbered lists
-- **Include examples**: Where helpful, provide concrete examples of inputs/outputs
-- **Note prerequisites**: Before each task, list what the user needs to have ready
-
-#### 5.2 Content Generation Rules
-
-- **DO NOT** include technical implementation details (API endpoints, database schemas, code)
-- **DO NOT** reference internal architecture or system design
-- **DO NOT** include developer-focused information (build steps, environment setup for development)
-- **DO NOT** invent or assume feature behaviors - every description must be backed by documentation
-- **DO** focus on user goals and outcomes
-- **DO** explain error messages in user-friendly terms
-- **DO** include "what happens next" after each major action
-- **DO** cite source documents for ALL feature descriptions, definitions, and workflows (see 5.3)
-
-#### 5.3 Source Citation Requirements (MANDATORY)
-
-Every feature definition, workflow explanation, or capability description **MUST** include a source citation. This ensures accuracy and traceability.
-
-**Citation Format:**
-- For epic-level information: `[Source: Epic X]`
-- For story-level information: `[Source: Epic X Story Y]`
-- For PRD sections: `[Source: PRD - {section-name}]`
-- For multiple sources: `[Source: Epic X Story Y, Epic Z Story W]`
-
-**What Requires Citation:**
-- Feature descriptions and what they do
-- Workflow steps and expected behaviors
-- User role definitions and permissions
-- System capabilities and limitations
-- Error scenarios and their meanings
-
-**Example:**
-```markdown
-### Managing Credentials
-
-Users can create, view, update, and delete credentials through the Credentials
-Management interface. Each credential is associated with a specific application
-and can be configured with custom expiration policies. [Source: Epic 2 Story 3]
-
-#### Creating a New Credential
-
-1. Navigate to **Credentials** > **New Credential**
-2. Select the target application from the dropdown
-3. Enter the credential details...
-[Source: Epic 2 Story 3, Epic 2 Story 4]
-```
-
-**Verification:**
-- Before writing any feature or workflow content, first locate the corresponding epic/story file
-- Read the acceptance criteria and requirements from the source file
-- Only document behaviors explicitly stated in the source
-- If no source can be found for a feature, flag it to the user: "I could not find documentation for [feature]. Please provide the source or confirm this should be excluded."
-
-#### 5.4 Diagram Requirements (MANDATORY)
-
-Every feature and workflow **MUST** include a diagram to visually explain the concept. Diagrams help users understand complex processes at a glance.
-
-**Diagram Format:**
-- Use Mermaid syntax for all diagrams (compatible with most markdown renderers)
-- Diagrams must be in the same language as the surrounding content (Spanish for `es/`, English for `en/`)
-
-**Diagram Types by Content:**
-
-| Content Type | Recommended Diagram | Purpose |
-|--------------|---------------------|---------|
-| Feature overview | `flowchart` or `block-beta` | Show main components and relationships |
-| User workflow | `flowchart TD` | Show step-by-step process with decision points |
-| Sequential process | `sequenceDiagram` | Show interactions between user and system |
-| State changes | `stateDiagram-v2` | Show how data/entities change states |
-| User journey | `journey` | Show user experience across touchpoints |
-
-**Example - Feature Diagram:**
-```markdown
-### Gestión de Credenciales
-
-Esta funcionalidad permite crear, ver, actualizar y eliminar credenciales.
-
-```mermaid
-flowchart LR
-    A[Usuario] --> B{Acción}
-    B --> C[Crear]
-    B --> D[Ver]
-    B --> E[Actualizar]
-    B --> F[Eliminar]
-    C --> G[(Base de Datos)]
-    D --> G
-    E --> G
-    F --> G
-```
-
-[Source: Epic 2 Story 3]
-```
-
-**Example - Workflow Diagram:**
-```markdown
-### Flujo de Autenticación
-
-```mermaid
-sequenceDiagram
-    actor U as Usuario
-    participant A as Aplicación
-    participant S as Servidor
-
-    U->>A: Ingresa credenciales
-    A->>S: Envía solicitud de login
-    S-->>A: Retorna token JWT
-    A-->>U: Muestra dashboard
-```
-
-[Source: Epic 1 Story 2]
-```
-
-**Diagram Guidelines:**
-- Keep diagrams simple and focused (max 10-12 nodes for flowcharts)
-- Use clear, descriptive labels in user-friendly language
-- Include decision points (diamonds) for conditional flows
-- Show error paths when relevant to the user
-- Ensure diagram accurately reflects the documented behavior from epic/story sources
-
-**What NOT to include in diagrams:**
-- Technical implementation details (database schemas, API internals)
-- System architecture components invisible to users
-- Code-level abstractions
-
-#### 5.5 Screenshot Placeholder Requirements (MANDATORY)
-
-The agent must include screenshot placeholders throughout the document to guide reviewers on what visual aids to add. Screenshots will be added later by the person reviewing the guide.
-
-**Placeholder Format:**
-```
-[Screenshot: IDENTIFIER - Description of what to capture]
-```
-
-**Identifier Naming Convention:**
-- Use UPPER_SNAKE_CASE for identifiers
-- Prefix with context: `FEATURE_`, `WORKFLOW_`, `UI_`, `ERROR_`
-- Make identifiers unique and descriptive
-- Examples:
-  - `[Screenshot: FEATURE_CREDENTIALS_LIST - Vista de la lista de credenciales con filtros aplicados]`
-  - `[Screenshot: WORKFLOW_LOGIN_STEP2 - Pantalla de verificación de dos factores]`
-  - `[Screenshot: UI_DASHBOARD_MAIN - Panel principal después de iniciar sesión]`
-  - `[Screenshot: ERROR_INVALID_TOKEN - Mensaje de error cuando el token expira]`
-
-**Where to Add Screenshot Placeholders:**
-- After feature introductions (show the main UI for that feature)
-- At key steps in workflows (show the screen at each important step)
-- For complex UI elements that need visual explanation
-- For error messages and their resolution screens
-- For before/after comparisons when relevant
-
-**Screenshot Index (End of Document):**
-At the end of each user guide, include a "Screenshot Index" section that consolidates all placeholders:
-
-```markdown
-## Screenshot Index / Índice de Capturas de Pantalla
-
-| ID | Ubicación | Descripción | Estado |
-|----|-----------|-------------|--------|
-| FEATURE_CREDENTIALS_LIST | Sección 4.1 | Vista de la lista de credenciales con filtros | Pendiente |
-| WORKFLOW_LOGIN_STEP2 | Sección 5.2 | Pantalla de verificación de dos factores | Pendiente |
-```
-
-**Guidelines:**
-- Add 1-3 screenshot placeholders per feature section
-- Add screenshot placeholders for each major step in workflows
-- Descriptions should be specific enough for someone else to capture the correct screen
-- Use the same language as the document (Spanish descriptions in `es/`, English in `en/`)
-- Track all placeholders in the Screenshot Index for easy reference
-
-### 6. Review and Validation
-
-#### 6.1 Self-Check
-
-Before finalizing, verify:
-
-- [ ] All major features from the PRD are covered
-- [ ] Instructions are clear enough for a new user
-- [ ] No technical jargon remains unexplained
-- [ ] All referenced UI elements exist and are named correctly
-- [ ] Workflows match actual system behavior
-- [ ] Troubleshooting covers common error scenarios
-- [ ] **Every feature description has a source citation** `[Source: Epic X Story Y]`
-- [ ] **Every workflow explanation has a source citation**
-- [ ] **No undocumented features are described** (if source not found, flagged to user)
-- [ ] Source citations reference actual existing epic/story files
-- [ ] **Every feature includes a Mermaid diagram** explaining its components/flow
-- [ ] **Every workflow includes a Mermaid diagram** showing the process
-- [ ] Diagrams are in the correct language (Spanish in `es/`, English in `en/`)
-- [ ] Diagrams are simple, user-focused, and free of technical implementation details
-- [ ] **Every feature has screenshot placeholders** with format `[Screenshot: ID - Description]`
-- [ ] **Every workflow has screenshot placeholders** for key steps
-- [ ] Screenshot placeholders have unique UPPER_SNAKE_CASE identifiers
-- [ ] **Screenshot Index exists at end of document** listing all placeholders with locations
-
-#### 6.2 Present Draft to User
-
-Present the completed draft and ask (in Spanish):
-
-1. "¿Cubre esto todas las funcionalidades que sus usuarios necesitan conocer?"
-2. "¿Es el lenguaje apropiado para su audiencia objetivo?"
-3. "¿Hay secciones que necesiten más detalle o ejemplos?"
-4. "¿Debería agregar marcadores de posición para capturas de pantalla en secciones específicas?"
-
-### 7. Finalize and Save
-
-#### 7.1 Apply Filename Decision from Step 1.3
-
-- Use the target filename and action determined in step 1.3
-- If creating a new guide or replacing (with confirmation), proceed with save
-- If updating an existing guide, merge new content appropriately while preserving existing customizations
-
-#### 7.2 Save the User Guide (Both Languages)
-
-Save user guides in BOTH Spanish and English using the following folder structure:
-
-**Standard Structure (single file per language):**
-```
-docs/user-guide/
-├── es/
-│   └── [audience]-guide.md      (e.g., admin-guide.md, enduser-guide.md)
-├── en/
-│   └── [audience]-guide.md
-└── index.md                      (language selector / navigation)
-```
-
-**Extended Structure (sharded, for extensive guides):**
-```
-docs/user-guide/
-├── es/
-│   └── [audience]/
-│       ├── index.md
-│       ├── getting-started.md
-│       ├── features/
-│       │   └── [feature-name].md
-│       ├── workflows/
-│       │   └── [workflow-name].md
-│       └── troubleshooting.md
-├── en/
-│   └── [audience]/
-│       ├── index.md
-│       ├── getting-started.md
-│       ├── features/
-│       │   └── [feature-name].md
-│       ├── workflows/
-│       │   └── [workflow-name].md
-│       └── troubleshooting.md
-└── index.md
-```
-
-Where `[audience]` matches the target audience (e.g., `admin`, `enduser`, `api`)
-
-**Process:**
-1. First, generate the complete user guide content in Spanish
-2. Then, translate the content to English maintaining identical structure
-3. Ensure source citations `[Source: Epic X Story Y]` remain unchanged in both versions
-4. Save both versions to their respective language folders
-
-#### 7.3 Update User Guide Index (Language Selector)
-
-Create or update `docs/user-guide/index.md` with language selection and guide navigation:
-
-```markdown
-# User Guides / Guías de Usuario
-
-## Select Language / Seleccionar Idioma
-
-| Language | Idioma |
-|----------|--------|
-| [English](./en/) | [Español](./es/) |
-
----
-
-## Available Guides / Guías Disponibles
-
-### English
-
-| Guide | Audience | Description |
-|-------|----------|-------------|
-| [Guide Name](./en/[audience]-guide.md) | [Audience] | [Brief description] |
-
-### Español
-
-| Guía | Audiencia | Descripción |
-|------|-----------|-------------|
-| [Nombre de Guía](./es/[audience]-guide.md) | [Audiencia] | [Descripción breve] |
-```
-
-#### 7.4 Provide Summary
-
-Provide summary to user (in Spanish):
-
-- Acción realizada: [Creado nuevo / Actualizado existente / Reemplazado]
-- Ubicación de guías:
-  - Español: `[ruta del archivo en español]`
-  - English: `[ruta del archivo en inglés]`
-- Audiencia objetivo: [audiencia identificada]
-- Épicas incluidas: [listar épicas seleccionadas, ej: Epic 1, Epic 3, Epic 5]
-- Épicas excluidas: [listar épicas no incluidas, si aplica]
-- Funcionalidades documentadas: [cantidad]
-- Flujos de trabajo documentados: [cantidad]
-- Diagramas incluidos: [cantidad]
-- Capturas de pantalla sugeridas: [cantidad] (ver Índice de Capturas de Pantalla al final del documento)
-- Otras guías existentes: [listar otras guías de usuario en el proyecto]
-- Próximos pasos recomendados:
-  - Revisar con usuarios finales reales para obtener retroalimentación
-  - Agregar capturas de pantalla o ayudas visuales donde se indique
-  - Establecer un ciclo de revisión para mantener la guía actualizada
-  - Considerar crear guías adicionales específicas por audiencia si es necesario
-  - Verificar que ambas versiones (español e inglés) estén sincronizadas
-
-## Success Criteria
-
-- User guide is written in non-technical, user-friendly language
-- All major features and workflows are documented
-- Instructions are actionable and verifiable
-- Document is structured for easy navigation
-- Content is traceable to PRD requirements
-- Guide is appropriate for the identified target audience
-- Existing user guides are preserved unless explicit replacement is confirmed
-- Multiple audience-specific guides can coexist with clear organization
-- User guide index is maintained when multiple guides exist
-- **Every feature and workflow description includes source citation** in format `[Source: Epic X Story Y]`
-- **No content is invented** - all descriptions are backed by epic/story documentation
-- **Only selected epics are documented** - user explicitly chose which epics to include
-- **Every feature includes a Mermaid diagram** explaining its components or flow
-- **Every workflow includes a Mermaid diagram** showing the complete process
-- **Diagrams are localized** - Spanish labels in `es/`, English labels in `en/`
-- **Every feature and workflow has screenshot placeholders** with format `[Screenshot: ID - Description]`
-- **Screenshot Index exists at end of document** consolidating all placeholders for reviewers
-- **Both Spanish and English versions are generated** with identical content and structure
-- **Language folder structure** (`es/`, `en/`) is properly created and maintained
-- **Index file includes language selector** for easy navigation between versions
-
-## Notes
-
-- This task creates documentation for END USERS, not developers
-- The guide should be usable by someone with no knowledge of the underlying technology
-- Focus on user outcomes and business value, not technical implementation
-- Keep the guide maintainable by linking to single sources of truth where possible
-- Consider versioning the guide alongside product releases
-- **Multiple Guides**: A project may have separate guides for different audiences (admins, end users, API consumers). Each should be clearly named and organized
-- **Never Auto-Replace**: Always check for existing guides and require explicit user confirmation before replacing any existing documentation
-- **Language Requirements**:
-  - Agent interaction with users must be in **Spanish** during task execution
-  - Output is generated in **both Spanish and English**
-  - Spanish version is created first, then translated to English
-  - Source citations `[Source: Epic X Story Y]` remain in original format (not translated)
-  - Both versions must be kept synchronized when updates are made
-- **Diagram Requirements**:
-  - Every feature and workflow MUST have a Mermaid diagram
-  - Diagrams must be user-focused, not technical
-  - Diagram labels must be in the same language as the document (Spanish/English)
-  - Use appropriate diagram types: flowcharts for processes, sequence diagrams for interactions
-  - Keep diagrams simple (max 10-12 nodes) for readability
-- **Screenshot Requirements**:
-  - Include placeholders with format `[Screenshot: ID - Description]`
-  - Use UPPER_SNAKE_CASE identifiers with prefixes: `FEATURE_`, `WORKFLOW_`, `UI_`, `ERROR_`
-  - Descriptions must be specific enough for reviewers to capture the correct screen
-  - Screenshot Index at end of document consolidates all placeholders
-  - Reviewers will add actual screenshots later following the index instructions