# Praxis HTTP Examples Contract Surfaces

> Praxis HTTP Examples Contract Surfaces

- Skill: `codexrodrigues/praxis-http-examples-contract-surfaces` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-http-examples-contract-surfaces`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-http-examples-contract-surfaces/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-http-examples-contract-surfaces

---


# 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.

