Web app safe refactor status

This document is a living snapshot for conservative, behavior-preserving alignment with Prego Web App Standard. It records audit findings, risk classification, and deferred work — not a mandate to rewrite working code.

Rules: Production behavior is assumed correct. Uncertain items → document and defer, not silent change.

1. Safe audit summary (evidence-based)

Deviations from standard (current monorepo)

Topic	Observation	Severity
Next.js major	Aligned (2026-04): `www` / `admin-web` / `client-web` 16.0.11 (see standardization plan matrix)	Low — keep matrix updated on bumps
Middleware → `proxy` (Next 16)	Build logs deprecate `middleware.ts` in favor of `proxy.ts`. client-web: keep `middleware.ts` + `experimental-edge` for next-on-pages. admin-web: `proxy.ts` was trialed — `opennextjs-cloudflare build` errors (Node.js middleware is not currently supported); keep `middleware.ts` for `cf:build`. (Deploy ADR § Middleware vs `proxy`)	Medium — defer; track OpenNext + Next
Zod + RHF	Strong in client-web. admin-web uses `zod`, `react-hook-form`, `@hookform/resolvers` for email OTP + `@platform/web-auth-schemas`. www uses the same shared package for `TrialEmailGate`. client-web `authEmailSchema` on `SignInForm`, `/signup`, `/forgot-passcode`, `/auth/verify-email`	Medium — extend screen-by-screen
Shared packages	Existing: `@platform/shell`, `@platform/lottie-ui`, `@platform/platform-trust`, cookies/theme/favicon, `@platform/contracts` (ERP + onboarding Zod; re-exports `@platform/web-auth-schemas`), `@platform/web-auth-schemas`. No dedicated `packages/ui`, `packages/forms`, `packages/api-client` as in standard — extraction remains incremental	Medium
Legacy HTML (admin-web)	Reference/demo shells live under `apps/admin-web/archive/legacy-html/` (moved from repo root); `styles.css` / `api.js` / `app.js` stay at app root; lint checks divider copy vs `AuthSocialDivider.tsx`	Low — do not treat as deploy targets
Gateway vs BFF	Matches api-bff-governance — admin same-origin auth BFF; www trial → Zuplo	OK — not a deviation

Risky areas (do not refactor blindly)

admin-web: app/api/auth/*, trial handoff, OAuth callbacks, JWT cookie domain — any change affects login/signup.
www: lib/trial-gateway.ts, trial copy verification scripts — marketing + compliance.
client-web: tenant routes, lib/api-client, dictionaries — i18n and gateway contracts.

Safe refactor opportunities (low risk first)

Documentation cross-links (this file, standard, plan).
Done (partial): @platform/web-auth-schemas — authEmailSchema, otpCodeSchema; consumed by admin-web (signup, AuthCard, EmailOtpVerifyPanel) and www (TrialEmailGate).
Future PR: additional www / client-web forms — same non-breaking rules.

Must defer (high risk or cross-repo)

~~Next major alignment across three apps in one PR.~~ Done in phased PRs — all three apps on 16.0.11; further bumps per matrix, not one mega-PR.
Moving admin-web root HTML without updating verify-*.mjs and README.
New public routes without prego-zuplo OpenAPI first.

2. Risk map

Area	Risk level	Why sensitive	Safe action	Deferred action
Auth / OTP / JWT (admin)	High	BFF + cookie rewriting	Doc-only; add Zod only behind same payloads	OAuth route changes
Trial www → admin handoff	High	CP internal + cookies	Doc-only	Any URL/env change
Billing / Stripe (admin)	High	Money path	Doc-only	Schema without E2E
client-web tenant + API	High	Multi-tenant	Doc-only; extract dup only with tests	Hono/route changes in app
www marketing / trial copy	Medium	Scripts gate copy	Doc-only	Wording without `verify:*`
Legacy HTML (admin)	Medium	Lint ties HTML ↔ TS	Document location	Move to `archive/` in dedicated PR
Next version drift	Low (was Medium)	Three apps on 16.0.11; adapters differ (OpenNext vs next-on-pages)	Track matrix + ADR	Patch bumps without CI

3. Conservative refactoring plan (ordered)

Keep this status doc + hub links updated when standards change.
Per-app PR (future): admin-web — add zod + react-hook-form to one flow; mirror existing validation rules exactly.
Per-app PR (future): extract duplicate Zod types to packages/contracts only when two call sites already match.
Legacy HTML: Done (admin-web): index.html, signup.html, signup-verify.html, billing.html, dashboard.html → archive/legacy-html/; scripts/README updated; internal asset links use ../ to root JS/CSS.
Next alignment: follow standardization plan phases — admin + client first.

4. Shared package extraction plan

Target	From	Into	Compatibility
Email + OTP Zod (admin, www trial)	`apps/admin-web` local modules	`@platform/web-auth-schemas`	Done — same `AUTH_EMAIL_RE` / `otpCodeSchema`
Duplicate API shapes	client-web Hono + future second consumer	`packages/contracts` (new)	Password sign-in/up schemas now in `@platform/web-auth-schemas`; broader extraction still when two call sites need it
Form primitives	Only if 3+ dupes	`packages/forms`	Wrapper components

Precondition: prove duplication; add tests or snapshot before/after.

5. App-by-app notes

apps/admin-web

Issues vs standard: Legacy HTML at repo root with intentional lint coupling.
Target non-breaking state: RHF + Zod on new/edited forms only; payloads unchanged; prefer @platform/web-auth-schemas for shared email/OTP rules.
Must not change: Public routes, app/api/auth/* semantics, env contract, root HTML strings relied on by scripts/verify-*.mjs.

apps/client-web

Closer to standard (Zod, RHF, TanStack-adjacent patterns per codebase). authEmailSchema on SignInForm, /signup, /forgot-passcode, /auth/verify-email (stored / query email + before OTP verify).
Must not change: dictionaries/* merge rules, NEXT_PUBLIC_API_URL usage patterns, PWA build pipeline without QA.

apps/www

Static/marketing; trial → Zuplo direct. TrialEmailGate uses RHF + Zod + @platform/web-auth-schemas (authEmailSchema).
Must not change: Trial gateway behavior, Pages Functions contracts checked by verify:www-pages-functions.mjs.

6. Cleanup plan (default: defer)

Item	Location	Issue	Proposed action	Why safe	If uncertain
Root `*.html`	admin-web	Was mixed with active tree	Done — see `archive/legacy-html/README.md`	Lint paths updated	—

7. Documentation update plan

Code area	Affected doc	Change type
Safe refactor program	This file	New / revise snapshot
Hub discovery	Platform hub	Link row
Standardization	Web app standardization plan	Link to this status

8. Validation checklist (after any future code PR)

App verify / CI scripts pass (verify:www, verify:client-web — quick step includes Vitest test:unit with app verify, then production next build; see apps/client-web/AGENTS.md, admin lint + typecheck + targeted E2E as applicable).
client-web app/my-ai/ edits: do not import @/app/my-ai/page-controller from orchestration modules — ESLint eslint.config.mjs; see apps/client-web/AGENTS.md (Assistant UI).
No route or env rename without runbook update.
OpenAPI unchanged unless prego-zuplo PR merged first.
This doc or standard updated if behavior contract documented.

9. Next incremental candidates (not scheduled)

Area	Idea	Risk
`EmailOtpVerifyPanel`	Done: RHF + `zodResolver` (`code` = `otpCodeSchema`) before `verifyOtp`; API/resend errors on `root`	—
`CompanyInfoStep` (`app/page.tsx`)	Done: RHF + `zodResolver`(`companyInfoStepFormSchema`) + `useFieldArray` for invites; same Zod rules as before	E2E optional
www / client-web (shared email + RHF where listed in §3.4)	Done for current snapshot — `TrialEmailGate`, manual approval `workEmail`, client-web auth/signup/forgot/`SignInForm`/`verify-email`/invoices recipient, `lib/schemas/auth`	Deep ERP forms, new screens — per-screen / future

10. Revision

Date	Note
2026-04-06	Initial snapshot — audit-only; no app source edits in the same commit as doc introduction.
2026-04-06	admin-web `app/signup/page.tsx`: email field uses RHF + Zod (`@platform/web-auth-schemas`); same `AUTH_EMAIL_RE` as before; trial handoff still uses `setValue`. Empty/invalid submit now shows inline messages (previously empty was silent).
2026-04-06	admin-web `components/auth/AuthCard.tsx` (used by `/login` and onboarding `/` step 2): same RHF + Zod schema; `app/login/page.tsx` preset query uses shared `AUTH_EMAIL_RE`.
2026-04-06	Renamed schema module `signup-email.ts` → `auth-email.ts` (now `packages/prego-web-auth-schemas`); exports `authEmailSchema`, `AuthEmailValues`, `AUTH_EMAIL_RE`.
2026-04-06	Prego Web App Standard §3.4 implementation snapshot; this doc §9 next candidates; Korean summary updated.
2026-04-06	admin-web `EmailOtpVerifyPanel`: `otpCodeSchema` before `verifyOtp`.
2026-04-06	`@platform/web-auth-schemas` workspace package: `auth-email` + `otp-code` modules; admin-web and www `TrialEmailGate` import from it; admin README + §3.4 updated.
2026-04-06	admin-web onboarding `CompanyInfoStep`: `lib/schemas/company-info-step.ts` — Zod for subdomain (`validateSubdomain`), company max length, invite emails (`authEmailStringSchema`); inline field errors (replaces subdomain-only `alert`).
2026-04-06	admin-web Vitest: `lib/schemas/company-info-step.test.ts`; schema imports `../api` (Vitest resolves `../`, not `@/`).
2026-04-06	client-web `SignInForm`: `authEmailSchema` before discover and send-code; `@platform/web-auth-schemas` + `next.config.mjs` `transpilePackages`.
2026-04-06	client-web `/signup` and `[lang]/forgot-passcode`: `authEmailSchema` before OTP request / passcode reset.
2026-04-06	client-web `auth/verify-email`: `authEmailSchema` for `sessionStorage` / `?email=` bootstrap and before `POST /auth/otp/verify`.
2026-04-06	`@platform/web-auth-schemas`: export `authEmailStringSchema` (refactor `authEmailSchema`); client-web onboarding + invoices/create use it.
2026-04-06	`client-web` `lib/schemas/auth` (Hono `/signin` / `/signup`) and `www` `manual-approval-verify-schema` `workEmail`: `authEmailStringSchema` (replaces `z.string().email()`).
2026-04-06	admin-web `lib/schemas/company-info-step`: invite emails validated with `authEmailStringSchema.safeParse` (replaces raw `AUTH_EMAIL_RE`).
2026-04-06	`@platform/web-auth-schemas`: Vitest *`src/.test.ts`, `vitest.config.ts`; root `build:verify` runs `pnpm --filter @platform/web-auth-schemas run test`. AGENTS.md** documents the package.
2026-04-06	GitHub Actions `.github/workflows/web-auth-schemas.yml` — `typecheck` + `test` on `packages/prego-web-auth-schemas` changes.
2026-04-08	`@platform/web-auth-schemas` / `@platform/contracts`: each package defines `verify` (= `typecheck` + Vitest). Root `pnpm run verify:web-auth-schemas`, `pnpm run verify:contracts`, `pnpm run verify:shared-zod` (both); `build:verify` uses `verify:shared-zod`. `.github/workflows/web-auth-schemas.yml` runs `pnpm --filter … run verify` for each package.
2026-04-08	`@platform/contracts`: Vitest `contracts-schemas.test.ts`, `index.barrel.test.ts` (barrel *`export `** smoke).
2026-04-08	`.github/workflows/build-client-web.yml`: `paths` include `packages/contracts/` and `packages/prego-web-auth-schemas/` so shared Zod changes still run client-web `verify:client-web` + E2E.
2026-04-06	Cursor `.cursor/rules/prego-client-web.mdc` + `prego-multi-repo-platform.mdc`: `@platform/web-auth-schemas`; repository README index Prego row links CI workflow.
2026-04-06	`prego-www`: `.cursor/rules/prego-www.mdc` + `apps/www/README.md` — `@platform/web-auth-schemas` (`TrialEmailGate`, manual approval `workEmail`).
2026-04-06	`prego-admin-web`: `.cursor/rules/prego-admin-web.mdc` + `apps/admin-web/AGENTS.md`; `prego-multi-repo-platform.mdc` points agents at admin-web when scoped to `apps/admin-web/`**.
2026-04-06	admin-web `CompanyInfoStep` (`app/page.tsx`): RHF + `useFieldArray` (`keyName: '_rhfRowId'`) + shared `companyInfoStepFormSchema`; exports `CompanyInfoStepFormValues` from `lib/schemas/company-info-step.ts`.
2026-04-06	admin-web `EmailOtpVerifyPanel`: RHF + `zodResolver` (`otpPanelFormSchema` = `z.object({ code: otpCodeSchema })`); digit UI syncs `code`; `setError('root')` for `verifyOtp` / `createOtp` failures.
2026-04-06	client-web `app/signup/page.tsx` (`SignUpPage`, used by `[companyId]/[lang]/signup`): RHF + `zodResolver` — `firstName` + `authEmailStringSchema`; API errors `setError('root')`.
2026-04-06	client-web `[companyId]/[lang]/forgot-passcode/page.tsx`: RHF + `zodResolver`(`authEmailSchema`); rate limit / API errors `setError('root')`.
2026-04-06	client-web `components/signin-form.tsx`: RHF + `authEmailSchema`; `useWatch` for email; discover API / demo-login failures `setError('root')`; `send_code` uses `trigger('email')`; demo navigations use `window.location.assign`.
2026-04-06	client-web `auth/verify-email`: `useForm`(`authEmailSchema`), `setValue` from session / `?email=`; `handleSuccess` uses `trigger('email')` + `setError('root')`. `invoices/create`: `recipientEmail` — RHF + `invoiceRecipientEmailSchema` (optional `authEmailStringSchema`).
2026-04-06	Web app standard §3.4: client-web row → Aligned (auth / email surfaces); §9 www / client-web candidate row → sweep Done for listed routes.
2026-04-06	client-web root `/signin`: placeholder password form removed; `router.replace` to `/default/{getPreferredAuthLocale()}/signin`.
2026-04-06	client-web `middleware.ts`: `/forgot-password` and `/forgot-passcode` (top-level) → `/{default}/forgot-passcode`; `isPublic` extended for `forgot-passcode`, `reset-passcode`, `passcode/set` (session-gated routes were incorrectly redirecting unauthenticated users).
2026-04-06	client-web Playwright `e2e/top-level-redirects.spec.ts` (top-level + legacy `/en` redirects); `playwright.config.ts` uses `next dev --webpack`; `.github/workflows/build-client-web.yml` runs `test:e2e` after `verify:client-web`. Monorepo `pnpm run test:e2e:client-web`. Root `/signin` fallback uses `NEXT_PUBLIC_DEFAULT_COMPANY_ID` (aligned with `middleware.ts`).
2026-04-07	Web app standard §2.3: Starlight 및 기타 문서 전용(외부) 솔루션은 본 표준 범위 밖 — 대상은 `www` / `admin-web` / `client-web` 만.
2026-04-07	client-web ERP 표면: `lib/schemas/checklist-add.ts` + `app/checklist/add/page.tsx` (RHF + `zodResolver`); `lib/schemas/leaves-request.ts` + `app/leaves/page.tsx` (휴가 신청 카드). (경비 캡처는 아래 2026-04-08 행.)
2026-04-08	client-web `expenses/capture`: RHF + `zodResolver` (`expenseCaptureFormSchema`); 제출 `handleSubmit`; 활성화 `formState.isValid` (`mode: 'onChange'`). Zod 원본은 `@platform/contracts` (`expense-capture`).
2026-04-07	client-web `tsconfig.json`: `include` 에서 `.next/dev/types` 제거 — 오래된 dev 타입으로 `tsc --noEmit` 가 실패하는 문제 완화; `.next/types` 만 포함.
2026-04-07	client-web Playwright `playwright.config.ts`: per-test `timeout` and `navigationTimeout` 90s (webpack first-compile can exceed default 30s); `AGENTS.md` notes this.
2026-04-07	admin-web 레거시 정적 HTML: 루트 *`.html` 다섯 파일 → `archive/legacy-html/`; 상대 경로로 루트 `styles.css`, `locale.js`, `api.js`, `app.js` 로드; `verify-auth-social-divider-copy.mjs`** 경로 갱신.
2026-04-07	Web app standardization plan: Next.js version matrix, deploy posture (client next-on-pages vs admin OpenNext), `packages/contracts` deferral 단락 추가.
2026-04-08	admin-web ESLint *`react-hooks/`: trial handoff / checkout success / mounted / `use-media-query` / celebration — avoid synchronous `setState` in effects (`queueMicrotask`); provisioning `pollJob` → inner `tick` recursion (no self-reference TDZ); `CompanyInfoStep` `watch('company')` → `useWatch`. `pnpm run lint`** passes.
2026-04-08	admin-web Playwright `playwright.config.ts`: default `workers: 1` (one `next dev` + route mocks flake under parallel workers); optional `PW_WORKERS`. Documented in `apps/admin-web/AGENTS.md`, monorepo `AGENTS.md`, `.cursor/rules/prego-admin-web.mdc`.
2026-04-08	client-web `tsconfig.json`: `include` 에서 `.next/dev/types` 다시 제거 (재추가되면 `tsc --noEmit` 가 `.next/dev/types/app/signup/page.ts` 등으로 실패할 수 있음). `.next/types` 만 유지.
2026-04-08	client-web: `next build` 가 `include` 에 `.next/dev/types` 를 다시 넣음 — `scripts/strip-next-dev-types-from-tsconfig.mjs` 를 `typecheck` / `build` (및 `build:fast` / `build:single`)에 연결; `exclude` 에 `.next/dev` 유지.
2026-04-08	client-web: `pages:build` (`@cloudflare/next-on-pages`) 끝에도 동일 strip 스크립트; `.github/workflows/build-client-web.yml` 주석 보강.
2026-04-09	admin-web `proxy.ts` trial (reverted): Next 16 `proxy` breaks `pnpm run cf:build` — OpenNext: Node.js middleware is not currently supported; `middleware.ts` restored. Deploy ADR § Middleware vs `proxy`.
2026-04-09	admin-web: `scripts/strip-next-dev-types-from-tsconfig.mjs` (same idea as client-web); `build`, `cf:build`, `typecheck` wired; `AGENTS.md` + `.cursor/rules/prego-admin-web.mdc` use `pnpm run typecheck` instead of raw `tsc`.
2026-04-09	www: same strip script; `tsconfig` `exclude`: `".next/dev"`; `build` / `typecheck`; `verify` runs `typecheck` after lint; `README.md` · `.cursor/rules/prego-www.mdc` · continuation plan §1.4.
2026-04-10	admin-web CI: `.github/workflows/admin-web-verify.yml` and `deploy-admin-web-worker.yml` run `pnpm --filter prego-admin-web run typecheck` after lint (strip `.next/dev/types` + `tsc --noEmit`, aligned with www / client-web). Monorepo `AGENTS.md` admin paragraph updated.
2026-04-11	www `next.config.mjs`: `outputFileTracingRoot` and `turbopack.root` → monorepo root (Turbopack could not resolve `next` when Playwright started `next dev`). Playwright: `webServer` command embeds `NEXT_PUBLIC_ZUPLO_API_URL=https://trial-e2e.invalid`; `reuseExistingServer` only if `PW_REUSE_WEB_SERVER=1` (avoids reusing a dev server without Zuplo env). `e2e/marketing-pages.spec.ts`: `OPTIONS` + CORS headers on mocked Zuplo `fulfill`. `.github/workflows/deploy-pages.yml` (comment on marketing E2E), `apps/www/README.md`, `.cursor/rules/prego-www.mdc`.
2026-04-11	client-web `app/my-ai/prompt-wizard/page.tsx`: RHF + `zodResolver` (`lib/schemas/prompt-wizard.ts` — When / What / How / Output required); template query `?t=` uses `setValue`; field errors replace toast-only “fill all”.
2026-04-11	client-web `playwright.config.ts`: default `workers: 1` (parallel `next dev` navigations could kill the server → `ERR_CONNECTION_REFUSED`); optional `PW_WORKERS`. `apps/client-web/AGENTS.md`, `.cursor/rules/prego-client-web.mdc`, monorepo `AGENTS.md`.
2026-04-12	`@platform/web-auth-schemas`: `password-auth` (`signInSchema`, `signUpSchema`, `SignInInput`, `SignUpInput`) — Vitest `password-auth.test.ts`; client-web `lib/schemas/auth` re-exports for Hono `src/server/routes/auth.ts`.
2026-04-13	client-web BFF *`/api/auth/email/`: Zod on Route Handlers (`authEmailSchema`, `authEmailVerifyOtpBodySchema`) before Zuplo; `fetchAuthEmailSendOtp` / `fetchAuthEmailVerifyOtp`; Playwright `e2e/auth-email-bff-validation.spec.ts`; ESLint ignores `test-results/`, `playwright-report/`. `@platform/contracts` barrel test covers `otpCodeSchema` + `authEmailVerifyOtpBodySchema`. Two OTP flows (ERP `/auth/otp/`* vs Zuplo *`/auth/email/` Auth email OTP) documented in `apps/client-web/AGENTS.md` and `.cursor/rules/prego-client-web.mdc`. §1 shared-packages row + §11 `packages/contracts`** backlog updated.
2026-04-14	admin-web BFF *`/api/auth/email/`: same Zod validation as client-web (`authEmailSchema`, `authEmailVerifyOtpBodySchema` from `@platform/web-auth-schemas`); Playwright `e2e/auth-email-bff-validation.spec.ts`; ESLint `test-results/`, `playwright-report/`. `apps/admin-web/AGENTS.md`, `.cursor/rules/prego-admin-web.mdc`, monorepo `AGENTS.md`** (Playwright bullet).
2026-04-15	Docs / discovery: monorepo root `README.md` repository table — `packages/README.md`, `prego-web-auth-schemas`, `contracts`; mermaid Packages subgraph includes `web-auth-schemas + contracts`. `docs/README.md` Quick links (platform hub, repository README index, `packages/README.md`, `pnpm run build:verify` → `AGENTS.md`); management guideline + KO sync for workspace Zod. `docs/api-spec/README.md` — spec sync mentions `shared-schema`, `web-auth-schemas`, `contracts` (not `shared-schema` only). Repository README index Prego row; `pnpm run build:docs` / `cd docs && pnpm run build` exercised. `AGENTS.md`: `pnpm run build:verify` (`typecheck:shell`, `@platform/lottie-ui` verify, `verify:cookies`, `verify:shared-zod`, `@platform/platform-trust` build + test, `build:docs`).
2026-04-13	client-web BFF *`/api/auth/email/`: Zuplo 프록시 전 Route Handler에서 `authEmailSchema`, `authEmailVerifyOtpBodySchema` 검증; `fetchAuthEmailSendOtp` / `fetchAuthEmailVerifyOtp`; Playwright `e2e/auth-email-bff-validation.spec.ts`; ESLint `test-results/`, `playwright-report/` 무시. ERP `/auth/otp/`* 와 Zuplo *`/auth/email/` (Auth email OTP) 두 OTP 흐름은 `apps/client-web/AGENTS.md` · `.cursor/rules/prego-client-web.mdc`** 에 명시.
2026-04-14	admin-web BFF *`/api/auth/email/`: client-web 과 동일 Zod (`authEmailSchema`, `authEmailVerifyOtpBodySchema`, `@platform/web-auth-schemas`); Playwright `e2e/auth-email-bff-validation.spec.ts`; ESLint 동일 ignore. `apps/admin-web/AGENTS.md`, `.cursor/rules/prego-admin-web.mdc`, 모노레포 `AGENTS.md`** (Playwright bullet).
2026-04-15	문서·발견 (한국어 요약 행): 루트 `README.md` 저장소 표 + mermaid Packages 노드 `web-auth-schemas + contracts`; `docs/README.md` 빠른 링크에 `pnpm run build:verify` → `AGENTS.md` 행 추가 · `docs/api-spec/README.md`; 저장소 README 색인 Prego 행; `pnpm run build:docs` 검증. `AGENTS.md` — `pnpm run build:verify` 전체 단계 (`typecheck:shell`, lottie-ui, cookies, `verify:shared-zod`, platform-trust, `build:docs`).
2026-04-16	client-web Assistant UI `/my-ai`: `@/app/my-ai/page-controller` barrel (hook, types, param builders, shell pipeline pure helpers); tests *`app/my-ai/page-controller/.test.ts`; `pnpm run verify` includes Vitest `test:unit`; `test:unit:watch`, monorepo `test:unit:client-web` / `test:unit:client-web:watch`. `apps/client-web/AGENTS.md`, `README.md`, refactoring prompt table, §8 checklist here, continuation plan §1.2, web app standard §3.4 client-web row, `.cursor/rules/prego-client-web.mdc`; monorepo `AGENTS.md`** client-web bullet.
2026-04-17	client-web Assistant UI: `eslint.config.mjs` `no-restricted-imports` — `@/app/my-ai/page-controller` allowed only from `app/my-ai/page.tsx` and `app/my-ai/page-controller/` (barrel + tests); other `app/my-ai/` modules must use concrete *`build-my-ai-page-controller-.ts` paths (avoids circular dependency with `useMyAiPageController`). `apps/client-web/AGENTS.md`, `.cursor/rules/prego-client-web.mdc`**.
2026-04-18	Docs: Web app standard §3.4 client-web row — Assistant UI barrel + ESLint note; `apps/client-web/app/my-ai/page-controller/index.ts` JSDoc (ESLint pointer). Continuation plan §1.1 — client-web — Assistant UI main route bullet (barrel, Vitest, ESLint, links to `AGENTS.md`, standard, safe refactor status §10). `apps/client-web/README.md` (EN + KR) — Assistant UI ESLint bullet under Verification. Refactoring prompt — client-web — Assistant UI paragraph after verify commands table; Prompt A mandatory-context bullet when `app/my-ai/` is in scope; Prompt A — Example 4 (Assistant UI orchestration, ready to paste).
2026-04-19	Monorepo `AGENTS.md`: client-web bullet — parenthetical pointer to Assistant UI `page-controller` barrel, Vitest `test:unit`, ESLint (`apps/client-web/AGENTS.md` is source of truth). §8 validation checklist — `app/my-ai/` barrel-import row.
2026-04-20	client-web BFF `app/api/auth/email/send-otp`, `verify-otp`: `export const runtime = 'edge'` so `@cloudflare/next-on-pages` / `pnpm run pages:build` includes them (Node-default Route Handlers fail the Pages bundle). `apps/client-web/AGENTS.md` `pages:build` bullet documents the rule.
2026-04-21	Monorepo: `@platform/next-dev-scripts` — shared `prego-strip-next-dev-types-from-tsconfig` CLI (`process.cwd()` → app `tsconfig.json`); www / admin-web / client-web remove per-app `scripts/strip-next-dev-types-from-tsconfig.mjs`. Root `pnpm run verify:next-dev-scripts` (also `build:verify`). `packages/README.md`, `AGENTS.md`, app `AGENTS.md`, *`.cursor/rules/prego--web.mdc`**.
2026-04-22	CI: `.github/workflows/next-dev-scripts.yml` — runs on `packages/prego-next-dev-scripts/` (and lockfile / root `package.json`); `pnpm run verify:next-dev-scripts`. Standardization plan §4 deploy block: DX — Next tsconfig hygiene** bullet.
2026-04-23	CI: `next-dev-scripts.yml` path filters include `apps/www/package.json`, `apps/admin-web/package.json`, `apps/client-web/package.json` (strip CLI wiring changes). Refactoring prompt verify table: monorepo `@platform/next-dev-scripts` row. Repository README index Prego row: `next-dev-scripts.yml` link next to `web-auth-schemas.yml`.
2026-04-24	Web app standard §7 — bullet on `@platform/next-dev-scripts` / `prego-strip-next-dev-types-from-tsconfig`; 한국어 요약 동기화. Dependency inspection (AI) §8 (+ 한국어 요약) — 변경 시 `pnpm run verify:next-dev-scripts`.
2026-04-25	IDE guide — Prego monorepo verification section; platform hub Related — `build:verify` / `verify:next-dev-scripts`. `@platform/next-dev-scripts` `package.json` `engines.node` → `>=24`.
2026-04-26	Monorepo `AGENTS.md` — dedicated Next dev scripts (`@platform/next-dev-scripts`) section (CLI, CI, links to `prego-web-app-standard.md` §7 · `ai-ide-guide.md`); `packages/README.md` index bullet lists `@platform/next-dev-scripts`. Package `README.md` Related docs; `.cursor/rules/prego-multi-repo-platform.mdc` pointer to those paths.
2026-04-27	`.github/workflows/README.md` — workflow index table; root `README.md` (EN + KO) — `pnpm run build:verify` + link to workflows README.
2026-04-28	`docs/README.md` Quick links + KO 관리 가이드라인 — `.github/workflows/README.md`. Platform hub Related (+ KO) — GitHub Actions index. Dependency inspection §8 (+ KO) — workflow table pointer.
2026-04-29	Monorepo `AGENTS.md` — `build:verify` paragraph + Next dev scripts section link `.github/workflows/README.md`; repository README index Prego row. `.cursor/rules/prego-multi-repo-platform.mdc` — GitHub Actions index line. Refactoring prompt verify table — workflow map pointer.
2026-04-30	Deploy ADR — Phase 4 migration delta checklist (표: middleware, E2E, PWA, BFF `runtime`, strip/typecheck, `pages:build` vs OpenNext, 캐시/R2). Continuation plan §2 E 행 · 표준화 계획 deploy 블록 링크 보강.
2026-05-01	client-web `lib/schemas/passcode-pin.ts` — `parsePasscodePin` / `passcodePinSchema` (`otpCodeSchema` 동일 규칙); `passcode/set`, `passcode/change`, `reset-passcode` 페이지에서 Worker `fetch` 전 검증; Vitest `lib/schemas/passcode-pin.test.ts`. Web app standard §3.4 client-web 행 · `apps/client-web/AGENTS.md`.
2026-05-02	client-web 동일 `parsePasscodePin` — `components/signin-form.tsx` (`/auth/verify`) · `app/[companyId]/[lang]/passcode/page.tsx`. `apps/client-web/AGENTS.md` passcode bullet 보강.
2026-05-03	Dependency inspection (AI) §8 (+ 한국어 요약) — client-web `parsePasscodePin` / Auth Worker 호출 전 검증. `lib/schemas/passcode-pin.test.ts` — 7자리 거부·선행 0 허용 케이스.
2026-05-04	IDE guide Prego monorepo verification (+ KO) — client-web passcode `parsePasscodePin` bullet. Refactoring prompt — client-web — passcode keypad 단락. 모노레포 `AGENTS.md` client-web 괄호 안 `lib/schemas/passcode-pin` 포인터. `.cursor/rules/prego-multi-repo-platform.mdc` — client-web 줄에 `parsePasscodePin` 안내.
2026-05-05	client-web `PASSCODE_PIN_LENGTH` (`lib/schemas/passcode-pin.ts`) — 키패드 `PasscodeEntryForm` / `PasscodeSetForm` / `PasscodeChangeForm` 기본값; 중복 `pinLength={6}` 제거. Vitest `PASSCODE_PIN_LENGTH` vs `passcodePinSchema`. `apps/client-web/AGENTS.md` · Dependency inspection §8 (+ KO) · IDE guide · Refactoring prompt · `.cursor/rules/prego-client-web.mdc` · `prego-multi-repo-platform.mdc` · 모노레포 `AGENTS.md`.
2026-05-06	Docs (MDX entry points): root `README.md` (English `Monorepo integration verify` + Korean `모노레포 통합 검증`) — internal `docs/` MDX + `docs/README.md`. `docs/README.md` Quick links + KO 관리 가이드라인 — `src/content/docs/` MDX cross-ref. `docs/api-spec/README.md`, `packages/README.md`, `.github/workflows/README.md` — MDX + `docs/README.md`. `pnpm run build:docs` exercised. Platform hub Related already covered MDX.
2026-05-07	`docs/architecture/README.md` — Related (EN + KO): published docs in Starlight `docs/src/content/docs/`, `pnpm run build:docs`, MDX + `docs/README.md`; clarifies this `architecture/` tree is plain Markdown for diagrams. `packages/prego-next-dev-scripts/README.md` — Related docs (Starlight) adds MDX link to `docs/README.md`.
2026-05-08	`docs/README.md` — Document structure table architecture row + Quick links row → `architecture/README.md` (Starlight `src/content/docs/` vs plain `docs/architecture/`). Korean 목적 architecture bullet aligned.
2026-05-09	Docs — stale `docs/dist` troubleshooting: `renderers.mjs` (and `docs/dist` chunk) called out consistently — root `README.md` (EN + KO), `AGENTS.md`, `docs/README.md` (Starlight bullets + Quick links + KO 관리 가이드라인), `docs/api-spec/README.md` (EN + KO), `.github/workflows/README.md`, `packages/README.md` (EN + KO), `.cursor/rules/prego-multi-repo-platform.mdc`, Dependency inspection §8 (+ KO), platform hub, IDE guide, repository README index, web app standard / standardization plan / refactoring prompt. `pnpm run build:docs` — pass (250 pages).
2026-05-10	Phase 2 — platform doc index: roadmap §7 Related platform docs (EN + KR); overview Where to read next; repo responsibility matrix prego-control-plane / prego_ai rows; dependency inspection §3 (+ KR); platform hub KR — Phase 2. prego-control-plane root `README.md` Phase 2 paragraph (connector kind / `credentialRef` TBD). Monorepo `AGENTS.md` §4 Phase 2 pointer.
2026-04-07	client-web `auth/verify-email`: ERP `POST /auth/otp/verify` 전 `CodeEntryForm` 코드에 `parsePasscodePinFromInput` (`lib/schemas/passcode-pin.ts` — 비숫자 제거 후 `parsePasscodePin` / `otpCodeSchema`). Vitest `parsePasscodePinFromInput` 케이스. `apps/client-web/AGENTS.md` verify-email 불릿.
2026-04-07	client-web `CodeEntryForm` / `OtpDigitBoxes`: 로컬 `6` 상수 제거 → `PASSCODE_PIN_LENGTH`; `otp-digit-boxes` `maxLength` 를 해석된 `len` 과 일치. `apps/client-web/AGENTS.md` passcode 불릿.
2026-04-07	client-web `takeLeadingDigits` (`lib/schemas/passcode-pin.ts`): 비숫자 제거 + 최대 길이 슬라이스 — `parsePasscodePinFromInput`·`otp-digit-boxes` 가 공유; Vitest `takeLeadingDigits` 케이스. `apps/client-web/AGENTS.md` passcode 불릿.
2026-04-07	client-web `lib/api-json.test.ts`: `jsonListPayload` (목록 API `{ data }` / `{ results }` / 배열) — notices·checklist·invoices 등에서 사용; Vitest.
2026-04-07	client-web `lib/escape-html.test.ts`: `escapeHtml` (`dangerouslySetInnerHTML` 전용 최소 이스케이프) — Vitest.
2026-04-07	client-web Vitest: `get-dictionary.test.ts` (`isSupportedLocale`), `lib/data/countries.test.ts` (`formatCallingCode`), `onboarding-page-helpers.test.ts`, `cookie-settings-label.test.ts`, `autopilot-prompt-wizard-build.test.ts`, `autopilot-templates-catalog.test.ts`.
2026-04-07	client-web Vitest: `extract-prego-jwt-from-set-cookie.test.ts` (`extractPregoJwtFromResponseHeaders`), `my-ai-labels.test.ts` (Scheduled automation·remove 메뉴 라벨 폴백).
2026-04-07	client-web Vitest: `my-ai-engine-display.test.ts` (`buildEngineDisplayRows`, `ENGINE_OPTIONS`).
2026-04-07	client-web Vitest: `dark-chrome-border.test.ts`, `logo-base-url.test.ts`, `zuplo-public-paths.test.ts`.
2026-04-07	client-web Vitest: `auth-email-upstream-base.test.ts` (`getServerZuploBaseForAuthEmail`), `my-ai-replace-message-by-id.test.ts`, `my-ai-share-url.test.ts`.
2026-04-07	client-web Vitest: `my-ai-send-resolve-inputs.test.ts` (redo / composer / hub·wizard), `autopilot-landing-myai.test.ts` (`formatAutopilotTemplateStartedToast`).
2026-04-07	client-web Vitest: `autopilot-config.test.ts` (`detectTemplateFromInput`, `buildPlanFromTemplate`), `my-ai-build-user-message.test.ts` (`buildMyAiUserMessage`).
2026-04-07	client-web Vitest: `autopilot-template-labels.test.ts` (`buildMermaidFromLabels`), `my-ai-page-helpers.test.ts`, `my-ai-session-sidebar-derivations.test.ts`, `lib/utils.test.ts` (`cn`), `lib/utils/date-formatter.test.ts` (`getFormattedMonthYear` — app locale `zh` literal branch + `en` smoke).
2026-04-07	client-web Vitest: `checkin-config.test.ts` (`isCheckinDevMode`, dynamic import + `vi.stubEnv`), `my-ai-chat-request-body.test.ts` (`buildMyAiChatPostBody`), `my-ai-session-last-message-preview.test.ts` (`updateMyAiSessionLastMessagePreview`), `set-prego-jwt-on-response.test.ts` (`setPregoJwtCookieOnResponse`). `onboarding-affirmation-fallback.test.ts` — `vi.mock` `.md` imports then `getAffirmationFallback`*.
2026-04-07	client-web Vitest: `onboarding-notice-fallback.test.ts` (`vi.mock` `.md`), `my-ai-mock-assistant-message.test.ts`* (`buildMyAiMockAssistantMessage`), `my-ai-chat-stream-text.test.ts` (`collectMyAiChatStreamText` — blank / `!ok` / SSE / JSON), `lib/utils/detect-language.test.ts` (`detectBrowserLanguage`, `getPreferredAuthLocale` + `vi.stubGlobal`).
2026-04-07	Monorepo — Phase 2 thin slots: `@platform/contracts` `connectorKindSchema` / `connectorEndpointSchema`; `prego_ai` `workers/src/lib/connector-kind.ts`; platform doc Phase 2 — connector slots. packages: `@platform/ui` (lottie re-exports), `@platform/forms` (`zodResolver` barrel), `@platform/api-client` (`fetchJson`) — verify in root `build:verify`; app imports optional / gradual. Zuplo (prego-zuplo): attendance+ business OAS bundles (`pnpm run oas:bundle-attendance-business`, 67→61 fragments); `docs/planning/oas-layout-history.md`. middleware → `proxy`: still deferred (Deploy ADR § Middleware vs `proxy`); no `proxy.ts` rollout for admin-web / client-web in this round. client-web → OpenNext: ADR + checklist only; no `pages:build` → Worker migration. CP Hono / public HTTP: unchanged — how-to-add-api order; CP optional P6.
2026-04-07	Continuation: Zuplo Assistant UI `31`–`61` → four bundles (`pnpm run oas:bundle-my-ai`, 61→34 fragments); `@platform/forms` `devDependency` `@hookform/resolvers` aligned to `^3.9.1` (avoids `zodResolver` type drift vs apps). admin-web / www — `zodResolver` from `@platform/forms` + `transpilePackages`; CI path filters `packages/prego-forms/` (`admin-web-verify`, `deploy-pages`, `deploy-admin-web-worker`**).
2026-04-07	Zuplo (continued): trial `15`–`19`, CP public `20`–`21`, external AI/MCP `62`–`67` → `15-trial-access-bundle`, `20-control-plane-public-bundle`, `35-external-ai-mcp-bundle` (`pnpm run oas:bundle-trial-cp-external`, 34→24 fragments); prego-zuplo `verify` pass.
2026-04-07	Zuplo (portal): `scripts/sanitize-oas-parameter-required.mjs` — bundle deep-merge could yield invalid *`components.parameters..required: {}` (OpenAPI requires boolean; Zudoku `verify:portal` failed). `scripts/sync-oas.mjs` runs sanitize before copy + merge; `docs/planning/oas-layout-history.md` · prego-zuplo `AGENTS.md`. `pnpm run verify:portal`** pass.
2026-04-07	Phase 2 — connector kind: `@platform/contracts` `connector-metadata.test.ts` asserts `connectorKindSchema.options` (four kinds). phase-2-connector-slots documents Vitest alignment with prego_ai `connector-kind.test.ts` · `AGENTS.md`.

11. Backlog execution snapshot (2026-04-06)

Prior item	Action this round
Next major alignment	Done — three apps on 16.0.11; matrix + ADR updated; `pnpm` verify/build paths exercised (`admin` `cf:build`, client `verify`+`build`, www `verify`+`build`, `build:docs`).
`packages/contracts`	In use — ERP + onboarding shapes + Vitest barrel smoke; broader extraction still follows standardization plan (prove duplication before new modules). Password sign-in/up Zod lives in `@platform/web-auth-schemas`; client-web `lib/schemas/auth` re-exports for Hono.
`packages/forms`	Introduced — `@platform/forms` (`zodResolver` re-export); apps migrate imports gradually — no mandatory sweep.
`packages/ui` / `api-client`	Introduced (thin) — `@platform/ui` (re-exports `@platform/lottie-ui` loaders), `@platform/api-client` (`fetchJson`); use when adding new code — not a forced migration.
Legacy HTML → `archive/`	Done for admin-web `archive/legacy-html/` (see §10).
client-web deploy / OpenNext	ADR added — prego-web-app-deploy-convergence-adr; code migration remains Phase 4.
Deeper ERP screens	Deferred — continue per-screen PRs (checklist / leaves / expenses already exemplified).
Billing / Stripe (admin)	Deferred — high risk; needs dedicated E2E + product sign-off.
Public HTTP / OpenAPI	Unchanged — how-to-add-api order; no gateway edits.
Control Plane Hono	Out of scope — optional track (P6).

한국어 요약

이 페이지는 동작 보존 전제의 감사·리스크·연기 항목 기록입니다. admin-web 과 www 트라이얼 이메일 게이트는 @platform/web-auth-schemas 로 RHF + Zod 를 공유하고, 온보딩 회사/서브도메인 단계(CompanyInfoStep)는 companyInfoStepFormSchema 와 RHF + useFieldArray 로 동일 규칙을 적용합니다. client-web 은 가입·로그인(SignInForm)·비밀번호 찾기·이메일 인증·인보이스 수신 이메일 등 §3.4 에 적은 화면에서 RHF 와 공유 스키마를 맞추었고, www 는 트라이얼·수동 승인 workEmail 등과 동일 패키지를 씁니다. 레거시 정적 HTML 은 apps/admin-web/archive/legacy-html/ 로 옮겼고, lint·README가 그 경로를 가리킵니다. admin-web Playwright는 기본 workers: 1 (로컬 병렬은 PW_WORKERS). 세 앱 Next 16.0.11 정렬·배포 수렴 ADR 은 표준화 계획·continuation plan·Deploy ADR 을 따릅니다. middleware → proxy 경고는 client-web Edge 제약으로 연기(§1 표). Zuplo /auth/email/* (Auth OAS fragments) 동일 출처 BFF /api/auth/email/* 는 client-web·admin-web Route Handler에서 Zuplo로 보내기 전 authEmailSchema / authEmailVerifyOtpBodySchema 로 검증하고, ERP /auth/otp/* 와의 두 OTP 흐름은 에이전트 문서에 구분해 두었습니다. 루트 README.md·docs/README.md·docs/api-spec/README.md·저장소 README 색인 등 발견용 문서와 모노레포 AGENTS.md 의 pnpm run build:verify 단계는 10절 개정 표의 2026-04-15 행을 참고하세요. client-web Assistant UI /my-ai 페이지 오케스트레이션 (app/my-ai/page-controller 배럴, page-controller/*.test.ts Vitest)은 10절 2026-04-16 행을 참고하세요. 배럴 import 를 ESLint 로 제한 (eslint.config.mjs no-restricted-imports, 순환 의존 방지)하는 내용은 10절 2026-04-17 행을 참고하세요. Web app standard §3.4·continuation plan §1.1·apps/client-web/README.md (검증·Assistant UI)·리팩터링 프롬프트 (검증 표 하단 Assistant UI 문단, Prompt A app/my-ai/ 맥락·Example 4) 정합은 10절 2026-04-18 행을 참고하세요. 모노레포 루트 AGENTS.md client-web 줄의 Assistant UI 안내·8절 검증 체크리스트 app/my-ai/ 배럴 import 행은 10절 2026-04-19 행을 참고하세요. 위 /api/auth/email/* BFF 의 runtime = 'edge' (pnpm run pages:build) 는 10절 2026-04-20 행을 참고하세요. 내부 Starlight docs 에서 astro build 가 docs/dist 누락 청크로 실패할 때(예: renderers.mjs) 루트 pnpm run build:docs:clean 안내와 문서 정합은 10절 2026-05-09 행을 참고하세요.