Praxis HTTP Examples Contract Surfaces
Use this skill for HTTP examples that exercise Praxis metadata, config, and quickstart contracts. Examples must explain and execute canonical contracts; they must not redefine them.
Source Audit
Inspect the owner before editing:
praxisui-http-examples/README.md
http/metadata/**
http/config/**
http/resources/**
http/views/**
http/operations/**
payloads/config/**
payloads/resources/**
payloads/views/**
examples.manifest.json
LLM_BOOTSTRAP.md
LLM_SURFACE.md
ENTITY_LOOKUP_PUBLICATION_RUNBOOK.md when an example covers RESOURCE_ENTITY, provider-backed option sources, dependencyFilterMap, or governed option-source materialization
Canonical Boundary
Metadata examples derive from praxis-metadata-starter and the quickstart published host: /schemas/filtered, /schemas/catalog, /schemas/surfaces, /schemas/actions, item capabilities, _links, ETag, If-None-Match, X-Schema-Hash, option sources, stats, and resource endpoints.
Config examples derive from praxis-config-starter hosted by quickstart: /api/praxis/config/ui, ai-context, ai-registry, domain-rules, domain-knowledge, authoring/patch/SSE, tenant headers, and allowed Origin.
Decision Rules
- Public metadata examples should stay header-light unless debugging requires tenant context.
- Auth-light examples may use
X-Tenant-ID, X-Env, and X-User-ID for deterministic scoped behavior.
- Protected config examples must preserve allowed
Origin and tenant/environment headers.
- Destructive/protected writes should not be promoted into default LLM operational examples.
- Do not infer persistence, AI, schema, option-source, or domain-rule contracts from illustrative-only/legacy examples.
- When a contract changes, update request file, payload, manifest, LLM surface, and source-of-truth links together.
- For option-source examples, separate LLM-safe operational evidence from canonical runtime proof. An HTTP example may demonstrate a published lookup route, mapped dependency payload, by-ids rehydration, or governed materialization readback, but it must point back to the canonical metadata/config owner and quickstart focused tests for descriptor semantics, selection policy, invalid-value handling, ordering guarantees, and provider SPI behavior.
- Do not promote an option-source example into
llmOperational only because it succeeds once against the published backend. It must be read-only or auth-light, have stable headers, use a deterministic payload, avoid ordinary production scopes, and explain whether it is discovery/reachability, runtime lookup proof, or governed materialization evidence.
- For
dependencyFilterMap, examples should show the backend filter payload accepted by the endpoint and link it to the schema-published mapping. Do not teach Angular, Ergon, or LLM consumers to invent local field translations when the backend descriptor is the source of truth.
Reactive Determination examples pair the operation-specific filtered schema with
success and business-rejection execution payloads, preserve provenance without
leaking snapshots, and remain synchronized with examples.manifest.json, the
corpus verifier, smoke, and LLM surface.
No Keyword Routing
Do not decide endpoint class, header requirements, source owner, or safety level by filename words, labels, aliases, regexes, or local fuzzy matching as the primary decision. Use manifest flags, HTTP method, route contract, source-of-truth links, protected/public classification, and canonical starter/quickstart evidence.
Aderence Inventory
Before adding metadata/config examples, headers, payloads, response-shape hints, protected flags, or source links, classify:
ja-suportado-so-ux
ja-suportado-mal-nomeado-ou-mal-materializado
suportado-parcialmente
lacuna-real-de-contrato
Only real example coverage gaps justify corpus additions. Backend contract gaps belong to the canonical owner.
Validation
Use focused local gates:
- manifest and generated surface:
npm run verify:manifest
- public metadata examples:
npm run smoke:public
- protected/auth-light examples:
npm run smoke:auth or the narrower relevant smoke
- LLM operational surface examples:
npm run smoke:llm-surface
- generated LLM/bootstrap promises:
npm run smoke:corpus-promises and npm run smoke:bootstrap-minimums
- domain-rule proof:
npm run smoke:domain-rules-publication
State whether validation hit the published backend or only structural checks.
Companion Skills
Use praxis-reactive-determinations for the end-to-end owner/runtime contract behind the examples.
Use praxis-http-examples-corpus-manifest for manifest flags and corpus integrity.
Use praxis-http-examples-llm-smoke for LLM-safe lanes and smoke selection.
Use praxis-api-quickstart-security-config for Origin/config exposure behavior.
Use praxis-metadata-* and praxis-config-* skills for canonical contract changes.
Versioned Resource Writes
A versioned PUT/PATCH example must pair the payload with the strong ETag of the same GET snapshot and send it unchanged as If-Match. Include session and CSRF prerequisites where the host requires them. If the corpus parser supports only one request per file, keep GET and mutation as separate indexed requests with explicit transfer instructions instead of silently adding an unparsed multi-request flow. Reject stale snapshots (412) and absent preconditions (428); never refresh only the token and automatically resend stale data. Keep candidate proof separate from published-backend confirmation.
For payroll G4, inspect the corpus's PAYROLL_G4_CONTRACT.md, the exact
operation request schemas and Quickstart command DTOs before editing examples.
The host-specific precondicoesFolhas is a typed list of
{folhaPagamentoId, resourceVersion}; do not invent a generic decisionVersion
or reinterpret one main If-Match as a multi-parent header. Event edit captures
the body, event response ETag and precondicaoFolhaAtual in one joined GET
snapshot. Preserve that origin token; create/destination changes capture the
selected payroll through its official GET. A move includes distinct origin and
destination entries, while same-parent edit includes one original entry.
Preserve complete strong token bytes, including quotes when encoded in JSON,
and keep fixture identities/tokens explicitly illustrative until provisioned.
Keep source-derived G4 examples classified as candidates with
runtimeRecordConfirmed=false, publishedBackendConfirmed=false and
llmOperational=false until the relevant runtime/published proof exists.
Offline manifest/schema checks do not establish HTTP, current authorization,
CAS, atomic persistence or deployed adoption. Synchronize the candidate note,
request, payload, manifest, verifier and LLM surface without promoting a write
or adding an unproved version claim. Declared financial outputs are verified by
the governed host; no client formula or invented authority field fills a gap.
1---2name: praxis-http-examples-contract-surfaces3description: "Use when Codex must work on praxisui-http-examples contract request surfaces: metadata examples for /schemas/filtered, /schemas/catalog, /schemas/surfaces, /schemas/actions, /capabilities, _links, ETag and schema headers; config examples for /api/praxis/config/**, ui config, AI context, AI registry, domain rules, domain knowledge, authoring/patch/SSE, Origin and tenant headers."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-http-examples-contract-surfaces6---78# Praxis HTTP Examples Contract Surfaces910Use this skill for HTTP examples that exercise Praxis metadata, config, and quickstart contracts. Examples must explain and execute canonical contracts; they must not redefine them.1112## Source Audit1314Inspect the owner before editing:1516- `praxisui-http-examples/README.md`17- `http/metadata/**`18- `http/config/**`19- `http/resources/**`20- `http/views/**`21- `http/operations/**`22- `payloads/config/**`23- `payloads/resources/**`24- `payloads/views/**`25- `examples.manifest.json`26- `LLM_BOOTSTRAP.md`27- `LLM_SURFACE.md`28- `ENTITY_LOOKUP_PUBLICATION_RUNBOOK.md` when an example covers `RESOURCE_ENTITY`, provider-backed option sources, `dependencyFilterMap`, or governed option-source materialization2930## Canonical Boundary3132Metadata examples derive from `praxis-metadata-starter` and the quickstart published host: `/schemas/filtered`, `/schemas/catalog`, `/schemas/surfaces`, `/schemas/actions`, item capabilities, `_links`, `ETag`, `If-None-Match`, `X-Schema-Hash`, option sources, stats, and resource endpoints.3334Config examples derive from `praxis-config-starter` hosted by quickstart: `/api/praxis/config/ui`, `ai-context`, `ai-registry`, `domain-rules`, `domain-knowledge`, authoring/patch/SSE, tenant headers, and allowed `Origin`.3536## Decision Rules3738- Public metadata examples should stay header-light unless debugging requires tenant context.39- Auth-light examples may use `X-Tenant-ID`, `X-Env`, and `X-User-ID` for deterministic scoped behavior.40- Protected config examples must preserve allowed `Origin` and tenant/environment headers.41- Destructive/protected writes should not be promoted into default LLM operational examples.42- Do not infer persistence, AI, schema, option-source, or domain-rule contracts from illustrative-only/legacy examples.43- When a contract changes, update request file, payload, manifest, LLM surface, and source-of-truth links together.44- For option-source examples, separate LLM-safe operational evidence from canonical runtime proof. An HTTP example may demonstrate a published lookup route, mapped dependency payload, by-ids rehydration, or governed materialization readback, but it must point back to the canonical metadata/config owner and quickstart focused tests for descriptor semantics, selection policy, invalid-value handling, ordering guarantees, and provider SPI behavior.45- Do not promote an option-source example into `llmOperational` only because it succeeds once against the published backend. It must be read-only or auth-light, have stable headers, use a deterministic payload, avoid ordinary production scopes, and explain whether it is discovery/reachability, runtime lookup proof, or governed materialization evidence.46- For `dependencyFilterMap`, examples should show the backend filter payload accepted by the endpoint and link it to the schema-published mapping. Do not teach Angular, Ergon, or LLM consumers to invent local field translations when the backend descriptor is the source of truth.4748Reactive Determination examples pair the operation-specific filtered schema with49success and business-rejection execution payloads, preserve provenance without50leaking snapshots, and remain synchronized with `examples.manifest.json`, the51corpus verifier, smoke, and LLM surface.5253## No Keyword Routing5455Do not decide endpoint class, header requirements, source owner, or safety level by filename words, labels, aliases, regexes, or local fuzzy matching as the primary decision. Use manifest flags, HTTP method, route contract, source-of-truth links, protected/public classification, and canonical starter/quickstart evidence.5657## Aderence Inventory5859Before adding metadata/config examples, headers, payloads, response-shape hints, protected flags, or source links, classify:6061- `ja-suportado-so-ux`62- `ja-suportado-mal-nomeado-ou-mal-materializado`63- `suportado-parcialmente`64- `lacuna-real-de-contrato`6566Only real example coverage gaps justify corpus additions. Backend contract gaps belong to the canonical owner.6768## Validation6970Use focused local gates:7172- manifest and generated surface: `npm run verify:manifest`73- public metadata examples: `npm run smoke:public`74- protected/auth-light examples: `npm run smoke:auth` or the narrower relevant smoke75- LLM operational surface examples: `npm run smoke:llm-surface`76- generated LLM/bootstrap promises: `npm run smoke:corpus-promises` and `npm run smoke:bootstrap-minimums`77- domain-rule proof: `npm run smoke:domain-rules-publication`7879State whether validation hit the published backend or only structural checks.8081## Companion Skills8283- Use `praxis-reactive-determinations` for the end-to-end owner/runtime contract behind the examples.8485- Use `praxis-http-examples-corpus-manifest` for manifest flags and corpus integrity.86- Use `praxis-http-examples-llm-smoke` for LLM-safe lanes and smoke selection.87- Use `praxis-api-quickstart-security-config` for Origin/config exposure behavior.88- Use `praxis-metadata-*` and `praxis-config-*` skills for canonical contract changes.8990## Versioned Resource Writes9192A versioned PUT/PATCH example must pair the payload with the strong ETag of the same GET snapshot and send it unchanged as If-Match. Include session and CSRF prerequisites where the host requires them. If the corpus parser supports only one request per file, keep GET and mutation as separate indexed requests with explicit transfer instructions instead of silently adding an unparsed multi-request flow. Reject stale snapshots (412) and absent preconditions (428); never refresh only the token and automatically resend stale data. Keep candidate proof separate from published-backend confirmation.9394For payroll G4, inspect the corpus's `PAYROLL_G4_CONTRACT.md`, the exact95operation request schemas and Quickstart command DTOs before editing examples.96The host-specific `precondicoesFolhas` is a typed list of97`{folhaPagamentoId, resourceVersion}`; do not invent a generic `decisionVersion`98or reinterpret one main `If-Match` as a multi-parent header. Event edit captures99the body, event response ETag and `precondicaoFolhaAtual` in one joined GET100snapshot. Preserve that origin token; create/destination changes capture the101selected payroll through its official GET. A move includes distinct origin and102destination entries, while same-parent edit includes one original entry.103Preserve complete strong token bytes, including quotes when encoded in JSON,104and keep fixture identities/tokens explicitly illustrative until provisioned.105106Keep source-derived G4 examples classified as candidates with107`runtimeRecordConfirmed=false`, `publishedBackendConfirmed=false` and108`llmOperational=false` until the relevant runtime/published proof exists.109Offline manifest/schema checks do not establish HTTP, current authorization,110CAS, atomic persistence or deployed adoption. Synchronize the candidate note,111request, payload, manifest, verifier and LLM surface without promoting a write112or adding an unproved version claim. Declared financial outputs are verified by113the governed host; no client formula or invented authority field fills a gap.