kolega-code 0.8.0__tar.gz → 0.8.2__tar.gz

{kolega_code-0.8.0 → kolega_code-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.8.0
+Version: 0.8.2
 Summary: Local-first AI coding agent for the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/

{kolega_code-0.8.0 → kolega_code-0.8.2}/docs/src/content/docs/cli/overview.md

@@ -39,6 +39,7 @@ kolega-code [PROJECT_PATH]
 | `--new` | Start a new session (this is the default) |
 | `--resume [THREAD_ID]` | Resume the latest saved thread, or a specific thread/session ID |
 | `--browser-visible` | Launch visible Playwright browser windows instead of headless |
+| `--show-logs` | Show the optional diagnostic Logs side-panel tab. Hidden by default to avoid unnecessary log rendering work |
 | `--permission-mode <auto\|ask>` | Shell/edit permission mode. TUI sessions default to `ask` |
 | `--session <ID>` | Legacy alias for `--resume THREAD_ID` |
 

{kolega_code-0.8.0 → kolega_code-0.8.2}/docs/src/content/docs/gigacode.mdx

@@ -43,6 +43,15 @@ When the agent runs a workflow, the transcript shows **phase headers** and short
 [sub-agent inspector](../tui/interface/#sub-agent-inspector) — press `Ctrl+G` to
 watch every agent's live trajectory, grouped by phase.
 
+The `run_workflow` result is a compact artifact manifest. It includes paths like
+`resultPath` and `transcriptPath`; the completed workflow result is written to
+`resultPath` instead of returned inline. For normal workflow output, the agent
+should read those main files and avoid reading individual sub-agent transcripts.
+Raw and per-agent debug artifacts may exist under the run directory for explicit
+workflow debugging.
+The agent should read those paths first — not re-run the workflow just to recover
+output text.
+
 ## How it works
 
 Under the hood, the agent authors a short **Python script** and runs it with a
@@ -69,9 +78,11 @@ return findings
 
 <Aside type="note">
 Workflows are deterministic and **resumable**. Each run is saved under Kolega
-Code's state directory (`workflows/<run-id>/`) with its script, a journal, and each
-sub-agent's transcript, so an interrupted run can pick up where it left off instead
-of redoing finished work.
+Code's state directory (`workflows/<run-id>/`) with its script, full result files,
+a readable Markdown transcript, raw JSONL, a resume journal, and debug sub-agent
+transcripts, so an interrupted run can pick up where it left off instead of redoing
+finished work. Use resume when intentionally iterating on the workflow; use the
+artifact paths when you only need to inspect output.
 </Aside>
 
 ## Behavior and safety

{kolega_code-0.8.0 → kolega_code-0.8.2}/docs/src/content/docs/tui/interface.md

@@ -14,8 +14,9 @@ The screen is split into two columns:
 - **Conversation panel** (left, larger) — your chat with the agent. Responses
   stream in live, tool calls and sub-agent activity appear inline, and detailed
   tool results are collapsed by default so you can expand only what you need.
-- **Side panel** (right) — a set of tabs for status, logs, the terminal, planning,
-  and settings. Toggle it with `Ctrl+O` or `/sidebar`.
+- **Side panel** (right) — a set of tabs for status, the terminal, planning,
+  and settings. Toggle it with `Ctrl+O` or `/sidebar`. The diagnostic Logs tab is
+  opt-in; launch with `--show-logs` when you want it.
 
 At the bottom sits the **composer** — the text box where you type prompts. See
 [Chat Composer](../composer/) for everything it can do.
@@ -25,7 +26,7 @@ At the bottom sits the **composer** — the text box where you type prompts. See
 | Tab | What it shows |
 | --- | --- |
 | **Status** | The active provider/model and thinking effort, the current interaction mode (Build/Plan), permission mode, the agent's turn state (idle, generating, thinking, running a tool, running sub-agents, waiting for input, …), token usage, and context warnings. |
-| **Logs** | A timestamped, color-coded activity log: sub-agent lifecycle, tool calls, configuration changes. An indicator flags new entries when you're on another tab. |
+| **Logs** | Optional. Launch with `--show-logs` to show a timestamped, color-coded diagnostic activity log. New entries preserve manual scrollback and an indicator flags unseen entries when you're on another tab. |
 | **Terminal** | Live output from commands the agent runs. |
 | **Planning** | The current **Plan** (markdown from the planning agent) and the shared **Task List** that both modes can edit. |
 | **Settings** | Provider, model, thinking effort, and API-key configuration. See [Settings & API Keys](../../configuration/settings-and-api-keys/). |

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/__init__.py

@@ -18,6 +18,7 @@ from .agent.planningagent import PlanningAgent
 from .agent.compression import HistoryCompressor
 from .agent.context import AgentContext, AgentServices, Telemetry, WorkspaceInfo
 from .agent.conversation import Conversation
+from .agent.errors import AgentError, MaxAgentIterationsExceeded
 from .events import AgentEventEmitter
 
 # Configuration
@@ -86,6 +87,8 @@ __all__ = [
     "AgentContext",
     "AgentServices",
     "Telemetry",
+    "AgentError",
+    "MaxAgentIterationsExceeded",
     "WorkspaceInfo",
     "Conversation",
     "HistoryCompressor",
@@ -148,4 +151,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.8.0"
+__version__ = "0.8.2"

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/__init__.py

@@ -8,6 +8,9 @@ from .browseragent import BrowserAgent
 from .generalagent import GeneralAgent
 from .planningagent import PlanningAgent
 
+# Export agent errors
+from .errors import AgentError, MaxAgentIterationsExceeded
+
 # Export agent models
 from kolega_code.events import AgentStatus, AgentEvent
 
@@ -25,6 +28,8 @@ __all__ = [
     "BrowserAgent",
     "GeneralAgent",
     "PlanningAgent",
+    "AgentError",
+    "MaxAgentIterationsExceeded",
     "AgentStatus",
     "AgentEvent",
     "AgentConfig",
@@ -39,4 +44,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.8.0"
+__version__ = "0.8.2"

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/baseagent.py

@@ -12,6 +12,7 @@ from typing import Any, AsyncGenerator, Dict, List, Optional
 
 from .common import LogMixin
 from .compression import CompactionResult, HistoryCompressor
+from .errors import MaxAgentIterationsExceeded
 from kolega_code.config import AgentConfig, ModelProvider
 from kolega_code.events import AgentConnectionManager
 from .context import AgentContext, AgentServices, Telemetry, WorkspaceInfo
@@ -119,6 +120,7 @@ class BaseAgent(LogMixin):
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[HookDispatcher] = None,
         context: Optional[AgentContext] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new BaseAgent instance.
@@ -203,7 +205,11 @@ class BaseAgent(LogMixin):
         if hook_dispatcher is not None:
             context.hook_dispatcher = hook_dispatcher
 
+        if max_iterations is not None and max_iterations < 1:
+            raise ValueError("max_iterations must be a positive integer or None")
+
         self.context = context
+        self.max_iterations = max_iterations
 
         # Flat attributes kept for compatibility with subclasses, tools, and hosts.
         self.project_path = context.workspace.project_path
@@ -1282,7 +1288,15 @@ class BaseAgent(LogMixin):
 
         stop_reason = None
         stop_overrides = 0
+        iterations = 0
         while stop_reason not in ["end_turn", "max_tokens", "stop_sequence"]:
+            iterations += 1
+            if self.max_iterations is not None and iterations > self.max_iterations:
+                raise MaxAgentIterationsExceeded(
+                    f"Agent '{self.agent_name}' exceeded max_iterations={self.max_iterations} "
+                    "without reaching a terminal stop reason"
+                )
+
             self.mark_cache_checkpoint()
 
             try:

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/browseragent.py

@@ -45,6 +45,7 @@ class BrowserAgent(BaseAgent):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new BrowserAgent instance.
@@ -97,6 +98,7 @@ class BrowserAgent(BaseAgent):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         self.tool_collection = ToolCollection(

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/coder.py

@@ -49,6 +49,7 @@ class CoderAgent(BaseAgent, LogMixin):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new CoderAgent instance.
@@ -104,6 +105,7 @@ class CoderAgent(BaseAgent, LogMixin):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         # Configure tool collection with custom coder agent tools

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/conversation.py

@@ -16,6 +16,7 @@ from kolega_code.llm.models import (
     Message,
     MessageHistory,
     RedactedThinkingBlock,
+    ResponsesReasoningBlock,
     TextBlock,
     ThinkingBlock,
     ToolCall,
@@ -113,8 +114,21 @@ def replace_image_blocks_with_placeholders(messages: List[Message], model_name:
     return result
 
 
+# Groups of providers whose reasoning is mutually replayable. The api-key
+# `openai` and the ChatGPT-subscription `openai_chatgpt` are both the OpenAI
+# Responses API, so encrypted reasoning produced by one replays cleanly to the
+# other — the one exception to "only replay reasoning to the same provider".
+_REASONING_COMPATIBLE_GROUPS: tuple[frozenset[str], ...] = (frozenset({"openai", "openai_chatgpt"}),)
+
+
 def _preserve_reasoning_block(block: Any, *, source_provider: str, target_provider: str) -> bool:
-    return bool(source_provider) and source_provider == target_provider
+    if not source_provider:
+        return False
+    if source_provider == target_provider:
+        return True
+    return any(
+        source_provider in group and target_provider in group for group in _REASONING_COMPATIBLE_GROUPS
+    )
 
 
 def _reasoning_placeholder(block: Any, source_provider: str) -> TextBlock:
@@ -134,7 +148,7 @@ def _adapt_content_blocks_for_provider(
         if isinstance(block, ImageBlock) and not supports_vision:
             adapted.append(TextBlock(text=_image_placeholder(block.media_type, target_model)))
             changed = True
-        elif isinstance(block, (ThinkingBlock, RedactedThinkingBlock)):
+        elif isinstance(block, (ThinkingBlock, RedactedThinkingBlock, ResponsesReasoningBlock)):
             if _preserve_reasoning_block(block, source_provider=source_provider, target_provider=target_provider):
                 adapted.append(block)
             else:

kolega_code-0.8.2/kolega_code/agent/errors.py

@@ -0,0 +1,9 @@
+"""Exceptions raised by agent runtime loops."""
+
+
+class AgentError(RuntimeError):
+    """Base class for catchable agent runtime errors."""
+
+
+class MaxAgentIterationsExceeded(AgentError):
+    """Raised when an opt-in agent loop iteration cap is exceeded."""

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/generalagent.py

@@ -47,6 +47,7 @@ class GeneralAgent(BaseAgent):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new GeneralAgent instance.
@@ -99,6 +100,7 @@ class GeneralAgent(BaseAgent):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         # Full coder-style toolset, minus sub-agent dispatch (a dispatched agent

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/investigationagent.py

@@ -45,6 +45,7 @@ class InvestigationAgent(BaseAgent):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new InvestigationAgent instance.
@@ -97,6 +98,7 @@ class InvestigationAgent(BaseAgent):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         self.tool_collection = ToolCollection(

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/orchestration/guide.py

@@ -134,10 +134,26 @@ After the workflow returns, integrate the results, run the full test suite yours
 report. If the plan is small or its parts are tightly coupled, skip the workflow and just
 implement it directly — orchestration is for genuinely independent fan-out.
 
+### Artifacts and transcripts
+
+`run_workflow` returns a concise manifest, not necessarily the full workflow output.
+Every completed run persists full artifacts under the state directory and returns
+paths including `resultPath` and `transcriptPath`. If the inline tool result says output was omitted, looks incomplete,
+or would require a long transcript to understand, READ `resultPath` or `transcriptPath`
+with the file-reading tools before deciding work is missing. For normal workflow
+output, use only those main files; avoid reading individual sub-agent transcripts
+unless you are explicitly debugging workflow execution.
+
+Never re-run a completed workflow solely to recover output from an omitted/truncated
+inline result. The workflow already ran; inspect the persisted result/transcript first.
+Use `resume_from_run_id` only when you intentionally want to iterate on or change the
+workflow, not as a transcript-recovery mechanism.
+
 ### Resume
 
-Each run persists its script and a journal under the state directory and returns a
-`runId` and `scriptPath`. To iterate, edit the script and re-run with `script_path`,
-or pass `resume_from_run_id` to replay cached `agent()` results for the unchanged
-prefix and only re-run new/changed calls.
+Each run persists its script, full results, a readable transcript, raw JSONL, and a
+resume journal under the state directory and returns a `runId` plus artifact paths.
+To iterate, edit the script and re-run with `script_path`, or pass `resume_from_run_id`
+to replay cached `agent()` results for the unchanged prefix and only re-run new/changed
+calls.
 """

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/orchestration/journal.py

@@ -4,9 +4,13 @@ Everything a run needs lives under::
 
     <state-dir>/workflows/<run_id>/
         script.py        the authored source (its path is returned for edit + re-run)
-        run.json         meta, args, status, timing, token totals
+        run.json         meta, args, status, timing, token totals, artifact paths
         journal.jsonl    one line per completed agent() call (drives resume)
-        agents/          per sub-agent transcripts (wired via sub_agent_recorder)
+        result.json      full JSON-rendered workflow return value
+        result.md        readable workflow return value
+        transcript.jsonl raw workflow events/call outcomes
+        transcript.md    readable workflow transcript/index
+        agents/          per sub-agent raw/readable transcripts
 
 Resume contract: scripts are deterministic (the runtime blocks ``random``/``time``
 and ``import``), so the same source + args produce ``agent()`` calls in the same
@@ -18,6 +22,7 @@ new call onward.
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
@@ -32,6 +37,15 @@ def saved_workflows_dir(state_dir: Path) -> Path:
     return workflows_root(state_dir) / "_saved"
 
 
+def _slugify(value: str, *, fallback: str = "agent", max_length: int = 64) -> str:
+    """Return a filesystem-friendly slug for workflow artifact filenames."""
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", str(value or "").strip().lower())
+    slug = re.sub(r"-+", "-", slug).strip("-._")
+    if not slug:
+        slug = fallback
+    return slug[:max_length].rstrip("-._") or fallback
+
+
 class RunJournal:
     """Owns the on-disk artifacts for a single workflow run."""
 
@@ -40,6 +54,10 @@ class RunJournal:
         self.run_id = run_id
         self.agents_dir = self.run_dir / "agents"
         self._journal_path = self.run_dir / "journal.jsonl"
+        self._transcript_jsonl_path = self.run_dir / "transcript.jsonl"
+        self._transcript_md_path = self.run_dir / "transcript.md"
+        self._result_json_path = self.run_dir / "result.json"
+        self._result_md_path = self.run_dir / "result.md"
         self._script_path = self.run_dir / "script.py"
         self._meta_path = self.run_dir / "run.json"
 
@@ -55,6 +73,33 @@ class RunJournal:
     def script_path(self) -> Path:
         return self._script_path
 
+    @property
+    def journal_path(self) -> Path:
+        return self._journal_path
+
+    @property
+    def transcript_jsonl_path(self) -> Path:
+        return self._transcript_jsonl_path
+
+    @property
+    def transcript_md_path(self) -> Path:
+        return self._transcript_md_path
+
+    @property
+    def result_json_path(self) -> Path:
+        return self._result_json_path
+
+    @property
+    def result_md_path(self) -> Path:
+        return self._result_md_path
+
+    def agent_artifact_paths(self, call_index: int, label: Optional[str] = None) -> Dict[str, Path]:
+        """Return stable per-agent raw/readable artifact paths for a workflow call."""
+        self.ensure_dirs()
+        suffix = _slugify(label or f"call-{call_index}")
+        stem = f"agent-{call_index:03d}-{suffix}"
+        return {"markdown": self.agents_dir / f"{stem}.md", "jsonl": self.agents_dir / f"{stem}.jsonl"}
+
     def write_script(self, source: str) -> Path:
         self.ensure_dirs()
         self._script_path.write_text(source, encoding="utf-8")
@@ -86,16 +131,41 @@ class RunJournal:
         label: Optional[str],
         value: Any,
         status: str = "completed",
+        **metadata: Any,
     ) -> None:
-        """Append one completed ``agent()`` result for resume replay."""
+        """Append one completed ``agent()`` result for resume replay.
+
+        ``journal.jsonl`` is the resume contract. Extra fields are allowed and ignored
+        by ``load_cache()`` so newer artifact metadata remains backward-compatible.
+        """
         self.ensure_dirs()
-        line = json.dumps(
-            {"index": call_index, "key": key, "label": label, "status": status, "value": value},
-            default=str,
-        )
+        payload = {"index": call_index, "key": key, "label": label, "status": status, "value": value}
+        payload.update({k: v for k, v in metadata.items() if v is not None})
+        line = json.dumps(payload, default=str)
         with self._journal_path.open("a", encoding="utf-8") as handle:
             handle.write(line + "\n")
 
+    def append_transcript_event(self, event: Dict[str, Any]) -> None:
+        """Append one raw workflow transcript event as JSONL."""
+        self.ensure_dirs()
+        with self._transcript_jsonl_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(event, default=str) + "\n")
+
+    def write_result_artifacts(self, result: Any, markdown: str) -> None:
+        """Persist the full workflow return value in JSON and readable Markdown."""
+        self.ensure_dirs()
+        try:
+            rendered_json = json.dumps(result, indent=2, default=str)
+        except (TypeError, ValueError):
+            rendered_json = json.dumps(str(result), indent=2)
+        self._result_json_path.write_text(rendered_json + "\n", encoding="utf-8")
+        self._result_md_path.write_text(markdown, encoding="utf-8")
+
+    def write_transcript_markdown(self, markdown: str) -> None:
+        """Persist the readable workflow transcript."""
+        self.ensure_dirs()
+        self._transcript_md_path.write_text(markdown, encoding="utf-8")
+
     def load_cache(self) -> Dict[int, Tuple[str, Any]]:
         """Read a prior run's journal into ``{call_index: (key, value)}``.
 

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/orchestration/runtime.py

@@ -150,8 +150,19 @@ class WorkflowRuntime:
 
         cached = self._resume_cache.get(index)
         if cached is not None and cached[0] == key:
-            self._emit_soon("workflow_agent_cached", {"label": spec.label or prompt[:60], "phase": spec.phase})
-            return cached[1]
+            cached_value = cached[1]
+            label = spec.label or prompt[:60]
+            self._journal.append_transcript_event(
+                {
+                    "type": "agent_cached",
+                    "index": index,
+                    "label": label,
+                    "phase": spec.phase,
+                    "value": cached_value,
+                }
+            )
+            self._emit_soon("workflow_agent_cached", {"label": label, "phase": spec.phase})
+            return cached_value
 
         self._agent_count += 1
         if self._agent_count > self._agent_cap:
@@ -169,7 +180,34 @@ class WorkflowRuntime:
 
         self.budget.add(result.tokens)
         value = result.value
-        self._journal.record(index, key, spec.label, value, status=result.status)
+        self._journal.record(
+            index,
+            key,
+            spec.label,
+            value,
+            status=result.status,
+            phase=spec.phase,
+            agent_type=spec.agent_type,
+            tokens=result.tokens,
+            error=result.error,
+            transcript_path=result.transcript_path,
+            transcript_markdown_path=result.transcript_markdown_path,
+        )
+        self._journal.append_transcript_event(
+            {
+                "type": "agent_call",
+                "index": index,
+                "label": spec.label,
+                "phase": spec.phase,
+                "agent_type": spec.agent_type,
+                "status": result.status,
+                "tokens": result.tokens,
+                "error": result.error,
+                "value": value,
+                "transcript_path": result.transcript_path,
+                "transcript_markdown_path": result.transcript_markdown_path,
+            }
+        )
         return value
 
     async def parallel(self, thunks: Iterable[Callable[[], Awaitable[Any]]]) -> List[Any]:

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/orchestration/types.py

@@ -56,6 +56,8 @@ class AgentRunResult:
     agent_id: Optional[str] = None
     status: str = "completed"  # completed | failed | skipped
     error: Optional[str] = None
+    transcript_path: Optional[str] = None
+    transcript_markdown_path: Optional[str] = None
 
     @property
     def value(self) -> Any:

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/planningagent.py

@@ -44,6 +44,7 @@ class PlanningAgent(BaseAgent):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         super().__init__(
             project_path,
@@ -70,6 +71,7 @@ class PlanningAgent(BaseAgent):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         self._completed_plan: Optional[str] = None

{kolega_code-0.8.0 → kolega_code-0.8.2}/kolega_code/agent/prompt_templates/system/agents/coder_cli.md.j2

@@ -46,6 +46,10 @@ Do not run destructive commands automatically. Treat commands that delete files,
 
 When running tests or builds, choose the smallest command that gives confidence first, then broaden verification when the change has a wider blast radius.
 
+## Git Branches and Pull Requests
+
+When creating a branch or opening a pull request, follow repository or user conventions if provided; otherwise use Conventional Commits-style names. Use lowercase kebab-case branch names with a conventional type prefix, such as `feat/add-login-rate-limit` or `fix/navbar-overlap`. Use Conventional Commit PR titles, such as `feat(auth): add session timeout` or `fix: handle empty search results`. Keep names descriptive but not overly long.
+
 ## Development Servers
 
 When starting a local development server, use an available port and tell the user the URL. If a server is already running on the default port, use another suitable port. Stop servers you started when they are no longer needed unless the user is actively testing them.