Add CI, edge-case tests, contributor docs, and issue templates

- GitHub Actions CI: test, clippy, fmt, WASM build on push/PR
- 12 edge-case integration tests + 9 new unit tests in distance/search
- CONTRIBUTING.md with build, test, and PR instructions
- Bug report and feature request issue templates
- GitHub Pages redirect to altorlab.dev
- README: add CI badge, live demo link, "How it works" section
- Fix pre-existing clippy warnings (doc comments, useless vec)
- Format codebase with cargo fmt

Author: anshulbasia27

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug Report
+about: Report a bug in altor-vec
+title: ""
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+Steps or code snippet to reproduce the behavior:
+
+```rust
+// your code here
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- altor-vec version:
+- Rust version (`rustc --version`):
+- OS:
+- Browser (if WASM):

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature Request
+about: Suggest an idea for altor-vec
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+**Problem**
+What problem does this feature solve?
+
+**Proposed solution**
+How you'd like it to work.
+
+**Alternatives considered**
+Any other approaches you've thought about.

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo test --all-features
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo clippy --all-targets --all-features -- -D warnings
+
+  fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --all -- --check
+
+  wasm:
+    name: WASM Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+      - uses: Swatinem/rust-cache@v2
+      - uses: jetli/wasm-pack-action@v0.4.0
+      - run: cd wasm && wasm-pack build --target web --release

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to altor-vec
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Building from source
+
+```bash
+git clone https://github.com/altor-lab/altor-vec.git
+cd altor-vec
+cargo build
+```
+
+## Running tests
+
+```bash
+cargo test                     # core tests
+cargo test --all-features      # include serialization tests
+```
+
+## Building WASM
+
+```bash
+cargo install wasm-pack        # one-time setup
+cd wasm && wasm-pack build --target web --release
+```
+
+## Code style
+
+We use standard Rust tooling — please run these before submitting a PR:
+
+```bash
+cargo fmt                      # format code
+cargo clippy --all-targets --all-features -- -D warnings  # lint
+```
+
+## Pull request process
+
+1. Open an issue describing the change you'd like to make.
+2. Fork the repo and create a feature branch from `main`.
+3. Make your changes, add tests, and ensure `cargo test --all-features` passes.
+4. Run `cargo fmt` and `cargo clippy` with no warnings.
+5. Submit a PR — we'll review it as soon as we can.
+
+## Questions?
+
+Open an issue or email [anshul@altorlab.dev](mailto:anshul@altorlab.dev).

README.md

@@ -6,10 +6,14 @@
   <p align="center">
     <a href="https://www.npmjs.com/package/altor-vec"><img src="https://img.shields.io/npm/v/altor-vec?color=blue&label=npm" alt="npm version"></a>
     <a href="https://www.npmjs.com/package/altor-vec"><img src="https://img.shields.io/npm/dm/altor-vec?color=green" alt="npm downloads"></a>
+    <a href="https://github.com/altor-lab/altor-vec/actions/workflows/ci.yml"><img src="https://github.com/altor-lab/altor-vec/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
     <a href="https://github.com/altor-lab/altor-vec/stargazers"><img src="https://img.shields.io/github/stars/altor-lab/altor-vec?style=social" alt="GitHub stars"></a>
     <a href="https://github.com/altor-lab/altor-vec/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
     <img src="https://img.shields.io/badge/WASM-54KB_gzipped-orange" alt="WASM size">
   </p>
+  <p align="center">
+    <a href="https://altorlab.dev"><img src="https://img.shields.io/badge/%F0%9F%9A%80_Try_Live_Demo-altorlab.dev-blueviolet?style=for-the-badge" alt="Try Live Demo"></a>
+  </p>
 </p>
 
 ---
@@ -149,6 +153,12 @@ const output = await embed('your query', { pooling: 'mean', normalize: true });
 const results = JSON.parse(engine.search(new Float32Array(output.data), 5));
 ```
 
+## How it works
+
+altor-vec uses **HNSW (Hierarchical Navigable Small World)** — the same algorithm behind Pinecone, Qdrant, and pgvector. HNSW builds a multi-layer graph where each node is a vector and edges connect nearby neighbors. Upper layers act as express lanes for coarse navigation; the bottom layer contains all vectors for fine-grained search. A query enters at the top and greedily descends to find the nearest neighbors in O(log n) time.
+
+All vectors are L2-normalized at insert time, so dot product distance equals cosine similarity — no extra computation at search time.
+
 ## Architecture
 
 ```
@@ -175,7 +185,7 @@ cd wasm && wasm-pack build --target web --release  # build WASM
 
 ## Contributing
 
-We welcome contributions! Open an issue to discuss what you'd like to change, then submit a PR.
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, code style, and PR process.
 
 ## License
 

benches/search_bench.rs

@@ -1,6 +1,6 @@
-use criterion::{criterion_group, criterion_main, Criterion};
 use altor_vec::distance::normalize;
 use altor_vec::HnswIndex;
+use criterion::{criterion_group, criterion_main, Criterion};
 use rand::Rng;
 
 fn random_unit_vector(dims: usize, rng: &mut impl Rng) -> Vec<f32> {
@@ -49,5 +49,10 @@ fn bench_search_1k(c: &mut Criterion) {
     });
 }
 
-criterion_group!(benches, bench_search_ef50, bench_search_ef500, bench_search_1k);
+criterion_group!(
+    benches,
+    bench_search_ef50,
+    bench_search_ef500,
+    bench_search_1k
+);
 criterion_main!(benches);

docs/index.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="refresh" content="0; url=https://altorlab.dev">
+  <title>altor-vec — Redirecting</title>
+</head>
+<body>
+  <p>Redirecting to <a href="https://altorlab.dev">altorlab.dev</a>...</p>
+</body>
+</html>

src/distance.rs

@@ -42,4 +42,54 @@ mod tests {
         let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
         assert!((norm - 1.0).abs() < 1e-6);
     }
+
+    #[test]
+    fn test_dot_product_zero_vector() {
+        let a = vec![1.0, 2.0, 3.0];
+        let b = vec![0.0, 0.0, 0.0];
+        assert!((dot_product(&a, &b)).abs() < 1e-6);
+    }
+
+    #[test]
+    fn test_dot_product_identical_vectors() {
+        let a = vec![0.6, 0.8];
+        // dot(a, a) = 0.36 + 0.64 = 1.0
+        assert!((dot_product(&a, &a) - 1.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn test_dot_product_high_dimensions() {
+        let dims = 1536;
+        let a: Vec<f32> = (0..dims).map(|i| (i as f32).sin()).collect();
+        let b: Vec<f32> = (0..dims).map(|i| (i as f32).cos()).collect();
+        // Just verify it runs without panicking and produces a finite result
+        let result = dot_product(&a, &b);
+        assert!(result.is_finite());
+    }
+
+    #[test]
+    fn test_normalize_zero_vector() {
+        let mut v = vec![0.0, 0.0, 0.0];
+        let norm = normalize(&mut v);
+        assert!((norm - 0.0).abs() < 1e-6);
+        // Vector should remain zero
+        for x in &v {
+            assert!((*x).abs() < 1e-6);
+        }
+    }
+
+    #[test]
+    fn test_normalize_already_unit() {
+        let mut v = vec![1.0, 0.0, 0.0];
+        let norm = normalize(&mut v);
+        assert!((norm - 1.0).abs() < 1e-6);
+        assert!((v[0] - 1.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn test_normalize_returns_original_norm() {
+        let mut v = vec![3.0, 4.0];
+        let norm = normalize(&mut v);
+        assert!((norm - 5.0).abs() < 1e-6);
+    }
 }

src/hnsw/construction.rs

@@ -19,7 +19,12 @@ pub fn random_layer(m: usize, rng: &mut impl Rng) -> usize {
 
 /// Insert a new vector into the HNSW graph.
 /// The vector should already be L2-normalized.
-pub fn insert(graph: &mut Graph, vector: Vec<f32>, ef_construction: usize, rng: &mut impl Rng) -> usize {
+pub fn insert(
+    graph: &mut Graph,
+    vector: Vec<f32>,
+    ef_construction: usize,
+    rng: &mut impl Rng,
+) -> usize {
     let new_layer = random_layer(graph.m, rng);
     let new_id = graph.add_node(vector, new_layer);
 
@@ -49,11 +54,7 @@ pub fn insert(graph: &mut Graph, vector: Vec<f32>, ef_construction: usize, rng:
         let results = search_layer(graph, &query, &current_entry_points, ef_construction, layer);
 
         // Select M neighbors (use M, not Mmax — paper Algorithm 2)
-        let neighbors: Vec<usize> = results
-            .iter()
-            .take(graph.m)
-            .map(|&(id, _)| id)
-            .collect();
+        let neighbors: Vec<usize> = results.iter().take(graph.m).map(|&(id, _)| id).collect();
 
         // Connect new node to neighbors
         graph.set_neighbors(new_id, layer, neighbors.clone());
@@ -107,7 +108,7 @@ mod tests {
     fn test_random_layer_distribution() {
         let mut rng = rand::thread_rng();
         let m = 16;
-        let mut layers = vec![0usize; 10];
+        let mut layers = [0usize; 10];
         for _ in 0..10000 {
             let l = random_layer(m, &mut rng);
             if l < layers.len() {

src/hnsw/graph.rs

@@ -1,10 +1,13 @@
-/// Layered graph structure for HNSW.
-///
-/// Each node stores its vector and a list of neighbor lists (one per layer it exists in).
-/// Neighbors are stored as (node_id, distance) pairs sorted by distance.
+//! Layered graph structure for HNSW.
+//!
+//! Each node stores its vector and a list of neighbor lists (one per layer it exists in).
+//! Neighbors are stored as (node_id, distance) pairs sorted by distance.
 
 /// A single node in the HNSW graph.
-#[cfg_attr(feature = "serialization", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(
+    feature = "serialization",
+    derive(serde::Serialize, serde::Deserialize)
+)]
 pub struct Node {
     /// The vector data (L2-normalized at insert time).
     pub vector: Vec<f32>,
@@ -16,7 +19,10 @@ pub struct Node {
 }
 
 /// The HNSW layered graph.
-#[cfg_attr(feature = "serialization", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(
+    feature = "serialization",
+    derive(serde::Serialize, serde::Deserialize)
+)]
 pub struct Graph {
     /// All nodes in insertion order. Node ID = index.
     pub nodes: Vec<Node>,