create-jay 0.25.3 → 0.25.5

package/dist/index.js

@@ -264,11 +264,9 @@ async function scaffoldProject(projectDir, name, selectedPlugins) {
   writeFile(projectDir, ".jay", readTemplate("jay-config.yaml"));
   writeFile(projectDir, "vite.config.ts", readTemplate("vite.config.ts"));
   writeFile(projectDir, "tsconfig.json", readTemplate("tsconfig.json"));
-  writeFile(projectDir, "CLAUDE.md", readTemplate("CLAUDE.md"));
-  const jaySkillPath = path.join(templatesDir(), "jay-skill.md");
-  if (fs.existsSync(jaySkillPath)) {
-    writeFile(projectDir, "jay-skill.md", fs.readFileSync(jaySkillPath, "utf-8"));
-  }
+  const agentGuidance = readTemplate("CLAUDE.md");
+  writeFile(projectDir, "CLAUDE.md", agentGuidance);
+  writeFile(projectDir, "agents.md", agentGuidance);
   const hasDesignValidator = selectedPlugins.some(
     (p) => p.name === "@jay-framework/design-system-validator"
   );

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "create-jay",
-  "version": "0.25.3",
+  "version": "0.25.5",
   "type": "module",
   "description": "Create a new Jay Stack project",
   "license": "Apache-2.0",
   "bin": "./dist/index.js",
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "skills"
   ],
   "scripts": {
     "build": "tsup",

package/skills/jay/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: jay
+description: Create a new Jay Stack project from scratch — the preconditions to check first and the scaffolding command that generates a working project. Hands off to the in-project CLAUDE.md and agent-kit for actually building pages, components, and plugins.
+---
+
+# Create a new Jay project
+
+A short, ordered playbook for scaffolding a brand-new Jay Stack project. Use it when there is **no Jay
+project yet** and you need to bootstrap one.
+
+**Scope — bootstrapping only.** This skill gets a project onto disk and running. It does **not** teach
+how to build pages, components, contracts, or plugins — that guidance ships _inside_ the scaffolded
+project as `CLAUDE.md` plus the generated `agent-kit/` (designer / developer / plugin / devops role
+guides). After scaffolding, read those.
+
+## 0 · Preconditions (check before scaffolding)
+
+- **Node ≥ 20** — `node --version`. The scaffolder and CLI require it.
+- **A package manager** — npm (bundled with Node) or Yarn. `npm create jay` auto-detects which one
+  invoked it and uses it for install.
+- **For the AIditor (visual AI editor, included by default): Claude Code installed locally + an API
+  key.** The project ships with `@jay-framework/aiditor`, whose `/aiditor` route runs an agent
+  server-side via the Claude Agent SDK. Its authentication matches Claude Code: install the `claude`
+  CLI, then either set `ANTHROPIC_API_KEY` in the environment **or** run `claude login`. Without this
+  the project still scaffolds, builds, and runs — only the `/aiditor` route's agent won't run.
+- **For any Wix plugin (`wix-stores` / `wix-members` / `wix-media` / `wix-data` / `wix-deploy`): a Wix
+  account + a browser login.** All Wix plugins share one credential owner,
+  `@jay-framework/wix-server-client`, which is pulled in automatically when you select any `wix-*`
+  plugin. Its setup is **interactive** — during `setup` it shells out to the Wix CLI
+  (`npx @wix/cli login`, opening a browser for OAuth) and, if the project isn't connected to a site yet,
+  runs `npm create @wix/new init` to connect one. From there it fetches the app secret and writes
+  `config/.wix.yaml` for you — you are **not** prompted for an API key, site ID, or client ID (those are
+  derived or fetched). Notes:
+  - This step **requires interactive mode.** In non-interactive / CI runs it is skipped with a
+    `needs-config` note; re-run `yarn setup` in a terminal to complete it.
+  - **`wix-deploy` additionally needs a live Wix login at deploy time** (`yarn wix:deploy`) — it uses
+    the Wix CLI session in `~/.wix`. If that session is missing it errors with "Run `wix login` first";
+    just run `npx @wix/cli login` again.
+  - **API key is optional / manual.** The default flow uses the auto-fetched app secret; only hand-edit
+    an `apiKey` into `config/.wix.yaml` if you deliberately choose the API-key strategy.
+
+## 1 · Scaffold the project
+
+**Interactive** (prompts for a project name and a plugin selection):
+
+```bash
+npm create jay@latest
+# or:  yarn create jay
+# or:  npx create-jay
+```
+
+- **Project name** — lowercase letters, numbers, and hyphens; must start and end with a letter or
+  number; at least 3 characters (e.g. `my-store`).
+- **Plugins** — a checklist (UI Kit, validators, Wix Stores/Members/Media/Data, etc.). Defaults are
+  pre-checked; accept them or adjust.
+
+**Non-interactive** (CI / scripted — pass a name and an explicit, possibly empty, plugin list):
+
+```bash
+# a few plugins by package name (comma-separated):
+npm create jay@latest -- --name my-store --plugins "@jay-framework/ui-kit,@jay-framework/wix-stores"
+
+# no optional plugins:
+npm create jay@latest -- --name my-site --plugins ""
+```
+
+The scaffolder then, in order: creates `./<name>/`, installs dependencies, generates the agent-kit
+(`npx jay-stack-cli agent-kit`), and runs plugin setup (`npx jay-stack-cli setup`). A step that can't
+complete non-interactively (e.g. a plugin needing credentials) is skipped with a note and can be re-run
+later with `yarn setup`.
+
+### Completing setup non-interactively (agents / CI)
+
+`jay-stack-cli setup` has three input modes:
+
+- `--interactive` — prompts a human in the terminal.
+- `--answers <file>` — reads answers from a YAML file (for agents).
+- _(neither)_ — surfaces every needed answer instead of prompting.
+
+When a plugin needs a value it can't get, setup does **not** hang or guess — it prints a structured,
+machine-readable block and exits that plugin:
+
+```
+setup-needs-answer:
+  plugin: @jay-framework/some-plugin
+  key: apiKey
+  type: input
+  message: "Enter your API key"
+  choices:          # only present for select-type questions
+    - us: United States
+```
+
+**The loop for an agent:** run `yarn setup` → for each `setup-needs-answer:` block, add a line
+`<key>: "<value>"` to an `answers.yaml` → re-run `jay-stack-cli setup --answers answers.yaml`. Any value
+still missing surfaces again as another `setup-needs-answer:`; repeat until none remain. The `key` is the
+stable join field between the question and your answer.
+
+**Exception — Wix login is not answerable via file.** The Wix plugins' credential setup shells out to
+the Wix CLI for a browser-based OAuth login (`npx @wix/cli login`). In non-interactive mode it returns a
+`needs-config` note ("requires interactive mode"), **not** a `setup-needs-answer:` — there is no key you
+can put in `answers.yaml` for it. A human must run `yarn setup` in a real terminal once to complete the
+Wix login; everything else (app secret, client ID, site ID) is fetched/derived automatically after that.
+
+## 2 · What you get
+
+```
+my-store/
+  src/
+    pages/            # file-system routing — starts with a home page
+      page.jay-html
+      page.ts
+      page.jay-contract
+    styles/theme.css
+  .jay                # project + plugin configuration
+  CLAUDE.md           # in-project agent guidance — read this next
+  agent-kit/          # generated role guides + contract/plugin references
+  package.json        # scripts: dev, setup, agent-kit, validate, build, serve
+```
+
+## 3 · First run
+
+```bash
+cd my-store
+yarn dev            # or: npm run dev   → dev server (and the /aiditor route)
+```
+
+If plugin setup was skipped (missing credentials) run `yarn setup` to configure API keys, then
+`yarn agent-kit` to refresh generated references.
+
+## 4 · Hand-off — build inside the project
+
+Scaffolding is done. To actually build the site, switch to the in-project guidance:
+
+1. Read `CLAUDE.md` at the project root.
+2. Read `agent-kit/plugins-index.yaml` to see what plugins and contracts are available.
+3. Read the role guide that matches your task under `agent-kit/` — `designer/` (jay-html pages,
+   styling), `developer/` (`page.ts`, services, routing), `plugin/` (headless components, actions),
+   `devops/` (build, deploy, serve).
+
+Run `yarn validate` after changes.

package/templates/CLAUDE.md

@@ -6,8 +6,26 @@ This is a Jay Stack project.
 
 Run `yarn setup` then `yarn agent-kit` to generate the agent kit.
 
-Read `agent-kit/` for contracts, plugin references, and role guides. See the `/jay` skill for full details on the agent kit structure, CLI commands, and project organization.
+### Plugin setup (credentials)
+
+`yarn setup` configures each installed plugin. For agents/CI it is non-interactive: a plugin that needs
+a value exits with a structured `setup-needs-answer:` block (`plugin`/`key`/`type`/`message`/`choices`).
+Put each `<key>: "<value>"` into `answers.yaml` and re-run `jay-stack-cli setup --answers answers.yaml`;
+repeat until every plugin reports `configured`. See `agent-kit/devops/INSTRUCTIONS.md` for the full loop.
+
+**Wix plugins are the exception:** their login is a browser OAuth via the Wix CLI, so it can't be
+answered from a file — run `yarn setup` once in a real terminal to complete it. Everything else (app
+secret, client ID, site ID) is fetched automatically afterward.
+
+Read `agent-kit/` for contracts, plugin references, and role guides — this is the authoritative
+guidance for the agent kit structure, CLI commands, and project organization.
 
 Before making changes, read `agent-kit/plugins-index.yaml` and the relevant role guide (`agent-kit/designer/`, `agent-kit/developer/`, etc.).
 
 Run `yarn validate` after changes.
+
+## Visual editing (AIditor)
+
+This project includes the AIditor — a visual AI editor at the `/aiditor` route (`yarn dev`). It runs
+an agent server-side via the Claude Agent SDK, so it **requires Claude Code installed locally with an
+API key**: install the `claude` CLI, then either set `ANTHROPIC_API_KEY` or run `claude login`.

package/templates/jay-skill.md

@@ -1,123 +0,0 @@
----
-name: jay
-description: Getting started with Jay Stack projects. Covers plugin setup, agent-kit generation, the four roles (designer, developer, plugin, devops), and key CLI commands.
----
-
-# Jay Stack — Agent Skill
-
-Jay Stack is a full-stack framework. Plugins provide headless components (data + logic, no UI). Designers build UI in jay-html templates that bind to plugin contracts. Developers write page logic and services.
-
-## Getting Started with a Jay Project
-
-### Step 1: Setup plugins
-
-```bash
-yarn jay-stack-cli setup
-```
-
-This configures plugins interactively — prompts for API keys and credentials, creates config files, validates services. Run this once when starting a new project or after adding a plugin. Use `--no-interactive` in CI/scripts to create config templates without prompting.
-
-### Step 2: Generate the agent kit
-
-```bash
-yarn jay-stack-cli agent-kit
-```
-
-This materializes contracts, generates reference data, and copies role guides into `agent-kit/`. Run this after setup, or any time you need fresh contract data.
-
-### Step 3: Read the agent kit
-
-The agent kit is your entry point. Start here:
-
-**`agent-kit/plugins-index.yaml`** — lists every plugin and what it provides:
-
-```yaml
-plugins:
-  - name: wix-stores
-    contracts:
-      - name: product-page
-        description: Product detail page with SSR
-    actions:
-      - name: searchProducts
-        description: Search the product catalog
-    services:
-      - name: products-db
-        description: Product catalog API
-    commands:
-      - name: sync-catalog
-        description: Sync product catalog from CMS
-```
-
-Use this file to discover what's available before writing any code.
-
-**`agent-kit/materialized-contracts/`** — the actual `.jay-contract` files. Read these to understand the data shapes, rendering phases, and refs for each component.
-
-**`agent-kit/references/<plugin>/`** — pre-generated discovery data (product catalogs, collection schemas, etc.). Check here before running CLI commands — it's faster.
-
-## The Four Roles
-
-The agent kit contains guides organized by role. Read the role that matches your task:
-
-| Folder                 | Role             | When to read                                                      |
-| ---------------------- | ---------------- | ----------------------------------------------------------------- |
-| `agent-kit/designer/`  | Designer         | Creating or editing `.jay-html` pages, styling, template syntax   |
-| `agent-kit/developer/` | Developer        | Writing `page.ts` components, services, state management, routing |
-| `agent-kit/plugin/`    | Plugin Developer | Creating headless components, contracts, actions, CLI commands    |
-| `agent-kit/devops/`    | DevOps           | Building, deploying, serving in production, invalidation          |
-
-Each folder has an `INSTRUCTIONS.md` that lists all available guides. Start there.
-
-## Key CLI Commands
-
-```bash
-# Development
-yarn jay-stack-cli dev                    # Start dev server
-yarn jay-stack-cli dev -v                 # Verbose mode
-
-# Validation
-yarn jay-stack-cli validate               # Validate all jay-html, contracts, actions
-
-# Discovery
-yarn jay-stack-cli agent-kit --list       # List available contracts
-yarn jay-stack-cli params <plugin>/<contract>  # Discover URL params for a contract
-yarn jay-stack-cli action <plugin>/<action> --input '{}'  # Run a plugin action
-
-# Plugin commands (admin/batch operations)
-yarn jay-stack-cli run --list             # List available plugin commands
-yarn jay-stack-cli run <plugin>/<command> # Run a plugin command
-
-# Production
-yarn jay-stack-cli build                  # Build production artifacts
-yarn jay-stack-cli serve                  # Start production server
-```
-
-## Project Structure
-
-```
-src/
-  pages/              # File-system routing
-    page.jay-html     # Root page (/)
-    products/
-      page.jay-html   # /products
-      [slug]/
-        page.jay-html # /products/:slug
-        page.ts       # Page component (optional)
-  plugins/            # Local plugins
-  components/         # Headfull components
-  init.ts             # Project service initialization
-agent-kit/            # Generated by jay-stack agent-kit
-  plugins-index.yaml  # Discovery index
-  designer/           # Designer role guides
-  developer/          # Developer role guides
-  plugin/             # Plugin developer guides
-  devops/             # DevOps guides
-  materialized-contracts/
-  references/
-```
-
-## Before Writing Code
-
-1. Read `agent-kit/plugins-index.yaml` to see what plugins and contracts exist
-2. Read the relevant contract file to understand the data shape
-3. Read the role guide that matches your task (designer/developer/plugin/devops)
-4. Check `agent-kit/references/<plugin>/` for pre-generated data before using CLI commands