Implement bounded repository navigation with repo-lens

- Add map, find, and around commands with repository root discovery
- Stream literal ripgrep searches with match counts and result limits
- Add direct subprocess execution and explicit error returns
- Disable C++ exceptions and add navigation tests
- Support CMake installation and document builds and deployment
- Add a reusable agent skill and document skill discovery

README.md

@@ -1,16 +1,29 @@
 # repo-lens
 
-repo-lens is a planned lightweight, agent-agnostic repository navigation and context tool. It is infrastructure that coding agents can use, not an autonomous coding agent.
+repo-lens is a lightweight, agent-agnostic repository navigation and context tool. It is infrastructure that coding agents can use, not an autonomous coding agent.
 
 Coding agents often spend expensive model context rediscovering where code lives and reading irrelevant source. repo-lens aims to perform cheap, deterministic repository queries locally and return compact, bounded results, leaving the model more room to reason about the requested change.
 
-**Status:** early bootstrap stage. The repository contains a native C++ CLI skeleton and inherited build/test scaffolding, but navigation functionality is not yet implemented. The command-line executable is named `repo`.
+**Status:** first functional version. The native C++20 executable is named `repo` and implements three bounded navigation commands:
 
-The skeleton defines `find`, `map`, and `around` tool types. Argument parsing, usage output, and tool implementations remain TODOs; `around` is not dispatched yet. The existing test is a sample assertion, not a navigation test. C++ functions use trailing return types, and the tool interface requires checked `[[nodiscard]]` results and `noexcept` execution.
+```text
+repo map process
+repo find RepoLensToolFind
+repo around src/main.cpp:30
+repo around src/main.cpp:30 --before 10 --after 10
+```
 
-## Building the skeleton
+Run from anywhere inside a Git repository; the nearest ancestor containing `.git` is the root. Relative source paths are resolved from that root; absolute paths (including Windows drive letters) also work. `repo` and `repo --help` show usage.
 
-Use CMake 4.0 or newer, Ninja, and a C++20 compiler. Presets use separate build directories under `build/<preset>` and provide matching configure, build, and test commands:
+- `map` queries `docs/PROJECTMAP.md` case-insensitively, preferring heading matches over body matches. Sections end at the next heading. Output is limited to 3 sections, 120 lines, and 16 KiB, with an explicit truncation notice.
+- `find` requires ripgrep (`rg`) on `PATH`. It searches a non-empty, single-line literal, respects normal ignore rules, sorts paths, displays up to 20 occurrence locations, and counts all occurrences (including repeated matches on one line). It streams results without retaining the full search output. No semantic labels are inferred.
+- `around` shows 30 lines before and after the requested line, clamped to the file. Optional counts range from 0 to 1000. Output identifies the file, target, and actual range; malformed locations, missing files, and out-of-range lines fail clearly.
+
+No-result searches succeed. Usage/file/process errors return non-zero; ripgrep failures preserve its exit code. Subprocesses execute directly without a shell, streaming stdout and reporting up to 4096 bytes of stderr (spooled to a temporary file).
+
+## Building
+
+Use CMake 4.0 or newer, Ninja, and a C++20 compiler. C++ exceptions are disabled; recoverable failures use explicit status returns. Presets use separate build directories under `.build/<preset>` and provide matching configure, build, and test commands:
 
 ```text
 cmake --list-presets
@@ -21,7 +34,7 @@ ctest --preset msvc-debug
 
 After editing code, repeat the build and test steps; reconfigure when changing options or presets. To work in Visual Studio, open the repository folder and select a preset. Ninja does not generate a solution for `cmake --open`. Manual configuration with a Visual Studio generator still supports that command, using a separate build directory.
 
-Configuration generates `compile_commands.json` in the build directory, for example `build/msvc-debug/compile_commands.json`. Export is enabled by default for manual builds too. CMake supports this with Ninja and Makefile generators; Visual Studio solution generators do not produce it. In Visual Studio, use Open Folder with a Ninja preset when you need the compilation database.
+Configuration generates `compile_commands.json` in the build directory, for example `.build/msvc-debug/compile_commands.json`. Export is enabled by default for manual builds too. CMake supports this with Ninja and Makefile generators; Visual Studio solution generators do not produce it. In Visual Studio, use Open Folder with a Ninja preset when you need the compilation database.
 
 Choose a preset for your host and compiler:
 
@@ -38,12 +51,52 @@ Warnings remain local to project targets. `ENABLE_WARNINGS_AS_ERRORS=OFF` disabl
 
 On Windows, run these commands from an x64 Native Tools Command Prompt or Developer PowerShell for Visual Studio, with Ninja on `PATH`. On Linux, install the chosen compiler and Ninja; on macOS, install Xcode Command Line Tools and Ninja. Toolchain files in `cmake/toolchains/` select native compilers; these presets do not cross-compile to another operating system. Local paths and overrides belong in an untracked `CMakeUserPresets.json` or configure arguments.
 
-The default build includes the existing GoogleTest sample test and may download its build dependencies. For an application-only build without downloads, configure with `-DENABLE_TESTS=OFF` and skip the test step. Sanitizers are opt-in with `-DENABLE_SANITIZERS=ON`; static analysis and warnings retain their existing configuration options. Building successfully does not make the stub commands functional. Manual configuration with `cmake -S . -B build/manual` remains supported; set `-DCMAKE_BUILD_TYPE=Debug` for single-configuration generators.
+The default build includes navigation unit and integration tests and may download its build dependencies. For an application-only build without downloads, configure with `-DENABLE_TESTS=OFF` and skip the test step. Sanitizers are opt-in with `-DENABLE_SANITIZERS=ON`; static analysis and warnings retain their existing configuration options. Manual configuration with `cmake -S . -B build/manual` remains supported; set `-DCMAKE_BUILD_TYPE=Debug` for single-configuration generators.
 
 GoogleTest is pinned to v1.18.0 and managed by CMake's built-in FetchContent. To reuse a local checkout without downloading it, configure with `-DFETCHCONTENT_SOURCE_DIR_GOOGLETEST=/absolute/path/to/googletest`.
 
 CI installs CMake 4.x and runs Debug, Release, and sanitizer presets for Linux GCC/Clang, macOS AppleClang, and Windows MSVC. The inherited static-analysis helper configures Visual Studio generators; the Ninja presets do not currently run clang-tidy or Microsoft code analysis.
 
+## Installing
+
+Build Release, then install into a directory you own (Developer PowerShell on Windows):
+
+```powershell
+cmake --preset msvc-release
+cmake --build --preset msvc-release
+ctest --preset msvc-release
+cmake --install .build/msvc-release --prefix "$env:LOCALAPPDATA/repo-lens"
+```
+
+This installs `bin/repo.exe`. Add `%LOCALAPPDATA%\repo-lens\bin` to your user `PATH`, or call the installed executable by its full path. The install does not bundle ripgrep or modify `PATH`; `find` still needs `rg` available.
+
+For a Visual Studio solution build, use `cmake --build build/vs --config Release` followed by `cmake --install build/vs --config Release --prefix "$env:LOCALAPPDATA/repo-lens"`. On Linux/macOS, use the matching Release preset and install its build directory with a suitable `--prefix`, for example `"$HOME/.local"`.
+
+## Agent skill setup
+
+The reusable [repo-lens skill](skills/repo-lens/SKILL.md) teaches agents the `map -> find -> around` workflow. Copy it into a target repository using this layout:
+
+```text
+your-repository/
+├── AGENTS.md
+└── .agents/
+    └── skills/
+        └── repo-lens/
+            └── SKILL.md
+```
+
+Codex automatically discovers `.agents/skills/` directories from its current working directory up to the repository root. Personal skills can live in `~/.agents/skills/`. An `AGENTS.md` pointer is not required for Codex discovery. See the [official skill discovery documentation](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills).
+
+There is no universal discovery folder across all agents. The shared skill format is a named folder containing `SKILL.md` with `name` and `description` frontmatter; discovery paths depend on the agent. Claude uses `.claude/skills/<skill-name>/SKILL.md`; see the [migration documentation](https://developers.openai.com/cookbook/examples/agents_sdk/migrate-from-claude-agent-sdk/readme).
+
+For agents that follow `AGENTS.md` but do not scan `.agents/skills/`, add an explicit pointer:
+
+```markdown
+- Before navigating source, read and follow `.agents/skills/repo-lens/SKILL.md`.
+```
+
+Alternatively, keep the file at `docs/repolens/SKILL.md` and point to that path in `AGENTS.md`; this provides repository guidance rather than automatic skill discovery. The skill supplies instructions only: `repo` and `rg` still need to be available on `PATH`. CMake installation currently installs the executable, not the skill.
+
 ## Navigation philosophy
 
 `search -> narrow -> inspect -> expand only when necessary`
@@ -58,20 +111,9 @@ Semantic bookmarks may identify stable architectural locations in source that or
 
 Two `# @ai-bookmark` comments currently mark build invariants: the optional test dependency boundary and MSVC sanitizer annotation alignment. Their paths are listed in [the project map](docs/PROJECTMAP.md). Locate them with ripgrep for now; bookmark commands remain directional.
 
-## Directional CLI
+## Future direction
 
-These examples illustrate possible workflows. They are neither implemented nor a final command set:
-
-```text
-repo map cloth
-repo find ClothWorld
-repo bookmarks
-repo bookmark CLOTH_SOLVE
-repo around src/Physics/Cloth/ClothWorld.cpp:417
-repo history ClothWorld.cpp
-repo diff
-repo changed
-```
+Bookmarks, Git history/diff queries, symbol lookup, AST/clangd/LSP integration, telemetry, configuration files, and semantic search remain deferred. Only `map`, `find`, and `around` are implemented. The milestone measures whether `route -> narrow -> inspect` reduces context use; it adds no measurement infrastructure.
 
 ## Scope and development