@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [5.28.0]
+
+- added `plugin create <folder> [skeleton-identifier]` command to scaffold a new Crystallize plugin from a selectable git skeleton: downloads the skeleton tarball (re-rooting an optional monorepo subfolder), generates an RSA JWK keypair (reusing `plugin keygen`'s generator, writing `public.jwk.json` 0644 / `private.jwk.json` 0600 and ensuring `private.jwk.json` is gitignored even in a fresh non-git folder), substitutes mustache tokens, and installs dependencies. Interactive Ink journey by default; fully scriptable headless path via `--no-interactive` (`--name`, `--identifier`, `--author`, `--vendor-url`, `--bits`, `--kid`, `--no-install`).
+- `plugin create` token substitution covers file contents and file/directory names across the scaffold (skipping `node_modules`/`.git`, binary files, and symlinks): `{{plugin_name}}`, `{{plugin_identifier}}`, `{{author_name}}`, `{{vendor_url}}`, `{{public_jwk}}`, `{{private_jwk}}`, `{{kid}}`.
+- `plugin create` materializes `*.dist` templates to their final filenames before token substitution (e.g. `.env.dist` → `.env`, `dev-payload.config.jsonc.dist` → `dev-payload.config.jsonc`), without overwriting an existing target, so the generated files receive their tokens too.
+- the no-lockfile dependency-install default for `plugin create` is `npm` (lockfiles still auto-detect bun/pnpm/npm/yarn).
+- added bash completion for the new `plugin create` command.
+
 ## [5.27.0]
 
 - bumped `@crystallize/js-api-client` to ^7.2.0 (renamed `signature` → `signatureStatus`, `backendToken` → `backendTokenStatus` on the decrypter result; `envelope.config` → `envelope.configuration`; new `tenantId`, `event`, `signatureSecret`, `staticAuthToken` fields on `CrystallizePluginPayload`) and bumped `jose` to ^6 (drops the `KeyLike` re-export in favor of native `CryptoKey`).
 
@@ -39,6 +39,8 @@ The CLI enhances Developer Experience while also being CI/CD-friendly for automa
 
 - **Mass Operations:** Experimental but functional. You can `dump` your content model as JSON, `run` mass operations, and `execute` sets of mutations.
 
+- **Plugin Development:** Scaffold a new Crystallize plugin from a skeleton, generate its keypair, and wire up its config in one command.
+
 ## Interactivity
 
 Most commands are interactive. If credentials are missing, or input is required, the CLI will prompt you. To disable interactivity (e.g., in a CI environment), use `--no-interactive` where applicable.
@@ -62,6 +64,30 @@ An interactive command designed to simplify setting up boilerplates.
 - `folder` (required): The installation directory.
 - `tenant-identifier` and `boilerplate-identifier` (optional): If omitted, a wizard will guide you.
 
+## Plugin Development
+
+Scaffold a new Crystallize plugin from a selectable git skeleton.
+
+```bash
+~/crystallize plugin create <folder> [skeleton-identifier]
+```
+
+- `folder` (required): Target directory (must be empty or not exist).
+- `skeleton-identifier` (optional): If omitted, an interactive wizard lets you pick one.
+
+The command downloads the skeleton (a git repo, optionally a subfolder of a monorepo), generates an RSA JWK keypair (`public.jwk.json` / `private.jwk.json`, the private key auto-added to `.gitignore`), substitutes mustache tokens, and installs dependencies.
+
+Tokens replaced across file contents and file/directory names: `{{plugin_name}}`, `{{plugin_identifier}}`, `{{author_name}}`, `{{vendor_url}}`, `{{public_jwk}}`, `{{private_jwk}}`, `{{kid}}`. Any `*.dist` template is also materialized to its final filename (e.g. `.env.dist` → `.env`) before substitution, without overwriting an existing target.
+
+For CI / scripting, run non-interactively:
+
+```bash
+~/crystallize plugin create ./my-plugin hono-plugin-skeleton --no-interactive \
+  --name "My Plugin" --author "Acme" --vendor-url https://acme.example --no-install
+```
+
+Other plugin subcommands (`keygen`, `encrypt-secret`, `decrypt-payload`) help generate keys and test the plugin payload protocol locally.
+
 ## Tenant Management
 
 ### Creating a Tenant
 
@@ -1,6 +1,6 @@
 {
     "name": "@crystallize/cli",
-    "version": "5.27.0",
+    "version": "5.28.0",
     "description": "Crystallize CLI",
     "license": "MIT",
     "contributors": [
 
@@ -0,0 +1,198 @@
+import { Argument, Command, Option } from 'commander';
+import { Box, Text, Newline, render } from 'ink';
+import { Provider } from 'jotai';
+import path from 'node:path';
+import { logo } from '../..';
+import { pluginSkeletons } from '../../content/plugin-skeletons';
+import type { FlySystem } from '../../domain/contracts/fly-system';
+import type { Logger } from '../../domain/contracts/logger';
+import type { CommandBus, QueryBus } from '../../domain/contracts/bus';
+import { ALLOWED_BITS, type AllowedBits } from '../../domain/use-cases/generate-plugin-keypair';
+import { writeKeypairFiles } from '../../core/helpers/keypair-files';
+import { CreatePluginJourney } from '../../ui/journeys/create-plugin/create-plugin.journey';
+import type { CreatePluginStore } from '../../ui/journeys/create-plugin/create-store';
+
+type Deps = {
+    logger: Logger;
+    flySystem: FlySystem;
+    queryBus: QueryBus;
+    commandBus: CommandBus;
+    createPluginCommandStore: CreatePluginStore;
+};
+
+type Flags = {
+    name?: string;
+    identifier?: string;
+    author?: string;
+    vendorUrl?: string;
+    bits: string;
+    kid: string;
+    install: boolean; // commander: --no-install => false
+    interactive: boolean; // commander: --no-interactive => false
+};
+
+const EXIT_INVALID_FLAGS = 2;
+
+const kebab = (value: string) =>
+    value
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+
+const fail = (logger: Logger, code: number, message: string): never => {
+    logger.error(message);
+    logger.flush();
+    process.exit(code);
+};
+
+export const createPluginCreateCommand = ({
+    logger,
+    flySystem,
+    queryBus,
+    commandBus,
+    createPluginCommandStore,
+}: Deps): Command => {
+    const command = new Command('create');
+    command.description('Scaffold a new Crystallize plugin from a skeleton.');
+    command.addArgument(new Argument('<folder>', 'Target folder (must be empty or not exist).'));
+    command.addArgument(new Argument('[skeleton-identifier]', 'Skeleton identifier to use.'));
+    command.addOption(new Option('--name <name>', 'Plugin display name.'));
+    command.addOption(new Option('--identifier <id>', 'Plugin identifier (kebab-case).'));
+    command.addOption(new Option('--author <author>', 'Author name.'));
+    command.addOption(new Option('--vendor-url <url>', 'Vendor URL.'));
+    command.addOption(new Option('--bits <n>', 'RSA modulus length.').default('2048'));
+    command.addOption(new Option('--kid <kid>', 'Key id.').default('public'));
+    command.addOption(new Option('--no-install', 'Skip dependency installation.'));
+    command.addOption(new Option('--no-interactive', 'Run headless (all inputs via flags).'));
+
+    command.action(async (folder: string, skeletonIdentifier: string | undefined, flags: Flags, cmd: Command) => {
+        await flySystem.createDirectoryOrFail(folder, 'Please provide an empty folder for the plugin.');
+
+        const bits = Number(flags.bits);
+        if (!Number.isInteger(bits) || !ALLOWED_BITS.includes(bits as AllowedBits)) {
+            fail(
+                logger,
+                EXIT_INVALID_FLAGS,
+                `invalid --bits: ${flags.bits}. must be one of ${ALLOWED_BITS.join(', ')}`,
+            );
+        }
+        const skeleton =
+            pluginSkeletons.find((s) => s.identifier === skeletonIdentifier) ??
+            (skeletonIdentifier
+                ? fail(logger, EXIT_INVALID_FLAGS, `unknown skeleton "${skeletonIdentifier}"`)
+                : undefined);
+
+        const headless = flags.interactive === false || !process.stdin.isTTY;
+
+        if (headless) {
+            if (!skeleton) fail(logger, EXIT_INVALID_FLAGS, 'non-interactive mode requires a [skeleton-identifier]');
+            if (!flags.name) fail(logger, EXIT_INVALID_FLAGS, 'non-interactive mode requires --name');
+            if (!flags.author) fail(logger, EXIT_INVALID_FLAGS, 'non-interactive mode requires --author');
+            if (!flags.vendorUrl) fail(logger, EXIT_INVALID_FLAGS, 'non-interactive mode requires --vendor-url');
+            // Assign to typed locals so the try block retains non-optional types.
+            // tsc does not propagate narrowing from `if (!x) fail(...)` into subsequent const assignments
+            // (known limitation), so one `!` per local is required here.
+            const resolvedSkeleton = skeleton!;
+            const resolvedName = flags.name!;
+            const resolvedAuthor = flags.author!;
+            const resolvedVendorUrl = flags.vendorUrl!;
+            const identifier = kebab(flags.identifier || resolvedName);
+
+            try {
+                const dlQuery = queryBus.createQuery('DownloadPluginSkeletonArchive', {
+                    skeleton: resolvedSkeleton,
+                    destination: folder,
+                });
+                await queryBus.dispatch(dlQuery);
+                logger.info('skeleton downloaded');
+
+                const kpCmd = commandBus.createCommand('GeneratePluginKeypair', {
+                    bits: bits as AllowedBits,
+                    kid: flags.kid,
+                });
+                const { result: pair } = await commandBus.dispatch(kpCmd);
+                if (!pair) fail(logger, 1, 'failed to generate keypair');
+                // pair is narrowed to non-undefined here; assign to a const so tsc retains that inside the try block.
+                const resolvedPair = pair!;
+                await writeKeypairFiles({
+                    flySystem,
+                    logger,
+                    pair: resolvedPair,
+                    publicPath: path.join(folder, 'public.jwk.json'),
+                    privatePath: path.join(folder, 'private.jwk.json'),
+                    autoGitignore: true,
+                });
+                logger.info('keypair generated');
+
+                const rtCmd = commandBus.createCommand('ReplacePluginTokens', {
+                    folder,
+                    tokens: {
+                        '{{plugin_name}}': resolvedName,
+                        '{{plugin_identifier}}': identifier,
+                        '{{author_name}}': resolvedAuthor,
+                        '{{vendor_url}}': resolvedVendorUrl,
+                        '{{public_jwk}}': JSON.stringify(resolvedPair.publicJwk),
+                        '{{private_jwk}}': JSON.stringify(resolvedPair.privateJwk),
+                        '{{kid}}': flags.kid,
+                    },
+                });
+                await commandBus.dispatch(rtCmd);
+                logger.info('tokens substituted');
+
+                if (flags.install !== false) {
+                    const inCmd = commandBus.createCommand('InstallPluginDependencies', { folder });
+                    await commandBus.dispatch(inCmd);
+                    logger.info('dependencies installed');
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                fail(logger, 1, `plugin scaffolding failed: ${message}. the folder ${folder} was left in place.`);
+            }
+            logger.success(`plugin created in ${folder}`);
+            logger.flush();
+            return;
+        }
+
+        logger.setBuffered(true);
+        const { storage, atoms } = createPluginCommandStore;
+        storage.set(atoms.setFolderAtom, folder);
+        if (skeleton) storage.set(atoms.setSkeletonAtom, skeleton);
+        if (flags.install === false) storage.set(atoms.setSkipInstallAtom, true);
+        if (cmd.getOptionValueSource('bits') === 'cli' || cmd.getOptionValueSource('kid') === 'cli') {
+            storage.set(atoms.setKeypairAtom, { bits: bits as AllowedBits, kid: flags.kid });
+        }
+        if (flags.name && flags.author && flags.vendorUrl) {
+            storage.set(atoms.setInfoAtom, {
+                name: flags.name,
+                identifier: kebab(flags.identifier || flags.name),
+                author: flags.author,
+                vendorUrl: flags.vendorUrl,
+            });
+        }
+
+        console.log(logo);
+        const { waitUntilExit } = render(
+            <Box flexDirection="column" padding={1}>
+                <Box flexDirection="column" marginBottom={1}>
+                    <Text>
+                        Let's create your Crystallize plugin! <Newline />
+                    </Text>
+                    <Provider store={storage}>
+                        <CreatePluginJourney
+                            store={atoms}
+                            queryBus={queryBus}
+                            commandBus={commandBus}
+                            flySystem={flySystem}
+                            logger={logger}
+                        />
+                    </Provider>
+                </Box>
+            </Box>,
+            { exitOnCtrlC: true },
+        );
+        await waitUntilExit();
+    });
+
+    return command;
+};
@@ -1,13 +1,13 @@
 import { Command, Option } from 'commander';
 import path from 'node:path';
 import { chmod, stat } from 'node:fs/promises';
-import { spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import pc from 'picocolors';
 import type { Logger } from '../../domain/contracts/logger';
 import type { FlySystem } from '../../domain/contracts/fly-system';
 import type { CommandBus } from '../../domain/contracts/bus';
 import { ALLOWED_BITS, type AllowedBits } from '../../domain/use-cases/generate-plugin-keypair';
+import { findGitRoot, gitignoreContains } from '../../core/helpers/keypair-files';
 
 type Deps = {
     logger: Logger;
@@ -50,24 +50,6 @@ const promptYesNo = async (question: string): Promise<boolean> => {
     }
 };
 
-const findGitRoot = (cwd: string): string | null => {
-    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
-        cwd,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    if (result.status !== 0) return null;
-    const output = result.stdout.trim();
-    return output.length > 0 ? output : null;
-};
-
-const gitignoreContains = (content: string, name: string): boolean => {
-    return content
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .some((line) => line === name || line === `/${name}` || line === `./${name}`);
-};
-
 export const createPluginKeygenCommand = ({ logger, flySystem, commandBus }: Deps): Command => {
     const command = new Command('keygen');
     command.description('Generate an RSA JWK keypair for a Crystallize plugin revision.');
 
@@ -153,11 +153,16 @@ _crystallize_completions() {
     ;;
     plugin)
         if [[ "${COMP_CWORD}" -eq 2 ]]; then
-                local options="keygen encrypt-secret decrypt-payload ${default_options}"
+                local options="create keygen encrypt-secret decrypt-payload ${default_options}"
                 COMPREPLY=($(compgen -W "${options}" -- "${cur}"))
                 return 0
         fi
         case "${subcmd}" in
+            create)
+                local options="--name= --identifier= --author= --vendor-url= --bits= --kid= --no-install --no-interactive ${default_options}"
+                COMPREPLY=($(compgen -W "${options}" -- "${cur}"))
+                return 0
+                ;;
             keygen)
                 local options="--bits= --kid= --out-dir= --public-out= --private-out= --stdout --public-only --force --yes ${default_options}"
                 COMPREPLY=($(compgen -W "${options}" -- "${cur}"))
 
@@ -0,0 +1,33 @@
+import type { PluginSkeleton } from '../domain/contracts/models/plugin-skeleton';
+
+export const pluginSkeletons: PluginSkeleton[] = [
+    {
+        identifier: 'hono-plugin-skeleton',
+        name: 'Hono Plugin Skeleton',
+        baseline: 'Minimal Crystallize plugin server built with Hono and React',
+        description: 'A vendor-hosted plugin upstream server: config schema, post-install webhook, payload decryption.',
+        git: 'https://github.com/CrystallizeAPI/plugins',
+        subfolder: 'plugins/crystallize-plugin-skeleton',
+        branch: 'main',
+    },
+    {
+        identifier: 'cloudflare-hono-plugin-buddy',
+        name: 'Cloudflare Hono Plugin Buddy (not a Skeleton but an example)',
+        baseline: 'Crystallize plugin server built with Hono and React, designed for deployment on Cloudflare Workers.',
+        description:
+            'A vendor-hosted plugin upstream server: config schema, post-install webhook, payload decryption. Includes Cloudflare-specific optimizations and deployment configuration.',
+        git: 'https://github.com/CrystallizeAPI/plugins',
+        subfolder: 'plugins/crystallize-buddy',
+        branch: 'main',
+    },
+    {
+        identifier: 'hello-world-plugin',
+        name: 'Hello World Plugin (not a Skeleton but an example)',
+        baseline: 'A simple Crystallize plugin server.',
+        description:
+            'A minimal plugin server that responds to installation and configuration events with basic logging. Ideal for learning and testing plugin development.',
+        git: 'https://github.com/CrystallizeAPI/plugins',
+        subfolder: 'plugins/hello-world',
+        branch: 'main',
+    },
+];
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@crystallize/cli",`
`3`		`- "version": "5.27.0",`
	`3`	`+ "version": "5.28.0",`
`4`	`4`	`"description": "Crystallize CLI",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"contributors": [`