eddev 2.3.12 → 2.3.14

package/skills/eddev/docs/design/responsive-scaling.mdx

@@ -0,0 +1,312 @@
+# Responsive Scaling (/docs/design/responsive-scaling)
+
+**Configure responsive Tailwind tokens with the local helper.**
+
+Responsive scaling is configured in `tailwind.config.ts` through the local
+`tailwind-helper`. Current projects still use Tailwind v3, so the helper config
+is the source of truth for Tailwind screens, design token values, and how those
+values move between screens.
+
+The usual pattern is to author real design values at `BASE` and one key desktop
+breakpoint, then let the helper fill the intermediate and wide-screen values.
+That keeps components on stable classes such as `p-8`, `gap-grid-gutter`,
+`rounded-lg`, and `type-title-xl`, while the generated CSS adjusts the actual
+size continuously as the viewport changes.
+
+## Standard Config [#standard-config]
+
+```ts filename="tailwind.config.ts"
+responsiveTheme({
+  screens: { sm: 600, md: 900, lg: 1200, xl: 1600, xxl: 2000 },
+  breakpoints: ["lg"],
+  interpolate: {
+    sm: {},
+    md: { base: "sm", lerp: true },
+    lg: { base: "lg", lerp: true },
+    xl: { base: "lg", scale: 1.2, lerp: true },
+    xxl: { base: "lg", scale: 1.3 },
+  },
+  spacing: {
+    BASE: {
+      4: 12,
+      8: 32,
+    },
+    lg: {
+      4: 16,
+      8: 56,
+    },
+  },
+})
+```
+
+`screens` defines the normal Tailwind min-width breakpoints. `BASE` is not a
+Tailwind screen; it is the value before any screen media query applies.
+
+`breakpoints` lists the screens that need explicit token maps. With
+`breakpoints: ["lg"]`, token families such as `spacing`, `size`,
+`borderRadius`, and `typography.styles` normally define `BASE` and `lg`. The
+other screens are generated from those anchors.
+
+`interpolate` describes how each screen gets its value:
+
+| Entry                                        | Meaning                                                                           |
+| -------------------------------------------- | --------------------------------------------------------------------------------- |
+| `sm: {}`                                     | Carry the current value at `600px`. This is usually still the `BASE` value.       |
+| `md: { base: "sm", lerp: true }`             | Start a smooth ramp at `900px`, from the `sm` value toward the next screen value. |
+| `lg: { base: "lg", lerp: true }`             | Use the authored `lg` value at `1200px`, then ramp toward `xl`.                   |
+| `xl: { base: "lg", scale: 1.2, lerp: true }` | Use the `lg` value scaled up for `1600px`, then ramp toward `xxl`.                |
+| `xxl: { base: "lg", scale: 1.3 }`            | Use the `lg` value scaled up for `2000px` and above.                              |
+
+`lerp` applies to the segment that starts at that screen. For example, `md`
+starts the `900px -> 1200px` ramp, and `lg` starts the `1200px -> 1600px`
+ramp.
+
+## How Values Are Generated [#how-values-are-generated]
+
+For each token, the helper walks the screens in order:
+
+1. Read the current screen's `base`.
+2. If that base has an authored token value, use it.
+3. If it does not, carry the previously resolved value.
+4. Apply `scale` when present.
+5. If `lerp` is true, emit a fluid value that reaches the next screen's value at
+   the next screen width.
+
+Using the `spacing.8` example above, the generated shape is:
+
+```css
+:root {
+  --spacing-8: 32px;
+}
+
+@media (min-width: 900px) {
+  :root {
+    --spacing-8: calc(32px + (100vw - 900px) / 300 * 24);
+  }
+}
+
+@media (min-width: 1200px) {
+  :root {
+    --spacing-8: calc(56px + (100vw - 1200px) / 400 * 11.2);
+  }
+}
+
+@media (min-width: 1600px) {
+  :root {
+    --spacing-8: calc(67.2px + (100vw - 1600px) / 400 * 5.6);
+  }
+}
+
+@media (min-width: 2000px) {
+  :root {
+    --spacing-8: 72.8px;
+  }
+}
+```
+
+There is no sudden jump at `900px`, `1200px`, or `1600px`: each ramp starts at
+the value already on screen and ends at the value the next media query starts
+with.
+
+## Smooth Versus Stepped [#smooth-versus-stepped]
+
+Without interpolation, the site keeps one value until the next breakpoint and
+then snaps to the new value. With interpolation, the value changes gradually
+across the viewport range.
+
+<figure>
+  <svg width="100%" height="320" viewBox="0 0 640 320" role="img" aria-label="Interpolated responsive scaling ramps smoothly between breakpoints while stepped sizing jumps at breakpoints">
+    <rect x="38" y="18" width="564" height="238" rx="8" fill="transparent" stroke="#94A3B8" strokeWidth="1" />
+
+    <line x1="60" y1="230" x2="580" y2="230" stroke="#94A3B8" strokeWidth="1" />
+
+    <line x1="60" y1="70" x2="60" y2="230" stroke="#94A3B8" strokeWidth="1" />
+
+    <line x1="216" y1="70" x2="216" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="294" y1="70" x2="294" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="372" y1="70" x2="372" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="476" y1="70" x2="476" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="580" y1="70" x2="580" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <path d="M60 230 L294 230 L372 150 L476 102 L580 78" fill="none" stroke="#16A34A" strokeWidth="4" strokeLinecap="round" strokeLinejoin="round" />
+
+    <path d="M60 230 L372 230 L372 150 L476 150 L476 102 L580 102 L580 78" fill="none" stroke="#64748B" strokeWidth="3" strokeDasharray="8 7" strokeLinecap="round" strokeLinejoin="round" />
+
+    <circle cx="294" cy="230" r="4" fill="#16A34A" />
+
+    <circle cx="372" cy="150" r="4" fill="#16A34A" />
+
+    <circle cx="476" cy="102" r="4" fill="#16A34A" />
+
+    <circle cx="580" cy="78" r="4" fill="#16A34A" />
+
+    <text x="60" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      0
+    </text>
+
+    <text x="216" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      sm
+    </text>
+
+    <text x="294" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      md
+    </text>
+
+    <text x="372" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      lg
+    </text>
+
+    <text x="476" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      xl
+    </text>
+
+    <text x="580" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      xxl
+    </text>
+
+    <text x="48" y="234" fontSize="12" textAnchor="end" fill="currentColor">
+      base
+    </text>
+
+    <text x="48" y="154" fontSize="12" textAnchor="end" fill="currentColor">
+      lg
+    </text>
+
+    <text x="48" y="106" fontSize="12" textAnchor="end" fill="currentColor">
+      1.2x
+    </text>
+
+    <text x="48" y="82" fontSize="12" textAnchor="end" fill="currentColor">
+      1.3x
+    </text>
+
+    <line x1="80" y1="292" x2="116" y2="292" stroke="#16A34A" strokeWidth="4" strokeLinecap="round" />
+
+    <text x="124" y="296" fontSize="12" fill="currentColor">
+      interpolated
+    </text>
+
+    <line x1="238" y1="292" x2="274" y2="292" stroke="#64748B" strokeWidth="3" strokeDasharray="8 7" strokeLinecap="round" />
+
+    <text x="282" y="296" fontSize="12" fill="currentColor">
+      stepped
+    </text>
+  </svg>
+
+  <figcaption>
+    The interpolated line reaches the same anchor values as the stepped line,
+    but it travels between them instead of snapping at each breakpoint.
+  </figcaption>
+</figure>
+
+## Why This Works Well [#why-this-works-well]
+
+Most designs have a strong mobile composition and a strong desktop composition.
+The awkward part is everything between them. If spacing, control sizes, radii,
+and type all jump at a single breakpoint, the page can feel like it rebuilds
+itself while the browser is being resized.
+
+The helper avoids that by treating breakpoints as anchors, not cliffs. The
+`BASE` and `lg` values still preserve the design decisions. The interpolation
+config simply describes how to travel between those decisions, and the wide
+screen `scale` values keep large displays from feeling like the same desktop
+layout stretched across too much space.
+
+Because the same interpolation map is used by spacing, size, radius, and
+typography tokens, their relationships stay coordinated. A card's padding, its
+gap, its corner radius, and the heading inside it can all resize through the
+same viewport ranges without each one inventing a separate breakpoint behavior.
+Grid gutters and margins can join the same rhythm by referencing spacing
+variables in the grid config.
+
+<figure>
+  <svg width="100%" height="320" viewBox="0 0 640 320" role="img" aria-label="Different token values resize continuously through the same breakpoint ranges">
+    <rect x="38" y="18" width="564" height="238" rx="8" fill="transparent" stroke="#94A3B8" strokeWidth="1" />
+
+    <line x1="60" y1="230" x2="580" y2="230" stroke="#94A3B8" strokeWidth="1" />
+
+    <line x1="60" y1="70" x2="60" y2="230" stroke="#94A3B8" strokeWidth="1" />
+
+    <line x1="294" y1="70" x2="294" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="372" y1="70" x2="372" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="476" y1="70" x2="476" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <line x1="580" y1="70" x2="580" y2="230" stroke="#CBD5E1" strokeWidth="1" strokeDasharray="4 4" />
+
+    <path d="M60 206 L294 206 L372 198 L476 192 L580 188" fill="none" stroke="#2563EB" strokeWidth="4" strokeLinecap="round" strokeLinejoin="round" />
+
+    <path d="M60 166 L294 166 L372 118 L476 96 L580 84" fill="none" stroke="#16A34A" strokeWidth="4" strokeLinecap="round" strokeLinejoin="round" />
+
+    <path d="M60 142 L294 142 L372 110 L476 86 L580 74" fill="none" stroke="#EA580C" strokeWidth="4" strokeLinecap="round" strokeLinejoin="round" />
+
+    <circle cx="372" cy="198" r="4" fill="#2563EB" />
+
+    <circle cx="372" cy="118" r="4" fill="#16A34A" />
+
+    <circle cx="372" cy="110" r="4" fill="#EA580C" />
+
+    <text x="60" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      BASE
+    </text>
+
+    <text x="294" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      md
+    </text>
+
+    <text x="372" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      lg
+    </text>
+
+    <text x="476" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      xl
+    </text>
+
+    <text x="580" y="262" fontSize="12" textAnchor="middle" fill="currentColor">
+      xxl
+    </text>
+
+    <line x1="80" y1="286" x2="116" y2="286" stroke="#2563EB" strokeWidth="4" strokeLinecap="round" />
+
+    <text x="124" y="290" fontSize="12" fill="currentColor">
+      spacing.4
+    </text>
+
+    <line x1="238" y1="286" x2="274" y2="286" stroke="#16A34A" strokeWidth="4" strokeLinecap="round" />
+
+    <text x="282" y="290" fontSize="12" fill="currentColor">
+      spacing.8
+    </text>
+
+    <line x1="406" y1="286" x2="442" y2="286" stroke="#EA580C" strokeWidth="4" strokeLinecap="round" />
+
+    <text x="450" y="290" fontSize="12" fill="currentColor">
+      title size
+    </text>
+  </svg>
+
+  <figcaption>
+    Different tokens can have different authored values, but they still move
+    through the same breakpoint rhythm.
+  </figcaption>
+</figure>
+
+## Practical Rules [#practical-rules]
+
+* Keep `screens` in ascending order and treat names like `md` or `lg` as layout
+  ranges, not device names.
+* Keep `breakpoints` short. Most sites only need `BASE` and `lg` token maps.
+* Put actual design decisions in `BASE` and each key breakpoint. Use
+  interpolation for the in-between screens.
+* Use `scale` for wide screens when a project should breathe more at `xl` and
+  `xxl`; omit it when the desktop composition should stay fixed.
+* For grid gutters and margins, reference spacing variables when they should
+  scale with the token system.
+* Prefer token classes in components. If a value should scale with the system,
+  add it to `spacing`, `size`, `borderRadius`, or `typography.styles` instead
+  of hard-coding a one-off responsive value.

package/skills/eddev/docs/design/type.mdx

@@ -0,0 +1,125 @@
+# Typography (/docs/design/type)
+
+**Configure typography tokens through Tailwind helper classes.**
+
+Typography tokens are normal Tailwind classes generated by `tailwind-helper`.
+Define the token names and responsive values in `tailwind.config.ts`, then use
+classes such as `type-title-xl`, `type-body-m`, and `type-ui-s` in views,
+blocks, and shared components.
+
+## Configuration [#configuration]
+
+```ts filename="tailwind.config.ts"
+responsiveTheme({
+  screens: { sm: 600, md: 900, lg: 1200, xl: 1600, xxl: 2000 },
+  breakpoints: ["lg"],
+  interpolate: {
+    sm: {},
+    md: { base: "sm", lerp: true },
+    lg: { base: "lg", lerp: true },
+    xl: { base: "lg", scale: 1.2, lerp: true },
+    xxl: { base: "lg", scale: 1.3 },
+  },
+  typography: {
+    fontFamily: {
+      body: "'GT-Cinetype', Helvetica, sans-serif",
+      heading: "'Agrandir-Wide', Helvetica, sans-serif",
+    },
+    styles: {
+      "title-xl": {
+        fontSize: { BASE: "32px", lg: "56px" },
+        lineHeight: "100%",
+        fontFamily: "heading",
+        fontWeight: "400",
+        letterSpacing: "-0.03em",
+        textTransform: "uppercase",
+      },
+      "body-m": {
+        fontSize: { BASE: "16px", lg: "18px" },
+        lineHeight: { BASE: "130%", lg: "140%" },
+        fontFamily: "body",
+        fontWeight: "400",
+        letterSpacing: "normal",
+        textTransform: "none",
+      },
+    },
+  },
+})
+```
+
+The helper creates component classes for each style:
+
+```tsx
+<h1 className="type-title-xl text-balance">{props.title}</h1>
+<div className="type-body-m text-fg-secondary">{props.description}</div>
+```
+
+It also maps `fontFamily` keys into Tailwind's font family theme, so regular
+classes like `font-body` can be used when a full text style is too much.
+
+## Responsive Values [#responsive-values]
+
+Text styles can use a single value or a breakpoint map. The helper converts
+percentage line heights into pixel values, interpolates `fontSize` and
+`lineHeight` when the interpolation config says to lerp, and emits media-query
+rules for the generated `.type-*` class.
+
+```ts filename="tailwind.config.ts"
+"title-l": {
+  fontSize: { BASE: "24px", lg: "40px" },
+  lineHeight: { BASE: "110%", lg: "100%" },
+  fontFamily: "heading",
+  fontWeight: "400",
+  letterSpacing: "-0.03em",
+  textTransform: "uppercase",
+}
+```
+
+Use `BASE` for the mobile/base value. Add only the breakpoints that need a real
+change.
+
+## Figma Export [#figma-export]
+
+The ED. Web Handoff plugin reads local Figma text styles and can output the
+`typography.styles` object for the Tailwind helper.
+
+Artworking rules:
+
+1. Create local text styles for the reusable type scale.
+2. Put breakpoint-specific styles at the end of the name, for example
+   `Title / XL / Laptop`.
+3. Keep breakpoint names out of the middle of the style name.
+4. Prefix design-only styles with `_`, or place them under a `/_` group, if
+   they should be ignored.
+
+The plugin uses the configured breakpoint labels. In its default config,
+`Mobile` maps to `BASE`, then `Phablet`, `Tablet`, `Laptop`, `Desktop`, and
+`4K` map to the named breakpoints.
+
+The plugin also reports font family/style combinations. Review those warnings
+before copying code, because the generated `fontFamily` token and `fontWeight`
+come from the font configuration or the plugin's weight guess.
+
+## Site Styles [#site-styles]
+
+Use type classes directly in components. For rich text or WordPress-rendered
+HTML, apply them in CSS with Tailwind's element variants or normal selectors:
+
+```css filename="styles/index.css"
+@layer components {
+  .wysiwyg {
+    @apply type-body-m;
+  }
+
+  .wysiwyg h2 {
+    @apply type-title-l mt-6 mb-4;
+  }
+
+  .wysiwyg a {
+    @apply underline underline-offset-[0.15em] decoration-fg/30;
+  }
+}
+```
+
+Keep component code on token names, not raw pixel values, unless the value is a
+one-off layout fix.

package/skills/eddev/docs/devtool/cli.mdx

@@ -0,0 +1,201 @@
+# eddev CLI (/docs/devtool/cli)
+
+**Run development, builds, codegen, and diagnostics through the eddev CLI.**
+
+The `eddev` CLI is the main development and build runner for an eddev theme. Run it from the theme root, usually through the project scripts in `package.json`.
+
+```json filename="package.json"
+{
+  "scripts": {
+    "dev": "eddev dev",
+    "build": "eddev build"
+  }
+}
+```
+
+Most day-to-day work should use `yarn dev --fast`. Fast mode runs the local serverless dev server with hot reloading on port `8080`, plus GraphQL codegen. It skips the admin and frontend SPA bundles, which are only needed when you access the local WordPress frontend directly without the `:8080` dev server port.
+
+Production SPA builds use `yarn build`. To check serverless production behavior locally, run `eddev build --serverless` and then `eddev preview`.
+
+<Callout type="info">
+  The CLI reads `.env`, `ed.config.json`, the Git repo name, WordPress theme files, GraphQL files, and the WordPress origin. If a command behaves strangely, first check that you are running it from the theme root and that `SITE_URL` points to the WordPress origin.
+</Callout>
+
+## Commands [#commands]
+
+| Command                    | What It Does                                                                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eddev dev --fast`         | Recommended development command. Starts GraphQL codegen and the hot-reloading serverless dev server on port `8080`.                                                             |
+| `eddev dev`                | Starts every dev mode, including watched admin and frontend SPA bundles. Use this when you need the WordPress-hosted SPA/admin asset builds.                                    |
+| `eddev build`              | Builds production frontend and admin bundles for WordPress-hosted SPA mode. This is not the serverless build.                                                                   |
+| `eddev build --serverless` | Builds the production serverless app. Usually followed by `eddev preview` when testing locally. Vercel uses this path automatically because `VERCEL` is set in the environment. |
+| `eddev preview`            | Runs the output from a previous `eddev build --serverless`. Usually used together with that build command.                                                                      |
+| `eddev analyze`            | Generates a frontend bundle analysis in `dist/frontend-analysis/`.                                                                                                              |
+| `eddev info`               | Prints discovered project, block, and view information.                                                                                                                         |
+
+Some older theme `package.json` files may still include `eddev setup`. That command is not present in the current CLI source; prefer the active commands above.
+
+## `eddev dev` [#eddev-dev]
+
+Use fast mode for normal development:
+
+```bash
+yarn dev --fast
+```
+
+Fast mode runs:
+
+| Mode         | What It Does                                                                                                                  |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `serverless` | Starts the local serverless dev server on port `8080`. This is the normal local frontend preview, with hot reloading.         |
+| `graphql`    | Loads the WordPress schema, validates project GraphQL files, generates TypeScript outputs, and optimizes query files for PHP. |
+
+The full `eddev dev` command runs every mode:
+
+| Mode         | What It Does                                                 |
+| ------------ | ------------------------------------------------------------ |
+| `serverless` | Starts the local serverless dev server on port `8080`.       |
+| `graphql`    | Runs GraphQL codegen and optimized query output.             |
+| `frontend`   | Builds and watches the WordPress-hosted SPA frontend bundle. |
+| `admin`      | Builds and watches WordPress admin/editor assets.            |
+
+Use the full command when you specifically need the local WordPress frontend or admin/editor asset bundles. If you are previewing the site through `https://site.local:8080`, fast mode is usually enough.
+
+The terminal UI shows the serverless frontend URL, the WordPress origin URL, and the status of the active services. Press `q` to quit. Press `c` or `k` to clear the visible serverless log.
+
+### Dev Options [#dev-options]
+
+| Option              | What It Does                                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--fast`            | Recommended. Shorthand for `--mode graphql,serverless`. Runs the hot-reloading serverless dev server and GraphQL codegen only. |
+| `--https <enabled>` | Enables or disables HTTPS for the serverless dev server. Defaults to `true`. Use `--https false` for plain HTTP.               |
+| `--verbose`         | Shows extra debugging information in logs.                                                                                     |
+
+Examples:
+
+```bash
+yarn dev --fast
+yarn dev --https false
+```
+
+`--mode <modes>` is available for debugging individual services, for example `yarn dev --mode graphql` or `yarn dev --mode frontend,admin`. Prefer `--fast` for normal project work.
+
+When HTTPS is enabled, eddev creates a local certificate under `.eddev/certs/`. If macOS does not trust the certificate yet, the CLI prints Keychain instructions.
+
+## Generated Files [#generated-files]
+
+The CLI writes several generated files during `dev` and `build`.
+
+| Output                           | Source                                     | Purpose                                                                                             |
+| -------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `ed.dist.json`                   | Blocks, views, template parts              | PHP reads this manifest to register blocks, templates, and related theme metadata.                  |
+| `types.graphql.ts`               | WordPress schema and project GraphQL files | GraphQL operation, fragment, scalar, enum, and schema-derived TypeScript types.                     |
+| `types.views.ts`                 | `views/**/*.graphql` and view manifest     | The `ViewProps` map used by `defineView`.                                                           |
+| `types.blocks.ts`                | `blocks/**/*.graphql` and block manifest   | The `BlockProps` map used by `defineBlock`.                                                         |
+| `types.util.ts`                  | WordPress info, blocks, views              | Utility global types for post types, page templates, core blocks, block tags, flags, and post meta. |
+| `types.api.ts`                   | `server/routes/**/*`                       | RPC route and context types used by serverless functions and RPC hooks.                             |
+| `hooks/queries.ts`               | `queries/**/*.graphql`                     | Runtime query and mutation hooks.                                                                   |
+| `schema.json`                    | WordPress GraphQL schema                   | Local schema file for editor tooling.                                                               |
+| `.eddev/queries/**`              | Project GraphQL files                      | Optimized query text and fragments used by the PHP runtime.                                         |
+| `.eddev/dev*` and `.eddev/prod*` | Build codegen                              | Internal bootstrap files for SPA and serverless builds.                                             |
+
+Do not edit generated files directly. Change the source block, view, route, or GraphQL file instead.
+
+## GraphQL Codegen [#graphql-codegen]
+
+GraphQL codegen is part of `eddev dev` and `eddev build`; there is no separate public command for it.
+
+The generator:
+
+* loads the GraphQL endpoint from `DEBUG_GRAPHQL_URL`
+* passes `SITE_API_KEY` when origin protection is enabled
+* reads GraphQL files from `views/`, `blocks/`, `queries/`, and `queries/fragments/`
+* validates operations against the WordPress schema
+* writes TypeScript types and generated hooks
+* writes optimized query files into `.eddev/queries/`
+
+For file locations and caching comments such as `# ttl: 300` and `# nocache`, see [GraphQL](/docs/graphql).
+
+## `eddev build` [#eddev-build]
+
+`eddev build` builds the production frontend and admin bundles used by WordPress-hosted SPA mode. It does not build the serverless app.
+
+```bash
+yarn build
+```
+
+This production build:
+
+* loads project configuration and manifests
+* writes `ed.dist.json`
+* generates SPA bootstrap files
+* builds the admin bundle into `dist/cms/`
+* builds the frontend bundle into `dist/frontend/`
+* runs GraphQL generation and writes optimized query files
+
+Use this when deploying or pushing the theme to WordPress in SPA mode, including the WordPress admin/editor assets.
+
+## `eddev build --serverless` [#eddev-build---serverless]
+
+`eddev build --serverless` builds the production serverless app. Use it with `eddev preview` to test how the site will behave on production Vercel.
+
+```bash
+eddev build --serverless
+eddev preview
+```
+
+When Vercel runs the build, eddev takes the serverless path automatically because the `VERCEL` environment variable is set.
+
+Serverless builds require `SITE_URL` so eddev knows which WordPress origin to query. If origin protection is enabled, also set `SITE_API_KEY`. Before building, the CLI checks that it can access the origin.
+
+See [Serverless](/docs/serverless) for Vercel setup, `SITE_URL`, `SITE_API_KEY`, endpoint mappings, and cache behavior.
+
+## `eddev preview` [#eddev-preview]
+
+`eddev preview` runs the local production serverless build from `.output/server/index.mjs`. It is mainly useful after `eddev build --serverless`.
+
+```bash
+eddev preview
+eddev preview --port 8081
+```
+
+eddev uses the `SITE_URL` hostname when it ends in `.local`; otherwise it falls back to `127.0.0.1`. The command sets up local HTTPS with the same certificate helper used by `eddev dev`.
+
+<Callout type="warning">
+  The current `preview` command exposes `--host` as a flag rather than a value-taking option, so prefer the default host behavior and only override `--port`.
+</Callout>
+
+Run `eddev build --serverless` before using `eddev preview`; either command on its own is rarely useful for day-to-day work.
+
+## `eddev analyze` [#eddev-analyze]
+
+`eddev analyze` builds a frontend analysis bundle and writes a visualizer report under `dist/frontend-analysis/`.
+
+```bash
+eddev analyze
+```
+
+Use it when a client bundle looks too large or when you need to inspect what is included in the frontend build.
+
+## `eddev info` [#eddev-info]
+
+`eddev info` prints the discovered project information, block manifest, and view manifest.
+
+```bash
+eddev info
+eddev info --verbose
+```
+
+This is useful when WordPress is not registering an expected block or page template. It lets you check whether eddev can discover the source files before debugging PHP registration.
+
+## Environment Variables [#environment-variables]
+
+| Variable            | Used By                                                    | Notes                                                                                                                 |
+| ------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `SITE_URL`          | Project loading, serverless dev/build, preview             | WordPress origin URL. Required for serverless work.                                                                   |
+| `SITE_API_KEY`      | GraphQL, runtime query fetches, serverless origin requests | Optional unless the WordPress origin uses eddev Access Control.                                                       |
+| `DEBUG_GRAPHQL_URL` | GraphQL codegen                                            | WordPress/PHP normally writes this for local development. Refresh the WordPress admin if it is missing on a new site. |
+
+The CLI loads `.env` before it starts. Vercel project environment variables are used for production serverless builds.
+
+Variables prefixed with `ED_PUBLIC_` are injected into client and server bundles. Variables prefixed with `ED_` are injected only into non-client bundles.

package/skills/eddev/docs/devtool/overlay.mdx

@@ -0,0 +1,5 @@
+# Dev Overlay (/docs/devtool/overlay)
+
+**Use the in-browser development overlay while working on eddev sites.**
+
+TODO: Info about the dev overlay