@h-ai/cli 0.1.0-alpha.59 → 0.1.0-alpha.61

package/templates/features/iam/routes-admin/(auth)/auth/register/+page.svelte.hbs

@@ -1,122 +1,11 @@
-{{!-- Admin 注册页面 --}}
 <script lang='ts'>
-  /**
-   * 注册页面
-   */
+  import { goto } from '$app/navigation'
   import { resolve } from '$app/paths'
-{{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
-{{/if}}
-  import { Alert, Button, FormField, Input } from '@h-ai/ui'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
 
-  let username = $state('')
-  let email = $state('')
-  let password = $state('')
-  let confirmPassword = $state('')
-  let error = $state('')
-  let loading = $state(false)
-
-  async function handleRegister(event: SubmitEvent) {
-    event.preventDefault()
-    error = ''
-    if (password !== confirmPassword) {
-{{#if hasI18n}}
-      error = m.auth_error_password_mismatch()
-{{else}}
-      error = '密码不一致'
-{{/if}}
-      return
-    }
-    loading = true
-    try {
-      const res = await fetch('/api/auth/register', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ username, email, password, confirmPassword }),
-      })
-      const data = await res.json()
-      if (data.success) {
-        window.location.href = '/auth/login'
-      }
-      else {
-{{#if hasI18n}}
-        error = data.error?.message || m.auth_register_failed()
-{{else}}
-        error = data.error?.message || '注册失败'
-{{/if}}
-      }
-    }
-    catch {
-{{#if hasI18n}}
-      error = m.auth_error_network()
-{{else}}
-      error = '网络错误'
-{{/if}}
-    }
-    finally {
-      loading = false
-    }
-  }
+  const actions = kit.client.createAuthActions()
 </script>
 
-<svelte:head>
-{{#if hasI18n}}
-  <title>{m.auth_register_title()}</title>
-{{else}}
-  <title>注册</title>
-{{/if}}
-</svelte:head>
-
-{{#if hasI18n}}
-<h2 class='text-2xl font-bold text-center mb-6'>{m.auth_register_title()}</h2>
-{{else}}
-<h2 class='text-2xl font-bold text-center mb-6'>注册</h2>
-{{/if}}
-
-{#if error}
-  <Alert variant='error' class='mb-4'>{error}</Alert>
-{/if}
-
-<form onsubmit={handleRegister} class='space-y-4'>
-{{#if hasI18n}}
-  <FormField label={m.auth_label_username()} required>
-    <Input id='username' type='text' bind:value={username} required />
-  </FormField>
-  <FormField label={m.auth_label_email()} required>
-    <Input id='email' type='email' bind:value={email} required />
-  </FormField>
-  <FormField label={m.auth_label_password()} required>
-    <Input id='password' type='password' bind:value={password} required />
-  </FormField>
-  <FormField label={m.auth_label_confirm_password()} required>
-    <Input id='confirmPassword' type='password' bind:value={confirmPassword} required />
-  </FormField>
-  <Button type='submit' variant='primary' loading={loading} class='w-full'>
-    {loading ? m.auth_register_loading() : m.auth_register_submit()}
-  </Button>
-{{else}}
-  <FormField label='用户名' required>
-    <Input id='username' type='text' bind:value={username} required />
-  </FormField>
-  <FormField label='邮箱' required>
-    <Input id='email' type='email' bind:value={email} required />
-  </FormField>
-  <FormField label='密码' required>
-    <Input id='password' type='password' bind:value={password} required />
-  </FormField>
-  <FormField label='确认密码' required>
-    <Input id='confirmPassword' type='password' bind:value={confirmPassword} required />
-  </FormField>
-  <Button type='submit' variant='primary' loading={loading} class='w-full'>
-    {loading ? '注册中...' : '注册'}
-  </Button>
-{{/if}}
-</form>
-
-<div class='text-center mt-4'>
-{{#if hasI18n}}
-  <a href={resolve('/auth/login', {})} class='link link-primary text-sm'>{m.auth_register_to_login()}</a>
-{{else}}
-  <a href={resolve('/auth/login', {})} class='link link-primary text-sm'>已有账号？立即登录</a>
-{{/if}}
-</div>
+<AuthPanel config={page.data.iamPublicConfig} {actions} initialMode='register' loginUrl={resolve('/auth/login', {})} registerUrl={resolve('/auth/register', {})} onauthenticated={() => goto(resolve('/admin', {}))} />

package/templates/features/iam/routes-admin/(auth)/auth/reset-password/+page.svelte.hbs

@@ -0,0 +1,10 @@
+<script lang='ts'>
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const actions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} {actions} initialMode='reset' resetToken={page.url.searchParams.get('token') ?? ''} loginUrl={resolve('/auth/login', {})} />

package/templates/features/iam/routes-h5/auth/forgot-password/+page.svelte.hbs

@@ -0,0 +1,10 @@
+<script lang='ts'>
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const actions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} {actions} initialMode='forgot' resetToken={page.url.searchParams.get('token') ?? ''} loginUrl={resolve('/auth/login', {})} />

package/templates/features/iam/routes-h5/auth/login/+page.svelte.hbs

@@ -1,102 +1,11 @@
-{{!-- H5 登录页面 --}}
 <script lang='ts'>
-  /**
-   * H5 登录页面
-   */
+  import { goto } from '$app/navigation'
   import { resolve } from '$app/paths'
-{{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
-{{/if}}
-  import { Alert, Button, FormField, Input } from '@h-ai/ui'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
 
-  let username = $state('')
-  let password = $state('')
-  let error = $state('')
-  let loading = $state(false)
-
-  async function handleLogin(event: SubmitEvent) {
-    event.preventDefault()
-    error = ''
-    loading = true
-    try {
-      const res = await fetch('/api/auth/login', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ identifier: username, password }),
-      })
-      const data = await res.json()
-      if (data.success) {
-        window.location.href = '/'
-      }
-      else {
-{{#if hasI18n}}
-        error = data.error?.message || m.auth_login_failed()
-{{else}}
-        error = data.error?.message || '登录失败'
-{{/if}}
-      }
-    }
-    catch {
-{{#if hasI18n}}
-      error = m.auth_error_network()
-{{else}}
-      error = '网络错误'
-{{/if}}
-    }
-    finally {
-      loading = false
-    }
-  }
+  const authActions = kit.client.createAuthActions()
 </script>
 
-<svelte:head>
-{{#if hasI18n}}
-  <title>{m.auth_login_title()}</title>
-{{else}}
-  <title>登录</title>
-{{/if}}
-</svelte:head>
-
-<div class='p-4 pt-12 space-y-4'>
-{{#if hasI18n}}
-  <h1 class='text-2xl font-black tracking-tight text-center'>{m.auth_login_title()}</h1>
-{{else}}
-  <h1 class='text-2xl font-black tracking-tight text-center'>登录</h1>
-{{/if}}
-
-  {#if error}
-    <Alert variant='error'>{error}</Alert>
-  {/if}
-
-  <form onsubmit={handleLogin} class='space-y-4'>
-{{#if hasI18n}}
-    <FormField label={m.auth_label_username()} required>
-      <Input id='username' type='text' bind:value={username} required />
-    </FormField>
-    <FormField label={m.auth_label_password()} required>
-      <Input id='password' type='password' bind:value={password} required />
-    </FormField>
-    <Button type='submit' variant='primary' loading={loading} class='w-full'>
-      {loading ? m.auth_login_loading() : m.auth_login_submit()}
-    </Button>
-{{else}}
-    <FormField label='用户名' required>
-      <Input id='username' type='text' bind:value={username} required />
-    </FormField>
-    <FormField label='密码' required>
-      <Input id='password' type='password' bind:value={password} required />
-    </FormField>
-    <Button type='submit' variant='primary' loading={loading} class='w-full'>
-      {loading ? '登录中...' : '登录'}
-    </Button>
-{{/if}}
-  </form>
-
-  <div class='text-center'>
-{{#if hasI18n}}
-    <a href={resolve('/auth/register', {})} class='link link-primary text-sm'>{m.auth_login_to_register()}</a>
-{{else}}
-    <a href={resolve('/auth/register', {})} class='link link-primary text-sm'>没有账号？立即注册</a>
-{{/if}}
-  </div>
-</div>
+<AuthPanel config={page.data.iamPublicConfig} actions={authActions} initialMode='login' loginUrl={resolve('/auth/login', {})} registerUrl={resolve('/auth/register', {})} onauthenticated={() => goto(resolve('/', {}))} />

package/templates/features/iam/routes-h5/auth/register/+page.svelte.hbs

@@ -1,117 +1,11 @@
-{{!-- H5 注册页面 --}}
 <script lang='ts'>
-  /**
-   * H5 注册页面
-   */
+  import { goto } from '$app/navigation'
   import { resolve } from '$app/paths'
-{{#if hasI18n}}
-  import * as m from '$lib/paraglide/messages'
-{{/if}}
-  import { Alert, Button, FormField, Input } from '@h-ai/ui'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
 
-  let username = $state('')
-  let password = $state('')
-  let confirmPassword = $state('')
-  let error = $state('')
-  let loading = $state(false)
-
-  async function handleRegister(event: SubmitEvent) {
-    event.preventDefault()
-    error = ''
-    if (password !== confirmPassword) {
-{{#if hasI18n}}
-      error = m.auth_error_password_mismatch()
-{{else}}
-      error = '密码不一致'
-{{/if}}
-      return
-    }
-    loading = true
-    try {
-      const res = await fetch('/api/auth/register', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ username, password, confirmPassword }),
-      })
-      const data = await res.json()
-      if (data.success) {
-        window.location.href = '/auth/login'
-      }
-      else {
-{{#if hasI18n}}
-        error = data.error?.message || m.auth_register_failed()
-{{else}}
-        error = data.error?.message || '注册失败'
-{{/if}}
-      }
-    }
-    catch {
-{{#if hasI18n}}
-      error = m.auth_error_network()
-{{else}}
-      error = '网络错误'
-{{/if}}
-    }
-    finally {
-      loading = false
-    }
-  }
+  const authActions = kit.client.createAuthActions()
 </script>
 
-<svelte:head>
-{{#if hasI18n}}
-  <title>{m.auth_register_title()}</title>
-{{else}}
-  <title>注册</title>
-{{/if}}
-</svelte:head>
-
-<div class='p-4 pt-12 space-y-4'>
-{{#if hasI18n}}
-  <h1 class='text-2xl font-black tracking-tight text-center'>{m.auth_register_title()}</h1>
-{{else}}
-  <h1 class='text-2xl font-black tracking-tight text-center'>注册</h1>
-{{/if}}
-
-  {#if error}
-    <Alert variant='error'>{error}</Alert>
-  {/if}
-
-  <form onsubmit={handleRegister} class='space-y-4'>
-{{#if hasI18n}}
-    <FormField label={m.auth_label_username()} required>
-      <Input id='username' type='text' bind:value={username} required />
-    </FormField>
-    <FormField label={m.auth_label_password()} required>
-      <Input id='password' type='password' bind:value={password} required />
-    </FormField>
-    <FormField label={m.auth_label_confirm_password()} required>
-      <Input id='confirmPassword' type='password' bind:value={confirmPassword} required />
-    </FormField>
-    <Button type='submit' variant='primary' loading={loading} class='w-full'>
-      {loading ? m.auth_register_loading() : m.auth_register_submit()}
-    </Button>
-{{else}}
-    <FormField label='用户名' required>
-      <Input id='username' type='text' bind:value={username} required />
-    </FormField>
-    <FormField label='密码' required>
-      <Input id='password' type='password' bind:value={password} required />
-    </FormField>
-    <FormField label='确认密码' required>
-      <Input id='confirmPassword' type='password' bind:value={confirmPassword} required />
-    </FormField>
-    <Button type='submit' variant='primary' loading={loading} class='w-full'>
-      {loading ? '注册中...' : '注册'}
-    </Button>
-{{/if}}
-  </form>
-
-  <div class='text-center'>
-{{#if hasI18n}}
-    <a href={resolve('/auth/login', {})} class='link link-primary text-sm'>{m.auth_register_to_login()}</a>
-{{else}}
-    <a href={resolve('/auth/login', {})} class='link link-primary text-sm'>已有账号？立即登录</a>
-{{/if}}
-  </div>
-</div>
+<AuthPanel config={page.data.iamPublicConfig} actions={authActions} initialMode='register' loginUrl={resolve('/auth/login', {})} registerUrl={resolve('/auth/register', {})} onauthenticated={() => goto(resolve('/', {}))} />

package/templates/features/iam/routes-h5/auth/reset-password/+page.svelte.hbs

@@ -0,0 +1,10 @@
+<script lang='ts'>
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const actions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} {actions} initialMode='reset' resetToken={page.url.searchParams.get('token') ?? ''} loginUrl={resolve('/auth/login', {})} />

package/templates/features/iam/routes-shared/api/auth/config/+server.ts

@@ -0,0 +1,4 @@
+import { iam } from '@h-ai/iam'
+import { kit } from '@h-ai/kit'
+
+export const GET = kit.auth.createApi(iam).publicConfig

package/templates/features/iam/routes-shared/api/auth/login/+server.ts

@@ -1,36 +1,4 @@
-import type { CoreConfig } from '@h-ai/core'
-/**
- * 登录 API
- */
-import type { RequestHandler } from './$types'
-import { core } from '@h-ai/core'
 import { iam } from '@h-ai/iam'
 import { kit } from '@h-ai/kit'
-import { z } from 'zod'
 
-const LoginInputSchema = z.object({
-  identifier: z.string().trim().min(1).max(254),
-  password: z.string().min(1).max(128),
-}).strict()
-
-export const POST: RequestHandler = kit.handler(async ({ request, cookies, locals }) => {
-  const { identifier, password } = await kit.validate.body(request, LoginInputSchema)
-
-  const result = await iam.auth.login({ identifier, password })
-  if (!result.success) {
-    return kit.response.fromError(result.error, locals.requestId)
-  }
-
-  const { tokens } = result.data
-  const config = core.config.getOrThrow<CoreConfig>('core')
-
-  cookies.set('session_token', tokens.accessToken, {
-    path: '/',
-    httpOnly: true,
-    sameSite: 'lax',
-    secure: config.env === 'production' || config.env === 'staging',
-    maxAge: tokens.expiresIn,
-  })
-
-  return kit.response.ok({ authenticated: true }, locals.requestId)
-})
+export const POST = kit.auth.createApi(iam).login

package/templates/features/iam/routes-shared/api/auth/login/ldap/+server.ts

@@ -0,0 +1,4 @@
+import { iam } from '@h-ai/iam'
+import { kit } from '@h-ai/kit'
+
+export const POST = kit.auth.createApi(iam).loginWithLdap

package/templates/features/iam/routes-shared/api/auth/login/otp/+server.ts

@@ -0,0 +1,4 @@
+import { iam } from '@h-ai/iam'
+import { kit } from '@h-ai/kit'
+
+export const POST = kit.auth.createApi(iam).loginWithOtp

package/templates/features/iam/routes-shared/api/auth/otp/send/+server.ts

@@ -0,0 +1,4 @@
+import { iam } from '@h-ai/iam'
+import { kit } from '@h-ai/kit'
+
+export const POST = kit.auth.createApi(iam).sendOtp

package/templates/features/iam/routes-shared/api/auth/password-reset/confirm/+server.ts

@@ -0,0 +1,4 @@
+import { iam } from '@h-ai/iam'
+import { kit } from '@h-ai/kit'
+
+export const POST = kit.auth.createApi(iam).confirmPasswordReset

package/templates/features/iam/routes-shared/api/auth/password-reset/request/+server.ts

@@ -0,0 +1,4 @@
+import { iam } from '@h-ai/iam'
+import { kit } from '@h-ai/kit'
+
+export const POST = kit.auth.createApi(iam).requestPasswordReset

package/templates/features/iam/routes-shared/api/auth/register/+server.ts

@@ -1,26 +1,4 @@
-/**
- * 注册 API
- */
-import type { RequestHandler } from './$types'
 import { iam } from '@h-ai/iam'
 import { kit } from '@h-ai/kit'
 
-export const POST: RequestHandler = async ({ request, locals }) => {
-  const body = await request.json()
-  const { username, email, password, confirmPassword } = body
-
-  if (!username || !password) {
-    return kit.response.badRequest('Username and password are required')
-  }
-
-  if (password !== confirmPassword) {
-    return kit.response.badRequest('Passwords do not match')
-  }
-
-  const result = await iam.user.register({ username, email, password })
-  if (!result.success) {
-    return kit.response.badRequest(result.error.message)
-  }
-
-  return kit.response.ok({ message: 'Registration successful' }, locals.requestId)
-}
+export const POST = kit.auth.createApi(iam).register

package/templates/features/iam/routes-website/auth/forgot-password/+page.svelte.hbs

@@ -0,0 +1,10 @@
+<script lang='ts'>
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const actions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} {actions} initialMode='forgot' resetToken={page.url.searchParams.get('token') ?? ''} loginUrl={resolve('/auth/login', {})} />

package/templates/features/iam/routes-website/auth/login/+page.svelte.hbs

@@ -0,0 +1,11 @@
+<script lang='ts'>
+  import { goto } from '$app/navigation'
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const authActions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} actions={authActions} initialMode='login' loginUrl={resolve('/auth/login', {})} registerUrl={resolve('/auth/register', {})} onauthenticated={() => goto(resolve('/', {}))} />

package/templates/features/iam/routes-website/auth/register/+page.svelte.hbs

@@ -0,0 +1,11 @@
+<script lang='ts'>
+  import { goto } from '$app/navigation'
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const authActions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} actions={authActions} initialMode='register' loginUrl={resolve('/auth/login', {})} registerUrl={resolve('/auth/register', {})} onauthenticated={() => goto(resolve('/', {}))} />

package/templates/features/iam/routes-website/auth/reset-password/+page.svelte.hbs

@@ -0,0 +1,10 @@
+<script lang='ts'>
+  import { resolve } from '$app/paths'
+  import { page } from '$app/state'
+  import { kit } from '@h-ai/kit'
+  import { AuthPanel } from '@h-ai/ui/components/scenes/iam/index'
+
+  const actions = kit.client.createAuthActions()
+</script>
+
+<AuthPanel config={page.data.iamPublicConfig} {actions} initialMode='reset' resetToken={page.url.searchParams.get('token') ?? ''} loginUrl={resolve('/auth/login', {})} />

package/templates/skills/hai-api-client/SKILL.md

@@ -174,3 +174,8 @@ if (login.success) {
 - 客户端不导入 `@h-ai/crypto` 的内部 transport 工厂，只通过 `transport: { crypto }` 装配。
 - 前端只依赖 `@h-ai/api-client` 和 contract 类型，不依赖业务模块实现。
 - httpOnly cookie 模式需服务端与客户端同步配置，不支持跨域刷新（`SameSite=Strict`）。
+
+
+## 配置驱动认证页面
+
+`apiClient.createAuthActions(client)` 为含标准 iam contract 的客户端提供 publicConfig、login、register、sendOtp、requestPasswordReset、confirmPasswordReset。login 输入使用 identifier/password/method/code，method 为 password、ldap、email、sms。成功认证自动调用既有安全 TokenStorage；应用只需把动作传给 AuthPanel，并在 onauthenticated 中刷新自己的用户状态或导航。

package/templates/skills/hai-app-create/reference.md

@@ -312,6 +312,16 @@ interface CreateArticleInput {
 
 ## 初始化顺序
 
+CLI 项目统一忽略 `**/data/`，含根目录、workspace 子目录及 `.gitkeep`；数据库/上传文件不入 Git。Fullstack 的服务端 config 始终保留 core、serv、db、cache、iam、storage、audit、reach、ai、vecdb、payment、scheduler、deploy 共 13 份 YAML，未启用模块整份注释，可选字段及替代 Provider 按块注释，`.env.example` 也保留未启用模块的注释凭据。
+
+H5 认证路由独立显示；业务页面使用 `@h-ai/ui` 的 `BottomNav` 与移动端壳样式，导航启用 centered/maxWidth/safeArea，与页面同宽。
+
+扩展这些配置前先核对当前安装版本及模块公开 Schema。在服务端 workspace 安装需要的依赖，在 `src/server/runtime.ts` 按依赖顺序校验/初始化、失败清理并反序关闭，再接入 contract/procedure。整份注释文件先去掉一层外层注释，可选块只开启需要的字段；切换 Provider 时替换旧连接块并保持名称唯一。配置文件存在不代表模块已启用。crypto.init() 无配置参数，datapipe 无生命周期，不增加虚构的 YAML。
+
+环境变量叶子覆盖只遍历 YAML 已有路径，注释键须先取消注释，或用 HAI_DB/HAI_CACHE 等整体对象覆盖。camelCase 不拆词，例如 connectTimeout → HAI_CACHE_CONNECTTIMEOUT；密钥仅写入被忽略的环境文件或部署环境。语言列表在前端/shared 的 project.inlang/settings.json 中同步，core 只配置 defaultLocale。
+
+Fullstack 自动生成的 .env 默认只启用管理员初始密码和 PUBLIC_API_BASE，其余环境覆盖保留注释，YAML 修改可直接生效。显式开启环境覆盖后，修改 YAML 时须核对该覆盖是否仍适用。
+
 复用当前应用服务端启动/关闭入口；SvelteKit 通常为 `$lib/server/init.ts`，API/fullstack 使用已有 service/serv 初始化文件。下列是启用 IAM 时的常见依赖关系，不要求无关应用安装这些模块：
 
 ```

package/templates/skills/hai-iam/SKILL.md

@@ -13,15 +13,21 @@ description: "使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key
 | 适用场景 | 应用身份认证、会话失效或角色权限管理 |
 | 输入 | IamConfigInput、已初始化依赖、凭据、用户/角色/权限 ID |
 | 输出 | 认证、会话与授权操作的 HaiResult |
-| 限制 | 仅服务端，先初始化 reldb/cache（crypto 未初始化时由 IAM 初始化）；公开认证入口是 iam.auth。客户端经 contract/API 调用，不能暴露密码或完整 token。 |
+| 限制 | 仅服务端，先初始化 reldb/cache（crypto 未初始化时由 IAM 初始化）；公开认证入口是 iam.auth。客户端经 contract/API 调用，凭证只用于认证和安全存储，不进入日志或公开配置。 |
 
 ## 使用路径
 
-- `_iam.yml` 只传 IamConfigInput；不把 reldb/cache 句柄混入配置。
+- `_iam.yml` 只存 IamConfigSettingsInput，运行时回调单独传给 iam.init；不把 reldb/cache 句柄混入配置。
 - 角色资料与 permissionIds 一次保存：未传保持、空数组清空、未知 ID 失败；人数查询失败不能显示为 0。
 - IAM 服务端是 iam.auth；typed HTTP client 的路径是 apiClient.iam.auth。
 - OTP/API Key 等先核对 login 开关；不把未启用能力的 NOT_INITIALIZED 当认证失败。
 
+- 认证页面使用 iam.publicConfig + AuthPanel，协议用弹窗，表单通过 header/extraFields/footer 或 AuthPanel 的 login*/register* snippet 扩展；Kit 使用 kit.auth.createApi/publicPaths + kit.client.createAuthActions，HTTP 客户端使用 apiClient.createAuthActions。
+- LDAP/Reach 均可选：基础认证无需安装；默认 LDAP 关闭，选用默认客户端才安装 ldapts 并设置 login.ldap + ldap。OTP 邮件/短信由 otp.email/sms 控制，选择 Reach 标准模板或自定义发送回调；具体签名与失败处理见参考中的“可选 LDAP 与通知”。
+- 多节点共享 DB + Redis，Memory 只用于单进程。重置的策略失败计入 maxAttempts；OTP 消费不解除 resendInterval。管理员 createUser 不受自助注册开关限制。
+
+- 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
+
 ## 按需参考
 
 详细配置、API 签名、错误码和范本在 [reference.md](reference.md)。按下列标题定位所需小节，不默认通读；用例中的业务变量需结合当前应用补齐。
@@ -30,6 +36,7 @@ description: "使用 @h-ai/iam 实现登录、注册、会话、OTP/LDAP/API Key
 - 依赖
 - 适用场景
 - 使用步骤
+- 可选 LDAP 与通知 — 安装、TLS/AD 配置、标准模板、自定义发送
 - 核心 API
 - HTTP API 契约
 - 错误码 — `HaiIamError`