@wix/agent-skills 1.0.0

package/skills/wix-headless/references/SETUP.md

@@ -0,0 +1,154 @@
+# Setup
+
+Runs once per session, immediately after plan approval. Establishes MCP connectivity, installs apps, pulls env, kicks off npm install in background, writes memory, creates the user-facing roadmap.
+
+Target: **~15 seconds on the critical path** (everything after the MCP prefix discovery in Step 0 runs as a single concurrent batch).
+
+---
+
+## Step 0 — MCP Prefix Discovery + Schema Bootstrap (first time only)
+
+Runs once per session, before any MCP call. Separate from the Setup step because it requires a sequential **discover prefix → verify connectivity → bootstrap schemas** chain.
+
+1. **Discover the MCP prefix.** Wix MCP tool names take the form `<prefix>WixREADME`. Use whatever tool-discovery primitive your runtime provides to look up `WixREADME` and strip the trailing suffix from the returned tool name — the remainder (ending in `wix-mcp-remote__` or similar) is the **MCP prefix**.
+2. Call `<prefix>WixREADME` once to verify connectivity.
+3. If discovery returns no match or the verify call fails → stop and tell the user: *"Wix MCP tools are not available in this session. Please ensure the Wix MCP server is connected (or that the Wix plugin is enabled), then restart your client."*
+4. **Pre-load Wix MCP tool schemas** — read `<SKILL_ROOT>/references/commands/mcp-bootstrap.md` and follow its single `ToolSearch` invocation. Loads every Wix MCP tool schema the build will use (CallWixSiteAPI, SearchWixRESTDocumentation, ReadFullDocsArticle, ReadFullDocsMethodSchema, SearchWixCLIDocumentation, SearchWixSDKDocumentation, SearchWixHeadlessDocumentation, SearchWixWDSDocumentation, SearchBuildAppsDocumentation, BrowseWixRESTDocsMenu).
+5. Hold the prefix for the whole session. Pass it into **every** subagent prompt as:
+   ```
+   MCP tool prefix: <prefix>
+   Use this prefix for every Wix MCP call. Example: <prefix>CallWixSiteAPI, <prefix>WixREADME.
+   ```
+
+See `references/shared/MCP_PREFIX.md` for the tool-not-found recovery procedure that subagents use if the prefix somehow fails downstream.
+
+> **Why the MCP bootstrap is mandatory.** Without it, the first `CallWixSiteAPI` emits `body` as a JSON string (because the schema isn't loaded) and returns `Expected object, received string`. Pinning the schema-load list in `references/commands/mcp-bootstrap.md` and reading it as a discrete step makes the operation impossible to skim past — the orchestrator can skip a footnote; it can't skip a numbered step that resolves to a single concrete tool call.
+
+---
+
+## Setup Dispatch — one concurrent batch
+
+> **BATCHING — read this twice before proceeding.**
+>
+> Launch every operation below as a single concurrent batch. No narration, no *"Now setting up:"*, no transition text between dispatches.
+>
+> Any text adjacent to a dispatch closes the batch and forces remaining operations into separate turns. An earlier run lost 13s to roadmap-tracker calls splitting across 13 turns; an earlier run lost ~50 minutes to an npm install recovery gate. Both are eliminated by strict single-batch dispatch here.
+
+### Contents of the setup dispatch
+
+The skill assembles this dispatch dynamically from the loaded vertical packs. The items below list what to emit.
+
+#### 1. Verify scaffold completed
+
+**Before the setup dispatch:** read `<project>/wix.config.json` to confirm the background scaffold from Discovery Step 1 finished. If not, wait for the background scaffold to finish. On scaffold failure, retry the inline `npm create @wix/new` call once (same shell command from DISCOVERY.md Step 1); surface the error if it still fails. Recovery ladder is documented in DISCOVERY.md § "Strict-then-recover" — auth, invalid template, etc.
+
+Once `wix.config.json` exists, extract `siteId` (value of the `siteId` field — this is the businessId for all MCP calls in the session).
+
+`cd` into the project directory so all subsequent file operations and shell commands are relative to it.
+
+#### 2. The dispatch itself (one concurrent batch)
+
+**MCP app installs** — one `<prefix>CallWixSiteAPI` per app in the union of loaded packs' `apps[*]`. Example for an ecommerce run (stores pack contributes one app; cms pack contributes none):
+
+```
+<prefix>CallWixSiteAPI(
+  siteId: "<siteId>",
+  reason: "Install Wix Stores app for <brand>",
+  sourceDocUrl: "https://dev.wix.com/docs/picasso/wix-ai-docs/recipes-v2/manage/platform/recipe-install-wix-apps",
+  method: "POST",
+  url: "https://www.wixapis.com/apps-installer-service/v1/app-instance/install",
+  body: {
+    tenant: { tenantType: "SITE", id: "<siteId>" },
+    appInstance: { appDefId: "<pack.apps[0].appDefId>", enabled: true }
+  }
+)
+```
+
+> The `CallWixSiteAPI` schema was already loaded by the Step 0 MCP bootstrap, so `body` is correctly typed as a JSON object on the first call. See `references/shared/MCP_PREFIX.md` § "CallWixSiteAPI call conventions".
+
+A 200 response with `"enabled": true` confirms success.
+
+**Packs with `apps: []` (e.g. `cms`)** — record a phase entry in `run.json` anyway: `{phase: "app-install-<pack>", status: "skipped", notes: "Bundled with Wix platform; no install required"}`. Without an explicit skipped entry, `run.json` reads as a silent omission ("did the CMS install run? was it skipped? did it fail?"); the explicit entry makes observability unambiguous.
+
+**Namespace propagation:** After app install, the app's API namespace may take up to 30 seconds to register. If a downstream MCP call fails with `UNSUPPORTED_FORM_NAMESPACE`, wait 10 seconds and retry up to 3 times. Phase 1 Seeders handle this retry themselves.
+
+**Shell: `npx @wix/cli env pull`** (foreground, ~5s). Writes `WIX_CLIENT_ID` to `.env.local`. Idempotent. Skipping this historically caused `Missing environment variable WIX_CLIENT_ID` build failures.
+
+**Background shell: `npm install ...`**:
+
+The package list is the union of:
+- Always: `@wix/sdk tailwindcss @tailwindcss/vite`
+- Per loaded pack: each pack's `packages` array
+
+> **Do not add any package beyond this set.** If a pack feels like it should have its own SDK (`@wix/<pack-name>`), confirm by reading its `packages:` array. Passive packs (gift-cards) intentionally declare nothing because they're runtime-detected via REST. There is no `@wix/gift-cards` SDK on npm — adding it on a hunch fails with `npm 404`. Same logic for any other pack: the union above is the install list. Period.
+
+Flags: `--no-fund --no-audit --legacy-peer-deps`. `--legacy-peer-deps` is mandatory (Wix SDK transitive peer conflicts). `--no-fund --no-audit` prevent interactive prompts that hang agent sessions.
+
+Because scaffold runs with `--skip-install`, delete the stale lockfile before installing: `rm -f package-lock.json`.
+
+Example combined command (ecommerce run):
+```bash
+rm -f package-lock.json && npm install --no-fund --no-audit --legacy-peer-deps \
+  @wix/sdk tailwindcss @tailwindcss/vite \
+  @wix/stores @wix/ecom @wix/redirects @wix/site \
+  @wix/data @wix/essentials
+```
+
+Capture the background process's handle (whatever your runtime uses to wait on a long-running shell) for later wait in Step 8 (Build & Preview).
+
+**Memory writes** — two writes:
+1. `MEMORY.md` index entry (one line)
+2. `project`-type memory file with brand, vertical(s), apps, pages, project path, phase: `scaffolding`
+
+**User-facing roadmap × N** — target 6–8 entries mapped to phase boundaries:
+
+| Entry | Marks completed |
+|------|-----------------|
+| Scaffold project | Immediately on creation (already done in Discovery) |
+| Install apps | Immediately on creation (this dispatch) |
+| Seed data | After Phase 1 Seed returns (Step 6) |
+| Design site | After Phase 2 Design System returns (Step 4) |
+| Generate images | After image subagent returns (may finish later than critical path) |
+| Wire features | After Phase 3 Components + Phase 4 Pages return (Step 7/8) |
+| Install dependencies | After npm install background shell completes (Step 8) |
+| Build and preview | After Step 8 |
+
+> **No ampersands in roadmap titles.** Some progress trackers HTML-escape input — `"Build & preview"` renders as literal `Build &amp; preview`. Spell out "and" (or restructure) to avoid `&`. Same for `<`, `>`, `"` and other HTML-meaningful characters.
+
+> **Avoid the 13-entry sprawl.** Historical runs used one entry per phase-per-feature ("Design page — Home", "Seed stores", "Wire CMS", etc.). Collapse to the phase-boundary list above. Users care about milestones, not sub-phases.
+
+**Shell: `mkdir -p .wix`** — minimal. No `.wix/logs/`.
+
+### Batching verification
+
+After the dispatch, the run log should show ~8–12 operations dispatched as one concurrent batch (varies by pack count). If they spread across multiple turns, the batching guidance failed and the skill needs to be tightened.
+
+---
+
+## npm install recovery
+
+If the background npm install from the Setup dispatch fails or hangs:
+
+1. **Foreground retry with 90-second timeout:**
+   ```bash
+   npm install --no-fund --no-audit --legacy-peer-deps <packages>
+   ```
+
+2. **If still hanging, retry with `--prefer-offline`:**
+   ```bash
+   npm install --prefer-offline --no-fund --no-audit --legacy-peer-deps <packages>
+   ```
+
+3. **If still hanging, clear the cache:**
+   ```bash
+   npm cache clean --force
+   npm install --no-fund --no-audit --legacy-peer-deps <packages>
+   ```
+
+4. **Last resort:** tell the user: *"npm install is hanging. Please run `npm install --legacy-peer-deps` manually in your terminal, then let me know when it's done."*
+
+---
+
+## After the Setup Dispatch
+
+Proceed immediately to **Step 3 — Phase 1 Seed + Phase 2 Design System + Image Phase 1** — see `ORCHESTRATION.md`. Do not wait for the background npm install; that's waited on in Step 8.

package/skills/wix-headless/references/blog/BLOG_CONTENT.md

@@ -0,0 +1,152 @@
+# Recipe: Seed Initial Blog Posts via MCP
+
+Create 3 on-brand blog posts so the blog has real content on first preview.
+
+> **Critical Rules — Read Before Starting**
+> 1. **Seed content is required** — a blog with zero posts on first preview is a build failure. Do not skip this section.
+> 2. **Re-publish after PATCH** — updating a published post sets `hasUnpublishedChanges: true`. Call `publish` again or visitors see the old version.
+> 3. **Use `@wix/blog`, not `@wix/data`** — blog posts are NOT CMS collections.
+> 4. **`RICH_CONTENT` fieldset required** — without it, `post.richContent` is undefined and rendering fails.
+
+> **Required in the Seed phase.** When dispatched with `Scope: seed`, MCP tools and discovery context are guaranteed available. Always execute this section — do not skip. A blog with zero posts on first preview is a build failure.
+>
+> **Skip only for standalone invocations** where the Blog skill is invoked directly AND `mcp__wix-mcp-remote__CallWixSiteAPI` is genuinely unavailable. In that case, the user can create posts manually in the Wix dashboard.
+
+## Step 0: Ensure Blog App Is Installed
+
+Before querying blog data, verify the Blog app is installed:
+
+1. **Probe** — `CallWixSiteAPI: POST /blog/v3/posts/query` with body `{ "query": { "paging": { "limit": 1 } } }`
+2. **If the API returns a "REQUIRED_APP_NOT_INSTALLED" error** → install the Wix Blog app:
+   ```
+   CallWixSiteAPI: POST https://www.wixapis.com/apps-installer-service/v1/app-instance/install
+   body: {
+     "tenant": { "tenantType": "SITE", "id": "<siteId>" },
+     "appInstance": { "appDefId": "14bcded7-0066-7c35-14d7-466cb3f09103", "enabled": true }
+   }
+   ```
+   > Translate this prose-HTTP form into the full `CallWixSiteAPI` tool-call shape — include `siteId`, `reason`, `sourceDocUrl` wrapper fields and pass `body` as a real object (NOT a stringified JSON). See `../../shared/MCP_PREFIX.md` § "CallWixSiteAPI call conventions".
+
+   Then retry the probe query to confirm installation succeeded.
+3. **If the probe succeeds** → proceed to Step 1.
+
+---
+
+## Step 1: Get Member ID
+
+Blog posts require a `memberId` (the post author). Fetch the first site member:
+
+```
+CallWixSiteAPI: GET /members/v1/members
+```
+
+Extract the first member's `_id` from the response. This will be used as the author for all posts.
+
+## Step 2: Design 3 On-Brand Blog Posts
+
+No API call — use discovery context (business type, brand name, tone, industry) to plan 3 posts:
+
+- Titles, summaries, and rich content appropriate for the business
+- Content should demonstrate different Ricos node types (paragraphs, headings, code blocks, lists, blockquotes)
+- Posts should feel like real content a reader would engage with, not placeholder text
+
+**Post design guidelines by business type:**
+
+| Business Type | Post 1 | Post 2 | Post 3 |
+|--------------|--------|--------|--------|
+| AI / tech blog | Architecture deep-dive | Practical comparison (X vs Y) | Lessons learned / field report |
+| Skincare / beauty | Ingredient science spotlight | Routine guide (morning/evening) | Myth-busting or FAQ |
+| Food / restaurant | Behind the recipe | Seasonal menu spotlight | Sourcing / farm-to-table story |
+| Fitness / wellness | Training methodology breakdown | Nutrition or recovery guide | Client transformation story |
+| Fashion / retail | Trend analysis | Styling guide | Behind the brand / process |
+| General business | Industry insight | How-to guide | Company news / milestone |
+
+Adapt titles, tone, and content to match the brand's voice and style.
+
+## Step 3: Create Posts
+
+For each post, call `POST /blog/v3/draft-posts` with `publish: true` to create and immediately publish.
+
+> Do not include the `media` field — cover images are handled separately by the image agent after post creation.
+
+```
+CallWixSiteAPI: POST /blog/v3/draft-posts
+body: {
+  "draftPost": {
+    "title": "<Post Title>",
+    "memberId": "<member-id-from-step-1>",
+    "richContent": {
+      "nodes": [
+        {
+          "type": "HEADING",
+          "id": "<unique-id>",
+          "nodes": [
+            { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "Section Heading", "decorations": [] } }
+          ],
+          "headingData": { "level": 2 }
+        },
+        {
+          "type": "PARAGRAPH",
+          "id": "<unique-id>",
+          "nodes": [
+            { "type": "TEXT", "id": "", "nodes": [], "textData": { "text": "Paragraph content here.", "decorations": [] } }
+          ],
+          "paragraphData": {}
+        }
+      ]
+    }
+  },
+  "publish": true
+}
+```
+
+### Ricos JSON Node Reference
+
+Use these node types to build rich, varied content:
+
+| Node Type | Structure | Use For |
+|-----------|-----------|---------|
+| `PARAGRAPH` | `{ type: "PARAGRAPH", id, nodes: [TEXT], paragraphData: {} }` | Body text |
+| `HEADING` | `{ type: "HEADING", id, nodes: [TEXT], headingData: { level: 2 } }` | Section headers (level 2–4) |
+| `CODE_BLOCK` | `{ type: "CODE_BLOCK", id, nodes: [TEXT], codeBlockData: { language: "javascript" } }` | Code snippets |
+| `BULLETED_LIST` | `{ type: "BULLETED_LIST", id, nodes: [LIST_ITEM] }` | Unordered lists |
+| `LIST_ITEM` | `{ type: "LIST_ITEM", id, nodes: [PARAGRAPH] }` | Items inside BULLETED_LIST |
+| `BLOCKQUOTE` | `{ type: "BLOCKQUOTE", id, nodes: [PARAGRAPH] }` | Pull quotes, callouts |
+| `TEXT` | `{ type: "TEXT", id: "", nodes: [], textData: { text: "...", decorations: [] } }` | Inline text (leaf node inside paragraphs, headings, etc.) |
+
+**Tips:**
+- Container nodes (PARAGRAPH, HEADING, etc.) need a unique `id` (use any string, e.g., `"n1"`, `"n2"`). TEXT nodes can use an empty string `""` for `id`.
+- TEXT nodes are always leaf nodes inside PARAGRAPH, HEADING, CODE_BLOCK, etc.
+- LIST_ITEM nodes contain PARAGRAPH nodes (not TEXT directly)
+- Mix at least 3 different node types per post for visual variety
+- Create all 3 posts in sequence (one `CallWixSiteAPI` call per post)
+- **Best practice:** include all fields (title, content, media) in the initial creation call to avoid needing a re-publish
+
+> **Re-publish after PATCH:** If you update a published post (e.g., adding a cover image via PATCH after creation), it becomes `hasUnpublishedChanges: true`. You must call `POST /blog/v3/draft-posts/{draftPostId}/publish` to re-publish. To avoid this, include media in the initial creation call.
+
+## Step 4: Verify
+
+Query published posts to confirm all 3 exist:
+
+```
+CallWixSiteAPI: POST /blog/v3/posts/query
+body: {
+  "query": {
+    "paging": { "limit": 10 }
+  }
+}
+```
+
+Confirm 3 posts are returned. Report post titles to the user.
+
+### Step 5: Log Results
+
+Write a sidecar file at `.wix/logs/blog-data.md` (see `../../shared/LIFECYCLE_LOG.md` for the sidecar contract). Do **not** append to `.wix/lifecycle.log.md` directly — the orchestrator concatenates all sidecars at the end. Use a `####` heading so the entry nests under `### features-orchestrator` in the assembled log:
+
+```markdown
+## blog
+- Status: complete
+- Content: {n} posts published ({post titles})
+- Images: {generated (n/n attached) | skipped (user declined) | not attempted}
+```
+

package/skills/wix-headless/references/blog/BLOG_PAGES.md

@@ -0,0 +1,299 @@
+# Reference: Blog Pages
+
+Blog listing, post detail, RSS feed, layout, SEO head component, and date formatting.
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `src/pages/blog/index.astro` | Blog listing page |
+| `src/pages/blog/[...slug].astro` | Blog post detail page (with RicosViewer) |
+| `src/pages/rss.xml.js` | RSS feed |
+| `src/layouts/BlogPost.astro` | Blog post layout wrapper |
+| `src/components/BaseHead.astro` | SEO head component (OG/Twitter cards) |
+| `src/components/FormattedDate.astro` | Date formatting helper |
+
+---
+
+## 1. SEO Head Component (`src/components/BaseHead.astro`)
+
+```astro
+---
+import '../styles/global.css';
+
+interface Props {
+  title: string;
+  description: string;
+  image?: string;
+}
+
+const canonicalURL = new URL(Astro.url.pathname, Astro.site);
+
+const { title, description, image = '/blog-placeholder-1.jpg' } = Astro.props;
+---
+
+<!-- Global Metadata -->
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+<meta name="generator" content={Astro.generator} />
+
+<!-- Canonical URL -->
+<link rel="canonical" href={canonicalURL} />
+
+<!-- Primary Meta Tags -->
+<title>{title}</title>
+<meta name="title" content={title} />
+<meta name="description" content={description} />
+
+<!-- Open Graph / Facebook -->
+<meta property="og:type" content="website" />
+<meta property="og:url" content={Astro.url} />
+<meta property="og:title" content={title} />
+<meta property="og:description" content={description} />
+<meta property="og:image" content={new URL(image, Astro.url)} />
+
+<!-- Twitter -->
+<meta property="twitter:card" content="summary_large_image" />
+<meta property="twitter:url" content={Astro.url} />
+<meta property="twitter:title" content={title} />
+<meta property="twitter:description" content={description} />
+<meta property="twitter:image" content={new URL(image, Astro.url)} />
+```
+
+> If the project already has a `<head>` component or `Layout.astro` with SEO tags, adapt the existing component instead of creating a new one. The key additions are the OG/Twitter meta tags with `image` support.
+
+---
+
+## 2. Formatted Date Component (`src/components/FormattedDate.astro`)
+
+```astro
+---
+interface Props {
+  date: Date;
+}
+
+const { date } = Astro.props;
+---
+
+<time datetime={date.toISOString()}>
+  {
+    date.toLocaleDateString('en-us', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    })
+  }
+</time>
+```
+
+---
+
+## 3. Blog Post Layout (`src/layouts/BlogPost.astro`)
+
+```astro
+---
+import BaseHead from '../components/BaseHead.astro';
+import Header from '../components/Header.astro';
+import Footer from '../components/Footer.astro';
+import FormattedDate from '../components/FormattedDate.astro';
+
+interface Props {
+  title: string;
+  description?: string;
+  pubDate: Date;
+  updatedDate?: Date;
+  heroImage?: string;
+  tags?: Array<{ label: string; slug: string }>;
+}
+
+const { title, description, pubDate, updatedDate, heroImage, tags = [] } = Astro.props;
+---
+
+<html lang="en">
+  <head>
+    <BaseHead title={title} description={description ?? ''} />
+    <style is:global>
+      /* All BlogPost layout styles are created by the design skill.
+         See COMPONENT_PATTERNS.md → Blog Post Content for the complete
+         styling contract: .hero-image, .prose, .title, .date, .tags,
+         .ricos-content overrides, etc. */
+    </style>
+  </head>
+
+  <body>
+    <Header />
+    <main>
+      <article>
+        <div class="hero-image">
+          {heroImage && <img width={1020} height={510} src={heroImage} alt="" />}
+        </div>
+        <div class="prose">
+          <div class="title">
+            <div class="date">
+              <FormattedDate date={pubDate} />
+              {
+                updatedDate && (
+                  <div class="last-updated-on">
+                    Last updated on <FormattedDate date={updatedDate} />
+                  </div>
+                )
+              }
+            </div>
+            <h1>{title}</h1>
+            {tags.length > 0 && (
+              <div class="tags">
+                {tags.map((tag) => (
+                  <span class="tag">{tag.label}</span>
+                ))}
+              </div>
+            )}
+            <hr />
+          </div>
+          <slot />
+        </div>
+      </article>
+    </main>
+    <Footer />
+  </body>
+</html>
+```
+
+> Adapt `Header` and `Footer` imports to match the project's existing components. If the project uses a different layout pattern (e.g., `Layout.astro` wrapper), use that instead and incorporate the blog-specific elements (hero image, date, title, tags).
+
+---
+
+## 4. Blog Listing Page (`src/pages/blog/index.astro`)
+
+```astro
+---
+import { queryBlogPosts } from "../../lib/blog";
+import BaseHead from "../../components/BaseHead.astro";
+import Footer from "../../components/Footer.astro";
+import FormattedDate from "../../components/FormattedDate.astro";
+import Header from "../../components/Header.astro";
+import { SITE_DESCRIPTION, SITE_TITLE } from "../../consts";
+
+const posts = await queryBlogPosts();
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <BaseHead title={SITE_TITLE} description={SITE_DESCRIPTION} />
+    <style>
+      /* Listing page styles are created by the design skill.
+         Feature skill only wires queryBlogPosts() data. */
+    </style>
+  </head>
+  <body>
+    <Header />
+    <main>
+      <section>
+        {
+          posts.length === 0 ? (
+            <div>There are no posts available.</div>
+          ) : (
+            <ul>
+              {posts.map((post) => (
+                <li>
+                  <a href={`/blog/${post.slug}/`}>
+                    {post.coverImageUrl && (
+                      <img
+                        width={720}
+                        height={360}
+                        src={post.coverImageUrl}
+                        alt=""
+                      />
+                    )}
+                    <h4 class="title">{post.title}</h4>
+                    <p class="date">
+                      <FormattedDate date={post.pubDate} />
+                    </p>
+                  </a>
+                </li>
+              ))}
+            </ul>
+          )
+        }
+      </section>
+    </main>
+    <Footer />
+  </body>
+</html>
+```
+
+> Adapt the layout to match the project's existing design. The key pattern is: `queryBlogPosts()` from the blog service, linking to `/blog/${post.slug}/`.
+
+---
+
+## 5. Blog Post Detail Page (`src/pages/blog/[...slug].astro`)
+
+```astro
+---
+import RicosViewer from '../../components/RicosViewer';
+import { getPostBySlug } from "../../lib/blog";
+import BlogPost from '../../layouts/BlogPost.astro';
+
+export const wixMetadata = {
+  appDefId: "14bcded7-0066-7c35-14d7-466cb3f09103",
+  pageIdentifier: "wix.blog.sub_pages.post",
+  identifiers: {
+    slug: "BLOG.POST.SLUG",
+  },
+};
+
+const { slug } = Astro.params;
+const post = await getPostBySlug(slug!);
+
+if (!post) {
+  return Astro.redirect("/blog");
+}
+---
+
+<BlogPost
+  title={post.title}
+  description={post.excerpt}
+  pubDate={post.pubDate}
+  heroImage={post.coverImageUrl}
+  tags={post.tags}
+>
+  <RicosViewer client:only="react" content={post.richContent} />
+</BlogPost>
+```
+
+Critical details:
+- **`wixMetadata` export is required** — it tells the Wix platform this page is a blog post page. The `appDefId` is the Wix Blog app's ID (constant, do not change). `identifiers.slug` maps the URL param to the blog post slug.
+- **`client:only="react"` is required** — `@wix/ricos` is a React component; `client:only="react"` ensures it renders only on the client, avoiding SSR issues with React-dependent code.
+- **`[...slug]` (rest param)** — uses Astro's rest parameter syntax, not `[slug]`, to match the full slug path.
+- **`RicosViewer`** renders the rich content from the Wix Blog editor (images, videos, text formatting, embeds, etc.) using `quickStartViewerPlugins()` for full content-type support.
+- **No `getStaticPaths()`** — Wix headless projects use `output: "server"` (SSR on Cloudflare Workers), so pages use `Astro.params` directly instead of static path generation.
+- **404 handling** — `getPostBySlug` returns `null` for missing posts; redirect to `/blog` listing.
+- **Ricos color overrides** — The BlogPost layout's `<style is:global>` block includes `.ricos-content` overrides that force `var(--color-text)` on all Ricos elements. Without these, blog text is invisible on dark themes.
+
+---
+
+## 6. RSS Feed (`src/pages/rss.xml.js`)
+
+```javascript
+import rss from '@astrojs/rss';
+import { queryBlogPosts } from '../lib/blog';
+import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
+
+export async function GET(context) {
+  const posts = await queryBlogPosts();
+  return rss({
+    title: SITE_TITLE,
+    description: SITE_DESCRIPTION,
+    site: context.site,
+    items: posts.map((post) => ({
+      title: post.title,
+      pubDate: post.pubDate,
+      description: post.excerpt,
+      link: `/blog/${post.slug}/`,
+    })),
+  });
+}
+```
+
+> Requires the `site` property in `astro.config.mjs` (set in BLOG_SETUP.md step 1).