docs(cli): help for config keys and output, changes dates, alias search

`idx config --help` lists the keys and says when it prints JSON;
`ownership changes` says both dates must be imported releases and that
accounts are summed; `ownership search` and `entity` describe alias and
substring matching. Regenerated the CLI reference page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V3syn2fN2LNo5pvTSqc6eh

crates/idx-cli/src/cli/config.rs

@@ -5,7 +5,11 @@ use crate::output::{OutputSetting, json};
 use idx_core::error::IdxError;
 
 #[derive(Debug, Args)]
-#[command(about = "Manage configuration")]
+#[command(
+    about = "Manage configuration",
+    long_about = "Manage configuration in ~/.config/idx/config.toml (or $XDG_CONFIG_HOME/idx/config.toml).\n\nResults print as plain text, even when piped, so `$(idx config path)` works in scripts. Ask for JSON with `-o json`, `IDX_OUTPUT=json`, or `general.output = \"json\"`.",
+    after_help = "Keys:\n  general.provider, general.history_provider, general.exchange, general.output,\n  general.color, cache.quote_ttl, cache.fundamental_ttl, ownership.db_path,\n  ownership.snapshot_manifest\n\nExamples:\n  idx config init\n  idx config set general.output json\n  idx config get cache.quote_ttl\n  idx config path"
+)]
 pub struct ConfigCmd {
     #[command(subcommand)]
     pub command: ConfigSubcommand,
@@ -16,9 +20,16 @@ pub enum ConfigSubcommand {
     #[command(about = "Create default configuration file")]
     Init,
     #[command(about = "Get a configuration value by key")]
-    Get { key: String },
+    Get {
+        /// Key such as general.provider (see `idx config --help`).
+        key: String,
+    },
     #[command(about = "Set a configuration value by key")]
-    Set { key: String, value: String },
+    Set {
+        /// Key such as general.provider (see `idx config --help`).
+        key: String,
+        value: String,
+    },
     #[command(about = "Print configuration file path")]
     Path,
 }

crates/idx-cli/src/cli/ownership.rs

@@ -50,8 +50,15 @@ pub enum OwnershipCommand {
     /// Show all holders for a ticker (KSEI + Bing combined).
     Ticker(TickerArgs),
     /// Show all holdings for an entity across tickers.
+    #[command(
+        after_help = "Examples:\n  idx ownership entity \"ASTRA INTERNATIONAL\"\n  idx ownership search astra   # list candidates first"
+    )]
     Entity(EntityArgs),
-    /// Search entities by name.
+    /// Search entities by name or KSEI alias.
+    #[command(
+        long_about = "Search entities by name or KSEI alias.\n\nMatches canonical names and the raw names KSEI prints (e.g. `PT ASTRA INTERNATIONAL TBK`), case-insensitively. Ranked: exact name, exact alias, prefix, then substring.",
+        after_help = "Examples:\n  idx ownership search astra\n  idx ownership search \"PT ASTRA INTERNATIONAL TBK\" --limit 5"
+    )]
     Search(SearchArgs),
     /// Rank entities by cross-ownership breadth.
     CrossHolders(CrossHolderArgs),
@@ -60,6 +67,10 @@ pub enum OwnershipCommand {
     /// Show Bing institutional flow for a ticker.
     Flow(FlowArgs),
     /// Diff two KSEI releases.
+    #[command(
+        long_about = "Diff two KSEI releases: new, exited, increased, and decreased holders.\n\nBoth dates must be imported releases (`idx ownership releases` lists them), with --from before --to. A holder's accounts in a ticker are summed, so an investor with several accounts compares by its total stake.",
+        after_help = "Examples:\n  idx ownership releases\n  idx ownership changes --from 2026-08-31 --to 2026-09-30"
+    )]
     Changes(ChangesArgs),
     /// Ownership network graph.
     Graph(GraphArgs),
@@ -114,11 +125,13 @@ pub struct TickerArgs {
 
 #[derive(Debug, Args)]
 pub struct EntityArgs {
+    /// Entity name or part of one, case-insensitive; the shortest match is shown.
     pub name: String,
 }
 
 #[derive(Debug, Args)]
 pub struct SearchArgs {
+    /// Name, KSEI alias, or part of one.
     pub query: String,
     #[arg(long, default_value_t = 20)]
     pub limit: usize,
@@ -147,8 +160,10 @@ pub struct FlowArgs {
 
 #[derive(Debug, Args)]
 pub struct ChangesArgs {
+    /// Earlier release date, YYYY-MM-DD.
     #[arg(long)]
     pub from: String,
+    /// Later release date, YYYY-MM-DD.
     #[arg(long)]
     pub to: String,
 }

crates/idx-cli/tests/golden/help-config.golden

@@ -1,6 +1,8 @@
 exit: 0
 --- stdout
-Manage configuration
+Manage configuration in ~/.config/idx/config.toml (or $XDG_CONFIG_HOME/idx/config.toml).
+
+Results print as plain text, even when piped, so `$(idx config path)` works in scripts. Ask for JSON with `-o json`, `IDX_OUTPUT=json`, or `general.output = "json"`.
 
 Usage: idx config [OPTIONS] <COMMAND>
 
@@ -12,11 +14,37 @@ Commands:
   help  Print this message or the help of the given subcommand(s)
 
 Options:
-  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
+  -o, --output <OUTPUT>
-      --no-color         Disable colored output
+          Output format [default: auto = table on a terminal, json when piped]
-  -q, --quiet            Suppress non-essential output
+          
-  -v, --verbose...       Increase verbosity (-v, -vv)
+          [possible values: auto, table, json, jsonl]
-      --offline          Run without network requests
+
-      --no-cache         Bypass local cache
+      --no-color
-  -h, --help             Print help
+          Disable colored output
+
+  -q, --quiet
+          Suppress non-essential output
+
+  -v, --verbose...
+          Increase verbosity (-v, -vv)
+
+      --offline
+          Run without network requests
+
+      --no-cache
+          Bypass local cache
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Keys:
+  general.provider, general.history_provider, general.exchange, general.output,
+  general.color, cache.quote_ttl, cache.fundamental_ttl, ownership.db_path,
+  ownership.snapshot_manifest
+
+Examples:
+  idx config init
+  idx config set general.output json
+  idx config get cache.quote_ttl
+  idx config path
 --- stderr

crates/idx-cli/tests/golden/help-ownership.golden

@@ -15,7 +15,7 @@ Commands:
   sync           Install or refresh a maintained ownership SQLite snapshot
   ticker         Show all holders for a ticker (KSEI + Bing combined)
   entity         Show all holdings for an entity across tickers
-  search         Search entities by name
+  search         Search entities by name or KSEI alias
   cross-holders  Rank entities by cross-ownership breadth
   concentration  Rank tickers by ownership concentration
   flow           Show Bing institutional flow for a ticker

web/src/content/docs/cli/reference.md

@@ -463,7 +463,9 @@ Examples:
 ## `idx config`
 
 ```text
-Manage configuration
+Manage configuration in ~/.config/idx/config.toml (or $XDG_CONFIG_HOME/idx/config.toml).
+
+Results print as plain text, even when piped, so `$(idx config path)` works in scripts. Ask for JSON with `-o json`, `IDX_OUTPUT=json`, or `general.output = "json"`.
 
 Usage: idx config [OPTIONS] <COMMAND>
 
@@ -475,13 +477,39 @@ Commands:
   help  Print this message or the help of the given subcommand(s)
 
 Options:
-  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
+  -o, --output <OUTPUT>
-      --no-color         Disable colored output
+          Output format [default: auto = table on a terminal, json when piped]
-  -q, --quiet            Suppress non-essential output
+
-  -v, --verbose...       Increase verbosity (-v, -vv)
+          [possible values: auto, table, json, jsonl]
-      --offline          Run without network requests
+
-      --no-cache         Bypass local cache
+      --no-color
-  -h, --help             Print help
+          Disable colored output
+
+  -q, --quiet
+          Suppress non-essential output
+
+  -v, --verbose...
+          Increase verbosity (-v, -vv)
+
+      --offline
+          Run without network requests
+
+      --no-cache
+          Bypass local cache
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Keys:
+  general.provider, general.history_provider, general.exchange, general.output,
+  general.color, cache.quote_ttl, cache.fundamental_ttl, ownership.db_path,
+  ownership.snapshot_manifest
+
+Examples:
+  idx config init
+  idx config set general.output json
+  idx config get cache.quote_ttl
+  idx config path
 ```
 
 ### `idx config init`
@@ -509,7 +537,7 @@ Get a configuration value by key
 Usage: idx config get [OPTIONS] <KEY>
 
 Arguments:
-  <KEY>
+  <KEY>  Key such as general.provider (see `idx config --help`)
 
 Options:
   -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
@@ -529,7 +557,7 @@ Set a configuration value by key
 Usage: idx config set [OPTIONS] <KEY> <VALUE>
 
 Arguments:
-  <KEY>
+  <KEY>    Key such as general.provider (see `idx config --help`)
   <VALUE>
 
 Options:
@@ -633,7 +661,7 @@ Commands:
   sync           Install or refresh a maintained ownership SQLite snapshot
   ticker         Show all holders for a ticker (KSEI + Bing combined)
   entity         Show all holdings for an entity across tickers
-  search         Search entities by name
+  search         Search entities by name or KSEI alias
   cross-holders  Rank entities by cross-ownership breadth
   concentration  Rank tickers by ownership concentration
   flow           Show Bing institutional flow for a ticker
@@ -833,7 +861,7 @@ Show all holdings for an entity across tickers
 Usage: idx ownership entity [OPTIONS] <NAME>
 
 Arguments:
-  <NAME>
+  <NAME>  Entity name or part of one, case-insensitive; the shortest match is shown
 
 Options:
   -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
@@ -843,27 +871,55 @@ Options:
       --offline          Run without network requests
       --no-cache         Bypass local cache
   -h, --help             Print help
+
+Examples:
+  idx ownership entity "ASTRA INTERNATIONAL"
+  idx ownership search astra   # list candidates first
 ```
 
 ### `idx ownership search`
 
 ```text
-Search entities by name
+Search entities by name or KSEI alias.
+
+Matches canonical names and the raw names KSEI prints (e.g. `PT ASTRA INTERNATIONAL TBK`), case-insensitively. Ranked: exact name, exact alias, prefix, then substring.
 
 Usage: idx ownership search [OPTIONS] <QUERY>
 
 Arguments:
   <QUERY>
+          Name, KSEI alias, or part of one
 
 Options:
-      --limit <LIMIT>    [default: 20]
+      --limit <LIMIT>
-  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
+          [default: 20]
-      --no-color         Disable colored output
+
-  -q, --quiet            Suppress non-essential output
+  -o, --output <OUTPUT>
-  -v, --verbose...       Increase verbosity (-v, -vv)
+          Output format [default: auto = table on a terminal, json when piped]
-      --offline          Run without network requests
+
-      --no-cache         Bypass local cache
+          [possible values: auto, table, json, jsonl]
-  -h, --help             Print help
+
+      --no-color
+          Disable colored output
+
+  -q, --quiet
+          Suppress non-essential output
+
+  -v, --verbose...
+          Increase verbosity (-v, -vv)
+
+      --offline
+          Run without network requests
+
+      --no-cache
+          Bypass local cache
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Examples:
+  idx ownership search astra
+  idx ownership search "PT ASTRA INTERNATIONAL TBK" --limit 5
 ```
 
 ### `idx ownership cross-holders`
@@ -927,20 +983,45 @@ Options:
 ### `idx ownership changes`
 
 ```text
-Diff two KSEI releases
+Diff two KSEI releases: new, exited, increased, and decreased holders.
+
+Both dates must be imported releases (`idx ownership releases` lists them), with --from before --to. A holder's accounts in a ticker are summed, so an investor with several accounts compares by its total stake.
 
 Usage: idx ownership changes [OPTIONS] --from <FROM> --to <TO>
 
 Options:
       --from <FROM>
-  -o, --output <OUTPUT>  Output format [default: auto = table on a terminal, json when piped] [possible values: auto, table, json, jsonl]
+          Earlier release date, YYYY-MM-DD
-      --no-color         Disable colored output
+
+  -o, --output <OUTPUT>
+          Output format [default: auto = table on a terminal, json when piped]
+
+          [possible values: auto, table, json, jsonl]
+
+      --no-color
+          Disable colored output
+
       --to <TO>
-  -q, --quiet            Suppress non-essential output
+          Later release date, YYYY-MM-DD
-  -v, --verbose...       Increase verbosity (-v, -vv)
+
-      --offline          Run without network requests
+  -q, --quiet
-      --no-cache         Bypass local cache
+          Suppress non-essential output
-  -h, --help             Print help
+
+  -v, --verbose...
+          Increase verbosity (-v, -vv)
+
+      --offline
+          Run without network requests
+
+      --no-cache
+          Bypass local cache
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Examples:
+  idx ownership releases
+  idx ownership changes --from 2026-08-31 --to 2026-09-30
 ```
 
 ### `idx ownership graph`