ZhenIns Public Whitepaper

Version: 1.1
Published: 19 May 2026
Applicable to: Policyholders, insurance advisors, brokerage firms, and ecosystem partners
Previous version: v1.0 (2026-05-10)

---

Change Summary (v1.0 → v1.1)

• Unified Identity & SSO (ADR-009): Consumer SMS authentication and advisor OAuth login both connect to the auth.zhenrobot.com unified identity center, enabling cross-platform identity recognition and passwordless recovery.
• Consumer Session Persistence: Full CRUD support for conversation history (create, read, rename, delete). Session data is no longer limited to browser local storage.
• Precise Token Counting: Introduced tiktoken for per-token metering, replacing traditional character-length estimation. Provides accurate context-budget management for complex insurance reasoning.
• Consent Full-Cycle Closure: From AI suggestion trigger → profile authorization confirmation → advisor receipt → consumer revocation, the entire flow is stateful, auditable, and revocable.
• Frontend State Race Protection: Chat session layer and business-state layer are decoupled, eliminating duplicate loading and quota-state drift during mount/unmount cycles.
• End-to-End Test Full Coverage: lint + build + E2E + backend integration test + production smoke 5-step curl all纳入 CI gate.

---

1. Overview

1.1 What is ZhenIns

ZhenIns is the AI-powered insurance consulting frontstage of the Zhen ecosystem. It serves policyholders through a chat-first interface for coverage-gap analysis, plan recommendations, and document preparation guidance. When a conversation touches a complex scenario—such as replacing an existing policy, conflicting health disclosures, severe budget constraints, or special-risk populations—the system automatically routes the case to a licensed insurance advisor for human review via the Agent2Human protocol.

ZhenIns does not sell insurance products directly. Its role is to help clients answer three questions:

• Where are my coverage gaps?
• Is my current plan sufficient?
• What should I do next, and what documents should I prepare?

1.2 Who We Serve

1.3 Core Commitments

1. AI first, human fallback: AI handles standard cases; complex cases are escalated automatically or on demand. The client always has a choice.
2. Data minimization: Full sensitive data is not collected before explicit authorization; every data request states its purpose; users may revoke authorization at any time.
3. Compliance audit trail: Consultation requests, recommendation outputs, human-review nodes, and authorization records are all logged and auditable.
4. No final-conclusion pretense: AI outputs are recommendation summaries, not formal underwriting conclusions. Final coverage, claims, and compliance determinations are executed by licensed insurers.

---

2. Position in the Zhen Ecosystem

2.1 Business Frontend Shell

ZhenIns is a Business Frontend Shell in the Zhen ecosystem. It is responsible for public client acquisition, consultation interaction, plan explanation, authorization documentation, and the compliance whitepaper. It does not maintain a standalone identity system, billing platform, or organization backend.

The shell architecture ensures that insurance-grade compliance, audit, and data-minimization requirements are met centrally, not rebuilt in every vertical site.

2.2 Relationship to zhen-brain-core

zhen-brain-core handles insurance reasoning, plan generation, risk assessment, and memory.

Critical constraint: ZhenIns must not call zhen-brain-core directly in production. All requests are forwarded through the zhen-platform-core gateway. The fixed execution chain is:

ZhenIns Frontend → zhen-platform-core → zhen-brain-core

This constraint ensures identity verification, permission checks, usage auditing, and compliance logging are enforced at the gateway layer, preventing direct exposure of reasoning interfaces from the frontstage.

2.3 Relationship to zhen-platform-core

zhen-platform-core is the unified operating kernel of the Zhen ecosystem, responsible for:

• Identity & Organization: consumer SMS authentication, advisor OAuth login, workspace and organization management
• Billing & Entitlements: membership subscriptions, orders, refunds, invoices
• Payments: unified checkout (Alipay / WeChat Pay), with the pricing catalog as the single source of truth
• Audit Logging: session metadata, authorization records, compliance tags

ZhenIns does not maintain a second identity or billing system locally. It consumes platform-core services via API and surfaces results to users.

2.4 Relationship to zhen-platform-console

zhen-platform-console is the unified post-login control plane.

ZhenIns retains only transitional entry points for logged-in management; long-term ownership belongs to the console. The following actions redirect to the console:

• Viewing orders and entitlements
• Managing API Keys
• Team seats and organization settings
• Downloading compliance reports and audit files
• Subscription management and invoices

The frontstage's responsibility is to guide users to the correct console entry point, not to rebuild the control plane inside the site.

2.5 Why This Division is Necessary

The insurance industry has far stricter regulatory requirements than typical SaaS:

• Identity authenticity: Insurance transactions are bound to verified identity; anonymous sessions are insufficient.
• Authorization traceability: Any data collection and processing must have explicit authorization records.
• Data minimization: The cloud does not hold raw client data by default; uploads are authorization-driven.
• Centralized risk control: Reasoning, assessment, and sandbox capabilities are governed by a unified brain to avoid inconsistent interpretations across frontstages.

Centralizing identity, billing, risk control, and audit is the minimum viable architecture to meet these requirements.

---

3. Agent2Human Protocol

3.1 Protocol Definition

Agent2Human is ZhenIns's collaboration protocol. Its core principle: AI handles standard cases; human advisors handle complex cases.

The AI advisor continuously assesses conversation complexity. When complexity exceeds a safe threshold, or when the client explicitly requests human assistance, the system automatically transfers a de-sanitized summary of the conversation context to a licensed insurance advisor.

3.2 Automatic Escalation Triggers

The following scenarios trigger automatic human handoff:

• Complex health disclosure: Prior conditions, multiple hospital records, non-standard underwriting status
• Existing policy replacement: Surrender-loss calculations, waiting-period overlap, liability conflicts
• Liability conflicts: Duplicate coverage or gap hedging across multiple family policies
• Severe budget constraints: Budget and coverage needs are too far apart, requiring trade-off analysis
• Special populations: High-risk occupations, non-standard health, high-net-worth individuals, foreign nationals, complex family structures

3.3 Client-Initiated Escalation

Clients may request human review at any stage, for example:

"I'd like to speak with a professional insurance advisor." "I'm not sure about this recommendation." "Can someone confirm this for me?"

Client-initiated escalation bypasses AI complexity assessment and enters the human queue directly.

3.4 Advisor Qualifications

Advisors receiving referrals must meet:

• Valid professional license
• Minimum 2 years of experience
• Quarterly platform re-certification
• Full-process audit logging

Service standards:

The advisor side is equipped with a multi-channel notification system—on-site notifications, Web Push, SMS, and Email—ensuring high-intent leads (score ≥ 7) reach advisors within 15 seconds.

3.5 Data De-sanitization Boundary

AI conversations may collect complete data (ID numbers, detailed health records, asset details). When transferring to a human advisor, only a de-sanitized summary is shared:

• Age bracket / household structure / budget / occupation type
• Coverage-gap summary
• Complex-point description (de-sanitized)
• Client request

Not shared:

• Complete AI conversation history
• Detailed client identity (before authorization)
• AI internal assessment logic
• Complete household asset details

If the human advisor requires full data, they must issue a secondary authorization request to the client. The data is only released after explicit client consent. Clients may revoke consent at any stage; upon revocation, the advisor workstation immediately loses profile access via real-time WS.

3.6 Consent Full-Cycle

Handoff Consent is the data-authorization core of the Agent2Human protocol, forming a complete closed loop:

1. Trigger: AI identifies complex needs during conversation, returning a suggested_handoff: true marker
2. Authorization confirmation: Frontend pops a Consent Modal, listing profile items to be shared (age, city, household, budget, health, etc.), with sensitive fields marked
3. Advisor receipt: Advisor workstation displays real-time leads with AI-extracted structured profiles and conversation summaries
4. Revocation: Consumers may revoke consent at any time from "My Service Progress"; advisor side receives a lead_revoked WS event in real time, and profile access is immediately revoked
5. Audit: Authorization, sharing, and revocation are fully logged to the notifications table and lead_events log

3.7 Quality Assurance

• Quarterly review of advisor licenses
• Monthly review of service scores and complaint rates
• Full conversation logging for compliance auditing
• Refund or advisor replacement available on dissatisfaction
• Platform outbound E2E tests covering the full consumer journey, advisor workspace, payment orchestration, and authorization chain (32+ test cases)

---

4. Data Governance and Compliance

4.1 Minimization and Tiered Authorization

ZhenIns follows the Personal Information Protection Law requirements, applying data minimization and tiered authorization:

Hard rules:

• Full sensitive data may not be requested before explicit authorization.
• "Upload entry exists" may not be stated as "system has received official documents."
• "Recommendation summary" may not be stated as "final coverage result."

4.2 Data Holdings Boundary

Key principle: The cloud does not hold raw client data by default. All uploads are authorization-driven and necessary for business purposes.

4.3 Transport and Storage Security

• Transport: TLS 1.3 full-path encryption
• Storage: AES-256 encryption for sensitive data
• Audit: Periodic security audits and penetration testing
• Logging: Access logs retained in accordance with regulatory requirements

4.4 Compliance Logging and Audit

The following events are mandatorily logged:

• Time, scenario, and user identifier (de-sanitized) of each consultation request
• AI recommendation summary output
• Agent2Human trigger reason and human review outcome
• Client authorization and withdrawal records
• Payment order status changes

Log data supports compliance audit exports and is managed centrally by zhen-platform-core.

---

5. Technical Architecture

5.1 Three-Layer Execution Chain

ZhenIns's production execution chain is frozen as a three-layer structure:

Business Frontend (ZhenIns)
  → zhen-platform-core (unified gateway)
    → zhen-brain-core (insurance reasoning and risk control)

Frontend responsibilities: initiate business requests, display status, surface results, render conversations.
Gateway responsibilities: identity verification, permission validation, usage auditing, compliance logging.
Brain responsibilities: insurance reasoning, plan generation, risk assessment, memory retention.

5.2 SSE Real-Time Streaming Consultation

The frontend uses Server-Sent Events (SSE) for real-time AI chat streaming. After a user sends a message, the AI generates responses token-by-token without waiting for the full response.

Technical parameters:

• First-token latency: 3–6 seconds (influenced by external inference API queuing)
• Token buffer: 30ms timeout / ≥8 character flush
• Frontend typewriter effect: 75ms per CJK character, 22ms per Latin word
• Burst smoothing: 25ms backend smoothing to prevent frontend stutter
• Precise token metering: Introduced tiktoken + CJK-aware fallback, replacing len(text) with estimate_tokens() across the entire stack to ensure accurate context budgets for complex insurance scenarios

5.3 Payment Flow

Payments are progressively centralized to the zhen-platform-core unified checkout. New order flow:

User confirms service package → platform-core generates order → Alipay / WeChat Pay
  → Payment success → entitlement sync → ZhenIns receipt page

The local payment system (previously direct Alipay / WeChat SDK) was formally retired on 2026-05-16; /billing/recharge and legacy webhook endpoints return 410 Gone. The frontstage retains only payment orchestration pages, result handling, and receipt logging.

5.4 Scoped API Key and OpenClaw Skill

• Scoped API Key: Cross-platform access uses unified identity + unified billing + scope-limited permission keys, avoiding universal-key risks
• OpenClaw Skill: Exposes AI insurance consulting capabilities via standardized interfaces to third-party workflows, supporting recognition of human-review nodes and de-sanitized handoff in local AI environments. insurance-broker@2.0.2 has been published to ClawHub with a single proxy action and whitelist-protected endpoints

5.5 Frontend State Layering and Race Protection

The Chat frontend has completed a state-layering refactor, decoupling session state (conversations/messages/streaming) from business state (alert/consumer/handoff):

• chat-session-context.tsx: Pure session container responsible for CRUD, SSE consumption, and loading states
• chat-business-context.tsx: Business-state container responsible for quotas, errors, and handoff suggestions
• alert-reducer.ts: Action-Based guard with a unified entry point for state changes

Key protection: mount-phase loadConversations is guarded by hasInitialLoadedRef to prevent duplicate execution; clearQuotaState(reason) provides a unified entry point to eliminate race conditions.

---

6. Business Model

6.1 Client Side

Consumer conversation quotas are managed by the zhen-platform-core entitlement system; the local free_messages_used field has been retired.

6.2 Advisor Side

Advisor login is unified through OAuth (auth.zhenrobot.com); the local password system was formally retired on 2026-05-07. The advisor workspace includes real-time WS push, lead pools, multi-dimensional filtering, performance rankings, and commission statistics.

6.3 Enterprise Side

Enterprise plans include multi-seat management, organization permissions, API Key integration, compliance reports, and audit exports.

6.4 Pricing Centralization

Product pricing (advisor memberships, team seats, enterprise plans) is no longer maintained locally by ZhenIns. The zhen-platform-core catalog serves as the single source of truth. The frontstage is responsible only for display and purchase guidance.

---

7. Roadmap and Milestones

7.1 Completed

7.2 In Progress

7.3 Planned

Feature expansion is driven by the Zhen ecosystem roadmap and is not released independently by ZhenIns. The frontstage maintains its "shell" positioning; new capabilities are inherited naturally through platform-core and brain-core upgrades.

---

Appendix A: Glossary

Appendix B: Compliance Document Index

• Authorization
• Privacy Policy
• Terms of Service
• Security & Compliance
• Documentation Center
• Download Center

---

This document is the ZhenIns public whitepaper v1.1. Detailed technical specifications, ecosystem master documents, and internal interface definitions are maintained in upstream architecture documents and are not superseded by this whitepaper. Historical versions are permanently accessible: /whitepaper/v/v1.0.