docs: onboarding (#25)

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "takopi"
 authors = [{name = "banteg"}]
-version = "0.5.0"
+version = "0.5.1"
 description = "Telegram bridge for Codex, Claude Code, and other agent CLIs."
 readme = "readme.md"
 license = { file = "LICENSE" }
@@ -29,7 +29,6 @@ Issues = "https://github.com/banteg/takopi/issues"
 
 [project.scripts]
 takopi = "takopi.cli:main"
-takopi-debug-onboarding = "takopi.debug_onboarding:main"
 
 [build-system]
 requires = ["uv_build>=0.9.18,<0.10.0"]

readme.md

@@ -19,6 +19,7 @@ parallel runs across threads, per thread queue support.
 ## requirements
 
 - `uv` for installation (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- python 3.14+ (uv can install it: `uv python install 3.14`)
 - at least one engine installed:
   - `codex` on PATH (`npm install -g @openai/codex` or `brew install codex`)
   - `claude` on PATH (`npm install -g @anthropic-ai/claude-code`)
@@ -27,8 +28,9 @@ parallel runs across threads, per thread queue support.
 
 ## install
 
-- `uv tool install takopi` to install as `takopi`
-- or try it with `uvx takopi`
+- `uv python install 3.14`
+- `uv tool install -U takopi` to install as `takopi`
+- or try it with `uvx takopi@latest`
 
 ## setup
 

src/takopi/__init__.py

@@ -1 +1 @@
-__version__ = "0.5.0"
+__version__ = "0.5.1"

src/takopi/onboarding.py

@@ -26,7 +26,7 @@ class SetupResult:
 
 
 def config_issue(path: Path) -> SetupIssue:
-    config_display = _config_path_display(path)
+    config_display = _config_path_display(_preferred_config_path(path))
     return SetupIssue(
         "create a config",
         (
@@ -82,6 +82,12 @@ def _config_path_display(path: Path) -> str:
         return str(path)
 
 
+def _preferred_config_path(path: Path) -> Path:
+    if path.name == "takopi.toml" and path.parent.name == ".codex":
+        return path.parent.parent / ".takopi" / "takopi.toml"
+    return path
+
+
 def render_setup_guide(result: SetupResult) -> None:
     if result.ok:
         return

tests/test_onboarding.py

@@ -51,3 +51,20 @@ def test_check_setup_marks_invalid_chat_id(monkeypatch, tmp_path: Path) -> None:
 
     titles = {issue.title for issue in result.issues}
     assert "create a config" in titles
+
+
+def test_onboarding_prefers_new_config_path_for_legacy_file(monkeypatch) -> None:
+    backend = engines.get_backend("codex")
+    monkeypatch.setattr(onboarding.shutil, "which", lambda _name: "/usr/bin/codex")
+    legacy_path = Path.home() / ".codex" / "takopi.toml"
+    monkeypatch.setattr(
+        onboarding,
+        "load_telegram_config",
+        lambda: ({"bot_token": "token", "chat_id": "123"}, legacy_path),
+    )
+
+    result = onboarding.check_setup(backend)
+
+    issue = next(issue for issue in result.issues if issue.title == "create a config")
+    assert any("~/.takopi/takopi.toml" in line for line in issue.lines)
+    assert all(".codex/takopi.toml" not in line for line in issue.lines)

uv.lock

@@ -354,7 +354,7 @@ wheels = [
 
 [[package]]
 name = "takopi"
-version = "0.5.0"
+version = "0.6.0.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },