@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-app/references/dashboard-page/DRAFT_TEMPLATE_COLLECTION.md

@@ -1,184 +0,0 @@
-# Draft Template — Collection page (Cases A, B and D)
-
-> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first. This page is shared by A, B
-> and D.
-
-> **You write `fetchData`, the filters and the columns.** This holds whatever the rows are: for a
-> CMS collection `fetchData` calls `@wix/data` `items.query()`
-> ([WIX_DATA.md](../data-collection/WIX_DATA.md)) and nothing else on this page changes.
-
-## Two rules this skeleton encodes, so read them before editing it
-
-**Every row opens a page of its own, never a panel.** `onRowClick` navigates —
-`navigateToEntityPage` to an `EntityPage` route when the record is editable, or to a read-only
-detail route when the page is display-only ([DRAFT_TEMPLATE_ROUTER.md § 4](DRAFT_TEMPLATE_ROUTER.md#4-read-only-detail-route--case-a)).
-A WDS `SidePanel` is not the drill-in: in Cairo it is the host for a page's own side panels — the
-fields card's "Manage fields", a table's column panel — and `example-bm` uses it as a row drill-in
-in exactly nothing. Every collection example there navigates.
-
-**No `SummaryBar` unless the request asked for one.** Not "unless the page seems to want one" —
-unless the prompt named a total, a count, or a "how many / how much" figure. It is absent from this
-skeleton on purpose; adding one uninvited pushes the rows down the page and puts a number on screen
-nobody has to be right about. When you do add one, wire it from
-[SKILL.md § Step 2](../../SKILL.md) — no `SummaryBar` unless the request asked for one.
-
-## The collection page
-
-This is the file [Step 4c's UX Completeness Self-Audit](../../SKILL.md#step-4c-ux-completeness-self-audit)
-is about: a working filter, named filters, and a row that opens.
-
-```tsx
-// {Feature}CollectionPage.tsx — Case A, B, D
-import type { FC } from 'react';
-import {
-  CollectionEmptyState, CollectionErrorState, CollectionNoResultsState, CollectionSearch, CollectionToolbarFilters,
-  MultiSelectCheckboxFilter, Table, stringsArrayFilter,
-  useStaticListFilterCollection, useTableCollection,
-} from '@wix/patterns';
-import { CollectionPage } from '@wix/patterns/page';
-import { usePatternsNavigate } from '@wix/patterns/router';
-import { fetch{Feature}Page, type {Entity}Row } from './{feature}-api';
-
-const STATUS_LABELS: Record<string, string> = { ACTIVE: 'Active', ARCHIVED: 'Archived' };
-// Filter factories are module-level: one instance per page, not per render.
-const statusFilter = stringsArrayFilter<'ACTIVE' | 'ARCHIVED'>({
-  // `name` is NOT the visible title — it feeds a11y legends, BI grouping and dataHooks.
-  // The title comes from the label props in the JSX below; the package's own
-  // `Collection Toolkit.md` guide has the prop model.
-  name: 'Status',
-  itemKey: (item) => item,
-  itemName: (item) => STATUS_LABELS[item] ?? item,
-});
-
-export const {Feature}CollectionPage: FC = () => {
-  const { navigateToEntityPage } = usePatternsNavigate<{Entity}Row>();
-
-  const state = useTableCollection<{Entity}Row, { status: typeof statusFilter }>({
-    queryName: '{feature}',
-    paginationMode: 'cursor', // 'offset' if your API pages by offset
-    itemKey: (item) => item.id,
-    itemName: (item) => item.name,
-    filters: { status: statusFilter },
-    // Every declared filter AND the search box are read here — one that never
-    // reaches the query renders fine and narrows nothing.
-    fetchData: async (query) =>
-      fetch{Feature}Page({
-        limit: query.limit,
-        cursor: query.cursor ?? undefined, // return `cursor: next || undefined` — key always
-        //                                    present, '' walks pages forever
-        search: query.search,
-        filters: { status: query.filters.status },
-      }),
-    // fetchTotal is for a requested aggregate, so it is commented out here. Uncommented, it
-    // must RESOLVE A NUMBER from an endpoint that counts, and it OVERRIDES the fallback to the
-    // loaded-rows count — so a wrong one reports 0 beside a full table while tsc stays green.
-    // Read QUERY_AND_PAGING.md, "What fetchTotal is allowed to call", before uncommenting.
-    // fetchTotal: async (query) => count{Feature}({ search: query.search, filters: query.filters }),
-    fetchErrorMessage: ({ err }) => (err instanceof Error ? err.message : 'Failed to load {feature}'),
-  });
-
-  const statusOptions = useStaticListFilterCollection(statusFilter, ['ACTIVE', 'ARCHIVED']);
-
-  // Nothing here reads `state` directly: the Table observes it internally. The moment you
-  // DO derive a number from it in this component — a header figure, a badge, a requested
-  // SummaryBar — it is MobX, and a plain read is computed once while the collection is still
-  // empty and never recomputed. Wrap it in `useSelector` and select a primitive: TABLE_STATE.md.
-
-  return (
-    <CollectionPage>
-      <CollectionPage.Header title={{ text: '{Page Title}' }} />
-      <CollectionPage.Content>
-        <Table
-          state={state}
-          // `search` defaults to ON, so omitting it ships a box that reaches no
-          // query. Wire it AND read query.search above. If the API has no
-          // free-text filter, resolve the term to one it does support.
-          search={<CollectionSearch placeholder="Search {feature}" />}
-          filters={
-            <CollectionToolbarFilters>
-              {/* BOTH label props, same string, and never accordionItemProps.title.
-                  The resolution model is the package's own `Collection Toolkit.md` guide. */}
-              <MultiSelectCheckboxFilter
-                filter={statusFilter} collection={statusOptions}
-                toolbarItemProps={{ label: 'Status' }}
-                accordionItemProps={{ label: 'Status' }}
-              />
-            </CollectionToolbarFilters>
-          }
-          // Three distinct messages. Without errorState a failed query looks
-          // exactly like a slow one: skeletons, forever.
-          emptyState={<CollectionEmptyState title="No {feature} yet" />}
-          // Name what excluded the rows — a seeded default or a missing scope
-          // looks exactly like "nothing matched", and only one is actionable.
-          noResultsState={<CollectionNoResultsState title="No {feature} match" subtitle="…" />}
-          // errorState is a RENDER FUNCTION: (err, { retry }) => ReactElement.
-          errorState={(err, { retry }) => (
-            <CollectionErrorState
-              title="Couldn't load {feature}"
-              subtitle={String(err)}
-              action={{ text: 'Retry', onClick: retry }}
-            />
-          )}
-          // The drill-in. Editable record → the EntityPage route (`/${item.id}`).
-          // Display-only → the read-only route, DRAFT_TEMPLATE_ROUTER.md §4. Either way a
-          // route, and passing `entity` lets the target title itself before its fetch lands.
-          onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
-          columns={[
-            // One column per field the prompt names; verify each source field —
-            // DATA_SOURCES.md, "A column must show what its header promises."
-            { id: 'name', title: 'Name', render: (item) => item.name },
-          ]}
-        />
-      </CollectionPage.Content>
-    </CollectionPage>
-  );
-};
-```
-
-## Turning `query.search` into a query
-
-`{feature}-api.ts` turns one term into a filter over *several* fields — an OR. **This is where
-search ships broken**: it renders, it reaches the query, and still returns every row, so nothing
-looks wrong until someone counts results.
-
-### A CMS collection — `@wix/data`
-
-`or()` combines two filters; it is **not** a condition. Called on a query or filter holding no
-condition yet it contributes an empty `{}` branch, and `{} OR x` matches the whole collection. Seed
-the filter with the first field, `or()` the rest onto it, then `and()` it onto the query — which is
-also what keeps the facet filters applying to *every* branch:
-
-```ts
-// SHORT_TEXT / LONG_TEXT fields only: `contains` on a number, date or
-// reference field is not a narrower match, it is no match.
-const searchFilter = (term: string, fields: string[]) =>
-  fields.map((f) => items.filter().contains(f, term)).reduce((acc, f) => acc.or(f));
-
-let query = items.query(COLLECTION_ID).eq('status', status).limit(limit);
-const term = search?.trim();
-if (term) query = query.and(searchFilter(term, ['companyName', 'contactEmail']));
-
-// ❌ or() onto a query holding no condition — empty $or branch, every row matches
-items.query(ID).or(items.filter().contains('a', t)).or(items.filter().contains('b', t));
-// ❌ or() onto the query itself — `status` survives only on the first branch
-items.query(ID).eq('status', s).contains('a', t).or(items.filter().contains('b', t));
-```
-
-### A vertical SDK — `@wix/bookings`, `@wix/ecom`, …
-
-No shared free-text operator; the shape differs per endpoint. Read its *Supported Filters* page
-([QUERY_AND_PAGING.md](QUERY_AND_PAGING.md#the-filterable-fields-are-a-closed-list-published-per-endpoint)),
-then `$or` one clause per identity field it lists. Never route the term to a single field by its
-shape — a measured run shipped this, and one branch is always dead:
-
-```ts
-query = term.includes('@')
-  ? query.startsWith('loginEmail', term)
-  : query.startsWith('contact.firstName', term);  // a surname matches nothing, ever
-```
-
-`startsWith` is prefix-only too — "Smith" never finds "John Smith" — so prefer the containment
-operator when the endpoint declares one, and say which you used in `noResultsState`.
-
-**Whatever the shape, prove it narrows.** Run one term you expect to hit a known row and one you
-expect to hit nothing, and check the row count changes for both.

package/skills/wix-app/references/dashboard-page/DRAFT_TEMPLATE_ROUTER.md

@@ -1,204 +0,0 @@
-# Draft Template — Cases A, B and D (router-wired)
-
-**Applies to [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md)'s Cases A, B and D.** All three need `PatternsReactRouter`, because in all three a row opens a page of its own — a panel is not the drill-in ([UX_SUCCESS_MODEL.md](UX_SUCCESS_MODEL.md)). Case A's detail route is read-only (§4); B and D route to a full `EntityPage`. This file covers only what a router adds.
-
-Every snippet below is copied from the installed `dist/docs/*.md` this session read, not from memory.
-
-## 1. Entry — `location` is manual in a Wix CLI app, and only because the router needs it
-
-`PatternsReactRouter` reads the page location through `container.usePageLocation()`, which only `withDashboard`'s `location` prop feeds — nothing supplies it automatically in a Wix CLI app:
-
-```tsx
-// {feature}.tsx — Case A, B or D
-import { useEffect, useState, type FC } from 'react';
-import { dashboard } from '@wix/dashboard';
-import { BusinessManagerTheme } from '../../BusinessManagerTheme';
-import { {Feature}App } from './{Feature}App';
-
-type PageLocation = Parameters<Parameters<typeof dashboard.observeState>[0]>[1]['pageLocation'];
-
-const Page: FC = () => {
-  const [location, setLocation] = useState<PageLocation | undefined>();
-
-  useEffect(() => {
-    const subscription = dashboard.observeState((_pageParams, environment) => {
-      setLocation(environment.pageLocation);
-    });
-    return () => subscription.disconnect();
-  }, []);
-
-  return (
-    <BusinessManagerTheme>
-      {location ? <{Feature}App location={location} /> : null}
-    </BusinessManagerTheme>
-  );
-};
-
-export default Page;
-```
-
-`BusinessManagerTheme` belongs here, not in `{Feature}App.tsx` — its default props must apply above `WixPatternsProvider`. Write it once per app: [BUSINESS_MANAGER_THEME.md](../BUSINESS_MANAGER_THEME.md#2-the-wrapper--write-this-file-once-per-app).
-
-**Skipping either the theme or `location` is a runtime-only failure.** Per `PatternsReactRouter`'s own docs: "Nothing catches this before runtime — type checking and bundling both pass, because neither renders the page." Only a browser catches a missing `location` or an unthemed page, which is why [Step 5's Preview](../../SKILL.md#validation) is not optional.
-
-## 2. App shell — provider, router, routes
-
-```tsx
-// {Feature}App.tsx — Case A, B or D
-import { withDashboard } from '@wix/patterns';
-import { WixPatternsProvider } from '@wix/patterns/provider';
-import { PatternsReactRouter, PatternsReactRoute } from '@wix/patterns/router';
-import { {Feature}CollectionPage } from './{Feature}CollectionPage';
-import { {Feature}EntityPage } from './{Feature}EntityPage';
-// Case D only:
-import { {Feature}SettingsPage } from './{Feature}SettingsPage';
-
-export const {Feature}App = withDashboard(() => (
-  <WixPatternsProvider>
-    <PatternsReactRouter>
-      <PatternsReactRoute type="collection" path="/" element={<{Feature}CollectionPage />} />
-      {/* Case B/D — editable record. Case A registers this ONE route instead, with
-          {Feature}DetailPage as the element and no /new route (§4). Either way the
-          type is `editEntity`: it wires back-navigation to the collection. */}
-      <PatternsReactRoute type="editEntity" path="/:id" element={<{Feature}EntityPage />} />
-      {/* Case B/D only — Case A has nothing to create: */}
-      <PatternsReactRoute type="createEntity" path="/new" element={<{Feature}EntityPage />} />
-      {/* Case D only: */}
-      <PatternsReactRoute type="other" path="/settings" element={<{Feature}SettingsPage />} />
-    </PatternsReactRouter>
-  </WixPatternsProvider>
-));
-```
-
-`PatternsReactRoute`'s `type` is one of exactly `"collection" | "createEntity" | "editEntity" | "other"` — no dedicated settings value, so a settings route is `"other"`. Case B: delete the `/settings` route and the import above it — nothing else changes.
-
-`{Feature}CollectionPage` is [DRAFT_TEMPLATE_COLLECTION.md](DRAFT_TEMPLATE_COLLECTION.md)'s component, unchanged; `{Feature}SettingsPage` (Case D) is [DRAFT_TEMPLATE_SETTINGS.md](DRAFT_TEMPLATE_SETTINGS.md).
-
-## 2b. The collection side of the handoff
-
-The router file above registers `/new`; something has to navigate there. All three of these live on
-the collection page, and `usePatternsNavigate` comes from **`@wix/patterns/router`** — not the root
-export, which is where it is easy to reach for it:
-
-```tsx
-import { PrimaryPageButton } from '@wix/patterns';
-import { usePatternsNavigate } from '@wix/patterns/router';
-
-const { navigateToEntityPage } = usePatternsNavigate<{Entity}>();
-const openNew = () => navigateToEntityPage({ path: '/new' }); // no record yet — omit `entity`
-
-// CollectionPage.Header — primaryAction takes an ELEMENT, not a { text, onClick } config:
-<CollectionPage.Header
-  title={{ text: '{Page Title}' }}
-  primaryAction={<PrimaryPageButton text="Add {entity}" onClick={openNew} />}
-/>
-
-// the empty state should offer the same action, and this one IS a config object:
-<CollectionEmptyState title="No {feature} yet" addNewCta={{ text: 'Add {entity}', onClick: openNew }} />
-
-// and a row opens the edit route:
-onRowClick={(item) => navigateToEntityPage({ path: `/${item.id}`, entity: item })}
-```
-
-The two shapes differ on purpose — `primaryAction` is an element, `addNewCta` is `{ text, onClick }`.
-Guessing either costs a compile round.
-
-## 3. Entity page — one component for both `/new` and `/:id`
-
-Full call details (both generics, what `onSave` receives, the `UseEntityPageParams` pick list) are in `<pkgRoot>/dist/docs/useEntityPage.md` — read it before filling in fields. The part specific to this router-based shape:
-
-```tsx
-// {Feature}EntityPage.tsx — Case B or D (sketch — see dist/docs/useEntityPage.md for the full call)
-import { useParams } from 'react-router-dom'; // NOT @wix/patterns/router — PatternsReactRoute wraps react-router-dom's Route, but only exports PatternsReactRoute/PatternsReactRouter/usePatternsNavigate itself
-import { useEntityPage, EntityPage } from '@wix/patterns';
-import { useForm } from '@wix/patterns/form';
-import { fetch{Entity}, save{Entity}, type {Entity} } from './{feature}-api';
-
-// The form's shape is yours to declare, and need not match the saved entity type.
-type {Entity}FormFields = { name: string };
-
-export const {Feature}EntityPage = () => {
-  const { id } = useParams<{ id?: string }>();
-  const form = useForm<{Entity}FormFields>();
-
-  const state = useEntityPage<{Entity}, {Entity}FormFields>({
-    parentPath: '/', // NOT parentPageId — this shape always uses Patterns Router
-    isNewEntity: () => !id, // a getter: the route can change (/new -> /:id after save) while this stays mounted
-    form,
-    fetch: () => (id ? fetch{Entity}(id).then((entity) => ({ entity })) : Promise.resolve({ entity: undefined })),
-    onSave: ({ widgetsFormData }) =>
-      save{Entity}({ id, ...form.getValues(), ...widgetsFormData }).then((updatedEntity) => ({ updatedEntity })),
-  });
-
-  return (
-    <EntityPage state={state}>
-      <EntityPage.Header title={{ text: id ? 'Edit {Entity}' : 'New {Entity}' }} />
-      <EntityPage.Content>
-        <EntityPage.MainContent>{/* form cards — see dist/docs/EntityPage.md */}</EntityPage.MainContent>
-      </EntityPage.Content>
-    </EntityPage>
-  );
-};
-```
-
-`useEntityPage`'s own docs are explicit about both details above: `parentPath` "Must be passed if using Patterns Router" (`parentPageId` is the non-router alternative — irrelevant here, since Case B/D always uses the router), and `isNewEntity` should be "a getter when the route can change while the page stays mounted" — exactly this component's case, since a successful create typically navigates `/new` → `/:newId`.
-
-**`UseEntityPageParams` is a `Pick<>`, so a param missing from it is a compile error, not an ignored prop.** `isNewEntity` is in that list at 1.470.0 and absent before ~1.46x. If it doesn't compile, read the pick list in your installed `dist/types/hooks/useEntityPage.d.ts` and upgrade — deleting the line makes a create route behave as an edit.
-
-## 4. Read-only detail route — Case A
-
-A display-only collection still routes its rows to a page — but not an `EntityPage`, which has no
-read-only mode and still has none at **1.471.0**: `fetch` and `onSave` are both required, and
-`actionsBarConfig` (`saveCta.text`, `cancelCta`) can retext Save but not remove it. It would ship
-two buttons that either do nothing or save a form nobody was offered.
-
-Use a WDS `Page` — what Cairo does itself: `example-bm`'s `DataExtensionEntityViewPage` and
-auto-patterns' `ViewModeEntityPage` are both plain WDS `Page`s, the latter unexported.
-
-```tsx
-// {Feature}DetailPage.tsx — Case A
-import { useEffect, useState } from 'react';
-import { useParams } from 'react-router-dom';
-import { Card, Loader, Page, Text } from '@wix/design-system';
-import { usePatternsNavigate } from '@wix/patterns/router';
-import { fetch{Entity}, type {Entity} } from './{feature}-api';
-
-export const {Feature}DetailPage = () => {
-  const { id } = useParams<{ id: string }>();
-  const { navigateToCollectionPage } = usePatternsNavigate();
-  const [entity, setEntity] = useState<{Entity} | undefined>();
-
-  useEffect(() => {
-    if (id) {
-      fetch{Entity}(id).then(setEntity);
-    }
-  }, [id]);
-
-  return (
-    <Page>
-      {/* The way back is the header's back button — a read-only page has no Cancel. */}
-      <Page.Header
-        title={entity?.name ?? '{Entity}'}
-        showBackButton
-        onBackClicked={() => navigateToCollectionPage({ path: '/' })}
-      />
-      <Page.Content>
-        {entity ? (
-          <Card>
-            <Card.Header title="Details" />
-            <Card.Divider />
-            <Card.Content>
-              <Text>{entity.name}</Text>
-            </Card.Content>
-          </Card>
-        ) : (
-          <Loader />
-        )}
-      </Page.Content>
-    </Page>
-  );
-};
-```
-
-If the request later grows an edit form this becomes §3's `EntityPage`, route type and `onRowClick`
-unchanged — which is why Case A registers `editEntity`, not `other`.

package/skills/wix-app/references/dashboard-page/DRAFT_TEMPLATE_SETTINGS.md

@@ -1,44 +0,0 @@
-# Draft Template — Settings page (Cases C and D)
-
-> Pick your case in [DRAFT_TEMPLATE.md](DRAFT_TEMPLATE.md) first; this page covers Case C or D.
-
-## The settings page
-
-No dedicated toolkit file exists for this yet (unlike Entity/Collection) — the shape, verified against `useSettingsPage.md`:
-
-```tsx
-// {Feature}SettingsPage.tsx — Case C or D
-import { SettingsPage, useSettingsPage, useSettings } from '@wix/patterns';
-import { useForm } from '@wix/patterns/form';
-import { fetch{Feature}Settings, save{Feature}Settings, type {Feature}Settings } from './{feature}-api';
-
-// The form's shape is yours to declare, and need not match the saved settings type —
-// one field per control on the page.
-type {Feature}SettingsFormFields = { reminderHours: number; notifyStaff: boolean };
-
-export const {Feature}SettingsPage = () => {
-  const form = useForm<{Feature}SettingsFormFields>();
-
-  const state = useSettingsPage<{Feature}Settings, {Feature}SettingsFormFields>({
-    form,
-    fetch: () => fetch{Feature}Settings().then((settings) => ({ settings })),
-    onSave: () => save{Feature}Settings(form.getValues()),
-    onCancel: async () => form.reset(),
-    saveSuccessToast: 'Settings saved',
-    saveErrorToast: (err, { retry }) => ({ message: 'Failed to save settings', action: { text: 'Retry', onClick: retry } }),
-  });
-
-  const settings = useSettings<{Feature}Settings, {Feature}SettingsFormFields>(state);
-
-  return (
-    <SettingsPage state={state}>
-      <SettingsPage.Header title={{ text: '{Settings Page Title}' }} />
-      <SettingsPage.Content>
-        <SettingsPage.MainContent>{/* form cards — same field-controller patterns as EntityPage */}</SettingsPage.MainContent>
-      </SettingsPage.Content>
-    </SettingsPage>
-  );
-};
-```
-
-`useSettingsPage`'s params are all required except `saveSuccessToast`/`saveErrorToast`: `form`, `fetch`, `onSave`, `onCancel`. There is no `parentPath`/`parentPageId` — a settings page isn't reached by drilling into a row, so it carries no back-navigation contract, and Case C needs no router at all to reach it (Section 1's entry renders it directly).

package/skills/wix-headless/entry/bootstrap.mjs

@@ -1,156 +0,0 @@
-#!/usr/bin/env node
-import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-// ── tiny event protocol (one JSON object per line) ───────────────────────────
-const emit = (event, extra = {}) =>
-  process.stdout.write(JSON.stringify({ event, ...extra }) + '\n');
-const fail = (event, extra = {}) => {
-  emit(event, { ok: false, ...extra });
-  process.exit(1);
-};
-
-// ── platform-safe binary names (npm/npx are .cmd on Windows) ─────────────────
-const isWin = process.platform === 'win32';
-const bin = (name) => (isWin ? `${name}.cmd` : name);
-const WIX = [bin('npx'), '-y', '@wix/cli@latest']; // run the CLI via npx — no global install/mutation
-
-// Force the CLI into non-interactive "agent" mode. Without an agent signal in
-// the env, `wix login` renders an interactive Ink TUI (device code + keypress)
-// that needs a raw TTY and crashes in an agent sandbox — and it never emits the
-// JSON login events this script forwards. The CLI uses @vercel/detect-agent,
-// whose first check is the AI_AGENT env var, so setting it guarantees agent mode
-// (and the awaiting_user/success/logged_in events) for every child we spawn.
-// Respect an existing value so a known runner (claude, cursor, …) keeps its name.
-const AGENT_ENV = { ...process.env, AI_AGENT: process.env.AI_AGENT || 'wix-headless-skill' };
-
-// Where the detached login parks its output between runs. It has to outlive this
-// process, so it can't be a pipe and can't live in the project.
-const STATE_DIR = join(tmpdir(), 'wix-headless-login');
-const LOG = join(STATE_DIR, 'login.log');
-const PIDFILE = join(STATE_DIR, 'login.pid');
-
-// run a command, capture stdout+stderr (combined), return {status, out}
-function capture(cmd, args, opts = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', shell: isWin, env: AGENT_ENV, ...opts });
-  return { status: r.status ?? 1, out: `${r.stdout || ''}${r.stderr || ''}`, error: r.error };
-}
-
-// ── 1. CLI reachable (via npx — no install) ──────────────────────────────────
-function checkCli() {
-  const r = capture(WIX[0], [...WIX.slice(1), '--version']);
-  if (r.status !== 0) fail('cli_unreachable', { detail: r.out.trim().slice(0, 400) });
-  // npx interleaves "npm notice …" lines with the version, so don't just take the
-  // last line — pick the first semver-looking token, falling back to the last line.
-  const version = (r.out.match(/\d+\.\d+\.\d+[^\s]*/) || [])[0] || r.out.trim().split('\n').pop();
-  emit('cli_ok', { version });
-}
-
-// ── 2. Reuse an existing session, or start device login ──────────────────────
-const hasExistingSession = () => capture(WIX[0], [...WIX.slice(1), 'whoami']).status === 0;
-
-function loginEvents() {
-  if (!existsSync(LOG)) return [];
-  return readFileSync(LOG, 'utf8')
-    .split('\n')
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .map((l) => {
-      try {
-        return JSON.parse(l);
-      } catch {
-        return null; // non-JSON CLI chatter
-      }
-    })
-    .filter((e) => e && e.event);
-}
-
-const alive = (pid) => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-// A login this machine started earlier may still be waiting on the browser. Reuse
-// its code instead of minting a second one — a new login invalidates nothing, but
-// it hands the user a different code than the one already on their screen.
-function pendingLogin() {
-  if (!existsSync(PIDFILE)) return null;
-  let state;
-  try {
-    state = JSON.parse(readFileSync(PIDFILE, 'utf8'));
-  } catch {
-    return null;
-  }
-  if (!state.pid || !alive(state.pid)) return null;
-  const ev = loginEvents().find((e) => e.event === 'awaiting_user');
-  if (!ev) return null;
-  // Don't hand back a code that's about to expire mid-typing.
-  const ageSeconds = Math.round((Date.now() - state.startedAt) / 1000);
-  if (ageSeconds > (ev.expiresInSeconds ?? 600) - 60) return null;
-  return ev;
-}
-
-// Detach so the login keeps polling after this process exits. stdio goes to a
-// file, not a pipe: a pipe dies with the parent, and the CLI would get EPIPE.
-function startLogin() {
-  mkdirSync(STATE_DIR, { recursive: true });
-  writeFileSync(LOG, '');
-  const out = openSync(LOG, 'a');
-  const child = spawn(WIX[0], [...WIX.slice(1), 'login'], {
-    detached: true,
-    stdio: ['ignore', out, out],
-    env: AGENT_ENV,
-    shell: isWin,
-  });
-  child.on('error', (e) => fail('login_failed', { detail: String(e) }));
-  writeFileSync(PIDFILE, JSON.stringify({ pid: child.pid, startedAt: Date.now() }));
-  child.unref();
-}
-
-async function waitForCode(timeoutMs = 60000) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const events = loginEvents();
-    const ev = events.find((e) => e.event === 'awaiting_user');
-    if (ev) return ev;
-    const bad = events.find((e) => e.event === 'login_failed');
-    if (bad) fail('login_failed', bad);
-    await new Promise((r) => setTimeout(r, 500));
-  }
-  const detail = existsSync(LOG) ? readFileSync(LOG, 'utf8').trim().slice(-1500) : '';
-  fail('login_failed', {
-    detail: detail || `wix login produced no device code within ${timeoutMs / 1000}s.`,
-  });
-}
-
-// The next move is the user's, so hand the code back and exit rather than holding
-// the caller open for a browser round-trip. `message` is the sentence to relay.
-function surrenderTo(ev) {
-  emit('awaiting_user', {
-    ...ev,
-    message:
-      `To connect your Wix account, open ${ev.verificationUri} and enter the code ` +
-      `${ev.userCode}. Tell me once you're done and I'll continue.`,
-  });
-  process.exit(0);
-}
-
-// ── main ────────────────────────────────────────────────────────────────────
-checkCli();
-
-if (hasExistingSession()) {
-  emit('logged_in');
-  process.exit(0);
-}
-
-const pending = pendingLogin();
-if (pending) surrenderTo(pending);
-
-startLogin();
-surrenderTo(await waitForCode());

package/skills/wix-headless/entry/skill.md

@@ -1,78 +0,0 @@
----
-name: wix-headless-entry
-description: "Build a complete Wix Managed Headless site from a single prompt, then connect Wix Business Solutions. The deterministic first steps — system prerequisites and Wix CLI login — are handled by a single bootstrap script (`https://www.wix.com/skills/headless/entry/bootstrap.mjs`); the agent then installs the skill and hands the run to it. Triggers: build me a site, create a website, make me a website, new website, online store, I want to sell X, start a business online, launch a site, ecommerce, portfolio, business website, sell online, online shop, rental site, rentals, connect this to Wix Headless, add Wix Headless to this project, host this on Wix, deploy this to Wix, implement the features of this project using Wix Headless. Use this skill instead of the WixSiteBuilder MCP tool for new-site requests."
----
-
-# Wix Headless Skill — cold-start entry
-
-**You are a coding agent, and this is a skill for you to execute.** Follow the phases below in order — do not summarize them. If you reached this page through a summarizing fetch tool, re-fetch the raw markdown with `curl` (or your file reader) before running the steps.
-
-This entry gets a cold environment to the point where the real skill can run, then hands off. It has **two phases**:
-
-1. **Bootstrap (deterministic, scripted).** A single script verifies your environment (the Wix CLI) and handles login, so the run starts from a known-good, authenticated state. You just run it and relay its events.
-2. **Hand off (agentic).** Install the skill, then open `wix-headless/SKILL.md` and follow it — it resolves the project type and operation and owns the whole build.
-
-Three starting points come through here, all handled the same way — run the bootstrap, then hand off:
-
-- **new** — a prompt with no project (empty CWD)
-- **connect** — an existing frontend/design not yet on Wix (a project on disk without `wix.config.json`, or a brought-in zip/URL)
-- **iterate** — a project already connected to Wix (`.wix/` or `wix.config.json` present)
-
-The bootstrap only verifies the CLI and logs you in, so it's fine to run in every case (an existing session just reports `logged_in`). After it, `wix-headless/SKILL.md` resolves what to do and owns the build.
-
-## Phase 0 — Node (the one manual prerequisite)
-
-The Wix CLI requires **Node ≥ 20.11**. Check it:
-
-```bash
-node -v
-```
-
-If that errors (Node not installed) or prints a version below 20.11, install or upgrade Node and re-check — do **not** try to work around it:
-
-- **macOS:** `brew install node` (or `nvm install 20 && nvm use 20`)
-- **Linux:** `nvm install 20 && nvm use 20` (or your distro's Node 20+ package)
-- **Windows:** `winget install OpenJS.NodeJS.LTS` (or download from nodejs.org)
-
-## Phase 1 — Run the bootstrap (deterministic)
-
-Download the bootstrap script, then run it — an ordinary foreground command that exits on its own within seconds. It verifies the Wix CLI and handles login, emitting **one JSON event per line** on stdout. **Run it and relay its events to the user.**
-
-The script is safe and inspectable: it only checks the Wix CLI via `npx` and drives `wix login` (a device-code flow) — no other network calls, and the only files it writes are the login's own output and pid under the OS temp dir. Read it first if your sandbox flags externally-downloaded code — either at the URL below or after downloading; both are the same file.
-
-```bash
-# macOS/Linux:
-curl -fsSL -O https://www.wix.com/skills/headless/entry/bootstrap.mjs
-# Windows PowerShell:
-iwr https://www.wix.com/skills/headless/entry/bootstrap.mjs -OutFile bootstrap.mjs
-
-node bootstrap.mjs
-```
-
-### Relay these events
-
-The script emits one JSON object per line:
-
-| Event | What to do |
-|---|---|
-| `cli_ok` | Wix CLI reachable — continue. |
-| `awaiting_user` (`verificationUri`, `userCode`, `message`) | The script has exited and the next step is the user's. Send them `message` as-is; the login keeps running on its own. |
-| `logged_in` / `success` | Login done — continue. |
-| `cli_unreachable` / `login_failed` (with `detail`) | Stop and show the user the `detail`. **Do not** improvise a parallel setup by hand. |
-
-On `awaiting_user`, run the script again once the user says they've logged in: it reports `logged_in` and you continue. Re-running while they're still in the browser is harmless — it returns the same code rather than issuing a new one.
-
-## Phase 2 — Install the skill and hand off
-
-Install the Wix Headless skills (`CI=1` forces plain non-interactive CLI output — keep it on every Wix CLI command):
-
-```bash
-CI=1 npx skills@latest add wix/skills --yes
-```
-
-The skills land in `.agents/skills/`.
-
-Then **open `wix-headless/SKILL.md` and follow it.** That skill owns the rest of the run — it resolves the **project type** (`managed` / `self-managed` / `stripe`) and, for managed, the **operation** (create / connect), then runs Discovery → Setup → Seed → the SDK handoff, and for managed create/connect it also scaffolds, builds, and releases.
-
-- **Don't** scaffold, install apps, or release by hand here — the skill does all of that (`SETUP.md`, `references/managed/CREATE.md`, etc.). This entry stops at *logged in*.
-- You're already authenticated from Phase 1, so the skill's managed auth step (`references/managed/AUTHENTICATION.md` §1 `whoami`) will pass without prompting again.