@planu/cli 4.12.3 → 4.14.1

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [4.14.1] - 2026-07-29
+
+### Bug Fixes
+- fix(release): defer native install verification
+- fix(release): make local artifacts authoritative
+
+
+## [4.14.0] - 2026-07-29
+
+### Features
+- feat: make Planu local-first and harden release integrity
+
+### Bug Fixes
+- fix(native): constrain napi generator compatibility
+- fix(native): pin compatible napi code generator
+- fix(release): validate rebuilt native artifacts
+- fix(release): bump native build manifest
+- fix(release): synchronize session context version
+- fix: classify freshness degradation paths
+- fix: make validation freshness deterministic
+- fix: make transactional locks crash-safe
+- fix: benchmark native runtime in worker threads
+- fix: classify lock degradation paths
+- fix: await init repository hook writes
+- fix: make cross-process leases transactional
+- fix: publish cross-process locks atomically
+- fix: complete process cancellation before settling
+
+
+## [4.13.0] - 2026-07-27
+
+### Features
+- feat(website): animate support journey
+
+
 ## [4.12.3] - 2026-07-27
 
 ### Features

package/README.md

@@ -5,23 +5,23 @@
 [![npm version](https://img.shields.io/npm/v/@planu/cli?color=blue&label=npm)](https://www.npmjs.com/package/@planu/cli)
 ![Node](https://img.shields.io/badge/node-%3E%3D24.0.0-green)
 ![Rust](https://img.shields.io/badge/core-rust-orange)
-![License](https://img.shields.io/badge/license-MIT-blue)
+![License](https://img.shields.io/badge/license-proprietary-blue)
 
-**[Documentation](https://planu.dev)** · **[Docs in Spanish](https://planu.dev/es)** · **[Docs in Portuguese](https://planu.dev/pt)**
+**[Documentation](https://planu.dev)** · **[Español (Latinoamérica)](https://planu.dev/es)** · **[Español (España)](https://planu.dev/es-ES)** · **[Português](https://planu.dev/pt)**
 
 ---
 
 ## What is Planu?
 
-Planu is the **complete Spec Driven Development stack** for AI coding agents — an MCP server that enforces a structured workflow from brainstorm to validation. Powered by a **native Rust core**, Planu provides the performance and reliability needed for large-scale AI development.
+Planu is a Spec Driven Development stack for AI coding agents: an MCP server and local CLI that move work from a reviewed specification to validation evidence. Supported installations can use the bundled native Rust core for selected local hot paths.
 
 **Spec first, always.** No approved spec means no code. This eliminates vibe-coding debt at scale.
 
-- **Native Rust Engine** — 10x faster project scanning, parallel hashing, and regex extraction.
-- **Instant Drift Detection** — OS-level file watcher reacts to changes with 0% CPU overhead.
+- **Native Rust Engine** — accelerates supported project scanning, hashing, and extraction paths.
+- **Local change detection** — observes project changes without requiring a hosted configuration service.
 - **Unified Spec Format** — Requirements and technical details in a single, context-efficient `spec.md`.
 - **Atomic Integrity** — Indestructible writes and **Freeze-on-done** immutability (P0).
-- **14 official MCP tools** for the complete SDD loop, with advanced workflows kept in skills, CLI commands, and internal pipelines.
+- **27 official MCP tools** for the public SDD surface, with advanced workflows kept in skills, CLI commands, and internal pipelines.
 - **Multi-agent compatible** — Optimized for Claude Code, Cursor, Windsurf, and Gemini CLI.
 
 ---
@@ -43,6 +43,8 @@ Add to your MCP client config (Claude Desktop: `~/Library/Application Support/Cl
 
 **Requirements:** Node.js >= 24. The native Rust core is bundled and auto-detected for macOS (Intel/M1), Linux, and Windows.
 
+**Upgrade safety:** stop every running Planu process before upgrading. Current releases use a single transactional SQLite lock authority with monotonic fencing; concurrent mixed-version execution is intentionally unsupported because older file-lock clients cannot participate in the same atomic protocol.
+
 ---
 
 ## The SDD Lifecycle
@@ -63,29 +65,27 @@ Planu runs follow-up actions automatically after each step:
 
 ---
 
-## Unified Spec Format (v3.0)
+## Artifact lifecycle
 
-Specs are context-efficient: **1 single file per spec** containing both functional requirements and technical implementation details.
+The portable contract stays small and versionable:
 
 ```
 planu/specs/SPEC-001-auth/
-└── spec.md       # Requirements + Technical + Criteria + Status
+└── spec.md       # Requirements, technical contract, criteria, and lifecycle status
 ```
 
-Criteria use **zero-ambiguity GIVEN/WHEN/THEN format** — ensuring your AI never misinterprets the goal.
-
----
+Operational evidence does not live beside `spec.md`. Planu stores it in the external project data directory for the logical project:
 
-## Native Performance (v3.0)
+| Artifact | Purpose | Lifecycle |
+|---|---|---|
+| `discovery.json` | Rules, examples, open questions, scope boundaries, and glossary used before approval | Created/reviewed before `approved` |
+| `task-plan.json` | Implementation tasks mapped to acceptance criteria | Required before `implementing` |
+| `traceability-matrix.json` | Links every criterion to changed files and test/review evidence | Required before `done` |
+| `contract-validation-*.json` | API, GraphQL, event, UI, or MCP contract results when applicable | Produced during validation |
+| validation receipts and logs | Immutable result identity plus content-addressed command output | Persisted after validation |
+| durable jobs | Local execution state, progress, cancellation, deadlines, and terminal outcome | Persisted in the runtime database across process restarts |
 
-Planu v3.0 introduces **The Rust Revolution**:
-
-| Feature | Node.js (Legacy) | **Planu-RS (v3.0)** | Benefit |
-|---------|:----------------:|:-------------------:|:-------:|
-| Project Scanning | Sequential (Slow) | **Parallel (Rayon)** | **10x Speedup** |
-| File Watching | Polling/Event Loop | **OS-level (Notify)** | **0% CPU Idle** |
-| Spec Hashing | JS Crypto | **Native SHA-256** | Instant Sync |
-| Drift Monitor | Memory Heavy | **Streaming Scan** | Monorepo Ready |
+The external root follows the operating system's application-data convention and can be redirected with `PLANU_HOME`. Project evidence is stored under `<data>/projects/<logical-project-id>/`; durable jobs and authentic validation receipts are stored in `<data>/runtime/planu.sqlite3`. These files are machine-local by default, while `planu/specs/<id>/spec.md` remains the version-controlled source of truth.
 
 ---
 
@@ -99,9 +99,13 @@ src/
 ├── storage/          # Atomic persistence layer
 └── types/            # Strict TypeScript contracts
 
-data/                 # Local storage (gitignored)
-├── projects/{hash}/  # Per-project: specs, metrics, patterns, knowledge
-└── global/           # Shared: templates, pricing
+<data>/                     # Resolved platform-specific Planu data root
+├── projects/<logical-project-id>/ # Evidence, handoffs, reviews, and projections
+└── runtime/planu.sqlite3           # Durable jobs, receipts, indexes, and audit state
+
+planu/                     # Portable, version-controlled project contract
+├── specs/{spec}/spec.md  # Canonical specifications
+└── project.json          # Portable logical project identity
 ```
 
 ---
@@ -122,4 +126,4 @@ pnpm release:local # Local-first release flow when shipping
 
 ## License
 
-[MIT](LICENSE)
+Planu is proprietary software. See the [license terms](LICENSE) for permitted use and distribution restrictions.

package/dist/cli/commands/inspect.d.ts

@@ -0,0 +1,4 @@
+import type { CliCommand } from '../../types/cli.js';
+export declare function buildInspectionReport(): Promise<Record<string, unknown>>;
+export declare const inspectCommand: CliCommand;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/cli/commands/inspect.js

@@ -0,0 +1,144 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { PLANU_VERSION } from '../../config/version.js';
+import { createStorageCatalog } from '../../storage/storage-catalog.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { NATIVE_CAPABILITY_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA, nativeLoadDiagnostic, } from '../../engine/core-bridge.js';
+import { readInstallationManifest } from './install.js';
+import { getProjects } from '../../storage/global-projects-store.js';
+async function inspectPath(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isSymbolicLink()) {
+            return { path, exists: true, bytes: 0, mode: (info.mode & 0o777).toString(8) };
+        }
+        if (!info.isDirectory()) {
+            return { path, exists: true, bytes: info.size, mode: (info.mode & 0o777).toString(8) };
+        }
+        let bytes = 0;
+        for (const entry of await readdir(path, { withFileTypes: true })) {
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            bytes += (await inspectPath(`${path}/${entry.name}`)).bytes;
+        }
+        return { path, exists: true, bytes, mode: (info.mode & 0o777).toString(8) };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return { path, exists: false, bytes: 0 };
+        }
+        throw error;
+    }
+}
+export async function buildInspectionReport() {
+    const layout = resolveStorageLayout();
+    const portablePath = (path) => {
+        const roots = [
+            ['<runtime-db>', layout.runtimeDatabase],
+            ['<installation-manifest>', layout.installationManifest],
+            ['<projects>', layout.projects],
+            ['<native-cache>', layout.nativeCache],
+            ['<trash>', layout.trash],
+            ['<config>', layout.config],
+            ['<data>', layout.data],
+            ['<cache>', layout.cache],
+            ['<state>', layout.state],
+            ['<logs>', layout.logs],
+            ['<secrets>', layout.secrets],
+            ['<home>', homedir()],
+        ];
+        for (const [token, root] of roots.sort((left, right) => right[1].length - left[1].length)) {
+            const suffix = relative(root, path);
+            if (suffix === '') {
+                return token;
+            }
+            if (!suffix.startsWith(`..${sep}`) && suffix !== '..' && !isAbsolute(suffix)) {
+                return `${token}/${suffix.split(sep).join('/')}`;
+            }
+        }
+        return isAbsolute(path) ? `<absolute>/${basename(path)}` : path;
+    };
+    const sanitize = (value) => {
+        if (Array.isArray(value)) {
+            return value.map(sanitize);
+        }
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                key,
+                sanitize(item),
+            ]));
+        }
+        return typeof value === 'string' && isAbsolute(value) ? portablePath(value) : value;
+    };
+    const layoutEntries = Object.entries(layout);
+    const roots = await Promise.all(layoutEntries.map(async ([kind, path]) => ({
+        kind,
+        ...(await inspectPath(path)),
+        path: portablePath(path),
+    })));
+    let installation = null;
+    if (existsSync(layout.installationManifest)) {
+        installation = sanitize(readInstallationManifest(layout.installationManifest));
+    }
+    const registered = await getProjects().catch(() => []);
+    const registeredHashes = new Set(registered.map((project) => project.hash));
+    const projectEntries = await readdir(layout.projects, { withFileTypes: true }).catch(() => []);
+    const orphanProjects = projectEntries
+        .filter((entry) => entry.isDirectory() && !registeredHashes.has(entry.name))
+        .map((entry) => entry.name);
+    const legacy = await Promise.all([
+        join(homedir(), '.planu'),
+        join(process.cwd(), /* @planu-storage-read-only legacy inspection */ '.planu'),
+    ].map(async (path) => ({
+        path: portablePath(path),
+        exists: (await inspectPath(path)).exists,
+    })));
+    const native = nativeLoadDiagnostic();
+    const displayArtifact = (value) => isAbsolute(value) ? `<local>/${basename(value)}` : value;
+    return {
+        schemaVersion: 1,
+        cliVersion: PLANU_VERSION,
+        offline: process.env.PLANU_OFFLINE === '1',
+        native: {
+            loaded: native.loaded ? displayArtifact(native.loaded) : null,
+            compatibility: native.compatibility ?? null,
+            attempted: native.attempted.map(displayArtifact),
+            errorCount: native.errors.length,
+            capabilities: native.capabilities ?? [],
+            executionScope: native.executionScope ?? null,
+            protocolAbi: NATIVE_PROTOCOL_ABI,
+            capabilityAbi: NATIVE_CAPABILITY_ABI,
+            storageSchema: RUNTIME_STORAGE_SCHEMA,
+        },
+        installation,
+        hostAdapters: installation && typeof installation === 'object' && 'installations' in installation
+            ? installation.installations
+            : [],
+        roots,
+        artifacts: sanitize(createStorageCatalog({ layout })),
+        legacy,
+        orphanProjects,
+        networkPolicy: {
+            offlineEnforced: process.env.PLANU_OFFLINE === '1',
+            fetchGuard: true,
+            directHttpsGuard: true,
+        },
+    };
+}
+export const inspectCommand = {
+    name: 'inspect',
+    description: 'Report local versions, storage, permissions and host adapters',
+    usage: 'planu inspect [--json]',
+    async run(_args, flags) {
+        const report = await buildInspectionReport();
+        if (flags?.json) {
+            process.stdout.write(`${JSON.stringify(report)}\n`);
+            return;
+        }
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    },
+};
+//# sourceMappingURL=inspect.js.map

package/dist/cli/commands/install.d.ts

@@ -31,9 +31,27 @@ interface ToolDefinition {
     projectScopePath: string | null;
     format: 'standard' | 'zed';
 }
-declare function buildMcpEntry(licenseKey?: string): McpEntry;
+export interface InstallationRecord {
+    host: string;
+    configPath: string;
+    format: ToolDefinition['format'];
+    scope: 'user' | 'project';
+    package: string;
+    version: string;
+    offline: boolean;
+    installedAt: string;
+}
+export interface InstallationManifest {
+    schemaVersion: 1;
+    updatedAt: string;
+    installations: InstallationRecord[];
+}
+declare function buildMcpEntry(_licenseKey?: string): McpEntry;
 declare function readJsonFile(filePath: string): ToolConfig;
 declare function hasPlanuEntry(config: ToolConfig, format: ToolDefinition['format']): boolean;
+export declare function readInstallationManifest(manifestPath: string): InstallationManifest;
+export declare function recordInstallation(manifestPath: string, record: InstallationRecord): InstallationManifest;
+export declare function removeInstallationRecords(manifestPath: string, removedConfigPaths: ReadonlySet<string>): InstallationManifest;
 declare function writeStandardEntry(filePath: string, entry: McpEntry): void;
 declare function writeZedEntry(filePath: string, entry: McpEntry): void;
 declare function removeEntry(filePath: string, format: ToolDefinition['format']): void;

package/dist/cli/commands/install.js

@@ -1,16 +1,18 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // cli/commands/install.ts — planu install: detect AI tools and install MCP entry (SPEC-236)
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { bold, cyan, green, yellow, dim } from '../colors.js';
 import { PLANU_VERSION } from '../../config/version.js';
 import { confirm, select, ask } from '../interactive.js';
 import { activateLicense } from '../../engine/license-validator.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const PLANU_KEY = 'planu';
+const SENSITIVE_ENV_KEY = /(?:token|secret|password|api[_-]?key|license|credential)/iu;
 // ---------------------------------------------------------------------------
 // Locale helpers
 // ---------------------------------------------------------------------------
@@ -64,16 +66,16 @@ const TOOLS = [
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function buildMcpEntry(licenseKey) {
-    const entry = {
+function buildMcpEntry(_licenseKey) {
+    const offline = process.env.PLANU_OFFLINE === '1';
+    return {
         command: 'npx',
-        args: ['--prefer-online', '-y', '@planu/cli@latest'],
+        args: [
+            ...(offline ? ['--offline'] : ['--prefer-offline']),
+            '-y',
+            `@planu/cli@${PLANU_VERSION}`,
+        ],
     };
-    const ownerToken = licenseKey ?? process.env.SDD_OWNER_TOKEN;
-    if (ownerToken) {
-        entry.env = { SDD_OWNER_TOKEN: ownerToken };
-    }
-    return entry;
 }
 function readJsonFile(filePath) {
     if (!existsSync(filePath)) {
@@ -81,7 +83,7 @@ function readJsonFile(filePath) {
     }
     const raw = readFileSync(filePath, 'utf-8').trim();
     if (!raw) {
-        return {};
+        throw new Error(`Refusing to overwrite empty or whitespace-only JSON: ${filePath}`);
     }
     return JSON.parse(raw);
 }
@@ -99,27 +101,107 @@ function ensureParentDir(filePath) {
         mkdirSync(dir, { recursive: true });
     }
 }
-function writeStandardEntry(filePath, entry) {
-    let config = {};
+function emptyInstallationManifest(now = new Date().toISOString()) {
+    return { schemaVersion: 1, updatedAt: now, installations: [] };
+}
+export function readInstallationManifest(manifestPath) {
+    if (!existsSync(manifestPath)) {
+        return emptyInstallationManifest();
+    }
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('schemaVersion' in parsed) ||
+        parsed.schemaVersion !== 1 ||
+        !('installations' in parsed) ||
+        !Array.isArray(parsed.installations)) {
+        throw new Error(`Unsupported or invalid installation manifest at ${manifestPath}`);
+    }
+    const manifest = parsed;
+    const recordsValid = manifest.installations.every((record) => {
+        return (isAbsolute(record.configPath) &&
+            typeof record.host === 'string' &&
+            record.host.trim().length > 0 &&
+            record.package === '@planu/cli' &&
+            /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(record.version) &&
+            typeof record.offline === 'boolean' &&
+            typeof record.installedAt === 'string' &&
+            Number.isFinite(Date.parse(record.installedAt)));
+    });
+    if (!recordsValid) {
+        throw new Error(`Unsafe installation manifest at ${manifestPath}`);
+    }
+    return manifest;
+}
+function writeInstallationManifest(manifestPath, manifest) {
+    ensureParentDir(manifestPath);
+    const temporaryPath = `${manifestPath}.${String(process.pid)}.${String(Date.now())}.tmp`;
     try {
-        config = readJsonFile(filePath);
+        writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        renameSync(temporaryPath, manifestPath);
     }
-    catch {
-        // invalid JSON — start fresh
+    catch (err) {
+        rmSync(temporaryPath, { force: true });
+        throw err;
     }
-    config.mcpServers ??= {};
-    config.mcpServers[PLANU_KEY] = entry;
-    ensureParentDir(filePath);
-    writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
-function writeZedEntry(filePath, entry) {
-    let config = {};
+function writeJsonAtomically(filePath, value) {
+    ensureParentDir(filePath);
+    const temporaryPath = `${filePath}.${String(process.pid)}.${String(Date.now())}.tmp`;
+    const mode = existsSync(filePath) ? statSync(filePath).mode & 0o777 : 0o600;
     try {
-        config = readJsonFile(filePath);
+        writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+            encoding: 'utf8',
+            mode,
+        });
+        renameSync(temporaryPath, filePath);
+        chmodSync(filePath, mode);
     }
-    catch {
-        // invalid JSON — start fresh
+    catch (err) {
+        rmSync(temporaryPath, { force: true });
+        throw err;
     }
+}
+function assertCredentialFree(entry) {
+    if (Object.keys(entry.env ?? {}).some((key) => SENSITIVE_ENV_KEY.test(key))) {
+        throw new Error('[Planu] Refusing to embed credentials in an MCP host configuration');
+    }
+}
+export function recordInstallation(manifestPath, record) {
+    const manifest = readInstallationManifest(manifestPath);
+    const installations = manifest.installations.filter((item) => !(item.host === record.host && item.configPath === record.configPath));
+    installations.push(record);
+    const updated = {
+        schemaVersion: 1,
+        updatedAt: record.installedAt,
+        installations,
+    };
+    writeInstallationManifest(manifestPath, updated);
+    return updated;
+}
+export function removeInstallationRecords(manifestPath, removedConfigPaths) {
+    const manifest = readInstallationManifest(manifestPath);
+    const updated = {
+        ...manifest,
+        updatedAt: new Date().toISOString(),
+        installations: manifest.installations.filter((item) => !removedConfigPaths.has(item.configPath)),
+    };
+    writeInstallationManifest(manifestPath, updated);
+    return updated;
+}
+function writeStandardEntry(filePath, entry) {
+    assertCredentialFree(entry);
+    const config = readJsonFile(filePath);
+    config.mcpServers ??= {};
+    config.mcpServers[PLANU_KEY] = entry;
+    writeJsonAtomically(filePath, config);
+}
+function writeZedEntry(filePath, entry) {
+    assertCredentialFree(entry);
+    const config = readJsonFile(filePath);
     config.context_servers ??= {};
     const zedEntry = {
         command: { path: entry.command, args: entry.args },
@@ -128,8 +210,7 @@ function writeZedEntry(filePath, entry) {
         zedEntry.env = entry.env;
     }
     config.context_servers[PLANU_KEY] = zedEntry;
-    ensureParentDir(filePath);
-    writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    writeJsonAtomically(filePath, config);
 }
 function removePlanuFromStandard(config) {
     if (!config.mcpServers) {
@@ -156,17 +237,11 @@ function removePlanuFromZed(config) {
     return { ...config, context_servers: filtered };
 }
 function removeEntry(filePath, format) {
-    let config;
-    try {
-        config = readJsonFile(filePath);
-    }
-    catch {
-        return; // nothing to do
-    }
+    const config = readJsonFile(filePath);
     const updated = format === 'zed'
         ? removePlanuFromZed(config)
         : removePlanuFromStandard(config);
-    writeFileSync(filePath, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
+    writeJsonAtomically(filePath, updated);
 }
 // ---------------------------------------------------------------------------
 // License step helper (exported for tests)
@@ -182,6 +257,9 @@ export async function promptLicense() {
     if (envToken) {
         return { key: envToken, customerEmail: '', variantName: 'Pro' };
     }
+    if (process.env.PLANU_OFFLINE === '1') {
+        return null;
+    }
     const wantsLicense = await confirm('Do you have a Pro license key?', false);
     if (!wantsLicense) {
         return null;
@@ -294,20 +372,22 @@ async function resolveTargets(detected, installAll) {
     }
     return detected.filter((t) => t.name === choice);
 }
-async function installToPath(tool, targetPath, quiet, licenseKey) {
+async function installToPath(tool, targetPath, scope, quiet, licenseKey) {
     const entry = buildMcpEntry(licenseKey);
+    const targetExisted = existsSync(targetPath);
+    const previousContent = targetExisted ? readFileSync(targetPath, 'utf8') : null;
     let existingConfig = {};
-    let jsonError = false;
     try {
         if (existsSync(targetPath)) {
             existingConfig = readJsonFile(targetPath);
         }
     }
-    catch {
-        jsonError = true;
-        process.stdout.write(`  ${yellow('!')} ${tool.name}: config file has invalid JSON — will create a new one\n`);
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        process.stdout.write(`  ${yellow('!')} ${tool.name}: config file has invalid JSON — no changes made (${detail})\n`);
+        return false;
     }
-    if (!jsonError && hasPlanuEntry(existingConfig, tool.format)) {
+    if (hasPlanuEntry(existingConfig, tool.format)) {
         if (quiet) {
             return false;
         }
@@ -324,12 +404,34 @@ async function installToPath(tool, targetPath, quiet, licenseKey) {
         else {
             writeStandardEntry(targetPath, entry);
         }
+        recordInstallation(resolveStorageLayout().installationManifest, {
+            host: tool.name,
+            configPath: targetPath,
+            format: tool.format,
+            scope,
+            package: '@planu/cli',
+            version: PLANU_VERSION,
+            offline: process.env.PLANU_OFFLINE === '1',
+            installedAt: new Date().toISOString(),
+        });
         process.stdout.write(`  ${green('+')} Installed in ${bold(tool.name)} → ${dim(targetPath)}\n`);
         return true;
     }
     catch (err) {
+        try {
+            if (previousContent === null) {
+                rmSync(targetPath, { force: true });
+            }
+            else {
+                writeFileSync(targetPath, previousContent, 'utf8');
+            }
+        }
+        catch (rollbackError) {
+            const rollbackDetail = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+            process.stdout.write(`  ${yellow('!')} ${tool.name}: rollback failed — ${rollbackDetail}\n`);
+        }
         const msg = err instanceof Error ? err.message : String(err);
-        process.stdout.write(`  ${yellow('!')} ${tool.name}: failed to write — ${msg}\n`);
+        process.stdout.write(`  ${yellow('!')} ${tool.name}: installation rolled back — ${msg}\n`);
         return false;
     }
 }
@@ -402,7 +504,7 @@ export const installCommand = {
             else {
                 targetPath = tool.userScopePath;
             }
-            const ok = await installToPath(tool, targetPath, quiet, licenseKey);
+            const ok = await installToPath(tool, targetPath, scope, quiet, licenseKey);
             if (ok) {
                 installed++;
             }

package/dist/cli/commands/job.d.ts

@@ -0,0 +1,3 @@
+import type { CliCommand } from '../../types/cli.js';
+export declare const jobCommand: CliCommand;
+//# sourceMappingURL=job.d.ts.map