chore: update docs (#151)

Author: yuluo-yx

docs/reference/how-it-works.md

@@ -94,21 +94,23 @@ Notes:
 
 - Built-in command candidates cover common cloud tools even before PATH discovery runs.
 - Built-in tree-shaped subcommands cover common `git`, `docker`, and `kubectl` nested commands even before dynamic discovery runs.
-- Typo caches discovered subcommands in `~/.typo/subcommands.json` using `schema_version: 2`.
+- Typo caches discovered subcommands in `~/.typo/subcommands.json` using `schema_version: 3`.
 - Hierarchical subcommand discovery is supported for `git`, `docker`, `aws`, `gcloud`, and `az`; `kubectl` resource correction uses a conservative built-in resource tree.
-- Older subcommand cache files without `schema_version: 2` are moved aside automatically and regenerated.
+- Older subcommand cache files without `schema_version: 3` are moved aside automatically and regenerated.
 
-### Subcommand cache version 2
+### Subcommand cache version 3
 
 `subcommands.json` uses a versioned tree format:
 
 ```json
 {
-  "schema_version": 2,
+  "schema_version": 3,
   "tools": [
     {
       "tool": "git",
       "tree": {
+        "long_options": ["--help", "--version"],
+        "long_options_with_values": ["--git-dir", "--work-tree"],
         "children": {
           "stash": {
             "children": {
@@ -123,22 +125,26 @@ Notes:
 }
 ```
 
-Version 2 stores nested subcommands directly instead of keeping a flat root list
-plus path-specific child lists. This lets typo correct each command level
-independently, for example `gcloud container clusers lisr` to
-`gcloud container clusters list`.
+Version 3 keeps the nested command tree format and adds long-option metadata to
+tree nodes. This lets typo correct each command level independently, for example
+`gcloud container clusers lisr` to `gcloud container clusters list`, while also
+keeping the option candidates used by experimental `--long-option` correction in
+the same cache.
 
 Node fields have these meanings:
 
 - `children`: valid child tokens below the current level
 - `terminal`: the token can end a command path
 - `passthrough`: arguments after this token are treated as user input, not subcommands
 - `alias`: canonical token to output when a short alias is used
-
-If typo finds an older cache format, it renames that file to
-`subcommands.json.corrupt-<timestamp>` and rebuilds a fresh version 2 cache on
-next use. The file only contains discovered command metadata, so no user rules,
-history, or configuration are lost.
+- `long_options`: known `--long-option` tokens visible at this node
+- `long_options_with_values`: known `--long-option` tokens that consume the next argument
+
+If typo finds an older cache format, including version 2 or files without a
+schema version, it renames that file to
+`subcommands.json.corrupt-<timestamp>` and rebuilds a fresh version 3 cache on
+next use. The file only contains discovered command metadata and option
+metadata, so no user rules, history, or configuration are lost.
 
 ## Local files
 

docs/reference/how-it-works_CN.md

@@ -87,21 +87,23 @@ Typo 不仅能修正顶层命令，也能修正常见工具的子命令。
 
 - 常用云工具会作为内置命令候选加入，即使 PATH 发现还没执行，也能先修正顶层命令。
 - `git`、`docker`、`kubectl` 内置了树形子命令结构，即使动态发现还没执行，也能修正常见多层子命令。
-- 动态发现到的子命令会以 `schema_version: 2` 的树形结构缓存到 `~/.typo/subcommands.json`。
+- 动态发现到的子命令会以 `schema_version: 3` 的树形结构缓存到 `~/.typo/subcommands.json`。
 - `git`、`docker`、`aws`、`gcloud`、`az` 支持层级化子命令发现；`kubectl` 资源修正使用保守的内置资源树。
-- 不符合 `schema_version: 2` 的旧子命令缓存会被自动隔离，并在后续使用时重新生成。
+- 不符合 `schema_version: 3` 的旧子命令缓存会被自动隔离，并在后续使用时重新生成。
 
-### 子命令缓存 v2
+### 子命令缓存 v3
 
 `subcommands.json` 使用带版本号的树形格式：
 
 ```json
 {
-  "schema_version": 2,
+  "schema_version": 3,
   "tools": [
     {
       "tool": "git",
       "tree": {
+        "long_options": ["--help", "--version"],
+        "long_options_with_values": ["--git-dir", "--work-tree"],
         "children": {
           "stash": {
             "children": {
@@ -116,16 +118,18 @@ Typo 不仅能修正顶层命令，也能修正常见工具的子命令。
 }
 ```
 
-v2 会直接保存嵌套子命令，不再使用“根级扁平列表 + 路径子列表”的旧格式。这样 Typo 可以逐层修正命令，例如把 `gcloud container clusers lisr` 修正为 `gcloud container clusters list`。
+v3 保留嵌套命令树格式，并在树节点上增加长选项元数据。这样 Typo 既可以逐层修正命令，例如把 `gcloud container clusers lisr` 修正为 `gcloud container clusters list`，也可以把实验性 `--long-option` 修正所需的候选保存在同一份缓存里。
 
 节点字段含义如下：
 
 - `children`：当前层级下的有效子命令。
 - `terminal`：该 token 可以作为命令路径的结束。
 - `passthrough`：该 token 后面的内容按用户参数处理，不再继续当作子命令修正。
 - `alias`：短别名对应的规范输出名称。
+- `long_options`：当前节点可见的已知 `--long-option` token。
+- `long_options_with_values`：当前节点可见、且会消费下一个参数的已知 `--long-option` token。
 
-如果 Typo 发现旧格式缓存，会把该文件重命名为 `subcommands.json.corrupt-<时间戳>`，并在下次使用时重新生成 v2 缓存。该文件只包含动态发现到的命令元数据，不包含用户规则、历史记录或配置，因此隔离旧缓存不会丢失用户数据。
+如果 Typo 发现旧格式缓存，包括 v2 或没有 schema 版本的文件，会把该文件重命名为 `subcommands.json.corrupt-<时间戳>`，并在下次使用时重新生成 v3 缓存。该文件只包含动态发现到的命令元数据和选项元数据，不包含用户规则、历史记录或配置，因此隔离旧缓存不会丢失用户数据。
 
 ## 本地文件
 

docs/troubleshooting/upgrade-from-0x.md

@@ -101,13 +101,15 @@ The `~/.typo/` directory layout has expanded:
 
 ### Subcommand cache format
 
-Current v1 builds write `subcommands.json` with `schema_version: 2`. This format
-stores a tree of subcommands so typo can correct nested command paths such as
-`aws cloudformation wait stack-create-complete` and
-`gcloud container clusters list`.
-
-Older cache files from previous builds may not have a `schema_version` field or
-may use a flat list format. On first load, typo moves those files aside as
+Current v1 builds write `subcommands.json` with `schema_version: 3`. This format
+stores a tree of subcommands plus long-option metadata so typo can correct nested
+command paths such as `aws cloudformation wait stack-create-complete` and
+`gcloud container clusters list`, and can reuse cached option candidates for
+experimental `--long-option` correction.
+
+Older cache files from previous builds may not have a `schema_version` field,
+may use a flat list format, or may use the previous tree-only version 2 format.
+On first load, typo moves those files aside as
 `subcommands.json.corrupt-<timestamp>` and creates a fresh cache when
 subcommand discovery runs again.
 

docs/troubleshooting/upgrade-from-0x_CN.md

@@ -101,9 +101,9 @@ Invoke-Expression (& typo init powershell | Out-String)
 
 ### 子命令缓存格式
 
-当前 v1 版本写入的 `subcommands.json` 使用 `schema_version: 2`。该格式保存树形子命令，因此 Typo 可以修正 `aws cloudformation wait stack-create-complete`、`gcloud container clusters list` 这类多层命令路径。
+当前 v1 版本写入的 `subcommands.json` 使用 `schema_version: 3`。该格式保存树形子命令和长选项元数据，因此 Typo 可以修正 `aws cloudformation wait stack-create-complete`、`gcloud container clusters list` 这类多层命令路径，也可以复用缓存中的选项候选来支持实验性 `--long-option` 修正。
 
-旧版本生成的缓存可能没有 `schema_version` 字段，也可能使用扁平列表格式。Typo 首次加载时会把这些旧缓存隔离为 `subcommands.json.corrupt-<时间戳>`，并在下一次执行子命令发现时重新生成缓存。
+旧版本生成的缓存可能没有 `schema_version` 字段，也可能使用扁平列表格式，或使用上一版仅包含树形子命令的 v2 格式。Typo 首次加载时会把这些旧缓存隔离为 `subcommands.json.corrupt-<时间戳>`，并在下一次执行子命令发现时重新生成缓存。
 
 不需要手动迁移。该缓存不保存用户规则、历史记录或配置。如果需要强制刷新，可以删除 `~/.typo/subcommands.json`，然后运行会触发子命令修正的命令。