feat(repl): add an interactive command-line debugger

Debug Robot Framework runs straight from the terminal — pause a run, see
where you are, inspect and change state, run keywords in the live context,
and step through execution, no editor required. It's the scriptable,
terminal-native counterpart to the VS Code extension's graphical debugger.

- **Two ways in.** `robotcode robot-debug <paths>` (alias `run-debug`) runs a
  real suite through the normal runner with the debugger attached — same
  output, options and arguments as `robotcode robot`, and the run keeps
  streaming as you step, continue or detach. `robotcode repl` (alias `shell`)
  now has the debugger built in too, so breakpoints fire while you try
  keywords at the prompt.
- **Pause where you want.** Line and keyword breakpoints (`--break
  login.robot:42`, `--break "Open Browser"`), an embedded `Breakpoint` step in
  a `.robot` file, `--stop-on-entry`, and breaking on failures (uncaught
  failures by default, plus `--break-on-all-exceptions`, `--break-on-failed-test`
  and `--break-on-failed-suite`). Every stop shows why, which keyword, and where.
- **Step through it.** `.step`/`.next`/`.return`/`.continue`/`.until`, plus
  `.detach` (stop debugging but let the run finish) and `.abort` (end it now).
- **Inspect and change state.** Walk the call stack (`.where`/`.up`/`.down`/
  `.frame`), list variables by scope (`.vars`), evaluate in the selected frame
  (`.print`/`.pprint`/`.whatis`), auto-show expressions at every stop
  (`.display`), set variables (`.set`), and run any keyword right at the prompt
  in the paused context.
- **Manage breakpoints live.** List them and add conditional, one-shot,
  logpoint or command-list breakpoints; set conditions, ignore N hits, delete,
  and disable/enable by number (`.breakpoints`/`.condition`/`.ignore`/`.delete`/
  `.disable`/`.enable`/`.commands`/`.tbreak`). Arm exception breakpoints on the
  fly with `.catch`.
- **Read source and docs in place.** `.list` shows the source at the stop,
  `.source <kw>` a named keyword's definition; the full shell command set
  (`.kw`, `.doc`, `.imports`, `.save`, …) works at the debug prompt too. On the
  rich prompt these open in a scrollable full-screen viewer with search and
  links; on the plain prompt they print inline.
- **Built for humans and agents alike.** Context-aware completion, syntax
  highlighting, persistent history and multi-line editing on the rich prompt;
  `--plain` (or `--backend` / `ROBOTCODE_REPL_*`) gives a bare prompt that reads
  commands from stdin, and the rich prompt falls back to plain automatically on
  piped input — so the debugger drives cleanly from scripts, CI or AI agents.
- Long commands accept any unambiguous prefix; one-letter aliases mirror pdb.

Author: d-biehl

docs/03_reference/index.md

@@ -14,6 +14,8 @@ This reference provides a comprehensive resource for effectively using and confi
 
 - [**Discovering Tests, Tasks and Suites**](discovering-tests.md): A task-oriented guide to the `robotcode discover` family of commands — turning a project's source files into a tree, flat lists, tag indexes, or a file inventory without ever executing a test. Covers Robot-native and search filters, the `TestItem` JSON schema used by editor integrations, and CI recipes for sharding, tag reports, and parse-error gates.
 
-- [**Interactive Robot Framework REPL**](repl.md): A task-oriented guide to the `robotcode repl` command — a live keyword-driven shell for exploring libraries, prototyping snippets, debugging keyword behaviour and capturing ad-hoc sessions as a normal `output.xml` / `log.html`. Covers the prompt model, state persistence, file-execution and `--inspect` mode, output capture, and recipes for library exploration and CI smoke checks.
+- [**Interactive Robot Framework REPL**](repl.md): A task-oriented guide to the `robotcode repl` command — a live keyword-driven shell for exploring libraries, prototyping snippets, debugging keyword behaviour and capturing ad-hoc sessions as a normal `output.xml` / `log.html`. Covers the prompt model, state persistence, file-execution and `--inspect` mode, output capture, and recipes for library exploration and CI smoke checks. Also covers the built-in `pdb`-style **command-line debugger** (`robotcode robot-debug`) — breakpoints, stepping, the call stack, per-frame variables, and source listing.
+
+- [**Working with AI Agents**](ai-agents.md): How **RobotCode** lets AI coding agents (GitHub Copilot Chat, Claude Code, Codex, and other Open-Plugins-compatible tools) work through the project's own `robotcode` CLI instead of guessing. Covers the bundled VS Code chat plugin and its toggle, installing the plugin in other agents via the marketplace, what the agent is taught to do (discover, libdoc, REPL, results, analyze on the resolved project), and the CLI's AI-agent detection that keeps captured terminal output clean.
 
 Together, these sections provide the knowledge needed to fully customize `robotcode` for a flexible and efficient testing workflow.

docs/03_reference/repl.md

@@ -4,11 +4,30 @@
 
 
 class Repl:
+    """Marker library backing the RobotCode REPL/debugger integration.
+
+    ``Breakpoint`` is the one keyword meant for use in your own suites (to pause
+    into the debug prompt under ``robotcode robot-debug``); ``Repl`` and ``Exit``
+    are used internally by ``robotcode repl`` and aren't normally called by hand.
+    """
+
     ROBOT_LIBRARY_SCOPE = "GLOBAL"
     ROBOT_LIBRARY_VERSION = __version__
 
     def repl(self) -> None:
-        pass
+        """Internal marker keyword that opens the interactive REPL prompt.
+
+        Called by the synthetic suite ``robotcode repl`` runs; not meant to be
+        used directly in your own tests.
+        """
+
+    def breakpoint(self) -> None:
+        """No-op marker keyword: the RobotCode debugger pauses here when attached.
+
+        Place ``Breakpoint`` in a suite (after ``Library    robotcode.repl.Repl``)
+        to drop into the debug prompt at that point under ``robotcode robot-debug``;
+        in a normal ``robot`` run it does nothing.
+        """
 
     def exit(self, exit_code: int = 0) -> None:
         sys.exit(exit_code)

packages/repl/src/robotcode/repl/Repl/repl.py

@@ -0,0 +1,35 @@
+"""Synchronous, logger-driven Robot Framework debug core.
+
+The `DebugController` consumes the keyword event stream (start/end) emitted by
+the interpreter's logger (see `BaseInterpreter.register_observer`) and
+drives pausing/stepping/inspection through a small `Frontend` protocol. It is
+deliberate that this core knows nothing about threads, sockets, or DAP — those
+are concerns of a particular front-end. The CLI front-end is the
+`ConsoleInterpreter` itself (it implements `Frontend.wait_at_stop`).
+"""
+
+from .controller import DebugController
+from .types import (
+    Breakpoint,
+    DebugTerminated,
+    Frontend,
+    ResumeAction,
+    Scope,
+    StackFrame,
+    StopEvent,
+    StopReason,
+    Variable,
+)
+
+__all__ = [
+    "Breakpoint",
+    "DebugController",
+    "DebugTerminated",
+    "Frontend",
+    "ResumeAction",
+    "Scope",
+    "StackFrame",
+    "StopEvent",
+    "StopReason",
+    "Variable",
+]