fix(docs): make doc-path index migration conditional (#255)

fresh install向け10枠割当と既存deploymentの実在indexを分離し、list確認後にだけ必要なmutationを行う手順へ修正した。

Author: lipluscodex

docs/0-requirements.ja.md

@@ -286,7 +286,7 @@ Vectorize は hybrid retrieval の dense 側を担う。次の metadata を伴
 - documentation path
 - commit SHA / file path / file status / commit date / commit author / blob SHA（diff only）
 
-Metadata index（10/10 枠使用）:
+fresh install向けmetadata index割当（platform上限10枠）:
 
 - Pre-filter 対応: repo, type, state, milestone, doc_path
 - 将来の pre-filter 用に格納: label_0, label_1, label_2, label_3, assignee_0

docs/0-requirements.md

@@ -292,7 +292,7 @@ Vectorize is the dense side of hybrid retrieval. It stores semantic embeddings a
 - wiki page slug + extension (wiki_doc rows)
 - commit SHA, file path, file status, commit date, commit author, blob SHA (diff only)
 
-Metadata indexes (10/10 slots used):
+Fresh-install metadata index allocation (10/10 platform slots):
 
 - Pre-filter capable: repo, type, state, milestone, doc_path
 - Stored for future pre-filter: label_0, label_1, label_2, label_3, assignee_0

docs/installation.ja.md

@@ -182,13 +182,27 @@ wrangler deploy
 
 vector 作成後に metadata index を追加した場合、stored hash を reset して次回 cron で全件 re-embed させる。
 
-既存 deployment が `assignee_1` を index 済みなら、`path_prefix` 対応の deploy 前に未使用の将来用 filter 枠を置き換える。
+既存 deployment はmetadata indexを変更する前に実在一覧を確認する。
+
+```bash
+wrangler vectorize list-metadata-index github-rag-issues
+```
+
+`doc_path` がすでに存在すれば変更不要。存在せず、一覧が10件未満なら何も削除せず追加する。
+
+```bash
+wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path
+```
+
+10枠すべて使用済みで、かつ `assignee_1` が一覧に実在する場合だけ、未使用の将来用 filter 枠を置き換える。
 
 ```bash
 wrangler vectorize delete-metadata-index github-rag-issues --property-name assignee_1
 wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path
 ```
 
+10枠使用済みでも `assignee_1` が実在しない場合は、別の未使用な将来用 index を明示的に選ぶ。production pre-filterを推測で削除しない。
+
 `doc_path` index 作成前に upsert 済みの vector は path filter の対象にならない。既存 doc に `path_prefix` を使う repository ごとに reset する。metadata index 作成後に追加する新しい固定コーパスには過去分の再 index は不要。
 
 Admin endpoint:

docs/installation.md

@@ -182,13 +182,27 @@ Recommended verification flow:
 
 If metadata indexes were created after vectors already existed, reset stored hashes so the next cron run re-embeds everything.
 
-For an existing deployment that still indexes `assignee_1`, replace that unused future-filter slot before deploying `path_prefix` support:
+Inspect an existing deployment before changing its metadata indexes:
+
+```bash
+wrangler vectorize list-metadata-index github-rag-issues
+```
+
+If `doc_path` is already listed, no index mutation is needed. If it is absent and fewer than ten properties are listed, create it without deleting anything:
+
+```bash
+wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path
+```
+
+Only when all ten slots are occupied **and** `assignee_1` is actually listed, replace that unused future-filter slot:
 
 ```bash
 wrangler vectorize delete-metadata-index github-rag-issues --property-name assignee_1
 wrangler vectorize create-metadata-index github-rag-issues --type string --property-name doc_path
 ```
 
+If all ten slots are occupied but `assignee_1` is not listed, choose another unused future-filter index deliberately; do not delete a production pre-filter by assumption.
+
 Vectors upserted before `doc_path` was indexed are not path-filterable. Reset each existing repository whose old docs must support `path_prefix`; a new fixed corpus added after the metadata index exists needs no historical re-index.
 
 Admin endpoint: