Add OpenStock agent CLI skill

2026-06-09 17:22:59 +09:00
parent 9e4d6aecc7
commit 347c9546ed
34 changed files with 1005 additions and 0 deletions
@@ -174,6 +174,15 @@ docker compose logs --tail=120 openstock-runner
 | `status` | string | 항상 `error`입니다. |
 | `message` | string | 실패 원인 메시지입니다. |
 ## Agent CLI Skill
 에이전트는 별도 MCP 서버나 plugin wrapper 없이 `openstock` CLI를 직접 실행하는 전략을 사용합니다.
 | Document | Purpose |
 | --- | --- |
 | `skills/openstock-agent-cli/SKILL.md` | 에이전트가 따라야 할 실행 전략, 출력 해석 규칙, 주문 안전 규칙 |
 | `skills/openstock-agent-cli/references/commands/` | CLI depth별 명령 설명과 IO 계약 |
 ### Command Output Fields
 #### `version`
@@ -0,0 +1,97 @@
 ---
 name: openstock-agent-cli
 description: Use when operating OpenStock through its CLI for Korean stock search, KIS market/account/order commands, KIND universe scans, OpenDART disclosures, cache management, or agent-safe trading evidence workflows. This skill intentionally avoids MCP/plugin wrappers and relies on direct CLI execution.
 ---
 # OpenStock Agent CLI Skill
 Use this skill when an agent needs Korean stock search, market data, KIS account/order access, KIND universe data, or OpenDART disclosure evidence from this repository.
 ## Strategy
 Do not start an MCP server or create a plugin wrapper. Use the installed `openstock` CLI directly and treat its stdout/stderr JSON as the tool contract.
 The CLI is the single integration surface for humans and agents:
 ```bash
 openstock search 삼성전자
 openstock market 005930
 openstock dart show 005930 --from 20260601 --to 20260609
 openstock account status
 ```
 ## Runtime Model
 - `openstock` is a normal process per command invocation.
 - It is not a daemon.
 - It does not open a port.
 - It reads config and cache from `~/.config/openstock`.
 - It prints one JSON object to stdout on success.
 - It prints one JSON object to stderr on failure.
 ## Output Contract
 Every command returns explained JSON:
 ```json
 {
  "command": "logical command name",
  "description": "human and agent readable result description",
  "fields": [
    {
      "name": "field_name",
      "description": "field meaning",
      "value": "actual value"
    }
  ],
  "raw": null
 }
 ```
 Agent behavior:
 - Read `fields[].description` before interpreting `fields[].value`.
 - Prefer typed commands over `api call` when a typed command exists.
 - Use `raw` only when the command explicitly returns raw API data.
 - Preserve numeric strings from broker APIs; do not coerce them unless calculation is required.
 - Treat stderr JSON as a command failure even when it is parseable.
 ## Safety Rules
 - `order buy` and `order sell` are live KIS orders.
 - Do not place orders unless the user explicitly requests a real order in the current task.
 - Before any order, check `account status`, target symbol evidence, quantity, order type, and price.
 - For evidence gathering, use read-only commands: `search`, `market`, `market history`, `dart`, `universe`, `account status`, `order status`.
 - Never infer that a missing cache means missing data; run the relevant `sync` command when appropriate.
 ## Command Documentation
 Commands are documented by CLI depth under `references/commands`.
 | Command | Documentation |
 | --- | --- |
 | `openstock version` | `references/commands/version/guide.md` |
 | `openstock update` | `references/commands/update/guide.md` |
 | `openstock search` | `references/commands/search/guide.md` |
 | `openstock api *` | `references/commands/api/guide.md` |
 | `openstock account *` | `references/commands/account/guide.md` |
 | `openstock market *` | `references/commands/market/guide.md` |
 | `openstock universe *` | `references/commands/universe/guide.md` |
 | `openstock dart *` | `references/commands/dart/guide.md` |
 | `openstock order *` | `references/commands/order/guide.md` |
 | `openstock cache *` | `references/commands/cache/guide.md` |
 ## Recommended Evidence Flow
 ```bash
 openstock api login
 openstock universe sync
 openstock dart sync
 openstock search 삼성전자
 openstock market 005930
 openstock market history 005930 --from 20260101 --to 20260609
 openstock dart show 005930 --from 20260601 --to 20260609 --index 1
 openstock account status
 ```
 This flow gathers evidence. It is not sufficient by itself for unattended trading.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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.