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）。两者接受完全相同的标志，形式也完全相同（-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>——指定要操作的基目录，而非当前目录。可重复使用，以便在一次运行中指定多个位置（例如，在单体仓库中使用 -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 的常见含义一致：默认关闭，选择启用后才会扩大搜索范围。

-p、-t 和 -l 是选择基目录的三种不同方式——-t 和 -l 各自只会解析为一个基目录，不能与 -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（默认）：仅检查一个位置——如果基础目录本身已经是 scrolls 文件夹（含有 STARTER.md），则检查该目录；否则检查 <base>/docs/.scrolls。速度快，且与 /scrolls-setup 和 /scrolls-update 默认使用的位置一致，因此直接运行时会优先检查最显而易见的位置。
• 带 -r/--recurse：在基础目录下的有限层级内，搜索名称确切为 .scrolls 且包含 STARTER.md 的目录。这个限制使得从宽泛的基础目录（甚至整个仓库）递归搜索也很安全：碰巧同名但不含 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 会将它写成指向 SCROLLS.md 的固定指针，而不是直接引用 scrolls 路径，因此无需重写其中的内容。/scrolls-setup 会写入简短且可移植的引用（相对于 SCROLLS.md 所在位置的 docs/.scrolls），因此在包含多个位置的批量处理中，两个不同的 scrolls 文件夹可能恰好使用完全相同的简短字符串；若“热心地”更广泛地搜索匹配的 SCROLLS.md 文件，就可能重写无关的同级软件包文件。（对于按照旧约定、使用自定义 --path 设置的 scrolls 文件夹，重写操作也会尝试完整路径。）
3. 打印附近仍提及旧路径的其他文件——这些文件只会列出，不会编辑；其他 scrolls 文件夹内部的文件会被排除（在使用共享简短形式约定时，这类文件是常见的误报来源），但偶尔仍可能包含一个误报的同级 SCROLLS.md——这是预期情况，见下文第 2 步。脚本有意不触碰 scrolls 文件夹及其自身的 SCROLLS.md 以外的文件，因为在未先阅读的情况下重写任意文本（README、CI 配置、其他文档）可能会破坏无关内容。

如果某个基础目录下没有匹配的文件夹，脚本会报错退出——不带 -r 时，这意味着应检查路径；如果原本预期的是仓库根目录，则尝试使用 -t；如果目录可能嵌套得更深，则添加 -r；否则请用户运行 /scrolls-setup。

2. 处理报告中遗留的引用

对于脚本在“其他引用……留待手动检查”下列出的每个文件，请先阅读；如果确实是过时路径（例如 README、CONTRIBUTING 文档或 CI 脚本），则使用常规编辑判断自行更新引用，而不是盲目查找并替换。跳过与本项目的 scrolls 文件夹无关的内容（例如碰巧匹配的字符串）。

3. 汇报结果

列出每个已取消隐藏的文件夹（旧路径 → 新路径）、每个文件夹中自动修复的内容（文件夹自身的文件、SCROLLS.md）、跳过的项目及原因（目标已存在），以及第 2 步中手动修复的内容（如有）。

开发

有关目录结构、运行 tests/ 回归测试套件以及版本管理说明，请参阅 meta/MAINTAINERS.md。执行用户的 /scrolls-unhide 请求时，不会读取这两者；回答此类请求时，请勿处理 meta/MAINTAINERS.md 或 tests/。