Imported from Algiras/vs-zinios-conference-2025-11-18 (AGENTS.md). Install upstream with npx skills add Algiras/vs-zinios-conference-2025-11-18. Copyright stays with the author.

AGENTS.md - Project Structure Guide for AI Agents

This document explains the project structure and where to find/create files when working on this codebase.

🎯 Primary Work File

ONLY EDIT THIS FILE:

slides/presentation.md - The main presentation source file

All other files are either:

Generated (output files)
Reference only (documentation, repos)
Configuration (package.json, .marprc.yml)

📁 Directory Structure

vs-zinios/
├── slides/                    # Presentation files
│   ├── presentation.md        # ⭐ ONLY EDIT THIS FILE
│   ├── presentation.pptx      # Generated (PPTX export)
│   ├── presentation.pdf       # Generated (PDF export)
│   ├── slide-images/          # Generated (PNG exports)
│   └── images/                # Generated (Mermaid/QR images)
│       ├── mermaid/           # Generated Mermaid diagrams
│       └── qr/                # Generated QR codes
│
├── docs/                      # Reference documentation
│   ├── README.md              # Documentation index
│   ├── mcp/                   # Model Context Protocol docs
│   ├── agents/                # Agent architecture docs
│   └── frameworks/            # Framework documentation
│
├── themes/                    # Marp theme files
│   ├── rose-pine-dawn.css     # Light theme
│   └── rose-pine-moon.css     # Dark theme
│
├── thoughts/                  # LLM-generated analysis (gitignored)
│   ├── README.md              # Only tracked file
│   └── *.md                   # All other .md files ignored
│
├── scripts/                   # Build automation
│   ├── export-with-validation.js
│   ├── slides-to-image.js
│   └── preprocess-for-pdf.js
│
├── repos/                     # Reference repos (gitignored)
│   ├── ag2/                   # AutoGen reference
│   ├── langchain-python/      # LangChain reference
│   └── voltagent/             # VoltAgent reference
│
├── package.json               # NPM dependencies
├── .marprc.yml                # Marp CLI configuration
├── .gitignore                 # Git ignore rules
├── .cursorrules               # Cursor IDE rules
├── README.md                  # Project overview
└── AGENTS.md                  # This file

🚫 What NOT to Edit

Generated Files (will be overwritten):

slides/presentation.pptx - Generated by export
slides/presentation.pdf - Generated by export
slides/slide-images/*.png - Generated by export
slides/images/mermaid/* - Generated by preprocessing
slides/images/qr/* - Generated by preprocessing
slides/presentation.preprocessed.md - Generated by preprocessing

Reference Only:

docs/**/*.md - Documentation (read-only)
repos/**/* - Cloned repositories (read-only)
themes/*.css - Theme files (use, don't modify)

✅ What TO Edit

Primary:

slides/presentation.md - Main presentation source

Configuration (if needed):

package.json - Add dependencies
.marprc.yml - Marp CLI settings
.gitignore - Git ignore rules
.cursorrules - Cursor IDE rules

Documentation (if adding new docs):

docs/**/*.md - Add new documentation files
docs/README.md - Update index when adding docs

📝 Where to Put LLM Thoughts

All LLM-generated analysis files go in:

thoughts/*.md - Any analysis, notes, or thoughts

Rules:

✅ Create .md files in thoughts/ folder
✅ Files are automatically gitignored
✅ Only thoughts/README.md is tracked
❌ Don't put thoughts in root directory
❌ Don't create files outside thoughts/ for analysis

🎨 Themes

Available Themes:

themes/rose-pine-dawn.css - Light theme (warm beige)
themes/rose-pine-moon.css - Dark theme (dark purple)

Usage in presentation.md:

---
theme: ../themes/rose-pine-dawn  # Light
# or
theme: ../themes/rose-pine-moon  # Dark
---

🔧 Build Scripts

Available Commands:

npm run dev - Development server with hot reload
npm run export - Full export (images + PPTX)
npm run export:images - PNG generation only
npm run export:pptx - PPTX generation only
npm run preview - Preview without watching

Scripts Location:

scripts/export-with-validation.js - Main export workflow
scripts/slides-to-image.js - Image generation
scripts/preprocess-for-pdf.js - Preprocessing

📚 Documentation Structure

Documentation is organized by topic:

docs/
├── README.md              # Start here - index of all docs
├── mcp/                   # Model Context Protocol
│   ├── README.md
│   ├── architecture.md
│   ├── tools.md
│   └── resources.md
├── agents/                # Agent architectures
│   ├── reflex-agents.md
│   ├── learning-agents.md
│   ├── finite-state-machines.md
│   ├── behavior-trees.md
│   ├── goap.md
│   └── scratchpad-pattern.md
└── frameworks/           # Framework comparisons
    ├── python-frameworks.md
    ├── typescript-frameworks.md
    └── workflow-orchestration.md

🔍 Finding Information

To find information about:

Marp/Presentation: See thoughts/ folder for guides
Agent Types: docs/agents/*.md
Frameworks: docs/frameworks/*.md
MCP Protocol: docs/mcp/*.md
Code Examples: repos/*/ (reference only)
Build Process: scripts/*.js and thoughts/EXPORT_WORKFLOW.md

🎯 Quick Reference

What You Need	Where to Find It
Edit presentation	`slides/presentation.md`
Add LLM thoughts	`thoughts/*.md`
Find agent docs	`docs/agents/*.md`
Find framework docs	`docs/frameworks/*.md`
Change theme	Edit `theme:` in `slides/presentation.md`
Add dependencies	`package.json`
Build scripts	`scripts/*.js`
Reference code	`repos/*/` (read-only)
Documentation guides	`thoughts/*.md`

⚠️ Important Rules

ONLY edit slides/presentation.md - All other files are generated or reference
Put all LLM thoughts in thoughts/ - They're gitignored automatically
Don't modify generated files - They'll be overwritten
Don't modify repos/ - They're reference only
Check thoughts/ for guides - Documentation moved there

🚀 Common Tasks

Adding a new slide:

Edit slides/presentation.md
Add content after --- separator
Run npm run dev to preview

Changing theme:

Edit theme: line in slides/presentation.md front matter
Options: ../themes/rose-pine-dawn or ../themes/rose-pine-moon

Adding Mermaid diagram:

Use ```mermaid ... ``` syntax in slides/presentation.md
Diagrams auto-generate via Kroki plugin

Adding QR code:

Use ![QR Code](qr:https://example.com) syntax
QR codes auto-generate

Exporting presentation:

Run npm run export for full export
Outputs: slides/presentation.pptx and slides/slide-images/

📖 Additional Resources

Project README: README.md - Overview and setup
Cursor Rules: .cursorrules - IDE-specific guidelines
Documentation Index: docs/README.md - All documentation
Thoughts Folder: thoughts/ - Detailed guides and analysis

📐 Slide Layout Patterns

This section documents all layout patterns used in slides/presentation.md for consistent slide design.

Column Layouts

Standard Two-Column Layout (.columns)

Usage: Most slides with diagrams or side-by-side content
Structure: 1.1fr 0.9fr (diagram left, text right typically)
Gap: 1em
Font size: 0.88em
Line height: 1.4
Example:

<div class="columns">
<div>
  <!-- Diagram or left content -->
</div>
<div>
  <!-- Text or right content -->
</div>
</div>

Reflex Columns (.reflex-columns)

Usage: Reflex Agent characteristics slides
Structure: Same as .columns but with larger gap (2.2em)
Font size: 0.9em
Special: Used for strengths/constraints comparisons

Takeaways Grid (.takeaways-grid)

Usage: Key takeaways slides (2-column grid)
Structure: repeat(2, minmax(0, 1fr)) (equal columns)
Gap: 2.4em
Font size: 0.95em
Line height: 1.45

Resources Grid (.resources-grid)

Usage: Resources slide with cards
Structure: repeat(2, minmax(0, 1fr)) (equal columns)
Gap: 2em
Font size: 0.9em
Special: Cards have background (#f7f7f7), padding, border-radius

Flex Layouts (.mcp-highlights, .gateway-summary)

Usage: MCP highlights and gateway summary slides
Structure: Flexbox with gap: 1.5em
Behavior: Equal-width columns that flex

Best Practices (.best-practices)

Usage: Best practices slides
Structure: 1fr 1fr (equal columns)
Gap: 2em
Font size: 0.95em
Special: Larger h3 headings (1.2em)

Diagram Patterns

Mermaid Diagrams in Columns

Max height: 40% (for vertical diagrams like FSM)
Max width: 90% (for horizontal diagrams like BT)
Margin: 0.3em auto (centered)
Orientation:
- graph LR - Left-to-right (preferred for most diagrams)
- graph TB - Top-to-bottom (for FSM state diagrams)
- stateDiagram-v2 - State diagrams (vertical)

Diagram Sizing Guidelines:

Horizontal diagrams (graph LR): Use max-width: 90%, max-height: 40%
Vertical diagrams (graph TB): Use max-width: 80%, max-height: 35% (more constrained)
Complex diagrams (subgraphs): Use max-height: 45-47%, max-width: 85-87%

Slide Types

Lead Slides (.lead)

Usage: Title slide, section introductions, "Questions?", "Thank You!"
Features:
- Centered content
- No pagination ()
- No footer ()
Example:

<!-- _class: lead -->
<!-- _paginate: false -->
<!-- _footer: "" -->

# Title

Regular Slides

Features:
- Header: "Autonomous Development Workflows" (top)
- Footer: "Algimantas Krasauskas | Wix | November 2025" (bottom)
- Pagination: Bottom right
- Padding: 4em top, 3.5em bottom

Comparison Slides

Usage: Agent types, frameworks, patterns
Pattern: Two-column layout with headings in each column
Example: "Agent Types: Overview" uses .columns with h3 headings

Content Patterns

Bullet Lists

Margin: 0.4em 0
Padding left: 1.2em
Line height: 1.4-1.6 (varies by context)

Paragraphs in Columns

Margin: 0.4em 0 (standard), 0.6em 0 (with diagrams)
Font size: Inherits from column (typically 0.88em)

Headings

H2: margin-top: 0.2em, margin-bottom: 0.6em
H3 in columns: margin: 0 0 0.4-0.5em 0, font-size: 1.1-1.2em

Code Blocks

Usage: Tool examples, MCP structures
Font size: 0.85em (reduced for fit)
Margin: 0.5em top (to avoid header overlap)

Tables

Usage: Framework comparisons, pattern comparisons
Font size: 0.75em (reduced)
Line height: 1.3
Cell padding: 0.3em 0.2em

Special Patterns

QR Codes

Size: 200px × 200px
Position: Centered
Usage: Only on final "Thank You!" slide
Syntax: ![QR Code](qr:https://example.com)

Mermaid Diagram Syntax

Standard: ```mermaid ... ```
Auto-generated: Preprocessing converts to ![Mermaid diagram](images/mermaid/...)
Styling: Handled globally, no scoped styles needed

Scoped Styles (when needed)

Usage: Only for slide-specific overrides
Pattern: Most styling is global now
Example: Only used for special cases like .best-practices specific adjustments

Global Styling

All slides use consistent global styles defined in the front matter style: block:

Section padding: 4em top, 3.5em bottom
Column layouts: 1.1fr 0.9fr, gap: 1em
Diagram sizing: 40% max-height, 90% max-width
Text sizing: 0.88em base, 1.4 line-height
Headings: Consistent margins across all slides

Key Principle: Use global styles first, add scoped styles only when absolutely necessary for slide-specific needs.

Best Practices from Marp & Reveal.js

Consistent Heading Positioning:

H2 (slide titles): margin-top: 0.2em, margin-bottom: 0.6em (global)
H3 (section headings): margin: 0 0 0.4-0.5em 0, font-size: 1.1-1.2em (in columns)
Fitting headers: Use  comment for auto-scaling when needed (not currently used)
Heading hierarchy: Maintain consistent spacing between heading levels

Content Positioning:

Section padding: 4em top (header clearance), 3.5em bottom (footer clearance)
Left/Right padding: 1.5em (prevents edge overflow)
First element margin: Ensure adequate top margin after headings
Vertical centering: Not used (content flows top-to-bottom for consistency)

Text Spacing:

Paragraphs: 0.4em 0 (standard), 0.6em 0 (with diagrams)
Bullet lists: 0.4em 0 margin, 1.2em padding-left
Line height: 1.4 (base), 1.6 (with diagrams), 1.45 (takeaways)
Font size: 0.88em (base in columns), 0.9em (reflex columns), 0.95em (takeaways)

Diagram Positioning:

In columns: max-height: 40%, max-width: 90%, margin: 0.3em auto
Vertical diagrams: More constrained (max-height: 35%, max-width: 80%)
Margin after headings: 0.8em top margin to prevent overlap
Clearance: clear: both to prevent text wrapping

Layout Consistency:

Column ratio: 1.1fr 0.9fr (diagram/text split) for most slides
Equal columns: 1fr 1fr for comparisons and grids
Gap spacing: 1em (standard), 1.2em (with diagrams), 2em+ (grids)
Alignment: align-items: start (top-aligned content in columns)

Header/Footer Positioning:

Header: Fixed at top, hidden on lead slides
Footer: Fixed at bottom (15px from bottom), includes pagination
Pagination: Bottom right, hidden when _paginate: false
Clearance: Section padding ensures content doesn't overlap

Code Block Positioning:

Font size: 0.85em (reduced for fit)
Top margin: 0.5em (to avoid header overlap)
Line height: 1.3 (compact)

Table Positioning:

Font size: 0.75em (reduced)
Line height: 1.3
Cell padding: 0.3em 0.2em

Patterns to Follow:

Always use global styles for common patterns (columns, diagrams, headings)
Consistent spacing - Use the same margins/padding across similar slide types
Header clearance - Always account for header height in top padding
Footer clearance - Always account for footer height in bottom padding
Diagram containment - Use columns to bound diagrams and prevent overflow
Text hierarchy - Maintain consistent heading sizes and spacing
Scoped overrides - Only use for slide-specific needs, not common patterns

Remember: When in doubt, only edit slides/presentation.md. Everything else is either generated, reference-only, or should go in thoughts/.

vs-zinios-conference-2025-11-18

About