@hiai-gg/docsmint 0.6.8 → 0.7.1

package/README.md

@@ -17,13 +17,18 @@ server.
 [![Stars](https://img.shields.io/github/stars/hiai-gg/docsmint)](https://github.com/hiai-gg/docsmint/stargazers)
 [![CI](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml/badge.svg)](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)
 [![Bun](https://img.shields.io/badge/Runtime-Bun_1.3-black?logo=bun&logoColor=white)](https://bun.sh)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![Svelte](https://img.shields.io/badge/Svelte-5.x-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev)
 [![Elysia](https://img.shields.io/badge/Elysia-1.4-lightgrey?logo=elysia&logoColor=white)](https://elysiajs.com)
 [![Tailwind_CSS](https://img.shields.io/badge/Tailwind_CSS-v4-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
 [![Drizzle_ORM](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle&logoColor=black)](https://orm.drizzle.team)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-[![MCP Badge](https://lobehub.com/badge/mcp/hiai-gg-docsmint?style=plastic)](https://lobehub.com/mcp/hiai-gg-docsmint)
+[![MCP Badge](https://lobehub.com/badge/mcp/hiai-gg-docsmint)](https://lobehub.com/mcp/hiai-gg-docsmint)
+
+[GitHub](https://github.com/HiAi-gg/docsmint) ·
+[Docker Hub](https://hub.docker.com/r/vgalibov/docsmint) ·
+[npm](https://www.npmjs.com/package/@hiai-gg/docsmint) ·
+[LobeHub MCP](https://lobehub.com/mcp/hiai-gg-docsmint)
 
 <img width="1920" height="974" alt="DocsMint installable document workspace" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />
 
@@ -40,99 +45,22 @@ server.
 - **Own the full stack**: application data, vectors, graph, queue, and files run
   on infrastructure you control.
 
-## What's new in DocsMint 0.6.8?
-
-- **Workspace-safe recovery.** Explicit operator reindexing carries the
-  document's workspace into every durable pipeline stage, including RLS reads.
-- **Consistent operator authentication.** Both documented admin key headers
-  bypass interactive rate limits during maintenance operations.
-
-DocsMint 0.6.8 includes the self-host reliability fixes introduced in 0.6.7:
-
-- **Reliable HTTPS sessions.** Every protected SvelteKit route accepts Better
-  Auth's secure production cookie as well as the local-development cookie.
-- **Cleaner retrieval.** Deleted documents are excluded before exact, lexical,
-  fuzzy, vector, chunk, and graph ranking.
-- **Explicit GraphRAG providers.** Entity extraction requires its own
-  chat-completion URL and never sends chat requests to an embedding endpoint.
-- **Safer self-host defaults.** Auth origins are validated configuration, the
-  SeaweedFS Filer UI binds to loopback, folder moves refresh knowledge
-  metadata, and backups exclude `.env`.
-
-DocsMint 0.6.7 includes the safe index recovery introduced in 0.6.6:
-
-- **Safe explicit index recovery.** Admin document reindexing keeps the active
-  generation searchable until a new generation has passed embedding, graph,
-  summary, and finalize stages.
-- **Truthful queue admission.** Maintenance requests force a replacement
-  generation and report an error when durable enqueue fails instead of
-  returning a false-positive success.
-- **Verified MCP distribution.** The official MCP Registry manifest, npm stdio
-  package, hosted Streamable HTTP endpoint, bundled Skill, prompts, resources,
-  and 17-tool catalog remain one versioned contract.
-
-DocsMint 0.6.6 includes the registry metadata fixes released in 0.6.3-0.6.5
-and the complete MCP foundation introduced in 0.6.2:
-
-- **Official MCP identity.** DocsMint now publishes the verified
-  `io.github.HiAi-gg/docsmint` registry identity for both the npm stdio server
-  and the hosted Streamable HTTP endpoint.
-- **One capability implementation.** The public `@hiai-gg/docsmint/mcp`
-  contract lets hosts provide a scoped API client while reusing the same 17
-  tools, two prompts, three resources, and bundled document-manager Skill.
-- **Current protocol runtime.** The MCP server uses the stable v2 server
-  package and retains compatible stdio negotiation for existing clients.
-
-DocsMint 0.6.2 includes the reliable knowledge refresh and scoped automation
-foundation introduced in 0.6.1:
-
-- **Reliable knowledge refreshes.** Explicit full reindexing now supersedes
-  failed or stuck generations, retries release stale extraction claims, and
-  publishes embeddings, summaries, and graph projections only for the current
-  document generation.
-- **Safer scoped automation.** Global keys can manage the complete document
-  domain, while category keys stay confined to their category, folders,
-  documents, tags, graph traversal, and index operations according to explicit
-  `read`, `edit`, and `write` permissions.
-- **Portable agent integration.** The MCP package exposes 17 document-manager
-  tools, two reusable prompts, three context resources, and a bundled Skill,
-  with Bunx, NPX, and local-checkout installation paths.
-- **Compatible frontend packaging.** Published frontend entrypoints resolve the
-  canonical hiai-ui exports used by the source build and packed consumers.
-
-DocsMint 0.6.1 includes the mobile and PWA foundation introduced in 0.6.0:
-
-- **Installable, update-safe PWA.** A versioned service worker, responsive app
-  shell, install prompt, and deterministic offline fallback make DocsMint feel
-  at home on desktop and mobile browsers.
-- **Private offline reading and explicit drafts.** Identity-partitioned local
-  snapshots keep selected documents readable offline. Drafts autosave locally,
-  then return through a deliberate review-and-apply flow after reconnecting;
-  DocsMint never silently replays offline mutations.
-- **Touch-safe mobile navigation.** Sidebar document actions, Copy controls, and
-  overflow menus remain reachable on touch devices without depending on hover,
-  with accessible targets and narrow-screen layouts.
-- **A flexible editor contract.** Reactive visual/Markdown mode preferences,
-  Minimal toolbar support, and a reusable compact TipTap editor let hosts match
-  the writing surface to the task without forking editor internals.
-- **Stable document discovery.** The public API and TypeScript SDK provide
-  deterministic cursor pagination and global sorting by title, category,
-  folder, or update time, with canonical category and folder metadata.
-- **Clear public and restricted sharing.** Share creation exposes the resulting
-  URL for both public links and restricted invitation workflows, with an
-  explicit Copy action that works on narrow screens.
-- **Knowledge built for agents.** REST, the typed SDK, CLI, and MCP server expose
-  scoped document operations, while multilingual hybrid search and GraphRAG
-  help people and AI agents retrieve connected knowledge instead of isolated
-  keyword matches.
-
-DocsMint combines an installable self-hosted PWA knowledge base, mobile document
-workspace, offline reading, local drafts, multilingual semantic search,
-GraphRAG, MCP, a TypeScript SDK, CLI, and composable frontend hosts in one
-open-source system.
-
-For self-hosted customization, see [PWA hosting](docs/PWA_HOSTING.md) and
-[extension points](docs/EXTENDING.md).
+## What's new in 0.7.0?
+
+- **Signed workspace assertions.** Trusted server-to-server hosts can restrict
+  an assertion to one category with independent `read`, `edit`, and `write`
+  permissions. An omitted scope remains workspace-wide and role-derived.
+- **Consistent effective-category authorization.** Direct and folder-inherited
+  categories are enforced before counts, pagination, indexing, search, and
+  GraphRAG retrieval. Index status is read-only; refresh requires write.
+- **Release-safe indexing.** Context-aware embedding generations and recovery
+  prevent stale metadata work from becoming active.
+
+This OSS release adds no host RBAC, billing, invitations, or product UI. The
+0.6.x reliability work — workspace-safe reindex, HTTPS sessions, trash-aware
+retrieval, explicit GraphRAG providers, MCP Registry identity, and the
+installable PWA — ships in this line. See the [changelog](CHANGELOG.md) for
+the complete history and the [roadmap](docs/ROADMAP.md) for what comes next.
 
 ## Fastest installation: give this prompt to your agent
 
@@ -175,6 +103,20 @@ On its first run, the script creates an ignored root `.env`, generates the
 database, authentication, and storage secrets, builds the PostgreSQL image,
 applies migrations, and starts the complete application.
 
+Published application images are on
+[Docker Hub](https://hub.docker.com/r/vgalibov/docsmint). There is no untagged
+`latest` image; pull the role-specific tags:
+
+```bash
+docker pull vgalibov/docsmint:api-latest
+docker pull vgalibov/docsmint:web-latest
+docker pull vgalibov/docsmint:caddy-latest
+```
+
+Use versioned tags such as `api-v0.7.1` for reproducible deploys. The
+quickstart still builds the Compose stack from this repository so PostgreSQL,
+Redis, and SeaweedFS start together with the application.
+
 For OpenRouter, add one value to `.env` and run the script again:
 
 ```dotenv
@@ -223,6 +165,9 @@ The canonical local ports are:
 See [Deployment](docs/DEPLOYMENT.md) for domains, TLS, provider tuning,
 backups, and production operation.
 
+Embedding provider URLs, models, and credentials are deployment configuration.
+They are never stored in browser settings or local storage.
+
 ## Use DocsMint from the terminal
 
 The published package includes the CLI. It connects to an already running
@@ -241,7 +186,7 @@ bunx --package @hiai-gg/docsmint docsmint search "project architecture"
 bunx --package @hiai-gg/docsmint docsmint list
 bunx --package @hiai-gg/docsmint docsmint read <document-id>
 bunx --package @hiai-gg/docsmint docsmint create \
-  --title "Release notes" --content "# Version 0.2.9"
+  --title "Release notes" --content "# Highlights"
 ```
 
 Credentials can also be supplied through `HIAI_DOCS_URL` and
@@ -259,8 +204,8 @@ context resources, and a document-manager skill for agent clients.
 {
   "mcpServers": {
     "docsmint": {
-      "command": "bunx",
-      "args": ["--package", "@hiai-gg/docsmint", "docsmint-mcp"],
+      "command": "npx",
+      "args": ["-y", "@hiai-gg/docsmint", "docsmint-mcp"],
       "env": {
         "HIAI_DOCS_URL": "http://localhost:50700",
         "HIAI_DOCS_API_KEY": "your-global-or-category-key"
@@ -273,14 +218,59 @@ context resources, and a document-manager skill for agent clients.
 Run the server directly to verify the installation:
 
 ```bash
-bunx --package @hiai-gg/docsmint docsmint-mcp
+npx -y @hiai-gg/docsmint docsmint-mcp
 ```
 
+`npx` is the install path LobeHub and Node MCP clients validate. Bun checkouts can use
+`bunx --package @hiai-gg/docsmint docsmint-mcp` instead. The process speaks MCP on
+stdio and advertises tools, prompts, and resources without a running DocsMint API.
+
 The server uses stdio and works with MCP-capable clients such as Claude
 Desktop, Cursor, and coding agents that accept standard MCP configuration. See
 the [MCP guide](packages/mcp-server/README.md) for its 17 tools, prompts,
 resources, skill, and API routes.
 
+## MCP Features
+
+### Tools (17)
+
+- `search_documents`: Hybrid search (full-text + semantic pgvector).
+- `get_document`: Fetch document content and metadata.
+- `create_document`: Create a document with optional markdown, folder, and category.
+- `update_document`: Update title, content, folder, or category (new version on each save).
+- `list_documents`: Paginated document list, optionally filtered by folder or tag.
+- `list_folders`: List folders, optionally under a parent.
+- `create_folder`: Create a folder, optionally nested.
+- `create_snapshot`: Create a named snapshot of the current document.
+- `get_version_history`: List versions, optionally snapshots only.
+- `export_document`: Export a document as Markdown.
+- `list_categories`: List categories visible to the API key.
+- `create_category`: Create a category (workspace key with write access).
+- `list_tags`: List tags in the workspace or bound category.
+- `get_related_documents`: Traverse the knowledge graph from one authorized document.
+- `search_knowledge_graph`: Search connected knowledge from authorized seed documents.
+- `get_document_index_status`: Read indexing and knowledge-pipeline status.
+- `refresh_document_index`: Request reindexing after a document or metadata change.
+
+### Prompts (2)
+
+- `organize_workspace`: Plan safe document organization using DocsMint categories and folders.
+- `research_workspace`: Research a question with hybrid search and GraphRAG citing document IDs.
+
+### Resources (3)
+
+- `docsmint://guide/editor`: Editor usage guide.
+- `docsmint://guide/search`: Search and GraphRAG guide.
+- `docsmint://workspace/catalog`: Live scoped workspace catalog.
+
+### Skills (1)
+
+- [`docsmint-document-manager`](skills/docsmint-document-manager/SKILL.md):
+  create, organize, edit, and research DocsMint documents through the 17 MCP
+  tools, including hybrid search, GraphRAG, and index refresh.
+
+The same Skill ships in the npm package under `skills/docsmint-document-manager/SKILL.md`.
+
 ## Agent skills after installation
 
 The MCP tools are the recommended portable agent skills. A category-bound agent
@@ -410,6 +400,7 @@ deployment.
 
 - [Documentation index](docs/README.md)
 - [Product usage](docs/USAGE.md)
+- [Roadmap](docs/ROADMAP.md)
 - [REST API](docs/API.md) and [OpenAPI JSON](docs/openapi.json)
 - [Architecture](docs/ARCHITECTURE.md)
 - [Deployment and operations](docs/DEPLOYMENT.md)

package/backend/src/lib/api-keys.ts

@@ -5,6 +5,7 @@ import {
 	ZERO_UUID,
 } from "@hiai-docs/db/with-tenant";
 import { and, desc, eq } from "drizzle-orm";
+import { isAccountPurgeFencedError } from "./account-purge-fence";
 import { decryptApiKey, encryptApiKey } from "./api-key-encryption";
 
 const API_KEY_ADMIN_TENANT = adminTenantContext(ZERO_UUID);
@@ -228,12 +229,19 @@ export async function validateApiKey(key: string): Promise<{
 	if (!scopes) return null;
 
 	// Update last_used_at
-	await withTenant(API_KEY_ADMIN_TENANT, (tx) =>
-		tx
-			.update(apiKeys)
-			.set({ lastUsedAt: new Date() })
-			.where(eq(apiKeys.id, row.id)),
-	);
+	try {
+		await withTenant(API_KEY_ADMIN_TENANT, (tx) =>
+			tx
+				.update(apiKeys)
+				.set({ lastUsedAt: new Date() })
+				.where(eq(apiKeys.id, row.id)),
+		);
+	} catch (error) {
+		// Preserve the authenticated principal so guarded routes return the
+		// stable public fence error. The key row itself remains frozen until
+		// lifecycle cleanup deletes it.
+		if (!isAccountPurgeFencedError(error)) throw error;
+	}
 
 	return {
 		id: row.id,