CHANGELOG

1.8.0 — 2026-10-23

Upstream sync: the email skills from the upstream editor skills — maestra-email 1.18.2, maestra-email-ops 1.17.1 (skill versions mirror upstream). Rebuilt from the upstream text with the standing Maestra adaptations re-applied, including the 1.7.2 alt-text rule; the other skills are unchanged.

maestra-email — the reference is now a wiki, one page per tag. SKILL.md shrank to the procedure and the rules that span tags (upstream's 6 workflow steps plus the Maestra step 0, a tag table that says which page to open, "Rules across elements", "Value rules", "Refuse or simplify"); every attribute, default, value shape and snippet moved into references/wiki/ — containers.md (Template, Block, FlexRow, Column, Split, the grid, spacing and mobile stacking), text.md, typography.md (fonts), button.md, image.md, divider.md, html.md, groups.md (Menu, BulletList, Socials), label.md, theme.md (letter styles and moving a look into them), canvas.md (what the preview shows that the sent email will not), unsubscribe-link.md, quokka-block.md, sync-block.md, plus the four carried over: personalization.md, personalization-parameters.md, product-parameters.md, product-rows.md. The old dsl-surface.md, formats.md and examples.md are gone — their content lives on the pages. Rules that are new or sharper: a read email is written back as read (markers, font objects, placeholders, storage forms — nothing completed or trimmed); every image address — Image, Template.background, <img> in <Html>, bulletIcon, iconSrc — comes from the gallery through Ops; Image.alt with a chip, emptyVariableBehavior on any element with a chip; buttonSize with widthType and the mobile sides; a <Theme> is a patch down to the fields; what a chip prints on its own (currency sign, bonus word, greeting) is never written next to it; "Two values in one text" are two elements; a timer or a video is not writable in JSX — say so and build the rest. The email details card (step 0, references/email-details-card.md), the "one size and one font per <Text>" rule (now a section of wiki/text.md) and the "alt text on every image" rule from 1.7.2 (now a section of wiki/image.md, pointed at from html.md and the rules across elements) stay as Maestra additions.

• Universal blocks (<SyncBlock savedBlockInternalId="…" />, wiki/sync-block.md): a block shared between emails is carried over as the tag it came as, never expanded into a <Block> or rebuilt; its content is edited only in the editor; an unsubscribe link inside it is read off the preview and not duplicated. The saved-block list tells block / quokka / sync apart by kind.
• Editor-template blocks: <QuokkaBlock> settings are changed through visual_template_quokka_block_describe (the template's description names the attribute and its value shape) and written onto the tag already in the email.

maestra-email-ops:

• An email by a saved template (references/saved-template.md): the user picks one of the project's saved templates in the panel (client_visual_template_list); its blocks are read with visual_template_get, its letter styles with visual_template_theme_get, and the one save that applies it passes settingsSource so the email gets the template's width, background, CSS and letter styles; later edits are saved without it.
• The template argument: visual_template_get / visual_template_theme_get take the campaign's or the saved template as template, visual_template_preview / visual_template_save as settingsSource; formatInternalId on get, theme_get and preview is deprecated. Until the Maestra MCP release that carries these arguments reaches a project, the skill goes by the tool schema it sees and keeps passing formatInternalId; the saved-template route needs that release.
• Letter styles: "throughout the email" / "all the buttons" in the request settles the styles-vs-node question without asking (the number is still named); a layout verdict is given only after both preview snapshots were opened; a bare Internal server error is passed on verbatim, not read as a value-shape error; gallery_image_upload with a link fetches only https://; a preview or save refused because a sync block was not found offers to remove the tag or to open the editor; the campaign link is reported only once a save returned it.

Version 1.8.0 in all three manifests.

1.7.2 — 2026-10-13

• maestra-email: alt text on every image. <Image> takes alt, every <img> inside <Html> carries an alt attribute, and <Socials> lines get the network name. The alt is the image's text or meaning (a banner's headline and CTA, a nav tile's label, the brand name for a logo, a short description for a photo), read off the image rather than guessed from the file name; decorative images get alt="". When an email is copied or ported, meaningful source alts are kept and missing or placeholder ones are written. New "Images" → "Alt text" section, alt added to the allowlist row of Image, the <Html> hard rule and the self-check. A Maestra adaptation — on the next upstream sync keep the upstream wording if it carries the same rule, otherwise re-apply it.

1.7.1 — 2026-10-08

• maestra-email: one size and one font per text block. A heading is always its own <Text>, and so is any line that differs from its neighbors in size or font; an h1–h6 tag is the only content of its <Text>, and size or font is not changed with a <span>. Bold, italics, links and the color of a word inside a block stay allowed. A section that keeps a heading and a paragraph together in the source — a text block from Klaviyo or another email platform, an HTML cell, a mockup — is split into several <Text> one under another, with the spacing between them matched to the source. Applies to text the agent writes or carries over; library blocks and untouched text stay as they are. Added to the "Text — markup inside text" section and to the self-check. A Maestra adaptation — on the next upstream sync keep the upstream wording if it carries the same rule, otherwise re-apply it.

1.7.0 — 2026-10-05

Upstream sync: the email skills from the upstream editor skills 1.15.0, and flow-create, filter-build, filter-explain from the upstream public plugin 1.1.0. Upstream now ships these in English, so the Maestra copies are rebuilt from the upstream text with the standing Maestra adaptations re-applied; the next sync is an English-to-English diff. Skill versions mirror upstream: the email skills 1.15.0; flow-create, filter-build, filter-explain 1.0.0 (upstream restarted numbering for its public plugin; the previous 17.1.0 / 1.3.0 were its internal numbers).

maestra-email-ops — edits to a running automated campaign go into a draft. A working automated campaign keeps its email in two versions: the active one customers receive and the draft a person applies in the campaign editor. The skill reads the editability line campaign_get prints, writes once into the version the user sees — on a working campaign the draft, created by the save itself when there is none — and says plainly that customers see the edit only after the draft is applied. It no longer writes the same email into Draft and then Active. The subject, sender, preheader and schedule of a working campaign have no draft, so the skill leaves them to the editor. Verified on a live project: the save creates the draft and names its address, and a save aimed at the active version while a draft exists is refused.

maestra-email-ops, also new:

• Recipients. A bulk campaign's recipients can be set to a segment (segments_list) or to a filter built by maestra:filter-build, after a separate confirmation (references/recipients.md). An automated campaign's audience stays the flow's.
• Images. Uploads go through gallery_image_upload: its panel puts files straight into the project gallery with permanent addresses; an image given as a link is copied into the gallery too. In clients with MCP Apps, gallery_images_list opens a picker with thumbnails. The contact-sheet script gallery_contact_sheet.py and references/visual-gallery-selection.md are removed, as upstream did.
• Test sends go out from the saved version the user chose, with its formatInternalId; an unsaved edit is saved first or the user is told. The campaign version token is tracked on refusals and on a test send from the draft too; a version conflict on a metadata edit is a question to the user, not a retry.
• The feedback report's skill= field names email / email-ops, upstream's machine values.

maestra-email:

• Fonts only from the editor's 19-font list (10 web-safe, 9 Google fonts with a web-safe fallbackFontFamily); the closest one is picked and named.
• Buttons without an address are saved with an empty link and listed for the user to fill in, after one question for all of them.
• Editor-template blocks (<QuokkaBlock>) in an email that was read are carried over untouched (references/dsl-surface.md §13); a new one is never built. Verified: such an email saves back unchanged.
• RecipientGreeting already carries the whole greeting — no words are written around it; own words go in affixVariableText. Bonus pluralization rules; Image alt; the editor's default product card; new parameters MailingTopicName, OrderPresentment* and OrderItemPresentment* with the formatMoney formatter.
• The default unsubscribe line is "If you no longer want these emails — unsubscribe".

flow-create:

• null is not a general clear — per member it clears, resets, is ignored or is refused, so it is sent only where the reference says the member is clearable, and the block is read back.
• Self-check (step 7c): after the final validation, maestra:flow-issues-audit runs on each built flow in a sub-agent; a real undecided risk lands in the hand-over, nothing else is said.
• On acceptance, one line asks for a 1-to-10 rating, saying the number goes to the Maestra developers; a number given in reply is sent, anything else sends nothing.
• New references/feedback-and-selfcheck.md; filter-delegation.md asks the filter sub-agent to confirm the property set as well as the root.

filter-build, filter-explain: tool calls are described by name and the arguments that carry the request, the rest filled from the server's schema; descriptions keep the Maestra wording.

Maestra adaptations kept: the email details card (step 0), the inbox mockup — its reference now names the draft as "after" on a working campaign —, "letter styles", the note on the API's legacy editor-kind value, maestra: cross-references, the admin link from the project's system name, the multi-project tenant guidance in the filter skills, the filter starter set (the wiki still has no starter-set pattern), and feedback only with the user's consent — upstream's unasked documentation-mismatch message in flow-create is kept and offered at hand-over instead.

README: the Emails, Flows and "What the skills do" rows say the above; two try-it prompts. Removed from the repository: a stray __pycache__/inbox_mockup.cpython-310.pyc.

1.6.0 — 2026-10-04

• maestra-email: email details card, mandatory before a new email. A new step 0 of the workflow: building a new email (from a description, a mockup or a reference, a rebuild, a copy, a port) starts with one card of the open questions — where to save it, automatic or manual, which data to show, the product layout, which reference images to take, the style, and, when the look is not given, where to take it from: the brand's last 3 one-off emails, the last 3 flow emails, the website, or the client's brand book uploaded in the card — with what the project and the reference already tell preselected. Drawn with the visualization tool (show_widget, elicitation module) where the host has it; otherwise the host's native choice tool; otherwise numbered questions in one message. Nothing is uploaded, generated or created before the answer or a Skip; when nothing is open, one line says what was decided instead. Small edits of an existing email get no card. Procedure, question table, the card skeleton and the fallbacks in the new references/email-details-card.md. A Maestra adaptation — re-apply it on the next upstream sync.
• maestra-email-ops: the New JSX email and New campaign from scratch routes and the folder/brand question point at the card.

1.5.0 — 2026-10-03

• maestra-email-ops: inbox mockup, before/after. After an email is saved, the report ends with a one-line offer — once per email per conversation — of a picture of the email as it looks opened in a phone mail app; when there is an earlier version (an in-place edit, or a rebuild as a copy or in a new campaign) the two versions stand side by side. On a yes, each version is rendered with visual_template_preview under its own format, and the new bundled script scripts/inbox_mockup.py puts the render under a mail-app header, swaps the editor's sample values in personalization chips for invented ones (--list-chips, --replace OLD=NEW), and saves <prefix>-before.png, <prefix>-after.png and <prefix>-before-after.png, each with a small Maestra badge in the bottom-right corner, outside the email (--no-logo leaves it out; the badge is the wordmark from assets/maestra-green.svg on its dark pill, shipped as skills/maestra-email-ops/assets/maestra-badge.png). It needs Playwright with a Chromium it can launch; without one it exits with code 3 and the fallback puts the preview's mobile snapshots side by side with Pillow. Procedure, sample-value rules and the hand-over in references/before-after-mockup.md; an "Inbox mockup: before/after" section with the invariants, a Quickstart row, a Capabilities line and a References row in SKILL.md. references/preview-qa.md says the mockup is not QA. A Maestra adaptation — re-apply it on the next upstream sync.
• maestra-email: step 9 of the workflow points at the offer; the Generator builds nothing for it.
• README: the Emails row and the Run line name the mockup and its script.

1.4.9 — 2026-09-29

• SECURITY.md: where to report a security vulnerability.

1.4.8 — 2026-09-29

• .claude-plugin/plugin.json: documentation and support links point to help.maestra.io without a language path.

1.4.7 — 2026-09-29

• .claude-plugin/plugin.json: the documentation link points to the Maestra help center.

1.4.6 — 2026-09-29

• .claude-plugin/plugin.json: documentation, support, privacy policy, and terms of service links.

1.4.5 — 2026-09-29

• README: a Privacy section with a link to the Maestra Privacy Policy.

1.4.4 — 2026-09-29

• Plugin icon in SVG instead of PNG, same image.

1.4.3 — 2026-09-29

• Plugin icon, 600 × 600.

1.4.2 — 2026-09-29

• maestra-email-ops: wording in references/visual-gallery-selection.md; no behaviour change.

1.4.1 — 2026-09-29

• Every skill: a feedback report is sent only after the user has seen its full text and agreed, as the email skills already do. filter-build shows the report on an incorrect result or on a repeated listing failure; flow-create offers a report on tool behaviour in Suggestions; in filter-explain, flow-summary, flow-issues-audit and flow-business-audit, a line in SKILL.md says the same. Run as a sub-agent, a skill does not call feedback: filter-build returns the report under Feedback report, and flow-create offers it to the user. A Maestra adaptation — re-apply it on the next upstream sync.
• README: a new section, What the skills do in your account and on your computer: what the skills read and change, what they send (the image upload, feedback reports), what they run (downloads, the bundled contact-sheet script, the Pillow install, the Claude in Chrome fallback), and which files they leave in the working folder.
• README: the logo is a Markdown image instead of an HTML <img>; the SVG itself is now 220 px wide, so it renders at the same size.
• .claude-plugin/plugin.json: homepage, repository, license, and author.url, the same values as the root plugin.json.
• maestra-email-ops: the gallery contact-sheet script adds its own name to its User-Agent. A Maestra adaptation — re-apply it on the next upstream sync.
• filter-build: the maintenance note on the temporary starter-set section moves here from an HTML comment in SKILL.md. Remove the section once the filters wiki ships pattern/user.starter_filters.md; Batch requests and the starter-filter trigger phrase in the description stay.

1.4.0 — 2026-09-24

The four flow skills re-ported in full from the upstream flow plugin 2.1.0 (author "AI tribe"; the previous port was 1.27.0). Upstream 2.0.0 was a rewrite, not a patch — every file changed — so the Maestra copies were rebuilt from the new text rather than patched, with the standing Maestra adaptations re-applied. Skill versions now mirror upstream: flow-create 17.1.0, flow-business-audit 8.0.0, flow-summary and flow-issues-audit 1.0.0.

New in flow-create:

• Builds into a flow that is already running. A flow launched from the interface has no editable version; the skill now creates the draft itself with flows_create_draft, copied from the running or paused version the user names, waits until the copy is editable, takes a fresh row version, and continues as usual. A flow keeps at most one draft, and the refusal names it. Measured on a live project: the copy of a running version lands as ReadyForExecution, which is editable; the create's own row version is stale at once — both are written into the skill.
• No more copied contract. Field names, status spellings, presets, output tokens and defaults are no longer carried in the skill; they are read live from the tool schema and the wiki's write-path sub-folder (writing.*), so the skill cannot go stale against the platform. The SKILL.md is a third shorter for it.
• Every write is verified on two halves — the fields sent, and what the block held before the write and the body never mentioned — with the pre-write read kept as the baseline; opaque fragments go in complete; a session budget of six non-advancing writes ends the run with a decision put to the user, never with a manual step handed over.
• One research pass, one question batch: the project is fixed first when several are reachable, folder and brand are asked together and checked against each other before the create, the admin URL is derived from the project's system name (https://<system name>.maestra.io) rather than asked, and a batch of flows is one question round.

New in flow-summary, flow-issues-audit, flow-business-audit:

• Locale files. The wording each report prints — headings, verdicts, table headers, fixed phrases, urgency labels — lives in references/<locale>/terminology.md (en-US and ru-RU), with the worked examples and the themed HTML pages in the same two variants. A report is written in the reader's language from the matching variant; a language with no variant takes en-US and translates.
• flow-issues-audit: the per-flow checklist no longer names block tags or field names — each check points at the wiki document that carries them; a project-wide sweep keeps a findings file and can run in batches of sub-agents; running-only scope is filtered by the listing's own status vocabulary.
• flow-business-audit: form F (the burnt attempt) gets a read allowance of its own — one single-block settings read per scenario that reached level 2 — and is reported as "not checked" where unspent, never asserted from the skeleton; flows_list pages are a cost line of their own; whether a scenario is running is read from the set of version statuses (case-insensitive, an unknown value is "not established"), never from the active version line, and the run-close date is in the register of unreliable figures; the deck is the "proposal deck" with separate presenter notes, its labels "Decide today" / "Fix" / "Idea" per locale.

Kept from the Maestra port, and re-applied on the new text:

• flow-business-audit still runs on flow_report, not on SQL. Upstream 2.x still computes its figures over two scenario datamarts that this platform's catalogue does not carry; the numeric layer (metrics-map.md, rates.md, beyond-the-overview.md, invariants.md, calling-the-tools.md) is the Maestra edition, extended with upstream's version-status and run-timeline readings. Upstream's new attributable-deliveries denominator maps to the platform's own ConversionRate; its reach marts map to flow_report's per-customer family, printed only where the platform populates it. The metric names behind the locale wording are listed per key in terminology.md.
• Cross-skill references point at maestra:; the HTML examples print US dollars in both locales; flow links build on https://<system name>.maestra.io/scenarios/<id>.

1.3.0 — 2026-09-22

filter-build + filter-explain re-ported in full from the upstream filters plugin 1.3.0 (author "AI tribe", the same team as the email and flow skills; both skills now carry metadata.version: 1.3.0). Upstream rewrote both skills against the current filter tool family — filter_wiki_ls / filter_wiki_grep / filter_wiki_read, filter_search_entities, filter_sql_validate, filter_compile_preview, filter_json_to_sql — which is the family the Maestra MCP server exposes today; the previous skills described a route through the shared wiki tool and the retired lookup/build tools, so on a current server they had no working procedure.

New in filter-build:

• Edits an existing filter, not only builds a new one: the stored JSON is read back with filter_json_to_sql, every condition kept, the change applied, then validated and compiled again.
• The workflow is spelled out with tool-call examples: read the wiki's live README.md first, choose the root and editor (root/… pages, filterablePropertySet), consult recipes, glossary, patterns and — explicitly — help, resolve catalogue records with filter_search_entities (match and list modes, cursors, segmentations vs. segments) before drafting FilterSQL, clarify disputed choices, validate the complete draft with a coverage log of request → decision → reason, then compile once and require status: ready + platform: accepted.
• Regex search examples cover Russian and English word forms — the wiki's recipe, glossary and pattern pages carry both.
• JSON is requested (includeFilterJson=true) only when the user or another skill needs the payload, e.g. flow-create configuring a condition block; otherwise the link alone.
• A feedback template for a wrong result: the correct-filter URL, the trace URL or ID, and the chronological tool calls with arguments and responses, sent through the server's feedback tool.
• Bilingual trigger phrases (Russian and English) in the description.
• The CSM starter set (thirteen standard filters, the Texas geo segment, the two "bots" segments) stays as a Maestra appendix until the wiki ships it as a pattern.

New in filter-explain:

• Explains from the recovered FilterSQL: filter_json_to_sql first, then wiki lookups for each concept, catalogue lookups for values that stayed IDs, and a fixed answer shape — Result, Conditions, Limits and gaps — that preserves AND/OR grouping, negation, boundaries, time windows, segment-vs-segmentation and current-vs-historical distinctions.
• unlabelled / unsupported / UNSUPPORTED_FILTER(...) are disclosed as gaps, never rebuilt away.
• Bilingual trigger phrases in the description.

Plugin: .codex-plugin/plugin.json and skills/filter-*/agents/openai.yaml added (Codex / ChatGPT metadata, as upstream ships); plugin description now mentions editing and explaining filters.

1.2.1 — 2026-09-22

• flow-business-audit: the frontmatter description was 1,335 characters; claude.ai's plugin marketplace caps it at 1,024 and left the skill out of the sync with a warning. Shortened to under 1,000 characters with the same triggers and exclusions. No behaviour change.

1.2.0 — 2026-09-21

Four flow skills added, ported from the upstream flow plugin 1.27.0 (author "AI tribe") — the same team whose visual-editor skills became maestra-email and maestra-email-ops. The upstream pack was already English and already written against the flow tool family this platform exposes, so three of the four are near-verbatim ports; the fourth was rewired onto this platform's own reporting.

• flow-summary (read-only) — a concise, structured business summary of one flow from its structure: trigger, logic, goal. Reads the graph with flows_lookup and decodes blocks, events and steps from the Flows wiki. Optionally folds in ~30-day execution counts.
• flow-issues-audit (read-only) — a technical audit of one flow or a whole project against known anti-patterns (processing load, communication correctness), each finding with a concrete fix and a short why. Offers a presentation-ready HTML checklist on request.
• flow-create (writes drafts) — builds a correct draft flow from a plain-language request: reads the wiki, resolves entities to ids, creates and fills blocks, wires outputs, verifies every block by reading it back, and hands over a link. Filter bodies are delegated to filter-build in a sub-agent and written back unchanged; marketing mechanics come from the wiki's mechanics folder, never from memory. Creates a mailing per send step; launches nothing.
• flow-business-audit (read-only) — a business audit that ends in fixes to the flows themselves: the figures find the flows worth opening, then their construction says why they move and what to change. Two report forms, full report or client-ready deck.

flow-business-audit runs on flow_report, not on SQL. Upstream computed every figure with hand-written ClickHouse over two scenario marts; this platform's analytics catalogue does not carry them, and its flow_report tool answers money, volume, funnel and every rate for every flow and for the project in one call — the same computation behind the Scenarios screen, so a figure in the report and a figure in the admin UI are the same figure. The skill's template handles were kept (T1, T1m, T2, T10, T3f …) and their definitions replaced; metrics-map.md, rates.md, beyond-the-overview.md, invariants.md and calling-the-tools.md were rewritten around the new source. The datamart-coverage and recalculation-freshness handles retire with the marts, and the revenue-by-mailing-type split is now read from construction plus the wiki's flow_types rather than from a column — all three losses are stated in the skill rather than papered over.

Other adaptations: cross-skill references point at maestra: (maestra:filter-build, maestra:flow-summary); flow links build on https://<systemName>.maestra.io/scenarios/<id>; worked examples, both HTML report templates and the client deck are English with US currency; flow-summary's three output headings and flow-issues-audit's project table are English by default, translated with the report when the reader works in another language.

1.1.0 — 2026-09-15

maestra-email + maestra-email-ops synced with the upstream visual-editor skills, version 1.11.0 (both skills now carry metadata.version: 1.11.0). The generator and the ops skill were re-ported in full rather than patched, so the two stay diffable against the next upstream release.

New in the generator (maestra-email):

• Personalization with the <Var> chip: recipient, promo code, bonus balance, custom fields, order data; tenant-specific names come only from entities_list. New references personalization.md, personalization-parameters.md (43 email parameters) and product-parameters.md (125 product parameters by entity).
• Product rows <CollectionRow> / <CardTemplate> / <CollectionCard>: recommendations, product lists, order products, viewed products, manual selections — new reference product-rows.md.
• Letter styles: <Theme>, themeVariant, taking a node off the letter styles, moving repeated node styles into the theme (dsl-surface.md §8).
• <Label> / <Labels> inside product cards, dynamic images (image.mode: "dynamic"), saved blocks from the editor library, Template.containerWidth / background, element defaults (dsl-surface.md §6), pixel → grid and port-completeness self-checks.
• Rule changes: the unsubscribe link is added to every marketing email by default; an unsubscribe button is the SpecialLinkUnsubscribeLink chip; Divider.border needs one thickness on all four sides; buttonSize.width requires widthType.

New in ops (maestra-email-ops):

• Writes go to every visual-compatible format of the variant — Draft first, then Active.
• Test sends: campaign_test_recipients → campaign_send_test.
• Template-type change ("redo in the visual editor") is routed to a new campaign; mailingKind is a mandatory decision; folder/brand are resolved via entities_list.
• Letter styles via visual_template_theme_get; saved blocks via visual_template_saved_block_list / _get; feedback to the developers via MCP feedback (new reference feedback-examples.md).
• PNG preview links now arrive in the visual_template_preview response; ChangeConflict has no automatic retry.

1.0.0 — 2026-08-27

Initial public release: one maestra plugin carrying four skills.

• maestra-email + maestra-email-ops — create and edit emails for the Maestra visual editor: layout generation, gallery image search and upload, PNG preview, saving into your campaign as a draft.
• filter-build + filter-explain — build a CDP filter from a request in plain words, or explain a stored filter's JSON. Read-only.