@genui-a3/create 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genui-a3/create",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "CLI scaffolding tool for A3 agentic apps",
   "keywords": [
     "genui",

package/template/.cursor/rules/example-app.mdc

@@ -0,0 +1,9 @@
+---
+description: Example app rules (pointer to single source)
+globs: "**"
+alwaysApply: true
+---
+
+# Example App
+
+When working in this directory, follow the rules in **CLAUDE.md** in this directory (same content as `.cursorrules` via symlink). Do not duplicate rule content here; CLAUDE.md is the single source of truth for Claude Code and Cursor.

package/template/.cursorrules

@@ -0,0 +1,112 @@
+# Example App
+
+Next.js example for @genui-a3/core. AI rules for this app (Claude Code and Cursor). Single source of truth; Cursor uses via symlink `.cursorrules` → this file.
+
+## Stack
+
+- Next.js 16.1.6 (App Router), React 19, TypeScript 5.9+
+- Testing infrastructure planned (not yet configured)
+- MUI 7 (@mui/material) + styled-components for styling (`app/theme.ts`, `app/ThemeProvider.tsx`)
+
+## Dependencies
+
+- Pin all npm package versions (no `^` or `~`).
+- Use exact versions in package.json so installs are reproducible.
+
+## React / TypeScript
+
+- Named functions over arrow function assignments
+- Proper types and interfaces; follow React hooks rules and lifecycle
+- Error boundaries and handling where appropriate
+- Path aliases (from `tsconfig.json`):
+  - `@atoms` → `./app/components/atoms`
+  - `@molecules` → `./app/components/molecules`
+  - `@organisms` → `./app/components/organisms`
+  - `@components` → `./app/components`
+  - `@constants` → `./app/constants`
+  - `types` → `./app/types` (bare module, no @ prefix)
+
+## Dev Commands
+
+- `npm run dev` — Start Next.js dev server
+- `npm run build` — Build for production
+- `npm run start` — Start production server
+
+## Next.js
+
+- Use App Router, Server Components, Client Components, Server Actions, middleware as appropriate
+
+## Code Organization
+
+- Single-responsibility components; separation of concerns
+- Constants for config and string literals; clean folder structure; DRY
+- Use Atomic Design for component hierarchy (see below)
+- `app/api/` — API routes (agui, chat, stream endpoints)
+- `app/(pages)/` — Route groups (agui, chat, stream pages)
+- `app/agents/` — Agent implementations (e.g. age.ts, greeting.ts)
+- `app/lib/providers/` — Provider factory functions (Anthropic, Bedrock, OpenAI)
+
+## Component hierarchy (Atomic Design)
+
+- Place UI components under `app/components/` in Atomic Design layers:
+  1. **atoms/** — Single-purpose primitives (e.g. MessageBubble, buttons, inputs).
+  2. **molecules/** — Compositions of atoms (e.g. ChatMessage, ChatInput).
+  3. **organisms/** — Compositions of molecules and layout (e.g. Chat, ChatMessageList).
+- Pages import from organisms (or molecules when no organism exists).
+- Each layer may only use components from the same or lower layers (atoms use MUI/styled only; molecules use atoms; organisms use molecules/atoms).
+- Export public components via `index.ts` per folder.
+
+## State & Data
+
+- Appropriate React hooks; clear data flow
+- Handle loading, error, and success states; predictable updates
+
+## Testing
+
+Testing infrastructure is not yet configured for the example app.
+When added, tests should be comprehensive, runnable in isolation, and cover error cases.
+
+## Naming Conventions
+
+- camelCase for variables, functions, and file names
+- PascalCase for React components, interfaces, and type aliases
+- SCREAMING_SNAKE_CASE for module-level constants
+
+## API & UX
+
+- Proper error handling and loading states; correct response types; separate API logic
+- Loading states, clear error messages, responsive design, accessibility
+
+## Security
+
+- Sensitive data handled appropriately (HIPAA-aware)
+- Auth/authz where needed; no keys or tokens in code
+
+## Docs
+
+- Markdown per markdownlint (new line per sentence, "1." for lists; config inherited from root `.markdownlint.json`)
+
+## Workflow
+
+1. Understand requirements (business, technical, non-functional)
+2. Plan implementation
+3. Write tests, then code that passes them
+4. Document decisions; review for best practices
+
+Use latest React and TypeScript syntax. Code should be clean, readable, maintainable, efficient, and DRY.
+
+## A3 Framework Documentation
+
+The `docs/` directory contains essential A3 framework documentation.
+**You MUST read the relevant files below** before implementing or modifying any feature that touches A3 agents, providers, sessions, resilience, or logging.
+
+| File | Topic |
+|---|---|
+| `docs/QUICK-START-EXAMPLES.md` | Agent definitions, registration, multi-agent flows, ChatSession usage |
+| `docs/PROVIDERS.md` | Provider setup (Bedrock, OpenAI, Anthropic), config options, model fallback, per-agent overrides |
+| `docs/RESILIENCE.md` | Retry, backoff, timeout config, error classification, resilience error handling |
+| `docs/LOGGING.md` | Internal logging architecture, `log` singleton, log levels |
+| `docs/CUSTOM_LOGGING.md` | Supplying a custom logger via `configureLogger()` |
+
+When in doubt about A3 API usage, patterns, or configuration — **read the relevant doc file first**.
+Any new `.md` files added to `docs/` are part of this documentation set and should be consulted as needed.

package/template/CLAUDE.md

@@ -0,0 +1,112 @@
+# Example App
+
+Next.js example for @genui-a3/core. AI rules for this app (Claude Code and Cursor). Single source of truth; Cursor uses via symlink `.cursorrules` → this file.
+
+## Stack
+
+- Next.js 16.1.6 (App Router), React 19, TypeScript 5.9+
+- Testing infrastructure planned (not yet configured)
+- MUI 7 (@mui/material) + styled-components for styling (`app/theme.ts`, `app/ThemeProvider.tsx`)
+
+## Dependencies
+
+- Pin all npm package versions (no `^` or `~`).
+- Use exact versions in package.json so installs are reproducible.
+
+## React / TypeScript
+
+- Named functions over arrow function assignments
+- Proper types and interfaces; follow React hooks rules and lifecycle
+- Error boundaries and handling where appropriate
+- Path aliases (from `tsconfig.json`):
+  - `@atoms` → `./app/components/atoms`
+  - `@molecules` → `./app/components/molecules`
+  - `@organisms` → `./app/components/organisms`
+  - `@components` → `./app/components`
+  - `@constants` → `./app/constants`
+  - `types` → `./app/types` (bare module, no @ prefix)
+
+## Dev Commands
+
+- `npm run dev` — Start Next.js dev server
+- `npm run build` — Build for production
+- `npm run start` — Start production server
+
+## Next.js
+
+- Use App Router, Server Components, Client Components, Server Actions, middleware as appropriate
+
+## Code Organization
+
+- Single-responsibility components; separation of concerns
+- Constants for config and string literals; clean folder structure; DRY
+- Use Atomic Design for component hierarchy (see below)
+- `app/api/` — API routes (agui, chat, stream endpoints)
+- `app/(pages)/` — Route groups (agui, chat, stream pages)
+- `app/agents/` — Agent implementations (e.g. age.ts, greeting.ts)
+- `app/lib/providers/` — Provider factory functions (Anthropic, Bedrock, OpenAI)
+
+## Component hierarchy (Atomic Design)
+
+- Place UI components under `app/components/` in Atomic Design layers:
+  1. **atoms/** — Single-purpose primitives (e.g. MessageBubble, buttons, inputs).
+  2. **molecules/** — Compositions of atoms (e.g. ChatMessage, ChatInput).
+  3. **organisms/** — Compositions of molecules and layout (e.g. Chat, ChatMessageList).
+- Pages import from organisms (or molecules when no organism exists).
+- Each layer may only use components from the same or lower layers (atoms use MUI/styled only; molecules use atoms; organisms use molecules/atoms).
+- Export public components via `index.ts` per folder.
+
+## State & Data
+
+- Appropriate React hooks; clear data flow
+- Handle loading, error, and success states; predictable updates
+
+## Testing
+
+Testing infrastructure is not yet configured for the example app.
+When added, tests should be comprehensive, runnable in isolation, and cover error cases.
+
+## Naming Conventions
+
+- camelCase for variables, functions, and file names
+- PascalCase for React components, interfaces, and type aliases
+- SCREAMING_SNAKE_CASE for module-level constants
+
+## API & UX
+
+- Proper error handling and loading states; correct response types; separate API logic
+- Loading states, clear error messages, responsive design, accessibility
+
+## Security
+
+- Sensitive data handled appropriately (HIPAA-aware)
+- Auth/authz where needed; no keys or tokens in code
+
+## Docs
+
+- Markdown per markdownlint (new line per sentence, "1." for lists; config inherited from root `.markdownlint.json`)
+
+## Workflow
+
+1. Understand requirements (business, technical, non-functional)
+2. Plan implementation
+3. Write tests, then code that passes them
+4. Document decisions; review for best practices
+
+Use latest React and TypeScript syntax. Code should be clean, readable, maintainable, efficient, and DRY.
+
+## A3 Framework Documentation
+
+The `docs/` directory contains essential A3 framework documentation.
+**You MUST read the relevant files below** before implementing or modifying any feature that touches A3 agents, providers, sessions, resilience, or logging.
+
+| File | Topic |
+|---|---|
+| `docs/QUICK-START-EXAMPLES.md` | Agent definitions, registration, multi-agent flows, ChatSession usage |
+| `docs/PROVIDERS.md` | Provider setup (Bedrock, OpenAI, Anthropic), config options, model fallback, per-agent overrides |
+| `docs/RESILIENCE.md` | Retry, backoff, timeout config, error classification, resilience error handling |
+| `docs/LOGGING.md` | Internal logging architecture, `log` singleton, log levels |
+| `docs/CUSTOM_LOGGING.md` | Supplying a custom logger via `configureLogger()` |
+
+When in doubt about A3 API usage, patterns, or configuration — **read the relevant doc file first**.
+Any new `.md` files added to `docs/` are part of this documentation set and should be consulted as needed.

package/template/README.md

@@ -2,6 +2,10 @@
 
 Built with [GenUI A3](https://www.npmjs.com/package/@genui-a3/core).
 
+## Documentation
+
+Local documentation is available in the [`./docs`](./docs) folder. Check there for concepts, recipes, and API reference!
+
 ## Getting Started
 
 ```bash

package/template/app/agents/age.ts

@@ -11,6 +11,7 @@ const agePayload = z.object({
 
 export const ageAgent: Agent<State> = {
   id: 'age',
+  description: "Gets the user's age.",
   prompt: `
     You are a friendly agent. Your goal is to learn the user's age.
     If you don't know their age yet, ask for it politely.

package/template/app/agents/greeting.ts

@@ -19,6 +19,7 @@ const greetingPayload = z.object({
 
 export const greetingAgent: Agent<State> = {
   id: 'greeting',
+  description: 'Greets the user and learns their name.',
   prompt: `
     You are a friendly greeting agent. Your goal is to greet the user and learn their name.
     You also handle name changes — if the user wants to update their name, collect the new one.

package/template/app/lib/providers/anthropic.ts

@@ -5,7 +5,7 @@ let _instance: ReturnType<typeof createAnthropicProvider> | null = null
 export function getAnthropicProvider() {
   if (!_instance) {
     _instance = createAnthropicProvider({
-      models: ['claude-sonnet-4-5-20250929', 'claude-haiku-4-5-20251001'],
+      models: ['claude-sonnet-4-6', 'claude-haiku-4-5-20251001'],
     })
   }
   return _instance

package/template/docs/CUSTOM_LOGGING.md

@@ -0,0 +1,36 @@
+# Custom Logging
+
+By default, A3 logs internally using [tslog](https://tslog.js.org) with no configuration required.
+If you want A3's internal logs to flow through your own logging infrastructure — for example, to include your app's trace IDs, ship logs to a provider like Datadog or OpenTelemetry, or change the output format — you can provide a custom logger.
+
+## How it works
+
+A3 uses [LogLayer](https://loglayer.dev) as its logging interface.
+LogLayer is a transport-agnostic logging layer: you configure it with a _transport_ that wraps your preferred logging library, and LogLayer routes A3's log calls through it.
+
+You do not need to know the LogLayer API to use your own logger — you only need to wrap it in the appropriate LogLayer transport.
+
+## Default behaviour
+
+Out of the box, A3:
+
+- Outputs pretty, human-readable logs in development (`NODE_ENV !== 'production'`)
+- Outputs structured JSON in production
+- Defaults to log level `info`, overridden by the `A3_LOG_LEVEL` environment variable
+
+```bash
+# Supported levels: silly | trace | debug | info | warn | error | fatal
+A3_LOG_LEVEL=debug node your-app.js
+```
+
+## Configuring a custom logger
+
+A3 uses the [LogLayer](https://loglayer.dev) interface.
+Call `configureLogger()` with a `LogLayer` instance configured for your preferred logging library.
+See the [LogLayer documentation](https://loglayer.dev) for setup instructions and the full list of available transports.
+
+## Further reading
+
+- [LogLayer documentation](https://loglayer.dev) — full API, plugins, multi-transport, context, and more
+- [LogLayer transports](https://loglayer.dev/transports) — all available transports with setup instructions
+- [tslog documentation](https://tslog.js.org) — the default A3 logger