@wix/agent-skills 1.0.0

package/skills/wix-headless/references/cms/RESOURCE_LIBRARY.md

@@ -0,0 +1,356 @@
+# Recipe: Resource Library / Downloads
+
+Build a downloadable resource library using `@wix/data` — file listings with category filtering, file type badges, and detail pages with download buttons. Use for documents, guides, templates, whitepapers, or any downloadable assets.
+
+> Read `CMS_FOUNDATIONS.md` first for shared patterns (service module, image resolution, elevation, MCP seeding).
+
+## Collection Schema
+
+Create a collection in the Wix dashboard → CMS with these fields:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `title` | Text | Resource name |
+| `slug` | Text | URL-friendly identifier |
+| `description` | Rich Text | Resource description (HTML) |
+| `category` | Text | Resource category (e.g., "Guides", "Templates") |
+| `fileType` | Text | File extension — `PDF`, `DOC`, `ZIP`, `XLS`, etc. |
+| `fileUrl` | URL | Download URL (external link or Wix media URL) |
+| `fileSize` | Text | Human-readable file size (e.g., "2.4 MB") |
+| `coverImage` | Image | Thumbnail (`wix:image://` — resolve with `media.getScaledToFillImageUrl()`) |
+| `published` | Boolean | Publish status |
+| `_createdDate` | Date | Auto-populated creation date |
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `src/lib/resources.ts` | Service module — queries, category filtering, related resources |
+| `src/pages/resources/index.astro` | Listing with category filter + file type badges |
+| `src/pages/resources/[slug].astro` | Detail page with download button + related resources |
+| `src/components/ResourceCard.astro` | Card with file type icon, title, size |
+| `src/components/FileTypeIcon.astro` | SVG switch for PDF/DOC/ZIP/generic |
+
+## Implementation
+
+### 1. Resources Service Module (`src/lib/resources.ts`)
+
+```typescript
+import * as items from "@wix/wix-data-items-sdk";
+import { auth } from "@wix/essentials";
+import { media } from "@wix/sdk";
+
+const COLLECTION_ID = "Resources";
+
+export interface Resource {
+  _id: string;
+  title: string;
+  slug: string;
+  description?: string;
+  category: string;
+  fileType: string;
+  fileUrl: string;
+  fileSize?: string;
+  coverImage?: string;
+  published: boolean;
+  _createdDate?: string;
+}
+
+function resolveImage(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  return media.getScaledToFillImageUrl(url, 600, 400, {});
+}
+
+function mapResource(item: Record<string, any>): Resource {
+  return {
+    _id: item._id,
+    title: item.title ?? "",
+    slug: item.slug ?? "",
+    description: item.description,
+    category: item.category ?? "",
+    fileType: (item.fileType ?? "FILE").toUpperCase(),
+    fileUrl: item.fileUrl ?? "",
+    fileSize: item.fileSize,
+    coverImage: resolveImage(item.coverImage),
+    published: item.published ?? false,
+    _createdDate: item._createdDate,
+  };
+}
+
+export async function queryResources(): Promise<Resource[]> {
+  const elevatedQuery = auth.elevate(items.query);
+  const { items: results } = await elevatedQuery(COLLECTION_ID)
+    .eq("published", true)
+    .descending("_createdDate")
+    .limit(50)
+    .find();
+
+  return results.map(mapResource);
+}
+
+export async function getResourceBySlug(slug: string): Promise<Resource | null> {
+  const elevatedQuery = auth.elevate(items.query);
+  const { items: results } = await elevatedQuery(COLLECTION_ID)
+    .eq("slug", slug)
+    .eq("published", true)
+    .limit(1)
+    .find();
+
+  const item = results[0];
+  if (!item) return null;
+  return mapResource(item);
+}
+
+export async function queryRelatedResources(category: string, excludeId: string, limit = 3): Promise<Resource[]> {
+  const elevatedQuery = auth.elevate(items.query);
+  const { items: results } = await elevatedQuery(COLLECTION_ID)
+    .eq("published", true)
+    .eq("category", category)
+    .ne("_id", excludeId)
+    .descending("_createdDate")
+    .limit(limit)
+    .find();
+
+  return results.map(mapResource);
+}
+```
+
+Key details:
+- `queryRelatedResources()` finds same-category items excluding the current one
+- `fileType` normalized to uppercase for consistent badge display
+- Sorted by `_createdDate` descending (newest first)
+- Update `COLLECTION_ID` to match the exact collection name from the Wix dashboard (no namespace prefix for native collections)
+
+### 2. File Type Icon (`src/components/FileTypeIcon.astro`)
+
+```astro
+---
+interface Props {
+  type: string;
+  class?: string;
+}
+
+const { type, class: className = "w-8 h-8" } = Astro.props;
+const fileType = type.toUpperCase();
+
+// File type colors are applied by the design skill's component styles
+---
+
+<div class={className}>
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="w-full h-full">
+    <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z" />
+    <polyline points="14 2 14 8 20 8" />
+    <text x="12" y="17" text-anchor="middle" font-size="5" fill="currentColor" stroke="none" font-weight="bold">{fileType.slice(0, 4)}</text>
+  </svg>
+</div>
+```
+
+Key details:
+- Color-coded by file type — red for PDF, blue for DOC, green for XLS, yellow for ZIP
+- Falls back to neutral gray for unknown types
+- File type label rendered inside the document icon SVG
+
+### 3. Resource Card (`src/components/ResourceCard.astro`)
+
+```astro
+---
+import FileTypeIcon from "./FileTypeIcon.astro";
+
+interface Props {
+  resource: {
+    title: string;
+    slug: string;
+    category: string;
+    fileType: string;
+    fileSize?: string;
+    coverImage?: string;
+  };
+}
+
+const { resource } = Astro.props;
+---
+
+<a href={`/resources/${resource.slug}`}>
+  {resource.coverImage ? (
+    <div><img src={resource.coverImage} alt={resource.title} /></div>
+  ) : (
+    <div><FileTypeIcon type={resource.fileType} /></div>
+  )}
+  <div>
+    <div>
+      <span>{resource.fileType}</span>
+      {resource.fileSize && <span>{resource.fileSize}</span>}
+    </div>
+    <h3>{resource.title}</h3>
+    <p>{resource.category}</p>
+  </div>
+</a>
+```
+
+> **Styling note:** ResourceCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Resource Card.
+
+### 4. Resource Listing Page (`src/pages/resources/index.astro`)
+
+```astro
+---
+import Layout from "../../layouts/Layout.astro";
+import ResourceCard from "../../components/ResourceCard.astro";
+import CategoryFilter from "../../components/CategoryFilter.astro";
+import { queryResources } from "../../lib/resources";
+
+const activeCategory = Astro.url.searchParams.get("category");
+const allResources = await queryResources();
+const filtered = activeCategory
+  ? allResources.filter((r) => r.category === activeCategory)
+  : allResources;
+const categories = [...new Set(allResources.map((r) => r.category).filter(Boolean))];
+---
+
+<Layout title="Resources">
+  <main>
+    <div>
+      <h1>Resources</h1>
+      <p>Download guides, templates, and documents.</p>
+
+      <CategoryFilter categories={categories} activeCategory={activeCategory} basePath="/resources" />
+
+      <div>
+        {filtered.map((resource) => (
+          <ResourceCard resource={resource} />
+        ))}
+      </div>
+
+      {filtered.length === 0 && (
+        <p>No resources found.</p>
+      )}
+    </div>
+  </main>
+</Layout>
+```
+
+> Reuses the same `CategoryFilter.astro` component from the portfolio use case. If building both, no need to create it twice.
+
+### 5. Resource Detail Page (`src/pages/resources/[slug].astro`)
+
+```astro
+---
+import Layout from "../../layouts/Layout.astro";
+import ResourceCard from "../../components/ResourceCard.astro";
+import FileTypeIcon from "../../components/FileTypeIcon.astro";
+import { getResourceBySlug, queryRelatedResources } from "../../lib/resources";
+
+const { slug } = Astro.params;
+const resource = await getResourceBySlug(slug!);
+if (!resource) return Astro.redirect("/404");
+
+const related = await queryRelatedResources(resource.category, resource._id);
+
+const date = resource._createdDate
+  ? new Date(resource._createdDate).toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+    })
+  : "";
+---
+
+<Layout title={resource.title}>
+  <main>
+    <div>
+      <a href="/resources">
+        &larr; Back to resources
+      </a>
+
+      <div>
+        <FileTypeIcon type={resource.fileType} />
+        <div>
+          <div>
+            <span>{resource.fileType}</span>
+            {resource.fileSize && (
+              <span>{resource.fileSize}</span>
+            )}
+          </div>
+          {date && <p>Added {date}</p>}
+        </div>
+      </div>
+
+      <h1>{resource.title}</h1>
+
+      {resource.coverImage && (
+        <div>
+          <img
+            src={resource.coverImage}
+            alt={resource.title}
+          />
+        </div>
+      )}
+
+      {resource.description && (
+        <article set:html={resource.description} />
+      )}
+
+      {resource.fileUrl && (
+        <a
+          href={resource.fileUrl}
+          download
+        >
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
+          Download {resource.fileType}
+        </a>
+      )}
+
+      {related.length > 0 && (
+        <section>
+          <h2>Related Resources</h2>
+          <div>
+            {related.map((r) => (
+              <ResourceCard resource={r} />
+            ))}
+          </div>
+        </section>
+      )}
+    </div>
+  </main>
+</Layout>
+```
+
+Key details:
+- `<a download>` triggers browser download for the file
+- Related resources query pulls same-category items, excluding the current one
+- File type icon and badge prominently displayed
+
+## Seed with Images
+
+After seeding resources via MCP, generate cover images following `../../shared/IMAGE_GENERATION.md` and `CMS_FOUNDATIONS.md` → "MCP Seeding with Images".
+
+**Prompt template:**
+
+```
+Cover image for [TITLE], a [FILE TYPE]. Abstract [BRAND AESTHETIC]. Color tones: [BRAND COLORS]. No text, no watermarks
+```
+
+**Patch field:** `coverImage`
+
+Example patch:
+
+```
+CallWixSiteAPI: PATCH /wix-data/v2/items/{resourceId}
+body: {
+  "dataCollectionId": "Resources",
+  "dataItem": {
+    "data": {
+      "coverImage": "<wixstatic-url>"
+    }
+  }
+}
+```
+
+## Testing
+
+1. Create a "Resources" collection in the Wix dashboard → CMS with the schema above
+2. Add 4+ resources across 2+ categories with different file types (PDF, DOC, ZIP)
+3. Include `fileUrl` links (can be any downloadable URL for testing)
+4. Run `npx @wix/cli dev`
+5. `/resources` — shows all resources with category filters and file type badges
+6. Click a category — filters resources
+7. Click a resource — detail page with download button and related resources

package/skills/wix-headless/references/cms/TEAM_DIRECTORY.md

@@ -0,0 +1,299 @@
+# Recipe: Team / Staff Directory
+
+Build a team directory using `@wix/data` — staff cards grouped by department with individual profile pages. Use for about us, our team, meet the staff, or any people directory.
+
+> Read `CMS_FOUNDATIONS.md` first for shared patterns (service module, image resolution, elevation, MCP seeding).
+
+## Collection Schema
+
+Create a collection in the Wix dashboard → CMS with these fields:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `name` | Text | Full name |
+| `slug` | Text | URL-friendly identifier |
+| `role` | Text | Job title or role |
+| `department` | Text | Department or team (e.g., "Engineering", "Design") |
+| `bio` | Rich Text | Bio or description (HTML) |
+| `photo` | Image | Headshot (`wix:image://` — resolve with `media.getScaledToFillImageUrl()`) |
+| `email` | Text | Contact email |
+| `linkedIn` | URL | LinkedIn profile URL |
+| `twitter` | URL | Twitter/X profile URL |
+| `orderIndex` | Number | Manual sort order within department |
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `src/lib/team.ts` | Service module — queries, department grouping |
+| `src/pages/team/index.astro` | Department-sectioned directory |
+| `src/pages/team/[slug].astro` | Individual member profile |
+| `src/components/TeamMemberCard.astro` | Photo, name, role, social icons |
+
+## Implementation
+
+### 1. Team Service Module (`src/lib/team.ts`)
+
+```typescript
+import * as items from "@wix/wix-data-items-sdk";
+import { auth } from "@wix/essentials";
+import { media } from "@wix/sdk";
+
+const COLLECTION_ID = "Team";
+
+export interface TeamMember {
+  _id: string;
+  name: string;
+  slug: string;
+  role: string;
+  department: string;
+  bio?: string;
+  photo?: string;
+  email?: string;
+  linkedIn?: string;
+  twitter?: string;
+  orderIndex: number;
+}
+
+function resolvePhoto(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  return media.getScaledToFillImageUrl(url, 400, 400, {});
+}
+
+function mapMember(item: Record<string, any>): TeamMember {
+  return {
+    _id: item._id,
+    name: item.name ?? "",
+    slug: item.slug ?? "",
+    role: item.role ?? "",
+    department: item.department ?? "",
+    bio: item.bio,
+    photo: resolvePhoto(item.photo),
+    email: item.email,
+    linkedIn: item.linkedIn,
+    twitter: item.twitter,
+    orderIndex: item.orderIndex ?? 0,
+  };
+}
+
+export async function queryTeamMembers(): Promise<TeamMember[]> {
+  const elevatedQuery = auth.elevate(items.query);
+  const { items: results } = await elevatedQuery(COLLECTION_ID)
+    .ascending("orderIndex")
+    .limit(100)
+    .find();
+
+  return results.map(mapMember);
+}
+
+export async function getMemberBySlug(slug: string): Promise<TeamMember | null> {
+  const elevatedQuery = auth.elevate(items.query);
+  const { items: results } = await elevatedQuery(COLLECTION_ID)
+    .eq("slug", slug)
+    .limit(1)
+    .find();
+
+  const item = results[0];
+  if (!item) return null;
+  return mapMember(item);
+}
+
+export function groupByDepartment(members: TeamMember[]): Map<string, TeamMember[]> {
+  return members.reduce((map, member) => {
+    const dept = member.department || "Team";
+    if (!map.has(dept)) map.set(dept, []);
+    map.get(dept)!.push(member);
+    return map;
+  }, new Map<string, TeamMember[]>());
+}
+```
+
+Key details:
+- `resolvePhoto()` uses 400x400 for square headshot crops
+- `groupByDepartment()` returns a `Map` preserving insertion order — departments appear in the order of their first member
+- Update `COLLECTION_ID` to match the exact collection name from the Wix dashboard (no namespace prefix for native collections)
+
+### 2. Team Member Card (`src/components/TeamMemberCard.astro`)
+
+```astro
+---
+interface Props {
+  member: {
+    name: string;
+    slug: string;
+    role: string;
+    photo?: string;
+    email?: string;
+    linkedIn?: string;
+    twitter?: string;
+  };
+}
+
+const { member } = Astro.props;
+---
+
+<a href={`/team/${member.slug}`}>
+  <div>
+    {member.photo ? (
+      <img src={member.photo} alt={member.name} />
+    ) : (
+      <div>{member.name.charAt(0)}</div>
+    )}
+  </div>
+  <h3>{member.name}</h3>
+  <p>{member.role}</p>
+  <div>
+    {member.email && (
+      <a href={`mailto:${member.email}`} onclick="event.stopPropagation()">Email</a>
+    )}
+    {member.linkedIn && (
+      <a href={member.linkedIn} target="_blank" rel="noopener noreferrer" onclick="event.stopPropagation()">LinkedIn</a>
+    )}
+    {member.twitter && (
+      <a href={member.twitter} target="_blank" rel="noopener noreferrer" onclick="event.stopPropagation()">Twitter</a>
+    )}
+  </div>
+</a>
+```
+
+> **Styling note:** TeamMemberCard styling is created by the design skill. See `COMPONENT_PATTERNS.md` → Team Member Card.
+
+Key details:
+- Inline SVG icons — no icon library dependency
+- Fallback initial letter when no photo
+- Social links use `onclick="event.stopPropagation()"` to prevent navigation to profile when clicking social icons
+
+### 3. Team Directory Page (`src/pages/team/index.astro`)
+
+```astro
+---
+import Layout from "../../layouts/Layout.astro";
+import TeamMemberCard from "../../components/TeamMemberCard.astro";
+import { queryTeamMembers, groupByDepartment } from "../../lib/team";
+
+const members = await queryTeamMembers();
+const departments = groupByDepartment(members);
+---
+
+<Layout title="Our Team">
+  <main>
+    <div>
+      <h1>Our Team</h1>
+
+      {[...departments.entries()].map(([dept, deptMembers]) => (
+        <section>
+          <h2>{dept}</h2>
+          <div>
+            {deptMembers.map((member) => (
+              <TeamMemberCard member={member} />
+            ))}
+          </div>
+        </section>
+      ))}
+
+      {members.length === 0 && (
+        <p>No team members found.</p>
+      )}
+    </div>
+  </main>
+</Layout>
+```
+
+### 4. Member Profile Page (`src/pages/team/[slug].astro`)
+
+```astro
+---
+import Layout from "../../layouts/Layout.astro";
+import { getMemberBySlug } from "../../lib/team";
+
+const { slug } = Astro.params;
+const member = await getMemberBySlug(slug!);
+if (!member) return Astro.redirect("/404");
+---
+
+<Layout title={member.name}>
+  <main>
+    <div>
+      <a href="/team">
+        &larr; Back to team
+      </a>
+
+      <div>
+        {member.photo && (
+          <div>
+            <img
+              src={member.photo}
+              alt={member.name}
+            />
+          </div>
+        )}
+        <div>
+          <h1>{member.name}</h1>
+          <p>{member.role}</p>
+          {member.department && (
+            <p>{member.department}</p>
+          )}
+          <div>
+            {member.email && (
+              <a href={`mailto:${member.email}`}>
+                {member.email}
+              </a>
+            )}
+            {member.linkedIn && (
+              <a href={member.linkedIn} target="_blank" rel="noopener noreferrer">
+                LinkedIn
+              </a>
+            )}
+            {member.twitter && (
+              <a href={member.twitter} target="_blank" rel="noopener noreferrer">
+                Twitter
+              </a>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {member.bio && (
+        <article set:html={member.bio} />
+      )}
+    </div>
+  </main>
+</Layout>
+```
+
+## Seed with Images
+
+> **Do not skip:** Team members without photos appear as initial-letter placeholders.
+> Always ask the user if they want to generate headshot images before moving on.
+
+After seeding team members via MCP, generate headshot images following `../../shared/IMAGE_GENERATION.md` and `CMS_FOUNDATIONS.md` → "MCP Seeding with Images".
+
+**Prompt template:**
+
+```
+Professional headshot portrait of [NAME], [ROLE] at [BUSINESS NAME]. [BRAND AESTHETIC]. Warm studio lighting, neutral background with [BRAND COLORS]. No text, no watermarks
+```
+
+**Patch field:** `photo`
+
+Example: after generating and importing the image, patch the team member item:
+
+```
+CallWixSiteAPI: PATCH /wix-data/v2/items/{memberId}
+body: {
+  "dataCollectionId": "Team",
+  "dataItem": {
+    "data": {
+      "photo": "<wixstatic-url>"
+    }
+  }
+}
+```
+
+## Testing
+
+1. Create a "Team" collection in the Wix dashboard → CMS with the schema above
+2. Add 4+ members across 2+ departments, with photos and social links
+3. Run `npx @wix/cli dev`
+4. `/team` — shows members grouped by department
+5. Click a member — profile page with photo, bio, and social links

package/skills/wix-headless/references/commands/install-app.md

@@ -0,0 +1,42 @@
+# Install a Wix app onto a site
+
+Reference for the orchestrator. Invoked from `SKILL.md` Step 2 once per app entry across the loaded packs' `apps[*]`. Can't be a bash script — the install goes through the Wix MCP tool `CallWixSiteAPI`, not over the wire from the local shell.
+
+## Inputs
+
+- `siteId` — from `wix.config.json`.
+- `appName` — e.g. `wix-stores`, `wix-forms`, `wix-blog`. Resolved to `appDefId` via `<SKILL_ROOT>/references/commands/known-apps.json`. Unknown name → fail fast (`"Unknown app: {appName}. Known: [list]. Add it to references/commands/known-apps.json before retrying."`); do not guess.
+- `mcpPrefix` — captured in Step 0 (the discovered Wix MCP prefix; see `<SKILL_ROOT>/references/shared/MCP_PREFIX.md`).
+
+## Call
+
+Wrap in `date -u` captures so timing flows into `run.json.phases[]` as `{ phase: "app-install-{appName}", seconds: <duration> }`.
+
+```
+{mcpPrefix}CallWixSiteAPI
+  siteId:    {siteId}
+  url:       https://www.wixapis.com/apps-installer-service/v1/app-instance/install
+  method:    POST
+  body:      (a JSON object — NOT a string)
+             {
+               "tenant":      { "tenantType": "SITE", "id": "{siteId}" },
+               "appInstance": { "appDefId": "{appDefId}", "enabled": true }
+             }
+  reason:    Install {appName} on the new headless site
+  sourceDocUrl: https://dev.wix.com/docs/api-reference/business-management/app-installation/skills/install-wix-apps
+```
+
+The MCP tool requires explicit `url` / `method` / `body` / `reason` / `sourceDocUrl`. Do NOT pass `endpoint:`. Do NOT stringify `body` — pass it as a JSON object. (The Step 0 MCP bootstrap — see `<SKILL_ROOT>/references/commands/mcp-bootstrap.md` — preloads the `CallWixSiteAPI` schema so the orchestrator and subagents both see the right shape.)
+
+## Strict-then-recover
+
+| Outcome | Action |
+|---|---|
+| 2xx | Done. |
+| 4xx / 5xx with parseable body | Enter recover loop (max 1 retry): `{mcpPrefix}SearchWixRESTDocumentation` for `install app instance`, then `{mcpPrefix}ReadFullDocsMethodSchema` on the top match, then retry with the discovered shape. |
+| Recovery succeeds | Append to `run.json.commandDrift[]`: `{ command: "install-app", primaryError: { status, body }, recoveredWith: { endpoint, bodyPatch }, suggestedFix: "Update references/commands/install-app.md body template" }`. |
+| Both paths fail | Surface the original response body and the doc link to the user. Do not loop further. |
+
+## Why this is a reference doc, not a script
+
+The body shape and the strict-then-recover ladder are the parts that need to stay frozen across runs. Encoding them in a markdown reference the orchestrator reads (instead of a slash command the orchestrator dispatches) keeps the source of truth inside the skill and removes the round-trip through a slash-command shim.

package/skills/wix-headless/references/commands/known-apps.json

@@ -0,0 +1,5 @@
+{
+  "wix-stores": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+  "wix-forms": "225dd912-7dea-4738-8688-4b8c6955ffc2",
+  "wix-blog": "14bcded7-0066-7c35-14d7-466cb3f09103"
+}