dslinter 0.1.4 → 0.1.13

package/CHANGELOG.md

@@ -1,14 +1,93 @@
 # Changelog
 
+## v0.1.13
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.12...v0.1.13)
+
+### 🏡 Chore
+
+- **release:** V0.1.12 ([7c2190a](https://github.com/jrmybtlr/DSLinter/commit/7c2190a))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.1.12
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.10...v0.1.12)
+
+### 🏡 Chore
+
+- **release:** V0.1.11 ([bc2d134](https://github.com/jrmybtlr/DSLinter/commit/bc2d134))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.1.11
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.10...v0.1.11)
+
+## v0.1.10
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.8...v0.1.10)
+
+### 🏡 Chore
+
+- **release:** V0.1.9 ([a54ea04](https://github.com/jrmybtlr/DSLinter/commit/a54ea04))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.1.8
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.7...v0.1.8)
+
+### 🚀 Enhancements
+
+- Auto-scaffold dslint config and add scan scope options ([572e97b](https://github.com/jrmybtlr/DSLinter/commit/572e97b))
+
+### 🩹 Fixes
+
+- Warn when css_entrypoint path is missing ([88a5038](https://github.com/jrmybtlr/DSLinter/commit/88a5038))
+- Don't scope CSS discovery to include_dirs ([7e6df94](https://github.com/jrmybtlr/DSLinter/commit/7e6df94))
+
+## v0.1.7
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.5...v0.1.7)
+
+### 🏡 Chore
+
+- **release:** V0.1.6 ([1463fbc](https://github.com/jrmybtlr/DSLinter/commit/1463fbc))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.1.6
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.5...v0.1.6)
+
+## v0.1.5
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.4...v0.1.5)
+
 ## v0.1.4
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.3...v0.1.4)
 
 ## Unreleased
 
+### 🚀 Enhancements
+
+- **`dslinter/vite` plugin** — virtual `playground-modules` map keyed by `@dslint-scan/<rel_path>`; scanner proxy, react dedupe, `optimizeDeps.exclude`, and `server.fs.allow` for the scan root.
+- **`DashboardLayout autoPlayground`** and **`usePlaygroundFromReport`** — zero-config live previews without `buildRegistry.ts`.
+- **`npx dslinter`** auto-merges the plugin into consumer Vite via `vite/consumer.config.mjs` when a host app is detected.
+
 ### 🩹 Fixes
 
-- Remove `@/` path aliases from published `src/` so host apps with their own `@/*` Vite alias (Laravel/Inertia, etc.) no longer resolve dslinter UI imports to the wrong tree. Consumers need only the official vite snippet (proxy, react dedupe, `optimizeDeps.exclude`).
+- Remove `@/` path aliases from published `src/` so host apps with their own `@/*` Vite alias (Laravel/Inertia, etc.) no longer resolve dslinter UI imports to the wrong tree.
 
 ## v0.1.3
 

package/README.md

@@ -48,26 +48,48 @@ The crates.io crate **`dslint`** is a **different project**. Use **`cargo instal
 Typical usage:
 
 ```bash
-npx dslinter init                         # scaffold src/playground/buildRegistry.ts
+npx dslinter init                         # scaffold .dslint.json + src/playground/buildRegistry.ts
 npx dslinter                              # dev (watch + dashboard)
 npx dslinter --report /path/to/repo --json
 npx dslinter --report --output public/dslint-report.json
 npx dslinter --watch --output public/dslint-report.json
 ```
 
-Set `DSLINT_SERVE_PORT` to override the default scanner port (`7878`). Your Vite config should proxy `/dslint-report.json` and `/events` to that port in `serve` mode. Merge `templates/vite.dslinter.snippet.ts` (copied by `npx dslinter init`) or see repo `demo/vite.config.ts` for a linked-workspace example.
+Set `DSLINT_SERVE_PORT` to override the default scanner port (`7878`).
+On first local run, `npx dslinter` scaffolds `.dslint.json` automatically if missing.
 
-### Consumer Vite (Laravel, Inertia, existing `@/*` aliases)
+### Zero-config live previews (recommended)
+
+**`npx dslinter .`** from your project root auto-merges the dslinter Vite plugin (playground module glob, scanner proxy, react dedupe). In your app:
+
+```tsx
+import { DashboardLayout, useWorkspaceReport } from "dslinter";
+
+const dslinterReport = useWorkspaceReport({
+  reportUrl: "/dslint-report.json",
+  watchUrl: "/events",
+});
+
+<DashboardLayout autoPlayground dslinterReport={dslinterReport} tokenCatalog={...} />;
+```
+
+No `buildRegistry.ts` scaffold required. Works with Laravel/Inertia (`resources/js/Components/...`) and existing `@/*` → `resources/js/*` aliases.
+
+**Direct `vite --mode serve`:** add one line to `vite.config.ts`:
 
-Published `dslinter` source uses **relative imports only** — no `@/components/...` paths inside `node_modules/dslinter/src`. Your app's `@/*` alias (for example Laravel `@/*` → `resources/js/*`) will not hijack dslinter's internal UI imports.
+```ts
+import dslinter from "dslinter/vite";
 
-After `npx dslinter init --laravel`, merge only the official snippet into `vite.config.ts`:
+export default defineConfig({
+  plugins: [dslinter(), /* your plugins */],
+});
+```
 
-- `resolve.dedupe`: `["react", "react-dom"]`
-- `optimizeDeps.exclude`: `["dslinter"]` (source-first package; transpile from `node_modules`)
-- `server.proxy` for `/dslint-report.json` and `/events` → `DSLINT_SERVE_PORT`
+The plugin sets `DSLINT_SCAN_ROOT` from the environment (set by `npx dslinter`) or defaults to `process.cwd()`.
+
+### Consumer Vite (Laravel, Inertia, existing `@/*` aliases)
 
-You do **not** need alias overrides such as `@/components` → `node_modules/dslinter/src/components`.
+Published `dslinter` source uses **relative imports only** — your app's `@/*` alias does not hijack dslinter internal UI. You do **not** need `@/components` → `node_modules/dslinter` alias overrides.
 
 ## Styles (Tailwind v4)
 
@@ -84,44 +106,33 @@ You do **not** need alias overrides such as `@/components` → `node_modules/dsl
    @import "dslinter/theme.css";
    ```
 
-## Live component previews (consumer Vite apps)
+## Live component previews (advanced / custom glob)
 
-If the dashboard shows **“Scan snapshot — no live preview”** for a component that appears in the catalog, the scanner found the file but Vite did not load it. Wire previews in three steps:
+Use **`autoPlayground`** (above) for zero-config previews. Optionally scaffold a narrower glob for faster dev or custom controls:
 
-1. **Scaffold** (optional): `npx dslinter init` → `src/playground/buildRegistry.ts`; for Inertia/Laravel (`resources/js/…`) use `npx dslinter init --laravel`
-2. **Glob** must cover nested paths, e.g. `import.meta.glob("../components/**/*.{tsx,jsx}", { eager: true })`
-3. **App**: pass `playgroundEntries` and `playgroundJoinSkips` from the registry into `DashboardLayout`
+- `npx dslinter init` → `src/playground/buildRegistry.ts`
+- `npx dslinter init --laravel` → `resources/js/playground/buildRegistry.ts`
+
+`npx dslinter init` now also scaffolds a starter `.dslint.json` (unless one already exists), including:
+- `include_dirs` (directory scope for discovery)
+- `ignore_globs` (file/directory ignores)
+- `css_entrypoints` (main CSS entry files for token analysis)
 
 ```tsx
 import { useMemo } from "react";
 import { DashboardLayout, useWorkspaceReport } from "dslinter";
-import {
-  buildPlaygroundEntries,
-  getPlaygroundJoinSkips,
-} from "./playground/buildRegistry";
-
-const dslinterReport = useWorkspaceReport({
-  reportUrl: "/dslint-report.json",
-  watchUrl: "/events",
-});
+import { buildPlaygroundEntries } from "./playground/buildRegistry";
 
+const dslinterReport = useWorkspaceReport({ reportUrl: "/dslint-report.json", watchUrl: "/events" });
 const playgroundEntries = useMemo(
   () => buildPlaygroundEntries(dslinterReport.report),
   [dslinterReport.report],
 );
-const playgroundJoinSkips = useMemo(
-  () => getPlaygroundJoinSkips(dslinterReport.report),
-  [dslinterReport.report],
-);
 
-<DashboardLayout
-  playgroundEntries={playgroundEntries}
-  playgroundJoinSkips={playgroundJoinSkips}
-  dslinterReport={dslinterReport}
-/>;
+<DashboardLayout playgroundEntries={playgroundEntries} dslinterReport={dslinterReport} />;
 ```
 
-In dev, skipped joins are also logged to the console. The inspect pane shows the expected Vite glob key when a preview fails.
+Or use `usePlaygroundFromReport(report)` with `dslinter/playground-modules` when the Vite plugin is active.
 
 Run the scanner from the **project root** (`npx dslinter .`) so `playgrounds[].rel_path` matches your repo layout.
 
@@ -129,8 +140,8 @@ Run the scanner from the **project root** (`npx dslinter .`) so `playgrounds[].r
 
 `DashboardLayout` needs:
 
-- **`playgroundEntries`** — from the report’s `playgrounds` list joined to your React modules (see repo `demo/src/playground/buildRegistry.ts`).
-- **`playgroundJoinSkips`** (optional) — from `buildPlaygroundEntriesFromReportWithSkips` for richer inspect-pane hints.
+- **`autoPlayground`** (recommended) — or **`playgroundEntries`** from a custom registry / `usePlaygroundFromReport`.
+- **`playgroundJoinSkips`** (optional) — auto-filled when using `autoPlayground`.
 - **`tokenCatalog`** — token wall data (see `demo/src/tokenCatalog.ts`).
 - **`dslinterReport`** — from `useWorkspaceReport({ reportUrl: "/dslint-report.json", ... })`.
 

package/bin/lib/project-root.mjs

@@ -27,12 +27,26 @@ function maxMtimeInDir(dir, latest = 0) {
   return latest;
 }
 
+/**
+ * @param {string} [root]
+ * @returns {boolean} true when embed SPA sources exist (monorepo / git checkout).
+ */
+export function hasEmbedDashboard(root = packageRoot) {
+  return existsSync(join(root, "index.html"));
+}
+
 /**
  * Rebuild `dashboard-dist/` when embed sources are newer than the bundle (or dist is missing).
+ * Published npm installs omit embed sources; use prebuilt `dashboard-dist/` only.
  * @param {string} root
  */
 export function ensureDashboardBuilt(root = packageRoot) {
-  const distIndex = join(root, "dashboard-dist", "index.html");
+  const distDir = join(root, "dashboard-dist");
+  if (!hasEmbedDashboard(root)) {
+    return dashboardDirIfReady(distDir);
+  }
+
+  const distIndex = join(distDir, "index.html");
   const force =
     process.env.DSLINTER_REBUILD_DASHBOARD === "1" ||
     process.env.DSLINTER_REBUILD_DASHBOARD?.toLowerCase() === "true";
@@ -40,12 +54,9 @@ export function ensureDashboardBuilt(root = packageRoot) {
   let needsBuild = force || !existsSync(distIndex);
   if (!needsBuild) {
     const distMtime = statSync(distIndex).mtimeMs;
-    for (const sub of ["src", "embed"]) {
-      const dir = join(root, sub);
-      if (existsSync(dir) && maxMtimeInDir(dir) > distMtime) {
-        needsBuild = true;
-        break;
-      }
+    const embedDir = join(root, "embed");
+    if (existsSync(embedDir) && maxMtimeInDir(embedDir) > distMtime) {
+      needsBuild = true;
     }
     const configPath = join(root, "vite.config.ts");
     if (existsSync(configPath) && statSync(configPath).mtimeMs > distMtime) {
@@ -53,7 +64,7 @@ export function ensureDashboardBuilt(root = packageRoot) {
     }
   }
 
-  if (!needsBuild) return dashboardDirIfReady(join(root, "dashboard-dist"));
+  if (!needsBuild) return dashboardDirIfReady(distDir);
 
   process.stderr.write("[dslinter] Building dashboard bundle (dashboard-dist)…\n");
   const result = spawnSync("npm", ["run", "build:dashboard"], {
@@ -64,12 +75,7 @@ export function ensureDashboardBuilt(root = packageRoot) {
   if (result.status !== 0) {
     throw new Error("dslinter: dashboard build failed");
   }
-  return dashboardDirIfReady(join(root, "dashboard-dist"));
-}
-
-/** @returns {boolean} */
-export function hasEmbedDashboard() {
-  return existsSync(join(packageRoot, "index.html"));
+  return dashboardDirIfReady(distDir);
 }
 
 const VITE_CONFIG_NAMES = ["vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"];

package/bin/lib/project-root.test.mjs

@@ -0,0 +1,21 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ensureDashboardBuilt, hasEmbedDashboard } from "./project-root.mjs";
+
+describe("ensureDashboardBuilt (published install layout)", () => {
+  it("returns prebuilt dashboard-dist without spawning build when embed sources are absent", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-published-"));
+    mkdirSync(join(root, "dashboard-dist"), { recursive: true });
+    writeFileSync(join(root, "dashboard-dist", "index.html"), "<!doctype html>");
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(join(root, "src", "index.ts"), "export {};\n");
+
+    expect(hasEmbedDashboard(root)).toBe(false);
+
+    const dist = ensureDashboardBuilt(root);
+    expect(dist).toBeTruthy();
+    expect(dist).toContain("dashboard-dist");
+  });
+});

package/bin/lib/scaffold-config.mjs

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const CONFIG_NAMES = [".dslint.json", "dslint.json"];
+
+/**
+ * @param {string} targetDir
+ * @returns {string | null}
+ */
+export function findDslintConfigPath(targetDir) {
+  for (const name of CONFIG_NAMES) {
+    const candidate = join(targetDir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * @param {string} targetDir
+ * @param {string[]} candidates
+ * @returns {string[]}
+ */
+function existingPaths(targetDir, candidates) {
+  return candidates.filter((rel) => existsSync(join(targetDir, rel)));
+}
+
+/**
+ * @param {string} targetDir
+ * @param {"laravel" | "default"} layout
+ */
+function buildStarterConfig(targetDir, layout) {
+  const includeCandidates =
+    layout === "laravel"
+      ? ["resources/js/Components", "resources/js/components", "resources/js"]
+      : ["src/components", "src/ui", "src"];
+  const cssCandidates =
+    layout === "laravel"
+      ? ["resources/css/app.css", "src/index.css"]
+      : ["src/index.css", "src/styles.css", "src/app.css", "app/globals.css"];
+
+  const includeDirs = existingPaths(targetDir, includeCandidates);
+  const cssEntrypoints = existingPaths(targetDir, cssCandidates);
+  const groupPrefix = includeDirs[0];
+
+  return {
+    include_dirs: includeDirs,
+    ignore_globs: [],
+    css_entrypoints: cssEntrypoints,
+    ...(groupPrefix
+      ? {
+          playground_groups: {
+            components: [groupPrefix],
+          },
+        }
+      : {}),
+  };
+}
+
+/**
+ * @param {{ targetDir: string; layout: "laravel" | "default" }} opts
+ * @returns {{ created: boolean; path: string; existed: boolean }}
+ */
+export function ensureDslintConfig(opts) {
+  const targetDir = resolve(opts.targetDir);
+  const existing = findDslintConfigPath(targetDir);
+  if (existing) {
+    return { created: false, path: existing, existed: true };
+  }
+
+  const configPath = join(targetDir, ".dslint.json");
+  mkdirSync(targetDir, { recursive: true });
+  const payload = buildStarterConfig(targetDir, opts.layout);
+  writeFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`);
+  return { created: true, path: configPath, existed: false };
+}

package/bin/lib/scaffold-config.test.mjs

@@ -0,0 +1,33 @@
+import { mkdtempSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ensureDslintConfig } from "./scaffold-config.mjs";
+
+describe("ensureDslintConfig", () => {
+  it("writes starter config with detected include/css paths", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scaffold-"));
+    mkdirSync(join(root, "src", "components"), { recursive: true });
+    writeFileSync(join(root, "src", "index.css"), "@theme { --color-primary: #000; }");
+
+    const result = ensureDslintConfig({ targetDir: root, layout: "default" });
+    expect(result.created).toBe(true);
+
+    const raw = readFileSync(result.path, "utf8");
+    const parsed = JSON.parse(raw);
+    expect(parsed.include_dirs).toContain("src/components");
+    expect(parsed.css_entrypoints).toContain("src/index.css");
+    expect(parsed.ignore_globs).toEqual([]);
+  });
+
+  it("does not overwrite an existing config", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scaffold-existing-"));
+    const existing = join(root, ".dslint.json");
+    writeFileSync(existing, "{\n  \"ignore_globs\": [\"custom/**\"]\n}\n");
+
+    const result = ensureDslintConfig({ targetDir: root, layout: "default" });
+    expect(result.created).toBe(false);
+    expect(result.path).toBe(existing);
+    expect(readFileSync(existing, "utf8")).toContain("custom/**");
+  });
+});

package/bin/modes/build.mjs

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
 import { defaultReportPath, findViteRoot, resolveViteBin } from "../lib/project-root.mjs";
 import { runScannerSync } from "../lib/run-scanner.mjs";
 
@@ -32,9 +33,14 @@ export function runBuildMode({ scanPath, outputPath, scannerArgs }) {
     process.stderr.write(`dslinter: vite not installed in ${viteRoot}. Run npm install.\n`);
     process.exit(1);
   }
+  const scanAbs = resolve(scanPath);
   const child = spawnSync(process.execPath, [viteBin, "build"], {
     cwd: viteRoot,
     stdio: "inherit",
+    env: {
+      ...process.env,
+      DSLINT_SCAN_ROOT: scanAbs,
+    },
   });
   process.exit(child.status === null ? 1 : child.status);
 }

package/bin/modes/dev.mjs

@@ -12,6 +12,7 @@ import {
 import { writeDevBanner } from "../lib/dev-banner.mjs";
 import { findAvailablePort, warnIfPortBusy } from "../lib/port-check.mjs";
 import { spawnScanner } from "../lib/run-scanner.mjs";
+import { ensureDslintConfig } from "../lib/scaffold-config.mjs";
 import { waitForPort } from "../lib/wait-for-port.mjs";
 
 const POLL_MS = 150;
@@ -56,6 +57,10 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
   const port = servePort ?? defaultServePort();
   const reportPath = defaultReportPath(scanPath, outputPath);
   const scanAbs = resolve(scanPath);
+  const configResult = ensureDslintConfig({ targetDir: scanAbs, layout: "default" });
+  if (configResult.created) {
+    process.stderr.write(`dslinter: scaffolded ${configResult.path}\n`);
+  }
   const consumerViteRoot = findViteRoot(process.cwd());
   const embedRoot = getDashboardPackageRoot();
   const embedViteBin = hasEmbedDashboard() ? resolveViteBin(embedRoot) : null;
@@ -66,6 +71,10 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
     process.env.DSLINTER_NO_EMBED_VITE?.trim() !== "1";
 
   const bundledDist = useEmbedViteDev ? null : resolveBundledDashboardDir();
+  const useConsumerViteDev =
+    consumerViteRoot != null &&
+    bundledDist == null &&
+    process.env.DSLINTER_NO_CONSUMER_VITE?.trim() !== "1";
 
   const args = [...scannerArgs];
   const hasServe = args.some((a) => a === "--serve" || a.startsWith("--serve="));
@@ -172,7 +181,7 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
     return;
   }
 
-  if (consumerViteRoot) {
+  if (useConsumerViteDev) {
     const viteBin = resolveViteBin(consumerViteRoot);
     if (!viteBin) {
       process.stderr.write(`dslinter: vite not installed in ${consumerViteRoot}. Run npm install.\n`);
@@ -183,9 +192,23 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
     const uiPort = await resolveUiPort(5173);
     const dashboardUrl = `http://localhost:${uiPort}/`;
 
+    const consumerConfig = join(
+      getDashboardPackageRoot(),
+      "vite",
+      "consumer.config.mjs",
+    );
     const vite = spawn(
       process.execPath,
-      [viteBin, "--mode", "serve", "--port", String(uiPort), "--strictPort"],
+      [
+        viteBin,
+        "--config",
+        consumerConfig,
+        "--mode",
+        "serve",
+        "--port",
+        String(uiPort),
+        "--strictPort",
+      ],
       {
         cwd: consumerViteRoot,
         stdio: "inherit",
@@ -193,6 +216,7 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
           ...process.env,
           DSLINT_SERVE_PORT: String(port),
           DSLINT_SCAN_ROOT: scanAbs,
+          DSLINT_VITE_ROOT: consumerViteRoot,
         },
       },
     );

package/bin/modes/init.mjs

@@ -1,6 +1,7 @@
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ensureDslintConfig } from "../lib/scaffold-config.mjs";
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -39,62 +40,64 @@ export function runInitMode(opts = {}) {
     templateName,
   );
 
-  if (existsSync(registryPath)) {
-    process.stderr.write(
-      `dslinter init: ${registryPath} already exists — remove it first to re-scaffold.\n`,
-    );
-    process.exit(1);
+  const configResult = ensureDslintConfig({ targetDir, layout });
+  const wroteRegistry = !existsSync(registryPath);
+  if (wroteRegistry) {
+    mkdirSync(registryDir, { recursive: true });
+    copyFileSync(templatePath, registryPath);
   }
 
-  mkdirSync(registryDir, { recursive: true });
-  copyFileSync(templatePath, registryPath);
-
   const snippetPath = join(registryDir, "vite.dslinter.snippet.ts");
   const snippetTemplate = join(
     packageRoot,
     "templates",
     "vite.dslinter.snippet.ts",
   );
-  if (!existsSync(snippetPath) && existsSync(snippetTemplate)) {
+  if (wroteRegistry && !existsSync(snippetPath) && existsSync(snippetTemplate)) {
     copyFileSync(snippetTemplate, snippetPath);
   }
 
   const appHintPath = join(registryDir, "README.txt");
-  writeFileSync(
-    appHintPath,
-    [
-      "Wire live component previews in your App:",
-      "",
-      "  import { useMemo } from 'react';",
-      "  import { DashboardLayout, useWorkspaceReport } from 'dslinter';",
-      layout === "laravel"
-        ? "  import { buildPlaygroundEntries } from './playground/buildRegistry'; // adjust relative path from your entry file"
-        : "  import { buildPlaygroundEntries } from './playground/buildRegistry';",
-      "",
-      "  const dslinterReport = useWorkspaceReport({ reportUrl: '/dslint-report.json', watchUrl: '/events' });",
-      "  const playgroundEntries = useMemo(() => buildPlaygroundEntries(dslinterReport.report), [dslinterReport.report]);",
-      "",
-      "  <DashboardLayout playgroundEntries={playgroundEntries} dslinterReport={dslinterReport} ... />",
-      "",
-      "Run the scanner from the repo root: npx dslinter .",
-      "",
-    ].join("\n"),
-  );
+  if (wroteRegistry) {
+    writeFileSync(
+      appHintPath,
+      [
+        "Recommended (no registry file):",
+        "",
+        "  import { DashboardLayout, useWorkspaceReport } from 'dslinter';",
+        "  const dslinterReport = useWorkspaceReport({ reportUrl: '/dslint-report.json', watchUrl: '/events' });",
+        "  <DashboardLayout autoPlayground dslinterReport={dslinterReport} ... />",
+        "",
+        "Optional — custom glob via this registry:",
+        "",
+        "  import { buildPlaygroundEntries } from './playground/buildRegistry';",
+        "  <DashboardLayout playgroundEntries={buildPlaygroundEntries(dslinterReport.report)} ... />",
+        "",
+        "Run the scanner from the repo root: npx dslinter .",
+        "",
+      ].join("\n"),
+    );
+  }
 
   process.stdout.write(
     [
-      "dslinter init: wrote playground registry",
+      wroteRegistry
+        ? "dslinter init: wrote playground registry"
+        : "dslinter init: playground registry already exists (kept)",
       `  ${registryPath}`,
       "",
+      configResult.created
+        ? "dslinter init: wrote config"
+        : "dslinter init: config already exists (kept)",
+      `  ${configResult.path}`,
+      "",
       `Layout: ${layout}`,
       "",
       "Next:",
-      `  1. Import buildPlaygroundEntries in your App (see ${registryDir}/README.txt)`,
-      "  2. Merge vite.dslinter.snippet.ts into vite.config.ts (proxy, react dedupe, optimizeDeps.exclude)",
-      layout === "laravel"
-        ? "     No extra @ alias remapping is required — dslinter UI uses relative imports."
-        : "     No @ alias overrides needed for dslinter internal UI.",
-      "  3. Run npx dslinter . from the project root",
+      `  1. Use <DashboardLayout autoPlayground /> (see ${registryDir}/README.txt)`,
+      "  2. Run npx dslinter . from the project root (merges dslinter/vite automatically)",
+      "     Or add plugins: [dslinter()] from dslinter/vite for direct vite --mode serve",
+      "  3. Optional: use buildRegistry.ts for a narrower glob or control overrides",
       "",
     ].join("\n"),
   );

package/bin/modes/init.test.mjs

@@ -0,0 +1,16 @@
+import { existsSync, mkdtempSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { runInitMode } from "./init.mjs";
+
+describe("runInitMode", () => {
+  it("scaffolds config and playground registry", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-init-"));
+    mkdirSync(join(root, "src", "components"), { recursive: true });
+    runInitMode({ targetDir: root, argv: [] });
+
+    expect(existsSync(join(root, ".dslint.json"))).toBe(true);
+    expect(existsSync(join(root, "src", "playground", "buildRegistry.ts"))).toBe(true);
+  });
+});