Use Learn to understand and apply the system. Use Standards when you need the governing contract.
Build Your First Artifact Definition
Create a first synchronized Cuddler Artifact Definition set by aligning the governing Document Role, shared Artifact Specification, definition file context, and example documents.
Tutorial path
Building a first Artifact Definition
The shortest useful path is to follow the standards in the order they constrain the artifact family.
1Choose the role
Start from the Document Role so the artifact family has the right governing context.
→
2Apply the shared artifact rules
Read the Artifact Specification before drafting the family.
→
3Study published examples
Use existing Artifact Definitions to see how the public surface is structured.
→
4Draft aligned schemas
Keep the data contract and render contract in the same family from the start.
→
5Validate, then render
Finish by proving the contracts work before the final output step.
The tutorial is about applying the standards correctly, not replacing them.
This tutorial shows the shortest useful path for creating a synchronized local Artifact Definition set. The goal is not to reinvent the standards; it is to use them in the right order so the result can be validated, updated in place, and rendered consistently.
The workflow
Start with the relevant Document Role
so you know which domain you are working in.
Read the shared Artifact Specification
so your artifact follows the common publication rules.
Prepare the orchestration payload with outputPath and sourceDefinitionPath; point sourceDefinitionPath at the source-side JSON context file you want embedded, and the Process side now resolves automatically to the single *.process.json contract.
Inspect the matching Artifact Definitions
and any existing source definition file to see how published examples and current context are structured.
Draft the Process document, Data definition, and Template document together so the controller, model, and markdown-template view contracts stay aligned. Only the Data member is locally authored as a schema; the Template and Process members consume the published schemas from www.cuddler.dev.
Validate the synchronized bundle plus the definition file, then update the current files in place.
Use the resulting Data definition and Process document plus the concrete Template document to drive instance creation and final rendering.
What to keep in view
The Document Role tells you what the domain means.
The Artifact Specification tells you how a public Artifact Definition must be authored.
The latest standards registry at /standards/latest/index.json
exposes the current public versions and direct JSON URLs when a local cache needs to refresh.
<artifactId>.definition.json inside outputPath tells downstream tooling which synchronized bundle is current, including <artifactId>.data-example.json, and embeds the parsed JSON copied from sourceDefinitionPath.
The example Artifact Documents tell you what a successful implementation looks like without overriding the standards.
Practical checkpoints
Keep the synchronized bundle aligned on one artifact identity and business purpose.
Keep the selectedDefinitions block in <artifactId>.definition.json inside outputPath pointed at the current bundle.
Bind the instance "$schema" to the exact canonical schema identity.
Keep the Process output as one *.process.json document that consumes the published questionnaire schema; if the target questions are sequential, route question to question until completion, and if they branch, keep that branching inside deterministic question-level routing in the same document.
Treat validation failures as blockers, not warnings to work around.
Keep the final rendered output readable without weakening sanitization defaults.
Next step
Once you have a first synchronized definition set working, move to Create a Data Schema
and Create a Template Schema
so you can refine the shared Data and Template standards that govern the local synchronized bundle.
