context7-cli 0.2.0

# Changelog / Registro de Mudanças

All notable changes to `context7-cli` will be documented in this file.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## English

---

## [0.2.0] — 2026-04-09

### Added

- **Bilingual runtime UI** — English and Brazilian Portuguese output with auto-detect via system locale (`sys-locale` crate). Override at runtime with `--lang en` or `--lang pt`, or permanently with `CONTEXT7_LANG` environment variable.
- **Public library API** — `context7_cli` crate now published on [docs.rs](https://docs.rs/context7-cli). Programmatic usage is now possible by adding `context7-cli` as a dependency. Public API docstrings written in English (Rust ecosystem convention).
- **`[lib]` target in Cargo.toml** — resolves the docs.rs build failure from v0.1.0 (`error: no library targets found in package`, build #3116184). The `src/lib.rs` module now exposes the public API.
- **`[package.metadata.docs.rs]` section** — proper feature documentation generation on docs.rs.
- **`docs/HOW_TO_USE.md`** — complete bilingual step-by-step guide covering Linux, macOS, and Windows (replaces `como_usa.md`).
- **`docs/context7-skill.md`** — LLM skill file for invoking `context7-cli` from AI assistants. Includes YAML frontmatter, usage patterns, output parsing guide, and error handling.
- **`docs/context7-llm-rules.md`** — 7 prescriptive rules and 5 prompt templates for LLM agents using `context7-cli`.
- **`context7 keys rotate`** — new key operation that manually advances the active key pointer to the next available key in the pool.
- **`-q` short flag** — short alias for `--query` in both the `library` and `docs` subcommands.
- **`CONTEXT7_HOME` environment variable** — alternative XDG base directory for config (primarily useful for testing and CI environments).
- **New dependency** — `sys-locale 0.3` for language auto-detect.
- **New dev dependencies** — `assert_cmd 2` and `predicates 3` for CLI integration tests.
- **`rust-version = "1.75"`** declared in Cargo.toml (MSRV).
- **Integration tests** in `tests/` directory using `assert_cmd` and `predicates`.

### Changed

- **Modular architecture** — refactored from monolithic `context7.rs` (3006 lines) to `src/` with 8 files:
  - `src/lib.rs` — public API exports
  - `src/main.rs` — binary entry point
  - `src/cli.rs` — clap argument parsing
  - `src/api.rs` — HTTP client and Context7 API calls
  - `src/storage.rs` — XDG config persistence
  - `src/output.rs` — colored/JSON/text formatting
  - `src/errors.rs` — structured error types with `thiserror`
  - `src/i18n.rs` — bilingual message lookup table
- **Public API docstrings** — now in English to match docs.rs audience expectations (internal comments and user-facing messages remain in Brazilian Portuguese).
- **README.md** — complete rewrite with bilingual structure (English first, then Português). Added "Why use it?" section with 8 benefits, quick install for 3 OS, and links to new docs files.

### Fixed

- **docs.rs build failure** — v0.1.0 build #3116184 failed with `error: no library targets found in package`. Resolved by adding `[lib]` target in Cargo.toml.
- **`como_usa.md` consolidation** — content migrated and improved in `docs/HOW_TO_USE.md` with bilingual structure and 3-OS coverage.

### Preserved

All v0.1.0 CLI behavior is preserved without breaking changes:
- Subcommands: `library`, `docs`, `keys`
- Aliases: `lib`, `search`, `doc`, `context`, `key`
- XDG storage layout (Linux/macOS/Windows)
- Key file permissions (`0o600` on Unix)
- API key hierarchy (env var → XDG → `.env` → compile-time)
- Retry logic (3 attempts, 500ms → 1s → 2s backoff)
- `--json` and `--text` flags
- All v0.1.0 `keys` suboperations: `add`, `list`, `remove`, `clear`, `path`, `import`, `export` (plus new `rotate`)

---

## [0.1.0] — 2026-04-08

### Added

- Initial release published on [crates.io](https://crates.io/crates/context7-cli) and [GitHub](https://github.com/daniloaguiarbr/context7-cli).
- Native Rust binary `context7` — single file, no runtime dependencies.
- Subcommand `library` (aliases: `lib`, `search`) — search Context7 libraries by name with optional semantic context.
- Subcommand `docs` (aliases: `doc`, `context`) — fetch library documentation by ID with `--query`, `--text`, `--json` flags.
- Subcommand `keys` (alias: `key`) — manage API keys locally via operations `add`, `list`, `remove`, `clear`, `path`, `import`, `export`.
- XDG-compliant config storage (`~/.config/context7/config.toml` on Linux) with `chmod 600` on Unix.
- Multi-key rotation with shuffle without replacement.
- Exponential backoff retry: 3 attempts, 500ms → 1s → 2s.
- Dual logging: stderr with ANSI colors + XDG state file with rotation-by-deletion.
- `--json` global flag for machine-readable output.
- `como_usa.md` — usage guide in Brazilian Portuguese (791 lines).
- License: MIT OR Apache-2.0.

---

## Português

---

## [0.2.0] — 2026-04-09

### Adicionado

- **Interface bilíngue em runtime** — saída em inglês e português brasileiro com auto-detect via locale do sistema (crate `sys-locale`). Override em runtime com `--lang en` ou `--lang pt`, ou permanentemente com a variável de ambiente `CONTEXT7_LANG`.
- **API pública de biblioteca** — o crate `context7_cli` agora está publicado no [docs.rs](https://docs.rs/context7-cli). Uso programático agora é possível adicionando `context7-cli` como dependência. Docstrings da API pública escritas em inglês (convenção do ecossistema Rust).
- **Target `[lib]` no Cargo.toml** — resolve a falha de build no docs.rs da v0.1.0 (`error: no library targets found in package`, build #3116184). O módulo `src/lib.rs` agora expõe a API pública.
- **Seção `[package.metadata.docs.rs]`** — geração correta de documentação de features no docs.rs.
- **`docs/HOW_TO_USE.md`** — guia passo a passo bilíngue completo cobrindo Linux, macOS e Windows (substitui `como_usa.md`).
- **`docs/context7-skill.md`** — arquivo de skill para LLMs invocarem o `context7-cli` a partir de assistentes de IA. Inclui frontmatter YAML, padrões de uso, guia de parsing de output e tratamento de erros.
- **`docs/context7-llm-rules.md`** — 7 regras prescritivas e 5 templates de prompt para agentes LLM usando `context7-cli`.
- **`context7 keys rotate`** — nova operação de chave que avança manualmente o ponteiro da chave ativa para a próxima disponível no pool.
- **Flag curta `-q`** — alias curto para `--query` nos subcomandos `library` e `docs`.
- **Variável de ambiente `CONTEXT7_HOME`** — diretório base XDG alternativo para configuração (principalmente útil para testes e ambientes de CI).
- **Nova dependência** — `sys-locale 0.3` para auto-detect de idioma.
- **Novas dev-dependencies** — `assert_cmd 2` e `predicates 3` para testes de integração da CLI.
- **`rust-version = "1.75"`** declarado no Cargo.toml (MSRV).
- **Testes de integração** no diretório `tests/` usando `assert_cmd` e `predicates`.

### Alterado

- **Arquitetura modular** — refatorado de `context7.rs` monolítico (3006 linhas) para `src/` com 8 arquivos:
  - `src/lib.rs` — exports da API pública
  - `src/main.rs` — ponto de entrada do binário
  - `src/cli.rs` — parsing de argumentos com clap
  - `src/api.rs` — cliente HTTP e chamadas à API Context7
  - `src/storage.rs` — persistência de config XDG
  - `src/output.rs` — formatação colorida/JSON/texto
  - `src/errors.rs` — tipos de erro estruturados com `thiserror`
  - `src/i18n.rs` — tabela de lookup de mensagens bilíngues
- **Docstrings da API pública** — agora em inglês para corresponder às expectativas do público do docs.rs (comentários internos e mensagens para o usuário permanecem em português brasileiro).
- **README.md** — reescrita completa com estrutura bilíngue (inglês primeiro, depois Português). Adicionada seção "Por que usar?" com 8 benefícios, instalação rápida para 3 OS e links para os novos arquivos de docs.

### Corrigido

- **Falha de build no docs.rs** — build #3116184 da v0.1.0 falhou com `error: no library targets found in package`. Resolvido adicionando target `[lib]` no Cargo.toml.
- **Consolidação do `como_usa.md`** — conteúdo migrado e melhorado em `docs/HOW_TO_USE.md` com estrutura bilíngue e cobertura de 3 OS.

### Preservado

Todo comportamento CLI da v0.1.0 está preservado sem breaking changes:
- Subcomandos: `library`, `docs`, `keys`
- Aliases: `lib`, `search`, `doc`, `context`, `key`
- Layout de armazenamento XDG (Linux/macOS/Windows)
- Permissões do arquivo de chaves (`0o600` no Unix)
- Hierarquia de chaves de API (env var → XDG → `.env` → compile-time)
- Lógica de retry (3 tentativas, backoff 500ms → 1s → 2s)
- Flags `--json` e `--text`
- Todas as suboperações de `keys` da v0.1.0: `add`, `list`, `remove`, `clear`, `path`, `import`, `export` (mais a nova `rotate`)

---

## [0.1.0] — 2026-04-08

### Adicionado

- Lançamento inicial publicado no [crates.io](https://crates.io/crates/context7-cli) e [GitHub](https://github.com/daniloaguiarbr/context7-cli).
- Binário Rust nativo `context7` — arquivo único, sem dependências de runtime.
- Subcomando `library` (aliases: `lib`, `search`) — busca bibliotecas Context7 por nome com contexto semântico opcional.
- Subcomando `docs` (aliases: `doc`, `context`) — busca documentação de biblioteca por ID com flags `--query`, `--text`, `--json`.
- Subcomando `keys` (alias: `key`) — gerencia chaves de API localmente via operações `add`, `list`, `remove`, `clear`, `path`, `import`, `export`.
- Armazenamento de config compatível com XDG (`~/.config/context7/config.toml` no Linux) com `chmod 600` no Unix.
- Rotação multi-chave com shuffle sem reposição.
- Retry com backoff exponencial: 3 tentativas, 500ms → 1s → 2s.
- Logging dual: stderr com cores ANSI + arquivo de estado XDG com rotação por deleção.
- Flag global `--json` para saída legível por máquina.
- `como_usa.md` — guia de uso em português brasileiro (791 linhas).
- Licença: MIT OR Apache-2.0.