AI-Studio/app/MindWork AI Studio/Tools/PowerPoint/AGENTS.md

AGENTS.md

These instructions cover the PowerPoint tools in app/MindWork AI Studio/Tools/PowerPoint/, with which the Slide Assistant (app/MindWork AI Studio/Assistants/SlideBuilder/) plans slides for the layouts of a template and writes PowerPoint files. They add to the AGENTS.md in the repository root and to app/AGENTS.md, which apply here as well.

How a presentation comes about

1. PresentationTemplate.Read reads a .pptx or .potx with the Open XML SDK (DocumentFormat.OpenXml): its layouts, grouped into families of color variants, and the slides it carries. Without a template, PresentationTemplate.CreateDefault stands in, so that one prompt and one check serve both cases.
2. ToCatalogPrompt and ToTemplateSlidesPrompt describe the layouts and the chosen template slides to the model in words: where each slot sits, what a label belongs to, and how much text fits.
3. SlideDeckSpec.TryParse reads the JSON answer of the model leniently.
4. SlideDeckSpecValidator checks the deck against the template. Its issues are written for the model, which gets one repair round.
5. SlideDeckSpec.ToMarkdownOutline shows the result as an outline, and PresentationWriter.WriteAsync writes the file: a copy of the template, with its slides replaced. PresentationFile.CreateAsync makes that copy in the temporary folder and streams it into the target once it is complete.

Rules which are easy to break

• The validator is the only gate. PresentationWriter relies on a deck which passed SlideDeckSpecValidator, checks nothing again, and throws when it meets what the validator should have caught. A new rule about what fits a template belongs into the validator, worded for the model. SlideDeckSpecValidator.CanWrite decides which issues leave a deck unusable at all.
• Slot names are a contract. The model reads and writes slots and elements by names such as title, text 2, label 1, or element 3. The catalog (PresentationTemplate.Catalog.cs), PlaceholderRoleExtensions.TryParseSlotName, TemplateSlide.FindElement, the validator, the writer, and the outline all depend on them, so change them together. Slots are numbered per role in reading order; the copies of a slot on a template slide continue that numbering.
• No knowledge of a particular template. Everything comes from the file: roles from the type and size of a placeholder, variants from the layout names, the design from masters and layouts. Never add the names, labels, or language of a corporate template to the code.
• Prompt texts stay in English, the user's texts do not. Catalog, issues, and rules are written for the model. Every text the user reads, the outline included, goes through T() or TB().
• Template texts are content of a file. This holds for the names of the layouts as well as for the texts of the slides. They reach the model in the request, as LAYOUTS and TEMPLATE_SLIDES, never in the system prompt, and they pass PromptInjectionGuardService with the reporting scope of the request. The names of the attached pictures go with the request as well, as PICTURES.
• Pictures for the slides are not source material. The user attaches them in a zone of their own; each goes on exactly one slide, which the validator checks. Images among the documents are source material, which the model reads and never places. A file is never both: the pictures for the slides win. Pictures go to the model as images only when it reads images; otherwise their names are all it has.
• A picture library offers names, never pictures. PictureLibrary reads PNG and JPEG files of a folder, at most MAX_LIBRARY_PICTURES, sampled anew for every planning. Their numbers follow those of the pictures for the slides. The names are content of a folder which others may write to, so PICTURE_LIBRARY passes PromptInjectionGuardService like the texts of a template. A picture counts as an icon when its name or one of its folders, the library folder included, starts with "icon": icons may repeat, are never cropped, and never go into a backdrop (PresentationTemplate.IsBackdrop), which the catalog marks and the validator checks.
• Layout choices travel by name. The user chooses layouts for kinds of slides (LayoutPurpose) by their names, which outlive sessions and new versions of a template. ChosenLayouts finds them in the template, and only their IDs go into the system prompt. The validator checks the two kinds which show in a deck, the title slide and the start of a chapter; every other choice is a rule for the model. A choice says which layout a kind uses, not whether the deck has one, except for the kinds with a PromptPlacement: a choice for them adds such a slide, and the validator checks that a new slide uses their layout and that an imprint comes last. Everything about a kind of slide lives in the file of its area, LayoutPurposeExtensions.<Area>.cs; a new kind goes there and into LayoutPurpose, within its area.
• New slides carry no formatting of their own. They fill the placeholders of their layout and leave out every placeholder without content, so that no prompt text such as "Click to add text" remains. Only empty picture placeholders stay when the user asks for it (PresentationWriteOptions.KeepEmptyPicturePlaceholders), for pictures of their own.
• No copy of a file in memory. Templates of organizations carry pictures and videos and easily reach a hundred megabytes, and AI Studio also runs on small devices. Read templates from their file, and let the writer edit a copy on disk. The Open XML SDK holds the compressed parts of the file in memory while it saves, which is all it costs; a MemoryStream with the whole file multiplies that.
• Write only into the file the user chose. Inside the Flatpak, the save dialog grants access to exactly that file, so nothing may be created, renamed, or moved next to it. Temporary files go into the temporary folder, and the finished presentation is written over the chosen file, never moved there.
• Removing a shape removes what only it used: its image, chart, or diagram parts, and the animations of its slide, see PresentationWriter.RemoveShape. Otherwise PowerPoint offers to repair the file.

Tests

The tests in app/Tests/Tools/PowerPoint/ build their templates in code with TestTemplate, so no binary template is checked in. A test which writes a file also runs the OpenXmlValidator over it, see ValidationErrorsOf.