@hiai-gg/docsmint 0.7.6 → 0.8.2

package/README.md

@@ -6,9 +6,9 @@ applications, and AI agents.**
 DocsMint stores documents in a structured JSON editor model first. Markdown is
 the convenient second format for editing, importing, and exporting content.
 Automatic chunking, 1024-dimensional embeddings, multilingual hybrid search,
-and GraphRAG make the same knowledge base useful to people, applications, and
-agents through the web application, REST API, TypeScript SDK, CLI, and MCP
-server.
+GraphRAG, and cross-encoder rerank make the same knowledge base useful to
+people, applications, and agents through the web application, REST API,
+TypeScript SDK, CLI, and MCP server.
 
 [![Apache-2.0 License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/hiai-gg/docsmint?sort=semver)](https://github.com/hiai-gg/docsmint/releases)
@@ -36,7 +36,8 @@ server.
 
 - **Write naturally** in a rich visual editor or raw Markdown.
 - **Find meaning, not only keywords** with exact, lexical, fuzzy, vector,
-  multilingual expansion, and graph retrieval fused through RRF.
+  multilingual expansion, and graph retrieval fused through RRF, then
+  reranked with a cross-encoder (Voyage rerank-2.5 in the reference profile).
 - **Keep retrieval current** with automatic, incremental chunking and
   re-embedding after document or metadata changes.
 - **Connect agents directly** through REST, a typed SDK, CLI, or MCP.
@@ -45,46 +46,20 @@ server.
 - **Own the full stack**: application data, vectors, graph, queue, and files run
   on infrastructure you control.
 
-## What's new in 0.7.6?
+## What's new in 0.8.2?
 
-- **MCP Registry description fits the 100-character limit**, so official
-  catalog publication can complete after 0.7.3 reached npm.
+- **Correct rerank identity.** Empty candidates can no longer shift provider
+  scores onto the wrong document ID; partial and invalid provider responses
+  still preserve stable RRF fallback order.
+- **Recover optional AI stages safely.** Pipeline status includes typed graph
+  and summary warnings, and the API or SDK can retry only failed enrichment on
+  the current embedding generation without rebuilding ready chunks.
+- **Reliable public frontend imports.** The standalone frontend consumes only
+  published `hiai-ui` exports, with no source or distribution aliases.
 
-## What's new in 0.7.3?
-
-- **One public-link share dialog in OSS.** Dashboard, sidebar (including Recent),
-  and the editor open the same public token share. Hosts can opt into restricted
-  admission from `DocsmintAppShellHost`.
-- **Dialogs stay in their overlays** after hiai-ui 0.1, and nested routes load
-  CSS from `/_app` instead of `./_app`.
-- **hiai-ui 0.1.3** for circular theme spread; Inter remains the product UI
-  typeface.
-
-## What's new in 0.7.2?
-
-- **Share view matches the editor.** Twitter/Twemoji SVG emoji images no longer
-  expand across the public share column; they render as ordinary glyphs.
-- **Inter in the workspace chrome.** The sidebar uses the same Inter UI typeface
-  as docsmint.com instead of the operating-system sans stack.
-- **MCP catalog 0.7.2.** Registry, LobeHub, and runtime metadata ship the dark
-  catalog logo and the current product-aligned description.
-
-## 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.
+Read the complete release history in the [changelog](CHANGELOG.md) or
+[GitHub Releases](https://github.com/HiAi-gg/docsmint/releases). See the
+[roadmap](docs/ROADMAP.md) for what comes next.
 
 ## Fastest installation: give this prompt to your agent
 
@@ -137,7 +112,7 @@ docker pull vgalibov/docsmint:web-latest
 docker pull vgalibov/docsmint:caddy-latest
 ```
 
-Use versioned tags such as `api-v0.7.6` for reproducible deploys. The
+Use versioned tags such as `api-v0.8.1` for reproducible deploys. The
 quickstart still builds the Compose stack from this repository so PostgreSQL,
 Redis, and SeaweedFS start together with the application.
 
@@ -219,10 +194,24 @@ command and configuration precedence.
 
 ## Connect an MCP client
 
-DocsMint exposes document search, reading, creation, updates, categories,
-folders, tags, GraphRAG traversal, index status and refresh, snapshots,
-history, and export as MCP tools. It also publishes reusable prompts,
-context resources, and a document-manager skill for agent clients.
+Give agents a secure path to search, read, and maintain your knowledge without
+database or filesystem access. DocsMint publishes 17 tools plus ready-made
+research prompts, scoped resources, and a document-manager skill.
+
+### Hosted DocsMint
+
+Connect directly to the managed Streamable HTTP endpoint. Keep the API key in
+an environment variable rather than writing it into client configuration:
+
+```bash
+codex mcp add docsmint \
+  --url https://docsmint.com/mcp \
+  --bearer-token-env-var HIAI_DOCS_API_KEY
+```
+
+### Self-hosted DocsMint
+
+Run the published stdio bridge against your own DocsMint API:
 
 ```json
 {
@@ -239,70 +228,10 @@ context resources, and a document-manager skill for agent clients.
 }
 ```
 
-Run the server directly to verify the installation:
-
-```bash
-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
-can receive only the knowledge and operations it needs; a trusted personal
-agent can use a global key. Agents do not need database or filesystem access.
-After startup, create an API key in **Settings → API** and add the MCP block
-above to the agent client. For custom agent workflows, use the same key through
-the CLI, SDK, or REST API.
+Category keys let you expose only the documents and operations an agent needs.
+Use a global key only for trusted owner-wide automation. See the
+[complete MCP reference](packages/mcp-server/README.md) for Bun, npm, local
+checkout, all tools, prompts, resources, permissions, and REST mappings.
 
 ## TypeScript SDK
 
@@ -382,8 +311,12 @@ previous valid generation remains searchable if a provider call fails.
 Search combines exact title matches, multilingual lexical search, typo-tolerant
 fuzzy matching, semantic vectors, adaptive query expansion, and Apache AGE
 graph neighbors. Reciprocal rank fusion combines the channels without allowing
-one weak provider result to dominate. Authorization is applied before retrieval
-and again before results are returned.
+one weak provider result to dominate. A cross-encoder then reranks the fused
+prefix against the original query (Voyage rerank-2.5 by default). On a labeled
+24-document corpus that moved MRR 0.969 → 1.000 and nDCG@10 0.958 → 0.986
+versus RRF-only. Rerank, expansion, embeddings, and AGE failures keep the
+remaining channels. Authorization is applied before retrieval and again before
+results are returned.
 
 GraphRAG is part of the normal search path in the reference configuration. It
 extracts entities after embeddings are ready and finds related documents beyond