python-delphi-lsp 2.3.1__tar.gz → 2.3.3__tar.gz

{python_delphi_lsp-2.3.1/python_delphi_lsp.egg-info → python_delphi_lsp-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.3.1
+Version: 2.3.3
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -42,7 +42,7 @@ Dynamic: license-file
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.3 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -166,7 +166,8 @@ available without returning the complete file as agent context.
 Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
 Its resolution order is:
 
-1. An explicit project selection takes precedence.
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
 2. Otherwise, `.dpr` and `.dpk` candidates are considered.
 3. `MainSource` in a `.dproj` contributes its entry project.
 4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
@@ -175,11 +176,13 @@ Its resolution order is:
 6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
    directory to unit search paths.
 
-A single discovered project is selected automatically. With no project entry,
-the server uses a synthetic workspace of supported sources. Scans skip build
-and cache directories such as `build`, `dist`, environments, VCS folders,
-`node_modules`, and tool caches. Missing paths and invalid metadata become
-problems; paths are not guessed.
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
 
 ## Agent CLI and Interface/Protocol v2
 
@@ -197,7 +200,7 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
-                      [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
                       [--cursor TEXT] [--max-items INT] [--max-chars INT]
 delphi-lsp-agent skill install [--target PATH] [--force]
@@ -229,6 +232,32 @@ delphi-lsp-agent query --root PATH metrics UNIT_QUERY
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. Pass one when its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/README.md

@@ -2,7 +2,7 @@
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.3 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -126,7 +126,8 @@ available without returning the complete file as agent context.
 Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
 Its resolution order is:
 
-1. An explicit project selection takes precedence.
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
 2. Otherwise, `.dpr` and `.dpk` candidates are considered.
 3. `MainSource` in a `.dproj` contributes its entry project.
 4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
@@ -135,11 +136,13 @@ Its resolution order is:
 6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
    directory to unit search paths.
 
-A single discovered project is selected automatically. With no project entry,
-the server uses a synthetic workspace of supported sources. Scans skip build
-and cache directories such as `build`, `dist`, environments, VCS folders,
-`node_modules`, and tool caches. Missing paths and invalid metadata become
-problems; paths are not guessed.
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
 
 ## Agent CLI and Interface/Protocol v2
 
@@ -157,7 +160,7 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
-                      [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
                       [--cursor TEXT] [--max-items INT] [--max-chars INT]
 delphi-lsp-agent skill install [--target PATH] [--force]
@@ -189,6 +192,32 @@ delphi-lsp-agent query --root PATH metrics UNIT_QUERY
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. Pass one when its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 

python_delphi_lsp-2.3.3/delphi_lsp/_version.py

@@ -0,0 +1 @@
+__version__ = "2.3.3"

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/delphi_lsp/agent_cache.py

@@ -639,6 +639,21 @@ def _read_startup_tail(diagnostics: object, *, max_bytes: int = _STARTUP_DIAGNOS
     return b""
 
 
+def _daemon_process_options() -> dict[str, object]:
+    options: dict[str, object] = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+    }
+    if os.name == "nt":
+        options["creationflags"] = (
+            subprocess.CREATE_NO_WINDOW
+            | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+    else:
+        options["start_new_session"] = True
+    return options
+
+
 class _CacheService:
     def __init__(self, metadata: CacheMetadata) -> None:
         self.metadata = metadata
@@ -664,6 +679,7 @@ class _CacheService:
         self.last_budget = BudgetResult(0, 0.0, 0.0, False, False, False)
         self.prewarm_seconds = 0.0
         self.shutdown = threading.Event()
+        self.prewarm_thread: threading.Thread | None = None
 
     def _measure_retained_bytes(self) -> int:
         process_rss = current_process_rss_bytes()
@@ -694,15 +710,38 @@ class _CacheService:
         self.prewarm_seconds = time.monotonic() - started
         self.stats.parallel_fallbacks = self.context.parallel_stats.fallbacks
 
+    def start_prewarm(self) -> None:
+        def run() -> None:
+            try:
+                with self.lock:
+                    self.prewarm()
+            except Exception:
+                self.cache_state = "failed"
+
+        self.prewarm_thread = threading.Thread(
+            target=run,
+            name="delphi-cache-prewarm",
+            daemon=True,
+        )
+        self.prewarm_thread.start()
+
     def request(self, request: dict[str, object]) -> CacheClientResponse:
+        action = request.get("action")
+        if action == "status":
+            warning = "" if request.get("_startup_probe") is True else self._consume_warning()
+            return CacheClientResponse(self.status(), warning)
+        if action == "stop":
+            self.shutdown.set()
+            return CacheClientResponse({"stopping": True})
+        if self.cache_state == "warming":
+            self.last_activity = time.monotonic()
+            raise CacheClientError(
+                "cache_warming",
+                "Cache is still warming. Retry after cache status reports ready.",
+            )
+        if self.cache_state == "failed":
+            raise CacheClientError("cache_failed", "Cache warm-up failed.")
         with self.lock:
-            action = request.get("action")
-            if action == "status":
-                warning = "" if request.get("_startup_probe") is True else self._consume_warning()
-                return CacheClientResponse(self.status(), warning)
-            if action == "stop":
-                self.shutdown.set()
-                return CacheClientResponse({"stopping": True})
             self.last_activity = time.monotonic()
             before = self.last_revision
             was_warm = self.context.navigation_cache_is_warm
@@ -850,7 +889,7 @@ def run_cache_daemon(
     watcher: threading.Thread | None = None
     try:
         service = _CacheService(metadata)
-        service.prewarm()
+        _write_metadata(metadata)
         watcher = threading.Thread(
             target=_watch_workspace,
             args=(service,),
@@ -858,8 +897,14 @@ def run_cache_daemon(
             daemon=True,
         )
         watcher.start()
-        _write_metadata(metadata)
-        while not service.shutdown.is_set() and time.monotonic() - service.last_activity < idle_timeout:
+        service.start_prewarm()
+        while (
+            not service.shutdown.is_set()
+            and (
+                service.cache_state == "warming"
+                or time.monotonic() - service.last_activity < idle_timeout
+            )
+        ):
             try:
                 connection, _ = listener.accept()
             except socket.timeout:
@@ -921,11 +966,7 @@ def _start_cache_unlocked(
     ]
     if project:
         command.extend(("--project-file", project))
-    options: dict[str, object] = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL}
-    if os.name == "nt":
-        options["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
-    else:
-        options["start_new_session"] = True
+    options = _daemon_process_options()
     with tempfile.TemporaryFile() as diagnostics:
         options["stderr"] = diagnostics
         process = subprocess.Popen(command, **options)
@@ -1000,7 +1041,13 @@ def query_cache(root: str | Path, request: dict[str, object]) -> CacheClientResp
     if not _pid_alive(metadata.pid):
         _remove_metadata_if_owned(metadata)
         raise CacheClientError("cache_not_running", "Cache daemon is not running.")
-    return _client_exchange(metadata, request)
+    while True:
+        try:
+            return _client_exchange(metadata, request)
+        except CacheClientError as error:
+            if error.code != "cache_warming":
+                raise
+            time.sleep(0.05)
 
 
 def cache_status(root: str | Path) -> dict[str, object]:

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/delphi_lsp/agent_cli.py

@@ -151,7 +151,14 @@ def build_parser() -> argparse.ArgumentParser:
 
 def _add_cache_start_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--root", type=Path, default=Path("."))
-    parser.add_argument("--project-file", type=Path)
+    parser.add_argument(
+        "--project-file",
+        type=Path,
+        help=(
+            "Optionally select a .dproj, .dpr, or .dpk file, relative to "
+            "--root if needed."
+        ),
+    )
     parser.add_argument("--max-memory", type=parse_memory_size, default=DEFAULT_MAX_MEMORY_BYTES)
     parser.add_argument("--workers", type=parse_worker_setting, default=0)
     parser.add_argument("--idle-timeout", type=_positive_integer, default=DEFAULT_IDLE_TIMEOUT)

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/delphi_lsp/agent_context.py

@@ -853,6 +853,7 @@ class AgentContext:
             )
         elif request.project_id:
             self._focus = Focus(project_id=self._workspace.active_project_id)
+            self._require_registry(revision)
         return self._response(request, revision, [self._focus.to_mapping()])
 
     def _handle_metrics(self, request: AgentRequest, revision: str) -> AgentResponse:
@@ -992,7 +993,8 @@ class AgentContext:
         if not project_id:
             raise AgentProtocolError(
                 "project_required",
-                "Select a project before querying symbols.",
+                "Multiple projects were found. Run 'query open', then select one "
+                "with 'query focus --project-id PROJECT_ID'.",
             )
         return project_id
 

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/delphi_lsp/agent_templates.py

@@ -220,7 +220,7 @@ Inspect Delphi/Object Pascal only through `delphi_codebase`; never raw bash/read
 
 ## Protocol v2 workflow
 
-1. Call `open`. If the requested project is not active, select it with `focus(project_id)`.
+1. Call `open`. A multi-project repository is active as one workspace by default; select a concrete project with `focus(project_id)` only when project-specific compiler context is needed.
 2. Call `find` with a narrow query, then `focus(target_id)` for the returned target.
 3. Inspect focused details in this order as needed: `summary`, `declaration`, `members`, `context`, `body`, `implementations`.
 4. Trace relations with `references`, `callers`, `callees`, `uses`, `used_by`, `inherits`, or `implements`.

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/delphi_lsp/agent_workspace.py

@@ -112,6 +112,21 @@ class AgentWorkspace:
         )
         projects: list[AgentProject] = []
         project_paths: dict[str, Path | None] = {}
+        default_project_id = ""
+        if (
+            resolved_project_file is None
+            and len(discovery.project_files) > 1
+        ):
+            default_project_id = make_target_id("project", "", "workspace")
+            projects.append(
+                AgentProject(
+                    project_id=default_project_id,
+                    name="Workspace",
+                    path=".",
+                    kind="workspace",
+                )
+            )
+            project_paths[default_project_id] = None
         if discovery.project_files:
             for value in discovery.project_files:
                 path = Path(value)
@@ -140,7 +155,9 @@ class AgentWorkspace:
             project_paths[project_id] = None
 
         workspace = cls(root_path, discovery, tuple(projects), project_paths)
-        if len(projects) == 1:
+        if default_project_id:
+            workspace.select_project(default_project_id)
+        elif len(projects) == 1:
             workspace.select_project(projects[0].project_id)
         return workspace
 
@@ -305,7 +322,11 @@ class AgentWorkspace:
         project_path = self._project_paths[project_id]
         cached = self._project_cache.get(project_id)
         if project_path is None:
-            discovery = self._discovery if cached is None else discover_workspace_sources(self._root)
+            discovery = (
+                self._discovery
+                if cached is None and self._discovery.source_files
+                else discover_workspace_sources(self._root)
+            )
         else:
             discovery = discover_delphi_project(
                 self._root,

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/delphi_lsp/project_discovery.py

@@ -146,7 +146,21 @@ def discover_delphi_project(
     for value in defines:
         add_define(value)
 
-    candidates = _project_candidates(root_path, project_path)
+    explicit_dproj: Path | None = None
+    if (
+        project_path is not None
+        and project_path.suffix.casefold() == ".dproj"
+    ):
+        explicit_dproj = project_path
+        project_path = _project_entry_from_dproj(
+            explicit_dproj,
+            discovery,
+        )
+    candidates = (
+        []
+        if explicit_dproj is not None and project_path is None
+        else _project_candidates(root_path, project_path)
+    )
     for project in candidates:
         key = str(project).casefold()
         if key not in seen_projects:
@@ -160,8 +174,13 @@ def discover_delphi_project(
                 seen_search,
                 discovery.search_path_origins,
             )
-        dproj = project.with_suffix(".dproj")
-        if dproj.exists():
+        dproj_candidates = [project.with_suffix(".dproj")]
+        if explicit_dproj is not None:
+            dproj_candidates.insert(0, explicit_dproj)
+        for dproj in dproj_candidates:
+            config_key = str(dproj).casefold()
+            if config_key in seen_configs or not dproj.exists():
+                continue
             _read_dproj(
                 dproj,
                 discovery,
@@ -173,7 +192,7 @@ def discover_delphi_project(
                 discovery.include_path_origins,
                 add_define,
             )
-            seen_configs.add(str(dproj).casefold())
+            seen_configs.add(config_key)
             discovery.config_files.append(str(dproj))
         for cfg in (project.with_suffix(".cfg"), project.with_suffix(".dof")):
             if cfg.exists():
@@ -483,6 +502,72 @@ def _main_source_from_dproj(path: Path) -> str | None:
     return None
 
 
+def _project_entry_from_dproj(
+    path: Path,
+    discovery: DelphiProjectDiscovery,
+) -> Path | None:
+    try:
+        root = ET.parse(path).getroot()
+    except ET.ParseError as exc:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                f"Could not parse Delphi project file: {exc}",
+                str(path),
+            )
+        )
+        return None
+    except OSError as exc:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                f"Could not read Delphi project file: {exc}",
+                str(path),
+            )
+        )
+        return None
+
+    main_source = next(
+        (
+            (element.text or "").strip()
+            for element in root.iter()
+            if _xml_local_name(element.tag) == "MainSource"
+            and (element.text or "").strip()
+        ),
+        "",
+    )
+    if not main_source:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                "Delphi project file does not define MainSource.",
+                str(path),
+            )
+        )
+        return None
+
+    entry = (path.parent / main_source).resolve()
+    if entry.suffix.casefold() not in PROJECT_EXTENSIONS:
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                "MainSource must reference a .dpr or .dpk entry file.",
+                str(path),
+            )
+        )
+        return None
+    if not entry.is_file():
+        discovery.problems.append(
+            DiscoveryProblem(
+                "cant_read_project",
+                f"MainSource does not exist: {entry}",
+                str(path),
+            )
+        )
+        return None
+    return entry
+
+
 def _scan_sources(
     root: Path,
     discovery: DelphiProjectDiscovery,

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-delphi-lsp"
-version = "2.3.1"
+version = "2.3.3"
 description = "Python Delphi/Object Pascal parser, semantic indexer, and language server."
 readme = "README.md"
 requires-python = ">=3.10"

{python_delphi_lsp-2.3.1 → python_delphi_lsp-2.3.3/python_delphi_lsp.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.3.1
+Version: 2.3.3
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -42,7 +42,7 @@ Dynamic: license-file
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.3.1 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.3.3 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -166,7 +166,8 @@ available without returning the complete file as agent context.
 Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files.
 Its resolution order is:
 
-1. An explicit project selection takes precedence.
+1. An explicit `.dproj`, `.dpr`, or `.dpk` selection takes precedence. An
+   explicit `.dproj` resolves its `MainSource`.
 2. Otherwise, `.dpr` and `.dpk` candidates are considered.
 3. `MainSource` in a `.dproj` contributes its entry project.
 4. A selected entry associates same-stem `.dproj`, `.cfg`, and `.dof`.
@@ -175,11 +176,13 @@ Its resolution order is:
 6. Direct `Unit in 'path/Unit.pas'` references contribute their parent
    directory to unit search paths.
 
-A single discovered project is selected automatically. With no project entry,
-the server uses a synthetic workspace of supported sources. Scans skip build
-and cache directories such as `build`, `dist`, environments, VCS folders,
-`node_modules`, and tool caches. Missing paths and invalid metadata become
-problems; paths are not guessed.
+A single discovered project is selected automatically. With multiple project
+entries, a synthetic repository workspace containing every supported source is
+selected automatically while the concrete projects remain available. With no
+project entry, the same workspace model is used. Scans skip build and cache
+directories such as `build`, `dist`, environments, VCS folders, `node_modules`,
+and tool caches. Missing paths and invalid metadata become problems; paths are
+not guessed.
 
 ## Agent CLI and Interface/Protocol v2
 
@@ -197,7 +200,7 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
-                      [--project-id FILE] [--detail summary|declaration|members|context|body|implementations]
+                      [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
                       [--cursor TEXT] [--max-items INT] [--max-chars INT]
 delphi-lsp-agent skill install [--target PATH] [--force]
@@ -229,6 +232,32 @@ delphi-lsp-agent query --root PATH metrics UNIT_QUERY
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+The repository root is sufficient even when it contains many projects:
+
+```bash
+delphi-lsp-agent cache start --root PATH
+delphi-lsp-agent query --root PATH find TCustomer
+```
+
+This prewarms one bounded repository navigation index and requires no project
+selection. A `.dproj` is optional. Pass one when its project-specific compiler
+settings and `MainSource` should define the index:
+
+```bash
+delphi-lsp-agent cache start --root PATH --project-file relative/path/Main.dproj
+```
+
+An explicit `.dpr` or `.dpk` remains supported. To switch an already running
+repository cache to one of its concrete project views, list the projects and
+focus one by its returned `project_id`:
+
+```bash
+delphi-lsp-agent query --root PATH open
+delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
+```
+
+Selecting a project this way also prewarms its navigation cache.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.