From 2b5a1b28de26144a913e94cb9cb0e1f2bf22735d Mon Sep 17 00:00:00 2001
From: Ciphercat <78522797+0xrsydn@users.noreply.github.com>
Date: Thu, 5 Mar 2026 18:00:29 +0000
Subject: [PATCH] docs: add AGENTS.md + CLAUDE.md symlink for agent-first
 development

- Project summary, stack, structure map
- Dev commands, verification, rules
- CLAUDE.md symlinked to AGENTS.md (works with any agent harness)
---
 AGENTS.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a7a71f6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,78 @@
+# AGENTS.md
+
+## Project
+`idx-cli` — CLI tool for Indonesian stock market (IDX) analysis. Built in Rust for humans and AI agents. Single binary, zero runtime deps.
+
+## Stack
+- **Language:** Rust (stable, via rust-overlay)
+- **CLI:** clap 4 (derive)
+- **HTTP:** ureq 3 (sync, no async runtime)
+- **Output:** comfy-table, owo-colors
+- **Config:** TOML (`~/.config/idx/config.toml`)
+- **Cache:** JSON file-based (`~/.cache/idx/`)
+- **Testing:** cargo nextest, assert_cmd, predicates
+- **Hooks:** prek (pre-commit: fmt+clippy, pre-push: test)
+
+## Structure
+```
+src/
+├── main.rs              # Entry point, clap setup, command dispatch
+├── cli/                 # Command definitions (clap structs + handlers)
+│   ├── stocks.rs        # stocks quote, history commands
+│   ├── config.rs        # config get/set/init/path
+│   └── cache.rs         # cache info/clear
+├── api/                 # Data provider abstraction + implementations
+│   ├── mod.rs           # MarketDataProvider trait
+│   ├── yahoo.rs         # Yahoo Finance provider (query2 endpoint)
+│   └── types.rs         # Quote, OHLC, Period, Interval types
+├── output/              # Rendering layer (table, json)
+│   ├── table.rs         # comfy-table + owo-colors
+│   └── json.rs          # serde_json pretty print
+├── cache.rs             # File-based TTL cache
+├── config.rs            # Config loading + merge (flags > env > file > defaults)
+└── error.rs             # IdxError enum (thiserror)
+tests/
+├── cli.rs               # Integration tests (assert_cmd, mock provider)
+docs-internal/           # (gitignored) Specs, research, business strategy
+```
+
+## Development
+```bash
+# Enter dev shell (requires Nix + direnv)
+direnv allow  # or: nix develop
+
+# Build
+cargo build
+
+# Run
+cargo run -- stocks quote BBCA
+cargo run -- -o json stocks quote BBCA,BBRI
+cargo run -- stocks history BBCA --period 3mo
+
+# Test
+cargo nextest run   # or: cargo test
+
+# Lint
+cargo fmt --check
+cargo clippy -- -D warnings
+```
+
+## Docs
+- `docs-internal/SPEC.md` — system design, command tree, milestones (gitignored)
+- `docs-internal/TODO.md` — task breakdown with checklist (gitignored)
+- `docs-internal/OWNERSHIP_FEATURE_DESIGN.md` — ownership intelligence feature design (gitignored)
+
+## Verification
+```bash
+cargo build              # must compile
+cargo clippy -- -D warnings  # zero warnings
+cargo nextest run        # all tests pass
+```
+Hooks enforce this: prek runs fmt+clippy on commit, tests on push.
+
+## Rules
+1. **Provider abstraction** — all data access goes through `MarketDataProvider` trait, never call Yahoo directly from commands
+2. **Sync only** — no tokio/async, this is a CLI tool using ureq
+3. **Test with fixtures** — never hit live APIs in tests, use mock provider + fixture JSON
+4. **Output contract** — table mode to stdout for humans, `--json` for machines, errors to stderr
+5. **Symbol resolution** — always normalize symbols (`BBCA` → `BBCA.JK`) before API calls
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file