@lotagate/cli 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LotaGate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# @lotagate/cli
+
+@lotagate/cli is the terminal client for LotaGate AI agents. It provides an interactive streaming TUI, a headless automation interface, durable project-scoped sessions, local tools with approval controls, MCP, plugins, skills, hooks, and image, audio, and video commands.
+
+The CLI consumes @lotagate/sdk and @lotagate/agent-sdk as independent npm dependencies. CLI-specific policy, persistence, terminal presentation, local filesystem and shell integrations remain owned by this package.
+
+## Highlights
+
+- Interactive terminal workspace with streaming responses, slash commands, model selection, attachments, tool activity, and approval prompts.
+- Headless exec and JSONL agent protocol for scripts and integrations.
+- Project trust, explicit tool approval, workspace confinement, safe process execution, and encrypted local API-key storage.
+- Durable sessions, context compaction, resumable goals, and bounded subagents.
+- User- and project-scoped MCP servers, plugins, skills, and hooks.
+- Image, audio, speech, transcription, translation, and video workflows.
+- Native executable installation on supported Windows, macOS, and glibc Linux hosts, with a verified Node launcher fallback elsewhere.
+
+## Requirements
+
+- Node.js 22 or later for installation, development, and Node-launcher hosts.
+- A LotaGate API key and at least one model available from the configured API endpoint.
+- A terminal with ANSI input/output support for the interactive client.
+
+Native installations run independently after npm has installed the matching artifact. Node.js remains required on fallback hosts and for package-management commands.
+
+## Installation
+
+Install globally:
+
+~~~bash
+npm install --global @lotagate/cli
+lotagate --help
+~~~
+
+Or invoke the current package without a global installation:
+
+~~~bash
+npx @lotagate/cli --help
+~~~
+
+### Native executable distribution
+
+The main package selects a matching optional native package during installation and verifies its SHA-256 checksum before replacing the launcher. This gives the process its own LotaGate identity, such as lotagate.exe in Windows Task Manager. Do not install with --ignore-scripts or --omit=optional; either option prevents native installation.
+
+| Distribution | Hosts | Architectures |
+| --- | --- | --- |
+| Native executable | Windows, macOS, glibc Linux | x64, ARM64 |
+| Node launcher fallback | Alpine/musl Linux, Android/Termux, FreeBSD, OpenBSD, NetBSD | Architectures supported by Node.js |
+
+Windows native binaries include the LotaGate icon but are not code-signed. Windows may therefore show its normal unsigned-publisher warning on first run. This does not affect npm installation or normal execution.
+
+## Quick start
+
+~~~bash
+# Save an API-key profile. The command masks the key input.
+lotagate auth login
+
+# Fetch available models and select one.
+lotagate model list
+lotagate model use <model-id>
+
+# Start the interactive workspace.
+lotagate
+~~~
+
+When the interactive workspace starts in a new project, it asks whether to trust that project. Until trust is granted, local filesystem tools, shell commands, project MCP servers, plugins, skills, and hooks cannot run.
+
+## Interactive workspace
+
+Run lotagate to open the TUI. Type / to browse interactive commands.
+
+| Input | Action |
+| --- | --- |
+| Enter | Send the prompt or run the selected command |
+| Shift+Enter | Insert a newline |
+| Tab | Complete the active command suggestion |
+| Esc | Cancel an active response; when idle, clear the draft safely |
+| Ctrl+V | Paste text |
+| Alt+V | Paste an image when the host clipboard supports it |
+
+Use /model to select a model. Media slash commands prompt for a compatible request-only model when --model is omitted; the selection applies only to that command and never changes the active root model.
+
+Common commands:
+
+~~~text
+/help
+/context
+/session list
+/session resume <id>
+/goal <objective>
+/details
+/exit
+~~~
+
+The TUI records durable conversation state by project identity. It renders tool activity and approval choices below the composer, while the transcript remains scrollable with the session.
+
+## Direct commands and automation
+
+Use direct commands for scripts and non-interactive tasks:
+
+~~~bash
+# A direct chat completion.
+lotagate chat "Summarize the current project."
+
+# A trusted, tool-capable headless agent run.
+lotagate exec "Inspect the repository and report the test command."
+
+# A durable multi-turn objective.
+lotagate goal run "Audit the project configuration" --max-turns 20
+
+# Machine-readable agent protocol over standard input/output.
+lotagate agent stdio
+~~~
+
+lotagate exec --json and lotagate exec --jsonl provide structured output for automation. lotagate agent stdio exposes the versioned JSONL protocol; it validates requests, bounds in-flight work, supports cancellation, and emits safe structured errors instead of raw provider failures.
+
+Run lotagate help for the complete direct-command reference. The executable command catalog is the source of truth for command arguments and flags.
+
+## Models and media
+
+The CLI fetches its model catalog from LotaGate; it does not hardcode model identifiers. --model <model-id> overrides the model for one media request only.
+
+~~~bash
+lotagate image "A red fox reading in a library" --size 1024x1024
+lotagate image edit "Make the sky a sunset" --image assets/source.png
+
+lotagate audio speech "Welcome to LotaGate" --voice alloy --response-format mp3
+lotagate audio transcribe --file recordings/interview.wav --response-format srt
+lotagate audio translate --file recordings/interview.wav --response-format text
+
+lotagate video "A paper boat sailing through a city canal" \
+  --parameters '{"durationSeconds":8}'
+lotagate video status <operation-id>
+lotagate video download <operation-id>
+~~~
+
+All media inputs and outputs are confined to a trusted workspace. Generated artifacts default to dedicated directories below <workspace>/tmp/; use --out <file> for an exact path or --out-dir <directory> for a directory. The CLI does not overwrite an artifact unless --force is supplied with --out.
+
+Video creation is asynchronous. It normally waits for the gateway operation and downloads the final artifact. Use --no-wait to return the operation ID, then use video status and video download later. The CLI never polls a provider directly; the LotaGate gateway owns provider credentials and polling.
+
+## Trust, local tools, and approvals
+
+Trust is project-scoped and explicit:
+
+~~~bash
+lotagate trust status
+lotagate trust grant
+lotagate trust revoke
+~~~
+
+In a trusted project, local tools remain bounded by workspace path validation, symlink escape checks, structured shell arguments, output and timeout limits, and the approval policy. A tool approval allows or denies that one action; the TUI can remember a narrow local rule for a previously approved operation.
+
+Project policy lives in <project>/.lotagate/settings.json. For example:
+
+~~~json
+{
+  "schemaVersion": 1,
+  "permissions": {
+    "allow": ["shell.exec:git status"],
+    "ask": ["filesystem.write:src/*"],
+    "deny": ["shell.exec:git push*"]
+  }
+}
+~~~
+
+deny takes precedence over ask and allow. Local remembered approvals are stored separately in settings.local.json, which is intended to remain out of shared project configuration.
+
+## Extensions
+
+Extensions are either user-scoped or project-scoped. Direct commands require an explicit --scope user|project; the interactive client presents a selector when a scope is omitted. Project scope requires project trust.
+
+~~~bash
+# Add an MCP server to the trusted project.
+lotagate mcp add filesystem --type stdio --command npx \
+  --args "-y,@modelcontextprotocol/server-filesystem,." --scope project
+
+# Review configured integrations.
+lotagate mcp list
+lotagate plugin list
+lotagate skill list
+lotagate hook list
+
+# Install a verified plugin or standalone skill.
+lotagate plugin install <source> --scope user --sha256 <sha256>
+~~~
+
+Plugins are declarative packages with .lotagate-plugin/plugin.json. The CLI copies and validates them atomically; it does not run package-install scripts. Skills are validated SKILL.md directories and can be user, project, plugin, or immutable bundled skills. Project hooks are loaded only from <project>/.lotagate/hooks/ in a trusted project.
+
+## Configuration and data
+
+Configuration is merged in this order, with later layers taking precedence:
+
+1. <home>/.lotagate/settings.json
+2. <project>/.lotagate/settings.json
+3. <project>/.lotagate/settings.local.json
+
+Run lotagate config path to see the actual paths on the current host. Credentials are encrypted locally and are never written to settings.json or shown in diagnostic output.
+
+| Location | Purpose |
+| --- | --- |
+| <home>/.lotagate/credentials.enc.json | Encrypted API-key profiles |
+| <home>/.lotagate/projects/ | Project-scoped session journals, attachments, locks, and subagent records |
+| <home>/.lotagate/skills/ and plugins/ | User extensions |
+| <home>/.lotagate/mcp.json | User MCP configuration |
+| <home>/.lotagate/cache/ and logs/ | Bounded cache and redacted operational logs |
+| <project>/.lotagate/ | Reviewable project configuration and project extensions |
+
+Use LOTAGATE_HOME to choose the parent home used for global CLI storage. For non-persistent automation credentials, set LOTAGATE_API_KEY; optional LOTAGATE_BASE_URL and LOTAGATE_PROFILE select its endpoint and profile. Environment credentials are read-only and are not persisted.
+
+Operational controls:
+
+| Variable | Purpose |
+| --- | --- |
+| LOTAGATE_CACHE_ENABLED | Enable or disable the local cache |
+| LOTAGATE_MODEL_CACHE_TTL_SECONDS | Model-catalog cache lifetime |
+| LOTAGATE_CACHE_MAX_ENTRY_BYTES / LOTAGATE_CACHE_MAX_BYTES | Cache size limits |
+| LOTAGATE_LOG_LEVEL / LOTAGATE_LOG_RETENTION_DAYS | Redacted log policy |
+| LOTAGATE_VIDEO_POLL_INTERVAL_MS / LOTAGATE_VIDEO_WAIT_TIMEOUT_MS | Local video wait policy |
+| LOTAGATE_MEDIA_DOWNLOAD_TIMEOUT_MS | Generated-media download timeout |
+| LOTAGATE_ASCII=1 | Use ASCII-only terminal symbols |
+
+## Sessions, goals, and subagents
+
+Sessions are durable but isolated by canonical project identity. Resume or inspect them with lotagate session list, lotagate session show <id>, and lotagate session resume <id> --interactive. The CLI can compact a session to retain bounded context while preserving the system instructions and a durable summary.
+
+Goals make a multi-turn objective resumable:
+
+~~~bash
+lotagate goal run "Prepare a release checklist" --token-budget 50000
+lotagate goal status <session-id> --json
+lotagate goal pause <session-id>
+lotagate goal resume <session-id>
+~~~
+
+Trusted agents can delegate bounded research or explicitly scoped worker tasks to subagents. Child agents cannot create unrestricted nested work, and a safety-limit stop returns a resumable handoff rather than silently continuing.
+
+## Supported hosts
+
+The CLI centralizes host detection and supports Windows, Linux, macOS, and BSD (FreeBSD, OpenBSD, NetBSD); Android is handled through the Linux path. It selects platform-specific process, path, and clipboard behavior at startup.
+
+On Linux and BSD, image clipboard paste requires wl-paste or xclip. If no provider is available, the CLI reports that clipboard capability as unavailable instead of falling back to an unsafe shell command.
+
+## Security and support
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and security controls. The CLI redacts known sensitive values from operational logs and keeps provider failures out of the machine-readable protocol where possible, but users should still avoid placing credentials or private data in prompts.
+
+## Package and licensing
+
+- Package: @lotagate/cli
+- License: MIT
+- Website: [LotaGate](https://lotagate.com)
+- Support and bug reports: [Contact LotaGate](https://lotagate.com/contact)

package/SECURITY.md

@@ -0,0 +1,96 @@
+# Security
+
+This document defines the production security expectations for
+`@lotagate/cli`.
+
+## Security boundary
+
+The CLI is a local privileged application: it can read and write within a
+trusted workspace, execute approved local processes, connect to configured MCP
+servers and send workspace content to the selected model endpoint. Users and
+operators must treat a trusted project, an installed plugin and an MCP server
+as code and configuration that can cause side effects.
+
+## Production controls
+
+### Credentials
+
+- Authentication uses API keys only.
+- Interactive API-key input is not echoed.
+- Persisted profiles are encrypted with AES-256-GCM.
+- The CLI initializes a random local encryption key on first interactive use;
+  operators may provide `LOTAGATE_CREDENTIAL_SECRET` for managed key material.
+- API keys are excluded from settings files, status output and structured logs.
+- CI environment credentials are ephemeral and are never persisted by the CLI.
+- Credential files and session data are created with owner-only permissions
+  where the operating system supports them.
+
+### Project trust and authorization
+
+- A project must be explicitly trusted before local tools, MCP connections or
+  project extensions are enabled.
+- Tool approval is deny-by-default for untrusted projects.
+- `ask`, `auto` and `deny` approval modes are validated configuration values.
+- Approval is evaluated at the tool boundary; hiding a command in the UI is not
+  treated as authorization.
+
+### Filesystem and process execution
+
+- Workspace paths are canonicalized and checked for traversal and symlink
+  escapes.
+- Shell tools use structured command arguments with `shell: false`.
+- Process execution has bounded output and time limits and supports cancellation.
+- Tool results and clipboard images have explicit size limits.
+- Sensitive bearer and API-key-like values are redacted from process output.
+
+### Extensions and MCP
+
+- Plugin installation uses an atomic destination update.
+- Plugin packages reject symbolic links and manifest paths that escape the
+  plugin directory.
+- SHA-256 integrity verification is supported; Ed25519 verification can be
+  required by supplying a trusted public key and detached signature.
+- Skills cannot read supporting files outside their own directory.
+- MCP commands are validated before persistence and connections require project
+  trust.
+- Do not install plugins or configure MCP servers from untrusted sources.
+
+### Sessions, attachments and logs
+
+- Session metadata, journals and attachments are stored under the CLI data root.
+- Session writes use process locks and atomic metadata writes.
+- Attachment bytes are stored separately from transcript metadata.
+- Session export files may contain prompts, responses and image data; protect
+  them as confidential records.
+- Do not send logs, exported sessions or diagnostic output to public trackers
+  without removing secrets and workspace content.
+
+## Operator checklist
+
+Before production use:
+
+1. Use a dedicated API key with the minimum available service scope.
+2. Set restrictive permissions on the CLI data directory and backup location.
+3. Trust only repositories whose source and extension configuration has been
+   reviewed.
+4. Keep approval mode at `ask` unless the workspace and automation boundary are
+   controlled and `auto` is explicitly justified.
+5. Review MCP commands, URLs, headers and server ownership.
+6. Verify plugin checksums or signatures through an independent trusted channel.
+7. Apply the organization’s retention policy to sessions, attachments and logs.
+8. Keep Node.js and the CLI package on an approved supported release.
+
+## Reporting a vulnerability
+
+Do not disclose vulnerabilities, API keys, credentials, image Base64 payloads,
+session exports or private source code in public issues. Report privately to the
+LotaGate maintainers through the security contact configured for the project.
+Include:
+
+- affected CLI version and operating system;
+- reproduction steps and required trust/configuration state;
+- impact and security boundary crossed;
+- a minimal proof of concept with secrets removed.
+
+Allow maintainers reasonable time to investigate and coordinate a fix. Rotate
+any credential that may have appeared in a report immediately.

package/bin/lotagate.exe

@@ -0,0 +1 @@
+Native executable installation did not complete. Reinstall @lotagate/cli without --ignore-scripts or --omit=optional.

package/bin/lotagate.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import { main } from '../dist/main.js';
+
+void main(process.argv.slice(2)).then(
+  (exitCode) => { process.exitCode = exitCode; },
+  (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`lotagate: ${message}\n`);
+    process.exitCode = 1;
+  },
+);

package/native-targets.mjs

@@ -0,0 +1,35 @@
+/** Native distribution targets. Keep this list aligned with host-platform.ts. */
+export const NATIVE_TARGETS = Object.freeze([
+  target('windows-x64', ['win32', 'cygwin'], 'x64'),
+  target('windows-arm64', ['win32', 'cygwin'], 'arm64'),
+  target('linux-x64-gnu', ['linux'], 'x64', 'gnu'),
+  target('linux-arm64-gnu', ['linux'], 'arm64', 'gnu'),
+  target('macos-x64', ['darwin'], 'x64'),
+  target('macos-arm64', ['darwin'], 'arm64'),
+]);
+
+export function targetForRuntime(platform, arch, linuxLibc = detectLinuxLibc(platform)) {
+  return NATIVE_TARGETS.find((target) => target.platforms.includes(platform)
+    && target.arch === arch
+    && target.libc === linuxLibc);
+}
+
+export function targetById(id) {
+  return NATIVE_TARGETS.find((target) => target.id === id);
+}
+
+export function detectLinuxLibc(platform, report = process.report?.getReport?.()) {
+  if (platform !== 'linux') return undefined;
+  return report?.header?.glibcVersionRuntime === undefined ? 'musl' : 'gnu';
+}
+
+function target(id, platforms, arch, libc) {
+  return Object.freeze({
+    id,
+    platforms: Object.freeze(platforms),
+    arch,
+    packageName: `@lotagate/cli-native-${id}`,
+    binaryName: 'lotagate.exe',
+    libc,
+  });
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@lotagate/cli",
+  "version": "0.1.0",
+  "description": "Enterprise-grade terminal client for LotaGate AI agents.",
+  "type": "module",
+  "license": "MIT",
+  "author": "LotaGate",
+  "homepage": "https://lotagate.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huy20222003/lotagate-cli.git"
+  },
+  "bugs": {
+    "url": "https://lotagate.com/contact"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "lotagate",
+    "terminal",
+    "tui"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "packageManager": "npm@11.8.0",
+  "bin": {
+    "lotagate": "./bin/lotagate.exe"
+  },
+  "sideEffects": false,
+  "files": [
+    "bin/lotagate.exe",
+    "bin/lotagate.mjs",
+    "dist",
+    "scripts/install-native.mjs",
+    "native-targets.mjs",
+    "skills",
+    "README.md",
+    "LICENSE.md",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ./scripts/build.mjs",
+    "build:native": "node ./scripts/build-native.mjs",
+    "package:native": "node ./scripts/create-native-target-package.mjs",
+    "dev": "npm run build && node ./bin/lotagate.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+    "lint": "eslint .",
+    "test": "tsx --test test/**/*.test.ts test/**/*.test.tsx",
+    "test:integration": "tsx --test test/integration/**/*.test.ts",
+    "test:native": "node ./scripts/test-native-install.mjs",
+    "test:package": "npm run build && node test/package-smoke.mjs",
+    "pack:check": "npm pack --dry-run",
+    "postinstall": "node ./scripts/install-native.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@lotagate/agent-sdk": "^0.1.4",
+    "@lotagate/sdk": "^0.1.2",
+    "ink": "^7.1.1",
+    "react": "^19.2.4",
+    "tiktoken": "^1.0.22"
+  },
+  "optionalDependencies": {
+    "@lotagate/cli-native-linux-arm64-gnu": "0.1.0",
+    "@lotagate/cli-native-linux-x64-gnu": "0.1.0",
+    "@lotagate/cli-native-macos-arm64": "0.1.0",
+    "@lotagate/cli-native-macos-x64": "0.1.0",
+    "@lotagate/cli-native-windows-arm64": "0.1.0",
+    "@lotagate/cli-native-windows-x64": "0.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "@types/node": "20.19.43",
+    "@types/react": "^19.2.4",
+    "@typescript-eslint/eslint-plugin": "8.65.0",
+    "@typescript-eslint/parser": "8.65.0",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "globals": "16.4.0",
+    "ink-testing-library": "^4.0.0",
+    "resedit": "3.0.2",
+    "tsx": "4.23.12",
+    "typescript": "5.9.3"
+  }
+}

package/scripts/install-native.mjs

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { targetForRuntime } from '../native-targets.mjs';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const target = targetForRuntime(process.platform, process.arch);
+
+if (existsSync(resolve(packageRoot, '.git'))) process.exit(0);
+
+if (target === undefined) await installNodeFallback();
+else await installNativeTarget(target);
+
+async function installNativeTarget(nativeTarget) {
+  const nativePackageRoot = resolve(packageRoot, 'node_modules', ...nativeTarget.packageName.split('/'));
+  const source = resolve(nativePackageRoot, 'bin', nativeTarget.binaryName);
+  const destination = resolve(packageRoot, 'bin', nativeTarget.binaryName);
+  const metadataFile = resolve(nativePackageRoot, 'package.json');
+  const cliMetadataFile = resolve(packageRoot, 'package.json');
+  try {
+    const [metadataText, cliMetadataText, sourceStat] = await Promise.all([readFile(metadataFile, 'utf8'), readFile(cliMetadataFile, 'utf8'), stat(source)]);
+    if (!sourceStat.isFile()) fail(`Native artifact is invalid: ${nativeTarget.packageName}.`);
+    const metadata = JSON.parse(metadataText);
+    const cliMetadata = JSON.parse(cliMetadataText);
+    const declared = metadata.lotagateNative;
+    if (metadata.name !== nativeTarget.packageName || metadata.version !== cliMetadata.version) fail(`Native artifact metadata does not match @lotagate/cli ${String(cliMetadata.version)}.`);
+    if (declared?.target !== nativeTarget.id || declared?.sha256 !== await sha256(source)) fail(`Native artifact integrity validation failed: ${nativeTarget.packageName}.`);
+    await installExecutable(source, destination);
+  } catch (error) {
+    await rm(destination, { force: true }).catch(() => undefined);
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
+async function installNodeFallback() {
+  if (process.platform === 'win32' || process.platform === 'cygwin') fail(`No native LotaGate CLI artifact is available for ${process.platform}/${process.arch}.`);
+  const destination = resolve(packageRoot, 'bin', 'lotagate.exe');
+  try {
+    await installExecutable(resolve(packageRoot, 'bin', 'lotagate.mjs'), destination);
+  } catch (error) {
+    await rm(destination, { force: true }).catch(() => undefined);
+    fail(`Node launcher installation failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+async function installExecutable(source, destination) {
+  const temporary = `${destination}.install-${process.pid}-${Date.now()}`;
+  await mkdir(dirname(destination), { recursive: true });
+  await copyFile(source, temporary);
+  await chmodExecutable(temporary);
+  await rename(temporary, destination);
+}
+
+async function sha256(filePath) {
+  return createHash('sha256').update(await readFile(filePath)).digest('hex');
+}
+
+async function chmodExecutable(filePath) {
+  if (process.platform !== 'win32') await import('node:fs/promises').then(({ chmod }) => chmod(filePath, 0o755));
+}
+
+function fail(message) {
+  process.stderr.write(`@lotagate/cli: ${message}\n`);
+  process.stderr.write('Reinstall without --ignore-scripts or --omit=optional.\n');
+  process.exitCode = 1;
+  throw new Error(message);
+}

package/skills/api-contract-review/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: api-contract-review
+description: Review an API contract, adapter or protocol flow for compatibility, validation and failure behavior.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list]
+---
+# API contract review
+
+Trace the request and response from the public boundary through validation,
+application logic, adapters and mapping.
+
+Check input and output schemas, optionality, backward compatibility, error
+codes, authentication, authorization, timeouts, retries, cancellation,
+pagination, idempotency and sensitive data exposure. Compare the contract with
+callers and tests. Report evidence-backed findings and distinguish runtime
+verification requirements from confirmed behavior.

package/skills/architecture-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: architecture-review
+description: Trace a feature end to end and assess ownership, boundaries and extensibility.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list]
+---
+# Architecture review
+
+Analyze the requested feature using evidence from the repository.
+
+1. Identify the entry point, owning module and allowed dependency direction.
+2. Trace the flow through validation, application logic, ports, infrastructure
+   adapters and presentation boundaries.
+3. Reuse existing abstractions before proposing new files or dependencies.
+4. Check for duplicated business rules, leaky infrastructure details and
+   unclear ownership.
+5. Propose the smallest complete design that preserves contracts and supports
+   testing, operations and future extension; do not defer required behavior.
+
+Clearly distinguish confirmed facts from recommendations and runtime
+verification requirements.

package/skills/code-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: code-review
+description: Review a change for correctness, security, maintainability and regression risk.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list]
+---
+# Code review
+
+Review the requested repository scope as a production code review.
+
+1. Trace the affected execution flow before forming conclusions.
+2. Inspect the relevant callers, callees, contracts, validation and tests.
+3. Report confirmed defects before style preferences.
+4. For every finding, include severity, confidence, file/location, evidence,
+   impact and a focused remediation.
+5. Check security boundaries, error paths, cancellation, resource cleanup and
+   regression coverage.
+
+Do not modify files unless the user explicitly asks for implementation.

package/skills/database-review/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: database-review
+description: Review database access for correctness, integrity, query behavior and concurrency safety.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list]
+---
+# Database review
+
+Trace repositories, queries, transactions and constraints through their
+callers. Inspect filtering, tenant isolation, soft deletion, pagination,
+indexes, joins, read-modify-write races, unique constraints, lock behavior and
+external calls inside transactions.
+
+Do not recommend an index or schema change without query shape, data-volume and
+write-amplification evidence. Label runtime plans and load behavior as needing
+verification when no measurements are available.

package/skills/debugging/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: debugging
+description: Diagnose a reproducible failure from evidence and prepare a minimal safe fix.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list, shell.exec]
+---
+# Debugging
+
+Diagnose the reported failure without guessing.
+
+1. Reproduce or isolate the failure with the narrowest safe command.
+2. Trace the input from its boundary to the failing operation.
+3. Compare the runtime behavior with the declared types, validation and
+   configuration.
+4. Identify the root cause, affected cases and regression risk.
+5. Add or update a focused regression test before implementing a fix.
+6. Run the narrow test first, then the relevant project checks.
+
+Do not hide failures, weaken validation or modify unrelated modules.

package/skills/dependency-review/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: dependency-review
+description: Evaluate a dependency change for necessity, security, compatibility and operational cost.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list, shell.exec]
+---
+# Dependency review
+
+Check whether an existing abstraction, direct dependency, native API or
+framework capability already solves the problem. If a new package is still
+justified, assess maintenance, license, advisories, transitive dependencies,
+runtime cost, compatibility, migration risk and rollback.
+
+Do not modify manifests or lockfiles unless the user explicitly requests the
+dependency change and the evidence supports it.

package/skills/documentation/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: documentation
+description: Produce accurate maintainable documentation from verified repository behavior.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list, filesystem.write]
+---
+# Documentation
+
+Inspect the implementation, configuration and existing documentation before
+writing. Document the supported workflow, prerequisites, configuration,
+security boundaries, failure behavior, examples and verification commands.
+
+Keep documentation aligned with public behavior, avoid secrets and speculative
+claims, preserve the project voice, and update the nearest authoritative file
+rather than creating duplicate guidance.

package/skills/feature-implementation/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: feature-implementation
+description: Implement a requested feature end to end while preserving architecture, contracts and operational safety.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list, filesystem.exists, filesystem.write, shell.exec]
+---
+# Feature implementation
+
+Implement only an explicitly requested behavior change.
+
+1. Read repository guidance, the package manifest, relevant configuration and
+   the complete affected flow before editing.
+2. Identify the owning layer, reusable abstractions, public contracts and
+   trust boundaries. Extend an existing abstraction when ownership remains
+   cohesive.
+3. Define the smallest complete design, including validation, errors,
+   cancellation, persistence and user-visible states where applicable.
+4. Edit cohesive files with complete content. Preserve unrelated changes and
+   never write secrets, generated artifacts or unrelated formatting.
+5. Run focused type, lint and behavior checks after the implementation, then
+   run the relevant integrated regression checks.
+6. Report changed files, preserved contracts, evidence, limitations and risks.
+
+Do not defer required behavior or claim completion without verification.

package/skills/frontend-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: frontend-review
+description: Review a frontend flow for state ownership, rendering behavior, accessibility and resilient user states.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list]
+---
+# Frontend review
+
+Trace route, page, component, state, request and render behavior. Check state
+ownership, derived state, effect chains, stale responses, cancellation,
+loading/error/empty states, keyboard access, focus, semantics, large lists and
+user-visible failure recovery.
+
+Recommend memoization or component extraction only when the affected subtree,
+trigger and measurable benefit are clear. Preserve the established frontend
+architecture and avoid presentation code becoming the source of truth for
+authorization.

package/skills/incident-response/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: incident-response
+description: Investigate an operational failure using a bounded evidence-first response workflow.
+user-invocable: true
+model-invocable: false
+allowed-tools: [filesystem.read, filesystem.list, shell.exec]
+---
+# Incident response
+
+Establish the impact, timeline, affected component and current safety boundary
+before changing anything. Preserve evidence and secrets, inspect logs and
+configuration through approved paths, and separate confirmed facts from
+hypotheses.
+
+Prioritize containment, reversible mitigation, data integrity and clear
+rollback. Record commands, observations, decision points and verification. Do
+not delete evidence, rotate credentials, alter production state or apply a
+destructive fix without explicit authorization.

package/skills/performance-review/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: performance-review
+description: Find evidence-backed performance bottlenecks and define a measurable safe optimization.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list, shell.exec]
+---
+# Performance review
+
+Inspect the complete flow and existing measurements before proposing an
+optimization. Prioritize database and external I/O, duplicate requests,
+blocking CPU work, unbounded concurrency, memory growth and large payloads.
+
+For every finding state the evidence, workload, bottleneck, correctness risks,
+measurement command and acceptance criterion. Do not invent percentage gains or
+recommend caching, memoization, larger pools or infrastructure without an
+invalidation and capacity analysis.

package/skills/refactor/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: refactor
+description: Restructure existing code to improve ownership, reuse and testability without changing behavior.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list, filesystem.exists, filesystem.write, shell.exec]
+---
+# Refactor
+
+Refactor only when the requested scope has a concrete maintainability or
+correctness benefit.
+
+1. Trace all callers, exports, contracts and tests before moving code.
+2. Separate responsibilities by ownership and dependency direction, not by
+   arbitrary file size.
+3. Reuse existing utilities and preserve public behavior, errors, ordering and
+   side effects.
+4. Keep each extracted unit cohesive and independently testable.
+5. Use a focused diff and verify after each safe extraction, then run the
+   broader regression checks.
+
+Do not combine unrelated cleanup, introduce premature generic abstractions or
+hide behavior changes inside a refactor.

package/skills/release-readiness/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: release-readiness
+description: Assess whether a requested change is ready for release across behavior, security, operations and verification.
+user-invocable: true
+model-invocable: false
+allowed-tools: [filesystem.read, filesystem.list, filesystem.exists, shell.exec]
+---
+# Release readiness
+
+Inspect the diff, package metadata, build and test configuration, public
+contracts, migrations, configuration, documentation and deployment assumptions.
+
+Check backward compatibility, secret handling, authorization, error and
+rollback behavior, observability, resource cleanup, versioning and file-size
+constraints. Run only documented checks and report blockers, evidence,
+pre-existing failures and unverified runtime risks separately.

package/skills/security-review/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: security-review
+description: Review the current workspace for security risks with evidence and safe remediation guidance.
+user-invocable: true
+model-invocable: false
+allowed-tools: [filesystem.exists, filesystem.read, filesystem.list]
+---
+
+Review the current workspace for security issues. Trace each relevant input to
+its sensitive sink before reporting it. Prioritize authentication,
+authorization, path traversal, command injection, secret handling, unsafe
+deserialization, and dependency boundaries.
+
+Report only evidence-backed findings. For each finding, include the affected
+file and flow, trigger condition, impact, confidence, and the smallest safe
+remediation. Do not modify files unless the user explicitly asks for a fix.

package/skills/test-plan/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: test-plan
+description: Design a focused test plan covering behavior, errors, security and integration boundaries.
+user-invocable: true
+model-invocable: true
+allowed-tools: [filesystem.read, filesystem.list]
+---
+# Test plan
+
+Create an implementation-ready test plan for the requested change.
+
+Cover:
+
+- happy paths and important edge cases;
+- runtime validation and stable error behavior;
+- authentication, authorization and trust boundaries;
+- cancellation, timeout and bounded-concurrency behavior;
+- persistence, external adapters and malformed input;
+- the narrow unit test, integration test and final regression command.
+
+For each test, state the setup, action, expected result and why it protects a
+business invariant. Prefer behavior assertions over implementation details.

package/skills/verify/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: verify
+description: Identify and run the narrowest relevant verification for the requested workspace change.
+user-invocable: true
+model-invocable: false
+allowed-tools: [filesystem.exists, filesystem.read, filesystem.list, shell.exec]
+---
+
+Inspect the workspace documentation and package configuration to determine the
+narrowest relevant verification for the requested scope. Run only commands
+that are documented by the project. Report each command and its result,
+separating pre-existing failures from failures introduced by the requested
+change. Do not edit source files as part of verification.