@stackonward/cli 1.6.0 → 1.8.0

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/notification/contracts.go

@@ -0,0 +1,219 @@
+package notification
+
+import "time"
+
+// InboxQuery 保留原生查询的全部过滤条件，不替产品选择 scope。
+type InboxQuery struct {
+	UserID      int64    `json:"user_id"`
+	Categories  []string `json:"categories,omitempty"`
+	TargetRef   string   `json:"target_ref,omitempty"`
+	TargetScope string   `json:"target_scope"`
+	ReadStatus  string   `json:"read_status,omitempty"`
+	DeliveryIDs []int64  `json:"delivery_ids,omitempty"`
+	MessageIDs  []int64  `json:"message_ids,omitempty"`
+	Page        int      `json:"page,omitempty"`
+	PageSize    int      `json:"page_size,omitempty"`
+}
+
+// InboxMessage 是平台投影，不包含产品导航解释。
+type InboxMessage struct {
+	DeliveryID    int64             `json:"delivery_id"`
+	MessageID     int64             `json:"message_id"`
+	MessageNo     string            `json:"message_no"`
+	SourceVersion int64             `json:"source_version"`
+	Title         string            `json:"title"`
+	Subtitle      *string           `json:"subtitle,omitempty"`
+	Content       string            `json:"content"`
+	CoverURL      *string           `json:"cover_url,omitempty"`
+	ActionURL     *string           `json:"action_url,omitempty"`
+	Category      string            `json:"category"`
+	Metadata      map[string]string `json:"metadata"`
+	Status        string            `json:"status"`
+	TargetRef     *string           `json:"target_ref,omitempty"`
+	TargetKind    *string           `json:"target_kind,omitempty"`
+	ReadAt        *time.Time        `json:"read_at,omitempty"`
+	DeliveredAt   time.Time         `json:"delivered_at"`
+	CreatedAt     time.Time         `json:"created_at"`
+	UpdatedAt     time.Time         `json:"updated_at"`
+}
+
+// InboxPage 保留分页总数和分类未读汇总，供产品自行投影。
+type InboxPage struct {
+	Items         []InboxMessage   `json:"items"`
+	Total         int64            `json:"total"`
+	UnreadCount   int64            `json:"unread_count"`
+	UnreadSummary map[string]int64 `json:"unread_summary"`
+}
+
+// Unread 保留全局与分类未读事实。
+type Unread struct {
+	UnreadCount   int64            `json:"unread_count"`
+	UnreadSummary map[string]int64 `json:"unread_summary"`
+}
+
+// MessageVersion 仅确认用户已经查看的消息版本。
+type MessageVersion struct {
+	MessageNo     string `json:"message_no"`
+	SourceVersion int64  `json:"source_version"`
+}
+
+// AcknowledgeMessagesRequest 绑定可信接收人与精确消息版本。
+type AcknowledgeMessagesRequest struct {
+	UserID   int64            `json:"user_id"`
+	Messages []MessageVersion `json:"messages"`
+}
+
+// Acknowledgement 返回原子确认后的未读快照。
+type Acknowledgement struct {
+	Updated       int64            `json:"updated"`
+	UnreadCount   int64            `json:"unread_count"`
+	UnreadSummary map[string]int64 `json:"unread_summary"`
+}
+
+// DeviceRegistration 的账号与会话来自可信服务端上下文。
+type DeviceRegistration struct {
+	UserID               int64  `json:"user_id"`
+	SessionID            int64  `json:"session_id"`
+	ApplicationCode      string `json:"application_code"`
+	Environment          string `json:"environment"`
+	InstallationID       string `json:"installation_id"`
+	InstallationKey      string `json:"installation_key"`
+	RegistrationRevision int64  `json:"registration_revision"`
+	DeviceToken          string `json:"device_token"`
+	Platform             string `json:"platform"`
+	Provider             string `json:"provider"`
+	AppVersion           string `json:"app_version,omitempty"`
+	DeviceModel          string `json:"device_model,omitempty"`
+	OSVersion            string `json:"os_version,omitempty"`
+}
+
+// DeviceRevocation 使用安装能力，不要求保留已退出账号的身份。
+type DeviceRevocation struct {
+	ApplicationCode      string `json:"application_code"`
+	Environment          string `json:"environment"`
+	InstallationID       string `json:"installation_id"`
+	InstallationKey      string `json:"installation_key"`
+	RegistrationRevision int64  `json:"registration_revision"`
+}
+
+// Device 保留平台安全设备投影，不返回安装密钥或推送令牌。
+type Device struct {
+	ID                   int64      `json:"id"`
+	InstallationID       string     `json:"installation_id"`
+	ApplicationCode      string     `json:"application_code"`
+	Environment          string     `json:"environment"`
+	RegistrationRevision int64      `json:"registration_revision"`
+	Provider             string     `json:"provider"`
+	Platform             string     `json:"platform"`
+	AppVersion           *string    `json:"app_version"`
+	DeviceModel          *string    `json:"device_model"`
+	OSVersion            *string    `json:"os_version"`
+	Status               string     `json:"status"`
+	LastActiveAt         *time.Time `json:"last_active_at"`
+	CreatedAt            time.Time  `json:"created_at"`
+}
+
+// DeviceList 保留当前接收人的有效设备集合。
+type DeviceList struct {
+	Devices []Device `json:"devices"`
+}
+
+// QuietHours 表达调用方选择的静默时段，不设置产品默认值。
+type QuietHours struct {
+	Enabled  bool   `json:"enabled"`
+	Start    string `json:"start"`
+	End      string `json:"end"`
+	Timezone string `json:"timezone"`
+}
+
+// PushPreferences 同时保留渠道、分类和静默时段政策。
+type PushPreferences struct {
+	Enabled    bool            `json:"enabled"`
+	Categories map[string]bool `json:"categories"`
+	QuietHours QuietHours      `json:"quiet_hours"`
+}
+
+// PreferenceQuery 显式携带产品分类与默认值。
+type PreferenceQuery struct {
+	UserID     int64           `json:"user_id"`
+	Categories []string        `json:"categories"`
+	Defaults   PushPreferences `json:"defaults"`
+}
+
+// PreferenceUpdate 提交完整的产品作用域渠道偏好。
+type PreferenceUpdate struct {
+	UserID      int64           `json:"user_id"`
+	Preferences PushPreferences `json:"preferences"`
+}
+
+// TestPushRequest 仅供显式诊断调用，不参与构造或配置检查。
+type TestPushRequest struct {
+	UserID    int64   `json:"user_id"`
+	Title     string  `json:"title"`
+	Body      string  `json:"body"`
+	DeviceIDs []int64 `json:"device_ids"`
+}
+
+// TestPushResult 仅表示诊断发送的逐设备处理结果。
+type TestPushResult struct {
+	Succeeded int `json:"succeeded"`
+	Failed    int `json:"failed"`
+}
+
+// SourceEvent 由产品持久事件 owner 提供，不在协议层合成。
+type SourceEvent struct {
+	ID             string    `json:"id"`
+	Type           string    `json:"type"`
+	SubjectRef     string    `json:"subject_ref"`
+	SubjectVersion int64     `json:"subject_version"`
+	OccurredAt     time.Time `json:"occurred_at"`
+}
+
+// Recipient 使用平台公开用户引用，不接受调用方提供内部账号 ID。
+type Recipient struct {
+	UserPublicID string `json:"user_public_id"`
+}
+
+// InputContext 保留产品 owner 冻结的输入上下文。
+type InputContext struct {
+	Type      string `json:"type"`
+	Reference string `json:"reference"`
+}
+
+// Target 保留产品 target，不推导导航 URL。
+type Target struct {
+	Kind      string `json:"kind"`
+	Reference string `json:"reference"`
+}
+
+// DispatchStartRequest 不允许指定模板、提供商或发件身份。
+type DispatchStartRequest struct {
+	SourceEvent       SourceEvent    `json:"source_event"`
+	CommandKey        string         `json:"command_key"`
+	Channel           string         `json:"channel"`
+	Context           InputContext   `json:"context"`
+	Recipient         Recipient      `json:"recipient"`
+	Locale            string         `json:"locale"`
+	Target            Target         `json:"target"`
+	BusinessVariables map[string]any `json:"business_variables"`
+}
+
+// DispatchStartResult 表示持久入队与重放状态，不宣称设备已收到。
+type DispatchStartResult struct {
+	CommandUID string    `json:"command_uid"`
+	Status     string    `json:"status"`
+	ExpiresAt  time.Time `json:"expires_at"`
+	Replay     bool      `json:"replay"`
+}
+
+// SourceAdvanceRequest 仅推进事项版本，不携带发送内容。
+type SourceAdvanceRequest struct {
+	SourceEvent SourceEvent `json:"source_event"`
+	Recipient   Recipient   `json:"recipient"`
+}
+
+// SourceAdvanceResult 返回平台当前接受的事项版本。
+type SourceAdvanceResult struct {
+	Status        string `json:"status"`
+	SourceVersion int64  `json:"source_version"`
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/resilience.go

@@ -0,0 +1,23 @@
+package v1
+
+import (
+	"context"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+var dependencyOperationPartPattern = regexp.MustCompile(`^[a-z][a-z0-9_]{1,63}$`)
+
+// DependencyExecutor 在共享 transport 内按依赖操作隔离 bulkhead 与 circuit。
+type DependencyExecutor interface {
+	Execute(context.Context, string, func(context.Context) error) (bool, error)
+}
+
+func dependencyOperationKey(dependency, operation string) (string, error) {
+	if dependency != strings.TrimSpace(dependency) || operation != strings.TrimSpace(operation) ||
+		!dependencyOperationPartPattern.MatchString(dependency) || !dependencyOperationPartPattern.MatchString(operation) {
+		return "", fmt.Errorf("OneX dependency operation is invalid")
+	}
+	return dependency + "." + operation, nil
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/transport_policy.go

@@ -0,0 +1,96 @@
+package v1
+
+import (
+	"context"
+	"math"
+	"math/rand/v2"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+const maximumSafeReadRetries = 10
+
+// SafeReadRetryConfig 定义仅适用于 GET 的有界内联重试策略。
+type SafeReadRetryConfig struct {
+	MaxRetries     int
+	InitialBackoff time.Duration
+	MaxBackoff     time.Duration
+	JitterRatio    float64
+}
+
+// RetryWaiter 隔离重试等待，使 transport 合同可以使用确定性时钟验证。
+type RetryWaiter interface {
+	Wait(ctx context.Context, delay time.Duration) error
+}
+
+type timerRetryWaiter struct{}
+
+func (timerRetryWaiter) Wait(ctx context.Context, delay time.Duration) error {
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func validateSafeReadRetryConfig(config SafeReadRetryConfig) error {
+	if config.MaxRetries < 0 || config.MaxRetries > maximumSafeReadRetries {
+		return NewValidationError("onex_safe_read_retry_limit_invalid")
+	}
+	if config.MaxRetries == 0 {
+		return nil
+	}
+	if config.InitialBackoff <= 0 || config.MaxBackoff < config.InitialBackoff || config.JitterRatio < 0 || config.JitterRatio > 1 {
+		return NewValidationError("onex_safe_read_retry_config_invalid")
+	}
+	return nil
+}
+
+func shouldRetrySafeReadStatus(status int) bool {
+	switch status {
+	case http.StatusTooManyRequests, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
+		return true
+	default:
+		return false
+	}
+}
+
+func safeReadRetryDelay(config SafeReadRetryConfig, retryNumber int, retryAfter string, now time.Time) time.Duration {
+	if retryAfterDelay, ok := parseRetryAfter(retryAfter, now); ok {
+		return retryAfterDelay
+	}
+	delay := float64(config.InitialBackoff) * math.Pow(2, float64(retryNumber-1))
+	if delay > float64(config.MaxBackoff) {
+		delay = float64(config.MaxBackoff)
+	}
+	if config.JitterRatio > 0 {
+		minimum := delay * (1 - config.JitterRatio)
+		delay = minimum + rand.Float64()*(delay-minimum) //nolint:gosec // 仅用于重试抖动，不生成安全令牌。
+	}
+	return time.Duration(delay)
+}
+
+func parseRetryAfter(value string, now time.Time) (time.Duration, bool) {
+	if value == "" {
+		return 0, false
+	}
+	if seconds, err := strconv.ParseInt(value, 10, 32); err == nil {
+		if seconds < 0 {
+			return 0, false
+		}
+		return time.Duration(seconds) * time.Second, true
+	}
+	when, err := http.ParseTime(value)
+	if err != nil {
+		return 0, false
+	}
+	delay := when.Sub(now)
+	if delay < 0 {
+		delay = 0
+	}
+	return delay, true
+}

package/dist/resources/templates/go-backend/internal/products/README.md

@@ -1,5 +1,5 @@
 # Product modules
 
-Each module owns product use cases, models and persistence. Select Full DDD, Simplified DDD or Flat using [module standards](../../.claude/docs/module-standards.md); the directory name describes its business responsibility.
+Each module owns product use cases, models and persistence. Select Full DDD, Simplified DDD or Flat using [module standards](../../.codex/docs/module-standards.md); the directory name describes its business responsibility.
 
 Compose modules through Wire in `cmd/`. Depend on generic infrastructure and consumer-defined integration ports. Platform authentication, asset execution and payment services remain upstream owners; access their published contracts without querying their internal tables.

package/dist/resources/templates/go-backend/internal/sharedevents/README.md

@@ -2,4 +2,4 @@
 
 Declare cross-module event names and typed payloads here. Producers and consumers use the same pointer payload contract, with resource identity and audit metadata in the event envelope.
 
-Register persisted payload factories and explicit event schema versions when adding durable delivery. Domain state transitions remain in the owning product module. See [event runtime boundaries](../../.claude/docs/event-runtime-boundary.md) and [backend standards](../../CLAUDE.md).
+Register persisted payload factories and explicit event schema versions when adding durable delivery. Domain state transitions remain in the owning product module. See [event runtime boundaries](../../.codex/docs/event-runtime-boundary.md) and [backend standards](../../AGENTS.md).

package/dist/resources/templates/go-backend/scripts/check-openapi-clean-deletion.sh

@@ -27,10 +27,10 @@ fail_if_matches "Swagger annotations remain" '^\s*//\s*@[[:alpha:]]' "$BACKEND_D
 fail_if_matches "Swagger-only struct tags remain" '(^|[[:space:]`])(swaggertype|example|format):"' "$BACKEND_DIR" --glob '*.go'
 fail_if_matches "Swagger runtime registry reads remain" 'swag\.ReadDoc' "$BACKEND_DIR" --glob '*.go'
 fail_if_matches "Retired Swagger commands remain" 'make swag|generate-swagger|swagger_route_inventory' \
-  "$BACKEND_DIR/Makefile" "$BACKEND_DIR/CLAUDE.md" "$BACKEND_DIR/.claude/docs" \
+  "$BACKEND_DIR/Makefile" "$BACKEND_DIR/AGENTS.md" "$BACKEND_DIR/.codex/docs" \
   --glob '!**/worktrees/**'
 fail_if_matches "Retired Swagger guidance remains" 'Swagger/security|Swagger/API docs' \
-  "$BACKEND_DIR/CLAUDE.md" "$BACKEND_DIR/.claude/docs"
+  "$BACKEND_DIR/AGENTS.md" "$BACKEND_DIR/.codex/docs"
 fail_if_matches "Retired Swagger documentation pipelines remain" \
   'swaggo/swag|CMS_SWAGGER_URL|/swagger/doc\.json|Go Swagger' "$BACKEND_DIR/docs" --glob '*.md'
 
@@ -38,7 +38,7 @@ for path in \
   "$BACKEND_DIR/scripts/generate-swagger.sh" \
   "$BACKEND_DIR/scripts/swagger_route_inventory.py" \
   "$BACKEND_DIR/scripts/swagger_route_inventory_test.py" \
-  "$BACKEND_DIR/.claude/docs/swagger.md"
+  "$BACKEND_DIR/.codex/docs/swagger.md"
 do
   if [[ -e "$path" ]]; then
     echo "retired Swagger artifact remains: ${path#"$BACKEND_DIR/"}" >&2

package/dist/resources/templates/mcp-server/.prettierignore

@@ -0,0 +1 @@
+AGENTS.md

package/dist/resources/templates/nuxt/{.claude → .codex}/docs/stack.md

@@ -45,6 +45,16 @@ ESLint composes the Nuxt-generated flat configuration with `@stackonward/eslint-
 
 Never place OAuth secrets, service credentials or provider API keys here. An enabled client feature does not prove backend credentials or permission are configured. Validate numeric input at its actual consumer rather than relying on `Number.parseInt` alone.
 
+### Optional Web Push
+
+<web_push_contract>
+
+`runtimeConfig.public.webPush` owns `NUXT_PUBLIC_WEB_PUSH_ENABLED`, `API_ORIGIN`, `PRODUCT_CODE`, `APPLICATION_CODE`, `TOPIC_KEY` and `DATABASE_NAME` under the same `NUXT_PUBLIC_WEB_PUSH_` prefix. The capability MUST remain disabled by default. The optional `@stackonward/nuxt-site-shell/web-push` module bundles the editable `app/web-push/worker.ts` into a same-origin script; building that asset NEVER grants permission or registers a subscription.
+
+MUST consume browser/worker primitives from `@stackonward/web-push`, coordination from `@stackonward/composables`, and the named HTTP/storage protocol from `@stackonward/onex-web-push`. Product consent copy, branding, navigation targets and public identifiers remain in the application. MUST preserve an existing database namespace and record key when upgrading; those records contain the capability required for withdrawal. NEVER send cookies/account authorization, follow API redirects, automatically regrant consent, or couple messaging to optional analytics. Locale aliases are validated by the backend owner, not a copied frontend locale enum. Browser permission and real delivery require separate acceptance.
+
+</web_push_contract>
+
 ## II. Project Structure and Imports
 
 | Owner                                                                 | Responsibility                                                       |
@@ -372,6 +382,12 @@ const emit = defineEmits<{ submit: [] }>();
 
 Use Tailwind utilities and theme tokens. Scoped CSS is for behavior that utilities cannot express cleanly. Dark/light modes must use the same semantic tokens; never fix one page with a hardcoded light background that breaks dark mode.
 
+### Control Geometry and Scene Selection
+
+**MUST** follow [DESIGN.md](../../DESIGN.md#control-geometry-and-visual-scenarios) for control sizes, text/line height, padding, radii, widths and focus treatment. Marketing CTAs and product UI share `UiButton` and the existing Nuxt UI themes. Marketing sections select prominent actions and own their wider layout; product navigation, workbenches and forms select compact or form-sized controls from the same scale.
+
+Use `size` for the shared geometry and `block`/`fullWidth` for a full-width button. Keep section-specific CTA minimum widths at their section owner. **FORBIDDEN**: a second button implementation, marketing minimum widths in the generic theme or arbitrary per-page height/font/radius overrides for an existing size. Editable mobile fields retain the theme's readable text size; compact icon actions retain their accessible target.
+
 ### Icon Design Contract
 
 **MUST** read [DESIGN.md](../../DESIGN.md) for icon geometry, the size scale, semantic colors and acceptance. The installed system uses local Lucide functional icons and a separate `brand` collection. `UiIcon` owns standalone `name`, `size?: string | number` and `label?: string`; Nuxt UI controls retain their internal icon slots and use the same provider.
@@ -677,7 +693,7 @@ Read [Architecture](architecture.md), [Security and Lifecycle](security-lifecycl
 - [ ] Private configuration never enters public payloads.
 - [ ] Every visible action maps to a real implementation and error path.
 - [ ] All applicable NX-S/A/T/C/H/E/M/P/U rules are checked.
-- [ ] Design coverage includes children, overlays, icon sizes/names/targets and loading/empty/error/forbidden states.
+- [ ] Design coverage includes children, overlays, scene-appropriate control geometry, icon sizes/names/targets and loading/empty/error/forbidden states.
 - [ ] `pnpm typecheck` and `pnpm build` pass for code/contract changes.
 - [ ] Browser and network evidence proves the touched interactions.
 - [ ] No uninstalled lint/test/authorization capability is claimed.

package/dist/resources/templates/nuxt/.dockerignore

@@ -1,6 +1,6 @@
 .git
 .github
-.claude
+.codex
 .husky
 .nuxt
 node_modules

package/dist/resources/templates/nuxt/.env.example

@@ -1,5 +1,11 @@
 NUXT_PUBLIC_API_BASE_URL=
 NUXT_PUBLIC_API_TIMEOUT=30000
+NUXT_PUBLIC_WEB_PUSH_ENABLED=false
+NUXT_PUBLIC_WEB_PUSH_API_ORIGIN=
+NUXT_PUBLIC_WEB_PUSH_PRODUCT_CODE=
+NUXT_PUBLIC_WEB_PUSH_APPLICATION_CODE=
+NUXT_PUBLIC_WEB_PUSH_TOPIC_KEY=
+NUXT_PUBLIC_WEB_PUSH_DATABASE_NAME="{{projectName}}-web-push"
 NUXT_PUBLIC_SITE_URL=
 NUXT_PUBLIC_SITE_ENV=development
 NUXT_PUBLIC_SITE_NAME="{{projectName}}"

package/dist/resources/templates/nuxt/.prettierignore

@@ -1,4 +1,5 @@
-.claude
+.codex
+AGENTS.md
 .nuxt
 .output
 coverage

package/dist/resources/templates/nuxt/DESIGN.md

@@ -1,6 +1,6 @@
 # Nuxt Design Standard
 
-This document defines the visual contract for the application-owned Nuxt UI foundation. Read it with the [Nuxt Engineering Standard](.claude/docs/stack.md) before changing icons, controls or theme defaults. Application branding remains in its own assets and semantic color tokens.
+This document defines the visual contract for the application-owned Nuxt UI foundation. Read it with the [Nuxt Engineering Standard](.codex/docs/stack.md) before changing icons, controls or theme defaults. Application branding remains in its own assets and semantic color tokens.
 
 ## Design Decisions
 
@@ -13,18 +13,61 @@ This document defines the visual contract for the application-owned Nuxt UI foun
 
 ## Ownership
 
-| Owner                                            | Contract                                                                                    |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| `app/assets/css/site-shell.css`                  | `--site-icon-*` size tokens, `size-icon-*` Tailwind aliases and semantic colors             |
-| `app/theme/icon.ts`                              | Nuxt Icon defaults: 20px token, SVG mode, non-shrinking alignment and decorative attributes |
-| `app/app.config.ts`                              | Composes `icon` defaults and the Nuxt UI theme                                              |
-| `app/components/ui/Icon.vue`                     | Typed `name`, `size` and accessible `label` adapter                                         |
-| `app/theme/button.ts`, `input.ts`, `checkbox.ts` | Internal icon slots and the control's geometry                                              |
-| `nuxt.config.ts`                                 | Locally bundled `lucide`, `brand` SVG collection and `fallbackToApi: false`                 |
-| `app/assets/icons/brand/`                        | Reviewed third-party identity assets                                                        |
+| Owner                                                                        | Contract                                                                                    |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `app/assets/css/site-shell.css`                                              | `--site-control-height-*`, icon sizes, radius tokens, Tailwind aliases and semantic colors  |
+| `app/theme/icon.ts`                                                          | Nuxt Icon defaults: 20px token, SVG mode, non-shrinking alignment and decorative attributes |
+| `app/app.config.ts`                                                          | Composes `icon` defaults and the Nuxt UI theme                                              |
+| `app/components/ui/Icon.vue`                                                 | Typed `name`, `size` and accessible `label` adapter                                         |
+| `app/theme/button.ts`, `input.ts`, `select.ts`, `textarea.ts`, `checkbox.ts` | Internal icon slots and the control's geometry                                              |
+| `nuxt.config.ts`                                                             | Locally bundled `lucide`, `brand` SVG collection and `fallbackToApi: false`                 |
+| `app/assets/icons/brand/`                                                    | Reviewed third-party identity assets                                                        |
 
 Registry-installed source belongs to this application. **MUST** change the owning token or component when a repeated pattern changes. A one-location size choice stays at its caller. **FORBIDDEN**: adding a second icon component, runtime registry, icon font or icon library for an existing Lucide capability.
 
+## Control Geometry and Visual Scenarios
+
+Marketing and product UI use the same `UiButton`, Nuxt UI controls and theme tokens. **MUST** choose the size and composition for the action's context; **FORBIDDEN**: separate marketing/product button implementations or campaign dimensions in the generic button default.
+
+| Scenario                         | Controls                                                                                                          | Typography and layout ownership                                                                                            |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Marketing conversion             | Section CTAs use `2xl` for prominence, with a section-owned minimum width of 200px and `max-w-full`.              | Content sections own their larger headings, supporting copy, generous spacing and responsive content width.                |
+| Product navigation and workbench | Use `sm` for compact labeled actions and `md` for ordinary controls. Buttons fit their content.                   | App header, sidebar and editor owners control density, alignment and available width; controls retain the shared geometry. |
+| Product authentication and forms | Use `lg` when the form needs a larger field and submission target. Select `block` for a full-width submit action. | The form owns field width, label/help spacing and validation space; it does not inherit a marketing CTA's minimum width.   |
+
+The control scale uses `--site-control-height-*` tokens and `h-control-*` utilities. Values below assume a 16px root; height, text and padding use rem. Text shows font size / line height. Button labels use medium weight. Input/select padding is the base padding on each side; icon slots add their own reserved space.
+
+| Size           | Button height | Input/select height | Text      | Button horizontal padding | Input/select horizontal padding | Icon |
+| -------------- | ------------- | ------------------- | --------- | ------------------------- | ------------------------------- | ---- |
+| `xs`           | 32px          | 32px                | 12 / 16px | 12px                      | 12px                            | 16px |
+| `sm`           | 36px          | 36px                | 14 / 20px | 16px                      | 12px                            | 16px |
+| `md` (default) | 42px          | 42px                | 14 / 20px | 20px                      | 14px                            | 20px |
+| `lg`           | 48px          | 48px                | 16 / 24px | 24px                      | 16px                            | 20px |
+| `xl`           | 52px          | 52px                | 18 / 28px | 28px                      | 18px                            | 24px |
+| `2xl`          | 56px          | —                   | 18 / 28px | 32px                      | —                               | 24px |
+
+Editable inputs and textareas use 16px text below the `md` breakpoint unless the caller explicitly opts into the framework's `fixed` typography behavior. Their desktop typography follows the table. Select triggers retain their selected size. Textareas use rows/content height, not the single-line height scale; their vertical padding belongs to `app/theme/textarea.ts`.
+
+Ordinary buttons have intrinsic width with no shared minimum or fixed width. `block` or `fullWidth` explicitly fills the available width. Marketing CTA widths belong to `content/CallToAction.vue`, `content/Faq.vue`, `content/Reviews.vue` and `steps/Showcase.vue`; page widths and heading scales remain at their layout/section owner. Link buttons retain text-flow height. Square icon buttons keep at least 44 × 44px targets even when their selected size is smaller.
+
+Buttons, text inputs, selects and textareas use `--site-radius-md` through `rounded-ml` (10px); non-fullscreen dialogs use `--site-radius-lg` through `rounded-2ml` (20px). **MUST** reuse these radius tokens instead of adding a different radius to each field or button. Primary and neutral outline buttons and ordinary outlined fields use one 1px ring, without a second border. Primary solid buttons and primary outlined fields expose a 2px keyboard-focus outline; primary outline buttons use a 2px focus ring. Other semantic variants retain their theme-owned focus behavior. Focus treatment must remain visible and distinct from the resting edge.
+
+Custom token utilities **MUST** be registered in `app/theme/index.ts` through `tv.twMergeConfig.extend.theme`: `radius` owns `ml`/`2ml`, and `spacing` owns the `control-*`/`icon-*` scales. This lets Nuxt UI merge framework defaults, theme values and caller overrides consistently. **FORBIDDEN**: relying on CSS source order to resolve conflicting size or radius utilities.
+
+✅ **Select shared sizes; the caller owns emphasis and width.**
+
+```vue
+<UiButton size="sm" color="primary" variant="solid">Sign in</UiButton>
+<UiButton size="lg" block type="submit">Continue</UiButton>
+<UiButton size="2xl" class="min-w-[200px] max-w-full">Start creating</UiButton>
+```
+
+❌ **A generic width mandate and per-page sizing bypass both scene owners.**
+
+```vue
+<UiButton class="h-[39px] min-w-[200px] rounded-[7px] text-[15px]">Save</UiButton>
+```
+
 ## Functional Icon Geometry
 
 Functional icons **MUST** use `i-lucide-*` names from the installed collection. Their design uses a square 24 × 24 viewBox, 2-unit centered strokes, rounded open-path caps and rounded joins. Preserve the family's edge clearance, internal spacing and visual balance; identical CSS dimensions alone do not establish equal optical weight. These constraints follow the [Lucide specification](https://lucide.dev/contribute/icons/specification).
@@ -136,6 +179,8 @@ Use the existing locale owner for labels, visible focus on controls and the comp
 
 ### Acceptance Checklist
 
+- [ ] Marketing CTAs and product actions use the same controls with the appropriate size and caller-owned width.
+- [ ] Actual control heights, typography, padding, radii, border/focus states and narrow-view input text match the shared contract.
 - [ ] Functional icons come from the installed Lucide family; brand assets remain separate.
 - [ ] The 20px default, selected size tokens and explicit `size` override render correctly without competing size declarations.
 - [ ] Source geometry and proportional strokes are preserved; no arbitrary per-icon offsets or global SVG overrides exist.

package/dist/resources/templates/nuxt/README.md

@@ -30,6 +30,14 @@ pnpm dlx @stackonward/cli analytics generate \
 
 Import the generated JSON into a selected GTM web-container workspace, preview the merge, and publish the reviewed version. The generated Google Tag disables automatic page views because the Nuxt integration owns SPA page-view dispatch.
 
+## Optional Web Push
+
+Web Push is disabled by default. The generated `app/plugins/web-push.ts` composes the public browser primitives, Vue controller and named OneX adapter; `app/web-push/worker.ts` is bundled by `@stackonward/nuxt-site-shell/web-push` into the same-origin `push-sw.js`. The worker source is editable product code, not an unbundled public script.
+
+Configure the public `NUXT_PUBLIC_WEB_PUSH_*` settings in `.env.example` only after the matching OneX product, application, allowed origin, consent topic and VAPID provider are configured. Keep the generated database namespace stable after users subscribe. Product code owns consent wording, the visible subscribe/withdraw controls, notification fallback title and business destinations. There is no automatic visitor subscription, and analytics consent does not authorize Web Push.
+
+`useWebPush()` exposes `state`, `subscribe(locale, event)`, `revoke(event)` and `refresh()`. Call subscribe and revoke from real user click or keyboard events, surface the controller's safe error state, and retain recovery actions when a request has an unknown outcome. Locale is forwarded to the server for validation and normalization. Browser permission, subscription persistence, provider delivery and notification-click behavior require separate browser/device acceptance; a successful build does not prove delivery.
+
 ## Engineering workflow
 
 ```bash

package/dist/resources/templates/nuxt/nuxt.config.ts

@@ -6,7 +6,11 @@ const gtmId = process.env.NUXT_PUBLIC_GTM_ID || "";
 
 export default defineNuxtConfig({
   extends: ["@stackonward/nuxt-site-shell"],
-  modules: ["@nuxt/eslint", "@stackonward/google-tag-manager-nuxt"],
+  modules: [
+    "@nuxt/eslint",
+    "@stackonward/google-tag-manager-nuxt",
+    ["@stackonward/nuxt-site-shell/web-push", { entry: "app/web-push/worker.ts" }],
+  ],
   compatibilityDate: "2025-07-15",
   css: ["~/assets/css/site-shell.css"],
   i18n: {
@@ -56,6 +60,14 @@ export default defineNuxtConfig({
   },
   runtimeConfig: {
     public: {
+      webPush: {
+        enabled: false,
+        apiOrigin: "",
+        productCode: "",
+        applicationCode: "",
+        topicKey: "",
+        databaseName: "{{projectName}}-web-push",
+      },
       api: {
         baseUrl: process.env.NUXT_PUBLIC_API_BASE_URL || "",
         timeout: Number.parseInt(process.env.NUXT_PUBLIC_API_TIMEOUT || "30000", 10),

package/dist/resources/templates/nuxt/package.json

@@ -28,11 +28,13 @@
     "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
   },
   "dependencies": {
+    "@stackonward/web-push": "^0.0.1",
+    "@stackonward/onex-web-push": "^0.0.1",
     "@stackonward/api-client": "^0.0.3",
     "@stackonward/google-tag-manager-nuxt": "^0.3.3",
     "@stackonward/nuxt-layer-base": "^0.0.4",
-    "@stackonward/nuxt-site-shell": "^0.3.2",
-    "@stackonward/composables": "^0.0.2"
+    "@stackonward/nuxt-site-shell": "^0.4.0",
+    "@stackonward/composables": "^0.1.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackonward/cli",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "StackOnward CLI for creating projects and installing reusable components and snippets",
   "type": "module",
   "main": "dist/index.js",