開発ガイド (Development Guide)

1. ディレクトリ構成

パス	内容
`src/frontend/`	UI（Vanilla JS / CSS）。React/Vite は未使用。
`src/backend/`	Rust / Tauri / Axum。MCP サーバー・LSA・埋め込みエンジン。
`tests/`	テスト一式（原則ルート直下に集約）。API/MCP は `test_mcp_client.mjs`、E2E は `tests/e2e/`。Rust の結合テストファイルだけは Cargo の都合で `src/backend/tests/` に配置。詳細は `tests/README.md`。
`docs/specification/`	本仕様書群。
`.agent/rules/`	AI エージェント用プロジェクト運用ルール。
`tools/`	開発用スクリプト。計測（count_loc, nesting_depth）、Mermaid 構文チェック（check-mermaid）、起動・テスト用など。

Mermaid 構文チェック: Markdown 内の mermaid コードブロックを検証するには npm run check-mermaid を実行する。対象は docs/ と journals/（引数でファイル指定も可）。要 @mermaid-js/mermaid-cli（mmdc）。

Community: npm run dev（F5 などでそのまま起動できる）。起動時に LSA/HNSW 学習あり。
Community（速い起動）: npm run dev:fast。TELOS_SKIP_BOOT_TRAIN=1 で起動時学習をスキップ。検索が必要なら UI の「RE-INDEX」を実行。
Pro: npm run dev:pro または npm run dev:fast:pro。embedding_model/ に ONNX モデルと vocab を配置すること。

ルール: 配布ビルド（build:community / build:pro）の前に、Community 版・Pro 版の全テストを実行し、すべて成功していること。

必須テスト（順に実行し、いずれも exit 0 であること）:
1. npm run test:rust（Community 単体）
2. npm run test:rust:pro（Pro 単体）
3. npm run test:e2e（Community E2E）
4. npm run test:e2e:pro（Pro E2E。embedding モデル要）
一括実行: npm run test:all で上記 1〜4 を順に実行する。失敗したら配布ビルドを行わない。
Community: npm run build:community
- 設定: src/backend/tauri.community.conf.json（productName: TelosDB-Community、vec0.dll のみ同梱）
Pro: npm run build:pro
- 設定: src/backend/tauri.pro.conf.json（productName: TelosDB-Pro、埋め込みモデル等を含む）

それぞれ別名のインストーラ（例: TelosDB-Community_*.exe, TelosDB-Pro_*.exe）が生成されます。

デフォルト: Community（LSA）。cargo build で LSA のみ。
Pro: cargo build --no-default-features --features pro。埋め込み・HNSW 等の Pro 用コードが含まれる。

DB（src/backend/src/db/）: sqlite-vec（vec0）でベクトル、FTS5 で全文検索。次元は Community 50 / Pro 768。
- 件数・アイテム取得は get_document_count・get_item_content_with_doc・get_document_id_by_path 等のラップ関数を利用。FTS 同期は heal_items_fts。
MCP（src/backend/src/mcp/）:
- ルーティングは mod.rs の create_mcp_app(state)。起動は build_app_state で状態を組み立てたあと run_server で LSA/HNSW 同期 → listen。
- ツール定義は tools/registry.rs の tool_list()。新規ツール追加時は registry と tools::dispatch_tool の match の両方に追加する。
- 検索時のクエリベクトルは tools/search.rs の get_query_vector(state, text) で取得（LSA/埋め込みの切り替えはここで完結）。
LSA: utils/lsa.rs で SVD による 50 次元ベクトル化（Community）。
埋め込み: Pro は utils/embedding_pro.rs。ONNX（tract または ort）で 768 次元。詳細は 07_embedding_tract.md。

ゴール・KPI: 08_embedding_tract_goals_and_kpi.md
検証手順: 09_embedding_tract_implementation_and_tests.md
UI テスト方針: 12_ui_testing_options.md
E2E: npm run test:e2e はバイナリが既にあればビルドをスキップする。永遠に待たないようにするには npm run test:e2e:timed（既定 8 分で打ち切り）を使う。打ち切り時はコンソール出力をログとして確認する。
失敗しているスペックだけ回す: 全件 E2E で失敗したスペックが分かったら、そのファイルだけを繰り返し実行してパッチ当てする。例: npm run test:e2e:spec -- --spec tests/e2e/specs/screenshot-docs-modal.spec.js。複数指定する場合は --spec を複数並べるか、--spec "tests/e2e/specs/foo.spec.js" "tests/e2e/specs/bar.spec.js" のようにする。
E2E（1 回・打ち切り付き）: npm run test:e2e:timed で 1 回だけ実行（既定 8 分で打ち切り）。リトライはしない。失敗したら原因を直してから再実行する。

不具合時は質問より先にログを確認する。アプリ起動失敗・MCP が応答しない・E2E タイムアウト・indexing が終わらない等は、ターミナル・tauri-driver・バックエンドの標準出力・標準エラーおよび log::info! 等を読んでから原因を判断する。
ログをファイルに残す: npm run dev:log で起動すると標準出力・標準エラーが tmp/dev.log に追記される。不具合再現後に tmp/dev.log を開いて確認する。