feat(tests): add markdown output

Statistics: 15 files changed, 492 insertions, 28 deletions

Summary:
- Dirs: src=6, tests=5, .=2, docs=2
- Exts: .py=11, .md=2, .yaml=1, .lock=1
- A/M/D: 0/15/0
- Symbols: write_serve_endpoint_file, render_tools_detect_text, bind_serve_server, serve_endpoint_path, read_serve_endpoint

Modified files:
- README.md (+7/-4)
- docs/ai-tool-registry-2026.yaml (+3/-3)
- docs/cli-examples.md (+17/-0)
- src/koru/agents.py (+13/-0)
- src/koru/cli.py (+68/-9)
- src/koru/context.py (+2/-2)
- src/koru/serve.py (+102/-2)
- src/koru/tasks.py (+31/-5)
- src/koru/tools.py (+78/-0)
- tests/test_agents.py (+25/-0)
- tests/test_e2e.py (+22/-0)
- tests/test_serve.py (+73/-1)
- tests/test_tasks.py (+26/-0)
- tests/test_tools.py (+24/-1)
- uv.lock (+1/-1)

Implementation notes (heuristics):
- Type inferred from file paths + diff keywords + add/delete ratio
- Scope prefers 'goal' when goal/* is touched; otherwise based on top-level dirs
- For <=6 files: generate short per-file notes from added lines (defs/classes/click options/headings)
- A/M/D derived from git name-status; per-file +X/-X from git numstat

Author: tom-sapletta-com

CHANGELOG.md

@@ -60,6 +60,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `quality:regix` ↔ `gate:regix`, `quality:redup*` ↔ `gate:redup`,
   `quality:sumr:*` ↔ `gate:sumr`.
 
+## [0.1.38] - 2026-05-12
+
+### Docs
+- Update README.md
+- Update docs/ai-tool-registry-2026.yaml
+- Update docs/cli-examples.md
+
+### Test
+- Update tests/test_agents.py
+- Update tests/test_e2e.py
+- Update tests/test_serve.py
+- Update tests/test_tasks.py
+- Update tests/test_tools.py
+
+### Other
+- Update uv.lock
+
 ## [0.1.37] - 2026-05-12
 
 ### Docs

README.md

@@ -4,11 +4,11 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.37-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$3.19-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-20.9h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.38-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$3.13-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-21.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $3.1882 (60 commits)
-- 👤 **Human dev:** ~$2093 (20.9h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $3.1281 (61 commits)
+- 👤 **Human dev:** ~$2103 (21.0h @ $100/h, 30min dedup)
 
 Generated on 2026-05-12 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
@@ -166,6 +166,9 @@ koru autopilot status          # is the daemon up? plugins connected?
 koru tools detect
 koru tools detect --format json
 
+# phase-2 tool adapter scaffold ticket
+koru task "Prepare Gemini adapter" --project . --tool gemini-cli
+
 # non-invasive smoke test (daemon routing + IDE autodetect, no real key injection)
 scripts/autopilot-ide-autodetect-smoke.sh --require-running-ide
 scripts/autopilot-ide-autodetect-smoke.sh --check-ide jetbrains --check-ide windsurf

VERSION

@@ -1 +1 @@
-0.1.37
+0.1.38

docs/ai-tool-registry-2026.yaml

@@ -88,14 +88,14 @@ tools:
   - id: gemini-cli
     name: Gemini CLI
     category: cli_agent
-    lane: adapter
+    lane: native
     stability: beta
     detect:
       commands: ["gemini"]
       markers: []
       env: ["GEMINI_API_KEY"]
-    invoke: "planfile shell ticket with `gemini` command"
-    notes: "Adapter lane pending native integration."
+    invoke: "koru agent --agent gemini-cli --launch"
+    notes: "Native agent lane (phase-3 promotion); adapter tickets still supported."
 
   - id: cline
     name: Cline

docs/cli-examples.md

@@ -94,6 +94,23 @@ task loop:test
 task loop:lint
 ```
 
+### Create task tickets (including tool-adapter scaffold)
+
+```bash
+# standard NL ticket
+koru task "Fix login form validation" --project . --priority high
+
+# phase-2 adapter scaffold from tool registry
+koru task "Prepare Gemini adapter" --project . --tool gemini-cli
+
+# override inferred executor hint for the scaffold
+koru task "Prepare n8n webhook adapter" --project . --tool n8n --tool-kind api
+
+# use custom registry file
+koru task "Prepare custom tool adapter" --project . --tool my-tool \
+  --tool-registry /path/to/ai-tool-registry-2026.yaml
+```
+
 ### Real-world example (semcod org)
 
 ```bash

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "koru"
-version = "0.1.37"
+version = "0.1.38"
 description = "Closed-loop automation across semcod/* repositories."
 readme = "README.md"
 requires-python = ">=3.12"

src/koru/agents.py

@@ -53,6 +53,7 @@ def detect_agent_options(project: Path) -> list[AgentOption]:
     claude_cmd = _which("claude")
     aider_cmd = _which("aider")
     codex_cmd = _which("codex")
+    gemini_cmd = _which("gemini")
     openrouter_ready = bool(os.getenv("OPENROUTER_API_KEY"))
     antigravity_ready = bool(os.getenv("ANTIGRAVITY_AGENT"))
 
@@ -89,6 +90,18 @@ def detect_agent_options(project: Path) -> list[AgentOption]:
             command=codex_cmd,
             reason="Codex CLI detected in PATH." if codex_cmd else "Codex CLI is not in PATH.",
         ),
+        AgentOption(
+            id="gemini-cli",
+            label="Gemini CLI",
+            available=bool(gemini_cmd),
+            launchable=bool(gemini_cmd),
+            command=gemini_cmd,
+            reason=(
+                "Gemini CLI detected in PATH."
+                if gemini_cmd
+                else "Gemini CLI is not in PATH."
+            ),
+        ),
         AgentOption(
             id="cursor",
             label="Cursor",

src/koru/cli.py

@@ -5,6 +5,7 @@
 import argparse
 import asyncio
 import json
+import os
 import shlex
 import sys
 from collections.abc import Callable
@@ -34,8 +35,18 @@
 from .run_log import open_run_log_eagerly
 from .scan import ScanResult, run_scan
 from .serve import DEFAULT_HOST, DEFAULT_PORT, ServeConfig, serve
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
 from .tasks import create_nl_task
-from .tools import detect_tools, load_tool_registry, render_tools_detect_text
+from .tools import (
+    build_tool_task_scaffold,
+    detect_tools,
+    find_tool_entry,
+    load_tool_registry,
+    render_tools_detect_text,
+)
 from .watch import watch_planfile_events
 
 
@@ -295,6 +306,29 @@ def _build_task_parser() -> argparse.ArgumentParser:
     parser.add_argument("--sprint", default="current", help="Target planfile sprint.")
     parser.add_argument("--queue-name", default=None, help="Execution queue for the new ticket.")
     parser.add_argument("--priority", default="normal", help="Ticket priority.")
+    parser.add_argument(
+        "--tool",
+        dest="tool_id",
+        default=None,
+        help=(
+            "Build a tool-adapter scaffold ticket for this tool id "
+            "(from docs/ai-tool-registry-2026.yaml)."
+        ),
+    )
+    parser.add_argument(
+        "--tool-kind",
+        dest="tool_kind",
+        choices=("human", "shell", "api", "llm"),
+        default=None,
+        help="Override scaffolded executor hint for --tool.",
+    )
+    parser.add_argument(
+        "--tool-registry",
+        dest="tool_registry",
+        type=Path,
+        default=None,
+        help="Override tool registry path for --tool lookup.",
+    )
     return parser
 
 
@@ -323,6 +357,14 @@ def _build_serve_parser() -> argparse.ArgumentParser:
         default=DEFAULT_PORT,
         help=f"TCP port to listen on (default {DEFAULT_PORT}).",
     )
+    parser.add_argument(
+        "--auto-port",
+        action="store_true",
+        help=(
+            "If the port is busy, try the next ports (then an ephemeral port). "
+            "Also on when KORU_SERVE_AUTO_PORT is 1/true/yes."
+        ),
+    )
     open_group = parser.add_mutually_exclusive_group()
     open_group.add_argument(
         "--open",
@@ -876,20 +918,44 @@ def _build_agent_parser() -> argparse.ArgumentParser:
 
 def _task_main(argv: list[str]) -> int:
     args = _build_task_parser().parse_args(argv)
+    scaffold: dict[str, Any] | None = None
+    if args.tool_id:
+        registry, registry_path = load_tool_registry(args.tool_registry)
+        if not registry:
+            print(
+                "koru task: tool registry is empty or missing. "
+                "Use --tool-registry PATH or ensure docs/ai-tool-registry-2026.yaml exists."
+            )
+            return 2
+        tool = find_tool_entry(registry, args.tool_id)
+        if tool is None:
+            known = ", ".join(sorted(str(t.get("id")) for t in registry if t.get("id")))
+            print(f"koru task: unknown --tool '{args.tool_id}'. Known ids: {known}")
+            return 2
+        scaffold = build_tool_task_scaffold(tool, adapter_kind=args.tool_kind)
+        if registry_path is not None:
+            scaffold.setdefault("source_context", {})
+            if isinstance(scaffold.get("source_context"), dict):
+                scaffold["source_context"]["registry"] = str(registry_path)
+
     try:
         created = create_nl_task(
             args.project,
             " ".join(args.text),
             sprint=args.sprint,
             queue_name=args.queue_name,
             priority=args.priority,
+            scaffold=scaffold,
         )
     except ValueError as exc:
         print(f"koru task: {exc}")
         return 2
     print(f"koru task: ✓ created {created.ticket_id} in {created.path}")
     print(f"  name:  {created.name}")
     print(f"  queue: {args.queue_name or 'default'}")
+    if args.tool_id:
+        print(f"  tool:  {args.tool_id}")
+        print("  note: scaffold ticket created — fill concrete executor inputs before queue run")
     print("Next: run `koru` to get the LLM prompt, or `koru --queue` to execute one task.")
     emit_management_event(
         tool="koru.task",
@@ -915,14 +981,7 @@ def _serve_main(argv: list[str]) -> int:
         port=args.port,
         open_browser=args.open_browser,
         queue_name=args.queue_name,
-    )
-    emit_management_event(
-        tool="koru.serve",
-        action="started",
-        status="running",
-        message=f"http://{config.host}:{config.port}/",
-        queue=config.queue_name,
-        details={"project": str(config.project), "open_browser": config.open_browser},
+        auto_port=bool(args.auto_port) or _env_truthy("KORU_SERVE_AUTO_PORT"),
     )
     exit_code = serve(config)
     emit_management_event(

src/koru/context.py

@@ -778,9 +778,9 @@ def _render_ai_tool_support_2026() -> list[str]:
         "3. **manual lane** — no stable automation API yet; operator uses it directly.",
         "",
         "Current native lane includes: `windsurf`, `vscode`, `cursor`, `jetbrains`, `zed`, "
-        "`claude-code`, `aider`, `codex` and OpenRouter-compatible `llm` tickets.",
+        "`claude-code`, `aider`, `codex`, `gemini-cli` and OpenRouter-compatible `llm` tickets.",
         "",
-        "For tools not listed as native (e.g. Gemini CLI, Cline, OpenCode, Qwen Code, "
+        "For tools not listed as native (e.g. Cline, OpenCode, Qwen Code, "
         "Copilot/Tabnine plugins, app builders), use adapter lane first; promote to native "
         "only when reliability is proven.",
         "",