devcouncil 0.1.0 → 0.2.0

package/src/devcouncil/cli/commands/runs.py

@@ -0,0 +1,223 @@
+"""`dev runs` — list and inspect per-run agent manifests.
+
+Coding-CLI executors write a manifest at
+``.devcouncil/runs/<run-id>/agent-run.json`` (prompt file, executor, profile,
+resolved command, exit status, run metadata). These commands let a developer or a
+supervisor list and inspect those runs without reading raw JSON, and flag a run
+whose status is still ``running`` but whose manifest has gone stale (the executor
+process likely crashed) as ``orphaned``.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from devcouncil.utils.redaction import redact_text
+
+app = typer.Typer(help="List and inspect coding-agent run manifests.")
+console = Console()
+
+# A run still marked ``running`` whose manifest has not been touched for longer
+# than this is treated as orphaned (the executor process likely died). Used as a
+# sane default; can be overridden per-call with --orphan-after.
+_DEFAULT_ORPHAN_AFTER_SECONDS = 600
+
+# Transcript/log files (in priority order) whose tail `dev runs show` surfaces.
+_TRANSCRIPT_CANDIDATES = ("transcript.txt", "transcript.log", "output.log", "run.log")
+_TRANSCRIPT_TAIL_LINES = 40
+
+
+def _runs_dir(project_root: Path) -> Path:
+    return project_root / ".devcouncil" / "runs"
+
+
+def _orphan_after_seconds(project_root: Path) -> int:
+    """Threshold (seconds) after which a stale ``running`` manifest is orphaned.
+
+    Config-driven when available (execution.lease_ttl_seconds is a reasonable
+    proxy for "how long a live run can plausibly stay quiet"); falls back to a
+    sane default so the command works before `dev init`."""
+    try:
+        from devcouncil.app.config import load_config
+
+        ttl = int(load_config(project_root).execution.lease_ttl_seconds)
+        if ttl > 0:
+            return ttl
+    except Exception:
+        pass
+    return _DEFAULT_ORPHAN_AFTER_SECONDS
+
+
+def _load_manifest(manifest_path: Path) -> dict | None:
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _is_orphaned(manifest: dict, manifest_path: Path, *, orphan_after: int, now: float) -> bool:
+    """A run is orphaned when it is still ``running`` but its manifest file has
+    not been updated within the threshold — i.e. no heartbeat, executor gone."""
+    if manifest.get("status") != "running":
+        return False
+    try:
+        mtime = manifest_path.stat().st_mtime
+    except OSError:
+        return False
+    return (now - mtime) > max(0, orphan_after)
+
+
+def _run_summary(manifest: dict, manifest_path: Path, *, orphan_after: int, now: float) -> dict:
+    return {
+        "run_id": manifest.get("run_id") or manifest_path.parent.name,
+        "task_id": manifest.get("task_id"),
+        "agent": manifest.get("agent"),
+        "profile": manifest.get("profile"),
+        "status": manifest.get("status"),
+        "started_at": manifest.get("started_at") or manifest.get("timestamp"),
+        "finished_at": manifest.get("finished_at"),
+        "returncode": manifest.get("returncode"),
+        "orphaned": _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=now),
+    }
+
+
+def _collect_runs(project_root: Path, *, orphan_after: int) -> list[dict]:
+    runs_dir = _runs_dir(project_root)
+    if not runs_dir.is_dir():
+        return []
+    now = time.time()
+    summaries: list[tuple[float, dict]] = []
+    for manifest_path in runs_dir.glob("*/agent-run.json"):
+        manifest = _load_manifest(manifest_path)
+        if manifest is None:
+            continue
+        try:
+            sort_key = manifest_path.stat().st_mtime
+        except OSError:
+            sort_key = 0.0
+        summaries.append((sort_key, _run_summary(manifest, manifest_path, orphan_after=orphan_after, now=now)))
+    # Newest first.
+    summaries.sort(key=lambda item: item[0], reverse=True)
+    return [summary for _, summary in summaries]
+
+
+def _find_transcript(run_dir: Path, manifest: dict) -> Path | None:
+    recorded = manifest.get("transcript")
+    if isinstance(recorded, str) and recorded:
+        candidate = Path(recorded)
+        if not candidate.is_absolute():
+            candidate = run_dir / recorded
+        if candidate.is_file():
+            return candidate
+    for name in _TRANSCRIPT_CANDIDATES:
+        candidate = run_dir / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _transcript_tail(path: Path, *, lines: int = _TRANSCRIPT_TAIL_LINES) -> str:
+    """Return the redacted tail of a transcript file (best-effort)."""
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    tail = content.splitlines()[-lines:]
+    return redact_text("\n".join(tail))
+
+
+@app.command("list")
+def list_runs(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    limit: int = typer.Option(20, "--limit", help="Maximum number of runs to show."),
+    status: str | None = typer.Option(None, "--status", help="Filter by run status (e.g. running, finished, failed, timeout)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """List recorded coding-agent runs, newest first."""
+    root = project_root.expanduser().resolve()
+    orphan_after = _orphan_after_seconds(root)
+    runs = _collect_runs(root, orphan_after=orphan_after)
+    if status:
+        runs = [run for run in runs if run.get("status") == status]
+    if limit > 0:
+        runs = runs[:limit]
+
+    if json_output:
+        console.print_json(data={"runs": runs, "count": len(runs)})
+        return
+
+    if not runs:
+        console.print("[dim]No agent runs found under .devcouncil/runs/.[/dim]")
+        return
+
+    table = Table(title="Agent runs")
+    table.add_column("Run ID", overflow="fold")
+    table.add_column("Task")
+    table.add_column("Agent")
+    table.add_column("Profile")
+    table.add_column("Status")
+    table.add_column("Started")
+    for run in runs:
+        status_text = str(run.get("status") or "?")
+        if run.get("orphaned"):
+            status_text = f"[red]{status_text} (orphaned)[/red]"
+        table.add_row(
+            str(run.get("run_id") or ""),
+            str(run.get("task_id") or ""),
+            str(run.get("agent") or ""),
+            str(run.get("profile") or ""),
+            status_text,
+            str(run.get("started_at") or ""),
+        )
+    console.print(table)
+
+
+@app.command("show")
+def show_run(
+    run_id: str = typer.Argument(..., help="The run id to inspect."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+) -> None:
+    """Show the full manifest for a run plus a redacted transcript tail."""
+    root = project_root.expanduser().resolve()
+    run_dir = _runs_dir(root) / run_id
+    manifest_path = run_dir / "agent-run.json"
+    manifest = _load_manifest(manifest_path)
+    if manifest is None:
+        if json_output:
+            console.print_json(data={"ok": False, "error": f"Run {run_id} not found.", "run_id": run_id})
+        else:
+            console.print(f"[red]Run {run_id} not found under .devcouncil/runs/.[/red]")
+        raise typer.Exit(code=1)
+
+    orphan_after = _orphan_after_seconds(root)
+    orphaned = _is_orphaned(manifest, manifest_path, orphan_after=orphan_after, now=time.time())
+    transcript_path = _find_transcript(run_dir, manifest)
+    transcript_tail = _transcript_tail(transcript_path) if transcript_path else ""
+
+    if json_output:
+        console.print_json(data={
+            "ok": True,
+            "run_id": run_id,
+            "manifest": manifest,
+            "orphaned": orphaned,
+            "transcript_path": str(transcript_path) if transcript_path else None,
+            "transcript_tail": transcript_tail,
+        })
+        return
+
+    console.print_json(data=manifest)
+    if orphaned:
+        console.print("[red]This run is orphaned: still marked running but its manifest is stale.[/red]")
+    if transcript_path:
+        console.print(f"\n[bold]Transcript tail[/bold] [dim]({transcript_path})[/dim]:")
+        console.print(transcript_tail or "[dim](empty)[/dim]")
+    else:
+        console.print("\n[dim]No transcript file found for this run.[/dim]")

package/src/devcouncil/cli/commands/scaffold.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, detect_stacks, scaffold_ci
+
+console = Console()
+
+
+def scaffold_ci_command(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root to scaffold CI into."),
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing devcouncil.yml workflow."),
+):
+    """Write a starter GitHub Actions workflow derived from the configured commands."""
+    root = project_root.expanduser().resolve()
+    if not (root / ".devcouncil").exists():
+        console.print("[red]DevCouncil is not initialized here. Run 'dev setup' first.[/red]")
+        raise typer.Exit(code=1)
+
+    target = scaffold_ci(root, force=force)
+    if target is None:
+        console.print(
+            f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists. "
+            f"Re-run with --force to overwrite.[/yellow]"
+        )
+        return
+
+    stacks = detect_stacks(root)
+    detected = ", ".join(sorted(stacks)) if stacks else "none auto-detected"
+    console.print(f"[green]Wrote {target.relative_to(root).as_posix()} (stacks: {detected}).[/green]")
+    console.print("[dim]Review the setup/install steps and commands before relying on it.[/dim]")

package/src/devcouncil/cli/commands/semantic.py

@@ -0,0 +1,47 @@
+import json
+import typer
+from pathlib import Path
+from rich.console import Console
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.indexing.semantic_index import SemanticIndex
+
+app = typer.Typer(help="Semantic snapshots and diffs.")
+console = Console()
+
+
+@app.command("snapshot")
+def snapshot(
+    task_id: str = typer.Argument(...),
+    stage: str = typer.Option("before", "--stage", help="before or after"),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    if stage not in {"before", "after"}:
+        console.print("[red]--stage must be before or after[/red]")
+        raise typer.Exit(code=2)
+    path = SemanticIndex(root).create_snapshot(task_id, stage)
+    payload = {"task_id": task_id, "stage": stage, "path": str(path)}
+    if json_format:
+        typer.echo(json.dumps(payload, indent=2))
+    else:
+        console.print(f"[green]Wrote semantic snapshot:[/green] {path}")
+
+
+@app.command("diff")
+def semantic_diff(
+    task_id: str = typer.Argument(...),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    json_format: bool = typer.Option(False, "--json"),
+):
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    result = SemanticIndex(root).diff(task_id)
+    if json_format:
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        console.print(f"[cyan]Summary:[/cyan] {result['summary']}")
+        for item in result["classifications"]:
+            console.print(f" - {item['type']}: {item.get('path', '')}")

package/src/devcouncil/cli/commands/setup.py

@@ -1,18 +1,225 @@
 from pathlib import Path
+import os
 import shutil
+import sys
 
 import typer
+import yaml
 from rich.console import Console
 from rich.panel import Panel
 
+from devcouncil.app.config import (
+    _normalized_provider_name,
+    get_gcloud_access_token,
+    load_config,
+    load_local_secrets,
+    provider_api_key_env_var,
+)
 from devcouncil.cli.commands.doctor import render_doctor_check
-from devcouncil.cli.commands.init import initialize_project
-from devcouncil.cli.commands.integrate import _codex_command, _configure, _gemini_command
+from devcouncil.cli.commands.init import initialize_project, parse_role_model_overrides
+from devcouncil.cli.commands.integrate import (
+    _claude_command,
+    _codex_command,
+    _configure_antigravity,
+    _configure_cursor,
+    _configure_native_hooks,
+    _configure_opencode,
+    _configure_warp,
+    _configure,
+    _gemini_command,
+)
+from devcouncil.llm.provider import apply_provider_default_role_models, build_role_model_config, validate_model_provider
 
 app = typer.Typer()
 console = Console()
 
 
+def _set_model_provider(project_root: Path, provider: str) -> None:
+    normalized = validate_model_provider(provider)
+    config_path = project_root / ".devcouncil" / "config.yaml"
+    raw_config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    raw_config.setdefault("models", {})
+    previous = raw_config["models"].get("provider", "openrouter")
+    raw_config["models"]["provider"] = normalized
+    updated_role_defaults = apply_provider_default_role_models(raw_config, previous, normalized)
+    config_path.write_text(yaml.dump(raw_config, default_flow_style=False), encoding="utf-8")
+    if previous != normalized:
+        console.print(f"[green]Updated model provider from {previous} to {normalized}.[/green]")
+    if updated_role_defaults:
+        console.print(f"[green]Updated default role models for {normalized}.[/green]")
+
+
+def _set_model_roles(
+    project_root: Path,
+    model: str | None = None,
+    role_models: dict[str, str] | None = None,
+) -> None:
+    if not model and not role_models:
+        return
+
+    config_path = project_root / ".devcouncil" / "config.yaml"
+    raw_config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    raw_config.setdefault("models", {})
+    provider = validate_model_provider(raw_config["models"].get("provider", "openrouter"))
+    raw_config["models"]["roles"] = build_role_model_config(
+        provider,
+        model=model,
+        role_models=role_models,
+    )
+    config_path.write_text(yaml.dump(raw_config, default_flow_style=False), encoding="utf-8")
+    if model:
+        console.print(f"[green]Updated all model roles to use {model}.[/green]")
+    for role, selected_model in (role_models or {}).items():
+        console.print(f"[green]Updated {role} to use {selected_model}.[/green]")
+
+
+def _write_local_secret(project_root: Path, env_var: str, value: str) -> Path:
+    if "\n" in value or "\r" in value:
+        raise ValueError("API keys cannot contain newlines.")
+    secrets = load_local_secrets(project_root)
+    secrets[env_var] = value
+    path = project_root / ".devcouncil" / "secrets.env"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        "# Local DevCouncil secrets. This file is ignored by git.",
+        "# Process environment variables with the same name take precedence.",
+        *[f"{key}={val}" for key, val in sorted(secrets.items())],
+        "",
+    ]
+    path.write_text("\n".join(lines), encoding="utf-8")
+    return path
+
+
+def _configure_vertexai_settings(
+    project_root: Path,
+    provider: str,
+    vertex_project: str | None,
+    vertex_location: str | None,
+) -> None:
+    if provider != "vertexai":
+        return
+
+    local_secrets = load_local_secrets(project_root)
+    if vertex_project:
+        _write_local_secret(project_root, "VERTEXAI_PROJECT", vertex_project)
+        console.print("[green]Saved VERTEXAI_PROJECT to .devcouncil/secrets.env.[/green]")
+    elif not (
+        os.environ.get("VERTEXAI_PROJECT")
+        or os.environ.get("GOOGLE_CLOUD_PROJECT")
+        or local_secrets.get("VERTEXAI_PROJECT")
+        or local_secrets.get("GOOGLE_CLOUD_PROJECT")
+    ):
+        console.print(
+            "[yellow]VERTEXAI_PROJECT is not set. "
+            "Set it in your shell or rerun setup with --vertex-project PROJECT_ID.[/yellow]"
+        )
+
+    if vertex_location:
+        _write_local_secret(project_root, "VERTEXAI_LOCATION", vertex_location)
+        console.print("[green]Saved VERTEXAI_LOCATION to .devcouncil/secrets.env.[/green]")
+
+
+def _configure_api_key(project_root: Path, api_key: str | None, skip_api_key: bool) -> None:
+    config = load_config(project_root)
+    provider = config.models.provider
+    if _normalized_provider_name(provider) == "ollama":
+        console.print(
+            "[green]Ollama uses a local server (default http://localhost:11434); no API key required.[/green]"
+        )
+        return
+    env_var = provider_api_key_env_var(provider)
+    local_secrets = load_local_secrets(project_root)
+
+    if os.environ.get(env_var):
+        console.print(f"[green]{env_var} is already set in the environment.[/green]")
+        return
+    if local_secrets.get(env_var):
+        console.print(f"[green]{env_var} is already set in .devcouncil/secrets.env.[/green]")
+        return
+    if api_key:
+        _write_local_secret(project_root, env_var, api_key)
+        console.print(f"[green]Saved {env_var} to .devcouncil/secrets.env.[/green]")
+        return
+    if provider == "vertexai" and get_gcloud_access_token():
+        console.print("[green]Vertex AI access token is available from gcloud auth print-access-token.[/green]")
+        return
+    if skip_api_key:
+        console.print(f"[yellow]Skipped {env_var} setup. Model-backed commands will ask again if it is missing.[/yellow]")
+        return
+    if not sys.stdin.isatty():
+        console.print(
+            f"[yellow]{env_var} is not set.[/yellow] "
+            f"Run [bold]dev setup --api-key YOUR_KEY[/bold] or set it in your shell before model-backed commands."
+        )
+        return
+
+    console.print()
+    console.print(Panel.fit(
+        "\n".join([
+            f"Provider: {provider}",
+            f"Required key: {env_var}",
+            "Press Enter without a value to skip for now.",
+        ]),
+        title="Model API Key",
+        border_style="cyan",
+    ))
+    entered = typer.prompt(f"{env_var}", default="", hide_input=True, show_default=False)
+    if not entered:
+        console.print(f"[yellow]Skipped {env_var} setup.[/yellow]")
+        return
+    _write_local_secret(project_root, env_var, entered)
+    console.print(f"[green]Saved {env_var} to .devcouncil/secrets.env.[/green]")
+
+
+def _is_interactive_terminal() -> bool:
+    return sys.stdin.isatty()
+
+
+def _configure_coding_cli_integrations(project_root: Path, apply: bool, gemini_scope: str) -> None:
+    console.print()
+    console.print("[bold]Coding CLI integration[/bold]")
+    commands = [
+        ("Codex CLI", _codex_command(project_root)),
+        ("Gemini CLI", _gemini_command(project_root, gemini_scope)),
+        ("Claude Code", _claude_command(project_root, "local")),
+    ]
+    results = []
+    for tool, command in commands:
+        if apply and not shutil.which(command[0]):
+            console.print(f"[yellow]{tool} CLI not found on PATH. Skipping optional integration.[/yellow]")
+            continue
+        results.append(_configure(tool, command, apply))
+    results.append(_configure_cursor(project_root, apply))
+    results.append(_configure_opencode(project_root, apply))
+    results.append(_configure_antigravity(project_root, apply))
+    results.append(_configure_warp(project_root, apply))
+    _configure_native_hooks(project_root, "all", apply)
+    if apply and any(not ok for ok in results):
+        raise typer.Exit(code=1)
+
+
+def _prompt_for_first_run_integrations(project_root: Path, apply: bool, gemini_scope: str) -> bool:
+    if not _is_interactive_terminal():
+        return False
+
+    console.print()
+    console.print(Panel.fit(
+        "\n".join([
+            "DevCouncil can configure supported coding CLIs now.",
+            "This adds MCP setup and native hook config for detected clients.",
+            "Missing optional clients are skipped.",
+        ]),
+        title="Coding CLI Setup",
+        border_style="cyan",
+    ))
+    if not typer.confirm("Set up coding CLI integrations now?", default=True):
+        console.print("[yellow]Skipped coding CLI integration setup.[/yellow]")
+        return False
+
+    _configure_coding_cli_integrations(project_root, apply=apply, gemini_scope=gemini_scope)
+    return True
+
+
 @app.callback(invoke_without_command=True)
 def setup(
     ctx: typer.Context,
@@ -22,9 +229,24 @@ def setup(
         help="Target project repository root. Defaults to the terminal's current directory.",
     ),
     name: str | None = typer.Option(None, "--name", "-n", help="Project name for .devcouncil/config.yaml."),
-    integrate: bool = typer.Option(False, "--integrate", help="Configure supported coding CLI MCP integrations."),
+    integrate: bool = typer.Option(False, "--integrate", help="Configure supported coding CLI MCP integrations and native hooks."),
     apply: bool = typer.Option(False, "--apply", help="Apply integration config instead of previewing commands."),
     gemini_scope: str = typer.Option("project", "--gemini-scope", help="Gemini MCP config scope: project or user."),
+    provider: str | None = typer.Option(None, "--provider", help="Set models.provider before configuring the API key."),
+    model: str | None = typer.Option(None, "--model", "-m", help="Model id to use for every default role."),
+    role_model: list[str] | None = typer.Option(
+        None,
+        "--role-model",
+        help="Per-role model override in ROLE=MODEL form. Can be repeated.",
+    ),
+    api_key: str | None = typer.Option(None, "--api-key", help="Store the configured provider API key in local .devcouncil/secrets.env."),
+    vertex_project: str | None = typer.Option(None, "--vertex-project", help="Store VERTEXAI_PROJECT for the vertexai provider."),
+    vertex_location: str | None = typer.Option(None, "--vertex-location", help="Store VERTEXAI_LOCATION for the vertexai provider. Defaults to global."),
+    skip_api_key: bool = typer.Option(False, "--skip-api-key", help="Skip the first-run model API key prompt."),
+    skip_integrations: bool = typer.Option(False, "--skip-integrations", help="Skip the first-run coding CLI integration prompt."),
+    skip_map: bool = typer.Option(False, "--skip-map", help="Skip generating repo_map.json and agent guides on init."),
+    skip_skills: bool = typer.Option(False, "--skip-skills", help="Skip scaffolding engineering skills into .claude/skills/ on init."),
+    scaffold_ci: bool = typer.Option(False, "--scaffold-ci", help="Write a starter .github/workflows/devcouncil.yml from the configured commands."),
 ):
     """
     Initialize DevCouncil from a normal terminal in the target repository root.
@@ -39,42 +261,100 @@ def setup(
         raise typer.Exit(code=2)
 
     root = project_root.expanduser().resolve()
-    created = initialize_project(root, project_name=name)
+    try:
+        role_models = parse_role_model_overrides(role_model)
+        initial_provider = validate_model_provider(provider) if provider else "openrouter"
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=2) from e
+
+    # Size the default local model to the host's memory ceiling (unified RAM on Apple
+    # Silicon, VRAM on a discrete GPU, system RAM otherwise) instead of the static 7b,
+    # so users on any OS get a capable council out of the box. Only when the user chose
+    # Ollama and did not pin a model.
+    if initial_provider == "ollama" and model is None:
+        from devcouncil import hardware
+
+        host = hardware.describe_host()
+        model = host.recommended_ollama_model
+        console.print(
+            f"[green]Detected {host.chip_label} ({host.memory_label}); "
+            f"defaulting Ollama model to {model}.[/green] "
+            "Override with --model, and pull it first: "
+            f"[bold]ollama pull {model}[/bold]."
+        )
+    elif initial_provider == "ollama" and model is not None:
+        # Model pinned explicitly — still remind the user it must be pulled locally.
+        console.print(
+            f"[green]Using Ollama model {model}.[/green] "
+            f"Pull it first if needed: [bold]ollama pull {model}[/bold]."
+        )
+
+    created = initialize_project(
+        root,
+        project_name=name,
+        model_provider=initial_provider,
+        model=model,
+        role_models=role_models,
+        with_map=not skip_map,
+        with_skills=not skip_skills,
+    )
     if not created:
         console.print(f"[yellow]DevCouncil is already initialized at {root / '.devcouncil'}.[/yellow]")
 
+    if provider:
+        try:
+            _set_model_provider(root, provider)
+        except ValueError as e:
+            console.print(f"[red]{e}[/red]")
+            raise typer.Exit(code=2) from e
+
+    _set_model_roles(root, model=model, role_models=role_models)
+
+    configured_provider = load_config(root).models.provider
+    _configure_vertexai_settings(root, configured_provider, vertex_project, vertex_location)
+    _configure_api_key(root, api_key, skip_api_key)
+
     console.print()
-    render_doctor_check()
+    render_doctor_check(root)
+
+    if scaffold_ci:
+        from devcouncil.repo.ci_scaffold import WORKFLOW_RELPATH, scaffold_ci as scaffold_ci_workflow
+
+        written = scaffold_ci_workflow(root)
+        if written is None:
+            console.print(f"[yellow]{WORKFLOW_RELPATH.as_posix()} already exists; left unchanged.[/yellow]")
+        else:
+            console.print(f"[green]Wrote starter CI workflow {written.relative_to(root).as_posix()}.[/green]")
 
     if integrate:
-        console.print()
-        console.print("[bold]Coding CLI integration[/bold]")
-        commands = [
-            ("Codex CLI", _codex_command(root)),
-            ("Gemini CLI", _gemini_command(root, gemini_scope)),
-        ]
-        results = []
-        for tool, command in commands:
-            if apply and not shutil.which(command[0]):
-                console.print(f"[yellow]{tool} CLI not found on PATH. Skipping optional integration.[/yellow]")
-                continue
-            results.append(_configure(tool, command, apply))
-        if apply and any(not ok for ok in results):
-            raise typer.Exit(code=1)
+        _configure_coding_cli_integrations(root, apply=apply, gemini_scope=gemini_scope)
+    elif created and not skip_integrations:
+        _prompt_for_first_run_integrations(root, apply=True, gemini_scope=gemini_scope)
 
     console.print()
     console.print(Panel.fit(
         "\n".join([
             "[bold]Next commands[/bold]",
             f"Keep running DevCouncil commands in this terminal at: {root}",
+            "One-command agent path:",
+            "dev e2e \"Describe the implementation goal\"",
+            "",
+            "Manual sidecar path:",
             "dev plan \"Describe the implementation goal\"",
             "dev tasks",
             "dev run TASK-001 --executor manual",
             "dev prompt TASK-001",
             "Paste only the dev prompt output into your coding CLI.",
+            "Paste only the dev prompt output into your coding CLI, or run directly:",
+            "dev run TASK-001 --executor codex",
+            "dev run TASK-001 --executor gemini",
+            "dev run TASK-001 --executor claude",
+            "dev run TASK-001 --executor opencode",
+            "dev run TASK-001 --executor antigravity",
             "dev verify TASK-001",
             "",
-            "Use [bold]dev setup --integrate[/bold] to preview coding CLI MCP setup.",
+            "Use [bold]dev setup --integrate[/bold] to preview coding CLI MCP and native hook setup.",
             "Use [bold]dev setup --integrate --apply[/bold] to configure detected clients.",
         ]),
         title="DevCouncil is ready",