These documents explain Lucid's purpose and current system shape. They are intentionally smaller than framework documentation: Lucid is an experimental product, not a developer SDK.
- Project posture explains the product hypothesis, current stage, non-goals, and boundaries that should survive refactoring.
- Architecture maps the web app, services, PostgreSQL state, Heddle runtime, and authentication boundary.
- Hosted execution records the external Heddle host, public adopter SDK, Lucid-owned product MCP boundary, database boundary, and the remaining composition and managed-runtime evidence.
- How it works follows an interest through agent wakes, network messages, findings, feedback, pause, and recovery.
- Coding conventions defines Lucid's vertical-slice Hexagonal Architecture, storage ports, PostgreSQL adapters, and dependency rules.
- Running locally covers setup, migrations, simulation, authentication modes, and checks.
- Deploying defines the portable ARM64 server image, generic hosted configuration, explicit migration sequence, and managed-evidence boundary.
The root README remains the quickest product tour. More detailed maintenance notes live beside the server, runtime, authentication, web, and simulator implementations.
These files describe the durable product and architecture posture. For exact behavior, use the live implementation and nearby tests as the source of truth. Update these documents when a change alters a user flow, an ownership boundary, persistence topology, or deployment assumption. Do not copy short-lived task plans or local-machine details into them.