parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/cli.py

@@ -0,0 +1,1667 @@
+"""`parse` CLI — `sync`, `login`, `whoami`, `list`, `doctor`, `add`, `remove`.
+
+`parse sync` is the load-bearing command: hits the `/sdk/schemas`
+endpoint, renders a real `.py` per resource-modeled API into
+`./parse_apis/<slug>/__init__.py`. APIs without a `resources` block are
+skipped with a warning (hard-cutover SDK).
+
+A repo curates which APIs it syncs via the declarative `[tool.parse]` table in
+its pyproject (see `parse_sdk._project`): `parse add`/`remove` edit `apis` and
+reconcile; `parse sync` reconciles the generated tree to that committed,
+reproducible set. An absent `apis` key means "all your account APIs".
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+import urllib.parse
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # 3.10 — tomllib landed in 3.11; tomli is its backport
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional, Tuple
+
+import click
+
+if TYPE_CHECKING:
+    # httpx is imported lazily (function-local in _fetch_schemas + a module
+    # __getattr__ for `cli.httpx`): it costs ~32-35 ms to import — ~84% of the
+    # CLI's non-interpreter cold start — yet only `sync` uses it for transport.
+    # See plan 003. Kept here so the httpx annotations/uses resolve statically.
+    import httpx
+
+from parse_sdk import __version__, _project, docgen, doctor as doctor_mod, migrate, scaffold
+from parse_sdk.codegen_v2 import CodegenError, render_module, resolve_root_name
+from parse_sdk.scaffold import safe_slug
+from parse_sdk.config import (
+    CANONICAL_HOST, CREDENTIALS_PATH, DEFAULT_BASE_URL, Config,
+    _host_is_trusted, _read_credentials_file, extra_trusted_hosts, read_oauth,
+    resolve, save_oauth_credentials, save_credentials,
+)
+
+# Sync engine (staging / gates / atomic promote) lives in parse_sdk._sync; the
+# names are re-exported here because tests and downstream code reach them as
+# ``cli.<name>`` attributes (the extraction is mechanical, not a rename).
+from parse_sdk._sync import (  # noqa: F401 — re-exported surface
+    MANIFEST_NAME,
+    _find_pin,
+    OWNED_SLUG_FILES,
+    _assign_slugs,
+    _atomic_write_text,
+    _carry_skipped,
+    _example_drop_reason,
+    _load_manifest,
+    _safe_console,
+    _schema_endpoint_names,
+    _schema_modeled,
+    _schema_resources,
+    _schema_resource_names,
+    _slug_dir_differs,
+    _staged_check_failures,
+    _sweep_stale_stages,
+    stage_check_swap,
+)
+
+# The CLI configures no logging, so an engine-side ``logger.warning`` (e.g.
+# codegen's factory-suppression notice) would hit Python's lastResort handler —
+# raw, unstyled stderr on every render, duplicating the slugged CLI warning
+# channel. A NullHandler marks the tree "handled" without consuming records:
+# propagation is unaffected, so library consumers with real logging configs
+# still receive engine warnings.
+logging.getLogger("parse_sdk").addHandler(logging.NullHandler())
+
+
+def __getattr__(name: str):
+    """Lazily expose ``httpx`` as a module attribute (PEP 562).
+
+    httpx is no longer imported at module top (it cost ~32-35 ms on every
+    `parse` invocation; only `sync` uses it for transport — see plan 003). Tests
+    patch transport via ``monkeypatch.setattr(cli.httpx, "get", ...)``, which
+    needs ``cli.httpx`` to resolve to the real module; this returns the
+    ``sys.modules`` httpx, so a patch on it is seen by the function-local
+    ``import httpx`` in ``_fetch_schemas``."""
+    if name == "httpx":
+        import httpx
+        return httpx
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def _fetch_schemas(cfg: Config) -> list:
+    """Fetch ``/sdk/schemas`` for the resolved config.
+
+    Takes the whole ``Config`` (not a raw key + url pair) so the key↔host
+    binding is structural: ``require_key()`` is the single emit chokepoint and
+    a call site can never pair a key with a different host's URL.
+    """
+    import httpx  # lazy (see plan 003) — sync is the only httpx-transport user
+
+    # auth_headers() raises a RuntimeError (no credential, or an untrusted host)
+    # whose message is already agent-actionable — surface it as a clean colored
+    # error + exit(2), matching the other failure branches, instead of letting it
+    # escape as a raw Click traceback. Returns X-API-Key or a Bearer token.
+    try:
+        auth = cfg.auth_headers()
+    except RuntimeError as e:
+        click.echo(click.style(str(e), fg="red"), err=True)
+        click.echo(click.style(
+            "Run `uv run parse help` for setup, or `uv run parse doctor` to diagnose.",
+            fg="yellow"), err=True)
+        sys.exit(2)
+    url = f"{cfg.base_url}/sdk/schemas"
+    try:
+        r = httpx.get(url, headers=auth, timeout=30.0)
+    except httpx.HTTPError as e:
+        click.echo(click.style(f"Could not reach {cfg.base_url}: {e}", fg="red"), err=True)
+        sys.exit(2)
+    if r.status_code == 401:
+        click.echo(click.style(
+            f"Auth failed against {cfg.base_url}. Run `parse login` or set PARSE_API_KEY.",
+            fg="red"), err=True)
+        sys.exit(2)
+    if r.status_code == 403:
+        click.echo(click.style(
+            f"Your key is valid but not allowed to list schemas on {cfg.base_url} "
+            f"(HTTP 403) — check plan/permissions in Parse.", fg="red"), err=True)
+        sys.exit(2)
+    if r.status_code != 200:
+        click.echo(click.style(f"Schema fetch failed [{r.status_code}]: {_safe_console(r.text)}", fg="red"), err=True)
+        sys.exit(2)
+    try:
+        payload = r.json()
+    except ValueError:  # json.JSONDecodeError ⊂ ValueError — a 200 with a non-JSON body
+        click.echo(click.style(
+            f"Schema fetch returned a 200 with a non-JSON body from {url} "
+            f"(a proxy/gateway page?): {r.text[:200]!r}", fg="red"), err=True)
+        sys.exit(2)
+    if not isinstance(payload, dict):
+        click.echo(click.style(
+            f"Schema fetch returned unexpected JSON from {url} "
+            f"(expected an object, got {type(payload).__name__})", fg="red"), err=True)
+        sys.exit(2)
+    schemas = payload.get("schemas", [])
+    if not isinstance(schemas, list):
+        click.echo(click.style(
+            f"Schema fetch returned unexpected JSON from {url} "
+            f"(expected 'schemas' to be a list, got {type(schemas).__name__})",
+            fg="red"), err=True)
+        sys.exit(2)
+    # Trust-boundary row gate: one malformed server row (non-dict, missing
+    # id/slug) must skip with a warning, never crash the whole command with a
+    # raw KeyError — every downstream consumer (sync, init, list) does raw
+    # row['id']/row['slug'] derefs. Warnings go to STDERR so machine-readable
+    # stdout (--json) stays parseable.
+    valid: list = []
+    for i, row in enumerate(schemas):
+        problem = _valid_schema_row(row)
+        if problem is None:
+            valid.append(row)
+        else:
+            click.echo(click.style(
+                f"    · skipped malformed schema row #{i}: {_safe_console(problem)}",
+                fg="yellow", dim=True), err=True)
+    return valid
+
+
+def _valid_schema_row(row: object) -> Optional[str]:
+    """Why a server schema row is unusable, or ``None`` when well-shaped
+    (a dict whose ``id`` and ``slug`` are non-empty strings)."""
+    if not isinstance(row, dict):
+        return f"expected an object, got {type(row).__name__}"
+    for field in ("id", "slug"):
+        v = row.get(field)
+        if not (isinstance(v, str) and v):
+            return f"missing or non-string {field!r} (got {type(v).__name__})"
+    return None
+
+
+def _http_get_json(cfg: Config, path: str, *, params: Optional[dict] = None,
+                   with_key: bool = True) -> "Tuple[int, object]":
+    """GET ``{base_url}{path}`` → (status, parsed-json|text). Single transport
+    helper for the marketplace/SDK reads beyond ``/sdk/schemas`` (search, detail,
+    versioned schema). ``with_key`` attaches X-API-Key through the host gate
+    (require_key); public marketplace reads pass ``with_key=False``."""
+    import httpx  # lazy (see plan 003)
+
+    headers = {}
+    if with_key:
+        try:
+            headers = cfg.auth_headers()
+        except RuntimeError as e:
+            click.echo(click.style(str(e), fg="red"), err=True)
+            sys.exit(2)
+    try:
+        r = httpx.get(f"{cfg.base_url}{path}", headers=headers, params=params or {}, timeout=30.0)
+    except httpx.HTTPError as e:
+        click.echo(click.style(f"Could not reach {cfg.base_url}: {e}", fg="red"), err=True)
+        sys.exit(2)
+    try:
+        return r.status_code, r.json()
+    except ValueError:
+        return r.status_code, r.text
+
+
+def _fetch_marketplace_schema(cfg: Config, scraper_id: str,
+                              version: Optional[int]) -> Optional[dict]:
+    """Fetch a marketplace canonical's SDK schema (optionally version-pinned),
+    stamped with ``_pinned_version`` so codegen bakes the execution pin. Returns
+    None (with a stderr warning) when the API/version is gone — a stale manifest
+    entry must skip, never abort the whole sync."""
+    path = f"/sdk/schemas/{urllib.parse.quote(scraper_id)}"
+    params = {"version": version} if version is not None else None
+    status, body = _http_get_json(cfg, path, params=params)
+    if status == 200 and isinstance(body, dict):
+        schema = dict(body)
+        if version is not None:
+            schema["_pinned_version"] = version
+        return schema
+    detail = body.get("detail") if isinstance(body, dict) else _safe_console(body)
+    click.echo(click.style(
+        f"    · skipping marketplace API {scraper_id}"
+        f"{f' @v{version}' if version else ''} [{status}]: {_safe_console(detail)}",
+        fg="yellow", dim=True), err=True)
+    return None
+
+
+def _fetch_marketplace_schemas(cfg: Config,
+                               entries: "List[_project.MarketplaceEntry]") -> List[dict]:
+    """All resolvable marketplace schemas for the repo's recorded entries."""
+    out: List[dict] = []
+    for e in entries:
+        s = _fetch_marketplace_schema(cfg, e.scraper_id, e.version)
+        if s is not None:
+            out.append(s)
+    return out
+
+
+# Committed scaffold members inside src/parse_apis that `parse clean` / a payload
+# clean must never remove (mirrors scaffold.write_scaffold's package files).
+_SCAFFOLD_PKG_FILES = frozenset({"__init__.py", "py.typed"})
+
+
+def _render_modules(schemas: List[dict], base_url: str,
+                    *, quiet: bool = False) -> Tuple[List[tuple], List[dict]]:
+    """Render every schema to source, returning (rendered, skipped).
+
+    ``rendered`` is a list of ``(schema, source)``; ``skipped`` is the schemas
+    that produced no module, each carrying a ``_skip_reason``. A CodegenError
+    means a list op reached codegen with no (or an unknown) pagination block —
+    codegen refuses to guess the response shape. Skip that ONE API with a loud
+    warning (its raw HTTP endpoints still work) instead of crashing the whole
+    sync for every other API. ``quiet`` suppresses the stdout skip line (the
+    ``--json`` path carries the reason in the result struct instead); error
+    output on stderr is never suppressed.
+    """
+    rendered: List[tuple] = []
+    skipped: List[dict] = []
+    for s in schemas:
+        try:
+            src = render_module(s, base_url=base_url)
+        except CodegenError as e:
+            if not quiet:
+                click.echo(click.style(
+                    f"    · skipped {_safe_console(s.get('slug'))} ({_safe_console(s.get('id'))}): {_safe_console(e)}",
+                    fg="yellow", dim=True,
+                ))
+            skipped.append({**s, "_skip_reason": f"codegen refused: {e}"})
+            continue
+        except Exception as e:  # noqa: BLE001 — one row must never kill the fleet
+            # Anything other than CodegenError is an ENGINE bug (CodegenError
+            # blames the spec and tells the user to fix it in Parse — wrong
+            # advice for a crash). Distinct wording, stderr, same skip path.
+            click.echo(click.style(
+                f"    · codegen crashed on {_safe_console(s.get('slug'))} "
+                f"({_safe_console(s.get('id'))}): {_safe_console(e)} — engine bug, "
+                f"please report; API skipped this sync",
+                fg="red"), err=True)
+            skipped.append({**s, "_skip_reason": f"codegen crashed: {e}"})
+            continue
+        if src is None:
+            skipped.append({**s, "_skip_reason": "un-modeled (no `resources` in spec)"})
+            continue
+        rendered.append((s, src))
+    return rendered, skipped
+
+
+def _clean_payload(pkg: Path) -> List[Path]:
+    """Remove generated payload from an installed ``src/parse_apis`` package while
+    preserving the committed scaffold (``__init__.py``, ``py.typed``).
+
+    Generated payload = slug directories + ``_manifest.json`` + ``AGENTS.md`` +
+    ``CLAUDE.md`` (anything that is not a scaffold file). Returns removed paths.
+    This is the payload-only operation behind ``parse clean`` and ``parse sync
+    --clean`` — it never touches the package root or scaffold (the old
+    ``--clean`` did ``shutil.rmtree`` on the whole target, a data-loss hazard).
+    """
+    removed: List[Path] = []
+    if not pkg.is_dir():
+        return removed
+    for p in sorted(pkg.iterdir()):
+        if p.name in _SCAFFOLD_PKG_FILES:
+            continue
+        if p.is_dir() and not p.is_symlink():
+            shutil.rmtree(p)
+        else:
+            p.unlink()
+        removed.append(p)
+    return removed
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]},
+             epilog="Run `parse help` for a guided getting-started workflow.")
+@click.version_option(__version__, prog_name="parse")
+def cli() -> None:
+    """Parse SDK CLI. Run `parse init` once to set up the project's parse_apis
+    package, then `parse sync` to refresh your typed clients."""
+
+
+@cli.command("help")
+@click.option("--json", "as_json", is_flag=True,
+              help="Machine-readable orientation (stable, extensible shape).")
+def help_cmd(as_json: bool) -> None:
+    """Guided getting-started workflow: which commands to run, when, and how to authenticate."""
+    from parse_sdk import cli_help
+    click.echo(cli_help.render_overview(cli, as_json=as_json))
+
+
+def _login_web(base_url: Optional[str]) -> None:
+    """Run the browser OAuth flow against the resolved base URL and persist the
+    token. Loopback redirect → the captured token is host-gated on save."""
+    from parse_sdk import _oauth
+
+    target = (base_url or resolve().base_url).rstrip("/")
+    # Refuse an untrusted host UP FRONT — before opening a browser, registering a
+    # client, or running any OAuth round-trip — so nothing is opened or persisted
+    # for a host whose token save_oauth_credentials would reject anyway. (The save
+    # gate still fires as defense-in-depth; this just fails fast and cleanly.)
+    if not _host_is_trusted(target):
+        click.echo(click.style(
+            f"Refusing to log in against {target!r} — it is not a trusted Parse "
+            f"API host. Use https://{CANONICAL_HOST} (the default), a loopback URL, "
+            f"or an opted-in PARSE_EXTRA_TRUSTED_HOSTS host.", fg="red"), err=True)
+        sys.exit(2)
+    try:
+        tokens = _oauth.run_web_login(target)
+    except RuntimeError as e:
+        click.echo(click.style(str(e), fg="red"), err=True)
+        sys.exit(2)
+    except Exception as e:  # noqa: BLE001 — network/JSON/transport failures
+        click.echo(click.style(f"Web login failed against {target}: {e}", fg="red"), err=True)
+        sys.exit(2)
+    try:
+        saved = save_oauth_credentials(
+            access_token=tokens.access_token, refresh_token=tokens.refresh_token,
+            expires_at=tokens.expires_at, client_id=tokens.client_id, base_url=target)
+    except RuntimeError as e:
+        click.echo(click.style(str(e), fg="red"), err=True)
+        sys.exit(2)
+    click.echo(click.style("✓ logged in via browser", fg="green"))
+    click.echo(f"  saved token to {CREDENTIALS_PATH}")
+    click.echo(f"  base_url: {saved}")
+
+
+def _ensure_fresh_token() -> None:
+    """Refresh a stored OAuth token that is at/near expiry, persisting the new
+    one — a no-op for API-key users and for non-expiring/absent tokens. Called at
+    the top of networked CLI commands so `parse sync` keeps working past the 1h
+    access-token lifetime. Best-effort: a failed refresh leaves the old token
+    (the command then surfaces a clean 401)."""
+    from parse_sdk import _oauth
+    import time as _t
+
+    oauth = read_oauth()
+    refresh = oauth.get("refresh_token")
+    if not (isinstance(refresh, str) and refresh):
+        return
+    if not _oauth.is_expiring(oauth.get("expires_at"), now=int(_t.time())):
+        return
+    cfg = resolve()
+    # Refuse to send the (long-lived, high-value) refresh token to an untrusted
+    # host. cfg.base_url comes from PARSE_API_BASE_URL first, so an injected host
+    # would otherwise receive the refresh token via the discovery/token call
+    # before save_oauth_credentials' trust check ever fires (and the best-effort
+    # `except` would swallow it silently). Gate BEFORE any network call.
+    if not _host_is_trusted(cfg.base_url):
+        return
+    try:
+        meta = _oauth.discover(cfg.base_url)
+        token_ep = meta.get("token_endpoint")
+        if not isinstance(token_ep, str):
+            return
+        ts = _oauth.refresh_access_token(token_ep, refresh_token=refresh,
+                                         client_id=oauth.get("client_id"))
+        save_oauth_credentials(
+            access_token=ts.access_token, refresh_token=ts.refresh_token,
+            expires_at=ts.expires_at, client_id=ts.client_id, base_url=cfg.base_url)
+    except Exception:  # noqa: BLE001 — refresh is best-effort; old token still tried
+        return
+
+
+def _net_resolve() -> Config:
+    """resolve() for a command that makes authenticated network calls — refreshes
+    an expiring web-login token first so the request carries a live Bearer."""
+    _ensure_fresh_token()
+    return resolve()
+
+
+def _prompt_key_or_exit() -> str:
+    """Interactive API-key prompt that is SAFE non-interactively: when stdin is
+    not a TTY (agents / CI), emit the actionable setup message and exit 2 instead
+    of a getpass that hangs or aborts opaquely."""
+    if not sys.stdin.isatty():
+        click.echo(click.style(
+            "No Parse API key found. Set PARSE_API_KEY, run `uv run parse login` "
+            "(or `uv run parse login --web`), or pass `--api-key`. "
+            "Run `uv run parse help` for setup.", fg="red"), err=True)
+        sys.exit(2)
+    return click.prompt("Parse API key", hide_input=True)
+
+
+def _stdin_is_interactive() -> bool:
+    """True when a human is at the terminal to complete a browser flow / answer a
+    prompt. False under CI/agents (or a closed stdin) so callers fail fast with
+    guidance instead of hanging on a callback that never arrives."""
+    try:
+        return sys.stdin.isatty()
+    except (ValueError, OSError):
+        return False
+
+
+@cli.command()
+@click.option("--api-key", help="Log in with an API key instead of the browser. "
+                                 "Saved to ~/.config/parse/credentials.")
+@click.option("--web/--no-web", "web", default=None,
+              help="Browser (OAuth) login [default], or --no-web to use an API key.")
+@click.option("--base-url", help=f"Override the Parse base URL (default: {DEFAULT_BASE_URL}).")
+def login(api_key: Optional[str], web: Optional[bool], base_url: Optional[str]) -> None:
+    """Stash credentials so future commands work without env vars.
+
+    Default: open the browser, log in to Parse, and store the resulting OAuth
+    token (auto-refreshed). Use --api-key (or --no-web) to log in with an API key
+    instead.
+    """
+    if web is True and api_key:
+        click.echo(click.style("--web and --api-key are mutually exclusive.", fg="red"), err=True)
+        sys.exit(2)
+    # Browser OAuth is the default; an explicit --api-key or --no-web switches to
+    # API-key login (which prompts when no key value is supplied).
+    want_web = web if web is not None else (api_key is None)
+    # The browser flow needs a human at the terminal; default to it only when one
+    # is present (explicit --web, or an interactive TTY). Non-interactively
+    # (CI/agents) fall through to the key path, which fails fast with guidance
+    # rather than hanging on a callback that never arrives.
+    if want_web and (web is True or _stdin_is_interactive()):
+        _login_web(base_url)
+        return
+    if not api_key:
+        api_key = _prompt_key_or_exit()
+    try:
+        saved_base_url = save_credentials(api_key=api_key, base_url=base_url)
+    except RuntimeError as e:
+        click.echo(click.style(str(e), fg="red"), err=True)
+        sys.exit(2)
+    click.echo(f"Saved credentials to {CREDENTIALS_PATH}")
+    click.echo(f"  base_url: {saved_base_url}")
+    # Transparency: if this host is trusted ONLY because the user opted it in via
+    # PARSE_EXTRA_TRUSTED_HOSTS (not the canonical prod host / loopback), say so —
+    # the key now rides to a non-prod host, which is intended for staging QA only.
+    saved_host = (urllib.parse.urlsplit(saved_base_url).hostname or "").rstrip(".")
+    if saved_host in extra_trusted_hosts():
+        click.echo(click.style(
+            f"  note: {saved_host} is trusted only via PARSE_EXTRA_TRUSTED_HOSTS "
+            f"(staging/preview QA). Unset it for production.", fg="yellow"))
+
+
+def _mask_key(key: str) -> str:
+    # Non-overlapping mask: prefix+suffix only when they can't reconstruct the
+    # key (an 8-char key under [:6]…[-4:] leaked ALL its characters).
+    return f"{key[:4]}…{key[-4:]}" if len(key) >= 12 else "<set, hidden>"
+
+
+@cli.command()
+@click.option("--json", "as_json", is_flag=True,
+              help="Machine-readable output (stable shape; agents should prefer this).")
+def whoami(as_json: bool) -> None:
+    """Show which key + base URL the SDK is currently configured with."""
+    cfg = resolve()
+    key_configured = bool(
+        cfg.api_key
+        or os.environ.get("PARSE_API_KEY")
+        or _read_credentials_file().get("api_key")
+    )
+    web_token_stored = bool(read_oauth().get("access_token"))
+    # The credential that would actually ride to this host: key first, else token.
+    auth_method = "api_key" if cfg.api_key else ("oauth" if cfg.access_token else None)
+    if as_json:
+        # Stable JSON shape (documented in README): base_url, the masked key
+        # (null when unset/withheld), whether ANY key is configured, whether a
+        # web-login token is stored, and which credential rides to this host.
+        click.echo(json.dumps({
+            "base_url": cfg.base_url,
+            "api_key_masked": _mask_key(cfg.api_key) if cfg.api_key else None,
+            "key_configured": key_configured,
+            "key_sent_to_host": bool(cfg.api_key),
+            "web_login": web_token_stored,
+            "auth_method": auth_method,
+        }, indent=2, sort_keys=True))
+        return
+    key_summary = _mask_key(cfg.api_key) if cfg.api_key else "<unset>"
+    click.echo(f"base_url: {cfg.base_url}")
+    click.echo(f"api_key:  {key_summary}")
+    if web_token_stored:
+        click.echo(f"web login: {'active (token rides to this host)' if cfg.access_token else 'stored (withheld on this host)'}")
+    if not cfg.api_key and not cfg.access_token and (key_configured or web_token_stored):
+        click.echo(click.style(
+            "  a credential IS configured but withheld: this base_url's host is not "
+            "trusted to receive it (credentials ride only to https://api.parse.bot, "
+            "loopback, or a host in PARSE_EXTRA_TRUSTED_HOSTS). Unset "
+            "PARSE_API_BASE_URL, run `parse login`, or — for staging QA — set "
+            "PARSE_EXTRA_TRUSTED_HOSTS.", fg="yellow"))
+
+
+@cli.command("list")
+@click.option("--json", "as_json", is_flag=True,
+              help="Machine-readable output (stable shape; agents should prefer this).")
+@click.option("--long", "long_", is_flag=True,
+              help="Verbose per-API blocks (name, endpoint names, resources).")
+def list_cmd(as_json: bool, long_: bool) -> None:
+    """Print the APIs the current key can call (without generating modules)."""
+    cfg = _net_resolve()
+    schemas = _fetch_schemas(cfg)
+    if as_json:
+        # Stable JSON shape (documented in README) — json.dumps escapes any
+        # control characters, so no console sanitization is needed here.
+        click.echo(json.dumps([{
+            "id": s.get("id"),
+            "slug": s.get("slug"),
+            "name": s.get("name"),
+            "modeled": _schema_modeled(s),
+            "endpoints": _schema_endpoint_names(s),
+            "resources": _schema_resource_names(s),
+        } for s in schemas], indent=2, sort_keys=True))
+        return
+    if not schemas:
+        click.echo("No APIs found for this key.")
+        return
+    if long_:
+        for s in schemas:
+            modeled = _schema_modeled(s)
+            marker = click.style("[SDK]", fg="green") if modeled else click.style("[raw]", fg="yellow", dim=True)
+            click.echo(f"  {marker} {click.style(_safe_console(s['slug']), fg='cyan')}  {_safe_console(s['id'])}")
+            click.echo(f"        name:      {_safe_console(s.get('name'))}")
+            eps = ", ".join(_safe_console(name) for name in _schema_endpoint_names(s))
+            click.echo(f"        endpoints: {eps or '(none)'}")
+            if modeled:
+                res = ", ".join(_safe_console(k) for k in _schema_resource_names(s))
+                click.echo(f"        resources: {res}")
+        return
+    # Compact default: one sorted row per API + a summary line. The example
+    # column is SHIPPED-ness — the same render_example + drop-reason
+    # chokepoints sync runs — not payload presence: the live example-less
+    # APIs were DROPS of present examples, which a presence column would
+    # show as ✓ on exactly the motivating cases.
+    with_examples = 0
+    rows = []
+    for s in sorted(schemas, key=lambda x: str(x.get("slug") or "")):
+        # The per-row computation reaches codegen (render_example /
+        # resolve_root_name normalize the schema) — keep it total: one
+        # malformed spec row degrades to a stderr skip, never a crash that
+        # blanks the listing for every healthy API (same per-row isolation
+        # as _render_modules).
+        try:
+            ex = docgen.render_example(s, slug=safe_slug(str(s.get("slug"))))
+            shipped = ex is not None and _example_drop_reason(ex) is None
+            root = resolve_root_name(s)
+        except Exception as e:  # noqa: BLE001 — one row must never kill the list
+            click.echo(click.style(
+                f"    · skipped {_safe_console(s.get('slug'))} "
+                f"({_safe_console(s.get('id'))}): malformed spec "
+                f"({_safe_console(e)})", fg="yellow", dim=True), err=True)
+            continue
+        with_examples += 1 if shipped else 0
+        rows.append((s, root, shipped))
+    for s, root, shipped in rows:
+        n_eps = len(_schema_endpoint_names(s))
+        mark = "example ✓" if shipped else "example –"
+        click.echo(
+            f"  {click.style(_safe_console(s['slug']), fg='cyan')} · "
+            f"{_safe_console(root)} · "
+            f"{n_eps} endpoint{'s' if n_eps != 1 else ''} · {mark}")
+    click.echo(
+        f"{len(rows)} API{'s' if len(rows) != 1 else ''} · "
+        f"{with_examples} with examples")
+
+
+def _resolve_account_slug(selector: str, schemas: List[dict]) -> Optional[str]:
+    """Map a user selector to an account API's SERVER slug, or None.
+
+    Tries exact server-slug, case-insensitive server-slug, exact name, then
+    case-insensitive name. Server slugs (``zillow_com_api``) are the stable
+    handle recorded in ``[tool.parse].apis`` — the assigned on-disk dir slug may
+    be sanitized/de-duped, but the server slug is what `parse list` shows.
+    """
+    by_slug = {s["slug"]: s for s in schemas if isinstance(s.get("slug"), str)}
+    if selector in by_slug:
+        return selector
+    fold = {k.casefold(): k for k in by_slug}
+    if selector.casefold() in fold:
+        return fold[selector.casefold()]
+    for s in schemas:
+        if isinstance(s.get("name"), str) and s["name"] == selector:
+            return s.get("slug")
+    for s in schemas:
+        if isinstance(s.get("name"), str) and s["name"].casefold() == selector.casefold():
+            return s.get("slug")
+    return None
+
+
+def _apply_account_selection(schemas: List[dict],
+                             pcfg: "_project.ProjectConfig") -> Tuple[List[dict], List[str]]:
+    """(selected schemas, missing declared slugs). ``apis is None`` ⇒ all account
+    schemas (the default), no missing."""
+    if pcfg.apis is None:
+        return list(schemas), []
+    by_slug = {s["slug"]: s for s in schemas if isinstance(s.get("slug"), str)}
+    selected: List[dict] = []
+    missing: List[str] = []
+    for slug in pcfg.apis:
+        if slug in by_slug:
+            selected.append(by_slug[slug])
+        else:
+            missing.append(slug)
+    return selected, missing
+
+
+def _installed_account_slugs(project: Path, schemas: List[dict]) -> List[str]:
+    """Server slugs of the account APIs CURRENTLY generated in this repo.
+
+    Used to snapshot the set the first time `add`/`remove` switches a repo from
+    all-account mode to an explicit list, so nothing already present is dropped.
+    Order follows the server response (stable) for a deterministic written list.
+    """
+    manifest = _load_manifest(project / "parse_apis" / "src" / "parse_apis")
+    installed_uuids = set(manifest.keys())
+    return [s["slug"] for s in schemas
+            if isinstance(s.get("slug"), str) and s.get("id") in installed_uuids]
+
+
+def _warn_missing_selection(missing: List[str]) -> None:
+    """Stderr warning per declared-but-absent account slug (stdout stays clean
+    for --json consumers)."""
+    for slug in missing:
+        click.echo(click.style(
+            f"    · declared API {slug!r} is not in your account — skipping "
+            f"(run `parse list` for available slugs)", fg="yellow", dim=True), err=True)
+
+
+def _gather_desired_schemas(
+    cfg: Config, account_schemas: List[dict], pcfg: "_project.ProjectConfig",
+) -> Tuple[List[dict], List[str]]:
+    """The full schema set this repo should generate: the account selection
+    (`[tool.parse].apis`) PLUS every recorded `[[tool.parse.marketplace]]`
+    canonical (version-pinned, `_pinned_version`-stamped). Returns
+    (schemas, account_missing). Marketplace fetch failures skip with a warning
+    inside `_fetch_marketplace_schemas`."""
+    selected, missing = _apply_account_selection(account_schemas, pcfg)
+    _warn_missing_selection(missing)
+    if pcfg.marketplace:
+        selected = selected + _fetch_marketplace_schemas(cfg, pcfg.marketplace)
+    return selected, missing
+
+
+@cli.command()
+@click.option(
+    "--clean", is_flag=True,
+    help="Remove generated payload before regenerating (keeps the committed scaffold).",
+)
+@click.option(
+    "--check", "check", is_flag=True,
+    help="CI dry run: fetch, render, and run every promotion gate with NO "
+         "promote — print per-slug diff markers and findings, then exit 1 on "
+         "any finding (including would-be-quarantined APIs and a missing "
+         "parse-sdk pin). Requires an initialized project, same as a real sync.",
+)
+@click.option(
+    "--json", "as_json", is_flag=True,
+    help="Machine-readable result on stdout (stable shape; agents should "
+         "prefer this). Composes with --check. Errors still go to stderr.",
+)
+def sync(clean: bool, check: bool, as_json: bool) -> None:
+    """Fetch your APIs' schemas and write typed Python modules.
+
+    Target is the initialized project's `parse_apis/src/parse_apis` package
+    (run `parse init` first). Generated payload is staged, self-tested, and
+    promoted atomically — a failed sync never leaves broken or secret-bearing
+    files in your project.
+
+    APIs without a `resources` block (the agent didn't model them yet)
+    are skipped with a warning — they still work via raw HTTP through
+    the executor.
+    """
+    # Init precondition BEFORE any network round-trip; reuse the resolved
+    # paths for the reconcile + the staged swap so the check runs exactly once.
+    project, root, pkg = _require_generated_package()
+    cfg = _net_resolve()
+    schemas = _fetch_schemas(cfg)
+    if not schemas:
+        if as_json:
+            click.echo(json.dumps({"written": [], "skipped": [], "removed": [],
+                                   "quarantined": [], "failures": []},
+                                  indent=2, sort_keys=True))
+        else:
+            click.echo("No APIs found for this key.")
+        return
+    # Reconcile to the repo's declared set (`[tool.parse].apis` + marketplace):
+    # an absent apis key means all account APIs (unchanged behavior); an explicit
+    # list narrows it; recorded marketplace canonicals are added version-pinned.
+    consumer = project / "pyproject.toml"
+    pcfg = (_project.read_project_config(consumer) if consumer.exists()
+            else _project.ProjectConfig())
+    selected, _missing = _gather_desired_schemas(cfg, schemas, pcfg)
+    # Wipe-guard: refuse when the repo DECLARES a curated set (account slugs
+    # and/or marketplace canonicals) but every one is unresolvable. `pcfg.apis`
+    # alone misses the marketplace-only case (apis == [] / None with
+    # `[[tool.parse.marketplace]]` entries that all fail to resolve), which would
+    # otherwise prune every generated client. `declared_any` covers both axes.
+    declared_any = bool(pcfg.apis) or bool(pcfg.marketplace)
+    if declared_any and not selected:
+        click.echo(click.style(
+            "Refusing to sync: every API in [tool.parse] is unresolvable "
+            "(missing from your account / marketplace), which would prune all "
+            "generated clients. Fix the list (`parse list` shows valid slugs) or "
+            "remove the [tool.parse] table to track all account APIs.", fg="red"), err=True)
+        sys.exit(2)
+    _sync_installed(cfg, selected, clean=clean, check=check, as_json=as_json,
+                    _pkg_paths=(project, root, pkg))
+
+
+@cli.command()
+def clean() -> None:
+    """Remove generated payload from parse_apis, keeping the committed scaffold.
+
+    Payload-only — replaces the old destructive `parse sync --clean` (which
+    `rmtree`'d the whole tree). Never touches `__init__.py`, `py.typed`, or the
+    package `pyproject.toml`.
+    """
+    project = _find_project_root()
+    root = project / "parse_apis"
+    pkg = root / "src" / "parse_apis"
+    if not (pkg / "__init__.py").exists():
+        hint = _interrupted_promote_hint(root)
+        click.echo(click.style(
+            "No initialized `parse_apis` package found (searched this directory "
+            "and its parents). Run `parse init` first.",
+            fg="red"), err=True)
+        if hint:
+            click.echo(click.style(hint, fg="yellow"), err=True)
+        sys.exit(2)
+    _guard_target_project(project, command="clean")
+    removed = _clean_payload(pkg)
+    if removed:
+        for p in removed:
+            click.echo(click.style(f"    · removed {p.name}", fg="yellow", dim=True))
+        click.echo(
+            f"✓ cleaned {len(removed)} generated item"
+            f"{'s' if len(removed) != 1 else ''} (scaffold kept)")
+    else:
+        click.echo("Nothing to clean — no generated payload.")
+
+
+def _require_initialized_consumer(command: str) -> Tuple[Path, Path]:
+    """(project root, consumer pyproject) for a command that mutates the repo's
+    declared API set — exits 2 with the init hint when not initialized."""
+    project = _find_project_root()
+    consumer = project / "pyproject.toml"
+    pkg_init = project / "parse_apis" / "src" / "parse_apis" / "__init__.py"
+    if not (consumer.exists() and pkg_init.exists()):
+        click.echo(click.style(
+            "No initialized parse_apis project here (searched this directory and "
+            "its parents). Run `parse init` first.", fg="red"), err=True)
+        sys.exit(2)
+    _guard_target_project(project, command=command)
+    return project, consumer
+
+
+def _require_generated_package(command: str = "sync") -> Tuple[Path, Path, Path]:
+    """(project, ``parse_apis`` root, ``src/parse_apis`` pkg) for a command that
+    operates on the GENERATED payload. Exits 2 with the init hint — plus the
+    interrupted-promote recovery hint when a half-promoted tree is detected — and
+    the disjoint-env guard. Distinct from ``_require_initialized_consumer``, which
+    gates repo-mutating commands on the CONSUMER pyproject; this checks the
+    generated scaffold (``parse_apis/pyproject.toml`` + the package ``__init__``).
+    """
+    project = _find_project_root()
+    root = project / "parse_apis"
+    pkg = root / "src" / "parse_apis"
+    if not ((root / "pyproject.toml").exists() and (pkg / "__init__.py").exists()):
+        hint = _interrupted_promote_hint(root)
+        click.echo(click.style(
+            "No initialized `parse_apis` package found (searched this directory "
+            "and its parents). Run `parse init` first "
+            "(expected parse_apis/pyproject.toml and parse_apis/src/parse_apis/__init__.py). "
+            "Run `uv run parse doctor` to diagnose.",
+            fg="red"), err=True)
+        if hint:
+            click.echo(click.style(hint, fg="yellow"), err=True)
+        sys.exit(2)
+    _guard_target_project(project, command=command)
+    return project, root, pkg
+
+
+_UUID_RE = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+                      r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+
+
+def _host_of(url: str) -> str:
+    try:
+        h = (urllib.parse.urlsplit(url if "//" in url else f"//{url}").hostname or "").lower()
+    except ValueError:
+        return ""
+    return h[4:] if h.startswith("www.") else h
+
+
+def _marketplace_detail(cfg: Config, listing_id: str) -> Optional[dict]:
+    status, body = _http_get_json(cfg, f"/marketplace/apis/{urllib.parse.quote(listing_id)}",
+                                  with_key=False)
+    return body if status == 200 and isinstance(body, dict) else None
+
+
+def _marketplace_search(cfg: Config, query: str, *, limit: int = 25) -> List[dict]:
+    status, body = _http_get_json(cfg, "/marketplace/apis",
+                                  params={"q": query, "limit": limit}, with_key=False)
+    if status != 200 or not isinstance(body, dict):
+        return []
+    items = body.get("items")
+    return [it for it in items if isinstance(it, dict)] if isinstance(items, list) else []
+
+
+def _resolve_marketplace_selector(cfg: Config, selector: str) -> Optional[dict]:
+    """Resolve a listing-id / URL / slug / name to a marketplace detail dict
+    (carrying canonical_scraper_id, latest_version, slug, name, source_url,
+    is_authenticated), or None after printing the reason.
+
+    Ambiguity is fail-LOUD, never auto-picked (a broad term matches dozens):
+    prints the candidates and returns None so the caller exits non-zero.
+    """
+    # 1. Direct listing id.
+    if _UUID_RE.match(selector):
+        detail = _marketplace_detail(cfg, selector)
+        if detail:
+            return detail
+        click.echo(click.style(f"No marketplace API with id {selector}.", fg="red"), err=True)
+        return None
+
+    # 2. Search, then disambiguate by exact slug / host / single result.
+    items = _marketplace_search(cfg, selector)
+    if not items:
+        click.echo(click.style(
+            f"No marketplace APIs match {selector!r}. Try `parse search {selector}`.",
+            fg="red"), err=True)
+        return None
+    sel_fold = selector.casefold()
+    sel_host = _host_of(selector)
+    exact = [it for it in items
+             if str(it.get("slug", "")).casefold() == sel_fold
+             or str(it.get("name", "")).casefold() == sel_fold
+             or (sel_host and _host_of(str(it.get("source_url", ""))) == sel_host)]
+    chosen = None
+    if len(exact) == 1:
+        chosen = exact[0]
+    elif len(items) == 1:
+        chosen = items[0]
+    if chosen is None:
+        click.echo(click.style(
+            f"{selector!r} matches {len(items)} marketplace APIs — pick one by "
+            f"listing id or exact slug:", fg="yellow"), err=True)
+        for it in items[:15]:
+            click.echo(click.style(
+                f"    {it.get('slug')}  ·  {it.get('name')}  ·  "
+                f"{it.get('source_url')}  ·  {it.get('id')}", dim=True), err=True)
+        return None
+    detail = _marketplace_detail(cfg, str(chosen.get("id")))
+    if detail is None:
+        click.echo(click.style(
+            f"Couldn't load detail for {chosen.get('slug')} ({chosen.get('id')}).",
+            fg="red"), err=True)
+    return detail
+
+
+def _add_marketplace(cfg: Config, project: Path, consumer: Path,
+                     pcfg: "_project.ProjectConfig", selectors: Tuple[str, ...],
+                     version: Optional[int], as_json: bool) -> None:
+    """Resolve + record marketplace canonicals (version-pinned), then reconcile."""
+    if version is not None and len(selectors) != 1:
+        click.echo(click.style(
+            "--version pins a single API — pass exactly one selector with --version.",
+            fg="red"), err=True)
+        sys.exit(2)
+    # Reject non-positive / non-int (and bool, which is an int subclass) versions
+    # up front — otherwise `--version 0`/`-1` silently degraded to "no pin" with
+    # no signal that the explicit request was dropped.
+    if version is not None and (not isinstance(version, int) or isinstance(version, bool) or version < 1):
+        click.echo(click.style(
+            f"--version must be a positive integer (got {version!r}).", fg="red"), err=True)
+        sys.exit(2)
+
+    # Resolve + validate ALL selectors first, accumulating the entries and their
+    # user-facing output. Nothing is printed and nothing is persisted until every
+    # selector succeeds — otherwise a later failure (sys.exit) would leave the user
+    # staring at an "Added …" line for an entry that was never written to
+    # pyproject.toml.
+    by_sid = {m.scraper_id: m for m in pcfg.marketplace}
+    added: List[str] = []
+    deferred_msgs: List[str] = []
+    for sel in selectors:
+        detail = _resolve_marketplace_selector(cfg, sel)
+        if detail is None:
+            sys.exit(2)
+        sid = detail.get("canonical_scraper_id")
+        if not isinstance(sid, str) or not sid:
+            click.echo(click.style(
+                f"{sel!r} has no canonical scraper id — can't add.", fg="red"), err=True)
+            sys.exit(2)
+        pin = version if version is not None else detail.get("latest_version")
+        pin = pin if isinstance(pin, int) and pin >= 1 else None
+        entry = _project.MarketplaceEntry(
+            scraper_id=sid,
+            # Sanitize to the import-safe form codegen will use on disk (listing
+            # slugs use dashes: `zillow-com-api` → `zillow_com_api`).
+            slug=safe_slug(str(detail.get("slug") or sel)),
+            version=pin,
+            listing_id=str(detail.get("id")) if detail.get("id") else None,
+            source_url=str(detail.get("source_url")) if detail.get("source_url") else None,
+        )
+        by_sid[sid] = entry          # idempotent: re-adding updates the pin
+        added.append(entry.slug)
+        deferred_msgs.append(click.style(
+            f"Added marketplace API {entry.slug}"
+            f"{f' @v{pin}' if pin else ' (latest — no release to pin)'} "
+            f"— shared canonical, pinned and won't change under you.", fg="cyan"))
+        if detail.get("is_authenticated"):
+            deferred_msgs.append(click.style(
+                "    ⚠ this API requires authentication; calls need credentials/login "
+                "and may not work with a plain API key.", fg="yellow"))
+        deferred_msgs.append(click.style(
+            "    To customize it, subscribe + swap to your own clone in the dashboard, "
+            "then `parse add` your clone.", dim=True))
+
+    # Every selector resolved — persist first, then announce, so the "Added …"
+    # output only ever appears for entries that actually made it to disk.
+    pcfg.marketplace = list(by_sid.values())
+    _project.write_project_config(consumer, pcfg)
+    for msg in deferred_msgs:
+        click.echo(msg)
+
+    account_schemas = _fetch_schemas(cfg)
+    selected, _missing = _gather_desired_schemas(cfg, account_schemas, pcfg)
+    if not selected:
+        click.echo(click.style(
+            "Nothing to generate — the added marketplace API(s) returned no "
+            "resolvable schema.", fg="red"), err=True)
+        sys.exit(2)
+    _sync_installed(cfg, selected, clean=False, as_json=as_json)
+
+
+@cli.command()
+@click.argument("query", nargs=-1, required=True)
+@click.option("--limit", type=int, default=15, show_default=True, help="Max results.")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable results on stdout.")
+def search(query: Tuple[str, ...], limit: int, as_json: bool) -> None:
+    """Search the Parse marketplace for ready-made APIs.
+
+    Prints matches with their slug, name, source site, endpoint count, and listing
+    id. Add one with `parse add --marketplace <listing-id|slug>`.
+    """
+    cfg = _net_resolve()
+    q = " ".join(query).strip()
+    items = _marketplace_search(cfg, q, limit=max(1, min(limit, 50)))
+    if as_json:
+        click.echo(json.dumps([{
+            "id": it.get("id"), "slug": it.get("slug"), "name": it.get("name"),
+            "source_url": it.get("source_url"),
+            "endpoint_count": it.get("endpoint_count"),
+            "is_authenticated": it.get("is_authenticated"),
+        } for it in items], indent=2, sort_keys=True))
+        return
+    if not items:
+        click.echo(f"No marketplace APIs match {q!r}.")
+        return
+    for it in items:
+        n = it.get("endpoint_count")
+        auth = " 🔒" if it.get("is_authenticated") else ""
+        click.echo(
+            f"  {click.style(_safe_console(it.get('slug')), fg='cyan')}{auth} · "
+            f"{_safe_console(it.get('name'))} · {_safe_console(it.get('source_url'))} · "
+            f"{n if isinstance(n, int) else '?'} endpoint(s)")
+        click.echo(click.style(f"      add: parse add --marketplace {_safe_console(it.get('id'))}", dim=True))
+    click.echo(f"{len(items)} result{'s' if len(items) != 1 else ''} · "
+               f"add one with `parse add --marketplace <listing-id|slug>`")
+
+
+@cli.command()
+@click.argument("selectors", nargs=-1, required=True)
+@click.option("--marketplace", "-m", "is_marketplace", is_flag=True,
+              help="Treat selectors as MARKETPLACE APIs (listing id / URL / name) to "
+                   "download locally, version-pinned. `parse search` finds them.")
+@click.option("--version", "version", type=int, default=None,
+              help="Pin marketplace API(s) to this release version (default: latest at add time). "
+                   "Only valid with --marketplace and a single selector.")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable sync result on stdout.")
+def add(selectors: Tuple[str, ...], is_marketplace: bool, version: Optional[int],
+        as_json: bool) -> None:
+    """Add APIs to this repo's synced set, then reconcile.
+
+    Account APIs (default): appends server slugs / names to [tool.parse].apis —
+    switching the repo from "all account APIs" to an explicit, reproducible list
+    the first time (snapshotting what is already installed so nothing is dropped).
+
+    Marketplace APIs (--marketplace): downloads a shared canonical's typed client
+    locally, version-pinned, recording it under [[tool.parse.marketplace]]. No
+    subscription is created — the pinned canonical won't change under you; to
+    customize it, subscribe + swap to your clone in the dashboard.
+    """
+    cfg = _net_resolve()
+    project, consumer = _require_initialized_consumer("add")
+    pcfg = _project.read_project_config(consumer)
+
+    if is_marketplace:
+        _add_marketplace(cfg, project, consumer, pcfg, selectors, version, as_json)
+        return
+    if version is not None:
+        click.echo(click.style("--version is only valid with --marketplace.", fg="red"), err=True)
+        sys.exit(2)
+
+    schemas = _fetch_schemas(cfg)
+    resolved: List[str] = []
+    unknown: List[str] = []
+    for sel in selectors:
+        slug = _resolve_account_slug(sel, schemas)
+        (resolved.append(slug) if slug else unknown.append(sel))
+    if unknown:
+        click.echo(click.style(
+            f"Not found in your account APIs: {', '.join(unknown)}. Run "
+            f"`parse list` for valid slugs, or `parse add --marketplace {unknown[0]}` "
+            f"to add a shared marketplace API.", fg="red"), err=True)
+        sys.exit(2)
+
+    switched = pcfg.apis is None
+    base = _installed_account_slugs(project, schemas) if switched else list(pcfg.apis or [])
+    new_apis = list(base)
+    for slug in resolved:
+        if slug not in new_apis:
+            new_apis.append(slug)
+    pcfg.apis = new_apis
+    _project.write_project_config(consumer, pcfg)
+    if switched:
+        click.echo(click.style(
+            f"Switched this repo to an explicit API list (was: all account APIs). "
+            f"Now tracking {len(new_apis)}: {', '.join(new_apis)}", fg="cyan"))
+    else:
+        click.echo(f"Added {', '.join(resolved)} — now tracking {len(new_apis)} API(s).")
+
+    selected, _missing = _gather_desired_schemas(cfg, schemas, pcfg)
+    _sync_installed(cfg, selected, clean=False, as_json=as_json)
+
+
+@cli.command()
+@click.argument("selectors", nargs=-1, required=True)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable sync result on stdout.")
+def remove(selectors: Tuple[str, ...], as_json: bool) -> None:
+    """Stop syncing APIs in this repo: drop them from [tool.parse] and reconcile
+    (their generated clients are pruned).
+
+    Removes both account APIs (from `apis`) and marketplace APIs (matched by
+    slug / scraper id / listing id). If the repo currently tracks all account
+    APIs, this switches it to an explicit list of everything-installed-minus-removed.
+    """
+    cfg = _net_resolve()
+    project, consumer = _require_initialized_consumer("remove")
+    schemas = _fetch_schemas(cfg)
+    pcfg = _project.read_project_config(consumer)
+
+    # Resolve to a server slug when possible, else take the literal (so a stale
+    # entry no longer in the account can still be removed).
+    targets = {(_resolve_account_slug(sel, schemas) or sel) for sel in selectors}
+    base = _installed_account_slugs(project, schemas) if pcfg.apis is None else list(pcfg.apis)
+    new_apis = [s for s in base if s not in targets]
+    removed = [s for s in base if s in targets]
+
+    # Marketplace entries match on slug, scraper_id, or listing_id.
+    kept_mkt, removed_mkt = [], []
+    for m in pcfg.marketplace:
+        if targets & {m.slug, m.scraper_id, m.listing_id or ""}:
+            removed_mkt.append(m.slug)
+        else:
+            kept_mkt.append(m)
+
+    if not removed and not removed_mkt:
+        click.echo(f"Nothing to remove — none of [{', '.join(selectors)}] are tracked.")
+        return
+    pcfg.apis = new_apis
+    pcfg.marketplace = kept_mkt
+    _project.write_project_config(consumer, pcfg)
+    all_removed = removed + removed_mkt
+    click.echo(f"Removed {', '.join(all_removed)} — now tracking "
+               f"{len(new_apis)} account + {len(kept_mkt)} marketplace API(s).")
+
+    selected, _missing = _gather_desired_schemas(cfg, schemas, pcfg)
+    # Wipe-guard (parity with sync): if APIs are still declared (account or
+    # marketplace) but NONE resolve, refuse rather than prune every generated
+    # client. The config edit above stands (it reflects the remove intent); a
+    # later `parse sync` reconciles once the stale entries are fixed. Removing
+    # everything is an intentional empty repo, handled below.
+    declared_any = bool(pcfg.apis) or bool(pcfg.marketplace)
+    if declared_any and not selected:
+        click.echo(click.style(
+            "Not pruning: the remaining declared APIs are all unresolvable (missing "
+            "from your account / marketplace), so syncing would wipe every generated "
+            "client. Fix the stale entries (`parse list` shows valid slugs) or remove "
+            "the [tool.parse] table to track all account APIs, then `parse sync`.",
+            fg="red"), err=True)
+        sys.exit(2)
+    if not declared_any:
+        # Removing the LAST tracked API leaves an empty explicit selection. Do
+        # NOT `_sync_installed(cfg, [], ...)` — that swaps in a scaffold-only
+        # package and wipes every generated client (the old branch
+        # only *commented* "switch back rather than wipe-sync" but had no return).
+        # The config edit stands; the existing generated clients are left in
+        # place. To intentionally clear them, delete the [tool.parse] table (or
+        # the package) — `parse sync` then reconciles to all-account.
+        click.echo(click.style(
+            "    · this repo now tracks no APIs in [tool.parse]. Existing generated "
+            "clients were left untouched (no prune). Remove the [tool.parse] table "
+            "to track all account APIs again, then `parse sync`.",
+            fg="yellow", dim=True))
+        return
+    _sync_installed(cfg, selected, clean=False, as_json=as_json)
+
+
+def _unique_legacy_dir(project: Path) -> Path:
+    """A fresh `.parse/legacy-parse_apis[-N]` path to archive an old flat tree."""
+    base = project / ".parse"
+    base.mkdir(parents=True, exist_ok=True)
+    n = 0
+    while True:
+        candidate = base / ("legacy-parse_apis" if n == 0 else f"legacy-parse_apis-{n}")
+        if not candidate.exists():
+            return candidate
+        n += 1
+
+
+def _append_gitignore(project: Path) -> None:
+    """Append the deny-by-default ignore block to ``.gitignore`` once (idempotent).
+
+    The guard keys on the managed-block marker (its header line), not on a single
+    ignore pattern: a stray ``parse_apis/...`` line elsewhere must not suppress
+    writing the block, which includes the ``!``-re-includes for the committed
+    scaffold (skipping those would over-ignore — leaving the scaffold untracked).
+    """
+    gi = project / ".gitignore"
+    block = scaffold.render_gitignore_block()
+    marker = block.splitlines()[0]
+    existing = gi.read_text() if gi.exists() else ""
+    if marker in existing:
+        return
+    prefix = existing if existing.endswith("\n") or not existing else existing + "\n"
+    gi.write_text(prefix + ("\n" if existing else "") + block)
+
+
+def _interrupted_promote_hint(root: Path) -> Optional[str]:
+    """Recovery hint for a sync that crashed between the two promote renames:
+    the live package dir is gone, but its full prior contents sit in a
+    ``src/.parse_apis.old-*`` sibling (deliberately never swept — it can hold
+    the user's only live copy). Without this, the not-initialized error says
+    'Run `parse init` first', which mis-diagnoses the state and silently
+    orphans the one artifact kept for recovery."""
+    if not (root / "pyproject.toml").exists():
+        return None
+    # `src` can be absent independently of pyproject.toml (manual deletion, a
+    # half-built scaffold). Guard before globbing: this runs in error-recovery
+    # paths (clean/sync) where the tree is already broken, and pathlib's glob
+    # over a missing base is version-dependent (3.13 rewrote the globber) — an
+    # explicit precondition keeps the hint a clean None instead of risking a
+    # traceback that buries the diagnostic.
+    src = root / "src"
+    if not src.is_dir():
+        return None
+    olds = sorted(src.glob(".parse_apis.old-*"))
+    if not olds:
+        return None
+    d = olds[-1]
+    return (
+        f"A previous `parse sync` was interrupted mid-promote; your prior "
+        f"generated payload is intact at {d}.\n"
+        f"Restore it with:  mv {d} {root / 'src' / 'parse_apis'}\n"
+        f"or re-run `parse init` to rebuild the scaffold (then delete {d})."
+    )
+
+
+def _env_implied_project_root() -> Optional[Path]:
+    """The project root implied by the RUNNING interpreter's environment, or
+    None when the interpreter isn't a project venv.
+
+    ``uv run --project X parse …`` selects X's environment while the process
+    CWD stays wherever the shell was — the one signal that survives that split
+    is the interpreter itself: a project venv lives at ``<root>/.venv``.
+    ``VIRTUAL_ENV`` is honored first (matches uv's own resolution); a venv not
+    named ``.venv`` (pipx, ``uv tool``, global installs) yields None — no
+    guard, current behavior.
+    """
+    venv = os.environ.get("VIRTUAL_ENV") or sys.prefix
+    p = Path(venv)
+    if p.name == ".venv" and p.is_dir():
+        return p.parent.resolve()
+    return None
+
+
+def _guard_target_project(target: Path, *, command: str) -> None:
+    """Exit 2 when the target project and the env-implied root are DISJOINT.
+
+    The wrong-target shape this blocks: a user runs
+    ``uv run --project X parse init`` from an unrelated repo — init targets
+    CWD, which qualifies on its own (it has a pyproject.toml), and silently
+    mutates the WRONG project (archives its flat ``parse_apis/``, edits its
+    tracked pyproject/.gitignore). Containment, not equality: a target that IS
+    the env root or a DESCENDANT of it is allowed — uv workspaces share one
+    root ``.venv``, so member-directory work under the workspace root is a
+    legitimate, working flow. No interactive confirm by design: agents and
+    scripts auto-confirm, so a prompt is friction without protection; the
+    hard disjoint-gate is the protection.
+    """
+    env_root = _env_implied_project_root()
+    if env_root is None:
+        return
+    resolved = target.resolve()
+    if resolved == env_root or env_root in resolved.parents:
+        return
+    click.echo(click.style(
+        f"Refusing `parse {command}`: it would act on {resolved} (resolved "
+        f"from your working directory), but this `parse` runs from the "
+        f"environment of {env_root}.", fg="red"), err=True)
+    click.echo(click.style(
+        f"  Either `cd {env_root}` and re-run, or run `parse {command}` "
+        f"without `--project` from inside the project you intend to modify.",
+        fg="yellow"), err=True)
+    sys.exit(2)
+
+
+def _find_project_root() -> Path:
+    """Nearest ancestor (cwd included) holding an initialized ``parse_apis``
+    package. cwd-only lookup made agents in subdirectories fail mysteriously;
+    ``init`` STAYS cwd-bound (you init exactly where the project root should
+    be)."""
+    for cand in (Path.cwd(), *Path.cwd().parents):
+        if (cand / "parse_apis" / "src" / "parse_apis" / "__init__.py").exists():
+            return cand
+    return Path.cwd()  # callers' existing not-initialized error then names init
+
+
+def _project_dependencies_pos(text: str) -> Optional[int]:
+    """Index just after the opening ``[`` of ``dependencies = [`` *inside the
+    ``[project]`` table*, or None if absent.
+
+    Anchored to ``[project]`` so a ``dependencies = [`` under any other table
+    (e.g. a ``[tool.*]`` section) is never targeted — the prior unanchored
+    ``re.search`` matched the first occurrence anywhere in the file, which could
+    splice deps into the wrong table.
+    """
+    proj = re.search(r"(?m)^\[project\]\s*$", text)
+    if not proj:
+        return None
+    rest = text[proj.end():]
+    nxt = re.search(r"(?m)^\[", rest)            # start of the next table, if any
+    table = rest if nxt is None else rest[:nxt.start()]
+    dm = re.search(r"dependencies\s*=\s*\[", table)
+    if not dm:
+        return None
+    return proj.end() + dm.end()
+
+
+def _dep_present(text: str, dep: str) -> bool:
+    """True if ``dep`` is already a declared ``[project]`` dependency.
+
+    Decided from the PARSE, not the raw text: the prior whole-file regex
+    counted a quoted name ANYWHERE (e.g. a comment ``# we removed
+    "parse-sdk" while debugging``) as present, silently skipping the insert —
+    and ``still_missing`` re-ran the same regex, so the gap passed its own
+    verification. Distribution names are PEP-503-canonicalized on both sides
+    (``Parse_SDK>=0.3`` still counts; ``my-parse-sdk`` never does).
+    Unparseable TOML → False: the insert then runs, and the final
+    ``tomllib.loads`` invariant fails loud instead of silently passing."""
+    try:
+        deps = tomllib.loads(text).get("project", {}).get("dependencies", [])
+    except Exception:
+        return False
+    if not isinstance(deps, list):
+        return False
+    declared = set()
+    for d in deps:
+        if isinstance(d, str):
+            m = re.match(r"\s*([A-Za-z0-9][A-Za-z0-9._-]*)", d)
+            if m:
+                declared.add(re.sub(r"[-_.]+", "-", m.group(1)).lower())
+    return re.sub(r"[-_.]+", "-", dep).lower() in declared
+
+
+def _ensure_consumer_pyproject(path: Path) -> None:
+    """Record ``parse-sdk`` + ``parse-apis`` as deps and ``parse-apis`` as an
+    editable path source — WITHOUT a ``parse-sdk`` path source (that
+    path is machine-specific). Idempotent.
+
+    Corruption-proof: new dependency entries are inserted immediately
+    after the array's opening ``[``, each on its own line ending in a comma. That
+    yields valid TOML for EVERY array shape — empty, single-line, multiline,
+    PEP-508 extras (``foo[extra]``), inline ``#`` comments, trailing commas —
+    because a ``"name",`` prefix is always a legal first array element regardless
+    of what follows. (The prior regex that spliced before a non-greedy ``]`` and
+    stripped ``inner`` corrupted all of those shapes, including ``uv add`` output.)
+    """
+    text = path.read_text()
+    new = text
+
+    want = [d for d in ("parse-sdk", "parse-apis") if not _dep_present(new, d)]
+    if want:
+        dep_at = _project_dependencies_pos(new)
+        if dep_at is not None:
+            insert = "".join(f'\n    "{d}",' for d in want)
+            new = new[:dep_at] + insert + new[dep_at:]
+        elif re.search(r"(?m)^\[project\]\s*$", new):
+            # SAME anchor as _project_dependencies_pos — both must agree on what
+            # a [project] table is, or a header like `[project]  # x` routes
+            # here while the pos-finder said None and we'd write a duplicate
+            # `dependencies` key.
+            joined = ", ".join(f'"{d}"' for d in want)
+            new = re.sub(r"(?m)^(\[project\]\s*\n)",
+                         lambda mm: mm.group(1) + f"dependencies = [{joined}]\n",
+                         new, count=1)
+        else:
+            raise click.ClickException(
+                "pyproject.toml has no [project] table, so the parse-sdk/parse-apis "
+                "dependencies can't be recorded. Add a [project] table with `name` "
+                "and `version` (or create the project with `uv init`) and re-run "
+                "`parse init`."
+            )
+
+    if "[tool.uv.sources]" not in new:
+        new = new.rstrip() + (
+            '\n\n[tool.uv.sources]\n'
+            'parse-apis = { path = "parse_apis", editable = true }\n')
+    elif not re.search(r"parse-apis\s*=\s*\{", new):
+        new = re.sub(r"(\[tool\.uv\.sources\]\s*\n)",
+                     lambda mm: mm.group(1) + 'parse-apis = { path = "parse_apis", editable = true }\n',
+                     new, count=1)
+
+    try:
+        tomllib.loads(new)  # invariant: parse init never writes invalid TOML
+    except tomllib.TOMLDecodeError as e:
+        raise click.ClickException(
+            f"refusing to write pyproject.toml — the edit would corrupt it ({e}). "
+            "Add parse-sdk and parse-apis to [project].dependencies manually."
+        )
+    still_missing = [d for d in ("parse-sdk", "parse-apis") if not _dep_present(new, d)]
+    if still_missing:
+        raise click.ClickException(
+            f"could not record {', '.join(still_missing)} in pyproject.toml "
+            "([project].dependencies not found or unparseable) — add them manually "
+            "and re-run `parse init`."
+        )
+    if new != text:
+        _atomic_write_text(path, new)
+
+
+def _finalize_install(project: Path) -> None:
+    """Install the freshly-declared editable ``parse-apis`` so the project is
+    usable immediately — not only on the user's next ``uv run``.
+
+    Without this, ``parse init`` leaves ``parse-apis`` *declared* in pyproject but
+    *not installed*; an activated-venv ``python app.py`` right after init would
+    ``ModuleNotFoundError``. Best-effort: if ``uv`` is absent or sync fails, print
+    the exact remediation instead of a misleading "installed" message — never
+    fatal (the scaffold + deps are already written).
+    """
+    uv = shutil.which("uv")
+    if uv is None:
+        click.echo(click.style(
+            "  Next: run `uv sync` (or `pip install -e ./parse_apis`) to install the package.",
+            fg="yellow"))
+        return
+    # Bound both subprocesses: capture_output hides any progress, so a hung `uv`
+    # (e.g. an unreachable registry that never times out the TCP connect) would
+    # otherwise block the CLI forever with no user-visible signal.
+    try:
+        synced = subprocess.run([uv, "sync"], cwd=str(project),
+                                capture_output=True, text=True, timeout=300)
+    except subprocess.TimeoutExpired:
+        click.echo(click.style(
+            "  `uv sync` timed out — run `uv sync` manually to finish.", fg="yellow"))
+        return
+    if synced.returncode != 0:
+        stderr = synced.stderr.strip()
+        tail = (stderr.splitlines() or ["uv sync failed"])[-1]
+        click.echo(click.style("  Couldn't auto-install parse_apis — run `uv sync` to finish:", fg="yellow"))
+        click.echo(click.style(f"    {_safe_console(tail)}", fg="yellow", dim=True))
+        # Targeted hint for the pre-PyPI case: parse-sdk isn't on an index yet,
+        # so uv can't resolve the `parse-sdk==X` pin and reports the dep tree as
+        # unsatisfiable. The fix is to install parse-sdk from a local checkout.
+        low = stderr.lower()
+        if "parse-sdk" in low and ("unsatisfiable" in low or "no solution" in low
+                                   or "was not found" in low or "not found in the" in low):
+            click.echo(click.style(
+                "    parse-sdk isn't resolvable here yet. If it isn't published to "
+                "your index, install it from a local checkout:\n"
+                "      uv add --editable /path/to/Parse-sdk\n"
+                "    then re-run `uv sync`. Run `parse doctor` to re-check.",
+                fg="yellow"))
+        return
+    try:
+        verify = subprocess.run(
+            [uv, "run", "python", "-c", "import parse_apis"],
+            cwd=str(project), capture_output=True, text=True, timeout=120)
+    except subprocess.TimeoutExpired:
+        click.echo(click.style(
+            "  parse_apis installed but import verification timed out — check your environment.",
+            fg="yellow"))
+        return
+    if verify.returncode != 0:
+        tail = (verify.stderr.strip().splitlines() or ["import failed"])[-1]
+        click.echo(click.style(
+            "  parse_apis installed but import verification failed:", fg="yellow"))
+        click.echo(click.style(f"    {tail}", fg="yellow", dim=True))
+        click.echo(click.style(
+            "  Reproduce with: uv run python -c \"import parse_apis\"", fg="yellow"))
+    else:
+        click.echo(click.style("✓ installed and verified `import parse_apis`", fg="green"))
+
+
+@cli.command()
+@click.option("--api-key", help="Parse API key. Saved to ~/.config/parse/credentials.")
+@click.option("--base-url", help=f"Override the Parse base URL (default: {DEFAULT_BASE_URL}).")
+def init(api_key: Optional[str], base_url: Optional[str]) -> None:
+    """Initialize parse_apis in this project: scaffold, deps, gitignore, first sync.
+
+    Detects and migrates (or refuses) a legacy flat `parse_apis/` layout, writes
+    the committed scaffold, records the editable `parse-apis` dependency and the
+    deny-by-default gitignore, ensures credentials, then runs the first sync.
+    One-shot non-interactive setup: pass `--api-key` (and optionally `--base-url`).
+    """
+    project = Path.cwd()
+    consumer = project / "pyproject.toml"
+    if not consumer.exists():
+        click.echo(click.style(
+            "No pyproject.toml in the current directory. Run `parse init` from your "
+            "project root (a uv/pip project with a pyproject.toml).", fg="red"), err=True)
+        sys.exit(2)
+    _guard_target_project(project, command="init")
+    # Name the mutation target FIRST — init edits this project's pyproject/
+    # .gitignore and may archive a flat parse_apis/, so the user must see
+    # which absolute root that is before any of it happens.
+    click.echo(f"Initializing parse_apis in {click.style(str(project.resolve()), fg='cyan')}")
+
+    old = project / "parse_apis"
+    # Legacy flat layout: parse_apis/ exists but is not the new scaffold.
+    if old.exists() and not (old / "pyproject.toml").exists() and not (old / "src").exists():
+        report = migrate.classify_flat_layout(old)
+        if not report.is_fully_owned:
+            click.echo(click.style(
+                "Refusing to migrate: parse_apis/ contains files Parse did not generate.",
+                fg="red"), err=True)
+            for p in report.unknown:
+                click.echo(click.style(f"    · {p.relative_to(project)}", fg="red"), err=True)
+            click.echo(click.style(
+                "  Move or remove these, then re-run `parse init`.", fg="yellow"), err=True)
+            sys.exit(1)
+        legacy = _unique_legacy_dir(project)
+        click.echo(click.style(
+            f"    · archiving legacy flat parse_apis/ → {legacy.relative_to(project)}",
+            fg="yellow", dim=True))
+        shutil.move(str(old), str(legacy))
+
+    if api_key:
+        save_credentials(api_key=api_key, base_url=base_url)
+    cfg = _net_resolve()
+    if not cfg.api_key:
+        api_key = _prompt_key_or_exit()
+        save_credentials(api_key=api_key, base_url=base_url)
+        cfg = resolve()
+
+    scaffold.write_scaffold(project, __version__)
+    _append_gitignore(project)
+    _ensure_consumer_pyproject(consumer)
+    click.echo(click.style(
+        "✓ scaffolded parse_apis/ and recorded the editable dependency", fg="green"))
+
+    schemas = _fetch_schemas(cfg)
+    # Respect a committed [tool.parse] (clone + `parse init` reproduces the
+    # curated set incl. version-pinned marketplace canonicals); absent apis ⇒
+    # all account APIs. Marketplace entries can exist even with no account APIs.
+    pcfg = _project.read_project_config(consumer)
+    selected, _missing = _gather_desired_schemas(cfg, schemas, pcfg)
+    declared_any = bool(pcfg.apis) or bool(pcfg.marketplace)
+    if declared_any and not selected:
+        # The repo DECLARES a curated set (account slugs and/or marketplace
+        # canonicals) but every one is unresolvable (stale/typo'd, a key without
+        # those APIs, or marketplace fetch failures). Scaffolding an empty package
+        # — or pruning every generated client on a re-init — is never what the
+        # user wants; refuse with an actionable error, parity with `sync`.
+        click.echo(click.style(
+            "Refusing to sync: every API in [tool.parse] is unresolvable "
+            "(missing from your account / marketplace), which would leave "
+            "parse_apis with no generated clients. Fix the list (`parse list` "
+            "shows valid slugs) or remove the [tool.parse] table to track all "
+            "account APIs, then `parse sync`.", fg="red"), err=True)
+        sys.exit(2)
+    if selected:
+        _sync_installed(cfg, selected, clean=False)
+    else:
+        click.echo("No APIs for this key yet — run `parse sync` once you add APIs in Parse.")
+
+    # Actually install the editable package + verify, so the project is usable now.
+    _finalize_install(project)
+
+
+_DOCTOR_ICON = {doctor_mod.OK: ("✓", "green"),
+                doctor_mod.WARN: ("⚠", "yellow"),
+                doctor_mod.ERROR: ("✗", "red")}
+
+
+def _print_findings(findings: List["doctor_mod.Finding"]) -> None:
+    """Render findings to the terminal, most-severe first."""
+    for f in sorted(findings, key=doctor_mod.sort_key):
+        icon, color = _DOCTOR_ICON.get(f.level, ("·", "white"))
+        click.echo(f"{click.style(icon, fg=color)} {f.title}")
+        if f.detail:
+            for line in f.detail.splitlines():
+                click.echo(click.style(f"    {_safe_console(line)}", dim=True))
+        if f.fix:
+            click.echo(click.style(f"    → {f.fix}", fg="cyan"))
+
+
+def _apply_doctor_fixes(project: Path, cfg, findings: List["doctor_mod.Finding"]) -> None:
+    """Run the safe, offline-ish auto-remediations the findings ask for: re-record
+    the consumer pyproject deps/source, then `uv sync`. Network regens (`parse
+    sync`) are deliberately NOT auto-run — they're shown as the fix instead."""
+    kinds = {f.kind for f in findings if f.level != doctor_mod.OK}
+    consumer = project / "pyproject.toml"
+    if "record_deps" in kinds and consumer.exists():
+        try:
+            _ensure_consumer_pyproject(consumer)
+            click.echo(click.style("  · recorded parse-sdk + parse-apis deps / editable source", fg="green"))
+        except (click.ClickException, OSError) as e:
+            click.echo(click.style(f"  · couldn't record deps: {e}", fg="red"), err=True)
+    if kinds & {"record_deps", "uv_sync"}:
+        uv = shutil.which("uv")
+        if uv is None:
+            click.echo(click.style("  · skipped `uv sync` — uv not on PATH", fg="yellow"))
+        else:
+            try:
+                r = subprocess.run([uv, "sync"], cwd=str(project),
+                                   capture_output=True, text=True, timeout=300)
+                if r.returncode == 0:
+                    click.echo(click.style("  · ran `uv sync`", fg="green"))
+                else:
+                    tail = (r.stderr.strip().splitlines() or ["uv sync failed"])[-1]
+                    click.echo(click.style(f"  · `uv sync` failed: {_safe_console(tail)}", fg="red"), err=True)
+            except subprocess.TimeoutExpired:
+                click.echo(click.style("  · `uv sync` timed out", fg="red"), err=True)
+
+
+@cli.command()
+@click.option("--fix", "do_fix", is_flag=True,
+              help="Attempt safe auto-remediation (record deps + `uv sync`), then re-check.")
+@click.option("--json", "as_json", is_flag=True,
+              help="Machine-readable findings (stable shape; agents should prefer this).")
+def doctor(do_fix: bool, as_json: bool) -> None:
+    """Diagnose this project's Parse SDK install and explain (or fix) problems.
+
+    Checks uv, the parse_apis scaffold, your pyproject deps + editable source,
+    parse-sdk version skew, whether the project interpreter can import
+    parse_sdk + parse_apis (the usual cause of dead editor autocomplete), and
+    credentials/host-trust. Exits 1 if any error-level problem remains.
+    """
+    project = _find_project_root()
+    cfg = resolve()
+    findings = doctor_mod.run_diagnostics(project, cfg, version=__version__)
+    if do_fix and any(f.kind in ("record_deps", "uv_sync") for f in findings
+                      if f.level != doctor_mod.OK):
+        if not as_json:
+            click.echo("Applying fixes…")
+        _apply_doctor_fixes(project, cfg, findings)
+        # Re-resolve + re-check so the report reflects the post-fix state.
+        cfg = resolve()
+        findings = doctor_mod.run_diagnostics(project, cfg, version=__version__)
+    if as_json:
+        click.echo(json.dumps({
+            "ok": not doctor_mod.has_errors(findings),
+            "findings": [f.as_dict() for f in findings],
+        }, indent=2, sort_keys=True))
+    else:
+        _print_findings(findings)
+        n_err = sum(1 for f in findings if f.level == doctor_mod.ERROR)
+        n_warn = sum(1 for f in findings if f.level == doctor_mod.WARN)
+        auto_fixable = any(f.kind in ("record_deps", "uv_sync") for f in findings
+                           if f.level != doctor_mod.OK)
+        if n_err or n_warn:
+            summary = (f"\n{n_err} error{'s' if n_err != 1 else ''}, "
+                       f"{n_warn} warning{'s' if n_warn != 1 else ''}")
+            if auto_fixable and not do_fix:
+                summary += " — re-run with `parse doctor --fix` to auto-remediate."
+            click.echo(summary)
+        else:
+            click.echo(click.style("\n✓ all checks passed", fg="green"))
+    if doctor_mod.has_errors(findings):
+        sys.exit(1)
+
+
+def _sync_installed(cfg, schemas: List[dict], *, clean: bool,
+                    check: bool = False, as_json: bool = False,
+                    _pkg_paths: "Optional[Tuple[Path, Path, Path]]" = None) -> None:
+    """Default sync: build the COMPLETE next package beside the live one,
+    self-test it, then promote with an atomic directory swap. Refuses if the
+    project isn't initialized.
+
+    Atomicity: the live package is never mutated in
+    place. The next package — committed scaffold + freshly generated slugs +
+    retained present-but-skipped slugs — is built on the same filesystem and
+    swapped via two ``os.replace`` calls with rollback, so a failure (mid-build,
+    a failed check, or an interrupted swap) leaves the live tree exactly as it
+    was. Orphaned slugs (uuids dropped from the server) are simply not carried
+    into the next package — that IS the prune. ``--clean`` drops the
+    carried slugs too, rebuilding the payload from scratch — and, unlike the old
+    upfront ``rmtree``, only after the new payload is proven good.
+    """
+    # Init precondition + interrupted-promote hint + disjoint-env guard. `sync`
+    # already resolved these before the network and threads them in to
+    # avoid re-running the check; other callers resolve here.
+    project, root, pkg = _pkg_paths or _require_generated_package()
+
+    rendered, skipped = _render_modules(schemas, cfg.base_url, quiet=as_json)
+    stage_check_swap(cfg, schemas, rendered, skipped,
+                     project=project, root=root, pkg=pkg, clean=clean,
+                     check=check, as_json=as_json)
+
+
+# Per-command auth/init facts for `parse help --json` (read via getattr, omitted
+# when unset — never a silent false). A NEW command adds its row here or its facts
+# are honestly omitted from the orientation JSON. Verified against each body:
+# search = PUBLIC marketplace read (no key); remove fetches account schemas (needs
+# key); init CREATES the project (auth yes, init no); clean is local (init yes).
+for _cmd, _req_auth, _req_init in (
+    (login, False, False), (init, True, False), (list_cmd, True, False),
+    (sync, True, True), (whoami, False, False), (clean, False, True),
+    (doctor, False, False), (add, True, True), (search, False, False),
+    (remove, True, True),
+):
+    setattr(_cmd, "requires_auth", _req_auth)
+    setattr(_cmd, "requires_init", _req_init)
+del _cmd, _req_auth, _req_init
+
+
+if __name__ == "__main__":
+    cli()