syndai 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to the `syndai` npm package. Versions follow semver.
 
+## 0.6.0
+
+The steps that stay in the browser are one command away, and an agent can sign up.
+
+- `signup <email> [--code C]`: a new workspace and its key from a 6-digit code emailed to that
+  address, no browser. Continuing accepts the Terms and Privacy Policy (asked y/N on a terminal).
+  Off a terminal it mails the code and exits 3; rerun with `--code`, which only verifies. The
+  key is stored as `login` stores it. An address that already has a workspace uses `login`.
+- `connect <provider>` prints, and opens on a terminal, the workspace page that connects it
+  (`github`, `sentry`, `claude`, `chatgpt`, `openrouter`, `slack` and the social accounts).
+- `billing` shows the plan, the balance and the billing page; `billing packs` lists the credit
+  packs; `billing buy <pack>` and `billing plan <tier> [--interval month|year]` open a checkout a
+  person pays (nothing is charged until then); `card`, `cancel` and a plan change go to the
+  billing page.
+- `publish [--app A]` publishes the project as a hosted app and prints its live URL.
+- Out-of-credits and plan errors now name the workspace's billing page
+  (`https://app.syndai.ai/w/<id>/billing`; the old `app.syndai.ai/billing` link was dead), and
+  code-host errors its repositories card; both open on a terminal.
+- `watch` and `answer` print a question's connect link ("Connect it here") and open it on a
+  terminal.
+
+- `schedule add|edit` and `repeat` take `--budget` in credits (1 credit = US$0.25; the lowest
+  cap is 20 credits), and `schedule show` and `repeat` print the cap and the last run's cost in
+  credits, matching the portal. `--budget 5` used to mean US$5; it now means 5 credits.
+- `watch` (and `change`, `review`, which watch to the outcome) keeps watching through a deploy:
+  a run of 502/503s or dropped connections no longer ends it. It says once that Syndai is
+  unreachable and gives up only after 10 minutes without an answer.
+- `change --learn URL --sign-in` and `new "<text with a product link>" --sign-in`: before Syndai
+  reads the product, the run's page asks you to sign in to it yourself in a secure browser and
+  capture the in-app pages to learn from (or skip for public pages only). The CLI prints where to
+  do it and never asks for a password. `--sign-in` without a product is a usage error (exit 2).
+
+## 0.5.0
+
+Environments and secrets from a terminal, Doppler-style.
+
+- `env ls` lists the workspace's environments (the current one marked); `env use <env>` picks
+  the one this directory uses, stored in its link outside the repo. `link [project] --env E`
+  sets both. Otherwise: `--env`, then `SYNDAI_ENV`, then the workspace default.
+- `secrets` lists names, scope (shared or project) and when each changed, never a value.
+  `secrets set KEY` reads the value from a hidden prompt or stdin, never the command line;
+  `secrets rm KEY` asks first (`--yes` off a terminal); `secrets import FILE|-` stores a
+  `.env` in one all-or-nothing request. `--project` writes at the project's scope.
+- `secrets get KEY` prints one value to a terminal (`--plain` for a pipe, exact bytes);
+  `secrets download [-o FILE]` writes a `.env` to a pipe, or to a 0600 file and warns when git
+  does not ignore it; `run [--env E] [--] <command>` hands the values to the child's environment
+  only and exits with its code. The values layer the way a run's do: the project's over the
+  shared ones, over Test.
+- Reading values needs `coding:secrets:reveal`, which only a browser approval grants: the
+  first secrets command asks once for read, write and reveal together. Production values also
+  need you to allow each command in the browser; another process holding the same key, `SYNDAI_API_KEY`
+  (CI) and an MCP key never read them (exit 3).
+
+Learn from a product.
+
+- `new "<text>"` starts a project from scratch. A product link in the text (not GitHub) builds
+  your own version of it: Syndai reads its public pages, then asks which features to build and
+  what to call it. `--no-learn` treats the link as context only.
+- `change "<text>" --learn URL` adds features from that product to an existing project: Syndai
+  reads its public pages and asks which features to add (3 pre-checked). A link inside the
+  change text is never treated as one.
+
 ## 0.4.1
 
 - A running `watch`, `change` or MCP server no longer stops when `login` or a scope

package/README.md

@@ -9,6 +9,18 @@ npx -y syndai@latest change "make the header blue"
 # Changing bakery.syndai.app · goes live when checks pass
 ```
 
+Secrets and environments, Doppler-style:
+
+```bash
+syndai link bakery --env development     # this directory: project + environment
+syndai secrets                           # names, scope, updated (never a value)
+printf %s "$TOKEN" | syndai secrets set API_TOKEN   # or type it at the hidden prompt
+syndai secrets import .env               # a whole .env, all or nothing
+syndai run npm run dev                   # the values reach npm's environment only
+syndai secrets download -o .env.local    # 0600, warns if git does not ignore it
+syndai run --env production ./deploy     # asks you to allow this one command
+```
+
 Node 22 or newer, zero dependencies, no telemetry. The customer guide is the docs
 site's **CLI** page, https://syndai.ai/docs/cli (`web/content/docs/cli.mdx`); this
 README is for whoever works on the package.
@@ -18,28 +30,50 @@ README is for whoever works on the package.
 | command | does |
 |---|---|
 | `login [--with-token] [--scope S]...`, `logout`, `whoami` | browser-approved key (device flow); `--scope` asks for access on top of the key's current scopes; `--with-token` reads a key from stdin. Re-login saves the new key, then revokes the old one |
-| `link [project]` | remember which project this directory changes (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo) |
-| `change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome |
-| `new "<what>" [--no-learn] [--no-wait] [--timeout D]` | start a New project; a product URL in the text builds your own version of it (its feature pick is asked inline, Enter keeps the pre-checked core) |
+| `signup <email> [--code C]` | a new workspace and its key from a 6-digit emailed code (no browser); states that continuing accepts the Terms and Privacy Policy and asks y/N on a terminal. Off a terminal it mails the code and exits 3; `--code` only verifies (it never mails a new code). Stores the key as `login` does. An address that already has a workspace gets `code_invalid`: use `login` |
+| `link [project] [--env E]` | remember which project (and environment) this directory uses (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo); a re-link keeps the environment |
+| `env ls`, `env use <env>` | the workspace's environments (current marked); `use` stores one in this directory's link (an environment-only link when there is none). Chosen: `--env`, `SYNDAI_ENV`, the link, the workspace default |
+| `secrets [ls]` | names, scope (shared/project) and updated for the environment and this project; never a value, in text or `--json` |
+| `secrets set KEY`, `rm KEY [--yes]`, `import FILE\|-` [`--project`] | write shared values (or the project's with `--project`); `set` reads the value from a hidden prompt (one line) or stdin (any value, multi-line too), and refuses one on the command line without echoing it |
+| `secrets get KEY [--plain]`, `download [-o FILE]` | read values back: `get` refuses a pipe without `--plain` (then the exact bytes) and `--json`; `download` writes a pipe, or a 0600 file (`-o`, required on a terminal) and warns when git does not ignore it |
+| `run [--env E] [--app A] [--] <command>...` | spawn the command (syndai's options end at its first word; `--` only for a dash-led command) with the values added to its environment only; prints `Injected N values from <env>`; its exit code (a signal: 128+n, not found: 127) is syndai's |
+| `change "<what>" [--app A] [--review] [--learn URL [--sign-in]] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome; `--learn URL` reads that product's public pages and asks which of its features to add (3 pre-checked), then adds only those; `--sign-in` first has the run's page ask you to sign in to it yourself in a secure browser and capture its in-app pages (never a password here) |
+| `new "<what>" [--no-learn \| --sign-in] [--no-wait] [--timeout D]` | start a New project; a product URL in the text builds your own version of it (its feature pick is asked inline, Enter keeps the pre-checked core); `--sign-in` as for `change` |
 | `edit-text [--app A] [--page /] --from "..." --to "..."` / `--undo <sha>` | instant, free, undoable text swap on a live site |
 | `watch <run> [--timeout D] [--logs]` | follow any change; `--logs` tails its events |
 | `answer <run> [--input FILE\|-]` | answer an open question (`--input`: `{"entries":[...]}` from a file or stdin) |
 | `review <run> [--retry \| --close]` | see why a change is held, then approve it in the browser |
 | `go-live`, `revert`, `cancel <run>` | land actions |
+| `publish [--app A]` | publish (or redeploy) the project as a hosted app and print its live URL (`coding:apps:publish`) |
+| `connect <provider>` | print, and open on a terminal, the workspace page that connects it: `github` -> `settings#repositories`, `sentry` -> `sentry`, the plan logins, OpenRouter, Slack and social accounts -> `connections?connect=<provider>`. Finish in the browser; no key reads connection status |
+| `billing [--open]`, `packs`, `buy <pack>`, `plan <tier> [--interval month\|year] [--country CC]`, `card`, `cancel` | plan, balance (packs + included left - holds, as the portal shows it) and the billing page; `buy`/`plan` print and open a checkout a person pays (nothing is charged until then; `--country` else the locale's region else US prices it); `card`/`cancel` and an existing plan go to the billing page |
 | `status [--app A]` | what is running, and everything that needs you |
 | `settings [--app A] [get \| set k=v...]` | `autonomy`, `feature_requests`, `bug_scan`, `protected_paths` (`+=` adds) |
 | `mcp install claude\|cursor\|codex` | add the Syndai MCP server to that tool's user config, with its own key |
 | `schedule list [--app A \| --all]`, `show <id>` | a project's recurring runs: cadence, next fires, History |
-| `schedule add "<what>" --every E [--at T] [--tz Z] [--budget USD] [--app A]` | create one; `E` is `hourly` (`--at :MM`), `daily`/`weekdays` (`--at HH:MM`), `weekly` (`--at "mon HH:MM"`) or a 5-field cron |
-| `schedule edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget USD\|none]` | change only what differs |
+| `schedule add "<what>" --every E [--at T] [--tz Z] [--budget CREDITS] [--app A]` | create one; `E` is `hourly` (`--at :MM`), `daily`/`weekdays` (`--at HH:MM`), `weekly` (`--at "mon HH:MM"`) or a 5-field cron |
+| `schedule edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget CREDITS\|none]` | change only what differs |
 | `schedule pause \| resume \| run-now \| delete <id> [--yes]` | manage one (`delete` asks on a terminal, needs `--yes` off one) |
-| `repeat <run> --every E [--at T] [--tz Z] [--budget USD]` | repeat a run you liked; the server copies its prompt and project; the first run is the next scheduled time |
+| `repeat <run> --every E [--at T] [--tz Z] [--budget CREDITS]` | repeat a run you liked; the server copies its prompt and project; the first run is the next scheduled time |
 | `api` / `api <operationId> --help` | list every published operation / show one's parameters and body |
 | `api <operationId> \| <METHOD> <path> [-f k=v]... [-F k=v]... [--input FILE\|-] [--paginate] [--app A]` | call it with your key (`-f` string, `-F` typed, `k[]=v` lists) |
 
 A 403 that names a missing scope asks, on a terminal with a stored login, to approve
 it in the browser and retries once. `SYNDAI_API_KEY` never steps up; off a terminal the
 error names `syndai login --scope <scope>`. Members, keys and unpublish are portal-only.
+A missing `coding:secrets:*` scope asks once for all three (read, write, reveal). Reveal
+(reading values) is granted only by that browser approval, never by `--with-token`, the
+portal's key page or `mcp install`. A production environment's values also need a
+`PRODUCTION_STEP_UP_REQUIRED` approval: on a terminal with a stored login the CLI opens
+`/cli` for a person to allow THIS command, then retries once with that approval's grant (held
+in memory only, so another process with the same key gets nothing); off a terminal or under
+`SYNDAI_API_KEY` it exits 3.
+
+Errors a workspace page fixes name that page, `https://app.syndai.ai/w/<id>/<path>`
+(`portalUrl` in `src/errors.js`): out of credits or plan limits -> `billing`, a code-host
+connection -> `settings#repositories`. Like `review`, the CLI opens it on a terminal and
+only prints it under `--json` or `--no-input`. A question that needs a connection prints its
+`link` ("Connect it here") in `watch` and `answer`.
 
 Exit codes: 0 done, 1 failed/reverted/cancelled, 2 usage or no project, 3 needs you,
 4 live but unverified, 5 auth/scope/plan, 6 `--timeout` reached, 7 service
@@ -58,6 +92,9 @@ unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 - `src/openapi.js`: the live `/openapi.json` (cached 24h per host in `$XDG_CACHE_HOME/syndai`).
 - `src/api.js`: `syndai api` (operations by id, fields, `--paginate`).
 - `src/schedules.js`: `schedule` and `repeat` (the preset to cron mapping of `apps/portal-v2/src/lib/cadence.ts`).
+- `src/secrets.js`: `env`, `secrets` and `run` (environment choice, the production step-up retry).
+- `src/dotenv.js`: the `.env` reader (`import`) and writer (`download`); errors name lines, never values.
+- `src/portal.js`: `connect` and `billing`, the hand-offs to a workspace page.
 - `src/changes.js`, `src/settings.js`, `src/mcp.js`: the other commands.
 
 ## Development
@@ -71,7 +108,8 @@ CI runs it in its own **CLI Checks** job (`pr-ci.yml`, `main-ci.yml`) whenever
 part of **PR Gate** and deploys nothing.
 
 The suite runs a fake API on 127.0.0.1 (serving `/openapi.json` from the snapshot) and
-drives the CLI in-process (plus two child-process tests for Ctrl-C and a clean exit).
+drives the CLI in-process (plus child-process tests for Ctrl-C, a clean exit and `run`'s
+real child). `test/secrets.test.js` searches every output and request for a sentinel value.
 `test/schedule.test.js` imports `apps/portal-v2/src/lib/cadence.ts` to prove the
 `--every` presets give the portal's cron; that needs a Node that strips TypeScript
 types (23.6+, as `.nvmrc`), and is skipped on Node 22. `test/contract.test.js` checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndai",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "The Syndai owner CLI: say what to change, and Syndai builds it, checks it and puts it live. Also installs the Syndai MCP server into Claude Code, Cursor and Codex.",
   "type": "module",
   "bin": {

package/src/auth.js

@@ -4,6 +4,10 @@
 // owner or admin approves the request in a browser session at app.syndai.ai/cli. The key is
 // stored per workspace in credentials.json (0600). `SYNDAI_API_KEY` wins over it (CI).
 // There is no --api-key flag, so a key never lands in shell history.
+//
+// Reading secret values needs `coding:secrets:reveal`, which only this browser approval
+// grants. Production values also need a person to allow THIS key in the browser, for 10
+// minutes (`productionStepUp`); a stored key alone, or SYNDAI_API_KEY, never reads them.
 
 import { hostname } from "node:os";
 import { ApiError, CliError, EXIT, explain, PORTAL_URL, steppable } from "./errors.js";
@@ -82,6 +86,9 @@ export function createContext(io, flags, { stepUp = true } = {}) {
   return ctx;
 }
 
+/** One approval for every `syndai secrets` / `env` / `run` command, not one per scope. */
+export const SECRETS_SCOPES = ["coding:secrets:read", "coding:secrets:write", "coding:secrets:reveal"];
+
 /**
  * A 403 named the scope it needs. On a terminal, with the stored login (never
  * SYNDAI_API_KEY, which belongs to CI), ask once, approve a key with the current scopes plus
@@ -90,9 +97,11 @@ export function createContext(io, flags, { stepUp = true } = {}) {
 async function stepUpScope(ctx, scope) {
   const { io, ui } = ctx;
   if (!ui.interactive || !steppable(scope) || ctx.credential().source === "SYNDAI_API_KEY") return false;
-  const answer = await ask(io, `This needs the ${scope} scope. Approve it in your browser? [Y/n] `);
+  const secrets = SECRETS_SCOPES.includes(scope);
+  const what = secrets ? "access to this workspace's secrets" : `the ${scope} scope`;
+  const answer = await ask(io, `This needs ${what}. Approve it in your browser? [Y/n] `);
   if (/^n/i.test(answer)) return false;
-  const token = await deviceApproval(ctx, "CLI", await scopesWith(ctx, [scope]));
+  const token = await deviceApproval(ctx, "CLI", await scopesWith(ctx, secrets ? SECRETS_SCOPES : [scope]));
   await storeKey(ctx, token);
   return true;
 }
@@ -136,14 +145,53 @@ async function storeKey(ctx, token) {
  * Ask for a key and wait until an owner approves it in the browser. Returns the token
  * response `{api_key, customer_id, key_id, expires_at}`.
  */
-export async function deviceApproval(ctx, clientName, scopes) {
-  const { client, ui, io } = ctx;
-  const start = await client.call("deviceStart", {
+export function deviceApproval(ctx, clientName, scopes) {
+  return browserApproval(ctx, {
+    start: "deviceStart",
+    token: "deviceToken",
     // No `scopes` means the owner preset (owner_door); a list asks for those on top of it.
     body: { client_name: clientName, host: hostname(), ...(scopes ? { scopes } : {}) },
     auth: false,
-    retry: true,
+    again: "syndai login",
   });
+}
+
+/**
+ * A production value was refused (403 PRODUCTION_STEP_UP_REQUIRED). On a terminal with the
+ * stored login (never SYNDAI_API_KEY), ask once, wait for a person to allow THIS key in the
+ * browser, and answer true so the caller retries once. Off a terminal: false (exit 3).
+ */
+export async function productionStepUp(ctx) {
+  const { io, ui } = ctx;
+  if (!ui.interactive || ctx.credential().source === "SYNDAI_API_KEY") return false;
+  const answer = await ask(io, "Production values need your approval in the browser for this command. Open it? [Y/n] ");
+  if (/^n/i.test(answer)) return false;
+  let grant;
+  const allowed = await browserApproval(ctx, {
+    start: "startProductionAccess",
+    token: "redeemProductionAccess",
+    body: { client_name: "CLI", host: hostname() },
+    auth: true,
+    again: "run the command again",
+    onStart: (start) => {
+      grant = start.device_code;
+    },
+  });
+  const until = new Date(allowed.allowed_until).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  ui.progress(`Production values allowed for this command (until ${until}).`);
+  // The grant lives in this process only: another process with the same stored key has none.
+  return grant;
+}
+
+/**
+ * The RFC 8628 loop both approvals share: start, show the code and open the page, poll the
+ * token route until a person decides. `auth` sends the stored key (the production step-up
+ * is for the key that asks); `again` is the command a denied or expired code points to.
+ */
+async function browserApproval(ctx, { start: startRoute, token: tokenRoute, body, auth, again, onStart }) {
+  const { client, ui, io } = ctx;
+  const start = await client.call(startRoute, { body, auth, retry: true });
+  onStart?.(start);
   const url = start.verification_uri_complete ?? start.verification_uri;
   ui.progress(`Your one-time code: ${ui.bold(start.user_code)}`);
   ui.progress(`Approve it in your browser: ${url}`);
@@ -159,9 +207,9 @@ export async function deviceApproval(ctx, clientName, scopes) {
       if (io.signal.aborted) throw interrupted();
       throw err;
     }
-    const res = await client.call("deviceToken", {
+    const res = await client.call(tokenRoute, {
       body: { device_code: start.device_code },
-      auth: false,
+      auth,
       retry: true,
       raw: true,
     });
@@ -173,14 +221,10 @@ export async function deviceApproval(ctx, clientName, scopes) {
       continue;
     }
     if (error === "access_denied") {
-      throw new CliError(EXIT.AUTH, "The request was denied in the browser.", {
-        next: "syndai login",
-      });
+      throw new CliError(EXIT.AUTH, "The request was denied in the browser.", { next: again });
     }
     if (error === "expired_token" || error === "authorization_pending") {
-      throw new CliError(EXIT.AUTH, "The code expired before it was approved.", {
-        next: "syndai login",
-      });
+      throw new CliError(EXIT.AUTH, "The code expired before it was approved.", { next: again });
     }
     throw new ApiError(res.status, res.body, res.headers);
   }
@@ -216,6 +260,50 @@ export async function login(ctx) {
   return EXIT.OK;
 }
 
+export const TERMS_URL = "https://syndai.ai/legal/terms";
+export const PRIVACY_URL = "https://syndai.ai/legal/privacy";
+
+/**
+ * `syndai signup <email> [--code C]`: a new workspace and its key from one emailed code
+ * (no browser). Without --code it mails a code and reads it from the prompt; off a terminal it
+ * stops there and names the rerun. With --code it only verifies: mailing again would replace
+ * the code being typed. The key is stored exactly as `login` stores it.
+ */
+export async function signup(ctx, [email]) {
+  const { io, ui, flags, client } = ctx;
+  if (!email) throw new CliError(EXIT.USAGE, "Which address? syndai signup you@example.com");
+  ui.progress(`Continuing accepts Syndai's Terms (${TERMS_URL}) and Privacy Policy (${PRIVACY_URL}).`);
+  if (ui.interactive && !/^y/i.test(await ask(io, "Continue? [y/N] "))) {
+    throw new CliError(EXIT.FAILED, "Not signed up; nothing was sent.");
+  }
+  let code = flags.code;
+  if (code === undefined) {
+    await client.call("signup", {
+      body: { email, accept_terms: true, client_name: "CLI", host: hostname() },
+      auth: false,
+    });
+    const next = `syndai signup ${email} --code <code>`;
+    if (!ui.interactive) {
+      ui.result({ status: "code_sent", email, next }, `We emailed a 6-digit code to ${email}.`);
+      if (!ui.json) ui.progress(`Next: ${next}`);
+      return EXIT.NEEDS_YOU;
+    }
+    ui.progress(`We emailed a 6-digit code to ${email}.`);
+    code = await ask(io, "Code: ");
+  }
+  const token = await client.call("signupVerify", {
+    body: { email, code: String(code).replace(/\s+/g, "") },
+    auth: false,
+  });
+  await storeKey(ctx, token);
+  if (io.env.SYNDAI_API_KEY) ui.progress(ui.yellow("Note: SYNDAI_API_KEY is set and wins over this login."));
+  ui.result(
+    { customer_id: token.customer_id, key_id: token.key_id, expires_at: token.expires_at, app_url: token.app_url },
+    `Signed up. Your workspace: ${token.app_url}`,
+  );
+  return EXIT.OK;
+}
+
 export async function logout(ctx) {
   const { io, ui, paths } = ctx;
   const stored = storedCredential(io, paths);

package/src/changes.js

@@ -32,9 +32,15 @@ export async function change(ctx, words) {
   const text = words.join(" ").trim();
   if (!text) throw new CliError(EXIT.USAGE, 'Say what to change: syndai change "make the header blue"');
   const timeoutMs = timeoutOf(flags);
+  // --learn is explicit (L10): change prompts carry docs links and the owner's own site.
+  const reference = flags.learn === undefined ? null : productUrlFromText(flags.learn);
+  if (flags.learn !== undefined && !reference)
+    throw new CliError(EXIT.USAGE, `--learn takes a public product URL, like https://cal.com, not ${flags.learn}.`);
+  needReferenceForSignIn(flags, reference);
   const project = await resolveProject(ctx, { app: flags.app });
   const outcome = flags.review ? "opens a pull request for your review" : "goes live when checks pass";
   ui.progress(`Changing ${projectHost(project)} · ${outcome}`);
+  if (reference) ui.progress(`Learning from ${hostOf(reference)}`);
 
   const imageRefs = [];
   for (const file of flags.image ?? []) imageRefs.push(await uploadImage(ctx, file));
@@ -54,11 +60,13 @@ export async function change(ctx, words) {
       coding_repository_id: project.id,
       external_request_id: pending.request_id,
       ...(imageRefs.length ? { image_refs: imageRefs } : {}),
+      ...referenceField(reference, flags["sign-in"]),
       ...(flags.review ? { policy_config: { autonomy: "auto" } } : {}),
     },
   });
   clearPending(paths, pending.request_id);
   ui.progress(ui.dim(`Change ${runId}`));
+  signInHint(ctx, reference);
   if (flags["no-wait"]) {
     return finish(ctx, await getChange(ctx, runId), { exitCode: EXIT.OK, next: `syndai watch ${runId}` });
   }
@@ -80,6 +88,23 @@ export function productUrlFromText(text) {
   return null;
 }
 
+const hostOf = (url) => new URL(url).hostname.replace(/^www\./, "");
+// The typed top-level create-run field (learn-from-a-product L1); `metadata.reference_product` is
+// server-owned and 400s.
+// `sign_in` only when asked, so a public-only request stays byte-identical.
+const referenceField = (url, signIn) =>
+  url ? { reference_product: { kind: "url", value: url, ...(signIn ? { sign_in: true } : {}) } } : {};
+
+/** --sign-in needs a product to sign in to; a usage error before any POST. */
+function needReferenceForSignIn(flags, reference, hint = "--learn <product URL>") {
+  if (flags["sign-in"] && !reference) throw new CliError(EXIT.USAGE, `--sign-in needs ${hint}.`);
+}
+
+/** The owner signs in on the run page themselves (never a password in the terminal). */
+function signInHint({ flags, ui }, reference) {
+  if (flags["sign-in"] && reference) ui.progress(`Sign in to ${hostOf(reference)} on the run page once it asks.`);
+}
+
 /** Build-home parity: start a New project. A product URL in the text makes it "your own version
  * of X" (SPEC-build-your-own D5) unless --no-learn; its feature-pick question is asked inline. */
 export async function newProject(ctx, words) {
@@ -87,10 +112,13 @@ export async function newProject(ctx, words) {
   const text = words.join(" ").trim();
   if (!text) throw new CliError(EXIT.USAGE, 'Say what to build: syndai new "a booking site for my salon"');
   const timeoutMs = timeoutOf(flags);
+  // --no-learn says "don't read that product"; --sign-in says "read it signed in": they conflict.
+  if (flags["no-learn"] && flags["sign-in"]) throw new CliError(EXIT.USAGE, "--sign-in and --no-learn can't be used together: --no-learn skips reading the product, --sign-in reads it signed in. Drop one.");
   const reference = flags["no-learn"] ? null : productUrlFromText(text);
+  needReferenceForSignIn(flags, reference, "a product URL in the text, like https://cal.com");
   ui.progress(
     reference
-      ? `New project · your own version of ${new URL(reference).hostname.replace(/^www\./, "")}`
+      ? `New project · your own version of ${hostOf(reference)}`
       : "New project",
   );
   const pending = findPending(paths, { app: "new", text }) ?? {
@@ -105,11 +133,12 @@ export async function newProject(ctx, words) {
       prompt: text,
       new_repository: { scaffold: "syndai-web" },
       external_request_id: pending.request_id,
-      ...(reference ? { metadata: { reference_product: { kind: "url", value: reference } } } : {}),
+      ...referenceField(reference, flags["sign-in"]),
     },
   });
   clearPending(paths, pending.request_id);
   ui.progress(ui.dim(`Change ${runId}`));
+  signInHint(ctx, reference);
   if (flags["no-wait"]) {
     return finish(ctx, await getChange(ctx, runId), { exitCode: EXIT.OK, next: `syndai watch ${runId}` });
   }

package/src/dotenv.js

@@ -0,0 +1,80 @@
+// `.env` text <-> values, for `syndai secrets import` and `syndai secrets download`.
+//
+// Read: KEY=VALUE lines, an optional `export ` prefix, blank lines and `#` comments, an
+// unquoted value's ` # comment`, 'single quotes' (literal) and "double quotes" (\n \r \t \"
+// \\ escapes); either quote may span lines. A later KEY wins. Errors name the line, never a
+// value or a name: a malformed line may be a pasted secret.
+// Write: one KEY=value per name, sorted, quoted only when the value needs it.
+
+import { CliError, EXIT } from "./errors.js";
+
+/** The server's secret-name grammar (`ENV_NAME_PATTERN`). */
+export const NAME = /^[A-Z][A-Z0-9_]{0,127}$/;
+
+const ESCAPES = { n: "\n", r: "\r", t: "\t", '"': '"', "\\": "\\" };
+
+function bad(lineNo, why) {
+  return new CliError(EXIT.USAGE, `.env line ${lineNo}: ${why}.`);
+}
+
+/** `.env` text -> `[{key_name, value}]` in file order (a repeated name keeps its last value). */
+export function parseDotenv(text) {
+  const lines = String(text).replace(/^/, "").split(/\r?\n/);
+  const values = new Map();
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1;
+    // Only the start is trimmed: a quoted value keeps its trailing spaces.
+    const line = lines[i].trimStart();
+    if (!line.trim() || line.startsWith("#")) continue;
+    const match = /^(?:export\s+)?([^=\s]+)\s*=\s*(.*)$/.exec(line);
+    if (!match) throw bad(lineNo, "expected KEY=VALUE");
+    const [, name, rest] = match;
+    if (!NAME.test(name)) throw bad(lineNo, "a name is uppercase letters, digits and _ (like API_TOKEN)");
+    const quote = rest[0];
+    if (quote !== '"' && quote !== "'") {
+      values.delete(name);
+      values.set(name, rest.replace(/\s+#.*$/, "").trim());
+      continue;
+    }
+    // A quoted value: read on (across lines) to the closing quote.
+    let value = "";
+    let chunk = rest.slice(1);
+    let closed = false;
+    for (;;) {
+      for (let j = 0; j < chunk.length; j++) {
+        const ch = chunk[j];
+        if (quote === '"' && ch === "\\" && j + 1 < chunk.length) {
+          const next = chunk[++j];
+          value += ESCAPES[next] ?? `\\${next}`;
+        } else if (ch === quote) {
+          if (!/^\s*(#.*)?$/.test(chunk.slice(j + 1))) throw bad(i + 1, "text after the closing quote");
+          closed = true;
+          break;
+        } else {
+          value += ch;
+        }
+      }
+      if (closed) break;
+      if (++i >= lines.length) throw bad(lineNo, "a quote is never closed");
+      value += "\n";
+      chunk = lines[i];
+    }
+    values.delete(name);
+    values.set(name, value);
+  }
+  return [...values].map(([key_name, value]) => ({ key_name, value }));
+}
+
+/** `{NAME: value}` -> `.env` text that `parseDotenv` (and dotenv, docker) read back exactly. */
+export function serializeDotenv(values) {
+  return Object.keys(values)
+    .sort()
+    .map((name) => `${name}=${quoted(values[name])}\n`)
+    .join("");
+}
+
+function quoted(value) {
+  if (/^[\w./:@%+,=-]*$/.test(value)) return value;
+  if (!/['\n\r]/.test(value)) return `'${value}'`;
+  return `"${value.replace(/[\\"\n\r\t]/g, (ch) => ({ "\\": "\\\\", '"': '\\"', "\n": "\\n", "\r": "\\r", "\t": "\\t" })[ch])}"`;
+}

package/src/errors.js

@@ -40,9 +40,24 @@ export class ApiError extends Error {
 /** The service did not answer (network error, 5xx or 429) after the retry budget. */
 export class UnavailableError extends Error {}
 
-const BILLING_URL = "https://app.syndai.ai/billing";
 export const PORTAL_URL = "https://app.syndai.ai";
 
+/** A workspace page: `https://app.syndai.ai/w/<id>/<path>` (the portal root without an id). */
+export function portalUrl(customerId, path) {
+  return customerId ? `${PORTAL_URL}/w/${encodeURIComponent(customerId)}/${path}` : PORTAL_URL;
+}
+
+/** The workspace page that fixes each error, so a hint is the exact page, not the portal root. */
+export const PORTAL_PAGES = Object.freeze({
+  PLAN_UPGRADE_REQUIRED: "billing",
+  BUDGET_EXHAUSTED: "billing",
+  QUOTA_EXCEEDED: "billing",
+  INSTALLATION_INCOMPLETE: "settings#repositories",
+  REPO_NOT_BOUND: "settings#repositories",
+  ALREADY_SUBSCRIBED: "billing",
+  PLAN_UNKNOWN: "billing",
+});
+
 /**
  * A scope `syndai login --scope` may add with one browser approval. Members, keys and
  * unpublish stay portal-only: the approval page promises a CLI key never manages members or
@@ -52,7 +67,8 @@ export function steppable(scope) {
   return !/:members:|keys|:unpublish$/.test(scope);
 }
 
-// code -> [exit, sentence, next]. Either may be a function of the problem body.
+// code -> [exit, sentence, next]. Either may be a function of the problem body. A code in
+// PORTAL_PAGES has no `next` here: it is that page of the caller's workspace.
 const KNOWN = {
   INVALID_TOKEN: [EXIT.AUTH, "Your Syndai key is missing, expired or revoked.", "syndai login"],
   INVALID_SCOPE: [
@@ -67,9 +83,9 @@ const KNOWN = {
       !scope ? "syndai login" : steppable(scope) ? `syndai login --scope ${scope}` : PORTAL_URL,
   ],
   ROLE_REQUIRED: [EXIT.AUTH, "Only workspace owners and admins can do that.", null],
-  PLAN_UPGRADE_REQUIRED: [EXIT.AUTH, "Your plan does not include that.", BILLING_URL],
-  BUDGET_EXHAUSTED: [EXIT.AUTH, "This workspace is out of credits.", BILLING_URL],
-  QUOTA_EXCEEDED: [EXIT.AUTH, "This workspace is out of credits for now.", BILLING_URL],
+  PLAN_UPGRADE_REQUIRED: [EXIT.AUTH, "Your plan does not include that.", null],
+  BUDGET_EXHAUSTED: [EXIT.AUTH, "This workspace is out of credits.", null],
+  QUOTA_EXCEEDED: [EXIT.AUTH, "This workspace is out of credits for now.", null],
   CUSTOMER_DISABLED: [EXIT.AUTH, "This workspace is disabled. Contact Syndai support.", null],
   HUMAN_APPROVAL_REQUIRED: [
     EXIT.NEEDS_YOU,
@@ -82,13 +98,14 @@ const KNOWN = {
     null,
   ],
   CLI_UPGRADE_REQUIRED: [EXIT.FAILED, "This version of syndai is too old.", "npx -y syndai@latest"],
-  RUN_CONCURRENCY_LIMIT: [EXIT.FAILED, "Too many changes are running at once.", "syndai status"],
-  REPO_NOT_BOUND: [EXIT.USAGE, "That project is not available to this workspace.", "syndai link"],
-  INSTALLATION_INCOMPLETE: [
-    EXIT.FAILED,
-    "A code-host connection needs finishing in the portal.",
-    "https://app.syndai.ai",
+  PRODUCTION_STEP_UP_REQUIRED: [
+    EXIT.NEEDS_YOU,
+    "Production values need you to allow this command in your browser; a key alone never reads them.",
+    "run it again in a terminal logged in with syndai login",
   ],
+  RUN_CONCURRENCY_LIMIT: [EXIT.FAILED, "Too many changes are running at once.", "syndai status"],
+  REPO_NOT_BOUND: [EXIT.USAGE, "That project is not available to this workspace; connect its repository.", null],
+  INSTALLATION_INCOMPLETE: [EXIT.FAILED, "A code-host connection needs finishing in the portal.", null],
   HITL_REQUEST_SETTLED: [EXIT.FAILED, "That question is already answered or closed.", null],
   RUN_TERMINATED_BEFORE_RESPONSE: [EXIT.FAILED, "The change ended before your answer arrived.", null],
   TEXT_EDIT_REFUSED: [
@@ -102,12 +119,37 @@ const KNOWN = {
     "A change is in flight on this site; edit text once it lands.",
     (p) => (p.run_id ? `syndai watch ${p.run_id}` : "syndai status"),
   ],
+  REFERENCE_PRODUCT_INVALID: [
+    EXIT.USAGE,
+    "That is not a product link to learn from; use its full address, like https://cal.com.",
+    null,
+  ],
+  REFERENCE_PRODUCT_NEEDS_SCAFFOLD: [
+    EXIT.USAGE,
+    "Learning from a product needs a Syndai site project.",
+    null,
+  ],
+  ALREADY_SUBSCRIBED: [EXIT.FAILED, "You're already on a paid plan; change it on the billing page.", null],
+  PLAN_UNKNOWN: [EXIT.USAGE, "That is not a plan you can pick; the plans are on the billing page.", null],
+  PACK_UNKNOWN: [EXIT.USAGE, "No such credit pack.", "syndai billing packs"],
+  // `syndai signup` (problem+json, lowercase codes like the sign-in routes).
+  invalid_email: [EXIT.USAGE, "That is not a valid email address.", null],
+  email_disposable: [EXIT.USAGE, "Use a permanent email address; disposable ones can't sign up.", null],
+  terms_required: [EXIT.USAGE, "Signing up needs the Terms and Privacy Policy accepted.", null],
+  sso_required: [EXIT.AUTH, "This address signs in with its organization's SSO; sign up in the browser.", PORTAL_URL],
+  code_invalid: [
+    EXIT.AUTH,
+    "That code is not right. If you already have a workspace, run `syndai login`.",
+    null,
+  ],
+  code_expired: [EXIT.AUTH, "That code expired or was already used.", "syndai signup <email> (for a new code)"],
+  attempts_exhausted: [EXIT.AUTH, "Too many wrong codes for this address; try again tomorrow.", null],
   NOT_FOUND: [EXIT.FAILED, "Not found.", "syndai status"],
   RATE_LIMITED: [EXIT.UNAVAILABLE, "Syndai is rate-limiting this workspace.", null],
 };
 
-/** Map any thrown error to {exitCode, message, next}. */
-export function explain(err) {
+/** Map any thrown error to {exitCode, message, next}; `customerId` fills a PORTAL_PAGES link. */
+export function explain(err, customerId = null) {
   if (err instanceof CliError) {
     return { exitCode: err.exitCode, message: err.message, next: err.next };
   }
@@ -122,10 +164,11 @@ export function explain(err) {
     const known = err.code ? KNOWN[err.code] : null;
     if (known) {
       const [exitCode, sentence, next] = known;
+      const page = PORTAL_PAGES[err.code];
       return {
         exitCode,
         message: typeof sentence === "function" ? sentence(err.problem) : sentence,
-        next: typeof next === "function" ? next(err.problem) : next,
+        next: page ? portalUrl(customerId, page) : typeof next === "function" ? next(err.problem) : next,
       };
     }
     const auth = err.status === 401 || err.status === 402 || err.status === 403;