Unit 2 - Enforce controlled branding options and asset guardrails

[zcalifornia-ph]

Summary

Implement template-specific branding rules so Cardiff can support approved customization without opening the door to arbitrary styling or unsafe asset handling. The request contract already exposes options like variant, include_qr, and accent_hex, but Unit 2 requires tighter template-level rules, clearer asset semantics, and stronger packaging/licensing boundaries.

Current repo context

• Template option validation currently lives in the canonical contract layer.
• Asset-path validation already blocks traversal and unsupported paths, but Unit 2 needs template-specific constraints and manifest-level alignment.
• The existing business-card manifest declares required asset slots, but it does not yet capture a full controlled-branding policy.

Scope

• Define allowed typography choices, color rules, logo/image constraints, and approved asset-directory semantics for the business-card template.
• Enforce these rules consistently between cardiff.contract validation and template/render resolution.
• Add tests for invalid options, invalid assets, and supported approved-option combinations.
• Document template customization boundaries, including what can live in-repo versus what must be supplied externally.

Acceptance criteria

• Branding options are flexible only within explicit template package rules and safe asset boundaries.
• Invalid asset paths and seeded unsafe payloads continue to fail safely.
• Supported option combinations are documented and covered by tests.
• Asset and template packaging expectations are concrete enough to satisfy DEP-005.
• The issue closes with evidence aligned to TEST-003 and the Unit 2 acceptance criteria.

Suggested implementation areas

• cardiff/src/cardiff/contract/validation.py
• cardiff/src/cardiff/rendering/models.py
• cardiff/src/cardiff/rendering/templates.py
• cardiff/src/cardiff/templates/business-card/manifest.json
• cardiff/tests/contract/test_validation.py
• cardiff/tests/contract/test_security.py
• cardiff/docs/validation-contract.md

Out of scope

• Remote asset fetching
• Arbitrary user-supplied fonts with no packaging or licensing rules
• General-purpose theme/plugin systems

Labels: enhancement, python, latex, for experienced devs

Issue 4

Title: Unit 2 - Add QR-safe template support and approval sample set

Summary

Add optional QR behavior for the approved business-card template, but only if it can be implemented inside the Unit 2 guardrails. The request contract already has include_qr, and the current template only prints a text placeholder. Unit 2 needs a real QR-safe layout rule, clear payload constraints, and approval samples that prove required identity fields still win.

Scope

• Define where QR may appear on the card, how large it can be, and when it must be rejected.
• Define what QR payload is allowed for the approved template.
• Implement QR rendering or QR asset generation in a way that stays deterministic enough for tests and review.
• Add QR-on and QR-off approval samples.
• Add tests proving that QR-enabled layouts preserve field legibility and do not violate the approved layout geometry.
• Document when QR is allowed and what payload rules apply.

Acceptance criteria

• Optional QR support works inside explicit placement and sizing rules.
• QR-enabled layouts do not overlap or degrade required identity fields.
• The repo contains a human-reviewable approval sample set for QR-enabled and QR-disabled renders.
• The issue closes with evidence aligned to TEST-007, while keeping Unit 2 security expectations intact.

Suggested implementation areas

• cardiff/src/cardiff/templates/business-card/manifest.json
• cardiff/src/cardiff/templates/business-card/card.tex
• cardiff/src/cardiff/rendering/pipeline.py
• cardiff/src/cardiff/rendering/*
• cardiff/tests/rendering/*
• cardiff/tests/fixtures/approved-samples/business-card/*
• cardiff/docs/render-pipeline.md
• cardiff/docs/validation-contract.md

Out of scope

• Barcode types other than QR
• Arbitrary QR payload formats with no documented policy
• Frontend or API work outside the shared template/rendering surface