artifacty 0.2.0 → 0.3.0

package/AGENTS.md

@@ -23,6 +23,8 @@ Artifacty shares LLM artifacts over HTTP, CLI, and MCP.
 - `node src/cli.js import --agent claude --file artifact.html`: convert and store an external artifact.
 - `node src/cli.js install claude --dry-run`: preview generated MCP config.
 - `node src/cli.js check`: verify MCP tool discovery.
+- `node src/cli.js index rebuild`: rebuild the optional SQLite FTS5 search index.
+- `node src/cli.js integrity`: verify version files, hashes, and orphaned files.
 
 ## Coding Style & Naming Conventions
 

package/README.md

@@ -165,6 +165,7 @@ List artifacts:
 
 ```bash
 artifacty list
+artifacty list --query review --limit 20 --offset 20
 ```
 
 Run the MCP server:
@@ -179,6 +180,8 @@ Operational commands:
 
 ```bash
 artifacty audit --limit 20
+artifacty index rebuild
+artifacty integrity
 artifacty backup
 artifacty export --file ./artifacty-backup.json
 artifacty import-store --file ./artifacty-backup.json
@@ -200,6 +203,13 @@ ARTIFACTY_HOME=/path/to/shared/store artifacty serve
 
 Artifact metadata is stored in `artifacty.sqlite`; artifact content is stored as immutable version files under `artifacts/`. The current browser server URL is written to `server.json` so MCP tools can return the correct links when the default port falls back. Existing `index.json` stores are migrated automatically on first access.
 
+Search uses a SQLite FTS5 index when the local Node SQLite build supports it. The index covers the latest version body plus title, tags, source agent, artifact type, format, and metadata summary. If FTS5 is unavailable, Artifacty keeps working with metadata search. Rebuild or check the store when needed:
+
+```bash
+artifacty index rebuild
+artifacty integrity
+```
+
 ## API Example
 
 Start a protected server in another terminal, or generate a reusable shell token first:
@@ -245,6 +255,13 @@ Browser routes:
 - `/artifacts/:id/diff`: compare versions.
 - `/api/audit`: list audit events.
 
+List APIs support pagination with `limit` and `offset`. Responses keep the top-level `artifacts` array and include `pagination` and `search` metadata:
+
+```bash
+curl -s "http://127.0.0.1:8787/api/artifacts?q=handoff&limit=20&offset=0" \
+  -H "x-artifacty-token: $ARTIFACTY_API_TOKEN"
+```
+
 ## Interface Language
 
 The browser UI defaults to English. Add `?lang=ko` to any browser route to use Korean, for example `http://127.0.0.1:8787/new?lang=ko`. Forms and in-app links preserve the selected language. Documentation is maintained in English only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifacty",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local artifact exchange for heterogeneous LLM agents via HTTP and MCP.",
   "type": "module",
   "keywords": [

package/src/cli.js

@@ -4,11 +4,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   archiveArtifact,
+  checkStoreIntegrity,
   createArtifact,
   createStore,
   getArtifact,
   listAuditEvents,
-  listArtifacts,
+  listArtifactsPage,
+  rebuildSearchIndex,
   restoreArtifact,
   updateArtifact
 } from "./lib/storage.js";
@@ -200,14 +202,37 @@ async function main() {
   }
 
   if (command === "list") {
-    const artifacts = await listArtifacts(store, {
+    const page = await listArtifactsPage(store, {
       query: options.query,
       tag: Array.isArray(options.tag) ? options.tag[0] : options.tag,
       sourceAgent: options.source,
       includeArchived: options.includeArchived,
-      limit: options.limit
+      limit: options.limit,
+      offset: options.offset
+    });
+    printJson({
+      artifacts: page.artifacts,
+      pagination: paginationJson(page),
+      search: page.search
     });
-    printJson({ artifacts });
+    return;
+  }
+
+  if ((command === "index" || command === "search") && options._[0] === "rebuild") {
+    const result = await rebuildSearchIndex(store);
+    printJson(result);
+    if (!result.fts5) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (command === "integrity" || command === "check-store") {
+    const result = await checkStoreIntegrity(store);
+    printJson(result);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
     return;
   }
 
@@ -298,7 +323,7 @@ function parseArgs(args) {
 
     if (key === "tag") {
       options.tag = [...(options.tag || []), value];
-    } else if (key === "port" || key === "limit" || key === "version" || key === "schema-version" || key === "timeout" || key === "bytes") {
+    } else if (key === "port" || key === "limit" || key === "offset" || key === "version" || key === "schema-version" || key === "timeout" || key === "bytes") {
       options[toCamelCase(key)] = Number(value);
     } else {
       options[toCamelCase(key)] = value;
@@ -342,6 +367,17 @@ async function withUrls(store, artifact) {
   };
 }
 
+function paginationJson(page) {
+  return {
+    total: page.total,
+    limit: page.limit,
+    offset: page.offset,
+    hasMore: page.hasMore,
+    nextOffset: page.nextOffset,
+    previousOffset: page.previousOffset
+  };
+}
+
 function requireOption(options, name) {
   if (!options[name]) {
     throw new Error(`Missing required option --${name}`);
@@ -370,11 +406,13 @@ Usage:
   artifacty archive <id>
   artifacty restore <id>
   artifacty audit [--artifact <id>] [--limit 100]
+  artifacty index rebuild
+  artifacty integrity
   artifacty export --file <path>
   artifacty backup [--file <path>]
   artifacty import-store --file <path>
   artifacty service plist|install|uninstall [--dry-run] [--plist <path>]
-  artifacty list [--query text] [--tag tag] [--source agent] [--limit 50] [--include-archived]
+  artifacty list [--query text] [--tag tag] [--source agent] [--limit 50] [--offset 0] [--include-archived]
   artifacty show <id> [--version n] [--raw]
 
 Environment:

package/src/lib/i18n.js

@@ -15,7 +15,11 @@ const TRANSLATIONS = {
     "language.english": "English",
     "language.korean": "Korean",
     "dashboard.count": "{count} artifacts",
+    "dashboard.range": "{start}-{end} of {total} artifacts",
+    "dashboard.searchBackend": "{backend} search",
     "dashboard.empty": "No artifacts published yet.",
+    "dashboard.previous": "Previous",
+    "dashboard.next": "Next",
     "filter.search": "Search",
     "filter.tag": "Tag",
     "filter.source": "Source",
@@ -69,7 +73,11 @@ const TRANSLATIONS = {
     "language.english": "영어",
     "language.korean": "한국어",
     "dashboard.count": "아티팩트 {count}개",
+    "dashboard.range": "아티팩트 {total}개 중 {start}-{end}",
+    "dashboard.searchBackend": "{backend} 검색",
     "dashboard.empty": "아직 게시된 아티팩트가 없습니다.",
+    "dashboard.previous": "이전",
+    "dashboard.next": "다음",
     "filter.search": "검색",
     "filter.tag": "태그",
     "filter.source": "소스",

package/src/lib/render.js

@@ -2,17 +2,26 @@ import { EDITOR_CLIENT_PATH, VIEWER_CLIENT_PATH, editorImportMapJson } from "./e
 import { createI18n, DEFAULT_LOCALE, editorMessages, localizedHref, switchLocaleHref } from "./i18n.js";
 import { ARTIFACT_FORMATS, ARTIFACT_TYPES } from "./storage.js";
 
-export function renderDashboard({ artifacts, baseUrl, filters = {}, locale = DEFAULT_LOCALE, currentPath = "/" }) {
+export function renderDashboard({ artifacts, baseUrl, filters = {}, pagination, locale = DEFAULT_LOCALE, currentPath = "/" }) {
   const view = viewContext(locale, currentPath);
+  const total = pagination?.total ?? artifacts.length;
+  const start = artifacts.length ? (pagination?.offset ?? 0) + 1 : 0;
+  const end = artifacts.length ? (pagination?.offset ?? 0) + artifacts.length : 0;
+  const searchBackend = pagination?.search?.backend;
+  const pager = renderDashboardPager({ pagination, filters, view });
   const rows = artifacts
     .map((artifact) => {
       const tags = artifact.tags.map((tag) => `<span class="tag">${escapeHtml(tag)}</span>`).join("");
       const status = artifact.archivedAt ? statusBadge("archived") : "";
+      const snippet = artifact.searchSnippet
+        ? `<span class="row-snippet">${escapeHtml(artifact.searchSnippet)}</span>`
+        : "";
       return `
         <a class="artifact-row" href="${view.href(`/artifacts/${encodeURIComponent(artifact.id)}`)}">
           <span class="row-main">
             <strong>${escapeHtml(artifact.title)}</strong>
             <span>${escapeHtml(artifact.id)}</span>
+            ${snippet}
           </span>
           <span>${escapeHtml(artifact.sourceAgent)}</span>
           ${typeBadge(artifact.artifactType || "document")}
@@ -44,10 +53,12 @@ export function renderDashboard({ artifacts, baseUrl, filters = {}, locale = DEF
       </header>
       <main class="dashboard">
         <section class="toolbar">
-          <span>${view.text("dashboard.count", { count: artifacts.length })}</span>
+          <span>${view.text("dashboard.range", { start, end, total })}</span>
+          ${searchBackend ? `<span>${view.text("dashboard.searchBackend", { backend: searchBackend })}</span>` : ""}
         </section>
         <form class="filter-form" method="get" action="/">
           ${localeInput(view.locale)}
+          ${filters.limit ? `<input type="hidden" name="limit" value="${escapeAttribute(filters.limit)}">` : ""}
           <input name="q" value="${escapeAttribute(filters.query || "")}" placeholder="${view.attr("filter.search")}">
           <input name="tag" value="${escapeAttribute(filters.tag || "")}" placeholder="${view.attr("filter.tag")}">
           <input name="sourceAgent" value="${escapeAttribute(filters.sourceAgent || "")}" placeholder="${view.attr("filter.source")}">
@@ -58,12 +69,52 @@ export function renderDashboard({ artifacts, baseUrl, filters = {}, locale = DEF
         <section class="artifact-list">
           ${rows || `<div class="empty">${view.text("dashboard.empty")}</div>`}
         </section>
+        ${pager}
       </main>
     `,
     locale: view.locale
   });
 }
 
+function renderDashboardPager({ pagination, filters, view }) {
+  if (!pagination || pagination.total <= pagination.limit) {
+    return "";
+  }
+
+  const previous = pagination.previousOffset === null
+    ? `<span class="pager-disabled">${view.text("dashboard.previous")}</span>`
+    : `<a href="${view.href(dashboardPageHref(filters, pagination.previousOffset))}">${view.text("dashboard.previous")}</a>`;
+  const next = pagination.nextOffset === null
+    ? `<span class="pager-disabled">${view.text("dashboard.next")}</span>`
+    : `<a href="${view.href(dashboardPageHref(filters, pagination.nextOffset))}">${view.text("dashboard.next")}</a>`;
+
+  return `<nav class="pager" aria-label="Pagination">${previous}${next}</nav>`;
+}
+
+function dashboardPageHref(filters, offset) {
+  const params = new URLSearchParams();
+  if (filters.query) {
+    params.set("q", filters.query);
+  }
+  if (filters.tag) {
+    params.set("tag", filters.tag);
+  }
+  if (filters.sourceAgent) {
+    params.set("sourceAgent", filters.sourceAgent);
+  }
+  if (filters.includeArchived) {
+    params.set("includeArchived", "true");
+  }
+  if (filters.limit) {
+    params.set("limit", filters.limit);
+  }
+  if (offset > 0) {
+    params.set("offset", String(offset));
+  }
+  const query = params.toString();
+  return query ? `/?${query}` : "/";
+}
+
 export function renderArtifactFormPage({ mode, baseUrl, artifact, version, content, authToken = "", locale = DEFAULT_LOCALE, currentPath = "/" }) {
   const view = viewContext(locale, currentPath);
   const isEdit = mode === "edit";
@@ -705,6 +756,34 @@ export function pageShell({ title, body, head = "", afterBody = "", locale = DEF
       background: var(--panel);
       box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04);
     }
+    .pager {
+      display: flex;
+      justify-content: flex-end;
+      gap: 8px;
+      margin-top: 14px;
+      font-family: var(--mono);
+      font-size: 12.5px;
+    }
+    .pager a,
+    .pager-disabled {
+      display: inline-flex;
+      min-height: 34px;
+      align-items: center;
+      justify-content: center;
+      padding: 5px 12px;
+      border: 1px solid var(--line-2);
+      border-radius: 8px;
+      background: var(--panel);
+      color: var(--muted);
+    }
+    .pager a:hover {
+      border-color: var(--accent);
+      color: var(--text);
+      text-decoration: none;
+    }
+    .pager-disabled {
+      opacity: 0.55;
+    }
     .editor-form {
       display: grid;
       gap: 16px;
@@ -889,6 +968,13 @@ export function pageShell({ title, body, head = "", afterBody = "", locale = DEF
       font-size: 12px;
       color: var(--faint);
     }
+    .row-main .row-snippet {
+      color: var(--muted);
+      white-space: normal;
+      overflow: visible;
+      text-overflow: clip;
+      overflow-wrap: anywhere;
+    }
     .artifact-row > span:not(.row-main):not(.tags):not(.badge) {
       font-family: var(--mono);
       font-size: 12.5px;

package/src/lib/storage.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -112,6 +112,7 @@ export async function writeIndex(store, index) {
   const db = openDatabase(store);
   try {
     transaction(db, () => {
+      clearSearchIndex(db);
       db.prepare("DELETE FROM artifact_versions").run();
       db.prepare("DELETE FROM artifacts").run();
       for (const artifact of index.artifacts) {
@@ -120,6 +121,7 @@ export async function writeIndex(store, index) {
           insertVersionRecord(db, artifact.id, version);
         }
       }
+      rebuildSearchIndexInDb(db, store);
     });
   } finally {
     db.close();
@@ -155,6 +157,7 @@ export async function createArtifact(store = createStore(), input = {}) {
 
       insertArtifactRecord(db, artifact);
       insertVersionRecord(db, id, version);
+      upsertSearchIndex(db, artifact, version, normalized.content);
       insertAuditRecord(db, {
         action: input.auditAction || "create",
         artifactId: id,
@@ -209,6 +212,7 @@ export async function updateArtifact(store = createStore(), id, input = {}) {
         artifact.id
       );
       insertVersionRecord(db, artifact.id, version);
+      upsertSearchIndex(db, artifact, version, normalized.content);
       insertAuditRecord(db, {
         action: input.auditAction || "update",
         artifactId: artifact.id,
@@ -280,30 +284,316 @@ export async function restoreArtifact(store = createStore(), id, options = {}) {
 }
 
 export async function listArtifacts(store = createStore(), filters = {}) {
-  const index = await loadIndex(store);
+  return (await listArtifactsPage(store, filters)).artifacts;
+}
+
+export async function listArtifactsPage(store = createStore(), filters = {}) {
+  const db = openDatabase(store);
   const limit = clampInteger(filters.limit, 1, 200, 50);
-  const query = normalizeOptionalString(filters.query).toLowerCase();
+  const offset = clampInteger(filters.offset, 0, 1_000_000, 0);
+  const query = normalizeOptionalString(filters.query);
+  const normalizedQuery = query.toLowerCase();
   const tag = normalizeOptionalString(filters.tag).toLowerCase();
   const sourceAgent = normalizeOptionalString(filters.sourceAgent).toLowerCase();
 
-  return index.artifacts
-    .filter((artifact) => {
-      if (!filters.includeArchived && artifact.archivedAt) {
-        return false;
+  try {
+    if (query && searchIndexAvailable(db)) {
+      const ftsQuery = toFtsQuery(query);
+      if (ftsQuery) {
+        try {
+          const page = listArtifactsPageWithFts(db, {
+            ftsQuery,
+            tag,
+            sourceAgent,
+            includeArchived: filters.includeArchived,
+            limit,
+            offset
+          });
+          if (page.total > 0) {
+            return page;
+          }
+        } catch {
+          // Keep search usable even if the SQLite FTS parser rejects a query.
+        }
       }
-      if (query && !artifactMatchesQuery(artifact, query)) {
-        return false;
+    }
+
+    return listArtifactsPageWithSql(db, {
+      query: normalizedQuery,
+      tag,
+      sourceAgent,
+      includeArchived: filters.includeArchived,
+      limit,
+      offset
+    });
+  } finally {
+    db.close();
+  }
+}
+
+export async function rebuildSearchIndex(store = createStore()) {
+  const db = openDatabase(store);
+  try {
+    if (!searchIndexAvailable(db)) {
+      return {
+        ok: false,
+        fts5: false,
+        indexed: 0,
+        skipped: [],
+        message: "SQLite FTS5 is unavailable; metadata search fallback remains active."
+      };
+    }
+
+    return transaction(db, () => rebuildSearchIndexInDb(db, store));
+  } finally {
+    db.close();
+  }
+}
+
+export async function checkStoreIntegrity(store = createStore()) {
+  const db = openDatabase(store);
+  const checkedAt = new Date().toISOString();
+  try {
+    const artifacts = loadArtifacts(db);
+    const referencedPaths = new Set();
+    const missingFiles = [];
+    const hashMismatches = [];
+    const sizeMismatches = [];
+    const dbInconsistencies = [];
+    let totalBytes = 0;
+    let versionCount = 0;
+
+    for (const artifact of artifacts) {
+      if (!artifact.versions.length) {
+        dbInconsistencies.push({
+          artifactId: artifact.id,
+          issue: "artifact has no version rows"
+        });
       }
-      if (tag && !artifact.tags.some((item) => item.toLowerCase() === tag)) {
-        return false;
+      if (!artifact.versions.some((version) => version.version === artifact.latestVersion)) {
+        dbInconsistencies.push({
+          artifactId: artifact.id,
+          issue: `latest version ${artifact.latestVersion} has no version row`
+        });
       }
-      if (sourceAgent && artifact.sourceAgent.toLowerCase() !== sourceAgent) {
-        return false;
+
+      for (const version of artifact.versions) {
+        versionCount += 1;
+        const absolutePath = path.resolve(store.home, version.path);
+        referencedPaths.add(absolutePath);
+        if (!existsSync(absolutePath)) {
+          missingFiles.push({
+            artifactId: artifact.id,
+            version: version.version,
+            path: version.path
+          });
+          continue;
+        }
+
+        const content = readFileSync(absolutePath);
+        const actualSize = content.byteLength;
+        const actualSha256 = createHash("sha256").update(content).digest("hex");
+        totalBytes += actualSize;
+
+        if (actualSize !== version.sizeBytes) {
+          sizeMismatches.push({
+            artifactId: artifact.id,
+            version: version.version,
+            path: version.path,
+            expected: version.sizeBytes,
+            actual: actualSize
+          });
+        }
+        if (actualSha256 !== version.sha256) {
+          hashMismatches.push({
+            artifactId: artifact.id,
+            version: version.version,
+            path: version.path,
+            expected: version.sha256,
+            actual: actualSha256
+          });
+        }
       }
-      return true;
-    })
-    .slice(0, limit)
-    .map(toArtifactSummary);
+    }
+
+    const orphanFiles = listStoreFiles(store.artifactsDir)
+      .filter((filePath) => !referencedPaths.has(filePath))
+      .map((filePath) => {
+        const stat = statSync(filePath);
+        return {
+          path: path.relative(store.home, filePath),
+          sizeBytes: stat.size
+        };
+      });
+    const orphanBytes = orphanFiles.reduce((sum, file) => sum + file.sizeBytes, 0);
+    const ok =
+      missingFiles.length === 0 &&
+      hashMismatches.length === 0 &&
+      sizeMismatches.length === 0 &&
+      orphanFiles.length === 0 &&
+      dbInconsistencies.length === 0;
+
+    return {
+      ok,
+      checkedAt,
+      store: store.home,
+      artifactCount: artifacts.length,
+      versionCount,
+      totalBytes,
+      orphanBytes,
+      missingFiles,
+      hashMismatches,
+      sizeMismatches,
+      orphanFiles,
+      dbInconsistencies
+    };
+  } finally {
+    db.close();
+  }
+}
+
+function listArtifactsPageWithSql(db, filters) {
+  const { clauses, params } = artifactWhereClauses(filters);
+  if (filters.query) {
+    const like = `%${escapeLike(filters.query)}%`;
+    clauses.push(`(
+      LOWER(id) LIKE ? ESCAPE '\\' OR
+      LOWER(title) LIKE ? ESCAPE '\\' OR
+      LOWER(source_agent) LIKE ? ESCAPE '\\' OR
+      LOWER(tags_json) LIKE ? ESCAPE '\\'
+    )`);
+    params.push(like, like, like, like);
+  }
+
+  const whereSql = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+  const total = db.prepare(`SELECT COUNT(*) AS total FROM artifacts ${whereSql}`).get(...params).total;
+  const rows = db.prepare(`
+    SELECT id, title, artifact_type, schema_version, source_agent, tags_json, created_at, updated_at, latest_version, archived_at
+    FROM artifacts
+    ${whereSql}
+    ORDER BY updated_at DESC, created_at DESC
+    LIMIT ? OFFSET ?
+  `).all(...params, filters.limit, filters.offset);
+
+  return pagedResult({
+    artifacts: rows.map((row) => toArtifactSummary(artifactFromRow(db, row))),
+    total,
+    limit: filters.limit,
+    offset: filters.offset,
+    searchBackend: filters.query ? "metadata" : "sqlite"
+  });
+}
+
+function listArtifactsPageWithFts(db, filters) {
+  const { clauses, params } = artifactWhereClauses(filters, "a");
+  clauses.unshift("artifact_search MATCH ?");
+  params.unshift(filters.ftsQuery);
+  const whereSql = `WHERE ${clauses.join(" AND ")}`;
+  const total = db.prepare(`
+    SELECT COUNT(*) AS total
+    FROM artifact_search
+    JOIN artifacts a ON a.id = artifact_search.artifact_id
+    ${whereSql}
+  `).get(...params).total;
+  const rows = db.prepare(`
+    SELECT
+      a.id,
+      a.title,
+      a.artifact_type,
+      a.schema_version,
+      a.source_agent,
+      a.tags_json,
+      a.created_at,
+      a.updated_at,
+      a.latest_version,
+      a.archived_at,
+      bm25(artifact_search) AS search_rank,
+      snippet(artifact_search, 7, '', '', '...', 24) AS search_snippet
+    FROM artifact_search
+    JOIN artifacts a ON a.id = artifact_search.artifact_id
+    ${whereSql}
+    ORDER BY search_rank ASC, a.updated_at DESC, a.created_at DESC
+    LIMIT ? OFFSET ?
+  `).all(...params, filters.limit, filters.offset);
+
+  return pagedResult({
+    artifacts: rows.map((row) => ({
+      ...toArtifactSummary(artifactFromRow(db, row)),
+      searchScore: row.search_rank,
+      searchSnippet: normalizeWhitespace(row.search_snippet)
+    })),
+    total,
+    limit: filters.limit,
+    offset: filters.offset,
+    searchBackend: "fts5"
+  });
+}
+
+function artifactWhereClauses(filters, alias = "") {
+  const prefix = alias ? `${alias}.` : "";
+  const clauses = [];
+  const params = [];
+
+  if (!filters.includeArchived) {
+    clauses.push(`${prefix}archived_at IS NULL`);
+  }
+  if (filters.tag) {
+    clauses.push(`LOWER(${prefix}tags_json) LIKE ? ESCAPE '\\'`);
+    params.push(`%"${escapeLike(filters.tag)}"%`);
+  }
+  if (filters.sourceAgent) {
+    clauses.push(`LOWER(${prefix}source_agent) = ?`);
+    params.push(filters.sourceAgent);
+  }
+
+  return { clauses, params };
+}
+
+function pagedResult({ artifacts, total, limit, offset, searchBackend }) {
+  return {
+    artifacts,
+    total,
+    limit,
+    offset,
+    hasMore: offset + artifacts.length < total,
+    nextOffset: offset + artifacts.length < total ? offset + limit : null,
+    previousOffset: offset > 0 ? Math.max(0, offset - limit) : null,
+    search: {
+      backend: searchBackend
+    }
+  };
+}
+
+function artifactFromRow(db, row) {
+  return {
+    id: row.id,
+    title: row.title,
+    artifactType: row.artifact_type,
+    schemaVersion: row.schema_version,
+    sourceAgent: row.source_agent,
+    tags: parseJson(row.tags_json, []),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    archivedAt: row.archived_at,
+    latestVersion: row.latest_version,
+    versions: loadVersions(db, row.id)
+  };
+}
+
+function escapeLike(value) {
+  return String(value).replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+
+function normalizeWhitespace(value) {
+  return normalizeOptionalString(value).replace(/\s+/g, " ");
+}
+
+function toFtsQuery(value) {
+  const tokens = normalizeOptionalString(value).match(/[\p{L}\p{N}_-]+/gu) || [];
+  return tokens
+    .slice(0, 12)
+    .map((token) => `"${token.replaceAll("\"", "\"\"")}"`)
+    .join(" AND ");
 }
 
 export async function getArtifact(store = createStore(), id, options = {}) {
@@ -458,6 +748,7 @@ function openDatabase(store) {
   `);
   initializeSchema(db);
   migrateJsonIndex(db, store);
+  syncSearchIndexIfEmpty(db, store);
   return db;
 }
 
@@ -516,6 +807,7 @@ function initializeSchema(db) {
   ensureColumn(db, "artifacts", "schema_version", "INTEGER NOT NULL DEFAULT 1");
   ensureColumn(db, "artifacts", "archived_at", "TEXT");
   db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('store_version', ?)").run(String(STORE_VERSION));
+  ensureSearchTable(db);
 }
 
 function migrateJsonIndex(db, store) {
@@ -551,6 +843,135 @@ function migrateJsonIndex(db, store) {
   });
 }
 
+function ensureSearchTable(db) {
+  try {
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS artifact_search USING fts5(
+        artifact_id UNINDEXED,
+        title,
+        source_agent,
+        artifact_type,
+        tags,
+        format,
+        metadata,
+        content
+      );
+    `);
+    db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('fts5_enabled', 'true')").run();
+    return true;
+  } catch (error) {
+    db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('fts5_enabled', ?)").run(`false:${error.message}`);
+    return false;
+  }
+}
+
+function searchIndexAvailable(db) {
+  const row = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'artifact_search'").get();
+  return Boolean(row) || ensureSearchTable(db);
+}
+
+function syncSearchIndexIfEmpty(db, store) {
+  if (!searchIndexAvailable(db)) {
+    return;
+  }
+  const artifactCount = db.prepare("SELECT COUNT(*) AS count FROM artifacts").get().count;
+  if (artifactCount === 0) {
+    return;
+  }
+  const indexedCount = db.prepare("SELECT COUNT(*) AS count FROM artifact_search").get().count;
+  if (indexedCount === 0) {
+    transaction(db, () => rebuildSearchIndexInDb(db, store));
+  }
+}
+
+function clearSearchIndex(db) {
+  if (searchIndexAvailable(db)) {
+    db.prepare("DELETE FROM artifact_search").run();
+  }
+}
+
+function rebuildSearchIndexInDb(db, store) {
+  if (!searchIndexAvailable(db)) {
+    return {
+      ok: false,
+      fts5: false,
+      indexed: 0,
+      skipped: []
+    };
+  }
+
+  db.prepare("DELETE FROM artifact_search").run();
+  const skipped = [];
+  let indexed = 0;
+  for (const artifact of loadArtifacts(db)) {
+    const latest = artifact.versions.find((version) => version.version === artifact.latestVersion);
+    if (!latest) {
+      skipped.push({ artifactId: artifact.id, reason: "latest version row missing" });
+      continue;
+    }
+    const absolutePath = path.join(store.home, latest.path);
+    if (!existsSync(absolutePath)) {
+      skipped.push({ artifactId: artifact.id, version: latest.version, reason: "version file missing" });
+      continue;
+    }
+    upsertSearchIndex(db, artifact, latest, readFileSync(absolutePath, "utf8"));
+    indexed += 1;
+  }
+  db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('search_index_built_at', ?)").run(new Date().toISOString());
+  return {
+    ok: skipped.length === 0,
+    fts5: true,
+    indexed,
+    skipped
+  };
+}
+
+function upsertSearchIndex(db, artifact, version, content) {
+  if (!searchIndexAvailable(db)) {
+    return;
+  }
+  db.prepare("DELETE FROM artifact_search WHERE artifact_id = ?").run(artifact.id);
+  db.prepare(`
+    INSERT INTO artifact_search (
+      artifact_id, title, source_agent, artifact_type, tags, format, metadata, content
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    artifact.id,
+    artifact.title,
+    artifact.sourceAgent,
+    artifact.artifactType,
+    artifact.tags.join(" "),
+    version.format,
+    metadataSearchText(version.metadata),
+    content
+  );
+}
+
+function metadataSearchText(metadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return "";
+  }
+  return JSON.stringify(metadata).slice(0, 64 * 1024);
+}
+
+function listStoreFiles(root) {
+  if (!existsSync(root)) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listStoreFiles(fullPath));
+    } else if (entry.isFile()) {
+      files.push(path.resolve(fullPath));
+    }
+  }
+  return files;
+}
+
 function loadArtifacts(db) {
   const rows = db.prepare(`
     SELECT id, title, artifact_type, schema_version, source_agent, tags_json, created_at, updated_at, latest_version, archived_at
@@ -914,19 +1335,6 @@ function makeArtifactId(title) {
   return `${slug}-${randomUUID().slice(0, 8)}`;
 }
 
-function artifactMatchesQuery(artifact, query) {
-  const haystack = [
-    artifact.id,
-    artifact.title,
-    artifact.sourceAgent,
-    ...artifact.tags
-  ]
-    .join(" ")
-    .toLowerCase();
-
-  return haystack.includes(query);
-}
-
 function clampInteger(value, min, max, fallback) {
   const parsed = Number.parseInt(value, 10);
   if (Number.isNaN(parsed)) {

package/src/mcp-server.js

@@ -8,7 +8,7 @@ import {
   createStore,
   getArtifact,
   listAuditEvents,
-  listArtifacts,
+  listArtifactsPage,
   restoreArtifact,
   updateArtifact
 } from "./lib/storage.js";
@@ -86,7 +86,8 @@ const tools = [
         tag: { type: "string" },
         sourceAgent: { type: "string" },
         includeArchived: { type: "boolean" },
-        limit: { type: "number" }
+        limit: { type: "number" },
+        offset: { type: "number" }
       }
     },
     annotations: {
@@ -315,7 +316,7 @@ async function handleRequest(message) {
       serverInfo: {
         name: "artifacty",
         title: "Artifacty",
-        version: "0.1.0"
+        version: "0.3.0"
       },
       instructions: "Use Artifacty to create, import, list, read, and update local artifacts that other agents can reuse."
     };
@@ -346,12 +347,21 @@ async function callTool(name, args) {
 
   if (name === "artifacty_list") {
     const publicBaseUrl = await resolvePublicBaseUrl(store);
-    const artifacts = await listArtifacts(store, args);
+    const page = await listArtifactsPage(store, args);
     return toolResult({
-      artifacts: artifacts.map((artifact) => ({
+      artifacts: page.artifacts.map((artifact) => ({
         ...artifact,
         url: `${publicBaseUrl}/artifacts/${encodeURIComponent(artifact.id)}`
-      }))
+      })),
+      pagination: {
+        total: page.total,
+        limit: page.limit,
+        offset: page.offset,
+        hasMore: page.hasMore,
+        nextOffset: page.nextOffset,
+        previousOffset: page.previousOffset
+      },
+      search: page.search
     });
   }
 

package/src/server.js

@@ -9,7 +9,7 @@ import {
   createArtifact,
   createStore,
   getArtifact,
-  listArtifacts,
+  listArtifactsPage,
   listAuditEvents,
   MAX_ARTIFACT_BYTES,
   restoreArtifact,
@@ -177,15 +177,19 @@ export async function handleRequest({ request, response, store, host, port, secu
       query: url.searchParams.get("q") || "",
       tag: url.searchParams.get("tag") || "",
       sourceAgent: url.searchParams.get("sourceAgent") || "",
-      includeArchived: url.searchParams.get("includeArchived") === "true"
+      includeArchived: url.searchParams.get("includeArchived") === "true",
+      limit: url.searchParams.get("limit") || undefined,
+      offset: url.searchParams.get("offset") || undefined
     };
-    const artifacts = await listArtifacts(store, {
+    const page = await listArtifactsPage(store, {
       query: filters.query || undefined,
       tag: filters.tag || undefined,
       sourceAgent: filters.sourceAgent || undefined,
-      includeArchived: filters.includeArchived
+      includeArchived: filters.includeArchived,
+      limit: filters.limit,
+      offset: filters.offset
     });
-    return sendHtml(response, renderDashboard({ artifacts, baseUrl, filters, locale, currentPath }), 200, headOnly);
+    return sendHtml(response, renderDashboard({ artifacts: page.artifacts, baseUrl, filters, pagination: page, locale, currentPath }), 200, headOnly);
   }
 
   if (method === "GET" && pathname === "/new") {
@@ -240,14 +244,19 @@ export async function handleRequest({ request, response, store, host, port, secu
   }
 
   if (method === "GET" && pathname === "/api/artifacts") {
-    const artifacts = await listArtifacts(store, {
+    const page = await listArtifactsPage(store, {
       query: url.searchParams.get("q") || undefined,
       tag: url.searchParams.get("tag") || undefined,
       sourceAgent: url.searchParams.get("sourceAgent") || undefined,
       includeArchived: url.searchParams.get("includeArchived") === "true",
-      limit: url.searchParams.get("limit") || undefined
+      limit: url.searchParams.get("limit") || undefined,
+      offset: url.searchParams.get("offset") || undefined
     });
-    return sendJson(response, { artifacts }, 200, headOnly);
+    return sendJson(response, {
+      artifacts: page.artifacts,
+      pagination: paginationJson(page),
+      search: page.search
+    }, 200, headOnly);
   }
 
   if (method === "GET" && pathname === "/api/audit") {
@@ -442,6 +451,17 @@ export function decorateArtifactUrls(artifact, baseUrl) {
   };
 }
 
+function paginationJson(page) {
+  return {
+    total: page.total,
+    limit: page.limit,
+    offset: page.offset,
+    hasMore: page.hasMore,
+    nextOffset: page.nextOffset,
+    previousOffset: page.previousOffset
+  };
+}
+
 export async function readJsonBody(request) {
   const raw = await readBody(request, MAX_ARTIFACT_BYTES + 1024);
   if (!raw.trim()) {