@genui-a3/create 0.1.7 → 0.1.9

package/dist/index.js

@@ -130,6 +130,135 @@ function extractRegionFromIni(content, sectionName) {
   return void 0;
 }
 
+// src/utils/validation.ts
+function normalizeKey(key) {
+  return key.replace(/\s/g, "");
+}
+function buildAuthErrorMessage(status, detail, context) {
+  let message = `Invalid ${context.name} (${status}). ${detail}`;
+  if (status === 401) {
+    message += "\n\nMake sure:\n  \u2022 Your credentials are active and not revoked\n  \u2022 Your account has appropriate permissions\n  \u2022 The credentials haven't exceeded rate limits";
+    if (context.helpUrl) {
+      message += `
+
+Get help at: ${context.helpUrl}`;
+    }
+  } else if (status === 429) {
+    message = `${context.name} rate limited. Please try again in a moment.`;
+  }
+  return message;
+}
+async function validateOpenAIKey(apiKey) {
+  if (!apiKey.startsWith("sk-proj-")) {
+    return {
+      valid: false,
+      message: "Invalid format: OpenAI API key must start with sk-proj-\n\nGet a new key at: https://platform.openai.com/account/api-keys"
+    };
+  }
+  try {
+    const response = await fetch("https://api.openai.com/v1/models", {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (response.ok) {
+      return { valid: true, message: "OpenAI API key is valid." };
+    }
+    const body = await response.json().catch(() => null);
+    const detail = body?.error?.message ?? `HTTP ${response.status}`;
+    const message = buildAuthErrorMessage(response.status, detail, {
+      name: "OpenAI API key",
+      helpUrl: "https://platform.openai.com/account/api-keys"
+    });
+    return { valid: false, message };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { valid: false, message: `Network error: ${msg}` };
+  }
+}
+async function validateAnthropicKey(apiKey) {
+  if (!apiKey.startsWith("sk-ant-")) {
+    return {
+      valid: false,
+      message: "Invalid format: Anthropic API key must start with sk-ant-\n\nGet a new key at: https://console.anthropic.com/settings/keys"
+    };
+  }
+  try {
+    const response = await fetch("https://api.anthropic.com/v1/models", {
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01"
+      },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (response.ok) {
+      return { valid: true, message: "Anthropic API key is valid." };
+    }
+    const body = await response.json().catch(() => null);
+    const detail = body?.error?.message ?? `HTTP ${response.status}`;
+    const message = buildAuthErrorMessage(response.status, detail, {
+      name: "Anthropic API key",
+      helpUrl: "https://console.anthropic.com/settings/keys"
+    });
+    return { valid: false, message };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { valid: false, message: `Network error: ${msg}` };
+  }
+}
+async function validateAwsCredentials(credentials) {
+  if (credentials.mode === "keys") {
+    if (!credentials.accessKeyId.match(/^AKIA[0-9A-Z]{16}$/)) {
+      return {
+        valid: false,
+        message: "Invalid format: AWS Access Key ID must start with AKIA and be 20 characters total\n\nManage keys at: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html"
+      };
+    }
+    if (credentials.secretAccessKey.length < 40) {
+      return {
+        valid: false,
+        message: "Invalid format: AWS Secret Access Key appears too short (should be ~40 characters)\n\nManage keys at: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html"
+      };
+    }
+  }
+  try {
+    const { BedrockClient, ListFoundationModelsCommand } = await import("@aws-sdk/client-bedrock");
+    let clientConfig;
+    if (credentials.mode === "profile") {
+      const { fromIni } = await import("@aws-sdk/credential-provider-ini");
+      clientConfig = {
+        region: credentials.region,
+        credentials: fromIni({ profile: credentials.profile })
+      };
+    } else {
+      clientConfig = {
+        region: credentials.region,
+        credentials: {
+          accessKeyId: credentials.accessKeyId,
+          secretAccessKey: credentials.secretAccessKey
+        }
+      };
+    }
+    const client = new BedrockClient(clientConfig);
+    await client.send(new ListFoundationModelsCommand({ byOutputModality: "TEXT" }));
+    return { valid: true, message: "AWS credentials verified with Bedrock access." };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    let message = `AWS validation failed: ${msg}`;
+    if (msg.includes("Could not resolve credentials")) {
+      const profile = credentials.mode === "profile" ? credentials.profile : "unknown";
+      message = `Could not find credentials for profile "${profile}" in ~/.aws/credentials
+
+Set up a profile with: aws configure
+  Guide: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html`;
+    } else if (msg.includes("InvalidSignatureException") || msg.includes("InvalidSignature")) {
+      message = "Invalid AWS credentials (signature mismatch)\n\nMake sure:\n  \u2022 Your Access Key ID and Secret Access Key are correct\n  \u2022 They haven't been revoked or rotated\n\nManage credentials at: https://console.aws.amazon.com/iam/home#/security_credentials";
+    } else if (msg.includes("UnauthorizedOperation") || msg.includes("NotAuthorizedForSourceException")) {
+      message = "AWS credentials don't have permission to access Bedrock\n\nMake sure:\n  \u2022 Your IAM user/role has Bedrock access\n  \u2022 Your region has Bedrock enabled\n\nLearn more: https://docs.aws.amazon.com/bedrock/latest/userguide/";
+    }
+    return { valid: false, message };
+  }
+}
+
 // src/utils/prompts.ts
 function handleCancel(value) {
   if (p.isCancel(value)) {
@@ -146,7 +275,7 @@ async function promptProjectName() {
       defaultValue: "my-a3-quickstart"
     });
     handleCancel(value);
-    projectName = value;
+    projectName = value.trim();
   }
   return projectName;
 }
@@ -159,7 +288,7 @@ async function promptAccessKeys(config) {
     }
   });
   handleCancel(awsAccessKeyId);
-  config.awsAccessKeyId = awsAccessKeyId;
+  config.awsAccessKeyId = normalizeKey(awsAccessKeyId);
   const awsSecretAccessKey = await p.password({
     message: "AWS_SECRET_ACCESS_KEY:",
     validate(input) {
@@ -167,31 +296,106 @@ async function promptAccessKeys(config) {
     }
   });
   handleCancel(awsSecretAccessKey);
-  config.awsSecretAccessKey = awsSecretAccessKey;
+  config.awsSecretAccessKey = normalizeKey(awsSecretAccessKey);
 }
 async function promptOpenAIConfig(config) {
   p.log.step(PROVIDER_META.openai.label);
-  const openaiApiKey = await p.text({
-    message: "OpenAI API key:",
-    placeholder: "sk-...",
-    validate(input) {
-      if (!input) return "API key is required. Get one at https://platform.openai.com/api-keys";
+  let validated = false;
+  while (!validated) {
+    const openaiApiKey = await p.password({
+      message: "OpenAI API key:",
+      validate(input) {
+        if (!input) return "API key is required (starts with sk-...). Get one at https://platform.openai.com/api-keys";
+      }
+    });
+    handleCancel(openaiApiKey);
+    config.openaiApiKey = normalizeKey(openaiApiKey);
+    const spin = p.spinner();
+    spin.start("Validating OpenAI credentials...");
+    const result = await validateOpenAIKey(config.openaiApiKey);
+    spin.stop(result.valid ? "OpenAI credentials verified" : "OpenAI validation failed");
+    if (result.valid) {
+      validated = true;
+    } else {
+      p.log.warn(result.message);
+      p.log.info("Please try again.");
     }
-  });
-  handleCancel(openaiApiKey);
-  config.openaiApiKey = openaiApiKey;
+  }
 }
 async function promptAnthropicConfig(config) {
   p.log.step(PROVIDER_META.anthropic.label);
-  const anthropicApiKey = await p.text({
-    message: "Anthropic API key:",
-    placeholder: "sk-ant-...",
-    validate(input) {
-      if (!input) return "API key is required. Get one at https://console.anthropic.com/settings/keys";
+  let validated = false;
+  while (!validated) {
+    const anthropicApiKey = await p.password({
+      message: "Anthropic API key:",
+      validate(input) {
+        if (!input) return "API key is required (starts with sk-ant-...). Get one at https://console.anthropic.com/settings/keys";
+      }
+    });
+    handleCancel(anthropicApiKey);
+    config.anthropicApiKey = normalizeKey(anthropicApiKey);
+    const spin = p.spinner();
+    spin.start("Validating Anthropic credentials...");
+    const result = await validateAnthropicKey(config.anthropicApiKey);
+    spin.stop(result.valid ? "Anthropic credentials verified" : "Anthropic validation failed");
+    if (result.valid) {
+      validated = true;
+    } else {
+      p.log.warn(result.message);
+      p.log.info("Please try again.");
     }
+  }
+}
+async function promptProfileSelection(profiles) {
+  const MANUAL_ENTRY = "__manual__";
+  const awsProfile = await p.select({
+    message: "AWS profile",
+    options: [
+      ...profiles.map((prof) => ({ label: prof, value: prof })),
+      { label: "Enter manually", value: MANUAL_ENTRY }
+    ]
   });
-  handleCancel(anthropicApiKey);
-  config.anthropicApiKey = anthropicApiKey;
+  handleCancel(awsProfile);
+  if (awsProfile === MANUAL_ENTRY) {
+    const manualProfile = await p.text({
+      message: "AWS profile name:",
+      placeholder: "default",
+      defaultValue: "default",
+      validate(input) {
+        if (!input) return "Profile name is required.";
+      }
+    });
+    handleCancel(manualProfile);
+    return manualProfile.trim();
+  }
+  return awsProfile;
+}
+async function promptDetectProfile(config) {
+  const profiles = detectAwsProfiles();
+  if (profiles.length > 0) {
+    return promptProfileSelection(profiles);
+  }
+  while (true) {
+    p.log.warn("No AWS profiles found in ~/.aws/credentials");
+    p.log.info("Set up a profile with: aws configure\n  Guide: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html");
+    const action = await p.select({
+      message: "How would you like to proceed?",
+      options: [
+        { label: "Try again", value: "retry", hint: "Re-check ~/.aws/credentials" },
+        { label: "Use access keys instead", value: "keys", hint: "Provide key ID + secret directly" }
+      ]
+    });
+    handleCancel(action);
+    if (action === "keys") {
+      config.bedrockAuthMode = "keys";
+      await promptAccessKeys(config);
+      return null;
+    }
+    const retryProfiles = detectAwsProfiles();
+    if (retryProfiles.length > 0) {
+      return promptProfileSelection(retryProfiles);
+    }
+  }
 }
 async function promptBedrockConfig(config) {
   p.log.step(PROVIDER_META.bedrock.label);
@@ -205,74 +409,58 @@ async function promptBedrockConfig(config) {
   handleCancel(authMode);
   config.bedrockAuthMode = authMode;
   if (authMode === "profile") {
-    const detectedProfiles = detectAwsProfiles();
-    let selectedProfile = "";
-    if (detectedProfiles.length > 0) {
-      const MANUAL_ENTRY = "__manual__";
-      const awsProfile = await p.select({
-        message: "AWS profile",
-        options: [
-          ...detectedProfiles.map((prof) => ({ label: prof, value: prof })),
-          { label: "Enter manually", value: MANUAL_ENTRY }
-        ]
-      });
-      handleCancel(awsProfile);
-      if (awsProfile === MANUAL_ENTRY) {
-        const manualProfile = await p.text({
-          message: "AWS profile name:",
-          placeholder: "default",
-          defaultValue: "default",
-          validate(input) {
-            if (!input) return "Profile name is required.";
-          }
-        });
-        handleCancel(manualProfile);
-        selectedProfile = manualProfile;
+    const profile = await promptDetectProfile(config);
+    if (profile) config.awsProfile = profile;
+  } else {
+    await promptAccessKeys(config);
+  }
+  let validated = false;
+  let firstAttempt = true;
+  while (!validated) {
+    if (!firstAttempt) {
+      if (config.bedrockAuthMode === "keys") {
+        await promptAccessKeys(config);
       } else {
-        selectedProfile = awsProfile;
-      }
-    } else {
-      p.log.warn("No AWS profiles found in ~/.aws/credentials");
-      const noProfileAction = await p.select({
-        message: "How would you like to proceed?",
-        options: [
-          { label: "Enter a profile name", value: "manual", hint: "Configure the profile later with: aws configure --profile <name>" },
-          { label: "Use access keys instead", value: "keys", hint: "Provide key ID + secret directly" }
-        ]
-      });
-      handleCancel(noProfileAction);
-      if (noProfileAction === "manual") {
-        const awsProfile = await p.text({
-          message: "AWS profile name:",
-          placeholder: "default",
-          defaultValue: "default",
-          validate(input) {
-            if (!input) return "Profile name is required.";
-          }
+        const retryAction = await p.select({
+          message: "How would you like to retry?",
+          options: [
+            { label: "Try a different profile", value: "profile" },
+            { label: "Switch to access keys", value: "keys" }
+          ]
         });
-        handleCancel(awsProfile);
-        selectedProfile = awsProfile;
-      } else {
-        config.bedrockAuthMode = "keys";
-        await promptAccessKeys(config);
+        handleCancel(retryAction);
+        if (retryAction === "keys") {
+          config.bedrockAuthMode = "keys";
+          await promptAccessKeys(config);
+        } else {
+          const profile = await promptDetectProfile(config);
+          if (profile) config.awsProfile = profile;
+        }
       }
     }
-    if (config.bedrockAuthMode === "profile") {
-      config.awsProfile = selectedProfile;
+    firstAttempt = false;
+    const currentDetectedRegion = config.bedrockAuthMode === "profile" ? detectAwsProfileRegion(config.awsProfile) : void 0;
+    const awsRegion = await p.text({
+      message: "AWS region:",
+      ...currentDetectedRegion ? { initialValue: currentDetectedRegion } : { placeholder: "us-east-1" },
+      validate(input) {
+        if (!input) return "AWS region is required.";
+      }
+    });
+    handleCancel(awsRegion);
+    config.awsRegion = awsRegion.trim();
+    const spin = p.spinner();
+    spin.start("Validating AWS Bedrock credentials...");
+    const credentialInput = config.bedrockAuthMode === "profile" ? { mode: "profile", profile: config.awsProfile, region: config.awsRegion } : { mode: "keys", accessKeyId: config.awsAccessKeyId, secretAccessKey: config.awsSecretAccessKey, region: config.awsRegion };
+    const result = await validateAwsCredentials(credentialInput);
+    spin.stop(result.valid ? "AWS Bedrock credentials verified" : "AWS Bedrock validation failed");
+    if (result.valid) {
+      validated = true;
+    } else {
+      p.log.warn(result.message);
+      p.log.info("Re-entering credentials...");
     }
-  } else {
-    await promptAccessKeys(config);
   }
-  const detectedRegion = config.bedrockAuthMode === "profile" ? detectAwsProfileRegion(config.awsProfile) : void 0;
-  const awsRegion = await p.text({
-    message: "AWS region:",
-    ...detectedRegion ? { initialValue: detectedRegion } : { placeholder: "us-east-1" },
-    validate(input) {
-      if (!input) return "AWS region is required.";
-    }
-  });
-  handleCancel(awsRegion);
-  config.awsRegion = awsRegion;
 }
 async function promptPrimaryProvider(providers, config) {
   const primaryProvider = await p.select({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genui-a3/create",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CLI scaffolding tool for A3 agentic apps",
   "keywords": [
     "genui",
@@ -33,6 +33,8 @@
     "access": "public"
   },
   "dependencies": {
+    "@aws-sdk/client-bedrock": "^3.750.0",
+    "@aws-sdk/credential-provider-ini": "^3.750.0",
     "@clack/prompts": "1.1.0",
     "chalk": "5.4.1",
     "fs-extra": "11.3.0"

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.