# jevnotes

> Production-ready Nuxt AI SaaS site with auth, billing, docs, dashboard, and AI workflows.

Site: https://jevnotes.com

This file is generated from the current Nuxt Content docs/blog sources and configured site metadata.

# Core Pages

## jevnotes

URL: https://jevnotes.com/

Summary: Production-ready Nuxt AI SaaS site with auth, billing, docs, dashboard, and AI workflows.

Production-ready Nuxt AI SaaS site with auth, billing, docs, dashboard, and AI workflows.

## Pricing

URL: https://jevnotes.com/pricing

Summary: Plans, billing options, and credit packaging for the product.

Plans, billing options, and credit packaging for the product.

## Documentation

URL: https://jevnotes.com/docs

Summary: Product documentation and implementation guides.

Product documentation and implementation guides.

## Blog

URL: https://jevnotes.com/blog

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

Product updates, implementation notes, and launch articles.

# Documentation

## Introduction

URL: https://jevnotes.com/docs/introduction

Locale: en

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

The `web-nuxt` app is the Nuxt 4 frontend option in ZShip. It keeps landing pages, pricing, auth, blog, docs, and dashboard routes in one deployment.

### What ships today

- Nuxt SSR plus Nitro server proxy routes under `server/api/*`
- Built-in i18n, sitemap, robots, schema.org, ISR route rules, and image optimization
- Shared landing UI, auth pages, dashboard routes, and localized navigation

### Where to customize it

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

### Skills-first customization

If you want to modify `web-nuxt` 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`, or `dashboard.features.referral` to `false` when the Nuxt dashboard should hide that entry and reject direct route access.

### When to use this frontend

Choose `web-nuxt` when your team wants one Nuxt 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://jevnotes.com/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 Nuxt 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 sends visitors to `/guest-demo`.
- Sign in and confirm the same hero CTA 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`.
- 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` and confirm the balance matches the current session.
- Review `/dashboard/subscription` and `/dashboard/orders` to verify billing history and plan status.

### 5. Launch checklist before going public

- Update `apps/web-nuxt/zship.app.json` with the correct `domain`, `siteUrl`, `tagline`, and `contactEmail`.
- Configure the `footer` block in `apps/web-nuxt/zship.app.json`; see `Footer configuration` for the field-by-field reference.
- Review `dashboard.url` and `dashboard.features.checkin`, `dashboard.features.tickets`, `dashboard.features.referral` in `apps/web-nuxt/zship.app.json` so the dashboard only exposes the flows your product actually supports.
- Review `seo.landingTitle` and `seo.landingDescription` in `apps/web-nuxt/zship.app.json` carefully, since they become the homepage's primary keyword signals; audit them before you go live and before you submit the sitemap.
- Replace placeholder branding assets in `public/`.
- Before launch, open Admin `/launch-check`; it verifies the selected project's Admin settings, backend fallbacks, service bindings, AI, Provider1, CDN/R2, pricing, and support surfaces.
- Review the docs pages in this help center so support and billing expectations match your product.

### Recommended next reads

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

## Billing

URL: https://jevnotes.com/docs/billing-and-credits

Locale: en

Summary: How pricing, credits, subscriptions, and order history fit together in the Nuxt 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 on `/dashboard/credits`
- Inspect active subscription status on `/dashboard/subscription`
- Review previous purchases on `/dashboard/orders`

### How the flow works

1. The visitor chooses a plan on the pricing page.
2. Checkout is created through the pay-service proxy.
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`. The dashboard order history already exposes refund requests as a product-level action.

## Skills & vibe coding

URL: https://jevnotes.com/docs/skills-and-vibe-coding

Locale: en

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

`web-nuxt` now has a dedicated skills entry for prompt-driven customization. The goal is simple: let a builder describe the product change in natural language, then let Codex map that request onto the right files and shared layers.

### Recommended skill stack

- `$onboard` Use first when you need the repo map or want to confirm which layer owns a feature.
- `$customize-web-nuxt` Use when you are editing `apps/web-nuxt` directly: landing hero, pricing, docs, auth, guest-demo, dashboard entry flow, or app-level proxy routes.
- `$create-app` Use when you want a separate frontend copied from `apps/web-nuxt` 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

Use `$customize-web-nuxt` when `apps/web-nuxt` itself is the working frontend.

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-nuxt/zship.app.json` Brand identity, SEO, footer, analytics, dashboard feature flags.
- `apps/web-nuxt/app/components/LandingPage.vue` Hero, CTA flow, marketing sections, testimonials, closing CTA.
- `apps/web-nuxt/app/pages/pricing.vue` Pricing layout, comparison table, sales CTA.
- `apps/web-nuxt/content/docs/*` User-facing docs content in English and Simplified Chinese.
- `apps/web-nuxt/server/api/*` Public-page server proxies.

When a request clearly belongs to `packages/nuxt-common-layer` or `packages/nuxt-ai-layer`, Codex should explain that boundary before turning a local page tweak into a shared-platform change.

### Example prompts

- `Use $customize-web-nuxt to turn the landing hero into a waitlist-first launch page for an AI video tool.`
- `Use $customize-web-nuxt to simplify the dashboard home so the primary action is opening AI Playground.`
- `Use $customize-web-nuxt to add a docs page about API keys and link it in the existing docs list.`
- `Use $customize-web-nuxt to adjust pricing for annual plans only and update the CTA language across the landing page.`
- `Use $create-app NAME=my-product to fork web-nuxt, 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.
3. Describe the product change, not just the file name.
4. Let Codex inspect the current implementation before patching.
5. Ask for verification on the affected route after the change lands.

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

## Auth and guest mode

URL: https://jevnotes.com/docs/auth-and-guest-mode

Locale: en

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

The Nuxt 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` and `/auth/register`
- Supported modes: email, verification code, Google, GitHub
- 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.

## AI workspace

URL: https://jevnotes.com/docs/ai-playground

Locale: en

Summary: The user-facing Chat, Studio, and Usage surfaces in web-nuxt.

`web-nuxt` exposes a complete AI workspace instead of routing every workflow into one playground:

- `/dashboard/ai-chat` is the persistent conversational product surface, including history and multi-turn continuation.
- `/dashboard/ai-playground` is AI Studio for image, video, audio, and other structured generation workflows.
- `/dashboard/usage` combines Chat and provider generation usage, including image, video, audio, requests, tokens, credits, daily activity, and model breakdown.

### Why it matters

All three surfaces share the same session lifecycle, so they already understand:

- auth state
- guest sessions
- available credits
- API key lifecycle
- conversation and generation history
- provider-specific inputs
- user-scoped usage and billing data

Site owners can keep the native Workers AI binding or configure any HTTPS OpenAI-compatible Base URL and API Key in the admin AI upstream settings. The credential remains server-side in `node10-ai-service`; users only see enabled models, never the upstream key.

### Recommended user path

1. Start from `/guest-demo` or `/dashboard`
2. Open `/dashboard/ai-chat` for conversational work or `/dashboard/ai-playground` for generation
3. Continue previous conversations or create the first result
4. Review `/dashboard/usage` before upgrading to a full account or a higher plan

### What product teams should avoid

- Do not ask first-time users to paste a manual API key before they understand the product.
- Do not collapse Chat and structured generation into competing interfaces; keep each entry point tied to a distinct job.
- Do not separate credits, AI generation, and account state into unrelated pages without a guided default path.

## Support and refund

URL: https://jevnotes.com/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
- Docs should explain refunds and help expectations in plain language

### Signed-in support surfaces

- `/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 `zship.app.json`
- support copy in pricing, docs, and dashboard pages
- internal process for ticket response times and refund review

## Analytics

URL: https://jevnotes.com/docs/analytics

Locale: en

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

`web-nuxt` now 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

Analytics scripts are no longer injected unconditionally. The app now waits for a consent decision before loading those providers.

- Consent is persisted with a cookie plus local storage
- A shared `useAnalytics()` wrapper exposes `track()` and page-view tracking
- You can extend the same layer later for region-aware consent or first-party proxying

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

### 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.

## Footer configuration

URL: https://jevnotes.com/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-nuxt` footer is manifest-driven. Edit `apps/web-nuxt/zship.app.json` and keep the footer content inside the top-level `footer` object.

Do not hardcode footer copy, links, or legal text in `LandingFooter.vue`. 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`: icon buttons shown under the contact email. Each item needs `to`, `icon`, and either `labelKey` or localized `label`. Use an empty array to hide all social buttons.
- `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-nuxt/app/i18n/ui.json`:

```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-nuxt exec nuxt prepare`.

## Docs system

URL: https://jevnotes.com/docs/docs-system

Locale: en

Summary: The Nuxt Content docs setup inside web-nuxt and how to extend it.

The in-app docs now run on Nuxt Content instead of a custom `marked` parser.

### What is included

- Route-backed docs pages under `/docs` and `/docs/[slug]`
- Markdown files stored under `content/docs/`
- `content.config.ts` collections for English and Simplified Chinese docs
- SEO metadata and prerender 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, and retired locale routes should redirect back to the canonical English or Simplified Chinese path.

### How to add a page

1. Add a markdown file under `content/docs/en/`
2. Add the matching Chinese file under `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 to build on the same Nuxt Content workflow with search, navigation metadata, or remote content sources instead of replacing the stack again.

## 模板概览

URL: https://jevnotes.com/zh-CN/docs/introduction

Locale: zh-CN

Summary: 说明 web-nuxt 当前已经具备什么，以及主要改动入口在哪里。

`web-nuxt` 是 ZShip 里的 Nuxt 4 前台方案，把 landing、pricing、auth、blog、docs 和 dashboard 放在同一个部署里。

### 当前已内置的能力

- Nuxt SSR + Nitro BFF，`server/api/*` 已代理常见后端请求
- 已接好 i18n、sitemap、robots、schema.org、ISR 路由规则和图片优化
- 已有 landing UI、认证页、仪表盘页，以及多语言导航

### 主要改动入口

- `apps/web-nuxt/zship.app.json` 负责 `appKey`、域名、品牌信息、analytics ID、`dashboard.url` 与 `dashboard.features.*`
- `apps/web-nuxt/app/config/site.ts` 把 manifest 转成运行时 `siteConfig`
- `apps/web-nuxt/content/docs/*` 是站内 Docs 的 Nuxt Content 内容源
- `apps/web-nuxt/server/api/*` 用于扩展服务端代理路由

### 用 skills 做 prompt 驱动改造

如果你希望通过自然语言 + vibe coding 的方式直接改 `web-nuxt`，先看 `Skills 与 vibe coding`。这页会说明什么时候该直接改模板，什么时候应该先复制出独立 app，再继续定制。

如果某个仪表盘功能不想对外暴露，可以把 `dashboard.features.checkin`、`dashboard.features.tickets` 或 `dashboard.features.referral` 设为 `false`，对应入口会隐藏，直接访问路由也会被拦住。

### 什么时候适合选它

如果你的团队希望用一个 Nuxt 工程同时承载营销页、产品页和服务端代理，同时保留清晰的配置入口，把模板改造成自己的品牌前台，`web-nuxt` 很合适。

## 快速开始

URL: https://jevnotes.com/zh-CN/docs/quick-start

Locale: zh-CN

Summary: 从首次访问到真实演示、仪表盘激活路径与对外发布前检查清单。

这篇指南面向两类人：正在评估 Nuxt 模板的团队，以及准备把 `web-nuxt` 作为正式前台对外上线的开发者。

### 1. 先验证公开转化链路

- 未登录时打开首页，确认主 CTA 指向 `/guest-demo`
- 登录后再次打开首页，确认同一个主 CTA 指向 `/dashboard`
- 检查头部导航是否能看到 pricing、docs、support、blog
- 检查 footer 是否展示正确的联系邮箱与支持入口

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

- 打开 `/guest-demo`，确认系统会创建真实访客会话
- 从 demo 继续进入 `/dashboard/ai-playground`，确认会话仍然有效
- 打开 `/dashboard`，确认首页已经是激活页，而不是普通账户总览

### 3. 验证登录与升级

- 通过 `/auth/register` 注册新账户
- 登录后确认会跳回仪表盘，并继续显示激活卡片
- 确认访客可以平滑升级为正式账户，而不会偏离主产品路径

### 4. 验证计费与积分

- 在 `/pricing` 检查套餐是否是实时数据
- 在 `/dashboard/credits` 检查积分余额是否与当前会话一致
- 在 `/dashboard/subscription` 和 `/dashboard/orders` 检查订阅与订单状态

### 5. 正式上线前必须替换的内容

- 在 `apps/web-nuxt/zship.app.json` 中补齐 `domain`、`siteUrl`、`tagline`、`contactEmail`
- 在 `apps/web-nuxt/zship.app.json` 中配置 `footer` 区块；字段说明见 `Footer 配置`
- 在 `apps/web-nuxt/zship.app.json` 中检查 `dashboard.url` 以及 `dashboard.features.checkin`、`dashboard.features.tickets`、`dashboard.features.referral`，确保仪表盘只暴露你的产品真正支持的功能入口
- 在 `apps/web-nuxt/zship.app.json` 中认真检查 `seo.landingTitle` 与 `seo.landingDescription`，它们会直接成为首页核心关键词信号；正式上线并提交 sitemap 前请逐字审核后再提交
- 替换 `public/` 下的品牌资源
- 上线前打开 Admin `/launch-check`，它会按项目检查管理端配置、后端 fallback、Service Binding、AI、Provider1、CDN/R2、价格和支持入口
- 逐页检查帮助中心文档，确保支持、退款与计费说明符合你的产品策略

### 推荐继续阅读

- `Skills 与 vibe coding`
- `计费与积分`
- `Footer 配置`
- `登录与访客模式`
- `AI Playground`
- `支持与退款`

## 计费与积分

URL: https://jevnotes.com/zh-CN/docs/billing-and-credits

Locale: zh-CN

Summary: 说明定价、积分、订阅与订单历史在 Nuxt 模板中的关系。

ZShip 以前台的积分作为产品消耗单位，再用套餐和订阅来承载商业化。

### 用户能做什么

- 在 `/pricing` 对比套餐
- 在 `/dashboard/credits` 查看当前积分余额
- 在 `/dashboard/subscription` 查看订阅状态
- 在 `/dashboard/orders` 查看购买记录

### 一次完整链路如何工作

1. 用户在定价页选择套餐
2. 通过支付服务代理创建结账流程
3. 支付成功后更新订阅状态与积分账本
4. 仪表盘相关页面读取同一套后端数据并展示结果

### 上线前应重点确认

- 套餐文案与支付后台配置保持一致
- 用户能清楚理解每个套餐对应多少积分
- 退款预期在支持文档中有明确说明
- 支持团队知道哪些问题走工单，哪些问题交给支付门户处理

### 常见产品决策

#### 什么时候该把用户带去 pricing？

当用户积分不足、套餐不匹配，或者需要先理解商业模式时，都应该把他们带到 pricing。

#### 退款入口应该放在哪里？

建议统一走 `支持与退款` 文档说明的路径。订单页已经提供了产品侧的退款申请动作。

## Skills 与 vibe coding

URL: https://jevnotes.com/zh-CN/docs/skills-and-vibe-coding

Locale: zh-CN

Summary: 通过 repo 里的 skills，用自然语言驱动方式修改和自定义 apps/web-nuxt。

`web-nuxt` 现在补了一套更适合 prompt 驱动改造的 skills 入口。目标很直接：让使用者先描述产品改动，再由 Codex 把请求映射到正确的页面、配置文件和共享层，而不是从一堆文件名开始猜。

### 推荐的 skills 组合

- `$onboard` 先看仓库分层、确认某个功能到底归哪个 layer。
- `$customize-web-nuxt` 当你就是要直接修改 `apps/web-nuxt` 本体时使用。适合 landing hero、pricing、docs、auth、guest-demo、dashboard 激活路径、前台代理路由等改动。
- `$create-app` 当你不想继续直接改模板，而是希望先从 `apps/web-nuxt` 复制出一个独立前台时使用。
- `$customize-brand` 适合复制出独立 app 之后做品牌、SEO、footer、manifest 级配置。
- `$add-page` 适合新增独立页面和路由。
- `$add-dashboard` 适合给用户仪表盘增加新的功能页或新入口。

### 什么时候直接改模板，什么时候先复制

如果当前工作对象就是 `apps/web-nuxt`，直接用 `$customize-web-nuxt`。

如果你需要租户隔离、独立包名，或者希望产品前台拥有自己的发布节奏，就先用 `$create-app` 复制，再对复制出来的 app 使用其它 skills。

### 最常见的改动面

- `apps/web-nuxt/zship.app.json` 品牌信息、SEO、footer、analytics、dashboard feature 开关。
- `apps/web-nuxt/app/components/LandingPage.vue` 首页 hero、CTA、营销区块、社证内容、尾部 CTA。
- `apps/web-nuxt/app/pages/pricing.vue` 定价页结构、对比表、销售 CTA。
- `apps/web-nuxt/content/docs/*` 中英文站内文档内容。
- `apps/web-nuxt/server/api/*` 前台页面用到的服务端代理。

如果某个改动明显属于 `packages/nuxt-common-layer` 或 `packages/nuxt-ai-layer`，Codex 应该先说明边界，而不是把一个局部页面需求直接扩散成共享层大改。

### 示例提示词

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

### 实际使用方式

1. 从仓库根目录开始。
2. 在提示词里显式写出 skill 名称。
3. 先描述产品改动目标，不要只丢一个文件名。
4. 让 Codex 先读现有实现，再补丁。
5. 改完后要求它在对应路由上做验证。

这样做的效果是：`web-nuxt` 会更像一个可以持续“边聊边改”的产品前台，而不是一个只能手工拆解的静态模板。

## 登录与访客模式

URL: https://jevnotes.com/zh-CN/docs/auth-and-guest-mode

Locale: zh-CN

Summary: 说明登录、访客访问、账户升级以及这些路径应该把用户带到哪里。

这个 Nuxt 模板同时支持正式账户与访客会话，目标是在用户真正注册前尽可能降低体验门槛。

### 正式账户路径

- 入口：`/auth/login` 与 `/auth/register`
- 支持邮箱、验证码、Google、GitHub
- 登录后的默认目标页：`/dashboard`

正式用户进入后，应先看到激活导向的 dashboard 首页，再进入 AI、API Key、计费或支持相关页面。

### 访客路径

- 入口：`/guest-demo`
- 访客并不是伪造状态，而是真实会话，有自己的积分与可继续访问的 dashboard
- 访客模式的目标是帮助用户先验证流程，再决定是否升级

### 什么时候该鼓励用户升级

访客模式适合：

- 对外演示
- 首次体验流量
- 销售或试用环节中的低门槛验证

正式账户适合：

- 长期使用
- 订阅与计费
- API Key 管理
- 长期项目所有权

### 产品建议

不要把访客模式做成死胡同式沙盒。更好的做法是把它做成一个“真实第一会话”，让用户在感受到价值后自然升级。

## AI 工作区

URL: https://jevnotes.com/zh-CN/docs/ai-playground

Locale: zh-CN

Summary: 说明 web-nuxt 面向用户的 Chat、Studio 与 Usage 产品面。

`web-nuxt` 现在提供完整的 AI 工作区，而不是把所有任务都导向一个 Playground：

- `/dashboard/ai-chat` 是正式的持久化对话产品面，支持历史记录与多轮续聊
- `/dashboard/ai-playground` 是 AI 创作室，承载图像、视频、音频等结构化生成流程
- `/dashboard/usage` 合并对话与 Provider 生成用量，覆盖图片、视频、音频、请求、Token、积分、每日活动和模型明细

### 为什么要统一到这里

三个产品面共用同一套会话生命周期，因此都能理解：

- 当前登录状态
- 访客会话
- 当前积分余额
- API Key 生命周期
- 对话与生成记录
- 模型差异化输入
- 按用户隔离的用量与计费数据

站长可以继续使用原生 Workers AI Binding，也可以在管理端 AI 上游配置中填写任意 HTTPS OpenAI 兼容 Base URL 与 API Key。凭证只保存在 `node10-ai-service` 服务端，用户只能看到已启用模型，不会接触上游密钥。

### 推荐的用户路径

1. 从 `/guest-demo` 或 `/dashboard` 进入
2. 对话任务进入 `/dashboard/ai-chat`，生成任务进入 `/dashboard/ai-playground`
3. 继续历史对话或完成第一次生成
4. 在 `/dashboard/usage` 查看消耗，再按需升级正式账户或更高套餐

### 产品上应避免的做法

- 不要在用户还没理解产品前，就先要求他们粘贴手动 API Key
- 不要把 Chat 与结构化生成塞进语义重复的界面；每个入口应对应明确任务
- 不要把积分、AI 生成与账户状态拆成彼此孤立的页面，却又没有默认引导路径

## 支持与退款

URL: https://jevnotes.com/zh-CN/docs/support-and-refund

Locale: zh-CN

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

支持入口应该在用户卡住之前就可见。在 ZShip 里，支持既属于公开站点的信任入口，也属于登录后的产品路径。

### 公开支持入口

- 头部导航应该有 support 入口
- footer 应该展示联系邮箱
- docs 里要用清晰语言说明退款与帮助预期

### 登录后的支持入口

- `/dashboard/tickets`：产品与账户问题
- `/dashboard/orders`：购买记录与退款申请
- `/dashboard/subscription`：联系支持前先自查套餐状态

### 关于退款

退款流程应当可预测：

- 明确告诉用户什么情况下应申请退款
- 把他们引导到正确的工单流程
- 在联系支持前，让他们能先看到清晰的订单与套餐信息

### 上线前需要自定义的地方

- `zship.app.json` 中的 `contactEmail`
- pricing、docs、dashboard 里的支持文案
- 团队内部对工单响应时间与退款审核标准的约定

## 数据分析

URL: https://jevnotes.com/zh-CN/docs/analytics

Locale: zh-CN

Summary: 说明 web-nuxt 目前如何接入 GA4、Plausible 和 Clarity。

`web-nuxt` 现在已经支持从 `zship.app.json` 配置可选的 analytics provider。

### 当前支持的提供商

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

### 同意机制

分析脚本不再默认注入，只有用户明确同意之后才会加载。

- 同意状态会同时写入 cookie 和 local storage
- 统一通过 `useAnalytics()` 暴露 `track()` 与页面浏览统计
- 后续如果需要按地区合规、第一方代理或更细粒度事件，可继续在这一层扩展

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

### 后续建议

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

## Footer 配置

URL: https://jevnotes.com/zh-CN/docs/footer-configuration

Locale: zh-CN

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

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

不要把 Footer 文案、链接或法律说明硬编码进 `LandingFooter.vue`。组件只负责渲染 `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`：Footer 左侧的描述文案，可以配置多行。多语言站点建议使用 localized object。
- `socialLinks`：邮箱下方的社交图标按钮。每一项需要 `to`、`icon`，以及 `labelKey` 或多语言 `label`。设为空数组可以隐藏所有社交按钮。
- `sections`：右侧导航列。每个栏目使用 `titleKey` 或 `label`，每个链接使用 `labelKey` 或 `label` 加 `to`。
- `disclaimer`：底部法律或商标声明。设为空数组可以隐藏。
- `copyright`：底部左侧版权文案，支持 `{year}`、`{siteName}`、`{brandName}`。设为空字符串可以隐藏。

### 标签与多语言

已有翻译建议复用 `apps/web-nuxt/app/i18n/ui.json` 里的 `labelKey`：

```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 邮箱通常建议用 `footer.contactEmail` 管理。

### 上线检查清单

正式发布前请确认：

- `footer.description` 不再保留模板占位文案。
- `footer.contactEmail` 指向真实支持邮箱。
- 所有 `footer.sections[].items[].to` 都是存在的路由。
- 外部链接指向正确的品牌账号。
- `footer.disclaimer` 符合你的法律与商标使用策略。
- 执行 `pnpm --filter @zship/web-nuxt exec nuxt prepare`。

## Docs 系统

URL: https://jevnotes.com/zh-CN/docs/docs-system

Locale: zh-CN

Summary: 说明 web-nuxt 当前基于 Nuxt Content 的站内文档能力，以及如何继续扩展。

站内 Docs 现在已经改成基于 Nuxt Content 的内容流，不再依赖自定义 `marked` 解析管线。

### 当前包含的部分

- `/docs` 和 `/docs/[slug]` 路由
- 存放在 `content/docs/` 下的 markdown 文件
- `content.config.ts` 里定义的英文与简体中文 docs collections
- 已接入 SEO metadata 和 prerender
- 由同一内容源生成的侧边栏导航

### 语言策略

当前公开站点首发只提供英文与简体中文，docs 内容也遵循同样的范围：英文始终可用，已翻译的页面再补简体中文，其余已收口的 locale 路由会重定向回英文或简体中文 canonical。

### 如何新增页面

1. 在 `content/docs/en/` 下新增 markdown 文件
2. 如果需要中文版本，再在 `content/docs/zh/` 下补对应文件
3. 通过 frontmatter 配置 `title`、`label`、`description`、`order`

```md
---
title: 账单指南
label: Billing
description: 说明套餐、发票和积分。
order: 4
---

## 概览

在这里写正文。
```

### 下一步怎么升级

如果文档规模继续增长，下一步可以继续在 Nuxt Content 这一套上叠加搜索、导航 metadata 或远程内容源，而不是再换一套内容栈。

# Blog

## ZShip Product Changelog - July 2026

URL: https://jevnotes.com/blog/changelog

Locale: en

Updated: 2026-07-16 14:45:51

Summary: Five July 2026 updates improve workflow reliability, email delivery, credit processing, Admin navigation, and mobile ElevenLabs input.

This release brings together five product and platform updates prepared on July 16, 2026. The Admin interface update is already available; service-level improvements become active as their corresponding Workers and database migrations are rolled out.

### Safer provider workflow retries

Provider generation requests now carry stable workflow context and idempotency data through creation, status polling, webhooks, credit deductions, and result transfer. Retrying the same request no longer creates duplicate work or duplicate credit deductions, while webhook tokens add a stronger verification boundary for asynchronous results.

### Usage-balanced Resend delivery

Email delivery can now distribute traffic across eligible Resend keys while respecting daily quotas. The Admin email workspace includes key status, usage, routing preference, delivery logs, and localized management controls so operators can understand capacity before an email is sent.

### Faster configuration and credit processing

Provider configuration updates now support batch operations and more deliberate cache invalidation. Subscription credit jobs use bounded queries and processing budgets, reducing repeated database work and making scheduled runs more predictable as account volume grows.

### A clearer Admin workspace

The Admin shell now uses layered workspace tabs and integrated navigation. Parent menu groups open compact four-column matrices with icons above labels, allowing operators to scan more destinations at once. On mobile, the matrix opens below the selected group and stays within the viewport; light mode, dark mode, and localized labels are supported.

### Restored ElevenLabs dialogue input on mobile

ElevenLabs Dialogue V3 once again exposes a required prompt in Quick Create. The prompt is mapped into the provider's dialogue payload with sensible stability and automatic language defaults, so mobile users can submit a valid dialogue request without constructing provider JSON manually.

### Rollout notes

- Admin navigation is deployed independently through the Admin Pages project.
- Provider idempotency and ElevenLabs input require the provider service migrations and Worker release.
- Resend balancing requires the support service migration and Worker release.
- Credit scheduling improvements require the authentication service Worker release.

## ZShip 2026 年 7 月产品更新日志

URL: https://jevnotes.com/zh-CN/blog/changelog

Locale: zh-CN

Updated: 2026-07-16 14:45:51

Summary: 2026 年 7 月的五项更新覆盖工作流可靠性、邮件投递、积分处理、管理后台导航和移动端 ElevenLabs 输入。

本次更新汇总了 2026 年 7 月 16 日准备完成的五项产品与平台改进。管理后台界面已经上线；服务端能力会在对应 Worker 和数据库迁移发布后生效。

### Provider 工作流重试更安全

生成任务从创建、状态查询、Webhook、积分扣减到结果转存，现在都会携带稳定的工作流上下文与幂等信息。重复提交同一请求不会重复创建任务或重复扣减积分，Webhook token 也为异步结果增加了更清晰的校验边界。

### Resend 投递支持用量均衡

邮件投递现在可以在满足条件的 Resend 密钥之间分配流量，同时遵守每日配额。管理后台的邮件工作区补充了密钥状态、用量、路由偏好、投递日志和多语言管理控件，运营人员可以在发送前判断可用容量。

### 配置更新和积分处理更高效

Provider 配置支持批量更新，并采用更明确的缓存失效策略。订阅积分定时任务使用有界查询和处理预算，减少重复数据库工作，让账号规模增长后的定时执行更加稳定可控。

### 管理后台工作区更清晰

管理后台采用分层工作区标签页和融入式导航。点击父菜单会打开四列矩阵，图标在上、名称在下，可以一次扫读更多入口。移动端矩阵会在选中菜单下方展开并保持在视口内，同时支持浅色模式、深色模式和本地化文案。

### 移动端恢复 ElevenLabs 对话输入

ElevenLabs Dialogue V3 的快捷创建重新提供必填提示词。提示词会被映射到 Provider 的 dialogue 请求结构，并带有合理的稳定性与自动语言默认值，移动端用户无需手写 Provider JSON 即可提交有效请求。

### 发布说明

- 管理后台导航通过 Admin Pages 项目独立部署。
- Provider 幂等能力和 ElevenLabs 输入需要发布 Provider 服务迁移与 Worker。
- Resend 用量均衡需要发布 Support 服务迁移与 Worker。
- 积分定时任务优化需要发布 Auth 服务 Worker。