syndai 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to the `syndai` npm package. Versions follow semver.
 
+## 0.7.0
+
+Land your own branch, and keep a folder in a project's Knowledge.
+
+- `land [branch] [--app A] [--no-wait]` lands your pushed `people/<you>/<name>` branch on a project
+  Syndai hosts: the same checks, review and landing slot as Syndai's own changes, then it watches
+  the landing. It prints any live work on the same files first. A `people/<you>/t12` branch
+  delivers task t12 when it goes live.
+- `sync <dir> [--app A] [--watch]` keeps a folder (an Obsidian vault, any folder of notes) in
+  the project's Knowledge, where its runs and chat search it. Each sync sends every file's
+  sha256 and pushes only the new or changed ones: text files (`.md`, `.txt`, `.csv`, `.json`,
+  `.yaml` and the like) as their text, any other file by name only. A file deleted here is
+  removed there. Hidden files and folders (`.obsidian/`, `.trash/`, `.git/`), `node_modules/`,
+  symlinks, files over 10 MB and the patterns in `<dir>/.syndaiignore` stay out.
+- `--watch` syncs again a second after the last change, one sync at a time, until Ctrl-C; an
+  edit is searchable within seconds. Only changed files are read again.
+- A paused folder, or a folder of the same name someone else syncs, is refused (exit 1) with the
+  server's sentence. It needs `coding:knowledge:sync` (owners and admins); on a terminal the
+  first sync asks for it in the browser.
+- Picking the project from the git remote now matches `github.com/<owner>/<repo>` built from the
+  project's name. The API no longer sends repo URLs. Versions up to 0.6.0 read those URLs, so
+  they skip this rule and fall through to the only project or the picker.
+
+## 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.

package/README.md

@@ -30,27 +30,33 @@ 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 |
+| `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] [--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 |
-| `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) |
+| `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 |
+| `land [branch] [--app A] [--no-wait]` | on a project Syndai hosts, check, review and land your pushed `people/<you>/<name>` branch (default: the current one) |
+| `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 |
+| `sync <dir> [--app A] [--watch]` | keep a folder (an Obsidian vault) in the project's Knowledge (`coding:knowledge:sync`): see [Folder sync](#folder-sync) |
 | `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) |
 
@@ -65,10 +71,40 @@ portal's key page or `mcp install`. A production environment's values also need
 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
 unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 
+## Folder sync
+
+`syndai sync <dir>` (`src/sync.js`, SPEC-knowledge-sources K6) walks `<dir>`, hashes every
+file and sends the manifest (`compareKnowledgeFolder`, at most 20,000 `{path, sha256}`). The
+server deletes the files missing from it and answers `need`, the paths new or changed; those go
+up through `pushKnowledgeFolderFiles` in batches of at most 500 files and 8 MB, each read again
+so the hash sent matches the bytes. Text suffixes (the server's `TEXT_SUFFIXES`) carry their
+UTF-8 `content`; any other file goes with `content: null` (recorded by name). The folder's name
+is the basename of `<dir>`; paths are `/`-separated and relative to it. Both calls are
+idempotent (a manifest is a compare, a push upserts by path), so they retry like a GET.
+
+Skipped: names starting with `.` (so `.obsidian/`, `.trash/`, `.git/`, `.syndaiignore` itself),
+`node_modules/`, symlinks (never followed), files over 10 MB (left out of the manifest, listed
+as skipped) and `<dir>/.syndaiignore` patterns: one a line, `#` comments, `dir/` for folders,
+a pattern with a `/` anchored at the root, `*`, `?` and `**`; no `!`. A 409 (paused, or another
+person's folder of that name) prints the detail and exits 1; per-file `failed` rows are printed
+and do not change the exit code.
+
+`--watch` keeps `{size, mtimeMs, sha256}` per file, so a re-sync re-reads only what moved (a
+hash taken within 2 s of the mtime is redone, for coarse clocks). `io.watchDir` (`fs.watch`,
+recursive) is the trigger, debounced 1 s, one sync at a time; a stat-only check every 10 s
+catches missed events, and a watcher error falls back to it. An unreachable API is retried
+after 30 s; any other error ends the watch. Ctrl-C exits 130.
+
 ## Layout
 
 - `bin/syndai.js`: the entrypoint; wires SIGINT to an AbortSignal.
@@ -84,6 +120,8 @@ unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 - `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/sync.js`: `sync` (the walk, `.syndaiignore`, manifest and batched push, `--watch`).
 - `src/changes.js`, `src/settings.js`, `src/mcp.js`: the other commands.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndai",
-  "version": "0.5.0",
+  "version": "0.7.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

@@ -260,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

@@ -2,6 +2,7 @@
 // edit-text. Each command is a thin call to one route plus, where there is an outcome to
 // wait for, `watchChange`.
 
+import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
@@ -36,6 +37,7 @@ export async function change(ctx, words) {
   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}`);
@@ -59,12 +61,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),
+      ...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}` });
   }
@@ -89,7 +92,19 @@ export function productUrlFromText(text) {
 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.
-const referenceField = (url) => (url ? { reference_product: { kind: "url", value: url } } : {});
+// `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. */
@@ -98,7 +113,10 @@ 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 ${hostOf(reference)}`
@@ -116,11 +134,12 @@ export async function newProject(ctx, words) {
       prompt: text,
       new_repository: { scaffold: "syndai-web" },
       external_request_id: pending.request_id,
-      ...referenceField(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}` });
   }
@@ -157,6 +176,37 @@ async function uploadImage(ctx, file) {
   return { object_key: stored.object_key, content_type: contentType };
 }
 
+/** `syndai land [branch]`: validate, review and land your pushed people/<you>/<name> branch. */
+export async function land(ctx, [branch]) {
+  const { flags, ui } = ctx;
+  const name = branch ?? currentBranch();
+  if (!name) throw new CliError("Which branch? syndai land people/<you>/<name>", EXIT.USAGE);
+  const project = await resolveProject(ctx, { app: flags.app });
+  const landing = await ctx.client.call("landBranch", {
+    params: { coding_repository_id: project.id },
+    body: { branch: name },
+    retry: true, // one landing per pushed head: a retry answers the same run
+  });
+  ui.progress(ui.dim(`Landing ${name} at ${landing.head_sha.slice(0, 12)}: change ${landing.run_id}`));
+  for (const warning of landing.overlap ?? []) ui.progress(`Heads up: ${warning}`);
+  if (flags["no-wait"]) {
+    return finish(ctx, await getChange(ctx, landing.run_id), {
+      exitCode: EXIT.OK,
+      next: `syndai watch ${landing.run_id}`,
+    });
+  }
+  return watchChange(ctx, landing.run_id, { timeoutMs: timeoutOf(flags) });
+}
+
+function currentBranch() {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" }).trim();
+    return out && out !== "HEAD" ? out : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function watch(ctx, runId) {
   return watchChange(ctx, needRun(runId, "watch"), {
     timeoutMs: timeoutOf(ctx.flags),

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,
@@ -88,12 +104,8 @@ const KNOWN = {
     "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.", "syndai link"],
-  INSTALLATION_INCOMPLETE: [
-    EXIT.FAILED,
-    "A code-host connection needs finishing in the portal.",
-    "https://app.syndai.ai",
-  ],
+  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: [
@@ -117,12 +129,27 @@ const KNOWN = {
     "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 };
   }
@@ -137,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;

package/src/main.js

@@ -2,19 +2,22 @@
 // process I/O as `io`, so tests drive it in-process with a fake server and fake clocks.
 
 import { spawn } from "node:child_process";
+import { watch as watchFs } from "node:fs";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
-import { createContext, login, logout, whoami } from "./auth.js";
-import { answer, cancel, change, editText, goLive, newProject, review, revert, status, watch } from "./changes.js";
-import { CliError, EXIT, explain } from "./errors.js";
+import { createContext, login, logout, signup, whoami } from "./auth.js";
+import { answer, cancel, change, editText, goLive, land, newProject, review, revert, status, watch } from "./changes.js";
+import { ApiError, CliError, EXIT, explain, PORTAL_PAGES } from "./errors.js";
 import { VERSION } from "./http.js";
 import { mcp } from "./mcp.js";
-import { link } from "./projects.js";
+import { billing, connect } from "./portal.js";
+import { link, publish } from "./projects.js";
 import { api } from "./api.js";
 import { repeat, schedule } from "./schedules.js";
 import { env, run, secrets } from "./secrets.js";
 import { settings } from "./settings.js";
-import { closeInput, openBrowser, page } from "./ui.js";
+import { sync } from "./sync.js";
+import { closeInput, openBrowser, openPage, page } from "./ui.js";
 
 const str = { type: "string" };
 const bool = { type: "boolean" };
@@ -22,12 +25,15 @@ const COMMON = { json: bool, "no-input": bool, help: { type: "boolean", short: "
 
 const COMMANDS = {
   change: {
-    usage: 'change "<what>" [--app A] [--review] [--learn URL] [--image F]... [--no-wait] [--timeout D]',
+    usage:
+      'change "<what>" [--app A] [--review] [--learn URL [--sign-in]] [--image F]... [--no-wait] [--timeout D]',
     summary:
-      "Make a change; it goes live when its checks pass (--review: open a PR instead; --learn: pick features to add from a product's public pages).",
+      "Make a change; it goes live when its checks pass (--review: open a PR instead; --learn: pick features to add from a product's public pages).\n" +
+      "      --sign-in: Sign in to the --learn product yourself on the run page first, so the run reads its in-app pages.",
     options: {
       app: str,
       learn: str,
+      "sign-in": bool,
       review: bool,
       image: { type: "string", multiple: true },
       "no-wait": bool,
@@ -37,12 +43,23 @@ const COMMANDS = {
     stepUp: false,
   },
   new: {
-    usage: 'new "<what>" [--no-learn] [--no-wait] [--timeout D]',
-    summary: "Start a new project; a product URL in the text builds your own version of it.",
-    options: { "no-learn": bool, "no-wait": bool, timeout: str },
+    usage: 'new "<what>" [--no-learn | --sign-in] [--no-wait] [--timeout D]',
+    summary:
+      "Start a new project; a product URL in the text builds your own version of it.\n" +
+      "      --sign-in: Sign in to that product yourself on the run page first, so the run reads its in-app pages.",
+    options: { "no-learn": bool, "sign-in": bool, "no-wait": bool, timeout: str },
     run: (ctx, args) => newProject(ctx, args),
     stepUp: false,
   },
+  land: {
+    usage: "land [branch] [--app A] [--no-wait] [--timeout D]",
+    summary:
+      "On a project Syndai hosts: check, review and land your pushed branch (default: the current one, people/<you>/<name>).\n" +
+      "      A branch named for a task (people/<you>/t12) delivers it when the landing goes live.",
+    options: { app: str, "no-wait": bool, timeout: str },
+    run: (ctx, args) => land(ctx, args),
+    stepUp: false,
+  },
   watch: {
     usage: "watch <run> [--timeout D] [--logs]",
     summary: "Follow a change to its outcome (Ctrl-C detaches; the change keeps going).",
@@ -97,10 +114,19 @@ const COMMANDS = {
   login: {
     usage: "login [--with-token] [--scope S]...",
     summary:
-      "Log in by approving this computer in your browser (--scope adds access to the key's; --with-token reads a key from stdin).",
+      "Log in by approving this computer in your browser (--scope adds access to the key's; --with-token reads a key from stdin).\n" +
+      "      No workspace yet? syndai signup <email>",
     options: { "with-token": bool, scope: { type: "string", multiple: true } },
     run: (ctx) => login(ctx),
   },
+  signup: {
+    usage: "signup <email> [--code C]",
+    summary:
+      "Make a workspace and log in with a code emailed to you (continuing accepts the Terms and Privacy Policy).\n" +
+      "      Off a terminal it emails the code and exits 3; rerun with --code.",
+    options: { code: str },
+    run: (ctx, args) => signup(ctx, args),
+  },
   logout: {
     usage: "logout",
     summary: "Revoke and forget the stored key.",
@@ -113,6 +139,26 @@ const COMMANDS = {
     options: {},
     run: (ctx) => whoami(ctx),
   },
+  publish: {
+    usage: "publish [--app A]",
+    summary: "Publish the project as a hosted app (or redeploy it) and print its live URL.",
+    options: { app: str },
+    run: (ctx) => publish(ctx),
+  },
+  connect: {
+    usage: "connect <provider>",
+    summary:
+      "Open the workspace page that connects github, sentry, claude, chatgpt, openrouter, slack or a social account; finish in the browser.",
+    options: {},
+    run: (ctx, args) => connect(ctx, args),
+  },
+  billing: {
+    usage: "billing [--open] | packs | buy <pack> | plan <tier> [--interval month|year] [--country CC] | card | cancel",
+    summary:
+      "Plan and balance; buy and plan open a checkout a person pays in the browser (nothing is charged until then).",
+    options: { open: bool, interval: str, country: str },
+    run: (ctx, args) => billing(ctx, args),
+  },
   link: {
     usage: "link [project] [--env E]",
     summary: "Remember which project (and environment) this directory uses (stored outside the repo).",
@@ -147,6 +193,14 @@ const COMMANDS = {
     options: { app: str },
     run: (ctx, args) => settings(ctx, args),
   },
+  sync: {
+    usage: "sync <dir> [--app A] [--watch]",
+    summary:
+      "Sync a folder (an Obsidian vault) into a project's Knowledge: new and changed files go up, deleted ones are removed;\n" +
+      "      hidden files, node_modules/ and <dir>/.syndaiignore patterns stay out. --watch: keep syncing as files change (Ctrl-C stops).",
+    options: { app: str, watch: bool },
+    run: (ctx, args) => sync(ctx, args),
+  },
   mcp: {
     usage: "mcp install claude|cursor|codex",
     summary: "Add Syndai to an AI coding tool, with its own key.",
@@ -155,8 +209,8 @@ const COMMANDS = {
   },
   schedule: {
     usage:
-      'schedule list [--app A | --all] | show <id> | add "<what>" --every E [--at T] [--tz Z] [--budget USD] [--app A]\n' +
-      "               | edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget USD|none]\n" +
+      'schedule list [--app A | --all] | show <id> | add "<what>" --every E [--at T] [--tz Z] [--budget CREDITS] [--app A]\n' +
+      "               | edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget CREDITS|none]\n" +
       "               | pause | resume | run-now | delete <id> [--yes]",
     summary:
       'A project\'s recurring runs. E: hourly (--at :MM), daily or weekdays (--at HH:MM), weekly (--at "mon HH:MM"), or a 5-field cron.',
@@ -164,7 +218,7 @@ const COMMANDS = {
     run: (ctx, args) => schedule(ctx, args),
   },
   repeat: {
-    usage: "repeat <run> --every E [--at T] [--tz Z] [--budget USD]",
+    usage: "repeat <run> --every E [--at T] [--tz Z] [--budget CREDITS]",
     summary: "Run a change you liked again on a schedule (its first run is the next scheduled time).",
     options: { every: str, at: str, tz: str, budget: str },
     run: (ctx, args) => repeat(ctx, args),
@@ -214,6 +268,12 @@ export function processIo(signal) {
     sleep: (ms, abortSignal) => sleep(ms, undefined, { signal: abortSignal }),
     openUrl: openBrowser,
     page: (text) => page(process, text),
+    /** `syndai sync --watch`: `onChange(file)` for a change anywhere under `dir` (`file` relative, or null); returns `{close}`. */
+    watchDir: (dir, onChange, onError) => {
+      const watcher = watchFs(dir, { recursive: true }, (_event, file) => onChange(file ? String(file) : null));
+      watcher.on("error", onError);
+      return watcher;
+    },
     /**
      * `syndai run`: the child shares the terminal; resolves `{code, signal}` (ENOENT rejects).
      * While it runs the parent never exits first (that would orphan a child holding the
@@ -276,7 +336,7 @@ export async function main(argv, io) {
   try {
     return await spec.run(ctx, child ?? parsed.positionals);
   } catch (err) {
-    return report(ctx, err);
+    return await report(ctx, err);
   } finally {
     closeInput(io);
   }
@@ -298,10 +358,14 @@ function splitCommand(args, options) {
   return [args, []];
 }
 
-/** One error line (plus the next command) on stderr; a JSON error on stdout for machines. */
-function report(ctx, err) {
+/**
+ * One error line (plus the next command) on stderr; a JSON error on stdout for machines. An
+ * error a workspace page fixes (billing, GitHub) names that page, opened on a terminal.
+ */
+async function report(ctx, err) {
   const { ui, io } = ctx;
-  const { exitCode, message, next } = explain(err);
+  const page = err instanceof ApiError ? PORTAL_PAGES[err.code] : null;
+  const { exitCode, message, next } = explain(err, page ? await ctx.customerId().catch(() => null) : null);
   if (io.env.SYNDAI_DEBUG && err?.stack) io.stderr.write(`${err.stack}\n`);
   const extra = err instanceof CliError ? err.result : null;
   if (exitCode === EXIT.INTERRUPTED) {
@@ -317,5 +381,6 @@ function report(ctx, err) {
     }
   }
   if (next) ui.progress(`  next: ${next}`);
+  if (page) openPage(ctx, next);
   return exitCode;
 }