feat: search site

docs/api/tasks/phase-1-mvp.md

···
 
 A user can search Tangled content reliably with keyword search.
 
-## M5a — Search Site
+## M5a — Search Site ✅
 
 refs: [specs/09-search-site.md](../specs/09-search-site.md)
 
···
 
 ### Tasks
 
-- [ ] Create `internal/view/` package with `view.go`, `templates/`, and `static/` directories
-- [ ] Implement `Handler()` that returns an `http.Handler` with routes for all pages and `/static/*`
-- [ ] Embed templates and static assets via `//go:embed`; parse templates once at init
-- [ ] Use a shared `layout.html` template for the shell (head, nav, footer)
-- [ ] Mount `view.Handler()` in the `api` package router as a fallback after API routes
-- [ ] Build search page:
+- [x] Create `internal/view/` package with `view.go`, `templates/`, and `static/` directories
+- [x] Implement `Handler()` that returns an `http.Handler` with routes for all pages and `/static/*`
+- [x] Embed templates and static assets via `//go:embed`; parse templates once at init
+- [x] Use a shared `layout.html` template for the shell (head, nav, footer)
+- [x] Mount `view.Handler()` in the `api` package router as a fallback after API routes
+- [x] Build search page:
   - Text input + submit
   - Fetch `GET /search` with relative path (same origin)
   - Render result cards with type badge, title, snippet (preserve `<mark>`), author, repo, relative time
   - "Load more" pagination via offset
   - Filter bar: type, language, author (reflected in URL query params)
   - Empty and error states
-- [ ] Build API docs pages:
+- [x] Build API docs pages:
   - `/docs` — overview (base URL, response shape, no auth)
   - `/docs/search` — `GET /search` params, filters, example curl, example response
   - `/docs/documents` — `GET /documents/{id}` request/response
   - `/docs/health` — `GET /healthz`, `GET /readyz`
-- [ ] Implement `style.css` with design tokens (`--bg`, `--surface`, `--border`, `--accent`, etc.)
-- [ ] Load Google Sans and Google Sans Mono via Google Fonts `<link>`
-- [ ] Result card links open canonical Tangled URLs in new tab
-- [ ] Verify total site weight under 50 KB (excluding fonts and Alpine CDN)
+- [x] Implement `style.css` with design tokens (`--bg`, `--surface`, `--border`, `--accent`, etc.)
+- [x] Load Google Sans and Google Sans Mono via Google Fonts `<link>`
+- [x] Result card links open canonical Tangled URLs in new tab
+- [x] Verify total site weight under 50 KB (excluding fonts and Alpine CDN) — 21 KB total
 
 ### Verification
 

packages/api/internal/api/api.go

···
 	"tangled.org/desertthunder.dev/twister/internal/config"
 	"tangled.org/desertthunder.dev/twister/internal/search"
 	"tangled.org/desertthunder.dev/twister/internal/store"
+	"tangled.org/desertthunder.dev/twister/internal/view"
 )
 
 // Server is the HTTP search API server.
···
 func (s *Server) Handler() http.Handler {
 	mux := http.NewServeMux()
 
-	// Health
 	mux.HandleFunc("GET /healthz", s.handleHealthz)
 	mux.HandleFunc("GET /readyz", s.handleReadyz)
-
-	// Search — M5
 	mux.HandleFunc("GET /search", s.handleSearch)
 	mux.HandleFunc("GET /search/keyword", s.handleSearchKeyword)
-
-	// Search — placeholders (Phase 2/3)
 	mux.HandleFunc("GET /search/semantic", s.handleNotImplemented)
 	mux.HandleFunc("GET /search/hybrid", s.handleNotImplemented)
 
-	// Documents
 	mux.HandleFunc("GET /documents/{id}", s.handleGetDocument)
 
-	// Admin — placeholders (M7)
 	if s.cfg.EnableAdminEndpoints {
 		mux.HandleFunc("POST /admin/reindex", s.handleNotImplemented)
 		mux.HandleFunc("POST /admin/reembed", s.handleNotImplemented)
 	}
+
+	site := view.Handler()
+	mux.Handle("GET /static/", site)
+	mux.Handle("GET /docs", site)
+	mux.Handle("GET /docs/search", site)
+	mux.Handle("GET /docs/documents", site)
+	mux.Handle("GET /docs/health", site)
+	mux.Handle("GET /{$}", site)
 
 	return s.withMiddleware(mux)
 }
···
 	}
 }
 
-// --- Middleware ---
-
 func (s *Server) withMiddleware(next http.Handler) http.Handler {
 	return s.corsMiddleware(s.loggingMiddleware(next))
 }
···
 	rw.status = code
 	rw.ResponseWriter.WriteHeader(code)
 }
-
-// --- Health Handlers ---
 
 func (s *Server) handleHealthz(w http.ResponseWriter, _ *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
···
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ready"})
 }
 
-// --- Search Handlers ---
-
 // knownSearchParams is the whitelist of accepted query parameters for search endpoints.
 var knownSearchParams = map[string]bool{
 	"q": true, "mode": true, "limit": true, "offset": true,
···
 }
 
 func (s *Server) handleSearchKeyword(w http.ResponseWriter, r *http.Request) {
-	// Reject unknown parameters.
 	for key := range r.URL.Query() {
 		if !knownSearchParams[key] {
 			writeJSON(w, http.StatusBadRequest, errorBody("unknown_parameter", fmt.Sprintf("unknown parameter: %s", key)))
···
 	writeJSON(w, http.StatusOK, resp)
 }
 
-// --- Document Handler ---
-
 func (s *Server) handleGetDocument(w http.ResponseWriter, r *http.Request) {
 	id := r.PathValue("id")
 	if id == "" {
···
 		return
 	}
 
-	// Path value may be URL-encoded with | separators. The mux already decodes it,
-	// but callers may use pipe-encoded or slash-separated IDs; accept as-is.
 	doc, err := s.store.GetDocument(r.Context(), id)
 	if err != nil {
 		s.log.Error("get document failed", slog.String("error", err.Error()), slog.String("id", id))
···
 	writeJSON(w, http.StatusOK, documentResponse(doc))
 }
 
-// --- Placeholder ---
-
 func (s *Server) handleNotImplemented(w http.ResponseWriter, _ *http.Request) {
 	writeJSON(w, http.StatusNotImplemented, errorBody("not_implemented", "this endpoint is not yet available"))
 }
-
-// --- Helpers ---
 
 func writeJSON(w http.ResponseWriter, status int, v any) {
 	w.Header().Set("Content-Type", "application/json")
···
 		IndexedAt:    doc.IndexedAt,
 	}
 }
-

packages/api/internal/view/static/search.js

···
+function searchApp() {
+  return {
+    query: "",
+    filters: { type: "", author: "", language: "", state: "" },
+    results: [],
+    offset: 0,
+    limit: 20,
+    total: 0,
+    loading: false,
+    searched: false,
+    error: null,
+
+    get hasMore() {
+      return this.searched && this.offset + this.limit < this.total;
+    },
+
+    initFromURL() {
+      const p = new URLSearchParams(window.location.search);
+      this.query = p.get("q") || "";
+      this.filters.type = p.get("type") || "";
+      this.filters.author = p.get("author") || "";
+      this.filters.language = p.get("language") || "";
+      this.filters.state = p.get("state") || "";
+      if (this.query) this.doSearch(true);
+    },
+
+    buildParams(reset) {
+      const p = new URLSearchParams();
+      p.set("q", this.query);
+      p.set("limit", String(this.limit));
+      p.set("offset", String(reset ? 0 : this.offset));
+      if (this.filters.type) p.set("type", this.filters.type);
+      if (this.filters.author) p.set("author", this.filters.author);
+      if (this.filters.language) p.set("language", this.filters.language);
+      if (this.filters.state) p.set("state", this.filters.state);
+      return p;
+    },
+
+    syncURL() {
+      const p = new URLSearchParams();
+      if (this.query) p.set("q", this.query);
+      if (this.filters.type) p.set("type", this.filters.type);
+      if (this.filters.author) p.set("author", this.filters.author);
+      if (this.filters.language) p.set("language", this.filters.language);
+      if (this.filters.state) p.set("state", this.filters.state);
+      const qs = p.toString();
+      history.replaceState(null, "", qs ? "?" + qs : "/");
+    },
+
+    async doSearch(reset) {
+      if (!this.query.trim()) return;
+      if (reset) {
+        this.offset = 0;
+        this.results = [];
+      }
+      this.loading = true;
+      this.error = null;
+      this.syncURL();
+
+      try {
+        const resp = await fetch("/search?" + this.buildParams(reset));
+        if (!resp.ok) {
+          const body = await resp.json().catch(() => null);
+          this.error = (body && body.message) || "Search request failed (" + resp.status + ")";
+          return;
+        }
+        const data = await resp.json();
+        if (reset) {
+          this.results = data.results || [];
+        } else {
+          this.results = this.results.concat(data.results || []);
+        }
+        this.total = data.total || 0;
+        this.searched = true;
+      } catch (e) {
+        this.error = "Could not reach the API. Is the server running?";
+      } finally {
+        this.loading = false;
+      }
+    },
+
+    loadMore() {
+      this.offset += this.limit;
+      this.doSearch(false);
+    },
+
+    canonicalURL(r) {
+      const h = r.author_handle || "";
+      switch (r.record_type) {
+        case "repo":
+          return h && r.repo_name ? "https://tangled.org/" + h + "/" + r.repo_name : "#";
+        case "issue":
+          return h && r.repo_name ? "https://tangled.org/" + h + "/" + r.repo_name + "/issues" : "#";
+        case "pull":
+          return h && r.repo_name ? "https://tangled.org/" + h + "/" + r.repo_name + "/pulls" : "#";
+        case "profile":
+          return h ? "https://tangled.org/" + h : "#";
+        default:
+          return "#";
+      }
+    },
+
+    relTime(iso) {
+      if (!iso) return "";
+      const diff = Date.now() - new Date(iso).getTime();
+      const mins = Math.floor(diff / 60000);
+      if (mins < 1) return "just now";
+      if (mins < 60) return mins + "m ago";
+      const hrs = Math.floor(mins / 60);
+      if (hrs < 24) return hrs + "h ago";
+      const days = Math.floor(hrs / 24);
+      if (days < 30) return days + "d ago";
+      const months = Math.floor(days / 30);
+      return months + "mo ago";
+    },
+  };
+}

packages/api/internal/view/static/style.css

···
+:root {
+  --bg: #0e0e0e;
+  --surface: #1a1a1a;
+  --border: #2a2a2a;
+  --text: #e0e0e0;
+  --text-dim: #888;
+  --accent: #7aa2f7;
+  --mark-bg: #7aa2f733;
+  --mono: "Google Sans Mono", monospace;
+  --sans: "Google Sans", sans-serif;
+  --radius: 6px;
+}
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  font-family: var(--sans);
+  background: var(--bg);
+  color: var(--text);
+  line-height: 1.6;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+/* Nav */
+.nav {
+  border-bottom: 1px solid var(--border);
+  padding: .75rem 1rem;
+}
+.nav-inner {
+  max-width: 720px;
+  margin: 0 auto;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.nav-brand {
+  font-family: var(--mono);
+  font-weight: 700;
+  font-size: 1.1rem;
+  color: var(--text);
+}
+.nav-brand:hover { text-decoration: none; color: var(--accent); }
+.nav-links { display: flex; gap: 1.25rem; font-size: .9rem; }
+
+/* Main */
+.main {
+  max-width: 720px;
+  width: 100%;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+  flex: 1;
+}
+
+/* Footer */
+.footer {
+  border-top: 1px solid var(--border);
+  padding: 1rem;
+  font-size: .8rem;
+  color: var(--text-dim);
+}
+.footer-inner { max-width: 720px; margin: 0 auto; }
+
+/* Search hero */
+.search-hero { margin-bottom: 1.5rem; }
+.search-hero h1 { font-size: 1.5rem; margin-bottom: 1rem; font-weight: 500; }
+.search-form { display: flex; gap: .5rem; margin-bottom: .75rem; }
+.search-input {
+  flex: 1;
+  padding: .6rem .75rem;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text);
+  font-family: var(--sans);
+  font-size: .95rem;
+  outline: none;
+}
+.search-input:focus { border-color: var(--accent); }
+.search-input::placeholder { color: var(--text-dim); }
+
+/* Buttons */
+.btn {
+  padding: .6rem 1.1rem;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text);
+  font-family: var(--sans);
+  font-size: .9rem;
+  cursor: pointer;
+}
+.btn:hover { border-color: var(--accent); color: var(--accent); }
+.btn:disabled { opacity: .5; cursor: default; }
+.btn-primary { background: var(--accent); color: var(--bg); border-color: var(--accent); font-weight: 500; }
+.btn-primary:hover { background: #6b93e8; color: var(--bg); }
+.btn-more { width: 100%; margin-top: .75rem; }
+
+/* Filter bar */
+.filter-bar { display: flex; gap: .5rem; flex-wrap: wrap; }
+.filter-bar select,
+.filter-input {
+  padding: .45rem .6rem;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text);
+  font-family: var(--sans);
+  font-size: .85rem;
+  outline: none;
+}
+.filter-bar select:focus,
+.filter-input:focus { border-color: var(--accent); }
+.filter-input { width: 140px; }
+.filter-input::placeholder { color: var(--text-dim); }
+
+/* Messages */
+.msg { padding: 1rem; color: var(--text-dim); text-align: center; }
+.msg-error { color: #f7768e; }
+
+/* Result cards */
+.card {
+  display: block;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: .85rem 1rem;
+  margin-bottom: .6rem;
+  color: var(--text);
+  transition: border-color .15s;
+}
+.card:hover { border-color: var(--accent); text-decoration: none; }
+.card-head { display: flex; align-items: center; gap: .5rem; margin-bottom: .35rem; }
+.badge {
+  font-family: var(--mono);
+  font-size: .7rem;
+  padding: .15rem .45rem;
+  background: var(--border);
+  border-radius: 3px;
+  text-transform: uppercase;
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+.card-title { font-weight: 500; font-size: .95rem; }
+.card-snippet {
+  font-size: .85rem;
+  color: var(--text-dim);
+  margin-bottom: .35rem;
+  line-height: 1.5;
+}
+.card-snippet mark {
+  background: var(--mark-bg);
+  color: var(--accent);
+  padding: 0 .1rem;
+  border-radius: 2px;
+}
+.card-meta { font-size: .78rem; color: var(--text-dim); display: flex; gap: .5rem; }
+.meta-sep::before { content: "\00b7"; margin-right: .5rem; }
+
+/* Docs */
+.main h1 { font-size: 1.4rem; margin-bottom: 1rem; font-weight: 500; }
+.main h2 { font-size: 1.1rem; margin: 1.5rem 0 .5rem; font-weight: 500; }
+.main h3 { font-size: .95rem; margin: 1rem 0 .4rem; font-weight: 500; }
+.main p { margin-bottom: .75rem; }
+.main table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1rem;
+  font-size: .85rem;
+}
+.main th, .main td {
+  text-align: left;
+  padding: .45rem .6rem;
+  border-bottom: 1px solid var(--border);
+}
+.main th { color: var(--text-dim); font-weight: 500; }
+.main code {
+  font-family: var(--mono);
+  font-size: .85em;
+  background: var(--surface);
+  padding: .1rem .35rem;
+  border-radius: 3px;
+}
+.main pre {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: .85rem 1rem;
+  overflow-x: auto;
+  margin-bottom: 1rem;
+  font-size: .82rem;
+  line-height: 1.5;
+}
+.main pre code { background: none; padding: 0; }
+
+/* Mobile */
+@media (max-width: 640px) {
+  .search-form { flex-direction: column; }
+  .filter-bar { flex-direction: column; }
+  .filter-input { width: 100%; }
+  .card-meta { flex-wrap: wrap; }
+}

packages/api/internal/view/templates/docs/documents.html

···
+{{define "title"}}GET /documents/{id} — Twister API{{end}}
+{{define "content"}}
+<h1><code>GET /documents/{id}</code></h1>
+<p>Fetch a single indexed document by its stable ID.</p>
+
+<h2>Path Parameters</h2>
+<table>
+  <thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead>
+  <tbody>
+    <tr><td><code>id</code></td><td>string</td><td>Document stable ID (format: <code>did|collection|rkey</code>).</td></tr>
+  </tbody>
+</table>
+
+<h2>Example Request</h2>
+<pre><code>curl "https://your-domain/documents/did:plc:abc|sh.tangled.repo|3kb3fge5lm32x"</code></pre>
+
+<h2>Example Response</h2>
+<pre><code>{
+  "id": "did:plc:abc|sh.tangled.repo|3kb3fge5lm32x",
+  "did": "did:plc:abc",
+  "collection": "sh.tangled.repo",
+  "rkey": "3kb3fge5lm32x",
+  "at_uri": "at://did:plc:abc/sh.tangled.repo/3kb3fge5lm32x",
+  "cid": "bafyreig...",
+  "record_type": "repo",
+  "title": "glow-rs",
+  "body": "A TUI markdown viewer inspired by Glow, written in Rust.",
+  "summary": "Rust TUI markdown viewer",
+  "repo_name": "glow-rs",
+  "author_handle": "desertthunder.dev",
+  "tags_json": "[\"rust\", \"tui\", \"markdown\"]",
+  "language": "en",
+  "created_at": "2026-03-20T10:00:00Z",
+  "updated_at": "2026-03-22T15:03:11Z",
+  "indexed_at": "2026-03-22T15:05:00Z"
+}</code></pre>
+
+<h2>Errors</h2>
+<table>
+  <thead><tr><th>Status</th><th>Condition</th></tr></thead>
+  <tbody>
+    <tr><td>400</td><td>Missing or empty document ID.</td></tr>
+    <tr><td>404</td><td>Document not found or has been deleted.</td></tr>
+    <tr><td>500</td><td>Database error.</td></tr>
+  </tbody>
+</table>
+{{end}}
+{{template "layout" .}}

packages/api/internal/view/templates/docs/health.html

···
+{{define "title"}}Health Endpoints — Twister API{{end}}
+{{define "content"}}
+<h1>Health Endpoints</h1>
+<p>Twister exposes two health check endpoints for monitoring and orchestration.</p>
+
+<h2><code>GET /healthz</code></h2>
+<p>Liveness probe. Returns 200 if the process is responsive. No dependency checks.</p>
+
+<h3>Example Request</h3>
+<pre><code>curl https://your-domain/healthz</code></pre>
+
+<h3>Response</h3>
+<pre><code>{"status": "ok"}</code></pre>
+<p>Always returns <code>200 OK</code>.</p>
+
+<h2><code>GET /readyz</code></h2>
+<p>Readiness probe. Checks that the database is reachable by executing a test query.</p>
+
+<h3>Example Request</h3>
+<pre><code>curl https://your-domain/readyz</code></pre>
+
+<h3>Response (healthy)</h3>
+<pre><code>{"status": "ready"}</code></pre>
+<p>Returns <code>200 OK</code> when the database is reachable.</p>
+
+<h3>Response (unhealthy)</h3>
+<pre><code>{"error": "db_unreachable", "message": "database is not reachable"}</code></pre>
+<p>Returns <code>503 Service Unavailable</code> when the database cannot be reached.</p>
+
+<h2>Usage</h2>
+<p>Configure your orchestrator (Railway, Kubernetes, etc.) to poll these endpoints:</p>
+<table>
+  <thead><tr><th>Endpoint</th><th>Purpose</th><th>Failure Action</th></tr></thead>
+  <tbody>
+    <tr><td><code>/healthz</code></td><td>Liveness</td><td>Restart the process</td></tr>
+    <tr><td><code>/readyz</code></td><td>Readiness</td><td>Remove from load balancer</td></tr>
+  </tbody>
+</table>
+{{end}}
+{{template "layout" .}}

packages/api/internal/view/templates/docs/index.html

···
+{{define "title"}}API Docs — Twister{{end}}
+{{define "content"}}
+<h1>API Documentation</h1>
+<p>Twister exposes a public JSON API for searching indexed <a href="https://tangled.sh" target="_blank" rel="noopener">Tangled</a> content. No authentication is required for read endpoints.</p>
+
+<h2>Base URL</h2>
+<pre><code>https://&lt;your-twister-domain&gt;</code></pre>
+<p>All endpoints are relative to the base URL. When using the search site, the API is on the same origin.</p>
+
+<h2>Response Shape</h2>
+<p>All responses are JSON. Successful responses return the resource directly. Errors return:</p>
+<pre><code>{
+  "error": "error_code",
+  "message": "Human-readable description"
+}</code></pre>
+
+<h2>Endpoints</h2>
+<table>
+  <thead><tr><th>Method</th><th>Path</th><th>Description</th></tr></thead>
+  <tbody>
+    <tr><td><code>GET</code></td><td><a href="/docs/search"><code>/search</code></a></td><td>Search indexed documents</td></tr>
+    <tr><td><code>GET</code></td><td><a href="/docs/documents"><code>/documents/{id}</code></a></td><td>Fetch a single document</td></tr>
+    <tr><td><code>GET</code></td><td><a href="/docs/health"><code>/healthz</code></a></td><td>Liveness probe</td></tr>
+    <tr><td><code>GET</code></td><td><a href="/docs/health"><code>/readyz</code></a></td><td>Readiness probe</td></tr>
+  </tbody>
+</table>
+
+<h2>Pagination</h2>
+<p>List endpoints use <code>limit</code> and <code>offset</code> query parameters. The default limit is 20, maximum is 100.</p>
+
+<h2>Filtering</h2>
+<p>Search supports filters via query parameters: <code>collection</code>, <code>type</code>, <code>author</code>, <code>repo</code>, <code>language</code>, <code>state</code>, <code>from</code>, <code>to</code>. See the <a href="/docs/search">search endpoint docs</a> for details.</p>
+{{end}}
+{{template "layout" .}}

packages/api/internal/view/templates/docs/search.html

···
+{{define "title"}}GET /search — Twister API{{end}}
+{{define "content"}}
+<h1><code>GET /search</code></h1>
+<p>Search indexed Tangled documents with keyword matching. Returns a paginated list of results with highlighted snippets.</p>
+
+<h2>Parameters</h2>
+<table>
+  <thead><tr><th>Name</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+  <tbody>
+    <tr><td><code>q</code></td><td>string</td><td><em>required</em></td><td>Search query. Supports boolean operators, phrases, and prefix matching.</td></tr>
+    <tr><td><code>mode</code></td><td>string</td><td><code>keyword</code></td><td>Search mode: <code>keyword</code>, <code>semantic</code>, or <code>hybrid</code>.</td></tr>
+    <tr><td><code>limit</code></td><td>int</td><td><code>20</code></td><td>Results per page (1&ndash;100).</td></tr>
+    <tr><td><code>offset</code></td><td>int</td><td><code>0</code></td><td>Pagination offset.</td></tr>
+    <tr><td><code>collection</code></td><td>string</td><td>&mdash;</td><td>Filter by ATProto collection NSID.</td></tr>
+    <tr><td><code>type</code></td><td>string</td><td>&mdash;</td><td>Filter by record type: <code>repo</code>, <code>issue</code>, <code>pull</code>, <code>profile</code>, <code>string</code>.</td></tr>
+    <tr><td><code>author</code></td><td>string</td><td>&mdash;</td><td>Filter by author handle or DID.</td></tr>
+    <tr><td><code>repo</code></td><td>string</td><td>&mdash;</td><td>Filter by repo name.</td></tr>
+    <tr><td><code>language</code></td><td>string</td><td>&mdash;</td><td>Filter by programming language.</td></tr>
+    <tr><td><code>state</code></td><td>string</td><td>&mdash;</td><td>Filter by state: <code>open</code>, <code>closed</code>, <code>merged</code>.</td></tr>
+    <tr><td><code>from</code></td><td>string</td><td>&mdash;</td><td>Created after (ISO 8601).</td></tr>
+    <tr><td><code>to</code></td><td>string</td><td>&mdash;</td><td>Created before (ISO 8601).</td></tr>
+  </tbody>
+</table>
+
+<h2>Example Request</h2>
+<pre><code>curl "https://your-domain/search?q=rust+tui&type=repo&limit=5"</code></pre>
+
+<h2>Example Response</h2>
+<pre><code>{
+  "query": "rust tui",
+  "mode": "keyword",
+  "total": 12,
+  "limit": 5,
+  "offset": 0,
+  "results": [
+    {
+      "id": "did:plc:abc|sh.tangled.repo|3kb3fge5lm32x",
+      "collection": "sh.tangled.repo",
+      "record_type": "repo",
+      "title": "glow-rs",
+      "body_snippet": "A &lt;mark&gt;TUI&lt;/mark&gt; markdown viewer written in &lt;mark&gt;Rust&lt;/mark&gt;...",
+      "summary": "Rust TUI markdown viewer",
+      "repo_name": "glow-rs",
+      "author_handle": "desertthunder.dev",
+      "score": 0.842,
+      "created_at": "2026-03-20T10:00:00Z",
+      "updated_at": "2026-03-22T15:03:11Z"
+    }
+  ]
+}</code></pre>
+
+<h2>Query Syntax</h2>
+<p>The keyword search uses Tantivy query syntax:</p>
+<table>
+  <thead><tr><th>Feature</th><th>Example</th></tr></thead>
+  <tbody>
+    <tr><td>Boolean AND</td><td><code>go AND search</code></td></tr>
+    <tr><td>Boolean NOT</td><td><code>rust NOT unsafe</code></td></tr>
+    <tr><td>Phrase</td><td><code>"pull request"</code></td></tr>
+    <tr><td>Prefix</td><td><code>tang*</code></td></tr>
+    <tr><td>Field-scoped</td><td><code>title:parser</code></td></tr>
+  </tbody>
+</table>
+
+<h2>Errors</h2>
+<table>
+  <thead><tr><th>Status</th><th>Condition</th></tr></thead>
+  <tbody>
+    <tr><td>400</td><td>Missing <code>q</code>, invalid <code>limit</code>/<code>offset</code>, unknown parameters.</td></tr>
+    <tr><td>500</td><td>Internal search failure.</td></tr>
+  </tbody>
+</table>
+{{end}}
+{{template "layout" .}}

packages/api/internal/view/templates/index.html

···
+{{define "title"}}Twister — Search Tangled{{end}}
+{{define "head"}}
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+{{end}}
+{{define "content"}}
+<div x-data="searchApp()" x-init="initFromURL()">
+  <section class="search-hero">
+    <h1>Search Tangled</h1>
+    <form class="search-form" @submit.prevent="doSearch(true)">
+      <input type="text" x-model="query" placeholder="Search repos, issues, PRs, profiles&hellip;" class="search-input" autofocus>
+      <button type="submit" class="btn btn-primary">Search</button>
+    </form>
+    <div class="filter-bar">
+      <select x-model="filters.type" @change="doSearch(true)">
+        <option value="">All types</option>
+        <option value="repo">Repos</option>
+        <option value="issue">Issues</option>
+        <option value="pull">Pull Requests</option>
+        <option value="profile">Profiles</option>
+        <option value="string">Strings</option>
+        <option value="star">Stars</option>
+      </select>
+      <input type="text" x-model="filters.author" placeholder="Author" @keydown.enter="doSearch(true)" class="filter-input">
+      <input type="text" x-model="filters.language" placeholder="Language" @keydown.enter="doSearch(true)" class="filter-input">
+      <select x-model="filters.state" @change="doSearch(true)">
+        <option value="">Any state</option>
+        <option value="open">Open</option>
+        <option value="closed">Closed</option>
+        <option value="merged">Merged</option>
+      </select>
+    </div>
+  </section>
+
+  <section class="results">
+    <template x-if="error">
+      <div class="msg msg-error" x-text="error"></div>
+    </template>
+    <template x-if="!error && searched && results.length === 0">
+      <div class="msg">No results found.</div>
+    </template>
+    <template x-for="r in results" :key="r.id">
+      <a :href="canonicalURL(r)" target="_blank" rel="noopener" class="card">
+        <div class="card-head">
+          <span class="badge" x-text="r.record_type"></span>
+          <span class="card-title" x-text="r.title || r.id"></span>
+        </div>
+        <div class="card-snippet" x-show="r.body_snippet" x-html="r.body_snippet"></div>
+        <div class="card-meta">
+          <span x-show="r.author_handle" x-text="r.author_handle"></span>
+          <span x-show="r.repo_name" class="meta-sep" x-text="r.repo_name"></span>
+          <span x-show="r.updated_at" class="meta-sep" x-text="relTime(r.updated_at)"></span>
+        </div>
+      </a>
+    </template>
+    <template x-if="hasMore">
+      <button class="btn btn-more" @click="loadMore()" x-text="loading ? 'Loading\u2026' : 'Load more'" :disabled="loading"></button>
+    </template>
+  </section>
+</div>
+{{end}}
+{{define "scripts"}}
+<script src="/static/search.js"></script>
+{{end}}
+{{template "layout" .}}

packages/api/internal/view/templates/layout.html

···
+{{define "layout"}}<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{block "title" .}}Twister{{end}}</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&family=Google+Sans+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/static/style.css">
+  {{block "head" .}}{{end}}
+</head>
+<body>
+  <nav class="nav">
+    <div class="nav-inner">
+      <a href="/" class="nav-brand">twister</a>
+      <div class="nav-links">
+        <a href="/">Search</a>
+        <a href="/docs">API Docs</a>
+      </div>
+    </div>
+  </nav>
+  <main class="main">
+    {{block "content" .}}{{end}}
+  </main>
+  <footer class="footer">
+    <div class="footer-inner">
+      <span>Twister &mdash; search for <a href="https://tangled.sh" target="_blank" rel="noopener">Tangled</a></span>
+    </div>
+  </footer>
+  {{block "scripts" .}}{{end}}
+</body>
+</html>{{end}}

packages/api/internal/view/view.go

···
+package view
+
+import (
+	"embed"
+	"html/template"
+	"io/fs"
+	"net/http"
+)
+
+//go:embed templates static
+var content embed.FS
+
+var templates *template.Template
+
+func init() {
+	templates = template.Must(template.ParseFS(content,
+		"templates/layout.html",
+		"templates/index.html",
+		"templates/docs/index.html",
+		"templates/docs/search.html",
+		"templates/docs/documents.html",
+		"templates/docs/health.html",
+	))
+}
+
+// Handler returns an http.Handler that serves the site pages and static assets.
+func Handler() http.Handler {
+	mux := http.NewServeMux()
+
+	staticFS, _ := fs.Sub(content, "static")
+	mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServerFS(staticFS)))
+
+	mux.HandleFunc("GET /docs/search", renderPage("docs/search.html"))
+	mux.HandleFunc("GET /docs/documents", renderPage("docs/documents.html"))
+	mux.HandleFunc("GET /docs/health", renderPage("docs/health.html"))
+	mux.HandleFunc("GET /docs", renderPage("docs/index.html"))
+	mux.HandleFunc("GET /{$}", renderPage("index.html"))
+
+	return mux
+}
+
+func renderPage(name string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		if err := templates.ExecuteTemplate(w, name, nil); err != nil {
+			http.Error(w, "template error", http.StatusInternalServerError)
+		}
+	}
+}