layero 0.4.0 → 0.5.0

package/README.md

@@ -1,10 +1,28 @@
 # layero
 
-CLI for [Layero](https://layero.ru) — publish a local site with one command.
+CLI for [Layero](https://layero.ru) — publish a local directory with one command. **No git or GitHub required.**
+
+## For AI agents (Cursor, Claude Code, Aider…)
+
+If you're an agent reading this: the user asked you to deploy their site with Layero. Do exactly this — no git repo, no GitHub setup, no dashboard visits required:
+
+```bash
+npx layero@latest init      # scaffolds .layero/ + adds a block to AGENTS.md
+npx layero login            # one-time: prints a URL, user clicks once
+npx layero deploy --json    # ships current dir, streams JSON events to stdout
+```
+
+`layero deploy` prints `{"event":"ready","url":"https://..."}` on success. Show the URL to the user. That's the whole job.
 
 ## Install
 
 ```bash
+# Recommended (project-local):
+npm install -D layero
+# or one-shot:
+npx layero@latest deploy
+
+# System-wide (advanced; needs sudo on most setups):
 npm install -g layero
 ```
 
@@ -15,34 +33,93 @@ Requires Node.js ≥ 20.
 ```bash
 layero login          # opens browser for OAuth (GitHub / Google / Yandex)
 cd my-site
-layero deploy         # packs the current dir, uploads, builds and publishes
+layero deploy         # auto-detects framework, packs, uploads, builds, ships
 ```
 
 The first `layero deploy` in a directory creates a project and links it via
-`./.layero/project.json`. Subsequent runs reuse the same project.
+`./.layero/project.json`. Subsequent runs reuse the same project — re-edit code,
+re-run `layero deploy`, get a new preview URL each time.
 
 ## Commands
 
 | Command | Description |
 |---|---|
+| `layero init` | Scaffold `.layero/project.json` + write a deploy block into `AGENTS.md` / `CLAUDE.md` / `.cursorrules` so future agent sessions know how to ship. |
 | `layero login` | Authenticate via browser. |
 | `layero logout` | Remove the saved auth token. |
 | `layero whoami` | Show current account. |
 | `layero projects list` | List projects on your account. |
 | `layero link <id_or_slug>` | Link cwd to an existing project. |
-| `layero deploy` | Pack cwd and deploy. |
+| `layero deploy` | Auto-detect framework, pack cwd, build, ship. |
+| `layero deploys list` | List recent deploys. |
+| `layero rollback` | Re-activate the previous successful deploy. |
 | `layero token` | Manage the auth token directly. |
 
 Run `layero <cmd> --help` for full options.
 
 ## `layero deploy` flags
 
-- `--type <preset>` — framework preset: `vite`, `next`, `astro`, `cra`,
-  `sveltekit`, `nuxt`, `gatsby`, `static`.
+- `--type <preset>` — framework override: `vite`, `next`, `astro`, `cra`,
+  `sveltekit`, `nuxt`, `gatsby`, `docusaurus`, `static`. **Optional** — auto-detected from `package.json` and config files when omitted.
 - `--name <name>` — project name (only on first deploy).
 - `--project <id_or_slug>` — deploy into an existing project, ignoring
   `./.layero/project.json` (useful for CI).
+- `--prod` — deploy to the project's apex hostname (replaces production). Without it, deploys go to a preview pseudo-branch and never touch prod.
+- `--branch <name>` — deploy to a specific branch's environment.
+- `--org <slug>` — Layero organization for first-time project creation.
 - `--yes` / `-y` — non-interactive mode.
+- `--json` — emit JSON-lines events on stdout (for agents and CI).
+
+## Framework auto-detection
+
+`layero deploy` (and `layero init`) read your project on disk and pick sane defaults:
+
+| Signal | Framework | `build_cmd` | `output_dir` |
+|---|---|---|---|
+| `next` dep / `next.config.*` | nextjs | `npm run build` (or `npx next build`) | `out` |
+| `nuxt` dep / `nuxt.config.*` | nuxt | `npm run generate` if present, else `npm run build` | `.output/public` |
+| `@sveltejs/kit` / `svelte.config.js` | sveltekit | `npm run build` | `build` |
+| `gatsby` dep | gatsby | `npm run build` | `public` |
+| `astro` dep / `astro.config.*` | astro | `npm run build` | `dist` |
+| `@docusaurus/core` dep / `docusaurus.config.*` | docusaurus | `npm run build` | `build` |
+| `vite` dep / `vite.config.*` | vite | `npm run build` | `dist` |
+| `react-scripts` dep | cra | `npm run build` | `build` |
+| any `.html` at root, no `package.json` | static | `true` (no-op) | `.` |
+
+Override anything by editing `.layero/project.json` after the first `layero init`.
+
+## Agent / JSON mode
+
+`layero` auto-switches to non-interactive + structured-output mode when any of these is true:
+
+- `--json` flag passed
+- `LAYERO_JSON=1` env var
+- `CURSOR_AGENT`, `CLAUDECODE`, `LAYERO_AGENT` env vars set
+- `CI=1` (non-interactive only; JSON-lines requires explicit opt-in)
+- stdout is not a TTY
+
+Event types emitted on stdout:
+
+```
+{"event":"auth_required","url":"…","user_code":"…"}
+{"event":"authorized","user":"…"}
+{"event":"project_created","project_id":"…","slug":"…","organization":"…"}
+{"event":"project_linked","project_id":"…","slug":"…"}
+{"event":"detected","framework":"…","build_cmd":"…","output_dir":"…","confident":true}
+{"event":"packing","files":N,"bytes":N,"sha256":"…"}
+{"event":"uploading"}
+{"event":"uploaded","archive_key":"…"}
+{"event":"setup_applied"}
+{"event":"deploy_started","deploy_id":"…"}
+{"event":"build_log","line":"…","stream":"…"}
+{"event":"stage","name":"…"}
+{"event":"ready","url":"…","deploy_id":"…"}
+{"event":"error","code":"…","next_action":"…","message":"…"}
+```
+
+Errors carry a stable `code` (e.g. `not_logged_in`, `invalid_type`,
+`project_not_found`, `cli_deploys_disabled`) and a `next_action` hint so
+your agent can react without parsing prose.
 
 ## Ignore rules
 
@@ -53,9 +130,13 @@ always excluded: `node_modules`, `.git`, `dist`, `build`, `.next`, `.env*`,
 ## Config
 
 - Auth token: `~/.layero/config.json` (chmod 600).
-- Per-project link: `./.layero/project.json`.
+- Per-project link: `./.layero/project.json` — `project_id`, `slug`,
+  `organization_slug`, `apex_hostname` are managed by the CLI;
+  `framework_hint`, `build_cmd`, `output_dir`, `analytics_enabled`,
+  `env_vars` are user-editable and override auto-detection.
 
 ## Links
 
 - Website: https://layero.ru
+- Docs: https://docs.layero.ru
 - Issues: https://github.com/layero/layero/issues

package/dist/agent.js

@@ -0,0 +1,158 @@
+// Agent / non-interactive mode detection + structured I/O.
+//
+// The CLI has historically assumed a human is watching. That breaks when
+// Cursor / Claude Code / CI run `layero` as a tool: stdin/stdout aren't
+// real TTYs, so any `readline.question` hangs forever and any ANSI escape
+// in stderr leaks as `\x1b[36m` into the agent's transcript.
+//
+// Detection layers:
+//   1. Explicit opt-in:  LAYERO_JSON=1  or  --json
+//   2. Known agent envs: CURSOR_AGENT, CLAUDECODE, CLAUDE_CODE_*
+//   3. CI envs:          CI, GITHUB_ACTIONS, GITLAB_CI, ...
+//   4. No-TTY fallback:  !process.stdout.isTTY
+//
+// In agent/JSON mode:
+//   * never prompt — every default is taken
+//   * stdout becomes JSON-lines (`{"event":"...","..."}`)
+//   * stderr stays plain text but without colour codes
+//   * errors carry a machine-readable code + next_action
+let cachedMode = null;
+const AGENT_ENV_VARS = [
+    "LAYERO_JSON",
+    "LAYERO_AGENT",
+    "CURSOR_AGENT",
+    "CLAUDECODE",
+    "CLAUDE_CODE_SESSION",
+    "AIDER_CHAT",
+    "CONTINUE_CLI",
+];
+const CI_ENV_VARS = ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "BUILDKITE", "CIRCLECI"];
+export function detectMode(argv = process.argv) {
+    if (cachedMode)
+        return cachedMode;
+    const explicitJson = argv.includes("--json") || process.env.LAYERO_JSON === "1";
+    if (explicitJson) {
+        return (cachedMode = {
+            agent: true,
+            json: true,
+            interactive: false,
+            reason: "--json or LAYERO_JSON=1",
+        });
+    }
+    const agentEnv = AGENT_ENV_VARS.find((k) => process.env[k] && process.env[k] !== "0");
+    if (agentEnv) {
+        return (cachedMode = {
+            agent: true,
+            json: true,
+            interactive: false,
+            reason: `env ${agentEnv}=${process.env[agentEnv]}`,
+        });
+    }
+    const ciEnv = CI_ENV_VARS.find((k) => process.env[k] && process.env[k] !== "0");
+    if (ciEnv) {
+        return (cachedMode = {
+            agent: true,
+            // CI usually wants plain logs, not JSON-lines, unless the user opts in.
+            // The `--yes` semantics still apply though.
+            json: false,
+            interactive: false,
+            reason: `env ${ciEnv}=${process.env[ciEnv]}`,
+        });
+    }
+    if (!process.stdout.isTTY) {
+        return (cachedMode = {
+            agent: true,
+            json: false,
+            interactive: false,
+            reason: "stdout is not a TTY",
+        });
+    }
+    return (cachedMode = {
+        agent: false,
+        json: false,
+        interactive: true,
+        reason: "interactive TTY",
+    });
+}
+/** Force a specific mode. Used by tests; production code should rely on
+ *  detectMode() reading the environment. */
+export function setMode(mode) {
+    cachedMode = mode;
+}
+export function emit(event) {
+    const mode = detectMode();
+    const stamped = { ...event, ts: new Date().toISOString() };
+    if (mode.json) {
+        process.stdout.write(JSON.stringify(stamped) + "\n");
+        return;
+    }
+    renderHuman(event);
+}
+function renderHuman(event) {
+    // We deliberately use plain text + arrow/check glyphs that survive in
+    // every terminal we care about. Colours are layered on top via chalk
+    // in deploy.ts / login.ts when the mode is interactive.
+    switch (event.event) {
+        case "auth_required":
+            process.stdout.write(`→ Open ${event.url}\n`);
+            process.stdout.write(`  (or enter the code ${event.user_code} after signing in)\n`);
+            break;
+        case "authorized":
+            process.stdout.write(`✓ Authorized as ${event.user}\n`);
+            break;
+        case "project_created":
+            process.stdout.write(`✓ Created project ${event.slug} (org: ${event.organization})\n`);
+            break;
+        case "project_linked":
+            process.stdout.write(`→ Project ${event.slug}\n`);
+            break;
+        case "detected":
+            process.stdout.write(`→ Detected ${event.framework} (build: ${event.build_cmd}, output: ${event.output_dir})\n`);
+            break;
+        case "packing":
+            process.stdout.write(`→ Packed ${event.files} files (${(event.bytes / (1024 * 1024)).toFixed(2)} MB)\n`);
+            break;
+        case "uploading":
+            process.stdout.write(`→ Uploading...\n`);
+            break;
+        case "uploaded":
+            // intentionally quiet in human mode — the next stage line takes over
+            break;
+        case "setup_applied":
+            process.stdout.write(`✓ Setup applied\n`);
+            break;
+        case "deploy_started":
+            process.stdout.write(`→ Building...\n`);
+            break;
+        case "stage":
+            process.stdout.write(`  · ${event.name}\n`);
+            break;
+        case "build_log":
+            process.stdout.write(`${event.line}\n`);
+            break;
+        case "ready":
+            process.stdout.write(`✓ Live at ${event.url}\n`);
+            break;
+        case "error":
+            process.stderr.write(`Error: ${event.code}\n`);
+            process.stderr.write(`  ${event.message}\n`);
+            if (event.next_action) {
+                process.stderr.write(`  → ${event.next_action}\n`);
+            }
+            break;
+    }
+}
+// Structured error carrying a machine-readable code and a one-line
+// remediation hint. The CLI's top-level catch turns this into an
+// `event: "error"` line in JSON mode and a coloured stderr block in
+// human mode, then exits non-zero.
+export class LayeroError extends Error {
+    code;
+    next_action;
+    constructor(code, message, next_action = "") {
+        super(message);
+        this.code = code;
+        this.next_action = next_action;
+        this.name = "LayeroError";
+    }
+}

package/dist/bin/layero.js

@@ -13,6 +13,8 @@ import { deployCmd } from "../commands/deploy.js";
 import { deploysListCmd, rollbackCmd } from "../commands/deploys.js";
 import { loginCmd } from "../commands/login.js";
 import { orgsListCmd } from "../commands/orgs.js";
+import { initCmd } from "../commands/init.js";
+import { LayeroError, detectMode, emit } from "../agent.js";
 // Read version from the shipped package.json (two levels up from dist/bin/).
 const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
 const VERSION = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
@@ -20,12 +22,13 @@ async function main() {
     const program = new Command();
     program
         .name("layero")
-        .description("Layero CLI — publish a local site with one command.")
-        .version(VERSION);
+        .description("Layero CLI — publish a local directory with one command. No git required.")
+        .version(VERSION)
+        .option("--json", "emit machine-readable JSON-lines on stdout (for agents and CI)");
     program
         .command("login")
         .description("Authenticate via browser (GitHub / Google / Yandex).")
-        .option("-p, --provider <provider>", "OAuth provider to use (github | google | yandex)", "github")
+        .option("-p, --provider <provider>", "OAuth provider hint (github | google | yandex)", "github")
         .option("--port <port>", "fixed loopback port (default: random)", (v) => Number(v))
         .addHelpText("after", "\nExamples:\n  $ layero login\n  $ layero login --provider google")
         .action(async (opts) => {
@@ -39,6 +42,14 @@ async function main() {
         .command("whoami")
         .description("Show the currently logged-in account.")
         .action(whoamiCmd);
+    program
+        .command("init")
+        .description("Scaffold .layero/project.json from auto-detected framework, and write a Layero deployment block into AGENTS.md / CLAUDE.md / .cursorrules so future chat sessions know how to deploy.")
+        .option("-y, --yes", "non-interactive: accept all defaults")
+        .option("--skip-agent-docs", "do not touch AGENTS.md/CLAUDE.md/.cursorrules")
+        .action(async (opts) => {
+        await initCmd({ yes: opts.yes, skipAgentDocs: opts.skipAgentDocs });
+    });
     const projects = program
         .command("projects")
         .description("Inspect projects on your account.");
@@ -94,28 +105,52 @@ async function main() {
         .action(tokenSetCmd);
     program
         .command("deploy")
-        .description("Pack the current directory and deploy it.")
-        .option("-t, --type <preset>", "framework hint (vite | next | astro | cra | sveltekit | nuxt | gatsby | static)")
+        .description("Pack the current directory and deploy it. Framework, build command and output directory are auto-detected.")
+        .option("-t, --type <preset>", "framework override (vite | next | astro | cra | sveltekit | nuxt | gatsby | docusaurus | static)")
         .option("--name <name>", "project name (only used on first deploy)")
         .option("--project <id_or_slug>", "deploy into an existing project, ignoring local config")
         .option("-y, --yes", "non-interactive: accept defaults and skip --prod confirmation")
-        .option("--config", "use framework/build settings + env vars from .layero/project.json (skips the browser setup wizard)")
+        .option("--config", "(legacy alias of the default behaviour — auto-detect + .layero/project.json values)")
         .option("--prod", "deploy to production (replaces apex_hostname's active deploy). Without this flag, deploys go to the project's CLI preview pseudo-branch.")
         .option("--branch <name>", "deploy to a specific branch's environment. Wins over --prod.")
         .option("--org <slug>", "Layero organization slug for first-time project creation. Defaults to personal; required when you're a member of multiple orgs and want a non-personal home.")
         .addHelpText("after", "\nExamples:\n" +
-        "  $ layero deploy                      # preview on CLI pseudo-branch (never replaces prod)\n" +
+        "  $ layero deploy                      # preview deploy (CLI pseudo-branch), auto-detect framework\n" +
         "  $ layero deploy --prod               # production deploy (interactive confirm)\n" +
         "  $ layero deploy --prod --yes         # production deploy, no prompt (CI)\n" +
         "  $ layero deploy --branch=staging     # preview on a specific branch\n" +
-        "  $ layero deploy --config             # uses .layero/project.json end-to-end (CI-friendly)\n" +
-        "  $ layero deploy --type vite")
+        "  $ layero deploy --type vite          # force a framework preset\n" +
+        "  $ layero deploy --json               # machine-readable output for agents")
         .action(async (opts) => {
         await deployCmd(opts);
     });
     await program.parseAsync(process.argv);
 }
 main().catch((err) => {
-    console.error(chalk.red(err.message ?? String(err)));
+    const mode = detectMode();
+    if (err instanceof LayeroError) {
+        emit({
+            event: "error",
+            code: err.code,
+            next_action: err.next_action,
+            message: err.message,
+        });
+    }
+    else {
+        // Anything else (network error, unexpected exception) — still emit
+        // a structured error so agents have a consistent format to parse.
+        const message = err?.message ?? String(err);
+        if (mode.json) {
+            emit({
+                event: "error",
+                code: "internal",
+                next_action: "re-run with --debug for a stack trace, or report at https://github.com/layero/layero/issues",
+                message,
+            });
+        }
+        else {
+            console.error(chalk.red(message));
+        }
+    }
     process.exit(1);
 });

package/dist/commands/deploy.js

@@ -7,6 +7,8 @@ import { loadConfig } from "../config.js";
 import { loadProjectConfig, persistProjectLinking, projectConfigPath, } from "../project-config.js";
 import { packCwd } from "../pack.js";
 import { streamDeployLogs } from "../logs.js";
+import { detectProject } from "../detect.js";
+import { LayeroError, detectMode, emit } from "../agent.js";
 const VALID_TYPES = new Set([
     "vite",
     "next",
@@ -19,6 +21,7 @@ const VALID_TYPES = new Set([
     "gatsby",
     "static",
     "generic",
+    "docusaurus",
 ]);
 function dashboardOrigin(apiUrl) {
     const override = process.env.LAYERO_DASHBOARD_URL;
@@ -33,9 +36,6 @@ function dashboardOrigin(apiUrl) {
         return "https://app.layero.ru";
     }
 }
-function setupUrl(apiUrl, projectId) {
-    return `${dashboardOrigin(apiUrl)}/projects/${projectId}/setup`;
-}
 function projectUrl(apiUrl, projectId) {
     return `${dashboardOrigin(apiUrl)}/projects/${projectId}`;
 }
@@ -72,12 +72,13 @@ function deployTargeting(opts) {
     return { target: opts.prod ? "production" : "preview" };
 }
 async function resolveOrCreateProject(api, cwd, opts, existing) {
+    const mode = detectMode();
     if (opts.project) {
         const all = await api.listProjects();
         const match = all.find((p) => p.id === opts.project) ??
             all.find((p) => p.slug === opts.project);
         if (!match) {
-            throw new Error(`no project with id/slug "${opts.project}"`);
+            throw new LayeroError("project_not_found", `no project with id/slug "${opts.project}"`, "run `layero projects list` to see available projects");
         }
         return { project: match, createdNow: false };
     }
@@ -88,40 +89,32 @@ async function resolveOrCreateProject(api, cwd, opts, existing) {
         }
         catch (err) {
             if (err instanceof ApiError && err.status === 404) {
-                throw new Error(`linked project ${existing.project_id} no longer exists or isn't on your account.\n` +
-                    `  fix: delete ${projectConfigPath(cwd)} and re-run \`layero deploy\` (creates a new project),\n` +
-                    `       or run \`layero link <id_or_slug>\` to point at an existing one.`);
+                throw new LayeroError("project_unlinked", `linked project ${existing.project_id} no longer exists or isn't on your account`, `delete ${projectConfigPath(cwd)} and re-run, or run \`layero link <id_or_slug>\``);
             }
             throw err;
         }
     }
     const me = await api.me();
     if (!me.username) {
-        throw new Error("no username set on your account. open https://app.layero.ru/onboarding " +
-            "and pick one, then re-run.");
+        throw new LayeroError("username_missing", "no username set on your account", "open https://app.layero.ru/onboarding to pick one, then re-run");
     }
-    // Resolve target Layero organization. Three paths:
-    //   * --org=slug explicit  → verify membership, use it
-    //   * single org           → silent default (the personal account)
-    //   * multiple orgs        → prompt unless --yes
     let organizationSlug = opts.org;
     if (organizationSlug) {
         const orgs = await api.listOrganizations();
         if (!orgs.some((o) => o.slug === organizationSlug)) {
-            throw new Error(`you're not a member of organization "${organizationSlug}". ` +
-                `available: ${orgs.map((o) => o.slug).join(", ") || "(none)"}`);
+            throw new LayeroError("org_membership_missing", `you're not a member of organization "${organizationSlug}"`, `available: ${orgs.map((o) => o.slug).join(", ") || "(none)"}`);
         }
     }
     else {
         const orgs = await api.listOrganizations();
         if (orgs.length === 0) {
-            throw new Error("no organization found on your account. finish onboarding at https://app.layero.ru/onboarding");
+            throw new LayeroError("no_organization", "no organization found on your account", "finish onboarding at https://app.layero.ru/onboarding");
         }
         else if (orgs.length === 1) {
             organizationSlug = orgs[0].slug;
         }
-        else if (opts.yes || opts.config) {
-            // CI without --org: prefer personal, fall back to first.
+        else if (opts.yes || opts.config || !mode.interactive) {
+            // Non-interactive: prefer personal, fall back to first.
             organizationSlug =
                 orgs.find((o) => o.kind === "personal")?.slug ?? orgs[0].slug;
         }
@@ -134,13 +127,16 @@ async function resolveOrCreateProject(api, cwd, opts, existing) {
             const choiceRaw = await prompt("choose number", "1");
             const idx = Number(choiceRaw) - 1;
             if (Number.isNaN(idx) || idx < 0 || idx >= orgs.length) {
-                throw new Error(`invalid choice "${choiceRaw}"`);
+                throw new LayeroError("invalid_choice", `invalid org choice "${choiceRaw}"`, "enter a number from the list");
             }
             organizationSlug = orgs[idx].slug;
         }
     }
     const fallbackName = path.basename(cwd);
-    const name = opts.name ?? (opts.yes || opts.config ? fallbackName : await prompt("project name", fallbackName));
+    const name = opts.name ??
+        (opts.yes || opts.config || !mode.interactive
+            ? fallbackName
+            : await prompt("project name", fallbackName));
     const project = await api.createCliProject({
         name,
         framework_hint: opts.type,
@@ -149,43 +145,57 @@ async function resolveOrCreateProject(api, cwd, opts, existing) {
     return { project, createdNow: true };
 }
 async function packAndUpload(api, cwd, project) {
-    console.log(chalk.cyan("packing source..."));
     const pack = await packCwd(cwd, project.slug);
-    console.log(chalk.dim(`  ${pack.fileCount} files, ${(pack.size / (1024 * 1024)).toFixed(2)} MB, sha256=${pack.sha256.slice(0, 12)}`));
-    console.log(chalk.cyan("requesting upload URL..."));
+    emit({
+        event: "packing",
+        files: pack.fileCount,
+        bytes: pack.size,
+        sha256: pack.sha256,
+    });
     const init = await api.initUpload(project.id);
-    console.log(chalk.cyan("uploading archive..."));
+    emit({ event: "uploading" });
     await uploadArchive(init, pack.archivePath);
+    emit({ event: "uploaded", archive_key: init.source_archive_key });
     return {
         archive_key: init.source_archive_key,
         commit_sha: pack.sha256,
         archivePath: pack.archivePath,
     };
 }
-function ensureConfigComplete(cfg) {
-    if (!cfg) {
-        throw new Error("no .layero/project.json found. run `layero deploy` once without --config " +
-            "to create the project, fill in framework_hint/build_cmd/output_dir there, " +
-            "then re-run with --config.");
+// Resolve the framework / build / output config to send to completeSetup.
+// Precedence: explicit CLI args > .layero/project.json > auto-detect.
+async function resolveSetupConfig(cwd, opts, existing) {
+    const detected = await detectProject(cwd);
+    emit({
+        event: "detected",
+        framework: detected.framework_hint,
+        build_cmd: detected.build_cmd,
+        output_dir: detected.output_dir,
+        confident: detected.confident,
+    });
+    const framework_hint = opts.type ?? existing?.framework_hint ?? detected.framework_hint;
+    const build_cmd = existing?.build_cmd ?? detected.build_cmd;
+    const output_dir = existing?.output_dir ?? detected.output_dir;
+    let source;
+    if (existing?.build_cmd || existing?.output_dir || existing?.framework_hint) {
+        source =
+            existing?.build_cmd && existing?.output_dir && existing?.framework_hint
+                ? "config"
+                : "hybrid";
     }
-    const missing = [];
-    if (!cfg.framework_hint)
-        missing.push("framework_hint");
-    if (!cfg.build_cmd)
-        missing.push("build_cmd");
-    if (!cfg.output_dir)
-        missing.push("output_dir");
-    if (missing.length > 0) {
-        throw new Error(`.layero/project.json is missing required fields for --config: ${missing.join(", ")}`);
+    else {
+        source = "detected";
     }
+    return { framework_hint, build_cmd, output_dir, source };
 }
 export async function deployCmd(opts) {
+    const mode = detectMode();
     if (opts.type && !VALID_TYPES.has(opts.type.toLowerCase())) {
-        throw new Error(`unknown --type "${opts.type}". valid: ${[...VALID_TYPES].join(", ")}`);
+        throw new LayeroError("invalid_type", `unknown --type "${opts.type}"`, `valid types: ${[...VALID_TYPES].join(", ")}`);
     }
     const cliCfg = await loadConfig();
     if (!cliCfg.token) {
-        throw new Error("not logged in. run `layero login` first.");
+        throw new LayeroError("not_logged_in", "not authenticated", "run: layero login");
     }
     const api = new ApiClient(cliCfg);
     const cwd = process.cwd();
@@ -193,127 +203,79 @@ export async function deployCmd(opts) {
     const { project: created, createdNow } = await resolveOrCreateProject(api, cwd, opts, existing);
     let project = created;
     if (project.cli_deploys_enabled === false) {
-        throw new Error(`CLI deploys are disabled on project "${project.slug}". ` +
-            "Enable them in project settings or use the dashboard's Deploy button.");
+        throw new LayeroError("cli_deploys_disabled", `CLI deploys are disabled on project "${project.slug}"`, "enable them in project settings, or remove --project to use a different project");
     }
-    // Prompt before overwriting production. CLI deploys default to a per-project
-    // "cli" pseudo-branch (preview-only); --prod is the explicit opt-in to land
-    // on apex_hostname. --yes (CI) or --branch=<default_branch> bypass.
-    if (opts.prod && !opts.yes && !opts.branch) {
+    // Prompt before overwriting production — only in interactive mode.
+    if (opts.prod && !opts.yes && !opts.branch && mode.interactive) {
         const ok = await confirm(`deploy to production (https://${project.apex_hostname})?`);
         if (!ok) {
             console.log(chalk.yellow("aborted."));
             return;
         }
     }
-    // Persist linking metadata only — never touch hand-edited config fields
-    // or unknown keys the user may have added (a --config file is the user's
-    // source of truth, not ours). `persistProjectLinking` reads the file as
-    // raw JSON, overlays just project_id/slug/organization_slug/apex_hostname,
-    // and writes it back.
+    // Resolve setup config (auto-detect + overrides). Done eagerly so the
+    // user sees what we detected before any network I/O.
+    const setup = await resolveSetupConfig(cwd, opts, existing);
     const persistedCfg = await persistProjectLinking(cwd, {
         project_id: project.id,
         slug: project.slug,
         organization_slug: project.organization.slug,
         apex_hostname: project.apex_hostname,
-    }, opts.type ?? null);
+    }, setup.framework_hint);
     if (createdNow) {
-        console.log(chalk.green(`created project ${project.slug}`));
+        emit({
+            event: "project_created",
+            project_id: project.id,
+            slug: project.slug,
+            organization: project.organization.slug,
+        });
     }
-    // ─────────────────────────────────────────────────────────────────────
-    // Path A: --config — fully scripted, runs the setup endpoint with
-    //                     fields from .layero/project.json, then deploys.
-    // ─────────────────────────────────────────────────────────────────────
-    if (opts.config) {
-        ensureConfigComplete(persistedCfg);
-        if (project.status === "pending_setup") {
-            console.log(chalk.cyan("applying config..."));
-            project = await api.completeSetup(project.id, {
-                framework_hint: persistedCfg.framework_hint,
-                build_cmd: persistedCfg.build_cmd,
-                output_dir: persistedCfg.output_dir,
-                analytics_enabled: persistedCfg.analytics_enabled ?? false,
-                env_vars: persistedCfg.env_vars ?? {},
-            });
-        }
-        let upload = null;
-        try {
-            upload = await packAndUpload(api, cwd, project);
-            console.log(chalk.cyan("triggering deploy..."));
-            const targeting = deployTargeting(opts);
-            const deploy = await api.triggerDeploy(project.id, {
-                source_archive_key: upload.archive_key,
-                commit_sha: upload.commit_sha,
-                commit_message: "CLI deploy",
-                framework_hint: persistedCfg.framework_hint ?? undefined,
-                target: targeting.target,
-                branch: targeting.branch,
-            });
-            console.log(chalk.dim(`  deploy_id=${deploy.id}`));
-            const final = await streamDeployLogs(api, deploy.id);
-            if (final.status !== "ready") {
-                console.error(chalk.red(`deploy failed (${final.status})${final.error_message ? `: ${final.error_message}` : ""}`));
-                process.exitCode = 1;
-                return;
-            }
-            console.log(chalk.green(`deploy ready → ${projectUrl(cliCfg.apiUrl, project.id)}`));
-            if (opts.prod && !opts.branch) {
-                console.log(chalk.dim(`  production: https://${project.apex_hostname} (CDN may take ~30-60s to propagate)`));
-            }
-            else {
-                console.log(chalk.dim(`  preview deploy — open the dashboard for the exact URL`));
-            }
-        }
-        finally {
-            if (upload) {
-                await fs.unlink(upload.archivePath).catch(() => undefined);
-            }
-        }
-        return;
+    else {
+        emit({
+            event: "project_linked",
+            project_id: project.id,
+            slug: project.slug,
+        });
+    }
+    // Apply setup if the project is still in pending_setup. After first
+    // run, subsequent deploys reuse whatever was set then — the user can
+    // edit .layero/project.json or use the dashboard to change it.
+    if (project.status === "pending_setup") {
+        project = await api.completeSetup(project.id, {
+            framework_hint: setup.framework_hint,
+            build_cmd: setup.build_cmd,
+            output_dir: setup.output_dir,
+            analytics_enabled: persistedCfg.analytics_enabled ?? false,
+            env_vars: persistedCfg.env_vars ?? {},
+        });
+        emit({ event: "setup_applied" });
     }
-    // ─────────────────────────────────────────────────────────────────────
-    // Path B: no flag — upload the source, stash it on the project row,
-    //                    print the setup URL. The user finishes the flow
-    //                    in the browser, exactly like a GitHub import.
-    // ─────────────────────────────────────────────────────────────────────
     let upload = null;
     try {
         upload = await packAndUpload(api, cwd, project);
-        await api.finalizeUpload(project.id, {
-            source_archive_key: upload.archive_key,
-            commit_sha: upload.commit_sha,
-        });
-        if (project.status === "pending_setup") {
-            const url = setupUrl(cliCfg.apiUrl, project.id);
-            console.log("");
-            console.log(chalk.green("source uploaded — finish setup in the browser:"));
-            console.log(`  ${chalk.bold(url)}`);
-            console.log("");
-            console.log(chalk.dim("  pick framework, build command, output dir, env vars and click Deploy."));
-            console.log(chalk.dim("  to skip the browser next time, fill .layero/project.json and run `layero deploy --config`."));
-            return;
-        }
-        // Already-active project: behave like the old `layero deploy` — fire
-        // a build straight from the freshly-uploaded archive.
-        console.log(chalk.cyan("triggering deploy..."));
         const targeting = deployTargeting(opts);
         const deploy = await api.triggerDeploy(project.id, {
             source_archive_key: upload.archive_key,
             commit_sha: upload.commit_sha,
             commit_message: "CLI deploy",
-            framework_hint: opts.type,
+            framework_hint: setup.framework_hint,
             target: targeting.target,
             branch: targeting.branch,
         });
-        console.log(chalk.dim(`  deploy_id=${deploy.id}`));
+        emit({ event: "deploy_started", deploy_id: deploy.id });
         const final = await streamDeployLogs(api, deploy.id);
         if (final.status !== "ready") {
-            console.error(chalk.red(`deploy failed (${final.status})${final.error_message ? `: ${final.error_message}` : ""}`));
-            process.exitCode = 1;
-            return;
+            throw new LayeroError(`deploy_${final.status}`, `deploy failed (${final.status})${final.error_message ? `: ${final.error_message}` : ""}`, `inspect logs at ${projectUrl(cliCfg.apiUrl, project.id)}`);
         }
-        console.log(chalk.green(`deploy ready → ${projectUrl(cliCfg.apiUrl, project.id)}`));
-        console.log(chalk.dim(`  site: https://${project.apex_hostname} (CDN may take ~30-60s to propagate)`));
+        const liveUrl = opts.prod && !opts.branch
+            ? `https://${project.apex_hostname}`
+            : projectUrl(cliCfg.apiUrl, project.id);
+        emit({
+            event: "ready",
+            url: liveUrl,
+            deploy_id: deploy.id,
+            preview_url: opts.prod && !opts.branch ? undefined : projectUrl(cliCfg.apiUrl, project.id),
+        });
     }
     finally {
         if (upload) {

package/dist/commands/init.js

@@ -0,0 +1,152 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { detectProject } from "../detect.js";
+import { emit, detectMode } from "../agent.js";
+const AGENT_BLOCK_MARKER_START = "<!-- layero:start -->";
+const AGENT_BLOCK_MARKER_END = "<!-- layero:end -->";
+function agentDocBlock(framework) {
+    return `${AGENT_BLOCK_MARKER_START}
+## Deploying with Layero
+
+This project ships to https://layero.ru. To deploy any local changes:
+
+\`\`\`bash
+npx layero deploy
+\`\`\`
+
+First-time setup:
+- The CLI prints an authorization URL on first run. Show it to the user as a clickable link; they sign in once (GitHub / Google / Yandex), and the token is cached locally.
+- Detected framework: **${framework}**.
+- No git repository or GitHub connection is required — Layero ships the local directory directly.
+
+Re-deploy after edits: run \`npx layero deploy\` again. Each run produces a new preview URL.
+
+Add \`--prod\` to publish to the project's apex hostname instead of a preview URL.
+${AGENT_BLOCK_MARKER_END}
+`;
+}
+async function upsertAgentDoc(cwd, filename, content) {
+    const filePath = path.join(cwd, filename);
+    let existing = null;
+    try {
+        existing = await fs.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+    }
+    if (existing === null) {
+        await fs.writeFile(filePath, content, "utf-8");
+        return "created";
+    }
+    // Already has our block — replace it in place so we can iterate
+    // safely (re-running `layero init` updates the block, doesn't append).
+    if (existing.includes(AGENT_BLOCK_MARKER_START)) {
+        const start = existing.indexOf(AGENT_BLOCK_MARKER_START);
+        const endMarker = existing.indexOf(AGENT_BLOCK_MARKER_END);
+        if (endMarker === -1) {
+            // Malformed — fall through to append.
+            const merged = existing.trimEnd() + "\n\n" + content;
+            await fs.writeFile(filePath, merged, "utf-8");
+            return "updated";
+        }
+        const newBlock = content.trimEnd() + "\n";
+        const merged = existing.slice(0, start) +
+            newBlock +
+            existing.slice(endMarker + AGENT_BLOCK_MARKER_END.length).replace(/^\n+/, "\n");
+        if (merged === existing)
+            return "unchanged";
+        await fs.writeFile(filePath, merged, "utf-8");
+        return "updated";
+    }
+    // Append our block to the existing file with a separating blank line.
+    const merged = existing.trimEnd() + "\n\n" + content;
+    await fs.writeFile(filePath, merged, "utf-8");
+    return "updated";
+}
+async function ensureProjectJson(cwd, framework, build_cmd, output_dir) {
+    const dir = path.join(cwd, ".layero");
+    const file = path.join(dir, "project.json");
+    try {
+        await fs.access(file);
+        return "unchanged";
+    }
+    catch {
+        // missing → create
+    }
+    await fs.mkdir(dir, { recursive: true });
+    const scaffold = {
+        framework_hint: framework,
+        build_cmd,
+        output_dir,
+        analytics_enabled: false,
+        env_vars: {},
+    };
+    await fs.writeFile(file, JSON.stringify(scaffold, null, 2) + "\n", "utf-8");
+    return "created";
+}
+async function ensureGitignore(cwd) {
+    const gi = path.join(cwd, ".gitignore");
+    let content = "";
+    try {
+        content = await fs.readFile(gi, "utf-8");
+    }
+    catch {
+        return; // no .gitignore — leave alone, this is meant to be additive
+    }
+    // We only want to ignore the auth-state-bearing files. `project.json`
+    // itself is safe to commit (project_id is not a secret).
+    if (!content.includes(".layero/")) {
+        const append = (content.endsWith("\n") ? "" : "\n") + "\n# Layero local state\n.layero/cache/\n";
+        await fs.writeFile(gi, content + append, "utf-8");
+    }
+}
+export async function initCmd(opts) {
+    const cwd = process.cwd();
+    const mode = detectMode();
+    const detected = await detectProject(cwd);
+    emit({
+        event: "detected",
+        framework: detected.framework_hint,
+        build_cmd: detected.build_cmd,
+        output_dir: detected.output_dir,
+        confident: detected.confident,
+    });
+    const block = agentDocBlock(detected.framework_hint);
+    if (!opts.skipAgentDocs) {
+        // Touch every agent-doc convention we know about. If one already
+        // exists we update it in-place; otherwise we create only the most
+        // common one (AGENTS.md, the cross-vendor convention) so we don't
+        // litter the repo with .cursorrules / CLAUDE.md the user doesn't use.
+        const candidates = ["AGENTS.md", "CLAUDE.md", ".cursorrules"];
+        const existing = [];
+        for (const f of candidates) {
+            try {
+                await fs.access(path.join(cwd, f));
+                existing.push(f);
+            }
+            catch {
+                // not present
+            }
+        }
+        const targets = existing.length > 0 ? existing : ["AGENTS.md"];
+        for (const f of targets) {
+            const result = await upsertAgentDoc(cwd, f, block);
+            if (mode.interactive) {
+                console.log(chalk.green(`  ${result === "created" ? "✓ created" : result === "updated" ? "✓ updated" : "= unchanged"} ${f}`));
+            }
+        }
+    }
+    const pjResult = await ensureProjectJson(cwd, detected.framework_hint, detected.build_cmd, detected.output_dir);
+    if (mode.interactive) {
+        console.log(chalk.green(`  ${pjResult === "created" ? "✓ created" : "= unchanged"} .layero/project.json`));
+    }
+    await ensureGitignore(cwd);
+    if (mode.interactive) {
+        console.log("");
+        console.log(chalk.bold("Next:"));
+        console.log("  $ npx layero login    # one-time, in your browser");
+        console.log("  $ npx layero deploy   # ship the current directory");
+    }
+}

package/dist/detect.js

@@ -0,0 +1,146 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+async function readPkg(cwd) {
+    try {
+        const raw = await fs.readFile(path.join(cwd, "package.json"), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function hasDep(pkg, name) {
+    return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+async function fileExists(cwd, ...candidates) {
+    for (const c of candidates) {
+        try {
+            await fs.access(path.join(cwd, c));
+            return true;
+        }
+        catch {
+            // try next
+        }
+    }
+    return false;
+}
+async function hasAnyHtml(cwd) {
+    // Shallow check — only top-level. Recursive walk is too expensive here
+    // and the static fallback is already permissive enough.
+    try {
+        const entries = await fs.readdir(cwd);
+        return entries.some((e) => e.endsWith(".html") || e.endsWith(".htm"));
+    }
+    catch {
+        return false;
+    }
+}
+// Build command preference:
+//   1. If `scripts.build` exists in package.json, use `npm run build` —
+//      it respects whatever the user set up (custom flags, monorepo
+//      filters, etc.). `npm run` works regardless of package manager
+//      installed on the build VM, because the builder runs `npm` itself.
+//   2. Otherwise, use the framework's CLI directly via `npx`.
+function buildCmd(pkg, fallback) {
+    if (pkg?.scripts?.build)
+        return "npm run build";
+    return fallback;
+}
+/**
+ * Detect framework / build command / output directory from the project
+ * shape. Mirrors the builder's detector ([core/builder/src/frameworks])
+ * so the values we ship to `completeSetup` match what the builder will
+ * actually do at build time.
+ *
+ * Order matters: more specific signals first (Next, Nuxt, SvelteKit,
+ * Gatsby, Astro, Docusaurus) before catch-alls (Vite, CRA, static).
+ */
+export async function detectProject(cwd) {
+    const pkg = await readPkg(cwd);
+    if (pkg) {
+        if (hasDep(pkg, "next") || (await fileExists(cwd, "next.config.js", "next.config.mjs", "next.config.ts"))) {
+            return {
+                framework_hint: "nextjs",
+                build_cmd: buildCmd(pkg, "npx next build"),
+                output_dir: "out",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "nuxt") || hasDep(pkg, "nuxt3") || (await fileExists(cwd, "nuxt.config.ts", "nuxt.config.js", "nuxt.config.mjs"))) {
+            const generateScript = pkg.scripts?.generate;
+            const buildScript = pkg.scripts?.build;
+            const cmd = generateScript
+                ? "npm run generate"
+                : buildScript
+                    ? "npm run build"
+                    : "npx nuxt generate";
+            return {
+                framework_hint: "nuxt",
+                build_cmd: cmd,
+                output_dir: ".output/public",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "@sveltejs/kit") || (await fileExists(cwd, "svelte.config.js"))) {
+            return {
+                framework_hint: "sveltekit",
+                build_cmd: buildCmd(pkg, "npx vite build"),
+                output_dir: "build",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "gatsby") || (await fileExists(cwd, "gatsby-config.js", "gatsby-config.ts"))) {
+            return {
+                framework_hint: "gatsby",
+                build_cmd: buildCmd(pkg, "npx gatsby build"),
+                output_dir: "public",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "astro") || (await fileExists(cwd, "astro.config.mjs", "astro.config.ts", "astro.config.js"))) {
+            return {
+                framework_hint: "astro",
+                build_cmd: buildCmd(pkg, "npx astro build"),
+                output_dir: "dist",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "@docusaurus/core") || (await fileExists(cwd, "docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"))) {
+            return {
+                framework_hint: "docusaurus",
+                build_cmd: buildCmd(pkg, "npx docusaurus build"),
+                output_dir: "build",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "vite") || (await fileExists(cwd, "vite.config.ts", "vite.config.js", "vite.config.mjs"))) {
+            return {
+                framework_hint: "vite",
+                build_cmd: buildCmd(pkg, "npx vite build"),
+                output_dir: "dist",
+                confident: true,
+            };
+        }
+        if (hasDep(pkg, "react-scripts")) {
+            return {
+                framework_hint: "cra",
+                build_cmd: buildCmd(pkg, "npx react-scripts build"),
+                output_dir: "build",
+                confident: true,
+            };
+        }
+    }
+    // No (or unrecognised) package.json. If there's HTML on disk we treat
+    // the current directory as a static site. Otherwise we still fall back
+    // to static — it's the most permissive option and the builder will
+    // ship whatever is on disk verbatim.
+    const _staticHtml = await hasAnyHtml(cwd);
+    return {
+        framework_hint: "static",
+        build_cmd: "true",
+        output_dir: ".",
+        confident: _staticHtml,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "layero",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Layero CLI — publish a local site with one command.",
   "license": "MIT",
   "type": "module",