feat(wix-headless): merge index.astro home contributions in orchestrator

[moranshe-max]

Summary

• Phase 4 page agents that target home:* markers in src/pages/index.astro no longer patch the file at those markers themselves.
• Each agent returns its contribution as data.homeContributions = { imports, frontmatter, byMarker }.
• The orchestrator collects all returns and invokes a new scripts/merge-home.mjs once to splice contributions in deterministically.

Why

Two Phase 4 page agents currently patch index.astro at distinct home:* markers:

Agent	Marker
stores-pages-home-and-nav	home:stores (featured products grid)
gift-cards-pages	home:gift-cards (probe-gated teaser)

The markers don't collide (unlike nav:links in PR #209), but the failure mode this PR fixes is real: the 2026-05 Moran's Bakery run hit a MARKER_NOT_FOUND on <!-- home:gift-cards --> because the designer didn't emit it — gift-cards is a disabled: true pack and the designer was told to skip its surfaces. With orchestrator-merge, that omission becomes a structured skipped[] output from the merge script (non-fatal, observable) rather than getting buried inside an agent return.

The model also matches the sibling PR #209 (Navigation.astro) — both shared shells now use the same contribution → merge pattern, which keeps the surface area of "who can write what file" small and explicit.

Design

scripts/merge-home.mjs is structurally identical to scripts/merge-navigation.mjs:

• Dedupes imports[] and frontmatter[] against the designer's existing content (exact-line match after trim).
• Groups contributions per marker so multiple agents at the same marker join in input order. Input order = render order.
• Mirrors indentation of the marker line onto every line of every snippet.
• Reports unknown markers in skipped[] (status: partial) rather than hard-failing. This is the key motivation: the missing <!-- home:gift-cards --> from the disabled gift-cards pack now surfaces here rather than failing silently inside an agent.
• Atomic write (write-then-rename). Not idempotent by design — orchestrator invokes exactly once.

Note on stores home-and-nav scope

That agent still writes src/pages/index.astro directly for non-marker category-card href rewrites (rewriting designer-placeholder slugs against the real categoriesV3 catalog). Those edits are independent of the home:stores marker insertion. The orchestrator reads the post-edit file before invoking merge-home.mjs, so the rewrites are preserved.

In other words: only the marker-bound portion of each agent's home work moves to the contribution model. Non-marker surgical edits keep happening as direct writes by the owning agent.

What changed

File	Change
skills/wix-headless/scripts/merge-home.mjs	new — splices home contributions, dedupes imports/frontmatter, reports missing markers
skills/wix-headless/SKILL.md	Wave 6 step list adds new `merge-home` step (parallel to `merge-navigation` from PR #209); `requiredPhases` adds `merge-home`; renumbered subsequent steps; wave table row 6 mentions the script
skills/wix-headless/references/shared/RETURN_CONTRACT.md	New section "Phase 2: homeContributions" — identical shape to navContributions, with stores example
skills/wix-headless/references/stores/HOME_AND_NAV.md	Section 1 (home page: featured products) rewritten to return JSON instead of patching the marker. Section 2 (category-card href rewrites) UNCHANGED because it's a direct edit. Return-format updated.
skills/wix-headless/references/gift-cards/PAGES.md	Section 3 (Patch index.astro) rewritten to return JSON. The disabled-pack `MARKER_NOT_FOUND` case now surfaces via the merge script's `skipped[]` rather than agent error code.
skills/wix-headless/references/verticals/gift-cards.md	Removes `src/pages/index.astro (patch — gift-cards teaser)` from `pages.gift-cards-pages.files[]`. stores.md keeps `src/pages/index.astro` because that scope still writes it for non-marker rewrites.

Test plan

• Smoke test the script with 2 contributions at different markers; verify both inserted, marker comments preserved
• Dedupe: shared imports across contributions appear once
• Missing marker (gift-cards) reported in skipped[] with MARKER_NOT_FOUND; status: partial; exit code 0 (non-fatal)
• Indentation: snippets inserted after an indented marker line are themselves indented to match
• No --- frontmatter → script exits 2
• End-to-end skill run with the updated SKILL.md flow on a stores+ecom+cms+gift-cards build
• Verify category-href rewrites by stores home-and-nav still take effect (orchestrator reads index.astro AFTER the agent's edits)

Open follow-ups (not in this PR)

• This PR + feat(wix-headless): merge Navigation.astro contributions in orchestrator #209 together establish the contribution → merge pattern for two shared shells. Future packs adding home or nav surfaces should adopt the same model. Blog and forms packs already declare contributes: entries; their Phase 4 agents would adopt this contract when those flows are exercised.
• A small generalization is plausible: scripts/merge-shared-astro.mjs <file> covering both Navigation.astro and index.astro (the splicer logic is identical). Left for a future cleanup — keeping two scripts is clearer for now.

Notes

• Opens as draft while sibling PRs in this series land. Companion to feat(wix-headless): orchestrator writes .wix/image-urls.md from image agent's return #207 (image-urls), feat(wix-headless): merge-site-json.mjs script for deterministic site.json updates #208 (merge-site-json), feat(wix-headless): merge Navigation.astro contributions in orchestrator #209 (merge-navigation). All four are part of the same "orchestrator owns shared file writes" theme.

🤖 Generated with Claude Code