docs: bootstrap repo-lens project guidance

Document the project purpose, bounded-context navigation philosophy,
intended C++ CLI direction, and incremental benchmarking goals.

Add compact agent instructions and a project map for the existing
starter scaffolding. Clarify that CLI examples are provisional and
repo-lens functionality is not yet implemented.

README.md

@@ -1,4 +1,44 @@
-# blank-slate
-[![build](https://github.com/McMassiveNZ/blank-slate/actions/workflows/ci.yml/badge.svg)](https://github.com/McMassiveNZ/blank-slate/actions/workflows/ci.yml)
+# repo-lens
 
-A blank slate cpp project containing boilerplate for CMake, testing and basic CI
+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.
+
+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 documentation/bootstrap stage. The repository contains inherited C++ starter scaffolding, but repo-lens functionality is not yet implemented. The initial implementation is intended to be a native C++ command-line tool with the executable name `repo`.
+
+## Navigation philosophy
+
+`search -> narrow -> inspect -> expand only when necessary`
+
+Prefer symbol lookup when available for a known symbol, textual search for known text, and sparse semantic bookmarks for architectural concepts without a suitable symbol. Inspect a bounded source range or containing symbol, then expand into callers, callees, references, tests, or related code only when needed. Read whole files when justified.
+
+The tool should primarily orchestrate proven tools such as ripgrep (`rg`) and Git. Later, ast-grep or optional Clang/clangd/LSP information may improve navigation. Richer tooling should enhance simpler mechanisms; repo-lens must remain useful without parsers, language servers, semantic indexes, or network access.
+
+Results should have explicit context limits. A query with hundreds of matches should return a compact summary with total and shown counts instead of dumping every match. Semantic labels such as definitions or calls should appear only when supported by reliable evidence, not inferred with false precision from plain text matches.
+
+Semantic bookmarks may identify stable architectural locations in source that ordinary symbols cannot express. They should be sparse and avoid duplicating easily searchable symbols; lookup should lead to a bounded source excerpt.
+
+## Directional CLI
+
+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
+```
+
+## Scope and development
+
+Favour simple composable commands, human-readable output, agent-agnostic interfaces, progressive disclosure, and low maintenance cost. Source code and Git remain the canonical sources of truth; there will be no separate AI changelog or persistent agent history. Decision documents should preserve otherwise hard-to-recover rationale or invariants rather than duplicate source.
+
+Embeddings, vector databases, semantic RAG infrastructure, persistent AI memory, agent-specific SDKs, MCP dependencies, core language-server dependencies, and large repository metadata systems are deliberately out of scope unless measurements later demonstrate a real need.
+
+Development will be incremental and benchmarked. The objective is **context consumed per acceptable engineering result**, not minimum token usage alone. Useful measurements include files inspected, source lines or bytes returned, tool calls, irrelevant reads, whole-file reads, build/test attempts and failures, edit/retry cycles, elapsed time, token usage where exposed, and human corrections. Results must also be assessed for correctness, architectural and coding-style fit, unnecessary changes, and human rework. Lightweight command instrumentation may support this later; it is not implemented yet.
+
+See [the project map](docs/PROJECTMAP.md) for current repository routes and [agent instructions](AGENTS.md) for working expectations.