docs: update README with usage instructions

- Add installation instructions (nix flakes, go install)
- Add MCP server configuration example
- Add CLI examples for all commands
- Document environment variables and database connection strings
- List available MCP tools

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -4,20 +4,166 @@ A collection of Model Context Protocol (MCP) servers written in Go.
 
 ## NixOS Options MCP Server
 
-Search and query NixOS configuration options across multiple nixpkgs revisions.
+Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.
 
-**Features:**
+### Features
-- Search options with fuzzy matching
+
-- Query specific options with full metadata
+- Full-text search across option names and descriptions
-- Index multiple nixpkgs revisions
+- Query specific options with type, default, example, and declarations
+- Index multiple nixpkgs revisions (by git hash or channel name)
 - Fetch nixpkgs module source files
-- Support for PostgreSQL and SQLite
+- Support for PostgreSQL and SQLite backends
 
-## Status
+## Installation
 
-🚧 **In Development** - Not yet functional
+### Using Nix Flakes
 
-## Documentation
+```bash
+# Build the package
+nix build github:torjus/labmcp
 
-- See [TODO.md](TODO.md) for implementation progress
+# Or run directly
-- See [CLAUDE.md](CLAUDE.md) for architecture and design decisions
+nix run github:torjus/labmcp -- --help
+```
+
+### From Source
+
+```bash
+go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest
+```
+
+## Usage
+
+### As MCP Server
+
+Configure in your MCP client (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "nixos-options": {
+      "command": "nixos-options",
+      "args": ["serve"],
+      "env": {
+        "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
+      }
+    }
+  }
+}
+```
+
+Then start the server:
+
+```bash
+nixos-options serve
+```
+
+### CLI Examples
+
+**Index a nixpkgs revision:**
+
+```bash
+# Index by channel name
+nixos-options index nixos-unstable
+
+# Index by git hash
+nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08
+
+# Index with file contents (enables get_file tool, slower)
+nixos-options index --files nixos-unstable
+```
+
+**List indexed revisions:**
+
+```bash
+nixos-options list
+```
+
+**Search for options:**
+
+```bash
+# Basic search
+nixos-options search nginx
+
+# Limit results
+nixos-options search -n 10 postgresql
+
+# Search in specific revision
+nixos-options search -r nixos-unstable firewall
+```
+
+**Get option details:**
+
+```bash
+nixos-options get services.nginx.enable
+nixos-options get services.postgresql.package
+```
+
+**Delete an indexed revision:**
+
+```bash
+nixos-options delete nixos-23.11
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NIXOS_OPTIONS_DATABASE` | Database connection string | `sqlite://nixos-options.db` |
+
+### Database Connection Strings
+
+**SQLite:**
+```bash
+export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db"
+export NIXOS_OPTIONS_DATABASE="sqlite://:memory:"  # In-memory
+```
+
+**PostgreSQL:**
+```bash
+export NIXOS_OPTIONS_DATABASE="postgres://user:pass@localhost/nixos_options?sslmode=disable"
+```
+
+### Command-Line Flags
+
+The database can also be specified via the `-d` or `--database` flag:
+
+```bash
+nixos-options -d "postgres://localhost/nixos" serve
+nixos-options -d "sqlite://my.db" index nixos-unstable
+```
+
+## MCP Tools
+
+When running as an MCP server, the following tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `search_options` | Search for options by name or description |
+| `get_option` | Get full details for a specific option |
+| `get_file` | Fetch source file contents from nixpkgs |
+| `index_revision` | Index a nixpkgs revision |
+| `list_revisions` | List all indexed revisions |
+| `delete_revision` | Delete an indexed revision |
+
+## Development
+
+```bash
+# Enter development shell
+nix develop
+
+# Run tests
+go test ./...
+
+# Run benchmarks
+go test -bench=. ./internal/database/...
+
+# Build
+go build ./cmd/nixos-options
+```
+
+## License
+
+MIT