Add .claude/, .gitignore, and update README

- .claude/settings.json: project-level Claude Code config
- .gitignore: ignores test binary, build artifacts, shards cache, tags
- README.md: expanded with usage example, dev commands, and AI assistance
  disclosure (Claude used for review/bug-checking, not code generation)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ATnpoEGXj4RyuMoBLGWcjs

.claude/settings.json

@@ -0,0 +1 @@
+{}

.gitignore

@@ -0,0 +1,14 @@
+# Crystal build artifacts
+/.build/
+/bin/
+
+# Compiled test binary (crystal build test.cr)
+test
+
+# Shards cache
+/.shards/
+/lib/
+
+# Editor
+tags
+.DS_Store

README.md

@@ -1,6 +1,10 @@
-# CliGenerator
+# cligen
 
-This is a crystal project to manage setting up OptionParser objects based around "Command" objects and arguments you define inside them.
+A Crystal shard that generates CLI parsers from class definitions using annotations and macros. Define your commands as classes; cligen builds the runtime parse tree.
+
+## How It Works
+
+Subclass `CliGen::Command`, annotate your instance variables with `@[CliGen::Argument]` or `@[CliGen::Selection]`, and register the command with an `CliGen::App`. At compile time, macros inspect the annotations and generate typed `Flag(T)` objects; at runtime, `CliGen::App.process` walks the `CommandNode` tree to route arguments, populate your command instance, and dispatch to the right method.
 
 ## Installation
 
@@ -14,12 +18,47 @@ This is a crystal project to manage setting up OptionParser objects based around
 
 2. Run `shards install`
 
-
 ## Usage
+
 ```crystal
 require "cligen"
+
+@[CliGen::CommandInfo(description: "Greet someone")]
+class Greet < CliGen::Command
+  @[CliGen::Argument(short: "-n", long: "--name VALUE", description: "Name to greet")]
+  @name : String = "world"
+
+  def main
+    puts "Hello, #{@name}!"
+  end
+end
+
+CliGen::App.process
 ```
 
+```
+$ myapp --name Alice
+Hello, Alice!
+```
+
+Full API documentation and design notes are in [`design.adoc`](design.adoc).
+
+## Development
+
+```bash
+# Type-check without running
+crystal build src/cligen.cr --no-codegen
+
+# Run specs
+crystal spec
+```
+
+## AI Assistance Disclosure
+
+This project uses [Claude Code](https://claude.ai/code) as a development aid — specifically for catching bugs, spotting typos, reviewing implementations, and talking through design decisions. All architecture decisions, code, and design are written by the author. Claude is used the way one might use a second pair of eyes on a diff, not as a code generator.
+
+`CLAUDE.md` at the repo root documents the project structure for Claude's context. `.claude/` holds project-level Claude Code settings.
+
 ## Contributors
 
 - [Tristan Ancelet](https://git.arcanium.tech/tristan) - creator and maintainer