devcouncil 0.1.1 → 0.3.0

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

@@ -1,4 +1,5 @@
 from pathlib import Path
+import webbrowser
 
 import typer
 from rich.console import Console
@@ -15,6 +16,7 @@ def dashboard(
     ctx: typer.Context,
     host: str = typer.Option("127.0.0.1", "--host", help="Dashboard bind host."),
     port: int = typer.Option(8765, "--port", help="Dashboard bind port."),
+    open_browser: bool = typer.Option(False, "--open", help="Open the dashboard URL in the default browser before serving."),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
 ):
     """Serve a local live dashboard with project status, tasks, coverage, and traces."""
@@ -22,5 +24,8 @@ def dashboard(
         return
     root = project_root.expanduser().resolve()
     initialize_project(root, quiet=True)
-    console.print(f"Serving DevCouncil dashboard at http://{host}:{port}")
+    url = f"http://{host}:{port}"
+    console.print(f"Serving DevCouncil dashboard at {url}")
+    if open_browser:
+        webbrowser.open(url)
     run_dashboard(root, host=host, port=port)

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

@@ -0,0 +1,186 @@
+"""`dev design` — lint, export, and inspect a project design.md design system.
+
+Mirrors the upstream ``@google/design.md`` CLI's ``lint`` and ``export`` subcommands so a
+DevCouncil project can validate its design tokens and convert them to CSS / Tailwind / W3C
+Design Tokens. The same design.md is injected into coding-agent prompts (see
+``.devcouncil/knowledge/design``) so agents honor the system while they build.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.knowledge.design import export as export_design
+from devcouncil.knowledge.design import lint as lint_design
+from devcouncil.knowledge.design import parse_design_md
+from devcouncil.knowledge.design_conformance import (
+    STYLE_EXTENSIONS,
+    scan_files,
+)
+
+app = typer.Typer(help="Lint, export, and inspect a design.md design system.")
+console = Console()
+
+# Where a project's design system is looked for, in order.
+_DEFAULT_PATHS = (
+    ".devcouncil/knowledge/design/design.md",
+    "DESIGN.md",
+    "design.md",
+)
+
+# Directories pruned while auto-discovering style files (heavy / generated / vendored).
+_PRUNE_DIRS = frozenset({
+    ".git", ".hg", ".svn", "node_modules", ".venv", "venv", "env",
+    "dist", "build", "out", ".next", ".nuxt", ".svelte-kit", "coverage",
+    "__pycache__", ".mypy_cache", ".pytest_cache", ".cache", "vendor",
+})
+# Cap on auto-discovered files so an enormous repo can't make `check` run unbounded.
+_MAX_DISCOVERED_FILES = 5000
+
+
+def _discover_style_files(root: Path) -> list[Path]:
+    """Walk ``root`` for style-ish files, pruning heavy dirs and bounding the count."""
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _PRUNE_DIRS and not d.startswith(".")]
+        for name in filenames:
+            if Path(name).suffix.lower() in STYLE_EXTENSIONS:
+                found.append(Path(dirpath) / name)
+                if len(found) >= _MAX_DISCOVERED_FILES:
+                    return found
+    return found
+
+
+def _resolve_path(explicit: Path | None, project_root: Path) -> Path | None:
+    if explicit is not None:
+        candidate = explicit.expanduser()
+        return candidate if candidate.is_file() else None
+    for rel in _DEFAULT_PATHS:
+        candidate = project_root / rel
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+@app.command("lint")
+def lint(
+    path: Path = typer.Argument(None, help="Path to a design.md (defaults to the project's design system)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Validate a design system: broken token refs, contrast, ordering, orphans."""
+    root = project_root.expanduser().resolve()
+    target = _resolve_path(path, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    findings = lint_design(parse_design_md(target))
+    if not findings:
+        console.print(f"[green]✓ {target} passed all design.md lint rules.[/green]")
+        return
+
+    errors = [f for f in findings if f.severity == "error"]
+    color = {"error": "red", "warning": "yellow", "info": "cyan"}
+    console.print(f"[bold]{len(findings)} finding(s) in {target}:[/bold]")
+    for f in findings:
+        console.print(f"  [{color.get(f.severity, 'white')}]{f.format()}[/{color.get(f.severity, 'white')}]")
+    if errors:
+        raise typer.Exit(code=1)
+
+
+@app.command("export")
+def export(
+    path: Path = typer.Argument(None, help="Path to a design.md (defaults to the project's design system)."),
+    fmt: str = typer.Option("css", "--format", "-f", help="Output format: css | tailwind | w3c."),
+    output: Path = typer.Option(None, "--output", "-o", help="Write to this file instead of stdout."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Export design tokens to CSS custom properties, a Tailwind config, or W3C tokens."""
+    root = project_root.expanduser().resolve()
+    if fmt not in ("css", "tailwind", "w3c"):
+        console.print(f"[red]Unknown format '{fmt}'.[/red] Use one of: css, tailwind, w3c.")
+        raise typer.Exit(code=2)
+    target = _resolve_path(path, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    rendered = export_design(parse_design_md(target), fmt)  # type: ignore[arg-type]
+    if output is not None:
+        out = output.expanduser().resolve()
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(rendered, encoding="utf-8")
+        console.print(f"[green]Wrote {fmt} tokens to[/green] {out}")
+    else:
+        typer.echo(rendered, nl=not rendered.endswith("\n"))
+
+
+@app.command("check")
+def check(
+    files: list[Path] = typer.Argument(
+        None, help="Files to check (defaults to the repo's style-ish files)."),
+    design: Path = typer.Option(
+        None, "--design", help="Path to a design.md (defaults to the project's design system)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Flag hardcoded style literals (hex colors, px sizes) that bypass design tokens.
+
+    Exits non-zero when any violation is found so it can gate CI / a pre-commit hook.
+    """
+    root = project_root.expanduser().resolve()
+    target = _resolve_path(design, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    ds = parse_design_md(target)
+    paths = [f.expanduser() for f in files] if files else _discover_style_files(root)
+    violations = scan_files(paths, ds)
+
+    if not violations:
+        scanned = len([p for p in paths if p.suffix.lower() in STYLE_EXTENSIONS])
+        console.print(
+            f"[green]✓ No design-token violations in {scanned} file(s) "
+            f"(tokens from {target}).[/green]")
+        return
+
+    by_file: dict[str, list] = {}
+    for v in violations:
+        by_file.setdefault(v.file or "<text>", []).append(v)
+
+    console.print(
+        f"[bold red]{len(violations)} design-token violation(s) "
+        f"in {len(by_file)} file(s):[/bold red]")
+    for fname in sorted(by_file):
+        console.print(f"[bold]{fname}[/bold]")
+        for v in sorted(by_file[fname], key=lambda x: (x.line, x.kind)):
+            console.print(
+                f"  [yellow]{v.line}[/yellow] [{v.kind}] {v.message}\n"
+                f"      [dim]{v.snippet}[/dim]")
+    raise typer.Exit(code=1)
+
+
+@app.command("show")
+def show(
+    path: Path = typer.Argument(None, help="Path to a design.md (defaults to the project's design system)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root."),
+):
+    """Summarize a design system: token counts and document sections."""
+    root = project_root.expanduser().resolve()
+    target = _resolve_path(path, root)
+    if target is None:
+        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+        raise typer.Exit(code=1)
+
+    ds = parse_design_md(target)
+    console.print(f"[bold]{ds.name or target.name}[/bold] ({target})")
+    console.print(
+        f"  colors={len(ds.colors)}  typography={len(ds.typography)}  "
+        f"rounded={len(ds.rounded)}  spacing={len(ds.spacing)}  components={len(ds.components)}"
+    )
+    if ds.sections:
+        console.print("  sections: " + ", ".join(h for h, _ in ds.sections))

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

@@ -6,13 +6,230 @@ from pathlib import Path
 from rich.console import Console
 from rich.table import Table
 
-from devcouncil.app.config import load_config, load_local_secrets, provider_api_key_env_var
+from devcouncil.app.config import get_gcloud_access_token, load_config, load_local_secrets, provider_api_key_env_var
+from devcouncil.executors.agent_registry import (
+    CODING_CLI_INTEGRATION_INFO,
+    CODING_CLI_PROBE_ORDER,
+    CODING_CLI_VERSION_COMMANDS,
+    detect_available_coding_cli,
+    resolve_automated_executor,
+)
 from devcouncil.llm.provider import SUPPORTED_MODEL_PROVIDERS, validate_model_provider
 
 app = typer.Typer()
 console = Console()
 
+
+def _probe_ollama(base_url: str) -> tuple[bool, str]:
+    """Best-effort reachability check for a local Ollama server.
+
+    ``base_url`` carries the OpenAI-compatible ``/v1`` suffix; the native
+    ``/api/version`` endpoint lives one level up. Returns (reachable, detail);
+    any failure is reported, never raised.
+    """
+    root = base_url.rstrip("/")
+    if root.endswith("/v1"):
+        root = root[: -len("/v1")].rstrip("/")
+    try:
+        import httpx
+
+        resp = httpx.get(f"{root}/api/version", timeout=3.0)
+        if resp.status_code < 400:
+            version = ""
+            try:
+                version = (resp.json() or {}).get("version", "")
+            except Exception:
+                version = ""
+            return True, f"Reachable at {root}" + (f" (v{version})." if version else ".")
+        return False, f"Server at {root} returned HTTP {resp.status_code}."
+    except Exception:
+        return False, f"No Ollama server reachable at {root}."
+
+
+def _probe_ollama_models(base_url: str) -> tuple[bool, set[str]]:
+    """Best-effort list of locally-pulled Ollama model tags via native ``/api/tags``.
+
+    Returns (queried_ok, names). ``names`` holds the reported tags (e.g.
+    ``qwen2.5-coder:7b``). Any failure returns (False, set()) and is never raised — a
+    green liveness probe with no pulled model is the most common "configured but doesn't
+    work" trap, so this turns it into an actionable row."""
+    root = base_url.rstrip("/")
+    if root.endswith("/v1"):
+        root = root[: -len("/v1")].rstrip("/")
+    try:
+        import httpx
+
+        resp = httpx.get(f"{root}/api/tags", timeout=3.0)
+        if resp.status_code >= 400:
+            return False, set()
+        models = (resp.json() or {}).get("models", []) or []
+        names = {str(m.get("name", "")).strip() for m in models if m.get("name")}
+        return True, {n for n in names if n}
+    except Exception:
+        return False, set()
+
+
+def _ollama_model_present(model: str, pulled: set[str]) -> bool:
+    """Whether ``model`` is among the pulled tags, tolerant of the implicit ``:latest``
+    tag Ollama adds to untagged models."""
+    if model in pulled:
+        return True
+    base = model.split(":", 1)[0]
+    # configured "qwen2.5-coder" matches a pulled "qwen2.5-coder:latest", and vice versa.
+    candidates = {model, f"{model}:latest", base, f"{base}:latest"}
+    return any(tag in candidates or tag.split(":", 1)[0] == base and ":" not in model for tag in pulled)
+
+
+def _knowledge_dir(project_root: Path, config=None) -> str:
+    """Configured knowledge directory (honors ``knowledge.directory``), best-effort.
+
+    Mirrors ``cli.commands.okf._knowledge_okf_dir`` so doctor inspects the same location
+    ingest writes to. Any config failure falls back to the documented default rather than
+    raising — doctor must keep running even with a broken config.
+
+    ``config`` is an optional pre-loaded config (default ``None`` loads as before), so a
+    single doctor invocation can reuse one ``load_config`` call across checks.
+    """
+    directory = ".devcouncil/knowledge"
+    try:
+        cfg = config if config is not None else load_config(project_root)
+        directory = cfg.knowledge.directory
+    except Exception:
+        pass
+    return directory
+
+
+def check_ingested_knowledge(project_root: Path, config=None) -> list[tuple[str, str, str]]:
+    """Best-effort health rows for ingested knowledge under ``<knowledge dir>/{okf,design}``.
+
+    Returns ``(component, status_markup, notes)`` rows for the doctor table. This is the
+    most common "ingested but silently broken" surface: an OKF bundle with a dangling
+    cross-link, or a design.md with broken token references, both validate clean to the
+    eye but degrade the prompt context. We therefore read+validate every ingested bundle
+    and lint the design system, reporting counts and any problems.
+
+    Never raises: any knowledge-layer failure becomes a ``WARN`` row, and an empty
+    knowledge area yields a neutral ``INFO`` row — a project that never ingested knowledge
+    is not a misconfiguration.
+    """
+    ok = "[green]OK[/green]"
+    warn = "[yellow]WARN[/yellow]"
+    info = "[cyan]INFO[/cyan]"
+    rows: list[tuple[str, str, str]] = []
+
+    directory = _knowledge_dir(project_root, config=config)
+    base = project_root / directory
+    okf_area = base / "okf"
+    design_md = base / "design" / "design.md"
+
+    # Identify ingested OKF bundles. `dev okf ingest` writes each bundle into its own
+    # subfolder under okf/; treat each such subdir as a bundle. If documents sit loose
+    # directly under okf/ (and there are no subfolder bundles), treat okf/ as one bundle.
+    # Choosing one or the other avoids double-counting documents via rglob.
+    bundle_dirs: list[Path] = []
+    if okf_area.is_dir():
+        try:
+            subdir_bundles = [
+                child
+                for child in sorted(okf_area.iterdir())
+                if child.is_dir() and any(child.rglob("*.md"))
+            ]
+        except Exception:
+            subdir_bundles = []
+        loose_docs = any(p.is_file() for p in okf_area.glob("*.md"))
+        if subdir_bundles:
+            bundle_dirs = subdir_bundles
+        elif loose_docs:
+            bundle_dirs = [okf_area]
+
+    has_design = design_md.is_file()
+
+    # Nothing ingested at all → neutral info line, not a failure.
+    if not bundle_dirs and not has_design:
+        rows.append(
+            (
+                "Ingested knowledge",
+                info,
+                f"No ingested knowledge under {directory}/ (okf/, design/). "
+                "Add some with 'dev okf ingest <bundle>'.",
+            )
+        )
+        return rows
+
+    # --- OKF bundles -----------------------------------------------------------------
+    if bundle_dirs:
+        from devcouncil.knowledge.okf import read_bundle, validate_bundle
+
+        total_docs = 0
+        problems: list[str] = []
+        for bdir in bundle_dirs:
+            try:
+                bundle = read_bundle(bdir)
+                total_docs += len(bundle.documents)
+                problems.extend(validate_bundle(bundle))
+            except Exception as exc:  # never let a malformed bundle crash doctor
+                problems.append(f"{bdir.name}: failed to read bundle ({exc})")
+        summary = f"{len(bundle_dirs)} bundle(s), {total_docs} document(s)"
+        if problems:
+            preview = "; ".join(problems[:5])
+            extra = "" if len(problems) <= 5 else f" (+{len(problems) - 5} more)"
+            rows.append(
+                (
+                    "Ingested OKF",
+                    warn,
+                    f"{summary}: {len(problems)} validation problem(s): {preview}{extra}.",
+                )
+            )
+        else:
+            rows.append(("Ingested OKF", ok, f"{summary}; no validation problems."))
+
+    # --- Design system ----------------------------------------------------------------
+    if has_design:
+        from devcouncil.knowledge.design import lint, parse_design_md
+
+        try:
+            findings = lint(parse_design_md(design_md))
+        except Exception as exc:  # never let a malformed design.md crash doctor
+            rows.append(("Ingested design.md", warn, f"present, but lint failed: {exc}."))
+        else:
+            if findings:
+                preview = "; ".join(f.format() for f in findings[:5])
+                extra = "" if len(findings) <= 5 else f" (+{len(findings) - 5} more)"
+                rows.append(
+                    (
+                        "Ingested design.md",
+                        warn,
+                        f"present; {len(findings)} lint finding(s): {preview}{extra}.",
+                    )
+                )
+            else:
+                rows.append(("Ingested design.md", ok, "present; 0 lint findings."))
+
+    return rows
+
+
+def _add_logging_row(table, project_root: Path) -> None:
+    """Append a logging-health row: where the durable run log lives and how big it
+    is, so a user chasing a recurring failure knows exactly where to look."""
+    from devcouncil.telemetry.logging_setup import LOG_RELATIVE_PATH
+
+    log_path = project_root / LOG_RELATIVE_PATH
+    if log_path.exists():
+        size_kb = log_path.stat().st_size / 1024
+        detail = f"{log_path} ({size_kb:.0f} KB). View: dev logs tail"
+    else:
+        detail = f"Will write to {log_path} on first command. View: dev logs tail"
+    table.add_row("logging", "[green]OK[/green]", detail)
+
+
 def render_doctor_check(project_root: Path = Path(".")):
+    # Load config once for the whole invocation; the diagnostic checks below reuse
+    # this instead of re-reading config.yaml. None falls back to per-check loading.
+    try:
+        config = load_config(project_root)
+    except Exception:
+        config = None
+
     def _command_version(command: list[str]) -> str | None:
         executable = shutil.which(command[0])
         if not executable:
@@ -66,37 +283,48 @@ def render_doctor_check(project_root: Path = Path(".")):
     else:
         table.add_row("ripgrep (rg)", "[yellow]Missing[/yellow]", "ripgrep is highly recommended for fast repo mapping.")
 
-    # Check supported coding CLIs
-    codex_ver = _command_version(["codex", "--version"])
-    if codex_ver:
-        table.add_row(
-            "Codex CLI",
-            "[green]OK[/green]",
-            f"{codex_ver}. Setup: dev integrate codex --apply (or dev setup --integrate --apply).",
-        )
-    else:
-        table.add_row(
-            "Codex CLI",
-            "[yellow]Missing[/yellow]",
-            "Optional. Install Codex, then run 'dev integrate codex --apply' (or 'dev setup --integrate --apply').",
-        )
+    # Check supported coding CLIs (driven by the agent registry, so new
+    # built-in agents show up here without doctor edits).
+    for name in CODING_CLI_PROBE_ORDER:
+        info = CODING_CLI_INTEGRATION_INFO.get(name)
+        if info is None:
+            continue
+        version = None
+        for probe in CODING_CLI_VERSION_COMMANDS.get(name, ()):
+            version = _command_version(list(probe))
+            if version:
+                break
+        if version:
+            table.add_row(info.label, "[green]OK[/green]", f"{version}. Setup: {info.notes}.")
+        else:
+            table.add_row(
+                info.label,
+                "[yellow]Missing[/yellow]",
+                f"Optional. Install {info.label}, then use: {info.notes}.",
+            )
 
-    gemini_ver = _command_version(["gemini", "--version"])
-    if gemini_ver:
+    detected = detect_available_coding_cli(project_root)
+    resolved = resolve_automated_executor(project_root, None)
+    if detected:
         table.add_row(
-            "Gemini CLI",
+            "Recommended coding CLI",
             "[green]OK[/green]",
-            f"{gemini_ver}. Setup: dev integrate gemini --apply (or dev setup --integrate --apply).",
+            f"Use --executor {resolved} for dev go / dev run (detected on PATH).",
         )
     else:
         table.add_row(
-            "Gemini CLI",
+            "Recommended coding CLI",
             "[yellow]Missing[/yellow]",
-            "Optional. Install Gemini CLI, then run 'dev integrate gemini --apply' (or 'dev setup --integrate --apply').",
+            "No built-in coding CLI on PATH. Run dev integrate recommend after installing one.",
         )
 
+    # Ingested-knowledge health (added before the provider branch so it appears on every
+    # code path, including the early returns for ollama / unsupported providers).
+    for component, status, notes in check_ingested_knowledge(project_root, config=config):
+        table.add_row(component, status, notes)
+
     try:
-        provider = load_config(project_root).models.provider
+        provider = config.models.provider if config is not None else "openrouter"
     except Exception:
         provider = "openrouter"
     try:
@@ -108,6 +336,111 @@ def render_doctor_check(project_root: Path = Path(".")):
             "[red]Unsupported[/red]",
             f"{provider} is configured, but this runtime supports: {supported}.",
         )
+        _add_logging_row(table, project_root)
+        console.print(table)
+        return
+    if provider == "ollama":
+        # Use the provider's own resolver so the displayed URL reflects OLLAMA_HOST
+        # (with scheme/-/v1 normalization), not just OLLAMA_BASE_URL.
+        from devcouncil.execution.prompt_builder import MAX_PROMPT_CHARS
+        from devcouncil.llm.provider import OllamaProvider
+
+        base_url = OllamaProvider._resolve_base_url()
+        num_ctx = OllamaProvider._resolve_num_ctx()
+        # DevCouncil's planning prompts reach ~MAX_PROMPT_CHARS chars (~4 chars/token);
+        # recommend a context window that covers the prompt plus headroom for output.
+        recommended_ctx = 16384
+        min_ctx = max(8192, (MAX_PROMPT_CHARS // 4))
+        table.add_row(
+            "OLLAMA",
+            "[green]OK[/green]",
+            f"Local provider; no API key required (server: {base_url}).",
+        )
+
+        # Is the local Ollama server actually up? A native /api/version probe is
+        # cheap and turns the most common failure ("provider configured but
+        # `ollama serve` not running") into an actionable row instead of a
+        # connection traceback on the first model call.
+        reachable, detail = _probe_ollama(base_url)
+        if reachable:
+            table.add_row("OLLAMA server", "[green]OK[/green]", detail)
+        else:
+            table.add_row(
+                "OLLAMA server",
+                "[yellow]WARN[/yellow]",
+                f"{detail} Start it with 'ollama serve' (or 'brew services start ollama').",
+            )
+
+        # A reachable server with the configured model NOT pulled is the most common
+        # "all-green doctor, 404 on first call" trap. Verify the role models exist locally.
+        if reachable and config is not None:
+            try:
+                configured_models = sorted(
+                    {role.model for role in config.models.roles.values() if role.model}
+                )
+            except Exception:
+                configured_models = []
+            queried_ok, pulled = _probe_ollama_models(base_url)
+            if not queried_ok:
+                table.add_row(
+                    "OLLAMA models",
+                    "[yellow]WARN[/yellow]",
+                    "Could not list pulled models (/api/tags). Ensure each configured model is pulled.",
+                )
+            elif not configured_models:
+                table.add_row(
+                    "OLLAMA models",
+                    "[yellow]WARN[/yellow]",
+                    "No role models configured; run 'dev setup --provider ollama --model <model>'.",
+                )
+            else:
+                missing = [m for m in configured_models if not _ollama_model_present(m, pulled)]
+                if missing:
+                    pulls = "; ".join(f"ollama pull {m}" for m in missing)
+                    table.add_row(
+                        "OLLAMA models",
+                        "[yellow]WARN[/yellow]",
+                        f"Configured model(s) not pulled: {', '.join(missing)}. Pull first: {pulls}.",
+                    )
+                else:
+                    table.add_row(
+                        "OLLAMA models",
+                        "[green]OK[/green]",
+                        f"All configured models present locally ({', '.join(configured_models)}).",
+                    )
+
+        if num_ctx is None:
+            table.add_row(
+                "OLLAMA num_ctx",
+                "[yellow]WARN[/yellow]",
+                f"OLLAMA_NUM_CTX not set — Ollama's small default (~2048-4096) will "
+                f"truncate DevCouncil's large planning prompts. Set OLLAMA_NUM_CTX={recommended_ctx}.",
+            )
+        elif num_ctx < min_ctx:
+            table.add_row(
+                "OLLAMA num_ctx",
+                "[yellow]WARN[/yellow]",
+                f"OLLAMA_NUM_CTX={num_ctx} may be too small for planning prompts "
+                f"(~{MAX_PROMPT_CHARS // 4} tokens); recommend >= {recommended_ctx}.",
+            )
+        else:
+            table.add_row("OLLAMA num_ctx", "[green]OK[/green]", f"context window = {num_ctx} tokens.")
+
+        # Local model size is bounded by host memory — unified RAM on Apple Silicon,
+        # VRAM on a discrete-GPU box, system RAM otherwise. Surface a model that will
+        # actually fit on this host (any OS), not a one-size default.
+        from devcouncil import hardware
+
+        host = hardware.describe_host()
+        table.add_row(
+            host.platform_label,
+            "[green]OK[/green]",
+            f"{host.chip_label}, {host.memory_label}. "
+            f"Recommended local model: {host.recommended_ollama_model} "
+            f"(dev setup --provider ollama --model {host.recommended_ollama_model}).",
+        )
+
+        _add_logging_row(table, project_root)
         console.print(table)
         return
     env_var = provider_api_key_env_var(provider)
@@ -116,9 +449,33 @@ def render_doctor_check(project_root: Path = Path(".")):
         table.add_row(env_var, "[green]OK[/green]", f"Found in environment for {provider}.")
     elif local_secrets.get(env_var):
         table.add_row(env_var, "[green]OK[/green]", f"Found in .devcouncil/secrets.env for {provider}.")
+    elif provider == "vertexai" and get_gcloud_access_token():
+        table.add_row(env_var, "[green]OK[/green]", "Resolvable via gcloud auth print-access-token.")
+        table.caption = "Resolvable via gcloud auth print-access-token."
     else:
         table.add_row(env_var, "[yellow]Missing[/yellow]", f"Required if using {provider} provider. Run 'dev setup'.")
 
+    if provider == "vertexai":
+        project = (
+            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")
+        )
+        if project:
+            source = "environment" if os.environ.get("VERTEXAI_PROJECT") or os.environ.get("GOOGLE_CLOUD_PROJECT") else ".devcouncil/secrets.env"
+            table.add_row("VERTEXAI_PROJECT", "[green]OK[/green]", f"Found in {source}.")
+        else:
+            table.add_row(
+                "VERTEXAI_PROJECT",
+                "[yellow]Missing[/yellow]",
+                "Required for vertexai. Run 'dev setup --provider vertexai --vertex-project PROJECT_ID'.",
+            )
+
+        location = os.environ.get("VERTEXAI_LOCATION") or local_secrets.get("VERTEXAI_LOCATION", "global")
+        table.add_row("VERTEXAI_LOCATION", "[green]OK[/green]", location)
+
+    _add_logging_row(table, project_root)
     console.print(table)