@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.68

package/templates/apps/fullstack/packages/{{projectName}}-serv/src/server/runtime.ts.hbs

@@ -2,6 +2,9 @@ import type { CoreConfig, HaiResult } from '@h-ai/core'
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import process from 'node:process'
+{{#if features.ai}}
+import { ai, AIConfigSchema } from '@h-ai/ai'
+{{/if}}
 import { audit, AuditInitConfigSchema } from '@h-ai/audit'
 import { cache, CacheConfigSchema } from '@h-ai/cache'
 import { core } from '@h-ai/core'
@@ -11,13 +14,20 @@ import { reach, ReachConfigSchema } from '@h-ai/reach'
 import { reldb, ReldbConfigSchema } from '@h-ai/reldb'
 import { ServConfigSchema } from '@h-ai/serv'
 import { storage, StorageConfigSchema } from '@h-ai/storage'
+{{#if features.vecdb}}
+import { vecdb, VecdbConfigSchema } from '@h-ai/vecdb'
+{{/if}}
 import { serverM } from './messages.js'
 
 let initialized = false
 let initializing: Promise<void> | undefined
+let closing: Promise<void> | undefined
+let cleanupPending = false
 
 /** 初始化失败停止启动并反序释放资源；不把功能缺失降级为成功。 */
 export async function initializeModules(): Promise<void> {
+  if (closing)
+    await closing
   if (initialized)
     return
   initializing ??= runInitialization().finally(() => {
@@ -27,6 +37,9 @@ export async function initializeModules(): Promise<void> {
 }
 
 async function runInitialization(): Promise<void> {
+  if (cleanupPending)
+    await cleanupModules()
+  cleanupPending = true
   try {
     requireInitialized(core.config.validate('serv', ServConfigSchema), 'serv-config')
     const db = ReldbConfigSchema.parse(core.config.getOrThrow('db'))
@@ -38,6 +51,10 @@ async function runInitialization(): Promise<void> {
       await mkdir(path.dirname(db.database), { recursive: true })
     requireInitialized(await reldb.init(db), 'reldb')
     requireInitialized(await cache.init(cacheConfig), 'cache')
+{{#if features.vecdb}}
+    const vectorConfig = VecdbConfigSchema.parse(core.config.getOrThrow('vecdb'))
+    requireInitialized(await vecdb.init(vectorConfig), 'vecdb')
+{{/if}}
     requireInitialized(await crypto.init(), 'crypto')
     requireInitialized(await storage.init(storageConfig), 'storage')
     const reachConfig = core.config.get('reach')
@@ -45,13 +62,23 @@ async function runInitialization(): Promise<void> {
       requireInitialized(await reach.init(ReachConfigSchema.parse(reachConfig)), 'reach')
     requireInitialized(await iam.init({ ...iamConfig, reach }), 'iam')
     requireInitialized(await audit.init(auditConfig), 'audit')
+{{#if features.ai}}
+    const aiConfig = AIConfigSchema.parse(core.config.getOrThrow('ai'))
+    requireInitialized(await ai.init(aiConfig), 'ai')
+{{/if}}
     await ensureRolesAndAdmin()
     initialized = true
+    cleanupPending = false
     const app = core.config.getOrThrow<CoreConfig>('core')
     core.logger.info('Application initialized', { name: app.name, version: app.version, environment: app.env })
   }
   catch (error) {
-    await closeModules()
+    try {
+      await cleanupModules()
+    }
+    catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'Application startup and cleanup failed')
+    }
     throw error
   }
 }
@@ -91,12 +118,36 @@ async function ensureRolesAndAdmin(): Promise<void> {
 
 /** 关闭顺序与依赖初始化顺序相反，同时覆盖启动失败路径。 */
 export async function closeModules(): Promise<void> {
-  for (const [name, module] of [['audit', audit], ['iam', iam], ['reach', reach], ['storage', storage], ['crypto', crypto], ['cache', cache], ['reldb', reldb]] as const) {
-    if (!module.isInitialized)
-      continue
-    const result = await module.close()
-    if (result && !result.success)
-      core.logger.error('Failed to close application module', { module: name, error: result.error.code })
+  if (!closing) {
+    const pending = initializing
+    closing = (async () => {
+      if (pending)
+        await pending.catch(() => undefined)
+      await cleanupModules()
+    })().finally(() => {
+      closing = undefined
+    })
+  }
+  return closing
+}
+
+/** 不依赖 isInitialized 推断资源是否释放；关闭失败必须保留义务供重试。 */
+async function cleanupModules(): Promise<void> {
+  const failures: unknown[] = []
+  for (const [name, module] of [{{#if features.ai}}['ai', ai], {{/if}}['audit', audit], ['iam', iam], ['reach', reach], ['storage', storage], ['crypto', crypto], {{#if features.vecdb}}['vecdb', vecdb], {{/if}}['cache', cache], ['reldb', reldb]] as const) {
+    try {
+      const result = await module.close()
+      if (result && !result.success) {
+        core.logger.error('Failed to close application module', { module: name, error: result.error.code })
+        failures.push(result.error)
+      }
+    }
+    catch (error) {
+      failures.push(error)
+    }
   }
   initialized = false
+  cleanupPending = failures.length > 0
+  if (failures.length > 0)
+    throw new AggregateError(failures, 'Application cleanup failed; retry closeModules()')
 }

package/templates/apps/fullstack/packages/{{projectName}}-serv/tests/app-server.test.ts.hbs

@@ -46,6 +46,10 @@ beforeAll(async () => {
   vi.stubEnv('HAI_ADMIN_DEFAULT_PASSWORD', TEST_PASSWORD)
   core.init({ configDir: './config' })
   await initializeModules()
+  const key = crypto.asymmetric.generateKeyPair()
+  if (!key.success)
+    throw new Error(key.error.message)
+  vi.stubEnv('HAI_CRYPTO_TRANSPORT_SERVERKEYRING', JSON.stringify({ activeKeyId: 'test-v1', keys: { 'test-v1': key.data } }))
   app = createServerApp()
   transport = crypto.transport.createClient({
     keyExchangeUrl: `http://localhost${PREFIX}/_hai/key-exchange`,
@@ -339,7 +343,10 @@ describe('{{fullstack.servPackageName}} mini administration', () => {
   })
 
   it('rejects stale administrator snapshots and reports fresh user roles', async () => {
-    const stale = await iam.session.update(userToken, { roles: ['admin'], permissions: ['*'] })
+    const snapshot = await iam.session.get(userToken)
+    if (!snapshot.success || !snapshot.data)
+      throw new Error('Session unavailable')
+    const stale = await iam.session.update(userToken, { roles: ['admin'], permissions: ['*'] }, snapshot.data.version)
     expect(stale.success).toBe(true)
     for (const [route, input] of [['/admin/users/list', { page: 1, pageSize: 20 }], ['/admin/roles/list', undefined], ['/admin/audit/list', { page: 1, pageSize: 20 }]] as const) {
       const denied = await call(route, input, userToken)
@@ -354,8 +361,11 @@ describe('{{fullstack.servPackageName}} mini administration', () => {
   })
 
   it('returns a conflict when another administrator holds the mutation lock and resumes after release', async () => {
-    const locked = await cache.lock.acquire('hai:app:admin-mutation', { owner: 'test-owner', ttl: 10 })
+    const locked = await cache.lock.acquire('hai:app:admin-mutation', { ttl: 10 })
     expect(locked.success).toBe(true)
+    if (!locked.success || !locked.data)
+      throw new Error('Mutation lock unavailable')
+    const owner = locked.data
     try {
       const result = await call('/admin/users/update', { id: user.id, displayName: 'Locked' }, adminToken)
       expect(result.success).toBe(false)
@@ -363,7 +373,7 @@ describe('{{fullstack.servPackageName}} mini administration', () => {
         expect(result.error.httpStatus).toBe(409)
     }
     finally {
-      expect((await cache.lock.release('hai:app:admin-mutation', 'test-owner')).success).toBe(true)
+      expect((await cache.lock.release('hai:app:admin-mutation', owner)).success).toBe(true)
     }
     expect((await call('/admin/users/update', { id: user.id, displayName: 'Unlocked' }, adminToken)).success).toBe(true)
   })

package/templates/apps/fullstack/packages/{{projectName}}-shared/.gitignore.hbs

@@ -1,3 +1,10 @@
 node_modules
 .turbo
 src/lib/paraglide
+
+# 构建器生成的安装输入快照
+**/images/dependencies/
+
+# 项目本地缓存
+**/.pnpm-store/
+**/.cache/

package/templates/apps/fullstack/packages/{{projectName}}-shared/README.md.hbs

@@ -1,58 +1,84 @@
 # {{fullstack.sharedPackageName}}
 
+## Introduction
+
 Shared mini administration workspace for **{{projectName}}**. Web, Capacitor App and Tauri desktop use the same `AdminWorkspace`, responsive `AppShell`, typed API client and management store.
 
+## Core features
+
+- Shared management pages, forms, navigation and application state.
+- Typed encrypted API client and platform-specific token storage.
+- Themes, language preferences, onboarding and help.
+
+## Getting started
+
+### Behavior and configuration
+
 The behavior below describes the initial example. Roles, permissions, workflows, limits, preferences and audit policies can change with the user's requirements. Update conflicting implementation, tests and guidance together; preserve the applicable public API contracts and server security checks.
 
 - Administrators manage users, upload user avatars, assign the built-in administrator/user roles, edit role descriptions and query audit logs.
 - By default, ordinary users update their own profile, avatar, language, appearance and password. The server enforces the actual business permissions on every request.
+- The workspace uses the available window width. Tables scroll within their own area; settings panels form two columns on large screens and stack on phones.
 - `ManagementStore` owns API calls and business state; components render the state and forward user interactions.
 - Application name, version, environment and default locale come from the backend `app.info` contract, which reads `core` configuration. Do not duplicate these values in translations or frontend constants.
 - Requests, token refresh and JSON responses use the same `@h-ai/api-client` + `@h-ai/crypto` transport. Avatar uploads use encrypted JSON and validate PNG/JPEG/WebP content, with a 512 KiB limit.
 - Read metadata through the same initialized `managementApi.app.info()` client; inspect `success` before using `data`.
 
-All three Vite apps read the workspace root .env. Development and preview servers proxy /api to the local backend when no explicit API base is configured, so browser clients can use a single origin. In deployments, configure PUBLIC_API_BASE or the Web container runtime API origin for the actual service.
+Vite development and preview servers read the workspace root environment files and proxy /api to the backend. Builds do not load deployment environment files. Web containers receive their public API address at startup; native apps follow the platform configuration below.
 
 An origin-only API base uses `/api/v1`. For a custom service `http.apiPrefix`, include that path in `PUBLIC_API_BASE` or the runtime API base; the client preserves the configured path and restricts avatar URLs to its matching resource prefix.
 
-## Authentication and preferences
+### Authentication and preferences
 
 Web and browser previews keep access tokens in memory and refresh tokens in the server's httpOnly Cookie. Requests include credentials; reload restores the session through the encrypted refresh flow. Never store authentication tokens in localStorage.
 
-Capacitor native uses `createCapacitorTokenStorage()` and the trusted native token channel. Tauri native uses memory token storage and requires a new login after restarting the application. Native builds require a reachable `PUBLIC_API_BASE` in the workspace root `.env`; missing configuration produces a connection configuration error. Both send their frontend `clientName` and `X-HAI-Token-Transport: body`; the service verifies the allowed native origin before returning a refresh token in JSON.
+Capacitor native uses `createCapacitorTokenStorage()` and the trusted native token channel. Set its public API address in the App's `public/runtime-config.js` before compiling and syncing native assets. Tauri uses memory token storage and requires a new login after restart; set process `PUBLIC_API_BASE` before launching the installed application, and its Rust host injects the address. Both send `clientName` and `X-HAI-Token-Transport: body`; the service verifies the trusted native origin before returning a refresh token in JSON. Missing API configuration is an error, not a successful connection.
 
 Language and theme preferences are saved in IAM user metadata, restored after login and synchronized with the shared/host Paraglide runtimes and `core.i18n`. The small reactive theme store delegates DOM updates and safe appearance caching to `@h-ai/ui/theme` (`applyTheme` / `getSavedTheme`); the framework uses the `theme` localStorage key. Appearance selectors live in personal settings and save through the authenticated profile contract.
 
-## Onboarding and help
+### Onboarding and help
 
 AdminWorkspace mounts the shared `@h-ai/ui/guide` controller and GuideHost after authentication. AppShell includes a help button; first-use invitations offer start, later and dismiss. Web stores preferences in Cookies, while App/Desktop use localStorage, scoped by the current user and tour version. Help articles link to the overview and profile tours.
 
-Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
+Extend `src/lib/stores/guide-store.ts` and the shared Chinese/English/Japanese messages, then add stable data-guide attributes to existing components. Navigation uses the same ManagementStore. Keep business text as i18n callbacks and preserve the host's locale/scope binding. Browser tests cover completion, reload, replay, settings navigation and mobile help.
 
-## i18n and themes
+### i18n and themes
 
-Shared page copy belongs in `messages/{zh-CN,en-US}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
+Shared page copy belongs in `messages/{zh-CN,en-US,ja-JP}.json`. Frontend-specific copy belongs in each app's own messages directory. Keep `baseLocale` and `locales` aligned across all enabled projects, then run root `pnpm i18n:compile`; do not edit generated Paraglide files.
 
 All frontend and shared projects load the installed message-format plugin from the workspace root `node_modules`, matching the scaffold's hoisted dependency layout. Compilation uses the workspace dependency version and does not fetch a plugin from a CDN.
 
 The scaffold theme configuration determines the themes compiled into frontend CSS. Personal settings offer only those available themes. Customize the common layout in `src/lib/components/AppShell.svelte`, the management pages in adjacent components, and business behavior in `src/lib/stores/management-store.svelte.ts`.
 
-## Validation
+### Validation
 
 Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Shared API tests exercise real transport key exchange, encrypted request/response handling, configured core metadata and credential forwarding. Root browser tests cover administrator and ordinary-user workflows, avatar rendering, persisted preferences, password/session invalidation and narrow-screen layout. All selected Web/App/Desktop previews also exercise login, tours, help and profile navigation. Clean screenshots, reports, temporary projects, containers and helper processes in finally/teardown, including failure paths. These browser checks do not replace native-shell or miniapp device acceptance.
 
-## IAM configuration
+### IAM configuration
 
-The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. All service nodes must share the same database and Redis; memory cache is for a single process.
+The service's `config/_iam.yml` controls login methods, registration, password reset, agreements and `ui` branding. Email and SMS use providers/templates in `_reach.yml` or custom callbacks. `AuthPanel` uses the public configuration and framework auth actions to manage tokens, resend countdowns and errors. A single process can use memory cache. Multiple instances need shared database/cache, write routing and a shared managed transport key ring and registry as described in the project README.
 
 Authentication defaults to a split layout. Set `ui.variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `logoUrl` and `illustrationUrl` to customize login and registration. Without a `brandTitle`, the displayed application name comes from `app.info` and follows `core` configuration.
 
-LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
+LDAP and Reach are optional. Install ldapts in the IAM service workspace only when using its default LDAP client, then enable login.ldap and set connection settings. Custom onOtpSendEmail/onOtpSendSms/onPasswordResetRequest callbacks work without Reach and must reject on delivery failure. Their third context argument supplies expiresAt/idempotencyKey; senders durably deduplicate that key, and errors/timeouts mean unknown delivery with no automatic resend. Agreements open in a Modal. LoginForm/RegisterForm support header/extraFields/footer snippets; AuthPanel forwards loginHeader/loginFields/loginFooter and registerHeader/registerFields/registerFooter. See the generated hai-iam/hai-ui skills for configuration and examples.
 
-协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+Agreements accept Markdown text or a URL. Markdown takes precedence and opens in a safely rendered dialog.
 
 See `.agents/skills/hai-iam/reference.md` in the generated application for the complete contract.
 
-## Form layouts
+### Form layouts
+
+The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings fill the available width and use two columns on wide screens, with stacked labels and a single avatar editor. Narrow containers automatically stack cards, fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.
+
+## Development and testing
+
+Run root `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm test` and `pnpm test:e2e`. Browser checks cover shared workflows; test native shells on their target platforms separately.
+
+## 界面设计与验收
+
+共享管理界面的 Web/App/Desktop 使用同一套 UI 组件和状态。设计、实现、审查分别参考根目录 `.agents/skills/hai-ui-design/`、`hai-ui/`、`hai-ui-review/`；正常、加载、空态、错误恢复、键盘、语言/主题和窄容器均按实际场景验收。组件的筛选、排序和分页仍由业务数据回调接入。
+
+
+## License
 
-The user editor uses `FormLayout columns={2} labelPosition="left"`. Personal settings use a bounded page width, stacked labels and a single avatar editor. Narrow containers automatically stack fields and labels. UI controls and CRUD forms show client validation on blur, update errors while correcting input and validate untouched fields on submit. Field errors follow the current UI language. The management store syncs locale through the lightweight `@h-ai/ui/i18n` entry, without loading components or tour CSS. Configure `colSpan` on FormField to override automatic spans for textareas, uploads and multiple choices.
+Apache-2.0

package/templates/apps/fullstack/packages/{{projectName}}-shared/messages/ja-JP.json.hbs

@@ -0,0 +1,105 @@
+{{! @skipIfEmpty }}
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "settings_title": "個人設定",
+  "settings_language": "言語",
+  "settings_theme": "テーマ",
+  "home_refresh": "更新",
+  "home_loading": "読み込み中…",
+  "home_error": "APIサービスに接続できません",
+  "nav_users": "ユーザー",
+  "nav_roles": "ロール",
+  "nav_audit": "監査ログ",
+  "navigation": "メインナビゲーション",
+  "open_menu": "ナビゲーションを開く",
+  "close_menu": "ナビゲーションを閉じる",
+  "logout": "ログアウト",
+  "login_title": "ログイン",
+  "login_description": "ログインしてアカウントとワークスペースを管理します",
+  "login_invalid": "アカウントまたはパスワードが正しくありません。再試行してください。",
+  "session_expired": "セッションの有効期限が切れています。再度ログインしてください。",
+  "saved": "変更を保存しました",
+  "save": "保存",
+  "edit": "編集",
+  "delete": "削除",
+  "cancel": "キャンセル",
+  "search": "検索",
+  "details": "詳細",
+  "created_at": "作成日時",
+  "enabled": "有効",
+  "disabled": "無効",
+  "all_statuses": "すべての状態",
+  "operation_failed": "操作を完了できませんでした。再試行してください。",
+  "network_error": "接続に失敗しました。ネットワークを確認して再試行してください。",
+  "forbidden": "この操作を行う権限がありません。",
+  "conflict": "このアカウントは既に存在するか、変更が現在のデータと競合しています。",
+  "validation_failed": "入力内容を確認して再試行してください。",
+  "settings_description": "プロフィール、環境設定、アカウントのセキュリティを管理します",
+  "profile_title": "プロフィール",
+  "preferences_title": "環境設定",
+  "preferences_description": "言語と外観の設定は、端末にかかわらずアカウントに適用されます。",
+  "password_title": "パスワードを変更",
+  "password_rules": "現在と異なるパスワードを選んでください。",
+  "password_changed": "パスワードを更新しました。新しいパスワードでログインしてください。",
+  "avatar_hint": "PNG、JPEG、WebPの画像をアップロードしてください。最大512KBです。",
+  "avatar_invalid": "512KB以下のPNG、JPEG、WebP画像を選択してください。",
+  "avatar_saved": "アバターを更新しました",
+  "avatar_upload": "アバターをアップロード",
+  "users_description": "アカウントの作成、ロールの割り当て、アクセスを管理します",
+  "users_search": "ユーザー名、名前、メールアドレスを検索",
+  "user_account": "アカウント",
+  "user_username": "ユーザー名",
+  "user_display_name": "表示名",
+  "user_email": "メールアドレス",
+  "user_password": "初期パスワード",
+  "user_role": "ロール",
+  "user_status": "状態",
+  "user_create": "ユーザーを追加",
+  "initial_password_rules": "{min}文字以上で入力してください。",
+  "account_enabled": "ログインを許可",
+  "users_empty": "一致するアカウントがありません。検索条件を変更するか、ユーザーを作成してください。",
+  "user_edit": "ユーザーを編集",
+  "user_deleted": "ユーザーを削除しました",
+  "user_delete_title": "ユーザーを削除",
+  "user_delete_confirm": "{name}を削除しますか？アカウントとアクセス権は完全に削除されます。",
+  "roles_description": "2つのロールでアクセスを管理します。ロールはユーザー管理から割り当ててください。",
+  "role_admin": "管理者",
+  "role_user": "ユーザー",
+  "role_admin_capabilities": "ユーザー、ロールの説明、監査ログを管理し、個人設定を更新できます。",
+  "role_user_capabilities": "プロフィール、アバター、言語、外観、パスワードを更新できます。",
+  "role_members": "メンバー{count}人",
+  "role_edit": "説明を編集",
+  "role_description": "説明",
+  "audit_description": "アカウントと管理操作の履歴を確認します",
+  "audit_actor": "実行者",
+  "audit_action": "操作",
+  "audit_resource": "リソース",
+  "audit_resource_id": "リソースID",
+  "audit_ip": "IPアドレス",
+  "audit_start": "開始",
+  "audit_end": "終了",
+  "audit_action_placeholder": "すべての操作",
+  "audit_resource_placeholder": "すべてのリソース",
+  "audit_system": "システム",
+  "audit_details": "監査ログの詳細",
+  "audit_date_invalid": "終了日は開始日以降にしてください。",
+  "api_not_configured": "サービスへの接続が設定されていません。管理者にお問い合わせください。",
+  "guide_overview_title": "管理ワークスペースを見てみましょう",
+  "guide_overview_description": "簡単な手順でワークスペース、個人設定、ヘルプを紹介します。いつでも終了でき、ヘルプセンターから再開できます。",
+  "guide_content_title": "ワークスペース",
+  "guide_content_description": "現在のページがここに表示されます。ナビゲーションで機能を切り替えます。利用できる操作は権限に応じて変わります。",
+  "guide_theme_title": "外観",
+  "guide_theme_description": "ライトとダークの表示を切り替えます。設定でさらに多くのテーマを選択できます。",
+  "guide_profile_title": "プロフィール",
+  "guide_profile_description": "アバターからプロフィールや設定を開き、個人情報やパスワードを管理できます。",
+  "guide_help_title": "ヘルプセンター",
+  "guide_help_description": "困ったときは、ここで説明を検索したり、製品ツアーを再生したりできます。",
+  "guide_profile_tour_title": "プロフィールを設定",
+  "guide_profile_tour_description": "個人情報、環境設定、パスワード設定の場所を紹介します。ツアーでは変更を送信しません。",
+  "guide_profile_form_description": "プロフィールの表示や編集、アバターの選択、変更の保存ができます。アップロードするファイルは、画面に表示された形式とサイズの条件を満たす必要があります。",
+  "guide_preferences_description": "言語とテーマの設定を保存します。画面とヘルプの言語は選択に従います。",
+  "guide_password_title": "パスワードを変更",
+  "guide_password_description": "現在のパスワード、新しいパスワード、確認用パスワードを入力します。送信前にパスワードのルールを確認してください。",
+  "guide_overview_article": "## はじめに\n\n- ナビゲーションから各機能を開きます。メニューと操作は現在の権限に応じて変わります。\n- ワークスペースには一覧、詳細、設定が表示されます。画面の説明に従い、送信前に入力内容を確認してください。\n- アバターからプロフィールと設定を開きます。\n- ヘルプボタンで説明を検索したり、ツアーを再生したりできます。\n\n## 初回ツアー\n\n「後で通知」を選ぶと1日間通知を停止します。「今後通知しない」は設定を保存します。完了したツアーは自動で表示されなくなりますが、手動で再生できます。",
+  "guide_profile_article": "## プロフィールと環境設定\n\nプロフィールを開くと個人情報やアバターを確認・更新できます。ファイルの条件を確認し、変更を保存して結果のメッセージを確認してください。外観と言語は設定で変更できます。\n\n## パスワード\n\nパスワードの変更には、現在のパスワード、新しいパスワード、確認用パスワードが必要です。画面のルールに従い、送信後に結果を確認してください。\n\n「ツアーを開始」で関連するページを開きます。ツアーが自動でフォームを保存したり、アカウントを変更したりすることはありません。"
+}

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AdminWorkspace.svelte.hbs

@@ -59,7 +59,7 @@
 
 {#key store.locale}
   {#if store.initializing}
-    <div class='grid min-h-dvh place-items-center bg-base-200/50'><div class='w-72 space-y-4'><Skeleton variant='title' /><Skeleton count={3} /><p class='text-center text-sm text-base-content/50'>{m.home_loading()}</p></div></div>
+    <div role='status' aria-live='polite' class='grid min-h-dvh place-items-center bg-base-200/50'><div class='w-72 space-y-4'><Skeleton variant='title' /><Skeleton count={3} /><p class='text-center text-sm text-base-content/50'>{m.home_loading()}</p></div></div>
   {:else if !store.user || resetToken}
     <header class='border-b border-base-content/8 bg-base-100 px-6 py-3 text-sm font-medium'>{store.info?.name}</header>
     <main data-testid='login-page'>
@@ -78,11 +78,11 @@
     </main>
   {:else}
     <AppShell {platform} {store} onhelp={() => guide.openHelp()}>
-      <div class='space-y-5'>
+      <div class='flex min-h-0 flex-1 flex-col gap-5'>
         {#if store.error}<Alert variant='error' data-testid='error'>{store.error}</Alert>{/if}
         {#if store.notice}<Alert variant='success' data-testid='notice'>{store.notice}</Alert>{/if}
         {#await pageComponent}
-          <div class='space-y-4'><Skeleton variant='title' /><Skeleton count={3} /></div>
+          <div role='status' aria-label={m.home_loading()} class='space-y-4'><Skeleton variant='title' /><Skeleton count={3} /></div>
         {:then { default: Page }}
           <Page {store} />
         {/await}

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/components/AppShell.svelte.hbs

@@ -30,11 +30,11 @@
   }
 </script>
 
-<div class="flex min-h-dvh bg-base-200/50 text-base-content" class:hai-safe-area={platform === 'app'}>
+<div class="flex h-dvh overflow-hidden bg-base-200/50 text-base-content" class:hai-safe-area={platform === 'app'}>
   {#if menuOpen}
     <BareButton class="fixed inset-0 z-30 bg-black/30 lg:hidden" ariaLabel={m.close_menu()} onclick={() => { menuOpen = false }} />
   {/if}
-  <aside class="fixed inset-y-0 left-0 z-40 flex w-60 flex-col border-r border-base-content/8 bg-base-100 transition-transform duration-200 lg:sticky lg:top-0 lg:h-dvh lg:translate-x-0 {menuOpen ? 'translate-x-0' : '-translate-x-full'}">
+  <aside class="fixed inset-y-0 left-0 z-40 flex w-60 shrink-0 flex-col border-r border-base-content/8 bg-base-100 transition-transform duration-200 lg:sticky lg:top-0 lg:h-dvh lg:translate-x-0 {menuOpen ? 'translate-x-0' : '-translate-x-full'}">
     <div class="flex h-16 items-center gap-3 border-b border-base-content/8 px-5">
       <span class="grid size-8 shrink-0 place-items-center rounded-lg bg-primary text-primary-content"><span class="icon-[tabler--hexagon-letter-h] size-5"></span></span>
       <span class="truncate text-sm font-semibold" data-testid="app-name">{store.info?.name}</span>
@@ -48,8 +48,8 @@
     </nav>
     <div class="border-t border-base-content/8 p-4 text-xs text-base-content/40"><span data-testid="app-version">v{store.info?.version}</span></div>
   </aside>
-  <div class="flex min-w-0 flex-1 flex-col">
-    <header class="sticky top-0 z-20 flex h-16 items-center justify-between gap-2 border-b border-base-content/8 bg-base-100/95 px-3 backdrop-blur sm:px-4 lg:px-6">
+  <div class="flex min-h-0 min-w-0 flex-1 flex-col">
+    <header class="sticky top-0 z-20 flex h-16 shrink-0 items-center justify-between gap-2 border-b border-base-content/8 bg-base-100/95 px-3 backdrop-blur sm:px-4 lg:px-6">
       <div class="flex min-w-0 flex-1 items-center gap-2 sm:gap-3">
         <BareButton class="rounded-lg p-2 hover:bg-base-content/5 lg:hidden" ariaLabel={m.open_menu()} onclick={() => { menuOpen = !menuOpen }} data-testid="mobile-menu"><span class="icon-[tabler--menu-2] size-5"></span></BareButton>
         <span class="truncate text-sm font-medium">{title}</span>
@@ -66,7 +66,7 @@
         <Button variant="ghost" size="sm" loading={store.saving} onclick={() => void store.logout()} data-testid="logout">{m.logout()}</Button>
       </div>
     </header>
-    <main class="mx-auto w-full max-w-7xl flex-1 p-4 pb-8 sm:p-6 lg:p-8" data-guide="admin-content">{@render children()}</main>
-    <footer class="border-t border-base-content/8 px-6 py-3 text-center text-xs text-base-content/35">{store.info?.name} · v{store.info?.version}</footer>
+    <main class="flex min-h-0 w-full min-w-0 flex-1 flex-col overflow-auto p-4 pb-8 sm:p-6 lg:p-8" data-guide="admin-content">{@render children()}</main>
+    <footer class="shrink-0 border-t border-base-content/8 px-6 py-3 text-center text-xs text-base-content/35">{store.info?.name} · v{store.info?.version}</footer>
   </div>
 </div>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/audit.svelte.hbs

@@ -17,10 +17,10 @@
   ])
 </script>
 
-<section class="space-y-5" data-testid="audit-page">
-  <div><h1 class="text-xl font-semibold tracking-tight">{m.nav_audit()}</h1><p class="mt-1 text-sm text-base-content/50">{m.audit_description()}</p></div>
-  <div class="rounded-xl border border-base-content/8 bg-base-100">
-    <form class="grid items-end gap-3 border-b border-base-content/8 p-4 sm:grid-cols-2 xl:grid-cols-[repeat(4,minmax(0,1fr))_auto] [&_.fieldset]:p-0" onsubmit={(event) => {
+<section class="flex min-h-0 flex-1 flex-col gap-5" data-testid="audit-page">
+  <div class="shrink-0"><h1 class="text-xl font-semibold tracking-tight">{m.nav_audit()}</h1><p class="mt-1 text-sm text-base-content/50">{m.audit_description()}</p></div>
+  <div class="flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-base-content/8 bg-base-100">
+    <form class="grid shrink-0 items-end gap-3 border-b border-base-content/8 p-4 sm:grid-cols-2 xl:grid-cols-[repeat(4,minmax(0,1fr))_auto] [&_.fieldset]:p-0" onsubmit={(event) => {
       event.preventDefault()
       void store.loadAudit()
     }}>
@@ -30,8 +30,8 @@
       <div class="min-w-0 space-y-1"><label class="block text-xs text-base-content/60" for="audit-end">{m.audit_end()}</label><input id="audit-end" type="date" class="input block h-10 min-w-0 w-full" bind:value={store.auditEndDate} /></div>
       <Button type="submit" variant="outline" disabled={store.loading} class="h-10 w-full">{m.search()}</Button>
     </form>
-    <div class="overflow-x-auto">
-      <DataTable data={store.audit} {columns} keyField="id" loading={store.loading} striped={false}>
+    <div class="flex min-h-0 flex-1 flex-col overflow-auto">
+      <DataTable data={store.audit} {columns} keyField="id" loading={store.loading} striped={false} class="min-h-0 flex-1 overflow-auto">
         {#snippet cell(entry, key)}
           {#if key === 'createdAt'}<span class="whitespace-nowrap text-xs">{store.formatDate(entry.createdAt)}</span>
           {:else if key === 'username'}{entry.username || m.audit_system()}
@@ -42,7 +42,7 @@
         {#snippet actions(entry)}<Button size="xs" variant="ghost" onclick={() => { selected = entry }}>{m.details()}</Button>{/snippet}
       </DataTable>
     </div>
-    <div class="border-t border-base-content/8 p-4"><Pagination page={store.auditPage} total={store.auditTotal} pageSize={store.pageSize} onchange={page => void store.loadAudit(page)} /></div>
+    <div class="mt-auto shrink-0 border-t border-base-content/8 p-4"><Pagination page={store.auditPage} total={store.auditTotal} pageSize={store.pageSize} onchange={page => void store.loadAudit(page)} /></div>
   </div>
 </section>
 

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/settings.svelte.hbs

@@ -10,17 +10,17 @@
 
   interface Props { store: ManagementStore }
   const { store }: Props = $props()
-  const languageOptions = $derived(locales.filter(locale => store.info?.supportedLocales.includes(locale)).map(locale => ({ value: locale, label: locale === 'zh-CN' ? '简体中文' : 'English' })))
+  const languageOptions = $derived(locales.filter(locale => store.info?.supportedLocales.includes(locale)).map(locale => ({ value: locale, label: locale === 'zh-CN' ? '简体中文' : locale === 'ja-JP' ? '日本語' : 'English' })))
   const themeOptions = AVAILABLE_THEMES.map(theme => ({ value: theme, label: getThemeInfo(theme)?.name ?? theme }))
 </script>
 
-<section class='mx-auto w-full max-w-4xl space-y-6' data-testid='settings-page'>
-  <div>
+<section class='grid w-full min-w-0 gap-6 xl:grid-cols-2' data-testid='settings-page'>
+  <div class='xl:col-span-2'>
     <h1 class='text-xl font-semibold tracking-tight'>{m.settings_title()}</h1>
     <p class='mt-1 text-sm text-base-content/50'>{m.settings_description()}</p>
   </div>
   {#if store.user}
-    <Card title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
+    <Card class='xl:row-span-2' title={m.profile_title()} bordered shadow={false} data-guide='admin-profile-form'>
       <div class='mb-5 flex flex-wrap items-center gap-3 border-b border-base-content/8 pb-4'>
         <p class='min-w-0 break-all text-sm text-base-content/55'>@{store.user.username}</p>
         <Badge size='sm' variant='ghost'>{store.isAdmin ? m.role_admin() : m.role_user()}</Badge>

package/templates/apps/fullstack/packages/{{projectName}}-shared/src/lib/pages/users.svelte.hbs

@@ -63,16 +63,16 @@
   }
 </script>
 
-<section class="space-y-5" data-testid="users-page">
-  <div class="flex flex-wrap items-center justify-between gap-3">
+<section class="flex min-h-0 flex-1 flex-col gap-5" data-testid="users-page">
+  <div class="flex shrink-0 flex-wrap items-center justify-between gap-3">
     <div>
       <h1 class="text-xl font-semibold tracking-tight">{m.nav_users()}</h1>
       <p class="mt-1 text-sm text-base-content/50">{m.users_description()}</p>
     </div>
     <Button variant="primary" onclick={() => openEditor(null)} data-testid="create-user">{m.user_create()}</Button>
   </div>
-  <div class="rounded-xl border border-base-content/8 bg-base-100">
-    <form class="flex flex-wrap items-center gap-3 border-b border-base-content/8 p-4" onsubmit={(event) => {
+  <div class="flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-base-content/8 bg-base-100">
+    <form class="flex shrink-0 flex-wrap items-center gap-3 border-b border-base-content/8 p-4" onsubmit={(event) => {
       event.preventDefault()
       void store.loadUsers()
     }}>
@@ -82,8 +82,8 @@
       <div class="w-40"><Select bind:value={store.usersStatus} options={statusOptions} /></div>
       <Button type="submit" variant="outline" disabled={store.loading}>{m.search()}</Button>
     </form>
-    <div class="hidden overflow-x-auto md:block">
-      <DataTable data={store.users} {columns} keyField="id" loading={store.loading} striped={false}>
+    <div class="hidden min-h-0 flex-1 overflow-auto md:flex md:flex-col">
+      <DataTable data={store.users} {columns} keyField="id" loading={store.loading} striped={false} class="min-h-0 flex-1 overflow-auto">
         {#snippet cell(user, key)}
           {#if key === 'username'}
             <div class="flex items-center gap-3">
@@ -105,7 +105,7 @@
         {/snippet}
       </DataTable>
     </div>
-    <div class="space-y-3 p-4 md:hidden" data-testid="user-cards">
+    <div class="min-h-0 flex-1 space-y-3 overflow-auto p-4 md:hidden" data-testid="user-cards">
       {#if store.loading}
         <Skeleton count={3} />
       {:else if store.users.length === 0}
@@ -127,7 +127,7 @@
         {/each}
       {/if}
     </div>
-    <div class="border-t border-base-content/8 p-4">
+    <div class="mt-auto shrink-0 border-t border-base-content/8 p-4">
       <Pagination page={store.usersPage} total={store.usersTotal} pageSize={store.pageSize} onchange={page => void store.loadUsers(page)} />
     </div>
   </div>