@kiyeonjeon21/ncli 0.1.16 → 0.1.18

package/README.md

@@ -1,11 +1,52 @@
 # ncli
 
+[![npm](https://img.shields.io/npm/v/@kiyeonjeon21/ncli)](https://www.npmjs.com/package/@kiyeonjeon21/ncli)
+[![CI](https://github.com/kiyeonjeon21/naver-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/kiyeonjeon21/naver-cli/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/node/v/@kiyeonjeon21/ncli)](https://nodejs.org/)
+
 Agent-native CLI for Naver Open APIs.
 
 > Unofficial CLI for Naver Open APIs. Not affiliated with NAVER Corp.
 
 https://github.com/user-attachments/assets/c5776c61-b504-4aaa-bb08-591d4a95c4a1
 
+---
+
+## Why ncli?
+
+Naver Open APIs have no official CLI. Existing tools are either MCP servers (high token cost, 72% reliability) or single-purpose scripts.
+
+ncli is designed **for AI agents first** — structured JSON output, runtime schema introspection, input hardening, and safety rails — following the [agentic-cli-guide](https://github.com/kiyeonjeon21/agentic-cli-guide) principles.
+
+| | CLI (ncli) | MCP |
+|---|---|---|
+| Token cost | **1x** | 10-32x |
+| Reliability | **100%** | ~72% |
+| Startup | **Instant** | Protocol negotiation |
+| Context overhead | **Minimal** | 43+ tool schemas injected |
+
+---
+
+## Table of Contents
+
+- [Install](#install)
+- [Setup](#setup)
+- [Usage](#usage)
+  - [Search](#search)
+  - [DataLab](#datalab)
+  - [CAPTCHA](#captcha)
+  - [Schema Introspection](#schema-introspection)
+- [Agent-First Design](#agent-first-design)
+- [Rate Limits](#rate-limits)
+- [Configuration](#configuration)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Install
 
 ```bash
@@ -51,7 +92,7 @@ ncli search blog "TypeScript" --page-all --max-results 50 --output ndjson
 echo '{"query":"AI","display":5}' | ncli search blog --json -
 ```
 
-Available search types: `blog`, `news`, `web`, `image`, `book`, `cafe`, `kin`, `encyclopedia`, `shop`, `local`, `errata`, `adult`, `doc`
+Available search types: `blog` `news` `web` `image` `book` `cafe` `kin` `encyclopedia` `shop` `local` `errata` `adult` `doc`
 
 ### DataLab
 
@@ -110,48 +151,32 @@ ncli search blog --describe
 ### Other Commands
 
 ```bash
-# Check auth status
-ncli auth status
-
-# Print CONTEXT.md for agent consumption
-ncli context
-
-# Show version
-ncli --version
+ncli auth status       # Check authentication
+ncli context           # Print CONTEXT.md for agents
+ncli --version         # Show version
+ncli --help            # Show help
 ```
 
 ## Agent-First Design
 
-ncli is built for AI agents following the [agentic-cli-guide](https://github.com/kiyeonjeon21/agentic-cli-guide) principles:
-
 | Feature | Flag | Purpose |
 |---------|------|---------|
 | JSON output | `--output json` (default) | Machine-readable output |
-| NDJSON streaming | `--output ndjson` | Line-by-line streaming for large results |
+| NDJSON streaming | `--output ndjson` | Line-by-line streaming |
 | Field masks | `--fields "title,link"` | Reduce token usage |
 | Dry-run | `--dry-run` | Validate without executing |
-| Sanitize | `--sanitize` | Filter prompt injection in API responses |
+| Sanitize | `--sanitize` | Filter prompt injection |
 | Schema | `--describe` / `ncli schema` | Runtime API introspection |
 | Stdin | `--json -` | Pipe JSON payloads |
 | File input | `--json @payload.json` | Read JSON from file |
-| Pagination | `--page-all --max-results N` | Auto-paginate search results |
-| Context | `ncli context` | Inject CONTEXT.md into agent context |
-
-### Why CLI over MCP?
-
-| Metric | CLI | MCP |
-|--------|-----|-----|
-| Token cost | 1x | 10-32x |
-| Reliability | 100% | ~72% |
-| Startup | Instant | Protocol negotiation |
-
-CLI is the pragmatic choice for agent tooling. MCP servers for Naver APIs [already exist](https://github.com/isnow890/naver-search-mcp) for environments that need them.
+| Pagination | `--page-all --max-results N` | Auto-paginate results |
+| Context | `ncli context` | Inject CONTEXT.md into agent |
 
 ## Rate Limits
 
 | API | Limit |
 |-----|-------|
-| Search (all types) | 25,000/day |
+| Search (all 13 types) | 25,000/day |
 | DataLab (trend) | 1,000/day |
 | DataLab (shopping) | 1,000/day |
 | CAPTCHA | 1,000/day |
@@ -173,10 +198,24 @@ npm install
 cp .env.example .env  # add your credentials
 
 npm run dev -- search blog "test"   # run in dev mode
-npm test                             # run tests (58 tests)
+npm test                             # run tests
 npm run build                        # compile TypeScript
 ```
 
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `AUTH_REQUIRED` | Run `ncli init` or set `NAVER_CLIENT_ID` and `NAVER_CLIENT_SECRET` |
+| `HTTP_400` on DataLab | `endDate` must not be in the future |
+| `HTTP_429` rate limited | Wait until daily limit resets (midnight KST) |
+| Old version after install | Run `npm uninstall -g naver-cli` to remove legacy package |
+| `Scope Status Invalid` | Check API permissions at [developers.naver.com/apps](https://developers.naver.com/apps/) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and release flow.
+
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiyeonjeon21/ncli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Agent-native CLI for Naver Open APIs",
   "type": "module",
   "bin": {
@@ -12,6 +12,9 @@
     "AGENTS.md",
     "skills"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli.ts",