PriceForge/bible-local/bible/architecture/submodule-integration-contract.md

Submodule Integration Contract

Canonical Consumption Model

Host repositories consume this project as a git submodule and copy/sync selected artifacts from the kit into their own repository.

Direct runtime dependency on submodule paths is not the default integration pattern.

Recommended Host Placement

• tools/ui-design-code
• third_party/ui-design-code

Stable Public Surface

Host repositories may rely on:

• kit/
• exports/
• tools/designsync/
• VERSIONING.md
• CHANGELOG.md

demo/ is reference-only and not part of the stable integration contract.

Bundles

Bundle definitions live in exports/bundles/*.yaml and are indexed by exports/index.yaml.

Each bundle must define:

• stable id
• version
• source paths under kit/
• target mapping rules
• conflict policy
• template variables (if any)

Safety Rules

• Bundle manifests must not write outside the declared host target root.
• designsync must reject path traversal in manifest source/target paths.