feat(craft): better output formats

[rohoswagger]

Description

update AGENTS.md with the real output formats we support

How Has This Been Tested?

locally, + wenxi testing with these changes

Additional Options

• [Required] I have considered whether this PR needs to be cherry-picked to the latest beta branch.
• [Optional] Override Linear Check

[greptile-apps]

Greptile Overview

Greptile Summary

This PR enhances the AGENTS.template.md file by replacing the "Coming Soon" placeholder with actual documentation for markdown documents and image/slide outputs. It adds a helpful decision table to guide output format selection and provides specific instructions for each format type.

Key Changes:

• Added decision table comparing Web App, Markdown, Images/Slides, and Agent Response formats
• Documented markdown output format with outputs/markdown directory
• Documented image/slide output format with outputs/slides directory using Python visualization libraries

Critical Issues Found:

• The outputs/markdown and outputs/slides directories don't exist in the template structure at backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/
• Inconsistency with CLAUDE.template.md which references outputs/document (not outputs/markdown) and outputs/charts (not outputs/slides)
• These mismatches will cause runtime errors when agents attempt to save files to non-existent locations

Confidence Score: 2/5

• This PR has critical infrastructure gaps that will cause runtime failures
• The documentation changes look good, but the referenced directories don't exist in the template structure, and there's inconsistency with CLAUDE.template.md. This will cause failures when agents try to use these new output formats.
• backend/onyx/server/features/build/AGENTS.template.md requires the missing directories to be created, and CLAUDE.template.md needs to be updated for consistency

Important Files Changed

Filename	Overview
backend/onyx/server/features/build/AGENTS.template.md	Added documentation for markdown and image/slide output formats with decision table, but directories don't exist in templates and there's inconsistency with CLAUDE.template.md

Sequence Diagram

sequenceDiagram
    participant User
    participant Agent as AI Agent (Steve)
    participant Decision as Format Decision Logic
    participant WebApp as Web App Builder
    participant Markdown as Markdown Generator
    participant Image as Image/Slide Generator
    participant FileSystem as outputs/ Directory

    User->>Agent: Request output (e.g., "Create dashboard", "Write report", "Make chart")
    Agent->>Decision: Analyze request type
    
    alt Interactive data exploration
        Decision->>WebApp: Route to Web App format
        WebApp->>FileSystem: Write to outputs/web/
        FileSystem-->>User: Serve on port {{NEXTJS_PORT}}
    else Long-form report
        Decision->>Markdown: Route to Markdown format
        Markdown->>FileSystem: Write to outputs/markdown/*.md
        FileSystem-->>User: Return markdown document
    else Static visual for presentation
        Decision->>Image: Route to Image/Slide format
        Image->>FileSystem: Write to outputs/slides/*.png
        FileSystem-->>User: Return image file
    else Quick factual answer
        Decision->>Agent: Return direct response
        Agent-->>User: Text response (no file)
    end

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

The outputs/markdown directory doesn't exist in the template structure at backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/. This will cause errors when agents try to save files to this location.

Additionally, CLAUDE.template.md refers to outputs/document instead of outputs/markdown (line 96), creating an inconsistency between the two template files.

Prompt To Fix With AI

This is a comment left during a code review.
Path: backend/onyx/server/features/build/AGENTS.template.md
Line: 255:255

Comment:
The `outputs/markdown` directory doesn't exist in the template structure at `backend/onyx/server/features/build/sandbox/kubernetes/docker/templates/outputs/`. This will cause errors when agents try to save files to this location.

Additionally, `CLAUDE.template.md` refers to `outputs/document` instead of `outputs/markdown` (line 96), creating an inconsistency between the two template files.

How can I resolve this? If you propose a fix, please make it concise.

[rohoswagger]

incorrect, when we create a session we create a outputs/markdown directory for the sessions

[greptile-apps]

You're absolutely right. I can see from the setup_session_workspace method in the LocalSandboxManager that the session directory structure is indeed created dynamically when a session is set up. The outputs/markdown directory would be created as part of the template copying process during session setup.

My comment was based on looking at the static template structure, but you're correct that the actual runtime directory structure includes outputs/markdown when sessions are created. Thanks for the clarification!

[greptile-apps]

The outputs/slides directory doesn't exist in the template structure. Additionally, CLAUDE.template.md refers to outputs/charts (line 102) instead of outputs/slides, creating another inconsistency.

The example filename ender_drag.png also seems unusual - verify this is intentional.

Prompt To Fix With AI

This is a comment left during a code review.
Path: backend/onyx/server/features/build/AGENTS.template.md
Line: 259:259

Comment:
The `outputs/slides` directory doesn't exist in the template structure. Additionally, `CLAUDE.template.md` refers to `outputs/charts` (line 102) instead of `outputs/slides`, creating another inconsistency.

The example filename `ender_drag.png` also seems unusual - verify this is intentional.

How can I resolve this? If you propose a fix, please make it concise.

[rohoswagger]

incorrect, when we create a session we create a outputs/slides directory for the sessions

[greptile-apps]

You're correct - I was looking at the template structure rather than the actual session directories that get created at runtime. The outputs/slides directory is indeed created when a new session is initialized, so the reference in the documentation is accurate.

However, there's still the inconsistency I mentioned between this file referencing outputs/slides and CLAUDE.template.md referencing outputs/charts on line 102. Should these be aligned to use the same directory name?

[cubic-dev-ai]

No issues found across 1 file