@hiai-gg/docsmint 0.8.2 → 0.8.4

package/README.md

@@ -1,14 +1,14 @@
 # DocsMint
 
-**A self-hosted AI-native knowledge workspace and installable PWA for people,
-applications, and AI agents.**
+**Turn your documents into knowledge you and your AI agents can use.**
 
-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,
-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.
+Write and organize notes, guides, and project documentation in one workspace.
+Find answers with search that understands related concepts, then give your
+agents access to the same documents through MCP, REST, the SDK, or CLI.
+
+**[Connect DocsMint Cloud](https://docsmint.com/mcp/connect?source=github_mcp)** to get started without
+operating the stack, or **[self-host with Docker](#quickstart)** to run the
+Apache-2.0 application on your own infrastructure.
 
 [![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)
@@ -16,7 +16,7 @@ TypeScript SDK, CLI, and MCP server.
 [![Docker Pulls](https://img.shields.io/docker/pulls/vgalibov/docsmint?logo=docker)](https://hub.docker.com/r/vgalibov/docsmint)
 [![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)
+[![Bun](https://img.shields.io/badge/Runtime-Bun_1.4-black?logo=bun&logoColor=white)](https://bun.sh)
 [![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)
@@ -32,40 +32,76 @@ TypeScript SDK, CLI, and MCP server.
 
 <img width="1920" height="974" alt="DocsMint installable document workspace" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />
 
+## Connect your AI agent
+
+Connect DocsMint Cloud instantly or use your own self-hosted deployment. Search,
+read, create, organize and update persistent knowledge through MCP with hybrid
+retrieval, reranking and GraphRAG.
+
+**Recommended: [DocsMint Cloud setup](https://docsmint.com/mcp/connect?source=github_mcp).**
+No server installation is required. Sign up or log in, choose your workspace,
+create an MCP/API credential in the authenticated browser UI, follow your client's
+instructions, and verify the connection. Hosted MCP follows your plan and
+workspace permissions. Prefer workspace-bound or category-scoped credentials.
+
+The Cloud endpoint is `https://docsmint.com/mcp` (Streamable HTTP). OAuth-capable
+clients discover authorization and open DocsMint login and consent in the browser.
+Choose your workspace and explicit scopes; the authorization code uses PKCE S256.
+Access tokens expire after one hour; reconnect through browser authorization when
+they expire (no refresh tokens). API-key clients
+send `Authorization: Bearer <key>`. Credentials cannot create or elevate other
+credentials; lifecycle management belongs to the signed-in browser session.
+
+**Self-hosted alternative:** run [DocsMint with Docker](#quickstart), create an API
+key in its browser UI, and configure `HIAI_DOCS_URL` and `HIAI_DOCS_API_KEY` for
+`npx --yes --package @hiai-gg/docsmint docsmint-mcp`. The npm package is a stdio
+bridge to your running deployment, not a server installer. See the
+[MCP guide](packages/mcp-server/README.md) for client configuration.
+
 ## Why DocsMint?
 
-- **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, 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.
-- **Control access** with global keys or category-scoped `read`, `edit`, and
-  `write` permissions.
-- **Own the full stack**: application data, vectors, graph, queue, and files run
-  on infrastructure you control.
-
-## What's new in 0.8.2?
-
-- **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.
+- **Keep knowledge easy to edit.** Use a rich visual editor or Markdown;
+  organize documents with folders, categories, and tags.
+- **Find the document you mean.** Search combines keywords, meaning, typo
+  tolerance, and graph relationships across languages.
+- **Keep agents close to the source.** Let your tools search, read, and update
+  the same knowledge through MCP, REST, a typed SDK, and CLI.
+- **Choose what an integration can access.** Category keys grant explicit
+  `read`, `edit`, and `write` permissions for a defined part of your library.
+- **Keep retrieval up to date.** Document edits and metadata changes refresh
+  the search index automatically in the background.
+- **Choose how you run it.** Use [managed DocsMint](https://docsmint.com) or
+  self-host the application, database, search, queues, and files.
+
+## What's new in 0.8.4?
+
+MCP discovery now explains both supported deployment choices:
+
+- DocsMint Cloud is the recommended route for connecting without running a server.
+- Self-hosted DocsMint remains the complete Apache-2.0 alternative with the same
+  npm/stdio bridge, tools, prompts, resources and public contracts.
+- Registry, LobeHub and npm descriptions include hybrid search, reranking,
+  GraphRAG and scoped document access, with source-aware onboarding links.
+- The MCP guide explains Cloud browser authorization for OAuth-capable clients,
+  existing API-key configuration and the separate self-hosted setup.
+- Release checks now verify built public exports and MCP binaries before packaging.
+- Authorization regression coverage includes mixed category scopes, external tenant
+  assertions, scoped attachment deletion, workspace tags and partial category updates.
+- A deterministic offline retrieval baseline makes evaluation repeatable without
+  claiming a change to live retrieval quality.
+
+No database migration, tool redesign or SDK contract change is added. Hosted
+OAuth is a DocsMint Cloud capability; this OSS release documents how to connect
+and does not embed Cloud accounts, billing or analytics in self-hosted installs.
 
 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
+## Install with an AI agent
 
-If you are installing DocsMint through an AI coding agent, use this path first.
-It keeps the setup to Docker plus one provider choice and avoids unnecessary
-source-code changes.
+Prefer an assisted self-hosted setup? Give your coding agent this prompt.
+You will need Docker and a choice of AI provider.
 
 ```text
 Install DocsMint from https://github.com/HiAi-gg/docsmint.
@@ -112,8 +148,8 @@ docker pull vgalibov/docsmint:web-latest
 docker pull vgalibov/docsmint:caddy-latest
 ```
 
-Use versioned tags such as `api-v0.8.1` for reproducible deploys. The
-quickstart still builds the Compose stack from this repository so PostgreSQL,
+Use versioned tags `api-v0.8.4`, `web-v0.8.4`, and `caddy-v0.8.4` 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:
@@ -173,7 +209,7 @@ The published package includes the CLI. It connects to an already running
 DocsMint server; installing it does not deploy the server.
 
 ```bash
-npm install @hiai-gg/docsmint
+bun add @hiai-gg/docsmint
 ```
 
 ```bash
@@ -218,7 +254,7 @@ Run the published stdio bridge against your own DocsMint API:
   "mcpServers": {
     "docsmint": {
       "command": "npx",
-      "args": ["-y", "@hiai-gg/docsmint", "docsmint-mcp"],
+      "args": ["--yes", "--package", "@hiai-gg/docsmint", "docsmint-mcp"],
       "env": {
         "HIAI_DOCS_URL": "http://localhost:50700",
         "HIAI_DOCS_API_KEY": "your-global-or-category-key"
@@ -256,7 +292,8 @@ const results = await docs.search('what did we decide?');
 console.log(created.id, results.items);
 ```
 
-The SDK is a typed `fetch` client with retries for transient failures. See the
+The SDK is a typed `fetch` client with retries for transient failures and
+idempotent document creation retries. See the
 [SDK reference](packages/sdk/README.md) and [REST API](docs/API.md).
 
 ## API keys and integrations
@@ -283,6 +320,10 @@ affected by browser CORS. Browser integrations must add their exact origin to
 
 ## What is included?
 
+Documents use structured TipTap JSON as canonical content. Markdown is the
+source-editing, import, and export format. The same document store serves the
+web application and public integration interfaces.
+
 ```text
 frontend/          SvelteKit workspace and TipTap editor
 backend/           Elysia REST API, search, workers, and authentication
@@ -328,7 +369,7 @@ For pipeline internals and tuning, see [Architecture](docs/ARCHITECTURE.md) and
 
 ## Stack
 
-- Bun, TypeScript, Elysia, Zod, and Pino
+- Bun 1.4.0+, TypeScript, Elysia, Zod, and Pino
 - Svelte 5, SvelteKit, Tailwind CSS, and TipTap
 - Better Auth and Drizzle ORM
 - PostgreSQL 18, pgvector, pgvectorscale, and Apache AGE
@@ -336,23 +377,6 @@ For pipeline internals and tuning, see [Architecture](docs/ARCHITECTURE.md) and
 - SeaweedFS with its S3-compatible API
 - OpenAI-compatible providers through OpenRouter or local Ollama
 
-## Comparison
-
-DocsMint overlaps with several excellent open-source knowledge tools, but its
-focus is a compact knowledge runtime shared equally by humans and agents.
-
-| Project                                                      | Primary strength                             | Difference from DocsMint                                                               |
-| ------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------- |
-| [Outline](https://github.com/outline/outline)                | Polished team wiki and collaboration         | DocsMint emphasizes built-in retrieval, GraphRAG, scoped agent access, CLI, and MCP    |
-| [Docmost](https://github.com/docmost/docmost)                | Collaborative wiki and real-time editing     | DocsMint centers automatic embeddings and agent-facing integration surfaces            |
-| [AppFlowy](https://github.com/AppFlowy-IO/AppFlowy)          | Broad local-first productivity workspace     | DocsMint is narrower: a self-hosted document and retrieval service                     |
-| [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) | Chat-oriented RAG over imported sources      | DocsMint starts with the editable knowledge base and exposes it to many clients        |
-| [Danswer](https://github.com/danswer-ai/danswer) / Onyx      | Enterprise search across external connectors | DocsMint owns and edits its native corpus rather than primarily indexing other systems |
-
-This is a product-positioning summary, not a claim that every listed project
-lacks a feature. Check each project's current documentation when choosing a
-deployment.
-
 ## Documentation
 
 - [Documentation index](docs/README.md)
@@ -368,6 +392,8 @@ deployment.
 
 ## Development
 
+Use Bun 1.4.0 or later for local development.
+
 ```bash
 bun install
 bun run lint