Praxis AI Authoring Manifests
Use this skill for executable AI authoring contracts. A manifest is not decorative documentation; it is the contract that tells backend tools how to ground, validate, compile, and reject component edits.
Pair with praxis-ai-backend-config-contracts when manifest operations are exposed through /api/praxis/config/ai/**; pair with praxis-ai-turn-orchestration-transport when component edit plans are transported through assistant turns; pair with praxis-ai-composer-attachments-quick-replies when quick replies or clarifications select manifest targets or operations.
Use praxis-config-ai-registry-manifests when the backend ai_registry, registry snapshot ingestion, manifest projection, validators, compilers, or /api/praxis/config/ai/authoring/manifests/** behavior is the source of truth. Do not patch Angular manifests to compensate for stale backend registry projection.
Canonical Model
Every manifest change must preserve:
public component surface -> editable targets -> operation schema -> validators -> effects/handler contract -> affected paths -> editor/runtime round-trip -> registry ingestion
Do not expose arbitrary JSON patching when a component requires governed semantic decisions. Use component-specific operations with deterministic targets, schemas, validators, and effects.
Required Inventory
Inspect the owning component:
projects/<lib>/src/lib/ai/*authoring-manifest.ts
- focused manifest spec
- AI adapter and context pack when present
- component
public-api.ts
- component metadata /
ComponentDocMeta / configEditor
- visual editor and runtime specs for the edited paths
- related docs, examples, recipes, and registry ingestion outputs when public behavior changes
Also inspect projects/praxis-core/src/lib/ai/authoring-manifest.types.ts when changing manifest shape.
When backend registry projection, validation, compilation, or /api/praxis/config/ai/authoring/manifests/** endpoints are in scope, inspect praxis-config-starter/AGENTS.md, AgenticAuthoringManifestController, AgenticAuthoringManifestService, AgenticAuthoringManifestContractValidator, AgenticAuthoringManifestEditPlanRequest, AgenticAuthoringManifestValidationResult, AgenticAuthoringManifestCompileResult, and their focused tests. The backend is the runtime authority for resolving registry manifests, validating edit plans, compiling patches, and returning controlled configuration errors.
When ingestion/projection is in scope, inspect praxis-ai-registry-ingestion: extract-component-docs.js preserves authoringManifestRef, generate-registry-ingestion.ts projects authoringManifest, authoringManifestProfiles, and authoring-only entries, and validate-authoring-contracts-acceptance.js verifies the generated registry entry. Do not treat a source manifest as public until its registry projection is proven.
For component-specific manifest work, use the focused skill when available: praxis-page-builder-ai-agentic for PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST, UiCompositionPlan, child operation delegation, streaming authoring, and Page Builder registry gates; praxis-visual-builder-rules for PRAXIS_VISUAL_BUILDER_AUTHORING_MANIFEST, rule graph operations, JSON Logic round-trip, and visual-builder AI adapter behavior.
Manifest Rules
- Separate
consult/answer from edit/componentEditPlan; factual questions must not fabricate patches.
- Every operation target must resolve through an editable target with explicit ambiguity policy.
scope=global operations must use target.required=false; all non-global operations must provide a structured target with kind, resolver, ambiguityPolicy, and required=true unless the type or source owner documents a safe exception. Do not use the reserved scope='target'.
- Operation input schemas must be concrete enough for backend tooling; broad objects require a resolvable downstream schema or explicit blocker.
compile-domain-patch effects need deterministic handler contracts: reads, writes, stable identity keys, input schema, failure modes, and operational description.
- A new
compile-domain-patch.handler is only an Angular declaration until AgenticAuthoringEffectCompilerRegistry.supportsDomainPatchHandler(handler) and focused backend compiler tests prove it. Classify it as suportado-parcialmente until then.
- Effects must overlap affected paths and validators must be used by pertinent operations.
- Destructive operations require confirmation.
- Family-level manifests need an aggregate registry entry addressable by
componentId, not only child copies.
- Declared-only fields may be authorable for round-trip, but docs/validators must not imply active runtime behavior.
- Every non-global operation declares
target.kind, resolver, ambiguity policy, preconditions, supported string submissionImpact, validators, effects, and affected paths. The deprecated targetKind, when retained, must equal target.kind; boolean submissionImpact is legacy only and should not be introduced in semantically validated manifests.
- Every global validator is used by an operation. Effect paths must overlap affected paths; collection effects declare identity keys;
compile-domain-patch declares reads, writes, identity keys, input schema, failure modes, and a meaningful handler description.
- Manifest examples are executable grounding/eval evidence: include positive examples and at least one explicit negative example. Do not encode lexical routing as an example substitute.
- Remote-binding operations must prove input-schema and path/effect evidence, use a pertinent binding validator, and declare
affects-remote-binding; do not label an unrelated operation as remote merely to satisfy a gate.
- Family
controlProfiles repeat the same operation metadata and applicability evidence. The generated registry must expose the aggregate family entry, projectedComponentIds, child authoringManifestProfiles, and preserved operation metadata.
- For family manifests, edit profile semantics only in the aggregate source manifest. Child
authoringManifestProfiles in generated registry entries are applicability projections, not a
second manifest source. If a child component lacks a projected profile, audit the family
controlProfiles.appliesTo rules, component docs extraction, and registry ingestion before adding
a new operation, patching the corpus, or treating a capability alias as a component identity.
- Presentation affordances must identify their source, default target, and compatible options; they are consultative constraints, not edit permission.
- Quick replies, clarification options, feedback, stream diagnostics, and transport lifecycle events may select or carry
a backend-issued semantic decision, but they cannot invent
operationId, target resolver, validator, effect, handler,
affected path, submissionImpact, or apply permission. Those must resolve back to the projected manifest and backend
validation/compilation contract.
- A
semanticDecision or componentEditPlan is only executable when every referenced operation, target, validator,
effect, and presentation affordance can be traced to the current registry-projected manifest for the component/profile.
Treat untraceable references as contract drift or clarification, not as a reason to patch UI state locally.
Use projectComponentAuthoringManifest() when a child component such as Filter
Form or standalone Filter exposes a closed subset of an owner manifest. Select
source runtime inputs and operation ids by stable identity and require closure
of editable targets, validators, positive/negative examples, and round-trip
requirements. Missing or duplicate references fail closed. Never copy source
operations into a second child-owned manifest. Inspect Core
authoring-manifest.types.ts, authoring-manifest-projection.ts, and their
specs whenever this projection contract changes.
Synchronization Triggers
Review manifests when a public component change touches:
- inputs, outputs, events, config paths, editor fields, defaults, capabilities, actions, surfaces
- apply/save/reset/reopen behavior
- runtime/editor parity
ComponentDocMeta, configEditor, public README, examples, recipes, playgrounds
- AI assistant context, quick replies, diagnostics, preview, apply payload, or component edit plan
- backend AI manifest endpoints, turn stream payloads, quick reply semantic decisions, or clarification options that reference manifest targets/operations
If no manifest update is required after a public change, state why.
Validation
Run the focused manifest spec first. Use npm run validate:authoring-contracts or the direct validator when the manifest is complete/public. Use praxis-ai-registry-ingestion when generated registry/catalog artifacts must be updated or verified.
For backend registry projection, manifest endpoint, edit-plan validation, compile-patch, presentation affordance, or configuration-error behavior, run the focused config-starter gate:
mvn "-Dtest=AgenticAuthoringManifestContractValidatorTest,AgenticAuthoringManifestServiceTest,AgenticAuthoringManifestControllerTest" test
For Angular public manifest corpus changes, run:
npm run validate:authoring-contracts
For manifest changes that add or rename operation ids, target resolvers, validator ids, effect kinds, compile-domain-patch handlers, presentation affordance catalogs, or family profiles consumed by the config backend, pair Angular and backend proof:
npm run generate:registry:ingestion
mvn "-Dtest=AgenticAuthoringManifestServiceTest,AgenticAuthoringManifestControllerTest,AgenticAuthoringManifestContractValidatorTest,AgenticAuthoringTargetResolverRegistryTest,AgenticAuthoringValidatorRegistryTest,AgenticAuthoringEffectCompilerRegistryTest" test
For a public manifest, prove the owning runtime/editor round-trip and inspect the generated registry entry, public export, README claim, and required implementation/semantic reports. A passing TypeScript literal is insufficient when targets, effects, validators, profile projection, or runtime coverage disagree.
1---2name: praxis-ai-authoring-manifests3description: Use when creating, updating, reviewing, or validating Praxis component authoring manifests, `ComponentAuthoringManifest`, editableTargets, operations, validators, effects, handler contracts, consult/edit response modes, component edit plans, authoring context packs, AI adapters, or manifest synchronization after public component API/editor/runtime changes.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-ai-authoring-manifests6---78# Praxis AI Authoring Manifests910Use this skill for executable AI authoring contracts. A manifest is not decorative documentation; it is the contract that tells backend tools how to ground, validate, compile, and reject component edits.1112Pair with `praxis-ai-backend-config-contracts` when manifest operations are exposed through `/api/praxis/config/ai/**`; pair with `praxis-ai-turn-orchestration-transport` when component edit plans are transported through assistant turns; pair with `praxis-ai-composer-attachments-quick-replies` when quick replies or clarifications select manifest targets or operations.1314Use `praxis-config-ai-registry-manifests` when the backend `ai_registry`, registry snapshot ingestion, manifest projection, validators, compilers, or `/api/praxis/config/ai/authoring/manifests/**` behavior is the source of truth. Do not patch Angular manifests to compensate for stale backend registry projection.1516## Canonical Model1718Every manifest change must preserve:1920`public component surface -> editable targets -> operation schema -> validators -> effects/handler contract -> affected paths -> editor/runtime round-trip -> registry ingestion`2122Do not expose arbitrary JSON patching when a component requires governed semantic decisions. Use component-specific operations with deterministic targets, schemas, validators, and effects.2324## Required Inventory2526Inspect the owning component:2728- `projects/<lib>/src/lib/ai/*authoring-manifest.ts`29- focused manifest spec30- AI adapter and context pack when present31- component `public-api.ts`32- component metadata / `ComponentDocMeta` / `configEditor`33- visual editor and runtime specs for the edited paths34- related docs, examples, recipes, and registry ingestion outputs when public behavior changes3536Also inspect `projects/praxis-core/src/lib/ai/authoring-manifest.types.ts` when changing manifest shape.3738When backend registry projection, validation, compilation, or `/api/praxis/config/ai/authoring/manifests/**` endpoints are in scope, inspect `praxis-config-starter/AGENTS.md`, `AgenticAuthoringManifestController`, `AgenticAuthoringManifestService`, `AgenticAuthoringManifestContractValidator`, `AgenticAuthoringManifestEditPlanRequest`, `AgenticAuthoringManifestValidationResult`, `AgenticAuthoringManifestCompileResult`, and their focused tests. The backend is the runtime authority for resolving registry manifests, validating edit plans, compiling patches, and returning controlled configuration errors.3940When ingestion/projection is in scope, inspect `praxis-ai-registry-ingestion`: `extract-component-docs.js` preserves `authoringManifestRef`, `generate-registry-ingestion.ts` projects `authoringManifest`, `authoringManifestProfiles`, and authoring-only entries, and `validate-authoring-contracts-acceptance.js` verifies the generated registry entry. Do not treat a source manifest as public until its registry projection is proven.4142For component-specific manifest work, use the focused skill when available: `praxis-page-builder-ai-agentic` for `PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST`, `UiCompositionPlan`, child operation delegation, streaming authoring, and Page Builder registry gates; `praxis-visual-builder-rules` for `PRAXIS_VISUAL_BUILDER_AUTHORING_MANIFEST`, rule graph operations, JSON Logic round-trip, and visual-builder AI adapter behavior.4344## Manifest Rules4546- Separate `consult/answer` from `edit/componentEditPlan`; factual questions must not fabricate patches.47- Every operation target must resolve through an editable target with explicit ambiguity policy.48- `scope=global` operations must use `target.required=false`; all non-global operations must provide a structured `target` with `kind`, `resolver`, `ambiguityPolicy`, and `required=true` unless the type or source owner documents a safe exception. Do not use the reserved `scope='target'`.49- Operation input schemas must be concrete enough for backend tooling; broad objects require a resolvable downstream schema or explicit blocker.50- `compile-domain-patch` effects need deterministic handler contracts: reads, writes, stable identity keys, input schema, failure modes, and operational description.51- A new `compile-domain-patch.handler` is only an Angular declaration until `AgenticAuthoringEffectCompilerRegistry.supportsDomainPatchHandler(handler)` and focused backend compiler tests prove it. Classify it as `suportado-parcialmente` until then.52- Effects must overlap affected paths and validators must be used by pertinent operations.53- Destructive operations require confirmation.54- Family-level manifests need an aggregate registry entry addressable by `componentId`, not only child copies.55- Declared-only fields may be authorable for round-trip, but docs/validators must not imply active runtime behavior.56- Every non-global operation declares `target.kind`, resolver, ambiguity policy, preconditions, supported string `submissionImpact`, validators, effects, and affected paths. The deprecated `targetKind`, when retained, must equal `target.kind`; boolean `submissionImpact` is legacy only and should not be introduced in semantically validated manifests.57- Every global validator is used by an operation. Effect paths must overlap affected paths; collection effects declare identity keys; `compile-domain-patch` declares reads, writes, identity keys, input schema, failure modes, and a meaningful handler description.58- Manifest examples are executable grounding/eval evidence: include positive examples and at least one explicit negative example. Do not encode lexical routing as an example substitute.59- Remote-binding operations must prove input-schema and path/effect evidence, use a pertinent binding validator, and declare `affects-remote-binding`; do not label an unrelated operation as remote merely to satisfy a gate.60- Family `controlProfiles` repeat the same operation metadata and applicability evidence. The generated registry must expose the aggregate family entry, `projectedComponentIds`, child `authoringManifestProfiles`, and preserved operation metadata.61- For family manifests, edit profile semantics only in the aggregate source manifest. Child62 `authoringManifestProfiles` in generated registry entries are applicability projections, not a63 second manifest source. If a child component lacks a projected profile, audit the family64 `controlProfiles.appliesTo` rules, component docs extraction, and registry ingestion before adding65 a new operation, patching the corpus, or treating a capability alias as a component identity.66- Presentation affordances must identify their source, default target, and compatible options; they are consultative constraints, not edit permission.67- Quick replies, clarification options, feedback, stream diagnostics, and transport lifecycle events may select or carry68 a backend-issued semantic decision, but they cannot invent `operationId`, target resolver, validator, effect, handler,69 affected path, `submissionImpact`, or apply permission. Those must resolve back to the projected manifest and backend70 validation/compilation contract.71- A `semanticDecision` or `componentEditPlan` is only executable when every referenced operation, target, validator,72 effect, and presentation affordance can be traced to the current registry-projected manifest for the component/profile.73 Treat untraceable references as contract drift or clarification, not as a reason to patch UI state locally.7475Use `projectComponentAuthoringManifest()` when a child component such as Filter76Form or standalone Filter exposes a closed subset of an owner manifest. Select77source runtime inputs and operation ids by stable identity and require closure78of editable targets, validators, positive/negative examples, and round-trip79requirements. Missing or duplicate references fail closed. Never copy source80operations into a second child-owned manifest. Inspect Core81`authoring-manifest.types.ts`, `authoring-manifest-projection.ts`, and their82specs whenever this projection contract changes.8384## Synchronization Triggers8586Review manifests when a public component change touches:8788- inputs, outputs, events, config paths, editor fields, defaults, capabilities, actions, surfaces89- apply/save/reset/reopen behavior90- runtime/editor parity91- `ComponentDocMeta`, `configEditor`, public README, examples, recipes, playgrounds92- AI assistant context, quick replies, diagnostics, preview, apply payload, or component edit plan93- backend AI manifest endpoints, turn stream payloads, quick reply semantic decisions, or clarification options that reference manifest targets/operations9495If no manifest update is required after a public change, state why.9697## Validation9899Run the focused manifest spec first. Use `npm run validate:authoring-contracts` or the direct validator when the manifest is complete/public. Use `praxis-ai-registry-ingestion` when generated registry/catalog artifacts must be updated or verified.100101For backend registry projection, manifest endpoint, edit-plan validation, compile-patch, presentation affordance, or configuration-error behavior, run the focused config-starter gate:102103```sh104mvn "-Dtest=AgenticAuthoringManifestContractValidatorTest,AgenticAuthoringManifestServiceTest,AgenticAuthoringManifestControllerTest" test105```106107For Angular public manifest corpus changes, run:108109```sh110npm run validate:authoring-contracts111```112113For manifest changes that add or rename operation ids, target resolvers, validator ids, effect kinds, `compile-domain-patch` handlers, presentation affordance catalogs, or family profiles consumed by the config backend, pair Angular and backend proof:114115```sh116npm run generate:registry:ingestion117mvn "-Dtest=AgenticAuthoringManifestServiceTest,AgenticAuthoringManifestControllerTest,AgenticAuthoringManifestContractValidatorTest,AgenticAuthoringTargetResolverRegistryTest,AgenticAuthoringValidatorRegistryTest,AgenticAuthoringEffectCompilerRegistryTest" test118```119120For a public manifest, prove the owning runtime/editor round-trip and inspect the generated registry entry, public export, README claim, and required implementation/semantic reports. A passing TypeScript literal is insufficient when targets, effects, validators, profile projection, or runtime coverage disagree.