pi-fovea 0.31.0 → 0.31.2

package/README.md

@@ -108,6 +108,8 @@ Runtime slash controls:
 
 ## Install
 
+**0.31.2 compatibility:** tested against Pi 0.99.0 (Node 22.19+ for the extension). Pi APIs and TypeBox are host-provided wildcard peers, never bundled; development pins Pi 0.99.0 and TypeBox 1.3.27. Native codemode-only and Fabric declaration hiding leave Fovea tools callable, including nested grep middleware. The standalone CLI remains Node 20+ and host-free.
+
 Requires Node.js 20+. The install provisions [ast-grep](https://ast-grep.github.io/) automatically through the `@ast-grep/cli` npm optional dependency; an `ast-grep` found on PATH takes precedence over the packaged copy, and `FOVEA_AST_GREP=/path/to/sg` overrides both. Bend-only and config/protocol-only roots work without ast-grep; it is required when discovery or refresh includes a language that uses its parser.
 
 ```sh
@@ -156,6 +158,20 @@ From a checkout, `bun run fovea` runs the live source via `tsx`, and `bun run bu
 `bun run pack:cli` produces the scoped CLI tarball at `dist/fovea-cli.tgz` using the
 root package version. See [CLI usage](docs/cli.md) and [release checks and publishing](docs/releasing.md).
 
+## Agent skills
+
+Choose the skill for the interface your agent uses:
+
+| Skill | Use it for |
+| --- | --- |
+| [pi-fovea](skills/pi-fovea/SKILL.md) | Pi extension tools, persistent focus/dwell, turn sync, and Fabric integration. |
+| [fovea](skills/fovea/SKILL.md) | Standalone shell/CI commands, explicit repository roots, and stateless navigation. |
+
+The Pi package exposes both skills. The standalone `@monotykamary/fovea` package
+ships only `skills/fovea/SKILL.md`; register that directory with your agent's skill
+loader, or copy it into its skills directory. Installing the CLI alone does not
+register a skill with an agent.
+
 ## Many projects, one conversation
 
 Your Pi cwd can be a parent folder, a launcher, or unrelated to the work.

package/docs/cli.md

@@ -35,6 +35,18 @@ The trailing number is the output token budget. Each CLI invocation is
 stateless; use the Pi extension for focus and dwell across an interactive
 session.
 
+## Agent skill
+
+The standalone package includes `skills/fovea/SKILL.md`, a portable **fovea**
+skill with navigation, impact, coverage, and stateless CLI workflows. Register
+that directory with your agent's skill loader, or copy it into the agent's skills
+directory. Installing the executable alone does not register the skill.
+
+For a global npm install, the skill directory is
+`$(npm root -g)/@monotykamary/fovea/skills/fovea`. It is also available in the
+[source repository](https://github.com/monotykamary/pi-fovea/tree/main/skills/fovea).
+The separate **pi-fovea** skill covers Pi extension tools and session behavior.
+
 ## Pi extension
 
 Install the separate `pi-fovea` package in Pi:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.31.0",
+  "version": "0.31.2",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",
@@ -87,13 +87,13 @@
     "test:smoke": "vitest run tests/verified-kernels.test.ts tests/startup.test.ts tests/config.test.ts tests/settings.test.ts tests/substrate.test.ts tests/scan.test.ts tests/extract.test.ts tests/join.test.ts tests/heat.test.ts tests/nuclei.test.ts tests/render.test.ts"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.86.0",
-    "@earendil-works/pi-tui": "0.86.0",
+    "@earendil-works/pi-coding-agent": "0.99.0",
+    "@earendil-works/pi-tui": "0.99.0",
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.1",
     "knip": "^6.32.0",
     "tsx": "^4.19.0",
-    "typebox": "^1.3.10",
+    "typebox": "1.3.27",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"
   },

package/skills/fovea/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: fovea
+description: Token-efficient repository navigation with the standalone fovea CLI, independent of Pi. Use from an agent shell or CI to survey an unfamiliar repository, locate symbols and routes, trace dependencies, assess change impact, or refresh context after edits. Use the pi-fovea skill instead when working through Pi's session-aware extension tools.
+compatibility: Requires the fovea executable and Node.js 20+. Most source languages also need ast-grep, supplied by the CLI's optional dependency or available on PATH.
+---
+
+# Fovea
+
+Fovea builds a cross-language code graph of routes, symbols, imports, calls, and
+string/env literals. Start with a cheap silhouette, focus on a question, then
+read the indicated source ranges. This skill uses only the standalone `fovea`
+command; no Pi installation or extension tools are required.
+
+## Setup
+
+If `fovea` is missing, install the standalone package with the user's permission:
+
+```sh
+npm install -g @monotykamary/fovea
+```
+
+The executable is `fovea`. The legacy global `pi-fovea` package also supplies it;
+choose one global package, not both. No TypeScript loader or Bend compiler is
+needed for the installed CLI. In a Fovea source checkout with development
+dependencies installed, `bun run fovea <command> ...` runs the live source.
+
+Most source languages require ast-grep. The optional `@ast-grep/cli` dependency
+supplies it; an `ast-grep` on PATH takes precedence, and `FOVEA_AST_GREP` can select
+an explicit executable. If optional dependencies were omitted, arrange for
+ast-grep before treating missing source results as meaningful.
+
+## Navigation loop
+
+Always pass an explicit root (`.` or a repository path), then quote the query.
+This avoids ambiguity between a query containing `/` and a root path. File
+selectors in impact are relative to that root, not the shell's working directory.
+
+```sh
+fovea sketch /path/to/repo 900
+fovea focus /path/to/repo "CreateUserHandler" 1200
+fovea focus /path/to/repo "/api/users" 1200
+fovea focus /path/to/repo "src/api.ts" 1200
+```
+
+1. **Sketch** once to find production entry points and source regions. Test and
+   fixture architecture is collapsed; start around 512–1024 tokens.
+2. **Focus** on a symbol, route, env key, or file. Read relevant source windows
+   before making claims or edits. Close symbol spellings can resolve too.
+3. **Impact** before a risky edit to find likely dependents and review order.
+4. **Refresh** by rerunning focus or impact after edits, then run the project's
+   targeted checks. Graph output is navigation evidence, not verification.
+
+The trailing positive number is an approximate output token budget (about four
+characters per token). Sketch, focus, and impact default to 512 and clamp to
+256–16000. If the output is too narrow, rerun with a larger budget or a more
+specific query. When an overflow footer names a text artifact, read or search
+that exact path for the remaining eligible candidates; do not assume an artifact
+exists when no path is returned.
+
+## Change impact
+
+```sh
+# Current uncommitted changes (default).
+fovea impact /path/to/repo 1200
+
+# What-if analysis, without mixing in uncommitted changes.
+fovea impact /path/to/repo --files src/api.ts,src/types.ts --no-uncommitted 1200
+fovea impact /path/to/repo --symbols CreateUserHandler --no-uncommitted 1200
+
+# PR-style changes: git diff main...HEAD, not the working tree.
+fovea impact /path/to/repo --base main 1200
+```
+
+`--files` and `--symbols` take comma-separated values. Without `--no-uncommitted`,
+explicit seeds also include uncommitted changes; `--base` replaces that automatic
+working-tree selection with the three-dot diff. Use a base ref available locally.
+In a non-Git directory, use explicit file or symbol seeds rather than relying on
+a diff. Heat and co-change companions suggest where to inspect, not which files
+must change or which checks have passed.
+
+## Coverage and discovery
+
+```sh
+fovea status /path/to/repo
+fovea anchors /path/to/repo "/api/users"
+fovea anchors /path/to/repo --discovered
+fovea rules /path/to/repo
+fovea rules /path/to/repo --sigs
+```
+
+- **Status** summarizes index coverage and extraction problems. Missing parser
+  support, excluded files, and unresolved imports limit what the graph can say.
+- **Anchors** lists sorted, tab-separated anchor rows; the optional filter is a
+  substring match. `--discovered` keeps inferred anchors only. This listing is
+  not token-budgeted, so filter it instead of dumping a large repository.
+- **Rules** shows discovered shape hypotheses as JSON lines, or a plain-text
+  message if none qualify. `--sigs` shows supporting signature statistics.
+  `fovea rules /path/to/repo --adopt` **writes** promoted rules to
+  `.fovea/rules.json`; use it only when intentionally adopting reviewed rules.
+
+## CLI boundaries
+
+- Each invocation starts fresh. Disk caches speed extraction, but there is no
+  persistent focus, seen-result suppression, workspace attention, or turn sync.
+  A separate `fovea dwell` invocation cannot widen an earlier CLI focus; rerun
+  `focus` with a larger budget instead.
+- Output is rendered text on stdout, errors on stderr. There are no general
+  `--json` or `--tsv` output modes; anchors and rules have the formats noted above.
+  Pi tool arguments such as `fresh`, `path`, `language`, and `kind` are not CLI
+  flags. Do not assume unknown flags are validated.
+- Prefer graph navigation to bulk reading, but use native text search for exact
+  literals, regexes, or missing graph results. Small repositories may not need a
+  graph at all. Import coverage is not universal, and a possible import is not
+  proof of an exact dependency. Always inspect source and keep acceptance tests
+  in the host workflow.

package/skills/pi-fovea/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: pi-fovea
-description: Token-efficient repo navigation with the pi-fovea code graph. Use when you need to survey an unfamiliar repository, trace where a symbol or route lives and what depends on it, assess the blast radius of a change before editing, or re-orient after files have been edited mid-session (by any tool path, including bash and pi-fabric fabric_exec programs).
+description: Token-efficient repo navigation through the pi-fovea extension tools in Pi. Use when fovea_sketch, fovea_focus, fovea_dwell, and fovea_impact are available to survey repositories, trace symbols and routes, assess change impact, or re-orient after edits with session-aware sync. Includes pi-fabric integration; use the fovea skill instead for standalone shell/CLI workflows.
 ---
 
 # pi-fovea
 
+Use this skill for the **Pi extension** and its in-session tools. For standalone
+shell commands, scripting, or CI, use the **fovea** skill instead.
+
 pi-fovea maintains a cross-language code graph of the working repository — routes, symbols, imports, calls, string/env literals — and exposes it through progressive disclosure: cheap silhouettes first, detail only where you point it. It costs almost nothing until you ask, and it re-syncs automatically whenever file content drifts, no matter which tool made the edit.
 
 ## The loop
@@ -63,10 +66,6 @@ When writing or editing code **inside a `fabric_exec` program**, the fovea tools
 - Any file mutation performed by the program (including `pi.edit`/`pi.write` calls inside the sandbox) is picked up by turn sync automatically, so post-edit verification does not need a re-sketch.
 - Sketch `details` carries coverage counts; its compact text names the highest-value entry points. On an unfamiliar repo, fetch it once and reuse it instead of rediscovering entry points per call.
 
-## CLI
-
-The same engine runs headlessly as the `fovea` binary (repo root scan, plus JSON and TSV modes). Prefer the in-session tools unless you need scripting or a second opinion outside the extension's session state.
-
 ## Settings
 
 Use `/fovea status` for loaded version and index coverage, `/fovea reset` for fresh state, `/fovea reload` after updates, and `/fovea settings` for configuration. Files live under `~/.pi/agent/fovea.json` or trusted `.pi/fovea.json`; the external-editor key (`Ctrl+G` by default) switches the displayed and saved layer between global defaults and project overrides. `tools.grepMode` controls the grep integration: `"augment"` (default) keeps native grep semantics and appends a Fovea graph section to symbol-query results — including `pi.grep` calls inside fabric_exec — `"replace"` keeps the legacy bare-query takeover, `"off"` is native only.