docs: add llms.txt and AI agent FAQ

llms-full.txt

@@ -0,0 +1,347 @@
+# Be Framework - Full Documentation
+
+> Objects don't DO things—they BECOME things.
+
+Be Framework is a PHP framework for ontological programming where transformation (metamorphosis) replaces procedural action.
+
+## Core Philosophy
+
+A patient doesn't "get triaged." They **become** an emergency case or an observation case, based on the transcendent wisdom of medical protocol.
+
+## Key Concepts
+
+### Domain Ontology (Semantic Variables)
+
+Semantic variables define what CAN exist in a domain—not just validation rules, but the vocabulary of existence. This declarative foundation serves as documentation that both humans and AI can read to understand your domain.
+
+```php
+final class BodyTemperature
+{
+    #[Validate]
+    public function validate(float $bodyTemperature): void
+    {
+        if ($bodyTemperature < 30.0 || $bodyTemperature > 45.0) {
+            throw new LethalVitalException();
+        }
+    }
+}
+```
+
+### Reason (Transcendence)
+
+Domain logic becomes a first-class citizen: injectable, testable, and explicitly visible.
+
+```php
+final readonly class JTASProtocol
+{
+    /** @return 'emergency'|'observation' */
+    public function assess(float $bodyTemperature, int $heartRate): string
+    {
+        if ($bodyTemperature >= 39.0 || $heartRate >= 120) {
+            return 'emergency';
+        }
+        return 'observation';
+    }
+}
+```
+
+### Metamorphosis Pattern
+
+Input → Being → Final transformation through the Becoming class.
+
+```php
+$becoming = new Becoming($injector, 'Be\\App\\Semantic');
+$patient = new PatientArrival(bodyTemperature: 39.5, heartRate: 90);
+$result = $becoming($patient);
+// $result IS an EmergencyCase or ObservationCase
+```
+
+### Type-Driven Branching
+
+The `$being` property (Union type) determines which Final class receives the transformation.
+
+```php
+#[Be([EmergencyCase::class, ObservationCase::class])]
+final readonly class TriageAssessment
+{
+    public Emergency|Observation $being;
+
+    public function __construct(
+        #[Input] public float $bodyTemperature,
+        #[Input] public int $heartRate,
+        #[Inject] JTASProtocol $protocol
+    ) {
+        $urgency = $protocol->assess($bodyTemperature, $heartRate);
+        $this->being = ($urgency === 'emergency')
+            ? new Emergency()
+            : new Observation();
+    }
+}
+```
+
+### Type IS Capability
+
+Different Final types have different methods—the type determines what actions are possible.
+
+```php
+// EmergencyCase has assignER()
+// ObservationCase has assignWaitingArea()
+$result->assignER();  // Only possible for EmergencyCase
+```
+
+## Key Attributes
+
+- `#[Be([TargetClass::class])]` - Declares metamorphosis destination(s)
+- `#[Input]` - Receives data from previous stage
+- `#[Inject]` - Receives transcendent capability (DI)
+- `#[Validate]` - Semantic validation method marker
+
+## Domain Types (PHPDoc Union Types)
+
+Use PHPDoc union types to define domain vocabulary:
+
+```php
+final readonly class JTASProtocol
+{
+    /** @return 'emergency'|'observation' */
+    public function assess(float $bodyTemperature, int $heartRate): string
+    {
+        // ...
+    }
+}
+
+final readonly class EmergencyCase
+{
+    /** @var 'IMMEDIATE'|'DELAYED' */
+    public string $priority;
+    /** @var 'RED'|'GREEN' */
+    public string $color;
+}
+```
+
+This makes the domain vocabulary explicit and enables static analysis tools (Psalm, PHPStan) to catch invalid values.
+
+## Naming Conventions
+
+### Semantic Variables
+
+Semantic class name matches constructor parameter name (camelCase):
+
+- `BodyTemperature` class validates `$bodyTemperature` parameter
+- `HeartRate` class validates `$heartRate` parameter
+
+### Destiny Markers and Final Classes
+
+Final class receives the destiny marker matching its `#[Input]` type:
+
+```php
+// Destiny markers (empty classes that ARE the distinction)
+final readonly class Emergency {}
+final readonly class Observation {}
+
+// Final classes receive matching destiny via #[Input]
+final readonly class EmergencyCase
+{
+    public function __construct(
+        #[Input] public Emergency $being  // Receives Emergency marker
+    ) {}
+}
+
+final readonly class ObservationCase
+{
+    public function __construct(
+        #[Input] public Observation $being  // Receives Observation marker
+    ) {}
+}
+```
+
+## Transformation Flow
+
+### With Branching (Input → Being → Final)
+
+```
+Input (with #[Be([Being::class])])
+    ↓ Becoming executes
+Being (with #[Be([Final1::class, Final2::class])])
+    ↓ $being property determines branch
+Final (capability-specific type)
+```
+
+### Direct (Input → Final)
+
+When no branching is needed, Input can transform directly to Final:
+
+```php
+#[Be([Hello::class])]
+final readonly class HelloInput
+{
+    public function __construct(public string $name) {}
+}
+
+final readonly class Hello
+{
+    public function __construct(
+        #[Input] public string $name,
+        #[Inject] Greeting $greeting
+    ) {}
+}
+```
+
+## Error Handling
+
+When semantic validation fails, metamorphosis is rejected:
+
+```php
+try {
+    $becoming($input);
+} catch (SemanticVariableException $e) {
+    $messages = $e->getErrors()->getMessages('en');
+    // ["Vital signs indicate non-survivable conditions."]
+}
+```
+
+## Project Structure
+
+```
+src/
+├── Input/          # Starting points (raw data)
+├── Being/          # Intermediate transformations
+├── Final/          # Destinations (capability-specific types)
+├── Reason/         # Transcendent wisdom (domain logic)
+├── Semantic/       # Domain ontology (what CAN exist)
+├── Exception/      # Domain exceptions
+└── Module/         # DI configuration
+```
+
+## Example: Emergency Triage
+
+### Input Class
+
+```php
+#[Be([TriageAssessment::class])]
+final readonly class PatientArrival
+{
+    public function __construct(
+        public float $bodyTemperature,
+        public int $heartRate
+    ) {}
+}
+```
+
+### Being Class
+
+```php
+#[Be([EmergencyCase::class, ObservationCase::class])]
+final readonly class TriageAssessment
+{
+    public Emergency|Observation $being;
+
+    public function __construct(
+        #[Input] public float $bodyTemperature,
+        #[Input] public int $heartRate,
+        #[Inject] JTASProtocol $protocol
+    ) {
+        $urgency = $protocol->assess($bodyTemperature, $heartRate);
+        $this->being = ($urgency === 'emergency')
+            ? new Emergency()
+            : new Observation();
+    }
+}
+```
+
+### Final Classes
+
+```php
+final readonly class EmergencyCase
+{
+    /** @var 'IMMEDIATE'|'DELAYED' */
+    public string $priority;
+    /** @var 'RED'|'GREEN' */
+    public string $color;
+
+    public function __construct(
+        #[Input] public float $bodyTemperature,
+        #[Input] public int $heartRate,
+        #[Input] public Emergency $being
+    ) {
+        $this->priority = 'IMMEDIATE';
+        $this->color = 'RED';
+    }
+
+    public function assignER(): string
+    {
+        return "Secure ER Room 1 immediately.";
+    }
+}
+
+final readonly class ObservationCase
+{
+    /** @var 'IMMEDIATE'|'DELAYED' */
+    public string $priority;
+    /** @var 'RED'|'GREEN' */
+    public string $color;
+
+    public function __construct(
+        #[Input] public float $bodyTemperature,
+        #[Input] public int $heartRate,
+        #[Input] public Observation $being
+    ) {
+        $this->priority = 'DELAYED';
+        $this->color = 'GREEN';
+    }
+
+    public function assignWaitingArea(): string
+    {
+        return "Move to waiting area.";
+    }
+}
+```
+
+### Execution
+
+```php
+$injector = new Injector(new AppModule());
+$becoming = new Becoming($injector, 'Be\\App\\Semantic');
+
+$patient = new PatientArrival(bodyTemperature: 39.5, heartRate: 90);
+$result = $becoming($patient);
+
+echo $result->priority;     // "IMMEDIATE"
+echo $result->assignER();   // "Secure ER Room 1 immediately."
+```
+
+## Why Being Over Doing
+
+### Traditional (Doing)
+
+```php
+$patient = new Patient($temp, $hr);
+if ($triageService->isEmergency($patient)) {
+    $patient->setStatus('emergency');
+    $this->erService->assign($patient);
+}
+```
+
+Problems:
+- Patient can exist in invalid state
+- Status can be changed at any time
+- `erService->assign()` can be called on any patient
+
+### Be Framework (Being)
+
+```php
+$patient = new PatientArrival($temp, $hr);
+$result = $becoming($patient);
+$result->assignER();  // Type-safe: only possible for EmergencyCase
+```
+
+Benefits:
+- Non-survivable states cannot exist
+- Type IS the status (immutable)
+- Capabilities belong to existence
+
+## Documentation
+
+- English: https://be-framework.github.io/manuals/1.0/en/
+- Japanese: https://be-framework.github.io/manuals/1.0/ja/
+- Repository: https://github.com/be-framework/be-framework

llms.txt

@@ -0,0 +1,25 @@
+# Be Framework
+
+> Objects don't DO things—they BECOME things.
+
+Be Framework is a PHP framework for ontological programming where transformation (metamorphosis) replaces procedural action.
+
+## Documentation
+
+- [Overview](https://be-framework.github.io/manuals/1.0/en/01-overview.html): Framework philosophy
+- [Getting Started](https://be-framework.github.io/manuals/1.0/en/getting-started.html): Quick start guide
+- [Tutorial](https://be-framework.github.io/manuals/1.0/en/tutorial.html): Emergency Triage example
+- [Input Classes](https://be-framework.github.io/manuals/1.0/en/02-input-classes.html): Starting points
+- [Being Classes](https://be-framework.github.io/manuals/1.0/en/03-being-classes.html): Intermediate transformations
+- [Final Objects](https://be-framework.github.io/manuals/1.0/en/04-final-objects.html): Destinations
+- [Semantic Variables](https://be-framework.github.io/manuals/1.0/en/06-semantic-variables.html): Domain validation
+- [Type-Driven Metamorphosis](https://be-framework.github.io/manuals/1.0/en/07-type-driven-metamorphosis.html): Branching patterns
+- [Reason Layer](https://be-framework.github.io/manuals/1.0/en/08-reason-layer.html): Transcendence
+
+## Full Documentation
+
+For detailed API and examples, see [llms-full.txt](https://be-framework.github.io/llms-full.txt)
+
+## Repository
+
+https://github.com/be-framework/be-framework

manuals/1.0/en/faq.md

@@ -269,7 +269,21 @@ A mechanism for holding failures and history not as simple strings, but as struc
 
 ---
 
-## 11) Related Chapter Links
+## 11) Using AI Agents
+
+### Q27. How do I get AI to write Be Framework code?
+
+A. Simply ask the AI to read the llms-full.txt:
+
+```
+Please read https://be-framework.github.io/llms-full.txt
+```
+
+This file contains all the key concepts, naming conventions, and code examples needed for AI to understand and generate Be Framework code.
+
+---
+
+## 12) Related Chapter Links
 
 * **[Overview](./01-overview.html)**: First encounter with being-oriented programming
 * **[Metamorphosis](./05-metamorphosis.html)**: Inseparability of time and domain