@page "/docs/cli"
@namespace Lumeo.Docs.Pages.Docs

<PageTitle>CLI — Lumeo</PageTitle>

<Container MaxWidth="3xl" Padding="0" Center="false">
<Stack Gap="10">

    <!-- Intro -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="1" Size="3xl">Lumeo CLI</Heading>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                Sometimes you want to own the source. The <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.Cli</code> tool
                vendorizes Lumeo components directly into your project — like <Lumeo.Link Href="https://ui.shadcn.com" Class="text-foreground underline underline-offset-4 hover:text-muted-foreground transition-colors">shadcn/ui</Lumeo.Link>
                does for React. Run <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo add button</code> and get the
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.razor</code> file copied into your codebase, rewritten to
                your namespace. You own it. Edit it freely.
            </Lumeo.Text>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                This is an <Lumeo.Text As="span" Weight="medium" Class="text-foreground">optional path</Lumeo.Text>, not a replacement.
                The <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo</code> NuGet remains the default —
                pull it in and you get every component, every service, every update for free.
                Reach for the CLI when a component is 80% right and you want to tweak the last 20%.
            </Lumeo.Text>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Install -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="2">Install</Heading>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                Install as a global <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">dotnet</code> tool:
            </Lumeo.Text>
            <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-sm text-foreground">
                dotnet tool install -g Lumeo.Cli --version 2.2.2
            </Stack>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                The tool exposes a single command, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo</code>.
                Run <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo --help</code> to see subcommands.
            </Lumeo.Text>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Quickstart -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="2">Quickstart</Heading>

            <Stack Gap="3">
                <Heading Level="3">1. Initialize</Heading>
                <Lumeo.Text Size="sm" Color="muted" Class="mb-2">
                    From your Blazor project root:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-sm text-foreground">
                    lumeo init
                </Stack>
                <Lumeo.Text Size="sm" Color="muted" Class="mb-2">
                    You'll be asked for a target namespace (e.g. <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">MyApp.Components</code>)
                    and a components folder (defaults to <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Components/Ui</code>).
                    The tool writes a <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code>:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-sm text-foreground whitespace-pre">@("{")
  "namespace": "MyApp.Components",
  "componentsPath": "Components/Ui",
  "registry": "https://lumeo.nativ.sh/registry/registry.json"
@("}")</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3">2. Add a component</Heading>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-sm text-foreground">
                    lumeo add button
                </Stack>
                <Lumeo.Text Size="sm" Color="muted" Class="mb-2">
                    The tool downloads <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Button.razor</code>,
                    rewrites <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">@@namespace Lumeo</code> to
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">@@namespace MyApp.Components</code>, and writes it to
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Components/Ui/Button/Button.razor</code>.
                    Any dependencies (e.g. <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Spinner</code> for loading state) are
                    resolved and you're prompted to install them too.
                </Lumeo.Text>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3">3. Use it</Heading>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-sm text-foreground whitespace-pre">@@using MyApp.Components

&lt;Button Variant="Button.ButtonVariant.Primary"&gt;Save&lt;/Button&gt;</Stack>
            </Stack>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Setup paths -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="2">Setup paths</Heading>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                When you run <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo init</code>, the CLI walks up from the current
                directory looking for a <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.csproj</code> that references the
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo</code> NuGet. What happens next depends on the result.
            </Lumeo.Text>

            <Stack Gap="3">
                <Heading Level="3">NuGet already installed — default</Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    If <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">&lt;PackageReference Include="Lumeo" /&gt;</code> (or a
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ProjectReference</code> to the Lumeo library) is found, nothing
                    extra is written. CSS tokens, utility classes, and the JS interop ship with the package. The
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--with-css</code> / <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--with-tailwind</code> / <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--no-assets</code>
                    flags are ignored with a soft warning.
                </Lumeo.Text>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3">No NuGet — Option 1: pre-built CSS (recommended)</Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Zero build tooling. The CLI copies Lumeo's pre-compiled stylesheets and JS modules into your
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">wwwroot/</code>:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">wwwroot/css/lumeo.css
wwwroot/css/lumeo-utilities.css
wwwroot/js/theme.js
wwwroot/js/components.js</Stack>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Then add these tags to your <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">index.html</code> or
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">_Host.cshtml</code>:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">&lt;link rel="stylesheet" href="css/lumeo.css" /&gt;
&lt;link rel="stylesheet" href="css/lumeo-utilities.css" /&gt;
&lt;script src="js/theme.js"&gt;&lt;/script&gt;
&lt;script src="js/components.js" type="module"&gt;&lt;/script&gt;</Stack>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Pick this path via <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo init --with-css</code>, or just press
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">1</code> when prompted.
                </Lumeo.Text>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3">No NuGet — Option 2: Tailwind v4 scaffold</Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    If you're already writing Tailwind classes in your own markup, let the CLI wire up Tailwind v4 so it scans both
                    your pages and the vendored Lumeo components. It writes <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Styles/input.css</code>:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">@@import "tailwindcss";
@@import "./_content/Lumeo/css/lumeo.css" layer(base);  /* tokens */

@@source "./**/*.razor";
@@source "./Components/Ui/**/*.razor";</Stack>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    and either creates or merges into <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">package.json</code> a pair of
                    scripts + the <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">@@tailwindcss/cli</code> devDependency:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">"scripts": @("{")
  "build:css": "tailwindcss -i Styles/input.css -o wwwroot/css/app.css --minify",
  "watch:css": "tailwindcss -i Styles/input.css -o wwwroot/css/app.css --watch"
@("}")</Stack>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Then:
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">npm install
npm run watch:css</Stack>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Pick this path via <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo init --with-tailwind</code>.
                    You'll link <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">css/app.css</code> in your host HTML instead of
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.css</code>.
                </Lumeo.Text>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3">Keeping pre-built assets fresh</Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    When Lumeo ships CSS/JS tweaks, run <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo update-assets</code>.
                    It re-downloads the files listed under <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">assets.files</code> in
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> and prompts per-file on drift — the same flow as
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo update &lt;component&gt;</code>. Only runs when
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">assets.mode == "prebuilt"</code>; Tailwind users rebuild their own bundle.
                </Lumeo.Text>
            </Stack>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Commands -->
    <Stack>
        <Stack Gap="6">
            <Heading Level="2">Commands</Heading>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo init</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Creates <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> in the current directory
                    and scaffolds <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">README.md</code> + <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.gitkeep</code> under the components folder.
                    Interactive by default: if a <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.csproj</code> is present, the
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">&lt;RootNamespace&gt;</code> (or the filename) is auto-detected and suggested
                    as the default — just press Enter to accept.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--namespace &lt;ns&gt;     Target namespace (skips prompt).
--path &lt;path&gt;        Components folder (skips prompt).
--registry &lt;url&gt;     Override registry URL.
--yes, -y            Accept all defaults, skip prompts (CI mode).
--force              Overwrite existing lumeo.json.
--with-css           Copy Lumeo's pre-built CSS/JS into wwwroot/.
--with-tailwind      Scaffold Tailwind v4 (Styles/input.css + package.json).
--no-assets          Skip asset setup entirely.
--local              Copy assets from a local Lumeo checkout (dev only).</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo update-assets</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Refreshes the copied CSS/JS files (applies only when <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">assets.mode == "prebuilt"</code>).
                    Walks the same files <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">init --with-css</code> wrote and prompts per-file on drift —
                    overwrite, skip, or view a diff. Tailwind and skip modes are no-ops (tailwind users rebuild via
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">npm run build:css</code>).
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--local              Read assets from a local Lumeo checkout.
--force              Overwrite all files without prompting.
--dry-run            Print what would happen; don&apos;t touch the filesystem.</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo add &lt;component&gt;</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Downloads a component (and its registry-declared dependencies), rewrites its namespace, and writes files under
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">componentsPath</code>.
                    Records the install in <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> so
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">update</code> / <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">remove</code> know what&apos;s installed.
                    When a target file already exists you get a per-file prompt — overwrite, skip, view diff, all-overwrite, or abort.
                </Lumeo.Text>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Each registry entry includes a <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">nugetPackage</code> field that
                    maps the component to its NuGet package. When you run
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo add chart</code>, the CLI checks whether
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.Charts</code> is already referenced in your
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.csproj</code>. If not, it prompts:
                    <Lumeo.Text As="span" Weight="medium" Class="text-foreground font-mono">"Lumeo.Charts is required for this component — install it now?"</Lumeo.Text>
                    Confirming runs <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">dotnet add package Lumeo.Charts</code> before copying the component files.
                    This applies to all five satellites: <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.Charts</code>,
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.DataGrid</code>,
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.Editor</code>,
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.Scheduler</code>, and
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo.Gantt</code>.
                    Components in the core <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo</code> package skip this check.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--local              Read files from a local Lumeo checkout (dev only).
--yes, -y            Skip dependency confirmation prompts.
--force              Overwrite all conflicts without prompting (CI).
--skip-existing      Silently skip files that already exist.
--dry-run            Print what would happen; don&apos;t touch the filesystem.
--overwrite          Legacy alias of --force.</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo update [&lt;component&gt;]</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Refetches a component (or all installed components, when the name is omitted), computes a diff vs. the local vendored copy,
                    and prompts per file: <Lumeo.Text As="span" Weight="medium" Class="text-foreground">update</Lumeo.Text>,
                    <Lumeo.Text As="span" Weight="medium" Class="text-foreground">skip</Lumeo.Text>, or
                    <Lumeo.Text As="span" Weight="medium" Class="text-foreground">diff</Lumeo.Text>.
                    Use <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--check</code> in CI: exits
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">1</code> if any file has drifted,
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">0</code> if clean.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--local              Read from a local Lumeo checkout.
--force              Update without prompting.
--check              Report drift only; exit 1 if drift found.
--force-reset        Restore to registry version, discarding local edits.
--dry-run            Print what would happen; don&apos;t touch the filesystem.</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo remove &lt;component&gt;</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Deletes the vendored files for a component and cleans up empty folders. Warns if other installed components depend on it
                    (per the registry&apos;s <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">dependencies</code> field) before asking for confirmation.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--force              Skip the confirmation prompt.
--dry-run            Print what would be deleted; don&apos;t touch the filesystem.</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo list</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Prints every component in the registry, grouped by category, with a one-line description.
                    Filter to one category with <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--category</code>,
                    or emit JSON for tooling with <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--json</code>.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--local              Read from the local registry file.
--category &lt;name&gt;    Filter to one category (e.g. Forms).
--json               Dump entries as JSON.</Stack>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo diff &lt;component&gt;</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Compares the vendored copy in your repo against the registry version and reports which files have drifted.
                    Run <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo update &lt;component&gt;</code> to pull the upstream version
                    (or <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--force</code> to reset without prompting).
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--local              Diff against local registry.</Stack>
            </Stack>

            <Stack Gap="2">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo view &lt;component&gt;</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Prints a component's source files to stdout without writing anything to disk. Useful for previewing what
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo add</code> would copy in,
                    or for piping into a diff tool against your own copy.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--local              Read sources from a local Lumeo checkout (dev only).
--path &lt;dir&gt;         Override the components root path (rarely needed).</Stack>
            </Stack>

            <Stack Gap="2">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo info</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Prints your project's current Lumeo state: <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> contents,
                    installed components and their drift status, active theme preset, and the registry version the project resolves against.
                    Pass <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--json</code> for machine-readable output (CI / tooling).
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--json               Emit machine-readable JSON instead of pretty text.</Stack>
            </Stack>

            <Stack Gap="2">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo apply &lt;preset-or-flags&gt;</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Applies a theme preset to the project — writes <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> theme defaults
                    and refreshes <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">wwwroot/lumeo-theme.json</code> so the runtime matches.
                    Accepts a 6-character preset code (e.g. <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo apply ab12cd</code>) or
                    individual flags. The deprecated <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo theme apply</code> alias still works
                    for backwards compat.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--preset &lt;code&gt;      6-char preset code (alternative to positional arg).
--theme &lt;name&gt;       default | blue | orange | green | rose | zinc | violet | amber | teal
--style &lt;name&gt;       default | new-york
--base &lt;color&gt;       slate | gray | zinc | neutral | stone
--radius &lt;n&gt;         0 | 0.25 | 0.5 | 0.75 | 1
--font &lt;name&gt;        system | inter | geist | ibm-plex-sans | jetbrains-mono | fira-code
--icons &lt;name&gt;       lucide | bootstrap | fluentui | font-awesome | google-material |
                     material-design | ionicons | devicon | flag-icons
--only &lt;list&gt;        Only apply named keys (comma-separated).
--dry-run            Preview the resulting lumeo.json without writing.
--yes                Skip the confirmation prompt.
--silent             Suppress non-essential output.</Stack>
            </Stack>

            <Stack Gap="2">
                <Heading Level="3"><code class="rounded bg-muted px-1.5 py-0.5 text-sm font-mono text-foreground">lumeo preset encode</code></Heading>
                <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                    Generates a 6-character preset code from individual flags so you can share a theme as a single token
                    (e.g. paste into a README or pass to <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo apply</code>).
                    Pass <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">--command</code> to print the full
                    <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo apply --preset &lt;code&gt;</code> line instead of just the code.
                </Lumeo.Text>
                <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">--theme / --style / --base / --radius / --font / --icons   See `lumeo apply` for accepted values.
--menu-color &lt;name&gt;  Sidebar background color override.
--menu-accent &lt;name&gt; Sidebar active-item accent color override.
--dark               Encode dark mode as the default.
--command            Print `lumeo apply --preset &lt;code&gt;` instead of just the code.</Stack>
            </Stack>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- lumeo.json -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="2">The <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> manifest</Heading>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                After running <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo add</code>, the config grows an
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">components</code> map recording what&apos;s installed.
                It&apos;s used by <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">update</code>,
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">remove</code>, and
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">diff</code>. The map is optional — if
                missing, the CLI falls back to scanning <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">componentsPath</code> to infer installed
                components (so older <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.json</code> files keep working).
            </Lumeo.Text>
            <Stack Class="code-block rounded-lg border border-border/40 bg-muted px-4 py-3 font-mono text-xs text-foreground whitespace-pre">@("{")
  "namespace": "MyApp.Components",
  "componentsPath": "Components/Ui",
  "registry": "https://lumeo.nativ.sh/registry/registry.json",
  "assets": @("{")
    "mode": "prebuilt",
    "version": "2.0.0",
    "files": [
      "wwwroot/css/lumeo.css",
      "wwwroot/css/lumeo-utilities.css",
      "wwwroot/js/theme.js",
      "wwwroot/js/components.js"
    ]
  @("}"),
  "components": @("{")
    "button":  @("{") "version": "2.0.0", "files": ["UI/Button/Button.razor"] @("}"),
    "spinner": @("{") "version": "2.0.0", "files": ["UI/Spinner/Spinner.razor"] @("}")
  @("}")
@("}")</Stack>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                <Lumeo.Text As="span" Weight="medium" Class="text-foreground">assets.mode</Lumeo.Text> is one of
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">"prebuilt"</code> (Option 1 — copied CSS/JS),
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">"tailwind"</code> (Option 2 — <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Styles/input.css</code> +
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">package.json</code>), or
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">"none"</code> (skipped).
                When the NuGet is detected, the whole <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">assets</code> block is omitted.
            </Lumeo.Text>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Tradeoffs -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="2">Tradeoffs: NuGet vs vendor</Heading>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                Both paths are first-class. Pick per project, or mix them — nothing in the CLI prevents you from keeping the NuGet
                reference alongside a few vendored components.
            </Lumeo.Text>

            <Stack Gap="3">
                <Heading Level="3">NuGet — the default</Heading>
                <ul class="list-disc list-inside space-y-1.5 text-muted-foreground text-sm leading-relaxed ml-2">
                    <li><span class="text-foreground">Auto-update</span> — <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">dotnet add package Lumeo</code> and bump versions for bug fixes.</li>
                    <li><span class="text-foreground">Smaller codebase</span> — no component source files to maintain in your repo.</li>
                    <li><span class="text-foreground">Services included</span> — Toast, Overlay, Theme, etc. live in the package and just work.</li>
                    <li><span class="text-foreground">Best for</span> — most apps; shipping quickly; standard theming.</li>
                </ul>
            </Stack>

            <Stack Gap="3">
                <Heading Level="3">Vendor — for the last 20%</Heading>
                <ul class="list-disc list-inside space-y-1.5 text-muted-foreground text-sm leading-relaxed ml-2">
                    <li><span class="text-foreground">You own the source</span> — diverge freely; no "waiting for a PR to merge".</li>
                    <li><span class="text-foreground">No black-box overrides</span> — edit markup, add slots, change behavior.</li>
                    <li><span class="text-foreground">Opt-in updates</span> — <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo diff</code> shows drift, you decide when to pull.</li>
                    <li><span class="text-foreground">Best for</span> — design systems; component libraries built on Lumeo; heavily customized UIs.</li>
                </ul>
            </Stack>
        </Stack>
    </Stack>

    <Separator Class="my-4" />

    <!-- Limitations -->
    <Stack>
        <Stack Gap="4">
            <Heading Level="2">What the CLI can and can't vendor</Heading>
            <Lumeo.Text Size="base" Color="muted" Leading="relaxed">
                Only <Lumeo.Text As="span" Weight="medium" Class="text-foreground">presentation components</Lumeo.Text> —
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.razor</code> and their code-behind
                <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">.cs</code> files — can be vendored.
                Runtime services still require a reference to the <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">Lumeo</code> NuGet package:
            </Lumeo.Text>
            <ul class="list-disc list-inside space-y-1.5 text-muted-foreground text-sm leading-relaxed ml-2">
                <li><code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ToastService</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">OverlayService</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ThemeService</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">KeyboardShortcutService</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">ComponentInteropService</code>.</li>
                <li>JavaScript interop modules (<code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">_content/Lumeo/js/*</code>).</li>
                <li>Pre-compiled CSS (<code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo.css</code>, <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">lumeo-utilities.css</code>).</li>
                <li>The <code class="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">[LumeoForm]</code> source generator.</li>
            </ul>
            <Lumeo.Text Size="sm" Color="muted" Leading="relaxed">
                In practice: keep the NuGet reference; vendor the components you want to customize; delete any that you fully own.
            </Lumeo.Text>
        </Stack>
    </Stack>

</Stack>
</Container>
