Add OpenStock agent CLI skill

skills/openstock-agent-cli/references/commands/account/guide.md

@@ -0,0 +1,41 @@
+# `openstock account`
+
+## Purpose
+
+Read KIS account state for the configured live account.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock account status` | Show balance and holdings. |
+
+## `account status`
+
+### Usage
+
+```bash
+openstock account status
+```
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCOUNT` |
+| External IO | KIS balance inquiry endpoint. |
+| File IO | `~/.config/openstock/.env` read. |
+| Side effect | none |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for inquiry. |
+| `account` | Queried account number. |
+| `balance` | Cash, total evaluated asset amount, profit/loss, and account summary values. |
+| `holdings` | Currently held stock list. |
+
+## Agent Notes
+
+Use this before any proposed trade to check cash, holdings, and orderable quantity context.

skills/openstock-agent-cli/references/commands/account/status/guide.md

@@ -0,0 +1,17 @@
+# `openstock account status`
+
+Purpose: query balance and holdings for the configured KIS account.
+
+Usage:
+
+```bash
+openstock account status
+```
+
+Reads: `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCOUNT`.
+
+External IO: KIS balance inquiry.
+
+Output fields: `broker`, `account`, `balance`, `holdings`.
+
+Agent rule: run before any trade recommendation or live order.

skills/openstock-agent-cli/references/commands/api/call/guide.md

@@ -0,0 +1,19 @@
+# `openstock api call`
+
+Purpose: directly call a KIS GET endpoint with access-token headers.
+
+Usage:
+
+```bash
+openstock api call /uapi/... --param tr_id=... --param KEY=VALUE
+```
+
+Inputs: `endpoint`, repeated `--param KEY=VALUE`.
+
+Reads: KIS credentials and access token from config/env.
+
+External IO: KIS endpoint GET.
+
+Output fields: `broker`, `endpoint`, `params`, `request_semantics`, `response`, `response_semantics`.
+
+Agent rule: prefer typed commands; use this only for endpoints not yet implemented as stable commands.

skills/openstock-agent-cli/references/commands/api/guide.md

@@ -0,0 +1,91 @@
+# `openstock api`
+
+## Purpose
+
+Manage broker API metadata, KIS login, and raw endpoint calls.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock api list` | Show registered broker APIs and their capabilities. |
+| `openstock api login [--appkey KEY] [--appsecret SECRET] [--force]` | Issue or reuse a KIS access token. |
+| `openstock api call <endpoint> --param KEY=VALUE` | Direct KIS GET endpoint call with token headers. |
+
+## `api list`
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | none |
+| File IO | none |
+| Side effect | none |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `count` | Number of registered broker APIs. |
+| `apis` | Broker metadata, credential requirements, capability catalog, IO contract, and side effects. |
+
+## `api login`
+
+### Usage
+
+```bash
+openstock api login
+openstock api login --force
+```
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCESS_TOKEN`, `KIS_ACCESS_TOKEN_EXPIRED_AT` |
+| Config write | `~/.config/openstock/.env` auth state. |
+| External IO | KIS token endpoint only when token is missing, expired, or `--force` is used. |
+| Side effect | Writes auth token state. |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for login. |
+| `status` | Login result. |
+| `force` | Whether token refresh was forced. |
+| `credential_source` | Whether credentials came from CLI arguments or config. |
+| `token_storage` | Token storage path and env keys. |
+| `side_effect` | Auth-state write indicator. |
+
+## `api call`
+
+### Usage
+
+```bash
+openstock api call /uapi/... --param tr_id=... --param KEY=VALUE
+```
+
+### IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET` |
+| External IO | KIS endpoint GET. |
+| File IO | `~/.config/openstock/.env` read. |
+| Side effect | Endpoint dependent. |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker used for the direct call. |
+| `endpoint` | Requested endpoint. |
+| `params` | Request parameters. |
+| `request_semantics` | How params map to headers/query. |
+| `response` | Parsed API response. |
+| `response_semantics` | Explanation of response meaning. |
+
+## Agent Notes
+
+Prefer typed commands. Use `api call` only for inspection or endpoints not yet bound as typed commands.

skills/openstock-agent-cli/references/commands/api/list/guide.md

@@ -0,0 +1,15 @@
+# `openstock api list`
+
+Purpose: return registered broker APIs, credential requirements, capabilities, IO contracts, and side-effect metadata.
+
+Usage:
+
+```bash
+openstock api list
+```
+
+Inputs: none.
+
+Output fields: `count`, `apis`.
+
+Agent rule: use this to discover broker capability metadata; it performs no external IO.

skills/openstock-agent-cli/references/commands/api/login/guide.md

@@ -0,0 +1,21 @@
+# `openstock api login`
+
+Purpose: issue or reuse a KIS live API access token.
+
+Usage:
+
+```bash
+openstock api login
+openstock api login --force
+openstock api login --appkey KEY --appsecret SECRET
+```
+
+Inputs: optional `--appkey`, `--appsecret`, `--force`.
+
+Reads: `KIS_APPKEY`, `KIS_APPSECRET`, existing token values.
+
+Writes: `~/.config/openstock/.env` token state.
+
+Output fields: `broker`, `status`, `force`, `credential_source`, `token_storage`, `side_effect`.
+
+Agent rule: do not force refresh unless the user asks or an API call fails because the token is invalid.

skills/openstock-agent-cli/references/commands/cache/guide.md

@@ -0,0 +1,39 @@
+# `openstock cache`
+
+## Purpose
+
+Inspect and prune local cache under `~/.config/openstock/cache`.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock cache status` | Show cache size and namespace summary. |
+| `openstock cache prune [--dry-run]` | Apply cache retention policy. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| File read | Cache directories. |
+| File delete | Old cache files unless `--dry-run` is used. |
+| External IO | none |
+| Side effect | `prune` deletes files unless dry-run. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `root` | Cache root path. |
+| `exists` | Whether cache root exists. |
+| `total_files` | Number of cache files. |
+| `total_bytes` | Total cache size. |
+| `namespaces` | Cache namespace summaries. |
+| `dry_run` | Whether prune only reported actions. |
+| `deleted_files` | Number of deleted files. |
+| `deleted_bytes` | Bytes removed. |
+| `reports` | Prune reports by namespace. |
+
+## Agent Notes
+
+Run `cache prune --dry-run` before destructive pruning unless the user clearly asks to clean cache.

skills/openstock-agent-cli/references/commands/cache/prune/guide.md

@@ -0,0 +1,18 @@
+# `openstock cache prune`
+
+Purpose: apply cache retention policy.
+
+Usage:
+
+```bash
+openstock cache prune --dry-run
+openstock cache prune
+```
+
+Reads: `~/.config/openstock/cache`.
+
+Deletes: old cache files unless `--dry-run` is set.
+
+Output fields: `dry_run`, `deleted_files`, `deleted_bytes`, `reports`.
+
+Agent rule: run `--dry-run` first unless the user explicitly requests cleanup.

skills/openstock-agent-cli/references/commands/cache/status/guide.md

@@ -0,0 +1,15 @@
+# `openstock cache status`
+
+Purpose: inspect local cache size and namespace summary.
+
+Usage:
+
+```bash
+openstock cache status
+```
+
+Reads: `~/.config/openstock/cache`.
+
+Output fields: `root`, `exists`, `total_files`, `total_bytes`, `namespaces`.
+
+Agent rule: use before cache cleanup or when diagnosing stale local data.

skills/openstock-agent-cli/references/commands/dart/corp/guide.md

@@ -0,0 +1,17 @@
+# `openstock dart corp`
+
+Purpose: resolve a KRX stock symbol to an OpenDART corp code.
+
+Usage:
+
+```bash
+openstock dart corp 005930
+```
+
+Input: `symbol`.
+
+Reads: OpenDART corp code cache; refreshes on miss when needed.
+
+Output fields: `stock_code`, `corp_code`, `corp_name`, `modify_date`.
+
+Agent rule: use when an OpenDART command needs an explicit corp code.

skills/openstock-agent-cli/references/commands/dart/disclosures/guide.md

@@ -0,0 +1,20 @@
+# `openstock dart disclosures`
+
+Purpose: query disclosure lists from OpenDART.
+
+Usage:
+
+```bash
+openstock dart disclosures 005930 --from 20260601 --to 20260609
+openstock dart disclosures --corp-code 00126380 --page-count 50
+```
+
+Inputs: optional `symbol`, `--corp-code`, `--from`, `--to`, `--corp-cls`, `--page-no`, `--page-count`.
+
+Reads: `OPENDART_API_KEY`; corp-code cache when resolving a symbol.
+
+External IO: OpenDART list API.
+
+Output fields: `query`, `resolved`, `disclosures`.
+
+Agent rule: use for disclosure evidence lists without fetching document text.

skills/openstock-agent-cli/references/commands/dart/document/guide.md

@@ -0,0 +1,19 @@
+# `openstock dart document`
+
+Purpose: fetch and extract text from a DART disclosure document by receipt number.
+
+Usage:
+
+```bash
+openstock dart document 20260609000000 --max-chars 20000
+```
+
+Inputs: `rcept_no`, optional `--force`, `--max-chars`.
+
+Reads: `OPENDART_API_KEY`.
+
+Writes: document ZIP cache.
+
+Output fields: document metadata and extracted text.
+
+Agent rule: use `--max-chars` to cap large documents.

skills/openstock-agent-cli/references/commands/dart/guide.md

@@ -0,0 +1,43 @@
+# `openstock dart`
+
+## Purpose
+
+Query OpenDART listed-company mappings, disclosure lists, and disclosure documents.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock dart sync [--force]` | Refresh OpenDART corp code cache. |
+| `openstock dart status` | Show corp code cache status. |
+| `openstock dart corp <symbol>` | Resolve KRX symbol to DART corp code. |
+| `openstock dart disclosures [symbol] [--corp-code CODE] [--from YYYYMMDD] [--to YYYYMMDD] [--corp-cls Y|K|N|E] [--page-no N] [--page-count N]` | Query disclosure list. |
+| `openstock dart document <rcept_no> [--force] [--max-chars N]` | Fetch disclosure document text. |
+| `openstock dart show <symbol> [--from YYYYMMDD] [--to YYYYMMDD] [--index N] [--page-count N] [--force] [--max-chars N]` | Query disclosures for a symbol and fetch one selected document. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `OPENDART_API_KEY` for OpenDART API calls. |
+| External IO | OpenDART corp code, list, and document endpoints. |
+| File read/write | `~/.config/openstock/cache/opendart`. |
+| Side effect | `sync`, `document`, and `show` can write cache. |
+
+## Important Fields
+
+| Field | Meaning |
+| --- | --- |
+| `stock_code` | KRX stock code. |
+| `corp_code` | OpenDART 8-digit company code. |
+| `corp_name` | OpenDART company name. |
+| `modify_date` | Corp code mapping modification date. |
+| `query` | Disclosure query sent to OpenDART. |
+| `resolved` | Symbol/corp code resolution details. |
+| `disclosures` | Disclosure list. |
+| `selected` | Disclosure selected by `--index`. |
+| `document` | Disclosure document metadata and extracted text. |
+
+## Agent Notes
+
+Use `dart show` for the common workflow: symbol to disclosures to selected document. Use `dart disclosures` when only the list is needed.

skills/openstock-agent-cli/references/commands/dart/show/guide.md

@@ -0,0 +1,19 @@
+# `openstock dart show`
+
+Purpose: query disclosures for a symbol and fetch the selected disclosure document.
+
+Usage:
+
+```bash
+openstock dart show 005930 --from 20260601 --to 20260609 --index 1
+```
+
+Inputs: `symbol`, optional `--from`, `--to`, `--index`, `--page-count`, `--force`, `--max-chars`.
+
+Reads: `OPENDART_API_KEY`; corp-code and document cache.
+
+External IO: OpenDART list and document APIs.
+
+Output fields: `query`, `resolved`, `disclosures`, `selected`, `document`.
+
+Agent rule: preferred command when the task asks for a specific stock's latest disclosure and contents.

skills/openstock-agent-cli/references/commands/dart/status/guide.md

@@ -0,0 +1,15 @@
+# `openstock dart status`
+
+Purpose: inspect OpenDART corp code cache status.
+
+Usage:
+
+```bash
+openstock dart status
+```
+
+Reads: OpenDART corp code cache.
+
+Output fields: source/cache metadata and corp count.
+
+Agent rule: if cache is missing, run `openstock dart sync`.

skills/openstock-agent-cli/references/commands/dart/sync/guide.md

@@ -0,0 +1,18 @@
+# `openstock dart sync`
+
+Purpose: refresh OpenDART listed-company corp code mapping cache.
+
+Usage:
+
+```bash
+openstock dart sync
+openstock dart sync --force
+```
+
+Reads: `OPENDART_API_KEY`.
+
+Writes: `~/.config/openstock/cache/opendart/corp_codes.json`.
+
+Output fields: source/cache metadata and corp count.
+
+Agent rule: run when corp-code cache is missing, stale, or explicitly requested.

skills/openstock-agent-cli/references/commands/guide.md

@@ -0,0 +1,30 @@
+# OpenStock CLI Command Map
+
+This directory mirrors the `openstock` CLI command depth for agent execution.
+
+| CLI Depth | Folder |
+| --- | --- |
+| `openstock version` | `version/` |
+| `openstock update` | `update/` |
+| `openstock search` | `search/` |
+| `openstock api ...` | `api/` |
+| `openstock account ...` | `account/` |
+| `openstock market ...` | `market/` |
+| `openstock universe ...` | `universe/` |
+| `openstock dart ...` | `dart/` |
+| `openstock order ...` | `order/` |
+| `openstock cache ...` | `cache/` |
+
+Subcommands also have leaf folders matching CLI depth, for example:
+
+| CLI Depth | Folder |
+| --- | --- |
+| `openstock api login` | `api/login/` |
+| `openstock account status` | `account/status/` |
+| `openstock market history` | `market/history/` |
+| `openstock universe chunks` | `universe/chunks/` |
+| `openstock dart show` | `dart/show/` |
+| `openstock order buy` | `order/buy/` |
+| `openstock cache prune` | `cache/prune/` |
+
+Agents should read `../../SKILL.md` first, then open the folder matching the command depth they intend to run.

skills/openstock-agent-cli/references/commands/market/guide.md

@@ -0,0 +1,60 @@
+# `openstock market`
+
+## Purpose
+
+Read KIS market data for a stock symbol.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock market <symbol>` | Current price and company/basic information. |
+| `openstock market history <symbol> --from YYYYMMDD --to YYYYMMDD [--period D|W|M|Y] [--raw-price]` | OHLCV price history. |
+
+## `market <symbol>`
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for data. |
+| `symbol` | Queried KRX symbol. |
+| `price` | Current price and market values. |
+| `company` | Stock/company basic information. |
+
+## `market history`
+
+### Input
+
+| Input | Meaning |
+| --- | --- |
+| `symbol` | KRX symbol. |
+| `--from` | Start date in `YYYYMMDD`. |
+| `--to` | End date in `YYYYMMDD`. |
+| `--period` | `D`, `W`, `M`, or `Y`; default `D`. |
+| `--raw-price` | Use original prices instead of adjusted prices. |
+
+### Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker API used for data. |
+| `symbol` | Queried KRX symbol. |
+| `period` | Candle period. |
+| `date_range` | Requested date range. |
+| `adjusted` | Whether adjusted price was requested. |
+| `count` | Number of candles. |
+| `candles` | Date-ascending OHLCV values. Numeric values may be strings. |
+| `summary` | KIS summary data. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | KIS app credentials and access token. |
+| External IO | KIS domestic stock quote/history endpoints. |
+| Side effect | none |
+
+## Agent Notes
+
+Use `market` for current context and `market history` for price movement evidence. Always resolve ambiguous names with `search` first.

skills/openstock-agent-cli/references/commands/market/history/guide.md

@@ -0,0 +1,20 @@
+# `openstock market history`
+
+Purpose: query OHLCV price history for a stock.
+
+Usage:
+
+```bash
+openstock market history 005930 --from 20260101 --to 20260609
+openstock market history 005930 --from 20260101 --to 20260609 --period W
+```
+
+Inputs: `symbol`, `--from`, `--to`, optional `--period`, `--raw-price`.
+
+Reads: KIS credentials and access token.
+
+External IO: KIS price history endpoint.
+
+Output fields: `broker`, `symbol`, `period`, `date_range`, `adjusted`, `count`, `candles`, `summary`.
+
+Agent rule: use for price movement evidence; keep numeric strings intact unless calculating.

skills/openstock-agent-cli/references/commands/order/buy/guide.md

@@ -0,0 +1,20 @@
+# `openstock order buy`
+
+Purpose: place a live KIS domestic stock buy order.
+
+Usage:
+
+```bash
+openstock order buy 005930 --qty 1 --price 70000
+openstock order buy 005930 --qty 1 --market
+```
+
+Inputs: `symbol`, `--qty`, one of `--price` or `--market`.
+
+External IO: KIS live order endpoint.
+
+Side effect: live financial buy order.
+
+Output fields: `broker`, `side`, `symbol`, `qty`, `order_type`, `price`, `order`.
+
+Agent rule: only run after explicit current-user approval for a real order.

skills/openstock-agent-cli/references/commands/order/guide.md

@@ -0,0 +1,52 @@
+# `openstock order`
+
+## Purpose
+
+Place and query live KIS domestic stock orders.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock order buy <symbol> --qty QTY (--price PRICE|--market)` | Place a live buy order. |
+| `openstock order sell <symbol> --qty QTY (--price PRICE|--market)` | Place a live sell order. |
+| `openstock order status [order_no] [--from YYYYMMDD] [--to YYYYMMDD]` | Query order/execution status. |
+
+## Safety
+
+`buy` and `sell` are live financial orders. Do not run them unless the user explicitly asks for a real order in the current task.
+
+Before placing an order:
+
+1. Run `openstock account status`.
+2. Confirm the symbol with `search` or `market`.
+3. Confirm side, quantity, order type, and price.
+4. Prefer `order status` for verification after order placement.
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| Env read | `KIS_ACCESS_TOKEN`, `KIS_APPKEY`, `KIS_APPSECRET`, `KIS_ACCOUNT` |
+| External IO | KIS order and order inquiry endpoints. |
+| Side effect | `buy` and `sell` place live orders. `status` is read-only. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `broker` | Broker used for order. |
+| `side` | `buy` or `sell`. |
+| `symbol` | Ordered symbol. |
+| `qty` | Order quantity. |
+| `order_type` | `limit` or `market`. |
+| `price` | Limit price or market-order price representation. |
+| `order` | Broker order result. |
+| `account` | Account queried for status. |
+| `order_no` | Requested order number filter. |
+| `orders` | Order/execution list. |
+| `summary` | Broker summary values. |
+
+## Agent Notes
+
+For analysis-only tasks, never use `buy` or `sell`. Use `order status` only when order history is relevant.

skills/openstock-agent-cli/references/commands/order/sell/guide.md

@@ -0,0 +1,20 @@
+# `openstock order sell`
+
+Purpose: place a live KIS domestic stock sell order.
+
+Usage:
+
+```bash
+openstock order sell 005930 --qty 1 --price 70000
+openstock order sell 005930 --qty 1 --market
+```
+
+Inputs: `symbol`, `--qty`, one of `--price` or `--market`.
+
+External IO: KIS live order endpoint.
+
+Side effect: live financial sell order.
+
+Output fields: `broker`, `side`, `symbol`, `qty`, `order_type`, `price`, `order`.
+
+Agent rule: only run after explicit current-user approval for a real order.

skills/openstock-agent-cli/references/commands/order/status/guide.md

@@ -0,0 +1,18 @@
+# `openstock order status`
+
+Purpose: query KIS order and execution status.
+
+Usage:
+
+```bash
+openstock order status
+openstock order status 1234567890 --from 20260601 --to 20260609
+```
+
+Inputs: optional `order_no`, `--from`, `--to`.
+
+External IO: KIS order inquiry endpoint.
+
+Output fields: `broker`, `account`, `order_no`, `orders`, `summary`.
+
+Agent rule: read-only; use after order placement or when auditing order history.

skills/openstock-agent-cli/references/commands/search/guide.md

@@ -0,0 +1,38 @@
+# `openstock search`
+
+## Purpose
+
+Search stock candidates by name or symbol using Naver mobile stock search.
+
+## Usage
+
+```bash
+openstock search 삼성전자
+openstock search 005930
+```
+
+## Input
+
+| Input | Meaning |
+| --- | --- |
+| `query` | Stock name or stock code. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | `GET https://m.stock.naver.com/front-api/search/autoComplete` |
+| File IO | none |
+| Side effect | none |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `provider` | External data provider. |
+| `query` | Query submitted by the user/agent. |
+| `stocks` | Matching stock candidates. Items can include code, name, market, market code, nation code, category, Reuters code, and URL. |
+
+## Agent Notes
+
+Use this to resolve a human company name to a tradable symbol before calling `market`, `market history`, or `dart`.

skills/openstock-agent-cli/references/commands/universe/chunks/guide.md

@@ -0,0 +1,17 @@
+# `openstock universe chunks`
+
+Purpose: divide the stock universe into scan chunks.
+
+Usage:
+
+```bash
+openstock universe chunks --market KOSDAQ --kind common_stock --size 100
+```
+
+Inputs: optional `--market`, `--kind`, `--size`.
+
+Reads: universe cache.
+
+Output fields: `source`, `cache_date`, `filtered_count`, `chunk_size`, `chunk_count`, `chunks`.
+
+Agent rule: preferred for full-market scan planning.

skills/openstock-agent-cli/references/commands/universe/guide.md

@@ -0,0 +1,46 @@
+# `openstock universe`
+
+## Purpose
+
+Build and query a local universe of listed Korean stocks from KIND.
+
+## Subcommands
+
+| Command | Purpose |
+| --- | --- |
+| `openstock universe sync [--force]` | Refresh KIND universe cache. |
+| `openstock universe status` | Show local universe cache status. |
+| `openstock universe list [--market MARKET] [--kind KIND] [--offset N] [--limit N]` | Page through stocks. |
+| `openstock universe chunks [--market MARKET] [--kind KIND] [--size N]` | Build scan chunks. |
+| `openstock universe validate` | Validate expected size and representative symbols. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | KIND listed company download on sync/cache miss. |
+| File read/write | `~/.config/openstock/cache/universe/kind`. |
+| Side effect | `sync` writes cache and prunes old snapshots. Read commands can sync on cache miss. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `source` | Data source. |
+| `cache_date` | Cache date. |
+| `refreshed_at` | Refresh timestamp. |
+| `refreshed` | Whether command refreshed data. |
+| `stock_count` | Number of stocks in snapshot. |
+| `counts_by_market` | Count by market. |
+| `total_count` | Total stocks before filtering. |
+| `filtered_count` | Stocks after filter. |
+| `offset` | Pagination offset. |
+| `limit` | Pagination limit. |
+| `stocks` | Normalized stock records. |
+| `chunk_size` | Requested chunk size. |
+| `chunk_count` | Number of chunks. |
+| `chunks` | Scan chunk list. |
+
+## Agent Notes
+
+Use `chunks` when scanning many stocks. Do not request the whole universe if a paged or chunked workflow is enough.

skills/openstock-agent-cli/references/commands/universe/list/guide.md

@@ -0,0 +1,17 @@
+# `openstock universe list`
+
+Purpose: page through normalized stock universe records.
+
+Usage:
+
+```bash
+openstock universe list --market KOSPI --kind common_stock --offset 0 --limit 100
+```
+
+Inputs: optional `--market`, `--kind`, `--offset`, `--limit`.
+
+Reads: universe cache; may refresh on cache miss.
+
+Output fields: `source`, `cache_date`, `total_count`, `filtered_count`, `offset`, `limit`, `stocks`.
+
+Agent rule: use pagination instead of loading the full universe when possible.

skills/openstock-agent-cli/references/commands/universe/status/guide.md

@@ -0,0 +1,15 @@
+# `openstock universe status`
+
+Purpose: inspect local KIND universe cache status.
+
+Usage:
+
+```bash
+openstock universe status
+```
+
+Reads: universe cache.
+
+Output fields: `source`, `cache_date`, `refreshed_at`, `refreshed`, `stock_count`, `counts_by_market`.
+
+Agent rule: if cache is missing, run `openstock universe sync`.

skills/openstock-agent-cli/references/commands/universe/sync/guide.md

@@ -0,0 +1,18 @@
+# `openstock universe sync`
+
+Purpose: refresh KIND listed stock universe cache.
+
+Usage:
+
+```bash
+openstock universe sync
+openstock universe sync --force
+```
+
+External IO: KIND listed company download.
+
+Writes: `~/.config/openstock/cache/universe/kind`.
+
+Output fields: `source`, `cache_date`, `refreshed_at`, `refreshed`, `stock_count`, `counts_by_market`.
+
+Agent rule: run before broad scans if the cache date matters.

skills/openstock-agent-cli/references/commands/universe/validate/guide.md

@@ -0,0 +1,18 @@
+# `openstock universe validate`
+
+Purpose: validate universe size and representative stock expectations.
+
+Usage:
+
+```bash
+openstock universe validate
+openstock universe validate --expect 005930=삼성전자
+```
+
+Inputs: minimum count options and repeated `--expect SYMBOL=NAME`.
+
+Reads: universe cache.
+
+Output fields: validation checks and status.
+
+Agent rule: run after sync when verifying that the cached universe is usable.

skills/openstock-agent-cli/references/commands/update/guide.md

@@ -0,0 +1,49 @@
+# `openstock update`
+
+## Purpose
+
+Update the installed `openstock` binary from the latest Gitea release asset.
+
+## Usage
+
+```bash
+openstock update
+openstock update --force
+```
+
+## Input
+
+| Input | Meaning |
+| --- | --- |
+| `--force` | Reinstall from the latest release asset even when the current version matches. |
+| `OPENSTOCK_INSTALL_DIR` | Optional install directory override. |
+| `OPENSTOCK_RELEASE_API_URL` | Optional release API URL override. |
+| `OPENSTOCK_RELEASE_ASSET_SUFFIX` | Optional asset suffix override. |
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | Gitea latest release API and selected release asset download. |
+| File write | Installed `openstock` binary. |
+| Side effect | Replaces the installed binary when newer or forced. |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `release_api_url` | Gitea release API endpoint used for update discovery. |
+| `current_version` | Version of the running binary. |
+| `latest_version` | Version parsed from latest release tag. |
+| `release_tag` | Latest release tag. |
+| `release_url` | Human-readable release page. |
+| `asset_name` | Release asset selected for installation. |
+| `asset_url` | Asset download URL. |
+| `install_dir` | Directory where the binary is installed. |
+| `status` | `updated` or `up_to_date`. |
+| `stdout` | Installer stdout. |
+| `stderr` | Installer stderr. |
+
+## Agent Notes
+
+Use `--force` only when the user asks to reinstall or when verifying release assets.

skills/openstock-agent-cli/references/commands/version/guide.md

@@ -0,0 +1,34 @@
+# `openstock version`
+
+## Purpose
+
+Return the installed `openstock` package name and version.
+
+## Usage
+
+```bash
+openstock version
+```
+
+## Input
+
+No arguments.
+
+## IO
+
+| Direction | Data |
+| --- | --- |
+| External IO | none |
+| File IO | none |
+| Side effect | none |
+
+## Output Fields
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Cargo package/program name. |
+| `version` | Version of the running `openstock` binary. |
+
+## Agent Notes
+
+Use this before update checks or when reporting runtime provenance.