superqode 0.2.2__tar.gz → 0.2.3__tar.gz

{superqode-0.2.2 → superqode-0.2.3}/CHANGELOG.md

@@ -7,24 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.2.1] - 2026-06-24
+## [0.2.3] - 2026-06-24
 
 ### Added
 
 - **TUI harness wizard** - Added a step-by-step `:harness wizard` flow for creating starter HarnessSpec files from the TUI, plus `:harness init` / flag shortcuts using the same wizard builder as the CLI.
 - **TUI CLI parity** - Exposed the remaining CLI command surface in the TUI command list and routed unsupported subcommands through the CLI runner so CLI-only workflows can be launched from the TUI.
+- **First harness documentation** - Documented the TUI and CLI wizard path for creating, loading, checking, and running a first HarnessSpec in a few steps.
 
 ### Fixed
 
 - **Smoke script source checkout support** - Made the Omnigent agent-session smoke script import SuperQode reliably when run directly from a checkout.
-- **Harness model routing** - Made `model_policy.primary` override the active TUI connection for harness runs and added a clear local-provider warning when an MLX-tagged model is routed through Ollama.
+- **Harness model routing** - Made `model_policy.primary` override the active TUI connection for harness runs while preserving valid Ollama model tags such as `*-mlx`.
 - **Harness wizard defaults** - Made Enter-through defaults in the TUI wizard create a runnable Qwen local harness with an explicit `ollama/qwen3-coder` model policy.
+- **Harness wizard final prompt** - Treated `yes`/`no` typed on the output-file step as the final load answer so the wizard no longer stores `yes` as a filename and loops back to the output prompt.
+- **Harness wizard output paths** - Picked the next available default output path such as `harness-2.yaml` when `harness.yaml` already exists, preventing default runs from bouncing back to the output prompt.
 - **Harness wizard loading** - Fixed the final “Load this harness now?” step so loaded harnesses remain visible after reconnect/disconnect state changes, and stale `SUPERQODE_HARNESS` paths no longer crash Pure Mode startup.
 - **Harness streaming** - Forwarded builtin harness `model_delta` events through Pure Mode so TUI harness runs no longer report `chunks=0` when the model did stream content.
 
 ### Changed
 
-- **Release metadata** - Bumped the package version and runtime `__version__` to `0.2.1`.
+- **Release metadata** - Bumped the package version and runtime `__version__` to `0.2.3`.
 
 ## [0.2.0] - 2026-06-23
 

{superqode-0.2.2/src/superqode.egg-info → superqode-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 0.2.2
+Version: 0.2.3
 Summary: SuperQode: harness engineering framework for coding agents, optimized for local and open models
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -230,7 +230,7 @@ Inside the TUI, the local-first MVP path is:
 | File | Purpose | Created by |
 | --- | --- | --- |
 | `superqode.yaml` | Project configuration: providers, endpoints, MCP, memory, defaults | `superqode config init` or `:init` |
-| `harness.yaml` | Portable agent run contract | `superqode harness init ...` |
+| `harness.yaml` | Portable agent run contract | `:harness wizard`, `superqode harness wizard`, or `superqode harness init ...` |
 | `superqode.local.yaml` | Local-first HarnessSpec generated for this machine | `:local init` or `superqode local init --repo .` |
 | `superqode.airplane.yaml` | Strict no-network HarnessSpec for offline local work | `:local airplane prepare` or `superqode local airplane prepare` |
 
@@ -242,7 +242,26 @@ superqode --print "inspect this repository and suggest the smallest next step"
 
 ### Your First Harness Run
 
-A harness is the repeatable contract for how an agent run behaves. Start with the default coding harness:
+A harness is the repeatable contract for how an agent run behaves. In the TUI, create and load your first harness without writing YAML:
+
+```text
+:connect local
+:harness wizard
+```
+
+Press Enter through the defaults for a runnable local coding harness, choose an output file, and answer `yes` when asked whether to load it. If `harness.yaml` already exists, the wizard uses the next available path such as `harness-2.yaml`.
+
+For the CLI path, start with the interactive wizard or the default coding template:
+
+```bash
+cd your-project
+superqode harness wizard
+superqode harness explain --spec harness.yaml
+superqode harness doctor --spec harness.yaml
+superqode harness run --spec harness.yaml --prompt "summarize the architecture"
+```
+
+Template shortcut:
 
 ```bash
 cd your-project

{superqode-0.2.2 → superqode-0.2.3}/README.md

@@ -102,7 +102,7 @@ Inside the TUI, the local-first MVP path is:
 | File | Purpose | Created by |
 | --- | --- | --- |
 | `superqode.yaml` | Project configuration: providers, endpoints, MCP, memory, defaults | `superqode config init` or `:init` |
-| `harness.yaml` | Portable agent run contract | `superqode harness init ...` |
+| `harness.yaml` | Portable agent run contract | `:harness wizard`, `superqode harness wizard`, or `superqode harness init ...` |
 | `superqode.local.yaml` | Local-first HarnessSpec generated for this machine | `:local init` or `superqode local init --repo .` |
 | `superqode.airplane.yaml` | Strict no-network HarnessSpec for offline local work | `:local airplane prepare` or `superqode local airplane prepare` |
 
@@ -114,7 +114,26 @@ superqode --print "inspect this repository and suggest the smallest next step"
 
 ### Your First Harness Run
 
-A harness is the repeatable contract for how an agent run behaves. Start with the default coding harness:
+A harness is the repeatable contract for how an agent run behaves. In the TUI, create and load your first harness without writing YAML:
+
+```text
+:connect local
+:harness wizard
+```
+
+Press Enter through the defaults for a runnable local coding harness, choose an output file, and answer `yes` when asked whether to load it. If `harness.yaml` already exists, the wizard uses the next available path such as `harness-2.yaml`.
+
+For the CLI path, start with the interactive wizard or the default coding template:
+
+```bash
+cd your-project
+superqode harness wizard
+superqode harness explain --spec harness.yaml
+superqode harness doctor --spec harness.yaml
+superqode harness run --spec harness.yaml --prompt "summarize the architecture"
+```
+
+Template shortcut:
 
 ```bash
 cd your-project

{superqode-0.2.2 → superqode-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "0.2.2"
+version = "0.2.3"
 description = "SuperQode: harness engineering framework for coding agents, optimized for local and open models"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-0.2.2 → superqode-0.2.3}/src/superqode/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{superqode-0.2.2 → superqode-0.2.3}/src/superqode/app_main.py

@@ -12007,7 +12007,7 @@ class SuperQodeApp(App):
                 "tool_call_format": "auto",
                 "workflow_preset": "single",
             },
-            "output": "harness.yaml",
+            "output": self._default_harness_wizard_output(),
             "load": True,
             "force": False,
         }
@@ -12130,6 +12130,11 @@ class SuperQodeApp(App):
                 answers["workflow_preset"] = choice
                 self._harness_wizard_next(state, "output")
             elif step == "output":
+                load_answer = self._parse_yes_no(raw) if raw else None
+                if load_answer is not None:
+                    state["load"] = load_answer
+                    self._finish_harness_wizard_flow(log)
+                    return True
                 if raw:
                     state["output"] = raw
                 self._harness_wizard_next(state, "load")
@@ -12161,6 +12166,17 @@ class SuperQodeApp(App):
         state.setdefault("history", []).append(state["step"])
         state["step"] = next_step
 
+    @staticmethod
+    def _default_harness_wizard_output() -> str:
+        base = Path("harness.yaml")
+        if not base.exists():
+            return str(base)
+        for index in range(2, 1000):
+            candidate = Path(f"harness-{index}.yaml")
+            if not candidate.exists():
+                return str(candidate)
+        return "harness-new.yaml"
+
     @staticmethod
     def _parse_yes_no(raw: str) -> bool | None:
         lowered = raw.strip().lower()
@@ -12274,11 +12290,11 @@ class SuperQodeApp(App):
                 default = " (default)" if key == "single" else ""
                 t.append(f"  {index}. {key:<22} {label}{default}\n", style=THEME["text"])
         elif step == "output":
-            t.append("  Step 9/9  Output file\n", style=f"bold {THEME['cyan']}")
+            t.append("  Step 9/10  Output file\n", style=f"bold {THEME['cyan']}")
             t.append(f"  Default: {state['output']}\n", style=THEME["muted"])
             t.append("  Example: harness.yaml\n", style=THEME["text"])
         elif step == "load":
-            t.append("  Final  Load this harness now?\n", style=f"bold {THEME['cyan']}")
+            t.append("  Step 10/10  Load this harness now?\n", style=f"bold {THEME['cyan']}")
             t.append("  Default: yes\n", style=THEME["muted"])
             t.append("  Answer: yes or no\n", style=THEME["text"])
 
@@ -12293,7 +12309,10 @@ class SuperQodeApp(App):
         load_after_write = bool(state.get("load", True))
 
         if output.exists() and not state.get("force", False):
-            log.add_error(f"{output} already exists. Type a different output path or cancel.")
+            state["output"] = self._default_harness_wizard_output()
+            log.add_error(
+                f"{output} already exists. Suggested next available path: {state['output']}"
+            )
             state["step"] = "output"
             self._render_harness_wizard_step(log)
             return

{superqode-0.2.2 → superqode-0.2.3}/src/superqode/pure_mode.py

@@ -168,12 +168,7 @@ class PureMode:
     @staticmethod
     def _validate_harness_route(provider: str, model: str) -> None:
         """Catch common local provider/model mismatches before streaming."""
-        if provider == "ollama" and model.lower().endswith("-mlx"):
-            raise RuntimeError(
-                "The active harness is trying to run an MLX-tagged model through Ollama: "
-                f"ollama/{model}. Use the exact Ollama model tag from `ollama list`, or set "
-                "`model_policy.primary: mlx/<model>` and connect with the MLX provider."
-            )
+        return
 
     def get_providers_for_picker(self) -> List[Dict[str, Any]]:
         """Get providers formatted for the TUI picker."""

{superqode-0.2.2 → superqode-0.2.3/src/superqode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 0.2.2
+Version: 0.2.3
 Summary: SuperQode: harness engineering framework for coding agents, optimized for local and open models
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -230,7 +230,7 @@ Inside the TUI, the local-first MVP path is:
 | File | Purpose | Created by |
 | --- | --- | --- |
 | `superqode.yaml` | Project configuration: providers, endpoints, MCP, memory, defaults | `superqode config init` or `:init` |
-| `harness.yaml` | Portable agent run contract | `superqode harness init ...` |
+| `harness.yaml` | Portable agent run contract | `:harness wizard`, `superqode harness wizard`, or `superqode harness init ...` |
 | `superqode.local.yaml` | Local-first HarnessSpec generated for this machine | `:local init` or `superqode local init --repo .` |
 | `superqode.airplane.yaml` | Strict no-network HarnessSpec for offline local work | `:local airplane prepare` or `superqode local airplane prepare` |
 
@@ -242,7 +242,26 @@ superqode --print "inspect this repository and suggest the smallest next step"
 
 ### Your First Harness Run
 
-A harness is the repeatable contract for how an agent run behaves. Start with the default coding harness:
+A harness is the repeatable contract for how an agent run behaves. In the TUI, create and load your first harness without writing YAML:
+
+```text
+:connect local
+:harness wizard
+```
+
+Press Enter through the defaults for a runnable local coding harness, choose an output file, and answer `yes` when asked whether to load it. If `harness.yaml` already exists, the wizard uses the next available path such as `harness-2.yaml`.
+
+For the CLI path, start with the interactive wizard or the default coding template:
+
+```bash
+cd your-project
+superqode harness wizard
+superqode harness explain --spec harness.yaml
+superqode harness doctor --spec harness.yaml
+superqode harness run --spec harness.yaml --prompt "summarize the architecture"
+```
+
+Template shortcut:
 
 ```bash
 cd your-project

{superqode-0.2.2 → superqode-0.2.3}/tests/test_harness_kernel.py

@@ -346,15 +346,17 @@ async def test_pure_mode_harness_primary_overrides_active_connection(monkeypatch
     assert created["config"].model == "qwen3.6:35b-mlx"
 
 
-def test_pure_mode_harness_warns_for_ollama_mlx_model(tmp_path: Path):
+def test_pure_mode_harness_allows_ollama_mlx_tagged_model(tmp_path: Path):
     from superqode.pure_mode import PureMode
 
     pure = PureMode()
     pure.set_harness(get_harness_template("no-tool"))
     assert pure.connect("ollama", "qwen3.6:35b-mlx", working_directory=tmp_path)
 
-    with pytest.raises(RuntimeError, match="MLX-tagged model through Ollama"):
-        pure._resolve_harness_route()
+    provider, model = pure._resolve_harness_route()
+
+    assert provider == "ollama"
+    assert model == "qwen3.6:35b-mlx"
 
 
 def test_pure_mode_set_harness_updates_visible_status(tmp_path: Path):

{superqode-0.2.2 → superqode-0.2.3}/tests/test_tui_smoke.py

@@ -1257,6 +1257,48 @@ def test_tui_harness_wizard_final_yes_loads_and_exits(tmp_path, monkeypatch):
     assert "Loaded harness my-harness" in rendered
 
 
+def test_tui_harness_wizard_yes_on_output_step_loads_default_path(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    app = make_app()
+    log = FakeLog()
+    app._show_command_output = lambda target_log, content, clear_log=True: target_log.write(content)
+
+    app._harness_cmd("wizard", log)
+    for _ in range(8):
+        app._handle_harness_wizard_input("", log)
+    assert "Output file" in render_plain(log.items[-1])
+
+    app._handle_harness_wizard_input("yes", log)
+
+    assert (tmp_path / "harness.yaml").exists()
+    assert not (tmp_path / "yes").exists()
+    assert app._awaiting_harness_wizard is False
+    assert app._harness_wizard_state is None
+    assert app._pure_mode is not None
+    status = app._pure_mode.get_status()["harness"]
+    assert status["enabled"] is True
+    assert status["path"].endswith("harness.yaml")
+
+
+def test_tui_harness_wizard_defaults_use_next_available_output(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "harness.yaml").write_text("existing: true\n")
+    app = make_app()
+    log = FakeLog()
+    app._show_command_output = lambda target_log, content, clear_log=True: target_log.write(content)
+
+    app._harness_cmd("wizard", log)
+    for _ in range(10):
+        app._handle_harness_wizard_input("", log)
+
+    assert (tmp_path / "harness-2.yaml").exists()
+    assert (tmp_path / "harness.yaml").read_text() == "existing: true\n"
+    assert app._awaiting_harness_wizard is False
+    status = app._pure_mode.get_status()["harness"]
+    assert status["enabled"] is True
+    assert status["path"].endswith("harness-2.yaml")
+
+
 def test_tui_help_surfaces_developer_workflows():
     app = make_app()
     log = FakeLog()