pythinker-code 2.0.0__tar.gz → 2.1.0__tar.gz

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythinker-code
-Version: 2.0.0
+Version: 2.1.0
 Summary: Pythinker Code is your next CLI agent.
 Keywords: cli,agent,ai,coding-assistant,llm,claude,openai,terminal
 Author: Mohamed Elkholy
@@ -53,11 +53,11 @@ Requires-Dist: opentelemetry-api>=1.30,<2
 Requires-Dist: opentelemetry-sdk>=1.30,<2
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30,<2
 Requires-Python: >=3.12
-Project-URL: Changelog, https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://github.com/mohamed-elkholy95/Pythinker-Code#readme
 Project-URL: Homepage, https://github.com/mohamed-elkholy95/Pythinker-Code
-Project-URL: Issues, https://github.com/mohamed-elkholy95/Pythinker-Code/issues
 Project-URL: Repository, https://github.com/mohamed-elkholy95/Pythinker-Code
+Project-URL: Issues, https://github.com/mohamed-elkholy95/Pythinker-Code/issues
+Project-URL: Changelog, https://github.com/mohamed-elkholy95/Pythinker-Code/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/mohamed-elkholy95/Pythinker-Code#readme
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -71,10 +71,10 @@ Description-Content-Type: text/markdown
 
 <br />
 
-[![PyPI](https://img.shields.io/badge/pythinker--cli-v1.0.0-2563eb?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/pythinker-code/)
+[![PyPI](https://img.shields.io/pypi/v/pythinker-code?style=for-the-badge&logo=pypi&logoColor=white&color=2563eb&label=pythinker-code)](https://pypi.org/project/pythinker-code/)
 [![Python](https://img.shields.io/badge/Python-3.12%2B-3776ab?style=for-the-badge&logo=python&logoColor=white)](pyproject.toml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-16a34a.svg?style=for-the-badge)](LICENSE)
-[![CI](https://img.shields.io/github/actions/workflow/status/mohamed-elkholy95/Pythinker-Code/ci-pythinker-code.yml?label=CI&color=22c55e&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/actions/workflows/ci-pythinker-code.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/mohamed-elkholy95/Pythinker-Code/ci-pythinker-cli.yml?label=CI&color=22c55e&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/actions/workflows/ci-pythinker-cli.yml)
 
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-f59e0b.svg?style=flat-square&logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
 [![ACP ready](https://img.shields.io/badge/ACP-ready-7c3aed.svg?style=flat-square)](https://github.com/agentclientprotocol/agent-client-protocol)
@@ -189,6 +189,20 @@ Swap providers and models per-session: `--model openai/gpt-5.5`, hosted Pythinke
 
 ## ⚡ Quick Start
 
+### ✨ Recommended install (clean, with logo)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install.ps1 | iex
+```
+
+The installer fetches `uv` if missing, installs `pythinker-code` quietly, and prints a single-line confirmation instead of the full dependency wall.
+
 ### 🚀 One-off run with `uvx`
 
 ```sh

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/README.md

@@ -9,10 +9,10 @@
 
 <br />
 
-[![PyPI](https://img.shields.io/badge/pythinker--cli-v1.0.0-2563eb?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/pythinker-code/)
+[![PyPI](https://img.shields.io/pypi/v/pythinker-code?style=for-the-badge&logo=pypi&logoColor=white&color=2563eb&label=pythinker-code)](https://pypi.org/project/pythinker-code/)
 [![Python](https://img.shields.io/badge/Python-3.12%2B-3776ab?style=for-the-badge&logo=python&logoColor=white)](pyproject.toml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-16a34a.svg?style=for-the-badge)](LICENSE)
-[![CI](https://img.shields.io/github/actions/workflow/status/mohamed-elkholy95/Pythinker-Code/ci-pythinker-code.yml?label=CI&color=22c55e&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/actions/workflows/ci-pythinker-code.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/mohamed-elkholy95/Pythinker-Code/ci-pythinker-cli.yml?label=CI&color=22c55e&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/mohamed-elkholy95/Pythinker-Code/actions/workflows/ci-pythinker-cli.yml)
 
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-f59e0b.svg?style=flat-square&logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
 [![ACP ready](https://img.shields.io/badge/ACP-ready-7c3aed.svg?style=flat-square)](https://github.com/agentclientprotocol/agent-client-protocol)
@@ -127,6 +127,20 @@ Swap providers and models per-session: `--model openai/gpt-5.5`, hosted Pythinke
 
 ## ⚡ Quick Start
 
+### ✨ Recommended install (clean, with logo)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/mohamed-elkholy95/Pythinker-Code/main/scripts/install.ps1 | iex
+```
+
+The installer fetches `uv` if missing, installs `pythinker-code` quietly, and prints a single-line confirmation instead of the full dependency wall.
+
 ### 🚀 One-off run with `uvx`
 
 ```sh

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythinker-code"
-version = "2.0.0"
+version = "2.1.0"
 description = "Pythinker Code is your next CLI agent."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -65,7 +65,7 @@ dependencies = [
 dev = [
     "pyinstaller==6.18.0",
     "inline-snapshot[black]>=0.31.1",
-    "pyright>=1.1.407",
+    "pyright>=1.1.409",
     "ty>=0.0.9",
     "pytest>=9.0.3",
     "pytest-asyncio>=1.3.0",

pythinker_code-2.1.0/src/pythinker_code/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## Unreleased
+
+## 2.1.0 (2026-05-08)
+
+TUI CLI design and slash command enhancements.
+
+- New selectors package — interactive `/theme`, `/thinking`, `/model`, `/login`, `/settings`, `/extension`, and `/show-images` panels replace inline numeric/text prompts.
+- New `/thinking` slash command for adjusting reasoning effort at runtime.
+- `SettingsList` component + `/settings` selector for live `Config` editing (theme, default model, TUI style, default thinking, telemetry).
+- Selector framework: `SelectorHeader` sentinel and per-row `on_change` callback.
+- Card-style TUI polish: bordered shell card, footer/toolbar, tool renderers (read/write/edit/grep/find/bash/agent) and a diff component; subagent tool cards get a running-dots spinner.
+- Pythinker-branded slash menu, input row, and tool execution components.
+- Prompt template discovery simplified to `.pythinker/prompts` at project and user scope (legacy directory lookup removed).
+- TUI style flag now accepts only `card` (default) or `pythinker`; the legacy alias has been dropped.
+
+- Update notifier: standalone "Update Available" banner shown above the welcome panel when a newer release is on PyPI; suppressed by `PYTHINKER_CLI_NO_AUTO_UPDATE=1`.
+- New `pythinker update` subcommand (`--check` for a non-installing check) that auto-detects the install method (`uv tool`, `pipx`, or `pip`) and runs the matching upgrade command.
+- Image paste placeholder now renders as `[Image #N]` in the input/buffer (mirroring `[Pasted text #N +K lines]`); history serialization keeps the canonical `[image:<id>,WxH]` form so attachments still resolve cross-session.
+- Lower default paste-placeholderize thresholds to 200 chars / 5 lines (was 1000 / 15) so medium-length pastes collapse into `[Pasted text #N]` instead of overflowing the compact input window. Override via `PYTHINKER_CLI_PASTE_CHAR_THRESHOLD` and `PYTHINKER_CLI_PASTE_LINE_THRESHOLD`.
+
+## 1.0.0 (2026-05-06)
+
+Initial release of Pythinker CLI.
+
+- Interactive terminal AI coding agent with shell command mode (Ctrl-X)
+- ACP server (`pythinker acp`) for IDE integrations such as Zed and JetBrains
+- MCP tool support: `pythinker mcp` sub-commands and ad-hoc `--mcp-config-file`
+- Multi-provider auth: OpenAI, OpenAI Codex, Anthropic, OpenRouter, DeepSeek, MiniMax, Opencode-Go
+- Skills, plugins, and slash commands across project / user / built-in scopes
+- Session persistence with subagents and approval workflows
+- Print mode and wire mode for non-interactive and programmatic use
+- Plan mode for read-only research and design before code changes
+- YOLO mode (`--yolo` / `/yolo`) to dangerously skip permission approvals while keeping the user reachable via `AskUserQuestion`
+- Auto mode (`--auto` / `/auto`) for unattended runs: auto-approves tool calls and auto-dismisses `AskUserQuestion` so the agent finishes end-to-end without a user

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/src/pythinker_code/__main__.py

@@ -46,6 +46,7 @@ Commands:
   export   Export session data.
   mcp      Manage MCP server configurations.
   plugin   Manage plugins.
+  update   Check for and install Pythinker CLI updates.
   vis      Run Pythinker Agent Tracing Visualizer.
   web      Run Pythinker CLI web interface.
 

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/src/pythinker_code/app.py

@@ -703,9 +703,9 @@ class PythinkerCLI:
         from pythinker_code.ui.shell import Shell, WelcomeInfoItem
 
         if command is None:
-            from pythinker_code.ui.shell.update import check_update_gate
+            from pythinker_code.ui.shell.update import print_update_banner
 
-            check_update_gate()
+            print_update_banner()
 
         welcome_info = [
             WelcomeInfoItem(

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/src/pythinker_code/cli/_lazy_group.py

@@ -18,6 +18,11 @@ class LazySubcommandGroup(typer.core.TyperGroup):
         "export": ("pythinker_code.cli.export", "cli", "Export session data."),
         "mcp": ("pythinker_code.cli.mcp", "cli", "Manage MCP server configurations."),
         "plugin": ("pythinker_code.cli.plugin", "cli", "Manage plugins."),
+        "update": (
+            "pythinker_code.cli.update",
+            "cli",
+            "Check for and install Pythinker CLI updates.",
+        ),
         "vis": ("pythinker_code.cli.vis", "cli", "Run Pythinker Agent Tracing Visualizer."),
         "web": ("pythinker_code.cli.web", "cli", "Run Pythinker CLI web interface."),
     }
@@ -26,6 +31,7 @@ class LazySubcommandGroup(typer.core.TyperGroup):
         "export",
         "mcp",
         "plugin",
+        "update",
         "vis",
         "web",
     )

pythinker_code-2.1.0/src/pythinker_code/cli/update.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+cli = typer.Typer(help="Check for and install Pythinker CLI updates.")
+
+
+@cli.callback(invoke_without_command=True)
+def update(
+    check_only: Annotated[
+        bool,
+        typer.Option(
+            "--check",
+            help="Only check whether an update is available; don't install.",
+        ),
+    ] = False,
+):
+    """Check for and install Pythinker CLI updates."""
+    from pythinker_code.ui.shell.update import UpdateResult, do_update
+
+    result = asyncio.run(do_update(print=True, check_only=check_only))
+    if result in (UpdateResult.FAILED, UpdateResult.UNSUPPORTED):
+        raise typer.Exit(1)

{pythinker_code-2.0.0 → pythinker_code-2.1.0}/src/pythinker_code/config.py

@@ -175,6 +175,20 @@ class MCPClientConfig(BaseModel):
     """Timeout for tool calls in milliseconds."""
 
 
+class TUIConfig(BaseModel):
+    """TUI rendering style configuration."""
+
+    style: Literal["pythinker", "card"] = Field(
+        default="card",
+        description=(
+            "TUI rendering style. 'card' (default) uses highlighted user "
+            "messages and bordered tool cards. 'pythinker' keeps the legacy "
+            "worklog-based rendering. Override at runtime with the env var "
+            "PYTHINKER_TUI_STYLE=pythinker."
+        ),
+    )
+
+
 class MCPConfig(BaseModel):
     """MCP configuration."""
 
@@ -238,6 +252,7 @@ class Config(BaseModel):
     )
     services: Services = Field(default_factory=Services, description="Services configuration")
     mcp: MCPConfig = Field(default_factory=MCPConfig, description="MCP configuration")
+    tui: TUIConfig = Field(default_factory=TUIConfig, description="TUI rendering configuration")
     hooks: list[HookDef] = Field(default_factory=list, description="Hook definitions")  # pyright: ignore[reportUnknownVariableType]
     merge_all_available_skills: bool = Field(
         default=True,

pythinker_code-2.1.0/src/pythinker_code/events.py

@@ -0,0 +1,102 @@
+"""In-process event bus.
+
+ . A
+minimal pub/sub primitive that extension/plugin code can use to broadcast
+state changes (assistant message, tool call started/ended, model changed,
+etc.) without holding direct references to listeners.
+
+Handlers may be sync or async. Async handlers are scheduled on the running
+event loop; if no loop is running they're executed via ``asyncio.run``
+(useful in tests). Exceptions in any handler are logged and swallowed so a
+broken extension can't take down the host.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from pythinker_code.utils.logging import logger
+
+__all__ = [
+    "EventBus",
+    "EventHandler",
+    "create_event_bus",
+]
+
+
+EventHandler = Callable[[Any], Any]
+
+
+class EventBus:
+    """Channel-keyed pub/sub.
+
+    Use :func:`create_event_bus` rather than constructing directly — that
+    keeps the constructor signature private and matches Pythinker's factory.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[EventHandler]] = {}
+
+    def emit(self, channel: str, data: Any = None) -> None:
+        """Fire *data* on *channel*. Handlers run sequentially; failures log."""
+        for handler in list(self._handlers.get(channel, ())):
+            self._dispatch(channel, handler, data)
+
+    def on(self, channel: str, handler: EventHandler) -> Callable[[], None]:
+        """Subscribe *handler* to *channel*. Returns an unsubscribe fn."""
+        self._handlers.setdefault(channel, []).append(handler)
+
+        def _off() -> None:
+            handlers = self._handlers.get(channel)
+            if not handlers:
+                return
+            try:
+                handlers.remove(handler)
+            except ValueError:
+                return
+            if not handlers:
+                self._handlers.pop(channel, None)
+
+        return _off
+
+    def clear(self) -> None:
+        """Remove every handler on every channel. Intended for tests."""
+        self._handlers.clear()
+
+    # ----------------------------------------------------------------------
+
+    def _dispatch(self, channel: str, handler: EventHandler, data: Any) -> None:
+        try:
+            result = handler(data)
+        except Exception:  # noqa: BLE001 — extension must not crash host
+            logger.exception("Event handler error on channel '{channel}'", channel=channel)
+            return
+        if inspect.iscoroutine(result):
+            self._schedule_coro(channel, result)
+
+    @staticmethod
+    def _schedule_coro(channel: str, coro: Any) -> None:
+        async def _runner() -> None:
+            try:
+                await coro
+            except Exception:  # noqa: BLE001
+                logger.exception("Async event handler error on '{channel}'", channel=channel)
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No running loop — execute inline. Mostly hit in tests.
+            try:
+                asyncio.run(_runner())
+            except Exception:  # noqa: BLE001
+                logger.exception("Failed to run async handler for '{channel}'", channel=channel)
+            return
+        loop.create_task(_runner())
+
+
+def create_event_bus() -> EventBus:
+    """Factory mirroring the ``createEventBus()``."""
+    return EventBus()

pythinker_code-2.1.0/src/pythinker_code/extensions.py

@@ -0,0 +1,151 @@
+"""In-process extension API.
+
+This module exposes Pythinker's extension hooks for the registries that
+already exist in the codebase:
+
+* tool renderers           — :func:`register_tool_renderer`
+* keybindings              — :func:`register_keybinding`
+* footer status badges     — :func:`register_footer_status`
+* event handlers           — :func:`register_event_handler`
+* lifecycle hooks          — :func:`register_extension`
+
+The footer status registry is a thin placeholder for the day the card-style
+:class:`FooterState` is wired into the live prompt; until then it just
+stores entries that callers can read out.
+
+the ``register_command`` overlaps with Pythinker's existing
+``SlashCommandRegistry`` — extensions should use that registry directly.
+
+Extensions are registered with::
+
+    from pythinker_code.extensions import register_extension
+
+    def setup(ctx):
+        ctx.register_tool_renderer(my_renderer)
+        ctx.register_keybinding("app.tools.expand", "alt+e")
+        ctx.bus.on("assistant.message", on_assistant_message)
+
+    register_extension(name="my-ext", setup=setup)
+
+The host calls :func:`run_pending_extensions` once at startup; setup
+errors are logged but do not crash the host.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from pythinker_code.events import EventBus, EventHandler, create_event_bus
+from pythinker_code.ui.shell.keymap import register_keybinding as _register_keybinding
+from pythinker_code.ui.shell.tool_renderers import (
+    ToolRenderDefinition,
+)
+from pythinker_code.ui.shell.tool_renderers import (
+    register_tool_renderer as _register_tool_renderer,
+)
+from pythinker_code.utils.logging import logger
+
+__all__ = [
+    "ExtensionContext",
+    "ExtensionSetup",
+    "footer_statuses",
+    "register_extension",
+    "registered_extensions",
+    "run_pending_extensions",
+    "shared_event_bus",
+]
+
+
+_GLOBAL_BUS: EventBus = create_event_bus()
+"""Process-wide bus extensions write to. Independent from any per-session
+event streams to keep the surface stable."""
+
+_FOOTER_STATUSES: dict[str, str] = {}
+"""Read-only-from-outside map of extension id → status text."""
+
+
+def shared_event_bus() -> EventBus:
+    """Return the global :class:`EventBus` extensions subscribe to."""
+    return _GLOBAL_BUS
+
+
+def footer_statuses() -> dict[str, str]:
+    """Return a copy of the current extension footer-status map."""
+    return dict(_FOOTER_STATUSES)
+
+
+@dataclass(slots=True)
+class ExtensionContext:
+    """Handle passed into an extension's setup function.
+
+    Each method delegates to the appropriate global registry. Method names
+    mirror the ``register*`` API surface so porting an extension between
+    runtimes is mostly mechanical.
+    """
+
+    name: str
+    bus: EventBus = field(default_factory=lambda: _GLOBAL_BUS)
+
+    def register_tool_renderer(self, definition: ToolRenderDefinition) -> None:
+        _register_tool_renderer(definition)
+
+    def register_keybinding(self, semantic_id: str, *keys: str) -> None:
+        _register_keybinding(semantic_id, *keys)
+
+    def register_footer_status(self, key: str, text: str) -> None:
+        """Add or replace an extension's footer status badge.
+
+        ``key`` is normally the extension name. Pass an empty *text* to
+        clear it. The footer reads :func:`footer_statuses` when rendering.
+        """
+        if not text:
+            _FOOTER_STATUSES.pop(key, None)
+            return
+        _FOOTER_STATUSES[key] = text
+
+    def register_event_handler(self, channel: str, handler: EventHandler) -> Callable[[], None]:
+        return self.bus.on(channel, handler)
+
+
+ExtensionSetup = Callable[[ExtensionContext], None]
+
+
+@dataclass(frozen=True, slots=True)
+class _Extension:
+    name: str
+    setup: ExtensionSetup
+    started: bool = False
+
+
+_PENDING: list[_Extension] = []
+_LOADED: list[str] = []
+
+
+def register_extension(*, name: str, setup: ExtensionSetup) -> None:
+    """Queue *setup* to run when :func:`run_pending_extensions` is next called."""
+    _PENDING.append(_Extension(name=name, setup=setup))
+
+
+def run_pending_extensions() -> list[str]:
+    """Execute every pending extension's setup. Returns the names that ran.
+
+    Errors are logged and the rest of the queue continues — the same behavior.
+    """
+    started: list[str] = []
+    while _PENDING:
+        ext = _PENDING.pop(0)
+        ctx = ExtensionContext(name=ext.name)
+        try:
+            ext.setup(ctx)
+        except Exception:  # noqa: BLE001 — extension error must not crash host
+            logger.exception("Extension '{name}' setup failed", name=ext.name)
+            continue
+        _LOADED.append(ext.name)
+        started.append(ext.name)
+    return started
+
+
+def registered_extensions() -> list[str]:
+    """Snapshot of extension names that have been successfully started."""
+    return list(_LOADED)

pythinker_code-2.1.0/src/pythinker_code/prompt_templates.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from pythinker_host.path import HostPath
+
+from pythinker_code.utils.frontmatter import parse_frontmatter, strip_frontmatter
+from pythinker_code.utils.logging import logger
+from pythinker_code.utils.path import find_project_root
+
+PromptTemplateScope = Literal["project", "user"]
+
+
+@dataclass(frozen=True, slots=True)
+class PromptTemplate:
+    """A markdown prompt template exposed as a slash command."""
+
+    name: str
+    description: str
+    content: str
+    file_path: HostPath
+    scope: PromptTemplateScope
+    argument_hint: str | None = None
+
+
+def parse_command_args(args_string: str) -> list[str]:
+    """Parse template arguments using simple shell quoting."""
+    args: list[str] = []
+    current = ""
+    quote: str | None = None
+
+    for char in args_string:
+        if quote is not None:
+            if char == quote:
+                quote = None
+            else:
+                current += char
+        elif char in {'"', "'"}:
+            quote = char
+        elif char in {" ", "\t"}:
+            if current:
+                args.append(current)
+                current = ""
+        else:
+            current += char
+
+    if current:
+        args.append(current)
+    return args
+
+
+def substitute_args(content: str, args: list[str]) -> str:
+    """Substitute prompt-template placeholders.
+
+    Supports ``$1``, ``$2``, ``$@``, ``$ARGUMENTS``, ``${@:N}``, and
+    ``${@:N:L}``. Replacement is one-pass; inserted argument values are not
+    recursively substituted.
+    """
+    import re
+
+    def positional(match: re.Match[str]) -> str:
+        index = int(match.group(1)) - 1
+        return args[index] if 0 <= index < len(args) else ""
+
+    result = re.sub(r"\$(\d+)", positional, content)
+
+    def sliced(match: re.Match[str]) -> str:
+        start = max(0, int(match.group(1)) - 1)
+        length_group = match.group(2)
+        if length_group is None:
+            return " ".join(args[start:])
+        length = int(length_group)
+        return " ".join(args[start : start + length])
+
+    result = re.sub(r"\$\{@:(\d+)(?::(\d+))?\}", sliced, result)
+    all_args = " ".join(args)
+    result = result.replace("$ARGUMENTS", all_args)
+    result = result.replace("$@", all_args)
+    return result
+
+
+def expand_prompt_template(template: PromptTemplate, args_string: str) -> str:
+    """Expand *template* with a raw slash-command argument string."""
+    return substitute_args(template.content, parse_command_args(args_string))
+
+
+async def discover_prompt_templates(work_dir: HostPath) -> dict[str, PromptTemplate]:
+    """Discover project/user prompt templates.
+
+    Project templates win over user templates.
+    """
+    roots: list[tuple[PromptTemplateScope, HostPath]] = []
+    project_root = await find_project_root(work_dir)
+    roots.extend(
+        [
+            ("project", project_root / ".pythinker" / "prompts"),
+            ("user", HostPath.home() / ".pythinker" / "prompts"),
+        ]
+    )
+
+    templates: dict[str, PromptTemplate] = {}
+    for scope, root in roots:
+        for template in await _load_templates_from_dir(root, scope=scope):
+            templates.setdefault(template.name, template)
+    return dict(sorted(templates.items()))
+
+
+async def _load_templates_from_dir(
+    directory: HostPath,
+    *,
+    scope: PromptTemplateScope,
+) -> list[PromptTemplate]:
+    try:
+        if not await directory.is_dir():
+            return []
+    except OSError as exc:
+        logger.debug("Cannot stat prompt templates dir {path}: {error}", path=directory, error=exc)
+        return []
+
+    templates: list[PromptTemplate] = []
+    try:
+        async for entry in directory.iterdir():
+            try:
+                if await entry.is_dir() or not entry.name.lower().endswith(".md"):
+                    continue
+                content = await entry.read_text(encoding="utf-8")
+            except OSError as exc:
+                logger.info(
+                    "Skipping unreadable prompt template {path}: {error}",
+                    path=entry,
+                    error=exc,
+                )
+                continue
+            try:
+                templates.append(parse_prompt_template_text(content, file_path=entry, scope=scope))
+            except Exception as exc:
+                logger.info(
+                    "Skipping invalid prompt template {path}: {error}",
+                    path=entry,
+                    error=exc,
+                )
+    except OSError as exc:
+        logger.warning(
+            "Failed to iterate prompt templates dir {path}: {error}",
+            path=directory,
+            error=exc,
+        )
+    return sorted(templates, key=lambda t: t.name)
+
+
+def parse_prompt_template_text(
+    text: str,
+    *,
+    file_path: HostPath,
+    scope: PromptTemplateScope,
+) -> PromptTemplate:
+    """Parse a markdown prompt template file."""
+    frontmatter = parse_frontmatter(text) or {}
+    body = strip_frontmatter(text).strip()
+    name = file_path.name.rsplit(".", 1)[0]
+    description = str(frontmatter.get("description") or "").strip()
+    if not description:
+        description = _first_body_line(body)
+    argument_hint = frontmatter.get("argument-hint")
+    return PromptTemplate(
+        name=name,
+        description=description,
+        argument_hint=str(argument_hint).strip() if argument_hint else None,
+        content=body,
+        file_path=file_path,
+        scope=scope,
+    )
+
+
+def _first_body_line(body: str) -> str:
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped[:60] + ("..." if len(stripped) > 60 else "")
+    return "Prompt template"