# kamishibai

> You choose words and meanings; AI prepares flashcards with phrases and audio. Reviewing them in the Anki app helps you remember the phrases and use them in conversation.

kamishibai is free, open-source software for macOS, Linux and Windows. Card generation uses the Google Gemini API with your own key and may incur API charges. AI generates the phrases, explanations, audio and illustrations; Anki schedules reviews.

kamishibai works three ways: an interactive terminal UI, a headless JSON CLI for software agents, and a bring-your-own-cards JSON mode. Learning pairs cover EN, ZH, ES, JA, FR, DE, KO, RU, IT, PT, HI, AR, TR, PL, UK, ID, VI, TH, EL, HE, NL, CS, in any combination.

This file is the installation bootstrap for software agents. After installation, the output of `kamishibai agent-contract` is the sole authority for setup, commands, JSON documents, errors and exit codes. It is embedded in the binary and version-matched; this website does not duplicate the runtime contract.

## Agent bootstrap

### macOS or Linux

If `brew` is available, prefer Homebrew. For a fresh installation:

    brew install anatoly-chichikov/tap/kamishibai

For an existing Homebrew installation:

    brew update
    brew upgrade anatoly-chichikov/tap/kamishibai

If Homebrew is unavailable, use the shell installer:

    curl -fsSL https://raw.githubusercontent.com/anatoly-chichikov/kamishibai/main/install.sh | sh

The shell installer resolves the latest stable release for the current platform, downloads both its archive and `SHA256SUMS.txt`, and refuses to install on a missing checksum or checksum mismatch. It installs to `~/.local/bin` by default. Prebuilt Linux releases require glibc on x86_64 or ARM64; the installer does not support musl or Alpine.

The Homebrew formula lives in the author's personal tap (`anatoly-chichikov/tap`), not in homebrew-core. A bare `brew install kamishibai` fails with "No available formula"; always use the fully qualified name — `brew` adds the tap automatically on first install. The tap is updated manually after each release and can briefly lag behind the latest GitHub release; the shell installer always serves the latest release, and the embedded contract stays version-matched either way. If no prebuilt bottle matches the host, Homebrew builds from source, which needs a Rust toolchain — prefer the shell installer in that case.

### Windows

Every release ships a Windows x86_64 archive (`kamishibai-v<version>-x86_64-pc-windows-msvc.zip`) next to `SHA256SUMS.txt` on the GitHub releases page. Download the archive, verify its checksum against that manifest, extract `kamishibai.exe`, and use the executable's full path in every command below. In a POSIX shell such as Git Bash, the macOS/Linux shell installer works as well. There is no Windows ARM64 release.

### Verify and load the contract

    kamishibai --version
    kamishibai agent-contract
    kamishibai config --json

If `kamishibai` is not found, the install directory is missing from the current shell's PATH: Homebrew is on PATH in any normal setup, and the shell installer copies to `~/.local/bin` and prints a PATH reminder when that directory is not on PATH. Start a new shell, or call the binary by its full path. On Windows, use the full path of the extracted `kamishibai.exe`.

`agent-contract` is text-only; do not add `--json`. Its `Release:` line must match `--version`; if `agent-contract` is missing, upgrade the installed binary and retry. Never substitute a mutable `main/llms.txt` or a separate cards-schema document for this embedded output: it already contains the complete session and `new --build` contracts.

### After the contract is loaded

Follow the contract's first-time setup section to read local state (`config --json`), save the language the user already knows, and provide the Gemini key. Two rules bind chat-driven agents beyond the contract. Ask the user before saving any preference. Never ask for the credential in chat — the key reaches kamishibai only through `GEMINI_API_KEY` or the contract's standard-input flow.

## Site pages

The website is published in 22 languages. English is canonical at /, /idea/ and /faq/; translations use the same paths under /zh/, /es/, /ja/, /fr/, /de/, /ko/, /ru/, /it/, /pt/, /hi/, /ar/, /tr/, /pl/, /uk/, /id/, /vi/, /th/, /el/, /he/, /nl/, /cs/. Every page carries its complete localized copy in the first HTML response, and appending index.html.md to any page URL returns a clean Markdown mirror. Legacy .html URLs redirect permanently; never treat them as canonical.

- [Product](https://kamishibai.io/index.html.md): You choose words and meanings; AI prepares flashcards with phrases and audio. Reviewing them in the Anki app helps you remember the phrases and use them in conversation.
- [Learning idea](https://kamishibai.io/idea/index.html.md): Familiar words and patterns link new phrases to ones you know. AI prepares flashcards for regular practice as you build your command of the language.
- [FAQ](https://kamishibai.io/faq/index.html.md): Answers to questions about using kamishibai to learn a language independently with AI.
- [Full content](https://kamishibai.io/llms-full.txt): the three English pages in one Markdown file

## Optional

- [Source repository](https://github.com/anatoly-chichikov/kamishibai): code, issues and license on GitHub
- [English product page](https://kamishibai.io/): canonical HTML entry point for the whole site