# Madoo > Madoo is a workflow engine for AI media generation (images, video, audio, 3D, documents). These docs explain how to build workflows and document templates and how to integrate Madoo through its Public API (REST) and its MCP server. Every page is also served as markdown at its address plus ".md": start from the page index at the end of this file and fetch only the pages you need. ## Documentation Sets - [Abridged documentation](https://testing-docs.madoo.ai/llms-small.txt): a compact version of the documentation for Madoo, with non-essential content removed - [Complete documentation](https://testing-docs.madoo.ai/llms-full.txt): the full documentation for Madoo ## Notes - The complete documentation includes all content from the official documentation - The content is automatically generated from the same source as the official documentation ## Pages Every page of the documentation, one per line, in markdown. Fetch only the pages you need: the whole-site files above are large. Each line gives the page, what it covers and, after "Read when", the situation it is for. ### Start here - [Madoo documentation](https://testing-docs.madoo.ai/index.md): How Madoo works, how to build workflows and document templates with it, and how to integrate it through the Public API and MCP. Read when: Start here to find the page that fits your task; every page says when it is worth reading. - [When a subscription ends](https://testing-docs.madoo.ai/madoo/account-and-subscription.md): What a Madoo account can and cannot do once its subscription has ended or is paused, how it is reactivated, what happens to its credits, and how long its data is kept. Read when: Read when a call answers subscription_blocked, when someone asks why nothing can be changed or run any more, or before advising someone who is about to cancel or let a subscription lapse. - [AI safety limits](https://testing-docs.madoo.ai/madoo/ai-safety-limits.md): The limits Madoo sets on how much AI an organization and its workspaces can use in a day and in a month — how they show as percentages, what pauses when one is reached (ai_spend_paused with reason safety_limit), when AI resumes, and what to tell the person. Read when: Read when a call answers ai_spend_paused, a run fails with AI_SPEND_PAUSED, or someone asks why AI generation stopped although there are credits, or what the "AI today / AI month" rows of the credit badge mean. - [Usage limits](https://testing-docs.madoo.ai/madoo/usage-limits.md): The optional daily and monthly credit limits of an organization and of its workspaces — what counts, when a request is refused with credit_cap_reached, when work starts again, the 80 % and 100 % warnings, and who can change a limit. Read when: Read when a call answers credit_cap_reached or a run fails with CREDIT_CAP_REACHED, before planning a large batch for an organization that may have a limit, or when someone asks how to stop a team from spending too many credits in a day or a month. - [What Madoo is](https://testing-docs.madoo.ai/madoo/what-is-madoo.md): Madoo is a workflow engine for producing and transforming content — images, video, audio, 3D and documents — with and without AI, repeatably and at any scale, built to be the content engine behind other products. Read when: Read first, before building anything, to understand what Madoo is for, what a workflow is and which way of working with Madoo fits the person you are helping. ### Workflows - [Checking what a run produced](https://testing-docs.madoo.ai/workflows/checking-results.md): How to look at the outputs of a run before delivering them, without downloading them: an image, the pages of a PDF, the slides of a carousel on one contact sheet; a video as twelve timed frames and the waveform of its sound, with the facts that matter (duration, codecs, pixel format, loudness, silences); a stretch of a video or audio looked at closely with from and to. Why an agent should check its own work, how video and audio previews are prepared, and a review that finds a wrong transition in two calls. Free. Read when: After a run completes and before its outputs are shown, sent or chained into another run — always for documents, carousels, videos and audio an agent built, and whenever someone reports that a file looks or sounds wrong. - [Finding a workflow or a run](https://testing-docs.madoo.ai/workflows/finding-workflows-and-runs.md): How to find a workflow or an execution however many there are: the search of the Workflows and Executions pages, REST v1 and MCP is done by the server on the whole workspace and the whole history, page by page. What a search can hold — words of a name (and, for workflows, of a description or a tag), or a complete ID: wf_…, run_…, a GUID, a number — and what each finds, child runs such as the attempts of Repeat Until Accepted included. Read when: When a workflow or a run must be found by its name or by an ID someone gave you — a run_ from a report, a wf_ from a link, the number shown in the app — and before listing every page of a list to look for one. - [How workflows are built](https://testing-docs.madoo.ai/workflows/how-workflows-work.md): The anatomy of a Madoo workflow — nodes, typed ports, parameters, models — its lifecycle from draft to published version, and what happens when it runs. Read when: Before building or changing any workflow, and whenever a validation error or a failed run needs explaining. - [Iteration — processing lists of items](https://testing-docs.madoo.ai/workflows/iteration.md): How one Madoo workflow processes a list of items without loops — enumerators fan a list out, the nodes after them run once per item, aggregators collect the results back — and what happens with lists created at run time, skipped items and two lists at once. Read when: Whenever a workflow must process several items (rows of a table, photos, languages, segments of a long video) or produce one file from many results; read it before wiring any enumerator or aggregator. - [Repeat until accepted — generate, check, correct, try again](https://testing-docs.madoo.ai/workflows/repeat-until-accepted.md): How one step turns a check into a correction: Repeat Until Accepted runs a body workflow — generate, judge, write what to fix — up to five times, hands every attempt the judgement of the one before, and delivers the first result the body accepts, or the best one marked as not accepted. The body's contract, how to choose a judge (a measurement or a model) and write a correction that converges, how many attempts to allow, a whole catalogue in one run, what it costs, how to see every attempt — its picture, verdict and correction — while it runs, and how to read its report; a free lab and two complete examples: a catalogue kept in the brand's colours and a product placed in a scene without being redrawn. Read when: When generated pictures, videos, texts or documents must meet a requirement before they are delivered — the product must stay the product, the picture must keep to the brand colours, the copy must follow the rules — and a check alone would only throw away what fails. Read it before building a workflow with workflow/repeat, and when its report or disposition needs explaining. ### Data and decisions - [Data and decisions](https://testing-docs.madoo.ai/data.md): How values travel through a Madoo workflow — typed inputs, JSON documents, spreadsheets — and how a workflow decides what to do with them: reading fields, calculating, comparing, choosing a branch, checking quality, and skipping the work that is not needed. Read when: Before building a workflow that reads structured data (an order, a record, an AI answer in JSON, a spreadsheet), computes numbers, or runs a step only when a condition holds. - [Branches and absence](https://testing-docs.madoo.ai/data/branches.md): What happens when a value does not arrive: the two kinds of absence (not provided and rejected), which nodes run without a value and which are skipped, how a rejected branch stops everything after it at no cost, the inputs made to receive a cut branch, and how to read absent outputs and skip reasons. Read when: When a workflow has optional inputs, filters, fields that may be missing or steps that run only sometimes — and when a run completed but an output came back absent and you want to know why. - [Building JSON](https://testing-docs.madoo.ai/data/building-json.md): Compose JSON (utility/json_compose) — a JSON document written once with {{name}} placeholders, filled with the values of other steps: typed when a string is one placeholder, escaped inside longer strings, files as their stored reference; checked against a Madoo contract or your own schema. Generate JSON's object shape for lists; Parse JSON for a text that already holds JSON. A lab turns a model's answer and three hotel photos into a booking-site listing with its teaser keyframe map, at no cost. Read when: When a step needs a JSON document made of values from other steps — a keyframe map for Keyframes to Video, the body of a webhook, an item of a template list — and when Text Template would mean writing quotes and escapes by hand. - [Asset bundles](https://testing-docs.madoo.ai/data/bundles.md): A bundle is a package of uploaded files described by one manifest (madoo.bundle-manifest/v1): what it contains, why it beats a fixed number of image inputs when the count varies, how to compose and check one, how a workflow processes each file and chooses by role, what the credit estimate says, and what happens to a file that fails its checks. Read when: When a workflow receives a set of files whose number changes from run to run — the photos of a property, the images of a product, a press kit, the pictures of a hotel — and each file comes with information that matters, such as its role. - [Calculating](https://testing-docs.madoo.ai/data/calculating.md): Calculate (utility/calculate) — totals, VAT, discounts, deposits and averages with exact decimal arithmetic: expressions whose variables become input ports, paths into JSON, sums over lists, if() for conditional amounts, rounding, and why amounts are never left to an AI model. And Date Calculation (utility/date) — the same for calendar dates: an end date, a notice deadline, the days to a booking, the end of the month. Read when: When a workflow needs a number computed from other values — a line total, a subtotal, VAT, a discount above a threshold, a deposit, a count or an average — or a date computed from another — the end of a contract, the last day to give notice, the days left before a booking — and when an error names a CALC_ or DATE_ code. - [Choosing](https://testing-docs.madoo.ai/data/choosing.md): Select by Key — choosing one of several values by a key such as a language code, a category or a format: the selection configuration, what happens when no key matches, and the two patterns: picking among values that were all produced, and routing to one branch and rejoining it so that only the chosen branch runs. Read when: When a workflow must deliver one of several versions — a language, a format, a variant per category — chosen by a key that arrives with the run. - [Deciding](https://testing-docs.madoo.ai/data/deciding.md): Predicate, Combine Conditions and Filter — turning values into true/false decisions, combining several decisions with all/any and nesting, and letting a decision choose which branch runs: pass or reject a value, if/else with two filters, overrides; strict comparisons, and the errors. Read when: When a step should run only if a condition holds — a score above a threshold, a product in stock, an approval, a switch a person turns on — and when a workflow must do one thing or another. - [Data and decisions — examples](https://testing-docs.madoo.ai/data/examples.md): Complete, installable workflows that put the techniques of Data and decisions to work on real jobs: spreadsheets turned into shop catalogues, photos screened before money is spent on them, one language paid for instead of five — AI where writing or imagery helps, deterministic nodes where facts, numbers and decisions must be right. Read when: When you want to see how reading data, calculating, deciding, checking and branching combine with AI steps in a real workflow, or to install one as a starting point. - [Quality checks](https://testing-docs.madoo.ai/data/quality.md): Quality Gate — measured checks turned into one decision: what a quality check is and which nodes produce one, the policy (profile, required checks, weights, missing checks), the three modes (route, warn, fail), the value that is released only on acceptance, and how to read the report. Read when: When a result must meet a standard before it is delivered or before money is spent on it — a photo large enough to print, a mix at the right loudness, a transcript clean enough to translate — and a failure must be explained, not guessed. - [Reading JSON](https://testing-docs.madoo.ai/data/reading-json.md): Extract (utility/extract) — reading one typed value out of a JSON document with a path; the expected type that catches a document that changed shape; what to do when a field is missing (fail, absent, default) and the found output that tells which; where JSON documents come from; errors and their fixes. Read when: When a workflow needs one field of an order, a record, a plan or the JSON answer of an AI model — a name, a flag, a score, an item of a list — and when an error says a path was not found or a value has the wrong type. - [Schemas and contracts](https://testing-docs.madoo.ai/data/schemas.md): JSON Schema in Madoo — why the JSON a workflow receives or exchanges needs a contract, the versioned contracts Madoo defines for its own nodes (dataset, bundle, quality, media, captions, dubbing…), and Validate JSON Schema: checking a document against a catalog schema, your own schema or one received at run time, with fail, warn or route. Read when: When JSON enters a workflow from outside — an AI answer, a supplier feed, a webhook, a file — or passes between steps and the next step needs exact fields and types; and when you want to know what a Madoo node's JSON port contains. - [Spreadsheets and datasets](https://testing-docs.madoo.ai/data/spreadsheets.md): Reading a table — an Excel workbook, a CSV, a JSON array — into a workflow: Data Input and Data Rows, inspecting a file before authoring, how cells become typed values (locale, codes, empty cells, formulas), one iteration per row, collecting the rows back, and when to use CSV Input instead. Read when: When a workflow must process a table that changes from run to run — a price list, a product feed, a list of attendees — or produce one result per row. - [Troubleshooting data and decisions](https://testing-docs.madoo.ai/data/troubleshooting.md): What to do when a data-driven workflow is refused, fails, skips something or returns a wrong value — organised by symptom: validation errors, refused inputs, failed nodes by code, absent outputs and skip reasons, numbers read the wrong way, deferred estimates; with how to read the result and the trace. Read when: When a workflow that reads, computes or decides is rejected at validation, refused at submit, fails at a node, completes with an output absent, or returns a value you did not expect. - [Values and types](https://testing-docs.madoo.ai/data/values.md): The types of the values that travel between Madoo nodes, the input nodes that receive them, why Madoo never converts one type into another, one JSON value versus a list that fans out, JSON inline or stored in a file, and how a value becomes text for a prompt or a message. Read when: When a workflow receives numbers, switches, JSON documents or text from a person, an app or an agent, and whenever an error says a value has the wrong type. - [D01 — Shop catalog from a price list](https://testing-docs.madoo.ai/data/examples/d01-shop-catalog.md): A ceramics studio's Excel price list becomes a Shopify product CSV ready to import: AI copy, tags and SEO checked by a JSON Schema, a product photo generated for each piece, prices with VAT computed, pieces out of stock left out at no cost, and copy that breaks the rules sent to a review list. Installable. Read when: When a catalogue must go from a spreadsheet to a shop, a marketplace or a feed with AI-written copy and images, and you want the numbers exact, the copy held to the shop's limits and no credit spent on what will not be published. - [D02 — Hotel photos to social clips, screened first](https://testing-docs.madoo.ai/data/examples/d02-hotel-clips.md): A hotel's photo shoot arrives as one bundle and only the photos that deserve it become AI video clips: a free measurement drops the photo too small to use, a cheap AI judgement held to a schema drops the blurred and the underexposed ones, and only then the video model is paid — with a motion direction written for each photo. Every photo is accounted for. Installable. Read when: When an expensive AI step (video, high-resolution images, voice) should run only on inputs that are worth it, and you want the screening cheap, explainable and in front of the spending. - [D03 — The audio guide in the visitor's language](https://testing-docs.madoo.ai/data/examples/d03-audio-guide.md): A museum offers the audio guide of a painting in five languages and pays for one: the visitor's choice, however it is written, is normalised to a supported language with English as the fallback; a Predicate and a Filter per language let only that branch run, where an AI rewrites the curator's text for listening and a voice reads it; Select by Key rejoins the branches. Installable. Read when: When one of several versions — a language, a market, a format, a tier — must be produced on demand, each with paid AI steps, and only the one asked for should run and cost. - [D04 — A flower order, priced, confirmed and painted](https://testing-docs.madoo.ai/data/examples/d04-florist-order.md): A flower shop's web order is priced by rules — line totals, a delivery fee per zone that becomes free from 80 euros, an optional coupon — every amount and the delivery day are written in the customer's language by Format as Text, an AI writes the confirmation from those facts without recomputing them, and a gift, only a gift, gets a watercolour card of the very bouquet ordered with the customer's message in handwriting. Installable. Read when: When a workflow must state numbers, prices or dates to a person — a confirmation, a quote, a receipt, a reminder — in that person's language, and an AI writes the message around them; or when an optional part of an order (a gift card, an add-on) should cost only when it is asked for. - [D05 — A supplier's feed to a clean catalog](https://testing-docs.madoo.ai/data/examples/d05-supplier-feed.md): An outdoor-gear shop receives its supplier's daily product feed as a German CSV — semicolons, decimal commas — with the usual mistakes in it. Every row is checked against the shop's contract by a JSON Schema: a valid row becomes a listing, with the retail price computed by rule and the description written by AI; a rejected row goes back to the supplier in a corrections file and a ready-to-send email, each problem stated with its line, the value sent and what is expected. Installable. Read when: When data arrives from someone else — a supplier, a partner, a form, an export — and some of it will be wrong: to keep the good rows moving, stop the bad ones before they reach anything that costs or publishes, and tell the sender exactly what to fix. ### Text - [Text](https://testing-docs.madoo.ai/text.md): How Madoo works with text: confirmations, notices, captions, product listings, summaries, translations, the JSON a later step reads, the prompts of other AI steps. Text that can be assembled from data is written by four free, exact nodes; text that has to be written comes from a language model — a paid step whose answer is a proposal, made reliable by asking for data, checking it and filling the figures in afterwards. Where to read about each part. Read when: Before building a workflow that produces or reads text — a message to a customer, a listing, a summary of a document or a video, a translation, a category for routing, the prompt of an image step — or when a text step fails, is skipped, costs more than expected or writes something it should not. - [What text costs](https://testing-docs.madoo.ai/text/costs.md): How text steps are priced: assembling text is free; a model is charged for the tokens it reads and writes — reasoning included — at the provider's real price converted to credits, to the thousandth; a failed step is charged only what the provider billed for it. The prices of the main models in credits per thousand tokens, what the labs of this section actually cost, how the estimate before a run is made and why the final charge can be far lower (text) or higher (video), and how to keep text steps cheap. A lab writes the same summary with five settings and compares estimate and charge. Read when: When planning what a text workflow will cost, choosing a model or a reasoning setting, reading an estimate that looks high, or a charge that does not match the estimate — and before running a long video or a large batch through an AI text step. - [Text — examples](https://testing-docs.madoo.ai/text/examples.md): Complete, installable workflows that put the techniques of the Text section to work on real jobs: a month of guest reviews in five languages turned into a one-page report and forty replies; an Italian lease turned into a one-page plain-English summary whose dates are checked and computed; six photos turned into a printed catalogue in three languages; a recorded briefing turned into a story, a picture, a voice and posts — the model reads and writes, the workflow counts, checks and verifies. Read when: When you want to see how assembling text, writing with a model, structured answers, checks and templates combine in a real workflow, or to install one as a starting point. - [Languages and translation](https://testing-docs.madoo.ai/text/languages.md): Text in the reader's language: telling a model which language to write in, or letting it answer in the customer's own; translating with Text Generation so that names stay untranslated and the markers a template must fill survive; keeping dates and amounts out of the text and writing them per language with Format as Text; several languages in one JSON answer or one step per language; and the language settings of the other nodes. A lab translates a ferry company's notice into Italian, German and French, with the two mistakes it made on the way. Read when: When a workflow must produce text in more than one language — notices, product sheets, emails, confirmations for customers of several countries — or answer customers in the language they wrote in; and when a translation came back with a date in English, an amount in the wrong format, a lost marker or a sentence that does not agree with the value filled into it. - [Prompts for other AI steps](https://testing-docs.madoo.ai/text/prompts-for-ai-steps.md): How a workflow produces the prompt of its next AI step from its own data: assembled by a template from the fields (exact, free, the same every time), written by a text model following an art direction (richer, a proposal), read from a reference picture by a vision model, or carried in one JSON answer together with the copy. When to use each, how to brief the model that writes the prompt, what it can still get wrong, and a lab that illustrates a cooking school's recipe card twice from the same recipe. Read when: When an image, video or audio step must receive a prompt that depends on the item — a product, a recipe, a property, a person's order — instead of a fixed one; when choosing between a template and a model to write it; and when the pictures of a batch come out generic, inconsistent, or with details that are not in the data. - [Reading pictures](https://testing-docs.madoo.ai/text/reading-pictures.md): The vision nodes that turn photographs into text: Image Analysis answers any question about up to 20 pictures, in prose or as a JSON object (alt texts, attributes, a condition report, a comparison); Image Classifier files a picture under one of your categories and now fails rather than guess when the model answers something else; Product Description writes a whole shop listing in eleven languages; Image to Prompt writes the prompt that would make the picture again. What each one is for, how to steer it, what it does not guarantee, and a lab that catalogues an antiques dealer's objects. Read when: When a workflow must describe, tag, check, sort or list pictures — alt texts for a site, attributes for a catalogue, a listing for a marketplace, the department or template a photo belongs to, a condition report — or when a vision step answered something unexpected, failed with CATEGORY_NOT_IN_LIST, or invented a detail that is not in the photo. - [Reading video and documents](https://testing-docs.madoo.ai/text/reading-video-and-documents.md): Video Analysis watches a video with a Gemini model and answers about it — a summary, chapters with their times, who appears, what happens — in prose or as a JSON object; Document Analysis reads up to 20 PDFs, text and Markdown files with a GPT or Claude model and answers about them, the way to turn a quote, a contract or a price list into data. What each reads, its limits, what it costs (a minute of video is about 0.31 credits), why times from a video model are approximate and figures from a document must be checked, and a lab that reads a supplier's quote and indexes a press briefing. Read when: When a workflow must get text or data out of a video or a document — a summary, chapters, a description of a clip, the lines and totals of a quote, the dates of a contract, the items of a price list — or when a document step was refused for size, or a video step cost more than its estimate. - [Structured answers](https://testing-docs.madoo.ai/text/structured-answers.md): How to get a model to answer with data instead of prose: Response Format JSON Object on Text Generation, Image Analysis, Video Analysis and Document Analysis; how to describe the object in the prompt; what happens when the answer is not an object (the step fails, with what to change, and is charged the tokens it used); why a valid object is not yet the right one and how a schema check guards it; how optional fields should be left out rather than set to null; and how the fields are then read and used. A lab sorts a garden centre's customer emails into tickets. Read when: When a later step needs to read an AI answer field by field — a category, a score, a yes/no, an order number, several texts at once — or decide on it; when a JSON step fails with INVALID_STRUCTURED_RESPONSE or STRUCTURED_RESPONSE_NOT_OBJECT; and when an AI answer that looked right breaks a step further on. - [Troubleshooting text](https://testing-docs.madoo.ai/text/troubleshooting.md): What to do when a text workflow does not give what you expected: a step stopped (AI_RESPONSE_INCOMPLETE, INVALID_STRUCTURED_RESPONSE, STRUCTURED_RESPONSE_NOT_OBJECT, CATEGORY_NOT_IN_LIST, FORMAT_TYPE_MISMATCH, REGEX_TIMEOUT, DOCUMENT_LIMIT_EXCEEDED…), steps after an AI answer were skipped, a text that is too long, invents a fact, mixes languages or loses a marker, a figure written the wrong way, or a charge far from the estimate. Each symptom with its cause and the page that explains it. Read when: When a text step fails, the steps after it are skipped, or the text comes back wrong — before changing the prompt or the model at random. - [Text without a model](https://testing-docs.madoo.ai/text/without-a-model.md): The text nodes that need no AI: Text Template fills named [markers] with values, Text Expression transforms texts with functions (upper case, capitalize, truncate, a condition), Format as Text writes money, numbers, percentages and dates the way a reader of a given language expects, Join Text puts pieces together and leaves out the empty ones, Replace Text finds and replaces words or patterns and counts what it changed. They are exact, instant and free: the same input gives the same text every time, at 0 credits. How each one reads its inputs, what it refuses, and a lab that turns a hotel booking into the confirmation a guest reads. Read when: When a workflow must produce text that can be assembled from data — a confirmation, a notification, an address, a file name, a price in the customer's language, a prompt built from fields — or must clean, mask or normalise a text before it is used; and before reaching for a model to write something that a template would write exactly. - [Writing with a model](https://testing-docs.madoo.ai/text/writing-with-a-model.md): Text Generation, the node that writes with a language model: the prompt and the system prompt and what belongs in each, a prompt assembled from data by a template, Max Tokens and reasoning (which count together and decide whether an answer is finished), which of the 35 models to choose and what each costs, and what a model does not guarantee — length, facts, the same words twice. A lab writes the same bookshop recommendation with four models and settings and compares words, tokens and credits. Read when: When a workflow must write a text that cannot be assembled — a description, a recommendation, a summary, an email, a prompt for another AI step — and when choosing the model, setting Max Tokens and reasoning, or working out why an answer was cut, too long, too free with the facts or more expensive than expected. - [T01 — A month of reviews to an action plan](https://testing-docs.madoo.ai/text/examples/t01-reviews-action-plan.md): A trattoria's forty guest reviews of a month — Google, TripAdvisor, TheFork, in Italian, English, German, French and Spanish — become a one-page report for the owner and a reply for every guest in the guest's own language. A model reads each review into checked data and writes the words of the page; every figure on the page is counted by the workflow, the quotation is verified word for word against the reviews before the page may print, and a document template lays it out with an illustration. About 6 credits. Read when: When many short texts written by customers — reviews, survey answers, support messages, feedback forms — must become something a team acts on: what to fix first, what to keep, who to call today, and a reply for each one; and as a worked pattern for making an AI-written report trustworthy. - [T02 — An Italian lease on one page, in plain English](https://testing-docs.madoo.ai/text/examples/t02-lease-key-terms.md): A residential lease written in Italian becomes a one-page summary in English for a tenant who does not read Italian: a model copies the facts and explains every article; the workflow checks the contract against itself — the end date against the start and the term, the yearly rent against the monthly one — computes the last day to give notice with Date Calculation, and prints the page only if everything agrees, with the notice sentence ready in Italian and English. About 5.4 credits. Read when: When a long document in another language — a lease, a terms-of-service, an employment contract, an insurance policy, a supplier agreement — must become one page a person can act on: the money, the dates, the clauses that matter and what to do before signing; and as a worked pattern for checking a document's figures against each other and computing its deadlines without a model. - [T03 — Six photos to a printed catalogue in three languages](https://testing-docs.madoo.ai/text/examples/t03-antiques-catalogue.md): An antiques dealer's records and photos become three printed catalogues — Italian, English and German — and the same texts for the website. A model looks at every photo and writes each entry in the three languages with no figures; the workflow holds back a lot whose photo is not the object, writes dating, size and price in each language's own conventions, and lays out the three catalogues from one template. About 0.4 credits. Read when: When products, objects or listings must be described in several languages and printed — a catalogue, a price list, a brochure, a marketplace feed — from records and photos; and as a worked pattern for checking that a photo belongs to its record, writing several languages in one step and formatting figures per language without a model. - [T04 — A recorded briefing to a story, a picture, a voice and posts in three languages](https://testing-docs.madoo.ai/text/examples/t04-briefing-to-story.md): Six minutes of NASA interviews become an editorial package in one run: the speech transcribed once; a news story whose quotations are each found word for word in what was said before they are printed; posts for LinkedIn and X in English, Italian and Spanish; a header picture; and a 44-second audio summary read by a synthetic voice. About 11 credits. Read when: When a recording — a press briefing, an interview, a talk, a webinar, a podcast — must become something to publish: an article, posts, a picture and an audio version; and as a worked pattern for quoting people exactly, by checking every quotation against the transcript before it is printed. ### Images - [Images](https://testing-docs.madoo.ai/images.md): How Madoo works with images: pictures travel between nodes as stored files; sizing, cropping, colour, filters, compositing, text, layouts and codes run locally at no credit cost and give the same result every time, while generating and editing with AI models are paid steps that propose a picture; how the two kinds combine in one workflow, what a file may be, and where to read about each family of nodes. Read when: Before building a workflow that prepares, corrects, brands, generates or edits images — product photos for a shop, a catalogue, social formats, ads, try-on, packaging labels — or when an image step fails, costs more than expected or gives a result you did not expect. - [AI edits and utilities](https://testing-docs.madoo.ai/images/ai-edits.md): The AI steps that fix a picture rather than invent one: Remove Background (a clean cut-out), Upscale (up to four times, Topaz by default), Text Removal (finds the text itself), Object Removal and Inpainting (a mask says where), Outpainting (more of the scene around), Reframe (a new frame, the subject untouched) and Perfect Size (an exact size in pixels, centimetres or inches). What each takes and returns, the size of the result, the price, how to make a mask, and a lab that runs six of them on museum-shop photos. Read when: When a product photo needs cleaning before it is used — a background to remove, a label or sticker to take away, a picture too small or in the wrong frame — or when an AI edit returns a picture of an unexpected size, redraws the subject or leaves something in the picture. - [The colors of an image](https://testing-docs.madoo.ai/images/colors-of-an-image.md): Color Palette finds the colors a picture is made of, ordered by how much of it they cover — each with its hex, OKLCh and nearest CSS name, the dominant, accent and background colors, the text color that reads on it — plus a swatch and a check that a picture keeps to the brand colors. Deterministic and free: the same picture always gives the same palette. Shown on real pictures: a teapot on a studio backdrop, garments, a cut-out amphora, hotels and courtyards, Van Gogh and Vermeer, Apollo 11, the NASA logo; with the backdrop marked, excluded or kept, fewer or finer colors, the brand check passing and failing, and recipes for listings, prompts, templates and gates. Read when: When a workflow must know the colors of a picture — the color of a product for its listing or its variants, the palette of a logo or a moodboard to reuse in a template or a prompt, a background that matches a cover, a text color that reads on a color, whether a generated picture keeps to the brand colors — and the answer must be exact, repeatable and free, not a guess from an AI model. - [Colour, tone and filters](https://testing-docs.madoo.ai/images/colour-and-filters.md): How Madoo corrects and styles images without AI: the automatic fix, brightness and contrast, exposure, levels and curves, shadows and highlights, saturation against vibrance, temperature and tint, a colour balance by tonal range, a look from a LUT, grayscale; and the filters — blur, sharpen, denoise, vignette, grain, sepia, colorize, duotone, posterize, threshold, invert, oil paint, emboss and edges — with what each one really does, and a lab that runs one photo through all of them. Read when: When a batch of photos must look consistent — the same exposure, the same warmth, the same look — when a picture needs a correction before it is published or sent to an AI step, when a brand wants a signature style (a duotone, a warm grade, black and white), or when an adjustment gives a result you did not expect. - [Compositing and branding](https://testing-docs.madoo.ai/images/compositing.md): How Madoo puts images and text together without AI: a logo in a corner with an anchored overlay, photographic blend modes, protective watermarks, text in your brand's exact fonts with a layout report, frames and shadows; how transparency is made and used — masks, chroma key, alpha — and a lab that builds a branded product card, a proof, a keyed product and a round crop. Read when: When a picture must carry a brand — a logo, a name, a price, a frame — when proofs must be marked before approval, when a product must be separated from a plain background or cut to a shape, or when an overlay, a watermark or a text lands in the wrong place. - [Consistency and brand](https://testing-docs.madoo.ai/images/consistency.md): How to make AI pictures of many products look like one shoot and one brand: one reference picture as the shared world, the same presets over a catalogue, the same person for a whole collection, and a deterministic brand layer — mark, fonts, colour, size — that is identical every time; what holds a series together and what does not, and a lab that puts three products in one house scene. Read when: When a catalogue, a collection or a campaign needs many AI pictures that belong together — the same set, light, look and brand mark — or when pictures made one by one come out looking like different shoots. - [Designs on products](https://testing-docs.madoo.ai/images/designs-on-products.md): How a logo, a print or a name becomes part of a product in a picture — embroidered on a bag, gold-foiled on a cover, burnt into wood: the 66 effects in 10 families, the seven AI nodes that take one, the blank product that tells the model which part is the design, how to put the design on the blank first with deterministic steps, and a lab that marks three blank products and renders each with a different finish. Read when: When a shop sells personalised or branded products — merchandise, gifts, stationery, packaging, homeware — and must show the design as it will be made, not printed flat on top; or when an effect changes the whole product instead of the design. - [Images — examples](https://testing-docs.madoo.ai/images/examples.md): Complete, installable image workflows on real jobs across business and life: a launch kit for every channel from one product photo, made by a reusable engine; an empty room staged and listed; a press carousel with captions read from the photos; a lookbook with shop codes; a pet painted as an old master; personalised gifts with a proof; a hotel's photos screened for a portal by measuring them; a team page with the same head shot for everyone; generated packshots checked against the real product before they are published; a catalogue kept in the brand colours and a product placed in a scene, each tried again until it is accepted — AI where pictures must be invented, deterministic steps for everything that must be exact. Read when: When you want to see how AI image steps and deterministic image steps combine in a real workflow, or to install one as a starting point. - [Image files and formats](https://testing-docs.madoo.ai/images/files-and-formats.md): How images get into a workflow and out of it — uploads, imports from a URL, runtime inputs, accepted formats and size — what an image node does to a file when it reads it (upright phone photos, SVG turned into pixels, the first frame of an animation, 8 bits per channel) and when it writes it (its own format, PNG when transparency is made, white under a JPEG); how to measure an image and hold it back when it does not meet a delivery's rules; and how to deliver it: WebP or JPEG, a size in kilobytes, metadata removed, a colour profile for print. Read when: Before a workflow accepts images from people or systems you do not control — supplier photos, phone pictures, logos — before a delivery with technical rules (a shop, an email, a print shop), or when an image comes out sideways, too heavy, on white instead of transparent, or in the wrong format. - [Finding a subject in a picture](https://testing-docs.madoo.ai/images/finding-a-subject.md): Locate Subject finds a given subject — the one shown in reference pictures, or the one described — in a picture, and gives it cut out, ready to be judged or measured: the product among the cups of a generated tea table, the person of a campaign, a mark on a page. It finds the subject even when it was changed, because judging it is the next step's job; it tells this subject from a similar one; it gives the whole object, with a margin. What it returns, how the crop is framed, what happens when the subject is missing, ambiguous, small or cut, which models it runs on and what they cost, and how to judge or measure the crop; people (portrait and role, a judge on features, skin and hair, responsible use); a lab on a coffee pot among cups. Read when: When a step must look at one subject inside a larger picture — judge whether a generated scene kept the product, check a person or a logo, measure the colour of a product in a lifestyle shot — and the picture holds other things that must not count. Read it before writing the body of a Repeat Until Accepted step that compares a scene with the real product. - [Finding and framing faces](https://testing-docs.madoo.ai/images/finding-and-framing-faces.md): Face Detect finds the faces of a picture with a local model — score, box and six points of each — and frames a crop region around the main one: the face, the head, or head and shoulders, square, 4:5 or 9:16, always inside the picture, ready for Crop. Free, on Madoo's workers; it locates faces and identifies no one. Shown on real pictures: a portrait in a café made a 512 × 512 profile photo, a full-length shot cut in three formats, a painting, an astronaut, a dog with no face; with recipes for profile photos, story formats, requiring a face and measuring its tone. Read when: When a workflow must crop pictures around a face — profile photos, avatars, author and team portraits, a head shot from a full-length photo — or know whether a picture shows a face, how many and where. - [Finding people and objects](https://testing-docs.madoo.ai/images/finding-people-and-objects.md): Instance Segment finds the people, animals and everyday objects of a picture — the 80 COCO categories — with a local model and gives each one its class, score, box and mask: a count to decide on, a mask to measure only the person, a box to crop. Free, on Madoo's workers. Shown on real pictures: a hotel room, a dog, an armchair, a model, a teapot it calls a vase, a rocket and a jacket it does not know, a portrait with three people behind, the boats on a lake; with recipes for requiring a subject, measuring inside it and cropping it. Read when: When a workflow must know whether a person, an animal or an object is in a picture, how many and where, measure the subject apart from its surroundings, or crop it — and the picture shows a scene, not a product on a backdrop. - [Geometry](https://testing-docs.madoo.ai/images/geometry.md): How Madoo sizes, cuts and frames images without AI: the four resize modes (fit, fill, stretch, pad) and what each keeps or cuts; exact crops and automatic trimming; a product centred on a canvas with a margin, as marketplaces ask; extending, rounding, rotating, mirroring and straightening; the ten platform sizes and why they always crop; units in pixels, percent, inches, centimetres and millimetres; and a lab that makes one product ready for every channel. Read when: When images must reach an exact size or proportion — a marketplace square, a story, an email header, a link preview, a print format — when a product must be centred with a margin, or when a resized image comes out cut, stretched, blurred or with bands you did not expect. - [How AI image steps work](https://testing-docs.madoo.ai/images/how-ai-steps-work.md): What happens when a workflow asks a model for a picture: the node, its default model and the others you can choose, the model's own settings and which setting wins, presets, effects and the prompt the node composes, which input images reach the model and in what form, variants, and how the price is known before the run, held and charged — with a lab that runs one prompt on three models and settings and two edits, estimate and charge side by side. Read when: Before the first AI image step of a workflow; when choosing a model or a setting that changes the price; when a preset, an effect or a prompt does not seem to reach the result; when variants fail, or a step costs more or less than expected. - [Layouts, batches and codes](https://testing-docs.madoo.ai/images/layouts-and-codes.md): How Madoo puts several images into one — a stack, a grid, a collage in a row, a column or a grid on a fixed canvas — how the same image steps run over a whole batch of pictures with an iteration, when a document template is the better layout tool, and how QR codes and EAN-13 or Code 128 barcodes are drawn as SVG and PNG in the brand's colours, with a logo, and proved to scan before they are returned. Read when: When several product pictures must become one — a contact sheet, a banner strip, a before-and-after — when the same processing must run on every photo of a catalogue, or when a label, a packaging, a flyer or a badge needs a QR code or a barcode that must scan. - [Magic Box](https://testing-docs.madoo.ai/images/magic-box.md): Product Magic Box takes one product photo and invents the picture — the scene, the light, the story — without being told what to make: every variant is a different idea, a new run on the same photo goes somewhere new, and the product stays exactly as it is. Its three settings (creativity, mood, variants), what it costs and how long it takes, when to prefer it to the controlled product nodes, and a lab on two museum-shop objects. Read when: When a shop, a brand or a campaign wants pictures nobody briefed — to find a direction, to refresh a catalogue, to have something unexpected to post — from a product photo alone, and when choosing between Magic Box and the product nodes whose result you set in advance. - [Measuring fine detail](https://testing-docs.madoo.ai/images/measuring-fine-detail.md): Image Detail measures the fine detail of a picture on small patches at full resolution — the gradient, the residual spread at two scales and how neighbouring residuals correlate, for the whole picture and per tone band, optionally only inside a mask — and chooses where to look closely: the flattest patch, the most detailed one, a bright detailed one, each with a rectangle ready for Crop. Deterministic and free. Shown on real pictures: a linen jacket and five ways of losing or adding detail (blur, a 2× enlargement, heavy JPEG, noise, sharpening), a jacket and a dress measured inside their cut-out, a patterned teapot and a painting with nothing flat to read; with recipes for a closer look by a vision model and a check against a reference. Read when: When a workflow must tell whether a picture kept its fine detail — a generated or edited picture against its reference, an upscale, a re-compressed file, a smoothed or sharpened photo — or must pick the area of a picture to look at closely and hand it to Crop and to a vision model at full size. - [Measuring the subject](https://testing-docs.madoo.ai/images/measuring-the-subject.md): Measure Subject reads a cut-out's transparency or a black-and-white mask and reports where the subject of an image is and how big it is — bounding box, area, coverage, centroid, the edges it touches, the width of bands along it and a profile — for the whole image, every cell of a grid or given rectangles; with a quality check for the Quality Gate. A line's length can be every subject pixel, the span from the first to the last, or the longest unbroken run — the main body without detached parts. Deterministic and free. Shown on real pictures: a product framed for a catalogue, a sheet of generated variants with its failed cells, one band measured across four versions of the same object, a statue's torso without its arms, an amphora and a jug with their handles, plus recipes for approving photos, filtering a list, comparing proportions and checking room for a badge. Read when: When a workflow must know where the subject of a picture is or how big it is — a product that must fill the frame without being cut off, a grid of generated variants where some cells may be empty or wrong, a list of photos to keep or drop by how much of the frame the subject fills, room left for a price or a badge, the proportions of a figure compared across images, the width of a body without the arms or the handle beside it, the outer size an object with handles takes — and the answer must not depend on an AI model. - [Measuring tone and colour](https://testing-docs.madoo.ai/images/measuring-tone-and-colour.md): Image Statistics measures how bright or dark a picture is and how its tones and colours are spread — brightness quantiles, the share of near-black and near-white pixels, luminance, the mean colour and the colour of each tone band — for the whole picture, a grid of cells or given regions, optionally only inside a mask. Deterministic and free. Shown on real pictures: one room photo at three exposures, packshots on white and on grey, a pool and a villa in a 3 × 3 grid, Vermeer, Apollo 11 and a dress measured inside their cut-out; with recipes for exposure gates, white backdrops, darker areas and subjects. Read when: When a workflow must know whether a picture is too dark, too bright or blown out, whether a packshot sits on a white backdrop, which area of a picture is darker, or how bright the subject is apart from its background — and the answer must be a number that is exact, repeatable and free, not a guess from an AI model. - [People and fashion](https://testing-docs.madoo.ai/images/people-and-fashion.md): Virtual Try-On puts a garment photographed flat on a person, keeping the face and the body: 15 poses, 41 settings, a background or a pose taken from a picture, a design on the garment rendered as embroidery or print, up to four variants; how the pictures are ordered and which one wins, the model it needs, and how the look goes on to a fashion clip — with a lab that dresses one model in one jacket in two places and three poses. Read when: When a fashion shop, a brand or a catalogue must show garments worn without a photo shoot — one model in many garments, one garment on many models, the same look in several settings — or when a try-on changes the person, ignores the pose or does not keep the garment. - [Product imagery](https://testing-docs.madoo.ai/images/product-imagery.md): The AI nodes built for products: a studio packshot with surface, light and angle; a lifestyle scene; a piece of furniture placed in a room; a background replaced; a product remade in another material or colour; an advertisement with title, call to action and the brand's mark in the format of each channel; a picture turned into a painting style. What each node keeps and what it changes, its presets and inputs, what the reference images are for, and a lab on a museum-shop collection. Read when: When a shop, a marketplace or a campaign needs pictures of a real product that was photographed once — on a clean background, in a scene, in a room, in other colours or materials, as an ad — and the product must stay exactly itself. - [Generating and editing with a prompt](https://testing-docs.madoo.ai/images/prompt-generation.md): The general-purpose AI image nodes: Text to Image makes a picture from words, with presets for style, mood, quality and frame and a choice of models from 1 to 15 credits — one of them draws real SVG vectors; Image Transform edits or combines up to 14 pictures with an instruction; Image Fusion composes up to five products with a layout; and the vision nodes read pictures back as text — Image Analysis describes them in prose or JSON, Image Classifier sorts them, Image to Prompt writes the prompt that would make them. How to write the instruction, and a lab that uses all of them. Read when: When a workflow must make a picture from a description, change or combine pictures with an instruction, put several products into one image, or read pictures — to describe, tag, sort or check them — and when choosing the model and the words for it. - [Troubleshooting images](https://testing-docs.madoo.ai/images/troubleshooting.md): What to do when an image workflow does not give what you expected: a step stopped before any charge (MODEL_TAKES_ONE_IMAGE, MODEL_ONE_IMAGE_PER_CALL, UPSCALE_FACTOR_NOT_SUPPORTED), a picture in the wrong frame or size, a product the model redrew, text misspelled or painted where it should not be, an effect on the whole product, a logo that covers everything, a transparent picture that turns black or white, variants that look alike, a price different from the estimate — symptom, cause and fix, with links to the pages that explain each. Read when: When an image step fails, stops before running, or returns a picture that is not the one you wanted — before changing the workflow at random. - [I01 — One product photo, a launch kit for every channel](https://testing-docs.madoo.ai/images/examples/i01-launch-kit.md): One photo of a perfume bottle becomes a launch kit in one run: a pure-white marketplace image checked against the marketplace's rules, a signed studio hero shot, an Instagram post with name and price in the brand's fonts, a story ad whose headline, line and button are written by GPT Image 2, a surprise picture as a Facebook banner, and a contact sheet. The engine is a Sub-workflow: the same engine, unchanged, made a second product's kit. About 26 credits per product; installable. Read when: When a shop, a brand or an agency launches products on several channels at once — marketplace, website, Instagram, Facebook — and wants every picture from one product photo, the exact parts deterministic and the invented parts AI; or to see how a long workflow becomes an engine that many workflows reuse. - [I02 — An empty room, staged, at dusk, and listed](https://testing-docs.madoo.ai/images/examples/i02-staged-listing.md): An estate agent's photo of an empty room becomes a listing in one run: the room furnished with an armchair and a vase while the photograph stays exactly as taken, the same room again at dusk with the fire and lamps lit, and the listing pack — the photo with headline, price and agency mark, a before-and-after, a flyer with a QR code to the listing that is read back before delivery, and a social post. 10 credits; installable. Read when: When an agency, a hotel, a rental or a furniture brand must show a space furnished and at its best from a plain photo — and must not change the space itself; or to see how a few AI steps and a deterministic layout make a complete, honest marketing pack. - [I03 — Four press photos, a carousel ready to post](https://testing-docs.madoo.ai/images/examples/i03-event-carousel.md): Four press photos of a rocket launch become an Instagram carousel in one run: a vintage-poster cover whose title and line GPT Image 2 writes, placed whole on the first slide; four slides with one house look at 1080 × 1350, numbered and signed; and the words — alt texts for screen readers, captions in English and Italian, the post and its hashtags — read from the pictures by a vision model, as JSON. About 10 credits; installable. Read when: When a newsroom, a magazine, a club, a school or a brand must turn the photos of an event into a ready-to-post carousel — cover, slides and words — the same day, in its own look, accessible and in two languages. - [I04 — Three garments, one model, one set: a lookbook with shop codes](https://testing-docs.madoo.ai/images/examples/i04-lookbook.md): Three garments photographed flat are worn by one model, each in a pose of its own and styled as said per garment, photographed in one set made for the collection as in a real shoot there; every look becomes a card with its name and price in the brand's font and a QR code to its product page, read back before delivery; the three cards make the lookbook page. 20 credits; installable. Read when: When a fashion brand, a boutique or a marketplace seller must show a collection worn — consistently, in one place, by one person — without a shoot, and link each piece to its shop page from print or screen. - [I05 — Your pet as an old-master portrait: print, post, wallpaper and sticker](https://testing-docs.madoo.ai/images/examples/i05-pet-portrait.md): A garden photo of a dog becomes a seventeenth-century noble portrait in the manner of a Velázquez — lace collar, velvet doublet, craquelure — with the dog itself kept exactly; enlarged four times, it is delivered as a 30 × 40 cm CMYK print with a name plaque, a framed square post, a phone wallpaper, and a sticker of the real dog. 11 credits; installable. Read when: When a pet shop, a print studio, a gift service or anyone at home wants a portrait that makes people smile — from a phone photo to a print ready for the framer — or to see how a style reference and deterministic print steps work together. - [I06 — A name, three personalised gifts and the proof](https://testing-docs.madoo.ai/images/examples/i06-personalised-gifts.md): A customer types a name; the workflow sets it in the shop's script exactly where each gift will carry it — a tote bag, a leather notebook, a cutting board — and shows each as it will be made: embroidered, stamped in gold foil, burnt into the wood. The proof sheet goes to the customer for approval, the order in JSON to the workshop. 15 credits; installable. Read when: When a gift shop, a merchandise printer or a corporate-gifts service sells personalised products and must show each customer their name on the real product before making it — the spelling exact, the finish believable — and hand the workshop a clean order. - [I07 — A hotel's photos screened for a booking portal: the good ones sized, the others with the reason](https://testing-docs.madoo.ai/images/examples/i07-listing-photos.md): A hotel sends its photos for a booking portal; the workflow measures every photo — size, exposure, sharpness, people in the picture —, cuts the ones that pass every check to the portal's 1280 × 720 and writes, for every photo, a line with the numbers and, for the others, the reason in words. The same verdicts an AI judgement gave on these photos, from measurements, at no credit cost; installable. Read when: When photos must be checked before they are published — a portal's rules, a brand's standards, a batch from a photographer or from users — and every rejection must come with a reason someone can act on, without paying a model to look at each picture. - [I08 — A team page from whatever photos people send: the same head shot for everyone](https://testing-docs.madoo.ai/images/examples/i08-crew-page.md): Six people send a photo for the team page, each taken a different way — and one sends a logo. Face Detect frames the same square head shot around every face, a Quality Gate stops the picture without one, Image Statistics measures the tone inside each face, and a template lays out the page; the person without a face is listed to be asked for a portrait. Shown on the official portraits of Apollo 11's prime and backup crews. No AI step, no credits; installable. Read when: When a team page, a speakers' page, a staff directory or an author list must show everyone the same way, from photos people sent in any framing — and someone must be told which photos will not do. - [I09 — Two generated packshots checked against the real product before they are published](https://testing-docs.madoo.ai/images/examples/i09-packshot-check.md): From one photo of a jacket an AI step makes a studio packshot and a warm mood shot. Before either is published, the jacket alone — cut out of each picture — is measured against the real one: colour shift, change of light, texture kept. The studio shot is released; the warm one, whose jacket came out more orange, is held back with its numbers. 13 credits; installable. Read when: When generated product pictures must be checked before they go live — the colour of the product is what the customer buys — and the check must be a number that holds every time, not a second model's impression. - [I10 — A catalogue in the brand colours: every picture measured, corrected and tried again until it is on brand](https://testing-docs.madoo.ai/images/examples/i10-brand-catalogue.md): Three products of a Delft collection, each photographed by Lifestyle in a cosy autumn scene. Every picture is measured against the brand colours — navy, a lighter navy, cream, ochre — by Color Palette, with no model; a picture off the palette is made again with the measured violations as its correction, at most three times per product. One Repeat Until Accepted per product, in one run: the warm first pictures became navy and cream, the products untouched. 40 credits for three products in the reference run (45 at most); installable. Read when: When a series of generated pictures must keep to a brand's colours — a catalogue, a campaign, a season — and a picture that does not should be made again with a precise correction, not just thrown away. Also the reference for a judge that is a measurement, and for Repeat Until Accepted run once per item. - [I11 — A product placed in a scene, judged against the real one until it is faithful](https://testing-docs.madoo.ai/images/examples/i11-faithful-scene.md): A sixteenth-century pharmacy jar — a helmeted portrait, ornaments, the lettering “S. amomi” — placed by Lifestyle on the marble counter of an old pharmacy, seen from above at three-quarters, another jar on the shelf beside it. Locate Subject finds this jar in each picture, and Decide with a Model compares only its crop with the museum photo, on what a change of viewpoint cannot explain — decoration, figure, colours, lettering letter for letter — and Image Analysis, told the verdict, writes what to correct; the picture is made again until it is faithful, at most three times. Accepted at the first attempt in the reference run: 5 credits of the 17 reserved. With the judging mistakes that were made on the way, and how they were fixed; installable. Read when: When a generated picture must show exactly the real product — its decoration, its print, its label — in a new scene, and a model must judge it. Read it before writing the judge of a Repeat Until Accepted body that compares a picture with a reference. - [I12 — The same model across a campaign: every picture checked against her portrait](https://testing-docs.madoo.ai/images/examples/i12-campaign-model.md): An autumn coat campaign in three scenes — a café terrace, a city square at dusk, an art gallery — with the brand's model, a character made with Madoo. In every scene Image Transform puts her among other people; Locate Subject finds her from her portrait and her role in the scene; Face Detect frames her face and the reference face; Image Analysis rates how well the face keeps the features, the skin and the hair, and names what differs, which becomes the correction of the next attempt. One Repeat Until Accepted per scene. All three accepted at the first attempt, 15 credits; with the measurement of the judge on ten faces, faithful and changed, and what it does not do. Read when: When the same person — a brand's model, a mascot played by a character, a recurring figure of a series — must look the same in every generated picture, and each picture should be checked before it is used. Read it before writing a judge that compares a person in a scene with a portrait. ### Video and audio - [Video and audio](https://testing-docs.madoo.ai/media.md): How Madoo works with video and audio: media travel between nodes as stored files; editing, mixing, loudness, captions and typography run locally at no credit cost, while generating, transcribing, translating and voicing are paid AI steps; how long and how large a media file can be; and how every step measures what it produced. Read when: Before building a workflow that edits, captions, dubs, finishes or generates video or audio — a social clip, a subtitled video, a localized version, a podcast, a voice-over — or when a media step fails on size, duration or format. - [Audio finishing](https://testing-docs.madoo.ai/media/audio-finishing.md): The local audio finishing nodes that turn raw speech and music into a delivery: cleaning a voice, levelling it, fitting music to the length of the programme, lowering it under every phrase, normalizing the mix to a platform's loudness, fitting a clip to an exact slot, and measuring the result so that a gate delivers only audio that meets the target — with the order that works and the lab that shows the difference. Read when: When a workflow produces or receives spoken audio — a voice-over, a podcast, an interview, a narration, a dub — and must deliver it at a known loudness, over music, clean and without clipping; or when a platform rejects audio for being too quiet, too loud or peaking. - [Building a dub from its blocks](https://testing-docs.madoo.ai/media/building-a-dub.md): How to assemble a dubbing workflow node by node, from the quickest dub — one pass, the voice fitted by tempo — to the natural-speech engine: the plan, a round and its eight nodes wired port by port, the final reconcile and the dialogue timeline, one voice per speaker, the optional background and subtitles, the engine as a sub-workflow; the wiring rules the validator enforces (NATURAL_SPEECH_WIRING), and every setting worth changing with what it does. Read when: When building or changing a dubbing workflow instead of installing the ready one: fewer rounds or a quicker dub for short clips, a different voice model or cast, more room for the lines, no background; or when validation reports NATURAL_SPEECH_WIRING. - [Dubbing with natural speech](https://testing-docs.madoo.ai/media/dubbing.md): How Madoo dubs a video into another language so that the new voices sound natural and stay on the picture: the ideas behind it (a window for every line, the words adapted rather than the voice sped up, every take measured, up to three rounds, one voice per speaker, the original background kept, deliver first and report everything), the engine phase by phase with its diagrams — listen, translate, fit the speech, rebuild the soundtrack, deliver and account — the quality checks and what each one proves, and the ready workflow that takes a video and a language and returns the dubbed video, subtitles, a manifest and a quality report. Read when: Before dubbing a video — an interview, a briefing, a course, a product video, a testimonial — into another language; to understand why a dubbed line was reworded, sped up or flagged; or before changing the dubbing engine or building one from its blocks. - [Dubbing: quality, costs and limits](https://testing-docs.madoo.ai/media/dubbing-quality.md): How to check a dub and what its numbers mean — the order to review it in, the quality report and the manifest line by line, the rounds' history, how much results vary from run to run and how to reduce quick lines; what a dub costs per minute of video by language and by step, and how long it takes; the limits worth knowing — speaker identity, one-word lines, overlapping speech, lips, background separation, the inferred kind of voice, provider quotas — and every warning and error code with what to do. Read when: Before promising a dub to a client — its cost per minute, its time, what it can and cannot do — and after a run, to read its quality report, to understand a warning or an error, or to decide whether a line needs a person. - [Editing video](https://testing-docs.madoo.ai/media/editing-video.md): The local video editing nodes: cutting by time and splitting, speed and speed ramps, joining clips with transitions, reframing for 9:16, 1:1 and 16:9, a logo or badge over the picture, a soundtrack mixed or replaced, a still frame, a GIF — what each does, what it accepts, and the lab that turns a landscape interview into a vertical reel at no cost. Read when: When a workflow must cut, join, reframe, brand or put sound on video — a reel from an interview, a product clip for three platforms, a trailer from several shots — or when one of these steps fails on a clip it was given. - [Video and audio — examples](https://testing-docs.madoo.ai/media/examples.md): Complete, installable workflows that put the techniques of Video and audio to work on real jobs: a briefing dubbed into another language with natural speech and one voice per speaker, and a screen recording finished for publishing with a cleaned voice, AI-written music and word-highlight subtitles — AI where listening, translating and voicing need it, measured and deterministic nodes for timing, mixing, loudness and delivery. Read when: When you want to see how transcription, translation, voices, timing, mixing and quality checks combine in a real media workflow, or to install one as a starting point. - [Media files and preflight](https://testing-docs.madoo.ai/media/files-and-preflight.md): How video and audio files get into a workflow and out of it — uploads, imports from a URL, runtime inputs, formats and size — and how Media Technical Info measures what a file really is (kind, size, duration, resolution, frame rate, codecs, streams) and checks it against a media policy, so a Quality Gate can hold back a clip that is not ready before anything is spent or published. Read when: Before a workflow accepts media from people or systems you do not control, before a paid step that expects a certain kind of file, and before a delivery with technical requirements — a Reel, a broadcast file, a podcast. - [Finding the scenes of a video](https://testing-docs.madoo.ai/media/finding-scenes.md): How Extract Scenes finds where the scenes of a video start and end — the change score frame by frame, the threshold, black gaps, short scenes and the jump cuts Subtle Cuts adds — takes a frame of each (one per scene, one every few seconds, or both), and returns the scene list (madoo.video-scenes/v1), the frames as an image set (madoo.image-set/v1) and a contact sheet, deterministically and at no credit cost. How to use the frames: an image model that reads a video through them, one step per scene, a storyboard, a cover, the pacing of an edit. Settings by kind of footage, limits (dissolves, camera moves), errors, and three labs on real footage. Read when: When a workflow needs to know what is in a video shot by shot — a summary or chapters from a model that sees images but not video, a storyboard, a cover or thumbnail chosen among the shots, the pacing of an edit, a check of every scene — or when a scene list has too many or too few scenes. - [Generative video and sound](https://testing-docs.madoo.ai/media/generative.md): How Madoo generates video, music, sound effects and sound for a clip with AI models: what each generative node makes, which model it uses by default and what it costs; how to choose another model and its settings; how the price is known before the run, held, and settled — exact or measured at dispatch; how a generation runs as a provider job and is stored in Madoo; how to fit, mix, level and measure the result locally at no credit cost; the limits; and a lab that brings a painting to life with its own sound. Read when: When a workflow must make a video from a prompt or an image, extend, restyle or upscale a clip, write music, make a sound effect or the sound for a silent clip; when choosing a generative model or its settings; or when a generation costs more than expected, fails, or does not look as asked. - [Subjects, continuations and fashion clips](https://testing-docs.madoo.ai/media/generative-shots.md): Three generative techniques beyond a single clip: keeping the same character and product across shots with Reference to Video and its @Image references; continuing a clip with Video Extend and joining it without a seam; and turning a flat product photo into a fashion clip with Virtual Try-On and Fashion Video. Which images each node really sends to its model, the limits and refusals, what each costs, and a lab for each. Read when: When a brand's mascot, a character or a product must look the same in several shots; when a clip must go on for a few more seconds; when a garment, shoes, a bag or jewellery must be shown worn and in motion; or when reference images, a last frame or a try-on do not seem to reach the model. - [Highlights](https://testing-docs.madoo.ai/media/highlights.md): How Madoo turns a long video into a short one of its best moments: an AI watches the video segment by segment and proposes moments with a score and a reason; a deterministic plan chooses them within a time budget, drops overlaps and snaps every cut to the end of a sentence; the master is cut once with hard cuts, measured; and the captions are moved onto the edit. The four steps, their settings and warnings, how to shape the result, what it costs, and a lab that cuts a six-minute briefing to under a minute. Read when: When a long video — an interview, a talk, a webinar, a briefing, a product demo — must become a short one for social media, a trailer or a recap; or when a highlight comes out too short, with cuts in the middle of a sentence, or without the moments you expected. - [Long media](https://testing-docs.madoo.ai/media/long-media.md): How Madoo works on long video and audio — an interview, a lecture, a webinar, a call of an hour: which steps take the whole master and which need it cut, the choice between one pass and segments for a transcription (speaker identity, billing, time), how Audio Segments and Video Segments cut at pauses with overlap, how the steps run side by side, how the aggregators put the pieces back on the master's timeline, several split-and-join stages in one workflow, the limits and traps, and a lab that transcribes the same six-minute briefing both ways. Read when: Before building a workflow for a recording longer than a few minutes, when a step fails on duration or size, when speakers change numbers halfway through a transcript, or when deciding whether and how to cut a long video or audio into segments. - [Transcription and captions](https://testing-docs.madoo.ai/media/transcription-and-captions.md): From speech to captions: transcribing with word timing and choosing the model, what SRT and WebVTT caption files are and when to use them instead of captions burned into the picture, the three ways of showing captions — readable phrases, one word, the spoken word highlighted — and the typography that decides how they look, with two labs: a captioned vertical reel, and a landscape interview for a vertical feed with a title above and captions below. Read when: When a video must carry what is said in it — captions for social clips watched without sound, subtitles for accessibility, a caption file for YouTube or a web player — or when captions come out too small, in the wrong place, one word at a time, or not at all. - [Translating captions](https://testing-docs.madoo.ai/media/translating-captions.md): Captions in other languages, on the original timing: how Madoo translates timed captions line by line without touching the timing, the short path for clips and reels and the segmented path for long recordings, several languages from one transcript, glossaries, the deliver-first policy with a repair round, and the three ways to deliver — selectable tracks beside the untouched video, subtitles burned into the picture, SRT and WebVTT files — with what it costs in credits and two labs: a reel in three languages and a three-speaker interview. Read when: When a video must be understood in another language without being dubbed — subtitles for a market, a course or a campaign in several languages, a player where the viewer chooses the language — or when translated captions lose their timing, split a sentence badly or come back in the source language. - [Troubleshooting video and audio](https://testing-docs.madoo.ai/media/troubleshooting.md): What to do when a video or audio workflow is refused, fails, completes partially, or delivers something that looks or sounds wrong — organised by symptom: where to read the reason, refusals at validation and submit, failed steps by code and the page that explains them, provider and credit failures, files too large or unreadable, runs that are slow, and results with the wrong loudness, timing, voices, captions or motion. Read when: When a media workflow is rejected when saved, refused when run, stops at a step, ends as a partial success, takes much longer than expected, or completes with a clip, a sound, a caption or a dub that is not right. - [Typography on video](https://testing-docs.madoo.ai/media/typography.md): Text drawn into video — titles, lower thirds, prices, quotes, calls to action — with exact fonts: the system fonts and a workspace's own, how a workflow pins them so the letters never change, the Text on Video node with one text or many timed layers in a single render, the Text Style field by field, the presets, recipes for the usual placements, and a lab that puts five layers with four looks on a reel. Read when: When a video must carry text that is not a transcript — a title card, the name of who is speaking, a price, a quote, a call to action, a brand's own typeface — or when text on video comes out in the wrong font, size or place, or does not fit. - [W01 — A briefing dubbed into another language, one voice per speaker](https://testing-docs.madoo.ai/media/examples/w01-dubbed-briefing.md): Six minutes of NASA interviews with four people — the Administrator and three astronauts — dubbed into Italian with natural speech: one transcription with the speakers, a voice cast per speaker by listening to each of them, the translation adapted and voiced in up to three rounds until each line fits its moment, the music and ambience kept, subtitles in both languages, a manifest and a quality report. The target language is an input; installable, engine included. Read when: When a video with several people speaking — an interview, a briefing, a panel, a training video, a testimonial — must be delivered in another language with voices rather than subtitles, or to see the dubbing engine at work on a real recording before building on it. - [W02 — A screen recording, finished for publishing](https://testing-docs.madoo.ai/media/examples/w02-screen-recording-finish.md): A one-minute product walkthrough recorded with a laptop microphone, finished for publishing: the voice cleaned and levelled, an instrumental bed written by an AI that watches the video, generated, fitted to the exact length and ducked under the voice, the programme levelled to −14 LUFS, subtitles that highlight each spoken word with an SRT, and a delivery report that never holds the video back. Every stage is its own output; installable; about 3 credits for a one-minute recording. Read when: When a screen recording, a software demo, a tutorial or an internal walkthrough must look and sound finished before it is published — a cleaner voice, music under it, the right loudness, subtitles — or to see voice cleaning, AI-written music, ducking and word-highlight captions working together on one job. - [W03 — A long recording, finished for publishing](https://testing-docs.madoo.ai/media/examples/w03-long-recording-finish.md): The finish of W02 set for recordings of half an hour to two hours: the voice cleaned and levelled on the whole master, the music brief written from a three-minute excerpt, a three-minute bed looped with long crossfades, the transcription cut into segments that stay under ten billed minutes and rejoined on one timeline, one narrator without speaker labels, block subtitles and an SRT, a two-hour media policy. Rehearsed on a two-and-a-half-minute walkthrough with the long paths forced: three segments rejoined, loop joins every 57 seconds, a brief from the first minute. Installable; about 4 credits plus 0.5 per minute of recording. Read when: When a long screen recording, a webinar, a lecture, a training session or a product demo of many minutes must be finished for publishing — cleaner voice, music, loudness, subtitles — or to see how a short-video workflow is adapted to long media, and how to rehearse it cheaply before the first long run. ### Document templates - [Document templates](https://testing-docs.madoo.ai/templates.md): What a Madoo document template is, how it turns data into PDF pages or images, how it connects to workflows, and which page of this guide to read for your task. Read when: Before creating, changing or using any document template — brochures, product sheets, price lists, certificates, posters, proposals, social images. - [Designing a template](https://testing-docs.madoo.ai/templates/designing.md): How to design a template that looks professional and survives real data — purpose and hierarchy, page grid, typography, color, images, designing for variable content, and the render-and-review loop, with the choices the Madoo examples make. Read when: Before creating a new template or redesigning one — read it before writing the document, not after. - [The document model](https://testing-docs.madoo.ai/templates/document-model.md): The structure of a Madoo template as one JSON document (madoo.design-document/2.0) — pages, master pages, elements and containers, coordinates, identifiers, limits and validation. Read when: Before writing or reading a whole template document, and whenever a document is rejected with a JSON path. - [Fields and data](https://testing-docs.madoo.ai/templates/fields-and-data.md): How a template receives data — fields and their types, codes, required values and defaults, lists of items, number formats, yes/no and color fields, conditions, links, the published contract and sample sets. Read when: When deciding which parts of a template change from one document to the next, when preparing the data for a render, and when a render fails because of a missing or wrong value. - [Examples](https://testing-docs.madoo.ai/templates/gallery.md): Complete, installable Madoo examples — templates and workflows that fill them with AI copy and verified data, each with its design, its nodes explained, its results, and a one-command install into your workspace. Read when: When you want a working reference to start from, to see a technique applied to a real case, or to install a complete template and workflow into a workspace. - [Templates in workflows](https://testing-docs.madoo.ai/templates/in-workflows.md): How workflows fill document templates — choosing between Render Document Template, Generate PDF and Multi-page PDF; connecting data objects, field inputs and assets; keeping AI copy and verified facts apart; computing amounts; validating AI copy against the page; one document per item or one PDF for a whole list; pinning revisions; and reading the layout report. Read when: When building or changing a workflow that produces a PDF or page images from a template, and when choosing how the data reaches the template. - [The template lifecycle](https://testing-docs.madoo.ai/templates/lifecycle.md): From draft to production — the editable draft and its ETag, sample sets, exact previews, publish readiness, immutable revisions and their contracts, how workflows pin and move revisions, duplicating, archiving, and sharing a template with other workspaces (fonts included). Read when: Before publishing a template, before changing a template that workflows already use, and when sharing a template or moving it between workspaces. - [Troubleshooting templates](https://testing-docs.madoo.ai/templates/troubleshooting.md): What to do when a Madoo template is rejected, a render fails or the page does not look right — organised by symptom, with the DESIGN_* codes, their causes and their fixes, and how to read the layout report. Read when: When saving a template document is rejected, a preview or a workflow render fails, a readiness check blocks publication, or the printed page differs from what was expected. - [F01 — B2B one-page proposal](https://testing-docs.madoo.ai/templates/gallery/f01-b2b-proposal.md): A one-page A4 commercial proposal from a salesperson's brief — AI copy validated against the page, an AI cover photograph, approved claims printed verbatim with their source, a formatted price and an optional client logo. Installable. Read when: When building a document that mixes AI-written copy with facts that must not be rewritten — proposals, quotes, offers — or when you want a complete, working reference of Render Document Template. - [F02 — Hotel campaign brochure in two languages](https://testing-docs.madoo.ai/templates/gallery/f02-hotel-brochure.md): A four-page A4 hotel brochure in Italian and English from one template — AI copy in two languages validated in one call, the verified offer as a second data object the AI never sees, the hotel's own summer photo brought into the campaign season, master pages and print-ready PDF/X-4. Installable. Read when: When one template must produce the same document in several languages, when AI copy and verified commercial terms must reach the page separately, or when you need a multi-page, print-ready document with page images for the web. - [F03 — Variable product flyer](https://testing-docs.madoo.ai/templates/gallery/f03-product-flyer.md): An A4 product flyer for any selection of up to nine catalogue products — an AI header with copy and an atmosphere photograph, product cards that print names, prices, sales and stock exactly as the store has them, stock badges from numeric conditions, clickable cards and an empty state. Installable. Read when: When a document must react to catalogue data — a variable number of items, badges that depend on values, prices formatted by the template, links built per item — or when you need a PDF and a shareable image from one render. - [F04 — Visual summary of a book](https://testing-docs.madoo.ai/templates/gallery/f04-visual-summary.md): A one-page visual summary of a book from its summary — the idea in one sentence, the argument in three steps, four to six key ideas and three actions written by the AI and validated with JSON Schema, the facts of the work as a second data object that wins over the AI, an AI illustration, and a page whose height follows its content. Installable. Read when: When a document must turn a text into a structure that fits a page, when verified facts must override anything a model writes, or when a variable list sits in the middle of a page with more content below it. - [F04B — Illustrated summary](https://testing-docs.madoo.ai/templates/gallery/f04b-illustrated-summary.md): The illustrated edition of the F04 visual summary — every key idea gets its own small picture, generated in parallel with the main illustration as style reference, then joined back to its idea before layout. Installable. Read when: When a document needs one AI image per item of a list, all in the same style, collected back into one page — or when you want a working reference of enumerate/json, ai/image_transform with a style reference and aggregate/json feeding Render Document Template. - [F05 — Wine price list from a spreadsheet](https://testing-docs.madoo.ai/templates/gallery/f05-wine-price-list.md): A multi-page wine price list from the winery's Excel export — one AI description per row validated with JSON Schema, prices, vintages and stock printed exactly as in the sheet and formatted per language, a card grid that continues on new pages under a master page. Installable. Read when: When a document is built from a spreadsheet or a data export with one AI text per row — catalogues, price lists, product sheets — or when you want a working reference of input/data, enumerate/data_rows and a list that continues on new pages. - [F06 — Proposal with the customer's photo](https://testing-docs.madoo.ai/templates/gallery/f06-terrace-proposal.md): A two-page personalised proposal from a plant nursery — the customer's own terrace photo with the chosen plants placed on it by AI and declared as a simulation, validated copy, plants and prices from the management system on a second data object, a table that follows its rows and a confirmation link. Installable. Read when: When a proposal or quote should show the product in the customer's own space, or when AI imagery and AI copy must sit next to prices that must not change — furniture, awnings, flooring, lighting, gardens. - [F07 — Property listing from a photo bundle](https://testing-docs.madoo.ai/templates/gallery/f07-property-listing.md): A property listing from a verified photo bundle — an AI judgement of every photo, a gallery of the publishable ones only, the cover chosen in the bundle, facts only from the agency's sheet, and a two-page A4 sheet plus a 4:5 social post from one template. Installable. Read when: When a set of photos must be screened before it reaches a document, when you need to keep only some rows of a list inside a workflow, or when one template must produce two products (a PDF and a social image). - [F08 — Course poster in a brand font](https://testing-docs.madoo.ai/templates/gallery/f08-brand-font-poster.md): A course poster set in a private brand font (Righteous, SIL Open Font License), shared from the head office's workspace to a school's workspace together with the font, and produced by both with the same look. Installable. Read when: When a template uses a font that is not built into Madoo, when a template or workflow must be shared with another workspace without losing its typography, or when you want a small, working reference of AI copy plus verified facts on a poster. - [F09 — Poster built by an agent through MCP](https://testing-docs.madoo.ai/templates/gallery/f09-agent-built-poster.md): An event programme poster whose template and workflow were designed, previewed, published, run and corrected by an AI agent through the Madoo MCP server with a workspace API key, without opening the editor. Installable. Read when: When an AI agent or an integration must build a template and a workflow without the editor, when you want to see the MCP authoring sequence end to end, or when you need a poster that turns a list of events into one line per event. - [F10 — Course certificates in one PDF](https://testing-docs.madoo.ai/templates/gallery/f10-course-certificates.md): One PDF with the cover of a course register and one certificate of attendance per participant — Generate PDF for the cover, Multi-page PDF over the participants, typed field ports for numbers, yes/no and lists, no AI. Installable. Read when: When you need the same page once for every item of a list in a single PDF — certificates, badges, catalogue sheets, exhibition labels — or when you want to choose between Render Document Template, Generate PDF and Multi-page PDF. - [F11 — Restaurant menu](https://testing-docs.madoo.ai/templates/gallery/f11-restaurant-menu.md): An evening menu on one A4 page — sections with their dishes as a list inside a list, dietary tags that appear only when a dish has them, prices formatted by the template, and a chef's note written by the AI from the chef's own shorthand and validated against the page. Installable. Read when: When a document has groups of items — menus, price lists by category, programmes by day, catalogues by family — or when you want a working reference of nested lists and optional tags. - [F12 — Quote from the quoting system](https://testing-docs.madoo.ai/templates/gallery/f12-quote.md): A two-page quote — letterhead and page numbers from a master page, line items that grow with their description, totals from the quoting system with a discount and a deposit shown only when present, VAT printed as a percentage, an acceptance link, and an introduction written by the AI from the site-visit notes on a separate data object. Installable. Read when: When producing quotes, invoices, order confirmations or statements — any document with line items and totals — or when you want a working reference of two data objects (AI words on data_0, system facts on data_1). - [F13 — Event badges](https://testing-docs.madoo.ai/templates/gallery/f13-event-badges.md): One A6 badge per participant in a single PDF for the printer — the event's colour and SVG logo as fields so one template serves every event, a check-in QR code per person drawn by the QR Code node, a role band chosen by conditions, a VIP ribbon shown by a yes/no field on a whole group, and long names that shrink to fit. No AI. Installable. Read when: When producing one printed piece per person or per item — badges, name cards, tickets, labels, place cards — when every piece needs its own QR code, or when you want a working reference of colour fields, SVG image fields and yes/no visibility on groups. - [F14 — Square social carousel](https://testing-docs.madoo.ai/templates/gallery/f14-social-carousel.md): An Instagram carousel of square slides from one brief — a cover with a full-bleed photo and a veil, one slide per tip made by a list that continues on new pages, a numbering sequence for the tips, a closing slide, all the words written by the AI as validated JSON, and the slides delivered as page images. Installable. Read when: When producing social carousels, slide sets, flash cards or any document with one page per item, or when a workflow must deliver page images instead of a PDF. - [Conditions, links and number formats](https://testing-docs.madoo.ai/templates/techniques/conditions-links-formats.md): How one Madoo template becomes many variants from its data — elements shown or hidden by conditions and yes/no fields, brand colours from color fields, prices and percentages formatted per market, and clickable links built from fields. Read when: When a template must adapt to its data — badges, optional blocks, several brands or markets, prices in different languages — and when a PDF needs links. - [Flowing layouts](https://testing-docs.madoo.ai/templates/techniques/flowing-layouts.md): Layout regions in a Madoo template — vertical stacks, horizontal rows and grids whose elements move when a text grows or a block disappears; sizing to content, anchors, padding and gaps, background layers with rounded corners, alignment, and how lists and conditions behave inside them. Read when: When texts of variable length must not leave gaps or overlap what follows, when a block can be absent, when a card or caption must wrap its content, and when elements must be spaced and aligned consistently. - [Images](https://testing-docs.madoo.ai/templates/techniques/images.md): Placing photos, logos and artwork in a Madoo template — fit, fill and stretch, image fields and their alignment, frames with focal point and zoom, borders, opacity masks, veils for text on photos, SVG as an image, and full-page background images. Read when: When a template shows a photo, a logo or a background, when an image must come from data, and when a photo is cropped in the wrong place. - [Repeated lists](https://testing-docs.madoo.ai/templates/techniques/lists.md): Repeated lists in a Madoo template — one row drawn per item of a JSON list, as a column, a row or a grid; item keys, rows that grow, backgrounds that follow the row, flags read by conditions, lists inside items, empty lists, limits and what happens when the rows do not fit, up to catalogues that continue on new pages. Read when: When a template shows a variable number of things — menu dishes, products, line items, speakers, participants, opening hours — and when a render fails with DESIGN_REPEAT_OVERFLOW or DESIGN_REPEAT_LIMIT_EXCEEDED. - [Multi-page documents](https://testing-docs.madoo.ai/templates/techniques/multi-page.md): Brochures, catalogues and reports in one Madoo template — several pages, master pages with shared headers and footers, automatic odd/even masters, page numbers and numbering sequences, covers without numbers, pages that grow with lists, pages whose height follows the content, and PDF metadata. Read when: When a template has more than one page, needs headers, footers or page numbers, or must produce an image whose height follows its content. - [Print-ready PDF](https://testing-docs.madoo.ai/templates/techniques/print.md): Standard PDF or print-ready PDF/X-4 from a Madoo template — when to use which, workspace ICC profiles, exporting from the editor and from a workflow, what PDF/X-4 changes (images, links, colours), and what it does not do yet. Read when: When a document goes to a printer, when a printer asks for PDF/X-4 or a specific ICC profile, and when photos must keep their full resolution. - [Styles and components](https://testing-docs.madoo.ai/templates/techniques/styles-and-components.md): Keeping a Madoo template consistent — named text, paint and object styles that update every linked element, local overrides, styles shared between documents, and reusable components placed many times with their own texts and colours. Read when: When a template has many texts of the same kind, repeated decorative blocks (chips, badges, icon rows, signature blocks), or must be restyled quickly — and before writing styleRefs or component instances in a document. - [Text](https://testing-docs.madoo.ai/templates/techniques/text.md): Everything a text element can do in a Madoo template — fonts and weights, size, color, alignment, line height and letter spacing, mixed formatting and lists, text fields, and what happens when a value is longer than its box. Read when: When placing or styling any text in a template, when a value must fit a box, and when a render reports a text that did not fit. - [Vector shapes and SVG artwork](https://testing-docs.madoo.ai/templates/techniques/vector-artwork.md): Shapes, lines and paths in a Madoo template — fills and strokes, rounded corners, dashes, arrows, linear and radial gradients, transparency — and SVG artwork imported as editable shapes or kept whole with a recolourable palette. Everything stays vector in the PDF. Read when: When a template needs bands, cards, dividers, icons, badges, arrows, gradients or a logo in SVG, and when an SVG must be recoloured for a brand. ### Integrations - [Building an app with Lovable](https://testing-docs.madoo.ai/integrations/lovable.md): How to build a working app on Madoo with Lovable without writing code: with one Madoo API key in the project's secrets, Lovable designs and publishes the Madoo workflow from its own work area, then wires the app to run it through the REST API from server-side code. Create the key, give Lovable its project knowledge, describe the app — with a tested starter app, the rules that make the first try work, what to do when something goes wrong, and the optional MCP connector. Read when: When someone wants to build an app, a tool or a prototype on Madoo with Lovable — a hackathon, a client demo, an internal tool — and needs the exact steps, or when an agent helps them and must know how building the workflow and running it fit together. ### Public API and MCP - [Madoo Public API — Developer Guide (v1)](https://testing-docs.madoo.ai/public-api.md) - [Assets (file uploads)](https://testing-docs.madoo.ai/public-api/assets.md) - [Authentication](https://testing-docs.madoo.ai/public-api/authentication.md) - [Workflow authoring (create, update, validate, lifecycle — headless)](https://testing-docs.madoo.ai/public-api/authoring.md) - [Batch executions (advanced)](https://testing-docs.madoo.ai/public-api/batch.md) - [Catalog discovery (node types, models, presets, effects)](https://testing-docs.madoo.ai/public-api/catalog.md) - [Design templates — document templates and PDF rendering](https://testing-docs.madoo.ai/public-api/design-templates.md) - [External embeds: workflow runtime and editor](https://testing-docs.madoo.ai/public-api/embed.md) - [Executions](https://testing-docs.madoo.ai/public-api/executions.md) - [MCP server — connect an AI client to Madoo](https://testing-docs.madoo.ai/public-api/mcp-server.md) - [Quickstart — your first generation, end to end](https://testing-docs.madoo.ai/public-api/quickstart.md) - [Reference](https://testing-docs.madoo.ai/public-api/reference.md) - [Repeat Until Accepted](https://testing-docs.madoo.ai/public-api/repeat-until-accepted.md) - [Outbound webhooks](https://testing-docs.madoo.ai/public-api/webhooks.md) - [Workflows & the interface](https://testing-docs.madoo.ai/public-api/workflows.md) ### Appendix - [Madoo contracts](https://testing-docs.madoo.ai/appendix/contracts.md): Every JSON contract Madoo defines for the documents its nodes exchange — datasets, bundles, quality checks, media facts, captions, dubbing, highlights — each with its fields, the nodes that produce and read it, and its complete schema. - [Credits and third-party licences](https://testing-docs.madoo.ai/appendix/credits.md): The third-party data and components Madoo includes whose licences ask to be credited — MaxMind GeoLite (IP geolocation), country-flag-icons (flag images) and Apache ECharts (charts) — with their attribution and licence texts. Read when: Read when someone asks which third-party data or components Madoo includes, where a location shown by Madoo comes from, or what licence covers them. - [madoo.attempts-report/v1](https://testing-docs.madoo.ai/appendix/contracts/attempts-report-v1.md): Madoo attempts report: What Repeat Until Accepted did: the body and its version, the policy, every attempt with its run, acceptance, score and feedback, and which attempt was delivered and why. - [madoo.audio-processing-report/v1](https://testing-docs.madoo.ai/appendix/contracts/audio-processing-report-v1.md): Madoo audio processing report: Explainable before-and-after envelope for an Audio Finishing transformation. - [madoo.audio-quality-report/v1](https://testing-docs.madoo.ai/appendix/contracts/audio-quality-report-v1.md): Madoo audio quality report: Deterministic loudness, peak, clipping, and silence measurements for one audio signal. - [madoo.audio-timeline/v1](https://testing-docs.madoo.ai/appendix/contracts/audio-timeline-v1.md): Madoo audio timeline: Deterministic evidence for audio clips placed on an absolute master timeline. - [madoo.bundle-manifest/v1](https://testing-docs.madoo.ai/appendix/contracts/bundle-manifest-v1.md): Madoo bundle manifest: Portable manifest for an authorized logical collection of uploaded assets. - [madoo.caption-block-family/v1](https://testing-docs.madoo.ai/appendix/contracts/caption-block-family-v1.md): Madoo caption block family: Caption block emitted in ordinary v1 mode or duration-aware v2 mode. - [madoo.caption-block/v1](https://testing-docs.madoo.ai/appendix/contracts/caption-block-v1.md): Madoo caption block: One bounded group of caption cues plus read-only neighbouring context for translation. - [madoo.caption-block/v2](https://testing-docs.madoo.ai/appendix/contracts/caption-block-v2.md): Madoo duration-aware caption block: One pending cue with original context and measured feedback for bounded spoken adaptation. - [madoo.caption-track/v1](https://testing-docs.madoo.ai/appendix/contracts/caption-track-v1.md): Madoo caption track: Provider-neutral ordered caption cues on an absolute media timeline. - [madoo.caption-translation-block/v1](https://testing-docs.madoo.ai/appendix/contracts/caption-translation-block-v1.md): Madoo translated caption block: Validated translated texts aligned one-to-one with the immutable cue IDs of a caption block. - [madoo.caption-translation-quality/v1](https://testing-docs.madoo.ai/appendix/contracts/caption-translation-quality-v1.md): Madoo caption translation quality: Cue coverage, timing preservation, bounded-repair counts and warnings for a translated caption track. - [madoo.color-palette/v1](https://testing-docs.madoo.ai/appendix/contracts/color-palette-v1.md): Madoo color palette: The colors an image is made of, by share: hex, OKLCh, CSS name, dominant, accent and background roles, a readable text color (Color Palette). - [madoo.dataset-profile/v1](https://testing-docs.madoo.ai/appendix/contracts/dataset-profile-v1.md): Madoo dataset profile: Bounded inspection result used to author and qualify a tabular data source. - [madoo.dataset-row/v1](https://testing-docs.madoo.ai/appendix/contracts/dataset-row-v1.md): Madoo dataset row: One normalized dataset row with stable identity and explicit value presence. - [madoo.dataset/v1](https://testing-docs.madoo.ai/appendix/contracts/dataset-v1.md): Madoo dataset: Format-neutral descriptor for a normalized tabular dataset and its row store. - [madoo.decision-questions/v1](https://testing-docs.madoo.ai/appendix/contracts/decision-questions-v1.md): Madoo decision questions: The questions Decide with a Model asks about its content: yes/no, a choice between options or a score on levels, each with its instructions and the threshold its answer must reach. Each question names output ports of the step. - [madoo.decision/v1](https://testing-docs.madoo.ai/appendix/contracts/decision-v1.md): Madoo decision: What Decide with a Model answered: for each question the answer, the probability of every option or level and whether it reached its threshold (accepted, uncertain, refused or invalid). - [madoo.design-document/2.0](https://testing-docs.madoo.ai/appendix/contracts/design-document-2-0.md): Madoo DesignDocument 2.0: A whole document template as the editor saves it; read, create and replace templates in this format. - [madoo.design-pages-manifest/v1](https://testing-docs.madoo.ai/appendix/contracts/design-pages-manifest-v1.md): DesignDocument page images manifest (v1): Results of runs before the public template ids: numeric document and version ids. - [madoo.design-pages-manifest/v2](https://testing-docs.madoo.ai/appendix/contracts/design-pages-manifest-v2.md): DesignDocument page images manifest: Selected raster pages and durable image references from a published document template. - [madoo.dubbing-cue-evidence/v1](https://testing-docs.madoo.ai/appendix/contracts/dubbing-cue-evidence-v1.md): Madoo dubbing cue evidence: Per-cue TTS generation and duration-fit evidence collected for the dubbing manifest. - [madoo.dubbing-manifest/v1](https://testing-docs.madoo.ai/appendix/contracts/dubbing-manifest-v1.md): Madoo dubbing manifest: Auditable delivery manifest for a timeline-aware localized dubbing workflow. - [madoo.dubbing-manifest/v2](https://testing-docs.madoo.ai/appendix/contracts/dubbing-manifest-v2.md): Madoo natural speech dubbing manifest: Delivery evidence with immutable plan, measured candidates and complete attempt history. - [madoo.image-detail/v1](https://testing-docs.madoo.ai/appendix/contracts/image-detail-v1.md): Madoo image detail: Fine detail and residuals of an image on small patches, globally and per tone band, and the patches to look at closely with a context rectangle ready for Crop (Image Detail). - [madoo.image-faces/v1](https://testing-docs.madoo.ai/appendix/contracts/image-faces-v1.md): Madoo image faces: Where the faces of an image are (Face Detect): score, box and six points (eyes, nose tip, mouth, ears) of each face, and the crop region framed around the selected one. Locates faces, never identifies anyone. - [madoo.image-instances/v1](https://testing-docs.madoo.ai/appendix/contracts/image-instances-v1.md): Madoo image instances: The people, animals and objects a model found in an image (80 COCO classes): class, score, box, mask area and edges reached of each instance, and which ones form the output mask (Instance Segment). A prediction, not a measurement. - [madoo.image-layout-report/v1](https://testing-docs.madoo.ai/appendix/contracts/image-layout-report-v1.md): Madoo professional still-image layout report: Authoritative exact-font, fitting, clipping, bounding-box and safe-area evidence for each rendered layer. - [madoo.image-set/v1](https://testing-docs.madoo.ai/appendix/contracts/image-set-v1.md): Madoo image set: A list of images, each a Madoo storage reference with an optional label and metadata: frames of a video, pages, any set of pictures. - [madoo.image-statistics/v1](https://testing-docs.madoo.ai/appendix/contracts/image-statistics-v1.md): Madoo image statistics: Tone and colour of an image, of grid cells or regions, optionally inside a mask: luma quantiles, near-black and near-white shares, luminance, Oklab means, colour per tone band (Image Statistics). - [madoo.image-text-layers/v1](https://testing-docs.madoo.ai/appendix/contracts/image-text-layers-v1.md): Madoo professional still-image text layers: One to 32 stable-ID text layers with deterministic z-order and optional complete style snapshots. - [madoo.image-typography/v1](https://testing-docs.madoo.ai/appendix/contracts/image-typography-v1.md): Madoo professional still-image typography: Exact-font sizing, layout, safe-area and readability style for deterministic still-image text. - [madoo.json-schema-errors/v1](https://testing-docs.madoo.ai/appendix/contracts/json-schema-errors-v1.md): JSON Schema validation errors: Structured diagnostics emitted by utility/json_schema_validate. - [madoo.keyframe-map/v1](https://testing-docs.madoo.ai/appendix/contracts/keyframe-map-v1.md): Madoo keyframe map: Where each image sits in a clip generated by Keyframes to Video: evenly spread or at explicit frames. - [madoo.mask-measurements/v1](https://testing-docs.madoo.ai/appendix/contracts/mask-measurements-v1.md): Madoo mask measurements: Where the subject of an image is and how big it is, per region: box, area, coverage, centroid, edges touched, bands and profile (Measure Subject). - [madoo.media-policy/v1](https://testing-docs.madoo.ai/appendix/contracts/media-policy-v1.md): Madoo media policy: Deterministic technical constraints evaluated against media facts. - [madoo.media-technical-info/v1](https://testing-docs.madoo.ai/appendix/contracts/media-technical-info-v1.md): Madoo media technical information: Normalized technical facts for a storage-backed image, audio, or video asset. - [madoo.quality-check/v1](https://testing-docs.madoo.ai/appendix/contracts/quality-check-v1.md): Madoo quality check: One deterministic check with explicit measurements, violations, and technique version. - [madoo.quality-policy/v1](https://testing-docs.madoo.ai/appendix/contracts/quality-policy-v1.md): Madoo quality policy: Rules for aggregating one or more portable quality checks. - [madoo.quality-report/v1](https://testing-docs.madoo.ai/appendix/contracts/quality-report-v1.md): Madoo quality report: Self-contained, explainable result of a quality-gate decision. - [madoo.quality-violations/v1](https://testing-docs.madoo.ai/appendix/contracts/quality-violations-v1.md): Madoo quality violations: Bounded portable quality violations emitted by deterministic probes. - [madoo.speaker-voices/v1](https://testing-docs.madoo.ai/appendix/contracts/speaker-voices-v1.md): Madoo speaker voices: The voice every speaker of a recording is voiced with. - [madoo.speech-timing-assessment/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-assessment-v1.md): Madoo speech timing assessment: Measured speech candidate with deterministic acceptance and natural padding evidence. - [madoo.speech-timing-candidate-rows/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-candidate-rows-v1.md): Madoo measured speech candidate rows: Candidate rows collected by aggregate/json for one speech-timing reconciliation round. - [madoo.speech-timing-candidate/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-candidate-v1.md): Madoo measured speech candidate: One authenticated synthesized speech candidate with measured duration and signal evidence. - [madoo.speech-timing-delivery/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-delivery-v1.md): Madoo selected natural speech: Authenticated accepted speech rows for ordinary enumeration and finishing. - [madoo.speech-timing-plan/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-plan-v1.md): Madoo speech timing plan: Immutable aligned caption plan and conservative speaking/fit policy. - [madoo.speech-timing-policy/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-policy-v1.md): Madoo speech timing policy: Bounded round, speaking-rate, fit-rate and tolerance controls for natural speech. - [madoo.speech-timing-state/v1](https://testing-docs.madoo.ai/appendix/contracts/speech-timing-state-v1.md): Madoo speech timing state: Bounded round checkpoint preserving accepted candidates and all rejected attempts. - [madoo.stem-separation/v1](https://testing-docs.madoo.ai/appendix/contracts/stem-separation-v1.md): Madoo stem separation receipt: Provider-neutral evidence for a named four-stem source-separation result. - [madoo.string-list/v1](https://testing-docs.madoo.ai/appendix/contracts/string-list-v1.md): Madoo string list: Bounded list of non-empty identifiers such as failed quality-check IDs. - [madoo.subject-location/v1](https://testing-docs.madoo.ai/appendix/contracts/subject-location-v1.md): Madoo subject location: Where Locate Subject found the subject of the reference pictures (or of the description) in a picture: its box and the crop region framed around it, its share of the picture, the edges it touches, whether it was ambiguous and the other candidates. A prediction, not a measurement. - [madoo.template-layout-report/v1](https://testing-docs.madoo.ai/appendix/contracts/template-layout-report-v1.md): DesignDocument template layout report (v1): Results of runs before the public template ids: numeric document and version ids. - [madoo.template-layout-report/v2](https://testing-docs.madoo.ai/appendix/contracts/template-layout-report-v2.md): DesignDocument template layout report: Public template identity, page selection, repeated content, image loading and timing evidence. - [madoo.transcript-aggregation-quality/v1](https://testing-docs.madoo.ai/appendix/contracts/transcript-aggregation-quality-v1.md): Madoo transcript aggregation quality: Coverage, overlap reconciliation, cleanup counts, duration and warnings for an aggregated transcript. - [madoo.transcript-segments/v1](https://testing-docs.madoo.ai/appendix/contracts/transcript-segments-v1.md): Madoo timed transcript: Provider-neutral speech segments or words with media-relative timestamps. - [madoo.tts-generation/v1](https://testing-docs.madoo.ai/appendix/contracts/tts-generation-v1.md): Madoo text-to-speech generation receipt: Provider-neutral evidence describing one synthesized speech clip and its effective controls. - [madoo.video-edit-manifest/v1](https://testing-docs.madoo.ai/appendix/contracts/video-edit-manifest-v1.md): Madoo video edit manifest: Measured mapping between source ranges and an assembled output-video timeline. - [madoo.video-highlight-candidates/v1](https://testing-docs.madoo.ai/appendix/contracts/video-highlight-candidates-v1.md): Madoo video highlight candidates: Bounded, provider-neutral highlight suggestions for one source-video segment. - [madoo.video-highlight-plan/v1](https://testing-docs.madoo.ai/appendix/contracts/video-highlight-plan-v1.md): Madoo video highlight plan: Deterministic chronological edit plan selected under an explicit duration budget. - [madoo.video-scenes/v1](https://testing-docs.madoo.ai/appendix/contracts/video-scenes-v1.md): Madoo video scenes: What a video is made of: its scenes between cuts and black gaps, the gaps, and the frames chosen for each scene (Extract Scenes). - [madoo.video-text-track/v1](https://testing-docs.madoo.ai/appendix/contracts/video-text-track-v1.md): Madoo video text track: Timed text events rendered together over a video by Video Text Overlay, in one encoding pass. - [madoo.video-typography/v1](https://testing-docs.madoo.ai/appendix/contracts/video-typography-v1.md): Madoo video typography: Exact font, size, colour, safe-area layout, outline, shadow, background box and motion of video text. ### Other - [Decisions with a model](https://testing-docs.madoo.ai/decisions.md): Decide with a Model (ai/decide) asks a decision model typed questions about a text or pictures — yes or no, a choice between options, a score on levels — and answers each with a probability, in a few hundred milliseconds, for a few thousandths of a credit. What it is for, how it differs from the free decision nodes and from vision and language models, and where each technique of the section is explained. Read when: When a workflow must judge content that is not structured — is this photo usable, which team handles this message, which variant fits the brief, what kind of document this is, is this text on brand — and choose a branch on the answer. - [Building it on every surface](https://testing-docs.madoo.ai/decisions/authoring.md): How to add and configure Decide with a Model in the workflow editor, in a workflow definition through the REST API v1, through the MCP server from an AI assistant, and by asking the AI agent or the AI assistant — the questions document, the ports to connect from, the validation errors with their paths, and how to read the decision of a run. Read when: When building a workflow with Decide with a Model by hand in the editor, from code, from Claude, ChatGPT or another MCP client, or by asking Madoo's own agent — or when one of these refused the step. - [Checking pictures](https://testing-docs.madoo.ai/decisions/checking-images.md): Decide with a Model as the eyes of a workflow: check a photo or a generated picture before it is delivered or before money is spent on it — focus, exposure, watermarks, framing, background, what it shows — choose the best of several variants, screen an uploaded picture, judge the frames of a video; low or high image detail, measured; what a decision model sees and what the measuring nodes see better. With a lab. Read when: When a workflow should look at pictures before delivering them, before a paid step, or to choose between them — product photos, AI generations, uploads from users, video frames. - [Costs, speed and limits](https://testing-docs.madoo.ai/decisions/costs-and-limits.md): What Decide with a Model costs and why: it is billed on what it reads only, about 0.006 credits per 1,000 tokens, at least 0.001 credits a call; how the content, each question and each picture count; what typical decisions cost next to the alternatives; what the estimate before a run assumes; how fast it answers; and every limit of the step. Read when: When estimating what a workflow with Decide with a Model will cost, comparing it with Image Analysis or a language model, or when a request is refused for a limit. - [Decisions with a model — examples](https://testing-docs.madoo.ai/decisions/examples.md): Complete, installable workflows where Decide with a Model judges and the free nodes route: product photos screened before a marketplace, a support inbox sorted in two languages, the best of four generated pictures delivered, documents sorted before the right reading — each with its real results and cost. Read when: When you want to see Decide with a Model on a real job end to end, or to install one as a starting point. - [How Decide with a Model works](https://testing-docs.madoo.ai/decisions/how-it-works.md): The Decide with a Model step in full: what it judges (a content, up to 20 pictures, an image set), the questions it asks (yes_no, choice, score — madoo.decision-questions/v1), the two ports each question gives, the decision document, the four statuses of an answer, what On Uncertain does with an answer below its threshold, the image detail, the model, and the envelope around the content. With a lab that triages a customer message. Read when: Before adding Decide with a Model to a workflow, when wiring its answers to other steps, or when an answer came back uncertain, refused or absent and you want to know why. - [Routing and grading text](https://testing-docs.madoo.ai/decisions/routing-and-grading.md): Decide with a Model on texts: send a message to the right team, sort documents before reading them, grade a generated text against a rubric or against the facts it should keep, and route on the answers with free nodes — Select by Key for one of several values, Predicate and Filter to pay only on the branch that needs it, a score to sort or escalate. Measured in English and Italian. With a lab. Read when: When a workflow receives texts — customer messages, emails, documents, reviews, AI drafts — and must decide what to do with each before spending on it. - [Hidden instructions, refusals and responsibility](https://testing-docs.madoo.ai/decisions/safety.md): What protects a Decide with a Model step from instructions hidden in the content (the fixed envelope, measured: 12 out of 12 right with it, 8 out of 12 without), why some questions are refused and what the step does then, where the content goes and what the provider keeps, and the decisions a model should not take alone — with the patterns that keep a person in the loop, and a lab. Read when: When the content a workflow judges comes from people outside it — customers, users of an App, suppliers, the web — or when a decision affects a person, a payment or a publication. - [Thresholds and uncertainty](https://testing-docs.madoo.ai/decisions/thresholds.md): How sure Decide with a Model is, and what to do when it is not: what a probability means and how well calibrated it is, the default thresholds and the measurements they come from (348 labelled decisions in English and Italian), how to set a threshold on your own examples, and the patterns for an uncertain answer — a person reviews it, the branch is skipped, the run stops, or a second, more expensive look. With a lab. Read when: When choosing the threshold of a question, when too many answers come back uncertain or a wrong one was accepted, or when designing what a workflow does with the cases the model is not sure about. - [Troubleshooting decisions with a model](https://testing-docs.madoo.ai/decisions/troubleshooting.md): What to do when a Decide with a Model step is refused, fails, comes back uncertain, leaves a port absent, or gives a wrong answer — by symptom: the validation codes of the questions with their paths, the run-time codes, uncertain and refused answers, missing connections after a rename, unexpected costs; with how to read the decision document and the trace. Read when: When a workflow with Decide with a Model is rejected at validation, a step fails or is skipped, an answer is uncertain or refused, a question's port has no value, or the answer is simply wrong. - [Writing questions](https://testing-docs.madoo.ai/decisions/writing-questions.md): How to write the questions of Decide with a Model so the answers are right and the probabilities mean something: statements in observable terms, one concern per question, options with descriptions and an 'other', levels from lowest to highest, the words the model takes literally, languages, order, what a decision model is weak at — with measured examples, questions ready to copy for products, messages, documents, pictures and texts, and a lab. Read when: When writing or reviewing the questions of a Decide with a Model step, or when its answers are uncertain or wrong and the question may be the reason. - [X01 — Product photos screened before a marketplace listing](https://testing-docs.madoo.ai/decisions/examples/x01-marketplace-photos.md): A ceramics shop's seven product photos checked by Decide with a Model — focus, exposure, watermark, framing, background, in one step per photo — and only the ones that pass every check with every answer sure padded to the marketplace's 1600 × 1600 square; a report says, photo by photo, what is wrong with the others. 0.05 credits for seven photos. Installable. Read when: When photos must meet a standard before they are published or paid for — a marketplace, a catalogue, a campaign — and you want the check automatic, cheap and explained photo by photo. - [X02 — A support inbox sorted in two languages](https://testing-docs.madoo.ai/decisions/examples/x02-support-inbox.md): Eight customer messages in English and Italian sorted by Decide with a Model — the team, the urgency, whether the item arrived damaged — with the doubtful ones flagged for a person and a reply draft written by a language model only for the sure refund requests; a work queue in JSON. 0.05 credits for eight messages. Installable. Read when: When a workflow receives messages — support emails, contact forms, reviews, chats — and must sort them, flag the urgent ones and spend on a written reply only where one is needed. - [X03 — Four generated pictures, the one that fits the brief delivered](https://testing-docs.madoo.ai/decisions/examples/x03-best-variant.md): A homeware brand's brief becomes four pictures from one Text to Image step; Decide with a Model reads the brief and the four pictures together, chooses the one that fits best and checks that none shows text or a logo; Select by Key delivers the chosen picture. The choice costs 0.009 credits next to 4 for the pictures, and the same call catches the picture that shows a logo. Installable. Read when: When a workflow generates several variants and only one should be delivered — a campaign picture, a product shot, a cover — and you want the choice made against the brief, not by the first variant. - [X04 — Documents sorted, then read the right way](https://testing-docs.madoo.ai/decisions/examples/x04-document-intake.md): A small agency's back office receives the text of invoices, quotes and contracts in Italian and English. Decide with a Model says what each document is; only the extraction that fits it runs — an invoice's supplier, number, total and due date, a quote's validity, a contract's parties and notice — so one paid reading per document, never three. 0.013 credits a document. Installable. Read when: When documents of different kinds arrive in one place and each kind must be read differently — invoices, quotes, contracts, orders, CVs — and you want to pay for the reading that fits, not for all of them.