@blinkhost/cli 2.0.0 → 2.1.0

package/README.md

@@ -6,14 +6,23 @@ The BlinkHost CLI brings project setup, local development, source control, previ
 
 Node.js 22.12 or newer is required.
 
-Install the signed release archive directly from BlinkHost's public repository:
-
 ```bash
-npm install --global https://github.com/blinkhost-ltd/blinkhost-cli/releases/download/v2.0.0/blinkhost-cli-2.0.0.tgz
+npm install --global @blinkhost/cli
 blinkhost --version
 ```
 
-Checksums, the CycloneDX SBOM, and Sigstore verification bundle are published with the archive at <https://github.com/blinkhost-ltd/blinkhost-cli/releases/tag/v2.0.0>.
+Signed release archives, checksums, the CycloneDX SBOM, and Sigstore verification bundle are available at <https://github.com/blinkhost-ltd/blinkhost-cli/releases>.
+
+## Start safely
+
+```bash
+blinkhost quickstart
+blinkhost docs
+blinkhost docs automation
+blinkhost help create
+```
+
+`quickstart` is local, read-only, and makes no network requests. It checks Node.js, Git, the operating-system credential service, the selected directory, and any existing BlinkHost manifest. It never signs in, uploads source, creates a cloud resource, or incurs usage. The bundled `docs` reference is offline and matches the installed CLI version; use the linked web documentation for longer guides.
 
 ## Connect an account
 
@@ -32,6 +41,8 @@ blinkhost profile use work
 
 Revoke a device with `blinkhost auth revoke SESSION_ID` or disconnect all CLI sessions for the active profile with `blinkhost auth logout`.
 
+Interactive credential storage uses macOS Keychain, Windows Password Vault, or Linux Secret Service (`secret-tool` with an available, unlocked session keyring). The CLI intentionally does not fall back to a plaintext refresh-token file. Headless systems should use a registered GitHub OIDC workload or a short-lived runtime access token.
+
 ## Create or adopt a project
 
 ```bash
@@ -42,10 +53,25 @@ blinkhost projects link PROJECT_ID
 blinkhost dev
 ```
 
-Supported frontends are Astro, HTML, React, Solid, Svelte, and Vue. Backend modules may use Go, Python, or Rust. `blinkhost init` detects supported metadata in an existing repository and creates `blinkhost.yaml` for review.
+Supported frontends are Astro, HTML, React, Solid, Svelte, and Vue. Backend modules may use Go, Python, or Rust. `blinkhost init` detects supported frontend metadata in an existing repository and creates `blinkhost.yaml` for review. Preview the exact result without writing anything first:
+
+```bash
+blinkhost init apps/storefront --dry-run --json
+```
+
+`init` writes only `blinkhost.yaml`, refuses an existing manifest unless `--force` is explicitly supplied, and never rewrites application source. It does not guess backend services; add existing Go, Python, or Rust modules explicitly to the reviewed manifest. One manifest describes one deployable application. In a monorepo, select the application directory, or place the manifest at a build-context root that contains the app and its shared workspace packages; use separate BlinkHost projects for independently deployable apps.
 
 Creation is atomic and refuses to replace an existing path. Dependency lifecycle scripts are disabled. Validation rejects unknown manifest fields, duplicate YAML keys, aliases, traversal, unsafe symbolic links, invalid cross-platform paths, duplicate module names, and missing declared inputs.
 
+When using `--no-install`, enter the generated directory, run the selected package manager's install command, then run `blinkhost test .`. For example:
+
+```bash
+blinkhost create study-circle --template astro --no-install
+cd study-circle
+npm install
+blinkhost test .
+```
+
 ## Remote workflows
 
 Resource commands use the same pattern:
@@ -101,7 +127,7 @@ Support bundles are local, redacted JSON files with mode `0600`. They exclude to
 
 ## CI and automation
 
-All commands support `--json`. Register one exact GitHub branch, tag, or protected environment as a workload identity, then grant the workflow `id-token: write`. The CLI exchanges GitHub's signed OIDC assertion for a ten-minute BlinkHost token automatically; no BlinkHost secret is stored in GitHub.
+All commands support `--json`. In JSON mode, stdout contains exactly one response object on success or failure; subprocess and human diagnostics use stderr. Register one exact GitHub branch, tag, or protected environment as a workload identity, then grant the workflow `id-token: write`. The CLI exchanges GitHub's signed OIDC assertion for a ten-minute BlinkHost token automatically; no BlinkHost secret is stored in GitHub.
 
 ```bash
 blinkhost workloads create --data @workload.json
@@ -129,6 +155,18 @@ blinkhost plugins run example -- arguments
 
 Update checks never install software. Plugins require explicit local approval, are pinned to their executable SHA-256 digest, stop when the executable changes, and receive neither BlinkHost credentials nor the parent environment. A plugin is still third-party code running with your operating-system account; review it before adding it.
 
+Pin or roll back explicitly with `npm install --global @blinkhost/cli@VERSION`. Tagged packages are published from the `blinkhost-ltd/blinkhost-cli` release workflow through npm Trusted Publishing with provenance. To verify a downloaded GitHub release, first run `sha256sum --check SHA256SUMS`, then verify its Sigstore bundle:
+
+```bash
+cosign verify-blob \
+  --bundle SHA256SUMS.sigstore.json \
+  --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.1.0" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  SHA256SUMS
+```
+
+The supported runtime is Node.js 22.12 or newer on Linux, macOS, and Windows, including x64 and arm64 environments where that Node release is available. Bash, Zsh, Fish, and PowerShell completion are generated by the CLI. For an offline installation, verify the package archive, checksum file, and Sigstore bundle on a connected machine, transfer them through an approved channel, then run `npm install --global ./blinkhost-cli-VERSION.tgz --offline`.
+
 ## Exit codes
 
 | Code | Meaning |

package/dist/api.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { activeProfile, writeConfig } from './config.js';
 import { deleteRefreshCredential, getRefreshCredential, setRefreshCredential } from './credentials.js';
 import { CliError, EXIT } from './errors.js';
+import { VERSION } from './version.js';
 const REQUEST_TIMEOUT_MS = 30_000;
 function messageFrom(payload, fallback) {
     if (payload && typeof payload === 'object') {
@@ -32,7 +33,7 @@ export async function publicRequest(apiOrigin, path, init = {}) {
             ...init,
             redirect: 'error',
             signal: controller.signal,
-            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': 'BlinkHost-CLI/2.0.0', ...Object.fromEntries(new Headers(init.headers).entries()) },
+            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': `BlinkHost-CLI/${VERSION}`, ...Object.fromEntries(new Headers(init.headers).entries()) },
         });
         return { response, data: await parseResponse(response) };
     }
@@ -105,13 +106,15 @@ export class ApiClient {
     async request(path, init = {}) {
         const headers = new Headers(init.headers);
         headers.set('Authorization', `Bearer ${this.accessToken}`);
-        headers.set('X-Request-ID', headers.get('X-Request-ID') || randomUUID());
+        const requestId = headers.get('X-Request-ID') || randomUUID();
+        headers.set('X-Request-ID', requestId);
         if (init.method && init.method !== 'GET' && !headers.has('Idempotency-Key'))
             headers.set('Idempotency-Key', randomUUID());
         const result = await publicRequest(this.profile.apiOrigin, path, { ...init, headers });
         if (!result.response.ok) {
             const exit = result.response.status === 401 || result.response.status === 403 ? EXIT.auth : result.response.status === 409 ? EXIT.conflict : EXIT.remote;
-            throw new CliError(messageFrom(result.data, `BlinkHost returned HTTP ${result.response.status}.`), exit, `api_${result.response.status}`);
+            const responseId = result.response.headers.get('x-request-id') || requestId;
+            throw new CliError(messageFrom(result.data, `BlinkHost returned HTTP ${result.response.status}.`), exit, `api_${result.response.status}`, [`Request ID: ${responseId}`]);
         }
         return result.data;
     }

package/dist/auth.js

@@ -5,7 +5,7 @@ import { activeProfile, validateApiOrigin, validateProfileName, writeConfig } fr
 import { deleteRefreshCredential, setRefreshCredential } from './credentials.js';
 import { ApiClient, publicRequest } from './api.js';
 import { CliError, EXIT } from './errors.js';
-const VERSION = '2.0.0';
+import { VERSION } from './version.js';
 const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 function openBrowser(url) {
     const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd.exe' : 'xdg-open';

package/dist/cli.js

@@ -13,45 +13,8 @@ import { login, logout } from './auth.js';
 import { activeProfile, readConfig, validateProfileName, writeConfig } from './config.js';
 import { openPreview, projectStatus, rawApi, readProjectLink, runRemote, runSecrets, syncProject, unlinkProject, uploadAsset, waitForRemote, writeProjectLink } from './remote.js';
 import { checkForUpdate, ciCheck, completion, observability, runDev, runPlugins, supportBundle, testProject } from './workflows.js';
-const VERSION = '2.0.0';
-const HELP = `BlinkHost CLI ${VERSION}
-
-Usage:
-  blinkhost create <project-name> [--template react] [--package-manager npm]
-                 [--module name:python] [--database APP_DB] [--no-install]
-  blinkhost init [path] [--force]
-  blinkhost validate [path]
-  blinkhost manifest [path]
-  blinkhost doctor [path]
-  blinkhost test [path]
-  blinkhost auth login|logout|status|sessions|revoke
-  blinkhost projects list|get|create|update|delete|action|link|current
-  blinkhost repositories|connections|previews|builds|deployments <action>
-  blinkhost modules|databases|bindings|assets|secrets <action>
-  blinkhost organizations|templates|approvals|handoffs|policies|workloads <action>
-  blinkhost dev [path] [--host HOST] [--port PORT]
-  blinkhost logs|metrics|analytics --project PROJECT_ID
-  blinkhost support bundle [--output PATH]
-  blinkhost completion bash|zsh|fish
-  blinkhost update check
-  blinkhost ci check
-  blinkhost plugins list|add|remove|verify|run
-  blinkhost api METHOD /api/customer/path/ [--data JSON_OR_@FILE]
-
-Global options:
-  --json       Return machine-readable output
-  --profile    Use a named account and API profile
-  --quiet      Suppress successful human-readable output
-  --verbose    Include safe diagnostic detail in errors
-  --no-color   Disable terminal colour (accepted for portable scripts)
-  --non-interactive  Never open a browser or prompt
-  --help       Show command help
-  --version    Show the CLI version
-
-Refresh credentials are stored only by the operating-system credential service.
-BlinkHost remains authoritative for roles, plan limits, approvals, builds, releases,
-deployments, and audit records. Secret values are accepted only through standard input.
-`;
+import { documentationIndex, documentationTopic, quickstart, renderTopHelp, renderTopic, searchDocumentation, TOP_LEVEL_COMMANDS } from './guidance.js';
+import { VERSION, supportedNodeVersion } from './version.js';
 let quietOutput = false;
 let verboseOutput = false;
 function terminalText(value) {
@@ -112,9 +75,13 @@ function parseModule(value) {
     }
     return { name, language: language };
 }
-async function runProcess(command, args, cwd) {
+async function runProcess(command, args, cwd, json = false) {
     return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { cwd, shell: false, stdio: 'inherit', env: { ...process.env, npm_config_ignore_scripts: 'true' } });
+        const child = spawn(command, args, { cwd, shell: false, stdio: json ? ['inherit', 'pipe', 'pipe'] : 'inherit', env: { ...process.env, npm_config_ignore_scripts: 'true' } });
+        if (json) {
+            child.stdout?.on('data', (chunk) => process.stderr.write(chunk));
+            child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+        }
         child.once('error', () => reject(new CliError(`The ${command} executable is not available.`, EXIT.filesystem, 'package_manager_unavailable')));
         child.once('exit', (code) => resolve(code ?? 1));
     });
@@ -141,7 +108,7 @@ async function commandCreate(args, json) {
     const install = !noInstall;
     assertNoUnknown(args);
     if (!SUPPORTED_FRONTENDS.includes(framework))
-        throw new CliError(`Unsupported template: ${framework}.`, EXIT.usage, 'invalid_template');
+        throw new CliError(`Unsupported template: ${framework}. Choose ${SUPPORTED_FRONTENDS.join(', ')}.`, EXIT.usage, 'invalid_template');
     if (!SUPPORTED_MANAGERS.includes(packageManager))
         throw new CliError(`Unsupported package manager: ${packageManager}.`, EXIT.usage, 'invalid_package_manager');
     if (database && !/^[A-Z][A-Z0-9_]{0,127}$/.test(database))
@@ -159,20 +126,45 @@ async function commandCreate(args, json) {
             yarn: ['install', '--mode=skip-build'],
             bun: ['install', '--ignore-scripts', '--no-progress'],
         };
-        const code = await runProcess(packageManager, installArgs[packageManager], target);
+        const code = await runProcess(packageManager, installArgs[packageManager], target, json);
         if (code !== 0)
             throw new CliError(`Dependency installation exited with code ${code}. The project files were kept.`, EXIT.filesystem, 'install_failed');
     }
-    emit({ ok: true, command: 'create', message: `Created ${name} at ${target}.`, data: { path: target, framework, modules: modules.length, installed: install && framework !== 'html' } }, json);
+    const nextSteps = !install && framework !== 'html' ? [`cd ${name}`, `${packageManager} install`, 'blinkhost test .', 'blinkhost dev .'] : [`cd ${name}`, 'blinkhost test .', ...(framework === 'html' ? [] : ['blinkhost dev .'])];
+    emit({ ok: true, command: 'create', message: `Created ${name} at ${target}.`, data: { path: target, framework, package_manager: packageManager, modules: modules.length, generated_files: [...scaffold.files.keys(), 'blinkhost.yaml'].sort(), installed: install && framework !== 'html', next_steps: nextSteps } }, json);
+}
+function commandSuggestion(command) {
+    const distance = (left, right) => {
+        const row = Array.from({ length: right.length + 1 }, (_, index) => index);
+        for (let i = 1; i <= left.length; i += 1) {
+            let previous = row[0];
+            row[0] = i;
+            for (let j = 1; j <= right.length; j += 1) {
+                const before = row[j];
+                row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (left[i - 1] === right[j - 1] ? 0 : 1));
+                previous = before;
+            }
+        }
+        return row[right.length];
+    };
+    const ranked = TOP_LEVEL_COMMANDS.map((candidate) => ({ candidate, distance: distance(command, candidate) })).sort((a, b) => a.distance - b.distance);
+    return ranked[0] && ranked[0].distance <= Math.max(2, Math.floor(command.length / 3)) ? ranked[0].candidate : null;
 }
 async function commandInit(args, json) {
     const force = takeFlag(args, '--force');
+    const dryRun = takeFlag(args, '--dry-run');
     const path = args.shift();
     assertNoUnknown(args);
+    if (force && dryRun)
+        throw new CliError('Choose either --force or --dry-run.', EXIT.usage, 'conflicting_options');
     const root = resolveLocalPath(path);
     const manifest = await detectManifest(root);
+    if (dryRun) {
+        emit({ ok: true, command: 'init', message: 'Detected a BlinkHost manifest without writing any files.', data: { path: root, framework: manifest.frontend.framework, written: false, manifest } }, json);
+        return;
+    }
     await writeManifest(root, manifest, force);
-    emit({ ok: true, command: 'init', message: `Created blinkhost.yaml in ${root}.`, data: { path: root, framework: manifest.frontend.framework } }, json);
+    emit({ ok: true, command: 'init', message: `Created blinkhost.yaml in ${root}.`, data: { path: root, framework: manifest.frontend.framework, written: true, changed_files: ['blinkhost.yaml'] } }, json);
 }
 async function commandValidate(args, json) {
     const path = args.shift();
@@ -235,18 +227,78 @@ export async function main(argv = process.argv.slice(2)) {
     const profile = takeOption(args, '--profile');
     const command = args.shift();
     try {
-        if (!command || command === '--help' || command === 'help') {
-            process.stdout.write(HELP);
+        const helpRequested = takeFlag(args, '--help');
+        if (!command || command === '--help') {
+            if (json)
+                emit({ ok: true, command: 'help', message: 'BlinkHost CLI command index.', data: documentationIndex() }, true);
+            else
+                process.stdout.write(renderTopHelp());
             return EXIT.success;
         }
         if (command === '--version' || command === 'version') {
-            process.stdout.write(`${VERSION}\n`);
+            if (json)
+                emit({ ok: true, command: 'version', message: `BlinkHost CLI ${VERSION}.`, data: { version: VERSION } }, true);
+            else
+                process.stdout.write(`${VERSION}\n`);
             return EXIT.success;
         }
-        if (takeFlag(args, '--help')) {
-            process.stdout.write(HELP);
+        if (command === 'help' || helpRequested) {
+            const requested = command === 'help' ? args.shift() : command;
+            assertNoUnknown(args);
+            if (!requested) {
+                if (json)
+                    emit({ ok: true, command: 'help', message: 'BlinkHost CLI command index.', data: documentationIndex() }, true);
+                else
+                    process.stdout.write(renderTopHelp());
+            }
+            else {
+                const topic = documentationTopic(requested);
+                if (!topic)
+                    throw new CliError(`No help is available for ${requested}. Run \`blinkhost docs\` to list topics.`, EXIT.usage, 'unknown_help_topic');
+                if (json)
+                    emit({ ok: true, command: `help ${requested}`, message: `${topic.title}.`, data: { schema: 'blinkhost/cli-docs/v1', cli_version: VERSION, topic } }, true);
+                else
+                    process.stdout.write(renderTopic(topic));
+            }
             return EXIT.success;
         }
+        if (command === 'docs') {
+            const search = takeOption(args, '--search');
+            const topicName = args.shift();
+            assertNoUnknown(args);
+            if (search && topicName)
+                throw new CliError('Choose a documentation topic or --search, not both.', EXIT.usage, 'conflicting_options');
+            if (search) {
+                const results = searchDocumentation(search);
+                if (json)
+                    emit({ ok: true, command: 'docs search', message: `${results.length} documentation topic(s) matched.`, data: { schema: 'blinkhost/cli-docs/v1', cli_version: VERSION, query: search, results } }, true);
+                else
+                    process.stdout.write(results.length ? results.map(renderTopic).join('\n') : `No offline documentation matched “${terminalText(search)}”.\n`);
+            }
+            else if (topicName) {
+                const topic = documentationTopic(topicName);
+                if (!topic)
+                    throw new CliError(`Unknown documentation topic: ${topicName}. Run \`blinkhost docs\` to list topics.`, EXIT.usage, 'unknown_docs_topic');
+                if (json)
+                    emit({ ok: true, command: `docs ${topicName}`, message: `${topic.title}.`, data: { schema: 'blinkhost/cli-docs/v1', cli_version: VERSION, topic } }, true);
+                else
+                    process.stdout.write(renderTopic(topic));
+            }
+            else if (json)
+                emit({ ok: true, command: 'docs', message: 'Offline documentation index.', data: documentationIndex() }, true);
+            else
+                process.stdout.write(renderTopHelp());
+            return EXIT.success;
+        }
+        if (command === 'quickstart') {
+            const path = args.shift();
+            assertNoUnknown(args);
+            const data = await quickstart(path);
+            emit({ ok: true, command, message: 'Local BlinkHost readiness check completed. No remote changes were made.', data }, json);
+            return EXIT.success;
+        }
+        if (!supportedNodeVersion())
+            throw new CliError(`Node.js ${process.versions.node} is unsupported. Install Node.js 22.12 or newer. Help, docs and quickstart remain available.`, EXIT.filesystem, 'unsupported_node');
         if (profile)
             validateProfileName(profile);
         if (command === 'create')
@@ -260,7 +312,7 @@ export async function main(argv = process.argv.slice(2)) {
         else if (command === 'doctor')
             await commandDoctor(args, json);
         else if (command === 'test') {
-            const data = await testProject(args);
+            const data = await testProject(args, json);
             emit({ ok: true, command, message: 'Project checks passed.', data }, json);
         }
         else if (command === 'auth') {
@@ -360,8 +412,8 @@ export async function main(argv = process.argv.slice(2)) {
         }
         else if (command === 'previews' && args[0] === 'open') {
             args.shift();
-            const data = await openPreview(args, profile);
-            emit({ ok: true, command: 'previews open', message: 'Opened the preview in your browser.', data }, json);
+            const data = await openPreview(args, profile, !nonInteractive);
+            emit({ ok: true, command: 'previews open', message: nonInteractive ? 'Preview URL loaded without opening a browser.' : 'Opened the preview in your browser.', data }, json);
         }
         else if ((command === 'builds' || command === 'deployments' || command === 'previews') && args[0] === 'wait') {
             args.shift();
@@ -382,7 +434,7 @@ export async function main(argv = process.argv.slice(2)) {
             emit({ ok: true, command, message: 'Secret operation completed.', data }, json);
         }
         else if (command === 'dev') {
-            const data = await runDev(args);
+            const data = await runDev(args, json);
             emit({ ok: true, command, message: 'Local development process finished.', data }, json);
         }
         else if (command === 'logs' || command === 'metrics' || command === 'analytics') {
@@ -412,21 +464,23 @@ export async function main(argv = process.argv.slice(2)) {
             emit({ ok: true, command: 'ci check', message: 'CI identity and API capabilities are ready.', data }, json);
         }
         else if (command === 'plugins') {
-            const data = await runPlugins(args);
+            const data = await runPlugins(args, json);
             emit({ ok: true, command, message: 'Plugin operation completed.', data }, json);
         }
         else if (command === 'api') {
             const data = await rawApi(args, profile);
             emit({ ok: true, command, message: 'API request completed.', data }, json);
         }
-        else
-            throw new CliError(`Unknown command: ${command}.`, EXIT.usage, 'unknown_command');
+        else {
+            const suggestion = commandSuggestion(command);
+            throw new CliError(`Unknown command: ${command}.${suggestion ? ` Did you mean \`${suggestion}\`?` : ' Run `blinkhost docs` to list commands.'}`, EXIT.usage, 'unknown_command');
+        }
         return EXIT.success;
     }
     catch (error) {
         const failure = error instanceof CliError ? error : new CliError(error instanceof Error ? error.message : String(error), EXIT.internal, 'internal_error');
         if (json)
-            process.stderr.write(`${JSON.stringify({ ok: false, command: command ?? '', error: { code: failure.code, message: failure.message, details: failure.details } })}\n`);
+            process.stdout.write(`${JSON.stringify({ ok: false, command: command ?? '', error: { code: failure.code, message: failure.message, details: failure.details } })}\n`);
         else {
             process.stderr.write(`Error: ${terminalText(failure.message)}\n`);
             for (const detail of failure.details)

package/dist/credentials.d.ts

@@ -1,3 +1,10 @@
+export interface CredentialStoreStatus {
+    available: boolean;
+    provider: 'macos-keychain' | 'windows-password-vault' | 'linux-secret-service';
+    remediation: string | null;
+}
+/** Checks only whether the platform credential service can be invoked. */
+export declare function credentialStoreStatus(): Promise<CredentialStoreStatus>;
 export declare function getRefreshCredential(profile: string): Promise<string | null>;
 export declare function setRefreshCredential(profile: string, token: string): Promise<void>;
 export declare function deleteRefreshCredential(profile: string): Promise<void>;

package/dist/credentials.js

@@ -1,6 +1,26 @@
 import { spawn } from 'node:child_process';
 import { CliError, EXIT } from './errors.js';
 const SERVICE = 'blinkhost-cli';
+async function executableAvailable(command, args) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { shell: false, stdio: 'ignore', windowsHide: true });
+        child.once('error', () => resolve(false));
+        child.once('exit', (code) => resolve(code === 0));
+    });
+}
+/** Checks only whether the platform credential service can be invoked. */
+export async function credentialStoreStatus() {
+    if (process.platform === 'darwin') {
+        const available = await executableAvailable('security', ['help']);
+        return { available, provider: 'macos-keychain', remediation: available ? null : 'Restore the macOS security command before interactive sign-in.' };
+    }
+    if (process.platform === 'win32') {
+        const available = await executableAvailable('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]']);
+        return { available, provider: 'windows-password-vault', remediation: available ? null : 'Use Windows with PowerShell and Password Vault available.' };
+    }
+    const available = await executableAvailable('secret-tool', ['--version']);
+    return { available, provider: 'linux-secret-service', remediation: available ? null : 'Install libsecret tools and start an unlocked Secret Service session, or use a short-lived workload identity in headless automation.' };
+}
 async function run(command, args, input, acceptMissing = false) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { shell: false, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });

package/dist/guidance.d.ts

@@ -0,0 +1,27 @@
+export interface DocumentationTopic {
+    name: string;
+    title: string;
+    summary: string;
+    usage: string[];
+    details: string[];
+    examples: string[];
+    related: string[];
+    url: string;
+}
+export declare const TOP_LEVEL_COMMANDS: ("plugins" | "profile" | "modules" | "dev" | "databases" | "secrets" | "manifest" | "projects" | "repositories" | "connections" | "previews" | "builds" | "deployments" | "bindings" | "assets" | "organizations" | "templates" | "approvals" | "handoffs" | "policies" | "workloads" | "create" | "update" | "quickstart" | "init" | "doctor" | "auth" | "validate" | "test" | "ci" | "logs" | "support" | "metrics" | "analytics" | "completion" | "api" | "docs")[];
+export declare function documentationIndex(): {
+    schema: string;
+    cli_version: string;
+    documentation_url: string;
+    topics: Array<{
+        name: string;
+        title: string;
+        summary: string;
+        url: string;
+    }>;
+};
+export declare function documentationTopic(name: string): DocumentationTopic | undefined;
+export declare function searchDocumentation(query: string): DocumentationTopic[];
+export declare function renderTopic(topic: DocumentationTopic): string;
+export declare function renderTopHelp(): string;
+export declare function quickstart(path?: string): Promise<Record<string, unknown>>;

package/dist/guidance.js

@@ -0,0 +1,256 @@
+import { spawn } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { credentialStoreStatus } from './credentials.js';
+import { SUPPORTED_FRONTENDS, SUPPORTED_MANAGERS, SUPPORTED_MODULES } from './manifest.js';
+import { resolveLocalPath, validateProject } from './project.js';
+import { DOCUMENTATION_URL, RELEASES_URL, VERSION, supportedNodeVersion } from './version.js';
+const resource = (name, summary, extra = []) => ({
+    name,
+    title: `${name[0].toUpperCase()}${name.slice(1)} commands`,
+    summary,
+    usage: [
+        `blinkhost ${name} list [--query name=value]`,
+        `blinkhost ${name} get ID`,
+        `blinkhost ${name} create --data @request.json`,
+        `blinkhost ${name} update ID --data @request.json`,
+        `blinkhost ${name} delete ID --confirm ID`,
+        `blinkhost ${name} action ID ACTION --data @request.json`,
+    ],
+    details: [
+        'List and get are read-only. Create, update, delete and action send remote requests to the active BlinkHost workspace.',
+        'Workspace roles, plan limits, protected-environment approvals, verified-artifact requirements and audit records remain enforced by BlinkHost.',
+        'Deletion requires the exact resource ID through --confirm. JSON request files must be regular files no larger than 1 MiB.',
+        ...extra,
+    ],
+    examples: [`blinkhost ${name} list --json`, `blinkhost ${name} get RESOURCE_ID --json`],
+    related: ['auth', 'automation', 'limits', 'troubleshooting'],
+    url: DOCUMENTATION_URL,
+});
+const TOPICS = {
+    quickstart: {
+        name: 'quickstart', title: 'Safe first steps', summary: 'Inspect local readiness and receive a non-destructive path to your first BlinkHost project.',
+        usage: ['blinkhost quickstart [path]', 'blinkhost quickstart [path] --json'],
+        details: ['Quickstart performs local checks only. It does not sign in, create cloud resources, deploy, upload source, or incur usage.', 'Use create for a new project or init to adopt an existing repository. Review blinkhost.yaml before linking a remote project.'],
+        examples: ['blinkhost quickstart', 'blinkhost create my-app --template astro --no-install', 'blinkhost init ./existing-app'], related: ['create', 'init', 'doctor', 'auth'], url: DOCUMENTATION_URL,
+    },
+    create: {
+        name: 'create', title: 'Create a local project', summary: 'Generate an atomic BlinkHost project scaffold without changing remote resources.',
+        usage: ['blinkhost create NAME [--template FRAMEWORK] [--package-manager MANAGER] [--module NAME:LANGUAGE] [--database BINDING] [--install|--no-install]'],
+        details: [`Frameworks: ${SUPPORTED_FRONTENDS.join(', ')}.`, `Package managers: ${SUPPORTED_MANAGERS.join(', ')}.`, `Backend module languages: ${SUPPORTED_MODULES.join(', ')}.`, 'The default template is react and the default package manager is npm. Existing paths are never overwritten. Dependency lifecycle scripts are disabled during installation.', 'Creation is local only; it does not create a BlinkHost project, database, preview, deployment, or billable resource.'],
+        examples: ['blinkhost create my-app --template astro', 'blinkhost create my-app --template react --module api:rust --module jobs:python --database APP_DB --no-install'], related: ['quickstart', 'validate', 'projects', 'manifest-reference'], url: DOCUMENTATION_URL,
+    },
+    init: {
+        name: 'init', title: 'Adopt an existing repository', summary: 'Detect supported project metadata and write a reviewable blinkhost.yaml.',
+        usage: ['blinkhost init [path] [--dry-run|--force]'],
+        details: ['Detection reads package.json dependencies and the pnpm, Yarn, Bun or npm lockfile at the selected application root. It recognizes Astro, React, Vue, Svelte and Solid; a directory without recognized framework metadata is described as static HTML.', '`--dry-run` returns the proposed manifest and writes nothing. Without it, init writes only blinkhost.yaml and refuses an existing manifest. `--force` replaces only an existing regular blinkhost.yaml after explicit use; application source and configuration are never rewritten.', 'Detection does not guess backend services. Review the proposal and add each Go, Python or Rust module explicitly before validation.', 'One manifest represents one deployable application. For a nested app, pass that directory. For a workspace app that imports shared packages, place the manifest at a root containing the complete build context and set frontend.root and frontend.dependency_root explicitly. Use separate application roots and BlinkHost projects for independently deployable monorepo applications.'],
+        examples: ['blinkhost init . --dry-run --json', 'blinkhost init apps/storefront', 'blinkhost docs manifest-reference'], related: ['validate', 'manifest-reference', 'projects'], url: DOCUMENTATION_URL,
+    },
+    validate: {
+        name: 'validate', title: 'Validate project compatibility', summary: 'Check the manifest, declared files, path safety and dependency metadata without building or uploading.',
+        usage: ['blinkhost validate [path]'],
+        details: ['Validation rejects unknown fields, duplicate YAML keys, aliases, traversal, unsafe symbolic links, reserved cross-platform paths, duplicate modules and missing declared inputs.', 'Warnings identify non-blocking portability or reproducibility concerns such as a missing lockfile.'],
+        examples: ['blinkhost validate', 'blinkhost validate apps/storefront --json'], related: ['manifest-reference', 'doctor', 'test'], url: DOCUMENTATION_URL,
+    },
+    manifest: {
+        name: 'manifest', title: 'Read the normalized project manifest', summary: 'Parse and print blinkhost.yaml after applying its strict schema rules.',
+        usage: ['blinkhost manifest [path]'], details: ['Use --json to wrap the normalized manifest in the stable CLI response envelope. Secret values are never valid manifest fields.'], examples: ['blinkhost manifest --json'], related: ['manifest-reference', 'validate'], url: DOCUMENTATION_URL,
+    },
+    doctor: {
+        name: 'doctor', title: 'Check the local toolchain', summary: 'Verify Node.js, Git, the selected directory and its BlinkHost manifest.',
+        usage: ['blinkhost doctor [path]'], details: ['Doctor is local and non-destructive. Quickstart additionally explains authentication prerequisites and next steps.'], examples: ['blinkhost doctor . --json'], related: ['quickstart', 'validate', 'portability'], url: DOCUMENTATION_URL,
+    },
+    test: {
+        name: 'test', title: 'Run project checks', summary: 'Validate the project and run its test script, or its build script when no test script exists.',
+        usage: ['blinkhost test [path]'], details: ['Static HTML projects require validation only. JavaScript dependencies must be installed first.', 'With --json, stdout contains exactly one JSON response; child-process diagnostics are sent to stderr.'], examples: ['blinkhost test .', 'blinkhost test . --json'], related: ['validate', 'automation', 'troubleshooting'], url: DOCUMENTATION_URL,
+    },
+    auth: {
+        name: 'auth', title: 'Authentication and sessions', summary: 'Connect a device through browser approval and manage its CLI sessions.',
+        usage: ['blinkhost auth login [--no-browser] [--api-origin URL]', 'blinkhost auth status', 'blinkhost auth sessions', 'blinkhost auth revoke SESSION_ID', 'blinkhost auth logout'],
+        details: ['Passwords are never entered in the terminal. Refresh credentials are stored only in macOS Keychain, Windows Password Vault, or Linux Secret Service through secret-tool.', 'Headless automation should use a registered GitHub OIDC workload or a short-lived BLINKHOST_ACCESS_TOKEN supplied by an approved CI secret service. Never persist it in source or CLI configuration.', '--non-interactive prevents browser authorization and fails closed when interaction would be required.'],
+        examples: ['blinkhost auth login', 'blinkhost auth login --no-browser', 'blinkhost auth sessions --json'], related: ['profile', 'ci', 'security', 'portability'], url: DOCUMENTATION_URL,
+    },
+    profile: {
+        name: 'profile', title: 'Account profiles', summary: 'Keep personal and work BlinkHost sessions separate.',
+        usage: ['blinkhost profile list', 'blinkhost profile use NAME'], details: ['--profile NAME selects a profile for one command. BLINKHOST_PROFILE selects a default for the current process. Profile names contain lowercase letters, numbers, hyphens or underscores.'], examples: ['blinkhost auth login --profile work', 'blinkhost profile use work'], related: ['auth', 'security'], url: DOCUMENTATION_URL,
+    },
+    projects: resource('projects', 'Manage projects and explicit local project links.', ['`projects link PROJECT_ID [path]` writes only a local .blinkhost/project.json pointer and does not change or deploy the remote project.', '`projects unlink [path]` removes only that local pointer. `projects pull|push CONNECTION_ID` synchronizes through a configured source connection.']),
+    repositories: resource('repositories', 'Inspect and manage connected source repositories.'),
+    connections: resource('connections', 'Manage project-to-repository source connections.'),
+    previews: resource('previews', 'Manage temporary preview environments.', ['`previews wait ID [--timeout 10..3600]` waits for a terminal state. `previews open ID` accepts only trusted BlinkHost HTTPS preview hosts. Preview operations can consume plan resources.']),
+    builds: resource('builds', 'Create, inspect and wait for verified builds.', ['`builds wait ID [--timeout 10..3600]` stops on success, failure, cancellation, expiry or timeout. Builds can consume plan resources.']),
+    deployments: resource('deployments', 'Manage production deployments and protected release actions.', ['Rollback uses `deployments action DEPLOYMENT_ID rollback --data @rollback.json`. Protected environments can require approval and a verified artifact. Deployment operations can consume plan resources.']),
+    modules: resource('modules', 'Manage Rust, Go and Python backend modules.'),
+    databases: resource('databases', 'Manage database resources.', ['Database list, get, create, update, delete and supported server actions are remote and may require plan capacity or protected-environment approval.', 'CLI v2.1 does not invent local backup, restore, credential-rotation or migration semantics. Use only actions returned by the active workspace API and consult the detailed database guide before production data changes. Deletion retains exact-ID confirmation and server authorization.']),
+    bindings: resource('bindings', 'Manage explicit application-to-resource bindings.'),
+    assets: resource('assets', 'Manage project assets.', ['Upload with `assets upload FILE --project PROJECT_ID [--parent ID] [--revision VALUE] [--replace ID]`. Uploads accept listed image, font, MP3 and MP4 types, reject symbolic links, verify SHA-256 and count against plan storage.']),
+    organizations: resource('organizations', 'Manage organizations within the permissions granted to your account.'),
+    templates: resource('templates', 'Inspect and manage verified source templates.'),
+    approvals: resource('approvals', 'Inspect and act on deployment approvals within your role.'),
+    handoffs: resource('handoffs', 'Manage explicit agency handoffs and their audit trail.'),
+    policies: resource('policies', 'Inspect and manage enterprise policies within authorized workspaces.'),
+    workloads: resource('workloads', 'Register narrowly scoped automation identities.', ['Use an exact GitHub branch, tag or protected-environment subject. Workload tokens are short-lived and do not replace workspace authorization.']),
+    secrets: {
+        name: 'secrets', title: 'Project secrets', summary: 'List, set, rotate and delete secret records without placing values in arguments.',
+        usage: ['blinkhost secrets list --project PROJECT_ID', "printf '%s' \"$VALUE\" | blinkhost secrets set NAME --project PROJECT_ID [--environment SCOPE] [--expires-in-days DAYS]", "printf '%s' \"$VALUE\" | blinkhost secrets rotate SECRET_ID", 'blinkhost secrets delete SECRET_ID --confirm SECRET_ID'],
+        details: ['Values are read only from standard input, limited to 64 KiB and never written to blinkhost.yaml. Disable shell tracing around secret input and use masked variables or an approved secret manager in CI.', 'List responses do not return secret values. Authorization and workspace scope are enforced by the API.'], examples: ["set +x; printf '%s' \"$API_TOKEN\" | blinkhost secrets set API_TOKEN --project PROJECT_ID"], related: ['security', 'automation'], url: DOCUMENTATION_URL,
+    },
+    dev: {
+        name: 'dev', title: 'Local development', summary: 'Run the manifest-declared frontend development process.', usage: ['blinkhost dev [path] [--host HOST] [--port PORT]'], details: ['This starts the local frontend process and sets BLINKHOST_LOCAL=1. It does not deploy a release. Static HTML projects should use a local static-file server.', 'Install dependencies first. Production bindings are not automatically exposed to local processes.'], examples: ['blinkhost dev . --host 127.0.0.1 --port 3000'], related: ['quickstart', 'test', 'previews'], url: DOCUMENTATION_URL,
+    },
+    logs: {
+        name: 'logs', title: 'Project observability', summary: 'Read authorized logs, metrics or analytics for a linked or explicit project.', usage: ['blinkhost logs [--project ID] [--since DURATION] [--limit COUNT]', 'blinkhost metrics [--project ID] [--since DURATION]', 'blinkhost analytics [--project ID]'], details: ['These commands are read-only and access is workspace-scoped.', 'Treat application logs as potentially sensitive. The CLI does not claim that arbitrary secrets written by application code can always be detected or redacted, so review output before sharing it. Use the redacted support bundle for platform diagnostics.', 'The service remains authoritative for retention, pagination, platform-managed filtering and audit access. Do not deliberately log credentials or personal data.'], examples: ['blinkhost logs --project PROJECT_ID --since 1h --limit 100 --json'], related: ['security', 'support', 'troubleshooting'], url: DOCUMENTATION_URL,
+    },
+    metrics: { name: 'metrics', title: 'Project metrics', summary: 'Read authorized metrics for a project.', usage: ['blinkhost metrics [--project ID] [--since DURATION]'], details: ['The command is read-only and accepts a linked project when --project is omitted.'], examples: ['blinkhost metrics --project PROJECT_ID --since 24h --json'], related: ['logs'], url: DOCUMENTATION_URL },
+    analytics: { name: 'analytics', title: 'Project analytics', summary: 'Read authorized analytics for a project.', usage: ['blinkhost analytics [--project ID]'], details: ['The command is read-only and accepts a linked project when --project is omitted.'], examples: ['blinkhost analytics --project PROJECT_ID --json'], related: ['logs'], url: DOCUMENTATION_URL },
+    support: {
+        name: 'support', title: 'Redacted support bundles', summary: 'Create a local diagnostic inventory for support without including source or credentials.', usage: ['blinkhost support bundle [--output PATH]'], details: ['The file is created with mode 0600 and refuses to overwrite an existing path. It excludes tokens, secret values, source code, filenames and repository URLs.', 'Review the generated file before sharing it. The default filename is blinkhost-support-<timestamp>.json in the current directory.'], examples: ['blinkhost support bundle', 'blinkhost support bundle --output ./support.json'], related: ['security', 'troubleshooting'], url: DOCUMENTATION_URL,
+    },
+    completion: {
+        name: 'completion', title: 'Shell completion', summary: 'Generate deterministic completion for Bash, Zsh, Fish or PowerShell.', usage: ['blinkhost completion bash|zsh|fish|powershell'], details: ['The command prints a script to standard output; source or install it using your shell configuration.'], examples: ['source <(blinkhost completion bash)', 'blinkhost completion zsh > ~/.zfunc/_blinkhost'], related: ['portability'], url: DOCUMENTATION_URL,
+    },
+    update: {
+        name: 'update', title: 'Check for CLI updates', summary: 'Compare this CLI version with the latest signed GitHub release.', usage: ['blinkhost update check'], details: ['The command reports an update but never installs one automatically. Pin a version with `npm install --global @blinkhost/cli@VERSION`; roll back with the same command and an earlier reviewed version.'], examples: ['blinkhost update check --json'], related: ['supply-chain'], url: DOCUMENTATION_URL,
+    },
+    ci: {
+        name: 'ci', title: 'CI readiness', summary: 'Verify the active workload identity and server-reported CLI capabilities.', usage: ['blinkhost ci check'], details: ['GitHub Actions should use an exact registered OIDC subject and id-token: write. No long-lived BlinkHost token is required.', 'Other CI systems may provide a short-lived BLINKHOST_ACCESS_TOKEN from an approved secret service; never commit or print it.'], examples: ['blinkhost ci check --non-interactive --json'], related: ['automation', 'auth', 'workloads'], url: DOCUMENTATION_URL,
+    },
+    plugins: {
+        name: 'plugins', title: 'Local CLI plugins', summary: 'Approve and run local executables with digest pinning and a restricted environment.', usage: ['blinkhost plugins list', 'blinkhost plugins add /absolute/path --name NAME', 'blinkhost plugins verify NAME', 'blinkhost plugins run NAME -- ARGS', 'blinkhost plugins remove NAME'], details: ['Plugins must be regular files, not symbolic links. BlinkHost records the SHA-256 digest and refuses changed executables until reviewed and added again.', 'Plugins receive only a small allowlist of process variables and never receive BlinkHost credentials. They still run with your operating-system account, so review them first.'], examples: ['blinkhost plugins verify formatter --json'], related: ['security'], url: DOCUMENTATION_URL,
+    },
+    api: {
+        name: 'api', title: 'Advanced customer API access', summary: 'Call supported customer API routes when a dedicated command is unavailable.', usage: ['blinkhost api GET /api/customer/path/', 'blinkhost api POST /api/customer/path/ --data @request.json'], details: ['Internal, staff, authentication and secret-bearing mutation routes are blocked. Absolute URLs, traversal, encoded paths and unsupported methods are rejected.', 'Prefer dedicated commands because they provide stronger validation and clearer safety boundaries.'], examples: ['blinkhost api GET /api/sites/ --json'], related: ['automation', 'security'], url: DOCUMENTATION_URL,
+    },
+    automation: {
+        name: 'automation', title: 'Automation contract', summary: 'Use deterministic output and short-lived identity safely from CI or coding agents.', usage: ['blinkhost COMMAND --json --non-interactive', 'blinkhost docs commands --json'], details: ['With --json, stdout is one JSON object for success or failure. Human and child-process diagnostics go to stderr. Exit codes, envelope fields and documented error codes remain stable within the v2 major line; service-specific data objects may add fields, so consumers must ignore unknown fields.', 'Mutating API requests carry a request ID and an idempotency key. A fresh key is generated for each CLI invocation. A timeout is not proof of failure: use the resource ID or request ID from output, list/get/status, and wait commands to reconcile state before starting a new mutation.', '`--non-interactive` prevents account authorization and preview commands from opening a browser. Never disable approvals, confirmation checks, workspace roles or plan controls in automation.'], examples: ['blinkhost validate . --json --non-interactive', 'blinkhost ci check --json --non-interactive'], related: ['exit-codes', 'ci', 'security', 'troubleshooting'], url: DOCUMENTATION_URL,
+    },
+    security: {
+        name: 'security', title: 'CLI security boundaries', summary: 'Understand credential, secret, plugin, path and remote-action safeguards.', usage: ['blinkhost docs security'], details: ['Passwords never enter the CLI. Refresh credentials require an operating-system credential service; CI uses short-lived identities.', 'Secret values enter only through stdin. Local project and payload files reject unsafe symbolic links and bounded inputs are enforced.', 'Remote roles, limits, approvals, verified artifacts and audit records remain server-enforced. CLI output must not be treated as a way around platform policy.'], examples: ['blinkhost auth sessions --json', 'blinkhost plugins verify NAME --json'], related: ['auth', 'secrets', 'plugins', 'supply-chain'], url: DOCUMENTATION_URL,
+    },
+    glossary: {
+        name: 'glossary', title: 'BlinkHost terminology', summary: 'Translate platform terms into the developer actions they represent.', usage: ['blinkhost docs glossary'],
+        details: ['Project: one deployable application and its resources. Module: a Go, Python or Rust backend service declared by that project. Binding: an explicit connection between application code and a managed resource.', 'Preview: a temporary environment for reviewing a change. Build: compilation and verification of source. Deployment: promotion of a verified artifact to an environment.', 'Profile: a local named account configuration. Workload: a narrowly scoped short-lived automation identity. Approval: a required authorized decision before a protected action. Handoff: an audited transfer of agency or team responsibility.'],
+        examples: ['blinkhost docs manifest-reference', 'blinkhost docs limits'], related: ['commands', 'manifest-reference'], url: DOCUMENTATION_URL,
+    },
+    portability: {
+        name: 'portability', title: 'Supported environments', summary: 'Prepare Linux, macOS, Windows and headless automation environments.', usage: ['blinkhost quickstart --json'], details: ['Node.js 22.12 or newer is required on Linux, macOS and Windows. npm may warn rather than block an unsupported Node version, so the CLI checks again before operational commands.', 'macOS uses Keychain through the security command. Windows uses Password Vault through PowerShell. Linux uses Secret Service through secret-tool and requires an available desktop or session keyring.', 'Headless CI should use a registered GitHub OIDC workload or a short-lived access token supplied at runtime. Plaintext refresh-token storage is intentionally unsupported.', 'For offline installation, download the package archive, SHA256SUMS and Sigstore bundle on a connected machine; verify them, transfer all files through an approved channel, then run `npm install --global ./blinkhost-cli-VERSION.tgz --offline`.'], examples: ['node --version', 'blinkhost quickstart --json'], related: ['auth', 'ci', 'completion', 'supply-chain'], url: DOCUMENTATION_URL,
+    },
+    'manifest-reference': {
+        name: 'manifest-reference', title: 'blinkhost.yaml reference', summary: 'Describe one application, frontend, backend modules and declared resources with schema blinkhost/v1.', usage: ['blinkhost manifest [path] --json', 'blinkhost validate [path] --json'], details: ['Top-level fields are schema, application, frontend, modules, resources, preview and ignore. Unknown fields are rejected.', `Frontend frameworks: ${SUPPORTED_FRONTENDS.join(', ')}. Package managers: ${SUPPORTED_MANAGERS.join(', ')}. Module languages: ${SUPPORTED_MODULES.join(', ')}.`, 'Paths are repository-relative POSIX paths. Values, aliases, traversal, symbolic-link escapes and platform-reserved segments are rejected. One manifest represents one BlinkHost application; use separate application roots and projects for multiple deployable applications in a monorepo.'], examples: ['blinkhost init apps/web', 'blinkhost validate apps/web --json'], related: ['init', 'validate', 'security'], url: DOCUMENTATION_URL,
+    },
+    limits: {
+        name: 'limits', title: 'Limits and cost boundaries', summary: 'Separate local CLI work from server-enforced plan usage.', usage: ['blinkhost docs limits'], details: ['quickstart, create, init, validate, manifest, doctor, local test and local dev do not create BlinkHost cloud resources.', 'Remote previews, builds, deployments, databases, assets and modules can consume plan capacity. Exact quotas and prices come from the active workspace and current pricing page; the CLI does not guess or hard-code them.', 'Use list/get/status commands to inspect existing state before a mutation. Protected operations may require approval.'], examples: ['blinkhost projects status --json', 'blinkhost auth status --json'], related: ['quickstart', 'automation', 'deployments'], url: 'https://app.blinkhost.me/pricing',
+    },
+    troubleshooting: {
+        name: 'troubleshooting', title: 'Failure and recovery guidance', summary: 'Recover safely from local, authentication, network and remote-operation failures.', usage: ['blinkhost doctor [path] --json', 'blinkhost support bundle'], details: ['Exit 2 means command usage, 3 validation, 4 local filesystem/tooling, 6 authentication/permission, 7 network/timeout, 8 remote failure, and 9 conflict or approval required.', 'The CLI does not automatically retry general remote mutations. Asset completion alone retries a temporary conflict for a bounded period. For a timeout, query the resource before retrying because the server may have completed the request; a new CLI invocation receives a new idempotency key.', 'Resume build, deployment or preview polling with `GROUP wait ID`; use list, get or status plus the request ID returned in an API error to reconcile uncertain state. There is no generic local resume for an interrupted upload or multi-resource sequence.', 'Missing dependencies: run the package manager install command, commit the lockfile, then retry test. Expired sessions: sign in again. Approval-required operations: complete the workspace approval rather than bypassing it.'], examples: ['blinkhost doctor . --json', 'blinkhost deployments get DEPLOYMENT_ID --json', 'blinkhost builds wait BUILD_ID --json'], related: ['support', 'automation', 'auth'], url: DOCUMENTATION_URL,
+    },
+    errors: {
+        name: 'errors', title: 'Error and compatibility contract', summary: 'Interpret stable CLI failures without parsing human prose.', usage: ['blinkhost COMMAND --json --non-interactive', 'blinkhost docs exit-codes'], details: ['Failure JSON has ok=false, command, and error with code, message and details. Details may gain entries; automation should branch on error.code and the process exit code, not message text.', 'Usage errors use exit 2, project/input validation 3, local tooling 4, unexpected CLI failures 5, authentication/authorization 6, network/timeouts 7, remote-service failures 8, and conflicts or required approvals 9.', 'HTTP failures include a request ID in details for support correlation. Secret values, authorization headers and refresh credentials are never intentionally added to CLI errors. Child-process output is sent to stderr in JSON mode and can contain whatever the child tool emits, so do not run untrusted scripts or print secrets from build scripts.'], examples: ['blinkhost creat --json', 'blinkhost validate . --json'], related: ['exit-codes', 'automation', 'security'], url: DOCUMENTATION_URL,
+    },
+    'supply-chain': {
+        name: 'supply-chain', title: 'Release verification', summary: 'Verify npm provenance or the signed GitHub release evidence.', usage: ['npm install --global @blinkhost/cli@VERSION'], details: ['Tagged releases publish from blinkhost-ltd/blinkhost-cli through the release.yml GitHub Actions workflow and npm Trusted Publishing.', 'Each GitHub release contains the package archive, CycloneDX SBOM, SHA256SUMS and SHA256SUMS.sigstore.json. Verify the checksum before installing an archive.', `Release evidence: ${RELEASES_URL}`], examples: ['sha256sum --check SHA256SUMS', `cosign verify-blob --bundle SHA256SUMS.sigstore.json --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v${VERSION}" --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS`], related: ['update', 'security'], url: RELEASES_URL,
+    },
+    'exit-codes': {
+        name: 'exit-codes', title: 'Exit codes and JSON responses', summary: 'Build deterministic scripts around stable outcome categories.', usage: ['blinkhost COMMAND --json --non-interactive'], details: ['0 success; 2 invalid command or option; 3 project or input validation; 4 local filesystem or executable; 5 unexpected CLI failure; 6 authentication or permission; 7 network or timeout; 8 remote service failure; 9 state conflict or approval required.', 'JSON mode writes exactly one response object to stdout. The object contains ok, command, message and optional data or warnings on success, or ok, command and error with code, message and details on failure.'], examples: ['blinkhost validate . --json', 'blinkhost docs commands --json'], related: ['automation', 'troubleshooting'], url: DOCUMENTATION_URL,
+    },
+};
+const COMMANDS = [
+    'quickstart', 'docs', 'create', 'init', 'validate', 'manifest', 'doctor', 'test', 'auth', 'profile', 'projects',
+    'repositories', 'connections', 'previews', 'builds', 'deployments', 'modules', 'databases', 'bindings', 'assets',
+    'secrets', 'organizations', 'templates', 'approvals', 'handoffs', 'policies', 'workloads', 'dev', 'logs', 'metrics',
+    'analytics', 'support', 'completion', 'update', 'ci', 'plugins', 'api',
+];
+export const TOP_LEVEL_COMMANDS = [...COMMANDS];
+export function documentationIndex() {
+    return {
+        schema: 'blinkhost/cli-docs/v1', cli_version: VERSION, documentation_url: DOCUMENTATION_URL,
+        topics: Object.values(TOPICS).map(({ name, title, summary, url }) => ({ name, title, summary, url })),
+    };
+}
+export function documentationTopic(name) {
+    if (name === 'commands' || name === 'docs')
+        return {
+            name: 'commands', title: 'Command reference', summary: 'Discover every top-level command in this CLI release.',
+            usage: ['blinkhost COMMAND --help', 'blinkhost help COMMAND', 'blinkhost docs TOPIC', 'blinkhost docs --search TERM'],
+            details: [`Commands: ${COMMANDS.join(', ')}.`, 'Use --json for a versioned machine-readable response and --non-interactive in automation.'],
+            examples: ['blinkhost create --help', 'blinkhost docs automation --json'], related: ['quickstart', 'automation', 'exit-codes'], url: DOCUMENTATION_URL,
+        };
+    return TOPICS[name] ?? (['metrics', 'analytics'].includes(name) ? TOPICS.logs : undefined);
+}
+export function searchDocumentation(query) {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized || normalized.length > 100 || /[\u0000-\u001f\u007f]/.test(normalized))
+        return [];
+    return Object.values(TOPICS).filter((topic) => JSON.stringify(topic).toLowerCase().includes(normalized));
+}
+export function renderTopic(topic) {
+    const block = [`BlinkHost CLI ${VERSION} — ${topic.title}`, '', topic.summary, '', 'Usage:', ...topic.usage.map((value) => `  ${value}`), '', ...topic.details, ''];
+    if (topic.examples.length)
+        block.push('Examples:', ...topic.examples.map((value) => `  ${value}`), '');
+    if (topic.related.length)
+        block.push(`Related topics: ${topic.related.join(', ')}`);
+    block.push(`Detailed documentation: ${topic.url}`, '');
+    return block.join('\n');
+}
+export function renderTopHelp() {
+    return `BlinkHost CLI ${VERSION}\n\nStart here:\n  blinkhost quickstart [path]   Check local readiness without changing anything\n  blinkhost docs [topic]        Read the version-matched offline reference\n  blinkhost help COMMAND        Show command-specific help\n\nCommands:\n  ${COMMANDS.join('\n  ')}\n\nGlobal options:\n  --json              Write one machine-readable response to stdout\n  --profile NAME      Use a named BlinkHost account profile\n  --quiet             Suppress successful human-readable output\n  --verbose           Include safe diagnostic detail in errors\n  --no-color          Disable terminal colour\n  --non-interactive   Never open a browser or prompt\n  --help              Show command-specific help\n  --version           Show the CLI version\n\nDocumentation: ${DOCUMENTATION_URL}\n`;
+}
+async function executable(command, args) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { shell: false, stdio: 'ignore', windowsHide: true });
+        child.once('error', () => resolve(false));
+        child.once('exit', (code) => resolve(code === 0));
+    });
+}
+export async function quickstart(path) {
+    const root = resolveLocalPath(path);
+    const nodeOk = supportedNodeVersion();
+    const gitOk = await executable('git', ['--version']);
+    const credential = await credentialStoreStatus();
+    let directoryOk = true;
+    try {
+        await access(root);
+    }
+    catch {
+        directoryOk = false;
+    }
+    let project = { status: 'not_configured', path: root };
+    if (directoryOk) {
+        try {
+            const validation = await validateProject(root);
+            project = {
+                status: validation.errors.length ? 'invalid' : 'valid', path: root,
+                framework: validation.manifest.frontend.framework,
+                modules: validation.manifest.modules.length,
+                databases: validation.manifest.resources.databases.length,
+                errors: validation.errors, warnings: validation.warnings,
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            project = { status: code === 'ENOENT' || (error instanceof Error && error.message.includes('No blinkhost.yaml')) ? 'not_configured' : 'unreadable', path: root };
+        }
+    }
+    const nextSteps = project.status === 'valid'
+        ? ['blinkhost test .', 'blinkhost auth login', 'blinkhost projects link PROJECT_ID', 'blinkhost dev .']
+        : ['blinkhost create my-app --template react --no-install', 'blinkhost init ./existing-app', 'blinkhost docs create', 'blinkhost docs init'];
+    return {
+        schema: 'blinkhost/cli-quickstart/v1', cli_version: VERSION,
+        mode: 'local_read_only', remote_changes: false, billable_resources_created: false,
+        checks: [
+            { name: 'node', ok: nodeOk, detected: process.versions.node, required: '>=22.12.0', remediation: nodeOk ? null : 'Install Node.js 22.12 or newer.' },
+            { name: 'git', ok: gitOk, remediation: gitOk ? null : 'Install Git and ensure it is available on PATH.' },
+            { name: 'credential_service', ok: credential.available, provider: credential.provider, required_for: 'interactive account sessions', remediation: credential.remediation },
+            { name: 'directory', ok: directoryOk, path: root },
+        ],
+        project,
+        capabilities: {
+            frontends: SUPPORTED_FRONTENDS, package_managers: SUPPORTED_MANAGERS, backend_modules: SUPPORTED_MODULES,
+            local: ['create', 'init', 'validate', 'manifest', 'doctor', 'test', 'dev', 'docs'],
+            remote: ['projects', 'repositories', 'previews', 'builds', 'deployments', 'modules', 'databases', 'assets'],
+            remote_requirements: 'Authentication, workspace permission, plan capacity, and approval where applicable.',
+        },
+        next_steps: nextSteps,
+        documentation_url: DOCUMENTATION_URL,
+    };
+}
+//# sourceMappingURL=guidance.js.map

package/dist/remote.d.ts

@@ -14,6 +14,6 @@ export declare function syncProject(kind: 'pull' | 'push', input: string[], prof
 export declare function runSecrets(input: string[], profile?: string): Promise<unknown>;
 export declare function rawApi(input: string[], profile?: string): Promise<unknown>;
 export declare function waitForRemote(group: 'builds' | 'deployments' | 'previews', input: string[], profile?: string): Promise<unknown>;
-export declare function openPreview(input: string[], profile?: string): Promise<unknown>;
+export declare function openPreview(input: string[], profile?: string, launchBrowser?: boolean): Promise<unknown>;
 export declare function uploadAsset(input: string[], profile?: string): Promise<unknown>;
 export {};

package/dist/remote.js

@@ -293,7 +293,7 @@ export async function waitForRemote(group, input, profile) {
     }
     throw new CliError(`Timed out waiting for ${group.slice(0, -1)} ${id}.`, EXIT.network, 'wait_timeout');
 }
-export async function openPreview(input, profile) {
+export async function openPreview(input, profile, launchBrowser = true) {
     const args = [...input];
     const id = safeIdentifier(args.shift());
     noExtra(args);
@@ -306,12 +306,14 @@ export async function openPreview(input, profile) {
     const trusted = url.protocol === 'https:' && (url.hostname === 'preview.blinkhost.me' || url.hostname.endsWith('.preview.blinkhost.me') || url.hostname.endsWith('.blinkhost.website'));
     if (!trusted || url.username || url.password)
         throw new CliError('BlinkHost returned an untrusted preview URL.', EXIT.remote, 'preview_url_untrusted');
-    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd.exe' : 'xdg-open';
-    const commandArgs = process.platform === 'win32' ? ['/d', '/s', '/c', 'start', '', url.toString()] : [url.toString()];
-    const child = spawn(command, commandArgs, { detached: true, shell: false, stdio: 'ignore' });
-    child.on('error', () => { });
-    child.unref();
-    return { id: decodeURIComponent(id), url: url.toString() };
+    if (launchBrowser) {
+        const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd.exe' : 'xdg-open';
+        const commandArgs = process.platform === 'win32' ? ['/d', '/s', '/c', 'start', '', url.toString()] : [url.toString()];
+        const child = spawn(command, commandArgs, { detached: true, shell: false, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+    }
+    return { id: decodeURIComponent(id), url: url.toString(), browser_opened: launchBrowser };
 }
 const ASSET_MEDIA_TYPES = {
     '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+export declare const VERSION = "2.1.0";
+export declare const DOCUMENTATION_URL = "https://app.blinkhost.me/docs/source-control/cli";
+export declare const RELEASES_URL = "https://github.com/blinkhost-ltd/blinkhost-cli/releases";
+export declare function supportedNodeVersion(version?: string): boolean;

package/dist/version.js

@@ -0,0 +1,8 @@
+export const VERSION = '2.1.0';
+export const DOCUMENTATION_URL = 'https://app.blinkhost.me/docs/source-control/cli';
+export const RELEASES_URL = 'https://github.com/blinkhost-ltd/blinkhost-cli/releases';
+export function supportedNodeVersion(version = process.versions.node) {
+    const [major = 0, minor = 0] = version.split('.').map(Number);
+    return major > 22 || major === 22 && minor >= 12;
+}
+//# sourceMappingURL=version.js.map

package/dist/workflows.d.ts

@@ -1,7 +1,7 @@
-export declare function runDev(input: string[]): Promise<unknown>;
-export declare function testProject(input: string[]): Promise<unknown>;
+export declare function runDev(input: string[], json?: boolean): Promise<unknown>;
+export declare function testProject(input: string[], json?: boolean): Promise<unknown>;
 export declare function observability(kind: 'logs' | 'metrics' | 'analytics', input: string[], profile?: string): Promise<unknown>;
-export declare function runPlugins(input: string[]): Promise<unknown>;
+export declare function runPlugins(input: string[], json?: boolean): Promise<unknown>;
 export declare function completion(shell: string | undefined): string;
 export declare function checkForUpdate(): Promise<unknown>;
 export declare function ciCheck(profile?: string): Promise<unknown>;

package/dist/workflows.js

@@ -8,6 +8,8 @@ import { readConfig, writeConfig } from './config.js';
 import { CliError, EXIT } from './errors.js';
 import { readProjectManifest, resolveLocalPath, validateProject } from './project.js';
 import { readProjectLink } from './remote.js';
+import { TOP_LEVEL_COMMANDS } from './guidance.js';
+import { VERSION } from './version.js';
 function takeOption(args, name) {
     const index = args.indexOf(name);
     if (index < 0)
@@ -22,9 +24,13 @@ function takeFlag(args, name) { const i = args.indexOf(name); if (i < 0)
     return false; args.splice(i, 1); return true; }
 function noExtra(args) { if (args.length)
     throw new CliError(`Unexpected argument: ${args[0]}`, EXIT.usage, 'unexpected_argument'); }
-async function spawnInherited(command, args, cwd, env) {
+async function spawnInherited(command, args, cwd, env, json = false) {
     return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { cwd, env: env || process.env, shell: false, stdio: 'inherit', windowsHide: true });
+        const child = spawn(command, args, { cwd, env: env || process.env, shell: false, stdio: json ? ['inherit', 'pipe', 'pipe'] : 'inherit', windowsHide: true });
+        if (json) {
+            child.stdout?.on('data', (chunk) => process.stderr.write(chunk));
+            child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+        }
         const forward = (signal) => child.kill(signal);
         process.once('SIGINT', forward);
         process.once('SIGTERM', forward);
@@ -32,7 +38,7 @@ async function spawnInherited(command, args, cwd, env) {
         child.once('exit', (code) => { process.off('SIGINT', forward); process.off('SIGTERM', forward); resolve(code ?? 1); });
     });
 }
-export async function runDev(input) {
+export async function runDev(input, json = false) {
     const args = [...input];
     const root = resolveLocalPath(args.shift());
     const host = takeOption(args, '--host');
@@ -51,12 +57,12 @@ export async function runDev(input) {
     if (port)
         managerArgs.push('--port', port);
     const dependencyRoot = manifest.frontend.dependency_root === '.' ? root : join(root, manifest.frontend.dependency_root);
-    const exitCode = await spawnInherited(manager, managerArgs, dependencyRoot, { ...process.env, BLINKHOST_LOCAL: '1' });
+    const exitCode = await spawnInherited(manager, managerArgs, dependencyRoot, { ...process.env, BLINKHOST_LOCAL: '1' }, json);
     if (exitCode !== 0)
-        throw new CliError(`The local development process exited with code ${exitCode}.`, EXIT.remote, 'dev_process_failed');
+        throw new CliError(`The local development process exited with code ${exitCode}.`, EXIT.remote, 'dev_process_failed', [`If dependencies are missing, run \`${manager} install\` in ${dependencyRoot}, then retry.`]);
     return { exit_code: exitCode };
 }
-export async function testProject(input) {
+export async function testProject(input, json = false) {
     const args = [...input];
     const root = resolveLocalPath(args.shift());
     noExtra(args);
@@ -69,9 +75,9 @@ export async function testProject(input) {
     const dependencyRoot = manifest.frontend.dependency_root === '.' ? root : join(root, manifest.frontend.dependency_root);
     const packageJson = JSON.parse(await readFile(join(dependencyRoot, 'package.json'), 'utf8'));
     const script = packageJson.scripts?.test ? 'test' : 'build';
-    const code = await spawnInherited(manifest.frontend.package_manager, ['run', script], dependencyRoot, { ...process.env, CI: '1' });
+    const code = await spawnInherited(manifest.frontend.package_manager, ['run', script], dependencyRoot, { ...process.env, CI: '1' }, json);
     if (code !== 0)
-        throw new CliError(`Project ${script} exited with code ${code}.`, EXIT.validation, 'project_test_failed');
+        throw new CliError(`Project ${script} exited with code ${code}.`, EXIT.validation, 'project_test_failed', [`If dependencies are missing, run \`${manifest.frontend.package_manager} install\` in ${dependencyRoot}, then retry.`]);
     return { validated: true, command: `${manifest.frontend.package_manager} run ${script}`, exit_code: code };
 }
 export async function observability(kind, input, profile) {
@@ -98,7 +104,7 @@ export async function observability(kind, input, profile) {
     return client.request(`/api/sites/${encodeURIComponent(project)}/observability/${kind}/${suffix}`);
 }
 async function sha256File(path) { return createHash('sha256').update(await readFile(path)).digest('hex'); }
-export async function runPlugins(input) {
+export async function runPlugins(input, json = false) {
     const args = [...input];
     const action = args.shift() || 'list';
     const config = await readConfig();
@@ -154,27 +160,29 @@ export async function runPlugins(input) {
         for (const key of allowed)
             if (process.env[key])
                 env[key] = process.env[key];
-        const code = await spawnInherited(plugin.executable, passthrough, process.cwd(), env);
+        const code = await spawnInherited(plugin.executable, passthrough, process.cwd(), env, json);
         if (code !== 0)
             throw new CliError(`Plugin ${name} exited with code ${code}.`, EXIT.remote, 'plugin_failed');
         return { name, exit_code: code };
     }
     throw new CliError(`Unknown plugins action: ${action}.`, EXIT.usage, 'unknown_action');
 }
+const commandWords = TOP_LEVEL_COMMANDS.join(' ');
+const powershellCommands = TOP_LEVEL_COMMANDS.map((command) => `'${command}'`).join(',');
 const COMPLETIONS = {
-    bash: `complete -W "auth projects repositories connections dev previews builds deployments modules databases bindings assets secrets organizations templates approvals handoffs policies logs metrics analytics doctor support completion update ci plugins api" blinkhost`,
-    zsh: `#compdef blinkhost\n_arguments '1:command:(auth projects repositories connections dev previews builds deployments modules databases bindings assets secrets organizations templates approvals handoffs policies logs metrics analytics doctor support completion update ci plugins api)'`,
-    fish: `complete -c blinkhost -f -a "auth projects repositories connections dev previews builds deployments modules databases bindings assets secrets organizations templates approvals handoffs policies logs metrics analytics doctor support completion update ci plugins api"`,
-    powershell: `Register-ArgumentCompleter -Native -CommandName blinkhost -ScriptBlock { param($wordToComplete) 'auth','projects','repositories','connections','dev','previews','builds','deployments','modules','databases','bindings','assets','secrets','organizations','templates','approvals','handoffs','policies','logs','metrics','analytics','doctor','support','completion','update','ci','plugins','api' | Where-Object { $_ -like "$wordToComplete*" } }`,
+    bash: `complete -W "${commandWords}" blinkhost`,
+    zsh: `#compdef blinkhost\n_arguments '1:command:(${commandWords})'`,
+    fish: `complete -c blinkhost -f -a "${commandWords}"`,
+    powershell: `Register-ArgumentCompleter -Native -CommandName blinkhost -ScriptBlock { param($wordToComplete) ${powershellCommands} | Where-Object { $_ -like "$wordToComplete*" } }`,
 };
 export function completion(shell) { if (!shell || !COMPLETIONS[shell])
     throw new CliError('Choose bash, zsh, fish, or powershell.', EXIT.usage, 'invalid_shell'); return `${COMPLETIONS[shell]}\n`; }
 export async function checkForUpdate() {
-    const response = await fetch('https://api.github.com/repos/blinkhost-ltd/blinkhost-cli/releases/latest', { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'BlinkHost-CLI/2.0.0' }, redirect: 'error' });
+    const response = await fetch('https://api.github.com/repos/blinkhost-ltd/blinkhost-cli/releases/latest', { headers: { Accept: 'application/vnd.github+json', 'User-Agent': `BlinkHost-CLI/${VERSION}` }, redirect: 'error' });
     if (!response.ok)
         throw new CliError('The release service could not be reached.', EXIT.network, 'update_check_failed');
     const data = await response.json();
-    return { current_version: '2.0.0', latest_version: data.tag_name?.replace(/^v/, '') || null, release_url: data.html_url || null, automatic_install: false };
+    return { current_version: VERSION, latest_version: data.tag_name?.replace(/^v/, '') || null, release_url: data.html_url || null, automatic_install: false };
 }
 export async function ciCheck(profile) {
     const client = await ApiClient.create(profile);
@@ -201,7 +209,7 @@ export async function supportBundle(input, profile) {
     catch (error) {
         api = { reachable: false, error_code: error instanceof CliError ? error.code : 'unknown' };
     }
-    const payload = { schema: 'blinkhost/support-bundle/v1', created_at: new Date().toISOString(), cli_version: '2.0.0', system: { platform: platform(), release: release(), node: process.versions.node, device_hash: createHash('sha256').update(hostname()).digest('hex').slice(0, 16) }, project, api };
+    const payload = { schema: 'blinkhost/support-bundle/v1', created_at: new Date().toISOString(), cli_version: VERSION, system: { platform: platform(), release: release(), node: process.versions.node, device_hash: createHash('sha256').update(hostname()).digest('hex').slice(0, 16) }, project, api };
     await mkdir(dirname(output), { recursive: true });
     await writeFile(output, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
     return { output, redacted: true };

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@blinkhost/cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Secure local and remote developer workflows for BlinkHost",
+  "keywords": ["blinkhost", "deployment", "hosting", "cloud", "cli", "developer-tools"],
+  "homepage": "https://app.blinkhost.me/docs/source-control/cli",
+  "repository": { "type": "git", "url": "git+https://github.com/blinkhost-ltd/blinkhost-cli.git" },
+  "bugs": { "url": "https://github.com/blinkhost-ltd/blinkhost-cli/issues" },
   "type": "module",
   "bin": { "blinkhost": "dist/cli.js" },
   "files": ["dist/*.js", "dist/*.d.ts", "README.md", "LICENSE"],