INSTRUCTIONS

The file map (deployed into src/)

Don’t read the shipped files — this table and the contracts below are everything you need. Open a shipped file’s source only on a real fallback (runtime error / uncovered field).

There are no shipped components — the data layer and hooks are the machinery; every component is yours.

Astro stack additionally gets:

There are no shipped pages — you author them (below).

What you build — the design job

Read the seed plan first: its collections, field keys, and permissions are the contract your pages bind to (collection ids and field keys verbatim).

1. A listing surface per content collection — your card (image, title, secondary fields) and rhythm, with skeletons while loading and an honest empty state — on useCollection (or SSR via queryItems alone when the page needs no interactivity).
2. An item page per collection with a slug field — your detail layout on the DTO (SSR fetch via getItemBy), with a real 404 on miss.
3. The home page — hero, featured items (fetch in frontmatter → your components), brand story.

Plus the theme (@theme block, one edit) and the chrome (SiteLayout, one pass). Style everything with Tailwind utilities on the tokens.

The contracts your components consume

Wiring — Astro (default)

1. Set the @theme tokens (one edit); brand SiteLayout.astro (one pass) and add one nav link per content surface.

2. Author your pages under src/pages/ — SSR fetch in the frontmatter, DTO props to your islands (client:load; a page with no interactivity needs no island at all). Listing:

   astroCopy

   ---
   import SiteLayout from "../layouts/SiteLayout.astro";
   import { queryItems } from "../wix/cms/items";
   import type { CmsPage } from "../wix/cms/types";
   let page: CmsPage = { items: [], hasNext: false, total: null };
   try {
     page = await queryItems("recipes", { sort: [{ field: "publishDate", direction: "desc" }] });
   } catch {
     // an unguarded SSR throw truncates the response mid-stream
   }
   ---

   Item page (src/pages/recipes/[slug].astro): getItemBy("recipes", "slug", Astro.params.slug!) in the frontmatter; return new Response(null, { status: 404 }) on null. SEO is plain <title>/<meta name="description"> from the DTO via the layout props — CMS collections have no owner-editable SEO item type, so don’t copy another vertical’s wixMetadata/<SEO.Tags> wiring.

3. Author your surfaces in as few messages as possible — batch multiple Writes per message (components and pages are independent files).

Wiring — React SPA (Vite etc.)

Import ./styles/global.css once at the app entry (needs @tailwindcss/vite in the vite plugins — deploy added the dep). Routes are yours: a list route per collection on useCollection, a detail route on useItem with by: { field: "slug", value }.

Hard rules

• Data only through the shipped exports — never re-derive a Wix Data request, never import @wix/data directly in your components, never hand-build a static.wixstatic.com URL.
• The id is _id, fields are flat — item.id is undefined; item.data.title is the REST shape and reads undefined.
• Bind by the seed plan’s ids and keys verbatim — collection ids have no namespace; a mistyped field key reads as a blank, not an error.
• An empty read on a PUBLIC collection is a seed permissions bug (read must be ANYONE) — fix the seed, never reach for auth.elevate (it doesn’t exist on this path). On a member-scoped collection an empty anonymous read is the gate working, not a bug.
• updateItem REPLACES the whole item — omitted fields are wiped. Spread the full item, or use patchItemFields. Date fields on any write are Date objects — a round-tripped ISO string is silently stored as text and breaks date queries.
• Writes 403 unless the collection was seeded with that verb open — surface a 403 as a permissions setup step (which permission, where in the dashboard), not a code bug.
• User-created content is a CMS contribution flow. For a member or visitor submission that the app must later list, use the seeded CMS collection and its intended permission preset. If the operation needs elevated access — especially a browser-created file that must enter Media Manager — follow references/shared/CUSTOM_OPERATIONS.md: validate the caller and input in a narrow server endpoint before elevating one documented operation. Never call a privileged Media API directly from a client island.
• Use the shipped upload capability when it fits. Declare its named policy in plan.capabilities.mediaUpload; Fast deploys the endpoint, client helper, dependencies, and generated policy module. Your CMS surface calls uploadMedia(policyId, file) and stores the returned Wix Media reference. Do not author another upload endpoint for that flow.
• RICH_TEXT is HTML, not plain text — render it with set:html (Astro) / dangerouslySetInnerHTML (React) on a wrapper; never interpolate it as text.
• Reference fields hold ids unless the query passed include — don’t render an id as content.
• Guard absent IMAGE fields — render a fallback, never an empty/broken <img>.
• Theme via the @theme tokens; no parallel theme files, no hardcoded palettes.
• Live data or an honest empty state — never mock items or invent fields not in the plan.

Point the user to their dashboard

Give the owner the dashboard link — the deploy step’s JSON printed dashboardUrl; append /wix-cms for the collections area (items, fields, and More Actions → Permissions & Privacy live there).

Seeding

Per seed/SEED.md — plain-data plan.json into seed-cms.mjs from the project root. The plan is the content model your pages bind to: design collections that exercise the UI (a slug field per detail page, an IMAGE field with a verified imageUrl per item, a DATE field when the content is chronological).

Verify (before declaring done)

• Not done: Each listing page renders live items SSR (view-source shows titles) through YOUR components; an empty collection shows your honest empty state (no mock items).
• Not done: Item pages resolve by slug with a real 404 on a bad slug.
• Not done: Images render (resolved https URLs, no raw wix:image://); absent images fall back gracefully.
• Not done: Dates render formatted (no “Invalid Date”, no raw ISO strings in copy).
• Not done: RICH_TEXT renders formatted (no visible HTML tags, no [object Object]).
• Not done: Any 403 surfaced as a permissions step with the dashboard link.
• Not done: Listing/item/home surfaces are YOUR designs on the tokens; data-layer/hook files unedited.
• Not done: Dashboard link handed to the owner.