convertible-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-05-27
+
+### Changed
+
+- Bare `convertible` (no subcommand) now opens the interactive harness (the `session` palette) when run at a terminal — the natural "get in and drive" gesture. Piped, redirected, or otherwise non-interactive, it still prints usage, preserving the discoverable surface for scripts and agents. `-h/--help` is unaffected.
+- Reframed `convertible drive` help and `explain` text to lead with the goal/instruction ("drive toward a goal") rather than "run a repo task"; the repo is the target, not the headline. No behavior change.
+
 ## [0.4.0] - 2026-05-27
 
 ### Added

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convertible-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
 Project-URL: Homepage, https://github.com/agentculture/convertible
 Project-URL: Issues, https://github.com/agentculture/convertible/issues
@@ -17,6 +17,27 @@ Description-Content-Type: text/markdown
 
 # convertible
 
+```text
+                      ,"^,::,:::::I::::::^                             
+                     ^!'`       `"^,.    ::`                           
+ `,;;i;,,'  .!^'`",. "<,"  "              ;,^                          
+ ^       '"^";"^```,":::','"'^`"."'.,:^,i::,"".                        
+.I.   '    I-l '",I;!ii,I.,,l;;IlIl:i!:::::,,,^^;",,'                  
+ '^ ""::``':.        .`";,"```"^..                  '^^'":,''.         
+   ::,`;!"..^..'^"^    .'  ..""   ..`"^                    ..`"`'"".   
+    ;;l!i:' ^        '^"`.       `"`..   ',^..                   `` '^ 
+     :i>I!lII".        .' .''^`       '`^'    .`".             ^. :;lI.
+     ",l!`;"':l;,,`.   .'       '",'.      ^...'^`'"...^l'":;Ii!!l:!';.
+      ^''^., '`^^`:l;"^"',!~ .^^^,""..'`^. .^l,I''^.:l!;;;i>|+,!IlI::^ 
+                  `;. :>i":` "`, ',^^"     ";  I.'. :::"^:;iil;'":^; '"
+                      '^"'"IlI,.:,::;:'  .`;"!l:``,,"``',,,^,,:ll!,,l^ 
+                           ":^:,I^:"!;::  :I>l:::"`""::,:I>!<i^ " ;.   
+                              ",;"Il;i^:  ',":;"`'`'^,   ><[il```'     
+                              " ;;I"l:^.^;^''lI"   :^::",:,'           
+                               ,`:;,I.^ ''                             
+                                `.   " "                               
+```
+
 > Convertible CLI is a swappable coder-agent harness that turns different models
 > into repo workers behind one shared task contract.
 >
@@ -106,10 +127,13 @@ engine, so it binds equally to `mock`, `vllm-openai`, and any future wheel.
 uv sync
 uv run pytest -n auto                          # full suite, no network needed
 
+# Open the interactive harness (the session palette) at a terminal:
+uv run convertible
+
 # Discover the engines installed in this environment:
 uv run convertible wheels list
 
-# Drive a task with the deterministic mock engine (no model, no network):
+# Drive toward a goal with the deterministic mock engine (no model, no network):
 uv run convertible drive "add a CONTRIBUTING.md stub" --repo . --engine mock --no-pr
 ```
 
@@ -297,6 +321,11 @@ loop, hooks, and artifact — no parallel code path):
 uv run convertible session --repo /path/to/repo --engine vllm-openai
 ```
 
+Running `convertible` with no arguments **at a terminal** opens this same palette
+(with the default engine and repo) — the natural "get in and drive" gesture.
+Piped, redirected, or otherwise non-interactive, bare `convertible` prints usage
+instead, so scripts and agents keep a discoverable surface.
+
 The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
@@ -333,7 +362,7 @@ rely on a non-existent flag.
 
 | Verb | What it does |
 |------|--------------|
-| `drive <instruction>` | Run a repo task through a coder engine; write the artifact; hand off. |
+| `drive <goal>` | Drive toward a goal/instruction: work autonomously through a coder engine; write the artifact; hand off. |
 | `drive --command <name> [args…]` | Expand a saved command template and drive it. |
 | `commands list` | List discovered command templates for a repo. |
 | `commands overview` | Describe the commands surface. |

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/README.md

@@ -1,5 +1,26 @@
 # convertible
 
+```text
+                      ,"^,::,:::::I::::::^                             
+                     ^!'`       `"^,.    ::`                           
+ `,;;i;,,'  .!^'`",. "<,"  "              ;,^                          
+ ^       '"^";"^```,":::','"'^`"."'.,:^,i::,"".                        
+.I.   '    I-l '",I;!ii,I.,,l;;IlIl:i!:::::,,,^^;",,'                  
+ '^ ""::``':.        .`";,"```"^..                  '^^'":,''.         
+   ::,`;!"..^..'^"^    .'  ..""   ..`"^                    ..`"`'"".   
+    ;;l!i:' ^        '^"`.       `"`..   ',^..                   `` '^ 
+     :i>I!lII".        .' .''^`       '`^'    .`".             ^. :;lI.
+     ",l!`;"':l;,,`.   .'       '",'.      ^...'^`'"...^l'":;Ii!!l:!';.
+      ^''^., '`^^`:l;"^"',!~ .^^^,""..'`^. .^l,I''^.:l!;;;i>|+,!IlI::^ 
+                  `;. :>i":` "`, ',^^"     ";  I.'. :::"^:;iil;'":^; '"
+                      '^"'"IlI,.:,::;:'  .`;"!l:``,,"``',,,^,,:ll!,,l^ 
+                           ":^:,I^:"!;::  :I>l:::"`""::,:I>!<i^ " ;.   
+                              ",;"Il;i^:  ',":;"`'`'^,   ><[il```'     
+                              " ;;I"l:^.^;^''lI"   :^::",:,'           
+                               ,`:;,I.^ ''                             
+                                `.   " "                               
+```
+
 > Convertible CLI is a swappable coder-agent harness that turns different models
 > into repo workers behind one shared task contract.
 >
@@ -89,10 +110,13 @@ engine, so it binds equally to `mock`, `vllm-openai`, and any future wheel.
 uv sync
 uv run pytest -n auto                          # full suite, no network needed
 
+# Open the interactive harness (the session palette) at a terminal:
+uv run convertible
+
 # Discover the engines installed in this environment:
 uv run convertible wheels list
 
-# Drive a task with the deterministic mock engine (no model, no network):
+# Drive toward a goal with the deterministic mock engine (no model, no network):
 uv run convertible drive "add a CONTRIBUTING.md stub" --repo . --engine mock --no-pr
 ```
 
@@ -280,6 +304,11 @@ loop, hooks, and artifact — no parallel code path):
 uv run convertible session --repo /path/to/repo --engine vllm-openai
 ```
 
+Running `convertible` with no arguments **at a terminal** opens this same palette
+(with the default engine and repo) — the natural "get in and drive" gesture.
+Piped, redirected, or otherwise non-interactive, bare `convertible` prints usage
+instead, so scripts and agents keep a discoverable surface.
+
 The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
@@ -316,7 +345,7 @@ rely on a non-existent flag.
 
 | Verb | What it does |
 |------|--------------|
-| `drive <instruction>` | Run a repo task through a coder engine; write the artifact; hand off. |
+| `drive <goal>` | Drive toward a goal/instruction: work autonomously through a coder engine; write the artifact; hand off. |
 | `drive --command <name> [args…]` | Expand a saved command template and drive it. |
 | `commands list` | List discovered command templates for a repo. |
 | `commands overview` | Describe the commands surface. |

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/convertible/cli/__init__.py

@@ -61,6 +61,17 @@ def _argv_has_json(argv: list[str] | None) -> bool:
     return any(t == "--json" or t.startswith("--json=") for t in tokens)
 
 
+def _stdio_is_interactive() -> bool:
+    """Whether stdin and stdout are both interactive terminals.
+
+    Bare ``convertible`` opens the interactive harness only at a real terminal;
+    isolated as a module function so tests can force the interactive branch
+    without a TTY (mirrors :func:`convertible.cli._banner._isatty`). Both streams
+    must be a TTY: the palette reads from stdin and renders its chrome to stdout.
+    """
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
 def _build_parser() -> argparse.ArgumentParser:
     from convertible.cli._commands import cli as _cli_group
     from convertible.cli._commands import commands as _commands_group
@@ -136,6 +147,14 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     if args.command is None:
+        # Bare `convertible` opens the interactive harness at a terminal; piped /
+        # redirected / non-interactive it prints usage so scripts and agents keep
+        # a discoverable surface. `-h/--help` is handled by argparse before here,
+        # so the help surface (and the teken rubric, which probes --help) stay
+        # available either way. Re-parsing ["session"] reuses the session
+        # subparser's defaults and func wiring — no parallel code path.
+        if _stdio_is_interactive():
+            return _dispatch(parser.parse_args(["session"]))
         parser.print_help()
         return 0
 

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/convertible/cli/_commands/drive.py

@@ -224,7 +224,10 @@ def cmd_drive(args: argparse.Namespace) -> int:
 def register(sub: argparse._SubParsersAction) -> None:
     p = sub.add_parser(
         "drive",
-        help="Run a repo task through a coder engine and hand off the result.",
+        help=(
+            "Drive toward a goal: work autonomously on a request or instruction "
+            "through a coder engine, then hand off the result."
+        ),
     )
     # ``instruction`` is now zero-or-more positional tokens (nargs="*") so
     # ``--command`` can be the sole input without argparse raising an error.
@@ -232,7 +235,7 @@ def register(sub: argparse._SubParsersAction) -> None:
         "instruction",
         nargs="*",
         help=(
-            "What the engine should do in the repo.  "
+            "A goal or instruction to pursue autonomously.  "
             "Mutually exclusive with --command.  "
             "When --command is used, any positional tokens are passed as template arguments."
         ),

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/convertible/explain/catalog.py

@@ -18,9 +18,13 @@ A clonable template for AgentCulture mesh agents. It carries an agent-first CLI
 buildable/deployable package baseline. Clone it, rename the package, edit
 `culture.yaml`, and you have a new agent.
 
+Run `convertible` with no verb at a terminal to open the interactive harness (the
+`session` palette); piped or non-interactive, it prints this usage instead.
+
 ## Verbs
 
-- `convertible drive <instruction>` — run a repo task through a coder engine.
+- `convertible drive <goal>` — drive toward a goal/instruction; work autonomously
+  through a coder engine and hand off the result.
 - `convertible session` — foreground interactive palette over the drive path.
 - `convertible wheels list` — list discovered engine wheels.
 - `convertible whoami` — identity probe from `culture.yaml`.
@@ -122,10 +126,11 @@ itself (distinct from the global `overview`, which describes the agent).
 _DRIVE = """\
 # convertible drive
 
-Run a repo task through a coder engine: select an engine wheel, run the bounded
-agentic tool-loop against the repo, write a result artifact, and hand off the
-change as a branch + PR. The same invocation works for every engine — only
-`--engine` changes.
+Drive toward a goal: hand convertible a request or instruction and it works
+autonomously — selecting an engine wheel, running the bounded agentic tool-loop,
+writing a result artifact, and handing off the change as a branch + PR. The repo
+is the target (`--repo`, default cwd); the same invocation works for every
+engine — only `--engine` changes.
 
 ## Usage
 

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "convertible-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract."
 readme = "README.md"
 license = "MIT"

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/tests/test_cli.py

@@ -18,12 +18,34 @@ def test_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
     assert __version__ in capsys.readouterr().out
 
 
-def test_no_args_prints_help(capsys: pytest.CaptureFixture[str]) -> None:
+def test_no_args_non_tty_prints_help(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # Force the non-interactive branch so this is deterministic regardless of
+    # pytest's capture mode: under `pytest -s` from a real terminal stdin/stdout
+    # would be TTYs and bare invocation would otherwise open the session loop
+    # (and block on input()). Non-interactive must fall back to usage, preserving
+    # the discoverable surface for scripts and agents.
+    monkeypatch.setattr("convertible.cli._stdio_is_interactive", lambda: False)
     rc = main([])
     assert rc == 0
     assert "usage: convertible" in capsys.readouterr().out
 
 
+def test_no_args_tty_opens_session(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # At an interactive terminal, bare `convertible` opens the session harness.
+    # Force the interactive branch via the isolated seam, and stub input() to a
+    # quit token so the session renders its palette header then exits cleanly.
+    monkeypatch.setattr("convertible.cli._stdio_is_interactive", lambda: True)
+    monkeypatch.setattr("builtins.input", lambda *a, **k: "q")
+    rc = main([])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "convertible session" in out
+
+
 def test_unknown_command_errors(capsys: pytest.CaptureFixture[str]) -> None:
     with pytest.raises(SystemExit) as exc:
         main(["bogus"])

{convertible_cli-0.4.0 → convertible_cli-0.5.0}/uv.lock

@@ -72,7 +72,7 @@ wheels = [
 
 [[package]]
 name = "convertible-cli"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 
 [package.dev-dependencies]