# Commercial Product Blueprint

## 1. Purpose

This document defines the final commercial product shape for `QianjiangClaw`.

It answers the high-level product questions that should not drift during implementation:

- What is the final product being sold
- How customers get access
- How login, entitlement, enterprise seats, and credits work
- Why skills are cloud-orchestrated
- What belongs to the desktop app, cloud services, and bundled OpenClaw runtime

If implementation details conflict with this document, this document wins.

---

## 2. Final Product Goal

The final product goal is locked as:

- the deliverable is a `Windows installer`
- the installer eventually `bundles OpenClaw runtime`
- customers must `sign in with a company account`
- entitlement uses `always-online verification`
- commercial packaging starts with `enterprise seats + platform credits`
- the platform grants `trial credits / initial credits`
- model usage is `platform-managed and platform-routed` by default
- Douyin/Xiaohongshu and similar capabilities are exposed as `skills`
- skills use `cloud orchestration + local presentation/execution entry`
- user profile, organization info, credit balance, and usage history are fetched through `cloud APIs`

The final product is not just a local chat client.

It is:

`a commercially sellable Windows AI desktop product with account, entitlement, and credits systems`

---

## 3. Target User Journey

The target end-state flow is:

1. Customer installs the company installer
2. Customer launches the desktop app
3. Customer signs in with a company-issued account
4. The app verifies online:
   - user validity
   - organization validity
   - seat availability
   - subscription/feature entitlement
   - credit availability
5. After login and entitlement pass, the customer enters the app
6. The app fetches and displays through APIs:
   - user profile
   - organization/package/seat status
   - current credit balance
   - recent usage and consumption history
   - skill catalog and allowed skills
7. The customer uses chat, skills, task execution, results, logs, and diagnostics directly
8. If credits are insufficient or entitlement becomes invalid, the UI refreshes the latest server state and explains the reason

For non-technical users, the intended experience is:

- no separate OpenClaw installation
- no local environment setup
- no command line usage
- no need to configure provider/model/API keys manually
- no exposure to Gateway, runtime, Node, or WSL2 concepts

---

## 4. Commercial Model

### 4.1 Access Model

Use:

- `account login`
- `enterprise seats`
- `online entitlement verification`

Do not use offline license keys as the primary control path.

Default rules:

- users must log in before using the product
- each user belongs to an organization
- organizations own subscriptions and seats
- the server decides whether the current user may continue using the product

### 4.2 Connectivity Policy

Use:

- `always-online`

Default behavior:

- login requires network access
- startup requires online entitlement and credit verification
- the app refreshes entitlement, credits, and package state during use
- if entitlement becomes invalid or credits are insufficient:
  - new tasks are blocked
  - the UI clearly explains the reason
  - the server remains the source of truth

### 4.3 Billing Model

Phase 1 commercial delivery uses:

- `platform-issued credits`
- `platform-paid model usage`
- `no customer-provided API key by default`

Meaning:

- the company grants credits to users or organizations
- chat, skills, and task execution consume platform credits
- users see balances, usage, and package information instead of underlying model secrets
- the platform manages providers, routing, and metering centrally

Later expansion can add:

- organization-level credit packages
- package-based monthly credit allocations
- skill-specific consumption rules
- recharge, gifting, compensation, and promotional credits

The default commercial path is no longer `customer-provided API keys`.

---

## 5. Skill Product Direction

The final product can evolve into a business-task AI worker platform.

Examples:

- Douyin operations
- Xiaohongshu operations
- topic planning
- title generation
- comment analysis
- pre-publish review
- multi-platform distribution

These capabilities should not be hardcoded into the desktop app.

They should be delivered through a `Skill Platform`.

Skill design principles:

- business definitions live in the cloud
- workflow orchestration lives in the cloud
- parameter rules live in the cloud
- permissions live in the cloud
- the desktop app collects input, triggers execution, and presents results

This allows:

- faster business iteration without shipping a new installer each time
- skill visibility controlled by organization, package, seat, and credit state
- cleaner commercial control later

---

## 6. System Architecture

### 6.1 Desktop Responsibilities

The desktop app is responsible for:

- installed user entry point
- sign-in
- entitlement status
- user profile and credit display
- chat entry
- skill catalog and run screens
- settings
- logs and diagnostics
- local runtime state display

The core boundary remains:

`Renderer -> preload -> Electron Main -> GatewayClient / RuntimeManager / AuthClient / ProfileClient / CreditClient / SkillClient`

### 6.2 Cloud Responsibilities

The cloud side must at least cover:

- authentication
- user profile APIs
- organizations
- seat management
- subscriptions and entitlements
- credit wallet / balance / grant rules
- credit consumption and usage history
- skill registry and delivery
- workflow orchestration
- provider routing and model metering
- audit and event logging

The first implementation does not need to be a microservice architecture, but these domain boundaries must stay clear.

### 6.3 Local Runtime Responsibilities

In the final product, the local OpenClaw runtime is responsible for:

- being bundled by the installer
- first-run initialization
- local health checks
- session/task hosting
- log output
- stable local Gateway capability

It does not own commercial entitlement, credits, or profile state. Those belong to cloud APIs.

---

## 7. Delivery Phases

### Phase 1: Commercial Transition MVP

Goal:

- add login, entitlement, and credits shell on top of the current external-OpenClaw desktop app

Focus:

- sign-in page
- online entitlement checks
- block core features when unauthorized
- profile API integration
- credit balance / usage API integration
- secure auth token storage
- diagnostics

Result:

- customers must log in with company accounts before using the app
- customers can see profile and credit state in the desktop app
- customers do not need to provide model/API keys

### Phase 2: Enterprise Seats, Credits, and Skill Platform

Goal:

- move from simple login gating to enterprise-seat, package, and credit-based control

Focus:

- organization/member/seat model
- entitlement fetch
- credit account and deduction rules
- cloud skill catalog
- skill forms and parameter definitions
- skill execution entry points

Result:

- different organizations see different capabilities
- capability boundaries can depend on package, seat, and credit state

### Phase 3: Installer Delivery

Goal:

- stabilize the Windows installer delivery path

Focus:

- installer startup reliability
- login, entitlement, profile, credits, and skill APIs in installed environments
- correct token, log, and diagnostics paths

Result:

- the installer can be sent to customers for trial use

### Phase 4: Bundled Runtime PoC

Goal:

- validate that the installer can reliably ship and run bundled OpenClaw runtime

Focus:

- fixed runtime directory layout
- `RuntimeManager` start/stop/health/logs
- first-run initialization
- bundled runtime becomes the preferred local path
- login, credits, and skills continue to work through APIs in bundled-runtime mode

Result:

- the app can run on machines without preinstalled OpenClaw

### Phase 5: Final Commercial Release

Goal:

- non-technical customers can install and use the product directly

Focus:

- bundled runtime
- company account login
- enterprise seat control
- online entitlement
- cloud-driven profile and credits display
- platform-managed model usage
- package-, org-, and credit-based skill access

Result:

- a commercially ready, one-install desktop AI product

---

## 8. Required Capability Additions

Desktop side needs:

- `AuthClient`
- `ProfileClient`
- `CreditClient`
- `EntitlementClient`
- `SkillClient`
- production `SecretManager (keytar)` for auth/session tokens and other local sensitive data
- production `RuntimeManager`

Cloud side needs:

- login/token service
- profile service
- organization/seat/subscription service
- entitlement decision service
- credit wallet and ledger service
- model metering service
- skill registry/publishing service
- skill orchestration service
- audit/event service

---

## 9. AI Usage Rules

Any future AI agent should read, in order:

1. `docs/product-roadmap.zh-CN.md` or `docs/product-roadmap.md`
2. `docs/commercial-product-blueprint.zh-CN.md` or `docs/commercial-product-blueprint.md`
3. `docs/progress-summary.md`

The AI must keep these facts fixed:

- the current external Gateway path is transitional only
- the final product must bundle runtime in the installer
- the final product must include company login, enterprise entitlement, and credits
- profile, credit, and skill state come from cloud APIs
- the default product path does not require customer-provided API keys
- the final product must support commercial skill delivery
- every implementation change must be explainable as part of a defined phase

If future work drifts into:

- only building a chat tool
- ignoring login/entitlement
- ignoring enterprise seats
- ignoring credit accounts and profile APIs
- ignoring cloud skill orchestration
- treating external Gateway as the final product
- keeping customer-provided API keys as the default model

then it is off-plan and must be corrected.
