refactorai-cli 0.7.11__tar.gz → 0.7.13__tar.gz

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.7.11
+Version: 0.7.13
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,7 +8,7 @@ Requires-Dist: typer>=0.12.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: PyYAML>=6.0.1
-Requires-Dist: refactorai-core>=3.2.22
+Requires-Dist: refactorai-core>=3.2.23
 
 # refactorai-cli
 
@@ -66,6 +66,55 @@ the managed host toolchain when no container runtime is available. `refactor
 doctor` reports the selected environment (and `refactor doctor --sandbox` shows
 its full state), so a run and diagnostics always agree.
 
+## Customizing refactor.config
+
+`refactor init` writes a **bare-minimum** `refactor.config`: just `version`,
+`project_id`, and a CLI-managed block seeded to `local_heuristic`. A normal
+developer never edits this file by hand — pick the mode (and provider keys, if
+any) in the web UI or via `refactor setup --mode <variant>`.
+
+### The managed block (single source of truth for the mode)
+
+```
+# >>> refactor managed (synced from server; do not edit) >>>
+execution_variant: cloud_byok
+provider: openai
+model_id: gpt-4.1-mini
+credential_ref: cred_01J...
+# <<< refactor managed <<<
+```
+
+- Owned by the CLI. `refactor setup` (terminal) writes it immediately; a change
+  made in the web UI is pulled into this block on the next `refactor doctor` /
+  `refactor watch` / `refactor setup` (**server-wins**).
+- Only these keys live here: `execution_variant`, `provider`, `model_id`,
+  `base_url` (local_model), `credential_ref`. **Secrets are never written** —
+  keep provider keys in the environment and reference them as `${ENV_VAR}`.
+
+### What each mode needs
+
+| variant          | you provide                                             |
+| ---------------- | ------------------------------------------------------- |
+| `local_heuristic`| nothing                                                 |
+| `local_model`    | nothing (setup writes the Ollama provider/model block)  |
+| `local_byok`     | provider API key in the env (`${VAR}`); provider/model via UI/setup |
+| `local_managed`  | nothing                                                 |
+| `cloud_byok`     | provider API key in env (or a UI credential); provider/model via UI/setup |
+| `cloud_managed`  | nothing                                                 |
+
+### Advanced knobs and precedence
+
+Advanced settings (`sandbox`, `verification`, `intelligence`, `compliance`,
+`watch`, `timeout`, `exclude`, `model_context_overrides`, …) are **not** written
+by `init`; add only the ones you need anywhere **outside** the managed block.
+`refactor init --full` writes the fully-annotated template with every knob if you
+prefer to start from that.
+
+Resolution precedence: CLI flags → environment (`provider_key`,
+`REFACTOR_PROVIDER`) → the synced managed block → code defaults. A key you place
+outside the managed block (later in the file) also takes precedence over the
+block, so power users can pin values while normal syncing continues.
+
 ## Local development install
 
 From repository root:

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/README.md

@@ -54,6 +54,55 @@ the managed host toolchain when no container runtime is available. `refactor
 doctor` reports the selected environment (and `refactor doctor --sandbox` shows
 its full state), so a run and diagnostics always agree.
 
+## Customizing refactor.config
+
+`refactor init` writes a **bare-minimum** `refactor.config`: just `version`,
+`project_id`, and a CLI-managed block seeded to `local_heuristic`. A normal
+developer never edits this file by hand — pick the mode (and provider keys, if
+any) in the web UI or via `refactor setup --mode <variant>`.
+
+### The managed block (single source of truth for the mode)
+
+```
+# >>> refactor managed (synced from server; do not edit) >>>
+execution_variant: cloud_byok
+provider: openai
+model_id: gpt-4.1-mini
+credential_ref: cred_01J...
+# <<< refactor managed <<<
+```
+
+- Owned by the CLI. `refactor setup` (terminal) writes it immediately; a change
+  made in the web UI is pulled into this block on the next `refactor doctor` /
+  `refactor watch` / `refactor setup` (**server-wins**).
+- Only these keys live here: `execution_variant`, `provider`, `model_id`,
+  `base_url` (local_model), `credential_ref`. **Secrets are never written** —
+  keep provider keys in the environment and reference them as `${ENV_VAR}`.
+
+### What each mode needs
+
+| variant          | you provide                                             |
+| ---------------- | ------------------------------------------------------- |
+| `local_heuristic`| nothing                                                 |
+| `local_model`    | nothing (setup writes the Ollama provider/model block)  |
+| `local_byok`     | provider API key in the env (`${VAR}`); provider/model via UI/setup |
+| `local_managed`  | nothing                                                 |
+| `cloud_byok`     | provider API key in env (or a UI credential); provider/model via UI/setup |
+| `cloud_managed`  | nothing                                                 |
+
+### Advanced knobs and precedence
+
+Advanced settings (`sandbox`, `verification`, `intelligence`, `compliance`,
+`watch`, `timeout`, `exclude`, `model_context_overrides`, …) are **not** written
+by `init`; add only the ones you need anywhere **outside** the managed block.
+`refactor init --full` writes the fully-annotated template with every knob if you
+prefer to start from that.
+
+Resolution precedence: CLI flags → environment (`provider_key`,
+`REFACTOR_PROVIDER`) → the synced managed block → code defaults. A key you place
+outside the managed block (later in the file) also takes precedence over the
+block, so power users can pin values while normal syncing continues.
+
 ## Local development install
 
 From repository root:

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "refactorai-cli"
-version = "0.7.11"
+version = "0.7.13"
 description = "Local-first CLI for the refactor platform"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -12,7 +12,7 @@ dependencies = [
   "httpx>=0.27.0",
   "rich>=13.7.0",
   "PyYAML>=6.0.1",
-  "refactorai-core>=3.2.22",
+  "refactorai-core>=3.2.23",
 ]
 
 [project.scripts]

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli/__init__.py

@@ -5,4 +5,4 @@ the shared `refactor_core` pipeline from a project folder while staying
 authenticated to the hosted platform via a developer key.
 """
 
-__version__ = "0.7.11"
+__version__ = "0.7.13"

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli/client.py

@@ -143,3 +143,68 @@ class PlatformClient:
             )
         payload = response.json()
         return payload if isinstance(payload, dict) else {}
+
+    def get_project_execution_mode(self, developer_key: str, project_id: str) -> dict:
+        """Read a project's engine execution settings via the developer key.
+
+        Used by the CLI (``setup`` / ``doctor`` / ``watch``) to sync the server's
+        ``execution_mode`` (as chosen in the web UI) into the local
+        ``refactor.config`` -- server-wins. Returns the project record dict.
+        """
+        try:
+            response = httpx.get(
+                f"{self.base_url}/v1/projects/{project_id}/execution-mode",
+                headers={"Authorization": f"Bearer {developer_key}"},
+                timeout=self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise PlatformError(f"Could not reach platform at {self.base_url}: {exc}") from exc
+        if response.status_code == 401:
+            raise PlatformError("Developer key is invalid or revoked", status_code=401)
+        if response.status_code == 404:
+            raise PlatformError("Project not found for this account", status_code=404)
+        if response.status_code >= 400:
+            raise PlatformError(
+                f"Could not read project execution mode ({response.status_code})",
+                status_code=response.status_code,
+            )
+        payload = response.json() if response.content else {}
+        return payload if isinstance(payload, dict) else {}
+
+    def set_project_execution_mode(
+        self, developer_key: str, project_id: str, execution_mode: str
+    ) -> dict:
+        """Push a chosen execution variant to the server project (developer key).
+
+        Lets ``refactor setup --mode`` keep the terminal and the web UI in sync.
+        Returns the updated project record dict.
+        """
+        try:
+            response = httpx.patch(
+                f"{self.base_url}/v1/projects/{project_id}/execution-mode",
+                headers={
+                    "Authorization": f"Bearer {developer_key}",
+                    "Content-Type": "application/json",
+                },
+                json={"execution_mode": execution_mode},
+                timeout=self.timeout,
+            )
+        except httpx.HTTPError as exc:
+            raise PlatformError(f"Could not reach platform at {self.base_url}: {exc}") from exc
+        if response.status_code == 401:
+            raise PlatformError("Developer key is invalid or revoked", status_code=401)
+        if response.status_code == 404:
+            raise PlatformError("Project not found for this account", status_code=404)
+        if response.status_code >= 400:
+            detail = ""
+            try:
+                detail = str((response.json() or {}).get("detail", ""))
+            except Exception:
+                detail = response.text[:200]
+            suffix = f": {detail}" if detail else ""
+            raise PlatformError(
+                f"Could not update project execution mode ({response.status_code}){suffix}",
+                status_code=response.status_code,
+            )
+        payload = response.json() if response.content else {}
+        return payload if isinstance(payload, dict) else {}

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli/commands/run_cmds.py

@@ -30,6 +30,7 @@ from refactor_core.constitution import (
     CONSTITUTION_FILENAME,
     DEFAULT_CONFIG,
     DEFAULT_CONSTITUTION,
+    MINIMAL_CONFIG,
     find_project_files,
     has_raw_secret_literal,
     load_config,
@@ -126,15 +127,8 @@ from refactorai_cli.auth import AuthContext, AuthError, ensure_authenticated
 from refactorai_cli.client import PlatformClient, PlatformError
 from refactorai_cli.credentials import load_credentials, save_credentials
 from refactorai_cli.dotenv_loader import DotenvResult, load_project_dotenv
-from refactorai_cli.local_engine_runtime import DEFAULT_ENGINE_PORT, read_engine_state
 from refactorai_cli.runtime_manager import runtime_status, runtime_version_dir
 from refactorai_cli.settings import mask_key, platform_url
-from refactorai_cli.setup_flow import (
-    BACKEND_BYOK,
-    BACKEND_LOCAL_SERVER,
-    read_setup_state,
-    stage_output_path,
-)
 
 console = Console()
 
@@ -165,67 +159,22 @@ def _sandbox_runtime():
     return _sr
 
 
-def _read_stage_output(stage_id: str) -> dict:
-    path = stage_output_path(stage_id)
-    if not path.is_file():
-        return {}
-    try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return {}
-    output = payload.get("output")
-    return output if isinstance(output, dict) else {}
-
-
-def _setup_recommended_model_id() -> str:
-    s5_output = _read_stage_output("S5")
-    model_id = str(s5_output.get("recommended_model_id") or "").strip()
-    return model_id or "qwen2.5-coder:1.5b-instruct"
+def _default_config_for_init(full: bool = False) -> tuple[str, str]:
+    """Return the config `init` writes.
 
+    By default this is the bare-minimum template (docs/46): ``version`` +
+    the CLI-managed block seeded to ``local_heuristic``. A normal developer never
+    hand-edits it -- they pick a mode in the web UI or via ``refactor setup
+    --mode`` and the managed block is filled in by the CLI. ``--full`` writes the
+    fully-annotated template with every advanced knob for power users.
 
-def _setup_engine_base_url() -> str:
-    state = read_engine_state()
-    try:
-        port = int(state.get("port", DEFAULT_ENGINE_PORT))
-    except (TypeError, ValueError):
-        port = DEFAULT_ENGINE_PORT
-    return f"http://127.0.0.1:{port}/v1"
-
-
-def _default_config_for_init() -> tuple[str, str]:
-    setup_state = read_setup_state()
-    backend = str(setup_state.get("execution_backend") or "").strip().lower()
-    if backend == BACKEND_LOCAL_SERVER:
-        model_id = _setup_recommended_model_id()
-        base_url = _setup_engine_base_url()
-        # local_model runs tests on the host and swaps the default heuristic
-        # provider block for an Ollama block pointing at the local engine.
-        config_text = DEFAULT_CONFIG.replace(
-            "# Heuristic (local, no LLM) - default for execution_variant: local_heuristic\n"
-            "provider: heuristic\n"
-            "model_id: heuristic-local-v1",
-            "# Ollama (local engine) - configured by `refactor init`\n"
-            "provider: ollama\n"
-            f"model_id: {model_id}\n"
-            f"base_url: {base_url}",
-            1,
-        )
-        config_text = config_text.replace(
-            "execution_variant: local_heuristic",
-            "execution_variant: local_model",
-            1,
-        )
-        return config_text, "local_server"
-    if backend == BACKEND_BYOK:
-        # BYOK only flips the execution variant. The developer chooses and
-        # uncomments a provider block in the Provider selection section.
-        config_text = DEFAULT_CONFIG.replace(
-            "execution_variant: local_heuristic",
-            "execution_variant: cloud_byok",
-            1,
-        )
-        return config_text, "byok"
-    return DEFAULT_CONFIG, "default"
+    Mode selection is a *setup*-time concern: ``init`` never derives the mode
+    from prior setup-backend state (that legacy coupling produced configs whose
+    variant disagreed with the server default and is intentionally removed).
+    """
+    if full:
+        return DEFAULT_CONFIG, "full"
+    return MINIMAL_CONFIG, "default"
 
 _SEVERITY_STYLE = {
     "critical": "bold red",
@@ -1413,6 +1362,12 @@ def init(
         "--force",
         help=f"Overwrite existing {CONSTITUTION_FILENAME} and {CONFIG_FILENAME}.",
     ),
+    full: bool = typer.Option(
+        False,
+        "--full",
+        hidden=True,
+        help="Write the fully-annotated refactor.config template (power users).",
+    ),
 ) -> None:
     """Create `refactor.consti` + `refactor.config` and register the project.
 
@@ -1479,7 +1434,7 @@ def init(
         raise typer.Exit(code=1)
 
     consti_target.write_text(DEFAULT_CONSTITUTION, encoding="utf-8")
-    config_text, config_profile = _default_config_for_init()
+    config_text, _config_profile = _default_config_for_init(full=full)
     config_text = _inject_project_id(config_text, project_id)
     config_target.write_text(config_text, encoding="utf-8")
     gitignore_updated = _ensure_refactor_gitignore(project_root)
@@ -1534,16 +1489,11 @@ def init(
         f"{account_label.title()}: [bold]{account_value}[/bold]. "
         f"Project id saved in {CONFIG_FILENAME}."
     )
-    if config_profile == "local_server":
-        console.print(
-            "[green]Configured[/green] refactor.config for local server setup "
-            "(provider=ollama with setup-recommended model)."
-        )
-    elif config_profile == "byok":
-        console.print(
-            "[green]Configured[/green] refactor.config for BYOK setup "
-            "(mode=cloud_byok, env-key-first via provider_key; credential_ref is optional fallback)."
-        )
+    console.print(
+        "[green]Configured[/green] refactor.config with the default mode "
+        "([bold]local_heuristic[/bold]). Choose your execution mode (and provider "
+        "keys, if any) in the web UI or via `refactor setup --mode <variant>`."
+    )
     console.print(
         f"Added {CONSTITUTION_FILENAME}. "
         f"{CONFIG_FILENAME} is treated as local by default and added to .gitignore "
@@ -5360,6 +5310,21 @@ def doctor(
     consti_path, _ = files
     project_root = consti_path.parent
 
+    # Server-wins: pull the project's execution mode (as chosen in the web UI)
+    # into the local refactor.config before reading it, so doctor diagnoses the
+    # mode that runs will actually use. Best-effort; a no-op when offline.
+    try:
+        from refactorai_cli.mode_sync import sync_execution_variant_from_server
+
+        synced = sync_execution_variant_from_server(
+            project_root, emit=lambda m: console.print(f"[dim]{m}[/dim]")
+        )
+        if synced:
+            files = find_project_files() or files
+            consti_path, _ = files
+    except Exception:
+        pass
+
     # Load ``.env`` BEFORE parsing config so ``${VAR}`` interpolation (for
     # example ``provider_key: ${OPENAI_API_KEY}``) resolves from it. The
     # entrypoint already loads it for real runs; here we also surface the status

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli/commands/watch_cmds.py

@@ -1098,6 +1098,16 @@ def watch(
     _ensure_auth_in_window(json_output)
     _report_heartbeat(project_root)
 
+    # Server-wins: sync the project's execution mode (web UI choice) into the
+    # local refactor.config before the loop reads it. Silent + best-effort so it
+    # never pollutes the --json stream or blocks the terminal when offline.
+    try:
+        from refactorai_cli.mode_sync import sync_execution_variant_from_server
+
+        sync_execution_variant_from_server(project_root)
+    except Exception:
+        pass
+
     state = WatchState(repo_name=project_root.name)
     try:
         state.current_branch = git_scope.current_branch(project_root) or ""

refactorai_cli-0.7.13/refactorai_cli/mode_sync.py

@@ -0,0 +1,171 @@
+"""Execution-mode sync between the server project and local ``refactor.config``.
+
+The web UI sets a project's ``execution_mode`` on the server (JWT). The CLI
+authenticates with a developer key and treats the server as the source of truth
+(server-wins): ``setup`` / ``doctor`` / ``watch`` pull the server mode and write
+it into the local ``refactor.config`` so a UI change reflects in terminal runs.
+``refactor setup --mode`` also pushes the chosen variant up so both agree.
+
+All operations are best-effort: offline / unauthenticated / unbound projects are
+a silent no-op so they never break the surrounding command.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from refactor_core.constitution import (
+    CONFIG_FILENAME,
+    MANAGED_KEYS,
+    find_project_files,
+    load_config,
+    upsert_managed_block,
+)
+from refactor_core.execution_variant import normalize_execution_variant
+from refactor_core.store import resolve_project_id
+
+from refactorai_cli.client import PlatformClient
+from refactorai_cli.credentials import resolve_developer_key
+
+
+def _local_config_path(project_root: Path) -> Path | None:
+    files = find_project_files(project_root)
+    if files:
+        return Path(files[1])
+    candidate = Path(project_root) / CONFIG_FILENAME
+    return candidate if candidate.is_file() else None
+
+
+def _current_managed_values(project_root: Path) -> dict:
+    """Current values of the managed keys as parsed from refactor.config."""
+    config_path = _local_config_path(project_root)
+    if config_path is None:
+        return {}
+    try:
+        settings = getattr(load_config(config_path), "settings", {}) or {}
+    except Exception:
+        return {}
+    values: dict = {}
+    for key in MANAGED_KEYS:
+        raw = settings.get(key)
+        if raw is None:
+            continue
+        text = str(raw).strip()
+        if text:
+            values[key] = text
+    return values
+
+
+def _desired_managed_fields(record: dict, current: dict, server_variant: str) -> dict:
+    """Compute the managed-block fields from the server record (server-wins).
+
+    When the server carries a remote provider (BYOK/managed set from the UI), the
+    provider/model/credential come from the server and any local ``base_url`` is
+    dropped. Otherwise (heuristic / terminal-set local_model, where the server has
+    no provider) the local provider/model/base_url are preserved and only the
+    variant is reconciled.
+    """
+    provider = str(record.get("inference_provider") or "").strip()
+    model_id = str(record.get("model_id") or "").strip()
+    credential_ref = str(record.get("provider_credential_ref") or "").strip()
+
+    fields: dict = {"execution_variant": server_variant}
+    if provider:
+        fields["provider"] = provider
+        if model_id:
+            fields["model_id"] = model_id
+        if credential_ref:
+            fields["credential_ref"] = credential_ref
+    else:
+        for key in ("provider", "model_id", "base_url", "credential_ref"):
+            if current.get(key):
+                fields[key] = current[key]
+    return fields
+
+
+def sync_execution_variant_from_server(
+    project_root: Path,
+    *,
+    client: PlatformClient | None = None,
+    emit: Callable[[str], None] | None = None,
+) -> str | None:
+    """Pull the server project's execution settings into the managed config block.
+
+    Server-wins for the managed keys (execution_variant / provider / model_id /
+    credential_ref). Secrets (``provider_key``) are never written -- they stay in
+    the environment. Returns the applied variant when the local config changed,
+    else ``None`` (already in sync, offline, unauthenticated, or unbound project).
+    """
+    try:
+        project_id = resolve_project_id(project_root)
+        if not project_id:
+            return None
+        resolved = resolve_developer_key(project_root)
+        if not resolved:
+            return None
+        client = client or PlatformClient()
+        record = client.get_project_execution_mode(resolved.key, project_id)
+    except Exception:
+        return None
+
+    server_variant = normalize_execution_variant((record or {}).get("execution_mode"))
+    if not server_variant:
+        return None
+
+    config_path = _local_config_path(project_root)
+    if config_path is None:
+        return None
+
+    current = _current_managed_values(project_root)
+    desired = _desired_managed_fields(record or {}, current, server_variant)
+
+    # No-op when the managed keys already match (compare only managed keys).
+    current_managed = {k: current.get(k) for k in MANAGED_KEYS if current.get(k)}
+    if desired == current_managed:
+        return None
+
+    try:
+        text = config_path.read_text(encoding="utf-8")
+        new_text = upsert_managed_block(text, desired)
+        if not new_text.endswith("\n"):
+            new_text += "\n"
+        if new_text == text:
+            return None
+        config_path.write_text(new_text, encoding="utf-8")
+    except OSError:
+        return None
+
+    if emit:
+        emit(f"Synced execution_variant from server: {server_variant}")
+    return server_variant
+
+
+def push_execution_variant_to_server(
+    project_root: Path,
+    variant: str,
+    *,
+    client: PlatformClient | None = None,
+    emit: Callable[[str], None] | None = None,
+) -> bool:
+    """Push a locally chosen execution variant to the server project.
+
+    Best-effort; returns ``True`` on a successful push, else ``False``.
+    """
+    normalized = normalize_execution_variant(variant)
+    if not normalized:
+        return False
+    try:
+        project_id = resolve_project_id(project_root)
+        if not project_id:
+            return False
+        resolved = resolve_developer_key(project_root)
+        if not resolved:
+            return False
+        client = client or PlatformClient()
+        client.set_project_execution_mode(resolved.key, project_id, normalized)
+    except Exception:
+        return False
+    if emit:
+        emit(f"Pushed execution_variant to server: {normalized}")
+    return True

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli/setup_flow.py

@@ -18,9 +18,11 @@ from rich.progress import BarColumn, DownloadColumn, Progress, TaskID, TextColum
 from refactorai_cli.local_engine_runtime import (
     DEFAULT_ENGINE_CONTAINER,
     DEFAULT_ENGINE_IMAGE,
+    DEFAULT_ENGINE_PORT,
     engine_status,
     ensure_engine_up,
     pull_model,
+    read_engine_state,
     resolve_runtime as resolve_engine_runtime,
 )
 from refactorai_cli.local_paths import ensure_dir, refactor_home
@@ -151,6 +153,19 @@ def write_stage_output(stage_id: str, payload: dict) -> None:
     tmp.replace(path)
 
 
+def read_stage_output(stage_id: str) -> dict:
+    """Return a stage's persisted ``output`` dict (or ``{}`` when absent)."""
+    path = stage_output_path(stage_id)
+    if not path.is_file():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    output = payload.get("output")
+    return output if isinstance(output, dict) else {}
+
+
 def get_setup_diagnostics() -> dict:
     state = read_setup_state()
     stages: dict[str, dict] = {}
@@ -562,17 +577,51 @@ def _resolve_project_variant() -> str:
         return ""
 
 
+def _local_model_provider_values() -> tuple[str, str]:
+    """Resolve (model_id, base_url) for the local_model Ollama provider block.
+
+    ``model_id`` prefers the S5 setup recommendation, falling back to a small
+    default; ``base_url`` targets the local engine port.
+    """
+    model_id = ""
+    try:
+        s5 = read_stage_output("S5")
+        model_id = str(s5.get("recommended_model_id") or "").strip()
+    except Exception:
+        model_id = ""
+    if not model_id:
+        model_id = "qwen2.5-coder:1.5b-instruct"
+    try:
+        port = int(read_engine_state().get("port", DEFAULT_ENGINE_PORT))
+    except Exception:
+        port = DEFAULT_ENGINE_PORT
+    return model_id, f"http://127.0.0.1:{port}/v1"
+
+
+def _local_model_managed_fields() -> dict:
+    """Managed-block fields for ``local_model`` (Ollama provider + model/base_url)."""
+    model_id, base_url = _local_model_provider_values()
+    return {
+        "execution_variant": LOCAL_MODEL,
+        "provider": "ollama",
+        "model_id": model_id,
+        "base_url": base_url,
+    }
+
+
 def _persist_variant_to_project_config(variant: str, emit: Callable[[str], None] | None = None) -> None:
-    """Write the chosen ``execution_variant`` into the project's refactor.config.
+    """Write the chosen ``execution_variant`` into the CLI-managed config block.
 
     Keeps a UI-selected or terminal-selected mode as the single source of truth
-    for subsequent runs (doctor/review/code read it from config). Best-effort: a
-    missing project config or write error never fails setup.
+    for subsequent runs (doctor/review/code read it from config). For
+    ``local_model`` the block also carries the local Ollama provider/model/base_url
+    (docs/46: local_model provider config is a setup concern, not an init concern).
+    Best-effort: a missing config or write error never fails setup.
     """
     if not variant:
         return
     try:
-        from refactor_core.constitution import find_project_files
+        from refactor_core.constitution import find_project_files, upsert_managed_block
 
         files = find_project_files()
         if not files:
@@ -580,19 +629,12 @@ def _persist_variant_to_project_config(variant: str, emit: Callable[[str], None]
         _consti_path, config_path = files
         config_path = Path(config_path)
         text = config_path.read_text(encoding="utf-8")
-        lines = text.splitlines()
-        new_line = f"execution_variant: {variant}"
-        replaced = False
-        for idx, line in enumerate(lines):
-            if line.strip().startswith("execution_variant:"):
-                if line.strip() == new_line:
-                    return
-                lines[idx] = new_line
-                replaced = True
-                break
-        if not replaced:
-            lines.append(new_line)
-        config_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        fields = _local_model_managed_fields() if variant == LOCAL_MODEL else {"execution_variant": variant}
+        new_text = upsert_managed_block(text, fields)
+        if not new_text.endswith("\n"):
+            new_text += "\n"
+        if new_text != text:
+            config_path.write_text(new_text, encoding="utf-8")
         if emit:
             emit(f"Recorded execution_variant: {variant} in refactor.config.")
     except Exception:
@@ -819,6 +861,20 @@ def run_setup(
         resolved_variant = _resolve_project_variant()
     if resolved_variant:
         _persist_variant_to_project_config(resolved_variant, on_progress)
+        # Push the chosen variant to the server project so the web UI and the
+        # terminal agree (server-wins on later syncs). Best-effort; never blocks
+        # setup when offline or the project is not bound to a cloud record.
+        try:
+            from refactor_core.constitution import find_project_files
+            from refactorai_cli.mode_sync import push_execution_variant_to_server
+
+            files = find_project_files()
+            if files:
+                push_execution_variant_to_server(
+                    Path(files[0]).parent, resolved_variant, emit=on_progress
+                )
+        except Exception:
+            pass
 
     state = read_setup_state()
     if not resume and not from_stage:

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refactorai-cli
-Version: 0.7.11
+Version: 0.7.13
 Summary: Local-first CLI for the refactor platform
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,7 +8,7 @@ Requires-Dist: typer>=0.12.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: rich>=13.7.0
 Requires-Dist: PyYAML>=6.0.1
-Requires-Dist: refactorai-core>=3.2.22
+Requires-Dist: refactorai-core>=3.2.23
 
 # refactorai-cli
 
@@ -66,6 +66,55 @@ the managed host toolchain when no container runtime is available. `refactor
 doctor` reports the selected environment (and `refactor doctor --sandbox` shows
 its full state), so a run and diagnostics always agree.
 
+## Customizing refactor.config
+
+`refactor init` writes a **bare-minimum** `refactor.config`: just `version`,
+`project_id`, and a CLI-managed block seeded to `local_heuristic`. A normal
+developer never edits this file by hand — pick the mode (and provider keys, if
+any) in the web UI or via `refactor setup --mode <variant>`.
+
+### The managed block (single source of truth for the mode)
+
+```
+# >>> refactor managed (synced from server; do not edit) >>>
+execution_variant: cloud_byok
+provider: openai
+model_id: gpt-4.1-mini
+credential_ref: cred_01J...
+# <<< refactor managed <<<
+```
+
+- Owned by the CLI. `refactor setup` (terminal) writes it immediately; a change
+  made in the web UI is pulled into this block on the next `refactor doctor` /
+  `refactor watch` / `refactor setup` (**server-wins**).
+- Only these keys live here: `execution_variant`, `provider`, `model_id`,
+  `base_url` (local_model), `credential_ref`. **Secrets are never written** —
+  keep provider keys in the environment and reference them as `${ENV_VAR}`.
+
+### What each mode needs
+
+| variant          | you provide                                             |
+| ---------------- | ------------------------------------------------------- |
+| `local_heuristic`| nothing                                                 |
+| `local_model`    | nothing (setup writes the Ollama provider/model block)  |
+| `local_byok`     | provider API key in the env (`${VAR}`); provider/model via UI/setup |
+| `local_managed`  | nothing                                                 |
+| `cloud_byok`     | provider API key in env (or a UI credential); provider/model via UI/setup |
+| `cloud_managed`  | nothing                                                 |
+
+### Advanced knobs and precedence
+
+Advanced settings (`sandbox`, `verification`, `intelligence`, `compliance`,
+`watch`, `timeout`, `exclude`, `model_context_overrides`, …) are **not** written
+by `init`; add only the ones you need anywhere **outside** the managed block.
+`refactor init --full` writes the fully-annotated template with every knob if you
+prefer to start from that.
+
+Resolution precedence: CLI flags → environment (`provider_key`,
+`REFACTOR_PROVIDER`) → the synced managed block → code defaults. A key you place
+outside the managed block (later in the file) also takes precedence over the
+block, so power users can pin values while normal syncing continues.
+
 ## Local development install
 
 From repository root:

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ refactorai_cli/local_constitution.py
 refactorai_cli/local_engine_runtime.py
 refactorai_cli/local_paths.py
 refactorai_cli/main.py
+refactorai_cli/mode_sync.py
 refactorai_cli/model_policy.py
 refactorai_cli/pre_push_gate.py
 refactorai_cli/refactor_branch_store.py

{refactorai_cli-0.7.11 → refactorai_cli-0.7.13}/refactorai_cli.egg-info/requires.txt

@@ -2,4 +2,4 @@ typer>=0.12.0
 httpx>=0.27.0
 rich>=13.7.0
 PyYAML>=6.0.1
-refactorai-core>=3.2.22
+refactorai-core>=3.2.23