From f50280364d413dc6e99a6b4b0cbea9c1ab4067c1 Mon Sep 17 00:00:00 2001
From: mitchell <m@mjfs.us>
Date: Sat, 18 Apr 2026 18:39:47 -0400
Subject: [PATCH] docs: add AGENTS.md with project conventions and architecture

---
 AGENTS.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..42944a0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# aicl
+
+Bun CLI tool for streaming LLM chat with inline markdown rendering.
+
+## Commands
+
+```
+bun run dev                   # dev run
+bun run prod                  # run bundled output
+bun run check                 # biome lint + format + organize imports
+```
+
+## Architecture
+
+- `index.ts` — CLI entry point, orchestration
+- `src/render/index.ts` — `Renderer` class: streams LLM response, buffers markdown, renders to stdout/stderr
+- `src/render/markdown.ts` — `renderMarkdown()`: syntax-highlighted markdown via `@comark/ansi` + Shiki
+
+## Gotchas
+
+- **Bun only** — not Node. Use `Bun.file()`, `Bun.argv`, `Bun.sleep()`.
+- **No tests** — none exist.
+- **Biome config**: double quotes, space indent, auto-import-organize on. Run `bun run check` before committing.
+
+## Style
+
+- Double quotes (enforced by biome).
+- Preserve `verbatimModuleSyntax` — imports must be used or type-imported.
+- `strict: true` in tsconfig.