@blocofy/cli 0.14.0 → 0.16.0

package/bin/blocofy.mjs

@@ -29,7 +29,14 @@ import {
   saveStore,
   withStoreLock,
   writeSecret,
+  credentialRefusal,
+  readOAuthTokens,
+  writeOAuthTokens,
 } from "../lib/credentials.mjs";
+import { CLI_CLIENT_ID, LoginError, revokeToken, runBrowserLogin } from "../lib/oauth.mjs";
+import { accessTokenFor } from "../lib/refresh.mjs";
+import { oauthSecretStore, storeLabel, SecretStoreError } from "../lib/secret-store.mjs";
+import { InitError, inspectInitDir, readInitState, runInit, initApi } from "../lib/init.mjs";
 import { printError, printTarget, printWarning, redact, registerSecret, targetData } from "../lib/output.mjs";
 import {
   CONTEXT_NAME_RE,
@@ -71,8 +78,9 @@ import { MANIFEST_PATH, buildManifest, validateSiteStateTree, verifyManifest } f
 import { SiteStateFsError, hashBuffer, readSiteStateTree, stagedWriteTree } from "../lib/site-state-fs.mjs";
 import { migrateSiteState } from "../lib/site-migrate.mjs";
 import { applySiteState, downloadAssetBytes, fetchSiteStateExport, planSiteState, publishSiteState, uploadMediaAsset } from "../lib/site-state-client.mjs";
-import { DRAFT_TARGET_AMBIGUOUS, PUBLISH_TARGET_UNCONFIRMED, publishTargetUnconfirmedMessage, diffTheme, draftSyncErrorLine, draftTargetAmbiguousMessage, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, findCliDraft, publishInstance, pullTheme, pushTheme, renameInstance } from "../lib/theme-sync.mjs";
+import { DRAFT_TARGET_AMBIGUOUS, PUBLISH_TARGET_UNCONFIRMED, publishTargetUnconfirmedMessage, diffTheme, draftSyncErrorLine, draftTargetAmbiguousMessage, fetchCanonicalSupport, fetchDevSession, fetchSiteStatus, findCliDraft, publishInstance, pullTheme, pushTheme, renameInstance, themeCapacityRefusal } from "../lib/theme-sync.mjs";
 import { isAffirmative, livePushDecision, resolvePushMode } from "../lib/confirm.mjs";
+import { DEFAULT_WORK_INTENT, WORK_INTENT_MAX, WORK_KEY_RE, approvalOutcome, approvalWaitState, cancelWork, getPublishStatus, getWork, isWorkHandle, newWorkKey, publishStatusLines, readSavedWork, requestApproval, resumeWork, safeApprovalUrl, saveWork, sealWork, staleLines, startWork, stateLabel, themeWorkRefusal, workLines } from "../lib/theme-work.mjs";
 import { hyperlink, openUrl } from "../lib/term.mjs";
 import { isValidToken, isValidUrl, normalizeUrl } from "../lib/validate.mjs";
 
@@ -86,13 +94,20 @@ const args = process.argv.slice(2);
 // 0.8.0: `login --api-key` DEĞERSİZ bayraktır (parser'da boolean) — sır gizli prompt'tan ya da
 // BLOCOFY_API_KEY'den gelir, argv'ye asla girmez. `pages media-uses` / `media-decide` v1 API komutlarıdır.
 const KNOWN = {
-  login: ["url", "token", "api-key", "api-url", "keychain"],
+  login: ["url", "token", "api-key", "api-url", "keychain", "site", "insecure-storage", "no-browser"],
+  init: ["site", "api-url", "insecure-storage", "no-browser"],
   pages: ["decisions", "expected-revision-id", "expected-version", "json", "dir"],
   themePull: ["draft", "instance"],
-  themePush: ["diff", "draft", "instance", "name", "live", "yes", "confirm", "dry-run", "validate", "idempotency-key", "prune"],
+  themePush: ["diff", "draft", "instance", "name", "live", "yes", "confirm", "dry-run", "validate", "idempotency-key", "prune", "work"],
   themeDev: ["port", "dry", "no-sync", "name", "instance"],
   themePublish: ["instance"],
   themeRename: ["name", "dir"],
+  themeWorkStart: ["intent", "idempotency-key"],
+  themeWorkStatus: ["dir"],
+  themeWorkResume: ["dir", "require-fresh"],
+  themeWorkCancel: ["dir"],
+  themeWorkSeal: ["dir"],
+  themeWorkRequestApproval: ["dir", "open", "wait", "interval"],
   content: [],
   settingsPush: ["instance", "live", "yes", "confirm"],
   pagesPull: ["strict"],
@@ -152,9 +167,23 @@ function printHelp() {
 Develop your theme locally against live data, preview it three ways, and publish.
 
 Usage
-  blocofy login [--context <name>] [--url <url>] [--token <bcf_…>] [--keychain]
-      Verify a dev token against its site (GET /api/dev/whoami) and save it as a named
-      context (default name: the site's slug). Nothing is saved if verification fails.
+  blocofy login [--context <name>] [--site <handle|slug>] [--api-url <url>] [--no-browser]
+                [--insecure-storage]
+      Log in with your browser (PKCE, loopback 127.0.0.1/[::1] callback): pick the site and
+      approve. The login is draft-only ("Tema geliştirme"): it can never change the live site or
+      publish. "Connected" is printed only after GET /api/v1/ping confirms site + profile. The
+      tokens go to the OS secure store (macOS Keychain, Windows DPAPI file, Linux Secret Service);
+      no store → refused, never a silent plain file. --insecure-storage (or
+      BLOCOFY_SECRET_STORE=file) chooses ~/.blocofy/secrets.json (0600) explicitly.
+      Needs a terminal: CI / SSH never opens a browser (use env credentials or the options below).
+        --api-url <url>  platform (default https://app.blocofy.com)
+        --no-browser     do not open the browser; open the printed URL yourself
+        --site           refuse (and revoke) the login unless this site was approved
+
+  blocofy login --url <url> --token [--context <name>] [--keychain]       (advanced)
+      Verify a pasted dev token (bcf_… / bcf2_…) against its site (GET /api/dev/whoami) and save
+      it as a named context (default name: the site's slug). The token is read from a hidden
+      prompt; --token <value> works but warns (argv is visible in ps and shell history).
       Get a token from the admin panel → Settings → Theme CLI tokens.
         --keychain   keep the secret in the macOS keychain (or BLOCOFY_SECRET_STORE=keychain);
                      default: ~/.blocofy/secrets.json (0600)
@@ -169,7 +198,18 @@ Usage
   blocofy contexts [--json]          list saved contexts (never prints secrets)
   blocofy use <name>                 default context for status / target / pages check outside a
                                      project (never used by any other command)
-  blocofy logout --context <name>    remove a context and its secrets
+  blocofy logout [--context <name>]  remove a context and its secrets; a browser login is also
+                                     revoked on the platform (RFC 7009). Both results are printed;
+                                     exit 4 if the local copy could not be removed or the platform
+                                     login was NOT revoked (then cut it in the panel).
+
+  blocofy init [dir] [--site <handle|slug>] [--context <name>]
+      Set up a new project: (browser login if needed) → a theme work of its own (idempotent:
+      .blocofy/init.json keeps its key; re-run continues, never a second work) → the work's theme
+      files → .blocofy/project.json → a preview link → the live theme read back unchanged.
+      Refuses a non-empty directory that is not a project and one bound to another site
+      (exit 3, nothing written). Non-interactive runs need --site and a saved/env credential.
+      Exit 5: the live theme changed meanwhile (init never writes it; not reported as success).
   blocofy link [dir] --context <name> [--adopt]
       Bind a project directory to the context's (verified) site: writes .blocofy/project.json
       (commit it), .blocofy/local.json (your context; git-ignored) and .blocofy/.gitignore.
@@ -193,8 +233,10 @@ Usage
 
   blocofy theme pull [dir] [--draft] [--instance <handle>]
       Download the live theme to disk. (dir defaults to cwd)
-        --draft      pull the draft theme (what 'theme dev' syncs into) instead of live;
-                     creates the draft if missing, so it needs a bound project
+        --draft      pull the CLI draft (what 'theme dev' / 'theme push --draft' write into)
+                     instead of live. Read-only: it never creates the draft — with none yet
+                     it stops (target_missing); run 'blocofy theme push --draft' first.
+                     Needs a bound project
         --instance <handle>  pull a specific theme by its handle (from the admin
                              panel theme card, or \`blocofy status\`)
 
@@ -218,6 +260,40 @@ Usage
         --prune      also REMOVE target files that no longer exist locally, locales/ included
                      (lists them first; on the live theme asks to confirm — non-interactive
                      shells must add --yes)
+        --work <wk_…>  write into that WORK's own draft theme (see 'theme work'); never live.
+                       Needs both the dev token and the v1 API key of the same site. Refused
+                       unless the work is open; with --live/--instance it is a usage error
+
+  blocofy theme work start [dir] [--intent "<text>"] [--idempotency-key <k>]   (new)
+      Start a WORK: a private, safe copy of the site's CURRENT live theme to change and
+      later hand over for publication. Visitors never see it. Prints its handle (wk_…) and
+      remembers it in .blocofy/local.json (git-ignored). Needs the v1 API key
+      (blocofy login --api-key); the work belongs to that key.
+        --intent "<text>"       a short label of the job (1-120 characters)
+        --idempotency-key <k>   retry key: the same key returns the SAME work, never a second one.
+                                Without it a fresh key is generated and printed
+  blocofy theme work status <wk_…> [--dir <dir>]
+      Show the work: its state, its theme handle, whether the site changed since it started,
+      and where its publication stands (review, waiting for approval, published).
+  blocofy theme work seal <wk_…> [--dir <dir>]
+      Prepare the work for review: its content is frozen and can no longer change. Asks for
+      no approval and publishes nothing.
+  blocofy theme work request-approval <wk_…> [--dir <dir>] [--open] [--wait [--interval <s>]]
+      Ask a person to publish the work (an open work is prepared for review first). Prints the
+      approval URL: a signed-in site owner or team member with the theme permission approves it
+      in Blocofy. The URL carries no token; having it is not a permission to publish.
+        --open           also open the approval page in your browser
+        --wait           wait until it is published, or the request expires, is declined, or the
+                         live site changes (read-only polling; nothing is published from here)
+        --interval <s>   seconds between status checks while waiting (1-60, default 3)
+      --wait exit codes: 0 published · 2 ended, nothing published (approval_stale, approval_expired,
+      approval_declined, approval_superseded, work_cancelled) · 1 wait_timeout or publish_failed
+  blocofy theme work resume <wk_…> [--dir <dir>] [--require-fresh]
+      Continue that exact work here (it becomes this project's saved work). Writes nothing.
+        --require-fresh   refuse (work_stale) when the site changed since the work started
+  blocofy theme work cancel <wk_…> [--dir <dir>]
+      Give the work up. The live site is not touched; its theme stays in the theme library.
+      Publication of a work is approved by a person in the admin panel; the CLI never publishes it.
 
   blocofy theme rename <handle> <new name> [--dir <dir>]
       Rename a theme (the name is just a label). Works on any of your themes,
@@ -392,7 +468,8 @@ Usage
   blocofy --help
 
 Examples
-  blocofy login --url https://store.myblocofy.com --token bcf_xxxxxxxx     (context "store")
+  blocofy login && blocofy init my-site                                     (browser login, new project)
+  blocofy login --url https://store.myblocofy.com --token                   (pasted dev token, hidden)
   blocofy theme pull store-theme --context store && cd store-theme && blocofy theme dev
   blocofy link ~/code/store-theme --context store     (an existing checkout)
   blocofy theme push && blocofy theme publish          (inside the bound project)
@@ -425,16 +502,19 @@ Targets (which site a command talks to)
   (one warning; run \`blocofy link --adopt\` to record it). A server that reports no origin cannot
   serve a binding that records one (TARGET_UNVERIFIED).
   Exit codes (every command): 0 ok · 1 usage/network/5xx/local check · 2 server refusal (HTTP 4xx)
-  · 3 target/binding refusal · 4 'site apply' only: not finished within its bounded pass count —
-  every step already applied is safe, re-run the same command to resume.
+  · 3 target/binding refusal · 4 'site apply': not finished within its bounded pass count —
+  every step already applied is safe, re-run the same command to resume; 'logout': the local
+  login was not removed or the platform login was NOT revoked · 5 'init': the live theme changed
+  meanwhile (init never writes it; not reported as a success).
   --json: every failure prints {"error":{"code","message","details"}} as the LAST stderr line; the
   target block ({"target":…}) and any warning lines are printed on stderr before it.
   Retries: network errors and HTTP 429/502/503/504 are retried up to 3 times (Retry-After honoured,
   max 30s per wait; else 0.3s/0.9s/2s), resending the identical request (pages push carries one
   x-idempotency-key per push). HTTP 500 is never retried. Each retry prints a notice on stderr.
 
-Auth: ~/.blocofy/credentials.json (contexts, no secrets) + ~/.blocofy/secrets.json (0600) or the
-macOS keychain. A pre-0.10 credentials file is migrated on first use (backup:
+Auth: ~/.blocofy/credentials.json (contexts, no secrets). A browser login's tokens live in the OS
+secure store (macOS Keychain, Windows DPAPI file, Linux Secret Service; the 0600 file only when
+chosen); a pasted token/key in ~/.blocofy/secrets.json (0600) or the macOS keychain. A pre-0.10 credentials file is migrated on first use (backup:
 ~/.blocofy/credentials.v1.bak.json — copy it back to roll back).
 The CLI does not build assets — bring your own (npm/Vite/Tailwind); the platform serves
 plain Liquid + static assets.`);
@@ -466,6 +546,7 @@ const retry = { onRetry };
  */
 function exitCodeFor(error) {
   if (error instanceof TargetError || error instanceof CredentialsError) return error.exitCode ?? 1;
+  if (error instanceof LoginError || error instanceof InitError || error?.name === "LoopbackError") return error.exitCode ?? 1;
   if (error instanceof CliRefusal) return 2;
   const status = Number(error?.status);
   return status >= 400 && status < 500 ? 2 : 1;
@@ -487,8 +568,25 @@ function envelopeFor(error) {
   return { code, message: error?.message || String(error), details };
 }
 
+/** The context the current command resolved (for the re-login hint of a credential refusal). */
+let activeContext = null;
+
+/**
+ * ADR-0014 (wave P4) — the plain Turkish lines of a credential refusal (the profile gate's codes and the CLI's own
+ * REAUTH_REQUIRED), printed before the usual `error [code]` line. Never under --json (the envelope carries the code).
+ */
+function printRefusalLines(error) {
+  if (JSON_MODE) return;
+  if (Array.isArray(error?.lines)) for (const line of error.lines) console.error(redact(line));
+  const code = error instanceof CliRefusal ? error.error?.code : error?.details?.server_code ?? error?.code;
+  const details = error instanceof CliRefusal ? error.error?.details : error?.serverDetails ?? error?.body?.details ?? error?.details;
+  const refusal = credentialRefusal(code, details ?? {}, { context: error?.details?.context ?? activeContext });
+  if (refusal) for (const line of refusal.lines) console.error(redact(line));
+}
+
 function failAndExit(error) {
   const code = exitCodeFor(error);
+  printRefusalLines(error);
   if ((error instanceof PagesCliError || error instanceof SiteStateFsError) && !JSON_MODE) {
     if (error.diagnostics?.length) reportPageDiagnostics(error.diagnostics);
   }
@@ -529,6 +627,19 @@ function failDraftTargetAmbiguous(error, command, { action = "write" } = {}) {
   });
 }
 
+/**
+ * Theme-capacity (ADR-0013) refusals of the dev theme endpoint: `target_missing`, `quota_exceeded`,
+ * `capacity_unavailable`, `resource_busy`, `source_stale`. The plain Turkish explanation first (human mode), then the
+ * shared `error [code]` line / `--json` envelope; exit 2 for the 4xx ones, 1 for the 503 ones. Returns only when
+ * `error` is not one of them.
+ */
+function failOnThemeCapacityRefusal(error, pushCommand) {
+  const refusal = themeCapacityRefusal(error, { pushCommand });
+  if (!refusal) return;
+  if (!JSON_MODE) for (const line of refusal.lines) console.error(line);
+  failAndExit({ code: error.code, status: error.status, message: refusal.message, details: refusal.details });
+}
+
 /**
  * Could `instance` be the live theme? Fail-closed (#989 review): yes when it is the live handle, when the live theme is
  * not known, and when it is a raw numeric id (the server accepts one, the live handle comparison cannot see it).
@@ -587,6 +698,9 @@ function saveVerifiedPair(name, kind, args) {
 function saveVerifiedPairLocked(name, kind, { url, secret, identity, storeName }) {
   const store = loadStore();
   const existing = store.contexts[name];
+  if (existing?.oauth) {
+    throw new TargetError("TARGET_CONTEXT_OCCUPIED", `Context "${name}" is a browser login (blocofy login); a pasted ${kind === "dev" ? "dev token" : "API key"} gets a context of its own. Nothing was saved. Use --context <another-name>.`, { context: name });
+  }
   writeSecret(name, kind, storeName, secret);
   if (existing?.[kind] && existing[kind].secret.store !== storeName) {
     try {
@@ -628,7 +742,7 @@ async function loginApiKey(flags, positionals) {
 
   let apiKey = null;
   if (process.stdin.isTTY) {
-    apiKey = await promptSecret("API key (blcf_live_…, hidden): ");
+    apiKey = await promptSecret("API key (blcf_live_… / blcf_k2_…, hidden): ");
     if (apiKey === null) {
       console.error("Cancelled. Nothing was written.");
       process.exit(1);
@@ -641,7 +755,7 @@ async function loginApiKey(flags, positionals) {
     process.exit(1);
   }
   if (!isValidApiKey(apiKey)) {
-    console.error("Invalid API key — a v1 key starts with blcf_live_ (a bcf_ dev token is not accepted for the v1 API). Nothing was written.");
+    console.error("Invalid API key — a v1 key starts with blcf_live_ or blcf_k2_ (a bcf_ dev token is not accepted for the v1 API). Nothing was written.");
     process.exit(1);
   }
   registerSecret(apiKey);
@@ -652,22 +766,198 @@ async function loginApiKey(flags, positionals) {
   await assertPairFitsContext(name, loadStore().contexts[name], identity, "dev");
   saveVerifiedPair(name, "api", { url: apiUrl, secret: apiKey, identity, storeName });
   console.log(`✓ API key saved to context "${name}" → ${credentialsPath()} (API: ${apiUrl})`);
+  console.log(`  Secret store: ${storeLabel(storeName)}`);
   console.log(`  Site: ${siteLabel(identity.site) || identity.site.id}`);
   console.log("Next: blocofy pages media-uses <page-handle>");
 }
 
+// ── browser login (ADR-0014 §5, wave P4) ──────────────────────────────────────────────────────────────────
+
+/** Where the owner manages connections (the "Connections and keys" hub). */
+const CONNECTIONS_PATH = "/settings/connections";
+
+/** A person at a terminal: stdin is a TTY and CI is not set. Unattended runs never open a browser. */
+const isUnattended = () => !process.stdin.isTTY || Boolean(process.env.CI);
+const isSshSession = () => Boolean(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY);
+
+const withLines = (error, lines) => Object.assign(error, { lines });
+
+function assertBrowserLoginPossible() {
+  if (isUnattended()) {
+    throw withLines(
+      new LoginError("LOGIN_UNATTENDED", "Browser login needs an interactive terminal (no TTY, or CI is set): no browser was opened and nothing was sent. In CI use BLOCOFY_API_KEY + BLOCOFY_API_URL (or BLOCOFY_URL + BLOCOFY_TOKEN); advanced: blocofy login --token / blocofy login --api-key."),
+      [
+        "Tarayıcıyla giriş bir terminal ister; bu oturum etkileşimsiz (CI ya da yönlendirilmiş girdi). Tarayıcı açılmadı, hiçbir şey gönderilmedi.",
+        "  CI/otomasyon: BLOCOFY_API_KEY + BLOCOFY_API_URL (ya da BLOCOFY_URL + BLOCOFY_TOKEN) ortam değişkenleri.",
+        "  Gelişmiş: yapıştırılan token ile giriş:  blocofy login --token   ya da   blocofy login --api-key",
+      ],
+    );
+  }
+  if (isSshSession()) {
+    throw withLines(
+      new LoginError("LOGIN_NO_BROWSER", "Browser login is not supported over SSH (the browser cannot reach this machine's 127.0.0.1 callback). Nothing was sent. Advanced: blocofy login --token / blocofy login --api-key."),
+      [
+        "Uzak (SSH) oturumda tarayıcıyla giriş desteklenmiyor: tarayıcı bu makinenin 127.0.0.1 adresine dönemez. Hiçbir şey gönderilmedi.",
+        "  Gelişmiş: yapıştırılan token ile giriş:  blocofy login --token   ya da   blocofy login --api-key",
+      ],
+    );
+  }
+}
+
+function loginOrigin(flags) {
+  const origin = normalizeUrl(typeof flags["api-url"] === "string" ? flags["api-url"] : DEFAULT_API_URL);
+  if (!isValidUrl(origin)) throw new LoginError("USAGE", "Invalid --api-url — must be a valid http(s):// URL. Nothing was written.");
+  return origin;
+}
+
+/** `--site <handle|slug>` names the approved site. */
+const siteMatches = (site, arg) => String(site.id) === String(arg) || (site.slug != null && site.slug === arg);
+
+/** A browser login owns its context: never one that holds pasted secrets, never one recorded for another site. */
+function assertContextFreeForLogin(name, identity) {
+  const ctx = loadStore().contexts[name];
+  if (!ctx) return;
+  if (ctx.dev || ctx.api) {
+    throw new TargetError("TARGET_CONTEXT_OCCUPIED", `Context "${name}" holds a pasted dev token / API key; a browser login gets a context of its own. Nothing was saved. Use --context <another-name> (or \`blocofy logout --context ${name}\` first).`, { context: name });
+  }
+  if (identity && ctx.site) {
+    const o = compareOrigin(ctx.platform_origin, identity.platformOrigin);
+    if (String(ctx.site.id) !== String(identity.site.id) || o === "mismatch" || o === "unproven") {
+      throw new TargetError("TARGET_SITE_MISMATCH", `Context "${name}" is for site ${ctx.site.slug ?? ctx.site.id}, but you approved ${identity.site.slug ?? identity.site.id}. Nothing was saved. Use another --context name.`, { context: name, context_site_id: ctx.site.id, new_site_id: identity.site.id });
+    }
+  }
+}
+
+/** Save a verified browser login (token set first, then the context). Returns the previous token set, if any. */
+function saveOAuthContext(name, storeName, { tokens, identity, metadata }, origin) {
+  return withStoreLock(() => {
+    const store = loadStore();
+    const existing = store.contexts[name];
+    let previous = null;
+    if (existing?.oauth) {
+      try {
+        const t = readOAuthTokens(name, existing);
+        if (t) previous = { token: t.refresh_token ?? t.access_token, endpoint: existing.oauth.revocation_endpoint ?? null };
+      } catch {
+        previous = null;
+      }
+    }
+    writeOAuthTokens(name, storeName, tokens);
+    if (existing?.oauth && existing.oauth.secret.store !== storeName) {
+      try {
+        removeSecrets(name, { oauth: existing.oauth });
+      } catch {
+        /* the old copy stays in the other store; the context now points at the new one */
+      }
+    }
+    store.contexts[name] = {
+      platform_origin: identity.platformOrigin ?? origin,
+      site: { id: identity.site.id, slug: identity.site.slug ?? null, name: identity.site.name ?? null, domain: identity.site.domain ?? null },
+      oauth: {
+        url: origin,
+        issuer: metadata.issuer,
+        client_id: CLI_CLIENT_ID,
+        token_endpoint: metadata.token_endpoint,
+        revocation_endpoint: metadata.revocation_endpoint ?? null,
+        dev_url: identity.devUrl ?? null,
+        profile: identity.profile,
+        secret: { store: storeName },
+        logged_in_at: new Date().toISOString(),
+      },
+      verified_at: new Date().toISOString(),
+    };
+    if (!store.current_context) store.current_context = name;
+    saveStore(store);
+    return previous;
+  });
+}
+
+/**
+ * The browser login and its save (ADR §5.2): used by `login` and by `init` when it has no credential. Success is the
+ * canonical identity probe, then the save. Returns `{ name, identity, storeName, explicitStore, origin }`.
+ */
+async function browserLoginAndSave({ flags, contextName = null, siteArg = null }) {
+  assertBrowserLoginPossible();
+  const origin = loginOrigin(flags);
+  let store;
+  try {
+    store = oauthSecretStore({ insecure: Boolean(flags["insecure-storage"]) });
+  } catch (error) {
+    throw error instanceof SecretStoreError ? new CredentialsError(error.code, error.message) : error;
+  }
+  if (contextName) {
+    contextNameOrExit(contextName);
+    assertContextFreeForLogin(contextName, null);
+  }
+  if (!JSON_MODE) console.error(`Blocofy girişi tarayıcıda açılıyor (${origin})…`);
+  const result = await runBrowserLogin({
+    origin,
+    openBrowser: flags["no-browser"] ? async () => {} : async (url) => openUrl(url),
+    print: (url) => {
+      if (JSON_MODE) return;
+      console.error("Tarayıcı açılmazsa bu adresi aç (adres sır içermez):");
+      console.error(`  ${url}`);
+      console.error("Tarayıcıda siteni seçip onayla; en çok 5 dakika bekliyorum…");
+    },
+    onRetry,
+  });
+  registerSecret(result.tokens.access_token);
+  registerSecret(result.tokens.refresh_token);
+  const { identity } = result;
+  if (siteArg && !siteMatches(identity.site, siteArg)) {
+    await result.abandon(new LoginError("LOGIN_SITE_MISMATCH", `You approved ${identity.site.slug ?? identity.site.id} in the browser, but --site asks for ${siteArg}. The new login was revoked; nothing was saved.`, { site: identity.site.id, requested: siteArg }, 3));
+  }
+  const name = contextName ?? identity.site.slug ?? "";
+  try {
+    contextNameOrExit(name);
+    assertContextFreeForLogin(name, identity);
+  } catch (error) {
+    await result.abandon(error);
+  }
+  const previous = saveOAuthContext(name, store.name, result, origin);
+  // A re-login replaces the context's previous login: close that one too (best effort; the hub lists any survivor).
+  if (previous?.token && previous.endpoint) await revokeToken({ endpoint: previous.endpoint, token: previous.token });
+  return { name, identity, storeName: store.name, explicitStore: store.explicit, origin };
+}
+
+async function browserLogin(flags, positionals) {
+  if (positionals.length > 0) throw new TargetError("USAGE", "Usage: blocofy login [--context <name>] [--site <handle|slug>] [--api-url <url>] [--no-browser] [--insecure-storage]", {}, 1);
+  const siteArg = typeof flags.site === "string" ? flags.site : null;
+  const { name, identity, storeName, explicitStore, origin } = await browserLoginAndSave({ flags, contextName: typeof flags.context === "string" ? flags.context : null, siteArg });
+  if (explicitStore) printWarning({ code: "SECRET_STORE_PLAINTEXT", message: `The login is kept in ~/.blocofy/secrets.json (0600) because you chose it (--insecure-storage / BLOCOFY_SECRET_STORE=file), not in the OS secure store.` }, { json: JSON_MODE });
+  const p = identity.profile;
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ login: { context: name, site: identity.site, platform_origin: identity.platformOrigin, profile: p, audience: identity.audience, store: storeName, policy_version: identity.policyVersion } }, null, 2));
+    return;
+  }
+  console.log(`✓ Bağlandı: ${siteLabel(identity.site) || identity.site.id} — context "${name}"`);
+  console.log(`  Profil: ${p.label ?? p.id} (${p.id}@${p.version ?? "?"})${p.id === "theme-dev" ? " — taslak üzerinde çalışır; canlı siteni değiştiremez, yayınlayamaz." : ""}`);
+  console.log(`  Giriş bilgisi: ${storeLabel(storeName)}`);
+  if (!identity.devUrl) console.log("  Not: sitenin henüz bir alan adı yok; tema dosyası komutları (theme dev/pull/push) şimdilik çalışmaz.");
+  console.log(`Sonraki adım: yeni proje için  blocofy init <dizin>   ·   mevcut dizin için  blocofy link <dizin> --context ${name}`);
+  console.log(`  Bağlantıyı panelden kesmek: ${origin}${CONNECTIONS_PATH}   ·   bu makineden çıkış: blocofy logout --context ${name}`);
+  console.log(`technical: platform ${identity.platformOrigin ?? origin}, audience ${identity.audience}, policy_version ${identity.policyVersion ?? "?"}`);
+}
+
 async function login(rest) {
   const { flags, positionals } = parseArgsOrExit(rest, KNOWN.login);
-  if (flags["api-key"] || flags["api-url"] !== undefined) {
-    if (!flags["api-key"]) {
-      console.error("--api-url is only used with --api-key. Nothing was written.");
-      process.exit(1);
-    }
+  if (flags["api-key"]) {
     await loginApiKey(flags, positionals);
     return;
   }
+  // ADR-0014 O2: the browser is the default; a pasted dev token (`--url` / `--token` / `--keychain`) is the advanced path.
+  if (flags.url === undefined && flags.token === undefined && !flags.keychain) {
+    await browserLogin(flags, positionals);
+    return;
+  }
+  if (flags["api-url"] !== undefined || flags.site !== undefined || flags["insecure-storage"] || flags["no-browser"]) {
+    console.error("--api-url / --site / --insecure-storage / --no-browser belong to the browser login (`blocofy login`) or `--api-key`; a pasted dev token takes --url and --token. Nothing was written.");
+    process.exit(1);
+  }
   let url = typeof flags.url === "string" ? normalizeUrl(flags.url) : "";
   let token = typeof flags.token === "string" ? flags.token.trim() : "";
+  // ADR-0014 B6: a token on the command line is visible to other local users (ps) and kept in shell history.
+  if (token) printWarning({ code: "TOKEN_IN_ARGV", message: "The dev token was given on the command line, where `ps` and your shell history can see it. Prefer `blocofy login --url <site> --token` (hidden prompt) or BLOCOFY_URL + BLOCOFY_TOKEN." }, { json: JSON_MODE });
 
   // Flag ile verildiyse anında doğrula (prompt'a düşmeden).
   if (url && !isValidUrl(url)) {
@@ -678,7 +968,7 @@ async function login(rest) {
     console.error(
       token.startsWith("blcf_")
         ? "Invalid --token — that is a v1 API key (blcf_…), not a theme dev token (bcf_…). The two are separate credentials: add the API key with `blocofy login --api-key`. Nothing was written."
-        : "Invalid --token — must start with bcf_.",
+        : "Invalid --token — must start with bcf_ or bcf2_.",
     );
     process.exit(1);
   }
@@ -697,13 +987,30 @@ async function login(rest) {
           "Enter a valid URL, e.g. https://store.myblocofy.com",
         );
       }
+      if (!token && process.stdin.isTTY) {
+        // ADR-0014 B6: the dev token prompt does not echo.
+        rl.close();
+        for (let i = 0; i < 3 && !token; i += 1) {
+          const answer = await promptSecret("Dev token (bcf_… / bcf2_…, hidden): ");
+          if (answer === null) {
+            console.error("Cancelled. Nothing was written.");
+            process.exit(1);
+          }
+          if (isValidToken(answer.trim())) token = answer.trim();
+          else console.error("  ✗ Token must start with bcf_ or bcf2_ — get one from the admin panel: Settings → Theme CLI tokens.");
+        }
+        if (!token) {
+          console.error("Too many invalid attempts.");
+          process.exit(1);
+        }
+      }
       if (!token) {
         token = await promptValid(
           rl,
           "Dev token (bcf_…): ",
           (s) => s.trim(),
           isValidToken,
-          "Token must start with bcf_ — get one from the admin panel: Settings → Theme CLI tokens.",
+          "Token must start with bcf_ or bcf2_ — get one from the admin panel: Settings → Theme CLI tokens.",
         );
       }
     } finally {
@@ -721,6 +1028,7 @@ async function login(rest) {
   saveVerifiedPair(name, "dev", { url, secret: token, identity, storeName });
   console.log(`✓ Saved context "${name}" → ${credentialsPath()}`);
   console.log(`  Site: ${siteLabel(identity.site)} — commands using context "${name}" target this site.`);
+  console.log(`  Secret store: ${storeLabel(storeName)}`);
   console.log(`Next: bind a project directory:  blocofy link <dir> --context ${name}   (or pull into an empty one: blocofy theme pull <dir> --context ${name})`);
 }
 
@@ -735,6 +1043,7 @@ async function contextsCommand(rest) {
     platform_origin: c.platform_origin ?? null,
     dev: c.dev ? { url: c.dev.url, store: c.dev.secret.store } : null,
     api: c.api ? { url: c.api.url, store: c.api.secret.store } : null,
+    login: c.oauth ? { url: c.oauth.url, store: c.oauth.secret.store, profile: c.oauth.profile ?? null, state: c.oauth.state ?? "active" } : null,
     verified_at: c.verified_at ?? null,
   }));
   if (JSON_MODE) {
@@ -747,7 +1056,8 @@ async function contextsCommand(rest) {
   }
   for (const r of rows) {
     const site = r.site ? `${siteLabel(r.site)} · ${r.site.id}` : "(not verified yet)";
-    const pairs = [r.dev ? `dev ${r.dev.url} [${r.dev.store}]` : null, r.api ? `api ${r.api.url} [${r.api.store}]` : null].filter(Boolean).join(", ");
+    const login = r.login ? `cli-login ${r.login.url} [${r.login.store}]${r.login.profile ? ` ${r.login.profile.id}@${r.login.profile.version}` : ""}${r.login.state === "reauth_required" ? " (needs a new login)" : ""}` : null;
+    const pairs = [r.dev ? `dev ${r.dev.url} [${r.dev.store}]` : null, r.api ? `api ${r.api.url} [${r.api.store}]` : null, login].filter(Boolean).join(", ");
     console.log(`${r.current ? "*" : " "} ${r.name}  ${site}  ${pairs}`);
   }
 }
@@ -766,20 +1076,82 @@ async function useCommand(rest) {
   console.log("  (Inside a bound project the project's site decides; `use` never retargets it.)");
 }
 
+/**
+ * ADR-0014 §5.5 — `blocofy logout [--context <name>]`. Two independent results, both printed:
+ *   server  revoked (RFC 7009 /revoke answered 200) | unreachable (network / 5xx: NOT revoked) | refused (another
+ *           answer: NOT revoked) | unavailable (the saved login could not be read: NOT revoked) | not_applicable
+ *           (a pasted token or key: revoke it in the panel)
+ *   local   cleared | failed — done whatever the server said.
+ * Exit 0 only when the local login is cleared and nothing is left open on the server; otherwise 4.
+ */
 async function logoutCommand(rest) {
   const { flags, positionals } = parseArgsOrExit(rest, []);
-  const name = typeof flags.context === "string" ? flags.context : null;
-  if (!name || positionals.length) throw new TargetError("USAGE", "Usage: blocofy logout --context <name>", {}, 1);
-  withStoreLock(() => {
-    const store = loadStore();
-    const ctx = store.contexts[name];
-    if (!ctx) throw new TargetError("TARGET_CONTEXT_UNKNOWN", `No context named "${name}".`, { context: name });
-    removeSecrets(name, ctx);
-    delete store.contexts[name];
-    if (store.current_context === name) store.current_context = null;
-    saveStore(store);
-  });
-  console.log(`✓ Removed context "${name}" and its secrets.`);
+  if (positionals.length) throw new TargetError("USAGE", "Usage: blocofy logout [--context <name>]", {}, 1);
+  const store0 = loadStore();
+  const name = typeof flags.context === "string" ? flags.context : store0.current_context;
+  if (!name) throw new TargetError("USAGE", "Usage: blocofy logout --context <name> (no default context is set; see `blocofy contexts`).", {}, 1);
+  const ctx = store0.contexts[name];
+  if (!ctx) throw new TargetError("TARGET_CONTEXT_UNKNOWN", `No context named "${name}".`, { context: name });
+
+  let server = { outcome: "not_applicable", status: null };
+  if (ctx.oauth) {
+    let tokens = null;
+    try {
+      tokens = readOAuthTokens(name, ctx);
+    } catch {
+      tokens = null;
+    }
+    const token = tokens?.refresh_token ?? tokens?.access_token ?? null;
+    if (token) registerSecret(token);
+    server = token && ctx.oauth.revocation_endpoint
+      ? await revokeToken({ endpoint: ctx.oauth.revocation_endpoint, token, clientId: ctx.oauth.client_id ?? CLI_CLIENT_ID })
+      : { outcome: "unavailable", status: null };
+  }
+
+  let local = "cleared";
+  let localError = null;
+  try {
+    withStoreLock(() => {
+      const store = loadStore();
+      const current = store.contexts[name];
+      if (!current) return;
+      removeSecrets(name, current);
+      delete store.contexts[name];
+      if (store.current_context === name) store.current_context = null;
+      saveStore(store);
+    });
+  } catch (error) {
+    local = "failed";
+    localError = error;
+  }
+
+  const hub = ctx.oauth ? `${String(ctx.oauth.url).replace(/\/+$/, "")}${CONNECTIONS_PATH}` : null;
+  const ok = local === "cleared" && (server.outcome === "revoked" || server.outcome === "not_applicable");
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ logout: { context: name, local, server: server.outcome, ...(server.status ? { server_status: server.status } : {}), ...(hub && server.outcome !== "revoked" ? { revoke_in_panel: hub } : {}) } }, null, 2));
+  } else {
+    console.log(local === "cleared" ? `✓ Yerel giriş silindi (context "${name}").` : `✗ Yerel giriş SİLİNEMEDİ (context "${name}"): ${redact(localError?.message ?? String(localError))}`);
+    switch (server.outcome) {
+      case "revoked":
+        console.log("✓ Sunucudaki CLI bağlantısı iptal edildi.");
+        break;
+      case "not_applicable":
+        console.log("  Sunucuda iptal edilecek bir CLI girişi yok: bu context yapıştırılmış bir token/anahtar taşıyordu; onu panelden iptal edebilirsin.");
+        break;
+      case "unreachable":
+        console.log(`✗ Sunucudaki bağlantı İPTAL EDİLMEDİ (platforma ulaşılamadı${server.status ? `, HTTP ${server.status}` : ""}) — panelden kes: ${hub}`);
+        break;
+      case "refused":
+        console.log(`✗ Sunucudaki bağlantı İPTAL EDİLMEDİ (platform isteği reddetti, HTTP ${server.status}) — panelden kes: ${hub}`);
+        break;
+      default:
+        console.log(`✗ Sunucudaki bağlantı İPTAL EDİLMEDİ (kayıtlı giriş okunamadı) — panelden kes: ${hub}`);
+    }
+  }
+  if (!ok) {
+    if (!JSON_MODE) console.error(`logout: local ${local}, server ${server.outcome} — not complete (exit 4).`);
+    process.exit(4);
+  }
 }
 
 async function linkCommand(rest) {
@@ -791,8 +1163,7 @@ async function linkCommand(rest) {
   if (!flagContext && !process.env.BLOCOFY_CONTEXT && !envCtx) {
     throw new TargetError("TARGET_CONTEXT_REQUIRED", "`blocofy link` needs the context to bind: pass --context <name> (see `blocofy contexts`).", {});
   }
-  const resolved = await resolveContext({ flagContext, envContextName: process.env.BLOCOFY_CONTEXT || null, envCtx, getStore: () => loadStore(), binding: null });
-  const secrets = resolved.env ? resolved.env.secrets : readSecrets(resolved.name, resolved.context);
+  const { resolved, secrets } = await credentialsFor(await resolveContext({ flagContext, envContextName: process.env.BLOCOFY_CONTEXT || null, envCtx, getStore: () => loadStore(), binding: null }));
   registerSecret(secrets.devToken);
   registerSecret(secrets.apiKey);
   assertCredentialTypes({ resolved, secrets });
@@ -832,6 +1203,31 @@ async function targetCommand(rest) {
   else printTarget(t.display, { stream: process.stdout });
 }
 
+/**
+ * ADR-0014 §5 — the secrets of a resolved context. A browser-login context answers with its (renewed) CLI token in
+ * both places: the v1 API at its platform origin and, when the site has a domain, the renderer's `/api/dev`.
+ * Returns `{ resolved, secrets, renewToken }` (`renewToken`: a getter for long-running commands, else null).
+ */
+async function credentialsFor(resolved) {
+  activeContext = resolved.name;
+  if (resolved.env) return { resolved, secrets: resolved.env.secrets, renewToken: null };
+  const ctx = resolved.context;
+  if (!ctx.oauth) return { resolved, secrets: readSecrets(resolved.name, ctx), renewToken: null };
+  const access = await accessTokenFor(resolved.name);
+  registerSecret(access);
+  const view = { ...ctx, api: { url: ctx.oauth.url, secret: ctx.oauth.secret } };
+  if (ctx.oauth.dev_url) view.dev = { url: ctx.oauth.dev_url, secret: ctx.oauth.secret };
+  return {
+    resolved: { ...resolved, context: view, oauth: true },
+    secrets: { devToken: ctx.oauth.dev_url ? access : null, apiKey: access },
+    renewToken: async () => {
+      const t = await accessTokenFor(resolved.name);
+      registerSecret(t);
+      return t;
+    },
+  };
+}
+
 /** "BLOCOFY_CONTEXT=beta, env credentials" — the stated context choices an explicit --context overrode. */
 function overridesLabel(ignored) {
   return ignored.map((a) => (a.source === "env" ? "env credentials" : `${a.source}=${a.name}`)).join(", ");
@@ -875,7 +1271,7 @@ async function prepareTarget({ command, commandClass, dir, flags, needs, mode, r
   const { newBinding } = enforceBindingPolicy({ commandClass, binding, dir, command });
   const envCtx = envContext();
   let cachedStore = null;
-  const resolved = await resolveContext({
+  const chosen = await resolveContext({
     flagContext: typeof flags.context === "string" ? flags.context : null,
     envContextName: process.env.BLOCOFY_CONTEXT || null,
     envCtx,
@@ -885,14 +1281,17 @@ async function prepareTarget({ command, commandClass, dir, flags, needs, mode, r
     isTTY: Boolean(process.stdin.isTTY && process.stderr.isTTY),
     prompt: promptContext,
   });
-  precheckContext({ binding, resolved });
-  const secrets = resolved.env ? resolved.env.secrets : readSecrets(resolved.name, resolved.context);
+  precheckContext({ binding, resolved: chosen });
+  const { resolved, secrets, renewToken } = await credentialsFor(chosen);
   registerSecret(secrets.devToken);
   registerSecret(secrets.apiKey);
   assertCredentialTypes({ resolved, secrets });
 
   const hasDev = Boolean(resolved.context.dev && secrets.devToken);
   const hasApi = Boolean(resolved.context.api && secrets.apiKey);
+  if (needs === "dev" && !hasDev && resolved.oauth) {
+    throw new TargetError("LOGIN_REQUIRED", `Context "${resolved.name}" is a CLI login, but the site has no domain yet, so the theme-file endpoints (/api/dev) cannot be reached. Nothing was sent. Give the site a domain in the panel, then log in again: blocofy login --context ${resolved.name}`, { context: resolved.name }, 1);
+  }
   if (needs === "dev" && !hasDev) {
     throw new TargetError("LOGIN_REQUIRED", `Login required: context "${resolved.name}" has no dev token. Run \`blocofy login${resolved.env ? "" : ` --context ${resolved.name}`}\` (or set BLOCOFY_URL + BLOCOFY_TOKEN).`, { context: resolved.name }, 1);
   }
@@ -907,7 +1306,7 @@ async function prepareTarget({ command, commandClass, dir, flags, needs, mode, r
   if (needs === "both" && !hasDev) {
     throw new TargetError(
       "LOGIN_REQUIRED",
-      `Login required: context "${resolved.name}" has no dev token. Run \`blocofy login${resolved.env ? "" : ` --context ${resolved.name}`}\` (or set BLOCOFY_URL + BLOCOFY_TOKEN). Site plan/apply need both a dev token and a v1 API key.`,
+      `Login required: context "${resolved.name}" has no dev token. Run \`blocofy login${resolved.env ? "" : ` --context ${resolved.name}`}\` (or set BLOCOFY_URL + BLOCOFY_TOKEN). This command needs both a dev token and a v1 API key (site plan/apply, theme push --work).`,
       { context: resolved.name },
       1,
     );
@@ -929,6 +1328,7 @@ async function prepareTarget({ command, commandClass, dir, flags, needs, mode, r
     binding,
     newBinding,
     display,
+    renewToken,
   };
 }
 
@@ -961,7 +1361,9 @@ async function themePull(rest) {
   const draft = Boolean(flags.draft);
   const instance = typeof flags.instance === "string" ? flags.instance : null;
   const what = instance ? `instance ${instance}` : draft ? "draft" : "live";
-  // Review M1: a draft pull provisions the draft server-side (`?draft=1`), so it is a remote mutation: binding required.
+  // Review M1: a draft pull was classed a remote mutation (binding required) because `?draft=1` used to provision the
+  // draft server-side. A current platform never creates a theme on a read (ADR-0013 D6: 404 `target_missing`); the
+  // class is kept fail-closed for platforms from before that change.
   const target = await prepareTarget({ command: draft ? "theme pull --draft" : "theme pull", commandClass: draft ? "remote-mutation" : "local-write", dir, flags, needs: "dev", mode: what });
   let count;
   try {
@@ -971,12 +1373,71 @@ async function themePull(rest) {
     if (error?.code === "draft_target_unverifiable") {
       failAndExit({ code: "draft_target_unverifiable", status: 503, message: "The platform could not verify which draft to pull (a read failed on its side). Nothing was written. Try again in a moment.", details: {} });
     }
+    failOnThemeCapacityRefusal(error, commandLine("blocofy theme push", positionals));
     throw error;
   }
   console.log(`Downloaded ${count} ${what} theme files → ${dir}`);
   bindAfterPull(target, dir);
 }
 
+// ── draft-only logins write into their own theme work (ADR-0014 §3.5, P4 follow-up) ───────────────────────
+
+/** Profiles that never write a live or implicit target: their writes go to their own theme work. */
+const DRAFT_ONLY_PROFILES = new Set(["theme-dev", "review", "service-ci"]);
+
+/** The project's saved work: `.blocofy/local.json` (theme work start / init), else `.blocofy/init.json`. */
+function savedWorkOf(binding) {
+  const local = readSavedWork(binding);
+  if (local?.handle && local.theme) return local;
+  let init = null;
+  try {
+    init = readInitState(binding.root);
+  } catch {
+    init = null;
+  }
+  if (init && isWorkHandle(init.work_handle) && String(init.site_id) === String(binding.project.site_id)) {
+    return { handle: init.work_handle, theme: typeof init.work_theme === "string" ? init.work_theme : null };
+  }
+  return local?.handle ? local : null;
+}
+
+/**
+ * Offline (no request): when the context this command will use carries a draft-only profile (a browser login, or a
+ * recorded profile), `{ profile, work }` with the project's saved work (or null); otherwise null — then the command
+ * behaves as before. Any resolution problem returns null and is reported by `prepareTarget` as usual.
+ */
+async function draftOnlyDefaults(dir, flags) {
+  let binding;
+  let resolved;
+  try {
+    binding = findBinding(dir);
+    resolved = await resolveContext({ flagContext: typeof flags.context === "string" ? flags.context : null, envContextName: process.env.BLOCOFY_CONTEXT || null, envCtx: envContext(), getStore: () => loadStore(), binding, isTTY: false, prompt: null });
+  } catch {
+    return null;
+  }
+  const profile = resolved.context?.oauth?.profile ?? resolved.context?.profile ?? null;
+  if (!profile || !DRAFT_ONLY_PROFILES.has(profile.id)) return null;
+  return { profile, work: binding ? savedWorkOf(binding) : null };
+}
+
+function themeWorkRequired(profile, command) {
+  return withLines(
+    new TargetError(
+      "THEME_WORK_REQUIRED",
+      `This login is draft-only (profile ${profile.id}): \`${command}\` writes only into its own theme work, and this project has no saved work. Nothing was sent. Set one up: blocofy init <dir> (a new project) or blocofy theme work start (this project); or name the target: --work <wk_…> / --instance <theme>.`,
+      { profile: profile.id },
+      3,
+    ),
+    [
+      `Bu giriş yalnız taslak üzerinde çalışır ("${profile.label ?? profile.id}"): \`${command}\` yalnız kendi tema çalışmasına yazar ve bu projede kayıtlı bir tema çalışması yok. Hiçbir şey gönderilmedi.`,
+      "  Yeni proje:  blocofy init <dizin>   ·   bu projede yeni çalışma:  blocofy theme work start",
+      "  Ya da hedefi açıkça ver:  --work <wk_…>  /  --instance <tema>",
+    ],
+  );
+}
+
+const savedWorkNote = (work) => `Kayıtlı tema çalışması kullanılıyor: ${work.handle}${work.theme ? ` (tema ${work.theme})` : ""} — başka bir hedef için --work / --instance ver.`;
+
 async function themePush(rest) {
   const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themePush);
   const dir = resolve(positionals[0] ?? process.cwd());
@@ -984,22 +1445,44 @@ async function themePush(rest) {
     console.error(`Theme directory not found: ${dir}`);
     process.exit(1);
   }
-  const instanceFlag = typeof flags.instance === "string" ? flags.instance : null;
+  let instanceFlag = typeof flags.instance === "string" ? flags.instance : null;
   const name = typeof flags.name === "string" ? flags.name : null;
   const dryRun = Boolean(flags["dry-run"] || flags.validate);
+  // CF-T2: `--diff` and `--dry-run` are reads; every other push is a remote mutation (binding required). The
+  // target is verified (whoami, both pairs, binding) before the first theme request — no best-effort swallow.
+  const readOnly = Boolean(flags.diff) || dryRun;
+  // Theme work: `--work <wk_…>` names the target itself — that work's own draft theme, read from the v1 API (the
+  // work belongs to the API key) and written through the dev token as `--draft --instance <work theme>`. Both pairs
+  // must resolve to the same site (prepareTarget "both"); the work must be open. Never live.
+  // A draft-only login with no explicit target writes into the project's saved work (explicit flags win).
+  let savedWork = null;
+  if (flags.work === undefined && !instanceFlag && !flags.live) {
+    const d = await draftOnlyDefaults(dir, flags);
+    if (d) {
+      if (!d.work) throw themeWorkRequired(d.profile, "theme push");
+      savedWork = d.work.handle;
+      if (!JSON_MODE) console.error(savedWorkNote(d.work));
+    }
+  }
+  const workHandle = flags.work === undefined ? savedWork : flags.work;
+  let workTarget = null;
+  if (workHandle !== null) {
+    if (!isWorkHandle(workHandle)) throw new TargetError("USAGE", "--work needs a work handle (wk_…, from `blocofy theme work start`). Nothing was sent.", {}, 1);
+    if (flags.live || instanceFlag) throw new TargetError("USAGE", "--work names the target itself; it cannot be combined with --live or --instance. Nothing was sent.", {}, 1);
+    workTarget = await prepareTarget({ command: "theme push", commandClass: readOnly ? "read" : "remote-mutation", dir, flags, needs: "both", mode: `${readOnly ? (flags.diff ? "read · diff vs " : "read · dry run · ") : "draft · "}work ${workHandle}` });
+    instanceFlag = (await openWorkTheme(workTarget.api, workHandle)).theme;
+  }
+  const draftFlag = Boolean(flags.draft) || workHandle !== null;
   // Yeni varsayılan hedef: DRAFT (güvenli). `--live` eski anında-canlı davranışını
   // açıkça geri getirir; `--instance` belirli bir temayı adresler. Sadece "live"
   // modu canlıya yazar ve onay gerektirir.
   const { mode, instance } = resolvePushMode({
     live: Boolean(flags.live),
-    draft: Boolean(flags.draft),
+    draft: draftFlag,
     instance: instanceFlag,
   });
-  // CF-T2: `--diff` and `--dry-run` are reads; every other push is a remote mutation (binding required). The
-  // target is verified (whoami, both pairs, binding) before the first theme request — no best-effort swallow.
-  const readOnly = Boolean(flags.diff) || dryRun;
   const opMode = flags.diff ? `read · diff vs ${instanceFlag ? `instance ${instanceFlag}` : mode === "draft" ? "CLI draft" : "live"}` : dryRun ? `read · dry run (${mode === "instance" ? `instance ${instance}` : mode})` : mode === "instance" ? `instance ${instance}` : mode;
-  const target = await prepareTarget({ command: "theme push", commandClass: readOnly ? "read" : "remote-mutation", dir, flags, needs: "dev", mode: `${opMode}${flags.prune && !readOnly ? " · prune" : ""}` });
+  const target = workTarget ?? (await prepareTarget({ command: "theme push", commandClass: readOnly ? "read" : "remote-mutation", dir, flags, needs: "dev", mode: `${opMode}${flags.prune && !readOnly ? " · prune" : ""}` }));
   const creds = target.dev;
   // 0.5.0: her push'a otomatik idempotency key — kanonik dal (protokol + key) ancak böyle seçilir; key
   // OLMADAN header'lar tek başına legacy writer'a düşer ve --live push pinned render'a YANSIMAZ (M4
@@ -1044,7 +1527,7 @@ async function themePush(rest) {
   const whoami = target.identity;
   const siteName = siteLabel(whoami.site) || String(whoami.site.id);
   if (mode === "instance") {
-    console.log(`→ Pushing to theme ${instance} of ${siteName}${whoami.liveThemeId != null && String(instance) === String(whoami.liveThemeId) ? " (the LIVE theme)" : ""}`);
+    console.log(`→ Pushing to theme ${instance} of ${siteName}${workHandle ? ` (work ${workHandle})` : whoami.liveThemeId != null && String(instance) === String(whoami.liveThemeId) ? " (the LIVE theme)" : ""}`);
   } else if (mode === "live") {
     console.log(dryRun ? `→ Validating against the LIVE theme of ${siteName} (dry run — nothing will be written)` : `→ Pushing to the LIVE theme of ${siteName}`);
   } else {
@@ -1061,7 +1544,7 @@ async function themePush(rest) {
   const instanceIsLive = mode === "instance" && instanceMaybeLive(instance, whoami.liveThemeId);
   // `--draft --instance <h>`: a draft write to a chosen draft. It never reaches the live theme — refused here when the
   // handle may be live (fail-closed), and by the server (422 draft_target_is_live) in any case.
-  const draftInstance = mode === "instance" && Boolean(flags.draft);
+  const draftInstance = mode === "instance" && draftFlag;
   if (draftInstance && instanceIsLive && !dryRun) {
     console.error(`✗ --draft --instance ${instance}: ${whoami.liveThemeId != null && String(instance) === String(whoami.liveThemeId) ? "that is the LIVE theme" : "this may be the LIVE theme (it could not be told apart from it)"}; a draft push never writes live. Nothing was written.`);
     console.error("  Pass a draft's handle (`blocofy status`), or drop --draft and confirm a live push.");
@@ -1182,6 +1665,8 @@ async function themePush(rest) {
       }
       failAndExit({ code: "idempotency_conflict", status: error.status, message: "The idempotency key was already used with different content. Retry with a new key (or omit --idempotency-key).", details: {} });
     }
+    // ADR-0013: the new draft this push needs was refused (definite answer, before the unknown-outcome handling below).
+    failOnThemeCapacityRefusal(error, commandLine("blocofy theme push", positionals));
     const refusal = themePushRefusal(error, { draft: mode === "draft", idempotencyKey });
     if (refusal) failAndExit({ code: error.code, status: error.status, ...refusal });
     throw error;
@@ -1223,6 +1708,10 @@ async function themePush(rest) {
       console.log(`✓ Deployed: ${ids}. The written files were not verified (this server does not read them back).`);
     }
     if (result.convergence === "converged") console.log("  (already applied by an earlier push with the same idempotency key)");
+    if (workHandle) {
+      console.log(`Çalışma ${workHandle} güncellendi (tema ${instance}). Canlı site değişmedi.`);
+      console.log(`Durumu:  blocofy theme work status ${workHandle}`);
+    }
     if (mode === "draft") {
       const h = typeof result.targetInstance === "string" ? result.targetInstance : null;
       const label = result.targetName ? ` "${result.targetName}"` : "";
@@ -2070,12 +2559,22 @@ async function themeDev(rest) {
 
   // CF-T2: draft sync mutates the site (remote-mutation, binding required); `--no-sync` only renders (read).
   const noSync = Boolean(flags["no-sync"]);
+  // A draft-only login syncs into the project's saved work's theme unless --instance names another target.
+  let savedInstance = null;
+  if (!noSync && typeof flags.instance !== "string") {
+    const d = await draftOnlyDefaults(themeDir, flags);
+    if (d) {
+      if (!d.work?.theme) throw themeWorkRequired(d.profile, "theme dev");
+      savedInstance = d.work.theme;
+      if (!JSON_MODE) console.error(savedWorkNote(d.work));
+    }
+  }
   const target = await prepareTarget({ command: "theme dev", commandClass: noSync ? "read" : "remote-mutation", dir: themeDir, flags, needs: "dev", mode: noSync ? "read · local preview" : "draft" });
   const creds = target.dev;
   const port = Number(flags.port) || 3030;
   // #989: `--instance <handle>` names the draft to sync into, for a site where the platform refuses to pick one. Draft
   // sync never writes the live theme, so the live theme's handle is refused here.
-  const devInstance = typeof flags.instance === "string" ? flags.instance : null;
+  const devInstance = typeof flags.instance === "string" ? flags.instance : savedInstance;
   if (devInstance && instanceMaybeLive(devInstance, target.identity?.liveThemeId ?? null)) {
     console.error(`✗ ${devInstance} is (or could not be told apart from) the LIVE theme. 'theme dev' syncs to a draft only; pick a draft handle (\`blocofy status\`) or use --no-sync.`);
     process.exit(2);
@@ -2151,7 +2650,8 @@ async function themeDev(rest) {
   const handle = startDevServer({
     dir: themeDir,
     url: creds.url,
-    token: creds.token,
+    // A CLI login's access token lives 10 minutes: the server asks for a fresh one per request.
+    token: target.renewToken ?? creds.token,
     port,
     // Taslak senkronu dev session'a BAĞLI DEĞİL: `pushTheme({draft:true})` /api/dev/theme'e gider ve
     // session'dan hiçbir veri kullanmaz. Bu satır `Boolean(session)` iken, session 410 alınca senkron
@@ -2271,6 +2771,8 @@ async function themePublish(rest) {
         details: { reason: error.reason ?? null, instance: error.instance ?? null },
       });
     }
+    // A theme work's copy is never published directly; its way live is the approval (`theme work request-approval`).
+    if (error?.code === "work_not_publishable") failOnThemeWorkRefusal(error, { op: "publish" });
     throw error;
   }
   console.log(
@@ -2278,6 +2780,442 @@ async function themePublish(rest) {
   );
 }
 
+// ── theme work ("çalışma"): a safe, private copy of the live theme, continued by its exact handle ──────────────
+
+/**
+ * A theme-work refusal: the plain Turkish explanation first (human mode), then the shared `error [code]` line /
+ * `--json` envelope; exit 2 for a 4xx refusal, 1 for a 5xx one. Returns only when `error` is not a known refusal.
+ */
+function failOnThemeWorkRefusal(error, opts) {
+  const refusal = themeWorkRefusal(error, opts);
+  if (!refusal) return;
+  if (!JSON_MODE) for (const line of refusal.lines) console.error(line);
+  const code = error instanceof CliRefusal ? error.error?.code : error?.code;
+  failAndExit({ code, status: error.status, message: refusal.message, details: refusal.details });
+}
+
+/** The handle positional of status/resume/cancel — explicit, never "the latest"; the saved one is only suggested. */
+function workHandleArg(positionals, flags, usage) {
+  const handle = positionals[0];
+  if (positionals.length > 1) throw new TargetError("USAGE", `Usage: ${usage}`, {}, 1);
+  if (handle === undefined) {
+    let saved = null;
+    try {
+      saved = readSavedWork(findBinding(commandDir(flags.dir)));
+    } catch {
+      saved = null;
+    }
+    const hint = saved ? ` This project's saved work is ${saved.handle}${saved.intent ? ` ("${saved.intent}")` : ""}.` : "";
+    throw new TargetError("USAGE", `Usage: ${usage} — name the work by its handle (wk_…).${hint} Nothing was sent.`, saved ? { saved_work: saved.handle } : {}, 1);
+  }
+  if (!isWorkHandle(handle)) throw new TargetError("USAGE", `"${handle}" is not a work handle (wk_ + 26 characters, from \`blocofy theme work start\`). Nothing was sent.`, {}, 1);
+  return handle;
+}
+
+/** `theme push --work`: the work's theme, only while the work is open. Refusals exit here. */
+async function openWorkTheme(api, handle) {
+  let work;
+  try {
+    ({ work } = await getWork({ ...api, handle, onRetry }));
+  } catch (error) {
+    failOnThemeWorkRefusal(error, { op: "push", handle });
+    throw error;
+  }
+  if (work.state !== "open" || !work.theme) {
+    if (!JSON_MODE) {
+      console.error(`Çalışma ${handle} şu an değiştirilemez (durum: ${stateLabel(work.state)}). Hiçbir şey yazılmadı.`);
+      console.error(work.state === "sealed" ? "  İnceleme bitince ya da panelde düzenlemeye geri alınınca tekrar dene." : "  Yeni bir çalışma başlat:  blocofy theme work start");
+    }
+    failAndExit({ code: "work_state_conflict", status: 409, message: `The work is ${work.state}; a push needs an open work. Nothing was written.`, details: { state: work.state, stateVersion: work.state_version } });
+  }
+  if (!JSON_MODE) for (const line of staleLines(work) ?? []) console.error(line);
+  return work;
+}
+
+async function themeWorkStart(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeWorkStart);
+  const dir = singleDirArg(positionals, 'blocofy theme work start [dir] [--intent "<text>"] [--idempotency-key <k>]');
+  if (flags.intent !== undefined && (typeof flags.intent !== "string" || !flags.intent.trim() || flags.intent.trim().length > WORK_INTENT_MAX)) {
+    throw new TargetError("USAGE", `--intent needs a short label (1-${WORK_INTENT_MAX} characters). Nothing was sent.`, {}, 1);
+  }
+  if (flags["idempotency-key"] !== undefined && (typeof flags["idempotency-key"] !== "string" || !WORK_KEY_RE.test(flags["idempotency-key"]))) {
+    throw new TargetError("USAGE", "--idempotency-key must be 8-120 characters: letters, digits, . _ : - Nothing was sent.", {}, 1);
+  }
+  const intent = typeof flags.intent === "string" ? flags.intent.trim() : DEFAULT_WORK_INTENT;
+  const key = typeof flags["idempotency-key"] === "string" ? flags["idempotency-key"] : newWorkKey();
+  const target = await prepareTarget({ command: "theme work start", commandClass: "remote-mutation", dir, flags, needs: "api", mode: "draft · new work" });
+  const retryLine = `blocofy theme work start${positionals[0] ? ` ${positionals[0]}` : ""} --intent ${JSON.stringify(intent)} --idempotency-key ${key}`;
+  let answer;
+  try {
+    answer = await startWork({ ...target.api, intent, idempotencyKey: key, onRetry });
+  } catch (error) {
+    // A 4xx is a definite refusal (nothing started). Anything else (network, a 5xx after the retries) may hide a work
+    // that WAS started: the SAME key returns it, a new key would start a second one — so the retry line names the key.
+    const definite = error instanceof CliRefusal;
+    const refusal = themeWorkRefusal(error, { op: "start" });
+    if (definite && !refusal) throw error;
+    if (!JSON_MODE) {
+      const lines = refusal?.lines ?? ["Platformdan kesin yanıt alınamadı; çalışmanın başlayıp başlamadığı bilinmiyor."];
+      for (const line of lines) console.error(line);
+      if (!definite) console.error(`  Aynı anahtarla tekrar çalıştır (başladıysa aynı çalışma döner, ikincisi açılmaz):  ${retryLine}`);
+    }
+    const code = definite ? error.error?.code : error?.code ?? (error instanceof TypeError ? "NETWORK_ERROR" : "ERROR");
+    const message = refusal?.message ?? `No definite answer from the platform; whether the work started is unknown. Run again with the same key: ${retryLine}`;
+    failAndExit({ code, status: error.status, message, details: { ...(refusal?.details ?? {}), ...(definite ? {} : { idempotencyKey: key }) } });
+  }
+  const { work } = answer;
+  const saved = saveWork(target.binding, work);
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ work, ...(answer.replayed ? { replayed: true } : {}), idempotency_key: key, saved }, null, 2));
+    return;
+  }
+  console.log(answer.replayed ? `✓ Bu anahtarla başlatılmış çalışma bulundu (yeni bir çalışma açılmadı): ${work.id}` : `✓ Çalışma başlatıldı: ${work.id}`);
+  for (const line of workLines(work)) console.log(line);
+  for (const line of staleLines(work) ?? []) console.log(line);
+  console.log("Canlı site değişmedi; bu çalışma ziyaretçilere görünmez.");
+  console.log(`Dosyalarını gönder:  blocofy theme push${positionals[0] ? ` ${positionals[0]}` : ""} --draft --work ${work.id}`);
+  console.log(`Durumu:              blocofy theme work status ${work.id}`);
+  console.log(saved ? "  (Bu projede kayıtlı çalışma olarak .blocofy/local.json'a yazıldı.)" : "  (Proje bağlı olmadığı için tanıtıcı kaydedilmedi; bir yere not et.)");
+  console.log(`technical: work ${work.id}, theme ${work.theme}, idempotency key ${key}`);
+}
+
+async function themeWorkStatus(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeWorkStatus);
+  const handle = workHandleArg(positionals, flags, "blocofy theme work status <wk_…> [--dir <dir>]");
+  const target = await prepareTarget({ command: "theme work status", commandClass: "read", dir: commandDir(flags.dir), flags, needs: "api", mode: `read · work ${handle}` });
+  let answer;
+  try {
+    answer = await getWork({ ...target.api, handle, onRetry });
+  } catch (error) {
+    failOnThemeWorkRefusal(error, { op: "status", handle });
+    throw error;
+  }
+  // Where its publication stands (read-only). A platform without the status endpoint just shows the work.
+  let publish = null;
+  try {
+    publish = await getPublishStatus({ ...target.api, handle, onRetry });
+  } catch {
+    publish = null;
+  }
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ work: answer.work, ...(publish ? { publish } : {}) }, null, 2));
+    return;
+  }
+  for (const line of workLines(answer.work)) console.log(line);
+  for (const line of publishStatusLines(publish)) console.log(line);
+  for (const line of staleLines(answer.work) ?? []) console.log(line);
+}
+
+/** A 404/405 from a review endpoint right after the work was read means the platform has no such endpoint yet. */
+const endpointMissing = (error) =>
+  error instanceof CliRefusal && ["not_found", "http_404", "http_405", "method_not_allowed"].includes(error.error?.code) && error.error?.details?.reason !== "target_deleted";
+
+async function themeWorkSeal(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeWorkSeal);
+  const handle = workHandleArg(positionals, flags, "blocofy theme work seal <wk_…> [--dir <dir>]");
+  const target = await prepareTarget({ command: "theme work seal", commandClass: "remote-mutation", dir: commandDir(flags.dir), flags, needs: "api", mode: `draft · prepare work ${handle} for review` });
+  try {
+    await getWork({ ...target.api, handle, onRetry });
+  } catch (error) {
+    failOnThemeWorkRefusal(error, { op: "seal", handle });
+    throw error;
+  }
+  let answer;
+  try {
+    answer = await sealWork({ ...target.api, handle, onRetry });
+  } catch (error) {
+    if (endpointMissing(error)) {
+      if (!JSON_MODE) {
+        console.error("Bu platform ayrı bir 'incelemeye hazırla' adımını henüz desteklemiyor. Hiçbir şey yazılmadı.");
+        console.error(`  Onay isteği çalışmayı kendisi hazırlar:  blocofy theme work request-approval ${handle}`);
+      }
+      failAndExit({ code: "seal_unsupported", status: error.status, message: "This platform has no seal endpoint yet; request-approval prepares the work itself (seal_unsupported)." });
+    }
+    failOnThemeWorkRefusal(error, { op: "seal", handle });
+    throw error;
+  }
+  if (JSON_MODE) {
+    console.log(JSON.stringify(answer, null, 2));
+    return;
+  }
+  console.log(answer.already_sealed ? `✓ Çalışma zaten incelemeye hazır: ${handle}` : `✓ Çalışma incelemeye hazır: ${handle}`);
+  console.log("  İçeriği artık değişmiyor. Canlı site değişmedi; onay istenmedi.");
+  if (answer.package?.digest_short) console.log(`  İçerik özeti: ${answer.package.digest_short}`);
+  console.log(`Yayın için onay iste:  blocofy theme work request-approval ${handle}`);
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * `--wait`: poll the read-only status until the request this command made ends (published, stale, expired, declined,
+ * superseded, cancelled, failed) or a deadline passes (the request's expiry + 1 minute, at most 20 minutes). A
+ * transient error keeps polling; a refusal ends the wait. Never publishes and never decides.
+ */
+async function waitForApproval(api, handle, approval, intervalMs) {
+  const expiry = Date.parse(approval.expires_at ?? "");
+  const cap = Date.now() + 20 * 60_000;
+  const deadline = Number.isFinite(expiry) ? Math.min(cap, expiry + 60_000) : cap;
+  let last = null;
+  for (;;) {
+    try {
+      last = await getPublishStatus({ ...api, handle, onRetry });
+      const state = approvalWaitState(last, approval.id);
+      if (state !== "pending") return { state, status: last };
+    } catch (error) {
+      if (error instanceof CliRefusal) {
+        failOnThemeWorkRefusal(error, { op: "wait", handle });
+        throw error;
+      }
+      if (!JSON_MODE) console.error("Durum okunamadı; tekrar denenecek.");
+    }
+    if (Date.now() + intervalMs > deadline) return { state: "timeout", status: last };
+    await sleep(intervalMs);
+  }
+}
+
+async function themeWorkRequestApproval(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeWorkRequestApproval);
+  const handle = workHandleArg(positionals, flags, "blocofy theme work request-approval <wk_…> [--dir <dir>] [--open] [--wait [--interval <s>]]");
+  let intervalMs = 3000;
+  if (flags.interval !== undefined) {
+    const n = Number(flags.interval);
+    if (!flags.wait || typeof flags.interval !== "string" || !Number.isInteger(n) || n < 1 || n > 60) {
+      throw new TargetError("USAGE", "--interval needs --wait and a whole number of seconds (1-60). Nothing was sent.", {}, 1);
+    }
+    intervalMs = n * 1000;
+  }
+  const target = await prepareTarget({ command: "theme work request-approval", commandClass: "remote-mutation", dir: commandDir(flags.dir), flags, needs: "api", mode: `draft · request approval for work ${handle}` });
+  let answer;
+  try {
+    answer = await requestApproval({ ...target.api, handle, onRetry });
+  } catch (error) {
+    failOnThemeWorkRefusal(error, { op: "request-approval", handle });
+    throw error;
+  }
+  const { approval } = answer;
+  const url = safeApprovalUrl(approval?.approval_url, target.api.apiUrl);
+  if (!JSON_MODE) {
+    console.log(`✓ Çalışma incelemeye hazır ve onay istendi: ${handle}`);
+    console.log(`Onay URL'i:  ${url ? (process.stdout.isTTY ? hyperlink(url) : url) : approval?.approval_url ?? "(yok)"}`);
+    console.log("  Site sahibi ya da tema yetkisi olan bir ekip üyesi Blocofy'de oturum açıp bu sayfadan onaylar.");
+    console.log("  URL'de gizli bir anahtar yok; URL'e sahip olmak yayın yetkisi vermez.");
+    if (approval?.digest_short) console.log(`  Onaylanacak içerik özeti: ${approval.digest_short}${approval.expires_at ? ` · son geçerlilik: ${approval.expires_at}` : ""}`);
+    console.log("  Onaylanana kadar canlı site değişmez. Bu komut yayınlamaz.");
+  }
+  if (flags.open) {
+    if (url) {
+      openUrl(url);
+      if (!JSON_MODE) console.log("Onay sayfası tarayıcıda açılıyor.");
+    } else if (!JSON_MODE) {
+      console.error("Onay URL'i bu platformun onay sayfası gibi görünmüyor; tarayıcıda açılmadı.");
+    }
+  }
+  if (!flags.wait) {
+    if (JSON_MODE) console.log(JSON.stringify(answer, null, 2));
+    else console.log(`Durumu izle:  blocofy theme work status ${handle}   (ya da --wait ile bekle)`);
+    return;
+  }
+  if (!JSON_MODE) console.log("Karar bekleniyor (Ctrl+C ile çıkabilirsin; onay isteği geçerli kalır)…");
+  const { state, status } = await waitForApproval(target.api, handle, approval, intervalMs);
+  const outcome = approvalOutcome(state, { handle, status });
+  if (outcome.ok) {
+    if (JSON_MODE) console.log(JSON.stringify({ ...answer, outcome: state, publish: status }, null, 2));
+    else for (const line of outcome.lines) console.log(line);
+    return;
+  }
+  if (!JSON_MODE) for (const line of outcome.lines) console.error(line);
+  // A definite "not published" end is a refusal (exit 2); a timeout or a failure is not (exit 1).
+  const definite = !["timeout", "failed"].includes(state);
+  failAndExit({ code: outcome.code, ...(definite ? { status: 409 } : {}), message: outcome.message, details: { approval: approval?.id ?? null, phase: status?.phase ?? null } });
+}
+
+async function themeWorkResume(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeWorkResume);
+  const handle = workHandleArg(positionals, flags, "blocofy theme work resume <wk_…> [--dir <dir>] [--require-fresh]");
+  const target = await prepareTarget({ command: "theme work resume", commandClass: "read", dir: commandDir(flags.dir), flags, needs: "api", mode: `read · work ${handle}` });
+  let answer;
+  try {
+    answer = await resumeWork({ ...target.api, handle, requireFresh: Boolean(flags["require-fresh"]), onRetry });
+  } catch (error) {
+    failOnThemeWorkRefusal(error, { op: "resume", handle });
+    throw error;
+  }
+  const saved = saveWork(target.binding, answer.work);
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ work: answer.work, saved }, null, 2));
+    return;
+  }
+  console.log(`✓ Çalışmaya devam ediliyor: ${handle}`);
+  for (const line of workLines(answer.work)) console.log(line);
+  for (const line of staleLines(answer.work) ?? []) console.log(line);
+  console.log(`Dosyalarını gönder:  blocofy theme push --draft --work ${handle}`);
+}
+
+async function themeWorkCancel(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeWorkCancel);
+  const handle = workHandleArg(positionals, flags, "blocofy theme work cancel <wk_…> [--dir <dir>]");
+  const target = await prepareTarget({ command: "theme work cancel", commandClass: "remote-mutation", dir: commandDir(flags.dir), flags, needs: "api", mode: `draft · cancel work ${handle}` });
+  let work;
+  try {
+    ({ work } = await getWork({ ...target.api, handle, onRetry }));
+    if (work.state !== "cancelled") ({ work } = await cancelWork({ ...target.api, handle, expectedStateVersion: work.state_version, onRetry }));
+  } catch (error) {
+    // A resend after a lost answer meets its own earlier cancel: the work IS cancelled — report it, not a conflict.
+    if (!(error instanceof CliRefusal && error.error?.code === "work_state_conflict" && error.error?.details?.state === "cancelled")) {
+      failOnThemeWorkRefusal(error, { op: "cancel", handle });
+      throw error;
+    }
+    work = { id: handle, state: "cancelled", state_version: error.error.details.stateVersion ?? null };
+  }
+  const saved = readSavedWork(target.binding);
+  if (saved?.handle === handle) saveWork(target.binding, null);
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ work }, null, 2));
+    return;
+  }
+  console.log(`✓ Çalışma iptal edildi: ${handle}. Canlı site değişmedi; çalışmanın teması tema kitaplığında duruyor.`);
+}
+
+// ── blocofy init (ADR-0014 §5.6, wave P4) ─────────────────────────────────────────────────────────────────
+
+const INIT_USAGE = "blocofy init [dir] [--site <handle|slug>] [--context <name>] [--api-url <url>] [--no-browser] [--insecure-storage]";
+
+/** The context a resumed init directory recorded (`.blocofy/local.json`), if any. */
+function savedInitContext(dir) {
+  try {
+    const local = JSON.parse(readFileSync(join(dir, ".blocofy", "local.json"), "utf8"));
+    return typeof local?.context === "string" && local.context ? local.context : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `blocofy init [dir]`: pre-checks without any request; then the credential (a saved context, env credentials, or a
+ * browser login on a terminal); then the state machine of lib/init.mjs. Exit 0 only when a preview exists and the live
+ * theme read back is the one read before; 5 when the live theme changed meanwhile; 3 for a directory/site refusal.
+ */
+async function initCommand(rest) {
+  const { flags, positionals } = parseArgsOrExit(rest, KNOWN.init);
+  if (positionals.length > 1) throw new TargetError("USAGE", `Usage: ${INIT_USAGE}`, {}, 1);
+  const dir = resolve(positionals[0] ?? process.cwd());
+  const siteArg = typeof flags.site === "string" ? flags.site : null;
+  const unattended = isUnattended();
+
+  // 1. Pre-checks: nothing sent, nothing written.
+  const pre = inspectInitDir(dir);
+  if (pre.kind === "dirty") {
+    throw new InitError("INIT_DIR_NOT_EMPTY", `${dir} is not empty and is not a Blocofy project. Nothing was written. Run \`blocofy init\` in a new, empty directory (init never overwrites files).`, {
+      exitCode: 3,
+      details: { dir },
+      lines: ["Bu dizin boş değil ve bir Blocofy projesi değil; hiçbir şeyin üzerine yazılmadı.", "  Boş, yeni bir dizinde çalıştır:  blocofy init <yeni-dizin>"],
+    });
+  }
+  if (pre.kind === "legacy_project") {
+    throw new InitError("INIT_ALREADY_BOUND", `${dir} is already bound to a site (by \`link\` or \`theme pull\`); init does not take it over. Nothing was written. In that project use: blocofy theme work start`, {
+      exitCode: 3,
+      details: { dir },
+      lines: ["Bu dizin zaten bir siteye bağlı (link ya da theme pull ile); init onu sahiplenmez. Hiçbir şey yazılmadı.", "  O projede yeni bir tema çalışması başlat:  blocofy theme work start"],
+    });
+  }
+  if (siteArg && pre.kind === "resume" && String(pre.init.site_id) !== siteArg && pre.project?.site_slug !== siteArg) {
+    throw new InitError("INIT_SITE_MISMATCH", `${dir} was set up for site ${pre.project?.site_slug ?? pre.init.site_id}, not ${siteArg}. Nothing was sent or written.`, { exitCode: 3, details: { dir } });
+  }
+  // Unattended: never a browser, never a guessed site.
+  if (unattended && !siteArg) {
+    throw new InitError("INIT_SITE_REQUIRED", "In a non-interactive run, init needs the site named explicitly: --site <handle|slug> (and a saved --context or env credentials). Nothing was sent.", {
+      exitCode: 3,
+      lines: ["Etkileşimsiz çalıştırmada init hangi siteye kurulacağını tahmin etmez; hiçbir şey gönderilmedi.", "  Siteyi açıkça ver:  blocofy init <dizin> --site <site> --context <giriş>"],
+    });
+  }
+
+  // 2. The credential.
+  const envCtx = envContext();
+  let contextName = typeof flags.context === "string" ? flags.context : process.env.BLOCOFY_CONTEXT || (envCtx ? ENV_CONTEXT : null) || (pre.kind === "resume" ? savedInitContext(dir) : null);
+  if (!contextName) {
+    if (unattended) {
+      throw new InitError("INIT_LOGIN_REQUIRED", "No credential for init: pass --context <name> of a saved login, or set env credentials. A non-interactive run never opens a browser. Nothing was sent.", { exitCode: 3 });
+    }
+    ({ name: contextName } = await browserLoginAndSave({ flags, contextName: null, siteArg }));
+  }
+  const chosen = await resolveContext({ flagContext: contextName, envContextName: null, envCtx, getStore: () => loadStore(), binding: null });
+  const { resolved, secrets, renewToken } = await credentialsFor(chosen);
+  registerSecret(secrets.devToken);
+  registerSecret(secrets.apiKey);
+  assertCredentialTypes({ resolved, secrets });
+  if (!(resolved.context.api && secrets.apiKey) || !(resolved.context.dev && secrets.devToken)) {
+    throw new TargetError("LOGIN_REQUIRED", `Context "${resolved.name}" cannot run init: it needs the v1 API (theme work, preview) and the theme files endpoint. Log in with \`blocofy login\` (one login covers both) or add the missing pair.`, { context: resolved.name }, 1);
+  }
+  const identity = await verifyTarget({ resolved, secrets, binding: null, retry });
+  for (const w of identity.warnings ?? []) printWarning(w, { json: JSON_MODE });
+  if (siteArg && !siteMatches(identity.site, siteArg)) {
+    throw new InitError("INIT_SITE_MISMATCH", `Context "${resolved.name}" is for ${identity.site.slug ?? identity.site.id}, not ${siteArg}. Nothing was sent or written.`, { exitCode: 3, details: { context: resolved.name, site: identity.site.id } });
+  }
+  if (!JSON_MODE) printTarget(targetData({ site: identity.site, url: resolved.context.api.url, platformOrigin: identity.platformOrigin, contextName: resolved.name, contextSource: chosen.source, contextOverrides: [], bindingLabel: pre.kind === "resume" ? "this init directory" : "none (new init)", command: "init", mode: "draft · new work" }));
+
+  // 3. The state machine.
+  const api = initApi({
+    apiUrl: resolved.context.api.url,
+    devUrl: resolved.context.dev.url,
+    token: renewToken ?? secrets.apiKey,
+    devToken: renewToken ?? secrets.devToken,
+    onRetry,
+  });
+  const result = await runInit({
+    dir,
+    identity,
+    contextName: resolved.env ? ENV_CONTEXT : resolved.name,
+    profile: resolved.context.oauth?.profile ?? null,
+    api,
+    log: (line) => {
+      if (!JSON_MODE) console.error(line);
+    },
+  });
+
+  const rel = relative(process.cwd(), dir) || ".";
+  if (!result.liveUnchanged) {
+    throw new InitError("INIT_LIVE_CHANGED", `The live theme read back after init (${result.liveAfter ?? "none"}) is not the one read before it started (${result.liveBefore ?? "none"}). init never writes the live site; the change came from elsewhere. Not reported as a success.`, {
+      exitCode: 5,
+      details: { live_before: result.liveBefore, live_after: result.liveAfter, work: result.work.id },
+      lines: [
+        `Canlı tema init başladığından beri değişti (önce: ${result.liveBefore ?? "yok"}, şimdi: ${result.liveAfter ?? "yok"}). Bu yüzden başarı denmedi.`,
+        "  init canlı siteye yazmaz; değişiklik panelden ya da başka bir bağlantıdan gelmiş olabilir. Panelde tema geçmişine bak.",
+        `  Çalışman ve dosyaların yerinde: ${result.work.id} → ${rel}`,
+      ],
+    });
+  }
+  if (result.state !== "previewed") {
+    throw new InitError("INIT_PREVIEW_UNAVAILABLE", `The project is set up (work ${result.work.id}, files in ${rel}) and the live site did not change, but no preview link could be made (${result.preview}: the work's theme has no page with a plain address). Run \`blocofy init\` again to retry the preview.`, {
+      exitCode: 1,
+      details: { work: result.work.id, preview: result.preview },
+      lines: [
+        "Proje hazır ve canlı siten değişmedi, ama önizleme bağlantısı oluşturulamadı: çalışmanın temasında adresi olan bir sayfa yok.",
+        `  Aynı dizinde yeniden çalıştırınca yalnız önizleme denenir:  blocofy init ${rel}`,
+      ],
+    });
+  }
+  if (JSON_MODE) {
+    console.log(JSON.stringify({ init: { dir, state: result.state, work: { id: result.work.id, theme: result.work.theme }, preview_url: result.previewUrl, preview_created_earlier: result.previewCreatedEarlier, live_unchanged: true, live_theme: result.liveAfter, context: resolved.name, site: identity.site } }, null, 2));
+    return;
+  }
+  console.log("✓ Taslak hazır. Canlı siten değişmedi.");
+  console.log(`  Çalışma: ${result.work.id} (tema ${result.work.theme}) — dosyalar: ${rel}`);
+  if (result.previewUrl) console.log(`  Önizleme (bir kez gösterilir; paylaşılabilir, süresi dolar): ${result.previewUrl}`);
+  else console.log("  Önizleme bağlantısı daha önce oluşturuldu (bağlantılar bir kez gösterilir).");
+  console.log(`Sonraki adım: dosyaları düzenle, sonra  blocofy theme push ${rel} --draft --work ${result.work.id}`);
+  console.log(`  Yayın için insan onayı iste:  blocofy theme work request-approval ${result.work.id}`);
+  console.log(`technical: live theme ${result.liveAfter ?? "none"} read before and after; state in ${join(rel, ".blocofy", "init.json")}`);
+}
+
+const THEME_WORK_USAGE = "blocofy theme work start|status|resume|seal|request-approval|cancel … (see `blocofy --help`)";
+
+async function themeWork(rest) {
+  const [sub, ...subRest] = rest;
+  const handler = { start: themeWorkStart, status: themeWorkStatus, resume: themeWorkResume, seal: themeWorkSeal, "request-approval": themeWorkRequestApproval, cancel: themeWorkCancel }[sub];
+  if (!handler) throw new TargetError("USAGE", `Usage: ${THEME_WORK_USAGE}`, {}, 1);
+  return handler(subRest);
+}
+
 async function themeRename(rest) {
   const { flags, positionals } = parseArgsOrExit(rest, KNOWN.themeRename);
   const handle = positionals[0];
@@ -2484,6 +3422,7 @@ function commandKey(a, b) {
 // command → handler. Every failure exits through failAndExit (exit codes 1/2/3, --json envelope last).
 const COMMANDS = {
   login: login,
+  init: initCommand,
   contexts: contextsCommand,
   use: useCommand,
   logout: logoutCommand,
@@ -2495,6 +3434,7 @@ const COMMANDS = {
   "theme push": themePush,
   "theme publish": themePublish,
   "theme rename": themeRename,
+  "theme work": themeWork,
   "pages media-uses": pagesMediaUses,
   "pages media-decide": pagesMediaDecide,
   "pages pull": pagesPull,