@hiai-gg/docsmint 0.8.1 → 0.8.3

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.
+
+**[Try managed DocsMint](https://docsmint.com)** 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)
@@ -34,106 +34,47 @@ TypeScript SDK, CLI, and MCP server.
 
 ## 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.1?
-
-- **GraphRAG expansion is connection-safe.** AGE reads pin `ag_catalog` on the
-  same pooled connection as `cypher()`, so scoped search keeps graph neighbors
-  even when the connection did not already have AGE first in `search_path`.
-
-## What's new in 0.7.9?
-
-- **GraphRAG on category/share search keeps inherited-folder neighbors.** The
-  allowed document list is the ACL; category is not applied a second time.
-
-## What's new in 0.7.8?
-
-- **GraphRAG still contributes after rerank.** Neighbors already in the fused
-  prefix keep the graph channel, so scoped search does not lose graph evidence.
-- **Public API identity is DocsMint.** Health reports `service: "docsmint"`;
-  startup and SDK errors no longer say `hiai-docs`.
-
-## What's new in 0.7.7?
-
-- **Cross-encoder rerank is on by default.** After RRF, search reranks the
-  original query against the fused prefix with Voyage `rerank-2.5` (Cohere
-  and NVIDIA fallbacks). Provider failures keep RRF order. Set
-  `SEARCH_RERANK_ENABLED=false` to turn it off.
-- **Live retrieval improved first-hit ranking.** On a 24-document labeled
-  corpus, RRF+rerank moved MRR 0.969 → 1.000 and nDCG@10 0.958 → 0.986.
-  Recall@10 stayed 1.0. The paraphrase query “operator API key header”
-  moved the API-key document from rank 2 to rank 1 (MRR 0.50 → 1.00).
-- **Three-model fallbacks** for embeddings, extraction, expansion, and
-  rerank so a single provider outage does not drop the channel.
-
-## What's new in 0.7.6?
-
-- **Better Auth 1.6 rollback remains possible** after the issuer migration by
-  deriving the legacy account issuer in a database trigger.
-
-## What's new in 0.7.5?
-
-- **Runtime and dependency graph** to Bun 1.4, TypeScript 6, Better Auth 1.7,
-  and current compatible editor/queue packages, with fail-closed issuer
-  identity.
-
-## What's new in 0.7.4?
-
-- **MCP Registry description fits the 100-character limit**, so official
-  catalog publication can complete after 0.7.3 reached npm.
-
-## 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.
-
-## Fastest installation: give this prompt to your 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.
+- **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.3?
+
+This maintenance release focuses on reliable saves and integrations:
+
+- Pending editor saves stay attached to the document being edited, even when
+  you switch documents.
+- Navigation waits for pending content saves; overlapping saves are serialized
+  so an older request cannot overwrite a newer edit.
+- SDK document creation retries reuse an idempotency key to prevent duplicates
+  after a lost response.
+- Workspace-wide tag management requires full write access; read-only and
+  category-scoped credentials can no longer mutate the entire tag collection.
+- Partial category API-setting updates preserve omitted permissions.
+- Public workspace share links retain their workspace context when loading
+  folders and documents.
+
+No schema migration is added. Existing public request and response shapes
+remain supported; the tag authorization fix intentionally rejects operations
+that exceeded the caller's permissions.
+
+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.
+
+## Install with an AI agent
+
+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.
@@ -180,8 +121,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.3`, `web-v0.8.3`, and `caddy-v0.8.3` 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:
@@ -241,7 +182,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
@@ -262,10 +203,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
 {
@@ -282,70 +237,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, GraphRAG, and rerank citing document IDs.
-
-### Resources (3)
-
-- `docsmint://guide/editor`: Editor usage guide.
-- `docsmint://guide/search`: Search, GraphRAG, and rerank 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, rerank, 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
 
@@ -370,7 +265,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
@@ -397,6 +293,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
@@ -442,7 +342,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
@@ -450,23 +350,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)
@@ -482,6 +365,8 @@ deployment.
 
 ## Development
 
+Use Bun 1.4.0 or later for local development.
+
 ```bash
 bun install
 bun run lint