openxiangda-skill-kit 2.0.0-alpha.129 → 2.0.0-alpha.130

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.129",
+  "version": "2.0.0-alpha.130",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "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.",
-      "sha256": "99c39264c2159b1236db8b61a58825433b3083fd996ed63e29be4298f8b8f45f"
+      "sha256": "30164c69a712928b1d63bbc79a294820f9b1a330259e0c915dcd8c70c3fb356e"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -30,6 +30,7 @@ Use this order:
    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.

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

@@ -157,6 +157,57 @@ Notification Hub recipient projection and deep-links to the platform-resolved
 target. Do not query Notification Hub management endpoints or recreate a local
 message state store.
 
+When an application needs branded user-end composition, keep those generated
+routes and contribute renderers from the application entry through the public
+`openxiangda/react` contract:
+
+```tsx
+import {
+  defineApplicationContributions,
+  type StandardApplicationTodoCenterProps,
+  type StandardUserPageFrameProps,
+  type StandardUserSurfaceContributions,
+} from 'openxiangda/react';
+
+const standardUserSurfaces = {
+  frame: {
+    desktop: DesktopUserFrame,
+    mobile: MobileUserFrame,
+  },
+  applicationTodoCenter: {
+    desktop: DesktopTodoCenter,
+    mobile: MobileTodoCenter,
+  },
+} satisfies StandardUserSurfaceContributions;
+
+export const applicationContributions = defineApplicationContributions(
+  { routes: appRoutes, authenticationSurfaces },
+  { pages, authentication, standardUserSurfaces },
+);
+```
+
+Both desktop/mobile members and both groups are mandatory once
+`standardUserSurfaces` is present; partial families fail at compile time and
+again at runtime. Omit the property to retain the platform defaults.
+
+`StandardUserPageFrameProps` contains `pageKind`, `device`, `mobile`, rendered
+`children`, safe `route` metadata, `canGoBack` and the platform-owned `back()`
+callback. The frame wraps Todo and standard Workflow work-center, launch, task
+and instance pages. It must not create a Router, resolve identity, redirect a
+standard path or reinterpret route metadata as authorization.
+
+`StandardApplicationTodoCenterProps` contains only the authenticated current
+user's `items`, aggregate `counts`, `total`, `loading`, `loadingMore`, `error`,
+immutable `query`, `hasMore`, and the bounded callbacks `setQuery`, `refresh`,
+`loadMore`, `recordInteraction` and `openItem`. `setQuery` owns view, keyword,
+unread and paged-offset changes; `loadMore` appends and de-duplicates the next
+platform page; `openItem` records a click best-effort and uses the
+platform-resolved desktop/mobile target. Render only these props. Never import
+the private platform client, call Notification Hub endpoints, persist a Todo
+copy, accept a user/token parameter, or navigate from an item object not
+supplied by the current render. A renderer exception is contained by the
+platform error boundary without replacing `RuntimeBoundary` or the Router.
+
 The compiler also emits the required generated `routeManifest`. This is the
 single desktop/mobile paired catalog for standard Workflow and Todo pages. Each
 entry carries stable route codes, path parameters, access metadata and a

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

@@ -24,6 +24,7 @@
   admin shell, and do not make user-end utilities depend on `--oxa-antd-*`.
 - Bind every generated `appRoutes` entry to its local page with `defineApplicationContributions`; desktop `admin` routes stay inside the platform Shell, while `user` routes render without an admin Shell for independent mobile/user experiences. Generated resource CRUD routes are compiler-owned under `/admin/resources/<resourceCode>...` and `/m/admin/resources/<resourceCode>...`; never recreate root resource paths, aliases or redirects. Explicit routes that have the same canonical shape as another explicit or generated route fail compilation, even when dynamic parameter names differ. Use only the typed `toolbar`, `row` and `detail` resource slots for generated resource actions. Declare the complete editable admin menu with `defineAdminNavigation` and its page/group helpers; the Shell renders only generated `adminNavigation` references and permissions only filter them. Do not create another router, menu store, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API and Workflow authorization remain server-owned.
 - Application login is optional `frontend.authentication`: existing platform users only, registration rejected, exact desktop `/login` and mobile `/m/login`. Bind generated `authenticationSurfaces` to separate PC/mobile renderers through `defineApplicationContributions`; renderers own only brand visuals and call `ApplicationLoginSurfaceProps`. The platform alone owns passwords, providers, OAuth state/callbacks, secure cookies, current identity and authorization. Never put login in protected `appRoutes`, call a v1 auth route, store tokens, create users/roles, or add another Router/identity provider. Keep QA in generated `platformAuthManifest`, outside the protected route denominator.
+- Branded standard user pages use the optional exact `standardUserSurfaces` contribution from `openxiangda/react`: provide separate desktop/mobile `frame` and `applicationTodoCenter` renderers or omit the property entirely. The platform still owns `/todos`, `/m/todos`, Workflow routes, `RuntimeBoundary`, current-user Notification Hub data, query/load/interaction callbacks and navigation. Never add a second Router, Todo API client, identity store or token prop.
 - External users without platform accounts use only an exact static `surface: 'user'` route declared through `frontend.publicAccess`. Declare the one resource, bounded field sets, required operations, draft limits and named duplicate validations; consume only generated `anonymousPublicAccess` and `createAnonymousPublicClient`. `own.list`/`own.read` mean records submitted by the same platform-issued HttpOnly browser credential, not a verified natural person, and another browser or cleared cookie intentionally loses access. Never create a guest role/user, call the general Native Data API, expose an anonymous upload path, store identity locally or derive ownership from IP, user-agent or fingerprint.
 - Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional `mutationOwner`, generated/list/layout/data-policy settings. Each field owns type, label, required state, Surface flags, reference/file metadata and access. Resource codes are lower kebab-case. Use `native` for direct Data API mutations, `action`, `readonly` or `workflow` for non-Native ownership; never grant or generate Native mutation for a non-Native owner.
 - Never write resource-level `schemaVersion`, `appCode`, `schema`, `surface`, `capabilities`, `fieldPolicies` or `platform/data` modules. The compiler derives the strict DataResource, CRUD capabilities, Surface and AI Schema. The application manifest still starts with its one top-level `schemaVersion: 3`.