docs: overhaul documentation and introduce .serverless-full-stack-webapp-starter-kit/ directory

.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md

@@ -0,0 +1,53 @@
+# Design Principles
+
+This document is for kit maintainers. If you copied this kit to build your own app, you can safely delete the `.serverless-full-stack-webapp-starter-kit/` directory.
+
+## What this kit is
+
+A template you **copy** (not fork) and grow into your own app. It is not a framework — users are expected to read, understand, and modify every file.
+
+## Quality standards
+
+As an aws-samples project:
+
+- Correctness is the top priority — users learn patterns from this code.
+- Reproducibility — following the README must produce a working deployment.
+- Readability — code should be understandable by developers new to serverless.
+- One-command deploy — `npx cdk deploy --all` must be the only deployment step.
+
+The litmus test for any PR: "After this merges, will a developer who copies the kit build their app on a correct understanding?"
+
+## Design decisions
+
+### Template, not framework
+
+- Breaking changes have low impact — users copy and diverge. Major versions can be bumped without a lengthy deprecation cycle.
+- The sample app exists solely to prove all kit components work together. Users will delete it. Do not expand sample app features beyond what is needed for this proof.
+- Avoid over-abstraction. Readability and modifiability matter more than DRY.
+
+### What to include
+
+- Patterns that every serverless full-stack webapp needs (auth, DB, async jobs, real-time).
+- Operational essentials (migration, logging, cost-optimized defaults).
+- Only what cannot be trivially added later.
+
+### What to exclude
+
+- App-specific business logic.
+- Dependencies on specific AI models or services.
+- Patterns needed by fewer than half of expected users.
+
+### Technology choices
+
+| Choice | Rationale |
+|--------|-----------|
+| `prisma db push` over `prisma migrate` | Simpler default for starter-kit scope. Users can switch to `prisma migrate` when they need migration history. |
+| NAT Instance over NAT Gateway | ~$30/month savings. Acceptable trade-off for a starter kit. |
+| Single Lambda for all async jobs | Reduces cold starts and simplifies deployment. `cmd` parameter selects the entry point. |
+| `proxy.ts` over Next.js middleware | Runs inside Lambda handler, avoiding cold-start CPU starvation from JWKS fetch in middleware. |
+| `output: 'standalone'` | Required for Lambda deployment via Docker image. |
+| Lambda Web Adapter | Enables response streaming with CloudFront + Lambda Function URL. |
+
+### Architecture Decision Records (ADR)
+
+ADRs are not used yet. Introduce `design/adr/` when a major technology decision is made (e.g., ORM migration, database engine change) that requires recording the context, alternatives considered, and rationale.

AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md
+
+## Commands
+
+```bash
+# webapp
+cd webapp && npm ci
+cd webapp && npm run dev          # starts on port 3010
+cd webapp && npm run build
+cd webapp && npm run lint
+cd webapp && npm run format
+
+# cdk
+cd cdk && npm ci
+cd cdk && npm run build
+cd cdk && npm test
+cd cdk && npm run format
+cd cdk && npx cdk deploy --all
+cd cdk && npx cdk diff
+
+# local development (requires Docker)
+docker compose up -d              # PostgreSQL on port 5432
+cd webapp && npx prisma db push   # sync schema to local DB
+cd webapp && npm run dev
+```
+
+## Development guide
+
+### Authentication
+
+All server-side mutations must go through `authActionClient` (defined in `lib/safe-action.ts`). It validates the Cognito session via Amplify server-side auth and injects `ctx.userId`. Never call Prisma directly from a Server Action without this middleware.
+
+`proxy.ts` handles route protection (redirect to `/sign-in` for unauthenticated users). It is NOT a Next.js middleware file — it runs inside the Lambda handler. There is no `middleware.ts` in this project.
+
+### Async jobs
+
+The dispatch flow is: Server Action → `runJob()` (Lambda async invoke) → `async-job-runner.ts` (discriminated union dispatch) → job handler → `sendEvent()` (AppSync Events) → client `useEventBus` hook.
+
+To add a new job:
+1. Add a Zod schema with a `type` literal to the discriminated union in `async-job-runner.ts`
+2. Implement the handler in `src/jobs/async-job/`
+3. Add the case to the switch statement
+
+All job types share a single Lambda function via `job.Dockerfile`. The CDK `cmd` parameter selects the entry point.
+
+### Database migration
+
+`prisma db push` is used for schema sync by default. The migration runner Lambda is invoked automatically during `cdk deploy` via CDK Trigger. For manual invocation, use the `MigrationCommand` from CDK outputs.
+
+Schema changes: edit `prisma/schema.prisma` → run `npx prisma db push` locally → commit. The `zod-prisma-types` generator auto-generates Zod schemas from the Prisma schema. If you switch to `prisma migrate`, update the migration runner accordingly.
+
+### Lambda environment
+
+The webapp runs on Lambda behind CloudFront via Lambda Web Adapter (response streaming). `next.config.ts` uses `output: 'standalone'`. Build-time env vars (prefixed `NEXT_PUBLIC_`) are injected via CDK `ContainerImageBuild` build args — they cannot be changed at runtime.
+
+### Real-time notifications
+
+Server → client push uses AppSync Events. Server-side: `sendEvent(channelName, payload)` with IAM SigV4 signing. Client-side: `useEventBus` hook with Cognito user pool auth. The channel namespace is `event-bus/`.
+
+## Documentation policy
+
+- Do not document what can be derived from code. An agent can read the codebase.
+- Enforce verifiable constraints with tests and linters, not prose.
+- Code comments explain "why not" only — the non-obvious reason something was done a certain way.
+- Before adding a line to this file, ask: "If I remove this line, will an agent make a mistake?" If no, don't add it. If a root cause is fixed, remove the corresponding line.
+
+## Conventions
+
+- PR titles and code comments in English.
+- Issues and discussions in English or Japanese.
+- PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, etc.).
+- UI components: use [shadcn/ui](https://ui.shadcn.com/). Do not introduce alternative component libraries.
+- Logs: use JSON structured output.
+- Dependencies: esbuild and Next.js bundle everything, so only packages with native binaries needed at Lambda runtime belong in `dependencies`. Everything else goes in `devDependencies`.
+
+## Do not
+
+- Do not bypass `authActionClient` for any mutation. No raw Prisma calls from Server Actions.
+- Do not add `middleware.ts`. Route protection is handled by `proxy.ts` inside the Lambda runtime.
+- Do not use `prisma migrate` commands unless you have explicitly switched from `prisma db push`. The default setup uses `prisma db push`.
+- Do not hardcode AWS region or account IDs. Use CDK context or environment variables.
+- Do not add `NEXT_PUBLIC_` env vars to `.env.local` for deployed builds — they must be set as CDK build args in `webapp.ts`.

CONTRIBUTING.md

@@ -6,6 +6,14 @@ documentation, we greatly value feedback and contributions from our community.
 Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
 information to effectively respond to your bug report or contribution.
 
+## Language policy
+
+- PR titles and code comments: English
+- Issues and discussions: English or Japanese
+
+## Commit and PR conventions
+
+PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (Angular style). Enforced by CI. Releases are automated via [Release Please](https://github.com/googleapis/release-please).
 
 ## Reporting Bugs/Feature Requests
 
@@ -19,7 +27,6 @@ reported the issue. Please try to include as much information as you can. Detail
 * Any modifications you've made relevant to the bug
 * Anything unusual about your environment or deployment
 
-
 ## Contributing via Pull Requests
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: