Merge pull request #33 from 0xrsydn/docs/readme-refresh

docs: refresh README for v0.2.4

README.md

@@ -13,22 +13,23 @@ curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | s
 Downloads the prebuilt `idx` binary for your platform from GitHub Releases,
 verifies it against the release `SHA256SUMS`, and installs it into
 `~/.local/bin` without sudo. Pin a version or change the directory with
-`sh -s -- --version v0.2.3 --dir ~/bin`. See [docs/INSTALL.md](docs/INSTALL.md).
+`sh -s -- --version v0.2.4 --dir ~/bin`. See [docs/INSTALL.md](docs/INSTALL.md).
 
-### Cargo
+### npm / npx
 
 ```bash
-cargo install idx-cli
+npx idx-cli --help          # run without installing
+npm install --global idx-cli
 ```
 
-This installs the `idx` binary. `idx-cli` currently requires Rust `1.85+`.
+The npm package downloads the same checksum-verified release binary during
+`postinstall`. pnpm 10+ and bun skip install scripts by default; allow them
+with `pnpm add --global --allow-build=idx-cli idx-cli` or
+`bun add --global --trust idx-cli`. See
+[docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md).
 
-If you use the install script or the Cargo install path directly, some commands also require helper tools at runtime:
-
-- Yahoo-authenticated flows require a `curl_chrome*` binary from `curl-impersonate-chrome` in `PATH`, or `IDX_CURL_IMPERSONATE_BIN` pointing at that binary.
-- Ownership PDF import requires `mutool` from MuPDF in `PATH`.
-
-Install those helpers with your OS package manager, or use the Nix app/package below so they are wrapped automatically.
+Prebuilt binaries cover Linux x64/arm64 (static musl) and macOS arm64/x64.
+On Windows, use WSL.
 
 ### Nix
 
@@ -37,26 +38,81 @@ nix run github:0xrsydn/idx-cli -- version
 nix profile install github:0xrsydn/idx-cli#default
 ```
 
-The Nix app wraps `idx` with `curl-impersonate` and `mupdf`, so the Yahoo auth and ownership PDF helper tools are available automatically.
+The Nix package wraps `idx` with `curl-impersonate` and `mupdf`, so every
+helper tool below is available automatically.
+
+### Cargo
+
+```bash
+cargo install idx-cli
+```
+
+Builds from source; requires Rust `1.85+`.
+
+### Runtime helper tools
+
+The install script, npm, and Cargo installs ship only the `idx` binary. A few
+commands call external tools:
+
+| Tool | Needed for |
+| --- | --- |
+| `curl_chrome*` from [curl-impersonate](https://github.com/lexiforest/curl-impersonate) (ownership also tries its Firefox and Safari profiles), or `IDX_CURL_IMPERSONATE_BIN` | `ownership discover` / `import --url` from IDX (behind Cloudflare), and Yahoo fundamentals when `IDX_PROVIDER=yahoo` |
+| `mutool` from MuPDF | importing legacy PDF ownership reports only |
+
+Everyday use (`stocks` with the default MSN provider, including history,
+`ownership sync`, and every local ownership query) needs neither.
 
 ## Quick start
 
 ```bash
+# Stocks
 idx stocks quote BBCA
 idx stocks quote BBCA,BBRI,BMRI
-idx -o json stocks quote BBCA
 idx stocks history BBCA --period 3mo
-idx config init
-idx cache info
-idx --offline stocks quote BBCA
+idx stocks technical BBCA
+idx stocks fundamental BBCA
+idx stocks compare BBCA BBRI BMRI
+idx -o json stocks quote BBCA
+
+# Ownership: download the maintained snapshot once, then query locally
+idx ownership sync
+idx ownership ticker BBCA
+idx ownership entity "ANTHONI SALIM"
+idx ownership search salim
+idx ownership changes --from 2026-07-31 --to 2026-08-31
 ```
 
 ## Features
 
-- Provider abstraction (swap data sources behind one interface)
-- Local file cache with TTL
-- Offline mode with stale-cache fallback
-- Human table output and machine-friendly JSON output
+### Stocks
+
+- Quotes, OHLC history, company profile, financial statements, earnings,
+  news, crowd sentiment, and AI insights
+- Analysis: `technical`, `growth`, `valuation`, `risk`, and a combined
+  `fundamental` report; multi-symbol `compare`; MSN stock `screen`
+- Providers: MSN is the default for quotes, fundamentals, and screening;
+  Yahoo serves history. Switch with `IDX_PROVIDER=msn|yahoo` and
+  `IDX_HISTORY_PROVIDER=auto|yahoo|msn`
+- Local file cache with TTL, and `--offline` mode with stale-cache fallback
+
+### Ownership (KSEI shareholders above 1%)
+
+- Source: the monthly KSEI holder register ("Pemegang Saham di Atas 1%")
+  published by IDX. Since June 2026 it is an XLSX file on IDX's
+  [Data Kepemilikan Saham](https://www.idx.co.id/id/perusahaan-tercatat/data-kepemilikan-saham/)
+  page; earlier months were PDF announcements
+- `ownership sync` installs a maintained SQLite snapshot (checked daily,
+  currently the latest three months), after which every query runs offline
+- Queries: holders per `ticker`, holdings per `entity`, entity `search`,
+  month-over-month `changes`, `concentration`, `cross-holders`, and an
+  ownership `graph`
+- Self-serve ingest: `ownership discover` finds the latest reports, and
+  `ownership import --url <xlsx-or-pdf>` / `--file` loads them into your
+  local database. See [docs/OWNERSHIP_SYNC.md](docs/OWNERSHIP_SYNC.md)
+
+### Output
+
+- Human-readable tables on stdout, JSON with `-o json`, errors on stderr
 
 ## Configuration
 
@@ -81,6 +137,17 @@ Precedence order:
 
 - Use `idx --help` and subcommand help for discoverability
 - Use `-o json` / `--output json` for structured output
+- `idx completions <shell>` generates shell completions
+
+## Documentation
+
+- [docs/INSTALL.md](docs/INSTALL.md): install script options
+- [docs/NPM_DISTRIBUTION.md](docs/NPM_DISTRIBUTION.md): npm package and release flow
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): providers, ownership ingest, and discovery
+- [docs/OWNERSHIP_SYNC.md](docs/OWNERSHIP_SYNC.md): snapshot manifest and sync rules
+- [docs/OWNERSHIP_PUBLISH.md](docs/OWNERSHIP_PUBLISH.md) and
+  [docs/OWNERSHIP_SELF_HOSTED.md](docs/OWNERSHIP_SELF_HOSTED.md): maintainer snapshot publishing
+- [docs/SMOKE.md](docs/SMOKE.md): smoke tests against live providers
 
 ## Development
 
@@ -94,6 +161,9 @@ Prek hooks are configured for quality gates:
 - pre-commit: `cargo fmt --check` + `cargo clippy -- -D warnings`
 - pre-push: `cargo test`
 
+Script test suites (no live network): `scripts/install-sh-test.sh`,
+`scripts/publish-ownership-snapshot-test.sh`, and `scripts/npm-smoke.sh`.
+
 ## License
 
 MIT

docs/INSTALL.md

@@ -45,7 +45,7 @@ them yourself.
 Pass flags through the pipe with `sh -s --`:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.2.3 --dir ~/bin
+curl -fsSL https://raw.githubusercontent.com/0xrsydn/idx-cli/main/install.sh | sh -s -- --version v0.2.4 --dir ~/bin
 ```
 
 ## Supported platforms

docs/NPM_DISTRIBUTION.md

@@ -31,7 +31,7 @@ npx idx-cli --help
 ```
 
 The package version and the release tag must match. For example, package
-version `0.2.3` downloads assets from the `v0.2.3` GitHub Release.
+version `0.2.4` downloads assets from the `v0.2.4` GitHub Release.
 
 The postinstall script downloads `SHA256SUMS` from the same release and
 refuses to install a binary whose checksum does not match.
@@ -81,7 +81,7 @@ URLs must stay aligned with `scripts/install.js`.
 To attach binaries to a tag that already exists, run the workflow manually:
 
 ```bash
-gh workflow run release.yml -f tag=v0.2.3
+gh workflow run release.yml -f tag=v0.2.4
 ```
 
 Pull requests that touch the workflow or the installer run the build jobs
@@ -91,4 +91,7 @@ Release order:
 
 1. Push the tag, or run the workflow for an existing tag.
 2. Confirm the release has all binaries plus `SHA256SUMS`.
-3. Run `npm publish`.
+3. Run `npm publish` from the tagged commit. The account has two-factor auth,
+   so npm asks for a browser approval or `--otp=<code>`. A version number
+   can never be republished, so bump `Cargo.toml` and `package.json` together
+   before tagging.