Pair category repair (#550) and saved instructions + dialog picker (#431) (#590)

* feat(maintenance): repair old Pair prompts' empty category and tags (#550) Squashed from PR #579. Closes #550. * feat(tagging): saved instructions with a default per engine (#431) Squashed from PR #587. * feat(tagging): pick saved instructions in the tagging dialogs (#431) Squashed from PR #588. Closes #431.
2026-11-01 03:01:07 +00:00
parent 9640ca86f8
commit 3295ff8b20
44 changed files with 3905 additions and 207 deletions
@@ -64,11 +64,31 @@ function measureMaintenance(mainSelector) {
    };
 }

-/** D102: the Metadata cache row says why its review is unavailable and its button is aria-disabled (D93's dimmed style). */
-function mapMaintenanceConcept(reference) {
+/**
+ * D192 (#550, beyond the concept): Database adds "Pair category and tags" after "Unused prompt components", shaped like
+ * the concept's plain Review plan row (Optimize database's).
+ */
+function mapPairRow(reference) {
    return {
        ...reference,
-        surfaces: reference.surfaces.map(surface => ({ ...surface, rows: surface.rows.map(row => row.title !== 'Metadata cache' ? row : {
+        surfaces: reference.surfaces.map(surface => {
+            const plain = surface.rows.find(row => row.title === 'Optimize database');
+            const at = surface.rows.findIndex(row => row.title === 'Unused prompt components');
+            if (!plain || at < 0) return surface;
+            return { ...surface, tree: [...surface.tree, 'div.operation'], rows: [...surface.rows.slice(0, at + 1),
+                { ...plain, title: 'Pair category and tags', description: 'Fill an empty category or tags on prompts older ' +
+                    'Pair node runs saved, from their saved pairs. Only empty fields of never-edited prompts.' },
+                ...surface.rows.slice(at + 1)] };
+        }),
+    };
+}
+
+/** D102: the Metadata cache row says why its review is unavailable and its button is aria-disabled (D93's dimmed style). */
+function mapMaintenanceConcept(reference) {
+    const mapped = mapPairRow(reference);
+    return {
+        ...mapped,
+        surfaces: mapped.surfaces.map(surface => ({ ...surface, rows: surface.rows.map(row => row.title !== 'Metadata cache' ? row : {
            ...row, description: `${row.description} Nothing is cached in this browser.`,
            actions: row.actions.map(action => ({ ...action, opacity: '0.55', cursor: 'not-allowed' })) }) })),
    };
@@ -209,8 +229,8 @@ test('maintenance comparison detects mutations', async ({ page, request }) => {
    const expected = mapMaintenanceConcept(concept);
    const production = await productionMaintenance(page, 'dark');
    expect(diffInventory(expected, production)).toEqual([]);
-    // Unmapped, the section differs only on the D102 row.
-    expect(diffInventory(concept, production).map(item => item.path).sort()).toEqual([
+    // Mapped only for the D192 row, the section differs only on the D102 row.
+    expect(diffInventory(mapPairRow(concept), production).map(item => item.path).sort()).toEqual([
        'surfaces.1.rows.3.actions.0.cursor', 'surfaces.1.rows.3.actions.0.opacity', 'surfaces.1.rows.3.description']);
    const measure = () => page.evaluate(measureMaintenance, '#workspace-main');
    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
@@ -35,6 +35,8 @@ const MODEL_OPTIONS = ['WD14 SwinV2 · ~400 MB', 'WD14 ViT · ~400 MB', 'GGUF Jo
 const SUGGESTIONS = 'From 1 to 100: the most suggestions Generate shows for one image.';
 const SKIPPED_DESCRIPTION = 'Suggested tags that contain one of these words are hidden. Words are separated by spaces, _ or -; '
    + 'other characters such as ( ) belong to the word.';
+const DEFAULT_DESCRIPTION = 'The Tag image dialog and batches start from this.';
+const INSTRUCTIONS_DESCRIPTION = 'Instructions for the language-model engines. Built-in can’t be changed; duplicate it to make your own.';
 const BATCH = 'Tag each output image from its own pixels with the model above. Prompts are not changed. Review the scope first.';

 /** Runs in the page: Auto-tagging's surface under `mainSelector`: rows, field, actions, operation, geometry and tokens. */
@@ -64,7 +66,7 @@ function measureTagging(mainSelector) {
            text: [...row.firstElementChild.children].map(node => [name(node), text(node), node.localName === 'label' ? node.htmlFor : null]),
            control: control(row), flexWrap: getComputedStyle(row).flexWrap,
            controlBelow: row.lastElementChild.getBoundingClientRect().top >= row.firstElementChild.getBoundingClientRect().bottom - 0.5 })),
-        field: { tree: [...field.children].map(name), label: [text(field.querySelector('label')), field.querySelector('label').htmlFor],
+        field: field && { tree: [...field.children].map(name), label: [text(field.querySelector('label')), field.querySelector('label').htmlFor],
            textarea: { id: field.querySelector('textarea').id, value: field.querySelector('textarea').value,
                ...css(field.querySelector('textarea'), 'fontSize', 'minHeight', 'backgroundColor', 'color', 'borderTopColor') },
            ...css(field, 'display', 'rowGap', 'fontSize', 'marginTop', 'marginBottom') },
@@ -81,7 +83,22 @@ function measureTagging(mainSelector) {
            label: css(block.querySelector('label'), 'fontSize', 'fontWeight', 'color'),
            description: css(block.querySelector('.setting-block-text p'), 'fontSize', 'color', 'marginTop'),
            input: css(block.querySelector('input'), 'fontSize', 'backgroundColor', 'color', 'borderTopColor') })(
-            surface.querySelector(':scope > .setting-block')),
+            surface.querySelector(':scope > .setting-block[data-setting="tag-skipped"]')),
+        // D203 (#431): Saved instructions (the concept has a template field instead).
+        instructions: (block => block && { tree: [...block.children].map(name), key: block.dataset.key,
+            text: [...block.firstElementChild.children].map(node => [node.localName, text(node)]),
+            list: [...block.querySelectorAll('[role="option"]')].map(option => [text(option.firstElementChild),
+                [...option.querySelectorAll('.badges > .chip')].map(chip => [text(chip), chip.className]), option.getAttribute('aria-selected')]),
+            listRole: block.querySelector('.instruction-list').getAttribute('role'),
+            actions: [...block.querySelectorAll('.instruction-actions > button')].map(item => [text(item), item.className, item.disabled]),
+            editor: [...block.querySelectorAll('.instruction-editor .field')].map(item => [text(item.querySelector('label > span')),
+                item.querySelector('input, textarea').value, item.querySelector('input, textarea').readOnly]),
+            note: text(block.querySelector('#instruction-note')),
+            layout: getComputedStyle(block.querySelector('.instructions-layout')).gridTemplateColumns.split(' ').length,
+            ...css(block, 'paddingTop', 'paddingBottom', 'borderTopWidth', 'borderTopColor'),
+            label: css(block.querySelector('label'), 'fontSize', 'fontWeight', 'color'),
+            textarea: css(block.querySelector('textarea'), 'fontSize', 'backgroundColor', 'borderTopColor') })(
+            surface.querySelector(':scope > .setting-block[data-setting="tag-instructions"]')),
        operations: [...surface.querySelectorAll(':scope > .operation')].map(row => ({ tree: [...row.children].map(name),
            title: text(row.querySelector('h3')), description: text(row.querySelector('p')),
            actions: [...row.querySelectorAll('.row-actions > button')].map(item => [text(item), item.className]) })),
@@ -115,14 +132,21 @@ function measureTagging(mainSelector) {
 * The concept's Auto-tagging with the recorded deviations applied, for the fixture (all engines on disk, none loaded).
 * `phone` is a viewport at the concept's 700px breakpoint or below.
 */
-function mapTaggingConcept(reference, { template, phone }) {
+function mapTaggingConcept(reference, { builtin, saved, phone }) {
    const [model, existing, general, character] = reference.rows;
    const [preview] = reference.actions.buttons;
+    // D203: Built-in first, then the saved entries, in each default select.
+    const names = ['Built-in', ...saved.map(entry => entry.name)];
+    const defaultRow = (engine, long) => ({ ...existing,
+        text: [['label', `Default for ${long}`, `instruction-default-${engine}`], ['p', DEFAULT_DESCRIPTION, null]],
+        control: { ...existing.control, id: `instruction-default-${engine}`, options: names.map(label => [label, false]),
+            selected: names[1] } });
    return {
        ...reference,
-        // D133 adds a row after the thresholds, D202 the Skipped tags block after it; D134 adds the operation after the
-        // actions.
-        tree: [...reference.tree.slice(0, 6), 'div.setting-row', 'div.setting-block', ...reference.tree.slice(6), 'div.operation'],
+        // D133 adds a row after the thresholds, D202 the Skipped tags block after it; D203 replaces the template field
+        // with Saved instructions, the two default rows and their note; D134 adds the operation after the actions.
+        tree: [...reference.tree.slice(0, 6), 'div.setting-row', 'div.setting-block', 'div.setting-block', 'div.setting-row',
+            'div.setting-row', 'p.instruction-reset.small', reference.tree[7], 'div.operation'],
        rows: [
            // D132 (OQ5, OQ6): the four real engines with their download size, and the chosen one's live status.
            { ...model, text: [model.text[0], ['p', 'Downloaded. Not loaded.', null]],
@@ -133,7 +157,26 @@ function mapTaggingConcept(reference, { template, phone }) {
            // D133: the persisted suggestion count, on the concept's number row.
            { ...general, text: [['label', 'Suggestions per image', 'tag-suggestions'], ['p', SUGGESTIONS, null]],
                control: { ...general.control, id: 'tag-suggestions', value: '10' } },
+            // D203: the default of each language-model engine (the fixture's saved entry is both), on the concept's
+            // select row.
+            defaultRow('gguf', 'GGUF JoyCaption'), defaultRow('hf', 'HuggingFace JoyCaption'),
        ],
+        // D203: Saved instructions in the concept's setting-row tokens (as D202), Built-in selected and read-only.
+        instructions: { tree: ['div.setting-block-text', 'div.instructions-layout'], key: 'autotag_instructions',
+            text: [['label', 'Saved instructions'], ['p', `${INSTRUCTIONS_DESCRIPTION} ${saved.length} of 20 saved · Built\u2011in is not counted.`]],
+            list: [['Built-in', [['Read-only', 'chip']], 'true'],
+                ...saved.map((entry, index) => [entry.name, index === 0
+                    ? [['Default for GGUF', 'chip blue'], ['Default for HuggingFace', 'chip blue']] : [], 'false'])],
+            listRole: 'listbox',
+            actions: [['+ New', '', false], ['Duplicate', '', false], ['Delete', 'danger', true]],
+            editor: [['Name', 'Built-in', true], ['Text', builtin, true]],
+            note: 'Built-in instructions can’t be changed. Duplicate them to make your own.',
+            layout: phone ? 1 : 2,
+            paddingTop: reference.row.paddingTop, paddingBottom: reference.row.paddingBottom,
+            borderTopWidth: reference.row.borderTopWidth, borderTopColor: reference.row.borderTopColor,
+            label: reference.label,
+            textarea: { fontSize: reference.field.textarea.fontSize, backgroundColor: reference.field.textarea.backgroundColor,
+                borderTopColor: reference.field.textarea.borderTopColor } },
        // D202 (#431): the Skipped tags block in the concept's setting-row tokens: its label and description as a row's,
        // the row's padding and rule above, the concept's field input; an empty list says so.
        skipped: { tree: ['div.setting-block-text', 'div.skip-add', 'p.skip-problem.small', 'div.skip-chips.tags', 'p.skip-preview.small'],
@@ -148,15 +191,15 @@ function mapTaggingConcept(reference, { template, phone }) {
                marginTop: reference.description.marginTop },
            input: { fontSize: '12px', backgroundColor: reference.field.textarea.backgroundColor, color: reference.field.textarea.color,
                borderTopColor: reference.field.textarea.borderTopColor } },
-        // The saved template (the server's default until one is saved) replaces the concept's sample text.
-        field: { ...reference.field, textarea: { ...reference.field.textarea, value: template } },
+        // D203: no template field.
+        field: null,
        // D132: Download (for an engine already on disk, "Download again") and Unload replace the two simulated jobs.
        actions: { ...reference.actions, buttons: [preview, ['Download again', ''], ['Unload', '']] },
        // D134: the prompt-tag batch, reviewed first.
        operations: [{ tree: ['div', 'div.row-actions'], title: 'Tag output images', description: BATCH, actions: [['Review', '']] }],
        // D132 (#398): every select shows its whole chosen option at every width (at 390 the concept's 120px cap cuts
        // them; production lets each grow past it).
-        selectsFit: reference.selectsFit.map(() => true),
+        selectsFit: [...reference.selectsFit, true, true].map(() => true),
    };
 }

@@ -180,7 +223,9 @@ async function productionTagging(page, theme) {
 async function savedTemplate(request, page) {
    const response = await request.get('/prompt_manager/settings');
    await expect(response).toBeOK();
-    return { template: (await response.json()).settings.autotag_template, phone: page.viewportSize().width <= 700 };
+    const { settings } = await response.json();
+    return { builtin: settings.autotag_builtin_instructions, saved: settings.autotag_instructions,
+        phone: page.viewportSize().width <= 700 };
 }

 for (const theme of THEMES) for (const [width, height] of SIZES) {
@@ -204,14 +249,15 @@ for (const theme of THEMES) for (const width of [390, 320]) {
        await page.locator('#workspace-main #tag-existing').selectOption('replace_after_review');
        await page.locator('#workspace-main section.surface').screenshot({ path: testInfo.outputPath(`production-tagging-selects-${theme}-${width}.png`) });
        const selects = page.locator('#workspace-main section.surface > .setting-row > select');
-        await expect(selects).toHaveCount(2);
-        for (let index = 0; index < 2; index += 1) {
+        // D203 adds the two per-engine default selects.
+        await expect(selects).toHaveCount(4);
+        for (let index = 0; index < 4; index += 1) {
            const select = selects.nth(index);
            const values = await select.evaluate(node => [...node.options].map(option => option.value));
            for (const value of values) {
                await select.selectOption(value);
                const measured = await page.evaluate(measureTagging, '#workspace-main');
-                expect(measured.selectsFit, `${await select.getAttribute('id')}=${value}`).toEqual([true, true]);
+                expect(measured.selectsFit, `${await select.getAttribute('id')}=${value}`).toEqual([true, true, true, true]);
                expect(measured.pageScroll, value).toBe(false);
            }
        }
@@ -225,15 +271,16 @@ test('auto-tagging comparison detects mutations', async ({ page, request }) => {
    const expected = mapTaggingConcept(concept, saved);
    const production = await productionTagging(page, 'dark');
    expect(diffInventory(expected, production)).toEqual([]);
-    // Unmapped, the section differs only where D132, D133, D134 and D202 are recorded (and the saved template's text).
+    // Unmapped, the section differs only where D132, D133, D134, D202 and D203 are recorded (and the saved template's text).
    // (The concept has no Skipped tags block, so every path under it is one D202 difference.)
-    expect(diffInventory(concept, production).map(item => (item.path.startsWith('skipped') ? 'skipped'
+    expect(diffInventory(concept, production).map(item => (/^(skipped|instructions|field)\b/.test(item.path) ? item.path.split('.')[0]
        : item.path.split('.').slice(0, 3).join('.')))
        .filter((path, index, all) => all.indexOf(path) === index).sort()).toEqual([
-        'actions.buttons.1', 'actions.buttons.2', 'field.textarea.value', 'operations.0.actions', 'operations.0.description',
-        'operations.0.title', 'operations.0.tree', 'operations.length', 'rows.0.control', 'rows.0.text', 'rows.4.control', 'rows.4.controlBelow',
-        'rows.4.flexWrap', 'rows.4.text', 'rows.4.tree', 'rows.length', 'skipped', 'tree.6', 'tree.7', 'tree.8', 'tree.9', 'tree.10',
-        'tree.length'].sort());
+        'actions.buttons.1', 'actions.buttons.2', 'field', 'instructions', 'operations.0.actions', 'operations.0.description',
+        'operations.0.title', 'operations.0.tree', 'operations.length', 'rows.0.control', 'rows.0.text',
+        ...[4, 5, 6].flatMap(row => ['control', 'controlBelow', 'flexWrap', 'text', 'tree'].map(key => `rows.${row}.${key}`)),
+        'rows.length', 'selectsFit.2', 'selectsFit.3', 'selectsFit.length', 'skipped',
+        ...Array.from({ length: 8 }, (_, index) => `tree.${index + 6}`), 'tree.length'].sort());
    const measure = () => page.evaluate(measureTagging, '#workspace-main');
    const paths = async () => diffInventory(expected, await measure()).map(item => item.path);
    // A removed row.
@@ -284,8 +331,8 @@ test('auto-tagging at 390 wraps only the engine row', async ({ page, request })
    const concept = await conceptTagging(page, 'dark');
    const production = await productionTagging(page, 'dark');
    expect(diffInventory(mapTaggingConcept(concept, await savedTemplate(request, page)), production)).toEqual([]);
-    expect(production.rows.map(row => row.flexWrap)).toEqual(['wrap', 'nowrap', 'nowrap', 'nowrap', 'nowrap']);
-    expect(production.selectsFit).toEqual([true, true]);
+    expect(production.rows.map(row => row.flexWrap)).toEqual(['wrap', 'nowrap', 'nowrap', 'nowrap', 'nowrap', 'nowrap', 'nowrap']);
+    expect(production.selectsFit).toEqual([true, true, true, true]);
 });

 /** Runs in the page: the open review dialog: its title, body and the concept's tokens. */
@@ -92,6 +92,8 @@ export function cardActionsInventory(card) {
    };
 }

+// #431: the fixture's saved "Describe the image" entry, the default of both engines (workspace_tagging_fixture.py).
+export const FIXTURE_INSTRUCTIONS_ID='d35c71be0a1e';
 // D84 (plan D61): the legacy engines' values, labels and sizes, GGUF JoyCaption in the concept's Ollama slot.
 const MODEL_LABELS=Object.freeze({'wd14-swinv2':['wd14-swinv2','WD14 SwinV2 · ~400 MB'],'wd14-vit':['wd14-vit','WD14 ViT · ~400 MB'],
    ollama:['gguf','GGUF JoyCaption (Recommended) · ~4.5 GB'],huggingface:['hf','HuggingFace JoyCaption · ~16 GB']});
@@ -106,17 +108,24 @@ const CONCEPT_LABELS=Object.freeze({'WD14 SwinV2 · fast classifier':'WD14 SwinV
 *   (`chip`: a concept `.chip` inventory, the heading's size chip) around the row's own text (12px) in the checked
 *   row's colours (accent border, `--soft-blue`);
 * - D84 (plan D61): the legacy engine labels and values, and the server's default instructions (`instructions`);
+ * - D204 (#431): a "Saved instructions" select (`picker`: its value and options) before the instructions, on the
+ *   concept's select field tokens;
 * - D91 (plan D68): a Suggestions count field after the model's own fields, on the concept's number field tokens
 *   (`numberField`: the concept's General confidence field) with the configured count (`limit`);
 * - D29: the prototype's "Sample suggestions from …" status reads "Suggestions from …".
 * The opened state is compared unmapped: both show the concept's on-screen "Generate suggestions with the selected
 * model before approving." (its renderTagModelOptions, a1062–1076, replaces the markup's sentence at once).
 */
-export function mapConceptTagging(reference,{instructions,limit=10,chip,numberField}) {
+export function mapConceptTagging(reference,{instructions,limit=10,chip,numberField,
+    picker={value:FIXTURE_INSTRUCTIONS_ID,options:[['builtin','Built-in'],[FIXTURE_INSTRUCTIONS_ID,`${instructions} · default`]]}}) {
    const [select,...own]=reference.modelPanel.fields;
+    // D204 (#431): a "Saved instructions" select on the concept's select field, before the instructions.
+    const pickField={...select,label:'Saved instructions',control:{...select.control,id:'image-tag-instructions-pick',
+        value:picker.value,options:picker.options}};
    const suggestionsField={...numberField,label:'Suggestions',control:{...numberField.control,id:'image-suggestion-limit',
        value:String(limit),min:'1',max:'100',step:'1'}};
-    const mappedOwn=own.map(field=>field.control.id==='image-tag-instructions'?{...field,control:{...field.control,value:instructions}}:field);
+    const mappedOwn=own.flatMap(field=>field.control.id==='image-tag-instructions'
+        ?[pickField,{...field,control:{...field.control,value:instructions}}]:[field]);
    const rows=reference.suggestions.rows.map(row=>({...row,
        control:row.control?.kind==='checkbox'&&row.control.checked?{kind:'remove',label:`Remove ${row.name}`}:row.control,
        borderTopLeftRadius:chip.borderTopLeftRadius}));
@@ -64,7 +64,9 @@ test('the section shows the concept rows; Metadata cache follows Q5 (D102)', asy
            item.querySelector('.row-actions > button').textContent, item.querySelector('.row-actions > button').className]),
    ]))).toEqual([
        ['Database', [['Integrity & relationship checks', 'Check', ''], ['Duplicate prompt text', 'Review plan', ''],
-            ['Optimize database', 'Review plan', ''], ['Unused prompt components', 'Review plan', 'danger']]],
+            ['Optimize database', 'Review plan', ''], ['Unused prompt components', 'Review plan', 'danger'],
+            // D192 (#550): beyond the concept.
+            ['Pair category and tags', 'Review plan', '']]],
        ['Images & cache', [['Missing-file links', 'Review plan', 'danger'], ['Duplicate image files', 'Find duplicates', ''],
            ['Thumbnail cache', 'Review options', ''], ['Metadata cache', 'Review plan', '']]],
    ]);
@@ -177,6 +179,70 @@ test("plan dialog shows the server's scope, protected, backup policy and media l
        expect(await serverJson(request, '/__test__/system/digest')).toEqual(before);
    });

+test('D192: Pair category and tags reviews old Pair prompts, keeps an edited one and fills the other (#550)',
+    async ({ page, request }) => {
+        await expect(await request.post('/__test__/system/pair-metadata')).toBeOK();
+        const answers = [];
+        page.on('response', response => { if (response.url().endsWith(PREVIEW_URL)) answers.push(response.json()); });
+        await openMaintenance(page);
+        const pairRow = row(page, 'Pair category and tags');
+        await expect(pairRow.locator('p')).toHaveText('Fill an empty category or tags on prompts older Pair node runs saved, ' +
+            'from their saved pairs. Only empty fields of never-edited prompts.');
+        await pairRow.getByRole('button', { name: 'Review plan', exact: true }).click();
+        const plan = dialog(page);
+        await expect(plan.locator('#modal-body > h3')).toHaveText('Pair category and tags');
+        const answer = await answers[0];
+        expect(answer.operation).toBe('pair_metadata');
+        expect(await gridOf(page)).toEqual([
+            ['Scope', '1 prompt to fill: 1 category, 1 tag set'],
+            ['Protected', '1 edited after it was saved'],
+            ['Backup', `Create and verify before changes (${answer.backup.destination_label})`],
+            ['Media on disk', 'No image file or saved pair is changed.'],
+        ]);
+        await expect(plan.locator('details > summary')).toHaveText('Listed records (3)');
+        await plan.locator('details > summary').click();
+        // Protected rows come first, the Record row last.
+        const lines = (await plan.locator('details > pre').textContent()).split('\n');
+        expect(lines).toHaveLength(3);
+        expect(lines[0]).toBe('S550 harbor · Kept: edited after it was saved; its empty category or tags may be intentional');
+        expect(lines[1]).toMatch(/^S550 lantern · Fills category “night” and 2 tags: s550-glow, s550-warm \(pair \d+\)$/);
+        expect(lines[2]).toMatch(/^Record · The job's report lists every filled field\. Download it to keep it/);
+        await plan.getByRole('button', { name: 'Apply reviewed operation', exact: true }).click();
+        await expect(dialog(page)).toHaveCount(0);
+        await expect(page).toHaveURL(/#\/activity\/[0-9a-f]{32}$/);
+        const job = await ended(request, page.url().split('/').pop());
+        expect([job.title, job.state, job.counters.changed, job.counters.protected])
+            .toEqual(['Pair category and tags', 'finished', 1, 1]);
+        const main = page.locator('#workspace-main');
+        await expect(main.locator('h1')).toHaveText('Pair category and tags');
+        await expect(main.getByRole('button', { name: 'Download report', exact: true })).toBeVisible();
+        // #550 live test: the Changed group lists the path-less record rows as plain text, never an open action.
+        const results = main.getByRole('region', { name: 'Results', exact: true });
+        await results.locator('.outcome-list > button').filter({ hasText: 'Changed' }).click();
+        const records = results.locator('.outcome-files > .file-row');
+        await expect(records).toHaveCount(1);
+        await expect(records.first()).toHaveText(/^Prompt \d+: category “night”; tags s550-glow, s550-warm$/);
+        expect(await records.first().evaluate(node => node.localName)).toBe('div');
+        await expect(results.locator('.outcome-files button')).toHaveCount(0);
+        await expect(results.getByRole('searchbox', { name: 'Filter results' })).toHaveAttribute('placeholder', 'Filter records…');
+        // Protected lists each kept prompt with the review's reason (#550 live re-check).
+        await results.locator('.outcome-list > button').filter({ hasText: 'Protected' }).click();
+        await expect(records).toHaveCount(1);
+        await expect(records.first()).toHaveText(
+            /^Prompt \d+: kept, edited after it was saved; its empty category or tags may be intentional$/);
+        // An empty group says records, not files.
+        await results.locator('.outcome-list > button').filter({ hasText: 'Errors' }).click();
+        await expect(results.locator('.outcome-files > p.empty-state')).toHaveText('No records in this group.');
+        const library = await serverJson(request, '/prompt_manager/library');
+        const lantern = library.items.find(item => item.text === 'S550 lantern');
+        const harbor = library.items.find(item => item.text === 'S550 harbor');
+        const filled = (await serverJson(request, `/prompt_manager/library/${lantern.id}?archive=all`)).positive;
+        expect([filled.category, [...filled.tags].sort()]).toEqual(['night', ['s550-glow', 's550-warm']]);
+        expect((await serverJson(request, `/prompt_manager/library/${harbor.id}?archive=all`)).positive.category).toBeFalsy();
+        await page.goto(`${workspace}#/library`);
+        await expect(page.locator(`article[data-prompt-id="${lantern.id}"] .card-title > .chip`)).toHaveText('night');
+    });
+
 test('a plan with nothing to do shows only Close, never Apply', async ({ page, request }) => {
    const applies = [];
    page.on('request', item => { if (item.url().endsWith(APPLY_URL)) applies.push(item.url()); });
@@ -112,13 +112,14 @@ test('model options are the four real engines with size and the description show
    await expect(status(page)).toHaveText('Unsaved changes.');
    // The other rows keep the concept's copy and the saved values (D133 adds Suggestions per image).
    expect(await surface(page).locator(':scope > .setting-row label').allTextContents()).toEqual(['Tagging model', 'Existing tags',
-        'General-tag confidence', 'Character-tag confidence', 'Suggestions per image']);
+        'General-tag confidence', 'Character-tag confidence', 'Suggestions per image', 'Default for GGUF JoyCaption',
+        'Default for HuggingFace JoyCaption']);
    await expect(page.locator('#tag-existing')).toHaveValue('skip');
    await expect(page.locator('#threshold-general')).toHaveValue('0.35');
    await expect(page.locator('#threshold-character')).toHaveValue('0.85');
    await expect(page.locator('#tag-suggestions')).toHaveValue('10');
-    const settings = await serverJson(request, SETTINGS_URL);
-    await expect(page.locator('#tag-template')).toHaveValue(settings.settings.autotag_template);
+    // D203 (#431): Saved instructions replace the template field.
+    await expect(page.locator('#tag-template')).toHaveCount(0);
    // Unload is offered only while a model is loaded (none is).
    await expect(actionOf(page, 'Unload')).toBeDisabled();
 });
@@ -500,3 +501,74 @@ test('skipped tags preview checks library tags only without a label list, and a
    await expect(skippedBlock(page)).toHaveAttribute('aria-invalid', 'true');
    await page.unrouteAll({ behavior: 'ignoreErrors' });
 });
+
+// D203 (#431): Saved instructions: Built-in read-only, New, edit, per-engine defaults, Delete resets a default, Save
+// preferences and a reload; the server pairs the two keys. D205: the batch review names the engine's default.
+const instructionOption = (page, name) => page.locator('#instruction-list [role="option"]').filter({ has: page.locator(`span:text-is("${name}")`) });
+
+test('saved instructions: new, edit, per-engine default, delete, save and reload (D203)', async ({ page, request }) => {
+    await openTagging(page);
+    const settings = (await serverJson(request, SETTINGS_URL)).settings;
+    await expect(page.locator('#instructions-count')).toHaveText('1 of 20 saved · Built\u2011in is not counted.');
+    await expect(page.locator('#instruction-list [role="option"] > span:first-child')).toHaveText(['Built-in', 'Describe the image']);
+    await expect(page.locator('#instruction-name')).toHaveValue('Built-in');
+    await expect(page.locator('#instruction-text')).toHaveValue(settings.autotag_builtin_instructions);
+    await expect(page.locator('#instruction-text')).toHaveAttribute('readonly', '');
+    await expect(page.locator('#instruction-delete')).toBeDisabled();
+    await expect(page.locator('#instruction-default-gguf')).toHaveValue(settings.autotag_instructions[0].id);
+    // + New, then name and text it, and make it HuggingFace's default.
+    await page.locator('#instruction-new').click();
+    await expect(page.locator('#instruction-name')).toHaveValue('New instructions');
+    await expect(page.locator('#instruction-note')).toHaveText('The text must not be empty.');
+    await page.locator('#instruction-name').fill('Photo realism');
+    await page.locator('#instruction-text').fill('Tag camera angle and lighting.');
+    await expect(page.locator('#instruction-text').locator('xpath=..').locator('label .muted')).toHaveText('30 of 4,000 characters');
+    await page.locator('#instruction-default-hf').selectOption({ label: 'Photo realism' });
+    await expect(instructionOption(page, 'Photo realism').locator('.chip')).toHaveText(['Default for HuggingFace']);
+    await expect(status(page)).toHaveText('Unsaved changes.');
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved to the server configuration.');
+    let saved = (await serverJson(request, SETTINGS_URL)).settings;
+    expect(saved.autotag_instructions.map(entry => [entry.name, entry.text])).toEqual([['Describe the image', 'Describe the image'],
+        ['Photo realism', 'Tag camera angle and lighting.']]);
+    expect(saved.autotag_default_instructions.hf).toBe(saved.autotag_instructions[1].id);
+    // A reload shows the saved list; deleting GGUF's default resets it to Built-in and says so.
+    await openTagging(page);
+    await instructionOption(page, 'Describe the image').click();
+    await page.locator('#instruction-delete').click();
+    await expect(page.locator('#instruction-reset')).toHaveText('GGUF now uses Built-in.');
+    await expect(page.locator('#instruction-default-gguf')).toHaveValue('builtin');
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved to the server configuration.');
+    saved = (await serverJson(request, SETTINGS_URL)).settings;
+    expect(saved.autotag_instructions.map(entry => entry.name)).toEqual(['Photo realism']);
+    expect(saved.autotag_default_instructions.gguf).toBe('builtin');
+    expect(saved.autotag_template).toBe(saved.autotag_builtin_instructions);
+});
+
+test('a refused instructions save names the entry and highlights the block (D203)', async ({ page }) => {
+    await openTagging(page);
+    await page.locator('#instruction-duplicate').click();
+    await page.locator('#instruction-name').fill('describe the IMAGE');
+    await expect(page.locator('#instruction-note')).toHaveText('The name “describe the IMAGE” is already used.');
+    await save(page).click();
+    await expect(status(page)).toHaveText('Saved instructions: entry 2 name “describe the IMAGE” is already used.');
+    await expect(surface(page).locator('.setting-block[data-setting="tag-instructions"]')).toHaveAttribute('aria-invalid', 'true');
+});
+
+test('the batch review names the language model\'s default instructions (D205)', async ({ page }) => {
+    await openTagging(page);
+    await page.locator('#tag-model').selectOption('gguf');
+    await page.locator('#tag-existing').selectOption('merge');
+    const answer = page.waitForResponse(item => item.url().endsWith(PREVIEW_URL));
+    await reviewButton(page).click();
+    await answer;
+    await expect(dialog(page).locator('#modal-title')).toHaveText('Review tag output images');
+    const grid = await gridOf(page);
+    expect(grid.slice(-3)).toEqual([['Instructions', 'Describe the image'], ['Settings', 'Up to 10 tags per image'],
+        grid.at(-1)]);
+    // The batch sends the default's text.
+    const start = page.waitForRequest(item => item.url().endsWith('/prompt_manager/jobs/autotag'));
+    await dialog(page).getByRole('button', { name: 'Start tagging', exact: true }).click();
+    expect((await start).postDataJSON().options).toEqual({ instructions: 'Describe the image' });
+});
@@ -341,3 +341,21 @@ test('a running scan makes the start report busy', async ({ page, request }) =>
        await request.post(`/__test__/jobs/${scan.job.id}/finish`, { data: { state: 'finished' } });
    }
 });
+
+// D204 (#431): Auto-tag selected has the same picker; the job sends the text the dialog shows.
+test('Auto-tag selected picks saved instructions and sends the text shown (D204)', async ({ page }) => {
+    await select(page, FIRST);
+    await barButton(page, 'Auto-tag selected').click();
+    await expect(title(page)).toHaveText('Auto-tag selected images');
+    const body = modal(page).locator('#modal-body');
+    await body.getByRole('combobox', { name: 'Tagging model', exact: true }).selectOption('gguf');
+    const pick = body.getByRole('combobox', { name: 'Saved instructions', exact: true });
+    await expect(pick).toHaveAttribute('id', 'bulk-tag-instructions-pick');
+    await expect(pick.locator('option')).toHaveText(['Built-in', 'Describe the image · default']);
+    const text = body.getByRole('textbox', { name: 'Tagging instructions', exact: true });
+    await text.fill('Bulk one-off.');
+    await expect(pick.locator('option:checked')).toHaveText('Edited for this run');
+    const started = jobStart(page);
+    await actionButtons(page).filter({ hasText: 'Start auto-tagging' }).click();
+    expect((await started).postDataJSON().options.instructions).toBe('Bulk one-off.');
+});
@@ -4,7 +4,7 @@
 import { startCoverage, saveCoverage } from '../../tools/vendor/browser-coverage.mjs';
 import { test, expect } from './fixtures.mjs';
 import { saveImageTags } from './concept-inventory.mjs';
-import { taggingInventory } from './tagging-canonical-comparison.mjs';
+import { FIXTURE_INSTRUCTIONS_ID, taggingInventory } from './tagging-canonical-comparison.mjs';

 const images = '/prompt_manager/workspace#/images';
 const MODULE = '/prompt_manager/js/workspace/image-tagging.mjs';
@@ -861,3 +861,49 @@ test('suggestions omit skipped tags and say how many were hidden', async ({ page
    await expect(chips(page).locator(':scope > span:first-child')).toHaveText(['sandstone', 'arch', 'sky', 'dune']);
    await expect(dialog(page).locator('#tag-suggestions > p.small')).toHaveText(`${CHIP_HINT} 2 skipped tags were not suggested.`);
 });
+
+// D204 (#431): the Saved instructions select above Tagging instructions: the engine default, a pick, a one-off edit
+// ("Edited for this run" and the muted note), an engine switch resets, WD14 hides both; Generate sends the text shown.
+test('the saved instructions picker fills, edits one-off and resets per engine (D204)', async ({ page, request }) => {
+    const settings = await (await request.get('/prompt_manager/settings')).json();
+    const builtin = settings.settings.autotag_builtin_instructions;
+    await openTag(page);
+    const options = dialog(page).locator('#image-tag-model-options');
+    const pick = options.getByRole('combobox', { name: 'Saved instructions', exact: true });
+    const text = options.getByRole('textbox', { name: 'Tagging instructions', exact: true });
+    const note = options.locator('.instructions-edited');
+    await expect(pick).toHaveCount(0);
+    await model(page).selectOption('gguf');
+    await expect(pick.locator('option')).toHaveText(['Built-in', 'Describe the image · default']);
+    await expect(pick).toHaveAttribute('id', 'image-tag-instructions-pick');
+    await expect(text).toHaveValue('Describe the image');
+    await expect(note).toBeHidden();
+    // A keyboard pick (the select focused) keeps focus on the select the fields are re-rendered with.
+    await pick.focus();
+    await pick.selectOption('builtin');
+    await expect(text).toHaveValue(builtin);
+    await expect(pick).toBeFocused();
+    await text.fill('Only the sky.');
+    await expect(text).toHaveAttribute('aria-describedby', 'image-tag-instructions-pick-note');
+    await expect(pick.locator('option:checked')).toHaveText('Edited for this run');
+    await expect(pick.locator('option[value="edited"]')).toBeDisabled();
+    await expect(note).toHaveText('Edits apply to this run only. Manage saved instructions in System › Auto-tagging.');
+    await expect(text).toBeFocused();
+    // Generate sends the edited text; the saved entries are unchanged.
+    const sent = page.waitForRequest(item => item.url().endsWith('/image-annotations/suggest'));
+    await generate(page).click();
+    expect((await sent).postDataJSON().options.instructions).toBe('Only the sky.');
+    // Choosing an entry replaces the edit; switching engines starts from the new engine's default.
+    await pick.selectOption('builtin');
+    await expect(text).toHaveValue(builtin);
+    await expect(note).toBeHidden();
+    await text.fill('Edited again.');
+    await model(page).selectOption('hf');
+    await expect(text).toHaveValue('Describe the image');
+    await expect(pick).toHaveValue(FIXTURE_INSTRUCTIONS_ID);
+    await model(page).selectOption('wd14-vit');
+    await expect(pick).toHaveCount(0);
+    await expect(text).toHaveCount(0);
+    expect((await (await request.get('/prompt_manager/settings')).json()).settings.autotag_instructions)
+        .toEqual(settings.settings.autotag_instructions);
+});
@@ -41,6 +41,11 @@ read. These per-server hooks only change what a System test needs on top:
 - ``POST /__test__/system/duplicate-prompts`` (S7) adds two prompts whose
  text differs only in case and spacing (a duplicate prompt text group);
  ``{"again": true}`` adds a third, so a reviewed plan no longer matches;
+- ``POST /__test__/system/pair-metadata`` (#550) saves two saved pairs the
+  way the Pair node did before #546 (the pair holds the category and tags,
+  its new positive prompt none): ``S550 lantern`` (category ``night``, tags
+  ``s550-glow``, ``s550-warm``) fills; ``S550 harbor`` was edited after it was
+  saved, so the plan keeps it;
 - ``POST /__test__/system/duplicate-files`` (S7) writes one PNG's bytes three
  times: ``output/s7-dupes/same.png``, ``input/s7-dupes/same.png`` (the same
  relative path in the other source) and ``output/s7-dupes/copy.png``;
@@ -344,6 +349,25 @@ def register_system_commands(app, routes, api, root: Path):
            conn.commit()
        return web.json_response({"success": True})

+    @routes.post("/__test__/system/pair-metadata")
+    async def pair_metadata(request):
+        def seed():
+            api.db.save_prompt_pair(
+                "S550 lantern",
+                "S550 blurry",
+                category="night",
+                tags=["s550-glow", "s550-warm"],
+            )
+            api.db.save_prompt_pair("S550 harbor", category="night")
+            with api.db.model.get_connection() as conn:
+                conn.execute(
+                    "UPDATE prompts SET updated_at='2099-01-01T00:00:00+00:00' "
+                    "WHERE text='S550 harbor'"
+                )
+
+        await api._run_in_executor(seed)
+        return web.json_response({"success": True})
+
    @routes.post("/__test__/system/duplicate-files")
    async def duplicate_files(request):
        body = await request.json() if request.can_read_body else {}
@@ -391,10 +391,15 @@ DOWNLOAD_HOLD_LIMIT_S = 60
 DEFAULTS = (0.35, 0.85, 10)


+# The saved "Describe the image" entry's id (#431).
+FIXTURE_INSTRUCTIONS_ID = "d35c71be0a1e"
+
+
 def _set_defaults(model, values) -> None:
    """Set the saved tagging defaults (``AutotagConfig``, #328); a reset also
-    puts back the saved model, batch policy and template (the fake model's
-    short instructions, which the concept comparisons show)."""
+    puts back the saved model, batch policy, skipped tags and instructions
+    (the fake model's short instructions, which the concept comparisons
+    show)."""
    from py.config import AutotagConfig

    general, character, limit = values
@@ -404,7 +409,21 @@ def _set_defaults(model, values) -> None:
    if values == DEFAULTS:
        AutotagConfig.MODEL_TYPE = "wd14-swinv2"
        AutotagConfig.EXISTING = "skip"
-        AutotagConfig.TEMPLATE = model.default_prompt
+        # #431: Built-in is always the shipped text, so the fake model's short
+        # instructions are a saved entry, the default of both engines (the
+        # concept comparisons show it).
+        AutotagConfig.INSTRUCTIONS = (
+            {
+                "id": FIXTURE_INSTRUCTIONS_ID,
+                "name": model.default_prompt,
+                "text": model.default_prompt,
+            },
+        )
+        AutotagConfig.DEFAULT_INSTRUCTIONS = {
+            "gguf": FIXTURE_INSTRUCTIONS_ID,
+            "hf": FIXTURE_INSTRUCTIONS_ID,
+        }
+        AutotagConfig._LEGACY_TEMPLATE = None
        AutotagConfig.SKIPPED_TAGS = ()