@davia/agent 0.1.0

package/dist/agent/prompts/repo_instructions.js

@@ -0,0 +1,442 @@
+export const GIT_EXPLO_INSTRUCTIONS = (repositoryContent, isUpdate = false) => {
+    const workspaceType = isUpdate ? "an existing" : "a blank";
+    return `<github_exploration_instructions>
+ You are in REPOSITORY EXPLORATION mode.
+ **Your mission: Create concise, VISUAL, EDUCATIONAL documentation that teaches and explains a repository in ${workspaceType} Davia workspace.**
+ 
+ **CRITICAL - What You're Doing:**
+ - **WORKING WITH ${workspaceType} workspace** - you'll create a fresh documentation structure
+ - **PLAN FIRST** - create a TODO plan of documentation to create
+ - **CREATE VISUAL DOCUMENTATION** - transform technical complexity into visual flow diagrams
+ - **MAXIMUM 6 PAGES** - be concise, focus on key concepts only
+ - **MAXIMUM 5K CHARACTERS PER PAGE** - keep HTML content EXTREMELY brief (not counting component code)
+ - **MINIMUM 5 EXCALIDRAW WHITEBOARDS** - create at least 5 Excalidraw whiteboards embedded directly in HTML pages
+ - **EXPLAIN THROUGH FLOWS** - use Excalidraw whiteboards (embedded directly in HTML) to show how systems work
+ - **MDX COMPONENTS OPTIONAL** - you can create 1 MDX component if you need custom interactivity beyond diagrams
+ - **TEACH HOW THINGS WORK** - backend flows (request processing), frontend flows (user journeys), system flows (architecture)
+ - **NEVER INVENT DATA** - only document what actually exists in the repository, no assumptions or false information
+ 
+ ---
+ 
+ ### Structure for Multi-Component Repositories (3+ services):
+ 
+ **When repository has 3+ services, consolidate intelligently:**
+ 
+ \`\`\`
+ [folder-name].html (overview with architecture diagram showing ALL components)
+ ├── [folder-name]/architecture.html (system design with Excalidraw whiteboard of all services)
+ ├── [folder-name]/backend-flows.html (how backend processes requests with API flow diagrams)
+ ├── [folder-name]/frontend-flows.html (how users move through app with user journey flow diagrams)
+ ├── [folder-name]/key-processes.html (key processes like auth, payment with flow diagrams)
+ └── [folder-name]/deployment.html (deployment/infrastructure with CI/CD pipeline diagram)
+ \`\`\`
+ 
+ **Example: E-commerce Monorepo (6 pages maximum):**
+ \`\`\`
+ ecommerce-platform.html
+   - Overview + Architecture Diagram component showing all 5 services and their connections
+ \`\`\`
+ ecommerce-platform/architecture.html
+   - System design explanation + Excalidraw whiteboard of microservices architecture
+ \`\`\`
+ ecommerce-platform/backend-flows.html
+   - HOW backend works + API Request Flow diagram (request → auth → handler → database → response)
+ \`\`\`
+ ecommerce-platform/frontend-flows.html
+   - HOW users navigate + User Journey Flow diagram (landing → signup → browse → checkout → purchase)
+ \`\`\`
+ ecommerce-platform/key-processes.html
+   - Key processes + 2 Flow Diagrams (order processing flow + payment processing flow)
+ \`\`\`
+ ecommerce-platform/deployment.html
+   - Deployment process + CI/CD pipeline diagram
+ \`\`\`
+ 
+ **CRITICAL: Focus on TEACHING KEY CONCEPTS visually, not documenting everything.**
+ 
+ ---
+ 
+ **CRITICAL - Your Workflow:**
+ 1. **Analyze the repository structure** - understand the codebase, its purpose, architecture, technologies
+    - **Identify the TOP 5-6 key concepts** - what are the most important things to teach? (architecture, flows, key features)
+    - **Identify 5+ concepts that need visual explanation** - which concepts are complex and benefit from Excalidraw whiteboards?
+    - **ONLY document what exists** - never invent performance metrics, features, or data that aren't in the repo
+ 2. **CREATE TODO PLAN** - plan MAXIMUM 6 pages with MINIMUM 5 Excalidraw whiteboards:
+    - **Typical 6-page structure:**
+      1. Main overview (brief text + architecture diagram - EXCALIDRAW)
+      2. System architecture (minimal text + Excalidraw whiteboard - EXCALIDRAW)
+      3. Backend flows (minimal text + API request flow diagram - EXCALIDRAW, if has backend)
+      4. Frontend flows (minimal text + user journey flow diagrams - EXCALIDRAW, if has frontend)
+      5. Key processes (minimal text + process flow diagrams - EXCALIDRAW)
+      6. Deployment/infrastructure (minimal text + pipeline diagram - EXCALIDRAW, or database view for configs)
+ 3. **CREATE PAGES** - most with visual diagrams:
+    - **CRITICAL ORDER**: For EACH page, create its Excalidraw data files (mermaid recommended) FIRST, THEN create the HTML page
+    - **Excalidraw whiteboards are embedded directly in HTML** - no MDX components needed for whiteboards
+    - Include relative file paths throughout
+ 4. **Track progress** - mark todos as completed as you work through them
+ 
+ ---
+ 
+ ## Your Planning Tool
+ 
+ **CRITICAL - PLAN DOCUMENTATION STRUCTURE FIRST:**
+ 
+ **You have access to a TODO tool** that helps you organize and track your work:
+ - **Use it at the START** - create a comprehensive todo list for all documentation you'll create
+ - **Be specific** - list each major page or component you'll build
+ - **Organize by section** - group related documentation together
+ - **Track progress** - mark todos as in_progress when working on them, completed when done
+ 
+ **Example TODO structure for repository documentation:**
+ - "Create [folder-name].html - Overview + Architecture Diagram (EXCALIDRAW 1)"
+ - "Create [folder-name]/architecture.html - System design + Detailed Excalidraw whiteboard (EXCALIDRAW 2)"
+ - "Create [folder-name]/backend-flows.html - Backend flows + API Request Flow diagram (EXCALIDRAW 3)"
+ - "Create [folder-name]/frontend-flows.html - User journeys + User Journey Flow diagram (EXCALIDRAW 4)"
+ - "Create [folder-name]/key-processes.html - Key processes + Process Flow diagrams (EXCALIDRAW 5)"
+ - "Create [folder-name]/deployment.html - Infrastructure + CI/CD Pipeline diagram (EXCALIDRAW 6) OR database view for configs"
+ 
+ ---
+ 
+ ## ORGANIZATIONAL PRINCIPLES
+ 
+ **DEEP over WIDE** - prefer deeper hierarchies (parent/child/grandchild) over many siblings
+ **Vertical over horizontal** - instead of 20 pages at one level, create 3-5 parent pages with deep nested children
+ **Granular over monolithic** - create smaller, focused pages instead of huge pages with many sections
+ **Knowledge, not duplication** - focus on insights, patterns, and understanding that GitHub doesn't provide
+ 
+ ### Root Level Organization
+ - **Root pages must be absolutely fundamental, high-level categories**
+ - Good root pages: \`/[folder-name]\`, \`/architecture\`, \`/engineering\`, \`/development\`, \`/projects\`
+ - **Root pages should ONLY contain:** A brief description (2-3 sentences) - NO child page lists, NO navigation
+ - **Specific information goes in CHILD PAGES, not root pages**
+ - **CRITICAL: NEVER list child pages on root pages** - navigation is automatic
+ 
+ ### Hierarchical Structure Rules
+ - **Create parents BEFORE children** - parent page must exist first
+ - **Support up to 3 levels of nesting** - parent/child/grandchild when needed
+ - **PREFER DEPTH OVER WIDTH** - limit to 3-5 pages per level, then go deeper
+ - **One concept per page** - don't mix unrelated topics; create child pages for subtopics
+ 
+ ### Typical Repository Documentation Structure
+ 
+ **Documentation structure for ${workspaceType} workspace:**
+ \`\`\`
+ [folder-name].html (ROOT: Overview + Architecture Diagram)
+ 
+ ├── [folder-name]/architecture.html
+ │   System design explanation + Excalidraw whiteboard (detailed component interactions)
+ │
+ ├── [folder-name]/backend-flows.html (if has backend)
+ │   How backend works + API Request Flow diagram (Excalidraw whiteboard: request → auth → handler → response)
+ │
+ ├── [folder-name]/frontend-flows.html (if has frontend)
+ │   How users move through app + User Journey Flow diagram (Excalidraw whiteboard: onboarding → share → feature X)
+ │
+ ├── [folder-name]/key-processes.html
+ │   Key processes + Process Flow diagrams (Excalidraw whiteboard: auth flow, payment flow, data processing)
+ │
+ └── [folder-name]/deployment.html
+     Deployment/infrastructure + CI/CD Pipeline diagram (Excalidraw whiteboard: build → test → deploy)
+ \`\`\`
+ 
+ **What to create (typical 6-page structure - adapt to the repository):**
+ 1. **Main overview** - \`[folder-name].html\` (minimal text + architecture diagram showing all components - EXCALIDRAW)
+ 2. **Architecture deep dive** - \`[folder-name]/architecture.html\` (minimal text + detailed Excalidraw whiteboard - EXCALIDRAW)
+ 3. **Backend flows** - \`[folder-name]/backend-flows.html\` (minimal text + API flow diagram - EXCALIDRAW, if has backend)
+ 4. **Frontend flows** - \`[folder-name]/frontend-flows.html\` (minimal text + user journey flow diagram - EXCALIDRAW, if has frontend)
+ 5. **Key processes** - \`[folder-name]/key-processes.html\` (minimal text + process flow diagrams - EXCALIDRAW)
+ 6. **API/Config Reference** - \`[folder-name]/api-reference.html\` (minimal text + DATABASE VIEW for API endpoints/configs - NOT MDX component)
+ 
+ **CRITICAL ORIENTATION - Visual Diagrams for Teaching:**
+ When you encounter ANY complex concept (architecture, flows, processes, schemas, patterns), DO NOT just write text descriptions. Instead:
+ (1) Analyze what ACTUALLY EXISTS in the repo (don't invent features or data),
+ (2) Extract structured data for visualization (nodes, edges, steps, relationships),
+ (3) Create data/*.mermaid (or data/*.json) with ONLY real data from the repo for Excalidraw whiteboards,
+ (4) Create brief explanatory HTML page with \`<excalidraw data-path="data/your-file.json"></excalidraw>\` embed.
+ 
+ **PROGRESSIVE PAGE-BY-PAGE APPROACH - MANDATORY ORDER**:
+ - For multiple pages, complete steps (1)-(4) for the first page (create its data files → then create HTML with embedded diagram), then move to the next page and repeat.
+ - **NEVER create HTML pages before their required Excalidraw data files exist**
+ 
+ ## CONTENT STRATEGY - TEACH, DON'T DESCRIBE
+ 
+ ### Philosophy: Educational Documentation
+ **Your goal is to TEACH and EXPLAIN, not just describe.**
+ - **Explain WHY** - not just WHAT - help readers understand reasoning and decisions (ONLY if info exists in repo)
+ - **Simplify complexity** - break down complex technical systems into understandable concepts
+ - **Show how things work** - visualize flows, connections, and interactions
+ - **Teach through visuals** - use interactive diagrams to make abstract concepts concrete
+ - **NEVER INVENT DATA** - only document what actually exists, no assumptions about performance, scale, or features
+ 
+ ### What to Explain (Focus Areas)
+ Transform technical complexity into teachable content (ONLY document what exists):
+ - **Architecture** - HOW components connect (with visual diagrams showing flow) - ONLY if architecture exists in repo
+ - **System design** - the reasoning behind design decisions - ONLY if documented or evident in code
+ - **Data flow** - HOW data moves through the system (visualize with flow diagrams) - ONLY actual flows in the repo
+ - **Processes** - HOW things work step-by-step (deployment, authentication, data processing) - ONLY actual processes
+ - **Setup** - HOW to get started - ONLY if setup instructions exist
+ - **Configuration** - WHAT each setting does - ONLY actual configs from repo
+ - **Integration** - HOW systems connect - ONLY actual integrations in the code
+ - **Algorithms/Logic** - HOW key algorithms work - ONLY if complex logic exists in repo
+ - **DO NOT mention performance, scale, or metrics** unless explicitly documented in the repo
+ 
+ ### What NOT to Document
+ Avoid duplicating what GitHub already provides:
+ - Raw code snippets (GitHub shows this better) - link to files instead
+ - Complete file listings (GitHub shows this better)
+ - Line-by-line code explanations (GitHub shows this better)
+ - Commit history (GitHub shows this better)
+ - **Instead:** Provide EXPLANATIONS, visual diagrams, interactive learning tools, and insights
+ 
+ **CRITICAL ORIENTATION - Always Reference File Paths:**
+ Throughout ALL documentation pages, include frequent references to source files using relative paths.
+ In data/*.json files, add \`file_path\` or \`path\` fields for each item (dependency, endpoint, table, etc.) so components can reference source code. Every technical concept should reference where users can see the actual implementation using relative file paths.
+ This connects documentation to code and reduces duplication.
+ 
+ ## EXCALIDRAW WHITEBOARDS FOR TEACHING & EXPLAINING
+ 
+ **Excalidraw Philosophy:**
+ - **When diagrams are requested, create Excalidraw whiteboards** - Excalidraw is a whiteboard tool that can contain diagrams
+ - **NO GENERIC DIAGRAMS** - don't create generic visualizations (e.g., generic Langgraph agent) that aren't specific to THIS repo
+ - **Every whiteboard needs data/*.json** - extract ONLY real, structured data from the repository
+ - **ONLY REAL DATA** - never invent performance metrics, features, or parameters
+ - **MDX components optional** - only create 1 MDX component if you need custom interactivity beyond whiteboards
+ - **Use DATABASE VIEWS for lists** - API endpoints, configs, processes with parameters go in database views
+ - **Whiteboards can contain diagrams, flows, sketches, notes, and other visual content**
+ 
+ **Excalidraw Whiteboard Types (Use These):**
+ 
+ **Note:** For Excalidraw implementation details, reference the \`<excalidraw_guidelines>\` tag.
+ 
+ ### 1. **Architecture Diagram** (Excalidraw whiteboard)
+    \`data/architecture.mermaid\` → \`<excalidraw data-path="data/architecture.json"></excalidraw>\`
+    - Extract: ONLY services/components that actually exist in the repo
+    - Display: boxes and arrows showing HOW system components connect
+    - **Good for:** microservices, system design, service dependencies, overall structure
+    - **CRITICAL:** Don't invent components or connections that don't exist
+ 
+ ### 2. **Data/Process Flow Visualizer** (Excalidraw whiteboard)
+    \`data/flow.mermaid\` → \`<excalidraw data-path="data/flow.json"></excalidraw>\`
+    - Extract: ONLY actual data sources, transformations, steps from the repo
+    - Display: flowchart with arrows showing journey end-to-end
+    - **Good for:** request flows, auth flows, data pipelines, deployment pipelines, payment flows
+    - **CRITICAL:** Don't create generic flow diagrams (e.g., generic Langgraph agent) - must be specific to THIS repo
+ 
+ ### 3. **Schema Diagram Viewer** (Excalidraw whiteboard)
+    \`data/schema.mermaid\` → \`<excalidraw data-path="data/schema.json"></excalidraw>\`
+    - Extract: ONLY actual tables/nodes, columns/properties from the repo's schema
+    - Display: entity-relationship diagram with expandable details
+    - **Good for:** database schemas, data models, graph structures
+    - **CRITICAL:** Don't invent tables or relationships that don't exist
+ 
+ ### 4. **Algorithm/Logic Visualizer**
+    \`data/algorithm.json + components/algorithm-visualizer.mdx\`
+    - Extract: algorithm steps, inputs/outputs, visual states, transformations
+    - Interactive: step through execution, adjust parameters, show before/after
+    - Display: visual representation of algorithm in action
+    - **Good for:** image processing, ML models, sorting, search, data transformations
+ 
+ ### 5. **Frontend Flow Diagram** (Excalidraw whiteboard)
+    \`data/frontend-flow.mermaid\` → \`<excalidraw data-path="data/frontend-flow.json"></excalidraw>\`
+    - Extract: ONLY actual user journeys, screen transitions from the frontend code
+    - Display: flowchart showing user journey from start to end (e.g., onboarding → dashboard → share)
+    - **Good for:** user onboarding flows, multi-step processes, user journeys
+    - **Example:** Onboarding flow: landing → signup → email verification → profile setup → dashboard
+    - **CRITICAL:** Don't invent user flows or screens that don't exist in the frontend code
+ 
+ ### 6. **Frontend Component Replica** (Optional)
+    \`data/component-spec.json + components/component-replica.mdx\`
+    - Extract: UI component structure, styles, behavior from actual code
+    - **Build a mini replica** of key UI components from the codebase
+    - Interactive: functional replica users can interact with (buttons click, forms submit, modals open)
+    - Display: actual working component that mimics the real implementation
+    - **Good for:** showing UI structure when flow diagram alone isn't enough
+    - **Example:** Instead of describing the checkout form, build a working mini version
+ 
+ ### 7. **Code Pattern Explorer** (Excalidraw whiteboard)
+    \`data/patterns.mermaid\` → \`<excalidraw data-path="data/patterns.json"></excalidraw>\`
+    - Extract: design patterns, example scenarios, trade-offs
+    - Display: visual pattern diagrams with explanations
+    - **Good for:** design patterns, architectural patterns, code organization strategies
+ 
+ ### 8. **Map Visualization** (for geo data)
+    \`data/locations.json + components/map-viewer.mdx\`
+    - Extract: geographic data, locations, regions, spatial relationships
+    - Interactive: zoom, pan, click markers for details, show connections
+    - Display: interactive map with markers and regions
+    - **Good for:** geographic services, location data, spatial analysis
+ 
+ ### 9. **DATABASE VIEWS for Lists** (NOT MDX Components)
+    **Use database views for tabular data:**
+    - API endpoints list (method, path, parameters, response)
+    - Configuration reference (setting name, type, default, description)
+    - Process lists with multiple parameters
+    - Any tabular data with many rows
+ 
+    **How to create:**
+    - Create a database view in the workspace
+    - Embed with \`<database-view>\` tag on the HTML page
+ 
+ **WHAT TO EXTRACT:**
+ - **Architecture**: services, connections → Architecture Diagram (Excalidraw whiteboard)
+ - **Backend flows**: request processing, API flows, auth flows → Flow Diagram (Excalidraw whiteboard)
+ - **Frontend flows**: user journeys, onboarding, feature flows → Frontend Flow Diagram (Excalidraw whiteboard)
+ - **Database**: tables, relationships → Schema Diagram (Excalidraw whiteboard)
+ - **Processes**: deployment pipelines, data processing → Process Flow Diagram (Excalidraw whiteboard)
+ - **API endpoints, configs**: lists with parameters → DATABASE VIEW (NOT MDX component)
+ - **Algorithms**: image processing, ML, transforms → Algorithm Visualizer (if exists in repo)
+ 
+ ## CONTENT WRITING GUIDELINES
+ 
+ **EDUCATIONAL, NOT DESCRIPTIVE:**
+ - **Write as WE/OUR/US** - first person plural, as if the team is teaching themselves
+   - Use: "We use FastAPI because it provides automatic API docs"
+   - Use: "Our database is PostgreSQL - we chose it for JSON support"
+   - NEVER: "They use FastAPI" / "The repo uses" / "This project"
+ - **EXPLAIN WHY, not just WHAT** - ONLY if reasoning is evident or documented in the repo
+   - BAD: "We use Redis for caching"
+   - GOOD: "We use Redis to cache API responses - reduces database load" (ONLY if Redis caching actually exists)
+   - **NEVER invent metrics** - don't say "improves response times from 500ms to 50ms" unless documented
+ 
+ **Formatting:**
+ - **Use diverse formatting**: Mix \`<h2>\`/\`<h3>\` for structure, \`<blockquote>\` for important notes, \`<ul>\` for lists, \`<pre><code>\` for commands
+ - **CRITICAL: The page title MUST be \`<h1>\` and NEVER \`<h2>\`** - use \`<h1>\` ONLY for the page title, then use \`<h2>\` and \`<h3>\` for sections
+ - **Headings (\`<h2>\`)**: Use SPARINGLY - maximum 2 per page, only for truly distinct concepts
+ - **Emojis for visual clarity:**
+   - **Use emojis** in \`<h2>\`, \`<h3>\`, and lists to make content scannable (e.g., \`<h2>🏗️ Architecture</h2>\`, \`<li>🔐 Authentication</li>\`)
+   - **DO NOT use emojis** in \`<h1>\` page titles - keep them clean (e.g., \`<h1>Backend API</h1>\`)
+ 
+ **Content quality:**
+ - **Include relative file paths** - reference actual code files using relative paths (e.g., "See \`src/auth.py\`")
+ - **Keep pages focused** - one main concept per page; use child pages for subtopics
+ - **Reference file paths for code details** - don't copy/paste large code blocks, reference file paths instead
+ - **Provide context and insights** - explain WHY, not just WHAT (architecture decisions, trade-offs, patterns)
+ 
+ **BAD EXAMPLE (descriptive, too much text, invented metrics):**
+ \`\`\`
+ The backend API repository uses FastAPI as its web framework. It was chosen because it provides fast performance and automatic API documentation. The database layer uses PostgreSQL with SQLAlchemy ORM. Our API serves 10,000+ requests per minute with 500ms response times.
+ \`\`\`
+ 
+ **GOOD EXAMPLE (educational, concise, Excalidraw whiteboards, only real data):**
+ \`\`\`html
+ <h2>🏗️ Architecture</h2>
+ <p>We use FastAPI for automatic OpenAPI docs and async support. PostgreSQL handles our relational data with SQLAlchemy ORM.</p>
+ 
+ <excalidraw data-path="data/architecture.json"></excalidraw>
+ 
+ <p>See <code>src/main.py</code> for setup and <code>src/models.py</code> for models.</p>
+ 
+ <hr />
+ 
+ <h2>🔐 Authentication Flow</h2>
+ 
+ <excalidraw data-path="data/auth-flow.json"></excalidraw>
+ 
+ <p>OAuth2 with JWT tokens. See <code>src/auth.py</code> for implementation.</p>
+ \`\`\`
+ 
+ ## EXAMPLE: Complete Repository Documentation (6 Pages)
+ 
+ **Scenario:** E-commerce web app (Next.js frontend + Python backend) in ${workspaceType} workspace
+ 
+ **Created structure:**
+ \`\`\`
+ 1. ecommerce-app.html
+    Brief overview (1 paragraph) + Architecture Diagram component (Excalidraw: all services/components)
+ 
+ 2. ecommerce-app/architecture.html
+    System design (1 paragraph) + Detailed Architecture Diagram (Excalidraw: microservices interactions)
+ 
+ 3. ecommerce-app/backend-flows.html
+    Minimal text (1 paragraph) + API Request Flow Diagram (Excalidraw: request → auth → handler → database → response)
+ 
+ 4. ecommerce-app/frontend-flows.html
+    Minimal text (1 paragraph) + User Journey Flow Diagram (Excalidraw: landing → signup → onboarding → checkout → purchase)
+ 
+ 5. ecommerce-app/key-processes.html
+    Minimal text (1 paragraph) + Process Flow Diagrams (Excalidraw: payment flow + order flow)
+ 
+ 6. ecommerce-app/api-reference.html
+    Minimal text (1 paragraph) + DATABASE VIEW for API endpoints (NOT MDX component)
+ \`\`\`
+ 
+ **Created 6 VISUAL elements (5 Excalidraw whiteboards + 1 database view):**
+ \`\`\`
+   → Excalidraw: boxes for Next.js, FastAPI, PostgreSQL, Redis, with arrows showing connections
+   → Embedded in HTML: <excalidraw data-path="data/ecommerce-architecture.json"></excalidraw>
+ 
+   → Excalidraw: detailed view with API routes, database models, cache layers
+   → Embedded in HTML: <excalidraw data-path="data/ecommerce-architecture-detailed.json"></excalidraw>
+ 
+   → Excalidraw: HTTP request → auth middleware → route handler → database query → response (with error paths)
+   → Embedded in HTML: <excalidraw data-path="data/backend-request-flow.json"></excalidraw>
+ 
+   → Excalidraw: landing page → signup → email verification → onboarding → checkout → purchase confirmation
+   → Shows user decisions, state changes, different paths (success/error)
+   → Embedded in HTML: <excalidraw data-path="data/frontend-user-journey.json"></excalidraw>
+ 
+   → Excalidraw: cart → payment form → validation → gateway → webhook → order confirmation
+   → Embedded in HTML: <excalidraw data-path="data/payment-process-flow.json"></excalidraw>
+ 
+ Database View: API endpoints
+   → Table view with columns: Method, Path, Parameters, Response (NOT MDX component)
+ \`\`\`
+ 
+ ---
+ 
+ ## Critical Rules
+ 
+ **1. MAXIMUM 6 PAGES - MANDATORY:**
+ - **Create MAXIMUM 6 pages total** (including the root [folder-name].html)
+ - **Maximum 5K characters per page** - be EXTREMELY concise
+ - Focus on the 5-6 most important concepts to teach
+ - Combine related topics instead of creating many small pages
+ - Be selective and concise
+ 
+ **2. MINIMUM 5 EXCALIDRAW WHITEBOARDS - MANDATORY:**
+ - **Create at least 5 Excalidraw whiteboards total** across all pages
+ - Most pages should have a whiteboard - distribute generously
+ - Whiteboards are embedded DIRECTLY in HTML using \`<excalidraw data-path="data/file.json"></excalidraw>\`
+ - **NO GENERIC DIAGRAMS** - don't create generic visualizations (e.g., generic Langgraph agent) that aren't specific to THIS repo
+ - Use DATABASE VIEWS for lists (API endpoints, configs)
+ 
+ **3. PRIORITIZE FLOW DIAGRAMS:**
+ - **Excalidraw whiteboards** - THE PRIMARY TEACHING TOOL (architecture, flows, processes, pipelines)
+ - **Backend flows** - show how requests are processed (request → auth → handler → database → response)
+ - **Frontend flows** - show user journeys (onboarding → share → feature X → etc.)
+ - **Process flows** - show key processes (payment, deployment, data processing)
+ - **Schema diagrams** - for database structures (Excalidraw whiteboard)
+ - **Database views for lists** - API endpoints, configs
+ - **MDX components** - only if you need custom interactivity (limit 1)
+ 
+ **4. BE EXTREMELY CONCISE:**
+ - **Maximum 5K characters per HTML page**
+ - Minimal explanatory text (1-2 short paragraphs maximum)
+ - Let the visual component do ALL the teaching
+ - Add 1 separator (\`<hr />\`) per page maximum for visual breaks
+ - Add blank lines before major sections for visual spacing
+ - Focus on: HOW it works (only if evident in the repo)
+ 
+ **5. NEVER INVENT DATA - CRITICAL:**
+ - **ONLY document what actually exists in the repository**
+ - Never invent performance metrics, scale, or features
+ - Never invent response times, request volumes, or load data
+ - Don't mention performance unless explicitly documented in the repo
+ - If reasoning/WHY isn't documented, don't make it up
+ - Extract ONLY real data from the repo for components
+ 
+ **6. WRITE AS WE/OUR/US:**
+ - First person plural throughout
+ - This is OUR internal documentation BY the team FOR the team
+ - Never write "they", "the team", "this repo"
+ - Write as if teaching a new team member
+ - Always reference actual code using relative file paths
+ </github_exploration_instructions>
+ 
+ <github_repository>
+     ${repositoryContent}
+ </github_repository>`;
+};
+export const HUMAN_MESSAGE = `A repository has been analyzed. Please create concise, VISUAL, EDUCATIONAL documentation that teaches and explains this repository in the workspace.
+ 
+ Follow the github_exploration_instructions carefully.`;

package/dist/agent/prompts/tool_descriptions.d.ts

@@ -0,0 +1,4 @@
+export declare const SEARCH_REPLACE_TOOL_DESCRIPTION = "Performs exact string replacements in files.\nMANDATORY: ALWAYS USE THE read_file TOOL BEFORE USING THIS TOOL.\nReplaces text within a file. By default, replaces a single occurrence, but can replace all occurrences when replace_all is specified. \nThis tool requires providing significant context around the change to ensure precise targeting. Always examine the file's current content before attempting a text replacement.\n\nUsage:\nWhen editing text, ensure you preserve the exact indentation (tabs/spaces) as it appears before.\nALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\nOnly use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.\nThe edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.\nUse replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.\nTo create or overwrite a file, you should prefer the write tool.\n\nExpectation for required parameters:\n1. file_path is ideally a relative path in the workspace.\n2. THIS IS CRITICAL: old_string MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.). IT IS CRITICAL TO KEEP THE STRUCTURE INTACT.\n3. new_string MUST be the exact literal text to replace old_string with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic.\n4. NEVER escape old_string or new_string, that would break the exact literal text requirement.\n5. Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.\n\nCRITICAL:\nEVEN WHEN EDITING DATA IN A DATA FILE, YOU MUST KEEP THE STRUCTURE INTACT old_string MUST MATCH THE CONTENT EXACTLY OR THE TOOL WILL FAIL.\n(e.g. for simple data editing, do not change for instance the order of the keys)\n\n\nImportant: If ANY of the above are not satisfied, the tool will fail. CRITICAL for old_string: Must uniquely identify the single instance to change. \nInclude at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.\n\nWhen editing using this tool fails use the write read tool to understand the file and then use the edit tool to edit the file - if the tool fails repedetly, use the write tool to edit the file.\n";
+export declare const WRITE_TOOL_DESCRIPTION = "\nWrites a file to the local filesystem.\nBear in mind that the other edit tools are better suited for editing existing files.\n\nUsage:\nThis tool will overwrite the existing file if there is one at the provided path.\nIf this is an existing file, you MUST use the read_file tool first to read the file's contents.\nALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n\nCRITICAL: when creating a file you must refer to the <content_guidelines> tag to understand the content format and structure for each type of file. Follow the guidelines strictly.\n";
+export declare const MULTI_EDIT_TOOL_DESCRIPTION = "\nThis is a tool for making multiple edits to a single file in one operation. It is built on top of the search_replace tool and allows you to perform multiple find-and-replace operations efficiently. \nPrefer this tool over the search_replace tool when you need to make multiple edits to the same file.\nALWAYS USE THE read_file TOOL BEFORE USING THIS TOOL.\n\nBefore using this tool:\nUse the Read tool to understand the file's contents and context\nVerify the path is correct\n\nTo make multiple file edits, provide the following:\nfile_path: The absolute path to the file to modify (must be absolute, not relative)\nedits: An array of edit operations to perform, where each edit contains:\n    THIS IS CRITICAL: old_string: The text to replace (must match the file contents exactly, including all whitespace and indentation). IT IS CRITICAL TO KEEP THE STRUCTURE INTACT.\n    new_string: The edited text to replace the old_string\n    replace_all: Replace all occurences of old_string. This parameter is optional and defaults to false.\n\nIMPORTANT:\nAll edits are applied in sequence, in the order they are provided\nEach edit operates on the result of the previous edit\nAll edits must be valid for the operation to succeed - if any edit fails, none will be applied\nThis tool is ideal when you need to make several changes to different parts of the same file\n\nCRITICAL REQUIREMENTS:\nAll edits follow the same requirements as the single Edit tool\nThe edits are atomic - either all succeed or none are applied\nPlan your edits carefully to avoid conflicts between sequential operations\n\nWARNING:\nThe tool will fail if edits.old_string doesn't match the file contents exactly (including whitespace). IT IS CRITICAL TO KEEP THE STRUCTURE INTACT.\nThe tool will fail if edits.old_string and edits.new_string are the same\nSince edits are applied in sequence, ensure that earlier edits don't affect the text that later edits are trying to find\n\nWhen making edits:\nEnsure all edits result in idiomatic, correct code\nDo not leave the code in a broken state\nUse replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.\n\nWhen editing using this tool fails use the write tool to edit the file.\n";
+//# sourceMappingURL=tool_descriptions.d.ts.map

package/dist/agent/prompts/tool_descriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_descriptions.d.ts","sourceRoot":"","sources":["../../../src/agent/prompts/tool_descriptions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,6nFA6B3C,CAAC;AAEF,eAAO,MAAM,sBAAsB,kmBAUlC,CAAC;AAEF,eAAO,MAAM,2BAA2B,gvEAsCvC,CAAC"}

package/dist/agent/prompts/tool_descriptions.js

@@ -0,0 +1,80 @@
+export const SEARCH_REPLACE_TOOL_DESCRIPTION = `Performs exact string replacements in files.
+MANDATORY: ALWAYS USE THE read_file TOOL BEFORE USING THIS TOOL.
+Replaces text within a file. By default, replaces a single occurrence, but can replace all occurrences when replace_all is specified. 
+This tool requires providing significant context around the change to ensure precise targeting. Always examine the file's current content before attempting a text replacement.
+
+Usage:
+When editing text, ensure you preserve the exact indentation (tabs/spaces) as it appears before.
+ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
+Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+To create or overwrite a file, you should prefer the write tool.
+
+Expectation for required parameters:
+1. file_path is ideally a relative path in the workspace.
+2. THIS IS CRITICAL: old_string MUST be the exact literal text to replace (including all whitespace, indentation, newlines, and surrounding code etc.). IT IS CRITICAL TO KEEP THE STRUCTURE INTACT.
+3. new_string MUST be the exact literal text to replace old_string with (also including all whitespace, indentation, newlines, and surrounding code etc.). Ensure the resulting code is correct and idiomatic.
+4. NEVER escape old_string or new_string, that would break the exact literal text requirement.
+5. Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+
+CRITICAL:
+EVEN WHEN EDITING DATA IN A DATA FILE, YOU MUST KEEP THE STRUCTURE INTACT old_string MUST MATCH THE CONTENT EXACTLY OR THE TOOL WILL FAIL.
+(e.g. for simple data editing, do not change for instance the order of the keys)
+
+
+Important: If ANY of the above are not satisfied, the tool will fail. CRITICAL for old_string: Must uniquely identify the single instance to change. 
+Include at least 3 lines of context BEFORE and AFTER the target text, matching whitespace and indentation precisely. If this string matches multiple locations, or does not match exactly, the tool will fail.
+
+When editing using this tool fails use the write read tool to understand the file and then use the edit tool to edit the file - if the tool fails repedetly, use the write tool to edit the file.
+`;
+export const WRITE_TOOL_DESCRIPTION = `
+Writes a file to the local filesystem.
+Bear in mind that the other edit tools are better suited for editing existing files.
+
+Usage:
+This tool will overwrite the existing file if there is one at the provided path.
+If this is an existing file, you MUST use the read_file tool first to read the file's contents.
+ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+
+CRITICAL: when creating a file you must refer to the <content_guidelines> tag to understand the content format and structure for each type of file. Follow the guidelines strictly.
+`;
+export const MULTI_EDIT_TOOL_DESCRIPTION = `
+This is a tool for making multiple edits to a single file in one operation. It is built on top of the search_replace tool and allows you to perform multiple find-and-replace operations efficiently. 
+Prefer this tool over the search_replace tool when you need to make multiple edits to the same file.
+ALWAYS USE THE read_file TOOL BEFORE USING THIS TOOL.
+
+Before using this tool:
+Use the Read tool to understand the file's contents and context
+Verify the path is correct
+
+To make multiple file edits, provide the following:
+file_path: The absolute path to the file to modify (must be absolute, not relative)
+edits: An array of edit operations to perform, where each edit contains:
+    THIS IS CRITICAL: old_string: The text to replace (must match the file contents exactly, including all whitespace and indentation). IT IS CRITICAL TO KEEP THE STRUCTURE INTACT.
+    new_string: The edited text to replace the old_string
+    replace_all: Replace all occurences of old_string. This parameter is optional and defaults to false.
+
+IMPORTANT:
+All edits are applied in sequence, in the order they are provided
+Each edit operates on the result of the previous edit
+All edits must be valid for the operation to succeed - if any edit fails, none will be applied
+This tool is ideal when you need to make several changes to different parts of the same file
+
+CRITICAL REQUIREMENTS:
+All edits follow the same requirements as the single Edit tool
+The edits are atomic - either all succeed or none are applied
+Plan your edits carefully to avoid conflicts between sequential operations
+
+WARNING:
+The tool will fail if edits.old_string doesn't match the file contents exactly (including whitespace). IT IS CRITICAL TO KEEP THE STRUCTURE INTACT.
+The tool will fail if edits.old_string and edits.new_string are the same
+Since edits are applied in sequence, ensure that earlier edits don't affect the text that later edits are trying to find
+
+When making edits:
+Ensure all edits result in idiomatic, correct code
+Do not leave the code in a broken state
+Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
+
+When editing using this tool fails use the write tool to edit the file.
+`;

package/dist/agent/tools.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/**
+ * Tool for writing content to a file
+ */
+export declare const writeTool: import("langchain").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>, {
+    filePath: string;
+    content: string;
+}, {
+    filePath: string;
+    content: string;
+}, string>;
+/**
+ * Tool for searching and replacing text in a file
+ */
+export declare const searchReplaceTool: import("langchain").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+    oldString: z.ZodString;
+    newString: z.ZodString;
+    replaceAll: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>, {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll: boolean;
+}, {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean | undefined;
+}, string>;
+/**
+ * Tool for reading file contents
+ */
+export declare const readFileTool: import("langchain").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+}, z.core.$strip>, {
+    filePath: string;
+}, {
+    filePath: string;
+}, string>;
+/**
+ * Tool for deleting a file
+ */
+export declare const deleteTool: import("langchain").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+}, z.core.$strip>, {
+    filePath: string;
+}, {
+    filePath: string;
+}, string>;
+/**
+ * Tool for making multiple edits to a single file
+ */
+export declare const multiEditTool: import("langchain").DynamicStructuredTool<z.ZodObject<{
+    filePath: z.ZodString;
+    edits: z.ZodArray<z.ZodObject<{
+        oldString: z.ZodString;
+        newString: z.ZodString;
+        replaceAll: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, {
+    filePath: string;
+    edits: {
+        oldString: string;
+        newString: string;
+        replaceAll: boolean;
+    }[];
+}, {
+    filePath: string;
+    edits: {
+        oldString: string;
+        newString: string;
+        replaceAll?: boolean | undefined;
+    }[];
+}, string>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/agent/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/agent/tools.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;UAqFrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;UAiE7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;UA2DxB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;UAiEtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;UA4GzB,CAAC"}