@wix/origami-skills 0.0.0-stage → 1.30.1

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# `@wix/origami-skills`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Markdown-only package holding the agent skills for sites exported by Origami.
+
+## Layout
+
+```
+skills/
+  <skill-name>/
+    SKILL.md      ← skill definition (frontmatter `name` + `description`, then instructions)
+    *.md          ← optional guides the skill links to
+```
+
+`wix-site-edit` is the native authoring skill: `SKILL.md` routes to `references/`, `playbooks/` and `examples/`, and
+runs `wix origami` CLI commands.
+
+`origami-setup` is the first-run skill: it skips what already works (one `wix whoami` first), installs the Wix CLI and its origami flow, signs in and
+exports a site. An agent reads it before any site or `node_modules` exists, so it is one `SKILL.md` with no links. It
+ends by reading `wix-site-edit` at its installed path and carrying on with the user's request.
+
+Every site created by `@wix/origami-site-generator` installs this package. The site itself has only a pointer: a
+`wix-site-edit` skill in `.claude/skills/`, plus `AGENTS.md` and a `CLAUDE.md`, which agents always load. All three tell the
+agent to read `node_modules/@wix/origami-skills/skills/wix-site-edit/SKILL.md` before every change. A new release reaches
+existing sites with `yarn install`; no re-export is needed.
+
+The skills refer to each other by their installed path (`node_modules/@wix/origami-skills/skills/<skill-name>/...`). Keep
+those paths in sync when you rename or move a file.
+
+The package has no build step; the files are published as-is. `pnpm test` checks that every Markdown link and
+anchor resolves inside the package.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@wix/origami-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.30.1",
+  "description": "Origami agent skills and READMEs, distributed as Markdown files",
+  "main": "README.md",
+  "files": [
+    "README.md",
+    "skills",
+    "!**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "exit 0",
+    "lint": "exit 0",
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishUnscoped": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "wix": {
+    "artifact": {
+      "groupId": "com.wixpress.npm",
+      "artifactId": "origami-skills",
+      "targets": {
+        "docker": false
+      }
+    },
+    "validations": {
+      "postBuild": [
+        "test",
+        "lint"
+      ]
+    }
+  },
+  "falconPackageHash": "c9f08abfbe146be78c67bc5d9818ea9e75abc2859a4879408d4375c8"
 }

package/skills/editor-react-component/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: editor-react-component
+description: Build a component when `packages/site-app/site-component-catalog.json` has no `{Name}` (and the type is not Page / Section / Header / Footer). Use for a missing component or behavior on this exported site, or inside a Wix CLI app. Read the local wix-app references; do not fetch them from GitHub. If the catalog has the type but the wrapper is missing, fetch the wrapper — do not use this skill.
+---
+
+# Editor React component
+
+The docs and scripts are in `wix-app/` at the workspace root, vendored from [EDITOR_REACT_COMPONENT.md](https://github.com/wix/skills/blob/main/skills/wix-app/references/EDITOR_REACT_COMPONENT.md). Read those local files. Do not fetch them from GitHub.
+
+When a file under `wix-app/` says `<SKILL_ROOT>`, that directory is `wix-app` (it contains `scripts/` and `references/`). Links such as `editor-react-component/ACCESSIBILITY.md` resolve under `wix-app/references/`.
+
+## Which path
+
+- **Wix CLI app.** If the project has `wix.config.json`, follow `wix-app/references/EDITOR_REACT_COMPONENT.md` as written. Scaffold with `npx wix generate` only when the component folder does not exist. Do not edit `*.generated.ts`. Finish with `npx wix build && npx wix generate manifest`.
+- **This exported site.** There is no `wix.config.json` (its `wix.config.mjs` only adds the `wix origami` commands). Do not run the Wix CLI app commands (`wix generate`, `wix build`). Do not scaffold `src/extensions/`. Do not add `*.generated.ts`, `component.preview.tsx`, or `*.extension.ts`.
+
+## This exported site
+
+0. Confirm `{Name}` is absent from `packages/site-app/site-component-catalog.json`. If a catalog row exists, stop and fetch the wrapper (`node_modules/@wix/origami-skills/skills/origami-component-usage/SKILL.md`).
+
+1. Read only the matching rows in `wix-app/references/EDITOR_REACT_COMPONENT.md`. The reference policy in that file still applies: read the required and triggered docs, and do not expand scope.
+2. Create `packages/site-app/src/components/<component-name>/`:
+   - `<component-name>.jsx` — UI and behavior
+   - `<component-name>.module.css` — scoped styles
+
+   This package is JavaScript. Keep the public props, semantic root, named parts, direction, and accessibility rules from the reference docs, and express the props in the JSX file.
+3. Import the component from `packages/site-app/src/pages/<page>/structure.jsx` and place it inside a Section. Direct children of `Page` stay Header, Footer, Section, or pinned.
+4. After the JSX is written, run:
+
+   ```bash
+   node wix-app/scripts/scan-a11y-review.cjs packages/site-app/src/components/<component-name>
+   ```
+
+   Then follow `wix-app/references/editor-react-component/ACCESSIBILITY.md`. If the scanner cannot load the component, say so and still apply that guide.
+5. Validate with `yarn build` from the workspace root. Do not run `npx wix build` or `npx wix generate manifest` here: `origami import-site` generates the manifest before it uploads the code.

package/skills/origami-component-usage/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: origami-component-usage
+description: Use whenever importing, rendering, or styling any UI component in a .tsx/.jsx file — a page/screen file or another component's file — including setting its props, adding CSS overrides, or applying a preset/theme. Resolve the type in `packages/site-app/site-component-catalog.json` first, then read `packages/site-app/llm-context/{module}/{Name}.md` and the wrapper `@origami-wrappers/{module}/{name}`. Do not guess from memory or other node_modules.
+---
+
+Resolve the type, then read its contract, then write the instance. Do not guess props, CSS, or presets from memory, from `node_modules`, or from a previous page. Do not look in `src/origamiComponents` or `wix-origami-components/`.
+
+The inventory is `packages/site-app/site-component-catalog.json`. The importable component is the wrapper `@origami-wrappers/{module}/{name}`: the `{name}` folder of its app's wrapper package, where `{name}` is `{Name}` lowercased (`wixEditorElements.WRichText` → `@origami-wrappers/wixEditorElements/wrichtext`). The readable contract is `packages/site-app/llm-context/{module}/{Name}.md`. Never treat `node_modules/@wix/origami-poc-runtime-snapshot/components/` as the catalog. Do not invent a wrapper by hand.
+
+After this dump: JSX trees (Section, BoxContainer + InternalContainer, Button / WRichText) in `node_modules/@wix/origami-skills/skills/wix-site-edit/references/components.md`, layout in `node_modules/@wix/origami-skills/skills/wix-site-edit/references/layout.md`, paint in `node_modules/@wix/origami-skills/skills/wix-site-edit/references/style.md`, import behavior in `node_modules/@wix/origami-skills/skills/wix-site-edit/playbooks/save-and-verify.md`.
+
+## 1. Catalog — pick the component
+
+Choosing what to build? Read `packages/site-app/component-catalog.md`, which lists every component the site has by kind, with its name and purpose, and pick the one whose purpose fits the content. Then look up that name here.
+
+Open `packages/site-app/site-component-catalog.json`. Top-level keys are modules (`wixEditorElements`, `wixSystemElements`, `wixGalleriesElements`, …). Each module has `appDefId`, `revision` and `entries`, which keeps components and context providers apart: `entries.components.{Name}` and `entries.contextProviders.{Name}`, each with `componentId`, `version`, and `description`. Render only a `components` entry; a `contextProviders` entry is a context provider (with its `hook`, when it has one), not a component to render.
+
+```sh
+NAME=Button   # replace with the component you're looking up
+CATALOG="packages/site-app/site-component-catalog.json"
+python3 -c "
+import json,sys
+name=sys.argv[1]
+c=json.load(open(sys.argv[2]))
+for module, body in c.items():
+    row=body.get('entries',{}).get('components',{}).get(name)
+    if row:
+        print(module)
+        print(body['appDefId'])
+        print(body['revision'])
+        print(row['componentId'])
+        print(row['version'])
+        print(row.get('description',''))
+        break
+else:
+    sys.exit(1)
+" "$NAME" "$CATALOG"
+```
+
+- **Found.** Remember `{module}`, `{appDefId}`, `{revision}`, `{componentId}`, `{version}`. Continue to step 2.
+- **Not found.** `Page`, `Section`, `HeaderSection`, and `FooterSection` stay on `@wix/origami-poc-runtime-snapshot/components/{Name}` (they are layout shells, not catalog rows). Any other missing name is not on this site; report it as unavailable and do not invent the type.
+
+## 2. Contract and wrapper — in this order
+
+Paths (replace `{module}` / `{Name}` from the catalog row):
+
+| What | Path |
+| --- | --- |
+| LLM contract (props, CSS allowlist, presets, ref elements) | `packages/site-app/llm-context/{module}/{Name}.md` |
+| Importable wrapper | `@origami-wrappers/{module}/{name}` (`{name}` is `{Name}` lowercased) |
+| Wrapper files, after `yarn install` | `node_modules/@origami-wrappers/{module}/{name}/` at the workspace root |
+| Wrapper entry | `…/index.ts` |
+| Definition / CSS | `…/definition.ts`, `…/defaults.css` |
+
+**Read `llm-context/{module}/{Name}.md` first** when that file exists. It is the dump: Props, CSS Defaults, Presets (`PRESET_NAMES`), Ref Elements (`REF_ELEMENTS`).
+
+**Then confirm the wrapper package is installed.** Import it from `@origami-wrappers/{module}/{name}`. Do not edit generated files (`// @generated — do not edit by hand`). Do not read `baseComp/` unless the definition or defaults are blocked.
+
+If the markdown is missing but the wrapper exists, dump the wrapper:
+
+```sh
+MODULE=wixEditorElements   # from the catalog
+NAME=Button
+ROOT="node_modules/@origami-wrappers/$MODULE/$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]')"
+
+find "$ROOT" -maxdepth 1 \( -name 'definition.ts' -o -name 'defaults.css' -o -name 'index.ts' -o -name '*.tsx' \) \
+  | sort \
+  | while IFS= read -r f; do echo "--- $f ---"; cat "$f"; done
+```
+
+If the catalog has the type but its app's wrapper package is not a dependency of `packages/site-app/package.json` (or the llm-context file is missing), **fetch it** (step 3). If it is a dependency but its folder is missing, run `yarn install`. Do not import that type from the runtime snapshot.
+
+## 3. Fetch a missing wrapper or llm-context
+
+Use the catalog row. Do not invent ids.
+
+```sh
+APP_ID=appDefId_from_catalog
+COMP_ID=componentId_from_catalog
+VERSION=version_from_catalog
+MODULE=module_from_catalog
+NAME=Button
+
+BASE="https://dev.wix.com/_api/component-wrapper-server/v1"
+
+# LLM markdown → packages/site-app/llm-context/{module}/{Name}.md
+curl --fail -sS "$BASE/component-llm-context/$APP_ID/$COMP_ID?version=$VERSION"
+```
+
+- Wrapper: every wrapper of an app is one package. When `packages/site-app/package.json` has no `@origami-wrappers/{module}` dependency, add the app's tarball to `dependencies`, then run `yarn install` at the workspace root. It needs no login.
+  ```json
+  "@origami-wrappers/{module}": "https://viewer-apps.parastorage.com/_api/component-wrapper-server/v1/app/{appDefId}/components.tgz?revision={revision}"
+  ```
+  `{revision}` is the module's `revision` in the catalog. The package always holds the app's latest components; the revision gives each set of component versions its own URL, so yarn and the CDN never answer a stale package for it.
+  When the package is installed but has no `{name}/` folder, the type has no wrapper: do not use it.
+- LLM response: `{ "llmContext": "markdown" }`. Write `packages/site-app/llm-context/{module}/{Name}.md`. Auth is the Wix CLI session (`wix login`). A 401 means login, then retry.
+- Do not hand-write wrapper source to skip the fetch.
+
+Export already added the wrapper package of every catalog app. Fetch only what is missing.
+
+## 4. Import the wrapper, then author the instance
+
+Any page or global Header/Footer `structure.jsx` imports the wrapper from its app's package:
+
+```ts
+import { Name } from '@origami-wrappers/{module}/{name}'
+```
+
+Reuse the import when that file already has the type.
+
+**Defaults stylesheet.** The wrapper's `defaults.css` is loaded by the item's generated component: the `.jsx` file in that item's `_generated/` folder named like its stylesheet (often `Home.jsx`, even on a page that is not the home page; a global component's is named after the component), not `index.jsx`. Export writes one import there for every wrapper type the structure used at that time, above `import { Structure }`, so the wrapper CSS loads before the item's own stylesheet; nothing rewrites it when you add a type. When you add a type that the item did not have, add its import to that file yourself, next to the other `@origami-wrappers` imports at the top:
+
+```js
+import '@origami-wrappers/{module}/{name}/css'
+```
+
+Never `@import` it from a `.css` file: the wrapper CSS (and its presets) must come before every site stylesheet, or its rules override the site's.
+
+This is the only edit you make under `_generated/`, and it only affects local preview: import sends `structure.jsx`, `layout.css`, `style.css`, and `unmapped.json`, not `_generated/`, and the next export writes that file again. Do not import `presets/*.css` — the wrapper's `defaults.css` loads those.
+
+Do not import a catalog type from `@wix/origami-poc-runtime-snapshot/components/{Name}` once its wrapper exists. The exception is `InternalContainer`: import it from `@wix/origami-system-components/InternalContainer`.
+
+1. **Props** — from `{Name}Props` in the llm-context / `definition.ts`. Give every instance an `id`. Pass only props that file lists, as literals. Do not pass `compId` or `role`; set `className` equal to the `id`. Do not wrap instances in a local component. Do not build ids or data with a function call, a template string, or a `.map()`. Image and WRichText nested data objects are in `node_modules/@wix/origami-skills/skills/wix-site-edit/references/components.md` (not in `{Name}Props`). Nesting (Section / InternalContainer / BoxContainer) is there too.
+
+2. **CSS overrides** — from the commented list in CSS Defaults / `defaults.css`. Give each element `className` equal to its `id` and write one `.id` rule per component (the import rejects `#id`). Put only properties from that list onto that component. A property that is not in the list becomes an unexpected `cssProperties` entry and the editor save is rejected. Never target the `{id}-presets-wrapper` class or any class other than the element's own `.id`; the import rejects them. Selector grammar is `node_modules/@wix/origami-skills/skills/wix-site-edit/references/style.md`.
+
+3. **Presets** — from `PRESET_NAMES` in the llm-context / `index.ts` / `.tsx`. If that array is empty, do not set a preset. Do not read `presets/*.css` or use `presets:` from the definition file. Apply the name as `node_modules/@wix/origami-skills/skills/wix-site-edit/references/components.md` (Presets) describes.
+
+4. **Ref (inner) elements** — `elements: { animatedIcon: prop.element<AnimatedIconProps>() }` means the child has its own contract. Recurse this skill for `{Child}` (catalog → llm-context → wrapper). Style the inner part as `.id [data-ie-name="<part>"]` (`node_modules/@wix/origami-skills/skills/wix-site-edit/references/style.md`). If the child has no catalog row, hide or collapse that inner element with a prop from the parent definition (for Button, `iconCollapsed`), not with CSS that is missing from the parent’s `defaults.css`.
+
+If the generated files do not match this pattern, trust the files.
+
+Services come from `@wix/origami-services` through `OrigamiServicesProvider`. Pages import DM config data from their global components in import order, then their own `servicesConfigs/index.ts`. No services wiring or consent shim is generated. The runtime snapshot is used only for components, never services.

package/skills/origami-setup/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: origami-setup
+description: Install the Wix CLI and its origami flow, sign in to Wix, and export a site or create a new one, then continue straight into the change the user asked for. Skips every step that already holds. Use when `wix` or its origami commands are not installed, are outdated or are signed out, or when the user is starting with Origami. Never imports or publishes.
+---
+
+# Origami setup
+
+Goal: get the user's Wix site into a local folder that is ready to edit, then carry on with what the user asked for.
+Setup is a means, not the result: run only the steps that are missing, and never end the turn at the export.
+
+## 1. Check what is already done
+
+Run one command first:
+
+```bash
+wix whoami; wix origami --help
+```
+
+- `wix` is not found: go to step 2.
+- `wix origami` is an unknown command: run `wix flows add origami`, then read the `wix whoami` result below.
+- `wix whoami` prints an email address: Node, the CLI and sign-in all work. Go to step 4 and skip the machine checks and the install.
+- `wix whoami` prints no email address: go to step 3.
+- The working folder, or a folder the user names, already holds an export (`packages/site-app/.env`): reuse it only when `wix origami sites | grep -F -- "<its VITE_WIX_METASITE_ID>"` prints that site and, if the user named a site, is that site. Otherwise export the requested site into a new folder in step 4.
+  - When `node_modules/@wix/origami-skills/skills/wix-site-edit/SKILL.md` exists in it, go to step 6.
+  - Otherwise ask the user before running `yarn install` in a folder this setup did not export, then go to step 5.
+
+## 2. Install the CLI
+
+Origami needs Node 22.16 or later and Corepack.
+Check both in one command, then install the Wix CLI and its origami commands:
+
+```bash
+node -v; corepack -v
+npm install -g @wix/cli
+wix flows add origami
+```
+
+- Install Node or change its version yourself once the user approves, and never run npm with `sudo`.
+- When `wix flows add origami` fails to reach the registry, ask the user to connect to the Wix network or VPN.
+- When a later command prints a CLI update diagnostic, run the update command it prints (outside a site, `wix flows remove origami && wix flows add origami`) and retry that command.
+
+## 3. Sign in
+
+- Run `wix login`, give the user the URL and the code it prints, and wait for it to report the signed-in user.
+- Never type the user's password.
+
+## 4. Get the site
+
+- Put every value the user gave (site name, folder) in single quotes in the command, writing each `'` inside it as `'\''`, so the shell never expands it. Replace a leading `~` in a folder with the absolute home path first, since `~` does not expand inside quotes.
+- Set `<site>` to a new folder named after the site with only lowercase letters, digits and hyphens, such as `bakery-site`, unless the user names a folder:
+  - When the working folder is the home folder, use `~/wix-sites/<name>` and create `~/wix-sites` if it is missing.
+  - Otherwise use `./<name>` inside the working folder, so the agent can edit the site and load its instructions without leaving its workspace.
+  - When that folder exists and is not empty, add a number, such as `bakery-site-2`.
+- Before you export or create a site, tell the user in one line that the export adds a web OAuth app named `export site` to a site that has none.
+- For a site the user names, narrow the list with `wix origami sites | grep -iF -- '<name or msid>'`; the full list can hold hundreds of sites. Keep only rows whose name or msid equals the user's words exactly, ask the user when none or several remain, then run `wix origami export-site --site <msid> -d <site>`.
+- For a new site, run `wix origami create-site --name '<name>' -d <site>` once; it creates a blank, unpublished Studio 2 site and exports it.
+- When `create-site` prints `was created but isn't ready to export yet`, run the `wix origami export-site` command it prints a minute later; never run `create-site` again for that site.
+- When the export fails without detail, export once more into a new empty folder.
+- Chain the export and the install in one command: `wix origami export-site … -d <site> && cd <site> && yarn install`.
+
+## 5. Install the site's packages
+
+- In `<site>`, run `yarn install`.
+- When `yarn` is not found, run `corepack enable`, then run `yarn install` again.
+- When the install fails, report the command and the error, and do not change the exported packages to make it pass.
+
+## 6. Continue with the user's request
+
+Read `<site>/node_modules/@wix/origami-skills/skills/wix-site-edit/SKILL.md` now, in the same turn, then:
+
+- The user's request names a change (content, design, a page, a section, a new site's purpose): make it now with `wix-site-edit`. Do not stop to report the setup; mention it in one line of the final answer.
+- The request names no change: read the exported pages and theme, then ask what to change, offering 2–4 concrete options that fit this site, such as restyling the theme, rewriting the home page for the user's business, or adding a page. Use a multiple-choice question tool when you have one.
+
+Never publish the site.

package/skills/wix-site-edit/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: wix-site-edit
+description: Applies Wix Editor-compatible practices for layout, style and components on an exported Wix site, and runs its `wix origami` CLI operations (export, build check, media upload, import). Builds from the site's full component catalog and Site Style/Brand, and keeps the files in a form the Wix Editor can import. Never publishes.
+---
+
+# Origami toolkit
+
+Author native Origami files in an exported Wix site workspace, using that export's component contracts.
+The scope is native components, theme, the shared header and footer, pages and menus; CMS bindings and custom components are outside it.
+Keep every edit in a form `wix origami import-site` accepts; the local preview also renders files the import rejects.
+`<site>` is the exported workspace folder.
+
+## Operations
+
+Choose the operation the user needs; the playbooks are optional sequences.
+
+| Need | Operation or reference |
+| --- | --- |
+| Install, update or sign in to the CLI | Follow `node_modules/@wix/origami-skills/skills/origami-setup/SKILL.md` |
+| Get a site, or create a new one | Section 4 of [origami-setup](../origami-setup/SKILL.md): `wix origami sites` and `wix origami export-site` for an existing site, `wix origami create-site` for a new one |
+| Export a site | `wix origami export-site --site <msid> -d <site>` into an empty folder |
+| See what the site can render | `component-catalog.md`: every component by kind, with its name and purpose ([Browse the catalog](references/components.md#browse-the-catalog)) |
+| Look up a component | find its app in `site-component-catalog.json`, then read `llm-context/<app>/<Name>.md` (props, CSS allowlist, presets, inner parts) |
+| Find font IDs | `wix origami search-font -f <words>` prints Wix font ids and their weights |
+| Validate local files | `yarn lint` from the workspace root after each change; correct reported errors ([Validate local files](playbooks/save-and-verify.md#validate-local-files)) |
+| Render and inspect locally, optionally | [Local render](playbooks/save-and-verify.md#local-render) |
+| Generate images with AI (spends AI credits) | [Generated images](#generated-images) |
+| Upload images named by URL or local file | `wix origami upload-media --site <msid> -d <site>`; it rewrites each `uri` to a Wix media id in place, so run it before `yarn build` and import |
+| Import the full bundle | `wix origami import-site --site <msid> -d <site>`; read [import behavior and verification](playbooks/save-and-verify.md) first |
+
+Follow an export's CLI update diagnostic before retrying.
+If an export fails without detail, retry once into a separate empty folder, keeping the partial export, before investigating.
+
+## Generated images
+
+From `<site>`, `wix origami generate-image -p "<prompt>" [-p "<prompt>" …]` generates one image per prompt and uploads each to the Media Manager of the site in `packages/site-app/.env` (`VITE_WIX_METASITE_ID`).
+
+1. Run it without `--yes`: it spends nothing and prints the AI credits left.
+2. Ask the user once for the whole batch, stating the number of images and the credits left. Offer the default model first (under 1 credit an image), then `--model google:4@2` (higher quality, about 6 credits an image).
+3. Rerun it with `--yes` and put each printed media id, width and height in the Image data.
+
+When no credits are left, the user declines, or a prompt is listed as `Failed:`, don't stop the task: tell the user in one line and use other images for the missing ones. Use images the user gives you, images already in the export, or the https URL of a freely licensed photo, then run `wix origami upload-media` ([Upload images](#operations)).
+
+## Workspace
+
+Read the exported files before editing them. The editable sources are under `<site>/packages/site-app/`:
+
+- the theme, `src/global/themes/theme.css`, and the menus in `src/global/menus/`;
+- `structure.jsx`, `layout.css`, `style.css` and `unmapped.json` of each page in `src/pages/<route>/` (Home is `src/pages/(home)/`);
+- the same four files of the header and footer in `src/global/components/<HeaderSection_…|FooterSection_…>/`.
+
+| Task | Read |
+| --- | --- |
+| What components the site has, and their props, data and nesting | [Components](references/components.md) |
+| Grids, Stacks, sizes and backgrounds | [Layout](references/layout.md) |
+| Brand palette, typography and shared styles | [Theme](references/theme.md) |
+| CSS properties, selectors and theme application | [Style](references/style.md) |
+| Breakpoints and mobile layout | [Responsive](references/responsive.md) |
+| Navigation, anchors and Menu | [Links and Menu](references/links-and-menu.md) |
+| Required lines, server rejections and known limits | [Supplement](references/supplement.md) |
+| Start from an empty folder | [Create a site](playbooks/create-a-site.md) |
+| Add a section locally | [Add a section](playbooks/add-a-section.md) |
+| Add a page | [New page](references/new-page.md) |
+| Inspect and import the full bundle | [Save and verify](playbooks/save-and-verify.md) |
+
+## Decision order
+
+1. Theme: follow a custom `theme.css`; when it is still the export default, update it first ([Theme](references/theme.md)).
+2. Component: [browse the catalog](references/components.md#browse-the-catalog) and use the component that fits the content's purpose most closely, with the props, presets and inner parts its contract offers ([Components](references/components.md)). Compose from boxes, text and images only when no component fits.
+3. Theme styles: connect the instance to its `var(--wst-…)` slot ([Style](references/style.md)).
+4. Page CSS: write layout in `layout.css` and paint in `style.css` only when the theme cannot express the styling.
+5. Missing component: when the catalog has no row for the type and it is not a Page, Section, header or footer, report the type as unavailable instead of building it.
+
+## Conduct
+
+- Use only the destination the user supplied or had created at their request.
+- Never publish.
+- Never type the user's credentials.
+- Read [import behavior](playbooks/save-and-verify.md#import-behavior) before describing what will change on the destination.
+- Preserve unrelated authored content and identities during local edits.
+- Complete the requested operation; local authoring or an export alone does not require an import.
+- Report validation, local visual inspection and import results separately, with any tool diagnostic and what remains unverified.
+- Stop once the requested operation and its report are done.

package/skills/wix-site-edit/examples/menu/menu-items.json

@@ -0,0 +1,11 @@
+{
+    "name": "Custom Main Menu",
+    "id": "CUSTOM_MAIN_MENU",
+    "type": "Builder.MenuItems",
+    "items": [
+        { "label": "Platform", "items": [], "id": "dataItem-menu-item-1", "isVisible": true, "type": "Builder.MenuItem",
+          "link": { "type": "AnchorLink", "id": "dataItem-menu-link-1", "anchorName": "Platform", "pageId": "#c1dmp", "anchorDataId": "#anchors-platform" } },
+        { "label": "Home", "items": [], "id": "dataItem-menu-item-2", "isVisible": true, "type": "Builder.MenuItem",
+          "link": { "type": "PageLink", "id": "dataItem-menu-link-2", "pageId": "#c1dmp", "target": "_self" } }
+    ]
+}

package/skills/wix-site-edit/examples/menu/menu.jsx

@@ -0,0 +1,86 @@
+// Copy this Menu's structure and icon data.
+// Keep all four _id fields populated; the server returns HTTP 500 without them.
+// Keep the animatedIcon SVGs; without them the mobile menu button shows no icon.
+// Choose IDs that do not collide with existing identities and update their references together.
+// Use references/links-and-menu.md for placement, paint and presets.
+// Imports in the header's structure.jsx (exactly these paths):
+//   import { Menu } from '@origami-wrappers/wixEditorElements/menu'
+//   import CUSTOM_MAIN_MENU from '../../../global/menus/CUSTOM_MAIN_MENU'
+//   import InternalContainer from '@wix/origami-system-components/InternalContainer'   (if the header doesn't import it yet)
+// Items: global/menus/CUSTOM_MAIN_MENU.json (shape in menu-items.json).
+
+<Menu
+    id="comp-menu"
+    className="comp-menu"
+    type="Container"
+    elementProps={{
+        hamburgerMenu: {
+            _id: 'data-mupia9m010',
+            content: <InternalContainer id="comp-menu-content" className="comp-menu-content" type="Container" />,
+            headerContent: <InternalContainer id="comp-menu-header" className="comp-menu-header" type="Container" />,
+            elementProps: {
+                hamburgerCloseButton: {
+                    elementProps: {
+                        animatedIcon: {
+                            _id: 'data-mupia9m016',
+                            svg: {
+                                uri: '7d72932f870a315ce1b030fcc29ba4e5.svg',
+                                type: 'Builder.VectorArt',
+                                id: 'data-mupia9m017',
+                            },
+                            svgLastAnimatedSelected: {
+                                uri: '11062b_702fac46ae484fc083b1aebda93bf545.svg',
+                                type: 'Builder.VectorArt',
+                                id: 'data-mupia9m019',
+                            },
+                            svgLastStaticSelected: {
+                                uri: '7d72932f870a315ce1b030fcc29ba4e5.svg',
+                                type: 'Builder.VectorArt',
+                                id: 'data-mupia9m018',
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        navbar: { _id: 'data-mupia9lz5', items: CUSTOM_MAIN_MENU.items },
+        hamburgerOpenButton: {
+            elementProps: {
+                animatedIcon: {
+                    _id: 'data-mupia9m028',
+                    duration: 0.6,
+                    svg: {
+                        uri: '11062b_eb9aba2e52494080bb879558d85e4109.svg',
+                        type: 'Builder.VectorArt',
+                        id: 'data-mupia9m029',
+                    },
+                    svgCustomAnimationSelected: {
+                        uri: '82fcd3_366fa2d88c2d4f00bca188880220525d.svg',
+                        type: 'Builder.VectorArt',
+                        id: 'data-mupia9m030',
+                    },
+                    svgLastStaticSelected: {
+                        uri: '11062b_eb9aba2e52494080bb879558d85e4109.svg',
+                        type: 'Builder.VectorArt',
+                        id: 'data-mupia9m031',
+                    },
+                    svgLastAnimatedSelected: {
+                        uri: '82fcd3_366fa2d88c2d4f00bca188880220525d.svg',
+                        type: 'Builder.VectorArt',
+                        id: 'data-mupia9m032',
+                    },
+                    svgCustomAnimationStart: {
+                        uri: '82fcd3_721d0e93e6824fe1a0ecc922c651afc4.svg',
+                        type: 'Builder.VectorArt',
+                        id: 'data-mupia9m033',
+                    },
+                    svgCustomAnimationEnd: {
+                        uri: '82fcd3_440e71671a8d42c0b224f11e366d98c0.svg',
+                        type: 'Builder.VectorArt',
+                        id: 'data-mupia9m034',
+                    },
+                },
+            },
+        },
+    }}
+/>

package/skills/wix-site-edit/examples/section.jsx

@@ -0,0 +1,25 @@
+// Syntax sample only: how a Section, a BoxContainer with its InternalContainer, and leaves nest.
+// Every element has a className equal to its id; section.layout.css and section.style.css select it as .id.
+// The leaf types (a heading and two buttons) are placeholders; use whichever catalog components fit the content.
+// Imports it needs in a page's structure.jsx (copy the export's own lines if they differ):
+//   import Section from '<the runtime snapshot package this export uses>/components/Section'
+//   import InternalContainer from '@wix/origami-system-components/InternalContainer'
+//   import { Background } from '@origami-wrappers/wixSystemElements/background'
+//   import { WRichText } from '@origami-wrappers/wixEditorElements/wrichtext'
+//   import { BoxContainer } from '@origami-wrappers/wixEditorElements/boxcontainer'
+//   import { Button } from '@origami-wrappers/wixEditorElements/button'
+<Section id="s1" className="s1">
+    <InternalContainer id="s1-ic" className="s1-ic" type="Container" backgroundLayer={[<Background id="s1-bg" className="s1-bg" type="Component" />]}>
+        <BoxContainer id="s1-group" className="s1-group" _id="dataItem-s1-group" type="Container" children={
+            <InternalContainer id="s1-group-ic" className="s1-group-ic" type="Container">
+                <WRichText id="s1-title" className="s1-title" type="Component" richText={{"html":"<h2>Heading</h2>","id":"dataItem-s1-title","type":"Builder.RichText"}} />
+                <BoxContainer id="s1-actions" className="s1-actions" _id="dataItem-s1-actions" type="Container" children={
+                    <InternalContainer id="s1-actions-ic" className="s1-actions-ic" type="Container">
+                        <Button id="s1-a" className="s1-a" type="Component" label={"First"} iconCollapsed={true} />
+                        <Button id="s1-b" className="s1-b" type="Component" label={"Second"} iconCollapsed={true} />
+                    </InternalContainer>
+                } />
+            </InternalContainer>
+        } />
+    </InternalContainer>
+</Section>

package/skills/wix-site-edit/examples/section.layout.css

@@ -0,0 +1,62 @@
+/* Decisions only: add the required lines in references/supplement.md. Desktop rules first, then the mobile block. */
+.s1-ic {
+    @origami-target internal-container-content-wrapper {
+        display: grid;
+        grid-template-columns: minmax(0px, 1fr);
+        grid-template-rows: auto;
+        padding-top: --spx(80);
+        padding-right: --spx(40);
+        padding-bottom: --spx(80);
+        padding-left: --spx(40);
+    }
+}
+.s1-group {
+    grid-row: 1 / 2;
+    grid-column: 1 / 2;
+    width: 100%;
+    align-self: start;
+    justify-self: start;
+}
+.s1-group-ic {
+    @origami-target internal-container-content-wrapper {
+        display: flex;
+        flex-direction: column;
+    }
+}
+.s1-title {
+    width: 100%;
+    align-self: start;
+    margin-bottom: --spx(24);
+}
+.s1-actions {
+    width: max-content;
+    align-self: start;
+}
+.s1-actions-ic {
+    @origami-target internal-container-content-wrapper {
+        display: flex;
+        flex-direction: row;
+    }
+}
+.s1-a {
+    width: --spx(140);
+    align-self: center;
+    margin-right: --spx(12);
+}
+.s1-b {
+    width: --spx(140);
+    align-self: center;
+}
+@media (max-width: 1023px) {
+    .s1-ic {
+        @origami-target internal-container-content-wrapper {
+            display: grid;
+            grid-template-columns: minmax(0px, 1fr);
+            grid-template-rows: auto;
+            padding-top: --spx(40);
+            padding-right: --spx(16);
+            padding-bottom: --spx(40);
+            padding-left: --spx(16);
+        }
+    }
+}

package/skills/wix-site-edit/examples/section.style.css

@@ -0,0 +1,13 @@
+/* Write every field of a theme slot you use (references/supplement.md, Required lines). */
+.s1-bg {
+    --backgroundColor: var(--wst-base-1-color);
+}
+.s1-title {
+    font: var(--wst-heading-2-font);
+}
+.s1-a {
+    background: var(--wst-button-primary-background-color);
+}
+.s1-b {
+    background: var(--wst-button-secondary-background-color);
+}

package/skills/wix-site-edit/examples/section.unmapped.json

@@ -0,0 +1,11 @@
+{
+    "components": {
+        "s1": {
+            "anchors": {
+                "type": "AnchorInfo",
+                "id": "anchors-s1",
+                "name": "s1"
+            }
+        }
+    }
+}

package/skills/wix-site-edit/playbooks/add-a-section.md

@@ -0,0 +1,12 @@
+# Add a section to a page
+
+Use this for a local edit in an exported site workspace.
+
+1. [Browse the catalog](../references/components.md#browse-the-catalog) and choose the components that fit the section's content.
+2. Add the Section in the requested position with [components](../references/components.md#nesting).
+3. Declare its [anchor](../references/links-and-menu.md#links) if anything links to it.
+4. Choose Grid or Stack, size and place the content, and add the Section's Page row with [layout](../references/layout.md).
+5. Author its [responsive layout](../references/responsive.md) and connect [theme styles](../references/style.md).
+6. Add the [required lines](../references/supplement.md#required-lines) and [validate](save-and-verify.md#validate-local-files) with `yarn lint`.
+7. Optionally, inspect the change in the [local render](save-and-verify.md#local-render).
+8. If the user asked to save to Wix, follow [save and verify](save-and-verify.md); the import sends the whole bundle, not only this Section.