Praxis Config API Metadata Grounding
Use this skill for API catalog ingestion, AI context composition, RAG/project-knowledge retrieval, and resource candidate grounding in praxis-config-starter. api_metadata is evidence for semantic grounding; it must not become a hardcoded conversational router.
Source Audit
Inspect the owner before editing:
praxis-config-starter/AGENTS.md
src/main/java/org/praxisplatform/config/controller/ApiMetadataController.java
src/main/java/org/praxisplatform/config/controller/AiContextController.java
src/main/java/org/praxisplatform/config/controller/ContextRetrievalController.java
src/main/java/org/praxisplatform/config/service/ApiMetadataIngestionService.java
src/main/java/org/praxisplatform/config/dto/ApiMetadataRagStatusResponse.java
src/main/java/org/praxisplatform/config/dto/ApiMetadataRagReconcileResponse.java
src/main/java/org/praxisplatform/config/service/AiContextService.java
src/main/java/org/praxisplatform/config/service/ContextRetrievalService.java
src/main/java/org/praxisplatform/config/service/SchemaRetrievalService.java
src/main/java/org/praxisplatform/config/domain/ApiMetadata.java
src/main/java/org/praxisplatform/config/repository/ApiMetadataRepository.java
src/main/java/org/praxisplatform/config/dto/ApiCatalogRequest.java
src/main/java/org/praxisplatform/config/dto/ApiSearchResult.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringApiMetadataCandidateCatalog.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringResourceDiscoveryService.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringProjectKnowledgeService.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringRuntimeComponentGroundingService.java
src/main/java/org/praxisplatform/config/ai/authoring/VectorRankedProjectKnowledgeCandidateRetriever.java
src/main/java/org/praxisplatform/config/service/RagProjectKnowledgeDerivedIndexService.java
src/main/java/org/praxisplatform/config/controller/DomainCatalogController.java
src/main/java/org/praxisplatform/config/service/DomainCatalogIngestionService.java
src/main/java/org/praxisplatform/config/service/DomainCatalogPromptContextService.java
src/main/java/org/praxisplatform/config/rag/RagDocumentIdentity.java
src/main/java/org/praxisplatform/config/rag/RagFilters.java
src/main/java/org/praxisplatform/config/rag/**
src/main/resources/db/migration/V4__create_api_metadata.sql, V28__scope_api_metadata_identity.sql, V8__create_api_metadata_embedding_index.sql, and vector-store migrations.
praxis-ui-angular/projects/praxis-ai/src/lib/core/services/ai-backend-api.service.ts
- focused API metadata, context, RAG, project knowledge, and resource discovery tests.
Canonical Boundary
/api/praxis/config/api-catalog/ingest stores normalized API metadata and publishes derived vector-store documents for retrieval. /api/praxis/config/ai-context/** composes component state, templates, schema hints, runtime config, and grounding context for AI authoring.
API Catalog Q&A should be an informative grounded answer path. It should not start page-preview, require executable resource clarification, or apply configuration until a later turn chooses an executable authoring route.
Keep the sources distinct: praxis-metadata-starter owns current resource structure and semantics through /schemas/filtered, /schemas/catalog, /schemas/surfaces, /schemas/actions, and capabilities. praxis-config-starter persists an ingested operational API search corpus and governs how that evidence is retrieved for AI. RAG documents, caches, candidate rankings, context packs, and answers are derived projections.
Ingestion Contract
POST /api/praxis/config/api-catalog/ingest accepts endpoint snapshots with path, method, tags, summary, description, operation id, request/response schemas, parameters, release id, version, and generated timestamp. An empty endpoint list is a no-op.
- Ingest resolves blank/missing scope to
tenantId=GLOBAL, environment=default, serviceKey=default, and release id from releaseId, then version/generated time, then v1.
- The structured
api_metadata row currently stores tenant, environment, service key, release id/version, generated time, full schemas, parameters, raw endpoint JSON, and embedding.
- Current scoped identity is canonical: V28 adds
tenant_id, environment, service_key, and release_id, replaces the legacy global path + method unique key, and enforces tenant_id + environment + service_key + release_id + path + method.
- Upsert first by scoped
path + method, then by scoped stable operationId + method to reconcile a moved endpoint without crossing tenant, environment, service, or release boundaries.
- Release identity resolves from
releaseId, then version/generated time according to RagDocumentIdentity. Preserve that identity and the content hash; do not publish anonymous chunks that cannot be replayed or purged by scope.
- API catalog ingestion persists canonical
api_metadata rows first. RAG/vector publication is scheduled after the database commit when transaction synchronization is active; outside a synchronized transaction the same publication task may run immediately after persistence.
- The controller returns
202 Accepted. Treat it as accepted structured ingestion, not proof that a vector store exists or that the derived RAG corpus is ready.
- Vector publication is derived and optional. A disabled/unavailable vector store or publication failure must not roll back canonical structured metadata, and a vector row must never become authority over a later canonical schema response.
GET /api/praxis/config/api-catalog/rag/status reports expected structured document count, vector-store availability, publication enablement, and release status for tenant/environment/service/release.
POST /api/praxis/config/api-catalog/rag/reconcile rebuilds derived API metadata RAG documents from canonical api_metadata rows for the requested tenant/environment/service/release. It returns 202 Accepted with the reconcile result and status.
- Reconciliation must delete derived API metadata documents for the release scope before upserting the rebuilt document set; do not append duplicate stale chunks.
- API RAG document ids and content hashes include tenant, environment, service key, release id, method/path, raw endpoint JSON, resource type, and chunk index. Preserve these fields for deterministic replay and purge.
Retrieval Precedence
For API and component-definition search, preserve this order and diagnostics:
- Resolve a release id and query the vector store with
resourceType, tenant/environment when provided, release, method, and supported tag filters.
- Apply default-release fallback only when
praxis.ai.rag.release.fallback.default-enabled=true; legacy version metadata fallback is a separate compatibility setting.
- When the vector store is available but the scoped release has no result, return no candidates instead of silently using the global structured table.
- When vector search is unavailable, legacy pgvector repository retrieval is allowed only for an unscoped request. Tenant/environment-scoped requests fail closed.
tags filters are normalized from comma, semicolon, or pipe separated tokens and matched case-insensitively as an AND set. tags filtering is supported on the vector path by over-fetching the scoped/method-filtered vector results and applying normalized tag matching before the effective limit. Legacy repository retrieval also receives normalized tags when vector search is unavailable and the request is unscoped. Keep tag evidence in focused ContextRetrievalServiceTest coverage when changing this path.
Semantic retrieval is candidate grounding, not primary intent resolution. AgenticAuthoringApiMetadataCandidateCatalog prefers semantic evidence, may supplement it with explicit or weak lexical evidence, and marks provenance such as semantic-retrieval, lexical-fallback, weak-evidence, and semantic role. Weak candidates may explain search but must not become executable selection or strong quick replies without governed confirmation.
Scoped semantic retrieval must not retry without tenant/environment scope. AgenticAuthoringApiMetadataCandidateCatalog may fall back to scoped structured metadata when semantic retrieval returns no candidates, but it must not issue an unscoped vector query to recover scoped results.
Context And Schema
GET /api/praxis/config/ai-context/{componentId} resolves current state through ui_user_config user-to-tenant fallback. POST uses transient caller state and does not persist it.
- Both paths compose the system component definition, optional template, component state, mode, resource path, and
AiSchemaContext. Default mode is edit; requireSchema defaults true only for create.
/ai-context does not fetch or populate the schema itself. schemaContext is a pointer. Executable authoring resolves the actual structure just in time through SchemaRetrievalService and canonical /schemas/filtered?path=...&operation=...&schemaType=....
- Schema retrieval returns typed failures for invalid context, missing base URL, access denial, not found, invalid payload, and transport/unavailable states. Do not replace a failed canonical schema request with
/schemas/catalog, api_metadata, or an inferred local schema.
- The Angular
AiBackendApiService derives the AI-context base URL from API_URL.default unless an explicit gateway override exists. Hosts must supply governed identity headers; demo/local header defaults are not corporate authorization.
Project Knowledge And Corpus
- Project Knowledge vector publication and retrieval are opt-in derived accelerators. Publish only active, approved, AI-visible concepts backed by active evidence; mask or redact content before indexing.
- AI visibility is a policy gate, not vector metadata convenience.
allow may publish safe content, mask/summarize_only may publish only masked or governed summaries, and deny/deny_for_llm must stay out of prompt/context projection even when a vector hit, score, or cached retrieval result looks strong.
- Vector hits only rank canonical concept keys. Reload Domain Knowledge rows by tenant/environment, then recheck lifecycle, curation, AI visibility, requested context/resource/kind, and active evidence before projecting influence into a turn.
- Reverted or superseded evidence must be removed from the derived index and must not influence new turns. A stale vector hit without a matching canonical concept/evidence row is discarded.
- Component corpus retrieval requires release/scoped metadata and
aiVisibility=allow; preserve source id/kind, chunk kind, source pointer, content hash, corpus version, score, and release provenance in diagnostics.
- Runtime component observations are accepted only as
untrusted_frontend_observation evidence. Ground them through AgenticAuthoringRuntimeComponentGroundingService into GroundedRuntimeComponentContext, preserving accepted/rejected claims, evidence refs, safe digests, lifecycle, omitted/redacted/sensitive field diagnostics, and available surfaces/affordances. Unsupported trust boundaries, stale observations, inactive observations, missing component identity, or unsupported schema versions must be rejected before they influence API/resource grounding.
Domain Catalog First-Turn Grounding
- The persisted latest governed Domain Catalog release remains canonical. Its vector documents are a derived ranking index; map ranked hits back to canonical items before prompt projection.
- Publish and filter Domain Catalog RAG documents with the same normalized release token from
RagDocumentIdentity.resolveReleaseId. Also preserve tenant, environment, service key, resource key, item type, context key, node type, and canonical item identity. A raw release key on one side and a normalized token on the other creates false empty retrieval and unreconciled status.
- Pre-intent planning must receive governed Domain Catalog context on the first authoring turn when the caller did not provide a Domain Catalog preference. Add a copied internal
enabled=true hint only for this asymmetry; preserve an explicit enabled=false or caller-provided scope.
- Retrieve semantically from the scoped latest release first, then use the existing scoped lexical query only as a fallback when semantic retrieval produces no canonical item. Lexical matching does not decide primary intent.
- In
DomainCatalogPromptContextService.buildResourceIdentityContext, over-fetch concept rows (RESOURCE_IDENTITY_FETCH_LIMIT) and deduplicate by resourceKey before applying MAX_LIMIT so alphabetical concept density never truncates distinct domain resources (e.g. operations.missoes) from DOMAIN_RESOURCE_IDENTITY_CATALOG.
- In
AgenticAuthoringApiMetadataCandidateCatalog, evaluate primaryBusinessEntityAlignmentScore after semanticRoleFit when resourceNeed == GENERIC_OPERATIONAL, preserving PROFILE and ANALYTICS projections while breaking ties in favor of the parent primaryBusinessEntity in parent-child and operational requests.
- Do not treat successful ingestion, a populated Domain 360 response, or vector availability alone as proof of grounding. An operational gate must wait for
expectedDocumentCount == publishedDocumentCount > 0 and audit that every provider pre-intent call contains the governed context.
Consultative Answers
artifactKind=api_catalog is a read-only consultative path. It may combine API candidates with a compact Domain Catalog projection and LLM-authored response, but it must not trigger preview/apply or pretend an unconfirmed domain exists.
- Preserve the structured grounding envelope, candidate APIs, consultative projection, warnings, evidence bundles, retrieval source, scores, scope, release, and elapsed/count diagnostics. Caches are bounded performance aids and must be invalidatable during ingestion verification.
- Resource candidates identify possible operations. Verify the chosen operation through
/schemas/filtered, actions, surfaces, and capabilities before generating executable configuration.
Decision Rules
- Treat
api_metadata, vector documents, project knowledge, domain catalog hints, schemas, and runtime state as evidence for AI/tool grounding.
- Do not answer API catalog questions with hardcoded deterministic prose when LLM/RAG grounding is available.
- Do not use local text search as the primary decision for business resource selection.
- Preserve tenant, environment, release id, version, generatedAt, operationId, schemas, params, tags, scores, content hashes, source pointers, retrieval source, and raw JSON enough for replayable grounding.
- Preserve RAG status/reconcile diagnostics when ingestion changes: expected document count, published document count, vector-store availability, publication-enabled flag, resource type, tenant, environment, service key, and release id.
- Fail closed when scoped or required grounding is unavailable; do not launder lexical fallback into a selected resource or successful materialization.
- Keep caches performance-only;
api_metadata, ai_registry, runtime metadata, and persisted turn events remain canonical.
- If schema or resource semantics are missing, inspect
praxis-metadata-starter contracts before inventing config-starter API metadata fields.
No Keyword Routing
Do not resolve intent, resource, endpoint, schema, field, or API recommendation through labels, aliases, regexes, or local fuzzy matching as the primary decision. Use governed LLM/tool resolution, api_metadata, schema contracts, Project Knowledge, Domain Catalog, declared tools, and candidate provenance for grounding; textual matching may only rank candidates after semantic scope is established.
Aderence Inventory
Before adding API metadata fields, context blocks, RAG metadata keys, candidate diagnostics, cache semantics, or context endpoints, classify:
ja-suportado-so-ux
ja-suportado-mal-nomeado-ou-mal-materializado
suportado-parcialmente
lacuna-real-de-contrato
Only real gaps justify new public grounding contracts. Identify source owner, downstream assistant/runtime consumers, generated AI contracts, docs, quickstart smokes, and minimum validation.
Validation
Use focused local gates:
- ingestion/context:
mvn "-Dtest=ApiMetadataIngestionServiceTest,ApiMetadataControllerTest,AiContextControllerTest,ContextRetrievalServiceTest,SchemaRetrievalServiceTest" test
- resource/project knowledge/runtime grounding:
mvn "-Dtest=AgenticAuthoringApiMetadataCandidateCatalogTest,AgenticAuthoringResourceDiscoveryServiceTest,AgenticAuthoringProjectKnowledgeServiceTest,VectorRankedProjectKnowledgeCandidateRetrieverTest,AgenticAuthoringRuntimeComponentGroundingServiceTest" test
- RAG/vector changes:
mvn "-Dtest=RagVectorStoreServiceTest,RagVectorStoreConfigurationTest,RagProjectKnowledgeMetadataTest,RagProjectKnowledgeDerivedIndexServiceTest" test
- Domain Catalog prompt/RAG grounding:
mvn "-Dtest=DomainCatalogIngestionServiceTest,DomainCatalogPromptContextServiceTest,RagVectorStoreServiceTest,AgenticAuthoringLlmPreIntentToolPlanningServiceTest" test
- Angular AI-context consumer:
npm run test:praxis-ai:backend-api
Review docs/ai/**, docs/domain-catalog/**, API contract docs, quickstart ingestion/smoke scripts, and Angular AI context consumers when public grounding changes.
Companion Skills
- Use
praxis-metadata-schema-contracts when grounding depends on backend resource schema semantics.
- Use
praxis-config-runtime-persistence when /ai-context GET state resolution or tenant/user/environment config behavior changes.
- Use
praxis-ai-backend-config-contracts when Angular endpoint resolution or identity headers change.
- Use
praxis-config-agentic-authoring-streaming when candidates feed intent resolution, turn stream, quick replies, or terminal diagnostics.
- Use
praxis-config-domain-decisions when grounding should route to shared rule/knowledge authoring.
- Use
praxis-api-quickstart-cockpit-http-validation for downstream proof of domain catalog ingest, API catalog grounding, Project Knowledge, and HTTP examples.
- Use
praxis-ai-semantic-intent for Angular assistant consult/edit boundaries.
1---2name: praxis-config-api-metadata-grounding3description: "Use when Codex must implement, audit, or consume Praxis API grounding: api_metadata ingestion and search, release-scoped RAG documents, /api/praxis/config/ai-context/**, /schemas/filtered resolution, Project Knowledge retrieval, component corpus evidence, resource candidates, consultative API Catalog answers, or grounding provenance and diagnostics."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-config-api-metadata-grounding6---78# Praxis Config API Metadata Grounding910Use this skill for API catalog ingestion, AI context composition, RAG/project-knowledge retrieval, and resource candidate grounding in `praxis-config-starter`. `api_metadata` is evidence for semantic grounding; it must not become a hardcoded conversational router.1112## Source Audit1314Inspect the owner before editing:1516- `praxis-config-starter/AGENTS.md`17- `src/main/java/org/praxisplatform/config/controller/ApiMetadataController.java`18- `src/main/java/org/praxisplatform/config/controller/AiContextController.java`19- `src/main/java/org/praxisplatform/config/controller/ContextRetrievalController.java`20- `src/main/java/org/praxisplatform/config/service/ApiMetadataIngestionService.java`21- `src/main/java/org/praxisplatform/config/dto/ApiMetadataRagStatusResponse.java`22- `src/main/java/org/praxisplatform/config/dto/ApiMetadataRagReconcileResponse.java`23- `src/main/java/org/praxisplatform/config/service/AiContextService.java`24- `src/main/java/org/praxisplatform/config/service/ContextRetrievalService.java`25- `src/main/java/org/praxisplatform/config/service/SchemaRetrievalService.java`26- `src/main/java/org/praxisplatform/config/domain/ApiMetadata.java`27- `src/main/java/org/praxisplatform/config/repository/ApiMetadataRepository.java`28- `src/main/java/org/praxisplatform/config/dto/ApiCatalogRequest.java`29- `src/main/java/org/praxisplatform/config/dto/ApiSearchResult.java`30- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringApiMetadataCandidateCatalog.java`31- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringResourceDiscoveryService.java`32- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringProjectKnowledgeService.java`33- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringRuntimeComponentGroundingService.java`34- `src/main/java/org/praxisplatform/config/ai/authoring/VectorRankedProjectKnowledgeCandidateRetriever.java`35- `src/main/java/org/praxisplatform/config/service/RagProjectKnowledgeDerivedIndexService.java`36- `src/main/java/org/praxisplatform/config/controller/DomainCatalogController.java`37- `src/main/java/org/praxisplatform/config/service/DomainCatalogIngestionService.java`38- `src/main/java/org/praxisplatform/config/service/DomainCatalogPromptContextService.java`39- `src/main/java/org/praxisplatform/config/rag/RagDocumentIdentity.java`40- `src/main/java/org/praxisplatform/config/rag/RagFilters.java`41- `src/main/java/org/praxisplatform/config/rag/**`42- `src/main/resources/db/migration/V4__create_api_metadata.sql`, `V28__scope_api_metadata_identity.sql`, `V8__create_api_metadata_embedding_index.sql`, and vector-store migrations.43- `praxis-ui-angular/projects/praxis-ai/src/lib/core/services/ai-backend-api.service.ts`44- focused API metadata, context, RAG, project knowledge, and resource discovery tests.4546## Canonical Boundary4748`/api/praxis/config/api-catalog/ingest` stores normalized API metadata and publishes derived vector-store documents for retrieval. `/api/praxis/config/ai-context/**` composes component state, templates, schema hints, runtime config, and grounding context for AI authoring.4950API Catalog Q&A should be an informative grounded answer path. It should not start `page-preview`, require executable resource clarification, or apply configuration until a later turn chooses an executable authoring route.5152Keep the sources distinct: `praxis-metadata-starter` owns current resource structure and semantics through `/schemas/filtered`, `/schemas/catalog`, `/schemas/surfaces`, `/schemas/actions`, and capabilities. `praxis-config-starter` persists an ingested operational API search corpus and governs how that evidence is retrieved for AI. RAG documents, caches, candidate rankings, context packs, and answers are derived projections.5354## Ingestion Contract5556- `POST /api/praxis/config/api-catalog/ingest` accepts endpoint snapshots with path, method, tags, summary, description, operation id, request/response schemas, parameters, release id, version, and generated timestamp. An empty endpoint list is a no-op.57- Ingest resolves blank/missing scope to `tenantId=GLOBAL`, `environment=default`, `serviceKey=default`, and release id from `releaseId`, then version/generated time, then `v1`.58- The structured `api_metadata` row currently stores tenant, environment, service key, release id/version, generated time, full schemas, parameters, raw endpoint JSON, and embedding.59- Current scoped identity is canonical: V28 adds `tenant_id`, `environment`, `service_key`, and `release_id`, replaces the legacy global `path + method` unique key, and enforces `tenant_id + environment + service_key + release_id + path + method`.60- Upsert first by scoped `path + method`, then by scoped stable `operationId + method` to reconcile a moved endpoint without crossing tenant, environment, service, or release boundaries.61- Release identity resolves from `releaseId`, then version/generated time according to `RagDocumentIdentity`. Preserve that identity and the content hash; do not publish anonymous chunks that cannot be replayed or purged by scope.62- API catalog ingestion persists canonical `api_metadata` rows first. RAG/vector publication is scheduled after the database commit when transaction synchronization is active; outside a synchronized transaction the same publication task may run immediately after persistence.63- The controller returns `202 Accepted`. Treat it as accepted structured ingestion, not proof that a vector store exists or that the derived RAG corpus is ready.64- Vector publication is derived and optional. A disabled/unavailable vector store or publication failure must not roll back canonical structured metadata, and a vector row must never become authority over a later canonical schema response.65- `GET /api/praxis/config/api-catalog/rag/status` reports expected structured document count, vector-store availability, publication enablement, and release status for tenant/environment/service/release.66- `POST /api/praxis/config/api-catalog/rag/reconcile` rebuilds derived API metadata RAG documents from canonical `api_metadata` rows for the requested tenant/environment/service/release. It returns `202 Accepted` with the reconcile result and status.67- Reconciliation must delete derived API metadata documents for the release scope before upserting the rebuilt document set; do not append duplicate stale chunks.68- API RAG document ids and content hashes include tenant, environment, service key, release id, method/path, raw endpoint JSON, resource type, and chunk index. Preserve these fields for deterministic replay and purge.6970## Retrieval Precedence7172For API and component-definition search, preserve this order and diagnostics:73741. Resolve a release id and query the vector store with `resourceType`, tenant/environment when provided, release, method, and supported tag filters.752. Apply default-release fallback only when `praxis.ai.rag.release.fallback.default-enabled=true`; legacy `version` metadata fallback is a separate compatibility setting.763. When the vector store is available but the scoped release has no result, return no candidates instead of silently using the global structured table.774. When vector search is unavailable, legacy pgvector repository retrieval is allowed only for an unscoped request. Tenant/environment-scoped requests fail closed.7879`tags` filters are normalized from comma, semicolon, or pipe separated tokens and matched case-insensitively as an AND set. `tags` filtering is supported on the vector path by over-fetching the scoped/method-filtered vector results and applying normalized tag matching before the effective limit. Legacy repository retrieval also receives normalized tags when vector search is unavailable and the request is unscoped. Keep tag evidence in focused `ContextRetrievalServiceTest` coverage when changing this path.8081Semantic retrieval is candidate grounding, not primary intent resolution. `AgenticAuthoringApiMetadataCandidateCatalog` prefers semantic evidence, may supplement it with explicit or weak lexical evidence, and marks provenance such as `semantic-retrieval`, `lexical-fallback`, `weak-evidence`, and semantic role. Weak candidates may explain search but must not become executable selection or strong quick replies without governed confirmation.8283Scoped semantic retrieval must not retry without tenant/environment scope. `AgenticAuthoringApiMetadataCandidateCatalog` may fall back to scoped structured metadata when semantic retrieval returns no candidates, but it must not issue an unscoped vector query to recover scoped results.8485## Context And Schema8687- `GET /api/praxis/config/ai-context/{componentId}` resolves current state through `ui_user_config` user-to-tenant fallback. `POST` uses transient caller state and does not persist it.88- Both paths compose the system component definition, optional template, component state, mode, resource path, and `AiSchemaContext`. Default mode is `edit`; `requireSchema` defaults true only for `create`.89- `/ai-context` does not fetch or populate the schema itself. `schemaContext` is a pointer. Executable authoring resolves the actual structure just in time through `SchemaRetrievalService` and canonical `/schemas/filtered?path=...&operation=...&schemaType=...`.90- Schema retrieval returns typed failures for invalid context, missing base URL, access denial, not found, invalid payload, and transport/unavailable states. Do not replace a failed canonical schema request with `/schemas/catalog`, `api_metadata`, or an inferred local schema.91- The Angular `AiBackendApiService` derives the AI-context base URL from `API_URL.default` unless an explicit gateway override exists. Hosts must supply governed identity headers; demo/local header defaults are not corporate authorization.9293## Project Knowledge And Corpus9495- Project Knowledge vector publication and retrieval are opt-in derived accelerators. Publish only active, approved, AI-visible concepts backed by active evidence; mask or redact content before indexing.96- AI visibility is a policy gate, not vector metadata convenience. `allow` may publish safe content, `mask`/`summarize_only` may publish only masked or governed summaries, and `deny`/`deny_for_llm` must stay out of prompt/context projection even when a vector hit, score, or cached retrieval result looks strong.97- Vector hits only rank canonical concept keys. Reload Domain Knowledge rows by tenant/environment, then recheck lifecycle, curation, AI visibility, requested context/resource/kind, and active evidence before projecting influence into a turn.98- Reverted or superseded evidence must be removed from the derived index and must not influence new turns. A stale vector hit without a matching canonical concept/evidence row is discarded.99- Component corpus retrieval requires release/scoped metadata and `aiVisibility=allow`; preserve source id/kind, chunk kind, source pointer, content hash, corpus version, score, and release provenance in diagnostics.100- Runtime component observations are accepted only as `untrusted_frontend_observation` evidence. Ground them through `AgenticAuthoringRuntimeComponentGroundingService` into `GroundedRuntimeComponentContext`, preserving accepted/rejected claims, evidence refs, safe digests, lifecycle, omitted/redacted/sensitive field diagnostics, and available surfaces/affordances. Unsupported trust boundaries, stale observations, inactive observations, missing component identity, or unsupported schema versions must be rejected before they influence API/resource grounding.101102## Domain Catalog First-Turn Grounding103104- The persisted latest governed Domain Catalog release remains canonical. Its vector documents are a derived ranking index; map ranked hits back to canonical items before prompt projection.105- Publish and filter Domain Catalog RAG documents with the same normalized release token from `RagDocumentIdentity.resolveReleaseId`. Also preserve tenant, environment, service key, resource key, item type, context key, node type, and canonical item identity. A raw release key on one side and a normalized token on the other creates false empty retrieval and unreconciled status.106- Pre-intent planning must receive governed Domain Catalog context on the first authoring turn when the caller did not provide a Domain Catalog preference. Add a copied internal `enabled=true` hint only for this asymmetry; preserve an explicit `enabled=false` or caller-provided scope.107- Retrieve semantically from the scoped latest release first, then use the existing scoped lexical query only as a fallback when semantic retrieval produces no canonical item. Lexical matching does not decide primary intent.108- In `DomainCatalogPromptContextService.buildResourceIdentityContext`, over-fetch `concept` rows (`RESOURCE_IDENTITY_FETCH_LIMIT`) and deduplicate by `resourceKey` before applying `MAX_LIMIT` so alphabetical concept density never truncates distinct domain resources (e.g. `operations.missoes`) from `DOMAIN_RESOURCE_IDENTITY_CATALOG`.109- In `AgenticAuthoringApiMetadataCandidateCatalog`, evaluate `primaryBusinessEntityAlignmentScore` after `semanticRoleFit` when `resourceNeed == GENERIC_OPERATIONAL`, preserving `PROFILE` and `ANALYTICS` projections while breaking ties in favor of the parent `primaryBusinessEntity` in parent-child and operational requests.110- Do not treat successful ingestion, a populated Domain 360 response, or vector availability alone as proof of grounding. An operational gate must wait for `expectedDocumentCount == publishedDocumentCount > 0` and audit that every provider pre-intent call contains the governed context.111112## Consultative Answers113114- `artifactKind=api_catalog` is a read-only consultative path. It may combine API candidates with a compact Domain Catalog projection and LLM-authored response, but it must not trigger preview/apply or pretend an unconfirmed domain exists.115- Preserve the structured grounding envelope, candidate APIs, consultative projection, warnings, evidence bundles, retrieval source, scores, scope, release, and elapsed/count diagnostics. Caches are bounded performance aids and must be invalidatable during ingestion verification.116- Resource candidates identify possible operations. Verify the chosen operation through `/schemas/filtered`, actions, surfaces, and capabilities before generating executable configuration.117118## Decision Rules119120- Treat `api_metadata`, vector documents, project knowledge, domain catalog hints, schemas, and runtime state as evidence for AI/tool grounding.121- Do not answer API catalog questions with hardcoded deterministic prose when LLM/RAG grounding is available.122- Do not use local text search as the primary decision for business resource selection.123- Preserve tenant, environment, release id, version, generatedAt, operationId, schemas, params, tags, scores, content hashes, source pointers, retrieval source, and raw JSON enough for replayable grounding.124- Preserve RAG status/reconcile diagnostics when ingestion changes: expected document count, published document count, vector-store availability, publication-enabled flag, resource type, tenant, environment, service key, and release id.125- Fail closed when scoped or required grounding is unavailable; do not launder lexical fallback into a selected resource or successful materialization.126- Keep caches performance-only; `api_metadata`, `ai_registry`, runtime metadata, and persisted turn events remain canonical.127- If schema or resource semantics are missing, inspect `praxis-metadata-starter` contracts before inventing config-starter API metadata fields.128129## No Keyword Routing130131Do not resolve intent, resource, endpoint, schema, field, or API recommendation through labels, aliases, regexes, or local fuzzy matching as the primary decision. Use governed LLM/tool resolution, `api_metadata`, schema contracts, Project Knowledge, Domain Catalog, declared tools, and candidate provenance for grounding; textual matching may only rank candidates after semantic scope is established.132133## Aderence Inventory134135Before adding API metadata fields, context blocks, RAG metadata keys, candidate diagnostics, cache semantics, or context endpoints, classify:136137- `ja-suportado-so-ux`138- `ja-suportado-mal-nomeado-ou-mal-materializado`139- `suportado-parcialmente`140- `lacuna-real-de-contrato`141142Only real gaps justify new public grounding contracts. Identify source owner, downstream assistant/runtime consumers, generated AI contracts, docs, quickstart smokes, and minimum validation.143144## Validation145146Use focused local gates:147148- ingestion/context: `mvn "-Dtest=ApiMetadataIngestionServiceTest,ApiMetadataControllerTest,AiContextControllerTest,ContextRetrievalServiceTest,SchemaRetrievalServiceTest" test`149- resource/project knowledge/runtime grounding: `mvn "-Dtest=AgenticAuthoringApiMetadataCandidateCatalogTest,AgenticAuthoringResourceDiscoveryServiceTest,AgenticAuthoringProjectKnowledgeServiceTest,VectorRankedProjectKnowledgeCandidateRetrieverTest,AgenticAuthoringRuntimeComponentGroundingServiceTest" test`150- RAG/vector changes: `mvn "-Dtest=RagVectorStoreServiceTest,RagVectorStoreConfigurationTest,RagProjectKnowledgeMetadataTest,RagProjectKnowledgeDerivedIndexServiceTest" test`151- Domain Catalog prompt/RAG grounding: `mvn "-Dtest=DomainCatalogIngestionServiceTest,DomainCatalogPromptContextServiceTest,RagVectorStoreServiceTest,AgenticAuthoringLlmPreIntentToolPlanningServiceTest" test`152- Angular AI-context consumer: `npm run test:praxis-ai:backend-api`153154Review `docs/ai/**`, `docs/domain-catalog/**`, API contract docs, quickstart ingestion/smoke scripts, and Angular AI context consumers when public grounding changes.155156## Companion Skills157158- Use `praxis-metadata-schema-contracts` when grounding depends on backend resource schema semantics.159- Use `praxis-config-runtime-persistence` when `/ai-context` GET state resolution or tenant/user/environment config behavior changes.160- Use `praxis-ai-backend-config-contracts` when Angular endpoint resolution or identity headers change.161- Use `praxis-config-agentic-authoring-streaming` when candidates feed intent resolution, turn stream, quick replies, or terminal diagnostics.162- Use `praxis-config-domain-decisions` when grounding should route to shared rule/knowledge authoring.163- Use `praxis-api-quickstart-cockpit-http-validation` for downstream proof of domain catalog ingest, API catalog grounding, Project Knowledge, and HTTP examples.164- Use `praxis-ai-semantic-intent` for Angular assistant consult/edit boundaries.