synthesisui 0.1.14 → 0.1.16

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,13 +57,29 @@ 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`;
         await writeFile(join(slugDir, "rules.md"), body, "utf8");
     }
+    // 5c. structured philosophy (personal DS) → philosophy.md at the slug root.
+    //     Narrative guidance (mission, principles, voice, motion doctrine…); the
+    //     GUIDE points the agent here right after rules.md.
+    const philosophy = payload.document.philosophy;
+    const sections = philosophy?.sections ?? [];
+    if (sections.length > 0 || philosophy?.context) {
+        const parts = [`# ${payload.name} - Philosophy`, ""];
+        parts.push("> The voice and principles behind this system. Read after rules.md;", "> let it shape every screen. Managed by synthesisui (edit in the studio).", "");
+        if (philosophy?.context) {
+            parts.push("## What this product is", "", philosophy.context, "");
+        }
+        for (const s of sections) {
+            parts.push(`## ${s.title}`, "", s.body, "");
+        }
+        await writeFile(join(slugDir, "philosophy.md"), `${parts.join("\n")}\n`, "utf8");
+    }
     // 6. discovery by the agent
     const claudeMd = await syncClaudeMd(projectRoot);
     // outcome line
@@ -72,7 +88,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)`);
@@ -89,6 +105,9 @@ export async function add(slug, opts) {
     if (rules.length > 0) {
         console.log(`  rules.md → ${rules.length} rule(s) (read these first)`);
     }
+    if (sections.length > 0 || philosophy?.context) {
+        console.log(`  philosophy.md → ${sections.length} section(s) (read after rules)`);
+    }
     console.log(`  CLAUDE.md ${claudeMd.created ? "created" : "updated"} (${claudeMd.count} system(s) installed)`);
     console.log("");
     console.log("Next steps:");

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

@@ -1,7 +1,11 @@
 import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
+import { add } from "./add.js";
 /**
- * Writes `_synthesisui/config.json` — where `synthesisui page` materializes
- * pages and which framework to target. Committable; safe to re-run.
+ * Bootstraps a project for SynthesisUI: writes `_synthesisui/config.json`
+ * (where `page` materializes pages, where components live, which framework to
+ * target) and - with `--ds <slug>` - immediately brings that system in, so the
+ * project lands with tokens, philosophy, rules and a CLAUDE.md in one step.
+ * Committable; safe to re-run.
  */
 export async function init(opts) {
     const root = opts.dir ?? process.cwd();
@@ -9,13 +13,22 @@ export async function init(opts) {
     const config = {
         target,
         pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
+        componentsDir: opts.componentsDir ?? DEFAULT_CONFIG.componentsDir,
     };
     await writeProjectConfig(root, config);
     console.log("✓ wrote _synthesisui/config.json");
-    console.log(`  target:   ${config.target}`);
-    console.log(`  pagesDir: ${config.pagesDir}`);
+    console.log(`  target:        ${config.target}`);
+    console.log(`  pagesDir:      ${config.pagesDir}`);
+    console.log(`  componentsDir: ${config.componentsDir}`);
+    // --ds bootstraps the project with a system in one step (tokens + philosophy
+    // + rules + CLAUDE.md all arrive via `add`).
+    if (opts.ds) {
+        console.log("");
+        await add(opts.ds, { registry: opts.registry, dir: root });
+        return;
+    }
     console.log("");
     console.log("Next steps:");
-    console.log("  • synthesisui add <slug>            bring a design system in");
+    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

@@ -4,9 +4,10 @@ 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 a deterministic file, we write it, and
- * the agent refines it in place. The page uses the DS's `.ds-*` classes +
- * inline token vars, so it re-vests once `tokens.css` is imported.
+ * 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);
@@ -17,16 +18,25 @@ export async function page(slug, template, opts) {
         : config.target;
     console.log(`→ generating "${template}" from "${slug}" (${target}) …`);
     const generated = await fetchPage(base, slug, template, target, opts.version);
-    // --out wins; otherwise <pagesDir>/<filename> (e.g. app/dashboard.tsx).
-    const relPath = opts.out ?? join(config.pagesDir, generated.filename);
-    const outPath = join(root, relPath);
-    await mkdir(dirname(outPath), { recursive: true });
-    await writeFile(outPath, generated.code, "utf8");
-    console.log(`✓ wrote ${relPath}  (${slug} v${generated.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-* classes (stays on-system)`);
+    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
@@ -39,6 +39,7 @@ export async function writeToken(token, registry) {
 export const DEFAULT_CONFIG = {
     target: "next",
     pagesDir: "app",
+    componentsDir: "components",
 };
 const projectConfigPath = (root) => join(root, "_synthesisui", "config.json");
 /** Reads the project config, falling back to defaults when absent/invalid. */
@@ -51,6 +52,9 @@ export async function readProjectConfig(root) {
             pagesDir: typeof parsed.pagesDir === "string" && parsed.pagesDir
                 ? parsed.pagesDir
                 : DEFAULT_CONFIG.pagesDir,
+            componentsDir: typeof parsed.componentsDir === "string" && parsed.componentsDir
+                ? parsed.componentsDir
+                : DEFAULT_CONFIG.componentsDir,
         };
     }
     catch {

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,7 +94,7 @@ 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)
@@ -109,32 +109,42 @@ This system ships whole-page templates: ${layoutNames.map((n) => `\`${n}\``).joi
 
 Materialize one as a real file:
 \`\`\`bash
-synthesisui page ${slug} ${layoutNames[0]}                 # Next .tsx (default)
-synthesisui page ${slug} ${layoutNames[0]} --target general  # plain HTML
+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** using this DS's \`.ds-*\` classes + inline token vars. **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-*\` classes so it stays on-system. Run \`synthesisui init\` once
-to set the target (next/general) and the output folder.
+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
+    const philosophy = payload.document.philosophy;
+    const hasPhilosophy = (philosophy?.sections?.length ?? 0) > 0 || !!philosophy?.context;
+    const readFirst = [
+        hasRules
+            ? `**Read \`_synthesisui/ds/${slug}/rules.md\` FIRST and obey it above everything else** - it carries this system's accumulated, project-specific rules; on any conflict they win.`
+            : "",
+        hasPhilosophy
+            ? `**Then read \`_synthesisui/ds/${slug}/philosophy.md\`** - the mission, principles, voice and motion doctrine. Let it shape every screen you build.`
+            : "",
+    ].filter(Boolean);
+    const rulesNote = readFirst.length > 0
         ? `
-## Rules — highest authority
+## Read first - 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
-generic guidance below.
+${readFirst.map((l) => `- ${l}`).join("\n")}
 
 ---
 `
         : "";
     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}
@@ -161,7 +171,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.
@@ -189,16 +199,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)" }}>
 \`\`\`
 
@@ -206,16 +216,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
@@ -223,15 +233,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">
@@ -251,27 +261,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.
 
 ---
@@ -282,11 +292,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.`
         : ""}
@@ -299,7 +309,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.
@@ -319,10 +329,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

@@ -7,11 +7,11 @@ 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 init [options]               write _synthesisui/config.json (target + pages dir)
+  synthesisui init [options]               write _synthesisui/config.json (target, dirs); --ds to bring one in
   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
@@ -22,15 +22,18 @@ Options:
   --registry <url>   registry URL (or env SYNTHESISUI_REGISTRY_URL)
   --dir <path>       consumer project root (default: current directory)
   --version <n>      install a specific version (default: latest)
-  --ds <slug>        target design system for generate (default: the installed one)
+  --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
   --target <t>       page/init target: next | general (default: next)
+  --pages-dir <dir>  init: folder for generated pages (default: app)
+  --components-dir <dir>  init: folder where components live (default: components)
   --out <path>       output path for the generated page (default: <pagesDir>/<file>)
   -h, --help         this help
 
 Examples:
   synthesisui login
   synthesisui init --target next
+  synthesisui init --target next --ds halogen   bootstrap + bring a system in
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3
@@ -81,7 +84,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;
             }
@@ -89,7 +92,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;
                 }
@@ -102,14 +105,19 @@ async function main() {
             break;
         case "init": {
             const target = typeof flags.target === "string" ? flags.target : undefined;
-            await init({ dir, target });
+            const pagesDir = typeof flags["pages-dir"] === "string" ? flags["pages-dir"] : undefined;
+            const componentsDir = typeof flags["components-dir"] === "string"
+                ? flags["components-dir"]
+                : undefined;
+            const ds = typeof flags.ds === "string" ? flags.ds : undefined;
+            await init({ dir, registry, target, pagesDir, componentsDir, ds });
             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>`");
+                console.error("error: provide slug and template - `synthesisui page <slug> <template>`");
                 process.exitCode = 1;
                 return;
             }
@@ -117,7 +125,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;
                 }
@@ -130,7 +138,7 @@ async function main() {
         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;
             }
@@ -140,7 +148,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/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.14",
+  "version": "0.1.16",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {