From 8a5a5f88ed3a368a44bd73d94de8f5975538b85a Mon Sep 17 00:00:00 2001
From: banteg <4562643+banteg@users.noreply.github.com>
Date: Fri, 2 Jan 2026 17:53:55 +0400
Subject: [PATCH] docs: onboarding (#25)

---
 pyproject.toml           |  3 +--
 readme.md                |  6 ++++--
 src/takopi/__init__.py   |  2 +-
 src/takopi/onboarding.py |  8 +++++++-
 tests/test_onboarding.py | 17 +++++++++++++++++
 uv.lock                  |  2 +-
 6 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index fa88473..c925f9c 100644
--- a/pyproject.toml
+++ b/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"]
diff --git a/readme.md b/readme.md
index 3749a61..6fb37fd 100644
--- a/readme.md
+++ b/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
 
diff --git a/src/takopi/__init__.py b/src/takopi/__init__.py
index 3d18726..dd9b22c 100644
--- a/src/takopi/__init__.py
+++ b/src/takopi/__init__.py
@@ -1 +1 @@
-__version__ = "0.5.0"
+__version__ = "0.5.1"
diff --git a/src/takopi/onboarding.py b/src/takopi/onboarding.py
index 04740ea..aada751 100644
--- a/src/takopi/onboarding.py
+++ b/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
diff --git a/tests/test_onboarding.py b/tests/test_onboarding.py
index 442917e..9224e08 100644
--- a/tests/test_onboarding.py
+++ b/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)
diff --git a/uv.lock b/uv.lock
index 26df37e..de847fa 100644
--- a/uv.lock
+++ b/uv.lock
@@ -354,7 +354,7 @@ wheels = [
 
 [[package]]
 name = "takopi"
-version = "0.5.0"
+version = "0.6.0.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "anyio" },