docs(skill): add a cross-repository recipe to the orbit-cli SQL reference
What does this MR do and why?
The orbit-cli skill's SQL reference has recipes for callers, callees, subtypes and imports, all within one repository, and describes the manifest table as bookkeeping. Nothing in the file shows how code in one indexed repository reaches a definition in another. This adds one recipe that resolves an imported symbol to its definition in another indexed repository, and lists the manifest as a table to query.
Related Issues
Relates to #1008 (closed).
Testing
Ran the recipe on orbit 0.119.0 against two indexed repositories, one importing a symbol the other defines. From inside a checkout with no flag it returns zero rows and prints nothing to stderr; with --all it returns the cross-repository row; from outside a checkout it returns the same row along with the existing stderr note. Re-indexing a repository at a second commit replaced its rows rather than adding to them, so no stale rows appeared and no commit_sha predicate is needed. The skill version-bump check passes.
Performance Analysis
Documentation only, no code paths change.
- This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context — long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered
Scope. skills/orbit-cli/references/sql.md: one table row for _orbit_manifest, project_id added to the key columns of the two rows the recipe joins (gl_file and gl_directory carry it too and are left as curated), one recipe after "Who imports a symbol", one note on edges. skills/orbit-cli/SKILL.md: the version line only, 0.5.2 to 0.5.3.
Why the recipe passes --all. 0905ce6b scopes the node tables to the current checkout, and _orbit_manifest is exempt from that scoping, so the cross-repository join returns nothing without the flag and says nothing about why.
flowchart TD
S["orbit sql, run inside an indexed checkout"] --> Q{"--all passed?"}
Q -->|"no"| V["scope_to_checkout creates TEMP VIEWs over gl_definition and gl_imported_symbol, pinned to this project_id and commit_sha"]
V --> M["_orbit_manifest has no id column, so it is never scoped and stays one row per checkout"]
M --> Z["im and dm resolve to the same row, dm.repo_path is never unequal to im.repo_path, and the query returns zero rows"]
Q -->|"yes"| N["no views created, node tables span every indexed repository"]
N --> R["join through _orbit_manifest returns the cross-repository row"]Why the manifest. gl_edge carries no project_id, and the fixture held no edge with endpoints in two repositories, so a cross-repository question is a join, and _orbit_manifest is the only table that maps project_id to a repository path. project_id is per checkout, and each one carries a single indexed commit, so joining on project_id alone is sufficient and a commit_sha predicate filters nothing.
Mirror surfaces. docs/source/local/getting-started.md still calls _orbit_manifest a bookkeeping table. It is left alone here: that page is being restructured, and the wording fix belongs with that work.
Form. Quoting, indentation and lead-line shape follow the six recipes already in the file. The join matches on symbol name, so the note says how to narrow it.
Provenance. First run on 0.111.0 on 2026-09-02, re-run on 0.115.0 on 2026-09-04, and re-verified on 0.119.0 after the scoping change landed.
%{all_commits}