vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/add-images/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: add-images
+description: add logos, hero images, icons, and other pictures that ship with the app (not user uploads). Use when the builder says something like: add my logo; hero image; app icon; add images.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-images
+
+**Goal:** add logos, hero images, icons, and other pictures that ship with the app (not user uploads).
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You place and wire images; the kit compresses them automatically.
+
+> (Under the hood — agent-only) Project assets live in `public/` (web), `assets/` (mobile), or
+> `public/icon/` (extension). Run `node scripts/optimizeAssets.mjs` (or `pnpm build` / `pnpm start`
+> which run it automatically). Display with `VybeImage` from `@vybekiit/assets` — it picks optimized
+> formats and CDN URLs for remote images via `resolveAssetDelivery()`.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/BrandAssetsPage.tsx` export `BrandAssetsPage` into the buyer app at route `/dashboard/brand`.
+   Recipe id: `brand-assets`. Presets: none.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-images')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Pick the folder.** Web → `public/`. Mobile → `assets/`. Extension → `public/icon/` (icons) or
+   `public/` for other static files.
+   **Verify:** the folder exists (scaffold ships placeholders).
+
+2. **Add the image files.** Copy or generate the builder's logo/hero/icons into that folder.
+   **Verify:** files are on disk with sensible names (`logo.svg`, `hero.jpg`, etc.).
+
+3. **Optimize.** Run `node scripts/optimizeAssets.mjs` (or the project's build/start script).
+   **Verify:** optimized variants exist (WebP/AVIF for photos, compressed SVG) and
+   `asset-manifest.json` is updated when applicable.
+
+4. **Show them in the UI.** Use `VybeImage` (`src/components/vybe-image.tsx`) instead of raw `<img>`
+   or bare `next/image` / `Image` — pass `/logo.svg` or a remote upload URL.
+   **Verify:** the screen builds and images render.
+
+5. **Try it for real.** Open the page (or extension popup / mobile screen) and confirm images load fast.
+   **Verify:** images look sharp and load quickly.
+   🎉 *Celebrate* — their brand is on the app.
+
+## If anything breaks
+
+Run `doctor` and re-run optimize. Most issues are a missing file path or skipping the optimize step.
+
+## Definition of done
+
+Project images appear in the app, optimized assets were generated, and `VybeImage` is used.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-language/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: add-language
+description: make the app speak another language — the builder asks in plain words ("make it Hebrew",. Use when the builder says something like: translate my app; add spanish; make it hebrew.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-language
+
+**Goal:** make the app speak another language — the builder asks in plain words ("make it Hebrew",
+"add Spanish"), you wire a full locale in one session.
+
+**Contract:** one action at a time · verify-before-advance · plain language · translate errors ·
+celebrate. Follow `i18n-vybekiit.md` for all technical steps.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/LanguagePage.tsx` export `LanguagePage` into the buyer app at route `/dashboard/language`.
+   Recipe id: `language`. Presets: none.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-language')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Ask which language** — plain words only. You pick the ISO code (e.g. Hebrew → `he`, Spanish → `es`).
+2. **Duplicate the catalog** — copy `messages/en.json` → `messages/{locale}.json`; translate every value.
+3. **Register the locale** — update `src/i18n/routing.ts` and `middleware.ts` (keep both in sync).
+4. **Wire RTL if needed** — for `ar`, `he`, `fa`, `ur`: confirm `<html dir="rtl">` on a page in the new locale.
+5. **Verify** — run `pnpm verify`. Open `/{locale}` in dev (e.g. `/he`) and confirm copy + layout.
+6. **Celebrate** — show the builder one screen in their language; offer the next goal from `goal-index.md`.
+
+## Definition of done
+
+The new locale loads at `/{locale}/…`, all keys resolve, tests green, builder confirmed they see their language.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-notifications/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: add-notifications
+description: the builder's users get notified — by email first; push can come later. Use when the builder says something like: notify users; send alerts.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-notifications
+
+**Goal:** the builder's users get notified — by email first; push can come later.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You wire sending; the builder describes when people should hear
+from the app.
+
+> (Under the hood — agent-only) Notifications via `@vybekiit/notifications` → `resolveNotificationsProvider()`
+> (`src/lib/notifications-client.ts`). Email channel still needs `setup-email` first.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/NotificationsCenterPage.tsx` export `NotificationsCenterPage` into the buyer app at route `/dashboard/notifications`.
+   Recipe id: `notifications-center`. Presets: notifications_log.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-notifications')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Confirm email works first.** If `setup-email` is not done, run that skill first.
+   **Verify:** a test email arrives.
+
+2. **Agree on what triggers a notification, in plain words.** Ask when users should get an email
+   (e.g. "when someone joins their team", "when a payment succeeds"). You map triggers to code.
+   **Verify:** read the list back and get a yes.
+
+3. **Wire notification sending.** Hook `@vybekiit/email` into each agreed moment. Replace dashboard
+   notification placeholder (`TODO(vybekiit): … — skill: add-notifications`).
+   **Verify:** code builds.
+
+4. **Send a real test notification.** Trigger one notification to the builder's own address in the
+   flow they care about most.
+   **Verify:** they confirm it arrived. 🎉 *Celebrate* — users get notified.
+
+5. **Write a test** for at least one notification path and keep it green.
+
+## If anything breaks
+
+Run `doctor`. Most issues are email not set up or an unverified sender.
+
+## Definition of done
+
+At least one real notification sends in a user flow, and a passing test covers that path.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-realtime/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: add-realtime
+description: the builder's app can push live updates to signed-in users. Use when the builder says something like: live updates; real-time; push changes instantly; refresh without reload.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-realtime
+
+**Goal:** the builder's app can push live updates to signed-in users.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate.
+
+> (Agent-only) Read `REALTIME_PROVIDER` and follow `platform-skills/db-presets-vybekiit.md` +
+> `platform-skills/supabase-vybekiit.md` when on the default stack.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/RealtimePage.tsx` export `RealtimePage` into the buyer app at route `/dashboard/realtime`.
+   Recipe id: `realtime`. Presets: realtime_publications.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-realtime')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. **Explain in one line.** *"I'll turn on live updates so your app refreshes when data changes."*
+
+2. **Apply the realtime preset.**
+   - Run `vybekiit apply-preset realtime_publications` (dry-run first if DATABASE_URL is new).
+   - **Verify:** `vybekiit verify-presets realtime_publications` passes.
+
+3. **Wire `@vybekiit/realtime`.** Use `resolveRealtimeProvider()` in server routes or client hooks
+   as your template README describes.
+
+4. **Smoke test.** Open two browser tabs on a signed-in page; change data in one tab.
+   **Verify:** the other tab updates without a full refresh.
+
+## Definition of done
+
+Live channel works for at least one table the builder cares about, with preset verified.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.

package/dist/global-skills/add-route/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: add-route
+description: add a new API endpoint without hand-writing boilerplate. Use when the builder says something like: add an endpoint; add api; new route.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-route
+
+**Goal:** add a new API endpoint without hand-writing boilerplate.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Ask the builder what the endpoint should do (plain words).
+2. Run `vybekiit backend add-route <name>`.
+3. Edit the generated controller logic for their use case.
+4. **Verify:** the new route responds on `/api/<name>`.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-search/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: add-search
+description: users can search the builder's data in plain language. Use when the builder says something like: let users search; find things; search my data.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-search
+
+**Goal:** users can search the builder's data in plain language.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+> (Under the hood — agent-only) `@vybekiit/search` → `resolveSearchProvider()` via `src/lib/search-client.ts`.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/SearchPage.tsx` export `SearchPage` into the buyer app at route `/dashboard/search`.
+   Recipe id: `search`. Presets: search_documents + embeddings.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-search')` / page-recipe-manifest.json.
+   **Verify:** route builds and shows practice UI before provider wiring.
+
+
+1. Explain: *"I'll add search so people can find things quickly."*
+2. Run `vybekiit apply-preset search_documents` then wire index on create/update and a search UI calling
+   `getSearch().search(query)` (see `platform-skills/db-presets-vybekiit.md`).
+3. **Verify:** `vybekiit verify-presets search_documents` + search test green.
+
+## Definition of done
+
+User can search and see matching results.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-signin/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: add-signin
+description: people can create accounts and log in to the builder's app. Use when the builder says something like: sign in; log in; create accounts; add users.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-signin
+
+**Goal:** people can create accounts and log in to the builder's app.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You wire all the code; the builder only pastes a value or clicks
+"approve" when a step truly needs it.
+
+> (Under the hood — agent-only) Sign-in routes through `@vybekiit/auth`'s `resolveAuthProvider()`.
+> Follow `platform-skills/better-auth-vybekiit.md` and `supabase-vybekiit.md` when wiring.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Install the page recipe first (catalog SSOT — Option C).**
+   Copy `apps/componentLibrary/src/pageRecipes/AuthPage.tsx` export `AuthPage` into the buyer app at route `/login`
+   (merge with existing login/sign-up screens if present — do not duplicate routes).
+   Recipe id: `auth`. Preset: auth-bridge.
+   Keep every `TODO:` in the recipe and wire each one after the route renders.
+   Goal id for lookup is `sign-in` (this skill folder is `add-signin`).
+   Also reference `packages/agentKit` `getPageRecipeInstall('sign-in')` / page-recipe-manifest.json.
+   **Verify:** `/login` builds and shows practice sign-in UI before provider wiring.
+
+1. **Make sure their app can remember things first.** Sign-in needs a database. If one isn't set
+   up yet, run `save-data` first, then come back.
+   **Verify:** the database is reachable (`@vybekiit/db`'s `pingDatabase`).
+
+2. **Set the sign-in secret settings.** Generate `BETTER_AUTH_SECRET` and collect `DATABASE_URL`
+   through the `doctor` flow — never ask the builder to type these by hand. Save them to the secret
+   settings file.
+   **Apply DB preset:** run `vybekiit apply-preset auth-bridge` (see `platform-skills/db-presets-vybekiit.md`).
+   **Verify:** `vybekiit verify-presets auth-bridge` passes.
+   **Verify:** both values are present and non-empty.
+
+3. **Add the sign-in handler.** Create the auth server route at `app/api/auth/[...all]/route.ts`
+   that mounts `resolveAuthProvider()`.
+   **Verify:** the route builds and responds.
+
+4. **Connect the sign-in screens.** In `src/lib/auth-client.ts`, replace the stubbed
+   `signInWithPassword` / `signUpWithPassword` / `sendEmailCode` / `verifyEmailCode` with real
+   `resolveAuthProvider()` calls (these resolve the `TODO(vybekiit): … — skill: add-signin` markers;
+   grep them).
+   **Verify:** the sign-up and login screens accept a real account.
+
+5. **Protect the dashboard.** Redirect to `/login` when no one is signed in (use the provider's
+   `getUser`). This resolves the dashboard's add-signin marker.
+   **Verify:** signed out → sent to login; signed in → see the dashboard.
+
+6. **Write a passing test** covering sign-up → login, and keep it green.
+
+7. **Try it for real.** Create an account, log in, and land on the dashboard.
+   **Verify:** the full sign-up → login → dashboard flow works.
+   🎉 *Celebrate* — people can now have their own accounts.
+
+## If anything breaks
+
+Run `doctor`. Most issues are a missing secret setting or the database not reachable yet — fix it
+for them, don't explain the internals.
+
+## Definition of done
+
+A real account can sign up, log in, and reach the protected dashboard; a passing test covers it; no
+add-signin markers remain (re-grep `TODO(vybekiit)`).
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-teams/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: add-teams
+description: the builder can invite teammates and work in shared organizations. Use when the builder says something like: invite teammates; add my team; organizations.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-teams
+
+**Goal:** the builder can invite teammates and work in shared organizations.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You design and wire the org model; the builder describes who should
+have access.
+
+> (Under the hood — agent-only) Orgs via `@vybekiit/tenancy` → `resolveTenancyProvider()` first;
+> then extend UI. Follow `platform-skills/better-auth-vybekiit.md` when auth wiring is needed.
+
+## Steps
+
+<!-- vybekiit:page-recipe-install -->
+0. **Page recipe (catalog SSOT — Option C; Tier-1 already shipped).**
+   Web ships interactive teams at `src/components/saas/teams.tsx` → `/dashboard/teams`.
+   Prefer that surface. Richer catalog reference: `apps/componentLibrary/src/pageRecipes/TeamsPage.tsx`
+   export `TeamsPage` (recipe id `teams`). Need admin user/role screens? Install catalog ids
+   `admin-panel` via `getPageRecipeInstall('admin-panel')`.
+   Also reference `packages/agentKit` `getPageRecipeInstall('add-teams')` / page-recipe-manifest.json.
+   **Verify:** `/dashboard/teams` renders with practice invite UI before provider wiring.
+
+1. **Confirm sign-in works first.** If `add-signin` is not done, run that skill first — teams need
+   accounts.
+   **Verify:** a user can sign in.
+
+2. **Agree on the team shape, in plain words.** Ask who can invite whom (e.g. "the owner invites
+   people by email"). You decide the data model; they confirm the behavior.
+   **Verify:** read the behavior back in one sentence and get a yes.
+
+3. **Use the shipped interactive teams surface (Tier-1).** Do not invent a blank page. Keep every
+   `TODO(vybekiit)` seam and wire it in the next step.
+   **Verify:** `/dashboard/teams` renders and can send a practice invite.
+
+4. **Wire organizations and invites.** Run `vybekiit apply-preset organizations`, then wire invite
+   flow through `@vybekiit/tenancy` → `resolveTenancyProvider()`. Replace each
+   `TODO(vybekiit)` in the teams feature page.
+   **Verify:** `vybekiit verify-presets organizations` passes; code builds.
+
+5. **Test end-to-end.** Write a test that creates an org, adds a member, and reads membership.
+   **Verify:** test green. 🎉 *Celebrate* — they can invite teammates.
+
+## If anything breaks
+
+Run `doctor`. Common cause: sign-in not wired, or migration not applied.
+
+## Definition of done
+
+Owner can invite a teammate by email, the invite is stored, and a passing test covers org membership.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/add-upload/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: add-upload
+description: let clients upload files safely. Use when the builder says something like: upload; store files; attachments; file upload endpoint.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: add-upload
+
+**Goal:** let clients upload files safely.
+
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) · translate every error · celebrate. Decide all technical choices yourself.
+
+## Steps
+
+1. Run `vybekiit backend add-upload`.
+2. **Verify:** POST `/api/upload` with a small image succeeds; oversized files are rejected.
+3. Wire storage to `@vybekiit/db` storage provider when going live.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/aws-cdk/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: aws-cdk
+description: Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Always use when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
+version: 1
+---
+
+# AWS CDK
+
+## Overview
+
+Domain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.
+
+**When NOT to use:** Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.
+
+## Critical Warnings
+
+**Deadly embrace**: Removing a cross-stack reference deadlocks deployment (`Export ... cannot be deleted as it is in use by ...`). Preferred fix: weaken the reference first — `CrossStackReferences.of($RESOURCE).produce(ReferenceStrength.BOTH)` then `WEAK`, then remove (three deploys). Legacy fallback: two-deploy `this.exportValue()` recipe. See [troubleshooting-deployment](references/troubleshooting-deployment.md).
+
+**Construct ID changes cause replacement**: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always `cdk diff` before deploy. See [refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md).
+
+**UPDATE_ROLLBACK_FAILED**: Stack is stuck. Fix with `cdk rollback $STACK` or `cdk rollback $STACK --orphan <LogicalId>`. See [troubleshooting-deployment](references/troubleshooting-deployment.md).
+
+**Non-empty S3 buckets persist after destroy**: You MUST set both `removalPolicy: DESTROY` and `autoDeleteObjects: true`. Versioned buckets are worse — delete markers persist even after apparent deletion.
+
+## Common Workflows
+
+| Task | Quick Command | Details |
+|------|--------------|---------|
+| Bootstrap | `cdk bootstrap aws://$ACCOUNT/$REGION` | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
+| New TS project | `cdk init app --language typescript` — use `tsx`, `eslint-plugin-awscdk` | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
+| New Python project | `cdk init app --language python` — pin deps, use virtualenv | [bootstrap-and-project-setup](references/bootstrap-and-project-setup.md) |
+| Deploy | `cdk synth --strict` → `cdk diff` → `cdk deploy` | Always diff before deploy to prod |
+| cdk-nag | `Aspects.of(app).add(new AwsSolutionsChecks())` | [compliance-and-drift](references/compliance-and-drift.md) |
+| Drift | `cdk drift $STACK` (use `--fail` in CI) | [compliance-and-drift](references/compliance-and-drift.md) |
+| Import resource | `cdk import` (interactive or `--resource-mapping` for CI), `cdk deploy --import-existing-resources` | [import-and-migrate](references/import-and-migrate.md) |
+| Refactor safely | `cdk refactor --unstable=refactor` — no property changes in same deploy | [refactor-and-prevent-replacement](references/refactor-and-prevent-replacement.md) |
+
+## Troubleshooting
+
+| Error | Cause → Fix |
+|-------|------------|
+| **DeployFailed / DeploymentError** | CDK error isn't the root cause. `cdk deploy $STACK --verbose`, then `cdk --unstable=diagnose diagnose $STACK` (CLI ≥ 2.1120.0); else `aws cloudformation describe-events --stack-name $STACK --filters FailedEvents=true` — the first `_FAILED` event is the cause. [Details](references/troubleshooting-deployment.md) |
+| **NoCredentials / ExpiredToken / AssumeRoleFailed** | `aws sts get-caller-identity` + `cdk doctor`. Expired SSO, missing `env`, missing `sts:AssumeRole`. [Details](references/troubleshooting-credentials.md) |
+| **Asset errors** (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed) | Path wrong, Docker not running, or bootstrap bucket perms. Use `path.join(__dirname, ...)`. [Details](references/troubleshooting-synth.md) |
+| **AppRequired** | Add `"app": "npx tsx bin/my-app.ts"` to `cdk.json`. [Details](references/troubleshooting-synth.md) |
+| **AnnotationErrors** | Fix the underlying issue; suppress with `NagSuppressions` only as last resort. [Details](references/troubleshooting-synth.md) |
+| **ConcurrentReadLock / ConcurrentWriteLock** | `rm -rf cdk.out` then re-run. Parallel CI: `--output ./cdk.out.$BUILD_ID`. [Details](references/troubleshooting-synth.md) |
+| **BootstrapVersionValidation** | Re-bootstrap. Match `--qualifier` everywhere. [Details](references/troubleshooting-credentials.md) |
+| **DependencyCycle** | Extract shared resource into third stack or use SSM for late-binding. [Details](references/troubleshooting-synth.md) |
+| **UnresolvedAccount** | Set explicit `env: { account, region }` on stack. Commit `cdk.context.json`. [Details](references/troubleshooting-credentials.md) |
+| **NoStacksMatched** | CDK uses logical ID (2nd constructor arg), not CFN name. `cdk list` to find IDs. [Details](references/troubleshooting-synth.md) |
+| **Cannot find module** (synth time) | Run `npx tsc --noEmit`, check `cdk.json` app path matches `tsconfig.json` `outDir`, delete stale `.js` files. Python: activate venv. [Details](references/troubleshooting-synth.md) |
+| **V1 import paths / duplicate aws-cdk-lib** | V1 `@aws-cdk/*` imports, wrong `Construct` import, duplicate lib copies in monorepos. [Details](references/v1-to-v2-migration.md) |
+| **Lambda Cannot find module** (runtime) | Wrong handler value, missing SDK v3 migration, Python deps not bundled. [Details](references/troubleshooting-deployment.md) |
+| **API Gateway multi-stage conflicts** | Set `deploy: false` on `RestApi`, create `Deployment` and `Stage` explicitly. [Details](references/troubleshooting-deployment.md) |
+
+## Construct Patterns
+
+Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: `node.defaultChild` → `addPropertyOverride`. See [construct-patterns](references/construct-patterns.md).
+
+## Additional Resources
+
+- Search AWS documentation for "CDK Developer Guide", "CDK API Reference" and "CDK Pipelines" respectively
+
+## Security Considerations
+
+- OIDC for CI/CD credentials (no static keys)
+- `--custom-permissions-boundary` on bootstrap
+- `grant*()` for inter-resource IAM
+- `cdk-nag` + `--strict` in CI
+- Stateful resources in own stack with `terminationProtection: true`
+- Commit `cdk.context.json`