synthesisui 0.1.13 → 0.1.15

package/dist/claude-md.js

@@ -21,7 +21,7 @@ async function readInstalled(projectRoot) {
             locks.push({ slug: lock.slug, name: lock.name, version: lock.version });
         }
         catch {
-            // folder without a valid .lock — ignore
+            // folder without a valid .lock - ignore
         }
     }
     return locks;
@@ -31,7 +31,7 @@ function renderRegion(installed) {
         return `${START}\n${END}`;
     }
     const lines = installed
-        .map((ds) => `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) — guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``)
+        .map((ds) => `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``)
         .join("\n");
     const body = `## Design Systems (via SynthesisUI)
 
@@ -39,12 +39,12 @@ This project uses design system(s) brought in by the \`synthesisui\` CLI. **When
 components, read the system's GUIDE.md and follow it:** use only semantic tokens
 (\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), scope the UI with \`data-ds="<slug>"\`,
 and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale. **To review a
-component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) — do not
+component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
 apply it to real production pages unless asked.**
 
 ${lines}
 
-_Block managed by the CLI — do not edit by hand; run \`synthesisui add <slug>\` to update._`;
+_Block managed by the CLI - do not edit by hand; run \`synthesisui add <slug>\` to update._`;
     return `${START}\n${body}\n${END}`;
 }
 /**

package/dist/commands/add.js

@@ -41,7 +41,7 @@ export async function add(slug, opts) {
     //    so the consumer's @import path never changes across updates
     const cssArtifacts = Object.keys(payload.artifacts).filter((f) => f.endsWith(".css"));
     for (const filename of cssArtifacts) {
-        await writeFile(join(slugDir, filename), `/* Active version (v${payload.version}). Managed by synthesisui — do not edit. */\n` +
+        await writeFile(join(slugDir, filename), `/* Active version (v${payload.version}). Managed by synthesisui - do not edit. */\n` +
             `@import "./v${payload.version}/${filename}";\n`, "utf8");
     }
     // 5. root pointer
@@ -57,8 +57,8 @@ export async function add(slug, opts) {
     //     highest authority; the GUIDE tells the agent to read it first)
     const rules = payload.rules ?? [];
     if (rules.length > 0) {
-        const body = `# ${payload.name} — Rules\n\n` +
-            "> Accumulated rules for this design system. **Max authority — follow these first.**\n" +
+        const body = `# ${payload.name} - Rules\n\n` +
+            "> Accumulated rules for this design system. **Max authority - follow these first.**\n" +
             `> Managed by synthesisui (edit in the studio). ${rules.length} rule(s).\n\n${rules
                 .map((r) => `- ${r}`)
                 .join("\n")}\n`;
@@ -72,7 +72,7 @@ export async function add(slug, opts) {
         console.log(`✓ ${payload.name} v${v} installed → _synthesisui/ds/${payload.slug}/`);
     }
     else if (prev.version === v) {
-        console.log(`✓ ${payload.name} v${v} already installed${opts.version == null ? " (latest)" : ""} — refreshed`);
+        console.log(`✓ ${payload.name} v${v} already installed${opts.version == null ? " (latest)" : ""} - refreshed`);
     }
     else if (v > prev.version) {
         console.log(`↑ ${payload.name} v${prev.version} → v${v} (kept v${prev.version}/ for rollback)`);

package/dist/commands/advise.js

@@ -4,7 +4,7 @@ import { buildRepoContext } from "../repo-context.js";
 /**
  * Asks the hosted advisor for engagement-pattern proposals, grounded in THIS
  * project (the CLI gathers a compact repo summary) + the value proposition you
- * pass. The advisor proposes only — it changes nothing in your project.
+ * pass. The advisor proposes only - it changes nothing in your project.
  */
 export async function advise(valueProp, opts) {
     const base = resolveRegistry(opts.registry);
@@ -26,6 +26,6 @@ export async function advise(valueProp, opts) {
         }
         console.log("");
     });
-    console.log(`(${res.usage.inputTokens} in / ${res.usage.outputTokens} out tokens — ` +
+    console.log(`(${res.usage.inputTokens} in / ${res.usage.outputTokens} out tokens - ` +
         `proposals only; nothing in your project was changed)`);
 }

package/dist/commands/generate.js

@@ -49,5 +49,5 @@ export async function generate(description, opts) {
     console.log("Use it:");
     console.log(`  • @import "_synthesisui/ds/${slug}/generated/${res.name}.css" in your CSS`);
     console.log(`  • <div data-ds="${slug}"><div class="ds-${res.name}">…</div></div>`);
-    console.log(`  (${res.usage.inputTokens} in / ${res.usage.outputTokens} out tokens — recipe is additive; nothing else changed)`);
+    console.log(`  (${res.usage.inputTokens} in / ${res.usage.outputTokens} out tokens - recipe is additive; nothing else changed)`);
 }

package/dist/commands/init.js

@@ -0,0 +1,21 @@
+import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
+/**
+ * Writes `_synthesisui/config.json` - where `synthesisui page` materializes
+ * pages and which framework to target. Committable; safe to re-run.
+ */
+export async function init(opts) {
+    const root = opts.dir ?? process.cwd();
+    const target = opts.target === "general" ? "general" : "next";
+    const config = {
+        target,
+        pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
+    };
+    await writeProjectConfig(root, config);
+    console.log("✓ wrote _synthesisui/config.json");
+    console.log(`  target:   ${config.target}`);
+    console.log(`  pagesDir: ${config.pagesDir}`);
+    console.log("");
+    console.log("Next steps:");
+    console.log("  • synthesisui add <slug>            bring a design system in");
+    console.log("  • synthesisui page <slug> <template>  materialize a full page");
+}

package/dist/commands/login.js

@@ -20,7 +20,7 @@ function openBrowser(url) {
         child.unref();
     }
     catch {
-        // no browser available — the user opens it manually
+        // no browser available - the user opens it manually
     }
 }
 /** Device authorization (RFC 8628): opens the browser, waits for approval. */

package/dist/commands/page.js

@@ -0,0 +1,42 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readProjectConfig, resolveRegistry } from "../config.js";
+import { fetchPage } from "../registry.js";
+/**
+ * Materializes a whole page from a DS template into the project (hybrid
+ * codegen-first): the server codegens deterministic files, we write them, and
+ * the agent refines them in place. The page uses the DS's `.ds-*` classes +
+ * path classes; the co-located CSS (Next target) carries the responsive media
+ * queries + the CSS-only hamburger, so it re-vests once `tokens.css` is in.
+ */
+export async function page(slug, template, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    const config = await readProjectConfig(root);
+    const target = opts.target === "general" || opts.target === "next"
+        ? opts.target
+        : config.target;
+    console.log(`→ generating "${template}" from "${slug}" (${target}) …`);
+    const generated = await fetchPage(base, slug, template, target, opts.version);
+    // --out targets the page (1st file); sibling files (e.g. the CSS) land in the
+    // same directory. Without --out, everything goes under <pagesDir>.
+    const [pageFile, ...siblings] = generated.files;
+    const pageRel = opts.out ?? join(config.pagesDir, pageFile.filename);
+    const pageDir = dirname(join(root, pageRel));
+    await mkdir(pageDir, { recursive: true });
+    await writeFile(join(root, pageRel), pageFile.code, "utf8");
+    console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
+    for (const f of siblings) {
+        const rel = opts.out
+            ? join(dirname(pageRel), f.filename)
+            : join(config.pagesDir, f.filename);
+        await writeFile(join(root, rel), f.code, "utf8");
+        console.log(`✓ wrote ${rel}`);
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
+    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    console.log("  • refine the file: wire real data, split into components, swap placeholders");
+    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
+}

package/dist/config.js

@@ -11,7 +11,7 @@ export function resolveRegistry(flag) {
     const base = flag || process.env.SYNTHESISUI_REGISTRY_URL || DEFAULT_REGISTRY;
     return base.replace(/\/+$/, ""); // no trailing slash
 }
-/** Where the device-flow token lives — per machine, in the home dir. */
+/** Where the device-flow token lives - per machine, in the home dir. */
 export const credentialsPath = join(homedir(), ".synthesisui", "credentials.json");
 /**
  * Reads the saved token, if any. Optional for now (open gate); the device-flow
@@ -35,3 +35,31 @@ export async function writeToken(token, registry) {
         mode: 0o600,
     });
 }
+/** Project-level config (committed): `<root>/_synthesisui/config.json`. */
+export const DEFAULT_CONFIG = {
+    target: "next",
+    pagesDir: "app",
+};
+const projectConfigPath = (root) => join(root, "_synthesisui", "config.json");
+/** Reads the project config, falling back to defaults when absent/invalid. */
+export async function readProjectConfig(root) {
+    try {
+        const raw = await readFile(projectConfigPath(root), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            target: parsed.target === "general" ? "general" : "next",
+            pagesDir: typeof parsed.pagesDir === "string" && parsed.pagesDir
+                ? parsed.pagesDir
+                : DEFAULT_CONFIG.pagesDir,
+        };
+    }
+    catch {
+        return DEFAULT_CONFIG;
+    }
+}
+/** Writes the project config (committable, plain JSON). */
+export async function writeProjectConfig(root, config) {
+    const path = projectConfigPath(root);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

package/dist/guide.js

@@ -1,7 +1,7 @@
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 const list = (items) => items.length ? items.map((i) => `\`${i}\``).join(", ") : "_(none)_";
 const dataAttrs = (variants) => Object.entries(variants).map(([axis, opts]) => `data-${kebab(axis)}="${Object.keys(opts).join("|")}"`);
-// Famílias genéricas do CSS — fallbacks, não webfonts a carregar.
+// Famílias genéricas do CSS - fallbacks, não webfonts a carregar.
 const GENERIC_FAMILIES = new Set([
     "sans-serif",
     "serif",
@@ -35,7 +35,7 @@ function customFontFamilies(families) {
 function componentEntry(cname, recipe) {
     const cls = `.ds-${kebab(cname)}`;
     const axes = dataAttrs(recipe.variants).map((a) => `\`${a}\``);
-    const variantsText = axes.length ? ` — variants: ${axes.join(", ")}` : "";
+    const variantsText = axes.length ? ` - variants: ${axes.join(", ")}` : "";
     const states = Object.keys(recipe.states ?? {});
     const statesText = states.length ? `\n  states: ${list(states)}` : "";
     const partEntries = Object.entries(recipe.parts ?? {});
@@ -51,7 +51,7 @@ function componentEntry(cname, recipe) {
     return `- **${cname}** (\`${cls}\`)${variantsText}\n  ${recipe.description}${partsText}${statesText}`;
 }
 /**
- * Builds GUIDE.md — instructions *for the agent* on how to build components
+ * Builds GUIDE.md - instructions *for the agent* on how to build components
  * that follow the design system. This is the piece that makes "I create the
  * components with claude-code" work: the tokens alone are not enough, the agent
  * needs the rules and the real vocabulary (semantic token names and recipes).
@@ -71,17 +71,17 @@ export function buildGuide(payload) {
         ? `
 ## Fonts
 
-This system's type relies on ${list(fontFamilies)} — **the DS ships token names, not the
+This system's type relies on ${list(fontFamilies)} - **the DS ships token names, not the
 fonts themselves.** If you don't load them they fall back to a generic family and the system loses
 its typographic identity. Load them once (any one approach):
 
-- **Google Fonts** — drop in your \`<head>\` (or root layout):
+- **Google Fonts** - drop in your \`<head>\` (or root layout):
   \`\`\`html
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link rel="stylesheet" href="${fontsHref}" />
   \`\`\`
-- **Next.js** (\`next/font/google\`), **Fontsource**, or self-hosted \`@font-face\` work too — just
+- **Next.js** (\`next/font/google\`), **Fontsource**, or self-hosted \`@font-face\` work too - just
   register the families above. If a family isn't on Google Fonts, self-host it.
 
 ---
@@ -94,16 +94,38 @@ its typographic identity. Load them once (any one approach):
     const hasTailwind = "theme.css" in payload.artifacts;
     const hasParts = Object.values(components).some((r) => r.parts && Object.keys(r.parts).length > 0);
     const componentLines = Object.entries(components).map(([cname, recipe]) => componentEntry(cname, recipe));
-    // Engagement blocks (gamification library) — category apart from core components.
+    // Engagement blocks (gamification library) - category apart from core components.
     const blockEntries = Object.entries(doc.blocks ?? {});
     const blockLines = blockEntries.map(([bname, recipe]) => componentEntry(bname, recipe));
     const artifactList = Object.keys(payload.artifacts)
         .map((f) => `\`${f}\``)
         .join(", ");
+    const layoutNames = Object.keys(doc.layouts ?? {});
+    const pagesSection = layoutNames.length > 0
+        ? `
+## Full pages (templates)
+
+This system ships whole-page templates: ${layoutNames.map((n) => `\`${n}\``).join(", ")}.
+
+Materialize one as a real file:
+\`\`\`bash
+synthesisui page ${slug} ${layoutNames[0]}                 # Next .tsx + .css (default)
+synthesisui page ${slug} ${layoutNames[0]} --target general  # single self-contained HTML
+\`\`\`
+It writes a **deterministic scaffold**: the page uses this DS's \`.ds-*\` recipe classes + layout
+path-classes, paired with a co-located scoped CSS (Next target) that carries the **responsive** media
+queries and the **CSS-only hamburger** - so the page is mobile-ready out of the box. **Refine it in
+place** - wire real data, split into components, swap the chart/icon/media placeholders - but keep the
+\`data-ds="${slug}"\` wrapper and the \`.ds-*\` / layout classes so it stays on-system. Run
+\`synthesisui init\` once to set the target (next/general) and the output folder.
+
+---
+`
+        : "";
     const hasRules = (payload.rules?.length ?? 0) > 0;
     const rulesNote = hasRules
         ? `
-## Rules — highest authority
+## Rules - highest authority
 
 **Read \`_synthesisui/ds/${slug}/rules.md\` FIRST and obey it above everything else in this guide.**
 It carries this system's accumulated, project-specific rules; on any conflict they win over the
@@ -114,7 +136,7 @@ generic guidance below.
         : "";
     return `# Design System: ${name}
 
-> Generated by \`synthesisui add ${slug}\` (v${version}). **Do not edit by hand** —
+> Generated by \`synthesisui add ${slug}\` (v${version}). **Do not edit by hand** -
 > run \`synthesisui add ${slug}\` again to update.
 
 ${meta.tagline}
@@ -141,7 +163,7 @@ ${rulesNote}
    \`\`\`
    All \`--ds-*\` custom properties and \`.ds-*\` classes only apply inside that scope.
    Applying \`data-ds="${slug}"\` at the app root (e.g. \`<body>\` or the root layout)
-   is the simplest choice — the whole app then wears the system.
+   is the simplest choice - the whole app then wears the system.
 ${hasAlt
         ? `
 3. Light/dark: an ancestor with \`data-scheme="${altScheme}"\` switches the neutral roles to the opposite mode.
@@ -169,16 +191,16 @@ backed by the design system: \`bg-*\`/\`text-*\`/\`border-*\` (semantic colors),
             ? `, \`bg-series-*\`/\`text-series-*\`/\`fill-series-*\` (data-viz series)`
             : ""}.
 
-**Prefer these utilities for layout and new composition** — they are this project's idiom and read
+**Prefer these utilities for layout and new composition** - they are this project's idiom and read
 far better than inline \`style\`. Reach for inline \`var(--ds-*)\` only when no utility fits.
 
 \`\`\`tsx
-// ✅ preferred — Tailwind utilities backed by the DS
+// ✅ preferred - Tailwind utilities backed by the DS
 <main className="bg-canvas text-foreground p-2xl flex flex-col gap-md">
   <button className="ds-button" data-intent="primary">Save</button>
 </main>
 
-// ❌ avoid — inline styles with raw var() when a utility exists
+// ❌ avoid - inline styles with raw var() when a utility exists
 <main style={{ background: "var(--ds-color-semantic-canvas)", padding: "var(--ds-spacing-2xl)" }}>
 \`\`\`
 
@@ -186,16 +208,16 @@ far better than inline \`style\`. Reach for inline \`var(--ds-*)\` only when no
 `
         : ""}
 This is **v${version}**. The stable entrypoints at \`_synthesisui/ds/${slug}/\` (the
-\`tokens.css\`/\`theme.css\` re-exports, plus \`.lock\`) always point at the active version — import
-those, not the versioned ones. The pinned files for this version — ${artifactList},
-\`design-system.json\` (canonical source of truth), \`GUIDE.md\` (this file) — live in
+\`tokens.css\`/\`theme.css\` re-exports, plus \`.lock\`) always point at the active version - import
+those, not the versioned ones. The pinned files for this version - ${artifactList},
+\`design-system.json\` (canonical source of truth), \`GUIDE.md\` (this file) - live in
 \`_synthesisui/ds/${slug}/v${version}/\`.
 
 ---
-
+${pagesSection}
 ## Building with the system
 
-**This system is for building real product UI** — pages, layouts, dashboards, whole flows.
+**This system is for building real product UI** - pages, layouts, dashboards, whole flows.
 Compose the \`.ds-*\` recipes (and their parts) together with the DS-backed utilities to assemble
 actual screens. There is **no "samples only" rule**: build the real app. An
 \`app/synthesisui-samples/<component>/\` page is a fine *optional* scratch space to eyeball a single
@@ -203,15 +225,15 @@ component, but it is never required.
 
 ### Layout & composition
 The system defines the scale; these are sensible defaults for spending it:
-- **Page gutter / container padding:** a large spacing step — ${list(Object.keys(foundations.spacing).filter((k) => /xl/.test(k)))}.
+- **Page gutter / container padding:** a large spacing step - ${list(Object.keys(foundations.spacing).filter((k) => /xl/.test(k)))}.
 - **Section gaps:** \`lg\` (or the nearest large step). **Card/panel padding:** \`md\`.
 - **Field / tight gaps:** \`2xs\`/\`3xs\`.
-- The system imposes no content max-width — cap long-form/text columns yourself for readability.
+- The system imposes no content max-width - cap long-form/text columns yourself for readability.
 ${hasParts
         ? `
 ### Multi-part components
 Components that have **parts** compile to \`.ds-<name>-<part>\` classes you nest yourself; the exact
-part classes and their \`data-*\` are listed per component below. Example — a table:
+part classes and their \`data-*\` are listed per component below. Example - a table:
 \`\`\`tsx
 <table className="ds-table">
   <thead className="ds-table-head">
@@ -231,27 +253,27 @@ part classes and their \`data-*\` are listed per component below. Example — a
 `
         : ""}
 ### Overlays & portals
-Dialogs, menus and toasts are often rendered through a portal at the end of \`<body>\` — **outside**
+Dialogs, menus and toasts are often rendered through a portal at the end of \`<body>\` - **outside**
 your \`data-ds\` scope. Since \`.ds-*\`/\`--ds-*\` only resolve inside the scope, wrap any portalled UI
 in its own \`<div data-ds="${slug}"${hasAlt ? ` data-scheme="…"` : ""}>\`, or apply \`data-ds\` at the
 app root so everything (portals included) inherits it. Behavior (open/close, focus trap, positioning,
-keyboard) is yours to wire — the system ships the **looks**, not the JavaScript.
+keyboard) is yours to wire - the system ships the **looks**, not the JavaScript.
 
-### Interactive recipes — the behavior contract
+### Interactive recipes - the behavior contract
 Several recipes are **static surfaces**: they ship the styling for every state, but never any
 JavaScript. You own the interaction and drive each state by toggling the documented \`data-*\`
 attributes (listed per component below). The recipe restyles itself; you wire the logic.
 - **Open / close** (menu, select, modal, tooltip, popover): render the surface, then handle show/hide,
   outside-click, focus trap, positioning and \`Esc\` yourself (or with a headless lib).
 - **Selection / active** (tabs, sidebar, pagination): set \`data-active="true"\` on the chosen item from
-  your own state/router — the recipe lifts it onto a surface.
+  your own state/router - the recipe lifts it onto a surface.
 - **On / off** (switch): toggle \`data-state="on"\` on the track **and** its thumb together.
-- **Command bar / ⌘K** (if your system ships one): the recipe is only the styled input row — wire the
+- **Command bar / ⌘K** (if your system ships one): the recipe is only the styled input row - wire the
   shortcut, the palette list and filtering yourself.
 - **Select** (native vs custom): \`.ds-select\` strips native chrome (\`appearance:none\`). On a real
   \`<select>\`, wrap it and overlay your own chevron; on a custom trigger, nest \`.ds-select-chevron\`.
 
-Pair these with the right ARIA (\`aria-expanded\`, \`role="dialog"\`, \`aria-current\`, …) — the system
+Pair these with the right ARIA (\`aria-expanded\`, \`role="dialog"\`, \`aria-current\`, …) - the system
 styles it, you make it work.
 
 ---
@@ -262,11 +284,11 @@ ${hasTailwind
 - **Styling mechanism:** prefer Tailwind utilities backed by the DS (\`bg-primary\`, \`p-md\`,
   \`font-display\`, \`font-medium\`, …) for layout and new composition, and reuse the \`.ds-*\` recipes
   for components the DS already covers. Use inline \`style\` with \`var(--ds-*)\` only as a last resort.
-  The token names below are the source vocabulary — every utility derives from them.`
+  The token names below are the source vocabulary - every utility derives from them.`
         : ""}
 - **Always use semantic tokens**, never raw values nor primitives directly.
   Color: \`var(--ds-color-semantic-<role>)\`${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}. The roles are: ${list(semanticRoles)}.
-- Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly —
+- Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly -
   they feed the semantic roles.${seriesKeys.length > 0
         ? `\n- Data-viz → \`var(--ds-color-series-<n>)\`${hasTailwind ? " (utility: `bg-series-<n>`/`text-series-<n>`/`fill-series-<n>`)" : ""}: categorical chart/series colors, ${seriesKeys.length} of them (${list(seriesKeys)}). Use them in order for multi-series charts; they re-paint with the system.`
         : ""}
@@ -279,7 +301,7 @@ ${hasTailwind
 - Motion: durations \`--ds-motion-durations-<key>\` (${list(Object.keys(motion.durations))}) and
   easings \`--ds-motion-easings-<key>\` (${list(Object.keys(motion.easings))}). Use them on
   \`transition\`/\`animation\` (e.g. \`transition: color var(--ds-motion-durations-fast) var(--ds-motion-easings-standard)\`)
-  so timing stays on-brand. The DS ships timing tokens, **not** a runtime — for entrance/reveal/stagger
+  so timing stays on-brand. The DS ships timing tokens, **not** a runtime - for entrance/reveal/stagger
   pair them with a motion lib (e.g. \`motion\`/Framer) or CSS \`@keyframes\`.
 - When **creating a new component** the DS does not cover yet: compose it from these semantic
   tokens to inherit the system's identity; do not invent colors/measures outside the scale.
@@ -299,10 +321,10 @@ ${blockEntries.length
 
 ## Engagement blocks (optional)
 
-A small gamification library the AI advisor (\`synthesisui advise\`) can propose — same
+A small gamification library the AI advisor (\`synthesisui advise\`) can propose - same
 \`.ds-<name>\` recipe shape as the components above, token-only so they wear the system. Use them
 **only where they fit the product** (progress, retention, recognition); they're a library to compose
-from, not a default — and lean against over-gamifying a serious B2B product. Each is a \`.ds-<name>\`
+from, not a default - and lean against over-gamifying a serious B2B product. Each is a \`.ds-<name>\`
 class inside the \`[data-ds="${slug}"]\` scope; multi-part ones expose \`.ds-<name>-<part>\`.
 
 ${blockLines.join("\n\n")}

package/dist/index.js

@@ -2,17 +2,21 @@
 import { add } from "./commands/add.js";
 import { advise } from "./commands/advise.js";
 import { generate } from "./commands/generate.js";
+import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
+import { page } from "./commands/page.js";
 import { RegistryError } from "./registry.js";
-const HELP = `synthesisui — bring SynthesisUI design systems into your project
+const HELP = `synthesisui - bring SynthesisUI design systems into your project
 
 Usage:
-  synthesisui login [options]          connect the CLI to your account (device-flow)
-  synthesisui list [options]           list the published design systems
-  synthesisui add <slug> [options]     materialize a DS into _synthesisui/ds/<slug>/
-  synthesisui advise "<value prop>"    engagement-pattern proposals for this project (login required)
-  synthesisui generate "<desc>"        generate a token-only component recipe for your DS (login required)
+  synthesisui login [options]              connect the CLI to your account (device-flow)
+  synthesisui init [options]               write _synthesisui/config.json (target + pages dir)
+  synthesisui list [options]               list the published design systems
+  synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
+  synthesisui page <slug> <template>       materialize a whole page from a DS template
+  synthesisui advise "<value prop>"        engagement-pattern proposals for this project (login required)
+  synthesisui generate "<desc>"            generate a token-only component recipe for your DS (login required)
 
 Options:
   --registry <url>   registry URL (or env SYNTHESISUI_REGISTRY_URL)
@@ -20,14 +24,18 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        target design system for generate (default: the installed one)
   --name <name>      preferred component name for generate
+  --target <t>       page/init target: next | general (default: next)
+  --out <path>       output path for the generated page (default: <pagesDir>/<file>)
   -h, --help         this help
 
 Examples:
   synthesisui login
+  synthesisui init --target next
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3
-  synthesisui add halogen --registry http://localhost:3737
+  synthesisui page halogen dashboard-sidebar
+  synthesisui page halogen landing --out app/page.tsx
   synthesisui advise "habit-building app for tracking personal finances"
   synthesisui generate "an upgrade banner with a title, message and a primary CTA"
 `;
@@ -73,7 +81,7 @@ async function main() {
         case "add": {
             const slug = args[0];
             if (!slug) {
-                console.error("error: provide the slug — `synthesisui add <slug>`");
+                console.error("error: provide the slug - `synthesisui add <slug>`");
                 process.exitCode = 1;
                 return;
             }
@@ -81,7 +89,7 @@ async function main() {
             if (typeof flags.version === "string") {
                 version = Number.parseInt(flags.version.replace(/^v/i, ""), 10);
                 if (!Number.isInteger(version) || version < 1) {
-                    console.error(`error: invalid --version "${flags.version}" — use an integer ≥ 1`);
+                    console.error(`error: invalid --version "${flags.version}" - use an integer ≥ 1`);
                     process.exitCode = 1;
                     return;
                 }
@@ -92,10 +100,37 @@ async function main() {
         case "login":
             await login({ registry });
             break;
+        case "init": {
+            const target = typeof flags.target === "string" ? flags.target : undefined;
+            await init({ dir, target });
+            break;
+        }
+        case "page": {
+            const slug = args[0];
+            const template = args[1];
+            if (!slug || !template) {
+                console.error("error: provide slug and template - `synthesisui page <slug> <template>`");
+                process.exitCode = 1;
+                return;
+            }
+            let version;
+            if (typeof flags.version === "string") {
+                version = Number.parseInt(flags.version.replace(/^v/i, ""), 10);
+                if (!Number.isInteger(version) || version < 1) {
+                    console.error(`error: invalid --version "${flags.version}" - use an integer ≥ 1`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            const target = typeof flags.target === "string" ? flags.target : undefined;
+            const out = typeof flags.out === "string" ? flags.out : undefined;
+            await page(slug, template, { registry, dir, out, target, version });
+            break;
+        }
         case "advise": {
             const valueProp = args.join(" ").trim();
             if (!valueProp) {
-                console.error('error: describe your product — `synthesisui advise "<value proposition>"`');
+                console.error('error: describe your product - `synthesisui advise "<value proposition>"`');
                 process.exitCode = 1;
                 return;
             }
@@ -105,7 +140,7 @@ async function main() {
         case "generate": {
             const description = args.join(" ").trim();
             if (!description) {
-                console.error('error: describe the component — `synthesisui generate "<description>"`');
+                console.error('error: describe the component - `synthesisui generate "<description>"`');
                 process.exitCode = 1;
                 return;
             }

package/dist/registry.js

@@ -42,6 +42,27 @@ export async function fetchDesignSystem(base, slug, version) {
     }
     return (await res.json());
 }
+/**
+ * Fetches a whole page generated from a DS template (`?page=&target=`). The
+ * server codegens it from `document.layouts[<template>]`; the CLI just writes it.
+ */
+export async function fetchPage(base, slug, template, target, version) {
+    const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+    url.searchParams.set("page", template);
+    url.searchParams.set("target", target);
+    if (version != null)
+        url.searchParams.set("version", String(version));
+    const res = await request(url.toString());
+    if (res.status === 404) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ??
+            `No template "${template}" in "${slug}". Run \`synthesisui list\` and check the DS templates.`);
+    }
+    if (!res.ok) {
+        throw new RegistryError(`Registry responded ${res.status} while generating "${template}".`);
+    }
+    return (await res.json());
+}
 /**
  * Calls the hosted advisor (`POST /api/ai/advisor`). Gated + metered server-side:
  * 401 = not logged in, 429 = daily quota reached. Sends the Bearer token if present.

package/dist/repo-context.js

@@ -1,7 +1,7 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 /**
- * Monta um resumo COMPACTO e aterrado do projeto pro advisor — barato em tokens
+ * Monta um resumo COMPACTO e aterrado do projeto pro advisor - barato em tokens
  * e suficiente pra propostas específicas: stack (package.json), forma do repo
  * (árvore nível 1), DS SynthesisUI instalado(s) e o começo do README. Sem dump
  * de código (custo/ruído): o advisor propõe padrões, não lê implementação.
@@ -52,7 +52,7 @@ async function installedDesignSystems(root) {
         }
     }
     catch {
-        // nenhum DS instalado — tudo bem
+        // nenhum DS instalado - tudo bem
     }
     return out;
 }
@@ -72,7 +72,7 @@ export async function buildRepoContext(root) {
     const pkg = await readJson(join(root, "package.json"));
     const parts = [];
     if (pkg) {
-        parts.push(`Projeto: ${pkg.name ?? "(sem nome)"}${pkg.description ? ` — ${pkg.description}` : ""}`);
+        parts.push(`Projeto: ${pkg.name ?? "(sem nome)"}${pkg.description ? ` - ${pkg.description}` : ""}`);
         const deps = [
             ...Object.keys(pkg.dependencies ?? {}),
             ...Object.keys(pkg.devDependencies ?? {}),

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * Minimal mirror of the registry contract — the CLI is standalone and does NOT
+ * Minimal mirror of the registry contract - the CLI is standalone and does NOT
  * import `@synthesisui-hub/ds-contracts` (it only consumes the endpoint JSON).
  * We type only what the CLI reads to generate GUIDE.md and the .lock.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {