@ihyeon/flow-qa 0.1.3 → 0.2.0

package/dist/src/schema.js

@@ -12,6 +12,9 @@ export const locatorSchema = z.discriminatedUnion('by', [
 ]);
 export const stepSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('open'), path: text.refine((v) => v.startsWith('/') && !v.startsWith('//') && !v.includes('\\'), 'Use an app-relative path starting with /.') }).strict(),
+    z.object({ type: z.literal('launchApp') }).strict(),
+    z.object({ type: z.literal('back') }).strict(),
+    z.object({ type: z.literal('swipe'), direction: z.enum(['up', 'down', 'left', 'right']) }).strict(),
     z.object({ type: z.literal('act'), instruction: text }).strict(),
     z.object({ type: z.literal('click'), locator: locatorSchema }).strict(),
     z.object({ type: z.literal('fill'), locator: locatorSchema, value: z.string().max(8192) }).strict(),
@@ -30,6 +33,7 @@ const caseSchema = z.object({
 }).strict();
 export const suiteSchema = z.object({
     schemaVersion: z.literal('flow-qa/suite-1'),
+    platform: z.enum(['web', 'mobile']).optional(),
     id: idSchema,
     title: text,
     source: z.object({ file: text, sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict().optional(),
@@ -49,6 +53,13 @@ export const suiteSchema = z.object({
             ctx.addIssue({ code: 'custom', path: ['cases', index, 'requirementIds'], message: 'Unknown requirement ID.' });
         if (!test.questions.length && !test.steps.some((s) => s.type.startsWith('assert')))
             ctx.addIssue({ code: 'custom', path: ['cases', index, 'steps'], message: 'A runnable case needs an explicit assertion.' });
+        test.steps.forEach((step, stepIndex) => {
+            const invalid = suite.platform === 'mobile'
+                ? step.type === 'open' || step.type === 'assertUrl'
+                : step.type === 'launchApp' || step.type === 'back' || step.type === 'swipe';
+            if (invalid)
+                ctx.addIssue({ code: 'custom', path: ['cases', index, 'steps', stepIndex, 'type'], message: `The ${step.type} step is not available on ${suite.platform ?? 'web'} suites.` });
+        });
     });
 });
 export const modelSchema = z.object({
@@ -57,10 +68,19 @@ export const modelSchema = z.object({
     apiKeyEnv: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional(),
 }).strict();
 export const plannerSchema = modelSchema;
-export const targetSchema = z.object({
+const webTargetSchema = z.object({
     url: httpURL,
     description: z.string().max(2000).default(''),
+    kind: z.literal('web').optional(),
 }).strict();
+const mobileTargetSchema = z.object({
+    kind: z.literal('mobile'),
+    platform: z.enum(['ios', 'android']),
+    bundleId: z.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'Use a native app ID without spaces or control characters.'),
+    device: z.string().trim().min(1).max(200).refine((value) => !/[\p{Cc}\p{Cf}]/u.test(value), 'Device names cannot contain control characters.'),
+    description: z.string().max(2000).default(''),
+}).strict();
+export const targetSchema = z.union([webTargetSchema, mobileTargetSchema]);
 export const configSchema = z.object({
     schemaVersion: z.literal('flow-qa/config-1'),
     targets: z.record(idSchema, targetSchema),

package/dist/src/targets.js

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+export function targetKind(target) {
+    return target.kind === 'mobile' ? 'mobile' : 'web';
+}
+export function targetLabel(target) {
+    return target.kind === 'mobile'
+        ? `${target.platform} · ${target.bundleId} · ${target.device}`
+        : target.url;
+}
+export function targetFingerprint(target) {
+    const identity = target.kind === 'mobile'
+        ? { kind: 'mobile', platform: target.platform, bundleId: target.bundleId, device: target.device }
+        : { kind: 'web', url: target.url };
+    return createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+}
+export function reportTarget(name, target) {
+    return target.kind === 'mobile'
+        ? { name, kind: 'mobile', platform: target.platform, bundleId: target.bundleId, device: target.device }
+        : { name, url: target.url, ...(target.kind === 'web' ? { kind: 'web' } : {}) };
+}

package/dist/src/ui/public/app.js

@@ -55,10 +55,16 @@
     $('sidebar').classList.remove('nav-open'); $('nav-toggle').setAttribute('aria-expanded', 'false');
     if (name === 'history') renderHistory();
   }
+  function suitePlatform() { return app.draft?.platform || 'web'; }
+  function targetPlatform(target) { return target?.kind === 'mobile' ? 'mobile' : 'web'; }
+  function selectedTarget() { return app.displayTargets.find((target) => target.name === $('target-select').value); }
+  function targetLabel(target) { return target?.kind === 'mobile' ? `${target.platform === 'ios' ? 'iOS' : 'Android'} · ${target.bundleId} · ${target.device}` : target?.url || ''; }
+  function targetDisplay(target) { return `${target?.name || t('app.noTarget')} · ${targetLabel(target)}`; }
+  function compatibleTarget() { const target = selectedTarget(); return target && targetPlatform(target) === suitePlatform(); }
   function readiness() {
     const active = app.state?.active;
     const ready = !!app.draft && !!app.script && !app.stale && !app.dirty;
-    $('run-btn').disabled = !app.connected || !ready || !app.savedFile || !app.savedHash || !$('review-checkbox').checked || !$('target-select').value || !!active || app.busy;
+    $('run-btn').disabled = !app.connected || !ready || !app.savedFile || !app.savedHash || !$('review-checkbox').checked || !compatibleTarget() || !!active || app.busy;
     $('save-btn').disabled = !ready || app.busy;
     $('script-download').disabled = !ready;
     for (const id of ['stop-btn', 'global-stop-btn']) {
@@ -72,6 +78,8 @@
     $('flow-input').disabled = app.busy;
     $('suite-editor').disabled = app.busy;
     $('prompt-btn').disabled = app.busy;
+    $('scenario-platform').disabled = app.busy;
+    $('mobile-setup-hint').hidden = suitePlatform() !== 'mobile' && $('scenario-platform').value !== 'mobile';
     $('run-readiness').textContent = t(!app.connected ? 'app.connectionRequired'
       : active ? (active.status === 'stopping' ? 'app.stopping' : active.kind === 'plan' ? 'app.planning' : 'app.running')
       : app.stale ? 'app.stale'
@@ -79,6 +87,7 @@
       : !ready ? 'app.needValidated'
       : !app.savedFile || !app.savedHash ? 'app.needSaved'
       : !$('target-select').value ? 'app.needTarget'
+      : !compatibleTarget() ? 'app.platformMismatch'
       : !$('review-checkbox').checked ? 'app.needReview' : 'app.ready');
     const cases = app.draft?.cases || [];
     const blocked = cases.filter((item) => item.questions?.length || (item.steps.some((step) => ['act', 'assertAgent'].includes(step.type)) && !app.state?.models?.agent?.keyReady)).length;
@@ -98,6 +107,9 @@
     const target = locatorText(step.locator);
     switch (step.type) {
       case 'open': return t('app.stepOpen', { path: step.path });
+      case 'launchApp': return t('app.stepLaunchApp');
+      case 'back': return t('app.stepBack');
+      case 'swipe': return t('app.stepSwipe', { direction: step.direction });
       case 'click': return t('app.stepClick', { target });
       case 'fill': return t('app.stepFill', { target, value: step.value });
       case 'assertVisible': return t(step.visible === false ? 'app.stepHidden' : 'app.stepVisible', { target });
@@ -137,23 +149,24 @@
   function setDraft(suite, script, origin, sourceFlow = '', savedFile = '', savedHash = '') {
     app.draft = suite; app.script = script; app.origin = origin; app.sourceFlow = sourceFlow; app.boundSource = suite.source ? { ...suite.source } : null; app.savedFile = savedFile; app.savedHash = savedHash; app.stale = false; app.dirty = false;
     $('suite-editor').value = JSON.stringify(suite, null, 2);
+    $('scenario-platform').value = suite.platform || 'web';
     $('review-checkbox').checked = false;
     summarize(suite); readiness();
   }
   function targetOptions() {
     const selected = $('target-select').value;
-    const previousURL = app.displayTargets.find((item) => item.name === selected)?.url;
+    const previousFingerprint = app.displayTargets.find((item) => item.name === selected)?.targetFingerprint;
     app.displayTargets = (app.state?.targets || []).map((target) => ({ ...target }));
     replace($('target-select'), el('option', '', t('scenario.selectTarget')));
     $('target-select').firstChild.value = '';
-    for (const target of app.state?.targets || []) { const option = el('option', '', target.name); option.value = target.name; $('target-select').append(option); }
+    for (const target of app.state?.targets || []) { const option = el('option', '', targetDisplay(target)); option.value = target.name; $('target-select').append(option); }
     if ((app.state?.targets || []).some((x) => x.name === selected)) $('target-select').value = selected;
-    if (previousURL !== app.displayTargets.find((item) => item.name === selected)?.url) $('review-checkbox').checked = false;
+    if (previousFingerprint !== app.displayTargets.find((item) => item.name === selected)?.targetFingerprint) $('review-checkbox').checked = false;
     targetDescription();
     const list = $('target-list'); replace(list);
-    for (const target of app.state?.targets || []) { const row = el('div', 'settings-entry'); row.append(el('strong', '', target.name), document.createTextNode(` · ${target.url}${target.description ? ` · ${target.description}` : ''}`)); list.append(row); }
+    for (const target of app.state?.targets || []) { const row = el('div', 'settings-entry'); row.append(el('strong', '', target.name), document.createTextNode(` · ${targetLabel(target)}${target.description ? ` · ${target.description}` : ''}`)); list.append(row); }
   }
-  function targetDescription() { const target = app.displayTargets.find((item) => item.name === $('target-select').value); $('target-description').textContent = target ? `${target.url}${target.description ? ` · ${target.description}` : ''}` : t('scenario.targetHint'); readiness(); }
+  function targetDescription() { const target = selectedTarget(); $('target-description').textContent = target ? `${targetLabel(target)}${target.description ? ` · ${target.description}` : ''}` : t('scenario.targetHint'); readiness(); }
   function modelDescription(role) {
     const model = app.state?.models?.[role] || {};
     const explanation = t(role === 'planner' ? 'app.modelPlannerHelp' : 'app.modelAgentHelp');
@@ -192,7 +205,7 @@
     const runs = app.state?.runs || [];
     if (!runs.length) { host.append(el('p', 'empty', t(app.state?.active ? 'app.historyActiveEmpty' : 'app.historyEmpty'))); return; }
     for (const run of runs) {
-      const row = el('div', 'list-row'); const copy = el('div'); copy.append(el('strong', '', `${run.suiteId} · ${i18n.status(run.status)}`), el('small', '', t('app.runMeta', { date: formatDate(run.startedAt), target: run.target?.name || t('app.noTarget'), passed: run.passedCount ?? 0, total: run.caseCount ?? 0, id: run.runId })));
+      const row = el('div', 'list-row'); const copy = el('div'); copy.append(el('strong', '', `${run.suiteId} · ${i18n.status(run.status)}`), el('small', '', t('app.runMeta', { date: formatDate(run.startedAt), target: targetDisplay(run.target), passed: run.passedCount ?? 0, total: run.caseCount ?? 0, id: run.runId })));
       const button = el('button', 'button', t('app.viewReport')); button.type = 'button'; button.disabled = run.status === 'running' || run.status === 'stopping'; button.addEventListener('click', () => loadReport(run.runId)); row.append(copy, button); host.append(row);
     }
   }
@@ -226,16 +239,16 @@
     const flow = $('flow-input').value.trim();
     if (!flow) throw localizedError('app.enterFlow');
     if (!app.state?.models?.planner?.configured || app.state.models.planner.kind !== 'openai-compatible' || !app.state.models.planner.keyReady) throw localizedError('app.configurePlanner');
-    const request = ++app.planRequest;
+    const request = ++app.planRequest; const platform = $('scenario-platform').value;
     app.planning = true; renderActive(); noticeKey('app.planStarted');
     try {
-      const result = await api('/api/plan', { flow });
+      const result = await api('/api/plan', { flow, platform });
       if (request !== app.planRequest) { noticeKey('app.planCancelledLate'); return; }
       setDraft(result.suite, result.script, 'generated', flow); noticeKey('app.planComplete');
     } catch (error) { if (request !== app.planRequest) noticeKey('app.planCancelledDraft'); else throw error; }
     finally { app.planning = false; await refresh(false).catch(() => {}); }
   }); }
-  async function prompt() { await work(async () => { const flow = $('flow-input').value.trim(); if (!flow) throw localizedError('app.enterFlow'); const result = await api('/api/prompt', { flow }); download('flow-qa-prompt.md', result.prompt, 'text/markdown'); noticeKey('app.promptDownloaded'); }); }
+  async function prompt() { await work(async () => { const flow = $('flow-input').value.trim(); if (!flow) throw localizedError('app.enterFlow'); const result = await api('/api/prompt', { flow, platform: $('scenario-platform').value }); download('flow-qa-prompt.md', result.prompt, 'text/markdown'); noticeKey('app.promptDownloaded'); }); }
   async function compile() { await work(async () => {
     if (app.stale) throw localizedError('app.compileStale');
     let suite; try { suite = JSON.parse($('suite-editor').value); } catch { throw localizedError('app.invalidJson'); }
@@ -249,7 +262,7 @@
     noticeKey('app.compileComplete');
   }); }
   async function save() { await work(async () => { if (!app.draft || app.dirty || app.stale) throw localizedError('app.needValidated'); const body = { suite: app.draft }; if (!app.boundSource && app.sourceFlow && app.sourceFlow === $('flow-input').value.trim()) body.flow = app.sourceFlow; const result = await api('/api/save', body); const saved = await api(`/api/suite?file=${encodeURIComponent(result.file)}`); $('flow-input').value = saved.flow || ''; setDraft(saved.suite, saved.script, 'library', saved.flow || '', result.file, saved.suiteHash || ''); noticeKey('app.savedSuite', { file: result.file }); await refresh(false); }); }
-  async function run() { await work(async () => { if (!app.draft || !app.script || !app.savedFile || !app.savedHash || app.dirty || app.stale || !$('review-checkbox').checked || !$('target-select').value) throw localizedError('app.runNotReady'); const result = await api('/api/run', { suite: app.savedFile, suiteHash: app.savedHash, targetName: $('target-select').value, targetURL: app.displayTargets.find((target) => target.name === $('target-select').value)?.url }); noticeKey('app.runStarted', { id: result.operationId }); await refresh(false); }); }
+  async function run() { await work(async () => { if (!app.draft || !app.script || !app.savedFile || !app.savedHash || app.dirty || app.stale || !$('review-checkbox').checked || !compatibleTarget()) throw localizedError('app.runNotReady'); const target = selectedTarget(); const result = await api('/api/run', { suite: app.savedFile, suiteHash: app.savedHash, targetName: target.name, targetFingerprint: target.targetFingerprint }); noticeKey('app.runStarted', { id: result.operationId }); await refresh(false); }); }
   async function stop() {
     if (app.stopping || !app.state?.active) return;
     if (app.state.active.kind === 'plan' && app.planning) app.planRequest += 1;
@@ -271,9 +284,9 @@
   }
   function renderReport() {
     const report = app.report; if (!report) return;
-    $('report-heading').textContent = `${report.runId} · ${i18n.status(report.status)} · ${report.target?.name || ''}`;
+    $('report-heading').textContent = `${report.runId} · ${i18n.status(report.status)} · ${targetDisplay(report.target)}`;
     const host = $('report-content'); replace(host);
-    const meta = el('div', 'report-meta'); for (const value of [t('app.reportStatus', { status: i18n.status(report.status) }), t('app.reportTarget', { target: report.target?.name || '' }), t('app.reportStarted', { date: formatDate(report.startedAt) }), t('app.reportFinished', { date: formatDate(report.finishedAt) })]) meta.append(el('span', '', value)); host.append(meta);
+    const meta = el('div', 'report-meta'); for (const value of [t('app.reportStatus', { status: i18n.status(report.status) }), t('app.reportTarget', { target: targetDisplay(report.target) }), t('app.reportStarted', { date: formatDate(report.startedAt) }), t('app.reportFinished', { date: formatDate(report.finishedAt) })]) meta.append(el('span', '', value)); host.append(meta);
     if (report.usage) host.append(el('p', 'hint', t('app.usage', { tokens: report.usage.modelTokens ?? t('app.unavailable'), cost: typeof report.usage.estimatedCostUsd === 'number' ? `$${report.usage.estimatedCostUsd.toFixed(4)}` : t('app.unavailable') })));
     if (report.errors?.length) host.append(el('p', 'report-errors', report.errors.join('\n')));
     for (const item of report.cases || []) {
@@ -302,7 +315,8 @@
   }
   async function saveModel(event) { event.preventDefault(); const form = event.currentTarget; await work(async () => { const values = new FormData(form); const body = { role: form.dataset.role, baseURL: String(values.get('baseURL') || '').trim(), model: String(values.get('model') || '').trim() }; const apiKeyEnv = String(values.get('apiKeyEnv') || '').trim(); if (apiKeyEnv) body.apiKeyEnv = apiKeyEnv; await api('/api/models', body); await refresh(true); noticeKey('app.modelSaved'); }); }
   async function clearModel(role) { await work(async () => { await api('/api/models', { role, clear: true }); await refresh(true); noticeKey('app.modelCleared'); }); }
-  async function saveTarget(event) { event.preventDefault(); const form = event.currentTarget; await work(async () => { const values = new FormData(form); await api('/api/targets', { name: String(values.get('name') || '').trim(), url: String(values.get('url') || '').trim(), description: String(values.get('description') || '').trim() }); form.reset(); await refresh(true); noticeKey('app.targetSaved'); }); }
+  function targetFields() { const mobile = $('target-kind').value !== 'web'; for (const [id, required] of [['target-url-field', !mobile], ['target-bundle-field', mobile], ['target-device-field', mobile]]) { const field = $(id); field.hidden = !required; field.querySelector('input').required = required; } }
+  async function saveTarget(event) { event.preventDefault(); const form = event.currentTarget; await work(async () => { const values = new FormData(form); const kind = String(values.get('kind') || 'web'); const body = { name: String(values.get('name') || '').trim(), description: String(values.get('description') || '').trim() }; if (kind === 'web') body.url = String(values.get('url') || '').trim(); else { body.kind = 'mobile'; body.platform = kind; body.bundleId = String(values.get('bundleId') || '').trim(); body.device = String(values.get('device') || '').trim(); } await api('/api/targets', body); form.reset(); targetFields(); await refresh(true); noticeKey('app.targetSaved'); }); }
   function renderLanguage() {
     const editedModels = [...document.querySelectorAll('.model-form')].map((form) => ({ role: form.dataset.role, values: Object.fromEntries([...form.querySelectorAll('input')].map((input) => [input.name, input.value])) }));
     const focusedModel = document.activeElement?.closest?.('.model-form');
@@ -310,6 +324,8 @@
     $('breadcrumb').textContent = t('app.breadcrumb', { name: t(names[app.view]) });
     const emptyTarget = $('target-select').querySelector('option[value=""]');
     if (emptyTarget) emptyTarget.textContent = t('scenario.selectTarget');
+    for (const option of $('target-select').options) { const target = app.displayTargets.find((item) => item.name === option.value); if (target) option.textContent = targetDisplay(target); }
+    const targetList = $('target-list'); for (const [row, target] of [...targetList.children].map((node, index) => [node, app.displayTargets[index]])) { if (target) row.replaceChildren(el('strong', '', target.name), document.createTextNode(` · ${targetLabel(target)}${target.description ? ` · ${target.description}` : ''}`)); }
     modelForms();
     for (const edited of editedModels) {
       const form = [...document.querySelectorAll('.model-form')].find((item) => item.dataset.role === edited.role);
@@ -340,6 +356,7 @@
       $('suite-editor').focus();
     });
     $('flow-input').addEventListener('input', () => { if ((app.sourceFlow || app.boundSource) && $('flow-input').value.trim() !== app.sourceFlow.trim()) { app.stale = true; app.savedHash = ''; $('review-checkbox').checked = false; readiness(); } });
+    $('scenario-platform').addEventListener('change', () => { app.planRequest += 1; if (app.draft) { app.stale = true; app.savedHash = ''; } $('review-checkbox').checked = false; readiness(); });
     $('suite-editor').addEventListener('input', () => { app.dirty = true; app.script = ''; app.savedFile = ''; app.savedHash = ''; if (app.origin === 'none') app.origin = 'manual'; $('review-checkbox').checked = false; summarize(null); readiness(); });
     $('review-checkbox').addEventListener('change', readiness); $('target-select').addEventListener('change', () => { $('review-checkbox').checked = false; targetDescription(); });
     $('plan-btn').addEventListener('click', generate); $('prompt-btn').addEventListener('click', prompt); $('compile-btn').addEventListener('click', compile); $('save-btn').addEventListener('click', save); $('run-btn').addEventListener('click', run); $('stop-btn').addEventListener('click', stop);
@@ -349,6 +366,7 @@
     $('report-md').addEventListener('click', downloadReportMarkdown);
     $('report-json').addEventListener('click', () => { if (app.report) download(`${app.selectedRun}.json`, JSON.stringify(app.report, null, 2), 'application/json'); });
     $('target-form').addEventListener('submit', saveTarget);
+    $('target-kind').addEventListener('change', targetFields); targetFields();
     $('language-select').addEventListener('change', (event) => i18n.setLocale(event.currentTarget.value));
     i18n.onChange(renderLanguage);
     let refreshing = false;

package/dist/src/ui/public/i18n.js

@@ -23,6 +23,10 @@
     'scenario.eyebrow': ['01 / SCENARIO', '01 / 시나리오'],
     'scenario.headingSecond': ['keep the evidence.', '검증을 남깁니다.'],
     'scenario.intro': ['Define the expected behavior, review the cases, then run them against a selected target.', '기대 동작을 정의하고 케이스를 검토한 뒤, 선택한 대상에서 실행하세요.'],
+    'scenario.platform': ['Case platform', '케이스 플랫폼'],
+    'scenario.web': ['Web', '웹'],
+    'scenario.mobile': ['Mobile app', '모바일 앱'],
+    'scenario.mobileSetup': ['For iOS, prepare Xcode, a simulator or signed device, and app signing. For Android, prepare the Android SDK and an emulator or authorized device. Configuration alone does not verify device access.', 'iOS는 Xcode, 시뮬레이터 또는 서명된 기기와 앱 서명을 준비하세요. Android는 Android SDK와 에뮬레이터 또는 승인된 기기를 준비하세요. 설정만으로 기기 접근이 검증되지는 않습니다.'],
     'scenario.flowTitle': ['Flow to test', '검증할 흐름'],
     'scenario.flowHelp': ['Describe the action and the result you expect to see.', '어떤 행동에 어떤 결과가 보여야 하는지 적어주세요.'],
     'scenario.flowLabel': ['Scenario and expected behavior', '시나리오와 기대 동작'],
@@ -98,7 +102,14 @@
     'settings.savedHere': ['Your display choices are saved in this browser.', '선택한 화면 설정은 이 브라우저에 저장됩니다.'],
     'settings.reset': ['Reset to defaults', '기본값으로 재설정'],
     'settings.targets': ['Run targets', '실행 대상'],
-    'settings.targetsHelp': ['Add an allowed HTTPS or local address.', '허용된 HTTPS 주소 또는 로컬 주소를 등록하세요.'],
+    'settings.targetsHelp': ['Add a web address or a native app and device.', '웹 주소 또는 네이티브 앱과 기기를 등록하세요.'],
+    'settings.targetType': ['Target type', '대상 유형'],
+    'settings.ios': ['iOS app', 'iOS 앱'],
+    'settings.android': ['Android app', 'Android 앱'],
+    'settings.targetUrl': ['URL', 'URL'],
+    'settings.bundleId': ['App bundle ID / package name', '앱 번들 ID / 패키지 이름'],
+    'settings.device': ['Device name or ID', '기기 이름 또는 ID'],
+    'settings.targetSafety': ['Saving a target does not connect a device or install an app.', '대상을 저장해도 기기가 연결되거나 앱이 설치되지는 않습니다.'],
     'settings.targetName': ['Target name', '대상 이름'],
     'settings.targetNamePlaceholder': ['e.g. local-demo', '예: local-demo'],
     'settings.description': ['Description', '설명'],
@@ -126,6 +137,7 @@
     'app.needValidated': ['Validated cases required.', '검증된 케이스가 필요합니다.'],
     'app.needSaved': ['Save cases or reload them from the library before running.', '실행 전 케이스를 저장하거나 보관함에서 다시 불러오세요.'],
     'app.needTarget': ['Select a run target.', '실행 대상을 선택하세요.'],
+    'app.platformMismatch': ['The case platform and target type must match.', '케이스 플랫폼과 대상 유형이 일치해야 합니다.'],
     'app.needReview': ['Review the contents, then select the checkbox.', '내용 검토 후 확인란을 선택하세요.'],
     'app.ready': ['Ready to run.', '실행할 준비가 됐습니다.'],
     'app.caseReadiness': ['{total} total · {ready} runnable · {blocked} blocked before run{hint}', '전체 {total}개 · 실행 가능 {ready}개 · 사전 차단 {blocked}개{hint}'],
@@ -144,6 +156,9 @@
     'app.locatorTestId': ['test ID', '테스트 ID'],
     'app.locatorName': ['name “{name}”', '이름 “{name}”'],
     'app.stepOpen': ['Open page: {path}', '페이지 열기: {path}'],
+    'app.stepLaunchApp': ['Launch app', '앱 실행'],
+    'app.stepBack': ['Go back', '뒤로 가기'],
+    'app.stepSwipe': ['Swipe {direction}', '{direction} 방향으로 스와이프'],
     'app.stepClick': ['Click: {target}', '클릭: {target}'],
     'app.stepFill': ['Fill: {target} → “{value}”', '입력: {target} → “{value}”'],
     'app.stepVisible': ['Expected: {target} visible', '기대 결과: {target} 표시됨'],
@@ -196,8 +211,8 @@
     'app.connected': ['Local server connected', '로컬 서버 연결됨'],
     'app.refreshSettings': ['Refresh settings', '설정 새로고침'],
     'app.runtimeDisconnected': ['Connect to the server to check the runtime.', '서버 연결 후 실행 환경을 확인할 수 있습니다.'],
-    'app.runtimeInstalled': ['Browser installed · Fixed-action cases can run without a model.', '브라우저 설치 확인됨 · 고정 조작 케이스는 모델 없이 실행할 수 있습니다.'],
-    'app.runtimeMissing': ['Browser installation required. Run {command} in a terminal. Automatic installation on first run can fail depending on network access.', '브라우저 설치가 필요합니다. 터미널에서 {command}을 실행하세요. 첫 실행의 자동 설치는 네트워크 환경에 따라 실패할 수 있습니다.'],
+    'app.runtimeInstalled': ['Web browser installed · Fixed-action web cases can run without a model. Mobile device access is checked during a run.', '웹 브라우저 설치 확인됨 · 고정 조작 웹 케이스는 모델 없이 실행할 수 있습니다. 모바일 기기 접근은 실행 중 확인합니다.'],
+    'app.runtimeMissing': ['Web browser installation required for web runs. Run {command} in a terminal. Mobile runs check device access at runtime.', '웹 실행에는 브라우저 설치가 필요합니다. 터미널에서 {command}을 실행하세요. 모바일 실행은 실행 중 기기 접근을 확인합니다.'],
     'app.plannerUnconfigured': ['AI planner is not connected. Configure a model in Connections or download the prompt.', 'AI 플래너가 연결되지 않았습니다. 연결 설정에서 모델을 지정하거나 프롬프트를 내려받으세요.'],
     'app.plannerKeyMissing': ['The configured key environment variable is missing on the server. Add it and restart the server.', '설정한 키 환경 변수가 서버에 없습니다. 키를 주입한 뒤 서버를 재시작하세요.'],
     'app.plannerCliOnly': ['This model can be used from the CLI. Connect an OpenAI-compatible model to generate cases in the UI.', '이 모델은 CLI에서 사용할 수 있습니다. UI에서 생성하려면 OpenAI 호환 모델을 연결하세요.'],

package/dist/src/ui/public/index.html

@@ -48,6 +48,8 @@
             <section class="work-section flow-section" aria-labelledby="flow-title">
               <div class="section-head"><span class="section-number">01</span><div><h2 id="flow-title" data-i18n="scenario.flowTitle">Flow to test</h2><p data-i18n="scenario.flowHelp">Describe the action and the result you expect to see.</p></div></div>
               <div class="section-body">
+                <label for="scenario-platform" class="field-label" data-i18n="scenario.platform">Case platform</label>
+                <select id="scenario-platform"><option value="web" data-i18n="scenario.web">Web</option><option value="mobile" data-i18n="scenario.mobile">Mobile app</option></select>
                 <label for="flow-input" class="field-label" data-i18n="scenario.flowLabel">Scenario and expected behavior</label>
                 <textarea id="flow-input" rows="11" placeholder="For example: When a user enters a title and selects Add, the same title appears in the list. An empty title shows an error." data-i18n-placeholder="scenario.flowPlaceholder"></textarea>
                 <p class="hint" data-i18n="scenario.flowHint">Generate cases when an AI planner is ready. You can also download the prompt and write them yourself without a model connection.</p>
@@ -76,7 +78,7 @@
             <section class="execution-section" aria-labelledby="run-title">
               <div class="section-head"><span class="section-number">03</span><div><h2 id="run-title" data-i18n="scenario.runTitle">Review, then run</h2><p data-i18n="scenario.runHelp">Select a target and confirm you have reviewed the cases.</p></div></div>
               <div class="execution-grid">
-                <div class="target-field"><label for="target-select" class="field-label" data-i18n="scenario.target">Run target</label><select id="target-select"><option value="" data-i18n="scenario.selectTarget">Select a target</option></select><p id="target-description" class="hint" data-i18n="scenario.targetHint">You can add a target in Connections.</p></div>
+                <div class="target-field"><label for="target-select" class="field-label" data-i18n="scenario.target">Run target</label><select id="target-select"><option value="" data-i18n="scenario.selectTarget">Select a target</option></select><p id="target-description" class="hint" data-i18n="scenario.targetHint">You can add a target in Connections.</p><p id="mobile-setup-hint" class="hint" hidden data-i18n="scenario.mobileSetup">For iOS, prepare Xcode, a simulator or signed device, and app signing. For Android, prepare the Android SDK and an emulator or authorized device. Configuration alone does not verify device access.</p></div>
                 <div class="execution-confirm"><p id="case-readiness" class="hint"></p><label class="review-line"><input type="checkbox" id="review-checkbox"><span data-i18n="scenario.reviewConfirm">I have reviewed the requirements, case steps, and expected results.</span></label><div class="run-bar"><span id="run-readiness" data-i18n="scenario.runInitial">Validated cases and a run target are required.</span><div class="actions"><button type="button" id="stop-btn" class="button quiet" hidden data-i18n="scenario.stop">Stop run</button><button type="button" id="run-btn" class="button primary" disabled><span data-i18n="scenario.run">Run QA</span><span aria-hidden="true">→</span></button></div></div></div>
               </div>
             </section>
@@ -106,7 +108,7 @@
             <div class="hds-footer"><p id="preferences-status" aria-live="polite">Your display choices are saved in this browser.</p><button id="reset-preferences" type="button" data-i18n="settings.reset">Reset to defaults</button></div>
           </section>
           <div class="settings-grid">
-            <section class="settings-section"><div class="section-head"><span class="section-number">01</span><div><h2 data-i18n="settings.targets">Run targets</h2><p data-i18n="settings.targetsHelp">Add an allowed HTTPS or local address.</p></div></div><form class="section-body form-stack" id="target-form"><label><span data-i18n="settings.targetName">Target name</span><input name="name" required placeholder="e.g. local-demo" data-i18n-placeholder="settings.targetNamePlaceholder" pattern="[A-Za-z0-9][A-Za-z0-9_-]*"></label><label>URL<input name="url" type="url" required placeholder="https://example.com"></label><label><span data-i18n="settings.description">Description</span><textarea name="description" rows="3" placeholder="What this target is for" data-i18n-placeholder="settings.descriptionPlaceholder"></textarea></label><button class="button primary" type="submit" data-i18n="settings.saveTarget">Save target</button><div id="target-list" class="settings-list"></div></form></section>
+            <section class="settings-section"><div class="section-head"><span class="section-number">01</span><div><h2 data-i18n="settings.targets">Run targets</h2><p data-i18n="settings.targetsHelp">Add a web address or a native app and device.</p></div></div><form class="section-body form-stack" id="target-form"><label><span data-i18n="settings.targetName">Target name</span><input name="name" required placeholder="e.g. local-demo" data-i18n-placeholder="settings.targetNamePlaceholder" pattern="[A-Za-z0-9][A-Za-z0-9_\-]*"></label><label><span data-i18n="settings.targetType">Target type</span><select name="kind" id="target-kind"><option value="web" data-i18n="scenario.web">Web</option><option value="ios" data-i18n="settings.ios">iOS app</option><option value="android" data-i18n="settings.android">Android app</option></select></label><label id="target-url-field"><span data-i18n="settings.targetUrl">URL</span><input name="url" type="url" required placeholder="https://example.com"></label><label id="target-bundle-field" hidden><span data-i18n="settings.bundleId">App bundle ID / package name</span><input name="bundleId" autocomplete="off"></label><label id="target-device-field" hidden><span data-i18n="settings.device">Device name or ID</span><input name="device" autocomplete="off"></label><label><span data-i18n="settings.description">Description</span><textarea name="description" rows="3" placeholder="What this target is for" data-i18n-placeholder="settings.descriptionPlaceholder"></textarea></label><button class="button primary" type="submit" data-i18n="settings.saveTarget">Save target</button><p class="hint" data-i18n="settings.targetSafety">Saving a target does not connect a device or install an app.</p><div id="target-list" class="settings-list"></div></form></section>
             <section class="settings-section"><div class="section-head"><span class="section-number">02</span><div><h2 data-i18n="settings.models">Model connections</h2><p data-i18n="settings.modelsHelp">Manage planner and run agent connections separately.</p></div></div><div class="section-body"><p class="hint" data-i18n="settings.modelsHint">Do not enter or store API key values here. Specify only the name of an environment variable in the server process.</p><div id="model-forms"></div></div></section>
           </div>
         </section>

package/dist/src/ui/public/style.css

@@ -148,7 +148,7 @@ button:focus-visible, input:focus-visible, select:focus-visible, textarea:focus-
 .preferences-section .hds-group { padding-block: calc(var(--space-factor) * 22px); }
 .settings-grid { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: clamp(25px, 3vw, 44px); }
 .form-stack, .model-form { display: grid; gap: calc(var(--space-factor) * 15px); }
-.form-stack label input, .form-stack label textarea, .model-form label input { margin-top: 8px; }
+.form-stack label input, .form-stack label select, .form-stack label textarea, .model-form label input { margin-top: 8px; }
 .form-stack > button { justify-self: start; }
 .settings-list { margin-top: 11px; border-top: 1px solid var(--line); }
 .settings-list:empty { display: none; }

package/dist/src/ui/server.js

@@ -14,6 +14,7 @@ import { EvidenceError, readEvidence } from "./evidence.js";
 import { buildPlanningPrompt, planFlow, PlannerError } from "../planner.js";
 import { renderMarkdown } from "../report.js";
 import { configSchema, idSchema, modelSchema, suiteSchema, targetSchema } from "../schema.js";
+import { targetFingerprint } from "../targets.js";
 import { CONFIG_FILE, sha256 } from "../workspace.js";
 const MAX_BODY = 256 * 1024;
 const MAX_FLOW = 128 * 1024;
@@ -28,7 +29,10 @@ const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 const FILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/;
 const reportEnvelope = z.object({
     schemaVersion: z.literal('flow-qa/report-1'), runId: z.string().regex(RUN_ID), suiteId: idSchema,
-    suiteHash: z.string(), target: z.object({ name: z.string(), url: z.string() }),
+    suiteHash: z.string(), target: z.union([
+        z.object({ name: z.string(), url: z.string() }),
+        z.object({ name: z.string(), kind: z.literal('mobile'), platform: z.enum(['ios', 'android']), bundleId: z.string(), device: z.string() }),
+    ]),
     startedAt: z.string(), finishedAt: z.string(), status: z.enum(['passed', 'failed', 'blocked', 'error', 'interrupted']),
     cases: z.array(z.object({ id: z.string(), title: z.string(), status: z.enum(['passed', 'failed', 'flaky', 'blocked', 'skipped', 'error']),
         expected: z.array(z.string()), attempts: z.array(z.unknown()), reason: z.string().optional() }).passthrough()),
@@ -66,7 +70,8 @@ const SCHEMA_FIELDS = new Set([
     'suite', 'schemaVersion', 'id', 'title', 'source', 'file', 'sha256', 'requirements', 'cases',
     'requirementIds', 'preconditions', 'questions', 'steps', 'type', 'path', 'instruction',
     'locator', 'by', 'value', 'name', 'visible', 'expected', 'match', 'flow', 'role', 'url',
-    'description', 'baseURL', 'model', 'apiKeyEnv', 'clear', 'targetName', 'targetURL', 'suiteHash',
+    'description', 'baseURL', 'model', 'apiKeyEnv', 'clear', 'targetName', 'targetURL', 'targetFingerprint', 'suiteHash',
+    'kind', 'platform', 'bundleId', 'device', 'direction',
 ]);
 const KNOWN_SCHEMA_MESSAGES = new Map([
     ['IDs must be unique.', 'IDs must be unique.'],
@@ -108,7 +113,8 @@ function plannerFailure(error) {
     }
     if (error.code === 'invalid-suite') {
         const allowedMessages = new Set(['A JSON object response is required.', 'A runnable case needs an expected-result assertion.',
-            'Check requirement links, duplicate IDs, and assertions.', 'Check required values, types, and limits in the case schema.']);
+            'Check requirement links, duplicate IDs, and assertions.', 'Check required values, types, and limits in the case schema.',
+            'The suite platform must match the selected planning platform.']);
         const allowedPaths = new Set([...SCHEMA_FIELDS, 'response', 'suite', '?']);
         const issues = error.issues?.slice(0, 8).map((issue) => ({
             path: issue.path.split('.').slice(0, 8).every((part) => allowedPaths.has(part) || /^(?:0|[1-9][0-9]?)$/.test(part)) ? issue.path : 'suite',
@@ -439,7 +445,7 @@ export async function startUIServer(options) {
                 const settings = await config();
                 const history = await runs();
                 sendJSON(response, 200, { csrfToken: token,
-                    targets: Object.entries(settings.targets).map(([name, target]) => ({ name, ...target })),
+                    targets: Object.entries(settings.targets).map(([name, target]) => ({ name, ...target, targetFingerprint: targetFingerprint(target) })),
                     models: { planner: modelState(settings.planner), agent: modelState(settings.agent) },
                     runtime: { browserInstalled: await browserInstalled(), browserInstallCommand: BROWSER_INSTALL_COMMAND },
                     suites: await suites(), runs: history,
@@ -522,10 +528,10 @@ export async function startUIServer(options) {
             throw new HTTPError(403, 'Invalid request token.');
         const body = await bodyJSON(request);
         if (url.pathname === '/api/prompt') {
-            const { flow } = parse(z.object({ flow: z.string().min(1) }).strict(), body);
+            const { flow, platform } = parse(z.object({ flow: z.string().min(1), platform: z.enum(['web', 'mobile']).optional() }).strict(), body);
             if (Buffer.byteLength(flow) > MAX_FLOW)
                 throw new HTTPError(413, 'The flow is too large.');
-            sendJSON(response, 200, { prompt: buildPlanningPrompt(flow) });
+            sendJSON(response, 200, { prompt: buildPlanningPrompt(flow, platform) });
             return;
         }
         if (url.pathname === '/api/stop') {
@@ -539,7 +545,7 @@ export async function startUIServer(options) {
         }
         if (url.pathname === '/api/plan') {
             const result = await mutation(async () => {
-                const { flow } = parse(z.object({ flow: z.string().min(1) }).strict(), body);
+                const { flow, platform } = parse(z.object({ flow: z.string().min(1), platform: z.enum(['web', 'mobile']).optional() }).strict(), body);
                 if (Buffer.byteLength(flow) > MAX_FLOW)
                     throw new HTTPError(413, 'The flow is too large.');
                 const settings = await config();
@@ -560,7 +566,7 @@ export async function startUIServer(options) {
                 timeout.unref();
                 try {
                     const result = await Promise.race([
-                        Promise.resolve().then(() => plan(flow, settings.planner, { signal: abort.signal })),
+                        Promise.resolve().then(() => plan(flow, settings.planner, { signal: abort.signal, platform })),
                         aborted,
                     ]);
                     if (abort.signal.aborted)
@@ -569,6 +575,8 @@ export async function startUIServer(options) {
                     if (!parsed.success)
                         throw new HTTPError(502, 'The model returned an invalid suite.', { category: 'invalid-suite' });
                     const planned = parsed.data;
+                    if ((planned.platform ?? 'web') !== (platform ?? 'web'))
+                        throw new HTTPError(502, 'The model returned cases for a different platform.', { category: 'invalid-suite' });
                     const { source: _modelSource, ...withoutSource } = planned;
                     const suite = suiteSchema.parse(withoutSource);
                     return { suite, script: compileSuite(suite) };
@@ -629,8 +637,11 @@ export async function startUIServer(options) {
         }
         if (url.pathname === '/api/targets') {
             await mutation(async () => {
-                const { name, url: targetURL, description } = parse(z.object({ name: idSchema, url: z.string(), description: z.string().optional() }).strict(), body);
-                const target = parse(targetSchema, { url: targetURL, ...(description === undefined ? {} : { description }) });
+                const { name, ...input } = parse(z.union([
+                    z.object({ name: idSchema, kind: z.literal('mobile'), platform: z.enum(['ios', 'android']), bundleId: z.string(), device: z.string(), description: z.string().optional() }).strict(),
+                    z.object({ name: idSchema, kind: z.literal('web').optional(), url: z.string(), description: z.string().optional() }).strict(),
+                ]), body);
+                const target = parse(targetSchema, input);
                 const settings = await config();
                 settings.targets[name] = target;
                 await updateConfig(settings);
@@ -658,18 +669,27 @@ export async function startUIServer(options) {
         if (url.pathname === '/api/run') {
             enterMutation();
             try {
-                const { suite: file, suiteHash, targetName, targetURL } = parse(z.object({
-                    suite: z.string(), suiteHash: z.string().regex(/^[a-f0-9]{64}$/), targetName: idSchema, targetURL: z.string(),
+                const { suite: file, suiteHash, targetName, targetURL, targetFingerprint: reviewedFingerprint } = parse(z.object({
+                    suite: z.string(), suiteHash: z.string().regex(/^[a-f0-9]{64}$/), targetName: idSchema,
+                    targetURL: z.string().optional(), targetFingerprint: z.string().regex(/^[a-f0-9]{64}$/).optional(),
                 }).strict(), body);
                 const selected = await getSuite(file, true);
                 if (selected.suiteHash !== suiteHash)
                     throw new HTTPError(409, 'The reviewed case file changed. Open it again to review.');
                 const { suite } = selected;
                 const settings = await config();
-                if (!settings.targets[targetName])
+                const target = settings.targets[targetName];
+                if (!target)
                     invalid('The selected target was not found.');
-                if (settings.targets[targetName].url !== targetURL) {
-                    throw new HTTPError(409, 'The selected target URL changed. Review it again.');
+                if ((suite.platform ?? 'web') !== (target.kind === 'mobile' ? 'mobile' : 'web')) {
+                    throw new HTTPError(409, 'The case platform and selected target do not match. Review them again.');
+                }
+                if (reviewedFingerprint !== undefined) {
+                    if (targetFingerprint(target) !== reviewedFingerprint)
+                        throw new HTTPError(409, 'The selected target changed. Review it again.');
+                }
+                else if (target.kind === 'mobile' || !targetURL || target.url !== targetURL) {
+                    throw new HTTPError(409, 'The selected target changed. Review it again.');
                 }
                 const operationId = randomUUID();
                 const abort = new AbortController();

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture and verification boundaries
 
-The local CLI and loopback web UI share one workspace format, case schema, execution path, and report contract. Flow QA runs browser tests against a target URL; it does not need the target application's source code.
+The local CLI and loopback web UI share one workspace format, case schema, execution path, and report contract. Flow QA runs browser tests against a target URL and native tests against a user-configured iOS or Android app/device. It does not need the target application's source code. Mobile integration is available from version 0.2.0; see the [mobile guide](mobile.md).
 
 ```mermaid
 flowchart LR
@@ -8,7 +8,7 @@ flowchart LR
   B --> C[JSON case suite]
   C --> D[Schema and source-hash validation]
   D --> E[Compile allowed steps to e2e code]
-  E --> F[tester-army/e2e browser run]
+  E --> F[tester-army/e2e web or mobile run]
   F --> G[QA report with attempts and evidence]
   H[CLI / local UI] --> B
   H --> D
@@ -22,7 +22,9 @@ flowchart LR
 
 **Only a defined vocabulary compiles.** The schema checks requirement references, assertions, step types, and inputs. It does not execute arbitrary code or shell commands from model output. Cases with unresolved `questions`, or steps that need an unavailable agent model, are blocked. `preconditions` describe required state; they are not an automatic setup contract.
 
-**Source and evidence stay linked.** Planning records the source flow's SHA-256 hash in the suite. `validate`, `generate`, and `run` check it again and stop when the flow changed. Each execution writes a new directory with a suite snapshot, generated tests, raw engine output, and Markdown/JSON reports. Previous evidence is not reused as a current success. `compare` permits a direct comparison only for the same suite hash and target URL; it cannot establish that external data was unchanged.
+**Source and evidence stay linked.** Planning records the source flow's SHA-256 hash in the suite. `validate`, `generate`, and `run` check it again and stop when the flow changed. Each execution writes a new directory with a suite snapshot, generated tests, raw engine output, and Markdown/JSON reports. Previous evidence is not reused as a current success. `compare` permits a direct comparison only for the same suite hash and target identity (web URL or native platform/app/device); it cannot establish that external data was unchanged.
+
+**Targets can be configured after authoring.** A suite's optional platform distinguishes web from mobile. Omitted platform preserves legacy web suites and their hashes. Native app IDs and explicit device names belong to target settings, not generated code from the planner. UI execution checks a fingerprint of the reviewed target identity. Mobile runtime readiness is checked before device execution; configuration alone does not prove connectivity.
 
 **Blocked and failed mean different things.** An unreachable app or unresolved question is blocked; an assertion mismatch is failed. A pass after retry has its own status. Engine output is validated rather than treating missing results as passes. The report records observations, not a root-cause verdict on the product.
 
@@ -31,8 +33,8 @@ flowchart LR
 | Area | Flow QA provides | External implementation or prerequisite |
 | --- | --- | --- |
 | Planning | Prompt, model connection, JSON schema validation | User-selected OpenAI-compatible model |
-| Execution | Step compilation, target connection, orchestration, cancellation | [tester-army/e2e](https://github.com/tester-army/e2e), Chromium |
+| Execution | Step compilation, target connection, orchestration, cancellation | [tester-army/e2e](https://github.com/tester-army/e2e), Chromium for web or `@e2e-dev/mobile`/agent-device for native apps |
 | Results | A fresh report per run, status interpretation, evidence links | Raw runs and evidence from the engine |
 | UI | Local workflow screens and English/Korean language switch | [Hyeonse Design System](https://github.com/hyeonse-swing/hyeonse-design-system) tokens and preference utilities |
 
-The UI binds only to `127.0.0.1` and serves approved report evidence, not arbitrary raw logs or HTML/SVG. Local reports may still contain data from the tested app and should be reviewed before sharing. This release does not manage login sessions, cap model spending, schedule CI runs, or support mobile devices.
+The UI binds only to `127.0.0.1` and serves approved report evidence, not arbitrary raw logs or HTML/SVG. Local reports may still contain data from the tested app and should be reviewed before sharing. It does not manage login sessions, cap model spending, schedule CI runs, or provision mobile SDKs, devices, and application builds.

package/docs/mobile.md

@@ -0,0 +1,59 @@
+# User-configured iOS and Android targets
+
+Mobile targets require Flow QA `0.2.0` or later and Node.js 24.8 or later. The web demo remains a browser demo; it is not proof of a mobile run.
+
+## Write cases now, connect an app later
+
+Choose **Mobile** on the scenario screen, describe the flow, and generate or download a planning prompt. You do not need to register an app or device to author, validate, compile, or save cases. A mobile suite has `"platform": "mobile"`; existing suites without a platform remain web suites.
+
+With the installed CLI:
+
+```sh
+npm install -g @ihyeon/flow-qa@0.2.0
+flow-qa init ./my-qa
+# Write your mobile flow in my-qa/flows/my-flow.md first.
+flow-qa plan flows/my-flow.md --platform mobile --prompt-only --workspace ./my-qa
+```
+
+Use your chosen AI tool to produce JSON from the prompt, then review and save it under `my-qa/cases/`. Alternatively, configure a planner and omit `--prompt-only`. Neither option needs the target app's source code. Product behavior and accessible element names must still be supplied; unknown expectations remain questions.
+
+## Register an app when ready
+
+In **Connections**, select **iOS** or **Android**, then enter a target name, the installed app's bundle/package ID, and an explicit device name or ID. Register multiple targets to use one mobile suite on both platforms when their accessible labels and expected behavior agree. Use separate suites where the two apps behave differently.
+
+CLI examples below contain placeholders; replace them with your own app and devices:
+
+```sh
+flow-qa connect my-ios --platform ios --bundle-id com.example.app --device "QA iPhone" --workspace ./my-qa
+flow-qa connect my-android --platform android --bundle-id com.example.app --device emulator-5554 --workspace ./my-qa
+flow-qa run cases/my-flow.json --target my-ios --workspace ./my-qa
+flow-qa run cases/my-flow.json --target my-android --workspace ./my-qa
+```
+
+Saving a target only writes configuration. It does not contact a model, boot a device, install an app, or start a test. You can update a saved target by saving the same target name again. The UI checks the reviewed app, platform, and device before dispatching a run; changed settings require another review.
+
+For an iOS simulator, prepare Xcode, an installed simulator runtime, a booted simulator, and a simulator build of the app installed on it. For Android, prepare the Android SDK and a booted emulator or an authorized connected device with the app installed. Physical iOS devices additionally need pairing, Developer Mode, and signing of the upstream automation runner. Follow the [mobile engine's setup instructions](https://e2e.tester.army/docs/mobile#physical-devices) for device-specific requirements.
+
+Flow QA does not download SDKs, create or boot simulators, or install application builds. A missing or unavailable selected device blocks the run; a saved target is not evidence of a working device or app. For physical device IDs that the underlying engine resolves by name, the device name must be unique after case and whitespace normalization; ambiguous selection blocks the run. Chromium is only required for web targets.
+
+## Native steps
+
+| Step | Behavior |
+| --- | --- |
+| `launchApp` | Launch the app registered in the selected target |
+| `click` | Tap an accessible element |
+| `fill` | Enter text in an accessible input |
+| `back` | Use the engine's app back navigation |
+| `swipe` | Swipe the viewport `up`, `down`, `left`, or `right` |
+| `assertVisible`, `assertText` | Check accessible elements and their text |
+| `act`, `assertAgent` | Use the separately configured agent model for an action or judgment |
+
+The compiler launches the configured app at the start of each runnable case unless the first step is already `launchApp`. It does not clear app data or create login state. A launch is not a fresh account/session. The web-only `open` path and `assertUrl` steps are rejected in mobile suites, and native steps are rejected in web suites.
+
+Native `testId` locators use iOS accessibility identifiers or Android resource IDs. Accessibility exposure depends on the app framework. Fixed steps need no model; natural-language steps require a compatible tool/image-capable agent. A WebView's exposed native controls may be usable, but this path does not provide a browser DOM session or prove JavaScript bridge behavior.
+
+## Results and proof boundaries
+
+Mobile reports record platform, app ID, and device rather than a fabricated URL. They use the same case statuses, attempt details, and approved screenshot/text evidence handling as web reports. Comparing different apps, platforms, or configured devices does not produce a direct regression verdict.
+
+Configuration, compilation, mocked runtime tests, and browser UI tests establish the integration behavior. Successful iOS and Android execution still requires recorded results on the user's chosen devices and apps. Flow QA does not supply app-specific cases, accounts, build artifacts, or a device farm.