@ushiradineth/veil 0.1.3 → 0.1.5

package/README.md

@@ -1,100 +1,54 @@
 # veil
 
-> High-performance MCP server and CLI for repository indexing and code search
+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 blazingly fast code indexing and search engine designed for AI agents and developer tools. It indexes code repositories and exposes retrieval tools over the Model Context Protocol (MCP), enabling sub-millisecond queries with minimal memory overhead.
+## 2-minute setup
 
-## Features
-
-- **Ultra-fast queries** - Sub-millisecond warm query latency (0.03-0.07ms p95)
-- **Smart indexing** - Extracts files, symbols, and semantic code chunks
-- **Flexible search** - File paths, symbol names, and full-text code search
-- **Memory efficient** - <100MB for typical workloads with intelligent caching
-- **Incremental updates** - Fast refresh with git-aware change detection
-- **Battle-tested** - Comprehensive correctness and performance test coverage
-- **Observable** - Built-in diagnostics and performance profiling
-- **MCP native** - First-class Model Context Protocol support
-
-## Performance
-
-Veil includes a reproducible benchmark suite for public comparisons across:
-
-- Veil MCP index tools
-- Shell tool workflows commonly used by non-indexed agent loops
-- Serena via `uvx` (from `https://github.com/oraios/serena`) plus optional custom adapter configs
-
-See [BENCHMARKS.md](BENCHMARKS.md) for methodology, fairness rules, and commands to generate fresh benchmark artifacts.
-
-**Memory usage:** <100MB for typical workloads  
-**Test coverage:** Run `bun test ./src/test.ts` for current suite status
-
-## Installation
-
-**Requirements:**
-- Bun runtime (or Node.js 18+)
-- Git (optional, for git-aware indexing)
-
-**Clone and install:**
-
-```bash
-git clone https://github.com/ushiradineth/veil.git
-cd veil
-bun install
-```
-
-## MCP Setup
-
-No-clone setup (recommended): run Veil directly from npm package.
-
-Add Veil to your MCP client configuration:
-
-### Claude Desktop
-
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add Veil to your MCP client config:
 
 ```json
 {
   "mcpServers": {
     "veil": {
       "command": "npx",
-      "args": ["-y", "@ushiradineth/veil", "server"],
-      "env": {}
+      "args": ["-y", "@ushiradineth/veil@latest", "server"]
     }
   }
 }
 ```
 
-### Codex
+Then restart your MCP client.
+
+## MCP config snippets
 
-Edit `~/.config/codex/mcp.json`:
+Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "veil": {
       "command": "npx",
-      "args": ["-y", "@ushiradineth/veil", "server"]
+      "args": ["-y", "@ushiradineth/veil@latest", "server"],
+      "env": {}
     }
   }
 }
 ```
 
-### OpenCode
-
-Edit `~/.config/opencode/mcp.json`:
+Codex (`~/.config/codex/mcp.json`) and OpenCode (`~/.config/opencode/mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "veil": {
       "command": "npx",
-      "args": ["-y", "@ushiradineth/veil", "server"]
+      "args": ["-y", "@ushiradineth/veil@latest", "server"]
     }
   }
 }
 ```
 
-Alternative package launch with Bun:
+Optional Bun launcher:
 
 ```json
 {
@@ -107,7 +61,7 @@ Alternative package launch with Bun:
 }
 ```
 
-Local clone setup (contributors):
+Local clone launcher:
 
 ```json
 {
@@ -120,187 +74,89 @@ Local clone setup (contributors):
 }
 ```
 
-**Example with workspace:**
+## Quick verification
 
-To index a specific repository (e.g., `~/nix-config`), first build the index:
+Package path:
 
 ```bash
-bun run src/cli.ts build --workspace ~/nix-config
+npx -y @ushiradineth/veil@latest cli status
 ```
 
-Then use the MCP tools with `workspace: "~/nix-config"` parameter, or omit it to use the current working directory.
-
-## Agent Adoption
-
-To improve real-world tool usage (selection and correctness), use:
-
-- `AGENTS.md` for default routing policy and anti-pattern constraints
-- `docs/SKILL.md` as a reusable skill prompt for research and investigation tasks
-
-Install the skill using the `skills` CLI from `vercel-labs/skills`:
+Local clone path:
 
 ```bash
-# install from local repo path
-npx skills add ./docs --skill veil-research-workflow
-
-# install from GitHub
-npx skills add https://github.com/ushiradineth/veil/tree/main/docs --skill veil-research-workflow
-
-# optional: target specific agents yourself
-npx skills add https://github.com/ushiradineth/veil/tree/main/docs --skill veil-research-workflow -a opencode
+node bin/veil.mjs cli status
 ```
 
-## CLI Usage
-
-All CLI and MCP text outputs are emitted in TOON format (not JSON text).
-
-Package-style CLI (no clone after install):
+Build and query a workspace:
 
 ```bash
-npx -y @ushiradineth/veil cli status
-npx -y @ushiradineth/veil cli discover --query "homebrew pnpm"
+npx -y @ushiradineth/veil@latest cli refresh --workspace ~/nix-config --mode full
+npx -y @ushiradineth/veil@latest cli discover --workspace ~/nix-config --query "where is buildIndex defined"
 ```
 
-```bash
-# Build index
-bun run src/cli.ts build --workspace <path>
-
-# Check status
-bun run src/cli.ts status --workspace <path>
-
-# Refresh index (incremental)
-bun run src/cli.ts refresh --workspace <path> --mode changed
-
-# Search and discover
-bun run src/cli.ts discover --workspace <path> --query "homebrew pnpm"
+If you run these commands from inside a local `veil` clone, keep `@latest` in the package spec so npm does not resolve to the local workspace package.
 
-# Intent-aware lookup with explainability
-bun run src/cli.ts lookup --workspace <path> --query "where is buildIndex defined"
+## Agent skill install (`veil`)
 
-# Fast web search without API keys (google, duckduckgo, wikipedia, github, reddit, deepwiki)
-bun run src/cli.ts web-search --query "typescript language server"
+Install and list from local path:
 
-# Optional debug diagnostics for web search (provider trace, ranking details)
-bun run src/cli.ts web-search --query "typescript language server" --debug 1
-
-# Fetch URL content with markdown-first negotiation
-bun run src/cli.ts fetch-url --url "https://example.com" --format markdown
-
-# Git repository lookups
-bun run src/cli.ts git-status --workspace <path>
-bun run src/cli.ts git-log --workspace <path> --limit 20
-bun run src/cli.ts git-diff --workspace <path> --staged 0 --path src/indexer.ts
-bun run src/cli.ts git-show --workspace <path> --rev HEAD
-
-# Optional GitHub lookup via gh CLI
-bun run src/cli.ts gh-lookup --workspace <path> --repo owner/name --kind prs --limit 10
-
-# Run diagnostics
-bun run src/cli.ts diagnostics
-
-# Run tests
-bun test ./src/test.ts
-
-# Benchmark (internal performance)
-bun run src/bench-harness.ts --workspace <path> --warm 50
-
-# Benchmark (vs traditional tools)
-bun run src/bench-comparison.ts --workspace <path>
-
-# Benchmark suite (public, multi-competitor)
-bun run src/bench-suite.ts --workspace <path> --cold 1 --warm 50 --out benchmarks/results/latest
-
-# Benchmark suite with custom Serena command overrides (optional)
-bun run src/bench-suite.ts --workspace <path> --serena-config benchmarks/serena.config.example.json --out benchmarks/results/latest
-```
-
-## Release Pipeline
-
-Manual release workflow: `.github/workflows/release.yml`.
-
-- Trigger via GitHub Actions `Release` workflow (`workflow_dispatch`)
-- Supports `patch|minor|major` bump
-- Supports `dry_run=true` for full validation without push/publish
-- Auto-updates `package.json` and `CHANGELOG.md`
-- Tags release as `v<version>`, publishes npm package, and creates GitHub release
-
-Required GitHub secrets:
-
-- `NPM_TOKEN`: npm automation token with publish access to `@ushiradineth/veil`
-
-No additional GitHub environment variables are required by default.
-
-## MCP Tools
-
-The server exposes the following MCP tools:
-
-- **status** - Get index status and staleness reasons
-- **refresh** - Build or refresh the index
-- **files** - Find files by substring path query
-- **symbols** - Find symbols by name
-- **search** - Search indexed code chunks by keyword
-- **lookup** - Intent-aware contextual lookup with confidence and fallback metadata
-- **web_search** - Fast web search without API keys (google, duckduckgo, wikipedia, github, reddit, deepwiki), minimal results by default with optional debug diagnostics
-- **fetch_url** - Fetch URL content with markdown-first output negotiation and fallback conversion
-  - returns `markdown_tokens`, `content_signal`, and `vary` when present in response headers
-- **discover** - Combined status + files + symbols + search in one call
-- **git_status** - Inspect branch state and dirty workspace changes
-- **git_log** - Query commit history with limit and filters
-- **git_diff** - Inspect uncommitted or revision-range diff output
-- **git_show** - Show commit details and optional patch output
-- **gh_lookup** - Optional GitHub issues/PRs/checks lookup via `gh`
-- **diagnostics** - Get performance diagnostics and cache stats
-
-## Index Storage
-
-Index artifacts are written to `<workspace>/.agents/index/`:
-- `files.ndjson` - File records with metadata
-- `symbols.ndjson` - Extracted symbols (functions, classes, types)
-- `chunks.ndjson` - Code chunks for semantic search
-- `manifest.json` - Index metadata and staleness tracking
-
-## Architecture
-
-**Hot path optimizations:**
-- Heap-based top-K scoring (O(n log k) vs O(n²))
-- Single-pass NDJSON parsing
-- Parallel file processing with batching
-- Normalized string caching for memory efficiency
-
-**Caching strategy:**
-- In-memory index cache with mtime validation
-- Query result caching per workspace
-- Status cache with TTL
-
-## Development
-
-**Run tests:**
 ```bash
-bun test ./src/test.ts
+npx -y skills add ./docs --skill veil --list
 ```
 
-**Run benchmarks:**
-```bash
-bun run src/bench-harness.ts --workspace /path/to/repo --warm 100
-```
+Install and list from GitHub path:
 
-**Start MCP server:**
 ```bash
-bun run src/server.ts
+npx -y skills add https://github.com/ushiradineth/veil/tree/main/docs --skill veil --list
 ```
 
-## License
+Note: this command reflects the current `main` branch contents on GitHub.
 
-MIT License - see [LICENSE](LICENSE) for details.
+Optional agent targeting:
 
-## Contributing
-
-Contributions are welcome! Please feel free to submit issues or pull requests.
-
-## Acknowledgments
+```bash
+npx -y skills add https://github.com/ushiradineth/veil/tree/main/docs --skill veil -a opencode
+```
 
-Built with performance in mind, leveraging:
-- Heap-based top-K algorithms for efficient ranking
-- Single-pass parsing to minimize allocations
-- Parallel file processing for multi-core systems
-- Intelligent caching strategies for memory efficiency
+## Integration checklist
+
+- `veil` server starts in your MCP client
+- `status` returns index metadata
+- `discover` returns relevant repo hits
+- local `skills ... --list` shows `veil`
+- Routing guidance is loaded from `docs/SKILL.md`
+
+## MCP tools
+
+- `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, and checks via `gh`
+- `diagnostics`: cache and latency diagnostics
+
+## Release workflow
+
+- Workflow: `.github/workflows/release.yml` (`workflow_dispatch`)
+- Inputs: `version_bump` (`patch|minor|major`) and `dry_run` (`true|false`)
+- Guardrails: release runs only from default branch and requires `package.json` version to match latest semver tag (`vX.Y.Z`) before bump
+- Outputs: updates `package.json` and `CHANGELOG.md`, tags `v<version>`, publishes npm package, and creates GitHub release
+- Release notes: generated via GitHub release notes config in `.github/release.yml` with changelog fallback so release pages are never empty
+- Required secret: `NPM_TOKEN` for npm publish (`GITHUB_TOKEN` is provided by Actions)
+
+## Links
+
+- Benchmark methodology and latest artifacts: `BENCHMARKS.md`
+- Agent routing policy: `AGENTS.md`
+- Reusable routing skill: `docs/SKILL.md`
+- License: `LICENSE`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ushiradineth/veil",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "repository": {