OSS-first docs
These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.
Entity-bound forms treat the business entity as the stable semantic anchor and the form as a renderable projection. A customer, appointment, or other entity can expose quick, full, edit, intake, or part projections without turning each projection into a new entity type.
Authoring model
•
Keep canonical entity identity and true entity-to-entity cardinality on entity contracts.
•
Keep renderable fields, layout, policy, and actions on `FormSpec`.
•
Bind a form projection to an entity with metadata such as entity key, projection kind, version, and field/path mappings.
•
Use form-part bindings for identity, address, contact, and other sub-capture surfaces when they are parts of one entity.
•
Use `EdgeSpec` only for real entity relations, such as customer-to-appointment, not for field-group containment.
Capture versus readiness
Capture acceptance and completion readiness are intentionally separate:
1.
**Capture accepted** means the user or message provided enough information to preserve a draft/intake payload.
2.
**Completion debt** records skipped or missing fields with path/profile metadata.
3.
**Strict readiness** can later require a full profile without invalidating the original capture.
This keeps quick creation and message intake permissive while still giving downstream workflows explicit quality gates.
Communication intake boundary
Communication runtime may map a normalized message/request into an entity-bound intake payload, but it should stay deterministic and adapter-free. The first-pass hook should carry source references such as message id, thread id, and channel, then return accepted values plus completion debt. Full AI extraction, persistence, and CommunicationOS UI remain downstream concerns.
Package exports
Consumers should import the form projection documentation surface from `@lssm-tech/lib.contracts-spec/forms/entity-bound` and implementation primitives from `@lssm-tech/lib.contracts-spec/forms` unless a narrower subpath is introduced with matching package exports and tests.