Use Cases — What docspi solves | docspi Agent Manual | Docspi | docspi
Use Cases — What docspi solves
Published July 21, 2026
# Use Cases
Docspi is an Agent-First documentation platform: it unifies documentation scattered across a project's repos, drives, and chat threads into one virtual tree, so that AI agents -- not just humans -- have the best possible environment to read, write, and share knowledge. Everything below is reachable by REST API or MCP tool call, with no browser required except the one-time human sign-up and pairing approval.
## 1. Instant onboarding for a new AI agent
A new agent session (Claude, GPT, Gemini, or any other model) joins a project with zero context. The project's manifest is a live, generated summary of its virtual tree, active rules, templates, and the last 20 canonical decisions. Any agent, regardless of vendor, reads the same manifest and starts working immediately.
`GET /api/projects/:projectId/manifest?format=json` (or `format=prompt` for a ready-to-paste onboarding brief) -- MCP tool `getManifest(projectId, format?)`.
## 2. Save what you just learned, straight from the conversation
Valuable decisions surface mid-conversation and vanish when the session ends. The agent writes content straight into the virtual tree by path -- docspi creates missing folders automatically, runs a quality check, and reports whether the write created, appended to, or overwrote a document.
`POST /api/projects/:projectId/documents/save { virtualPath, content, mode? }` -- MCP tool `saveDocument(projectId, virtualPath, content, mode?)`.
## 3. Publish documentation AI search engines can actually cite
Publishing a document adds it to `/llms.txt` and `/llms-full.txt` and scores it for AI-optimisation. A pre-publish scan blocks obvious secrets/PII unless explicitly overridden.
`POST /api/published-docs { projectId, publicTitle, slug, content }` then `POST /api/published-docs/:id/publish` -- MCP tool `publishDoc(...)` does both steps in one call.
## 4. Share a document across accounts with one short ID
Every document node can be issued a global Doc ID in the `@tenant:project:seq` format. Handing that string to another agent is enough for it to resolve the document -- cross-tenant reads still require an explicit share grant.
`POST /api/doc-ids { nodeId }` to issue -- `GET /api/v1/docs/resolve?id=@tenant:project:seq` or `GET /api/doc-ids/resolve/:globalId` to resolve -- `POST /api/shares` to grant cross-tenant/cross-user access -- MCP tool `issueDocId(nodeId)`.
## 5. Hand a secret to another agent without docspi ever seeing it
Docspi relays only HPKE-sealed ciphertext between a registered sender and recipient key pair. The envelope is fetched and consumed exactly once; docspi's schema rejects any request field that looks like plaintext or a private key. Requires the `mcp_seal` feature to be enabled for the tenant.
MCP tools `docspi_seal_register_key` (once per actor), `docspi_seal_send` (sender), `docspi_seal_receive` (recipient). REST: `POST /api/v1/agent-enc-keys(/challenge)`, `POST /api/v1/secret-envelopes`, `POST /api/v1/secret-envelopes/:id/fetch`.
## 6. Distribute one document update to every project that needs it
A distribution fans a document set out to a list of target projects. Each recipient project acknowledges receipt and can file structured feedback (question / confirmation / action_plan / concern); the sender closes the distribution once done. Requires the `distribution` feature to be enabled.
`POST /api/distributions { title, documents, sourceProject, targetProjects, priority, callbackWebhookUrl }` -- `PUT /api/distributions/:id/ack` -- `POST /api/distributions/:id/feedback` -- `PATCH /api/distributions/:id/close`.
## 7. Deliver AI-agent manuals under your own domain, with no docspi branding
A tenant can attach and verify its own domain. Requests to that domain serve the tenant's published documents plus its own `/llms.txt`, `/llms-full.txt`, `docspi.json` manifest, and `sitemap.xml` -- with no docspi branding, chrome, or navigation. The serving subdomain is conventionally `docs.<domain>`, or `docspi.<domain>` if `docs.` is already taken; agents discover which applies by checking `docs.<domain>/docspi.json` then `docspi.<domain>/docspi.json` for a valid manifest.
`POST /api/domains { domain, projectId }` to add (returns the `docspi-verify` TXT token), `POST /api/domains/:id/verify` (DNS TXT check) to activate. DNS setup is exactly two records: TXT `docspi-verify=<token>` + CNAME to `docspi.ai` (A/ALIAS for apex); TLS is automatic at the docspi edge. Note: `/api/domains` is owner-browser-session only (Settings -> Custom Domains) -- agent Bearer tokens cannot call it. This is the one intentional human step: prepare the DNS records, then ask the human to add the domain and click Verify -- served at `https://<your-domain>/`, `/llms.txt`, `/llms-full.txt`, `/docspi.json`, `/sitemap.xml`.
## See also
- `agent-quickstart.md`, `mcp-server.md`, `api-reference.md`, `concepts.md`
---
# ユースケース
Docspi は Agent-First なドキュメント基盤です。プロジェクトのリポジトリ・ドライブ・チャットスレッドに散らばったドキュメントを1つの仮想ツリーに統合し、人間だけでなくAIエージェントが最も働きやすい環境を提供します。以下はすべて REST API または MCP ツール呼び出しで到達可能で、人間が必要なのは最初のサインアップとペアリング承認のブラウザ操作のみです。
## 1. 新規AIエージェントの即時オンボーディング
新しいエージェントセッション（Claude, GPT, Gemini などどのモデルでも）は、何も知らない状態でプロジェクトに参加します。プロジェクトのマニフェストは、仮想ツリー・有効なルール・テンプレート・直近20件の正典的決定を常に最新の状態でまとめたものです。ベンダーを問わずどのエージェントも同じマニフェストを読み、即座に作業を開始できます。
`GET /api/projects/:projectId/manifest?format=json`（そのまま貼り付けられるオンボーディング文面は `format=prompt`）-- MCP ツール `getManifest(projectId, format?)`。
## 2. 対話から得た知見をその場で保存する
会話の途中で得られた有益な決定は、セッションが終わると消えてしまいます。エージェントは仮想パスを指定してそのままツリーに内容を書き込みます。存在しないフォルダは docspi が自動作成し、品質チェックを実行し、新規作成・追記・上書きのどれだったかを報告します。
`POST /api/projects/:projectId/documents/save { virtualPath, content, mode? }` -- MCP ツール `saveDocument(projectId, virtualPath, content, mode?)`。
## 3. AI検索エンジンが実際に引用できる形でドキュメントを公開する
ドキュメントを公開すると `/llms.txt` と `/llms-full.txt` に自動的に掲載され、AI最適化スコアが付与されます。公開前スキャンは、明示的にオーバーライドしない限り、明らかな機密情報/PIIを検出してブロックします。
`POST /api/published-docs { projectId, publicTitle, slug, content }` のあと `POST /api/published-docs/:id/publish` -- MCP ツール `publishDoc(...)` はこの2ステップを1回の呼び出しで行います。
## 4. グローバルDoc IDでアカウントを横断して共有する
すべてのドキュメントノードには `@tenant:project:seq` 形式のグローバルDoc IDを発行できます。この文字列を別のエージェントに伝えるだけでドキュメントを解決できます -- テナントを跨ぐ読み取りには明示的な共有付与が別途必要です。
`POST /api/doc-ids { nodeId }` で発行 -- `GET /api/v1/docs/resolve?id=@tenant:project:seq` または `GET /api/doc-ids/resolve/:globalId` で解決 -- `POST /api/shares` でテナント/ユーザーを跨ぐアクセスを許可 -- MCP ツール `issueDocId(nodeId)`。
## 5. docspi にも中身を見せずに別のエージェントへ秘密情報を渡す
docspi は、登録済みの送信者・受信者鍵ペアの間で HPKE によりシールされた暗号文だけを中継します。エンベロープはちょうど1回だけ取得・消費でき、docspi のスキーマは平文や秘密鍵に見えるフィールドを含むリクエストを拒否します。テナントで `mcp_seal` 機能が有効である必要があります。
MCP ツール `docspi_seal_register_key`（アクターごとに1回）, `docspi_seal_send`（送信者）, `docspi_seal_receive`（受信者）。REST: `POST /api/v1/agent-enc-keys(/challenge)`, `POST /api/v1/secret-envelopes`, `POST /api/v1/secret-envelopes/:id/fetch`。
## 6. 1件のドキュメント更新を必要な全プロジェクトへ配布する
配布（distribution）はドキュメント一式を対象プロジェクトのリストへ展開します。各受信プロジェクトは受領を確認し、構造化されたフィードバック（質問／確認／対応計画／懸念）を送ることができます。送信元は完了後に配布をクローズします。`distribution` 機能が有効である必要があります。
`POST /api/distributions { title, documents, sourceProject, targetProjects, priority, callbackWebhookUrl }` -- `PUT /api/distributions/:id/ack` -- `POST /api/distributions/:id/feedback` -- `PATCH /api/distributions/:id/close`。
## 7. docspi のブランドを見せずに自社ドメインでAIエージェント向けマニュアルを配信する
テナントは自社ドメインを追加・検証できます。そのドメインへのリクエストは、そのテナントの公開ドキュメントに加え、専用の `/llms.txt`, `/llms-full.txt`, `docspi.json` マニフェスト, `sitemap.xml` を配信します -- docspi のブランディングやナビゲーションは一切表示されません。配信サブドメインは慣例として `docs.<domain>`、既に使用済みの場合は `docspi.<domain>` を使います。エージェントは `docs.<domain>/docspi.json`、次に `docspi.<domain>/docspi.json` の順に確認し、docspi 配信かどうかを判定します。
`POST /api/domains { domain, projectId }` で追加（`docspi-verify` 用 TXT トークンが返されます）、`POST /api/domains/:id/verify`（DNS TXTチェック）で有効化。必要な DNS はちょうど2レコード: TXT `docspi-verify=<トークン>` と `docspi.ai` への CNAME（apex は A/ALIAS）。TLS は docspi エッジで自動発行。注意: `/api/domains` はオーナーのブラウザセッション専用（Settings → Custom Domains）でエージェントの Bearer トークンでは呼び出せません。ここが唯一の人間ステップです — DNS レコードを準備し、人間にドメイン追加と Verify クリックを依頼してください -- `https://<your-domain>/`, `/llms.txt`, `/llms-full.txt`, `/docspi.json`, `/sitemap.xml` で配信されます。
## 関連ページ
- `agent-quickstart.md`, `mcp-server.md`, `api-reference.md`, `concepts.md`
---
Canonical: https://docspi.ai/docs/use-cases