@ushiradineth/veil 0.1.10 → 0.2.0

package/README.md

@@ -1,155 +1,117 @@
-# Veil MCP
+# Veil CLI
 
-Veil is a fast MCP server and CLI for local code retrieval. It indexes a repo and exposes focused tools for files, symbols, search, lookup, web research, URL fetch, and git context.
+Veil is a fast CLI and skill for local code retrieval and agent context workflows.
 
-## What It Is For
+It indexes a repository and provides focused commands for files, symbols, semantic lookup,
+web/fetch context, and git or GitHub reads.
 
-Veil is built for agents that need to move from prompt to implementation quickly.
+## What It Is For
 
-It gives the agent indexed access to files, symbols, and relevant code chunks, so it can retrieve precise context before writing code. This reduces broad file reads and repeated text scans, improves token efficiency, and shortens time to first meaningful code change.
+Veil is built for agent workflows that need fast, token-lean context before editing code.
 
-In practice, Veil acts as a local retrieval layer for coding agents: discover where code lives, resolve symbols, pull focused context, then execute edits.
+- Start broad with `discover`
+- Narrow with `lookup`, `search`, `files`, or `symbols`
+- Use built-in git and web commands instead of ad hoc shell fallbacks
 
-## Get Started
+## Install
 
 Requires Node.js 20 or later.
 
-Add Veil to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "veil": {
-      "command": "npx",
-      "args": ["-y", "@ushiradineth/veil@latest", "server"]
-    }
-  }
-}
+```bash
+npm i -g @ushiradineth/veil
 ```
 
-Install the Veil skill (optional, improves agent tool routing):
+Or run without install:
 
 ```bash
-npx -y skills add https://github.com/ushiradineth/veil/tree/main/docs --skill veil
+npx -y @ushiradineth/veil@latest status --workspace .
 ```
 
-## MCP Tools
-
-Available Veil MCP tools:
-
-|     | Tool | Description |
-| --- | --- | --- |
-| - | `status` | Index status and staleness reasons |
-| - | `refresh` | Full or changed index refresh |
-| - | `files` | File path substring lookup |
-| - | `symbols` | Symbol name lookup |
-| - | `search` | Indexed code chunk search |
-| - | `lookup` | Intent-aware contextual retrieval with explainability |
-| - | `discover` | Combined status and focused retrieval in one call |
-| - | `web_search` | No-key web search (`google`, `duckduckgo`, `wikipedia`, `github`, `reddit`, `deepwiki`) |
-| - | `fetch_url` | Markdown-first URL content fetch |
-| - | `git_status` | Branch and workspace state |
-| - | `git_log` | Commit history lookup |
-| - | `git_diff` | Uncommitted or range diff lookup |
-| - | `git_show` | Commit details and optional patch |
-| - | `gh_lookup` | GitHub issues, PRs, checks, and repo context bootstrap via `gh` |
-| - | `diagnostics` | Cache and latency diagnostics |
+## Install Skill
+
+```bash
+npx -y skills add https://github.com/ushiradineth/veil/tree/main --skill veil
+```
 
 ## CLI Examples
 
 ```bash
 # status and refresh
-veil cli status --workspace .
-veil cli refresh --workspace . --mode changed
+veil status --workspace .
+veil init --workspace .
+veil refresh --workspace . --mode changed
 
 # local index retrieval
-veil cli discover --workspace . --query "find build logic"
-veil cli lookup --workspace . --query "where is parseNdjson defined"
+veil discover --workspace . --query "find build logic"
+veil lookup --workspace . --query "where is parseNdjson defined"
+veil search --workspace . --query "pnpm install"
 
 # web and fetch
-veil cli web-search --query "typescript language server" --limit 5
-veil cli fetch-url --url https://example.com --format markdown
+veil web-search --query "typescript language server" --limit 5
+veil fetch-url --url https://www.iana.org/domains/reserved --format markdown
 
 # git and github context
-veil cli git-status --workspace .
-veil cli git-log --workspace . --limit 10
-veil cli git-diff --workspace .
-veil cli git-show --workspace . --rev HEAD
-veil cli gh-lookup --repo owner/repo --kind issues --query "is:open"
+veil git-status --workspace .
+veil git-log --workspace . --limit 10
+veil git-diff --workspace .
+veil git-show --workspace . --rev HEAD
+veil gh-lookup --repo ushiradineth/veil --kind repo_context
 
 # diagnostics
-veil cli diagnostics
-```
+veil diagnostics
 
-## MCP Client Configuration
+# optional MCP server
+veil mcp server
 
-<details>
-  <summary>Codex</summary>
-  Follow the <a href="https://developers.openai.com/codex/mcp/#configure-with-the-cli">configure MCP guide</a>
-  using the standard config from above. You can also install Veil using the Codex CLI:
-
-```bash
-codex mcp add veil -- npx -y @ushiradineth/veil@latest server
 ```
 
-</details>
+## Commands
 
-<details>
-  <summary>Claude Code</summary>
+- `status`, `init`, `refresh`
+- `discover`, `lookup`, `files`, `symbols`, `search`
+- `web-search`, `fetch-url`
+- `git-status`, `git-log`, `git-diff`, `git-show`, `gh-lookup`
+- `diagnostics`
 
-Install via CLI:
+## Development Commands
 
 ```bash
-claude mcp add --scope user veil -- npx -y @ushiradineth/veil@latest server
+nix run nixpkgs#bun -- install
+nix run nixpkgs#bun -- run lint
+nix run nixpkgs#bun -- test ./src/test.ts
 ```
 
-See the <a href="https://code.claude.com/docs/en/mcp">Claude Code MCP guide</a> for more details.
-
-</details>
+## Benchmark A/B
 
-<details>
-  <summary>OpenCode</summary>
+Run A/B strategy benchmarks (Veil MCP vs Veil CLI+skill) with competitor cells:
 
-Add the following configuration to your `opencode.json` file. If you do not have one, create it at `~/.config/opencode/opencode.json` (<a href="https://opencode.ai/docs/mcp-servers">guide</a>):
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "veil": {
-      "type": "local",
-      "command": ["npx", "-y", "@ushiradineth/veil@latest", "server"]
-    }
-  }
-}
+```bash
+nix run nixpkgs#bun -- run src/bench-suite.ts --workspace /path/to/repo --agents veil,firecrawl --strategies mcp_transport,cli_skill --profile smoke --cold 1 --warm 1
 ```
 
-</details>
+## Release
 
-<details>
-  <summary>Cursor</summary>
+Releases follow a trunk-gated PR promotion flow.
 
-Click to install:
+1. Dispatch the `Release` workflow from `main` with a bump type (`patch`, `minor`, `major`).
+   This creates a `release/vX.Y.Z` branch and opens a PR to `main`.
+2. CI runs on the PR. Merge when checks pass.
+3. Merging triggers the `Publish` workflow which tags, publishes to npm, creates a GitHub release,
+   and updates the Homebrew formula in the tap repository.
 
-[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=veil&config=eyJjb21tYW5kIjoibnB4IC15IEB1c2hpcmFkaW5ldGgvdmVpbEBsYXRlc3Qgc2VydmVyIn0%3D)
+Required GitHub secrets:
 
-Or install manually in `Cursor Settings` -> `MCP` -> `New MCP Server` with:
+| Secret                      | Purpose                                        |
+| --------------------------- | ---------------------------------------------- |
+| `NPM_TOKEN`                 | Publish to npm registry                        |
+| `RELEASE_PR_TOKEN`          | PAT to open release PR so CI triggers on it    |
+| `HOMEBREW_TAP_GITHUB_TOKEN` | PAT with write access to the Homebrew tap repo |
 
-```json
-{
-  "mcpServers": {
-    "veil": {
-      "command": "npx",
-      "args": ["-y", "@ushiradineth/veil@latest", "server"]
-    }
-  }
-}
-```
+Optional repository variables:
 
-</details>
+| Variable                | Default                     | Purpose                  |
+| ----------------------- | --------------------------- | ------------------------ |
+| `HOMEBREW_TAP_REPO`     | `ushiradineth/homebrew-tap` | Tap owner/repo           |
+| `HOMEBREW_FORMULA_PATH` | `Formula/veil.rb`           | Formula file path in tap |
 
-<details>
-  <summary>Windsurf</summary>
-  Follow the <a href="https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json">configure MCP guide</a>
-  using the standard config from above.
-</details>
+Branch protection on `main` should require the `CI / test` check context before merge.