自動化と AI エージェント#

Ovellum は、ターミナルの前の人間以外のもの — CI ジョブ、デプロイスクリプト、AI エージェント — から操作されることを前提に作られています。すべてのコマンドはパイプ されてもきれいに動作し、主要なコマンドは JSON を話し、終了コードは安定しており、 エージェント向けの組み込み MCP サーバーがあります。全体像 — なぜ あなたのドキュメントが最初から AI 対応なのか — は AI エージェントのための Ovellumを参照してください。

機械可読な出力（--json）#

build、check、diff は --json フラグを受け付けます。JSON 経路では装飾的な出力はありません — stdout はパース可能な 単一の JSON オブジェクトで、成功時には stderr には何も書き込まれません。

ovellum build --json
ovellum check --json
ovellum diff --json

いずれにも --verbose を付けると、設定解決と各ステージ / ファイル I/O の詳細が出ます。 出力先は stderr なので、--json ときれいに併用できます（stdout は純粋な JSON のままです）。

build --json#

{
  "ok": true,
  "command": "build",
  "mode": "hybrid",
  "durationMs": 211,
  "config": "/project/ovellum.config.json",
  "warnings": [
    { "message": "did src/date.ts::a become …::b? …", "severity": "info" }
  ],
  "sources": 2,
  "written": ["docs/format.md", "docs/user.md"],
  "merged": [],
  "orphans": 0,
  "quarantined": [],
  "ir": ".ovellum/ir.json",
  "manifest": null
}

warnings[] の各エントリは { message, severity } です。severity は "warning"（対処すべき実際の問題 — 孤立したコンテンツ、安全のためスキップされた アセット、解析できない日付）または "info"（ビルドが行ったことの良性の通知 — ドラフトの除外、site.baseUrl 未設定による sitemap.xml のスキップ）です。 severity で分岐すれば、実際の問題のときだけ CI を失敗させられます: summary.warnings.some(w => w.severity === "warning")。ターミナルの人間向け サマリーはこれらを別々に数え（warnings: と notes:）、warning:/info: の行を 実際の問題を先頭にして表示します。

manual モードでは auto/hybrid のフィールドが output、pages （[{ url, outputPath }]）、landingRendered に置き換わります。

check --json#

{
  "ok": false,
  "command": "check",
  "mode": "manual",
  "durationMs": 9,
  "config": "/project/ovellum.config.json",
  "pages": 42,
  "counts": { "brokenLinks": 1, "unsafeSchemes": 0 },
  "issues": [
    { "file": "content/index.md", "line": 3, "kind": "broken-link", "message": "..." }
  ]
}

counts.staleTranslations は i18n サイト（site.locales が 2 つ以上）でのみ現れます。issue.kind は broken-link、unsafe-scheme、 stale-translation、orphan-translation のいずれか — さらに --strict では positional-zone、 stale-anchor、missing-frontmatter（counts.strictIssues に計上）が加わります。

終了コード#

コマンド間で安定しているため、スクリプトは出力をスクレイピングせずに分岐できます:

diff は --exit-code を渡さない限り、変更があっても 0 で終了します（git-diff の 慣習）。「ソースとドキュメントがずれたら CI を失敗させる」ゲートに便利です:

ovellum build            # ベースラインの IR スナップショットを記録
ovellum diff --exit-code # 現在のソースが一致しなくなったら exit 1

プログラマティック API#

CLI を起動するより、プロセス内で Ovellum を動かしたいとき — フレームワークの開発 サーバー、モノレポのタスク、独自のビルドステップから — ライブラリとしてインポートします。 import 'ovellum' は副作用がなく（CLI は別のバイナリ）、関数は CLI と同じ構造化された 結果を返します。

import { build, watch } from 'ovellum';

// 一回限り: ホストプロジェクトの配信フォルダへ直接ドキュメントを出力。
const summary = await build({ cwd: 'docs', out: '../site/public/docs', base: '/docs' });
console.log(summary.written);

// 開発サーバーと並走: 変更で再ビルドし、各ビルド完了時にリフレッシュ。
const watcher = await watch({ cwd: 'docs', onBuild: () => devServer.reload() });
// …終了時:
await watcher.close();

• build(options) → BuildSummary。オプション: cwd、configFile、out、 base、drafts、manifest、onLog（--verbose のストリーム）。
• watch(options) → close() を持つハンドル。オプション: cwd、configFile、 drafts、onBuild、onError。出力ディレクトリ / ベースパスは設定で指定します。 auto/hybrid モードでは再ビルドはインクリメンタルです。
• loadConfig(options) → 解決・検証済みの設定。
• defineConfig と設定 / サマリーの型を再エクスポートしているので、TypeScript の ovellum.config.ts とビルドスクリプトが単一の真実のソースを共有します。

パッケージは ESM 専用（type: module）です。CommonJS からは動的 import() を使ってください。

MCP サーバー#

エージェント向けに、ovellum mcp は Ovellum を Model Context Protocol サーバーとして stdio 上で 起動します — これは AI の普遍的なランタイムインターフェースです（Claude Code、Cursor、 Windsurf、Cline、VS Code などがすべて話します）。Ovellum をツール（シンボルの検索、 diff、check、孤立の一覧、ページの取得、ドキュメントの全文検索、ビルド、孤立の再アタッチ、 そして再生成を生き延びる保護ゾーンへの書き込み）、リソース（ovellum://llms.txt、 ovellum://llms-full.txt、ovellum://page/{path}、ovellum://ir、ovellum://orphans）、 プロンプト（set-up-ovellum、document-symbol、review-doc-drift）として公開します。完全な一覧は ovellum mcp リファレンスを参照してください。

お使いの AI ツールへのインストール#

Claude Code — 同梱プラグイン（Skill + MCP サーバー）でワンステップ:

/plugin marketplace add oinam/ovellum
/plugin install ovellum@ovellum

または直接登録: claude mcp add ovellum -- npx ovellum mcp。

Cursor / Windsurf / Cline / VS Code — そのツールの MCP 設定 （.cursor/mcp.json、~/.codeium/windsurf/mcp_config.json、Cline の MCP 設定、 .vscode/mcp.json）に Ovellum を追加します:

{
  "mcpServers": {
    "ovellum": { "command": "npx", "args": ["-y", "ovellum", "mcp"] }
  }
}

サーバーはプロジェクトディレクトリで実行されるので、そこに ovellum をインストール してください（または --cwd を渡します）。（VS Code の .vscode/mcp.json は "mcpServers" の代わりに "servers" キーを使います。値は同じです。）

Ovellum は MCP レジストリにも io.github.oinam/ovellum として登録されているので、レジストリを参照する クライアントから見つけられます。

エージェントに Ovellum の使い方を伝える#

2 つの成果物が、エージェントが探す場所で待ち受けます:

• AGENTS.md — ovellum init がプロジェクトのルートに AGENTS.md（「コーディング エージェントへの指示」のツール横断的な慣習）を生成します。モードに応じた内容で、 hybrid/auto プロジェクトでは保護ゾーンの契約 — 何が再生成を生き延び、何が上書きされるか — を先頭に置くので、エージェントが正しい場所を編集します。既存の AGENTS.md がある場合は 書き込みません。
• Claude Skill — 上記の Claude Code プラグインが ovellum-docs skill を同梱しているので、Claude が要求に応じて Ovellum ドキュメントを スキャフォールド・ビルド・安全に編集できます。プラグインなしで使うには、 plugins/ovellum/skills/ovellum-docs/ を .claude/skills/ にコピーしてください。

AI フレンドリーな出力#

ビルドは HTML の隣に機械可読なコンパニオンも出力します — /llms.txt、 /llms-full.txt、全ページの .md ミラー — エージェントが HTML をスクレイピングせずに ドキュメントを読めます。デフォルトでオンです。site.ai を参照してください。

ページごとの LLM アクション#

.md ミラーが有効なとき（デフォルト）、各ドキュメントページには小さなアクションの行が 付きます: ページをコピー（ページの Markdown をクリップボードにコピー）、 Markdown で表示（生の .md）、そして — site.baseUrl が設定されてリンクが絶対 URL に なるとき — ChatGPT で開く / Claude で開く（ページをそのアシスタントに渡します）。 site.ai.mdMirror 以外の設定は不要で、オフにすると消えます。