rubycli 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9809e4d2f9c1ddb0b97f7c7cede2d665888726952e96ed5b14584e9230c617b
-  data.tar.gz: 538af61eb924c66fdd0bf26df5bdcfaba66fbec76daa70ddbfcef943d2cfa654
+  metadata.gz: a71a438637363ea54e22377b645dc99a26a0c91692571bf57a68368403e32308
+  data.tar.gz: 367b354b2ffde5ee80e7ee3ee5b2858f15cbf8097cc8346fd812b780f41443e2
 SHA512:
-  metadata.gz: efc21b5eddfb00f727ae0a056c7507ee36e27cc3da47c7bad0d68f310862f6cb3f7511328ec9bc2ac40f1493fa9b340892482a858623c57ec6ff8a9069ea9f73
-  data.tar.gz: 1f21f11831d6b90b4981034827c33ac9a27a48385fae73cf22e806b7d5728835209f231977c1ca6f609cecd7bdfe12cae30d74adeaf409e0231e616262ced993
+  metadata.gz: 5eb055a5cbaa3daf0d311b67922a0c9bb7dbb8a75c2844524dc21f5faed232f560c8f1aaea6caf96737fea0b979625813b1ea5cc6c589ecee405b994b07ee16f
+  data.tar.gz: f64107c28083a96674970f8414090e47b77a749f8d3c9393ff9ca972a747ebe36a5da128d1c75a313ca570631436509392985477d1eefe271722eb4b046c69a8

data/CHANGELOG.md

@@ -1,6 +1,47 @@
 # Changelog
 
-## [0.1.0] - Unreleased
+## [0.1.4] - 2025-11-08
+
+### Changed
+- Re-cut the release that was briefly published as 0.1.3 (and yanked) so RubyGems now hosts the complete set of changes listed below.
+
+> _Note:_ 0.1.3 was yanked before general availability; consumers should upgrade directly to 0.1.4.
+
+## [0.1.3] - 2025-11-08
+
+### Added
+- TracePoint-backed constant capture so Rubycli can detect CLI classes/modules even when they are defined indirectly; bundled example and tests illustrate the behavior.
+- Strict/auto constant selection modes with the new `--auto-target` / `-a` flag so single callable constants are picked automatically when requested.
+- `--eval-lax` / `-E` argument mode that evaluates Ruby inputs but gracefully falls back to raw strings on parse failures.
+
+### Changed
+- Argument parsing internals were modularized so JSON/eval coercion now flows through a dedicated controller, simplifying future extensions.
+- `rubycli` now returns explicit status codes for success and failure, improving scriptability.
+- CLI constant selection errors provide clearer guidance, document the `--new` behavior, and consistently refer to the `--auto-target` flag.
+
+### Documentation
+- Clarified the authoritative source for documentation comments, reorganized helper logic in the showcase example, and expanded guidance around constant modes.
+
+### Fixed
+- CLI no longer dumps a Ruby backtrace when `Rubycli::Runner` reports user-facing errors; only the curated guidance is shown.
+
+## [0.1.2] - 2025-11-06
+
+### Added
+- Example `examples/documentation_style_showcase.rb` covering all supported documentation notations.
+- Parenthesised `(Type)` and `(type: Type)` annotations for positional and option documentation.
+
+### Documentation
+- Linked the showcase example from the English and Japanese READMEs to highlight the new syntax.
+- Clarified that optional arguments do not require brackets in comments and noted the current comma-delimited behaviour for repeated values.
+- Documented the refined literal parsing guard rails so only structured values auto-coerce while plain strings stay untouched unless type hints request otherwise.
+
+### Fixed
+- Restored uppercase positional placeholders in the generated help output so the default style stays consistent.
+- Help renderer now preserves documented placeholder casing instead of wrapping everything in `<...>`.
+- Default literal parsing now skips generic strings to avoid collapsing comma-separated inputs, while still supporting array coercion when documentation specifies list types.
+
+## [0.1.1] - 2025-11-01
 
 ### Added
 - Initial public release of Rubycli with the `rubycli` executable for running documented Ruby classes and modules.

data/README.ja.md

@@ -1,6 +1,8 @@
 # Rubycli — Python Fire 風の Ruby 向け CLI
 
-Rubycli は Ruby のクラス／モジュールに書いたコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しています。
+![Rubycli ロゴ](assets/rubycli-logo.png)
+
+Rubycli は Ruby のクラス／モジュールにある公開メソッドの定義と、そのメソッドに付けたドキュメントコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しており、コメントに書いた型ヒントや繰り返し指定が CLI の引数解釈もコントロールします。
 
 > English guide is available in [README.md](README.md).
 
@@ -28,7 +30,7 @@ Usage: hello_app.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name>
+    greet                <NAME>
 
 Detailed command help: hello_app.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -40,10 +42,10 @@ rubycli examples/hello_app.rb greet
 
 ```text
 Error: wrong number of arguments (given 0, expected 1)
-Usage: hello_app.rb greet <NAME>
+Usage: hello_app.rb greet NAME
 
 Positional arguments:
-  NAME
+  NAME    required
 ```
 
 ```bash
@@ -102,7 +104,7 @@ Usage: hello_app_with_docs.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name> [--shout=<value>]
+    greet                <NAME> [--shout]
 
 Detailed command help: hello_app_with_docs.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -113,13 +115,13 @@ rubycli examples/hello_app_with_docs.rb greet --help
 ```
 
 ```text
-Usage: hello_app_with_docs.rb greet <NAME> [--shout]
+Usage: hello_app_with_docs.rb greet NAME [--shout]
 
 Positional arguments:
-  NAME  [String] 挨拶対象
+  NAME  [String]  required  挨拶対象
 
 Options:
-  --shout  [Boolean] 大文字で出力 (default: false)
+  --shout  [Boolean]  optional  大文字で出力 (default: false)
 ```
 
 ```bash
@@ -145,18 +147,31 @@ end
 
 `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 フラグで切り替えられます。
+
+> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`attr_reader` や `def greet`）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。
+
 ## 開発方針
 
 - **便利さが最優先** – 既存の Ruby スクリプトを最小の手間で CLI 化できることを目的にしており、Python Fire の完全移植は目指していません。
 - **インスパイアであってポートではない** – アイデアの出自は Fire ですが、同等機能を揃える予定は基本的にありません。Fire 由来の未実装機能は仕様です。
-- **コードが一次情報、コメントは補助** – メソッド定義こそが真実であり、コメントはヘルプを豊かにする付加情報です。コメントと実装のズレを観測したいときだけ `RUBYCLI_STRICT=ON` で厳格モードを有効化し、警告を受け取ります。
+- **メソッド定義が土台、コメントが挙動を補強** – 公開メソッドのシグネチャが CLI に露出する範囲と必須／任意を決めますが、コメントに `TAG...` や `[Integer]` を書くと同じ引数でも配列化や型変換が行われます。コメントと実装のズレを観測したいときだけ `RUBYCLI_STRICT=ON` で厳格モードを有効化し、警告を受け取ります。
 - **軽量メンテナンス** – 実装の多くは AI 支援で作られており、深い Ruby メタプログラミングを伴う大規模拡張は想定外です。Fire 互換を求める PR は事前相談をお願いします。
 
 ## 特徴
 
 - コメントベースで CLI オプションやヘルプを自動生成
 - YARD 形式と `NAME [Type] 説明…` の簡潔記法を同時サポート
-- `--json-args` で渡された引数を自動的に JSON パース
+- 引数はデフォルトで安全なリテラルとして解釈し、必要に応じて厳格 JSON モードや Ruby eval モードを切り替え可能
 - `--pre-script`（エイリアス: `--init`）で任意の Ruby コードを評価し、その結果オブジェクトを公開
 - `RUBYCLI_STRICT=ON` で有効化できる厳格モードにより、コメントとシグネチャの矛盾を警告として検知可能
 
@@ -170,28 +185,24 @@ end
 | 機能 | Python Fire | Rubycli |
 | ---- | ----------- | -------- |
 | 属性の辿り方 | オブジェクトを辿ってプロパティ/属性を自動公開 | 対象オブジェクトの公開メソッドをそのまま公開（暗黙の辿りは無し） |
-| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` を指定した明示的な初期化のみ。引数はコメントで宣言 |
+| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` 指定時だけ引数なしで明示的に初期化（初期化引数の CLI 受け渡しは未対応なので、必要なら pre-script や自前ファクトリで注入） |
 | インタラクティブシェル | コマンド未指定時に Fire REPL を提供 | インタラクティブモード無し。コマンド実行専用 |
 | 情報源 | 反射で引数・プロパティを解析 | ライブなメソッド定義を基点にしつつコメントをヘルプへ反映 |
 | 辞書/配列 | dict/list を自動でサブコマンド化 | クラス/モジュールのメソッドに特化（辞書自動展開なし） |
 
 ## インストール
 
-まだ RubyGems で公開していません。リポジトリをクローンしてローカルパスを Bundler に指定するか、`.gemspec` 追加後に `gem build` で `.gem` を作成してインストールしてください。
+Rubycli は RubyGems からインストールできます。
 
 ```bash
-git clone https://github.com/inakaegg/rubycli.git
-cd rubycli
-# gem build rubycli.gemspec
-gem build rubycli.gemspec
-gem install rubycli-<version>.gem
+gem install rubycli
 ```
 
 Bundler 例:
 
 ```ruby
 # Gemfile
-gem "rubycli", path: "path/to/rubycli"
+gem "rubycli"
 ```
 
 ## クイックスタート（Rubycli をスクリプトに組み込む）
@@ -247,22 +258,46 @@ rubycli scripts/multi_runner.rb Admin::Runner list --active
 
 ## コメント記法
 
-| 用途 | YARD 互換 | 簡潔記法 |
-| ---- | --------- | -------- |
-| 位置引数 | `@param name [Type] 説明` | `NAME [Type] 説明`（NAME は大文字） |
-| キーワード引数 | 同上 | `--flag -f FLAG [Type] 説明` |
+| 用途 | YARD 互換 | Rubycli 標準 |
+| ---- | --------- | ----------- |
+| 位置引数 | `@param name [Type] 説明` | `NAME [Type] 説明` |
+| キーワード引数 | 同上 | `--flag -f VALUE [Type] 説明` |
 | 戻り値 | `@return [Type] 説明` | `=> [Type] 説明` |
 
-型は `String` や `Integer` のほか、`String[]` や `Array<String>`, `String | nil` なども利用できます。`[VALUE]` や `[VALUE...]` といったプレースホルダ表現で、真偽値や可変長引数を推論させられます。型名を省略した大文字プレースホルダ（例: `--quiet`）は自動的に Boolean フラグとして扱われます。
+短いオプション（`-f` など）は任意で、登場順も自由です。Rubycli 標準の書き方では次の例が同義になります。
+
+- `--flag -f VALUE [Type] 説明`
+- `--flag VALUE [Type] 説明`
+- `-f --flag VALUE [Type] 説明`
+
+README のサンプルは既定スタイルとして大文字プレースホルダ（`NAME`, `VALUE` など）を使用しています。次項以降の表記揺れは、必要に応じて選べる追加記法です。
+
+### 互換プレースホルダ表記
+
+コメントやヘルプ出力では次の表記も同じ意味として解釈されます。
+
+- 山括弧で値を明示: `--flag <value>`, `NAME [<value>]`
+- ロングオプションの `=` 付き表記: `--flag=<value>`
+- 繰り返し指定: `VALUE...`, `<value>...`
+
+実行時には `--flag VALUE`, `--flag <value>`, `--flag=<value>` のどれで入力しても同じ扱いです。プロジェクトで読みやすいスタイルを選択してください。`[VALUE]` や `[VALUE...]` のような表記を使うと、真偽値・任意値・リストなどの推論が働きます。値プレースホルダを省略したオプション（例: `--quiet`）は自動で Boolean フラグとして扱われます。
+
+> 補足: コメント内で任意引数を角括弧で表す必要はありません。Ruby 側のメソッドシグネチャから必須／任意は自動判定され、ヘルプ出力では Rubycli が適切に角括弧を追加します。
+
+型ヒントは `[String]`, `(String)`, `(type: String)` のように角括弧・丸括弧・`type:` プレフィックスのいずれでも指定できます。複数型は `(String, nil)` や `(type: String, nil)` のように列挙してください。
+
+`VALUE...` のような繰り返し指定（`TAG...` など）や、`[String[]]` / `Array<String>` といった配列型の注釈が付いたオプションは配列として扱われます。JSON/YAML 形式のリスト（例: `--tags '["build","test"]'`）を渡すか、カンマ区切り文字列（`--tags "build,test"`）を渡すことで配列に変換されます。スペース区切りの複数値入力（`--tags build test`）にはまだ対応しておらず、繰り返し注記のないオプションは従来どおりスカラーとして扱われます。
 
 代表的な推論例:
 
-- `ARG1` のように型ラベルを省略した大文字プレースホルダは既定で `String` として扱われます。
-- `--name ARG1` のようにオプションへ大文字プレースホルダだけを指定しても同じく `String` が推論されます。
+- `ARG1` のように型ラベルを省略したプレースホルダは既定で `String` として扱われます。
+- `--name ARG1` のようにオプションへプレースホルダだけを指定しても同じく `String` が推論されます。
 - `--verbose` のように値プレースホルダを省略したオプションは Boolean フラグとして扱われます。
 
 `@example` や `@raise`, `@see`, `@deprecated` などその他の YARD タグは、現状ヘルプ出力には反映されません。
 
+> すべての記法をまとめて試したい場合は `rubycli examples/documentation_style_showcase.rb canonical --help` や `... angled --help` などを実行してみてください。
+
 従来の `@param` 記法も既定で利用できます。簡潔なプレースホルダ記法だけに限定したい場合は `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` を設定してください（厳格モードでの検証は継続されます）。
 
 ### コメントが不足している場合のフォールバック
@@ -293,7 +328,7 @@ Usage: fallback_example.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    scale                <amount> [<factor>] [--clamp=<value>] [--notify=<value>]
+    scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
 
 Detailed command help: fallback_example.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -304,15 +339,15 @@ rubycli examples/fallback_example.rb scale --help
 ```
 
 ```text
-Usage: fallback_example.rb scale <AMOUNT> [<FACTOR>] [--clamp=<value>] [--notify]
+Usage: fallback_example.rb scale AMOUNT [FACTOR] [--clamp=<CLAMP>] [--notify]
 
 Positional arguments:
-  AMOUNT    [Integer] 処理対象の数値
-  [FACTOR]  (default: 2)
+  AMOUNT  [Integer]  required  処理対象の数値
+  FACTOR             optional  (default: 2)
 
 Options:
-  --clamp CLAMP  (type: String) (default: nil)
-  --notify       (type: Boolean) (default: false)
+  --clamp=<CLAMP>  [String]   optional  (default: nil)
+  --notify         [Boolean]  optional  (default: false)
 ```
 
 `AMOUNT` だけがドキュメント化されていますが、`factor` や `clamp`, `notify` も自動的に補完され、既定値や型が推論されていることがわかります。コメントとシグネチャの矛盾を早期に検知したい場合は `RUBYCLI_STRICT=ON` で厳格モードを有効化してください。
@@ -332,27 +367,29 @@ Options:
 - `@param` の行に続く箇条書きや補足行は CLI の自動生成には使われません。補足情報を表示したい場合は、`--flag ...` 行の説明に含めるか、README など別のドキュメントで扱ってください。
 - `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` にすると `@param`/`@return` などのタグは警告扱いになります。プロジェクト内で簡潔記法へ統一するときはこの環境変数で段階的に移行できます。
 
-## JSON モード
+## 引数解析モード
 
-CLI 実行時に `--json-args` を付けると、後続の引数が JSON として解釈され Ruby オブジェクトに変換されます。
+### 既定のリテラル解析
 
-```bash
-rubycli --json-args my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
-```
-
-プログラム側では `Rubycli.with_json_mode(true) { … }` で同じ効果を得られます。
+Rubycli は `{` や `[`、クォート、YAML の先頭記号といった「構造化リテラルらしい」形の引数に対して `Psych.safe_load` を試み、成功すれば Ruby の配列／ハッシュ／真偽値に変換してからメソッドへ渡します。たとえば `--names='["Alice","Bob"]'` や `--config='{foo: 1}'` のような値は追加フラグ無しでネイティブな配列・ハッシュとして届きます。一方、プレーンな `1,2,3` のような文字列はこの段階ではそのまま維持されます（コメントで `String[]` や `TAG...` と宣言されている場合は後段で配列に整形されます）。扱えない形式は自動的に文字列へフォールバックするため、`"2024-01-01"` のような値もそのまま文字列で受け取れますし、構文が崩れていても CLI 全体が落ちることはありません。
 
-## Eval モード
+### JSON モード
 
-`--eval-args` を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON では表現しづらいオブジェクトを扱いたいときに便利です。
+CLI 実行時に `--json-args`（短縮形 `-j`）を付けると、後続の引数が厳格に JSON として解釈されます。
 
 ```bash
-rubycli --eval-args scripts/data_cli.rb DataCLI run '(1..10).to_a'
+rubycli -j my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
 ```
 
-評価は `Object.new.instance_eval { binding }` に対して行われるため、信頼できる環境でのみ利用してください。プログラム側からは `Rubycli.with_eval_mode(true) { … }` で有効化できます。
+YAML 固有の書き方は拒否され、無効な JSON であれば `JSON::ParserError` が発生するため、入力の妥当性を強く保証したいときに便利です。プログラム側では `Rubycli.with_json_mode(true) { … }` で有効化できます。
+
+### Eval モード
+
+`--eval-args`（短縮形 `-e`）を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON や YAML では表現しづらいオブジェクトを扱いたいときに便利ですが、評価は `Object.new.instance_eval { binding }` 上で行われるため、信頼できる入力に限定してください。コード内では `Rubycli.with_eval_mode(true) { … }` で切り替えられます。
+
+Ruby 評価を使いつつ、構文エラーが出たときは元の文字列にフォールバックさせたい場合は `--eval-lax`（短縮形 `-E`）を指定します。`--eval-args` と同じく eval モードを有効にしますが、Ruby として解釈できなかったトークン（例: 素の `https://example.com`）は警告を出した上でそのまま渡すため、`60*60*24*14` のような式と文字列を気軽に混在させられます。
 
-`--eval-args` と `--json-args` は同時指定できません。両方付けた場合はエラーになります。
+`--json-args`/`-j` は `--eval-args`/`-e` および `--eval-lax`/`-E` と同時指定できません。どのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval（通常／lax）のいずれかを選択してください。
 
 ## Pre-script ブートストラップ
 

data/README.md

@@ -1,9 +1,13 @@
 # Rubycli — Python Fire-inspired CLI for Ruby
 
-Rubycli turns existing Ruby classes and modules into CLIs by reading their documentation comments. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations.
+![Rubycli logo](assets/rubycli-logo.png)
+
+Rubycli turns existing Ruby classes and modules into CLIs by inspecting their public method definitions and the doc comments attached to those methods. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations, and those annotations can actively change how a CLI argument is coerced (for example, `TAG... [String[]]` forces array parsing).
 
 > 🇯🇵 Japanese documentation is available in [README.ja.md](README.ja.md).
 
+![Rubycli demo showing generated commands and invocation](assets/rubycli-demo.gif)
+
 ### 1. Existing Ruby script (Rubycli unaware)
 
 ```ruby
@@ -28,7 +32,7 @@ Usage: hello_app.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name>
+    greet                <NAME>
 
 Detailed command help: hello_app.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -40,10 +44,10 @@ rubycli examples/hello_app.rb greet
 
 ```text
 Error: wrong number of arguments (given 0, expected 1)
-Usage: hello_app.rb greet <NAME>
+Usage: hello_app.rb greet NAME
 
 Positional arguments:
-  NAME
+  NAME    required
 ```
 
 ```bash
@@ -102,7 +106,7 @@ Usage: hello_app_with_docs.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    greet                <name> [--shout=<value>]
+    greet                <NAME> [--shout]
 
 Detailed command help: hello_app_with_docs.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -113,13 +117,13 @@ rubycli examples/hello_app_with_docs.rb greet --help
 ```
 
 ```text
-Usage: hello_app_with_docs.rb greet <NAME> [--shout]
+Usage: hello_app_with_docs.rb greet NAME [--shout]
 
 Positional arguments:
-  NAME  [String] Name to greet
+  NAME  [String]  required  Name to greet
 
 Options:
-  --shout  [Boolean] Print in uppercase (default: false)
+  --shout  [Boolean]  optional  Print in uppercase (default: false)
 ```
 
 ```bash
@@ -143,20 +147,38 @@ end
 
 ### 3. (Optional) Embed the runner inside your script
 
-Prefer to launch via `ruby hello_app.rb ...`? Require the gem and delegate to `Rubycli.run` (see Quick start below).
+Prefer to launch via `ruby ...` directly? Require the gem and delegate to `Rubycli.run` (see Quick start below for `examples/hello_app_with_require.rb`).
+
+```bash
+ruby examples/hello_app_with_require.rb greet Hanako --shout
+#=> HELLO, HANAKO!
+```
+
+## Constant resolution modes
+
+Rubycli assumes that the file name (CamelCased) matches the class or module you want to expose. When that is not the case you can choose how eagerly Rubycli should pick a constant:
+
+| Mode | How to enable | Behaviour |
+| --- | --- | --- |
+| `strict` (default) | do nothing / `RUBYCLI_AUTO_TARGET=strict` | Fails unless the CamelCase name matches. The error lists the detected constants and gives explicit rerun instructions. |
+| `auto` | `--auto-target`, `-a`, or `RUBYCLI_AUTO_TARGET=auto` | If exactly one constant in that file defines CLI-callable methods, Rubycli auto-selects it; otherwise you still get the friendly error message. |
+
+This keeps large projects safe by default but still provides a one-flag escape hatch when you prefer the fully automatic behaviour.
+
+> **Instance-only classes** – If a class only defines public *instance* methods (for example, it exposes functionality via `attr_reader` or `def greet` on the instance), you must run Rubycli with `--new` so the class is instantiated before commands are resolved. Otherwise Rubycli cannot see any CLI-callable methods. Add at least one public class method when you do not want to rely on `--new`.
 
 ## Project Philosophy
 
 - **Convenience first** – The goal is to wrap existing Ruby scripts in a CLI with almost no manual plumbing. Fidelity with Python Fire is not a requirement.
 - **Inspired, not a port** – We borrow ideas from Python Fire, but we do not aim for feature parity. Missing Fire features are generally “by design.”
-- **Comments enrich, code decides** – Method signatures remain the source of truth; optional documentation comments add richer help output and can surface warnings when you opt into strict mode (`RUBYCLI_STRICT=ON`).
+- **Method definitions first, comments augment behavior** – Public method signatures determine what gets exposed (and which arguments are required), while doc comments like `TAG...` or `[Integer]` can turn the very same CLI value into arrays, integers, booleans, etc. Enable strict mode (`RUBYCLI_STRICT=ON`) when you want warnings about mismatches.
 - **Lightweight maintenance** – Much of the implementation was generated with AI assistance; contributions that diverge into deep Ruby metaprogramming are out of scope. Please discuss expectations before opening parity PRs.
 
 ## Features
 
 - Comment-aware CLI generation with both YARD-style tags and concise placeholders
 - Automatic option signature inference (`NAME [Type] Description…`) without extra DSLs
-- Optional JSON coercion for arguments passed via `--json-args`
+- Safe literal parsing out of the box (arrays / hashes / booleans) with opt-in strict JSON and Ruby eval modes
 - Optional pre-script hook (`--pre-script` / `--init`) to evaluate Ruby and expose the resulting object
 - Opt-in strict mode (`RUBYCLI_STRICT=ON`) that emits warnings whenever comments contradict method signatures
 
@@ -170,36 +192,32 @@ Prefer to launch via `ruby hello_app.rb ...`? Require the gem and delegate to `R
 | Capability | Python Fire | Rubycli |
 | ---------- | ----------- | -------- |
 | Attribute traversal | Recursively exposes attributes/properties on demand | Exposes public methods defined on the target; no implicit traversal |
-| Constructor handling | Automatically prompts for `__init__` args when instantiating classes | Requires explicit `--new` plus comment docs; no automatic prompting |
+| Constructor handling | Automatically prompts for `__init__` args when instantiating classes | `--new` simply instantiates without passing CLI args (use pre-scripts or your own factories if you need injected dependencies) |
 | Interactive shell | Offers Fire-specific REPL when invoked without command | No interactive shell mode; strictly command execution |
 | Input discovery | Pure reflection, no doc comments required | Doc comments drive option names, placeholders, and validation |
 | Data structures | Dictionaries / lists become subcommands by default | Focused on class or module methods; no automatic dict/list expansion |
 
 ## Installation
 
-The library is not published on RubyGems yet. Clone the repository and point Bundler to the local path, or build a `.gem` once the `.gemspec` is added.
+Rubycli is published on RubyGems.
 
 ```bash
-git clone https://github.com/inakaegg/rubycli.git
-cd rubycli
-# gem build rubycli.gemspec
-gem build rubycli.gemspec
-gem install rubycli-<version>.gem
+gem install rubycli
 ```
 
 Bundler example:
 
 ```ruby
 # Gemfile
-gem "rubycli", path: "path/to/rubycli"
+gem "rubycli"
 ```
 
 ## Quick start (embed Rubycli in the script)
 
-Step 3 adds `require "rubycli"` so the script can invoke the CLI directly:
+Step 3 adds `require "rubycli"` so the script can invoke the CLI directly (see `examples/hello_app_with_require.rb`):
 
 ```ruby
-# hello_app.rb
+# hello_app_with_require.rb
 require "rubycli"
 
 module HelloApp
@@ -222,10 +240,10 @@ Rubycli.run(HelloApp)
 Run it:
 
 ```bash
-ruby hello_app.rb greet Taro
+ruby examples/hello_app_with_require.rb greet Taro
 #=> Hello, Taro!
 
-ruby hello_app.rb greet Taro --shout
+ruby examples/hello_app_with_require.rb greet Taro --shout
 #=> HELLO, TARO!
 ```
 
@@ -249,22 +267,46 @@ This is useful when a file defines multiple candidates or when you want a nested
 
 Rubycli parses a hybrid format – you can stick to familiar YARD tags or use short forms.
 
-| Purpose | YARD-compatible | Concise form |
-| ------- | --------------- | ------------ |
-| Positional argument | `@param name [Type] Description` | `NAME [Type] Description` (`NAME` must be uppercase) |
-| Keyword option | Same as above | `--flag -f FLAG [Type] Description` |
+| Purpose | YARD-compatible | Rubycli style |
+| ------- | --------------- | ------------- |
+| Positional argument | `@param name [Type] Description` | `NAME [Type] Description` |
+| Keyword option | Same as above | `--flag -f VALUE [Type] Description` |
 | Return value | `@return [Type] Description` | `=> [Type] Description` |
 
-Types accept `String`, `Integer`, `String[]`, `Array<String>`, union `String | nil`, etc. Optional placeholders like `[VALUE]` or `[VALUE...]` let Rubycli infer boolean flags, optional values, and list coercion. When you omit the type on an uppercase placeholder (for example `--quiet`), Rubycli infers a Boolean flag automatically.
+Short options are optional and order-independent, so the following examples are equivalent in Rubycli’s default style:
+
+- `--flag -f VALUE [Type] Description`
+- `--flag VALUE [Type] Description`
+- `-f --flag VALUE [Type] Description`
+
+Our examples keep the classic uppercase placeholders (`NAME`, `VALUE`) as the canonical style; the variations below are optional sugar.
+
+### Alternate placeholder notations
+
+Rubycli also understands these syntaxes when parsing comments and rendering help:
+
+- Angle brackets for user input: `--flag <value>` or `NAME [<value>]`
+- Inline equals for long options: `--flag=<value>`
+- Trailing ellipsis for repeated values: `VALUE...` or `<value>...`
+
+The CLI treats `--flag VALUE`, `--flag <value>`, and `--flag=<value>` identically at runtime—document with whichever variant your team prefers. Optional placeholders like `[VALUE]` or `[VALUE...]` let Rubycli infer boolean flags, optional values, and list coercion. When you omit the placeholder entirely (for example `--quiet`), Rubycli infers a Boolean flag automatically.
+
+> Tip: You do not need to wrap optional arguments in brackets inside the comment. Rubycli already knows which parameters are optional from the Ruby signature and will introduce the brackets in generated help.
+
+You can annotate types using `[String]`, `(String)`, or `(type: String)`—they all convey the same hint, and you can list multiple types such as `(String, nil)` or `(type: String, nil)`.
+
+Repeated values (`VALUE...`) now materialize as arrays automatically whenever the option is documented with an ellipsis (for example `TAG...`) or an explicit array type hint (`[String[]]`, `Array<String>`). Supply either JSON/YAML list syntax (`--tags "[\"build\",\"test\"]"`) or a comma-delimited string (`--tags "build,test"`); Rubycli will coerce both forms to arrays. Space-separated multi-value flags (`--tags build test`) are still not supported, and options without a repeated/array hint continue to be parsed as scalars.
 
 Common inference rules:
 
-- Writing a bare uppercase placeholder such as `ARG1` (without `[String]`) makes Rubycli treat it as a `String`.
+- Writing a placeholder such as `ARG1` (without `[String]`) makes Rubycli treat it as a `String`.
 - Using that placeholder in an option line (`--name ARG1`) also infers a `String`.
 - Omitting the placeholder entirely (`--verbose`) produces a Boolean flag.
 
 Other YARD tags such as `@example`, `@raise`, `@see`, and `@deprecated` are currently ignored by the CLI renderer.
 
+> Want to explore every notation in a single script? Try `rubycli examples/documentation_style_showcase.rb canonical --help`, `... angled --help`, or the other showcase commands.
+
 YARD-style `@param` annotations continue to work out of the box. If you want to enforce the concise placeholder syntax exclusively, set `RUBYCLI_ALLOW_PARAM_COMMENT=OFF` (strict mode still applies either way).
 
 ### When docs are missing or incomplete
@@ -295,7 +337,7 @@ Usage: fallback_example.rb COMMAND [arguments]
 
 Available commands:
   Class methods:
-    scale                <amount> [<factor>] [--clamp=<value>] [--notify=<value>]
+    scale                AMOUNT [<FACTOR>] [--clamp=<value>] [--notify]
 
 Detailed command help: fallback_example.rb COMMAND help
 Enable debug logging: --debug or RUBYCLI_DEBUG=true
@@ -306,15 +348,15 @@ rubycli examples/fallback_example.rb scale --help
 ```
 
 ```text
-Usage: fallback_example.rb scale <AMOUNT> [<FACTOR>] [--clamp=<value>] [--notify]
+Usage: fallback_example.rb scale AMOUNT [FACTOR] [--clamp=<CLAMP>] [--notify]
 
 Positional arguments:
-  AMOUNT    [Integer] Base amount to process
-  [FACTOR]  (default: 2)
+  AMOUNT  [Integer]  required  Base amount to process
+  FACTOR             optional  (default: 2)
 
 Options:
-  --clamp CLAMP  (type: String) (default: nil)
-  --notify       (type: Boolean) (default: false)
+  --clamp=<CLAMP>  [String]   optional  (default: nil)
+  --notify         [Boolean]  optional  (default: false)
 ```
 
 Here only `AMOUNT` is documented, yet `factor`, `clamp`, and `notify` are still presented with sensible defaults and inferred types. Enable strict mode (`RUBYCLI_STRICT=ON`) if you want mismatches between comments and signatures to surface as warnings during development.
@@ -327,27 +369,35 @@ Here only `AMOUNT` is documented, yet `factor`, `clamp`, and `notify` are still
 
 In short, comments never add live parameters by themselves; they enrich or describe what your method already supports.
 
-## JSON mode
+## Argument parsing modes
+
+### Default literal parsing
 
-Supply `--json-args` when invoking the runner and Rubycli will parse subsequent arguments as JSON before passing them to your method:
+Rubycli tries to interpret arguments that look like structured literals (values starting with `{`, `[`, quotes, or YAML front matter) using `Psych.safe_load` before handing them to your code. That means values such as `--names='["Alice","Bob"]'` or `--config='{foo: 1}'` arrive as native arrays / hashes without any extra flags. Plain strings like `1,2,3` stay untouched at this stage (if the documentation declares `String[]` or `TAG...`, a later pass still normalises them into arrays), and unsupported constructs fall back to the original text, so `"2024-01-01"` remains a string and malformed payloads still reach your method instead of killing the run.
+
+### JSON mode
+
+Supply `--json-args` (or the shorthand `-j`) when invoking the runner and Rubycli will parse subsequent arguments strictly as JSON before passing them to your method:
 
 ```bash
-rubycli --json-args my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
+rubycli -j my_cli.rb MyCLI run '["--config", "{\"foo\":1}"]'
 ```
 
-Programmatically you can call `Rubycli.with_json_mode(true) { … }`.
+This mode rejects YAML-only syntax and raises `JSON::ParserError` when the payload is invalid, which is handy for callers who want explicit failures instead of silent fallbacks. Programmatically you can call `Rubycli.with_json_mode(true) { … }`.
 
 ## Eval mode
 
-Use `--eval-args` to evaluate Ruby expressions before they are forwarded to your CLI. This is handy when you want to pass rich objects that are awkward to express as JSON:
+Use `--eval-args` (or the shorthand `-e`) to evaluate Ruby expressions before they are forwarded to your CLI. This is handy when you want to pass rich objects that are awkward to express as JSON:
 
 ```bash
-rubycli --eval-args scripts/data_cli.rb DataCLI run '(1..10).to_a'
+rubycli -e scripts/data_cli.rb DataCLI run '(1..10).to_a'
 ```
 
 Under the hood Rubycli evaluates each argument inside an isolated binding (`Object.new.instance_eval { binding }`). Treat this as unsafe input: do not enable it for untrusted callers. The mode can also be toggled programmatically via `Rubycli.with_eval_mode(true) { … }`.
 
-`--eval-args` and `--json-args` are mutually exclusive; Rubycli will raise an error if both are present.
+Need Ruby evaluation plus a safety net? Pass `--eval-lax` (or `-E`). It flips on eval mode just like `--eval-args`, but if Ruby fails to parse a token (for example, a bare `https://example.com`), Rubycli emits a warning and forwards the original string unchanged. This lets you mix inline math (`60*60*24*14`) with literal values without constantly juggling quotes.
+
+`--json-args`/`-j` cannot be combined with either `--eval-args`/`-e` or `--eval-lax`/`-E`; Rubycli will raise an error if both are present. Both modes augment the default literal parsing, so you can pick either strict JSON or one of the Ruby eval variants when the defaults are not enough.
 
 ## Pre-script bootstrap