Improve ROI Reporting Agent setup documentation and file organization

[ko47kmr]

Summary

This PR improves the ROI Reporting Agent setup experience by reorganizing Japanese reference files and enhancing documentation.

Changes

📁 File Organization

• Move Japanese files to docs/japanese/
  • OverallSummary_Spec_ja.md
  • CampaignDetails_Spec_ja.md
  • prompt_ja.md
  • README_JA.md
• Impact: Reduces Text KBs created from 4 to 2 (prevents accidental deployment of unused Japanese KBs)
• Benefit: Simpler, clearer setup while keeping Japanese materials accessible for reference

📖 README Improvements

Setup Instructions

• ✅ Add explicit database creation step with error handling note
• ✅ Clarify default project name works out-of-box
• ✅ Move custom project name to "Advanced Options" (collapsible section)
• ✅ Add verification steps with expected output
• ✅ Organize optional configurations in collapsible sections

File Structure

• ✅ Update to reflect new docs/japanese/ structure
• ✅ Add notes about auto-generated files
• ✅ Clarify language-independent report generation

Troubleshooting

• ✅ Expand from simple table to detailed sections with solutions
• ✅ Add setup issue solutions:
  • LLM_PROJECT_NOT_FOUND
  • Database not found
  • Missing tools/outputs
  • tdx version issues
• ✅ Add usage troubleshooting (Japanese reports, missing parameters, etc.)
• ✅ Include project management guidance

Japanese Documentation (New Section)

• ✅ Explain docs/japanese/ contents
• ✅ Clarify English KBs work for both languages
• ✅ Provide advanced option to use Japanese specs

Testing

Verified with fresh clone from GitHub:

cd /tmp
git clone --depth 1 --filter=blob:none --sparse https://github.com/treasure-data/treasure-boxes.git test-agent
cd test-agent
git sparse-checkout set engage-box/roi_reporting
cd engage-box/roi_reporting/agent

tdx llm project create "Test ROI Agent"
tdx agent push . -f

Result:

• ✅ Text Knowledge Bases: 2 created (previously 4)
• ✅ Agent tools: 4/4 correctly configured
• ✅ All components deployed successfully

Expected Impact

User Experience

• ✅ Default setup works immediately (no customization needed)
• ✅ Less confusion (2 Text KBs vs 4)
• ✅ Clear troubleshooting when issues arise
• ✅ Japanese materials still accessible for reference

Maintenance

• ✅ Clearer file organization
• ✅ Self-documenting structure (docs/japanese/)
• ✅ No breaking changes (English setup unchanged)

Checklist

• File organization changes implemented
• README sections updated
• Tested with fresh repository clone
• Verified Text KB count reduced to 2
• Confirmed all agent tools/outputs work
• Japanese materials accessible in docs/

Related

This addresses user feedback about setup complexity and confusion regarding Japanese KB files.

[Copilot]

Pull request overview

This PR reorganizes Japanese reference materials for the ROI Reporting Agent into docs/japanese/ and expands the main setup README to make first-time deployment and troubleshooting clearer.

Changes:

• Moved Japanese prompt/spec/README reference files under agent/docs/japanese/ to avoid accidental deployment as extra Text KBs.
• Expanded agent/README.md with clearer setup steps (including DB creation), deployment verification, advanced options, and detailed troubleshooting.
• Added Japanese reference documentation files in their new location.

Reviewed changes

Copilot reviewed 1 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
engage-box/roi_reporting/agent/README.md	Improves setup flow, verification steps, troubleshooting, and documents the new docs/japanese/ layout (includes a broken link to workflow docs).
engage-box/roi_reporting/agent/docs/japanese/README_JA.md	Adds Japanese README, but currently still describes the old (pre-reorg) file layout and tdx.json example.
engage-box/roi_reporting/agent/docs/japanese/prompt_ja.md	Adds Japanese system prompt reference under docs/japanese/.
engage-box/roi_reporting/agent/docs/japanese/OverallSummary_Spec_ja.md	Adds Japanese OverallSummary spec reference, but the link to the English spec is now broken due to relocation.
engage-box/roi_reporting/agent/docs/japanese/CampaignDetails_Spec_ja.md	Adds Japanese CampaignDetails spec reference, but the link to the English spec is now broken due to relocation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.