すべてのコマンドはプロジェクトルート（sorane.yaml があるディレクトリ）を --cwd で指定します。例では npx @sorane/cli（npm の最新版）を使います。CI でバージョン固定する場合は @sorane/[email protected] を付けてください。
オプショナルパッケージ#
| コマンド / 設定 | 追加パッケージ |
|---|---|
index / search | @sorane/search |
fonts.enabled: true | @sorane/font |
build.diagrams.enabled: true（client） | mermaid |
未インストール時は npm install <pkg> を表示します（yarn / pnpm は lockfile から自動判定）。対話端末ではインストール確認が出ます。index / search では --yes（または -y）で確認なしインストールできます。
npm install @sorane/cli @sorane/search # 検索まで使うサイト
sorane build#
静的サイトを生成します。
npx @sorane/cli build [--cwd <dir>] [--clean] [--watch] [--drafts] [--preview]
npx @sorane/cli watch [--cwd <dir>] [--clean] [--drafts] [--preview]
npx @sorane/cli preview [--cwd <dir>] [--port 4321] [--watch]
--clean は出力ディレクトリを削除してから再生成します。--watch（または sorane watch）は content/ と sorane.yaml の変更を監視して再ビルドします（2回目以降は自動で --clean）。
ローカルプレビュー#
npx @sorane/cli preview --cwd . --watch
dist/ をビルドして http://127.0.0.1:4321/ で配信します。--watch で保存のたびに再ビルドします。プレビューでは draft: true の記事も含め、全ページに「ローカルプレビュー」バナーを付けます。本番の build（CI デプロイ）では draft: true は 出力されません。
--skip-c2pa は build.c2pa.enabled 時でも静的画像への C2PA 署名を省略します（CI スナップショット向け）。
ビルド完了時に built N page(s) in X.Xs と所要時間を表示します。
sorane validate#
frontmatter と OKF プロファイル（sorane-okf/0.1 / 0.2 / 0.3）を検証します。
npx @sorane/cli validate [--cwd <dir>] [--json]
--json は AI エージェント向けの構造化レポート（schema_version: 1）を stdout に出力します。ok: false のとき exit code は非ゼロです。
findings[].severity | 意味 |
|---|---|
error | 修正必須（OKF / frontmatter） |
warning | 推奨修正（下表の category） |
findings[].category | 内容 |
|---|---|
okf | プロファイル・必須 frontmatter |
diagram | 図表フェンスの alt 欠落 |
heading | 見出し階層の飛び・本文 h1 |
image | 本文画像の alt 欠落 |
link | 非説明的リンクテキスト |
table | GFM 表のヘッダー不備 |
date | timestamp / updated の形式・順序 |
revision | revisions 配列の形式・日付・要約・並び |
faq | type: faq の ## 質問見出し・回答の構造 |
glossary | type: glossary / glossary-term の構造・推奨 frontmatter |
reference | type: reference の description / resource 推奨・GFM 表 |
dataset | type: dataset のライセンス・distribution URL など |
i18n | translation_key と site.i18n ロケールの整合性 |
lang | 本文の言語混在・lang 属性の形式 |
build.quality で image / link / table / date / lang_mixing の warning を個別に無効化できます。heading: error で見出し階層を error に昇格できます（設定）。
template/site/AGENTS.md と .grok/skills/sorane-content/SKILL.md がこの JSON 契約を前提にしています。
sorane migrate#
レガシー frontmatter を OKF 形式へ変換します。
npx @sorane/cli migrate [--cwd <dir>] [--dry-run] [--bump-profile 0.2|0.3]
--bump-profile は profile: sorane-okf/<version> へ上げるだけで、AI 開示や dataset 用フィールドは追加しません。
sorane index#
検索インデックス（SQLite FTS5、任意でベクトル）を構築します。既定は FTS のみです。
npx @sorane/cli index [--cwd <dir>] [--force] [--hybrid] [--fts-only] [--yes]
要 @sorane/search（未導入時は上記オプショナルパッケージの案内）。リポジトリ開発時や cargo build 済み環境では、ネイティブ Rust CLI（sorane-astro-backend index）を優先し、埋め込みは pure-Rust ONNX（ruri-v3-30m）を使います。バイナリが無い場合は @sorane/search（transformers.js）にフォールバックします。
ハイブリッド（experimental）を使う場合は search.mode: hybrid または --hybrid と、先に npm run fetch-model で ruri-v3-30m を取得してください（vendor/models/ruri-v3-30m/onnx/model_quantized.onnx と tokenizer.json が必要です）。
sorane search#
ローカルで検索を試します。
npx @sorane/cli search <query> [--cwd <dir>] [--type article|dataset|reference|glossary|glossary-term|faq] [--tag <slug>] [--k 10] [--json] [--fts-only] [--yes]
要 @sorane/search。ハイブリッド索引があるとき、クエリ埋め込みもネイティブ ONNX を優先します（ビルド済みかつモデルあり）。FTS のみの索引では --fts-only 不要（ベクトル列が無ければ自動で FTS のみ）。
ネイティブ Rust バックエンド（CLI）#
rust/sorane-astro-backend をビルドすると、sorane index / sorane search が TypeScript より先にネイティブ経路を試します。
cargo build --manifest-path rust/sorane-astro-backend/Cargo.toml
| 環境変数 | 効果 |
|---|---|
SORANE_INDEX_NATIVE=0 | sorane index を @sorane/search のみに固定 |
SORANE_EMBED_NATIVE=0 | sorane search のクエリ埋め込みを transformers.js のみに固定 |
SORANE_ASTRO_BACKEND_CLI | ネイティブバイナリのパスを上書き（index / embed / Astro backend 共通） |
SORANE_INDEX_NATIVE_CLI | sorane index 用バイナリパス（SORANE_ASTRO_BACKEND_CLI より優先されない） |
SORANE_EMBED_NATIVE_CLI | sorane search 用バイナリパス |
モデルが無い・不完全な場合は FTS-only にフォールバックし、ビルドは続行します。