scrolls-unhide

docs/.scrolls/ を表示する

/scrolls-setup は、デフォルトでドットファイルとして非表示になる .scrolls フォルダーを作成します。通常のディレクトリ一覧に表示したいプロジェクトでは、このスキルを使うと、既存のセットアップで .scrolls → scrolls に名前を変更し、確実に特定できた古いパスへの参照をすべて修正します。スコープ外のファイルに対する編集を推測で行うことはありません。これは /scrolls-hide の逆にあたります。

特に指定がない限り、すべて現在の作業ディレクトリを基準に処理します。 -t／--reporoot を指定した場合は、このスキル自体の場所ではなく、リポジトリのルートが基準になります。

クロスプラットフォーム対応

同梱スクリプトには、unhide.sh（bash — macOS、Linux、または Git Bash／WSL を搭載した Windows 向け）と unhide.ps1（PowerShell 7+ — Windows、または pwsh をインストールした macOS／Linux 向け）の 2 つの形式があります。どちらもまったく同じフラグを同じ形式で受け付け（-p／--path、-t／--reporoot、-l／--local、-r／--recurse）、同じ出力を生成します。異なるのは起動方法だけです。実際に利用できるものを選んでください。bash --version を試して、成功したら .sh を使用します。そうでない場合は、pwsh 経由で .ps1 を使用してください（推奨。不足している場合は https://aka.ms/powershell からインストールしてください）。pwsh を本当に利用できない場合に限り、Windows に組み込まれている Windows PowerShell の powershell.exe を使用してください（古いバージョンではテストしていません。このスクリプトは pwsh を対象に作成し、検証しています）。

オプション

呼び出しテキストから、以下のオプションを順不同で読み取ってください。ここには実際の argv パーサーがないため、プレーンテキストから手動で取り出してください。

• -p <path> / --path=<path> / --path <path> — 現在のディレクトリの代わりに処理対象とする基準ディレクトリです。1 回の実行で複数の場所を対象にする場合は、複数回指定できます（例：モノレポで -p packages/api -p packages/web）。
• -t / --reporoot — 実際にどのサブディレクトリから実行したかにかかわらず、git リポジトリの最上位（$(git rev-parse --show-toplevel)）を基準ディレクトリとして使用します。現在のディレクトリが git リポジトリ内にない場合は、明確なメッセージを表示して失敗します。
• -l / --local — 現在の作業ディレクトリを明示的に基準ディレクトリとして使用します。-p／-t／-l のいずれも指定されていない場合は、デフォルトで同じ動作になります。このフラグは、その動作を意図的に選んだことを示すためのものです。
• -r / --recurse — 基準ディレクトリ内で再帰的に scrolls フォルダーを検索します。基準ディレクトリ直下の docs/.scrolls だけを確認する代わりに、配下を再帰的に検索します。grep／cp／rm などのツールで通常使われる -r と同じ意味です。デフォルトでは無効で、対象範囲を広げる場合に指定します。上記のいずれかと組み合わせて使用できます（何も指定せず、cwd から再帰的に検索することもできます）。

-p、-t、-l は、基準ディレクトリを選ぶ 3 つの異なる方法です。-t と -l はそれぞれ 1 つのディレクトリに解決されるため、-p や相互に組み合わせることはできません。より具体的な対象を指定する場合は、-p を（複数回）指定してください。-r は独立しており、どのオプションとも併用できます。基準ディレクトリを指定しない場合、同梱スクリプトは、ユーザーが設定していれば DEFAULT_SCROLLS_RELPATH 環境変数の値をデフォルトとして使用し、そうでなければ現在のディレクトリを使用します。また、そのデフォルトが再帰検索ではなく、git リポジトリ内でリポジトリの最上位と異なる場合、スクリプトは代替手段として -t／-r を案内するメモを表示します。これがないと、リポジトリ内の別の場所にある scrolls フォルダーがエラーではなく、見つからないままになるためです。

手順

1. 同梱スクリプトを実行する

bash <skill-dir>/scripts/unhide.sh [-p BASE ...] [-t] [-l] [-r]
pwsh <skill-dir>/scripts/unhide.ps1 [-p BASE ...] [-t] [-l] [-r]

ユーザーが指定したフラグは、環境に合うほう（上記の「クロスプラットフォーム」を参照）に、指定された形式のまま渡してください。デフォルトを使う場合は、フラグを一切指定しません。スクリプトは、解決された各ベースディレクトリについて、次の処理を行います。

• -r を指定しない場合（デフォルト）：1 か所だけ確認します。ベースディレクトリ自体がすでに scrolls フォルダー（STARTER.md を含む）であればその場所を、そうでなければ <base>/docs/.scrolls を確認します。高速であり、/scrolls-setup／/scrolls-update がデフォルトで使用する場所にも合致するため、引数なしの実行ではまず明らかな場所が対象になります。
• -r／--recurse を指定する場合：ベースディレクトリ以下の限られた階層を検索し、STARTER.md を含む、文字どおり .scrolls という名前のディレクトリを探します。この条件があるため、広いベースディレクトリ（リポジトリ全体でも）から再帰検索しても安全です。偶然同じ名前になっただけで STARTER.md がないディレクトリは無視し、一般的に重いディレクトリやベンダーディレクトリ（node_modules、.git、vendor、dist、build、.venv、venv、__pycache__、target、.next、.cache）には降りず、検索対象から除外します。

どちらの場合も、見つかった各フォルダーについて次の処理を行います。

1. 同じ階層にすでに scrolls フォルダーがある場合は、その理由を報告して対象をスキップします。それ以外の場合、リポジトリとファイルが Git で追跡されていれば、履歴を保持するために git mv で名前を変更し、そうでなければ通常の mv にフォールバックします。
2. 古いパスへの参照を、移動したフォルダー内のファイル（自身のパスへの参照を含む STARTER.md など）で書き換えます。また、そのフォルダーの docs と同じ階層に、完全に一致する SCROLLS.md ファイルがある場合は、そこでも書き換えます。SCROLLS.md をより広い範囲で検索することはありません。CLAUDE.md 自体は変更しません。/scrolls-setup は CLAUDE.md を SCROLLS.md への固定ポインターとして書き込み、scrolls のパスを直接参照しないため、書き換えるものがありません。/scrolls-setup は、SCROLLS.md 自体の場所を基準にした短く移植可能な参照（docs/.scrolls）を書き込みます。そのため、複数の場所をまとめて処理する際、異なる 2 つの scrolls フォルダーで同じ短い文字列が正当に使われることがあります。該当する SCROLLS.md ファイルをより広く検索すると、無関係な同階層のパッケージのファイルを書き換えるおそれがあります。（この書き換えでは、以前の規則に基づいてカスタムの --path で設定された scrolls フォルダーに備え、検出された完全なパスも試します。）
3. 近くにあるファイルのうち、古いパスへの参照がまだ残っているものを表示します。これらは報告のみで、編集はされません。共有される短縮形式の規則では、誤検出の原因になりやすいため、ほかの scrolls フォルダー内のファイルは対象外です。ただし、同階層の SCROLLS.md が誤検出として含まれる場合もあります。これは想定内です。下記の手順 2 を参照してください。スクリプトが変更するのは scrolls フォルダーとその SCROLLS.md だけです。ほかのファイルを読まずに任意の文章（README、CI 設定、ほかのドキュメント）を書き換えると、無関係な内容を損なうおそれがあるためです。

指定されたベースディレクトリに一致するフォルダーがない場合、エラーで終了します。-r を指定していない場合は、パスを確認する、リポジトリのルートを想定していたなら -t を試す、またはさらに深い階層にある可能性があれば -r を追加する合図です。それ以外の場合は、ユーザーに /scrolls-setup を案内してください。

2. 報告された残りの参照を処理する

スクリプトが「Other references... left for manual review」に一覧表示したファイルは、それぞれ内容を読み、本当に古いパスへの参照であれば（README、CONTRIBUTING ドキュメント、CI スクリプトなど）、機械的な検索・置換ではなく、通常の編集上の判断に従って参照を更新してください。このプロジェクトの scrolls フォルダーとは実際には関係のないもの（偶然文字列が一致しただけの場合など）はスキップします。

3. 結果を報告する

公開状態に戻した各フォルダーについて、移動元のパスから移動先のパス（旧パス → 新しいパス）を一覧表示し、それぞれで自動修正した内容（フォルダー内のファイル、SCROLLS.md）を報告してください。スキップしたものがあれば、その理由（移動先がすでに存在していたこと）も記載し、手順 2 で手動修正した内容があれば、それも報告してください。

開発

ディレクトリ構成、tests/ の回帰テストスイートの実行方法、バージョン管理に関する注意事項については、meta/MAINTAINERS.md を参照してください。これらはいずれも、ユーザーの /scrolls-unhide リクエストへの対応時には読み込まれません。そのため、対応中に meta/MAINTAINERS.md や tests/ を操作しないでください。