docs: add llms.txt and AI agent FAQ

[koriym]

Summary

• Add llms.txt (summary with documentation links)
• Add llms-full.txt (comprehensive AI-readable documentation)
• Add FAQ section about using AI agents with Be Framework

llms-full.txt contents

• Core Philosophy
• Key Concepts (Domain Ontology, Reason, Metamorphosis, Type-Driven Branching)
• Domain Types (PHPDoc Union Types)
• Naming Conventions
• Transformation Flow
• Complete Triage Example
• Why Being Over Doing

FAQ addition (Q27)

How to get AI to write Be Framework code:

Please read https://be-framework.github.io/llms-full.txt

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation files describing Be Framework concepts and philosophy.
  • Updated FAQ with new section on using AI agents to generate code.
  • Expanded related chapter links in English and Japanese documentation for improved navigation and cross-referencing.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Introduces two comprehensive Be Framework documentation files (llms-full.txt and llms.txt) describing core philosophy, concepts, and code examples. Updates English and Japanese FAQ files with a new "Using AI Agents" section and expanded cross-linking references to related chapters. No functional code changes.

Changes

Cohort / File(s)	Summary
Documentation Files (New) llms-full.txt, llms.txt	Adds comprehensive Be Framework documentation covering philosophy, domain ontology, metamorphosis pattern, type-driven branching, attributes, transformation flow, error handling, project structure, and practical PHP-like code samples. Static descriptive content with external links; no executable logic.
FAQ Updates (English) manuals/1.0/en/faq.md	Restructures Section 11 from "Related Chapter Links" to "Using AI Agents"; adds Q27 with AI prompt guidance referencing llms-full.txt. Expands Section 12 Related Chapter Links with new cross-references: Semantic Variables, Type-Driven Metamorphosis, Reason Layer, Error Handling, Semantic Logging.
FAQ Updates (Japanese) manuals/1.0/ja/faq.md	Restructures Section 11 from "関連章へのリンク" to "AIエージェントの活用"; adds Q27 with AI prompt instructions. Adds new Section 12 "関連章へのリンク" with expanded cross-references including 変容, 意味変数, 型駆動変容, 存在理由層, エラーハンドリング, 意味的ログ.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Add comprehensive FAQ for Be Framework #7: Modifies the same manual FAQ files (manuals/1.0/en/faq.md and manuals/1.0/ja/faq.md) with documentation structure and linking updates.
• feat: add Practice section (P1 Quick Start, P2 Tutorial) #13: Adds and modifies the same llms documentation files (llms-full.txt, llms.txt) and related manual cross-references.

Poem

📚 A rabbit hops through docs so neat,
Building frameworks, concepts sweet,
With AI guides and links aligned,
Both Japanese and English intertwined,
Be Framework blooms—organized, refined! 🌸

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1a459ef and a49940f.

📒 Files selected for processing (4)

• llms-full.txt
• llms.txt
• manuals/1.0/en/faq.md
• manuals/1.0/ja/faq.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[koriym]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[claude]

Pull Request Review: llms.txt and AI Agent FAQ

Summary

This PR adds AI-friendly documentation (llms.txt and llms-full.txt) and updates the FAQ to help AI agents understand and generate Be Framework code. Overall, this is an excellent addition that will significantly improve AI comprehension of the framework.

---

Strengths

1. Clear Structure and Organization

• The two-tier approach (llms.txt as summary + llms-full.txt as comprehensive guide) is well-designed
• Logical flow from philosophy to concepts to examples to comparison
• Progressive disclosure helps both quick reference and deep understanding

2. Excellent Code Examples

• Complete, runnable triage example demonstrates all key concepts
• Shows both what and why effectively
• PHPDoc union types usage is well-documented (lines 99-122 in llms-full.txt)

3. Strong Conceptual Clarity

• Objects don't DO things they BECOME things tagline is memorable
• Clear distinction between traditional (Doing) and Be Framework (Being) approaches
• Type IS Capability concept is well-explained

4. Bilingual Consistency

• FAQ updates in both English and Japanese are consistent
• Translation quality is good

---

Suggestions for Improvement

1. Link Consistency in llms.txt (Lines 9-17)

The documentation links use different path styles. Some use absolute paths like /manuals/1.0/en/01-overview.html while llms-full.txt uses full URLs. For consistency and portability, consider using full URLs throughout since this will be hosted on GitHub Pages and fetched by AI agents.

2. Code Example Clarity

In llms-full.txt, the Final class examples (lines 255-297) show hardcoded property initialization. While this is clear for the example, it might be worth adding a comment explaining that in real-world usage, these might be determined by business logic rather than hardcoded.

3. Potential Discoverability Enhancements

Consider adding a brief mention in the main README.md pointing to llms.txt for better discoverability.

---

Code Quality Assessment

Documentation Quality: Excellent

• Clear, concise, well-structured
• Good balance of theory and practice
• Appropriate detail level for target audience (AI agents)

Accuracy: Verified

• Code examples appear syntactically correct
• Concepts align with framework philosophy
• No obvious technical errors

Completeness: Comprehensive

• Covers all essential concepts
• Includes error handling
• Shows both simple and complex patterns
• Project structure guide included

---

Security and Performance

Security: No Concerns

• No sensitive information exposed
• Static documentation files only
• Safe markdown and text content

Performance: Optimal

• Text files are lightweight
• No dynamic content generation needed
• Will serve efficiently from GitHub Pages

---

Testing Considerations

Manual testing needed after deployment:

1. Verify all documentation links work
2. Test that llms.txt is accessible at https://be-framework.github.io/llms.txt
3. Test llms-full.txt accessibility
4. Verify markdown rendering in FAQ pages

Optional: Add a simple CI test that validates all internal links in the llms files resolve correctly.

---

Final Verdict

Status: Approve with minor suggestions

This PR is well-executed and ready to merge. The suggestions above are enhancements, not blockers. The core contribution making Be Framework accessible to AI agents is solid and valuable.

Immediate Action: Safe to merge as-is

Follow-up Considerations (optional):

• Link consistency review
• CI link validation
• README.md mention of llms.txt

Great work on making ontological programming more accessible to AI!

[koriym]

Fixed: Updated llms.txt to use full URLs for AI agent compatibility.