nyuchi-docs

Nyuchi Docs

Nyuchi のエンジニアリングドキュメント — Nyuchi での開発の進め方と、 Nyuchi のプロジェクトから Mzizi ツールを使う方法をまとめています。

公開サイト： docs.nyuchi.com | 製品ドキュメント： docs.bundu.org | MCP： docs.nyuchi.com/mcp

---

パッケージ

6 つのパッケージからなる pnpm ワークスペースです。

パッケージ	パス	機能
site	site/	Astro + Starlight のドキュメントサイト本体です。Static Assets を使用する Cloudflare Worker として提供されます。
@nyuchi/nyuchi-docs-search	nyuchi-docs-search/	Starlight サイト向けの cmdk スタイルの検索モーダルと Ask-AI タブです。npm にはまだ公開されていません。
shamwari-docs-ai	shamwari-docs-ai/	Cloudflare Worker — Ask-AI チャットプロキシ（SSE）です。
nyuchi-docs-mcp-worker	nyuchi-docs-mcp-worker/	Cloudflare Worker nyuchi-docs-mcp — docs.nyuchi.com/mcp のドキュメント MCP サーバーです。
@nyuchi/nyuchi-docs-mcp	nyuchi-docs-mcp/	Streamable HTTP に対応していないクライアント向けに、ホストされたエンドポイントへ接続する stdio ブリッジです。
@nyuchi/nyuchi-docs-skills	nyuchi-docs-skills/	docs.nyuchi.com 向けの公開エージェントスキルです。リポジトリの作成用スキルは内部向けであり、意図的に公開していません。

関連サイト

bundu-labs/bundu-docs では、 Bundu Foundation の対外プロジェクト — Mzizi 製品、Ubuntu の教義、 Bundu のブランドシステムを扱っています。内部のみが閲覧できるリポジトリのため、 このリンクにアクセスできるのは組織のメンバーだけです。このサイトは @nyuchi/nyuchi-docs-search を使用し、nyuchi-docs-mcp Worker を参照しています。

@nyuchi/nyuchi-docs-search は npm にありません — registry.npmjs.org で確認すると {"error":"Not found"} が返されます（2026-09-12 に確認）。公開されるまでは、 bundu-docs はレジストリからインストールできません。

セクション（site/src/content/docs/）

• platform/ — Nyuchi プラットフォームの製品ガイドです。
• api/ — API ドキュメントです。/v1 ゲートウェイ、WorkOS 認証、コンソールで管理する API キー、セキュリティ、製品の名前空間を扱います。
• analytics/ — ダッシュボード、レポート、データソースへの接続を扱います。
• kweli/ — Mukoko Kweli の製品ガイドです。検証、アプリ間の使い方ガイド、オープンデータ、データ品質、デザインシステムを扱います。
• mukoko-weather/ — Mukoko Weather のユーザーガイドと観測所です。
• integrations/ — コネクター、ウェブフック、ドキュメント MCP サーバー、Mukoko Events MCP サーバーを扱います。
• identity/ — WorkOS、accounts.mukoko.com（AuthKit の発行者）、SSO、JWT を扱います。
• console/ — platform.nyuchi.com にある Nyuchi Console です。
• tools/ — リポジトリ横断のツールディレクトリです。Nyuchi と Bundu のリポジトリにあるすべてのスキル、CLI、MCP サーバーを扱います。
• mzizi-tools/ — mzizi-mcp、mzizi-cli、mzizi-skills、DNA 二重らせんアーキテクチャ、レジストリの健全性、A2A 設計を扱います。
• deployment/ — Cloudflare、Vercel、Supabase のデプロイパターンを扱います。
• conventions/ — PR の原則、コミットの原則、リポジトリ命名規則を扱います。

開発

pnpm install
pnpm dev            # site only
pnpm -r build       # all packages
pnpm -r test        # all packages

サイトの開発サーバー：http://localhost:4321。コンテンツは site/src/content/docs/ にあり、サイドバーは site/astro.config.mjs で設定されています。

検索と AI への質問

検索モーダルは ⌘K／Ctrl+K で開きます。AI に質問タブでは、 検索結果に基づく引用を含む回答が shamwari-docs-ai（Cloudflare Worker）からストリーミングされます。 ローカルで有効にするには、site/.env.example を site/.env にコピーします。

cp site/.env.example site/.env
# .env:
# PUBLIC_SHAMWARI_AI_URL=https://shamwari-docs-ai.nyuchi.workers.dev

デプロイ

このリポジトリにある両方の Worker は Cloudflare Workers Builds を介してデプロイされます。
Cloudflare GitHub App は nyuchi/nyuchi-docs に接続されており、各 Worker にトリガーが 1 つずつ設定されています（ルートディレクトリは Worker パッケージを指します）。GitHub Actions によるデプロイワークフローはなく、CLOUDFLARE_API_TOKEN リポジトリシークレットもありません。

• nyuchi-docs（サイト） — ルートは site/ です。Workers Static Assets を使う Cloudflare Worker として配信されます。 https://nyuchi-docs.nyuchi.workers.dev で公開されており、切り替えは完了しています。現在、docs.nyuchi.com はこの Worker を配信しています。両方のホストで同じ Astro 7.2.9／Starlight 0.41.10 のページが返されます（2026-09-12 に確認）。現在、ルートドメインの背後で Mintlify を Vercel にデプロイする構成はありません。
• shamwari-docs-ai — ルートは shamwari-docs-ai/ です。Cloudflare AI Search の前段にある薄いプロキシです。 https://shamwari-docs-ai.nyuchi.workers.dev で公開されており、提供するルートは GET /health と POST /chat の 2 つのみです。ルートパスは正しく 404 を返します。 コーパスごとの AI Search インスタンス設定（REST API で管理）については、 shamwari-docs-ai/README.md を参照してください。
• nyuchi-docs-mcp — ルートは nyuchi-docs-mcp-worker/ で、ドキュメント MCP サーバーです。https://nyuchi-docs-mcp.nyuchi.workers.dev で公開され、docs.nyuchi.com/mcp* からルーティングされます。専用の Workers Builds トリガーが必要です（ルートディレクトリは nyuchi-docs-mcp-worker/）。

よく知られたエンドポイントと機械可読エンドポイント

docs.nyuchi.com は、ドキュメントツリーの外で以下を提供します。ほとんどは site/public/ 内の静的ファイルです。security.txt はサイトワーカーによってリクエストごとに生成されます。

パス	配信元	内容
/robots.txt	site/public/robots.txt	クロールポリシーとサイトマップの参照先です。ここにある内容はすべてインデックス登録を想定しています。
/llms.txt	site/public/llms.txt	LLM 向けの機械可読なサイトインデックスです。
/AUTH.md	site/public/AUTH.md	エージェント向けの WorkOS 認証リファレンスです。nyuchi/api-gateway と同期されています。
/.well-known/mcp/server-card.json	site/public/.well-known/mcp/	/mcp にある nyuchi-docs-mcp ワーカーの MCP サーバーカードです。
/.well-known/security.txt	site/src/worker/security-txt.ts	RFC 9116 の開示連絡先です。静的ファイルではなく、リクエストごとに生成されます。

RFC 9116 では Expires が必須で、有効期限が1年未満に制限されているため、 security.txt は動的に生成されます。チェックイン済みのファイルは、時間の経過とともに 知らないうちに準拠しなくなるためです。site/wrangler.toml では run_worker_first = true が設定されているため、すべてのリクエストは すでに site/src/worker/gate.ts を通過します。このパスはゲートのチェックと アセットルーターより先に処理され、リクエスト時刻を基準に Expires（180日後）を 設定して応答します。mukoko-dev/mukoko-events（旧称 nhimbe）および mukoko-dev/kweli と同じ方法です。

pnpm ワークスペースを使う理由

検索パッケージ（nyuchi-docs-search）は、両方のプロジェクトで利用されます。 nyuchi-docs（このリポジトリ。workspace:* 経由）と、bundu-docs（別のリポジトリ。 npm レジストリ経由）です。ドキュメントサイトと同じワークスペースに置くことで、 pnpm dev の実行中に検索 UI のローカル変更がすぐに反映され、公開パッケージも pnpm publish を実行するだけで公開できます。

コマンド

コマンド	説明
pnpm dev	:4321 でドキュメントサイトを起動します。
pnpm build	サイトをビルドします。
pnpm build:all	すべてのワークスペースパッケージをビルドします。
pnpm test	すべてのパッケージのテストを実行します。
pnpm lint	すべてのパッケージのリンターを実行します。
pnpm check	すべてのパッケージの型／コンテンツチェックを実行します。
pnpm skills:validate	提供するエージェントスキルを検証します。
pnpm deploy:worker	shamwari-docs-ai をデプロイします。
pnpm deploy:mcp	nyuchi-docs-mcp-worker をデプロイします。
pnpm ingest	コーパスを Cloudflare AI Search に再取り込みします。

.mdx ファイルに対して prettier --write を実行しないでください。Prettier 3.9.x は {/* … */} を {/_ … _/} に書き換えるため、無効な MDX が生成されます。.md は安全です。

エコシステム

• docs.bundu.org — Bundu Foundation の製品ドキュメント
• mzizi.dev — Mzizi のデザインシステム。Bundu Foundation の オープンアーキテクチャプロジェクトで、Nyuchi が運営および開発しています。
• api.nyuchi.com — これらのドキュメントで説明する /v1 ゲートウェイ

バージョン管理

リリースは組織のバージョン管理ポリシー （nyuchi/.github#80）に従います。 ブランチによって更新区分が決まり、バージョンラベルはありません。

• staging へのマージ（公開中のベータ版）は、staging-version.yml によって次の パッチとして自動的にタグ付けされます。
• main へのリリースは、最も大きいタグより次のマイナーバージョンになります。 リリースする PR で nyuchi-docs-mcp/package.json の version をその値に設定します。 CI はそれ以外のバージョンを拒否し、正しいバージョンを示します。
• メジャーバージョンは手動でのみ作成します。オーナーが Actions タブから bump: major を指定してリリースワークフローを実行します。
• 各セグメントの値は 0～999 です。パッチが 999 に達すると次のマイナーに繰り上がり、 マイナーが 999 に達すると停止し、手動でのメジャー更新を求めます。

2026-10-04 より前にリリースされたバージョンは、番号を変更しません。

ライセンス

このリポジトリは公開されていますが、LICENSE ファイルがないため、リポジトリ全体に ライセンスは付与されていません。すべての権利は留保されています。© Nyuchi Africa (PVT) Ltd. @nyuchi/nyuchi-docs-search パッケージは、独自の package.json で MIT を宣言しています。 パッケージにこのライセンスを適用する意図がある場合は、それを裏付ける LICENSE が リポジトリに必要です。