mobile-automator 0.23.8

package/src/guide/content/setup.aware.md

@@ -0,0 +1,91 @@
+# Guide: setup (platform-aware)
+
+You are configuring a mobile-QA workspace by **analyzing this project**. The mechanical part is already done: `mauto setup` has scaffolded the `mobile-automator/` tree (scenarios, screenshots, results) and written a starter `config.json`. **This guide completes the project analysis** — you inspect the codebase, infer each fact, confirm anything uncertain with the user, and PERSIST every finding with `mauto config set <key> <value>`. Read each value back with `mauto config get <key>` to confirm it landed.
+
+You are doing LLM analysis work, not running a fixed script. Read real project files, reason about what you find, and only ask the user when a value genuinely cannot be inferred.
+
+## How to persist a finding
+
+Every analysis result is stored in the workspace config:
+
+```
+mauto config set <key> <value>
+```
+
+For list-valued keys (e.g. `protected_directories`), pass a comma-separated value. Run `mauto schema config` to see the declared type of any key. When a value is uncertain, confirm it with the user before persisting. When you truly cannot infer a value, ask the user directly and persist their answer.
+
+## 1. Detect the platform
+
+Inspect the project files to determine the mobile platform. First honor any `.gitignore` patterns, then run these checks in order and stop at the first match:
+
+- **Flutter** — `pubspec.yaml` at the root with `flutter` in `dependencies`/`environment`.
+- **React Native** — `package.json` with `react-native` in `dependencies`/`devDependencies`.
+- **Kotlin Multiplatform** — `build.gradle.kts`/`build.gradle` declaring the `kotlin("multiplatform")` plugin, or `shared/` / `composeApp/` source sets (`commonMain/`, `androidMain/`, `iosMain/`).
+- **Compose Multiplatform** — the `org.jetbrains.compose` plugin or a `composeApp/` `commonMain/` with `@Composable` functions.
+- **Android Native** — `build.gradle`/`build.gradle.kts` with the `com.android.application` plugin, or `AndroidManifest.xml`.
+- **iOS Native** — `*.xcodeproj` / `*.xcworkspace`, `*.swift`/`*.m` sources, or `Info.plist`.
+
+If none match, ask the user which platform this is. Confirm the detected platform with the user, then persist it:
+
+```
+mauto config set platform <platform>
+```
+
+## 2. Discover build environments
+
+Scan the project's build configuration for named environments, scoped to the detected platform:
+
+- **Gradle-based projects** — read the app/module build file; extract `productFlavors` (names + any `applicationIdSuffix`) and `buildTypes` (e.g. `debug`, `release`, `staging`). Compile the cross-product (e.g. `stagingDebug`, `productionRelease`).
+- **Xcode-based projects** — list build schemes (`*.xcscheme`) and per-configuration `*.xcconfig` files; treat each configuration as an environment.
+- **Flutter** — look for `--dart-define` patterns, flavor configs, and env files (`.env.staging`, `lib/flavors/`, `flutter_dotenv` / `envied`).
+- **React Native** — look for `.env*` files, env-specific `package.json` scripts, and `react-native-config` / `react-native-dotenv`.
+
+Deduplicate the result. If none are found, default to `production, staging, development`. Confirm with the user, then persist:
+
+```
+mauto config set environments <env1,env2,...>
+```
+
+The comma-separated value is stored as a JSON list.
+
+## 3. Infer the app package
+
+Read the application identifier from the build files, scoped to the platform:
+
+- **Android module** — base `applicationId` from the app build file's `defaultConfig`, plus any flavor/buildType `applicationIdSuffix`. Persist with `mauto config set android_package <id>`.
+- **Apple target** — `PRODUCT_BUNDLE_IDENTIFIER` from the Xcode project (`project.pbxproj`/`*.xcconfig`) or `CFBundleIdentifier` in `Info.plist`. Persist with `mauto config set ios_bundle_id <id>`.
+- **Cross-platform projects** — persist both the Android `android_package` and the Apple `ios_bundle_id`.
+
+If you cannot infer the identifier, ask the user for it (`e.g. com.example.myapp`), then persist. Confirm any inferred value with the user first.
+
+## 4. Capture project knowledge
+
+Infer each of the following from the codebase, confirm uncertain values with the user, and persist each one.
+
+- **Project name** — from `settings.gradle*` `rootProject.name`, `pubspec.yaml` `name`, `package.json` `name`, the `*.xcodeproj` name, or the root directory name. Persist: `mauto config set project_name <name>`.
+- **Platform details** — versions like `minSdk`/`targetSdk`/`compileSdk` (Gradle) or the deployment target (Xcode); format as e.g. `"Android (minSdk 24, targetSdk 34)"` or `"iOS (deployment target 16)"`. Persist: `mauto config set platform_details "<details>"`.
+- **Build system** — `"Gradle (AGP)"`, `"Xcode"`, `"Flutter CLI + Gradle + Xcode"`, or `"Metro + Gradle + Xcode"`. Persist: `mauto config set build_system "<system>"`.
+- **Build command** — the default debug/development build command (e.g. `./gradlew assembleDemoDebug`, `flutter build apk --flavor demo`, `npx react-native run-android`, or `xcodebuild -scheme <scheme>`). Persist: `mauto config set build_command "<command>"`.
+- **Architecture** — infer from directory and class naming (`viewmodel/` → MVVM; `repository/`+`usecase/`+`domain/`+`data/` → Clean Architecture; `bloc/`/`cubit/` → BLoC; `reducer/`/`store/` → Redux/MVI; `presenter/`/`interactor/` → MVP/VIPER). Combine findings (e.g. `"MVVM with Clean Architecture"`). If unclear, ask the user. Persist: `mauto config set architecture "<pattern>"`.
+- **Business domain** — read `README.md`, app-store metadata, `pubspec.yaml`/`package.json` description, or the app display name to infer a one-sentence domain description. If you cannot tell, ask the user. Persist: `mauto config set business_domain "<one sentence>"`.
+- **Business-critical paths** — analyze navigation graphs, route/deep-link definitions, screen/Activity/Fragment/ViewController/page definitions, and feature modules to find the most important user flows (login, signup, onboarding, checkout, payment, search, profile, …). Confirm the list with the user. Persist a comma-separated value (stored as a list): `mauto config set business_critical_paths "<onboarding, login, checkout>"`.
+- **Loading indicators** — grep for loading widgets/components (progress indicators, spinners, shimmer/skeleton placeholders) and any `*Loading*`/`*Spinner*`/`*Shimmer*`/`*Skeleton*` classes. Persist the found names, or a description like `"progress bars, spinners, shimmer effects"` if none found. Persist: `mauto config set loading_indicators "<list>"`.
+- **Protected directories** — list the source directories the QA tooling must NEVER modify (e.g. `app/src/`, `lib/`, `src/`, `shared/`, `composeApp/`, `iosApp/`). Confirm with the user. Persist a comma-separated value (stored as a list): `mauto config set protected_directories "<app/src/, lib/, core/>"`.
+
+## 5. Confirm the config
+
+Read the persisted values back with `mauto config get <key>` for each finding, and present a concise summary to the user. The workspace is now analyzed and configured: `mauto guide generate` and `mauto guide execute` will read these values to drive scenario authoring and execution.
+
+## Operational Boundaries
+
+### DO
+
+- Inspect real project files before inferring any value.
+- Persist every finding with `mauto config set <key> <value>` and verify with `mauto config get`.
+- Ask the user directly for any value that cannot be inferred, and confirm uncertain inferences.
+
+### DON'T
+
+- Modify app source code — this guide only reads it and writes the workspace config.
+- Re-scaffold the workspace — `mauto setup` already created the directory tree and starter config.
+- Invent a value you cannot find evidence for — ask the user instead.

package/src/guide/content/setup.invariants.md

@@ -0,0 +1,3 @@
+- Inspect real project files before inferring any value; never invent a value you cannot find evidence for — ask the user instead.
+- Persist every finding with `mauto config set <key> <value>` and verify it with `mauto config get <key>`.
+- Do not modify app source code, and do not re-scaffold the workspace — `mauto setup` already created it. This guide only reads the project and writes the workspace config.

package/src/guide/emitter.js

@@ -0,0 +1,137 @@
+'use strict';
+
+// Reasoning-delivery floor for the `mauto` CLI.
+//
+// emitGuide / emitSchema / emitBootstrap produce RAW content an agent injects
+// directly into its own context (markdown / JSON schema / text). They do NOT
+// wrap their output in the JSON envelope — only the CLI's ERROR paths (unknown
+// topic/name) do that. See src/cli.js for the raw-vs-envelope wiring.
+//
+// These are structured STUBS in slice 3; the full prose ports land in later
+// slices. The stubs are deliberately minimal but already honour every contract
+// the lint guards enforce: no `{{placeholder}}` tokens, no leaked `mobile_*`
+// tool names (the agent drives the device only through `mauto` verbs), and in
+// platform-agnostic mode no OS / OS-specific tooling words — per-OS facts are
+// reached through the four semantic actions, never named here.
+
+const fs = require('fs');
+const path = require('path');
+
+const { interpolate } = require('./placeholders');
+
+// Topics with REAL ported prose live as markdown content files (carrying
+// `{{placeholder}}` tokens lifted from the Gemini SKILLs). They are emitted by
+// loading the mode-appropriate file and running it through interpolate(...),
+// which fills tokens from the workspace config and applies a fallback so no
+// `{{` survives. Topics absent from this map fall through to the stub emitter.
+const CONTENT_DIR = path.resolve(__dirname, 'content');
+const PORTED_TOPICS = new Set(['generate', 'execute', 'setup']);
+
+const SCENARIO_SCHEMA = path.resolve(__dirname, '../schemas/scenario_schema.json');
+const RESULT_SCHEMA = path.resolve(__dirname, '../schemas/result_schema.json');
+const CONFIG_SCHEMA = path.resolve(__dirname, '../schemas/config_schema.json');
+
+const TOPICS = {
+  generate:
+    'Author a test scenario. The agent drives `mauto elements`/`tap`/`type`/`swipe`/`press` to explore the app, then assembles a scenario JSON validated with `mauto validate` against `mauto schema scenario`.',
+  execute:
+    'Run a scenario. The agent replays each step through `mauto` action verbs, evaluates checks with `mauto assert`, and records progress with `mauto result add-step` / `mauto result finalize`.',
+  setup:
+    'Initialise the workspace. `mauto setup` scaffolds the mobile-automator tree and a config; `mauto config get/set` reads and updates it.',
+};
+
+const SEMANTIC_ACTIONS = ['press_back', 'dismiss_keyboard', 'grant_permission', 'deny_permission'];
+
+function emitGuide(topic, { mode = 'platform-aware', projectRoot } = {}) {
+  const summary = TOPICS[topic];
+  if (!summary) {
+    throw new Error(`unknown guide topic: ${topic}`);
+  }
+
+  if (PORTED_TOPICS.has(topic)) {
+    const variant = mode === 'platform-agnostic' ? 'agnostic' : 'aware';
+    const file = path.join(CONTENT_DIR, `${topic}.${variant}.md`);
+    const template = fs.readFileSync(file, 'utf8');
+    return interpolate(template, { projectRoot, mode });
+  }
+
+  const lines = [];
+  lines.push(`# Guide: ${topic} (${mode})`);
+  lines.push('');
+  lines.push(summary);
+  lines.push('');
+  lines.push(`This guide directs the agent through \`mauto\` verbs for the \`${topic}\` workflow.`);
+
+  if (mode === 'platform-agnostic') {
+    lines.push('');
+    lines.push(
+      'Platform-agnostic: never rely on a specific platform. Map every OS-level gesture to one of the four semantic actions, executed through `mauto press`:'
+    );
+    lines.push('');
+    for (const act of SEMANTIC_ACTIONS) {
+      lines.push(`- \`${act}\``);
+    }
+  }
+
+  lines.push('');
+  lines.push('_(full guide content lands in a later slice)_');
+  lines.push('');
+  return lines.join('\n');
+}
+
+const SCHEMA_FILES = {
+  scenario: SCENARIO_SCHEMA,
+  result: RESULT_SCHEMA,
+  config: CONFIG_SCHEMA,
+};
+
+function emitSchema(name) {
+  const file = SCHEMA_FILES[name];
+  if (!file) {
+    throw new Error(`unknown schema name: ${name}`);
+  }
+  return fs.readFileSync(file, 'utf8');
+}
+
+function emitBootstrap() {
+  const verbs = [
+    ['elements', 'list the UI elements currently on screen'],
+    ['tap', 'tap at absolute screen coordinates'],
+    ['long-press', 'long-press at absolute screen coordinates (optional --duration <ms>)'],
+    ['double-tap', 'double-tap at absolute screen coordinates'],
+    ['type', 'type text into the focused element'],
+    ['swipe', 'swipe in a cardinal direction'],
+    ['press', 'press a system/hardware button or semantic action'],
+    ['launch', 'launch an installed app by its package/bundle id'],
+    ['install', 'install an app from a local artifact path'],
+    ['uninstall', 'uninstall an app by its package/bundle id'],
+    ['open-url', 'open a URL (deep link or web) on the device'],
+    ['orientation', 'set the device orientation (portrait | landscape)'],
+    ['screenshot', 'save a screenshot to a path'],
+    ['assert', 'evaluate an assertion against the current screen'],
+    ['validate', 'validate a scenario file against the scenario schema'],
+    ['result', 'record step results and finalize a run'],
+    ['setup', 'scaffold the workspace and write a config'],
+    ['config', 'get/set values in the workspace config'],
+    ['guide', 'print the guide for a workflow topic'],
+    ['schema', 'print the scenario, result, or config JSON schema'],
+  ];
+
+  const lines = [];
+  lines.push('# mauto bootstrap');
+  lines.push('');
+  lines.push('Verb map:');
+  for (const [verb, desc] of verbs) {
+    lines.push(`- \`mauto ${verb}\` — ${desc}`);
+  }
+  lines.push('');
+  lines.push('Invariants:');
+  lines.push('- Run `mauto guide <topic>` before first using a workflow.');
+  lines.push('- Drive the device ONLY through `mauto` verbs.');
+  lines.push('- Platform-agnostic: never rely on a stable element id from the view hierarchy.');
+  lines.push('- Every action verb returns a JSON envelope ({ ok, data } or { ok:false, error }).');
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = { emitGuide, emitSchema, emitBootstrap, TOPICS, SEMANTIC_ACTIONS };

package/src/guide/placeholders.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// Placeholder interpolation for ported guide prose.
+//
+// Guide content files (src/guide/content/*.md) carry `{{token}}` placeholders
+// lifted verbatim from the Gemini SKILL templates. At emit time we replace every
+// token with a config-derived value so the agent reads concrete, project-specific
+// prose. A token with no backing config value falls back to a clear "not
+// configured" note — guaranteeing NO `{{` survives, which the guide lint guards
+// enforce.
+//
+// PLACEHOLDER_KEYS maps each placeholder name to the config lookup(s) used to
+// resolve it. It is exported so the execute port (slice 5) reuses the
+// same contract instead of re-deriving it.
+
+const configManager = require('../config/manager');
+
+// How an UNSET placeholder renders has to fit the sentence it lands in. A
+// single context-blind string cannot: the 13 placeholder sites in the aware
+// guides occupy at least five grammatical roles (label value, inline noun,
+// parenthetical appositive, inline tail, whole section body). There are two
+// kinds of slot, and they want opposite things.
+//
+//   VALUE slots — `**Platform:** {{platform_details}}`, `the app package
+//   ({{app_package}})`. These want a short noun phrase naming the key to set.
+//   Critically it must carry NO parentheses of its own: the prose already
+//   supplies them where they belong, so a self-parenthesizing fallback rendered
+//   `the app package ((not configured …))` — the same class of malformation
+//   #143 set out to remove, in a different shape.
+//
+//   OPTIONAL slots — `the `mauto` CLI{{automation_extras}}.` and the trailing
+//   `{{additional_resources}}` bullet. These are additive prose; when there is
+//   nothing to add, the correct rendering is NOTHING. A diagnostic jammed onto
+//   the preceding word (`the `mauto` CLI(not configured …).`) is strictly worse
+//   than silence.
+const FALLBACK = 'not configured';
+
+// The fallback also used to read `set it via mauto config set <key>` with
+// `<key>` left LITERAL — so the guide told the agent to run a command with a
+// placeholder still in it, 13 times, and never named the missing key. The
+// candidate list knows the key, so name it.
+function fallbackFor(spec) {
+  if (!spec) return FALLBACK; // unknown token — nothing to name
+  if (spec.optional) return '';
+  return `${FALLBACK} — mauto config set ${spec.keys[0]}`;
+}
+
+// Each entry lists candidate config keys, tried in order. The config may be in
+// the flat agnostic shape (top-level keys) or the nested aware shape written by
+// setup (app.*, knowledge.*) — we probe both so one map serves every shape.
+//
+// `join: true`  -> array values are rendered as a comma-joined list.
+// `prefix`      -> rendered as `${prefix}${value}` when a value is present
+//                  (used by automation_extras / additional_resources, which in
+//                  the original prose are inline tails like ", plus adb").
+const PLACEHOLDER_KEYS = {
+  // ---- shared (aware + agnostic) ----
+  project_name: { keys: ['project_name', 'knowledge.project_name'] },
+  loading_indicators: { keys: ['loading_indicators', 'knowledge.loading_indicators'] },
+  protected_directories: {
+    keys: ['protected_directories', 'knowledge.protected_directories'],
+    join: true,
+  },
+  // `optional: true` -> renders as nothing when unset (see FALLBACK above).
+  additional_resources: {
+    keys: ['additional_resources', 'knowledge.additional_resources'],
+    prefix: '\n',
+    optional: true,
+  },
+
+  // ---- aware only ----
+  app_package: { keys: ['android_package', 'app.android_package', 'ios_bundle_id', 'app.ios_bundle_id'] },
+  architecture: { keys: ['architecture', 'knowledge.architecture'] },
+  platform_details: { keys: ['platform_details', 'knowledge.platform_details', 'platform'] },
+  build_system: { keys: ['build_system', 'knowledge.build_system'] },
+  build_command: { keys: ['build_command', 'knowledge.build_command'] },
+  // An inline tail (", plus adb") appended to "the `mauto` CLI" — optional, so
+  // an unset value ends the sentence cleanly instead of jamming a note onto it.
+  automation_extras: {
+    keys: ['automation_extras', 'knowledge.automation_extras'],
+    optional: true,
+  },
+  environments: { keys: ['environments'], join: true },
+
+  // ---- agnostic only ----
+  business_domain: { keys: ['business_domain', 'knowledge.business_domain'] },
+  business_critical_paths: {
+    keys: ['business_critical_paths', 'knowledge.business_critical_paths'],
+    join: true,
+  },
+};
+
+function firstDefined(projectRoot, keys) {
+  // No project root (e.g. lint guards emit guides without one) -> no config,
+  // every placeholder takes the fallback. Never let config I/O throw here.
+  if (!projectRoot) return undefined;
+  for (const k of keys) {
+    const v = configManager.get(projectRoot, k);
+    if (v !== undefined && v !== null && v !== '') return v;
+  }
+  return undefined;
+}
+
+function renderValue(value, spec) {
+  if (value === undefined) return undefined;
+  let out;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return undefined;
+    out = spec.join ? value.join(', ') : value.join(', ');
+  } else {
+    out = String(value);
+  }
+  if (spec.prefix) out = `${spec.prefix}${out}`;
+  return out;
+}
+
+// interpolate(template, { projectRoot, mode })
+// Replaces every {{token}} in `template`. Known placeholders resolve from config
+// (per PLACEHOLDER_KEYS); known-but-unset and entirely unknown tokens both fall
+// back to FALLBACK, so the returned string never contains `{{`.
+function interpolate(template, { projectRoot, mode } = {}) {
+  // `mode` is accepted for symmetry with emitGuide and future per-mode tweaks;
+  // resolution today is mode-agnostic (the candidate-key probing covers both).
+  void mode;
+  return String(template).replace(/\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g, (_, name) => {
+    const spec = PLACEHOLDER_KEYS[name];
+    const rendered = spec ? renderValue(firstDefined(projectRoot, spec.keys), spec) : undefined;
+    return rendered === undefined ? fallbackFor(spec) : rendered;
+  });
+}
+
+module.exports = { interpolate, PLACEHOLDER_KEYS, FALLBACK, fallbackFor };

package/src/init/adapters.js

@@ -0,0 +1,162 @@
+'use strict';
+
+// VendorAdapters — `mauto init --agent <claude|cursor|gemini|copilot|agents>`.
+//
+// Each adapter installs native Agent Skills (open standard: a SKILL.md folder
+// per topic) into the agent's skills directory, and is idempotent (re-running
+// yields byte-identical files). claude/cursor additionally keep writing their
+// thin slash-command/rule and merging the shared `mauto` MCP server entry.
+// Adapters never clobber a file they don't own.
+
+const fs = require('fs');
+const path = require('path');
+
+const guideEmitter = require('../guide/emitter');
+const { renderSkill, readInvariants, SKILL_TOPICS } = require('./skill-renderer');
+const { SKILL_META } = require('./skill-meta');
+
+const TOPICS = ['generate', 'execute', 'setup'];
+
+// The single mauto MCP server entry merged into a vendor's mcp config.
+const MAUTO_SERVER = { command: 'mauto', args: ['mcp'] };
+
+// Per-agent skills directory (relative to projectRoot). claude uses its own
+// namespace; cursor/gemini/copilot each use their native dir; `agents` targets
+// the open-standard location.
+const SKILL_DEST = {
+  claude: path.join('.claude', 'skills'),
+  cursor: path.join('.cursor', 'skills'),
+  gemini: path.join('.gemini', 'skills'),
+  copilot: path.join('.github', 'skills'),
+  agents: path.join('.agents', 'skills'),
+};
+
+// BACK-COMPAT FALLBACK — NOT the live instruction surface for a current host.
+//
+// Claude Code merged custom commands into skills, and a same-named skill wins:
+//   "if a skill and a command share the same name, the skill takes precedence"
+//   https://code.claude.com/docs/en/skills
+// We write both `mobile-automator-<topic>.md` here and a skill folder of the
+// same name, so on any host with skills support THIS FILE IS NEVER READ.
+// Editing it to change agent behavior on a current host does nothing — change
+// `<topic>.invariants.md` (directives) or the guide content (workflow) instead.
+//
+// It still wins in two places, which is why it is kept and why it must not be
+// thin: a Claude Code old enough to predate skills, and a workspace whose last
+// `mauto init` predates the release that started writing skills. On both, this
+// file IS the registered surface — so it renders from the same two sources the
+// skill does (`SKILL_META` + `<topic>.invariants.md`) and can never drift into
+// being the weaker of the two. The `description` frontmatter matters for the
+// same reason: without it a host derives one by truncating the body, which
+// yields a description of the mechanism rather than of when to use this.
+function claudeCommandBody(topic) {
+  return (
+    '---\n' +
+    `description: ${SKILL_META[topic].description}\n` +
+    '---\n\n' +
+    `Run \`mauto guide ${topic}\` and follow it.\n\n` +
+    '## Non-negotiable directives (always apply)\n' +
+    `${readInvariants(topic)}\n`
+  );
+}
+
+function cursorRuleBody() {
+  return (
+    '---\n' +
+    'description: Mobile Automator — drive mobile QA through the mauto CLI.\n' +
+    'alwaysApply: true\n' +
+    '---\n\n' +
+    guideEmitter.emitBootstrap() +
+    '\nRun `mauto guide <topic>` (generate|execute|setup) before a workflow. ' +
+    'Drive the device only through `mauto` verbs.\n'
+  );
+}
+
+function writeIfChanged(filePath, content) {
+  const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+  if (prev === content) return false;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+function mergeMcpConfig(filePath) {
+  let doc = {};
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8');
+    try {
+      doc = JSON.parse(existing);
+    } catch (err) {
+      // A hand-edited / partially-written host config. Surface a typed,
+      // actionable error instead of a bare SyntaxError, and never clobber the
+      // user's file — re-running converges once they fix it.
+      const e = new Error(`existing MCP config is not valid JSON: ${filePath}`);
+      e.code = 'corrupt_mcp_config';
+      throw e;
+    }
+    if (doc == null || typeof doc !== 'object' || Array.isArray(doc)) doc = {};
+  }
+  if (doc.mcpServers == null || typeof doc.mcpServers !== 'object') {
+    doc.mcpServers = {};
+  }
+  doc.mcpServers.mauto = { ...MAUTO_SERVER };
+  const next = JSON.stringify(doc, null, 2) + '\n';
+  const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+  if (prev === next) return { changed: false };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, next);
+  return { changed: true };
+}
+
+// Install one SKILL.md folder per topic under the agent's skills dir. Only the
+// folders we own are written; foreign skill folders are never touched.
+function writeSkills(projectRoot, agent, written) {
+  const root = path.join(projectRoot, SKILL_DEST[agent]);
+  for (const topic of SKILL_TOPICS) {
+    const { dirName, content } = renderSkill(topic);
+    const file = path.join(root, dirName, 'SKILL.md');
+    writeIfChanged(file, content);
+    written.push(file);
+  }
+}
+
+function makeAdapter(agent, extra) {
+  return {
+    apply({ projectRoot }) {
+      const written = [];
+      const merged = [];
+      if (extra) extra({ projectRoot, written, merged });
+      writeSkills(projectRoot, agent, written);
+      return { agent, written, merged };
+    },
+  };
+}
+
+const ADAPTERS = {
+  claude: makeAdapter('claude', ({ projectRoot, written, merged }) => {
+    const commandsDir = path.join(projectRoot, '.claude', 'commands');
+    for (const topic of TOPICS) {
+      const file = path.join(commandsDir, `mobile-automator-${topic}.md`);
+      writeIfChanged(file, claudeCommandBody(topic));
+      written.push(file);
+    }
+    const mcpPath = path.join(projectRoot, '.mcp.json');
+    mergeMcpConfig(mcpPath);
+    merged.push(mcpPath);
+  }),
+
+  cursor: makeAdapter('cursor', ({ projectRoot, written, merged }) => {
+    const rulePath = path.join(projectRoot, '.cursor', 'rules', 'mobile-automator.mdc');
+    writeIfChanged(rulePath, cursorRuleBody());
+    written.push(rulePath);
+    const mcpPath = path.join(projectRoot, '.cursor', 'mcp.json');
+    mergeMcpConfig(mcpPath);
+    merged.push(mcpPath);
+  }),
+
+  gemini: makeAdapter('gemini'),
+  copilot: makeAdapter('copilot'),
+  agents: makeAdapter('agents'),
+};
+
+module.exports = { ADAPTERS, MAUTO_SERVER, SKILL_DEST };

package/src/init/skill-meta.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// Frontmatter metadata for the installed Agent Skills. `name` MUST equal the
+// skill folder name and satisfy the strictest host rules (lowercase/hyphen,
+// <=64 chars, no reserved words). `description` is generic and placeholder-free
+// and names WHEN to use the skill so hosts surface it at the right moment.
+const SKILL_META = {
+  generate: {
+    name: 'mobile-automator-generate',
+    description:
+      'Author a mobile QA test scenario by driving the app on a device and ' +
+      'recording each step as structured JSON. Use when the user wants to ' +
+      'create, author, record, or generate a mobile test scenario.',
+  },
+  execute: {
+    name: 'mobile-automator-execute',
+    description:
+      'Execute a saved mobile QA scenario on a device and produce a pass/fail ' +
+      'report with diagnostics. Use when the user wants to run, replay, or ' +
+      'verify a mobile test scenario.',
+  },
+  setup: {
+    name: 'mobile-automator-setup',
+    description:
+      'Initialise and configure a mobile-automator workspace by analysing the ' +
+      'project. Use when the user wants to set up, configure, or initialise ' +
+      'mobile QA automation for this project.',
+  },
+};
+
+module.exports = { SKILL_META };

package/src/init/skill-renderer.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// Deterministic SKILL.md renderer (option C: hybrid). The body inlines the
+// placeholder-free QA invariants (guaranteed forcing the moment a host
+// activates the skill) and points to `mauto guide <topic>` for the full,
+// mode-aware, interpolated workflow. NO interpolation happens here, so the
+// renderer never reads config.json — see docs/plans/2026-06-28-*-design.md §5.
+const fs = require('fs');
+const path = require('path');
+
+const { SKILL_META } = require('./skill-meta');
+
+const SKILL_TOPICS = ['generate', 'execute', 'setup'];
+const CONTENT_DIR = path.resolve(__dirname, '../guide/content');
+
+const TITLES = {
+  generate: 'Generate',
+  execute: 'Execute',
+  setup: 'Setup',
+};
+
+// The non-negotiable directives for a topic, verbatim from disk. Exported so
+// every surface that has to carry these directives renders them from this one
+// source rather than restating them — see `claudeCommandBody` in adapters.js.
+function readInvariants(topic) {
+  return fs.readFileSync(path.join(CONTENT_DIR, `${topic}.invariants.md`), 'utf8').trim();
+}
+
+function renderSkill(topic) {
+  const meta = SKILL_META[topic];
+  if (!meta) {
+    throw new Error(`unknown skill topic: ${topic}`);
+  }
+  if (!TITLES[topic]) {
+    throw new Error(`unknown skill topic title: ${topic}`);
+  }
+  const invariants = readInvariants(topic);
+
+  const content =
+    '---\n' +
+    `name: ${meta.name}\n` +
+    `description: ${meta.description}\n` +
+    '---\n\n' +
+    `# Mobile Automator — ${TITLES[topic]}\n\n` +
+    '## Non-negotiable directives (always apply)\n' +
+    `${invariants}\n\n` +
+    '## Full workflow\n' +
+    'Load the complete, project-configured playbook and follow it step by step:\n\n' +
+    `    mauto guide ${topic}\n`;
+
+  // Defensive: the invariants are placeholder-free by construction; never let a
+  // stray token reach an installed skill.
+  if (content.includes('{{')) {
+    throw new Error(`skill ${topic} leaked a placeholder token`);
+  }
+
+  return { dirName: meta.name, content };
+}
+
+module.exports = { renderSkill, readInvariants, SKILL_TOPICS };