@icyouo/evt-cli 0.1.0 → 0.1.2

package/skills/evt-api-scanner/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: evt-api-scanner
+description: Use when an agent needs to discover API source locations, generate evt-cli scanner config, scan a codebase for HTTP endpoints, sync YAML API definitions, check endpoint coverage, or bootstrap endpoint data for evt-cli projects.
+---
+
+# evt-api-scanner
+
+Use this skill when working with an evt-cli project and you need to discover,
+scan, sync, or audit YAML API definitions.
+
+## Workflow
+
+1. Locate the project root and evt config root.
+   - Prefer the user's explicit `--config-root`.
+   - Otherwise use `EVT_CLI_ROOT`.
+   - Otherwise use `./cli` from the project root.
+2. Read any existing non-example API YAML first. Preserve existing endpoint IDs,
+   service names, auth flags, schema, response, and dangerous markers unless
+   source evidence proves they are wrong.
+3. Discover source locations and write scanner config:
+
+```bash
+node skills/evt-api-scanner/scripts/discover.js --root . --config-root ./cli
+```
+
+4. Generate or update endpoint YAML:
+
+```bash
+evt api sync --config-root ./cli
+```
+
+5. Enrich the generated YAML from source. Do not stop at scanner skeletons.
+6. Audit YAML quality:
+
+```bash
+evt api audit --config-root ./cli --strict
+```
+
+If strict audit fails because of empty schemas, generic responses, unresolved
+paths, or unmatched services, use the audit samples as the next edit queue and
+continue enrichment.
+
+7. Check YAML coverage:
+
+```bash
+evt api coverage --config-root ./cli
+```
+
+8. When bootstrapping an empty project, continue with:
+   - `evt-profile-generator` to create `data/profiles/*.json`.
+   - `evt-flow-generator` to create `data/flows/*.yaml`.
+
+## Source Evidence
+
+Collect these signals before finalizing YAML:
+
+- HTTP service declarations for method, path, body type, and function names.
+- Repository or client call sites for auth requirements, default arguments,
+  endpoint aliases, and feature ownership.
+- Request DTOs, method parameters, annotations, or typed request builders for
+  `schema.path`, `schema.query`, and `schema.body`.
+- Response DTOs, generic wrappers, serializers, or model declarations for
+  `response.envelope`, `response.data.model`, `response.data.type`, and fields.
+- App config, DI modules, HTTP clients, interceptors, or base URL providers for
+  `service` names and absolute URL handling.
+- Existing tests, docs, and product flows for dangerous operations and required
+  ordering.
+
+For Kotlin/KMP projects, inspect service interfaces, repositories, DTO/model
+files, app config, DI modules, and header/interceptor builders. For Swift, JS,
+and Dart projects, inspect equivalent API clients, request models, response
+models, environment config, and auth/header middleware.
+
+## Endpoint Format
+
+Endpoint definitions are always persisted as YAML under `data/apis/*.yaml` or
+legacy `apis/*.yaml`. JSON is only used as a machine-readable intermediate
+between scanner scripts and evt-cli.
+
+Example YAML:
+
+```yaml
+namespace: auth
+
+endpoints:
+  login:
+    method: "POST"
+    path: "/api/login"
+    auth: false
+    schema:
+      body:
+        email:
+          type: "string"
+          required: true
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "LoginData"
+        fields:
+          token: "string"
+          user:
+            type: "object"
+```
+
+## Quality Rules
+
+- Endpoint IDs should be stable. Preserve existing IDs. If no YAML exists, use
+  source function names exactly and do not add, remove, or normalize prefixes
+  such as `get` unless a project convention proves that mapping.
+- Do not leave `schema: {}` when source parameters or request DTOs exist.
+- Do not use generic `response.data.type: object` when a response type or DTO
+  can be resolved.
+- For wrapped responses such as `Resp<T>`, record the envelope and the nested
+  data model.
+- Preserve path parameters, query parameters embedded in path strings, and
+  absolute URLs. Map alternate hosts to `service` when profiles can provide a
+  named base URL.
+- Infer `auth` from the HTTP client, repository call path, interceptor, or
+  feature state. Public market/config endpoints are usually unauthenticated;
+  user/account/order/history endpoints usually require auth. Mark uncertain
+  cases in the final report.
+- Mark mutating or irreversible endpoints with `dangerous: true`; examples are
+  order creation/cancelation, withdrawal, transfer, account deletion, and
+  credential changes.
+- Keep scanner JSON internal. Runtime endpoint data remains YAML.
+
+## Completion Check
+
+Run these before final answer:
+
+```bash
+evt validate --config-root ./cli
+evt api audit --config-root ./cli --strict
+evt api coverage --config-root ./cli
+```
+
+Report endpoint count, empty-schema count, generic-response count, auth
+uncertain count, and any endpoints whose ID or path could not be resolved
+confidently.
+
+## Fallback
+
+evt-cli should prefer this skill scanner when configured. If the skill scanner
+fails or returns no endpoints, evt-cli falls back to the built-in regex scanner
+targets. The fallback exists for users without an agent or skill-aware workflow,
+but it is less complete.

package/skills/evt-api-scanner/scripts/discover.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".gradle",
+  ".idea",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".ufoo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "Pods",
+  "target"
+]);
+
+const LANGUAGE_DEFS = {
+  kotlin: {
+    extensions: [".kt"],
+    hints: [/Service\.kt$/i, /Api\.kt$/i, /Repository\.kt$/i, /http\.(get|post|put|patch|delete)/]
+  },
+  swift: {
+    extensions: [".swift"],
+    hints: [/Service\.swift$/i, /API\.swift$/i, /Api\.swift$/i, /client\.(get|post|put|patch|delete)/]
+  },
+  js: {
+    extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"],
+    hints: [/(service|api|client|request|http)\.[cm]?[jt]sx?$/i, /\b(fetch|axios)\s*\(/, /\.(get|post|put|patch|delete)\s*\(/]
+  },
+  dart: {
+    extensions: [".dart"],
+    hints: [/(service|api|client|repository)\.dart$/i, /\.(get|post|put|patch|delete)\s*\(/]
+  }
+};
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const raw = token.slice(2);
+    const equals = raw.indexOf("=");
+    const key = (equals >= 0 ? raw.slice(0, equals) : raw)
+      .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (key === "dryRun" || key === "json") {
+      options[key] = true;
+    } else {
+      options[key] = equals >= 0 ? raw.slice(equals + 1) : argv[++index];
+    }
+  }
+  return options;
+}
+
+function posixRelative(from, to) {
+  return path.relative(from, to).split(path.sep).join("/") || ".";
+}
+
+function defaultConfigRoot(cwd) {
+  if (process.env.EVT_CLI_ROOT) return path.resolve(process.env.EVT_CLI_ROOT);
+  if (process.env.EVERYTHING_CLI_ROOT) return path.resolve(process.env.EVERYTHING_CLI_ROOT);
+  if (path.basename(cwd) === "cli") return cwd;
+  return path.join(cwd, "cli");
+}
+
+function walkFiles(root, files = []) {
+  if (!fs.existsSync(root)) return files;
+  const stat = fs.statSync(root);
+  if (stat.isFile()) {
+    files.push(root);
+    return files;
+  }
+  if (!stat.isDirectory()) return files;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory() && IGNORE_DIRS.has(entry.name)) continue;
+    walkFiles(path.join(root, entry.name), files);
+  }
+  return files;
+}
+
+function fileLooksRelevant(file, language, root) {
+  const def = LANGUAGE_DEFS[language];
+  const relative = posixRelative(root, file);
+  const basename = path.basename(file);
+  const text = fs.readFileSync(file, "utf8").slice(0, 20000);
+  return def.hints.some((hint) => hint.test(basename) || hint.test(relative) || hint.test(text));
+}
+
+function collapseDirs(root, files) {
+  const dirs = [...new Set(files.map((file) => path.dirname(file)))]
+    .map((dir) => posixRelative(root, dir))
+    .sort((left, right) => left.length - right.length || left.localeCompare(right));
+  const collapsed = [];
+  for (const dir of dirs) {
+    if (!collapsed.some((parent) => dir === parent || dir.startsWith(`${parent}/`))) {
+      collapsed.push(dir);
+    }
+  }
+  return collapsed;
+}
+
+function discoverTargets(projectRoot) {
+  const files = walkFiles(projectRoot);
+  const targets = [];
+  for (const [language, def] of Object.entries(LANGUAGE_DEFS)) {
+    const matching = files
+      .filter((file) => def.extensions.includes(path.extname(file)))
+      .filter((file) => fileLooksRelevant(file, language, projectRoot));
+    if (matching.length === 0) continue;
+    targets.push({ language, paths: collapseDirs(projectRoot, matching) });
+  }
+  return targets;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+  const configRoot = path.resolve(options.configRoot || defaultConfigRoot(cwd));
+  const projectRoot = path.resolve(options.root || (path.basename(configRoot) === "cli" ? path.dirname(configRoot) : cwd));
+  const dataDir = path.join(configRoot, "data");
+  const apiDir = path.join(dataDir, "apis");
+  const scannerFile = path.resolve(options.scannerFile || path.join(dataDir, "scanner.json"));
+  const scannerDir = path.dirname(scannerFile);
+  const fallbackTargets = discoverTargets(projectRoot);
+  const config = {
+    root: posixRelative(scannerDir, projectRoot),
+    apiDir: posixRelative(scannerDir, apiDir),
+    targets: [
+      {
+        language: "skill",
+        name: "evt-api-scanner",
+        skill: "evt-api-scanner"
+      },
+      ...fallbackTargets
+    ]
+  };
+
+  if (!options.dryRun) {
+    fs.mkdirSync(apiDir, { recursive: true });
+    fs.mkdirSync(path.join(dataDir, "flows"), { recursive: true });
+    fs.mkdirSync(path.join(dataDir, "profiles"), { recursive: true });
+    fs.mkdirSync(scannerDir, { recursive: true });
+    fs.writeFileSync(scannerFile, `${JSON.stringify(config, null, 2)}\n`);
+  }
+
+  process.stdout.write(`${JSON.stringify({
+    wrote: !options.dryRun,
+    projectRoot,
+    configRoot,
+    scannerFile,
+    apiDir,
+    targets: config.targets
+  }, null, 2)}\n`);
+}
+
+main();

package/skills/evt-api-scanner/scripts/scan.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".gradle",
+  ".idea",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".ufoo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "Pods",
+  "target"
+]);
+
+const LANGUAGE_DEFS = {
+  kotlin: {
+    extensions: [".kt"],
+    receivers: ["http", "client", "api"],
+    helpers: ["get", "getRaw", "post", "postUrlEncoded", "postForm", "put", "patch", "delete", "deleteWithBody", "upload"],
+    functions: [/(?:override\s+)?suspend\s+fun\s+([A-Za-z_][A-Za-z0-9_]*)/g, /fun\s+([A-Za-z_][A-Za-z0-9_]*)/g],
+    stripPrefixes: ["I"],
+    stripSuffixes: ["Service", "Api", "API", "Repository"]
+  },
+  swift: {
+    extensions: [".swift"],
+    receivers: ["http", "client", "api"],
+    helpers: ["get", "post", "put", "patch", "delete", "upload"],
+    functions: [/func\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(/g],
+    stripSuffixes: ["Service", "Api", "API"]
+  },
+  js: {
+    extensions: [".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"],
+    receivers: ["http", "client", "api", "axios"],
+    helpers: ["get", "post", "put", "patch", "delete"],
+    functions: [
+      /(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g,
+      /(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?\(/g,
+      /([A-Za-z_$][A-Za-z0-9_$]*)\s*:\s*(?:async\s*)?function\s*\(/g
+    ],
+    stripSuffixes: ["Service", "Api", "API"]
+  },
+  dart: {
+    extensions: [".dart"],
+    receivers: ["http", "client", "api", "dio"],
+    helpers: ["get", "post", "put", "patch", "delete"],
+    functions: [
+      /(?:Future(?:<[^>]+>)?|Stream(?:<[^>]+>)?|void|[A-Za-z_][A-Za-z0-9_<>?]*)\s+([A-Za-z_][A-Za-z0-9_]*)\s*\([^)]*\)\s*(?:async\s*)?\{/g
+    ],
+    stripSuffixes: ["Service", "Api", "API"]
+  }
+};
+
+const METHOD_BY_HELPER = {
+  get: "GET",
+  getRaw: "GET",
+  fetch: "GET",
+  post: "POST",
+  postForm: "POST",
+  postUrlEncoded: "POST",
+  put: "PUT",
+  patch: "PATCH",
+  delete: "DELETE",
+  deleteWithBody: "DELETE",
+  upload: "POST"
+};
+
+const STRING_PATTERN = `"([^"]+)"|'([^']+)'|\`([^\`]+)\``;
+
+function parseArgs(argv) {
+  const options = { paths: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      options.paths.push(token);
+      continue;
+    }
+    const raw = token.slice(2);
+    const equals = raw.indexOf("=");
+    const key = (equals >= 0 ? raw.slice(0, equals) : raw)
+      .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    options[key] = equals >= 0 ? raw.slice(equals + 1) : argv[++index];
+  }
+  return options;
+}
+
+function posixRelative(from, to) {
+  return path.relative(from, to).split(path.sep).join("/") || ".";
+}
+
+function walkFiles(root, files = []) {
+  if (!fs.existsSync(root)) return files;
+  const stat = fs.statSync(root);
+  if (stat.isFile()) {
+    files.push(root);
+    return files;
+  }
+  if (!stat.isDirectory()) return files;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory() && IGNORE_DIRS.has(entry.name)) continue;
+    walkFiles(path.join(root, entry.name), files);
+  }
+  return files;
+}
+
+function languageForFile(file) {
+  const extension = path.extname(file);
+  return Object.entries(LANGUAGE_DEFS).find(([, def]) => def.extensions.includes(extension))?.[0];
+}
+
+function makeRegexUnion(values) {
+  return values.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+}
+
+function firstQuoted(match, startIndex) {
+  for (let index = startIndex; index < match.length; index += 1) {
+    if (match[index] !== undefined) return match[index];
+  }
+  return undefined;
+}
+
+function nearestFunction(source, index, def) {
+  const before = source.slice(0, index);
+  let nearest = { index: -1, name: "unknown" };
+  for (const pattern of def.functions) {
+    pattern.lastIndex = 0;
+    for (const match of before.matchAll(pattern)) {
+      if (match.index > nearest.index) nearest = { index: match.index, name: match[1] };
+    }
+  }
+  return nearest.name;
+}
+
+function namespaceForFile(file, language) {
+  const def = LANGUAGE_DEFS[language];
+  let namespace = path.basename(file, path.extname(file));
+  for (const prefix of def.stripPrefixes || []) {
+    if (namespace.startsWith(prefix)) namespace = namespace.slice(prefix.length);
+  }
+  for (const suffix of def.stripSuffixes || []) {
+    if (namespace.endsWith(suffix)) namespace = namespace.slice(0, -suffix.length);
+  }
+  return namespace.replace(/^[A-Z]/, (letter) => letter.toLowerCase());
+}
+
+function normalizePath(rawPath, language) {
+  if (!rawPath || !rawPath.startsWith("/")) return undefined;
+  let value = rawPath
+    .replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, ":$1")
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, ":$1");
+  if (language === "swift") value = value.replace(/\\\(([A-Za-z_][A-Za-z0-9_]*)\)/g, ":$1");
+  return value;
+}
+
+function bodyTypeFor(helper) {
+  if (helper === "postUrlEncoded") return "formUrlEncoded";
+  if (helper === "postForm" || helper === "upload") return "multipart";
+  return "json";
+}
+
+function pushEndpoint(endpoints, seen, file, root, source, language, helper, rawPath, matchIndex, explicitMethod) {
+  const pathTemplate = normalizePath(rawPath, language);
+  if (!pathTemplate) return;
+  const namespace = namespaceForFile(file, language);
+  const functionName = nearestFunction(source, matchIndex, LANGUAGE_DEFS[language]);
+  const method = String(explicitMethod || METHOD_BY_HELPER[helper] || helper).toUpperCase();
+  const key = `${method}:${pathTemplate}:${functionName}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  endpoints.push({
+    id: `${namespace}.${functionName}`,
+    namespace,
+    functionName,
+    method,
+    path: pathTemplate,
+    bodyType: bodyTypeFor(helper),
+    helper,
+    file: posixRelative(root, file),
+    source: "evt-api-scanner"
+  });
+}
+
+function scanFile(file, root) {
+  const language = languageForFile(file);
+  if (!language) return [];
+  const def = LANGUAGE_DEFS[language];
+  const source = fs.readFileSync(file, "utf8");
+  const endpoints = [];
+  const seen = new Set();
+  const receiverPattern = makeRegexUnion(def.receivers);
+  const helperPattern = makeRegexUnion(def.helpers);
+  const calls = [
+    new RegExp(`\\b(?:${receiverPattern})\\s*\\.\\s*(${helperPattern})(?:<[^>]+>)?\\s*\\(\\s*(?:${STRING_PATTERN})`, "g"),
+    new RegExp(`\\b(?:${receiverPattern})\\s*\\.\\s*(${helperPattern})(?:<[^>]+>)?\\s*\\([\\s\\S]{0,300}?\\burl\\s*=\\s*(?:${STRING_PATTERN})`, "g"),
+    new RegExp(`\\b(?:${receiverPattern})\\s*\\.\\s*(${helperPattern})\\s*\\(\\s*Uri\\.parse\\s*\\(\\s*(?:${STRING_PATTERN})`, "g")
+  ];
+  for (const pattern of calls) {
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+      pushEndpoint(endpoints, seen, file, root, source, language, match[1], firstQuoted(match, 2), match.index);
+    }
+  }
+
+  if (language === "js") {
+    const fetchCall = new RegExp(`\\bfetch\\s*\\(\\s*(?:${STRING_PATTERN})([\\s\\S]{0,300}?)\\)`, "g");
+    let match;
+    while ((match = fetchCall.exec(source)) !== null) {
+      const optionsSource = match[4] || "";
+      const methodMatch = optionsSource.match(/\bmethod\s*:\s*["'`]([A-Za-z]+)["'`]/);
+      pushEndpoint(endpoints, seen, file, root, source, language, "fetch", firstQuoted(match, 1), match.index, methodMatch && methodMatch[1]);
+    }
+  }
+  return endpoints;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const root = path.resolve(options.root || process.env.EVT_SCAN_ROOT || process.cwd());
+  const entries = options.paths.length > 0 ? options.paths.map((entry) => path.resolve(root, entry)) : [root];
+  const files = entries.flatMap((entry) => walkFiles(entry)).filter(languageForFile);
+  const endpoints = files.flatMap((file) => scanFile(file, root));
+  process.stdout.write(`${JSON.stringify({ endpoints }, null, 2)}\n`);
+}
+
+main();

package/skills/evt-flow-generator/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: evt-flow-generator
+description: Use when an agent needs to create or update evt-cli YAML flows from API YAML definitions, product workflows, authentication requirements, or test scenarios, including interactive inputs, waits, token cache saves, and feature smoke flows.
+---
+
+# evt-flow-generator
+
+Use this skill to produce executable evt-cli flows under `data/flows/*.yaml` or
+legacy `flows/*.yaml`.
+
+## Workflow
+
+1. Locate the evt config root.
+   - Prefer the user's explicit `--config-root`.
+   - Otherwise use `EVT_CLI_ROOT`.
+   - Otherwise use `./cli` from the project root.
+2. Inspect available endpoints:
+
+```bash
+evt api list --config-root ./cli
+evt api show <namespace.endpoint> --config-root ./cli
+```
+
+3. Read existing flow examples and product docs/source to identify:
+   - login or session refresh sequence
+   - token field path in the login response
+   - prerequisite calls for feature flows
+   - required waits between calls
+   - safe smoke-test values from profile fixtures
+4. Read the evt runtime semantics before saving values:
+   - each step result contains `response`, the full parsed response
+   - each step result contains `data`, the unwrapped `response.data` when present
+   - for wrapped APIs, prefer `steps.<id>.response.data.<field>` for cache saves
+5. Write YAML flows such as:
+   - `data/flows/login.yaml`
+   - `data/flows/smoke.yaml`
+   - `data/flows/<feature>.yaml`
+6. Validate:
+
+```bash
+evt validate --config-root ./cli
+```
+
+## Flow Format
+
+```yaml
+name: login
+description: Login and save session token.
+
+inputs:
+  email:
+    prompt: Email
+    type: string
+    required: true
+  password:
+    prompt: Password
+    type: password
+    required: true
+
+steps:
+  - id: login
+    call: auth.login
+    body:
+      email: "{{inputs.email}}"
+      password: "{{inputs.password}}"
+    expect:
+      path: response.data.token
+      exists: true
+
+save:
+  cache:
+    token: "{{steps.login.response.data.token}}"
+  required:
+    - cache.token
+```
+
+Use waits when the backend needs spacing:
+
+```yaml
+steps:
+  - id: createOrder
+    call: trade.createOrder
+    body:
+      symbol: "{{inputs.symbol}}"
+      side: "BUY"
+  - wait: 2s
+  - id: queryOrder
+    call: trade.orderDetail
+    query:
+      orderId: "{{steps.createOrder.response.data.orderId}}"
+```
+
+Use `afterWait` when only one step needs a post-call interval.
+
+## Rules
+
+- Runtime flows are YAML. Do not persist flow definitions as JSON.
+- Keep bundled `*.example.yaml` generic; write project-specific flows to
+  non-example YAML files.
+- Use `inputs` for values a user may need to type dynamically.
+- Use `profile.inputs` by naming flow inputs the same way as profile keys.
+- Use profile-backed values for device/session fields when source does so, for
+  example `{{profile.device.fingerprintId}}` instead of a new placeholder input.
+- Use `wait` or `afterWait` for backend intervals; valid values include `500ms`,
+  `2s`, and `1m`.
+- Preserve waits found in source, tests, docs, or existing flows.
+- Save login state through `save.cache.token` and `save.required`. For wrapped
+  responses, prefer `{{steps.login.response.data.token}}`.
+- Reference previous step outputs with `{{steps.<id>.<path>}}`.
+- Prefer `expect` checks for required response fields when a flow depends on
+  them.
+- Put logout last in flows that include logout.
+- For feature flows, include prerequisite reads, state-changing calls, follow-up
+  reads, waits, cleanup, and final assertions when the scenario needs them.
+- Use endpoint schema and profile fixtures to build request bodies. Do not
+  invent field names that are absent from endpoint YAML or source models.
+- Do not include destructive business actions unless the project or user states
+  that the environment is safe for testing.
+
+## Completion Check
+
+After writing flows, run:
+
+```bash
+evt validate --config-root ./cli
+evt flow run login --config-root ./cli --profile <profile> --dry-run
+```
+
+For login flows, inspect the dry-run output and verify:
+
+- the expected endpoint order is present
+- required waits are present
+- token save path matches the response model
+- headers come from the selected profile
+- no required input is missing
+
+When real credentials and a safe test environment are available, run the login
+flow without `--dry-run`, confirm the token is written to cache, then run the
+authenticated smoke or feature flow. Report any step that was only inferred.