specsmith 0.10.1.dev272__tar.gz → 0.10.1.dev277__tar.gz

{specsmith-0.10.1.dev272/src/specsmith.egg-info → specsmith-0.10.1.dev277}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.10.1.dev272
+Version: 0.10.1.dev277
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT
@@ -78,8 +78,6 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue&cacheSeconds=60)](https://pypi.org/project/specsmith/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![VS Code Extension](https://img.shields.io/badge/VS%20Code-AEE%20Workbench-4ec9b0?logo=visualstudiocode)](https://github.com/BitConcepts/specsmith-vscode)
-
 **Applied Epistemic Engineering toolkit for AI-assisted development.**
 
 > Intelligence proposes. Constraints decide. The ledger remembers.
@@ -142,23 +140,15 @@ specsmith phase set requirements  # jump to a specific phase
 specsmith phase list     # list all phases
 ```
 
-The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the VS Code
-Settings Panel. Each phase has a checklist of file/command criteria, recommended commands,
-and a readiness percentage.
+The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the
+Kairos Governance page. Each phase has a checklist of file/command criteria, recommended
+commands, and a readiness percentage.
 
 ---
 
 ## Install
 
-**Recommended — via the VS Code extension (creates a project-isolated environment):**
-
-1. Install the [specsmith AEE Workbench](https://github.com/BitConcepts/specsmith-vscode) VS Code extension
-2. Open `Ctrl+Shift+,` (⚙ specsmith Settings)
-3. Click **🔒 Create Environment** — creates `~/.specsmith/venv/` with specsmith + your provider packages
-
-The extension uses this environment for all agent sessions and terminal commands.
-
-**Or via pipx (system-wide):**
+**Recommended — via pipx (works with Kairos, any terminal, and CI):**
 
 ```bash
 pipx install specsmith                    # core CLI + epistemic library
@@ -316,36 +306,20 @@ requirement, test, and work-item identifiers Specsmith assigned.
 
 ---
 
-## VS Code Extension
+## Kairos — Flagship Terminal Client
 
-The **specsmith AEE Workbench** VS Code extension is the flagship client:
+**[Kairos](https://github.com/BitConcepts/kairos)** is the recommended terminal client for specsmith.
+Kairos spawns specsmith as a managed governance child process at startup and routes all
+preflight, verify, and BYOE proxy calls through it. The Governance settings page shows live
+specsmith status, version, and one-click update.
 
-```
-# VS Code: Ctrl+Shift+P → specsmith: New Agent Session
-# Settings:         Ctrl+Shift+,     (⚙ specsmith Settings — global)
-# Project Settings: Ctrl+Shift+G     (⚙ Project Settings — per-project)
+```bash
+# Kairos starts specsmith automatically; or run manually:
+specsmith governance-serve --port 7700 --project-dir .
 ```
 
-**Key features:**
-- **Dual-panel architecture** — **⚙ specsmith Settings** (global: venv, version, Ollama, system)
-  and **⚙ Project Settings** (per-project: scaffold, tools, files, actions, execution)
-- **Global environment management** — `~/.specsmith/venv/` with Create / Update / Rebuild / Delete;
-  persistent restart banner; Remove System Installs cleanup button
-- **VCS context at session start** — git status + recent commits shown in chat and in system prompt
-- **Execution profiles** — safe / standard / open / admin; custom allow/block command lists
-- **AEE phase indicator** — shows current phase with readiness %, Next Phase button, phase selector
-- **AI agent sessions** — independent process per project, JSONL bridge, chat with file injection
-- **AG2 agent shell** — Planner/Builder/Verifier agents over Ollama in Actions tab
-- **Agent tab** — per-project provider/model/context/iteration config (overrides global defaults)
-- **Live model listing** — Anthropic, OpenAI, Gemini, Mistral, local Ollama (GPU-aware)
-- **Ollama model catalog** — 16 models, 4 tiers, GPU-aware recommendations, filter by installed/available
-- **Ollama integration** — model manager (update/remove/update-all), version check, upgrade
-- **FPGA/HDL tool support** — vivado, gtkwave, vsg, ghdl, verilator, yosys, nextpnr, and 15 more
-- **Tool installer** — scan installed tools; one-click install via winget/brew/apt for missing tools
-- **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain)
-- **Update checker** — PyPI version check, auto-checks on panel open, release channel selector
-
-**[→ specsmith-vscode on GitHub](https://github.com/BitConcepts/specsmith-vscode)**
+The VS Code extension (`specsmith-vscode`) has been **deprecated** in favour of Kairos.
+Use `pipx install specsmith` for standalone CLI usage from any terminal.
 
 ---
 
@@ -353,7 +327,7 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
 
 specsmith is open source and built by a small team. Every bit of support helps:
 
-- ⭐ **Star** [specsmith](https://github.com/BitConcepts/specsmith) and [specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode) on GitHub
+- ⭐ **Star** [specsmith](https://github.com/BitConcepts/specsmith) and [kairos](https://github.com/BitConcepts/kairos) on GitHub
 - 📣 **Tell your friends and colleagues** — word of mouth is our best marketing
 - 🐛 **Report bugs** via [GitHub Issues](https://github.com/BitConcepts/specsmith/issues) — even small ones help
 - 💡 **Suggest features** via [GitHub Discussions](https://github.com/BitConcepts/specsmith/discussions) — we read every suggestion
@@ -376,8 +350,8 @@ specsmith ollama suggest requirements  # task-based recommendations
 specsmith ollama list                  # show installed models
 ```
 
-GPU-aware context sizing in the VS Code extension: 4K/8K/16K/32K tokens based on detected VRAM.
-Override with `specsmith.ollamaContextLength` in VS Code settings.
+GPU-aware context sizing: 4K/8K/16K/32K tokens based on detected VRAM.
+Override via `SPECSMITH_OLLAMA_CONTEXT_LENGTH` env var or `ollama.context_length` in `.specsmith/config.yml`.
 
 ---
 
@@ -478,20 +452,20 @@ Use cases: linguistics research, compliance pipelines, AI alignment, patent pros
 
 specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`
 in this repo to check its governance health. This means every feature we add to specsmith is
-immediately dogfooded on specsmith itself. The [VS Code extension](https://github.com/BitConcepts/specsmith-vscode)
-is developed alongside it as the flagship client.
+immediately dogfooded on specsmith itself. [Kairos](https://github.com/BitConcepts/kairos)
+is the companion terminal and flagship client.
 
 ## Documentation
 
 **[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,
-command reference, project types, tool registry, governance model, Ollama guide, VS Code extension.
+command reference, project types, tool registry, governance model, Ollama guide, Kairos integration.
 
 ## Links
 
 - [PyPI](https://pypi.org/project/specsmith/)
 - [Documentation](https://specsmith.readthedocs.io)
 - [Changelog](CHANGELOG.md)
-- [VS Code Extension](https://github.com/BitConcepts/specsmith-vscode)
+- [Kairos terminal client](https://github.com/BitConcepts/kairos)
 - [Contributing](CONTRIBUTING.md)
 - [Security](SECURITY.md)
 

{specsmith-0.10.1.dev272 → specsmith-0.10.1.dev277}/README.md

@@ -6,8 +6,6 @@
 [![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue&cacheSeconds=60)](https://pypi.org/project/specsmith/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![VS Code Extension](https://img.shields.io/badge/VS%20Code-AEE%20Workbench-4ec9b0?logo=visualstudiocode)](https://github.com/BitConcepts/specsmith-vscode)
-
 **Applied Epistemic Engineering toolkit for AI-assisted development.**
 
 > Intelligence proposes. Constraints decide. The ledger remembers.
@@ -70,23 +68,15 @@ specsmith phase set requirements  # jump to a specific phase
 specsmith phase list     # list all phases
 ```
 
-The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the VS Code
-Settings Panel. Each phase has a checklist of file/command criteria, recommended commands,
-and a readiness percentage.
+The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the
+Kairos Governance page. Each phase has a checklist of file/command criteria, recommended
+commands, and a readiness percentage.
 
 ---
 
 ## Install
 
-**Recommended — via the VS Code extension (creates a project-isolated environment):**
-
-1. Install the [specsmith AEE Workbench](https://github.com/BitConcepts/specsmith-vscode) VS Code extension
-2. Open `Ctrl+Shift+,` (⚙ specsmith Settings)
-3. Click **🔒 Create Environment** — creates `~/.specsmith/venv/` with specsmith + your provider packages
-
-The extension uses this environment for all agent sessions and terminal commands.
-
-**Or via pipx (system-wide):**
+**Recommended — via pipx (works with Kairos, any terminal, and CI):**
 
 ```bash
 pipx install specsmith                    # core CLI + epistemic library
@@ -244,36 +234,20 @@ requirement, test, and work-item identifiers Specsmith assigned.
 
 ---
 
-## VS Code Extension
+## Kairos — Flagship Terminal Client
 
-The **specsmith AEE Workbench** VS Code extension is the flagship client:
+**[Kairos](https://github.com/BitConcepts/kairos)** is the recommended terminal client for specsmith.
+Kairos spawns specsmith as a managed governance child process at startup and routes all
+preflight, verify, and BYOE proxy calls through it. The Governance settings page shows live
+specsmith status, version, and one-click update.
 
-```
-# VS Code: Ctrl+Shift+P → specsmith: New Agent Session
-# Settings:         Ctrl+Shift+,     (⚙ specsmith Settings — global)
-# Project Settings: Ctrl+Shift+G     (⚙ Project Settings — per-project)
+```bash
+# Kairos starts specsmith automatically; or run manually:
+specsmith governance-serve --port 7700 --project-dir .
 ```
 
-**Key features:**
-- **Dual-panel architecture** — **⚙ specsmith Settings** (global: venv, version, Ollama, system)
-  and **⚙ Project Settings** (per-project: scaffold, tools, files, actions, execution)
-- **Global environment management** — `~/.specsmith/venv/` with Create / Update / Rebuild / Delete;
-  persistent restart banner; Remove System Installs cleanup button
-- **VCS context at session start** — git status + recent commits shown in chat and in system prompt
-- **Execution profiles** — safe / standard / open / admin; custom allow/block command lists
-- **AEE phase indicator** — shows current phase with readiness %, Next Phase button, phase selector
-- **AI agent sessions** — independent process per project, JSONL bridge, chat with file injection
-- **AG2 agent shell** — Planner/Builder/Verifier agents over Ollama in Actions tab
-- **Agent tab** — per-project provider/model/context/iteration config (overrides global defaults)
-- **Live model listing** — Anthropic, OpenAI, Gemini, Mistral, local Ollama (GPU-aware)
-- **Ollama model catalog** — 16 models, 4 tiers, GPU-aware recommendations, filter by installed/available
-- **Ollama integration** — model manager (update/remove/update-all), version check, upgrade
-- **FPGA/HDL tool support** — vivado, gtkwave, vsg, ghdl, verilator, yosys, nextpnr, and 15 more
-- **Tool installer** — scan installed tools; one-click install via winget/brew/apt for missing tools
-- **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain)
-- **Update checker** — PyPI version check, auto-checks on panel open, release channel selector
-
-**[→ specsmith-vscode on GitHub](https://github.com/BitConcepts/specsmith-vscode)**
+The VS Code extension (`specsmith-vscode`) has been **deprecated** in favour of Kairos.
+Use `pipx install specsmith` for standalone CLI usage from any terminal.
 
 ---
 
@@ -281,7 +255,7 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
 
 specsmith is open source and built by a small team. Every bit of support helps:
 
-- ⭐ **Star** [specsmith](https://github.com/BitConcepts/specsmith) and [specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode) on GitHub
+- ⭐ **Star** [specsmith](https://github.com/BitConcepts/specsmith) and [kairos](https://github.com/BitConcepts/kairos) on GitHub
 - 📣 **Tell your friends and colleagues** — word of mouth is our best marketing
 - 🐛 **Report bugs** via [GitHub Issues](https://github.com/BitConcepts/specsmith/issues) — even small ones help
 - 💡 **Suggest features** via [GitHub Discussions](https://github.com/BitConcepts/specsmith/discussions) — we read every suggestion
@@ -304,8 +278,8 @@ specsmith ollama suggest requirements  # task-based recommendations
 specsmith ollama list                  # show installed models
 ```
 
-GPU-aware context sizing in the VS Code extension: 4K/8K/16K/32K tokens based on detected VRAM.
-Override with `specsmith.ollamaContextLength` in VS Code settings.
+GPU-aware context sizing: 4K/8K/16K/32K tokens based on detected VRAM.
+Override via `SPECSMITH_OLLAMA_CONTEXT_LENGTH` env var or `ollama.context_length` in `.specsmith/config.yml`.
 
 ---
 
@@ -406,20 +380,20 @@ Use cases: linguistics research, compliance pipelines, AI alignment, patent pros
 
 specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`
 in this repo to check its governance health. This means every feature we add to specsmith is
-immediately dogfooded on specsmith itself. The [VS Code extension](https://github.com/BitConcepts/specsmith-vscode)
-is developed alongside it as the flagship client.
+immediately dogfooded on specsmith itself. [Kairos](https://github.com/BitConcepts/kairos)
+is the companion terminal and flagship client.
 
 ## Documentation
 
 **[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,
-command reference, project types, tool registry, governance model, Ollama guide, VS Code extension.
+command reference, project types, tool registry, governance model, Ollama guide, Kairos integration.
 
 ## Links
 
 - [PyPI](https://pypi.org/project/specsmith/)
 - [Documentation](https://specsmith.readthedocs.io)
 - [Changelog](CHANGELOG.md)
-- [VS Code Extension](https://github.com/BitConcepts/specsmith-vscode)
+- [Kairos terminal client](https://github.com/BitConcepts/kairos)
 - [Contributing](CONTRIBUTING.md)
 - [Security](SECURITY.md)
 

{specsmith-0.10.1.dev272 → specsmith-0.10.1.dev277}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.10.1.dev272"
+version = "0.10.1.dev277"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

{specsmith-0.10.1.dev272 → specsmith-0.10.1.dev277}/src/specsmith/cli.py

@@ -5066,6 +5066,113 @@ def instinct_import(file_path: str, project_dir: str) -> None:
 main.add_command(instinct_group)
 
 
+# ---------------------------------------------------------------------------
+# specsmith config — global configuration (editor, etc.)
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="config")
+def config_group() -> None:
+    """Manage global specsmith configuration.
+
+    Settings are stored in ``~/.specsmith/config.toml``.
+    """
+
+
+@config_group.command(name="editor")
+@click.argument("command", required=False, default=None)
+@click.option(
+    "--list",
+    "list_editors",
+    is_flag=True,
+    default=False,
+    help="List all editors detected on this machine.",
+)
+@click.option(
+    "--set",
+    "set_cmd",
+    default="",
+    help="Set the preferred editor (saved to ~/.specsmith/config.toml).",
+)
+def config_editor_cmd(
+    command: str | None,
+    list_editors: bool,
+    set_cmd: str,
+) -> None:
+    """Manage the editor used by specsmith to open files.
+
+    \b
+    Resolution order:
+      1. $EDITOR environment variable  (highest priority)
+      2. 'editor' key in ~/.specsmith/config.toml
+      3. Auto-detected editor for this platform
+
+    \b
+    Examples:
+      specsmith config editor           # show currently resolved editor
+      specsmith config editor --list    # show all detected editors
+      specsmith config editor --set code  # set VS Code as preferred editor
+    """
+    from specsmith.editor import (
+        list_detected_editors,
+        resolve_editor,
+        set_editor_preference,
+    )
+
+    # --set flag takes precedence
+    if set_cmd or (command and not list_editors):
+        target = set_cmd or command or ""
+        if not target:
+            console.print("[red]Error:[/red] specify a command, e.g. --set code")
+            raise SystemExit(1)
+        saved_path = set_editor_preference(target)
+        console.print(
+            f"[green]\u2713[/green] Saved editor preference: [bold]{target}[/bold]\n"
+            f"  Config: {saved_path}"
+        )
+        return
+
+    if list_editors:
+        candidates = list_detected_editors()
+        if not candidates:
+            console.print("[yellow]No editors detected on this machine.[/yellow]")
+            console.print(
+                "  Install VS Code, Neovim, or another editor and re-run, or set $EDITOR manually."
+            )
+            return
+        console.print("[bold]Detected editors:[/bold]\n")
+        for c in candidates:
+            path_hint = f"  [dim]({c.path})[/dim]" if c.path else ""
+            console.print(f"  [cyan]{c.command:<20}[/cyan] {c.name}{path_hint}")
+        return
+
+    # Default: show the currently resolved editor
+    import os
+
+    env_val = os.environ.get("EDITOR", "").strip()
+    resolved = resolve_editor()
+
+    console.print("[bold]Editor configuration[/bold]\n")
+    if env_val:
+        console.print("  Source:   [green]$EDITOR[/green] environment variable")
+        console.print(f"  Command:  [bold]{env_val}[/bold]")
+    elif resolved:
+        console.print("  Source:   auto-detected")
+        console.print(f"  Command:  [bold]{resolved}[/bold]")
+    else:
+        console.print("  [yellow]No editor resolved.[/yellow]")
+        console.print("  Set $EDITOR or run [bold]specsmith config editor --set <command>[/bold].")
+    console.print()
+    console.print(
+        "  [dim]Override: set $EDITOR, or run "
+        "'specsmith config editor --set <cmd>' to persist.[/dim]"
+    )
+    console.print("  [dim]List available editors: 'specsmith config editor --list'[/dim]")
+
+
+main.add_command(config_group)
+
+
 # ---------------------------------------------------------------------------
 # Kill-switch / emergency stop (REG-005)
 # ---------------------------------------------------------------------------

specsmith-0.10.1.dev277/src/specsmith/editor.py

@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Cross-platform $EDITOR auto-detection for specsmith.
+
+Resolution order (highest to lowest priority):
+  1. ``$EDITOR`` environment variable
+  2. ``editor`` key in ``~/.specsmith/config.toml`` or project ``.specsmith/config.yml``
+  3. Auto-detection: probe PATH + well-known install locations per platform
+
+Usage::
+
+    from specsmith.editor import resolve_editor, list_detected_editors, set_editor_preference
+
+    # What will specsmith use to open files?
+    editor = resolve_editor()          # e.g. "code", "notepad++", "nvim"
+
+    # Show all detected editors on this machine:
+    editors = list_detected_editors()  # list of (name, path) tuples
+
+    # Persist a preference:
+    set_editor_preference("code")      # writes to ~/.specsmith/config.toml
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+from pathlib import Path
+from typing import NamedTuple
+
+__all__ = [
+    "EditorCandidate",
+    "list_detected_editors",
+    "resolve_editor",
+    "set_editor_preference",
+]
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+class EditorCandidate(NamedTuple):
+    """A discovered editor."""
+
+    name: str
+    """Short display name (e.g. 'VS Code', 'Notepad++')."""
+    command: str
+    """The executable / command to invoke (e.g. 'code', 'notepad++')."""
+    path: str | None
+    """Resolved absolute path, or None if only found via PATH probe."""
+
+
+# ---------------------------------------------------------------------------
+# Platform-specific candidate lists
+# ---------------------------------------------------------------------------
+
+#: Ordered list of (display_name, command) pairs for each platform.
+#: The first entry that resolves wins for auto-detection.
+_WINDOWS_CANDIDATES: list[tuple[str, str | list[str]]] = [
+    # VS Code (most popular cross-platform)
+    ("VS Code", "code"),
+    # Cursor (AI-first VS Code fork)
+    ("Cursor", "cursor"),
+    # Notepad++ — check common install paths since it's not always on PATH
+    ("Notepad++", r"%LOCALAPPDATA%\Programs\Notepad++\notepad++.exe"),
+    ("Notepad++", r"%PROGRAMFILES%\Notepad++\notepad++.exe"),
+    ("Notepad++", r"%PROGRAMFILES(X86)%\Notepad++\notepad++.exe"),
+    ("Notepad++", "notepad++"),
+    # Neovim (scoop / choco)
+    ("Neovim", "nvim"),
+    # Vim (git-bash / scoop / choco)
+    ("Vim", "vim"),
+    # Sublime Text
+    ("Sublime Text", r"%PROGRAMFILES%\Sublime Text\subl.exe"),
+    ("Sublime Text", r"%PROGRAMFILES%\Sublime Text 4\subl.exe"),
+    ("Sublime Text", "subl"),
+    # Built-in last resort
+    ("Notepad", "notepad"),
+]
+
+_MACOS_CANDIDATES: list[tuple[str, str | list[str]]] = [
+    ("VS Code", "code"),
+    ("Cursor", "cursor"),
+    ("Neovim", "nvim"),
+    ("Vim", "vim"),
+    ("BBEdit", "/Applications/BBEdit.app/Contents/OS X Resources/bbedit"),
+    ("BBEdit", "bbedit"),
+    ("Nano", "nano"),
+    # TextEdit — open -e opens the file in TextEdit
+    ("TextEdit", ["/usr/bin/open", "-e"]),
+]
+
+_LINUX_CANDIDATES: list[tuple[str, str | list[str]]] = [
+    ("VS Code", "code"),
+    ("Cursor", "cursor"),
+    ("Neovim", "nvim"),
+    ("Vim", "vim"),
+    ("Nano", "nano"),
+    ("Kate", "kate"),
+    ("gedit", "gedit"),
+    ("xed", "xed"),
+    ("Mousepad", "mousepad"),
+    ("Geany", "geany"),
+    ("Micro", "micro"),
+    ("Helix", "hx"),
+]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _expand(path_str: str) -> str:
+    """Expand environment variables in a path string (Windows-style %VAR%)."""
+    return os.path.expandvars(path_str)
+
+
+def _probe_command(cmd: str | list[str]) -> str | None:
+    """Return the resolved path for *cmd* if it is runnable, else None."""
+    # Multi-token command (e.g. ["open", "-e"]) — probe the first token.
+    executable = cmd[0] if isinstance(cmd, list) else cmd
+
+    # Expand env vars in Windows-style paths (%PROGRAMFILES%\...)
+    expanded = _expand(executable)
+    if os.sep in expanded or "/" in expanded:
+        # Looks like an absolute/relative path — check if the file exists
+        p = Path(expanded)
+        if p.is_file() and os.access(p, os.X_OK):
+            return str(p)
+        return None
+
+    # Plain command name — search PATH
+    found = shutil.which(executable)
+    return found if found else None
+
+
+def _platform_candidates() -> list[tuple[str, str | list[str]]]:
+    system = platform.system()
+    if system == "Windows":
+        return _WINDOWS_CANDIDATES
+    if system == "Darwin":
+        return _MACOS_CANDIDATES
+    return _LINUX_CANDIDATES  # Linux / BSD / WSL
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def list_detected_editors() -> list[EditorCandidate]:
+    """Return all editor candidates that are runnable on this machine.
+
+    Each ``EditorCandidate`` is unique by *command* (the first token for
+    multi-token commands). Duplicates (e.g. multiple Notepad++ paths) are
+    deduplicated to the first match.
+
+    Returns:
+        Ordered list of :class:`EditorCandidate`, best-first.
+    """
+    seen_commands: set[str] = set()
+    result: list[EditorCandidate] = []
+
+    for display_name, cmd in _platform_candidates():
+        cmd_key = cmd[0] if isinstance(cmd, list) else cmd
+        if cmd_key in seen_commands:
+            continue
+
+        resolved = _probe_command(cmd)
+        if resolved is None and isinstance(cmd, str):
+            # For plain command names that aren't found, skip
+            continue
+        if resolved is not None:
+            seen_commands.add(cmd_key)
+            result.append(
+                EditorCandidate(
+                    name=display_name,
+                    command=cmd_key,
+                    path=resolved if resolved != cmd_key else None,
+                )
+            )
+
+    return result
+
+
+def resolve_editor() -> str | None:
+    """Return the editor command specsmith should use, or ``None`` if unresolvable.
+
+    Resolution order:
+    1. ``$EDITOR`` environment variable (user's explicit choice)
+    2. ``editor`` key in ``~/.specsmith/config.toml``
+    3. First auto-detected editor on this machine
+
+    Returns:
+        The command string (e.g. ``"code"``, ``"notepad++"``, ``"nvim"``),
+        or ``None`` if nothing was found.
+    """
+    # Priority 1: $EDITOR env var
+    env_editor = os.environ.get("EDITOR", "").strip()
+    if env_editor:
+        return env_editor
+
+    # Priority 2: ~/.specsmith/config.toml
+    config_editor = _read_config_editor()
+    if config_editor:
+        return config_editor
+
+    # Priority 3: auto-detect
+    candidates = list_detected_editors()
+    return candidates[0].command if candidates else None
+
+
+def set_editor_preference(command: str) -> Path:
+    """Persist *command* as the preferred editor in ``~/.specsmith/config.toml``.
+
+    Creates the file and directory if they do not exist.
+
+    Args:
+        command: The editor command to save (e.g. ``"code"``, ``"nvim"``).
+
+    Returns:
+        The path of the written config file.
+    """
+    config_path = _global_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Read existing content (if any) and update/insert the editor key
+    existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+    lines = existing.splitlines()
+
+    # Find and replace an existing `editor = ...` line, or append
+    new_lines: list[str] = []
+    found = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("editor") and "=" in stripped:
+            new_lines.append(f'editor = "{command}"')
+            found = True
+        else:
+            new_lines.append(line)
+    if not found:
+        new_lines.append(f'editor = "{command}"')
+
+    config_path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+    return config_path
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _global_config_path() -> Path:
+    """Return ``~/.specsmith/config.toml``."""
+    return Path.home() / ".specsmith" / "config.toml"
+
+
+def _read_config_editor() -> str | None:
+    """Read the ``editor`` key from ``~/.specsmith/config.toml``."""
+    config_path = _global_config_path()
+    if not config_path.is_file():
+        return None
+    try:
+        # Minimal TOML parser for the editor key — avoids a tomllib dependency on 3.10
+        for line in config_path.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("editor") and "=" in stripped:
+                _, _, value = stripped.partition("=")
+                value = value.strip().strip('"').strip("'")
+                if value:
+                    return value
+    except OSError:
+        pass
+    return None