feat(skills,cli): benchmark-driven agent efficiency (batch, compact, --pin)

packages/cli/package.json

@@ -5,7 +5,8 @@
     "main": "./dist/lib.js",
     "types": "./dist/lib.d.ts",
     "bin": {
-        "n8nac": "./dist/index.js"
+        "n8nac": "./dist/index.js",
+        "n8n-as-code": "./dist/index.js"
     },
     "type": "module",
     "license": "MIT",

packages/cli/src/commands/base.ts

@@ -169,7 +169,10 @@ export class BaseCommand {
     }
 
     private tryResolveEnvironment(environmentNameOrId?: string): IResolvedWorkspaceEnvironment | undefined {
-        if (!this.configService.isWorkspaceConfigV4()) {
+        // Not `isWorkspaceConfigV4()`: a workspace `.env` resolves an environment with no
+        // config file on disk, and gating on the file alone left `list`/`pull`/`push`
+        // reporting an unconfigured CLI for a workspace that was in fact usable.
+        if (!this.configService.hasResolvableEnvironment()) {
             return undefined;
         }
         try {

packages/cli/src/commands/sync.ts

@@ -10,6 +10,20 @@ import inquirer from 'inquirer';
 
 export class SyncCommand extends BaseCommand {
 
+    /**
+     * Guards the level-0 validation notice: `push --verify` runs pushOne and
+     * verifyRemote on the same instance, and printing the same warning twice
+     * reads as two distinct problems (agents have tried to "fix" the second
+     * one by reconfiguring MCP mid-task). One notice per process is enough.
+     */
+    private levelNoticeShown = false;
+
+    private printLevelZeroNoticeOnce(): void {
+        if (this.levelNoticeShown) return;
+        this.levelNoticeShown = true;
+        console.log(chalk.dim(`   Validated against the bundled schema only (native MCP level 0 — discouraged, the instance may differ). Connect the instance MCP for instance-exact validation: n8nac native-mcp configure --level 1.`));
+    }
+
     async pullOne(workflowId: string): Promise<void> {
         const syncConfig = await this.getSyncConfig();
         const syncManager = new SyncManager(this.client, syncConfig);
@@ -152,7 +166,7 @@ export class SyncCommand extends BaseCommand {
             const finalWorkflowId = await syncManager.push(filename, { draft: options?.draft === true });
             spinner.succeed(chalk.green(`✔ Pushed workflow ${filename}.`));
             if (level === 0) {
-                console.log(chalk.dim(`   Validated against the bundled schema only (native MCP level 0 — discouraged, the instance may differ). Connect the instance MCP for instance-exact validation: n8nac native-mcp configure --level 1.`));
+                this.printLevelZeroNoticeOnce();
             }
             this.reportPublishState(publishReport, finalWorkflowId);
             return finalWorkflowId;
@@ -321,7 +335,7 @@ export class SyncCommand extends BaseCommand {
             console.log(chalk.dim('   Fix the issues locally, then push again.'));
         }
         if (effectiveNativeMcpLevel(this.activeEnvironment?.nativeMcp, process.env.N8NAC_NATIVE_MCP_LEVEL) === 0) {
-            console.log(chalk.dim('   Validated against the bundled schema only (native MCP level 0 — discouraged, the instance may differ). Connect the instance MCP for instance-exact validation: n8nac native-mcp configure --level 1.'));
+            this.printLevelZeroNoticeOnce();
         }
 
         return result.valid;

packages/cli/src/commands/update-ai.ts

@@ -1,8 +1,7 @@
-import { Command } from 'commander';
 import chalk from 'chalk';
 import fs from 'fs';
 import { readFileSync, existsSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+import { join, dirname, resolve, delimiter, basename } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import {
     N8nApiClient,
@@ -70,22 +69,36 @@ function hasWorkspaceDevCommand(projectRoot: string): boolean {
     return N8NAC_DEV_CONFIG_FILENAMES.some((filename) => existsSync(join(projectRoot, filename)));
 }
 
-function inferLocalDevCliCommand(projectRoot: string): string | undefined {
+/**
+ * True when a plain shell resolves `n8nac` on its own.
+ * PATH entries ending in node_modules/.bin are ignored: those are injected by our own
+ * npx / npm-script invocation and will not exist in the agent's shell afterwards.
+ */
+function isN8nacOnShellPath(): boolean {
+    const extensions = process.platform === 'win32'
+        ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+        : [''];
+    return (process.env.PATH || process.env.Path || '').split(delimiter).some((dir) =>
+        dir
+        && basename(dir) !== '.bin'
+        && extensions.some((ext) => existsSync(join(dir, `n8nac${ext}`))));
+}
+
+function inferFastCliCommand(projectRoot: string): string | undefined {
     if (process.env.N8NAC_COMMAND || hasWorkspaceDevCommand(projectRoot)) {
         return undefined;
     }
 
     const entrypoint = process.argv[1] ? resolve(process.argv[1]) : '';
-    if (!entrypoint || entrypoint.includes(`${join('node_modules', '')}`)) {
-        return undefined;
+    if (entrypoint
+        && !entrypoint.includes(`${join('node_modules', '')}`)
+        && entrypoint.endsWith(join('packages', 'cli', 'dist', 'index.js'))
+        && existsSync(entrypoint)) {
+        return `node ${quoteShellArg(entrypoint)}`;
     }
-    if (!entrypoint.endsWith(join('packages', 'cli', 'dist', 'index.js'))) {
-        return undefined;
-    }
-    if (!existsSync(entrypoint)) {
-        return undefined;
-    }
-    return `node ${quoteShellArg(entrypoint)}`;
+
+    // Prefer the installed binary: npx pays npm's own startup on every invocation.
+    return isN8nacOnShellPath() ? 'n8nac' : undefined;
 }
 
 /**
@@ -139,19 +152,6 @@ async function createAiContextGenerator(): Promise<AiContextGeneratorInstance> {
 }
 
 export class UpdateAiCommand {
-    constructor(private program: Command) {
-        this.program
-            .command('update-ai')
-            .description('Update AI Context (AGENTS.md and snippets)')
-            .option('--n8n-version <version>', 'n8n instance version to write when API discovery is unavailable')
-            .option('--cli-version <version>', 'n8nac CLI dist tag to use in generated AI context')
-            .option('--cli-cmd <command>', 'Override the generated n8nac command in AGENTS.md (for local dev builds)')
-            .option('--manager-cmd <command>', 'Override the generated n8n-manager command in AGENTS.md (for local dev builds)')
-            .option('--silent', 'Suppress all output (used for background refresh)')
-            .action(async (options) => {
-                await this.run(options);
-            });
-    }
 
     /**
      * Fire-and-forget check: if AGENTS.md is missing a version stamp or the stamped version
@@ -176,7 +176,7 @@ export class UpdateAiCommand {
                 if (currentLevel === undefined || stampedLevel === currentLevel) return;
             }
 
-            await new UpdateAiCommand(new Command()).run({ silent: true, projectRoot });
+            await new UpdateAiCommand().run({ silent: true, projectRoot });
         } catch {
             // Never surface background refresh errors to the user
         }
@@ -223,7 +223,7 @@ export class UpdateAiCommand {
                 : getDistTag();
             const nativeMcp = resolveActiveNativeMcpLevel(projectRoot);
             await aiContextGenerator.generate(projectRoot, version, distTag, {
-                cliCommandOverride: options.cliCmd || inferLocalDevCliCommand(projectRoot),
+                cliCommandOverride: options.cliCmd || inferFastCliCommand(projectRoot),
                 managerCommandOverride: options.managerCmd || inferLocalDevManagerCommand(),
                 cliVersion: getCliVersion(),
                 nativeMcp,

packages/cli/src/core/services/n8n-api-client.ts

@@ -91,6 +91,10 @@ export class N8nApiClient {
 
         this.client = axios.create({
             baseURL: host,
+            // Fail-closed default: no API call may hang indefinitely on a
+            // stalled network (setup, push, verify). Calls that need longer
+            // pass their own explicit timeout, which takes precedence.
+            timeout: 30_000,
             headers: {
                 'X-N8N-API-KEY': this.apiKey,
                 'Content-Type': 'application/json',
@@ -272,6 +276,35 @@ export class N8nApiClient {
      * 
      * @returns Array of IProject
      */
+    /**
+     * One authenticated request, reported honestly.
+     *
+     * Every other read method here swallows failures and falls back to a placeholder,
+     * which is right for a caller that wants data and wrong for a caller that wants to
+     * know whether the credentials work at all. Only a 2xx proves the n8n public API
+     * accepted the key: 401/403 means it rejected it, and anything else — a 404 from a
+     * non-n8n host, a 5xx, an HTML error page — is not a working API no matter what
+     * answered.
+     *
+     * `timeoutMs` must actually bound the process, not just the caller's patience: a
+     * request that only loses a `Promise.race` keeps the axios socket (and the event
+     * loop) alive until the instance-level timeout fires.
+     */
+    async verifyAccess(timeoutMs?: number): Promise<{ ok: boolean; reason?: 'unauthorized' | 'unreachable' | 'api-unavailable'; status?: number }> {
+        try {
+            await this.client.get('/api/v1/projects', {
+                params: { limit: 1 },
+                ...(timeoutMs ? { timeout: timeoutMs, signal: AbortSignal.timeout(timeoutMs) } : {}),
+            });
+            return { ok: true };
+        } catch (error: any) {
+            const status = error?.response?.status;
+            if (status === 401 || status === 403) return { ok: false, reason: 'unauthorized', status };
+            if (status) return { ok: false, reason: 'api-unavailable', status };
+            return { ok: false, reason: 'unreachable' };
+        }
+    }
+
     async getProjects(): Promise<IProject[]> {
         try {
             const projects: IProject[] = [];