Ship a working CLI and real documentation

The README now shows what AirForm does (features list, quick
start with Air, standalone usage) instead of a TODO placeholder.
The `airform` CLI previews rendered HTML for any importable
Pydantic model with syntax highlighting. docs/usage.md covers
validation, rendering, from_request, Depends, custom widgets,
and CLI usage.

Key design decisions:
- CLI uses importlib to load the model, so it works with any
  project without AirForm needing to know the project structure
- rich and typer are runtime dependencies (needed for the CLI
  entry point, not just dev)
- Placeholder utils.py removed

Author: audreyfeldroy

README.md

@@ -2,7 +2,7 @@
 
 ![PyPI version](https://img.shields.io/pypi/v/AirForm.svg)
 
-Pydantic-native form validation and rendering. Define a model, get a validated, rendered HTML form. Works with or without Air web framework.
+Pydantic-native form validation and rendering. Define a model, get a validated, rendered HTML form. Built for [Air](https://github.com/feldroy/air), also works standalone with FastAPI, Starlette, Litestar, or any ASGI framework.
 
 * GitHub: https://github.com/feldroy/AirForm/
 * PyPI package: https://pypi.org/project/AirForm/
@@ -11,7 +11,62 @@ Pydantic-native form validation and rendering. Define a model, get a validated,
 
 ## Features
 
-* TODO
+* Type-safe validated data via `AirForm[MyModel]` generic parameter
+* Reads the full [AirField](https://github.com/feldroy/AirField) metadata vocabulary: Widget, Label, Placeholder, HelpText, Choices, Autofocus, PrimaryKey, Hidden, ReadOnly
+* Auto-skips PrimaryKey and Hidden("form") fields in rendered output
+* HTML5 validation attributes from Pydantic constraints (minlength, maxlength, required)
+* Accessible by default: aria-invalid, aria-describedby, role="alert" on errors
+* Textarea, select, and checkbox rendering from type annotations and metadata
+* Swappable widget for custom renderers
+* `from_request()` for async ASGI request handling (works with FastAPI Depends)
+
+## Quick start
+
+### With Air
+
+```python
+from air import AirForm, AirModel, AirField
+import air
+
+app = air.Air()
+
+class Contact(AirModel):
+    name: str
+    email: str = AirField(type="email", label="Email Address")
+
+class ContactForm(AirForm[Contact]):
+    pass
+
+@app.post("/contact")
+async def submit(request: air.Request):
+    form = await ContactForm.from_request(request)
+    if form.is_valid:
+        return air.Html(air.H1(f"Thanks, {form.data.name}!"))
+    return air.Html(air.Raw(form.render()))
+```
+
+### Standalone (any ASGI framework)
+
+```python
+from pydantic import BaseModel
+from airform import AirForm
+
+class ContactModel(BaseModel):
+    name: str
+    email: str
+
+class ContactForm(AirForm[ContactModel]):
+    pass
+
+# Validate
+form = ContactForm()
+form.validate({"name": "Audrey", "email": "audreyfeldroy@example.com"})
+if form.is_valid:
+    print(form.data.name)  # type-safe: editor knows this is str
+
+# Render
+html = ContactForm().render()
+```
 
 ## Documentation
 
@@ -25,32 +80,23 @@ API documentation is auto-generated from docstrings using [mkdocstrings](https:/
 
 Docs deploy automatically on push to `main` via GitHub Actions. To enable this, go to your repo's Settings > Pages and set the source to **GitHub Actions**.
 
-## Development
-
-To set up for local development:
+## Installation
 
 ```bash
-# Clone your fork
-git clone git@github.com:your_username/AirForm.git
-cd AirForm
-
-# Install in editable mode with live updates
-uv tool install --editable .
+uv add AirForm
 ```
 
-This installs the CLI globally but with live updates - any changes you make to the source code are immediately available when you run `airform`.
+## CLI
 
-Run tests:
+Preview rendered form HTML from any Pydantic model:
 
 ```bash
-uv run pytest
+airform myapp.models:ContactModel
 ```
 
-Run quality checks (format, lint, type check, test):
+## Development
 
-```bash
-just qa
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.
 
 ## Author
 

docs/usage.md

@@ -1,7 +1,81 @@
 # Usage
 
-To use AirForm in a project:
+## Define a model and form
 
 ```python
-import airform
+from pydantic import BaseModel
+from airfield import AirField
+from airform import AirForm
+
+class ContactModel(BaseModel):
+    name: str
+    email: str = AirField(type="email", label="Email Address")
+    message: str = AirField(widget="textarea", placeholder="Your message...")
+
+class ContactForm(AirForm[ContactModel]):
+    pass
+```
+
+## Validate
+
+```python
+form = ContactForm()
+form.validate({"name": "Audrey", "email": "audreyfeldroy@example.com", "message": "Hello!"})
+
+if form.is_valid:
+    print(form.data.name)   # "Audrey" — typed as str
+    print(form.data.email)  # autocomplete works
+```
+
+## Render
+
+```python
+html = ContactForm().render()
+```
+
+Produces structured HTML with labels, inputs, accessibility attributes, and error messages. PrimaryKey and Hidden("form") fields are auto-skipped.
+
+## Validate from a request
+
+Works with any ASGI framework (Starlette, FastAPI, Litestar):
+
+```python
+@app.post("/contact")
+async def submit(request):
+    form = await ContactForm.from_request(request)
+    if form.is_valid:
+        send_email(form.data.name, form.data.email, form.data.message)
+```
+
+With FastAPI dependency injection:
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+@app.post("/contact")
+async def submit(form: Annotated[ContactForm, Depends(ContactForm.from_request)]):
+    if form.is_valid:
+        send_email(form.data.name, form.data.email, form.data.message)
+```
+
+## Custom widget
+
+Swap the renderer by setting `widget` on your form subclass:
+
+```python
+def my_renderer(*, model, data=None, errors=None, includes=None):
+    # Return an HTML string
+    ...
+
+class ContactForm(AirForm[ContactModel]):
+    widget = staticmethod(my_renderer)
+```
+
+## CLI preview
+
+Preview rendered HTML for any importable model:
+
+```bash
+airform myapp.models:ContactModel
 ```

pyproject.toml

@@ -23,7 +23,9 @@ dependencies = [
   "pydantic>=2.0",
   "AirField>=0.4.0",
   "annotated-types",
+  "rich",
   "starlette",
+  "typer",
 ]
 requires-python = ">= 3.12"
 
@@ -54,8 +56,8 @@ changelog = "https://github.com/feldroy/AirForm/releases"
 documentation = "https://feldroy.github.io/AirForm/"
 homepage = "https://github.com/feldroy/AirForm"
 
-# [project.scripts]
-# airform = "airform.cli:app"
+[project.scripts]
+airform = "airform.cli:app"
 
 [tool.ty]
 # All rules are enabled as "error" by default; no need to specify unless overriding.

src/airform/cli.py

@@ -1,20 +1,37 @@
-"""Console script for airform."""
+"""Console script for airform.
+
+Preview rendered form HTML from a Pydantic model:
+
+    airform preview myapp:ContactModel
+"""
+
+import importlib
 
 import typer
 from rich.console import Console
+from rich.syntax import Syntax
 
-from airform import utils
+from airform import default_form_widget
 
 app = typer.Typer()
 console = Console()
 
 
 @app.command()
-def main() -> None:
-    """Console script for airform."""
-    console.print("Replace this message by putting your code into airform.cli.main")
-    console.print("See Typer documentation at https://typer.tiangolo.com/")
-    utils.do_something_useful()
+def preview(model_path: str) -> None:
+    """Render a Pydantic model as form HTML and print it.
+
+    MODEL_PATH is module:ClassName, e.g. myapp.models:ContactModel
+    """
+    module_name, _, class_name = model_path.rpartition(":")
+    if not module_name or not class_name:
+        console.print(f"[red]Expected module:ClassName, got {model_path!r}[/red]")
+        raise typer.Exit(1)
+
+    module = importlib.import_module(module_name)
+    model = getattr(module, class_name)
+    html = default_form_widget(model=model)
+    console.print(Syntax(html, "html", theme="monokai"))
 
 
 if __name__ == "__main__":