@wix/agent-skills 1.13.0 → 1.15.0

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

@@ -1,92 +0,0 @@
-# Plan — the pre-approval funnel
-
-This file owns the run **from the first Discovery question to the user's approval of the plan** — operation routing, the questions, the background dispatches that hide latency, and the plan/approval gate. Its job is to get the user to the commitment moment **fast**, so keep it lean.
-
-**This file is the funnel router, and it routes on OPERATION.** It holds the shared funnel rules (concurrency vocabulary, the two-track model, operation routing, the Plan→Build contract, user-facing output, batching). The operation-specific funnel — how input is processed and how the plan looks — lives in `PLAN-create.md` (create a new site) and `PLAN-connect.md` (connect a brought-in design). **Read `operation` (set by `DISCOVERY.md` § Wave 0), then open the matching one and read only that:** `create` → `PLAN-create.md`, `connect` → `PLAN-connect.md`. (Today `create` coincides with `frontend: astro` and `connect` with `frontend: custom` — but the funnel branches on the *operation*, not the frontend; that is the seam the framework-SPA and extend plans build on.)
-
-**On approval, open `BUILD.md`** — the post-approval conductor that owns execution (Setup → design-system bridge → Seed → Components → Pages → Build → Release). Everything past the approval gate lives there, so it is not read until the user has committed.
-
-**The contract with the other files.** The domain/step files answer *what each step does* (the questions Discovery asks, the recipes, the prompt templates). This file + the operation funnels + `BUILD.md` answer *when, in what order, in parallel with what, gated on what*. The step files do not name the sequence or chain to each other; the conductor names when to apply each one. Neither prescribes a tool API — map each step to whatever subagent / parallel-execution primitive your runtime offers.
-
-## Concurrency vocabulary
-
-The terms below appear throughout this skill. They describe the *shape* of work; the runtime decides how to implement them:
-
-- **Subagent** — an isolated worker with its own context. The orchestrator sends it a prompt (an `Instruction file` path + inputs); the subagent reads the instruction file, performs the scope, and returns a structured result.
-- **Concurrent batch** — N subagents (or N tool calls) launched together so they execute in parallel rather than serially.
-- **Background subagent** — a subagent the orchestrator does not block on; it runs while the orchestrator continues with downstream work and reports its result asynchronously.
-- **Foreground subagent** — a subagent the orchestrator blocks on before continuing.
-- **Wait (gate)** — the orchestrator pauses until specified background work (subagents or background `Bash` jobs like the scaffold) finishes. **Waiting means awaiting the harness's background-task completion notification — never a `sleep`/poll loop against an output file.** A poll loop burns the whole wait as blocked orchestrator time and delays everything gated behind it (e.g. sleep-polling the scaffold lands the Composer late). The completion notification is the only signal you need; the same rule covers the `wix login` wait (`shared/AUTHENTICATION.md`) and the no-sidecar-poll rule for image phases (`images/INSTRUCTIONS.md`).
-- **Result** — the structured JSON block each subagent returns at the end of its run, per `references/shared/RETURN_CONTRACT.md`.
-
-## Two tracks (business vs frontend)
-
-The run is two semi-independent tracks that the orchestrator interleaves for wall-time:
-
-- **Business track** (frontend-blind) — create/connect the site, **install Wix apps**, **seed backend data**. Inputs: `siteId`, `verticals`, `intent`, `brand`. It never reads `frontend`/template — a product (or collection, post, form) is the same regardless of what renders it. Its domain content lives in `SETUP.md` (app installs) + `SEED.md` (seeders).
-- **Frontend track** (frontend-aware) — scaffold/prep the local project, Designer + design tokens, `compose.mjs` (the Composer script), components, pages, SDK wiring, build. Every `frontend`/template branch lives here. Its domain content lives in `scaffold.sh` + `seed-utilities.sh` + `DESIGN_SYSTEM.md` + `scripts/compose.mjs` (self-documenting) + the per-vertical references (frontend guides under `references/astro/`).
-
-The only cross-track data flow is **one-way, business → frontend**: seeders produce entity IDs which the orchestrator inlines into the frontend track's Page-subagent prompts. There is no frontend → business dependency.
-
-## Operation routing
-
-The Plan phase routes on **operation** — *create* (scaffold a new site from a prompt) vs *connect* (integrate a brought-in design). `operation` is captured by `DISCOVERY.md` § "Wave 0", held by the orchestrator in scratch, and selects the funnel:
-
-| `operation` | What it is | Funnel → Build |
-|---|---|---|
-| `create` | The user asks for a new site; the skill writes it | **`PLAN-create.md`** → on approval → `BUILD.md` routes Build on **framework**. The full astro playbook lives under `<SKILL_ROOT>/references/astro/`. |
-| `connect` | The user brings a finished design to wire to Wix | **`PLAN-connect.md`** → on approval → `BUILD.md` routes Build on **framework**. The frontend-track playbook is `<SKILL_ROOT>/references/custom/INSTRUCTIONS.md`. No scaffold, no Designer/Composer; init + shared Setup/Seed + connect/augment/persistence-swap; release is no-build (`none`) or the project's own build (`own` SPA). |
-
-> **Operation ≠ frontend.** The funnel branches on the *operation* (what the user is doing), not the frontend (what renders it). The two are orthogonal: *create* spans `frontendBuild` `wix` (astro default) and `own` (a named framework); *connect* spans `none` (static HTML), `own` (a brought SPA), and could span `wix` (a brought astro project) — none of which forks the operation router. Keeping operation and framework distinct is what lets these combinations be independently expressible without a new phase fork — see the framework-SPA plan and the extend plan.
-
-This is the **operation-selection routing layer**: `SETUP.md`'s steps assume the routing already happened; the conductor owns the branch. **Build does NOT route on operation** — it routes on framework (`BUILD.md`); operation feeds Build only through the contract below (specifically the bootstrap/wiring cells).
-
-## The Plan→Build contract
-
-Plan resolves a small, explicit contract that Build consumes. It is carried **in the orchestrator's in-context session scratch** and threaded into each subagent's dispatch prompt — it is **not persisted to disk** (nothing in this contract lands on disk). The orchestrator already resolves these fields in Wave 0 and holds them for the whole run, so a disk round-trip buys nothing; on scratch loss, `frontend`/`frontendBuild` are recovered from `package.json` (`@wix/astro` ⇒ astro/wix, else custom + re-derive from `scripts.build`).
-
-**Core (every operation resolves these identically; Build's install/build/release spine reads only these):**
-
-| Field | Today's values | Meaning |
-|---|---|---|
-| `operation` | `create` \| `connect` | what the user is doing (*extend* added later by its own plan) |
-| `frontend` | `astro` \| `custom` | what renders the site (held in scratch; recovered from `package.json` on scratch loss) |
-| `frontendBuild` | `wix` \| `none` \| `own` | the build-class Build routes on: `wix` (astro, `wix build`), `none` (brought static HTML, no build), `own` (framework SPA — the project's own `npm run build`; brought-in *or* scaffolded from a named framework) |
-| `verticals[]` | e.g. `["stores","ecom","cms"]` | loaded packs (top-level + transitive) |
-| `designSource` | `generate-fresh` \| `derive-from-brought` | create generates; connect derives from the brought design's own tokens |
-| `brand` | `{ name, description }` | brand metadata |
-
-`frontendBuild` is **derived inside the operation, not implied by it** (the axes are orthogonal): connect resolves it from the brought-in project on disk (`none` static HTML vs `own` framework SPA — `DISCOVERY-connect.md` § 1.5); create resolves it from an explicit framework keyword (`wix` astro default vs `own` named framework — `DISCOVERY.md` § "Wave 0"). Resolve it in Wave 0 alongside `frontend` and hold it in scratch (on scratch loss, recover from `package.json`). Build branches its install/build/release **purely off `frontendBuild`** — never off `operation`.
-
-**Operation section (feeds ONLY the bootstrap + wiring cells, never the build/release spine):**
-- `connect` carries the **connection plan** (binding-map / augmentation spec) inferred in Discovery.
-- `create` carries nothing extra.
-- *(extend will carry existing-state + delta — added by the extend plan.)*
-
-That is the precise sense in which the contract stays uniform across operations: the build/release spine is contract-uniform (it reads only the core), and **only** the bootstrap/wiring cells read the operation-specific payload. A *fresh session over an existing project* (extend) reconstructs the equivalent core from durable disk artifacts (`@wix/astro` dep, `package.json`, on-disk pages) rather than from scratch — same contract, sourced differently by lifecycle.
-
-## User-facing output (keep the machinery invisible)
-
-This rule governs the **whole run**, both modes. The user should see **milestones in plain language, never the orchestration machinery.** Between the Discovery approval and the final summary the run is largely silent — the orchestrator is dispatching, waiting, and gating, none of which is the user's concern.
-
-**Never put internal orchestration vocabulary in a user-facing message.** That includes: background-handle names (`*_handle`), dispatch markers ("→ dispatch:", "dispatching X", "launching Wave 3"), subagent START/END, "seed gate" / "all handles complete", wave/step numbers ("Wave 3", "Step 4.5"), in-flight **subagent/handle status tables** (especially any "Handle" column), and internal paths (`wix-manage-root`, the scaffold subdir). These describe *how the conductor works*, not *what the user is getting*.
-
-**The only user-facing messages in a run are:**
-1. **Discovery** — the questions, the plan, and the approval gate (the mode discovery file's domain).
-2. **One brief seed-progress sentence** (`SEED.md` Step 5) — plain prose naming what was seeded, no tables.
-3. **The final summary** (`BUILD.md` § "Final Message").
-
-Everything else is silent. If a long phase (Components, Pages) would otherwise look stalled, at most **one short plain-language line** ("Building your product and category pages…") — never a status table, handle list, or wave number. The in-flight subagent tables that runs have emitted ("Phase 3 Components running: | Subagent | Handle |…", "🎉 Seed gate open! All handles complete") are the anti-pattern this rule removes.
-
-## Batching discipline
-
-This rule governs **every** concurrent batch in the run, in both modes — the Wave-0 pack reads (mode funnel), and the post-approval dispatch batches owned by the conductor (`BUILD.md` and its mode files): the astro BUILD-entry scaffold + Designer dispatch, the Setup app-installs, the Wave-3 seed batch, the integration connection-plan + init batch. The step files describe *what* is in each batch; the rule that they go out as one batch lives here.
-
-Historical runs lost 1–2 minutes per phase to serialized dispatch — N operations emitted one-per-turn instead of in a single concurrent batch. Even when each ran fast, the inter-dispatch gaps accumulated to significant overhead per phase.
-
-Two mitigations; use both:
-
-1. **Fire the whole batch as one assistant message** — N `Agent`/`Bash` tool_uses as siblings. **No narration between dispatches** ("Now installing apps:", "Dispatching seeders:"). Any text adjacent to a dispatch closes the batch and forces the rest into separate turns, adding seconds per dispatch. This holds even for a 2-item batch.
-2. **Use background-on-dispatch for anything that doesn't block downstream work.** Even if the runtime serializes the launch turns, background dispatch lets the work overlap in execution, compressing wall-time substantially versus serial.
-
-If your runtime forces serialization across turns, make every subagent that can run in the background a background subagent — the Designer, seeders, and image phases all dispatch background so the foreground never blocks on them. (The Composer is no longer a subagent — it is the deterministic `compose.mjs` Bash step, sub-second and synchronous.)

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

@@ -1,300 +0,0 @@
-# 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 merged pages scope.
-         See references/shared/STYLING.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>
-      /* The merged blog-pages scope writes this route once — applying the
-         listing styles and binding queryBlogPosts() data in the same pass. */
-    </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.
-- **Blog deliberately uses the React `RicosViewer`** (full feature set: galleries, polls, embedded media) — not a contradiction with CMS, which uses the lighter SSR `renderRicos` walker (`src/utils/ricos.ts`). Blog posts can carry the full Ricos feature set, so they need the React island; static CMS pages (about/faq/portfolio/team/resource) only need paragraphs + lists and avoid shipping ~80kb of React. See `references/astro/cms/CMS_FOUNDATIONS.md` § "Why not @wix/ricos?".
-- **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).

package/skills/wix-headless/references/astro/blog/BLOG_SETUP.md

@@ -1,218 +0,0 @@
-# Reference: Blog Setup
-
-Prerequisites, dependencies, blog service module, and astro config changes for the Wix Blog app integration.
-
-## Prerequisites
-
-- A Wix Managed Headless project (has `wix.config.json` and `astro.config.mjs`)
-- The **Wix Blog app** installed on the connected Wix site (installed via the apps-installer REST endpoint after scaffolding — see `../../blog/BLOG_CONTENT.md` Step 0)
-- At least one published blog post in the Wix dashboard
-
-## Package Installation
-
-```bash
-npm install @wix/blog @wix/ricos @astrojs/rss @astrojs/sitemap
-```
-
-## Files to Create / Modify
-
-| File | Action | Purpose |
-|------|--------|---------|
-| `astro.config.mjs` | Modify | Add `site` property and `sitemap()` integration |
-| `src/lib/blog.ts` | Create | Blog service — queries posts, resolves categories/tags/media |
-| `src/consts.ts` | Create | Site-wide constants (title, description) |
-| `src/components/RicosViewer.tsx` | Create | React wrapper for `@wix/ricos` RicosViewer |
-
----
-
-## 1. Astro Config Changes (`astro.config.mjs`)
-
-Add the `site` property (required for RSS and sitemap) and the `sitemap()` integration:
-
-```javascript
-// @ts-check
-import { defineConfig } from "astro/config";
-import sitemap from "@astrojs/sitemap";
-import wix from "@wix/astro";
-import wixPages from "@wix/astro-pages";
-
-// https://astro.build/config
-export default defineConfig({
-  site: "https://example.com",
-  integrations: [wix(), wixPages(), sitemap()]
-});
-```
-
-> Replace `"https://example.com"` with the actual site URL. The `site` property is required for `@astrojs/rss` and `@astrojs/sitemap` to generate correct URLs.
-
-> `wix()` and `wixPages()` should already be in the config from project scaffolding. Only add `sitemap()` and the `site` property.
-
----
-
-## 2. Site Constants (`src/consts.ts`)
-
-```typescript
-// Place any global data in this file.
-// You can import this data from anywhere in your site by using the `import` keyword.
-
-export const SITE_TITLE = 'Astro Blog';
-export const SITE_DESCRIPTION = 'Welcome to my website!';
-```
-
-> Update `SITE_TITLE` and `SITE_DESCRIPTION` to match the user's site.
-
----
-
-## 3. RicosViewer React Wrapper (`src/components/RicosViewer.tsx`)
-
-A thin React wrapper around `@wix/ricos` for use in Astro pages with `client:only="react"`.
-
-```tsx
-import { quickStartViewerPlugins, RicosViewer } from '@wix/ricos';
-import '@wix/ricos/css/all-plugins-viewer.css';
-
-const plugins = quickStartViewerPlugins();
-
-export default function RicosContentViewer({ content }: { content: any }) {
-  if (!content) return null;
-  return (
-    <div className="ricos-content">
-      <RicosViewer content={content} plugins={plugins} />
-    </div>
-  );
-}
-```
-
-Key details:
-- `quickStartViewerPlugins()` is initialized at module level (once, not per render) — provides full content-type support (links, tables, galleries, embeds, etc.)
-- The CSS import is bundled by Vite into the client chunk
-- No key renaming needed — `@wix/ricos` accepts camelCase keys from the `@wix/blog` SDK directly
-- Used in Astro pages as `<RicosViewer client:only="react" content={post.richContent} />`
-- The `.ricos-content` wrapper div provides a CSS hook for theme color overrides — the Ricos library CSS hardcodes `color: rgb(0, 0, 0)` on paragraph and list elements, which is invisible on dark themes
-
----
-
-## 4. Blog Service Module (`src/lib/blog.ts`)
-
-This service module handles all Wix Blog SDK calls, resolving categories, tags, and media references into ready-to-use data.
-
-```typescript
-import { posts, categories, tags } from "@wix/blog";
-import { media } from "@wix/sdk";
-
-export interface BlogPost {
-  slug: string;
-  title: string;
-  excerpt: string;
-  coverImageUrl?: string;
-  date: string;
-  pubDate: Date;
-  category?: string;
-  richContent: any;
-  tags: Array<{ label: string; slug: string }>;
-}
-
-export async function queryBlogPosts(limit?: number): Promise<BlogPost[]> {
-  let query = posts
-    .queryPosts({ fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"] })
-    .descending("firstPublishedDate");
-
-  if (limit) query = query.limit(limit);
-
-  const { items } = await query.find();
-
-  return Promise.all(
-    items.map(async (item) => {
-      const resolvedCategories = await Promise.all(
-        (item.categoryIds || []).map(async (id) => {
-          const { category } = await categories.getCategory(id);
-          return category!;
-        })
-      );
-
-      const resolvedTags = await Promise.all(
-        (item.tagIds || []).map(async (id) => {
-          const tag = await tags.getTag(id);
-          return { label: tag.label!, slug: tag.slug! };
-        })
-      );
-
-      const imageUrl = item.media?.wixMedia?.image
-        ? media.getImageUrl(item.media.wixMedia.image).url
-        : undefined;
-
-      const pubDate = new Date(item.firstPublishedDate ?? "");
-
-      return {
-        slug: item.slug!,
-        title: item.title!,
-        excerpt: item.excerpt ?? "",
-        coverImageUrl: imageUrl,
-        date: pubDate.toLocaleDateString("en-us", {
-          year: "numeric",
-          month: "long",
-          day: "numeric",
-        }),
-        pubDate,
-        category: resolvedCategories[0]?.label,
-        richContent: item.richContent,
-        tags: resolvedTags,
-      };
-    })
-  );
-}
-
-export async function getPostBySlug(slug: string): Promise<BlogPost | null> {
-  const { items } = await posts
-    .queryPosts({ fieldsets: ["RICH_CONTENT", "CONTENT_TEXT"] })
-    .eq("slug", slug)
-    .find();
-
-  const item = items[0];
-  if (!item) return null;
-
-  const resolvedCategories = await Promise.all(
-    (item.categoryIds || []).map(async (id) => {
-      const { category } = await categories.getCategory(id);
-      return category!;
-    })
-  );
-
-  const resolvedTags = await Promise.all(
-    (item.tagIds || []).map(async (id) => {
-      const tag = await tags.getTag(id);
-      return { label: tag.label!, slug: tag.slug! };
-    })
-  );
-
-  const imageUrl = item.media?.wixMedia?.image
-    ? media.getImageUrl(item.media.wixMedia.image).url
-    : undefined;
-
-  const pubDate = new Date(item.firstPublishedDate ?? "");
-
-  return {
-    slug: item.slug!,
-    title: item.title!,
-    excerpt: item.excerpt ?? "",
-    coverImageUrl: imageUrl,
-    date: pubDate.toLocaleDateString("en-us", {
-      year: "numeric",
-      month: "long",
-      day: "numeric",
-    }),
-    pubDate,
-    category: resolvedCategories[0]?.label,
-    richContent: item.richContent,
-    tags: resolvedTags,
-  };
-}
-```
-
-Key details:
-- `categories.getCategory(id)` returns `{ category }` (envelope) — destructure it
-- `tags.getTag(id)` returns the `BlogTag` directly — do NOT destructure as `{ tag }`
-- `media.getImageUrl(ref).url` resolves Wix media references to real URLs
-- `getPostBySlug` returns `null` for missing posts — pages must handle this with a redirect
-- `queryBlogPosts()` sorts by `firstPublishedDate` descending (newest first)
-- `RICH_CONTENT` fieldset is required to get renderable content for `RicosViewer`

package/skills/wix-headless/references/astro/bookings/COMPONENTS.md

@@ -1,45 +0,0 @@
-# Bookings Components — the client islands (astro)
-
-The `components` scope of the bookings vertical. You write the React islands that
-power the booking UI. The **logic** is in `../../bookings/FLOW.md` (read it first);
-this doc is the astro wiring + the gotchas. `src/styles/components-bookings.css`
-and `src/components/bookingDriver.ts` are pre-copied — do **not** write them.
-
-Read `references/shared/IMPLEMENTER.md` + `references/shared/STYLING.md` first.
-
-> **Start from the templates — don't re-author the SDK wiring.** Each island has
-> an example at `<SKILL_ROOT>/references/astro/templates/bookings/`. Read and adapt
-> (brand copy, styling, class names already in `components-bookings.css`); keep the
-> SDK calls + payload shapes.
-
-## Islands you write
-
-| File | From template | Role |
-|------|---------------|------|
-| `src/components/ServiceBookingFlow.tsx` | `…/ServiceBookingFlow.tsx` | `client:only` coordinator — holds the selected slot, swaps calendar → form, redirects on success. Mounted by `services/[slug].astro`. |
-| `src/components/AvailabilityCalendar.tsx` | `…/AvailabilityCalendar.tsx` | the **week calendar** — week strip + nav → the picked day's slots. APPOINTMENT → `availabilityTimeSlots`; CLASS → `eventTimeSlots`. Optional **staff picker** (shown when >1 staff; filters availability + records `slot.resource`) and **location picker** (shown when the service has >1 business location; **always scopes availability to one location** — defaulting to the carried/first — so a multi-location service doesn't return duplicate per-location slots). Both fed by props from the SSR page. |
-| `src/components/BookingForm.tsx` | `…/BookingForm.tsx` | the **schema-driven** form — renders the `@wix/forms` field list (passed in from the SSR page), keys values by `target`, calls `bookingDriver.book()`. |
-
-## astro-specific rules
-
-1. **Islands call `@wix` ambiently — no `createClient`/`OAuthStrategy`.** In an
-   astro browser island the `@wix/astro` visitor client is ambient (the same way
-   the ecom `CartView` island works): `import { availabilityTimeSlots } from "@wix/bookings"`
-   and call it directly. Do **not** build an `OAuthStrategy` client or read
-   `WIX_CLIENT_ID` — that pattern is for own/static builds (`../../custom/bookings/WIRING.md`).
-2. **The booking sequence is imported, not re-authored.** Import `book`,
-   `navigateToCheckout`, `BookResultType`, and the `SelectedSlot` type from the
-   pre-copied `./bookingDriver`. The form island calls `book(...)` and branches:
-   `CheckoutRequired` → `navigateToCheckout(cartId, postFlowUrl)`; `CheckoutSkipped`
-   → redirect to `/booking-confirmation`.
-3. **Mount everything `client:only="react"`.** Availability + booking are
-   timezone/session-specific; never SSR them.
-4. **The form fields come from SSR.** `services/[slug].astro` fetches the booking
-   form schema and passes a `fields` array into `ServiceBookingFlow` → `BookingForm`
-   (see `SERVICES_PAGES.md`). The island renders the fields generically — it does
-   not fetch the schema itself.
-5. **No CSS.** The classes (`.availability-*`, `.time-slot*`, `.booking-*`) are in
-   the pre-copied `components-bookings.css`; reference them, don't write them.
-
-## Return
-`{ status, phase, scope: "components", summary, data, files, errors }`. If a pre-copied dependency (`bookingDriver.ts`, `components-bookings.css`) is missing, return `status: "partial"` with the coded error.