rubycli 0.1.7 → 0.2.0

data/README.ja.md

@@ -1,12 +1,49 @@
 # Rubycli — Python Fire 風の Ruby 向け CLI
 
-![Rubycli ロゴ](assets/rubycli-logo.png)
+![Rubycli ロゴ](https://raw.githubusercontent.com/inakaegg/rubycli/main/assets/rubycli-logo.png)
 
-Rubycli は Ruby のクラス／モジュールにある公開メソッドの定義と、そのメソッドに付けたドキュメントコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しており、コメントに書いた型ヒントや繰り返し指定が CLI の引数解釈もコントロールします。
+[![Gem Version](https://img.shields.io/gem/v/rubycli)](https://rubygems.org/gems/rubycli)
 
-> English guide is available in [README.md](README.md).
+Rubycli は、既存の Ruby クラス／モジュールをそのままコマンドラインインターフェースにするツールです。
+公開メソッドの定義と、メソッドに付けたドキュメントコメントを読み取って CLI を組み立てるため、
+最小構成ではスクリプト側の変更が一切不要です（`require "rubycli"` すら要りません）。
+コメント内の型アノテーションは単なる説明ではなく、CLI 引数の解釈そのものを制御します
+（例: `TAG... [String[]]` と書くと配列としてパースされます）。
 
-### 1. Rubycli を意識しない既存スクリプト
+[Python Fire](https://github.com/google/python-fire) にインスパイアされていますが、
+移植や公式プロジェクトではなく、Ruby のコメント記法と型アノテーションに焦点を当てた独自実装です。
+
+> English documentation: [README.md](README.md)
+
+![Rubycli のデモ（コマンド生成と実行の様子）](https://raw.githubusercontent.com/inakaegg/rubycli/main/assets/rubycli-demo.gif)
+
+## プロジェクトの状態
+
+Rubycli は**メンテナンスを終了しました。** 0.2.0 が最終リリースで、公開済み gem の挙動を
+全面監査して見つかった 8 件の不具合を修正し、区切りとしています
+（[CHANGELOG.md](CHANGELOG.md) 参照）。Issue・Pull Request の対応は行わず、
+今後のリリース予定もありません。
+
+コードは参考のため公開したまま残しています。実務で CLI ライブラリを選ぶのであれば、
+[Thor](https://github.com/rails/thor)、[dry-cli](https://dry-rb.org/gems/dry-cli/)、
+または Ruby 標準の `OptionParser` をご利用ください。
+
+## インストール
+
+```bash
+gem install rubycli
+```
+
+```ruby
+# Gemfile
+gem "rubycli"
+```
+
+Ruby 3.0 以上が必要です。ライセンスは [MIT](LICENSE) です。
+
+## クイックスタート
+
+### 1. 既存スクリプトをそのまま実行する
 
 ```ruby
 # hello_app.rb
@@ -19,7 +56,8 @@ module HelloApp
 end
 ```
 
-> リポジトリには `examples/hello_app.rb` を同梱しているので、プロジェクト直下で `rubycli examples/hello_app.rb` を実行すると公開コマンドをすぐに確認できます。
+同じ内容を `examples/hello_app.rb` として同梱しているので、以下のコマンドは
+プロジェクト直下でそのまま試せます。
 
 ```bash
 rubycli examples/hello_app.rb
@@ -30,11 +68,13 @@ Usage: hello_app.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <NAME>
+    greet                NAME
 
 Detailed command help: hello_app.rb COMMAND help
 ```
 
+引数が足りない場合はスタックトレースではなく使い方が表示されます。
+
 ```bash
 rubycli examples/hello_app.rb greet
 ```
@@ -52,16 +92,15 @@ rubycli examples/hello_app.rb greet Hanako
 #=> Hello, Hanako!
 ```
 
-`rubycli examples/hello_app.rb --help` を実行しても同じヘルプが表示されます。
+`rubycli examples/hello_app.rb --help` でも、コマンド未指定時と同じ一覧が表示されます。
 
-### 2. コメントのヒントを足してオプションを有効化
+### 2. コメントを足して型付きオプションを有効にする
 
-> まだ `require "rubycli"` は不要です。コメントでオプション解析とヘルプを制御します。
-
-**簡潔なプレースホルダ記法**
+この段階でも `require "rubycli"` は不要です。コメントだけでオプション解析とヘルプが変わります。
+簡潔なプレースホルダ記法と YARD タグのどちらでも書けます。
 
 ```ruby
-# hello_app.rb
+# 簡潔なプレースホルダ記法
 module HelloApp
   module_function
 
@@ -75,10 +114,8 @@ module HelloApp
 end
 ```
 
-**YARD タグでも同様に動作**
-
 ```ruby
-# hello_app.rb
+# YARD タグ
 module HelloApp
   module_function
 
@@ -92,21 +129,13 @@ module HelloApp
 end
 ```
 
-> README に合わせたドキュメント付きの版は `examples/hello_app_with_docs.rb` として同梱しています。
-
-```bash
-rubycli examples/hello_app_with_docs.rb
-```
-
-```text
-Usage: hello_app_with_docs.rb COMMAND [arguments]
-
-Available commands:
-  Class methods:
-    greet                <NAME> [--shout]
-
-Detailed command help: hello_app_with_docs.rb COMMAND help
-```
+ドキュメント付きの版は `examples/hello_app_with_docs.rb` として同梱しています。
+モジュール名は `HelloApp` のままなので、ファイル末尾に
+`HelloAppWithDocs = HelloApp` を置いてファイル名と一致する定数を用意しています。
+そのため追加のフラグなしで実行できます。一致する定数がないファイルの扱いは
+後述の[対象定数の解決](#対象定数の解決)を参照してください。
+（この別名の検出は Rubycli 0.1.7 以前では未対応です。それらのバージョンでは
+`--auto-target` / `-a` を付けてください。）
 
 ```bash
 rubycli examples/hello_app_with_docs.rb greet --help
@@ -116,10 +145,10 @@ rubycli examples/hello_app_with_docs.rb greet --help
 Usage: hello_app_with_docs.rb greet NAME [--shout]
 
 Positional arguments:
-  NAME  [String]  required  挨拶対象
+  NAME  [String]  required  Name to greet
 
 Options:
-  --shout  [Boolean]  optional  大文字で出力 (default: false)
+  --shout  [Boolean]  optional  Print in uppercase (default: false)
 ```
 
 ```bash
@@ -127,7 +156,11 @@ rubycli examples/hello_app_with_docs.rb greet --shout Hanako
 #=> HELLO, HANAKO!
 ```
 
-CLI に公開したくないヘルパーは、特異クラス側で `private` として定義してください:
+CLI コマンドになるのは、対象のクラス／モジュール自身に定義された public メソッドだけです。
+親クラスから継承したメソッド、`include` で取り込んだメソッド、`attr_accessor` が生成する
+メソッドは公開されないため、CLI から呼びたい場合は対象側にラッパーを定義してください。
+
+CLI に公開したくないヘルパーは、特異クラス側で `private` として定義します。
 
 ```ruby
 module HelloApp
@@ -135,99 +168,19 @@ module HelloApp
     private
 
     def internal_ping(url)
-      # CLI コマンドとしては露出しない
+      # CLI コマンドとしては公開されない
     end
   end
 end
 ```
 
-### 3. （任意）スクリプト内にランナーを組み込む
-
-`ruby hello_app.rb ...` の形で呼び出したい場合だけ `require "rubycli"` を追加し、`Rubycli.run` に制御を渡します（後述のクイックスタート参照）。
-
-## 定数解決モード
-
-Rubycli は「ファイル名を CamelCase にした定数」を公開対象だと想定しています。ファイル名とクラス／モジュール名が一致しない場合は、次のモードで挙動を切り替えられます。
-
-| モード | 有効化方法 | 挙動 |
-| --- | --- | --- |
-| `strict`（デフォルト） | 何もしない / `RUBYCLI_AUTO_TARGET=strict` | CamelCase が一致しないとエラーになります。検出した定数一覧と再実行コマンド例を表示します。 |
-| `auto` | `--auto-target`（短縮 `-a`） または `RUBYCLI_AUTO_TARGET=auto` | ファイル内で CLI として実行できる定数が 1 つだけなら自動選択します。複数あれば従来通りエラーで案内します。 |
-
-大規模なコードベースでも安全側を保ちながら、どうしても自動選択したいときだけ 1 フラグで切り替えられます。
-
-> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`def greet` など）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。`--new` を付ければ `rubycli --help` でもインスタンスメソッドが一覧に現れ、`rubycli --check --new` でコメントの lint も実行できます。初期化時に引数が必要なら `--new=VALUE` のように続けて指定できます（通常の引数と同様に YAML/JSON ライクな安全パースに加え、`--json-args` / `--eval-args` / `--eval-lax` も適用可能）。`initialize` に書いたコメントも通常の CLI メソッドと同様に型変換に反映されます。
-
-> 補足: `--new 1` のようにスペース区切りで 1 つだけ値を渡すと、後続トークンがパス扱いされやすいため `--new=VALUE` のように `=` 付きで指定するのが確実です。
-
-## 開発方針
-
-- **便利さが最優先** – 既存の Ruby スクリプトを最小の手間で CLI 化できることを目的にしており、Python Fire の完全移植は目指していません。
-- **インスパイアであってポートではない** – アイデアの出自は Fire ですが、同等機能を揃える予定は基本的にありません。Fire 由来の未実装機能は仕様です。
-- **メソッド定義が土台、コメントが挙動を補強** – 公開メソッドのシグネチャが CLI に露出する範囲と必須／任意を決めますが、コメントに `TAG...` や `[Integer]` を書くと同じ引数でも配列化や型変換が行われます。さらに Rubycli は `--names='["Alice","Bob"]'` のような JSON/YAML らしい入力を自動的に安全なリテラルとして評価します。`rubycli --check パス/対象.rb` でコメントと実装のズレ（未定義の型ラベルや列挙値の誤記を含む）を DidYouMean の候補付きで検査し、通常実行時に `--strict` を付ければドキュメント通りでない入力をその場でエラーにできます。
-- **軽量メンテナンス** – 実装の多くは AI 支援で作られており、深い Ruby メタプログラミングを伴う大規模拡張は想定外です。Fire 互換を求める PR は事前相談をお願いします。
-
-## 特徴
+### 3. （任意）スクリプトにランナーを組み込む
 
-- コメントベースで CLI オプションやヘルプを自動生成
-- YARD 形式と `NAME [Type] 説明…` の簡潔記法を同時サポート
-- 引数はデフォルトで安全なリテラルとして解釈し、必要に応じて厳格 JSON モードや Ruby eval モードを切り替え可能
-- `--pre-script`（エイリアス: `--init`）で任意の Ruby コードを評価し、その結果オブジェクトを公開
-- `--check` でコメント整合性を lint、`--strict` で入力値をドキュメント通りに強制する二段構えのガード
-- `examples/new_mode_runner.rb` ではインスタンス専用クラスを `--new=VALUE` で初期化し、eval/JSON モードや pre-script を組み合わせる例を示しています。
-
-### サンプル / 付属例
-
-- `examples/hello_app.rb` / `examples/hello_app_with_docs.rb`: 最小のモジュール関数とドキュメント付きの版
-- `examples/typed_arguments_demo.rb`: 標準ライブラリ型 (Date/Time/BigDecimal/Pathname) の coercion
-- `examples/strict_choices_demo.rb`: リテラル列挙と `--strict` の組み合わせ
-- `examples/new_mode_runner.rb`: インスタンス専用クラスを `--new=VALUE` で初期化し、eval/JSON/pre-script を組み合わせる例
-
-#### サンプルコマンド
-
-- `rubycli examples/new_mode_runner.rb run --new='["a","b","c"]' --mode reverse`
-- `rubycli --json-args --new='["x","y"]' examples/new_mode_runner.rb run --mode summary --options '{"source":"json"}'`
-- `rubycli --eval-args --new='["x","y"]' examples/new_mode_runner.rb run --mode summary --options '{tags: [:a, :b]}'`
-- `rubycli --pre-script 'NewModeRunner.new(%w[a b c], options: {from: :pre})' examples/new_mode_runner.rb run --mode summary`
-
-> 補足: `--strict` はコメントに書かれた型／許可値をそのまま信頼して検証するため、コメントが誤記だと実行時には検出できません。CI では必ず `rubycli --check` を走らせ、`--strict` は「 lint を通過したドキュメントを本番で厳密に守る」用途に使ってください。
-
-## Python Fire との違い
-
-- **コメント対応のヘルプ生成**: コメントがあればヘルプに反映しつつ、最終的な判断は常にライブなメソッド定義に基づきます。
-- **型に基づく解析**: `NAME [String]` や YARD タグから型を推論し、真偽値・配列・数値などを自動変換します。
-- **厳密な整合性チェック**: `rubycli --check` でコメントと実装のズレ（未定義の型ラベルや列挙値の誤記など）をコード実行前に検査し、通常実行時に `--strict` を付ければドキュメントで宣言した型・許可値以外の入力を拒否できます。
-- **Ruby 向け拡張**: キーワード引数やブロック (`@yield*`) といった Ruby 固有の構文に合わせたパーサや `RUBYCLI_*` 環境変数を用意しています。
-
-| 機能 | Python Fire | Rubycli |
-| ---- | ----------- | -------- |
-| 属性の辿り方 | オブジェクトを辿ってプロパティ/属性を自動公開 | 対象オブジェクトの公開メソッドをそのまま公開（暗黙の辿りは無し） |
-| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` 指定時だけ初期化（コンストラクタ引数は `--new=VALUE` で渡せる。YAML/JSON らしいリテラルは安全にパース、`--json-args` / `--eval-args` / `--eval-lax` も適用可能。より複雑なら pre-script や自前ファクトリを利用） |
-| インタラクティブシェル | コマンド未指定時に Fire REPL を提供 | インタラクティブモード無し。コマンド実行専用 |
-| 情報源 | 反射で引数・プロパティを解析 | ライブなメソッド定義を基点にしつつコメントをヘルプへ反映 |
-| 辞書/配列 | dict/list を自動でサブコマンド化 | クラス/モジュールのメソッドに特化（辞書自動展開なし） |
-
-## インストール
-
-Rubycli は RubyGems からインストールできます。
-
-```bash
-gem install rubycli
-```
-
-Bundler 例:
-
-```ruby
-# Gemfile
-gem "rubycli"
-```
-
-## クイックスタート（Rubycli をスクリプトに組み込む）
-
-ステップ3では `require "rubycli"` を追加し、スクリプト自身から CLI を起動できるようにします。
+`ruby スクリプト.rb ...` の形で起動したい場合は、gem を require して
+`Rubycli.run` に委譲します（`examples/hello_app_with_require.rb` として同梱）。
 
 ```ruby
-# hello_app.rb
+# hello_app_with_require.rb
 require "rubycli"
 
 module HelloApp
@@ -247,133 +200,206 @@ end
 Rubycli.run(HelloApp)
 ```
 
-実行例:
-
 ```bash
-ruby hello_app.rb greet Taro
-#=> Hello, Taro!
-
-ruby hello_app.rb greet Taro --shout
+ruby examples/hello_app_with_require.rb greet Taro --shout
 #=> HELLO, TARO!
 ```
 
-`require "rubycli"` を書かなくても、付属コマンドから同じファイルを実行できます:
+付属の `rubycli` コマンド経由で実行した場合は、メソッドの戻り値が自動で標準出力に表示されます。
+
+戻り値は標準出力、警告・エラー・失敗時に表示される usage は標準エラー出力へ送られます。
+そのため `rubycli app.rb command > result.json` としても診断メッセージが結果へ混ざらず、
+失敗時は終了コードが 0 以外になります。
+
+## 対象定数の解決
+
+Rubycli は「ファイル名を CamelCase にした定数」を公開対象と想定します。
+一致しない場合の挙動はモードで切り替えられます。
+
+| モード | 有効化方法 | 挙動 |
+| --- | --- | --- |
+| `strict`（既定） | 何もしない / `RUBYCLI_AUTO_TARGET=strict` | CamelCase 名が一致しないとエラー。検出した定数一覧と再実行方法を表示します。 |
+| `auto` | `--auto-target` / `-a` / `RUBYCLI_AUTO_TARGET=auto` | CLI として実行できる定数がファイル内に 1 つだけなら自動選択します。 |
+
+ファイルパスの後ろに定数名を明示することもできます。1 ファイルに候補が複数ある場合や、
+ネストした定数を選びたい場合に便利です。同梱サンプルでは
+`examples/multi_constant_runner.rb` が `MultiConstantRunner` と `HelperRunner` を、
+`examples/mismatched_constant_runner.rb` が `FriendlyGreeter` だけを定義しています。
 
 ```bash
-rubycli path/to/hello_app.rb greet --shout Hanako
+# ファイル名と一致しない定数を明示（既定の strict モードでも動く）
+rubycli examples/multi_constant_runner.rb HelperRunner inspect
+#=> Helper invoked   # メソッド自身が出力した行
+#=> :helper          # 戻り値を rubycli が出力した行
+
+# auto モードなら候補が 1 つだけのファイルを自動選択
+rubycli -a examples/mismatched_constant_runner.rb greet Hanako --message Hi
+#=> Hi, Hanako!      # メソッド自身が出力した行
+#=> Hi, Hanako!      # 同じ文字列が戻り値として出力される（--quiet を付けると 1 行になる）
 ```
 
-クラス／モジュール名を省略した場合でも、ファイル名に対応する定義を自動で推測し、ネストした `Module1::Inner::Runner` のようなクラスも見つけ出します。CLI から実行するとメソッドの戻り値は常に標準出力へ表示されます。
+`Outer::Inner::Runner` のようなネストした定数も、完全修飾名を渡せば検出できます。
 
-別の定数を明示的に指定したい場合は、ファイルパスの後ろに続けてください:
+## インスタンスメソッド専用クラスと `--new`
+
+公開メソッドがインスタンス側にしかないクラスは、`--new` を付けて事前にインスタンス化しないと
+CLI から呼び出せません（Rubycli から見えるコマンドが 1 つもない状態になります）。
+
+- `--new` を付けると `--help` の一覧にインスタンスメソッドが現れ、
+  `rubycli --check --new` でコメントの lint も実行できます。
+- コンストラクタに引数が必要な場合は、**ファイルパスより前に** `--new=VALUE` の形で渡します。
+  値は安全な YAML/JSON ライクなリテラルとして解釈され、`initialize` に付けたコメントも
+  通常の CLI メソッドと同様に型変換へ反映されます。
+- `--new=VALUE` が渡せるのは **値 1 つだけ** で、コンストラクタの第 1 引数に束縛されます。
+  `--new='["a","b","c"]'` はこの配列を 1 個の引数として渡します。配列が複数の引数へ
+  展開されたり、ハッシュがキーワード引数になったりはしません。引数が 2 つ以上必要な場合や
+  キーワード引数を渡したい場合は `--pre-script` を使ってください。
+- スペース区切りの `--new VALUE` は値がファイルパスと誤認されやすいため、
+  `--new=VALUE` の形を推奨します。
+- インスタンスを返す `--pre-script` はそれ自体でインスタンスメソッドを公開できるため、
+  `--new` と併用しなくても単独で使えます。
+
+実行例（`examples/new_mode_runner.rb`）:
 
 ```bash
-rubycli scripts/multi_runner.rb Admin::Runner list --active
+rubycli --new='["a","b","c"]' examples/new_mode_runner.rb run --mode reverse
+```
+
+```text
+[
+  "c",
+  "b",
+  "a"
+]
 ```
 
-1つのファイルに複数の候補がある場合や、ファイル名と異なるネストした定義を選びたいときに便利です。
+コマンドが構造を返した場合、戻り値は整形済み JSON として出力されます。
 
 ## コメント記法
 
+YARD タグと短縮形のどちらでも書けます。
+
 | 用途 | YARD 互換 | Rubycli 標準 |
 | ---- | --------- | ----------- |
 | 位置引数 | `@param name [Type] 説明` | `NAME [Type] 説明` |
 | キーワード引数 | 同上 | `--flag -f VALUE [Type] 説明` |
 | 戻り値 | `@return [Type] 説明` | `=> [Type] 説明` |
 
-短いオプション（`-f` など）は任意で、登場順も自由です。Rubycli 標準の書き方では次の例が同義になります。
+短いオプション（`-f` など）は任意で、順序も自由です。次の 3 つは同義です。
 
 - `--flag -f VALUE [Type] 説明`
 - `--flag VALUE [Type] 説明`
 - `-f --flag VALUE [Type] 説明`
 
-README のサンプルは既定スタイルとして大文字プレースホルダ（`NAME`, `VALUE` など）を使用しています。次項以降の表記揺れは、必要に応じて選べる追加記法です。
+型は `[String]` でも `(String)` でも指定でき、`(String, nil)` のように複数型も書けます。
 
 ### 互換プレースホルダ表記
 
-コメントやヘルプ出力では次の表記も同じ意味として解釈されます。
+コメントの解析とヘルプ出力の両方で、次の表記も同じ意味として扱われます。
 
-- 山括弧で値を明示: `--flag <value>`, `NAME [<value>]`
-- ロングオプションの `=` 付き表記: `--flag=<value>`
+- 山括弧: `--flag <value>`, `NAME [<value>]`
+- `=` 付きロングオプション: `--flag=<value>`
 - 繰り返し指定: `VALUE...`, `<value>...`
 
-実行時には `--flag VALUE`, `--flag <value>`, `--flag=<value>` のどれで入力しても同じ扱いです。プロジェクトで読みやすいスタイルを選択してください。`[VALUE]` や `[VALUE...]` のような表記を使うと、真偽値・任意値・リストなどの推論が働きます。値プレースホルダを省略したオプション（例: `--quiet`）は自動で Boolean フラグとして扱われます。
-
-> 補足: コメント内で任意引数を角括弧で表す必要はありません。Ruby 側のメソッドシグネチャから必須／任意は自動判定され、ヘルプ出力では Rubycli が適切に角括弧を追加します。
+実行時には `--flag VALUE`, `--flag <value>`, `--flag=<value>` のどれも同じ扱いなので、
+プロジェクトで読みやすいスタイルを選んでください。任意引数を自分で角括弧に包む必要は
+ありません。必須／任意は Ruby のメソッドシグネチャから自動判定され、ヘルプ出力では
+Rubycli が角括弧を補います。
 
-型ヒントは `[String]` や `(String)` のように角括弧／丸括弧で指定できます。複数型は `(String, nil)` のように列挙してください。
+注釈が部分的な場合の推論規則:
 
-`VALUE...` のような繰り返し指定（`TAG...` など）や、`[String[]]` / `Array<String>` といった配列型の注釈が付いたオプションは配列として扱われます。JSON/YAML 形式のリスト（例: `--tags '["build","test"]'`）を渡すか、カンマ区切り文字列（`--tags "build,test"`）を渡すことで配列に変換されます。スペース区切りの複数値入力（`--tags build test`）にはまだ対応しておらず、繰り返し注記のないオプションは従来どおりスカラーとして扱われます。`--strict` 実行時は各要素の型も検証されるため、`[String[]]` と書かれているのに `--tags [1,2]` のような数値配列を渡すと即エラーになります。
+- `ARG1` のように型を省略したプレースホルダは `String` として扱われます。
+- 値プレースホルダのないオプション（`--verbose`）は Boolean フラグになります。
+- 位置引数を Boolean にするには `[Boolean]` の明示が必要です。`NAME 説明` のように
+  型を省略すると、Ruby 側のデフォルト値に関わらず `String` とみなされます。
 
-JSON やカンマ区切りで表現しづらいシンボル配列・ハッシュなどを渡したい場合は eval モード（`--eval-args`/`-e` または `--eval-lax`/`-E`）を有効にし、ドキュメントで宣言した型に合わせた Ruby リテラルを渡してください。スペース区切りが未対応でも、安全に複数選択を指定できます（後述の eval 例を参照）。
+### 配列と繰り返し値
 
-代表的な推論例:
+`TAG...` のような繰り返し指定、または `[String[]]` / `Array<String>` のような配列型注釈が
+付いたオプションは配列としてパースされます。JSON/YAML 形式のリスト
+（`--tags '["build","test"]'`）とカンマ区切り文字列（`--tags "build,test"`）の両方を
+受け付けます。スペース区切りの複数値（`--tags build test`）には対応しておらず、
+繰り返し注記のないオプションはスカラーのままです。`--strict` 実行時は各要素の型も
+検証されるため、`[String[]]` と書かれた注釈に対して `--tags [1,2]` を渡すとエラーになります。
+`--tags '["true","null"]'` のように引用された要素は、別のリテラルに見える内容でも文字列の
+まま保持されます。
 
-- `ARG1` のように型ラベルを省略したプレースホルダは既定で `String` として扱われます。
-- `--name ARG1` のようにオプションへプレースホルダだけを指定しても同じく `String` が推論されます。
-- `--verbose` のように値プレースホルダを省略したオプションは Boolean フラグとして扱われます。
-- 位置引数を Boolean にしたい場合は必ず `[Boolean]` を明示してください。`NAME 説明` や `@param name 説明` のように型を省略すると、Ruby 側のデフォルト値に関わらず `String` とみなされます。
+### リテラル列挙（enum）
 
-### リテラル列挙による制約
+許容値の集合を型注釈の中に直接書けます: `--format MODE [:json, :yaml, :auto]`、
+`LEVEL [:info, :warn]` など。シンボル・文字列（裸の単語も可）・真偽値・数値・`nil` に対応し、
+`--channel TARGET [:stdout, :stderr, Boolean]` のように通常の型とも混在できます。
+`%i[info warn]` / `%w[debug info]` の短縮記法も展開されます。選択肢は常にヘルプへ表示され、
+許可外の値は `--strict` なしなら警告のみで続行、`--strict` 付きなら中断します。
 
-`--format MODE [:json, :yaml, :auto]` や `LEVEL [:info, :warn]` のように型注釈内へ許容リテラルを列挙すると、ヘルプに選択肢を表示しつつ Rubycli が入力制約として解釈します。シンボル・文字列（裸の単語も可）・真偽値・数値・`nil` に対応し、型ヒントと混在させて `--channel TARGET [:stdout, :stderr, Boolean]` のような宣言も書けます。`%i[info warn]` / `%w[debug info]` などの短縮記法も展開されるため、`LEVEL %i[info warn]` でも同じ効果になります。通常実行では許可外の入力に警告を表示して続行し、`--strict` を付けた場合は `Rubycli::ArgumentError` を送出して即座に停止します。
-
-> シンボルと文字列は厳密に区別されます。`[:info, :warn]` と書いた場合は `:info` のようにコロン付きで入力してください。`["info", "warn"]` を選んだ場合はプレーンな文字列のみ受け付けます。
-
-> 列挙は各スカラー値に適用されます。`[Symbol[]]` のような配列注釈に対して「許可される組み合わせ」をリテラルで書く構文（例: `[%i[foo bar][]]`）は未サポートなので、必要に応じて文章で説明するか、eval モードで Ruby の配列を渡してください。
+シンボルと文字列は厳密に区別されます。`[:info, :warn]` にはコロン付きの `:info` を、
+`["info", "warn"]` にはプレーンな文字列を入力してください。
 
 ```bash
-# literal choice デモ (examples/strict_choices_demo.rb)
-ruby examples/strict_choices_demo.rb report warn --format json
-#=> [WARN] format=json
+# examples/strict_choices_demo.rb — LEVEL の注釈は [:info, :warn, :error]
+rubycli examples/strict_choices_demo.rb report :warn --format json
+#=> [WARN] format=json   （続けて戻り値のハッシュが表示される）
 
-# --strict を付けると仕様外の値で即エラー
-ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report debug
-#=> Rubycli::ArgumentError: Value "debug" for LEVEL is not allowed: allowed values are :info, :warn, :error
-```
+# 裸の文字列はシンボルと一致しない: 警告して続行
+rubycli examples/strict_choices_demo.rb report warn
+#=> [WARN] LEVEL must be one of :info, :warn, :error (received "warn") (use --strict to abort on invalid input)
 
-```bash
-# シンボル入力はコロンを付ける
-ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report :warn
-#=> [WARN] format=text
-
-ruby -Ilib exe/rubycli --strict examples/strict_choices_demo.rb report warn
-#=> Rubycli::ArgumentError: Value "warn" for LEVEL is not allowed: allowed values are :info, :warn, :error
+# --strict を付けると許可外の入力で中断
+rubycli --strict examples/strict_choices_demo.rb report debug
+#=> [ERROR] LEVEL must be one of :info, :warn, :error (received "debug")
 ```
 
-### 標準ライブラリ型ヒント
+列挙は各スカラー引数に適用されます。`[%i[foo bar][]]` のような「配列の許容組み合わせ」を
+リテラルで書く構文は未サポートです。
+
+### 標準ライブラリの型ヒント
 
-コメントに `Date` や `Time`, `BigDecimal`, `Pathname` など標準ライブラリの型名を書けば、Rubycli が必要な `require` を行った上で CLI 引数をその型へ変換します。
+コメントに `Date`、`Time`、`BigDecimal`、`Pathname` などの標準クラスを書くと、
+Rubycli が必要な stdlib を読み込んだ上で CLI 入力をその型へ変換します。
+ハンドラには実際のオブジェクトが渡るため、追加のパース処理は不要です。
 
 ```bash
-# examples/typed_arguments_demo.rb より
-ruby examples/typed_arguments_demo.rb ingest \
+# examples/typed_arguments_demo.rb を参照
+rubycli examples/typed_arguments_demo.rb ingest \
   --date 2024-12-25 \
   --moment 2024-12-25T10:00:00Z \
   --budget 123.45 \
   --input ./data/input.csv
 ```
 
-ハンドラ側には `Date` / `Time` / `BigDecimal` / `Pathname` のインスタンスがそのまま渡るため、追加のパース処理は不要です。
+各オプションには既定値があるため、`... ingest --budget 999.99` のように
+1 つずつ試すこともできます。
 
-各オプションには既定値があるため、`ruby examples/typed_arguments_demo.rb ingest --budget 999.99` のように個別の型だけ試すこともできます。
+`@example`、`@raise`、`@see`、`@deprecated` などその他の YARD タグは、
+現状ヘルプ出力には反映されません。
 
-`@example` や `@raise`, `@see`, `@deprecated` などその他の YARD タグは、現状ヘルプ出力には反映されません。
+> すべての記法をまとめて試すには
+> `rubycli examples/documentation_style_showcase.rb canonical --help` などの
+> showcase コマンドを実行してください。
 
-> すべての記法をまとめて試したい場合は `rubycli examples/documentation_style_showcase.rb canonical --help` や `... angled --help` などを実行してみてください。
+### YARD 互換コメントを併用する際の注意
 
-従来の `@param` 記法も既定で利用できます。簡潔なプレースホルダ記法だけに限定したい場合は `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` を設定してください（厳格モードでの検証は継続されます）。
+- `**kwargs` を受け取るメソッドでも、キーは自動では公開されません。CLI で使わせたいキーは
+  すべて `--long-name PLACEHOLDER [Type] 説明` の行として明示してください。
+- `@param` 行に続く箇条書きや補足行は CLI 生成には使われません。補足情報は
+  オプションの説明文に含めてください。
+- 簡潔なプレースホルダ記法へ移行したい場合は `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` を設定して
+  `rubycli --check` を実行します。`@param` 行がドキュメント不整合として報告され（その lint
+  実行中は無視され）、書き換えが必要な箇所を洗い出せます。これは lint 用のスイッチであり
+  実行時の制限ではありません。通常実行では `@param` は従来どおり有効で、`@return` は
+  この設定の対象外です。
 
-### コメントが不足している場合のフォールバック
+### コメントが不足している場合
 
-Rubycli は常に実装中のメソッドシグネチャを信頼します。コメントに書いていない引数やオプションがあっても、定義そのものから名前や初期値を推論して CLI に表示します。
+Rubycli は常に実装のメソッドシグネチャを信頼します。コメントに書かれていない引数も、
+定義から名前・既定値・型を推論して CLI に公開されます。
 
 ```ruby
-# fallback_example.rb
+# examples/fallback_example.rb
 module FallbackExample
   module_function
 
-  # AMOUNT [Integer] 処理対象の数値
+  # AMOUNT [Integer] Base amount to process
   def scale(amount, factor = 2, clamp: nil, notify: false)
     result = amount * factor
     result = [result, clamp].min if clamp
@@ -383,20 +409,6 @@ module FallbackExample
 end
 ```
 
-```bash
-rubycli examples/fallback_example.rb
-```
-
-```text
-Usage: fallback_example.rb COMMAND [arguments]
-
-Available commands:
-  Class methods:
-    scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
-
-Detailed command help: fallback_example.rb COMMAND help
-```
-
 ```bash
 rubycli examples/fallback_example.rb scale --help
 ```
@@ -405,109 +417,202 @@ rubycli examples/fallback_example.rb scale --help
 Usage: fallback_example.rb scale AMOUNT [FACTOR] [--clamp=<CLAMP>] [--notify]
 
 Positional arguments:
-  AMOUNT  [Integer]  required  処理対象の数値
-  FACTOR             optional  (default: 2)
+  AMOUNT  [Integer]  required  Base amount to process
+  FACTOR  [String]   optional  (default: 2)
 
 Options:
   --clamp=<CLAMP>  [String]   optional  (default: nil)
   --notify         [Boolean]  optional  (default: false)
 ```
 
-`AMOUNT` だけがドキュメント化されていますが、`factor` や `clamp`, `notify` も自動的に補完され、既定値や型が推論されていることがわかります。開発時は `rubycli --check 対象.rb` でコメントとシグネチャの矛盾を検出し、本番実行で `--strict` を付ければ仕様外の入力をその場で弾けます。
+ドキュメント化されているのは `AMOUNT` だけですが、`factor`・`clamp`・`notify` も
+推論された既定値・型付きで表示されます。
 
-#### 存在しない引数やオプションをコメントに書いた場合
+コメントだけで実引数が増えることはありません。実装に存在しないオプション（例: `--ghost`）や
+位置引数をコメントに書いた場合、その行はヘルプ末尾の詳細セクションに素のテキストとして
+表示されるだけで、strict モードでは位置引数のズレに対する警告も出ます。動作するデモ:
+`rubycli examples/fallback_example_with_extra_docs.rb scale --help`
 
-- **整合しないコメントは詳細テキストへフォールバック** – 実装に存在しないオプション（例: `--ghost`）や位置引数（例: `EXTRA`）を記述すると、その行はヘルプ末尾の詳細セクションに素のテキストとして表示され、実際の引数としては機能しません。厳格モードなら `Extra positional argument comments were found: EXTRA` のような警告が出て、位置引数のズレにも気付きやすくなります。
+開発中は `rubycli --check 対象.rb` でコメントと実装のズレ（未定義の型ラベルや列挙値の
+誤記を含む。DidYouMean の候補付き）を検出し、実行時に `--strict` を付ければ仕様外の
+入力を警告ではなくエラーにできます。なお `--check` も実際のシグネチャを読むために対象
+ファイルを load するため、トップレベルのコードは実行されます（例えば
+`examples/hello_app_with_require.rb` は load 時に `Rubycli.run` を呼びます）。
+`--check` が行わないのは、選択したコマンドの実行です。
 
-> 実際に確認したい場合は `rubycli examples/fallback_example_with_extra_docs.rb scale --help` を試してみてください。
+> `--strict` はコメントに書かれた型・許容値をそのまま信頼します。コメント自体の誤記は
+> 実行時には検出できないため、CI で `rubycli --check` を回した上で `--strict` を
+> 使ってください。
 
-コメントだけでは実装を拡張できません。メソッドシグネチャとコメントを一致させておくことで、ヘルプと挙動の整合性を保てます。
+## 引数解析モード
 
-### YARD 互換コメントを併用する際の注意点
+### 既定のリテラル解析
 
-- `**kwargs` を受け取るメソッドでも、Rubycli は個別のキーワードコメント（`--config-path ...` など）が無い限りヘルプへ露出させません。CLI で使わせたいキーはすべて `--LONG-NAME PLACEHOLDER [Type] 説明` の行として明示してください。
-- `@param` で位置引数を記述した場合も解析できますが、位置引数・キーワード引数を同じ行形式で列挙する必要があります。`@param source Path` のように書いても、キーワード向けのロングオプションが自動生成されるわけではありません。
-- `@param` の行に続く箇条書きや補足行は CLI の自動生成には使われません。補足情報を表示したい場合は、`--flag ...` 行の説明に含めるか、README など別のドキュメントで扱ってください。
-- `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` にすると `@param`/`@return` などのタグは警告扱いになります。プロジェクト内で簡潔記法へ統一するときはこの環境変数で段階的に移行できます。
+`{`、`[`、クォート、YAML 記号で始まる「構造化リテラルらしい」引数は `Psych.safe_load` で
+解釈され、`--names='["Alice","Bob"]'` や `--config='{foo: 1}'` は追加フラグなしで
+ネイティブな配列・ハッシュとして届きます。`1,2,3` のようなプレーンな文字列はこの段階では
+そのまま維持され（コメントで `String[]` や `TAG...` と宣言されていれば後段で配列化）、
+解釈できない形式は元の文字列にフォールバックします。`"2024-01-01"` は文字列のまま届き、
+構文が崩れた入力でも実行全体は落ちません。
 
-## 引数解析モード
+引数が素の `[String]` としてドキュメント化されている場合は、リテラル解析よりコメント由来の
+変換が優先され、入力トークンがそのまま渡ります（引用符も含む）。そのため
+`--prefix '"quoted"'` は引用符付きの `"quoted"` として届き、注釈のない引数なら
+`quoted` として届きます。
 
-### 既定のリテラル解析
+### JSON モード（`--json-args` / `-j`）
 
-Rubycli は `{` や `[`、クォート、YAML の先頭記号といった「構造化リテラルらしい」形の引数に対して `Psych.safe_load` を試み、成功すれば Ruby の配列／ハッシュ／真偽値に変換してからメソッドへ渡します。たとえば `--names='["Alice","Bob"]'` や `--config='{foo: 1}'` のような値は追加フラグ無しでネイティブな配列・ハッシュとして届きます。一方、プレーンな `1,2,3` のような文字列はこの段階ではそのまま維持されます（コメントで `String[]` や `TAG...` と宣言されている場合は後段で配列に整形されます）。扱えない形式は自動的に文字列へフォールバックするため、`"2024-01-01"` のような値もそのまま文字列で受け取れますし、構文が崩れていても CLI 全体が落ちることはありません。
+後続の引数を厳格に JSON として解釈します。YAML 固有の記法は拒否され、無効な JSON は
+`JSON::ParserError` になるため、silent fallback ではなく明示的な失敗が欲しい場合に
+便利です。プログラムからは `Rubycli.with_json_mode(true) { ... }` で切り替えられます。
 
-### JSON モード
+### Eval モード（`--eval-args` / `-e`、`--eval-lax` / `-E`）
 
-CLI 実行時に `--json-args`（短縮形 `-j`）を付けると、後続の引数が厳格に JSON として解釈されます。
+各引数を Ruby 式として評価してから渡します。シンボル配列・Range・インライン計算など、
+JSON では書きにくい値に便利です。
 
 ```bash
-rubycli -j my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
-```
+# シンボルや %w リテラルがそのままオブジェクトとして届く
+rubycli -e --new='%w[x y]' examples/new_mode_runner.rb run --mode ':reverse'
+#=> ["y", "x"]
 
-YAML 固有の書き方は拒否され、無効な JSON であれば `JSON::ParserError` が発生するため、入力の妥当性を強く保証したいときに便利です。プログラム側では `Rubycli.with_json_mode(true) { … }` で有効化できます。
+# インライン計算は、コメント由来の型変換より先に評価される
+rubycli -e examples/documentation_style_showcase.rb canonical '"Foo"' '2*3'
+#=> {"style": "canonical", "subject": "Foo", "count": 6, ...}
+```
 
-### Eval モード
+`--eval-args` では **すべての引数** が有効な Ruby でなければならないため、
+`--mode summary` のような裸の単語はエラーになります。`':summary'`（または
+`'"summary"'`）と書くか、後述の `--eval-lax` を使ってください。
 
-`--eval-args`（短縮形 `-e`）を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON や YAML では表現しづらいオブジェクトを扱いたいときに便利ですが、評価は `Object.new.instance_eval { binding }` 上で行われるため、信頼できる入力に限定してください。コード内では `Rubycli.with_eval_mode(true) { … }` で切り替えられます。
+評価は隔離された binding（`Object.new.instance_eval { binding }`）内で行われます。
+1回の Runner 実行では、`--new=VALUE` のコンストラクタ引数と選択したコマンドの引数を含む
+すべての eval 引数が同じ binding を共有し、実行終了時に破棄されます。入力そのものは
+信頼できる呼び出し元に限定してください。プログラムからは
+`Rubycli.with_eval_mode(true) { ... }` で切り替えられます。
 
-Ruby 評価はシンボルや配列／ハッシュもそのまま扱えるため、列挙値の組み合わせをオプションへ渡すときにも役立ちます。
+`--eval-lax` / `-E` は `--eval-args` と同様に eval モードを有効にしつつ、Ruby として
+解釈できなかったトークン（例: 素の `https://example.com`）は警告を出して元の文字列の
+まま渡します。`60*60*24*14` のような式と通常の文字列を混在させたいときに便利です。
 
 ```bash
-rubycli -E scripts/report_runner.rb publish \
-  --targets '[:marketing, :sales]' \
-  --channels '[:email, :slack]'
+rubycli -E examples/hello_app.rb greet https://example.com
+#=> [WARN] Failed to evaluate argument as Ruby (...). Passing it through because --eval-lax is enabled.
+#=> Hello, https://example.com!
 ```
 
-Ruby 評価を使いつつ、構文エラーが出たときは元の文字列にフォールバックさせたい場合は `--eval-lax`（短縮形 `-E`）を指定します。`--eval-args` と同じく eval モードを有効にしますが、Ruby として解釈できなかったトークン（例: 素の `https://example.com`）は警告を出した上でそのまま渡すため、`60*60*24*14` のような式と文字列を気軽に混在させられます。
-
-`--json-args`/`-j` は `--eval-args`/`-e` および `--eval-lax`/`-E` と同時指定できません。どのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval（通常／lax）のいずれかを選択してください。
+`--json-args` と eval 系フラグは同時指定できません（両方あるとエラーになります）。
 
 ## Pre-script ブートストラップ
 
-付属 CLI を起動するときに `--pre-script SRC`（別名: `--init`）を指定すると、公開メソッドを呼び出す前に任意の Ruby コードを評価できます。評価は隔離された binding 内で行われ、以下のローカル変数があらかじめ用意されています。
+`--pre-script SRC`（別名: `--init`）を付けると、コマンド解決の前に任意の Ruby コードを
+評価できます。評価は隔離された binding 内で行われ、次のローカル変数が用意されています。
 
-- `target` – `--new` を適用する前のクラス／モジュール
-- `current` / `instance` – 現在公開予定のオブジェクト（`--new` を指定した場合は生成済みインスタンス）
+- `target` — 元のクラス／モジュール（`--new` 適用前）
+- `current` / `instance` — そのまま公開される予定のオブジェクト
 
-スクリプトの最後に評価された値が新しい公開対象になります。`nil` を返した場合は直前のオブジェクトを維持します。
+最後に評価された値が新しい公開対象になります（`nil` を返すと直前のオブジェクトを維持）。
+`SRC` にはインラインの Ruby コードとファイルパスのどちらも指定できます。
 
-インラインで書く例:
+実行例 — `--new` で作られるインスタンスを、自分で組み立てたものに差し替える:
 
 ```bash
-rubycli --pre-script 'InitArgRunner.new(source: "cli", retries: 2)' \
-  lib/init_arg_runner.rb summarize --verbose
+rubycli --pre-script 'NewModeRunner.new(%w[a b c], options: {from: :pre})' \
+  examples/new_mode_runner.rb run --mode summary
 ```
 
-ファイルに切り出す例:
+## フラグと環境変数
 
-```ruby
-# scripts/bootstrap_runner.rb
-instance = InitArgRunner.new(source: "preset")
-instance.logger = Logger.new($stdout)
-instance
-```
+| フラグ / 環境変数 | 説明 | 既定値 |
+| ---------------- | ---- | ------ |
+| `--auto-target` / `-a`, `RUBYCLI_AUTO_TARGET=auto` | ファイル名と定数名が一致しないときに自動選択 | `strict` |
+| `--new[=VALUE]` / `-n[=VALUE]` | コマンド解決前にインスタンス化。`VALUE` はコンストラクタの第 1 引数 | off |
+| `--pre-script SRC` / `--init SRC` | 公開対象オブジェクトを Ruby コードで構築・差し替え | off |
+| `--check` / `-c` | コメントと実装のズレを検査（コマンドは実行しない） | off |
+| `--strict` | ドキュメントの型・許容値を強制。仕様外入力はエラー | off |
+| `--json-args` / `-j` | 引数を厳格に JSON として解釈 | off |
+| `--eval-args` / `-e`, `--eval-lax` / `-E` | 引数を Ruby として評価（lax は失敗時に素の文字列へフォールバック） | off |
+| `--help` / `-h` / `help` | `rubycli` の使い方を表示 | — |
+| `--print-result`, `RUBYCLI_PRINT_RESULT=true` | 戻り値を標準出力へ表示。同梱の `rubycli` コマンドでは既定で有効なので、`Rubycli.run` を自分のスクリプトへ組み込む場合に効く | `rubycli` は on、`Rubycli.run` は off |
+| `RUBYCLI_DEBUG=true` | デバッグログを表示 | `false` |
+| `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` | `rubycli --check` 実行時に YARD `@param` 行を不整合として報告（通常実行には影響しない） | `ON` |
+
+## ライブラリ API
+
+- `Rubycli.parse_arguments(argv, method)` — コメント情報を考慮した引数解析
+- `Rubycli.available_commands(target)` — 公開 CLI コマンド一覧
+- `Rubycli.usage_for_method(name, method)` — 指定メソッドのヘルプ生成
+- `Rubycli.method_description(method)` — 構造化されたドキュメント取得
+
+## Python Fire との違い
+
+- **コメント対応のヘルプ生成** — コメントはヘルプを豊かにしますが、最終的な判断は常に
+  ライブなメソッド定義に基づきます。
+- **型に基づく解析** — プレースホルダ記法と YARD タグから、真偽値・配列・数値などへ
+  追加コードなしで変換します。
+- **二段構えの検証** — `--check` はコマンドを実行せずにドキュメントのズレを lint し、
+  `--strict` はドキュメントの型・許容値を実行時の契約として強制します。
+- **Ruby 中心の設計** — キーワード引数、ブロックドキュメント（`@yield*` タグ）、
+  `RUBYCLI_*` 環境変数に対応します。
+
+| 機能 | Python Fire | Rubycli |
+| ---- | ----------- | ------- |
+| 属性の辿り方 | プロパティ／属性を再帰的に自動公開 | 対象の公開メソッドのみ公開（暗黙の辿りなし） |
+| クラス初期化 | `__init__` 引数を自動で受け取る | `--new` 指定時のみ初期化。引数は `--new=VALUE`、複雑な構築は pre-script |
+| インタラクティブシェル | コマンド未指定時に Fire REPL | なし。コマンド実行専用 |
+| 情報源 | 純粋なリフレクション | ライブなメソッド定義 + コメントをヘルプへ反映 |
+| 辞書/配列 | dict/list を自動でサブコマンド化 | クラス／モジュールのメソッドに特化（自動展開なし） |
+
+## 開発方針
+
+- **便利さを最優先** — 既存の Ruby スクリプトを最小の手間で CLI 化することが目的です。
+  Python Fire との機能一致は目標ではなく、Fire 由来の未実装機能は基本的に仕様です。
+- **メソッド定義が土台、コメントが補強** — 公開範囲と必須／任意はシグネチャが決め、
+  コメントは型・ヘルプ・検証を補強します。
+- **メンテナンス** — 実装の多くは AI 支援で作られています。現在はメンテナンスを終了して
+  います（[プロジェクトの状態](#プロジェクトの状態)を参照）。
+
+## 同梱サンプル
+
+- `examples/hello_app.rb` / `examples/hello_app_with_docs.rb` — 最小のモジュール関数、
+  ドキュメントなし／あり
+- `examples/hello_app_with_require.rb` — `Rubycli.run` の組み込み
+- `examples/typed_arguments_demo.rb` — 標準ライブラリ型の変換
+  （Date/Time/BigDecimal/Pathname）
+- `examples/strict_choices_demo.rb` — リテラル列挙と `--strict`
+- `examples/new_mode_runner.rb` — `--new=VALUE` で初期化するインスタンス専用クラス
+- `examples/documentation_style_showcase.rb` — 全コメント記法のショーケース
+- `examples/fallback_example.rb` / `examples/fallback_example_with_extra_docs.rb`
+  — シグネチャからの補完とコメント不一致のデモ（この 2 つは意図的に
+  `rubycli --check` に落ちます）
+- `examples/multi_constant_runner.rb` / `examples/mismatched_constant_runner.rb`
+  — 定数選択のデモ（1 ファイルに複数候補がある場合と、ファイル名と定数名が
+  一致しない場合）
+
+本 README のコマンドはリポジトリ直下での実行を前提にしています。同じファイルは gem にも
+同梱されているため、`gem install rubycli` 後は `gem contents rubycli` で場所を確認できます。
+
+## 開発
 
 ```bash
-rubycli --pre-script scripts/bootstrap_runner.rb \
-  lib/init_arg_runner.rb summarize --verbose
+bundle install     # minitest / rake / rubocop（Rubycli 本体に実行時依存はありません）
+bundle exec rake   # テスト + RuboCop
 ```
 
-この仕組みを使えば、`--new` のシンプルさを保ったまま、DI 風の初期化やラッパーオブジェクトの準備といった高度な前処理を CLI で行えます。
+個別のタスク:
 
-## 環境変数とフラグ
+- `bundle exec rake test` — Minitest 一式（実際の `exe/rubycli` を子プロセスで起動する
+  E2E テストを含む）
+- `bundle exec rake lint` — RuboCop。未修正の指摘は `.rubocop_todo.yml` で管理しています
+  （大半はパーサ側のメソッド長メトリクス）
+- `bundle exec rake coverage` — テストに加えてリポジトリのカバレッジ基準
+  （全体 line 90%、branch 70%、`origin/main` から変更した実行可能行 90%）を検査
 
-| 変数 / フラグ | 説明 | 既定値 |
-| ------------- | ---- | ------ |
-| `RUBYCLI_DEBUG=true` | デバッグログ表示 | `false` |
-| `--check` | コメント／実装のズレを検査し、コマンドは実行しない | `off` |
-| `--strict` | ドキュメントで許可した型・値以外をエラーとして拒否 | `off` |
-| `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` | レガシーな `@param` 記法を無効化（互換性のため既定では ON） | `ON` |
+カバレッジゲートは外部依存なしで動くため、Bundler なしの
+`ruby -Ilib:test test/coverage_runner.rb` でも実行できます。
 
-## Rubycli API
+## ライセンス
 
-- `Rubycli.parse_arguments(argv, method)` – コメント情報を考慮した引数解析
-- `Rubycli.available_commands(target)` – 公開 CLI コマンド一覧
-- `Rubycli.usage_for_method(name, method)` – 指定メソッドのヘルプ生成
-- `Rubycli.method_description(method)` – 構造化されたドキュメント取得
+MIT。[LICENSE](LICENSE) を参照してください。
 
-ご意見・フィードバックは Issue や Pull Request でお寄せください。
+ご意見・不具合報告は Issue や Pull Request でお寄せください。