reachai-onboarding

# ReachAI Onboarding

## Operating Rules

Treat the current business repository as the source of truth. Inspect its Maven modules, Java version, Spring Boot version, configuration files, existing controller/service boundaries, and test commands before editing.

Never paste, print, or commit the registry app secret. Use the environment variable named by the manifest, normally `REACHAI_REGISTRY_APP_SECRET`.

Prefer minimal, reviewable changes:
- Add ReachAI dependencies only to the modules that need them.
- Put `reachai-spring-boot2-starter` in the runnable Spring Boot application module.
- Put `reachai-capability-sdk` in modules that declare `@ReachCapability` methods or DTO field metadata.
- Do not use the ReachAI platform base URL as a Maven repository, npm registry, or SDK file server. The platform onboarding URLs are only for the manifest, skill package, access-session reporting, and self-check APIs.
- Do not invent dependency download paths such as `/repository/**`, `/maven/**`, `/repository/maven/**`, `/api/embed/sdk`, or `/npm/**`. If Java or front-end artifacts cannot be resolved from the business repo's existing repositories, a corporate artifact repository, or the user's local Maven/npm cache, stop and report the missing artifact source.
- Avoid changing unrelated business logic, package structure, formatting, or dependency versions.
- For automatic Spring MVC scanning, restrict ReachAI to business-owned packages. Do not sync framework, platform, third-party, starter, or shared infrastructure controllers as business APIs.

## Workflow

1. Read the ReachAI onboarding manifest URL from the user prompt.
2. Download this skill package if it is not already installed, then read the reference files only as needed.
3. Detect the project layout:
   - Maven root and child modules.
   - Java source level.
   - Spring Boot version.
   - Runnable application module.
   - Business-owned Java base packages from application classes, controllers, services, and module names.
   - Framework/platform packages that should be excluded from ReachAI scanning.
   - Existing `application.yml`, `bootstrap.yml`, profile-specific config, or config-center conventions.
4. Add dependencies using `references/java-sdk-access.md` and `templates/pom-dependencies.xml`.
5. Add configuration using `templates/application-reachai.yml`, replacing the package placeholders with narrow business package allow-lists and framework/package deny-lists.
6. Select one or two low-risk query-style business methods and annotate them with `@ReachCapability` / `@ReachParam`. Use `templates/reach-capability-example.java` only as a style example.
7. Inspect the business gateway boundary before declaring onboarding complete:
   - Spring Cloud Gateway, Nginx, backend-for-frontend, or front-end dev proxy configuration.
   - Existing authentication headers and current-user extraction.
   - Whether a server-side token broker already exists.
8. Add or update the gateway route/token broker:
   - Route ReachAI capability traffic to the business service and preserve `X-ReachAI-Invocation-Token`, `X-ReachAI-Trace-Id`, `X-ReachAI-Run-Id`, and the business identity headers required by the service.
   - Expose a front-end token endpoint such as `/api/reachai/embed-token`.
   - Implement the token endpoint server-side so it maps the current business user to `principal.externalUserId`, signs the platform call with the project `appKey/appSecret`, and calls ReachAI `POST /api/embed/token/exchange`.
   - Keep `/api/reachai/embed-token` on the normal business login token path. It reads the current business user and exchanges that identity for a ReachAI embed token.
   - Add the gateway authentication whitelist or dedicated security chain for `/api/reachai/embed/**`. This path carries ReachAI embed tokens, so business OAuth/JWT filters must not validate it as a business login token; forward `Authorization: Bearer <embedToken>` unchanged to ReachAI.
   - In Spring Security WebFlux / OAuth2 Resource Server, `permitAll()` on `/api/reachai/embed/**` is not enough by itself: the resource server can still try to authenticate the `Bearer <embedToken>` before routing and return 401. Add a higher-priority `SecurityWebFilterChain` with `securityMatcher("/api/reachai/embed/**")` that permits all and does not enable `oauth2ResourceServer()` for that matcher.
   - Inspect whitelist/anonymous filters that remove or rewrite JWT headers, such as `IgnoreUrlsRemoveJwtFilter`, `RemoveJwtFilter`, `RemoveRequestHeader=Authorization`, or security filters that call `mutate().header("Authorization", "")`. Do not apply that header-clearing behavior to `/api/reachai/embed/**`; skipping business authentication must still preserve the embed token `Authorization` header.
   - If Spring Cloud Gateway proxies `/api/reachai/embed/**`, dedupe duplicate CORS response headers when both the gateway and ReachAI write them. A typical route filter is `DedupeResponseHeader=Access-Control-Allow-Origin Access-Control-Allow-Credentials, RETAIN_FIRST`.
   - Before front-end embed work, call `manifest.agentProvisioning.provisionAgentUrl` from the AI coding tool, local shell, or server-side integration step when present. It is idempotent and creates or reuses the project `PAGE_COPILOT` Agent plus its default Workflow binding.
   - Use the provisioning response `agent.keySlug` as the front-end `agentId`; write only that key slug into browser configuration. Fall back to `manifest.agentProvisioning.defaultKeySlug`, `manifest.agentWorkflow.globalAgentKeySlug`, or `manifest.embed.defaultAgentKeySlug` only when the provisioning API is unavailable.
   - Do not call provisioning from browser runtime code, and do not expose `aiCodingKey` to the business front end.
   - Do not ask the business user to manually create, choose, or configure the page copilot Agent during SDK onboarding.
   - Treat that Agent as the single embedded page copilot entry. Page-specific behavior is selected later by `pageKey` through A