openxiangda-skill-kit 2.0.0-alpha.13 → 2.0.0-alpha.131

package/skills/openxiangda-v2/SKILL.md

@@ -1,38 +1,71 @@
 ---
 name: openxiangda-v2
-description: Build, inspect, validate, and deliver a complete OpenXiangda 2.0 application workspace. Use when a task spans the React frontend, NestJS backend, Data API, authorization, workflow, events, or whole-application delivery.
+description: Use when researching, designing, building, testing, or delivering an OpenXiangda 2.0 application, including anonymous public forms and other no-account external-user pages.
 ---
 
 # OpenXiangda 2.0
 
-Treat the repository as one typed application product. Work through package contracts and deterministic commands; do not mutate platform resources one at a time.
+Treat requirement discovery, architecture, authorization, development, testing and delivery as one evidence-backed application lifecycle. OpenXiangda 2.0 has no compatibility surface: replace an incorrect alpha contract directly and never add aliases, migration branches, 1.x SDD, Umi, ProComponents, Function CRUD, application-owned identity switching or another identity path.
 
-## Start Here
+Before a workspace exists, use this Skill's exact npm version:
 
-1. Run `openxiangda app info` and inspect the returned workspace and platform contract versions.
-2. Read `openxiangda.config.ts`, then identify which domain skill applies:
-   - architecture: `$openxiangda-v2-architecture`
-   - frontend: `$openxiangda-v2-frontend`
-   - backend: `$openxiangda-v2-backend`
-   - data and authorization: `$openxiangda-v2-data-authz`
-   - workflow and events: `$openxiangda-v2-workflow-events`
-   - delivery: `$openxiangda-v2-delivery`
-3. Keep generated contracts current with `openxiangda generate`.
-4. Before delivery, run `openxiangda check` and `openxiangda test`.
+```bash
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ login --base-url <platform>
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ create <directory>
+```
 
-For a new repository, link it to the target platform and let an authorized platform administrator run `openxiangda app provision` once. The command is idempotent and provisions only a native 2.0 application identity.
+Inside an application, use only its locked executable through `pnpm openxiangda`. Never invoke a bare global `openxiangda`, because that executable may belong to stable 1.x. Moving tags such as `latest` and `alpha` are forbidden. To install or refresh this same Skill from the package, run:
 
-## Boundaries
+```bash
+pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
+```
 
-- Put browser code in `apps/web`, server code in `apps/server`, shared domain types in `packages/domain`, and generated declarations in `packages/contracts`.
-- Persist business records only through Data API or an App API implemented by the application backend.
-- Treat the active role and context attributes as explicit request state.
-- Use durable event consumers for side effects and idempotency keys for retries.
-- Build one immutable application package; the platform owns deployment execution, health gates, promotion, and rollback.
-- Reject any workspace that does not declare the native 2.0 application configuration.
+Use this order:
 
-## Delivery Gate
+1. Read [Commands](references/commands.md) when selecting a CLI operation. It is generated from the executable registry. `create` owns application binding and initialization, while `check`, `deploy` and `status` expose the current workspace and deployment facts.
+2. Read [Discovery](references/discovery.md), turn the request into actors, scenarios, data, permissions, constraints and acceptance evidence, and identify every unresolved choice.
+3. If the workspace contains `appspec/`, the user asks to maintain requirements, or the task changes observable behavior, read [AppSpec](references/appspec.md), load the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID. AppSpec is optional and never a release gate; L0 changes create no record.
+4. Read [Architecture](references/architecture.md), assign one owner to each capability and keep ordinary CRUD on platform Data API.
+5. For every resource or permission change, read [Data and authorization](references/data-authz.md) before editing `openxiangda.config.ts`.
+   When a custom authenticated page lets business users maintain application-role memberships or delegate that maintenance authority, also read [Frontend](references/frontend.md). Use the current-user role-management browser SDK documented there; never add actor selection, an application-owned grant table, or a proxy authorization service.
+6. If the request mentions external users without platform accounts, anonymous or guest access, a public form/page, resumable submission, duplicate checks, public uploads, or letting a visitor read their own submissions, read [Anonymous public access](references/public-access.md). Use the declared platform contract; do not invent a guest role, public Native Data API, fingerprint identity or application-owned token.
+7. Read [Frontend](references/frontend.md) for pages or fields and [Backend actions](references/backend.md) only for a real business action.
+   When the request customizes the application Todo center or the common PC/mobile frame around standard user pages, use only `standardUserSurfaces` from that reference. The platform must keep ownership of the Router, `RuntimeBoundary`, current user, Notification Hub and Workflow controllers.
+8. When the application explicitly enables standard approval, application events or notifications, read [Workflow, Events and Notification Hub](references/workflow-events.md). Keep them optional and out of ordinary CRUD.
+9. Run the connected loop with `pnpm openxiangda dev`, then follow [Testing](references/testing.md) and `pnpm openxiangda check`; check performs the target platform's read-only Native compatibility preflight before application checks or builds.
+10. Follow [Delivery](references/delivery.md): deploy preproduction first, inspect status/logs, then promote the exact successful version to production.
 
-Use `openxiangda build --backend-image <immutable-image>` only after checks pass. Use `openxiangda deploy`, `openxiangda status`, and `openxiangda logs` only when the user has authorized the environment change.
+For an AI-native client, start the workspace protocol through the same pinned executable:
 
-Read [Getting Started](../../docs/getting-started.md) for the complete development loop.
+```bash
+pnpm exec openxiangda --mcp-stdio --cwd <workspace>
+```
+
+Read `openxiangda://workspace/contracts` or call `contract_describe`. For first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration; never treat the proposal as runtime discovery. When AppSpec is enabled, read `openxiangda://workspace/appspec` or call `appspec_context`; treat it as advisory context, never as deployment authority. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. Never create an application MCP server, Catalog file, preview store or AI authorization path.
+
+Authenticated browser routes use the current logged-in user's complete application-role union. An application that serves every logged-in platform user may declare one existing package role through `authz.authenticatedUserRoleCode`; the platform materializes that role on first access and unions it with manual and business-projected roles. Do not fake the role in React, use a membership resource for a universal audience, or confuse the baseline access role with business membership. The only no-account exception is an exact static user route declared through `frontend.publicAccess`; it uses a platform-issued HttpOnly browser credential and dedicated `createAnonymousPublicClient` operations. It is not an application role, login session or general Data API identity. For both paths the platform remains authoritative for capabilities, fields, rows and RLS. A declared Perspective is only a read projection over the authenticated union: it may narrow pages, rows and readable fields, but never create/update/delete, workflow or custom-action authorization. Omitted Perspective means the complete union. Application code does not replace either identity, persist a platform token, construct an authorization result or keep a second permission state.
+
+Applications own one explicit typed admin navigation declaration. The compiler
+owns page/route generation, but it never turns every generated resource or
+Workflow into a menu item; the Shell renders only declared navigation and then
+filters it by authorization. Keep page existence, route reachability and menu
+visibility separate. Use resource mutation ownership and per-operation
+generated surface flags, and give only self-contained `standalone` Workflow
+launch pages a menu entry.
+
+Read only the references needed for the current change, except the mandatory discovery and Data/authorization rules above:
+
+- [Discovery](references/discovery.md)
+- [AppSpec](references/appspec.md)
+- [Commands](references/commands.md)
+- [Architecture](references/architecture.md)
+- [Workspace agent contract](references/workspace.md)
+- [Backend actions](references/backend.md)
+- [Data and authorization](references/data-authz.md)
+- [Anonymous public access](references/public-access.md)
+- [Frontend](references/frontend.md)
+- [Workflow, Events and Notification Hub](references/workflow-events.md)
+- [Testing](references/testing.md)
+- [Delivery](references/delivery.md)
+
+Workflow and Notification Hub are optional 2.0 modules outside the CRUD golden path. Never add their packages, routes, declarations or runtime workers to an application that does not enable them.

package/skills/openxiangda-v2/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "OpenXiangda 2.0"
-  short_description: "Build and deliver typed OpenXiangda 2.0 applications"
+  short_description: "Build internal and anonymous public OpenXiangda 2.0 apps"
   default_prompt: "Use $openxiangda-v2 to build and validate this OpenXiangda 2.0 application."

package/skills/openxiangda-v2/references/appspec.md

@@ -0,0 +1,67 @@
+# AppSpec
+
+AppSpec 是 OpenXiangda 2.0 应用仓库中的可选业务意图层。它帮助 AI 理解“为什么做、应当表现成
+什么、这次改变什么”，但不复制 `openxiangda.config.ts`、编译合同、代码、测试或部署状态，也
+不是发布门禁。
+
+AppSpec 只使用 2.0 的 `appspec/`、文档 schema v1 与 context v2。绝不读取、识别、导入或迁移
+1.x 的 `openspec/`、SDD、表单、页面、函数和发布材料。
+
+## 何时读取
+
+- 工作区存在 `appspec/` 时，在分析需求或修改行为前运行 `pnpm openxiangda spec context --json`，先读取
+  有界索引。
+- 从索引选择相关变更、能力、ADR 或历史变更 ID，再运行例如
+  `pnpm openxiangda spec context booking-window --json` 读取正文。
+- AI-native 客户端可读取 `openxiangda://workspace/appspec` 或调用 `appspec_context`。
+- 默认不加载全部正文；历史变更只在追查原因时用稳定 ID 按需读取。
+
+## 何时维护
+
+| 风险 | 典型变化 | 最小维护量 |
+| --- | --- | --- |
+| L0 | 重构、格式、无行为变化 | 不创建 ChangeSpec |
+| L1 | 文案、单字段、局部规则 | 一份短 ChangeSpec |
+| L2 | 跨资源、权限、状态变化 | 加正反验收、数据与回滚 |
+| L3 | 身份、迁移、并发、外部副作用 | 加失败/幂等、资源边界和 ADR |
+
+用户没有要求且变更是 L0 时，不要为了“流程完整”创建文档。小应用可以长期只维护 `app.md`。
+
+## 标准操作
+
+```bash
+pnpm openxiangda spec init
+pnpm openxiangda spec add-capability CAP-BOOKING --title "预约管理" --resources bookings
+pnpm openxiangda spec new booking-window --title "限制可预约时段" --risk L1 \
+  --capabilities CAP-BOOKING --resources bookings
+pnpm openxiangda spec context booking-window --json
+pnpm openxiangda spec check
+pnpm openxiangda spec close booking-window --current-spec merged \
+  --summary "已通过真实角色验收"
+```
+
+`spec check` 是用户主动选择的严格检查；普通 `check/dev/deploy` 只给 advisory，不因 AppSpec
+缺失或不完整而失败。
+
+新 ChangeSpec 的 `currentSpec` 固定从 `pending` 开始。关闭前先把长期有效结果合入 `app.md` 或相关
+CapabilitySpec，再由用户确认 `merged`；不改变长期规格时由用户确认 `not-applicable`。AI 可以列出
+未合入差异，但不能自行选择这两个值。稳定 REQ/AC 未进入当前规格、L2/L3 必需章节为空或保留默认
+占位内容时，`spec close` 不移动文件。
+
+## 写作边界
+
+- `app.md` 记录长期目标、角色、范围、术语和跨能力约束。
+- `capabilities/CAP-*.md` 记录当前有效需求，使用稳定 `REQ-*` 和可证伪 `AC-*`。
+- `changes/active/*.md` 只记录本次 delta、风险、影响范围与验收；关闭前把仍有效的结论合入能力规格，
+  并由用户确认 `currentSpec`。
+- `decisions/ADR-*.md` 只用于架构显著决定，不为普通小改创建。
+- 引用真实 2.0 resource/action code，不抄字段定义和权限矩阵的机器事实。
+- AI 可以创建 `draft`、指出未确认问题和建议更新，不能自行把需求标记为 `confirmed`。
+- 不因 AppSpec 与实现冲突就静默修改其中一方；明确指出冲突，由用户决定业务意图，技术事实以实时
+  编译合同为准。
+
+## 可迁移程度
+
+完整 AppSpec 能显著提高另一个新项目复现业务逻辑的概率，但最终文档本身不等于可执行应用。
+需要接近原应用时，应同时提供 AppSpec、`openxiangda.config.ts`、必要自定义动作、测试和外部接口
+合同；历史 ChangeSpec 不是必需输入。

package/skills/openxiangda-v2/references/architecture.md

@@ -0,0 +1,9 @@
+# OpenXiangda 2.0 Architecture
+
+Keep one React application, one optional NestJS service and one platform-owned data contract. Application code directly depends only on `openxiangda`; use `openxiangda/config`, `openxiangda/core`, `openxiangda/field-kit`, `openxiangda/react`, `openxiangda/nest` and `openxiangda/testing` as the public subpaths. Do not import the physical `openxiangda-*` implementation packages.
+
+Declare resources, routes, capabilities, row policies and operation-aware field policies once in `openxiangda.config.ts`. The compiler owns derived contracts; the root package owns Field Kit, CRUD Renderer, Shell, clients and Nest integration; the platform owns identity, authorization, data, environment Heads and deployment state.
+
+The compiler alone derives the AppPackage `requiredPlatformCapabilities` closure. Each entry binds a capability `code`, exact `contractVersion` and deterministic `usageDigest` of only that capability's normalized declarations. Never write `platform.requiredCapabilities`, append requirements through a build API, edit the AppPackage or accept a feature whose status is not `available` or whose contract version differs. The platform authoritatively recomputes the closure from the sealed config and contract artifacts.
+
+Ordinary list, detail, create, update and delete operations go directly through Data API. Add a NestJS endpoint only for a business action that cannot be represented as CRUD. Run `pnpm openxiangda check` after every contract change.

package/skills/openxiangda-v2/references/backend.md

@@ -0,0 +1,279 @@
+# OpenXiangda 2.0 Backend
+
+Read [Architecture](architecture.md) and [Data and authorization](data-authz.md)
+before adding a backend. Finish with [Testing](testing.md).
+
+Keep normal record CRUD in the platform Data API. Use `apps/server` only for typed business actions that need server-side logic. For an interactive request, the platform gateway supplies the verified current user, complete application-role union and capabilities. Controllers bind operations and capabilities through `openxiangda/nest`; workers continue to use their explicit application identity.
+
+Every interactive business action uses `@OpenXiangdaOperation(operation)`. The
+guard checks `operation.requiredCapability` once at App API ingress. Inside that
+declared action, inject `OpenXiangdaBusinessDataApiService`,
+`OpenXiangdaBusinessNotificationService`, or use
+`OpenXiangdaStandardOperations`: Native Data and Notification Hub then run as the trusted backend
+for this exact application, environment, version and operation. Do not forward
+the caller's resource, row or field permissions into that internal Data call,
+and do not author an `authorizationJSON` permission mirror. The platform still
+records the initiating user and action code in records, files, events and audit.
+The platform models this internal hop as the request-bounded
+`native-business-action` principal. It is neither an OAuth client nor a Native
+runtime credential: PostgreSQL accepts it only after the platform has verified
+the signed Gateway invocation, exact target/Head, published
+`code + requiredCapability`, application data scope and initiating user. Never
+copy an invocation token into application data, construct the action headers
+yourself, or fall back to `OpenXiangdaApplicationDataApiService` when this
+channel is rejected; a rejection means the platform/package combination is not
+compatible or the invocation is stale.
+
+For an informational business notification, inject
+`OpenXiangdaBusinessNotificationService` in the same declared action. The SDK
+uses the short-lived gateway invocation, never the caller's original login
+token. The platform rechecks the operation and capability, promotes the call to
+the exact application/environment principal, and records the initiating user
+and action. Do not grant ordinary users `app:notification2:send` and do not use
+the privileged `OpenXiangdaNotificationService` as an application workaround.
+
+```ts
+import { Inject } from '@nestjs/common';
+import {
+  OPENXIANGDA_NOTIFICATION_BUSINESS_SEND_V2,
+  OPENXIANGDA_NOTIFICATION_EVENT_SEND_V2,
+  OpenXiangdaBusinessNotificationService,
+} from 'openxiangda/nest';
+
+constructor(
+  @Inject(OpenXiangdaBusinessNotificationService)
+  private readonly notifications: OpenXiangdaBusinessNotificationService,
+) {}
+
+await this.notifications.send({
+  schemaVersion: OPENXIANGDA_NOTIFICATION_BUSINESS_SEND_V2,
+  eventId: body.eventId,
+  correlationId: `proposal:${proposal.id}`,
+  messageKey: `proposal:${proposal.id}:invite:${member.id}`,
+  sourceSequence: proposal.revision,
+  recipients: [{ userId: member.userId }],
+  title: '待您附议',
+  summary: proposal.title,
+  navigationTarget: {
+    kind: 'APP_ROUTE',
+    appCode: 'proposal_app',
+    routeCodes: {
+      desktop: 'proposal.detail',
+      mobile: 'proposal.detail-mobile',
+    },
+    pathParams: { id: proposal.id },
+    access: 'AUTHENTICATED',
+  },
+  idempotencyKey: `proposal:${proposal.id}:invite:${member.id}:v${proposal.revision}`,
+});
+
+```
+
+The fixed template accepts only `title` and optional `summary`. Reuse the same
+`eventId` or `idempotencyKey` for retries. Reuse `messageKey` with increasing
+`sourceSequence` for state convergence; do not generate a new logical message
+for each retry.
+
+The generated
+`notificationTemplateCodes.applicationInformational` constant documents the
+selected platform template; `send()` chooses it automatically and does not
+accept a caller-supplied template code.
+
+Inside a signed Application Events/date-trigger handler, call
+`sendFromEvent()` on the same service. The SDK obtains the application
+credential and forwards the current eventId, deliveryId and subscription code.
+Declare only dot paths beneath the immutable event `data`; Notification Hub
+resolves the actual Native user IDs and presentation text. Do not copy values
+from the event into a caller-supplied `recipients` array and never manufacture a
+user token.
+
+```ts
+await this.notifications.sendFromEvent({
+  schemaVersion: OPENXIANGDA_NOTIFICATION_EVENT_SEND_V2,
+  correlationId: `proposal:${event.data.proposalId}`,
+  messageKey: `proposal:${event.data.proposalId}:reminder`,
+  sourceSequence: event.data.revision,
+  recipientPaths: ['assigneeUserIds'],
+  titlePath: 'notification.title',
+  summaryPath: 'notification.summary',
+  navigationTarget: {
+    kind: 'APP_ROUTE',
+    appCode: 'proposal_app',
+    routeCodes: {
+      desktop: 'proposal.detail',
+      mobile: 'proposal.detail-mobile',
+    },
+    pathParams: { id: event.data.proposalId },
+    access: 'AUTHENTICATED',
+  },
+  idempotencyKey: event.id,
+});
+```
+
+`OpenXiangdaDataApiService` deliberately retains ordinary current-user Data
+authorization and automatically inherits the request Perspective for reads.
+Its writes still authorize against the complete role union. Do not use it to
+implement a declared business action. The
+business facade also rejects routes without immutable `OpenXiangdaOperation`
+metadata, so a controller cannot silently gain trusted Data access.
+
+If a custom controller bypasses the standard Data API and reads Nest-owned SQL,
+an external service or another datastore, inject `@CurrentPerspective()` and
+apply the declared role-based read projection explicitly. Perspective is not a
+credential and must never change mutation authorization. Prefer moving ordinary
+reads back to `OpenXiangdaDataApiService`, where the platform owns the contract.
+
+Do not duplicate resource persistence in controllers. Keep actions bounded and side-effect behavior explicit. Run `pnpm openxiangda dev` for the connected loop and `pnpm openxiangda check` before delivery.
+
+Keep the generated `apps/server/src/main.ts` on
+`bootstrapOpenXiangdaApplication(AppModule)`. Do not replace it with an
+application-owned `NestFactory` or `FastifyAdapter`: the SDK bootstrap owns the
+exact raw request bytes required by gateway signatures, proxy trust, shutdown
+hooks, and the runtime listen contract.
+
+Connected development and release builds deliberately use different compilers,
+so application Nest classes must never depend on emitted constructor metadata.
+Every constructor dependency in a `@Controller` or `@Injectable` class uses an
+explicit token:
+
+```ts
+import { Controller, Inject, Post } from '@nestjs/common';
+import { appOperations } from '@app/contracts';
+import {
+  OpenXiangdaBusinessDataApiService,
+  OpenXiangdaOperation,
+} from 'openxiangda/nest';
+
+@Controller()
+export class VisitorReservationsController {
+  constructor(
+    @Inject(OpenXiangdaBusinessDataApiService)
+    private readonly data: OpenXiangdaBusinessDataApiService,
+  ) {}
+
+  @Post('/api/reservations/enroll')
+  @OpenXiangdaOperation(appOperations.reservationEnroll)
+  async enroll() {
+    return await this.data.create('visitor-reservations', { status: 'pending' });
+  }
+}
+```
+
+`openxiangda check` and `openxiangda dev` reject implicit constructor injection.
+Do not silence that diagnostic or replace the connected-development compiler.
+
+Backend routes are private to the application unless their operation declaration contains an explicit `ai` block. Never infer AI exposure or risk from the HTTP method. A write action declares its touched resources and non-empty side effects, for example:
+
+Build operation request and response schemas through
+`resourceRecordSchema`, `schemaRef` and `composeAppOperationSchemas` from
+`openxiangda/config`. These helpers project canonical field value protocols
+from the same Resource declaration and prevent repeated user, department,
+resource-reference or managed-file shapes. Do not import a physical toolchain
+package or copy the JSON protocol by hand.
+
+```ts
+{
+  code: 'reservation.enroll',
+  method: 'POST',
+  path: '/api/reservations/enroll',
+  capability: 'app:visitor-app:reservation:enroll',
+  ...composeAppOperationSchemas({
+    request: resourceRecordSchema(visitorReservations, {
+      fields: ['visitorName', 'visitDate', 'startTime'],
+    }),
+    response: schemaRef('ReservationRecord'),
+    definitions: {
+      ReservationRecord: resourceRecordSchema(visitorReservations),
+    },
+  }),
+  ai: {
+    name: '预约访客',
+    description: '校验预约规则并创建访客预约',
+    risk: 'write',
+    resources: ['reservations'],
+    sideEffects: ['reservations:create'],
+    concurrency: 'none',
+    timeoutMs: 10000,
+  },
+}
+```
+
+Every custom operation capability is declared once in
+`authz.capabilities` with `kind: 'backend'`, then referenced by the operation
+and granted to every role allowed to call it. A capability string written only
+on an operation or role is invalid. Resource CRUD capabilities remain generated
+and must not be copied into this catalog.
+
+Generated CRUD and custom actions use the same platform Catalog, current-user authorization, Preview/Confirm boundary and idempotent execution path. Do not create an application-owned MCP server, preview store, AI role or database client.
+
+For visitor duplicates, meeting-time conflicts, and course capacity, use
+`OpenXiangdaStandardOperations`. These helpers submit the whole rule as one
+platform transaction. Do not query mutable rows before calling them and do not
+calculate replacement counters in application code. Course selection is a
+locked `record-assert` plus a bounded `increment`; replay must reach the
+platform idempotency receipt even after the course becomes full.
+
+The visitor helper has one exact command shape. `duplicateMatch` is the actual
+field-to-submitted-value object used for equality matching; it is never a list
+of field names:
+
+```ts
+return this.operations.createVisitorReservation({
+  reservationResourceCode: 'visitor-reservations',
+  duplicateMatch: {
+    visitorIdentityNumber: body.visitorIdentityNumber,
+    visitDate: body.visitDate,
+    startTime: body.startTime,
+  },
+  data: {
+    visitorIdentityNumber: body.visitorIdentityNumber,
+    visitDate: body.visitDate,
+    startTime: body.startTime,
+    status: body.status,
+  },
+  idempotencyKey: body.idempotencyKey,
+  activeStatusField: 'status',
+  activeStatusValues: ['pending', 'approved'],
+});
+```
+
+Use only declared field codes in `duplicateMatch`. Its values and `data` come
+from the same immutable request body.
+
+An idempotency key and the complete command payload are one immutable pair.
+Never put `new Date()`, `Date.now()`, `randomUUID()` or another changing value
+inside a controller while constructing the transaction. If a business time is
+part of the record, declare it as a required operation request field; the
+caller creates it once together with the idempotency key and reuses both on
+every retry. Platform-created record timestamps remain the source of truth
+when no separate business time is required.
+
+The Nest SDK automatically carries the platform Gateway `x-request-id` from a
+verified Named Action into its nested Data API, directory, workflow, and
+notification calls. Do not generate or replace that header in application
+code. If a strict authorization projection is temporarily unavailable, keep
+the complete command and `idempotencyKey` unchanged when retrying after the
+platform reports recovery: the Native transaction receipt returns the already
+committed items with `replayed: true` and does not repeat mutations or events.
+`OPENXIANGDA_AUTHORIZATION_PROJECTION_NOT_READY` is a fail-closed, retryable
+platform readiness response; it is not evidence that an earlier idempotent
+business transaction was rolled back. Diagnose it with the returned request id.
+
+When declaring a lower-level transaction directly, use only the current
+contract:
+
+- every guard has a stable `OPENXIANGDA_*` `errorCode`;
+- `query-empty` protects a business-key uniqueness rule;
+- `record-exists` requires one visible record without forcing a mutation of it;
+- `record-match` requires one visible record plus typed value/field assertions,
+  and may protect a mutation of another resource;
+- `record-assert` locks one exact record and checks declared field values or
+  declared field-to-field comparisons;
+- `databaseNowAssertion('publishAt', 'lte')` compares a declared `datetime`
+  field with the single PostgreSQL transaction time. Do not pass `Date.now()`,
+  an offset, a SQL function or a fallback timestamp; a successful idempotent
+  replay returns the original `evaluatedAt` without re-evaluating the guard;
+- `increment` targets one declared integer field and must have a matching
+  same-resource, same-record `record-assert` guard;
+- never send SQL, table names, expressions, old guards without `errorCode`, or
+  a pre-read/absolute-update fallback.

package/skills/openxiangda-v2/references/commands.md

@@ -0,0 +1,21 @@
+# OpenXiangda 2.0 Commands
+
+> Generated from `DEVKIT_COMMANDS`. Do not edit manually.
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `pnpm openxiangda create` | deploy | 创建、绑定并初始化应用 |
+| `pnpm openxiangda dev` | write-local | 连接平台测试数据启动本地 Web 与 Nest |
+| `pnpm openxiangda check` | write-local | 生成契约并在目标平台预检后执行检查、测试和构建 |
+| `pnpm openxiangda accept` | deploy | 按计划准备可选的真实预发验收身份 |
+| `pnpm openxiangda deploy` | deploy | 部署测试环境或显式复用测试版本部署生产 |
+| `pnpm openxiangda status` | read | 查询最近或指定部署状态 |
+| `pnpm openxiangda logs` | read | 查询最近或指定部署日志 |
+| `pnpm openxiangda cancel` | deploy | 幂等取消尚未提交激活的部署 |
+| `pnpm openxiangda retry` | deploy | 显式重试可恢复的失败部署 |
+| `pnpm openxiangda start` | deploy | 从当前不可变版本启动应用环境 |
+| `pnpm openxiangda stop` | deploy | 将应用环境缩容为零并保留数据 |
+| `pnpm openxiangda rollback` | deploy | 回滚测试或生产环境 |
+| `pnpm openxiangda login` | write-local | 通过平台浏览器授权登录 |
+| `pnpm openxiangda skill` | write-local | 安装当前版本的 AI Skill |
+| `pnpm openxiangda spec` | write-local | 维护可选的 AppSpec 需求与变更辅助 |