Praxis Java Host Project
Overview
Use this skill to create a new Java host that composes the Praxis platform correctly instead of inventing local contracts. Treat published Praxis starters as external Maven dependencies by default; use local starter source only when it is actually present and the task is platform-development work.
Before changing this skill or implementing a Java host, audit the resolved starter or local platform source for the contract being used: @ApiResource, AbstractResourceController, AbstractReadOnlyResourceController, AbstractBaseResourceService, AbstractReadOnlyResourceService, ResourceMapper, schema/catalog controllers, capabilities, actions, surfaces, export, option sources, config headers/ETag, and a representative quickstart resource when available. The goal is to codify what Praxis already knows canonically before adding host-local endpoints, DTO fields, registries, or AI/config abstractions.
When local source is available, start with praxis-metadata-starter/AGENTS.md, praxis-config-starter/AGENTS.md, and praxis-api-quickstart/AGENTS.md to confirm the current starter and reference-host boundaries. When source is absent, use released dependency metadata, generated docs, Maven artifacts, and HTTP behavior instead of requiring the monorepo.
When preparing a starter publication required for public host adoption, read
starter-publication-and-adoption.md.
Keep signed source, validated bundle, Central deployment, artifact availability
and consumer adoption as separate evidence gates. Follow the owning repository's
actual release workflow; this skill does not authorize a release.
Required Classification
Classify the request before editing:
arquitetural when creating a new host, choosing starter boundaries, or changing bootstrap structure.
contrato-publico when changing resource paths, @ApiResource, DTO schema, x-ui, /schemas/**, capabilities, actions, headers, or /api/praxis/config/**.
transversal when updating the host plus docs/examples/http corpus or shared starters.
local-pequena only for a contained host implementation detail with no public contract impact.
docs-apenas for editorial guidance only.
For arquitetural, contrato-publico, or transversal, map impact before patches: canonical owner, affected consumers, public docs, examples/playgrounds/HTTP corpus, minimum validation, and breaking-change risk.
Workflow
- Read the host repository's
AGENTS.md files when present.
- Determine dependency mode:
- Published dependency mode, default: the host consumes
io.github.codexrodrigues:praxis-metadata-starter and, when needed, io.github.codexrodrigues:praxis-config-starter from Maven Central or the configured artifact repository.
- Local Maven mode: the host consumes a starter version already installed in
~/.m2; do not assume source code is available.
- Platform source mode: starter source is present in the same workspace; inspect it only when debugging starter behavior or changing platform contracts.
- Resolve versions from the user's requested release, the host's existing
pom.xml, Maven Central metadata, or the reference host documentation. Prefer the public reference host https://github.com/codexrodrigues/praxis-api-quickstart-public when a local quickstart checkout is unavailable, but treat it as an example/reference, not a file dependency. Use local praxis-api-quickstart source only if it is available locally and the task benefits from comparing against the private/reference host. For consumer hosts, do not assume any quickstart pom.xml version has been published; prove artifact availability with Maven metadata or mvn dependency:get, preferably with a temporary -Dmaven.repo.local when the task is about an external scaffold.
- Decide whether the new project is:
- a minimal host proving platform bootstrap;
- a domain host with real resources;
- a reference/demo host that must mirror quickstart breadth.
- Collect or infer the minimum resource contract before generating files: base package, module, entity/projection name, ID type,
resourcePath, stable resourceKey, OpenAPI group, mutability/read-only mode, real fields, relationships, filter needs, option/lookup needs, and whether surfaces/actions/export/stats are in scope.
- Generate resource files in dependency order using the exact generic signatures and templates in resource-baseline.md (including Section 0 for complete
pom.xml/application.yml bootstrap with -parameters, MapStruct/Lombok annotation processors, springdoc.writer-with-order-by-keys: true, and praxis.resource-version.etag.secret). For a new application prefer ApiPaths, entity/projection, repository, DTOs, mapper, service, controller. For an existing application adding a resource, prefer DTOs, repository, mapper, service, controller, and only then surfaces, intents, actions, export, or analytics.
- Use the canonical resource-oriented baseline and deliver the Full-Power Praxis Value Pack on the first shot so the resource compiles immediately and showcases the platform without back-and-forth:
@ApiResource(value=..., resourceKey=..., title=..., description=..., icon=..., visualTone=..., identity=@ResourceIdentity(...), quickFilters={@QuickFilter(...)}) (note: @ApiResource is already meta-annotated with @RestController and @RequestMapping);
@ApiGroup(...) with semantic/visual metadata when grouping is meaningful;
- Entity with
@OptionLabel on the canonical human label getter/field (enabling /options/filter and /options/by-ids automatically) and @DefaultSortColumn;
BaseCrudRepository<E, ID>;
ResourceMapper<E, ResponseDTO, CreateDTO, UpdateDTO, ID> (note: ID is 5th; applyUpdate(E entity, UpdateDTO dto) takes entity first and must never overwrite route-owned id);
AbstractBaseResourceService<E, ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO> (note: ID is 3rd) overriding getResourceMapper(), getDatasetVersion(), getStatsFieldRegistry(), and StatsSupportMode.AUTO (getGroupByStatsSupportMode(), getTimeSeriesStatsSupportMode(), getDistributionStatsSupportMode(), getComparisonStatsSupportMode()) so /stats/* works out of the box;
AbstractResourceController<ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO> (note: 5 type params, no E, ID is 2nd) overriding getService() and getResponseId(ResponseDTO dto);
AbstractReadOnlyResourceController<ResponseDTO, ID, FilterDTO> and AbstractReadOnlyResourceService<E, ResponseDTO, ID, FilterDTO> for read-only views/projections;
- mutable resources: separate
ResponseDTO, CreateDTO (@JsonIgnoreProperties({"id"})), UpdateDTO (@JsonIgnoreProperties({"id"})), and FilterDTO implements GenericFilterDTO with rich domain @Schema(description=...), @UISchema (preset, controlType, numericFormat, group, order, icon, quickViewVisible, helpText), @DomainGovernance/@AiUsagePolicy, and a multi-operator @Filterable matrix (LIKE, EQUAL, IN, BETWEEN, IN_LAST_DAYS);
- read-only resources:
ResponseDTO and FilterDTO only;
- Composite PKs (
@EmbeddedId), Optimistic Concurrency (@Version), Governed Relationships (@ResourceReference / OptionSourceRegistry + Rich EntityLookupDescriptor), @Embedded Value Objects, JSONB @CustomFields, @ResourceFact, @MicroVisualization, @UiAnalytics, Governed Bulking (@BulkEditable / @BulkResourceOperations / @BulkOperation), Rich CollectionExport (CSV/JSON/EXCEL + CollectionExportFieldPresentation), ReactiveDeterminationDefinitionProvider, and Native JUnit Completeness Gate (SemanticMetadataReviewer + PraxisExpressionStaticValidator + OptionSourcePublicationInventory): follow Sections 9, 10, 11, 12, and 13 of resource-baseline.md and the 20-Pillar / 3-Phase Blueprint (META-INF/praxis/AI-RESOURCE-BLUEPRINT.md bundled in praxis-metadata-starter or GUIA-00-BLUEPRINT-COMPLETO-RECURSO-PRAXIS.md). Never attempt a multi-resource showcase in a single shallow pass; execute in 3 deep vertical phases (Phase 1: Data/DTOs/@UISchema/@MicroVisualization/Quick View 360°/Rich Lookups/FilterDTO; Phase 2: @UiSurface/@ResourceIntent/@WorkflowAction/Bulking/@ResourceFact/@UiAnalytics/CollectionExport; Phase 3: Domain Invariants/ReactiveDetermination/praxis-rules-engine//praxis/cockpit/N+1 & Completeness Gates).
- Treat
AbstractCrudController, AbstractReadOnlyController, BaseCrudService, and similar pre-resource-oriented classes as migration surfaces only. Do not use them as the default for new resources when the resolved starter exposes the resource-oriented baseline.
- Include
praxis-config-starter only when the host must expose /api/praxis/config/** or AI authoring/config-store surfaces and can provide the required config-store datasource, migrations/tables, and host adapters. Do not include it for a metadata/filter-only service. Before adding it, confirm the target host meets the starter's release prerequisites such as compatible Spring Boot baseline, supported config database/store, Flyway/baseline strategy, AI/RAG secrets when enabled, stream/auth policy, and required host adapters.
- Keep starter semantics in the starters. Do not patch a new host to redefine
x-ui, /schemas/filtered, /schemas/catalog, /schemas/domain, actions, capabilities, export, config headers, ETag, or AI contracts.
- Create only the host-owned code needed for the domain: application bootstrap, dependency composition, security/origin policy, datasource properties, resources, tests, and documentation.
- Validate with the smallest reliable command after inspecting which tests connect to a database. Local execution is limited to unit tests without a database. Use an explicitly assigned isolated remote Neon branch for database-backed tests; add real HTTP/schema proof when the task claims the runtime metadata endpoints work.
Diagnose Missing UI Metadata After Dependency Changes
When @UISchema is present on DTOs but generated x-ui is absent or incomplete after a Spring Boot, Springdoc, Swagger Jakarta, or starter version change, read openapi-metadata-troubleshooting.md to audit CustomOpenApiResolver ABI, OpenAPI 3.0 vs. 3.1 dialect wiring, and ModelConverters pipeline proofs before changing DTO annotations.
Reference Resource Audit
When the user asks to make an existing backend resource an exemplar for future
hosts or migrations, do not stop at "it compiles" or "the endpoint exists".
Audit the complete Praxis contract and classify reusable findings before
changing code:
- For migration or reference-host work, use the consumer workspace's approved
playbooks, phase gates, semantic-contract checkers, and reference-audit
templates when they exist. Do not copy the newest pilot blindly. Classify the
reusable backend shape first: read-only, partial mutable resource, full CRUD,
workflow action, related surface, master-detail resource, shared related
write, or blocked/deferred flow. A package marked not-reference-ready or
control-only must not become a platform reference until the consumer gate is
repaired and explicitly promotes it.
- Confirm the resource uses the narrowest canonical baseline that matches the
real operation state: read-only, read + create/update, full CRUD,
duplicate-draft, workflow action, related surface, or blocked/deferred.
- Verify response DTO, FilterDTO, command DTOs, option DTOs and lookup
descriptors publish deliberate
@Schema, @UISchema, validation,
governance and options metadata. Public text must be semantic product
documentation, not labels copied into descriptions.
- Execute or inspect focused runtime evidence for
/filter, detail/by-ids,
/options/filter, /options/by-ids, /schemas/filtered,
/schemas/surfaces, /schemas/actions, /schemas/domain when available,
item/collection capabilities and HATEOAS links/actions.
- For each write-like operation, record whether it is implemented, blocked,
deferred, not API, direct-table safe, or legacy/DB-backed required. Do not
infer delete, duplicate, or workflow actions from a legacy button label.
- Check that private context and locators such as tenant/company, user,
profile, session, SQL names, ROWID, package flags, and bridge internals stay
server-side and do not appear in DTOs, schemas, option payloads or x-ui.
- For related tabs or child resources, prefer
@UiSurface plus real
resource/operation/schema paths. Host-specific links may be assembled locally
when they are domain composition, but availability and schema semantics must
still come from canonical Praxis/host services.
- Separate platform gaps from host gaps. If a recurring need belongs in
praxis-metadata-starter, praxis-config-starter, shared starters, public
docs, examples, or this skill, record/update the canonical owner instead of
hiding the problem in the consumer host.
- Update handoff/parity artifacts after late-scope implementation. A resource
is not a good reference if final docs contradict implemented endpoints or
validated operation states.
Skill Coverage
This skill is sufficient for ordinary Java host API work with praxis-metadata-starter: project bootstrap, Maven dependency wiring, resource-oriented CRUD/read APIs, DTOs, filters, schemas, OpenAPI discovery, capabilities, surfaces, options, cursor/locate, stats, and collection export.
(In external Antigravity workspaces, full companion skills are available under ~/.gemini/praxis-skills/<skill-name>/SKILL.md or $CODEX_HOME/skills/<skill-name>/SKILL.md.)
Use companion Praxis skills when the API needs a specialized platform surface:
- Use
praxis-metadata-resource-baseline when choosing resource-oriented controllers/services, ResourceMapper, filters, HATEOAS envelopes, export, stats, and canonical CRUD/read-only baselines.
- Use
praxis-metadata-schema-contracts for x-ui, /schemas/filtered, schema hashes, OpenAPI operation resolution, ETag, and Angular schema consumption.
- Use
praxis-metadata-discovery-capabilities for surfaces, actions, capabilities, _links, availability, related resources, stats, and export discovery.
- Use
praxis-metadata-domain-option-sources for domain governance, field access, option sources, entity lookup, lookup/by-ids contracts, and semantic metadata review.
- Use
praxis-config-runtime-persistence, praxis-config-ai-registry-manifests, praxis-config-api-metadata-grounding, praxis-config-agentic-authoring-streaming, or praxis-config-domain-decisions before adding /api/praxis/config/**, AI registry, RAG/API metadata, authoring, SSE, or governed decision surfaces.
- Use
praxis-api-quickstart-operational-proof, praxis-api-quickstart-security-config, praxis-api-quickstart-domain-pilots, and praxis-api-quickstart-cockpit-http-validation when a host should mirror or validate against the reference operational proof.
- Use
praxis-http-examples-corpus-manifest, praxis-http-examples-contract-surfaces, and praxis-http-examples-llm-smoke when a Java-host change must update executable HTTP examples, public corpus promises, or LLM-facing lanes.
- Use
praxis-landing-public-docs-contracts and praxis-landing-registries-sitemap-playgrounds when the host change affects public docs, guides, examples, sitemap, LLM files, or landing projections.
- Use
praxis-dto-annotations when filling or reviewing @Schema, @UISchema,
@Filterable, @DomainGovernance, FieldControlType, PT-BR labels/help text, groups, icons,
options, and DTO/OpenAPI documentation for hosts that consume praxis-metadata-starter.
- Use
praxis-resource-entity-lookup-backend for governed RESOURCE_ENTITY lookup, OptionSourceRegistry, LIGHT_LOOKUP, x-ui.optionSource, provider policies, and option-source endpoints.
- Use
praxis-component-minimums when the question is about the minimum frontend/host runtime wiring needed for Angular components to consume this backend.
- Use
praxis-dynamic-fields-editorial when changing or validating control types, dynamic-field aliases, or Angular renderability beyond the Java/OpenAPI contract.
- Use
praxis-authoring-editors only for authored UI/editor/config persistence workflows, not for ordinary backend resources.
Do not use consumer-specific fieldspec guidance for Praxis resources unless the task explicitly targets that legacy fieldspec stack. For Praxis APIs, praxis-metadata-starter annotations and contracts are the source of truth.
Canonical Boundaries
praxis-metadata-starter owns x-ui, /schemas/filtered, /schemas/catalog, /schemas/surfaces, /schemas/actions, /schemas/domain, capabilities, OpenAPI enrichment, HATEOAS schema links, export contracts, governance metadata, and resource-oriented base contracts.
praxis-config-starter owns /api/praxis/config/**, persisted UI config, AI registry, templates, config headers, config ETag, authoring/context contracts, and the governed boundary for semantic-decision authoring, simulation, approval, publication, and materialization when that feature set is in scope.
- The new host owns Spring Boot composition, dependency versions, datasource wiring, security policy, concrete domain resources, domain persistence, and downstream proof that selected starters work in a real service.
praxis-api-quickstart-public is the preferred public reference host for external users and LLMs. praxis-api-quickstart local/private source is useful when available for platform development and comparison. Neither is a required checkout or the canonical owner of starter semantics.
Schema And Decision Boundaries
- Treat
/schemas/filtered as the structural schema source for UI/runtime consumption. Treat /schemas/catalog as documentation/discovery, /schemas/surfaces and /schemas/actions as semantic discovery, /schemas/domain as AI-operable domain vocabulary, and resource capabilities as aggregate availability snapshots. Do not use catalogs or capabilities as a second structural schema source.
- For AI or assistant features in a Java host, do not route primary user intent with keyword lists, regex command matching, or controller-local text heuristics. Expose canonical resources, tools, operation schemas, catalogs, surfaces, actions, capabilities, governed context, and config-starter contracts so semantic resolution can be LLM/governance-led and then grounded against those canonical candidates.
- If a required AI/config tool or contract is missing, model the tool or contract in the canonical owner, usually
praxis-config-starter for authoring/config decisions or praxis-metadata-starter for metadata discovery. Do not compensate by adding host-local AI registries, patch formats, magic request fields, or string-routing shortcuts.
- Before adding a new host contract, inventory whether the platform already publishes the needed fact through DTO annotations, OpenAPI enrichment,
x-ui, option sources, surfaces, actions, capabilities, domain catalog, config headers/ETag, quick replies, previews, diagnostics, or materializations. Classify the finding as already supported, poorly materialized, partial, or a real contract gap.
Project Baseline
Use Java 21 unless the selected starter release documents a different baseline. Prefer Maven unless the target host already standardizes on Gradle.
When no local platform repo is present, do not inspect praxis-metadata-starter or praxis-config-starter source. Use the dependency's public package names, generated API docs, Maven dependency metadata, javap against resolved jars when necessary, and runtime HTTP validation.
Minimum dependencies for a CRUD host usually include:
spring-boot-starter-web
spring-boot-starter-data-jpa
spring-boot-starter-validation
spring-boot-starter-actuator
spring-boot-starter-security when the host exposes real HTTP endpoints
praxis-metadata-starter
praxis-config-starter only when the host must provide /api/praxis/config/** and its required config-store/RAG/domain adapters
- database driver
- MapStruct and Lombok if following quickstart mapper/entity conventions
spring-boot-starter-test for tests; use the selected PostgreSQL driver for assigned remote Neon database proof, not H2 or embedded/local database substitutes
In Maven, declare explicit starter versions unless the host imports a managed Praxis BOM or parent:
<properties>
<praxis.core.version><!-- selected released version --></praxis.core.version>
</properties>
<dependency>
<groupId>io.github.codexrodrigues</groupId>
<artifactId>praxis-metadata-starter</artifactId>
<version>${praxis.core.version}</version>
</dependency>
Application bootstrap must scan the host package and the metadata starter package:
@SpringBootApplication(scanBasePackages = {
"com.example.praxis.<host>",
"org.praxisplatform.uischema"
})
Do not copy historical quickstart controllers literally. In the current starter, @ApiResource is the resource declaration and already supplies the necessary controller/request-mapping semantics; only add extra Spring stereotypes when the resolved starter version or target host pattern explicitly requires them.
If praxis-config-starter is in scope, treat it as a separate config-store boundary. Include org.praxisplatform.config scanning, config starter JPA repository/entity wiring, migrations/tables, and datasource configuration only when the host actually exposes /api/praxis/config/**. Do not point a legacy Oracle application datasource at the config store by accident; config/AI persistence normally needs its own supported store and baseline.
Domain Documentation Rule
Do not generate @Schema(description=...) in bulk from labels, property names, or camelCase. Investigate each field and write domain descriptions deliberately: what the field represents, constraints, relationships, and business impact. Keep @UISchema for UI behavior and labels; keep @Schema as product/domain documentation.
Also write @Operation, @ResourceIntent, @UiSurface, and @WorkflowAction text as semantic product contract. These strings feed /schemas/catalog, /schemas/surfaces, /schemas/actions, /schemas/domain, capabilities snapshots, RAG, and LLM consumers. Do not rely on generic Springdoc fallback summaries for public resource operations.
Deep Domain & Relational Synthesis Rule ("Além do Óbvio")
Do not act as a mechanical 1 table = 1 obvious CRUD generator. Analyze the business domain and the relationship graph between entities (@ManyToOne, @OneToMany, @Embedded) to uncover non-obvious enterprise capabilities across 3 dimensions:
- Deep Filtering & Unified Broad Search (
@Filterable(relations = {...})): Every operational FilterDTO must include at least one broad/omnibox search field (searchTerm / buscaAmpla / identificacaoOuFamiliar) using @Filterable(operation = FilterOperation.LIKE, relations = {"fullName", "socialName", "motherName", "fatherName", "dependents.fullName", "taxId"}) so users can search across name, surname, parent/dependent name, or ID in one input (OR), plus multi-operator coverage on the same attribute (LIKE+STARTS_WITH+EQUAL+IN, BETWEEN+IN_LAST_DAYS+IN_NEXT_DAYS, completeness IS_NULL/IS_NOT_NULL, collection cardinality SIZE_GT/SIZE_EQ) and multi-level cross-entity paths (relation = "department.costCenter.region").
- Exhaustive Bulking Discovery Across All 3 Modes: Audit 100% of mutable attributes instead of picking 2–3 obvious fields: enable
BulkMode.UNIFORM_UPDATE on all collective standardization fields (unit, cost center, shift, regime/plan, payment/bank, manager, flags); enable BulkMode.PER_ITEM_UPDATE broadly on inline batch-grid revision fields (phones, emails, addresses, bank accounts, individual amounts/limits, external codes, per-item dates); and analyze entity relationships and lifecycle to create collective BulkMode.DOMAIN_COMMAND @WorkflowAction(scope = ActionScope.COLLECTION) operations (batch relocation across units, batch approval/homologation, batch suspension/reactivation, parametric revision).
- New Cross-Entity Endpoints & Subdomain Intents: Create dedicated read-only analytical/consolidated endpoints (
AbstractReadOnlyResourceController) when entity relationships answer cross-table operational questions (vacancy/occupancy matrices, expiring-items radar, compliance audits), expose all 1:N child collections as 360° surfaces (@UiSurface + relatedChildResourceKey), and decompose broad entities into persona-oriented @ResourceIntent (PATCH + SurfaceKind.PARTIAL_FORM) endpoints.
For sensitive fields or fields that should guide AI/RAG behavior, use @DomainGovernance, AiUsagePolicy, and AiUsageMode deliberately. Validate that governance appears in x-domain-governance on /schemas/filtered and is reflected in /schemas/domain when the host publishes the domain catalog.
Validation
Prefer focused validation:
- New host scaffold or resource compile proof: select the host's unit tests that do not open database connections; use
mvn -B test only after confirming its complete selection is database-free or all database cases use the reviewed Neon assignment.
- Published dependency proof for external hosts: resolve starter artifacts with Maven metadata or
mvn dependency:get, preferably using a temporary local Maven repository when the task must prove no monorepo dependency.
- Metadata/public contract proof: add or run a focused
@SpringBootTest/MockMvc or TestRestTemplate test for /v3/api-docs, /schemas/filtered, /schemas/catalog, /schemas/surfaces, /schemas/actions, /schemas/domain when available, resource filter, options, actions, and capabilities.
- Config starter proof: assign isolated remote Neon API/Config resources explicitly, verify project/child/endpoint/PostgreSQL identity and client TLS before connecting, and prove the real owner/runtime/control-plane privileges and memberships required by the flow. Keep credentials private, bound fixture writes and cleanup to the assignment, preserve inherited data, and test
/api/praxis/config/** with the host's required headers/origin. A privileged fixture is not proof of the ordinary runtime path; do not disable migrations merely to imitate an old local fixture.
- Dependency/version change: confirm Maven resolution and run at least the host's test phase.
- For a full resource proof, execute the endpoints the UI/runtime will rely on:
/filter, /filter/cursor, /locate, /options/filter, /options/by-ids, option-source endpoints when registered, /schemas/filtered, /schemas/catalog, /schemas/surfaces?resource=..., /schemas/actions?resource=..., /schemas/domain when available, collection and item /capabilities, collection and item /actions, item /surfaces, configured /stats/*, and /export when collection export is supported.
Do not copy historical H2, embedded PostgreSQL or Testcontainers fixtures from
reference hosts or checklists into a new database proof. A reference host may
still contain unmigrated local database tests in its broad Maven/release gate;
record that gap and migrate or compose the complete required case matrix on
assigned Neon resources before release. Removing those tests, accepting skips,
or replacing them with a focal SDK-adoption or cold-start proof does not close
the broad release gate. Unit and focal passes remain evidence only for their
stated scope. Follow the owning repository's actual private and sanitized-public
release gates, retaining source/dependency identity, raw reports and cleanup.
When validation is partial, state exactly what ran and what remains unvalidated.
References
- Read
references/resource-baseline.md before implementing concrete resources (contains the exact generic signatures, starter imports, and the complete 1-Shot Golden Path code template).
- Read
references/host-checklist.md before finalizing a scaffold or reporting completion.
- Read
references/openapi-metadata-troubleshooting.md when diagnosing missing x-ui metadata after Spring Boot, Springdoc, or starter version changes.
- When local platform docs are available, use
praxis-metadata-starter/docs/guides/GUIA-01-AI-BACKEND-APLICACAO-NOVA.md, GUIA-02-AI-BACKEND-CRUD-METADATA.md, GUIA-04-QUANDO-USAR-RESOURCE-SURFACE-ACTION-CAPABILITY.md, GUIA-05-DO-CRUD-AO-CONTRATO-SEMANTICO.md, GUIA-06-REDACAO-SEMANTICA-DE-ANNOTATIONS-PARA-IA.md, FILTROS-E-PAGINACAO.md, OPTIONS-ENDPOINT.md, and COLLECTION-EXPORT.md as supporting references for gaps not covered here.
1---2name: praxis-java-host-project3description: Create or evolve Java/Spring Boot backend host projects for the Praxis platform using published Maven starter dependencies by default. Use when Codex must scaffold a new Praxis Java microservice, choose Praxis starter versions, wire praxis-metadata-starter or praxis-config-starter, create resource-oriented controllers/services/DTOs, adapt reference host patterns when available, or validate a host publishes canonical Praxis metadata surfaces such as /schemas/filtered, /schemas/domain, ApiResource, x-ui, actions, capabilities, export, and /api/praxis/config/**.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-java-host-project6---78# Praxis Java Host Project910## Overview1112Use this skill to create a new Java host that composes the Praxis platform correctly instead of inventing local contracts. Treat published Praxis starters as external Maven dependencies by default; use local starter source only when it is actually present and the task is platform-development work.1314Before changing this skill or implementing a Java host, audit the resolved starter or local platform source for the contract being used: `@ApiResource`, `AbstractResourceController`, `AbstractReadOnlyResourceController`, `AbstractBaseResourceService`, `AbstractReadOnlyResourceService`, `ResourceMapper`, schema/catalog controllers, capabilities, actions, surfaces, export, option sources, config headers/ETag, and a representative quickstart resource when available. The goal is to codify what Praxis already knows canonically before adding host-local endpoints, DTO fields, registries, or AI/config abstractions.1516When local source is available, start with `praxis-metadata-starter/AGENTS.md`, `praxis-config-starter/AGENTS.md`, and `praxis-api-quickstart/AGENTS.md` to confirm the current starter and reference-host boundaries. When source is absent, use released dependency metadata, generated docs, Maven artifacts, and HTTP behavior instead of requiring the monorepo.1718When preparing a starter publication required for public host adoption, read19[starter-publication-and-adoption.md](references/starter-publication-and-adoption.md).20Keep signed source, validated bundle, Central deployment, artifact availability21and consumer adoption as separate evidence gates. Follow the owning repository's22actual release workflow; this skill does not authorize a release.2324## Required Classification2526Classify the request before editing:2728- `arquitetural` when creating a new host, choosing starter boundaries, or changing bootstrap structure.29- `contrato-publico` when changing resource paths, `@ApiResource`, DTO schema, `x-ui`, `/schemas/**`, capabilities, actions, headers, or `/api/praxis/config/**`.30- `transversal` when updating the host plus docs/examples/http corpus or shared starters.31- `local-pequena` only for a contained host implementation detail with no public contract impact.32- `docs-apenas` for editorial guidance only.3334For `arquitetural`, `contrato-publico`, or `transversal`, map impact before patches: canonical owner, affected consumers, public docs, examples/playgrounds/HTTP corpus, minimum validation, and breaking-change risk.3536## Workflow37381. Read the host repository's `AGENTS.md` files when present.392. Determine dependency mode:40 - **Published dependency mode, default**: the host consumes `io.github.codexrodrigues:praxis-metadata-starter` and, when needed, `io.github.codexrodrigues:praxis-config-starter` from Maven Central or the configured artifact repository.41 - **Local Maven mode**: the host consumes a starter version already installed in `~/.m2`; do not assume source code is available.42 - **Platform source mode**: starter source is present in the same workspace; inspect it only when debugging starter behavior or changing platform contracts.433. Resolve versions from the user's requested release, the host's existing `pom.xml`, Maven Central metadata, or the reference host documentation. Prefer the public reference host `https://github.com/codexrodrigues/praxis-api-quickstart-public` when a local quickstart checkout is unavailable, but treat it as an example/reference, not a file dependency. Use local `praxis-api-quickstart` source only if it is available locally and the task benefits from comparing against the private/reference host. For consumer hosts, do not assume any quickstart `pom.xml` version has been published; prove artifact availability with Maven metadata or `mvn dependency:get`, preferably with a temporary `-Dmaven.repo.local` when the task is about an external scaffold.444. Decide whether the new project is:45 - a minimal host proving platform bootstrap;46 - a domain host with real resources;47 - a reference/demo host that must mirror quickstart breadth.485. Collect or infer the minimum resource contract before generating files: base package, module, entity/projection name, ID type, `resourcePath`, stable `resourceKey`, OpenAPI group, mutability/read-only mode, real fields, relationships, filter needs, option/lookup needs, and whether surfaces/actions/export/stats are in scope.496. Generate resource files in dependency order using the exact generic signatures and templates in [resource-baseline.md](references/resource-baseline.md) (including Section 0 for complete `pom.xml`/`application.yml` bootstrap with `-parameters`, MapStruct/Lombok annotation processors, `springdoc.writer-with-order-by-keys: true`, and `praxis.resource-version.etag.secret`). For a new application prefer `ApiPaths`, entity/projection, repository, DTOs, mapper, service, controller. For an existing application adding a resource, prefer DTOs, repository, mapper, service, controller, and only then surfaces, intents, actions, export, or analytics.507. Use the canonical resource-oriented baseline and deliver the **Full-Power Praxis Value Pack** on the first shot so the resource compiles immediately and showcases the platform without back-and-forth:51 - `@ApiResource(value=..., resourceKey=..., title=..., description=..., icon=..., visualTone=..., identity=@ResourceIdentity(...), quickFilters={@QuickFilter(...)})` (note: `@ApiResource` is already meta-annotated with `@RestController` and `@RequestMapping`);52 - `@ApiGroup(...)` with semantic/visual metadata when grouping is meaningful;53 - Entity with `@OptionLabel` on the canonical human label getter/field (enabling `/options/filter` and `/options/by-ids` automatically) and `@DefaultSortColumn`;54 - `BaseCrudRepository<E, ID>`;55 - `ResourceMapper<E, ResponseDTO, CreateDTO, UpdateDTO, ID>` (note: `ID` is 5th; `applyUpdate(E entity, UpdateDTO dto)` takes `entity` first and must never overwrite route-owned `id`);56 - `AbstractBaseResourceService<E, ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO>` (note: `ID` is 3rd) overriding `getResourceMapper()`, `getDatasetVersion()`, `getStatsFieldRegistry()`, and `StatsSupportMode.AUTO` (`getGroupByStatsSupportMode()`, `getTimeSeriesStatsSupportMode()`, `getDistributionStatsSupportMode()`, `getComparisonStatsSupportMode()`) so `/stats/*` works out of the box;57 - `AbstractResourceController<ResponseDTO, ID, FilterDTO, CreateDTO, UpdateDTO>` (note: 5 type params, no `E`, `ID` is 2nd) overriding `getService()` and `getResponseId(ResponseDTO dto)`;58 - `AbstractReadOnlyResourceController<ResponseDTO, ID, FilterDTO>` and `AbstractReadOnlyResourceService<E, ResponseDTO, ID, FilterDTO>` for read-only views/projections;59 - mutable resources: separate `ResponseDTO`, `CreateDTO` (`@JsonIgnoreProperties({"id"})`), `UpdateDTO` (`@JsonIgnoreProperties({"id"})`), and `FilterDTO implements GenericFilterDTO` with rich domain `@Schema(description=...)`, `@UISchema` (`preset`, `controlType`, `numericFormat`, `group`, `order`, `icon`, `quickViewVisible`, `helpText`), `@DomainGovernance`/`@AiUsagePolicy`, and a multi-operator `@Filterable` matrix (`LIKE`, `EQUAL`, `IN`, `BETWEEN`, `IN_LAST_DAYS`);60 - read-only resources: `ResponseDTO` and `FilterDTO` only;61 - **Composite PKs (`@EmbeddedId`), Optimistic Concurrency (`@Version`), Governed Relationships (`@ResourceReference` / `OptionSourceRegistry` + Rich `EntityLookupDescriptor`), `@Embedded` Value Objects, JSONB `@CustomFields`, `@ResourceFact`, `@MicroVisualization`, `@UiAnalytics`, Governed Bulking (`@BulkEditable` / `@BulkResourceOperations` / `@BulkOperation`), Rich `CollectionExport` (`CSV`/`JSON`/`EXCEL` + `CollectionExportFieldPresentation`), `ReactiveDeterminationDefinitionProvider`, and Native JUnit Completeness Gate (`SemanticMetadataReviewer` + `PraxisExpressionStaticValidator` + `OptionSourcePublicationInventory`):** follow Sections 9, 10, 11, 12, and 13 of [resource-baseline.md](references/resource-baseline.md) and the 20-Pillar / 3-Phase Blueprint (`META-INF/praxis/AI-RESOURCE-BLUEPRINT.md` bundled in `praxis-metadata-starter` or `GUIA-00-BLUEPRINT-COMPLETO-RECURSO-PRAXIS.md`). Never attempt a multi-resource showcase in a single shallow pass; execute in 3 deep vertical phases (Phase 1: Data/DTOs/`@UISchema`/`@MicroVisualization`/Quick View 360°/Rich Lookups/`FilterDTO`; Phase 2: `@UiSurface`/`@ResourceIntent`/`@WorkflowAction`/Bulking/`@ResourceFact`/`@UiAnalytics`/`CollectionExport`; Phase 3: Domain Invariants/`ReactiveDetermination`/`praxis-rules-engine`/`/praxis/cockpit`/N+1 & Completeness Gates).628. Treat `AbstractCrudController`, `AbstractReadOnlyController`, `BaseCrudService`, and similar pre-resource-oriented classes as migration surfaces only. Do not use them as the default for new resources when the resolved starter exposes the resource-oriented baseline.639. Include `praxis-config-starter` only when the host must expose `/api/praxis/config/**` or AI authoring/config-store surfaces and can provide the required config-store datasource, migrations/tables, and host adapters. Do not include it for a metadata/filter-only service. Before adding it, confirm the target host meets the starter's release prerequisites such as compatible Spring Boot baseline, supported config database/store, Flyway/baseline strategy, AI/RAG secrets when enabled, stream/auth policy, and required host adapters.6410. Keep starter semantics in the starters. Do not patch a new host to redefine `x-ui`, `/schemas/filtered`, `/schemas/catalog`, `/schemas/domain`, actions, capabilities, export, config headers, ETag, or AI contracts.6511. Create only the host-owned code needed for the domain: application bootstrap, dependency composition, security/origin policy, datasource properties, resources, tests, and documentation.6612. Validate with the smallest reliable command after inspecting which tests connect to a database. Local execution is limited to unit tests without a database. Use an explicitly assigned isolated remote Neon branch for database-backed tests; add real HTTP/schema proof when the task claims the runtime metadata endpoints work.6768## Diagnose Missing UI Metadata After Dependency Changes6970When `@UISchema` is present on DTOs but generated `x-ui` is absent or incomplete after a Spring Boot, Springdoc, Swagger Jakarta, or starter version change, read [openapi-metadata-troubleshooting.md](references/openapi-metadata-troubleshooting.md) to audit `CustomOpenApiResolver` ABI, OpenAPI 3.0 vs. 3.1 dialect wiring, and `ModelConverters` pipeline proofs before changing DTO annotations.7172## Reference Resource Audit7374When the user asks to make an existing backend resource an exemplar for future75hosts or migrations, do not stop at "it compiles" or "the endpoint exists".76Audit the complete Praxis contract and classify reusable findings before77changing code:7879- For migration or reference-host work, use the consumer workspace's approved80 playbooks, phase gates, semantic-contract checkers, and reference-audit81 templates when they exist. Do not copy the newest pilot blindly. Classify the82 reusable backend shape first: read-only, partial mutable resource, full CRUD,83 workflow action, related surface, master-detail resource, shared related84 write, or blocked/deferred flow. A package marked not-reference-ready or85 control-only must not become a platform reference until the consumer gate is86 repaired and explicitly promotes it.87- Confirm the resource uses the narrowest canonical baseline that matches the88 real operation state: read-only, read + create/update, full CRUD,89 duplicate-draft, workflow action, related surface, or blocked/deferred.90- Verify response DTO, FilterDTO, command DTOs, option DTOs and lookup91 descriptors publish deliberate `@Schema`, `@UISchema`, validation,92 governance and options metadata. Public text must be semantic product93 documentation, not labels copied into descriptions.94- Execute or inspect focused runtime evidence for `/filter`, detail/by-ids,95 `/options/filter`, `/options/by-ids`, `/schemas/filtered`,96 `/schemas/surfaces`, `/schemas/actions`, `/schemas/domain` when available,97 item/collection capabilities and HATEOAS links/actions.98- For each write-like operation, record whether it is implemented, blocked,99 deferred, not API, direct-table safe, or legacy/DB-backed required. Do not100 infer delete, duplicate, or workflow actions from a legacy button label.101- Check that private context and locators such as tenant/company, user,102 profile, session, SQL names, ROWID, package flags, and bridge internals stay103 server-side and do not appear in DTOs, schemas, option payloads or x-ui.104- For related tabs or child resources, prefer `@UiSurface` plus real105 resource/operation/schema paths. Host-specific links may be assembled locally106 when they are domain composition, but availability and schema semantics must107 still come from canonical Praxis/host services.108- Separate platform gaps from host gaps. If a recurring need belongs in109 `praxis-metadata-starter`, `praxis-config-starter`, shared starters, public110 docs, examples, or this skill, record/update the canonical owner instead of111 hiding the problem in the consumer host.112- Update handoff/parity artifacts after late-scope implementation. A resource113 is not a good reference if final docs contradict implemented endpoints or114 validated operation states.115116## Skill Coverage117118This skill is sufficient for ordinary Java host API work with `praxis-metadata-starter`: project bootstrap, Maven dependency wiring, resource-oriented CRUD/read APIs, DTOs, filters, schemas, OpenAPI discovery, capabilities, surfaces, options, cursor/locate, stats, and collection export.119120*(In external Antigravity workspaces, full companion skills are available under `~/.gemini/praxis-skills/<skill-name>/SKILL.md` or `$CODEX_HOME/skills/<skill-name>/SKILL.md`.)*121122Use companion Praxis skills when the API needs a specialized platform surface:123124- Use `praxis-metadata-resource-baseline` when choosing resource-oriented controllers/services, `ResourceMapper`, filters, HATEOAS envelopes, export, stats, and canonical CRUD/read-only baselines.125- Use `praxis-metadata-schema-contracts` for `x-ui`, `/schemas/filtered`, schema hashes, OpenAPI operation resolution, ETag, and Angular schema consumption.126- Use `praxis-metadata-discovery-capabilities` for surfaces, actions, capabilities, `_links`, availability, related resources, stats, and export discovery.127- Use `praxis-metadata-domain-option-sources` for domain governance, field access, option sources, entity lookup, lookup/by-ids contracts, and semantic metadata review.128- Use `praxis-config-runtime-persistence`, `praxis-config-ai-registry-manifests`, `praxis-config-api-metadata-grounding`, `praxis-config-agentic-authoring-streaming`, or `praxis-config-domain-decisions` before adding `/api/praxis/config/**`, AI registry, RAG/API metadata, authoring, SSE, or governed decision surfaces.129- Use `praxis-api-quickstart-operational-proof`, `praxis-api-quickstart-security-config`, `praxis-api-quickstart-domain-pilots`, and `praxis-api-quickstart-cockpit-http-validation` when a host should mirror or validate against the reference operational proof.130- Use `praxis-http-examples-corpus-manifest`, `praxis-http-examples-contract-surfaces`, and `praxis-http-examples-llm-smoke` when a Java-host change must update executable HTTP examples, public corpus promises, or LLM-facing lanes.131- Use `praxis-landing-public-docs-contracts` and `praxis-landing-registries-sitemap-playgrounds` when the host change affects public docs, guides, examples, sitemap, LLM files, or landing projections.132- Use `praxis-dto-annotations` when filling or reviewing `@Schema`, `@UISchema`,133 `@Filterable`, `@DomainGovernance`, FieldControlType, PT-BR labels/help text, groups, icons,134 options, and DTO/OpenAPI documentation for hosts that consume `praxis-metadata-starter`.135- Use `praxis-resource-entity-lookup-backend` for governed `RESOURCE_ENTITY` lookup, `OptionSourceRegistry`, `LIGHT_LOOKUP`, `x-ui.optionSource`, provider policies, and option-source endpoints.136- Use `praxis-component-minimums` when the question is about the minimum frontend/host runtime wiring needed for Angular components to consume this backend.137- Use `praxis-dynamic-fields-editorial` when changing or validating control types, dynamic-field aliases, or Angular renderability beyond the Java/OpenAPI contract.138- Use `praxis-authoring-editors` only for authored UI/editor/config persistence workflows, not for ordinary backend resources.139140Do not use consumer-specific fieldspec guidance for Praxis resources unless the task explicitly targets that legacy fieldspec stack. For Praxis APIs, `praxis-metadata-starter` annotations and contracts are the source of truth.141142## Canonical Boundaries143144- `praxis-metadata-starter` owns `x-ui`, `/schemas/filtered`, `/schemas/catalog`, `/schemas/surfaces`, `/schemas/actions`, `/schemas/domain`, capabilities, OpenAPI enrichment, HATEOAS schema links, export contracts, governance metadata, and resource-oriented base contracts.145- `praxis-config-starter` owns `/api/praxis/config/**`, persisted UI config, AI registry, templates, config headers, config ETag, authoring/context contracts, and the governed boundary for semantic-decision authoring, simulation, approval, publication, and materialization when that feature set is in scope.146- The new host owns Spring Boot composition, dependency versions, datasource wiring, security policy, concrete domain resources, domain persistence, and downstream proof that selected starters work in a real service.147- `praxis-api-quickstart-public` is the preferred public reference host for external users and LLMs. `praxis-api-quickstart` local/private source is useful when available for platform development and comparison. Neither is a required checkout or the canonical owner of starter semantics.148149## Schema And Decision Boundaries150151- Treat `/schemas/filtered` as the structural schema source for UI/runtime consumption. Treat `/schemas/catalog` as documentation/discovery, `/schemas/surfaces` and `/schemas/actions` as semantic discovery, `/schemas/domain` as AI-operable domain vocabulary, and resource capabilities as aggregate availability snapshots. Do not use catalogs or capabilities as a second structural schema source.152- For AI or assistant features in a Java host, do not route primary user intent with keyword lists, regex command matching, or controller-local text heuristics. Expose canonical resources, tools, operation schemas, catalogs, surfaces, actions, capabilities, governed context, and config-starter contracts so semantic resolution can be LLM/governance-led and then grounded against those canonical candidates.153- If a required AI/config tool or contract is missing, model the tool or contract in the canonical owner, usually `praxis-config-starter` for authoring/config decisions or `praxis-metadata-starter` for metadata discovery. Do not compensate by adding host-local AI registries, patch formats, magic request fields, or string-routing shortcuts.154- Before adding a new host contract, inventory whether the platform already publishes the needed fact through DTO annotations, OpenAPI enrichment, `x-ui`, option sources, surfaces, actions, capabilities, domain catalog, config headers/ETag, quick replies, previews, diagnostics, or materializations. Classify the finding as already supported, poorly materialized, partial, or a real contract gap.155156## Project Baseline157158Use Java 21 unless the selected starter release documents a different baseline. Prefer Maven unless the target host already standardizes on Gradle.159160When no local platform repo is present, do not inspect `praxis-metadata-starter` or `praxis-config-starter` source. Use the dependency's public package names, generated API docs, Maven dependency metadata, `javap` against resolved jars when necessary, and runtime HTTP validation.161162Minimum dependencies for a CRUD host usually include:163164- `spring-boot-starter-web`165- `spring-boot-starter-data-jpa`166- `spring-boot-starter-validation`167- `spring-boot-starter-actuator`168- `spring-boot-starter-security` when the host exposes real HTTP endpoints169- `praxis-metadata-starter`170- `praxis-config-starter` only when the host must provide `/api/praxis/config/**` and its required config-store/RAG/domain adapters171- database driver172- MapStruct and Lombok if following quickstart mapper/entity conventions173- `spring-boot-starter-test` for tests; use the selected PostgreSQL driver for assigned remote Neon database proof, not H2 or embedded/local database substitutes174175In Maven, declare explicit starter versions unless the host imports a managed Praxis BOM or parent:176177```xml178<properties>179 <praxis.core.version><!-- selected released version --></praxis.core.version>180</properties>181182<dependency>183 <groupId>io.github.codexrodrigues</groupId>184 <artifactId>praxis-metadata-starter</artifactId>185 <version>${praxis.core.version}</version>186</dependency>187```188189Application bootstrap must scan the host package and the metadata starter package:190191```java192@SpringBootApplication(scanBasePackages = {193 "com.example.praxis.<host>",194 "org.praxisplatform.uischema"195})196```197198Do not copy historical quickstart controllers literally. In the current starter, `@ApiResource` is the resource declaration and already supplies the necessary controller/request-mapping semantics; only add extra Spring stereotypes when the resolved starter version or target host pattern explicitly requires them.199200If `praxis-config-starter` is in scope, treat it as a separate config-store boundary. Include `org.praxisplatform.config` scanning, config starter JPA repository/entity wiring, migrations/tables, and datasource configuration only when the host actually exposes `/api/praxis/config/**`. Do not point a legacy Oracle application datasource at the config store by accident; config/AI persistence normally needs its own supported store and baseline.201202## Domain Documentation Rule203204Do not generate `@Schema(description=...)` in bulk from labels, property names, or camelCase. Investigate each field and write domain descriptions deliberately: what the field represents, constraints, relationships, and business impact. Keep `@UISchema` for UI behavior and labels; keep `@Schema` as product/domain documentation.205206Also write `@Operation`, `@ResourceIntent`, `@UiSurface`, and `@WorkflowAction` text as semantic product contract. These strings feed `/schemas/catalog`, `/schemas/surfaces`, `/schemas/actions`, `/schemas/domain`, capabilities snapshots, RAG, and LLM consumers. Do not rely on generic Springdoc fallback summaries for public resource operations.207208## Deep Domain & Relational Synthesis Rule ("Além do Óbvio")209210Do not act as a mechanical `1 table = 1 obvious CRUD` generator. Analyze the business domain and the relationship graph between entities (`@ManyToOne`, `@OneToMany`, `@Embedded`) to uncover non-obvious enterprise capabilities across 3 dimensions:2111. **Deep Filtering & Unified Broad Search (`@Filterable(relations = {...})`):** Every operational `FilterDTO` must include at least one broad/omnibox search field (`searchTerm` / `buscaAmpla` / `identificacaoOuFamiliar`) using `@Filterable(operation = FilterOperation.LIKE, relations = {"fullName", "socialName", "motherName", "fatherName", "dependents.fullName", "taxId"})` so users can search across name, surname, parent/dependent name, or ID in one input (`OR`), plus multi-operator coverage on the same attribute (`LIKE`+`STARTS_WITH`+`EQUAL`+`IN`, `BETWEEN`+`IN_LAST_DAYS`+`IN_NEXT_DAYS`, completeness `IS_NULL`/`IS_NOT_NULL`, collection cardinality `SIZE_GT`/`SIZE_EQ`) and multi-level cross-entity paths (`relation = "department.costCenter.region"`).2122. **Exhaustive Bulking Discovery Across All 3 Modes:** Audit 100% of mutable attributes instead of picking 2–3 obvious fields: enable `BulkMode.UNIFORM_UPDATE` on all collective standardization fields (unit, cost center, shift, regime/plan, payment/bank, manager, flags); enable `BulkMode.PER_ITEM_UPDATE` broadly on inline batch-grid revision fields (phones, emails, addresses, bank accounts, individual amounts/limits, external codes, per-item dates); and analyze entity relationships and lifecycle to create collective `BulkMode.DOMAIN_COMMAND` `@WorkflowAction(scope = ActionScope.COLLECTION)` operations (batch relocation across units, batch approval/homologation, batch suspension/reactivation, parametric revision).2133. **New Cross-Entity Endpoints & Subdomain Intents:** Create dedicated read-only analytical/consolidated endpoints (`AbstractReadOnlyResourceController`) when entity relationships answer cross-table operational questions (vacancy/occupancy matrices, expiring-items radar, compliance audits), expose all `1:N` child collections as 360° surfaces (`@UiSurface` + `relatedChildResourceKey`), and decompose broad entities into persona-oriented `@ResourceIntent` (`PATCH` + `SurfaceKind.PARTIAL_FORM`) endpoints.214215For sensitive fields or fields that should guide AI/RAG behavior, use `@DomainGovernance`, `AiUsagePolicy`, and `AiUsageMode` deliberately. Validate that governance appears in `x-domain-governance` on `/schemas/filtered` and is reflected in `/schemas/domain` when the host publishes the domain catalog.216217## Validation218219Prefer focused validation:220221- New host scaffold or resource compile proof: select the host's unit tests that do not open database connections; use `mvn -B test` only after confirming its complete selection is database-free or all database cases use the reviewed Neon assignment.222- Published dependency proof for external hosts: resolve starter artifacts with Maven metadata or `mvn dependency:get`, preferably using a temporary local Maven repository when the task must prove no monorepo dependency.223- Metadata/public contract proof: add or run a focused `@SpringBootTest`/MockMvc or TestRestTemplate test for `/v3/api-docs`, `/schemas/filtered`, `/schemas/catalog`, `/schemas/surfaces`, `/schemas/actions`, `/schemas/domain` when available, resource filter, options, actions, and capabilities.224- Config starter proof: assign isolated remote Neon API/Config resources explicitly, verify project/child/endpoint/PostgreSQL identity and client TLS before connecting, and prove the real owner/runtime/control-plane privileges and memberships required by the flow. Keep credentials private, bound fixture writes and cleanup to the assignment, preserve inherited data, and test `/api/praxis/config/**` with the host's required headers/origin. A privileged fixture is not proof of the ordinary runtime path; do not disable migrations merely to imitate an old local fixture.225- Dependency/version change: confirm Maven resolution and run at least the host's test phase.226- For a full resource proof, execute the endpoints the UI/runtime will rely on: `/filter`, `/filter/cursor`, `/locate`, `/options/filter`, `/options/by-ids`, option-source endpoints when registered, `/schemas/filtered`, `/schemas/catalog`, `/schemas/surfaces?resource=...`, `/schemas/actions?resource=...`, `/schemas/domain` when available, collection and item `/capabilities`, collection and item `/actions`, item `/surfaces`, configured `/stats/*`, and `/export` when collection export is supported.227228Do not copy historical H2, embedded PostgreSQL or Testcontainers fixtures from229reference hosts or checklists into a new database proof. A reference host may230still contain unmigrated local database tests in its broad Maven/release gate;231record that gap and migrate or compose the complete required case matrix on232assigned Neon resources before release. Removing those tests, accepting skips,233or replacing them with a focal SDK-adoption or cold-start proof does not close234the broad release gate. Unit and focal passes remain evidence only for their235stated scope. Follow the owning repository's actual private and sanitized-public236release gates, retaining source/dependency identity, raw reports and cleanup.237238When validation is partial, state exactly what ran and what remains unvalidated.239240## References241242- Read `references/resource-baseline.md` before implementing concrete resources (contains the exact generic signatures, starter imports, and the complete 1-Shot Golden Path code template).243- Read `references/host-checklist.md` before finalizing a scaffold or reporting completion.244- Read `references/openapi-metadata-troubleshooting.md` when diagnosing missing `x-ui` metadata after Spring Boot, Springdoc, or starter version changes.245- When local platform docs are available, use `praxis-metadata-starter/docs/guides/GUIA-01-AI-BACKEND-APLICACAO-NOVA.md`, `GUIA-02-AI-BACKEND-CRUD-METADATA.md`, `GUIA-04-QUANDO-USAR-RESOURCE-SURFACE-ACTION-CAPABILITY.md`, `GUIA-05-DO-CRUD-AO-CONTRATO-SEMANTICO.md`, `GUIA-06-REDACAO-SEMANTICA-DE-ANNOTATIONS-PARA-IA.md`, `FILTROS-E-PAGINACAO.md`, `OPTIONS-ENDPOINT.md`, and `COLLECTION-EXPORT.md` as supporting references for gaps not covered here.