# ZShip SvelteKit

> A SvelteKit frontend template for ZShip projects deployed to Cloudflare Workers with Workers Assets.

Site: https://sveltekit.zship.ai

This file is generated from the current SvelteKit docs, blog, policy content, and site metadata.

# Core Pages

## ZShip SvelteKit

URL: https://sveltekit.zship.ai/

Summary: Production-ready SvelteKit AI SaaS template with auth, billing, docs, blog, analytics, dashboard, and AI workflows built in.

Production-ready SvelteKit AI SaaS template with auth, billing, docs, blog, analytics, dashboard, and AI workflows built in.

## Pricing

URL: https://sveltekit.zship.ai/pricing

Summary: Plans, checkout entry points, subscriptions, and credit packages.

Plans, checkout entry points, subscriptions, and credit packages.

## Dashboard

URL: https://sveltekit.zship.ai/dashboard

Summary: Authenticated account, billing, credits, API keys, support, check-in, and AI workflows.

Authenticated account, billing, credits, API keys, support, check-in, and AI workflows.

## Documentation

URL: https://sveltekit.zship.ai/docs

Summary: Product documentation and implementation guides.

Product documentation and implementation guides.

## Blog

URL: https://sveltekit.zship.ai/blog

Summary: Product updates, implementation notes, and launch articles.

Product updates, implementation notes, and launch articles.

## Changelog

URL: https://sveltekit.zship.ai/changelog

Summary: Versioned product changes across the starter, dashboard, billing, and AI workspace.

Versioned product changes across the starter, dashboard, billing, and AI workspace.

# Documentation

## AI playground

URL: https://sveltekit.zship.ai/docs/ai-playground

Locale: en

Summary: The canonical AI entry in web-sveltekit and how it relates to credits, keys, and guest access.

`/dashboard/ai-playground` is the canonical AI entry point in `web-sveltekit`.

## Why it matters

ZShip exposes the AI playground as the recommended product flow because it already understands:

- auth state
- guest sessions
- available credits
- API key lifecycle
- generation history and provider-specific inputs

## Recommended user path

1. Start from `/guest-demo` or `/dashboard`
2. Open `/dashboard/ai-playground`
3. Generate the first result
4. Upgrade to a full account or a higher plan when usage grows

## What product teams should avoid

- Do not ask first-time users to paste a manual API key before they understand the product.
- Do not expose multiple competing AI entry points unless each one has a clearly different audience.
- Do not separate credits, AI generation, and account state into unrelated pages without a guided default path.

## Analytics

URL: https://sveltekit.zship.ai/docs/analytics

Locale: en

Summary: Optional analytics support for GA4, Plausible, and Microsoft Clarity with consent gating.

`web-sveltekit` supports optional global analytics providers from `zship.app.json`.

## Supported providers

- Google Analytics 4 via `analytics.googleAnalytics.measurementId`
- Plausible via `analytics.plausible.domain`
- Microsoft Clarity via `analytics.clarity.projectId`

## Consent flow

Third-party analytics scripts are **not** injected by default. When at least one provider is configured and `analytics.consentBanner.enabled` is `true`, the app shows a consent banner and waits for a decision before loading those providers.

- Consent is persisted with a cookie (`zship_analytics_consent`) plus `localStorage`
- Client helpers live in `src/lib/client/analytics.ts` (`setAnalyticsConsent`, `trackAnalyticsEvent`, `trackAnalyticsPageView`)
- The banner UI is `src/lib/components/AnalyticsConsentBanner.svelte`
- You can extend the same layer later for region-aware consent or first-party proxying

```json
{
  "analytics": {
    "consentBanner": {
      "enabled": true
    },
    "googleAnalytics": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "plausible": {
      "domain": "sveltekit.zship.ai",
      "scriptSrc": "",
      "apiEndpoint": ""
    },
    "clarity": {
      "projectId": "your-clarity-project-id"
    }
  }
}
```

Leave provider IDs empty in the template until you are ready for production tracking. Empty IDs mean no scripts and no banner.

## Next improvement path

If you need stricter compliance, add a dedicated consent center or route analytics through first-party endpoints before turning on provider IDs in production.

## Auth and guest mode

URL: https://sveltekit.zship.ai/docs/auth-and-guest-mode

Locale: en

Summary: Understand login, guest access, account conversion, and where each path should lead users.

The SvelteKit template supports both registered accounts and guest sessions. The goal is to reduce friction before a user commits to sign-up.

## Registered account flow

- Public entry: `/auth/login`, `/auth/register`, and `/login`
- Supported modes: email today; Google/GitHub OAuth when configured in later stages
- Post-login destination: `/dashboard`

Registered users should land on the activation-oriented dashboard homepage and continue from there into AI, keys, billing, or support.

## Guest flow

- Public entry: `/guest-demo`
- Guest sessions are real authenticated sessions with their own credits and dashboard access
- Guests should be encouraged to upgrade after they validate the workflow

## Upgrade guidance

Guest mode is ideal for:

- early product demos
- marketing traffic that is not ready to sign up
- sales conversations where you want a lower-friction proof point

Registered mode is ideal for:

- persistent usage
- billing and subscriptions
- API key management
- long-term project ownership

## Product recommendation

Do not treat guest mode as a dead-end sandbox. It should behave like a guided first session that naturally leads into account creation once the user sees value.

## Billing

URL: https://sveltekit.zship.ai/docs/billing-and-credits

Locale: en

Summary: How pricing, credits, subscriptions, and order history fit together in the SvelteKit template.

ZShip uses credits as the product-level spending unit and plans as the commercial packaging around those credits.

## What users can do

- Compare plans on `/pricing`
- Review current balance from the dashboard credits surfaces
- Inspect active subscription status and previous purchases through pay-service BFF routes

## How the flow works

1. The visitor chooses a plan on the pricing page.
2. Checkout is created through the SvelteKit pay-service proxy (`src/routes/api/pay/*`).
3. Successful payment updates subscription state and the credit ledger.
4. Dashboard pages read the latest balance and order records from the same backend state.

## What to validate before launch

- Pricing labels and descriptions match the plans configured in the pay service.
- Credit amounts are easy to understand from a user perspective.
- Refund expectations are documented and linked from support.
- The support team knows which cases should go through tickets versus payment provider portals.

## Common launch questions

### When should I send users to pricing?

Send users to pricing when they run out of credits, need a higher plan, or want to understand what each tier unlocks.

### Where should refund requests go?

Use the support flow documented in `Support and refund`. Order history should expose enough context for a product-level refund request.

## Docs system

URL: https://sveltekit.zship.ai/docs/docs-system

Locale: en

Summary: The Markdown docs setup inside web-sveltekit and how to extend it.

The in-app docs run on local Markdown files loaded through SvelteKit, not Nuxt Content.

## What is included

- Route-backed docs pages under `/docs` and `/docs/[slug]` (plus `/zh-CN/docs/*`)
- Markdown files stored under `src/content/docs/`
- English and Simplified Chinese collections under `en/` and `zh/`
- SEO metadata and sitemap coverage for the docs routes
- Shared sidebar navigation generated from the same content source

## Locale behavior

The public site currently launches in English and Simplified Chinese. The docs source follows the same rule: English is always available, Simplified Chinese is added where it exists.

## How to add a page

1. Add a markdown file under `src/content/docs/en/`
2. Add the matching Chinese file under `src/content/docs/zh/` if you want localized content
3. Use frontmatter for `title`, `label`, `description`, and `order`

```md
---
title: Billing guide
label: Billing
description: Explain plans, invoices, and credits.
order: 4
---

## Overview

Add your content here.
```

## Where to extend next

If docs volume grows, the next step is search, richer navigation metadata, or a remote content source — while keeping the same public `/docs` routes and frontmatter shape.

## Footer configuration

URL: https://sveltekit.zship.ai/docs/footer-configuration

Locale: en

Summary: Configure footer brand copy, contact email, social links, navigation columns, legal text, and copyright from zship.app.json.

The `web-sveltekit` footer is manifest-driven. Edit `apps/web-sveltekit/zship.app.json` and keep the footer content inside the top-level `footer` object.

Do not hardcode footer copy, links, or legal text in `SiteFooter.svelte`. The component should only render `siteConfig.footer`.

## Footer fields

```json
{
  "footer": {
    "brandDisplay": "logo-and-site-name",
    "contactEmail": "support@example.com",
    "description": [
      {
        "en": "Short product promise for the footer.",
        "zh-CN": "底部展示的简短产品说明。"
      }
    ],
    "socialLinks": [
      {
        "labelKey": "footer_github",
        "to": "https://github.com/your-org/your-repo",
        "external": true,
        "icon": "i-simple-icons-github"
      }
    ],
    "sections": [
      {
        "titleKey": "footer_section_product",
        "items": [
          {
            "labelKey": "nav_pricing",
            "to": "/pricing"
          }
        ]
      }
    ],
    "disclaimer": [
      {
        "en": "Optional legal or trademark disclaimer.",
        "zh-CN": "可选的法律或商标免责声明。"
      }
    ],
    "copyright": "© {year} {siteName}"
  }
}
```

## Field reference

- `brandDisplay`: controls brand rendering. Use `logo-and-site-name`, `logo-only`, or `site-name-only`.
- `contactEmail`: footer-specific email. Set it to an empty string to hide the email row. If the key is omitted, the app falls back to the top-level `contactEmail`.
- `description`: one or more footer description lines. Use localized objects when the public site supports multiple locales.
- `socialLinks`: optional social buttons. Each item needs `to` and either `labelKey` or localized `label`. Use an empty array to hide them.
- `sections`: navigation columns. Each section uses `titleKey` or `label`, and each item uses `labelKey` or `label` plus `to`.
- `disclaimer`: legal or trademark text shown in the bottom row. Use an empty array to hide it.
- `copyright`: bottom-left copyright text. It supports `{year}`, `{siteName}`, and `{brandName}` tokens. Set it to an empty string to hide it.

## Labels and localization

Use `labelKey` when a label already exists in `apps/web-sveltekit/src/lib/i18n.ts` footer labels:

```json
{
  "labelKey": "footer_support",
  "to": "/docs/support-and-refund"
}
```

Use localized `label` when the link is app-specific:

```json
{
  "label": {
    "en": "Changelog",
    "zh-CN": "更新日志"
  },
  "to": "/blog/changelog"
}
```

Localized text objects can include `en`, `zh-CN`, `zh-TW`, or `default`. If the active locale is missing, the resolver falls back to the default locale or the first non-empty value.

## Link rules

- Internal routes should start with `/`, for example `/pricing` or `/docs/quick-start`.
- Hash links can use `/#section-id`.
- External links should set `"external": true`.
- Internal non-page assets such as `/llms.txt` can set `"localize": false` to keep the exact URL.
- `mailto:` links are allowed, but footer email is usually clearer through `footer.contactEmail`.

## Launch checklist

Before publishing the site:

- Confirm `footer.description` no longer references the template if the product has been renamed.
- Confirm `footer.contactEmail` reaches a real support mailbox.
- Confirm every `footer.sections[].items[].to` route exists.
- Confirm external links open the expected brand accounts.
- Confirm `footer.disclaimer` matches your legal and trademark policy.
- Run `pnpm --filter @zship/web-sveltekit check`.

## Introduction

URL: https://sveltekit.zship.ai/docs/introduction

Locale: en

Summary: What the SvelteKit template already ships today, and where to customize it.

The `web-sveltekit` app is the SvelteKit frontend option in ZShip. It keeps landing pages, pricing, auth, blog, docs, and dashboard routes in one Cloudflare Workers deployment.

## What ships today

- SvelteKit SSR plus server routes under `src/routes/api/*`
- Built-in dual-locale public pages (English + Simplified Chinese), sitemap, robots, and llms.txt
- Shared landing UI, auth pages, dashboard routes, analytics consent, and localized navigation

## Where to customize it

- `apps/web-sveltekit/zship.app.json` controls `appKey`, domain, brand metadata, analytics IDs, `dashboard.url`, and `dashboard.features.*`
- `apps/web-sveltekit/src/lib/site.ts` turns the manifest into runtime `siteConfig`
- `apps/web-sveltekit/src/content/docs/*` is the Markdown source for the in-app docs
- `apps/web-sveltekit/src/routes/api/*` is where server-side BFF proxy routes live

## Skills-first customization

If you want to modify `web-sveltekit` through prompt-driven vibe coding, start with `Skills & vibe coding`. That page explains which repo skill to invoke for in-place template edits versus when to copy the app first and customize the copy.

Set `dashboard.features.checkin`, `dashboard.features.tickets`, `dashboard.features.referral`, or `dashboard.features.enterpriseBilling` to `false` when the dashboard should hide that entry and reject direct route access.

## When to use this frontend

Choose `web-sveltekit` when your team wants one SvelteKit codebase for marketing, product, and server-side proxy logic, with clear configuration points for turning the template into a branded public site.

## Quick start

URL: https://sveltekit.zship.ai/docs/quick-start

Locale: en

Summary: Go from first visit to live demo, dashboard activation, and launch-ready trust surfaces.

This guide is for teams evaluating the SvelteKit template and for builders preparing the first public launch.

## 1. Verify the public funnel

- Open the landing page while signed out and make sure the hero CTA can send visitors to `/guest-demo` or `/login`.
- Sign in and confirm the dashboard entry opens `/dashboard`.
- Confirm the public header exposes pricing, docs, support, and blog.
- Check that the footer shows a working contact email and a support entry.

## 2. Verify the product activation path

- Visit `/guest-demo` and confirm a real guest session is provisioned.
- Continue into `/dashboard/ai-playground` and make sure the same session still works.
- Open `/dashboard` and confirm the homepage acts as an activation page instead of a plain account summary.

## 3. Verify auth and account conversion

- Register a new account through `/auth/register` (or `/login`).
- Make sure the post-login redirect lands in the dashboard and keeps the activation cards visible.
- Confirm guest users can upgrade into a registered account without losing the main product path.

## 4. Verify credits and billing

- Check `/pricing` for live plan data.
- Open `/dashboard` credits/orders surfaces and confirm balances match the current session.
- Review subscription and order status after a sandbox checkout when pay-service is configured.

## 5. Launch checklist before going public

- Update `apps/web-sveltekit/zship.app.json` with the correct `domain`, `siteUrl`, `tagline`, and `contactEmail`.
- Configure the `footer` block in `apps/web-sveltekit/zship.app.json`; see `Footer configuration` for the field-by-field reference.
- Review `dashboard.url` and `dashboard.features.*` in `apps/web-sveltekit/zship.app.json` so the dashboard only exposes the flows your product actually supports.
- Review `seo.landingTitle` and `seo.landingDescription` in `apps/web-sveltekit/zship.app.json` carefully — they become the homepage's primary keyword signals; audit them before you go live and before you submit the sitemap.
- Configure `analytics.*` only when you are ready; scripts stay unloaded until consent when the banner is enabled.
- Replace placeholder branding assets in `static/`.
- Run `pnpm --filter @zship/web-sveltekit check` and `pnpm --filter @zship/web-sveltekit build` before deploy.
- Review the docs pages in this help center so support and billing expectations match your product.

## Local development

```bash
pnpm --filter @zship/web-sveltekit dev
```

Default dev port is `4329`.

## Recommended next reads

- `Skills & vibe coding`
- `Billing and credits`
- `Footer configuration`
- `Auth and guest mode`
- `Analytics`
- `AI playground`
- `Support and refund`

## Skills & vibe coding

URL: https://sveltekit.zship.ai/docs/skills-and-vibe-coding

Locale: en

Summary: Use repo skills to customize apps/web-sveltekit with prompt-driven edits instead of starting from a blank spec.

`web-sveltekit` is designed for prompt-driven customization. Describe the product change in natural language, then map the request onto the right files and shared packages.

## Recommended skill stack

- `$onboard`
  Use first when you need the repo map or want to confirm which layer owns a feature.
- `$create-app`
  Use when you want a separate frontend copied from `apps/web-sveltekit` instead of modifying the template in place.
- `$customize-brand`
  Use after copying the app, or when the change is mostly manifest-driven branding and SEO.
- `$add-page`
  Use when the new product surface needs its own route.
- `$add-dashboard`
  Use when the user dashboard needs a new feature tab or activation area.

## In-place editing vs copied app

Edit `apps/web-sveltekit` directly when this template itself is the working frontend for demos or platform work.

Use `$create-app` first if you want tenant isolation, a new package name, or a product frontend with its own release cadence. After that, use the other skills against the copied app.

## Main edit surfaces

- `apps/web-sveltekit/zship.app.json`
  Brand identity, SEO, footer, analytics, dashboard feature flags.
- `apps/web-sveltekit/src/lib/components/LandingPage.svelte`
  Hero, capability grid, workflow, FAQ, closing CTA.
- `apps/web-sveltekit/src/routes/pricing/+page.svelte`
  Pricing layout and checkout entry.
- `apps/web-sveltekit/src/content/docs/*`
  User-facing docs content in English and Simplified Chinese.
- `apps/web-sveltekit/src/routes/api/*`
  Public-page server proxies (BFF).

When a request clearly belongs to a shared backend package or worker, explain that boundary before turning a local page tweak into a platform change.

## Example prompts

- `Turn the web-sveltekit landing hero into a waitlist-first launch page for an AI video tool.`
- `Simplify the dashboard home so the primary action is opening AI Playground.`
- `Add a docs page about API keys and link it in the existing docs list.`
- `Adjust pricing for annual plans only and update the CTA language across the landing page.`
- `Use $create-app NAME=my-product to fork web-sveltekit, then use $customize-brand APP=apps/my-product to replace the default branding.`

## Practical workflow

1. Start from the repo root.
2. Invoke the skill explicitly in your prompt when available.
3. Describe the product change, not just the file name.
4. Inspect the current implementation before patching.
5. Verify the affected route after the change lands (`check` + `build`).

That approach keeps the work close to the real codebase and makes `web-sveltekit` feel like a modifiable product surface instead of a frozen template.

## Support and refund

URL: https://sveltekit.zship.ai/docs/support-and-refund

Locale: en

Summary: Where users should go for help, how refunds are handled, and what to expose on the public site.

Support should be visible before a user gets stuck. In ZShip, support is part of the public trust surface and part of the signed-in product flow.

## Public support surfaces

- Header navigation should expose a support entry
- Footer should expose a contact email from `zship.app.json` (`contactEmail` / `footer.contactEmail`)
- Docs should explain refunds and help expectations in plain language
- Legal pages keep the same contact email for trust continuity

## Signed-in support surfaces

- `/dashboard/support` or `/dashboard/tickets` for product and account help
- Dashboard orders for purchase history and refund requests
- Dashboard subscription for plan status before contacting support

## Refund guidance

Refund handling should be predictable:

- explain when users should request refunds
- point them to the correct ticket flow
- keep plan and order information easy to inspect before they contact you

## What to customize before launch

- `contactEmail` in `apps/web-sveltekit/zship.app.json`
- support copy in pricing, docs, and dashboard pages
- internal process for ticket response times and refund review

## AI playground

URL: https://sveltekit.zship.ai/zh-CN/docs/ai-playground

Locale: zh-CN

Summary: 说明 web-sveltekit 中统一 AI 入口与积分、API Key、访客会话之间的关系。

`/dashboard/ai-playground` 是 `web-sveltekit` 中统一的 AI 入口。

## 为什么重要

ZShip 把 AI playground 作为推荐产品路径，因为它已经理解：

- 登录状态
- 访客会话
- 可用积分
- API Key 生命周期
- 生成历史与 provider 相关输入

## 推荐用户路径

1. 从 `/guest-demo` 或 `/dashboard` 开始
2. 打开 `/dashboard/ai-playground`
3. 生成第一次结果
4. 用量增长后再升级为正式账号或更高套餐

## 产品团队应避免

- 不要在用户理解产品之前就要求粘贴手动 API Key。
- 不要暴露多个互相竞争的 AI 入口，除非受众明确不同。
- 不要把积分、AI 生成与账号状态拆到互不关联的页面，且缺少默认引导路径。

## Analytics

URL: https://sveltekit.zship.ai/zh-CN/docs/analytics

Locale: zh-CN

Summary: 说明 web-sveltekit 如何接入 GA4、Plausible 和 Clarity，以及 consent 门控。

`web-sveltekit` 支持从 `zship.app.json` 配置可选的 analytics provider。

## 支持的 provider

- Google Analytics 4，通过 `analytics.googleAnalytics.measurementId`
- Plausible，通过 `analytics.plausible.domain`
- Microsoft Clarity，通过 `analytics.clarity.projectId`

## Consent 流程

第三方 analytics 脚本**默认不会**注入。当至少配置了一个 provider，且 `analytics.consentBanner.enabled` 为 `true` 时，应用会展示 consent banner，并在用户做出选择后才加载对应脚本。

- Consent 通过 cookie（`zship_analytics_consent`）与 `localStorage` 持久化
- 客户端工具位于 `src/lib/client/analytics.ts`（`setAnalyticsConsent`、`trackAnalyticsEvent`、`trackAnalyticsPageView`）
- Banner UI 为 `src/lib/components/AnalyticsConsentBanner.svelte`
- 后续可在同一层扩展区域化 consent 或第一方代理

```json
{
  "analytics": {
    "consentBanner": {
      "enabled": true
    },
    "googleAnalytics": {
      "measurementId": "G-XXXXXXXXXX"
    },
    "plausible": {
      "domain": "sveltekit.zship.ai",
      "scriptSrc": "",
      "apiEndpoint": ""
    },
    "clarity": {
      "projectId": "your-clarity-project-id"
    }
  }
}
```

模板中请保持 provider ID 为空，直到你准备好上线统计。空 ID 意味着不加载脚本、也不展示 banner。

## 后续改进路径

如果生产环境需要更严格的合规控制，建议继续补上专门的 consent center，或走第一方代理后再启用 provider ID。

## 认证与访客

URL: https://sveltekit.zship.ai/zh-CN/docs/auth-and-guest-mode

Locale: zh-CN

Summary: 理解登录、访客访问、账号升级，以及各路径应把用户带到哪里。

SvelteKit 模板同时支持正式账号与访客会话，目标是在用户注册前降低摩擦。

## 正式账号流程

- 公开入口：`/auth/login`、`/auth/register` 与 `/login`
- 当前支持邮箱；后续阶段可配置 Google/GitHub OAuth
- 登录后目的地：`/dashboard`

正式用户应落在偏激活的控制台首页，再进入 AI、密钥、计费或支持。

## 访客流程

- 公开入口：`/guest-demo`
- 访客会话是真实已认证会话，拥有自己的积分与控制台访问
- 访客在验证主流程后应被引导升级

## 升级建议

访客模式适合：

- 早期产品演示
- 尚未准备注册的营销流量
- 需要低摩擦证明点的销售沟通

正式账号适合：

- 持续使用
- 计费与订阅
- API Key 管理
- 长期项目归属

## 产品建议

不要把访客模式做成死胡同沙箱。它应像一次有引导的首次会话，用户看到价值后自然走向注册。

## 计费

URL: https://sveltekit.zship.ai/zh-CN/docs/billing-and-credits

Locale: zh-CN

Summary: 说明 SvelteKit 模板中定价、积分、订阅与订单历史如何协作。

ZShip 以积分为产品级消耗单位，以套餐作为这些积分的商业包装。

## 用户可以做什么

- 在 `/pricing` 比较套餐
- 在控制台积分相关面查看当前余额
- 通过 pay-service BFF 查看订阅状态与历史订单

## 流程如何运转

1. 访客在定价页选择套餐。
2. 结账经 SvelteKit pay-service 代理创建（`src/routes/api/pay/*`）。
3. 支付成功后更新订阅状态与积分账本。
4. 控制台页面从同一后端状态读取最新余额与订单记录。

## 上线前要验证什么

- 定价标签与描述和 pay service 中配置的套餐一致。
- 积分数量对用户足够好理解。
- 退款预期已文档化，并在支持入口可找到。
- 支持团队清楚哪些案例走工单、哪些走支付服务商门户。

## 常见上线问题

### 何时把用户送到定价页？

积分不足、需要更高套餐，或想理解各档位权益时，把用户送到定价页。

### 退款请求应去哪里？

使用 `Support and refund` 中记录的支持流程。订单历史应提供足够上下文以发起产品级退款请求。

## 文档系统

URL: https://sveltekit.zship.ai/zh-CN/docs/docs-system

Locale: zh-CN

Summary: web-sveltekit 内的 Markdown 文档机制，以及如何扩展。

站内文档基于本地 Markdown，由 SvelteKit 加载，而不是 Nuxt Content。

## 已包含内容

- 路由页 `/docs` 与 `/docs/[slug]`（以及 `/zh-CN/docs/*`）
- Markdown 存放在 `src/content/docs/`
- 英文与简体中文分别在 `en/` 与 `zh/`
- 文档路由具备 SEO 元数据与 sitemap 覆盖
- 侧栏导航由同一内容源生成

## 语言行为

公开站目前启动英文与简体中文。文档源遵循同样规则：英文始终可用，简体中文按需提供。

## 如何新增一页

1. 在 `src/content/docs/en/` 添加 markdown
2. 如需中文，在 `src/content/docs/zh/` 添加同名文件
3. 使用 frontmatter 配置 `title`、`label`、`description`、`order`

```md
---
title: Billing guide
label: Billing
description: Explain plans, invoices, and credits.
order: 4
---

## Overview

在这里写正文。
```

## 下一步扩展

文档量增长后，可在保持公开 `/docs` 路由与 frontmatter 形状的前提下，增加搜索、更丰富的导航元数据或远端内容源。

## Footer 配置

URL: https://sveltekit.zship.ai/zh-CN/docs/footer-configuration

Locale: zh-CN

Summary: 通过 zship.app.json 配置 Footer 品牌文案、联系邮箱、社交链接、导航列、法律文案与版权信息。

`web-sveltekit` 的 Footer 是配置驱动的。请编辑 `apps/web-sveltekit/zship.app.json`，并把 Footer 相关内容放在顶层 `footer` 对象里。

不要在 `SiteFooter.svelte` 中硬编码文案、链接或法律声明。组件只应渲染 `siteConfig.footer`。

## Footer 字段

```json
{
  "footer": {
    "brandDisplay": "logo-and-site-name",
    "contactEmail": "support@example.com",
    "description": [
      {
        "en": "Short product promise for the footer.",
        "zh-CN": "底部展示的简短产品说明。"
      }
    ],
    "socialLinks": [
      {
        "labelKey": "footer_github",
        "to": "https://github.com/your-org/your-repo",
        "external": true,
        "icon": "i-simple-icons-github"
      }
    ],
    "sections": [
      {
        "titleKey": "footer_section_product",
        "items": [
          {
            "labelKey": "nav_pricing",
            "to": "/pricing"
          }
        ]
      }
    ],
    "disclaimer": [
      {
        "en": "Optional legal or trademark disclaimer.",
        "zh-CN": "可选的法律或商标免责声明。"
      }
    ],
    "copyright": "© {year} {siteName}"
  }
}
```

## 字段说明

- `brandDisplay`：控制品牌展示。可用 `logo-and-site-name`、`logo-only`、`site-name-only`。
- `contactEmail`：Footer 专用邮箱。设为空字符串可隐藏邮箱行；省略时回退到顶层 `contactEmail`。
- `description`：一行或多行说明，支持本地化对象。
- `socialLinks`：可选社交按钮。每项需要 `to`，以及 `labelKey` 或本地化 `label`。空数组表示隐藏。
- `sections`：导航列。每列用 `titleKey` 或 `label`，每项用 `labelKey` 或 `label` 加 `to`。
- `disclaimer`：底部法律/商标声明，空数组表示隐藏。
- `copyright`：左下版权文案，支持 `{year}`、`{siteName}`、`{brandName}`。空字符串表示隐藏。

## 标签与本地化

已有翻译建议复用 `apps/web-sveltekit/src/lib/i18n.ts` 中的 footer labels：

```json
{
  "labelKey": "footer_support",
  "to": "/docs/support-and-refund"
}
```

应用专属链接可用本地化 `label`：

```json
{
  "label": {
    "en": "Changelog",
    "zh-CN": "更新日志"
  },
  "to": "/blog/changelog"
}
```

本地化对象可包含 `en`、`zh-CN`、`zh-TW` 或 `default`。当前语言缺失时，会回退到默认语言或第一个非空值。

## 链接规则

- 内部路由应以 `/` 开头，例如 `/pricing` 或 `/docs/quick-start`。
- 锚点可用 `/#section-id`。
- 外链应设置 `"external": true`。
- `/llms.txt` 等非页面资源可设 `"localize": false` 保持原 URL。
- 允许 `mailto:`，但联系邮箱通常更适合走 `footer.contactEmail`。

## 上线检查清单

发布前确认：

- `footer.description` 在产品改名后不再引用模板文案。
- `footer.contactEmail` 指向真实支持邮箱。
- 每个 `footer.sections[].items[].to` 路由真实存在。
- 外链打开正确的品牌账号。
- `footer.disclaimer` 符合法律与商标策略。
- 执行 `pnpm --filter @zship/web-sveltekit check`。

## 简介

URL: https://sveltekit.zship.ai/zh-CN/docs/introduction

Locale: zh-CN

Summary: SvelteKit 模板当前已内置的能力，以及从哪里开始自定义。

`web-sveltekit` 是 ZShip 中的 SvelteKit 前台选项。它把落地页、定价、认证、博客、文档和控制台路由放在同一个 Cloudflare Workers 部署里。

## 当前已包含

- SvelteKit SSR，以及 `src/routes/api/*` 下的服务端 BFF 代理
- 内置双语文案公开页（英文 + 简体中文）、sitemap、robots 与 llms.txt
- 共享落地页、认证页、控制台、Analytics consent 与本地化导航

## 从哪里改

- `apps/web-sveltekit/zship.app.json` 负责 `appKey`、域名、品牌信息、analytics ID、`dashboard.url` 与 `dashboard.features.*`
- `apps/web-sveltekit/src/lib/site.ts` 把 manifest 转成运行时 `siteConfig`
- `apps/web-sveltekit/src/content/docs/*` 是站内文档的 Markdown 源
- `apps/web-sveltekit/src/routes/api/*` 是服务端 BFF 代理路由

## 优先用 Skills 自定义

如果你想通过 prompt 驱动改造 `web-sveltekit`，先看 `Skills & vibe coding`。那一页说明了何时原地改模板，何时先复制再定制。

当控制台需要隐藏某个入口并拦截直链时，把 `dashboard.features.checkin`、`dashboard.features.tickets`、`dashboard.features.referral` 或 `dashboard.features.enterpriseBilling` 设为 `false`。

## 何时选择这个前台

当你的团队希望用一套 SvelteKit 代码同时承载营销、产品与服务端代理逻辑，并希望通过清晰配置点把模板变成品牌公开站时，选择 `web-sveltekit`。

## 快速开始

URL: https://sveltekit.zship.ai/zh-CN/docs/quick-start

Locale: zh-CN

Summary: 从首次访问到演示、控制台激活与上线前信任面检查。

本指南面向评估 SvelteKit 模板的团队，以及准备第一次公开上线的构建者。

## 1. 验证公开漏斗

- 未登录打开落地页，确认 Hero CTA 可进入 `/guest-demo` 或 `/login`。
- 登录后确认控制台入口打开 `/dashboard`。
- 确认公开 Header 暴露定价、文档、支持与博客。
- 确认 Footer 展示可用联系邮箱与支持入口。

## 2. 验证产品激活路径

- 访问 `/guest-demo` 并确认真实访客会话已创建。
- 进入 `/dashboard/ai-playground`，确认同一会话仍然有效。
- 打开 `/dashboard`，确认首页更像激活页而不是纯账户摘要。

## 3. 验证认证与账号升级

- 通过 `/auth/register`（或 `/login`）注册新账号。
- 确认登录后跳转进入控制台，激活卡片仍然可见。
- 确认访客可以升级为正式账号且不丢失主产品路径。

## 4. 验证积分与计费

- 检查 `/pricing` 是否能加载真实套餐数据。
- 打开控制台积分/订单相关面，确认余额与当前会话一致。
- 在 pay-service 配置就绪时，用 sandbox 走完结账并检查订阅与订单状态。

## 5. 上线前清单

- 更新 `apps/web-sveltekit/zship.app.json` 中的 `domain`、`siteUrl`、`tagline`、`contactEmail`。
- 配置 `footer` 块；字段说明见 `Footer configuration`。
- 检查 `dashboard.url` 与 `dashboard.features.*`，只暴露产品真正支持的流程。
- 仔细审核 `seo.landingTitle` 与 `seo.landingDescription`——它们会成为首页主关键词信号；上线与提交 sitemap 前务必检查。
- 仅在准备好时配置 `analytics.*`；开启 consent banner 后，脚本在用户同意前不会加载。
- 替换 `static/` 中的占位品牌资源。
- 部署前运行 `pnpm --filter @zship/web-sveltekit check` 与 `pnpm --filter @zship/web-sveltekit build`。
- 检查本帮助中心文档，使支持与计费预期与产品一致。

## 本地开发

```bash
pnpm --filter @zship/web-sveltekit dev
```

默认开发端口为 `4329`。

## 推荐继续阅读

- `Skills & vibe coding`
- `Billing and credits`
- `Footer configuration`
- `Auth and guest mode`
- `Analytics`
- `AI playground`
- `Support and refund`

## Skills 与 vibe coding

URL: https://sveltekit.zship.ai/zh-CN/docs/skills-and-vibe-coding

Locale: zh-CN

Summary: 通过 repo skills 用自然语言驱动修改 apps/web-sveltekit，而不是从空白规格起步。

`web-sveltekit` 适合 prompt 驱动改造：先用自然语言描述产品改动，再映射到正确的文件与共享包。

## 推荐 skill 组合

- `$onboard`
  需要仓库地图、或确认某功能属于哪一层时先用。
- `$create-app`
  不想直接改模板，而是从 `apps/web-sveltekit` 复制独立前台时使用。
- `$customize-brand`
  复制后做品牌/SEO，或改动主要是 manifest 配置时使用。
- `$add-page`
  新产品面需要独立路由时使用。
- `$add-dashboard`
  用户控制台需要新功能页或激活区时使用。

## 原地改 vs 复制后改

当 `apps/web-sveltekit` 本身就是演示或平台工作前台时，可直接原地修改。

如果需要租户隔离、新包名，或独立发版节奏，先用 `$create-app` 复制，再对复制后的 app 使用其他 skills。

## 主要改动面

- `apps/web-sveltekit/zship.app.json`
  品牌信息、SEO、footer、analytics、dashboard feature 开关。
- `apps/web-sveltekit/src/lib/components/LandingPage.svelte`
  Hero、能力网格、工作流、FAQ、收尾 CTA。
- `apps/web-sveltekit/src/routes/pricing/+page.svelte`
  定价布局与结账入口。
- `apps/web-sveltekit/src/content/docs/*`
  英/中用户文档。
- `apps/web-sveltekit/src/routes/api/*`
  公开页服务端代理（BFF）。

若请求明显属于共享后端包或 Worker，应先说明边界，再决定是否把局部页面改动升级为平台改动。

## 示例 prompt

- `把 web-sveltekit 落地页 hero 改成 waitlist 优先的 AI 视频工具上线页。`
- `简化 dashboard 首页，让主操作打开 AI Playground。`
- `新增一篇关于 API Key 的文档页，并挂到现有文档列表。`
- `定价只保留年付，并同步更新落地页 CTA 文案。`
- `Use $create-app NAME=my-product to fork web-sveltekit, then use $customize-brand APP=apps/my-product to replace the default branding.`

## 实用流程

1. 从仓库根目录开始。
2. 有 skill 时在 prompt 中明确调用。
3. 描述产品改动，而不是只报文件名。
4. 改动前先阅读现有实现。
5. 改完后在对应路由上验证（`check` + `build`）。

这样可以把 `web-sveltekit` 当作可修改的产品面，而不是冻结模板。

## 支持与退款

URL: https://sveltekit.zship.ai/zh-CN/docs/support-and-refund

Locale: zh-CN

Summary: 用户应去哪里求助、退款如何处理，以及公开站应暴露哪些信任面。

支持入口应在用户卡住之前就可见。在 ZShip 中，支持既是公开信任面的一部分，也是登录后产品流程的一部分。

## 公开支持面

- Header 导航应暴露支持入口
- Footer 应展示来自 `zship.app.json` 的联系邮箱（`contactEmail` / `footer.contactEmail`）
- 文档应用通俗语言说明退款与帮助预期
- 法律页使用同一联系邮箱以保持信任连续性

## 登录后支持面

- `/dashboard/support` 或 `/dashboard/tickets` 处理产品与账号问题
- 控制台订单用于购买历史与退款请求
- 控制台订阅用于联系支持前查看套餐状态

## 退款指引

退款处理应可预期：

- 说明何时应申请退款
- 引导到正确的工单流程
- 在用户联系你之前，让套餐与订单信息易于查看

## 上线前要自定义什么

- `apps/web-sveltekit/zship.app.json` 中的 `contactEmail`
- 定价、文档与控制台页面中的支持文案
- 工单响应时效与退款审核的内部流程

# Blog

# Legal and Policies

## Content Policy

URL: https://sveltekit.zship.ai/content-policy

Updated: 2026-06-15

Summary: Rules for prompts, uploads, generated outputs, API usage, and support content submitted through the app.

## Allowed use

Use the product for lawful software, productivity, content, research, and business workflows.

You remain responsible for reviewing AI output before relying on it or publishing it.

## Restricted content

Do not submit content that enables abuse, credential theft, malware, exploitation, harassment, or illegal activity.

Do not upload secrets, regulated personal data, or third-party confidential material unless you are authorized to process it.

## Enforcement

The service may rate-limit, block, remove, or suspend content and accounts that violate this policy.

Support tickets and usage records may be reviewed when investigating safety, security, or payment issues.

## Privacy Policy

URL: https://sveltekit.zship.ai/privacy

Updated: 2026-06-15

Summary: How the SvelteKit app handles account, payment, support, analytics, and AI request information.

## Crisp support chat

When optional support chat is enabled and consent permits it, Crisp may receive the project identifier, conversation or guest identifier, email address, display name, profile image, and messages sent through chat.

You can decline Crisp loading through the consent prompt; support chat data is then handled by Crisp under its role as a customer-support service provider.

## Data we process

The app can process account identifiers, email addresses, session cookies, guest fingerprints, billing status, support messages, API keys, and usage records.

Payment details are handled by the configured provider; the app stores provider references and order state rather than raw card data.

## How data is used

Data is used to authenticate users, deliver credits and subscriptions, route support requests, prevent abuse, and operate AI workflows.

Service logs and analytics may be used to debug failures, improve reliability, and understand aggregate product usage.

## Retention and access

Operational records are retained for account, security, financial, and support needs.

Users can contact support to request access, correction, or deletion where applicable.

## Refund Policy

URL: https://sveltekit.zship.ai/refund

Updated: 2026-06-15

Summary: Refund expectations for subscriptions, credit packs, checkout failures, and support review.

## Eligible requests

Refunds can be reviewed for duplicate charges, accidental purchases, billing errors, or major service failures.

Consumed credits, completed usage, promotional balances, and abuse-related suspensions may be ineligible.

## How to request a refund

Open a support ticket from the dashboard with the order ID, account email, purchase date, and a short explanation.

The support workflow should verify provider status before changing account credits or subscription state.

## Processing

Approved refunds are returned through the original payment provider when possible.

Credit adjustments may be applied separately from provider refunds to keep usage balances accurate.

## Terms of Service

URL: https://sveltekit.zship.ai/terms

Updated: 2026-06-15

Summary: The baseline terms for using ZShip SvelteKit accounts, checkout, credits, API keys, and AI workflows.

## Use of the service

You are responsible for the activity under your account, API keys, and guest sessions.

Do not abuse, disrupt, reverse engineer, or use the service in a way that violates applicable law or third-party rights.

## Plans, credits, and billing

Paid plans, one-time credit packs, and subscriptions are processed through the configured payment provider.

Credits may be metered, reset, expire, or be adjusted according to the plan shown at checkout.

## Availability and changes

The service may change as backend workers, models, providers, and product workflows evolve.

We may limit or suspend access when activity creates operational, security, payment, or policy risk.