@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/cases/zephyr.ts

@@ -0,0 +1,153 @@
+import type { SourcesConfig } from "../config.ts"
+import { envSecret, htmlToText, http } from "./http.ts"
+import { resultText } from "./jira.ts"
+import type { CaseResult, CaseStep, TestCase, WriteBack } from "./types.ts"
+
+type ZCase = { key: string; name: string; objective?: string | null; precondition?: string | null; labels?: string[]; folder?: { id?: number } | null }
+type ZStep = { inline?: { description?: string | null; testData?: string | null; expectedResult?: string | null } | null; testCase?: { testCaseKey?: string } | null }
+type Paged<T> = { values?: T[]; isLast?: boolean; total?: number }
+
+export function zephyrApi(cfg: SourcesConfig): { api: string; auth: string; projectKey?: string } {
+  const z = cfg.zephyr
+  if (!z) throw new Error("Zephyr Scale is not set up. Add sources.zephyr to forgeqe.yaml, or set ZEPHYR_API_TOKEN.")
+  return { api: z.url, auth: `Bearer ${envSecret(z.tokenEnv, "Zephyr Scale")}`, projectKey: z.projectKey }
+}
+
+/** "SHOP-T12" → "SHOP": Zephyr Scale keys are the Jira project key, "-T", and a number. */
+export const zephyrProject = (key: string) => key.slice(0, key.lastIndexOf("-T"))
+
+async function paged<T>(url: string, auth: string): Promise<T[]> {
+  const out: T[] = []
+  for (let start = 0; ; start += 100) {
+    const { data } = await http<Paged<T>>(`${url}${url.includes("?") ? "&" : "?"}maxResults=100&startAt=${start}`, { auth })
+    const page = data?.values || []
+    out.push(...page)
+    if (!page.length || data?.isLast !== false) break
+  }
+  return out
+}
+
+async function steps(key: string, api: string, auth: string, depth = 0): Promise<CaseStep[]> {
+  const out: CaseStep[] = []
+  for (const s of await paged<ZStep>(`${api}/testcases/${encodeURIComponent(key)}/teststeps`, auth)) {
+    if (s.testCase?.testCaseKey && depth < 2) out.push(...(await steps(s.testCase.testCaseKey, api, auth, depth + 1)))
+    const action = htmlToText(s.inline?.description || "")
+    if (action) out.push({ action, data: htmlToText(s.inline?.testData || "") || undefined, expected: htmlToText(s.inline?.expectedResult || "") || undefined })
+  }
+  return out
+}
+
+const folderNames = new Map<string, Promise<string | undefined>>()
+
+/** A folder's name, for grouping cases in reports; undefined when it cannot be read. */
+function folderName(id: number | undefined, api: string, auth: string): Promise<string | undefined> {
+  if (id === undefined) return Promise.resolve(undefined)
+  const key = `${api}|${id}`
+  if (!folderNames.has(key)) {
+    folderNames.set(key, http<{ name?: string }>(`${api}/folders/${id}`, { auth }).then((r) => r.data?.name || undefined, () => undefined))
+  }
+  return folderNames.get(key)!
+}
+
+async function toCase(c: ZCase, api: string, auth: string, cycle?: string): Promise<TestCase> {
+  return {
+    id: c.key,
+    title: c.name,
+    source: "zephyr",
+    description: htmlToText(c.objective || "") || undefined,
+    preconditions: htmlToText(c.precondition || "") ? [htmlToText(c.precondition || "")] : undefined,
+    steps: await steps(c.key, api, auth),
+    tags: c.labels?.length ? c.labels : undefined,
+    group: await folderName(c.folder?.id ?? undefined, api, auth),
+    ref: { testCase: c.key, ...(cycle ? { cycle } : {}) },
+  }
+}
+
+/** The test case key in a reference like https://api.zephyrscale.smartbear.com/v2/testcases/SHOP-T1/versions/1. */
+function keyFromSelf(self: string | undefined): string | undefined {
+  const parts = (self || "").split("/")
+  const i = parts.indexOf("testcases")
+  return i >= 0 ? decodeURIComponent(parts[i + 1] || "") || undefined : undefined
+}
+
+/** `zephyr:SHOP-T1,SHOP-T2`, `zephyr:cycle=SHOP-R5` (results go to that cycle), or `zephyr:folder=123` (needs project_key). */
+export async function zephyrCases(ref: string, cfg: SourcesConfig): Promise<TestCase[]> {
+  const z = zephyrApi(cfg)
+  const cycle = ref.match(/^cycle=(.+)$/i)?.[1]?.trim().toUpperCase()
+  const folder = ref.match(/^folder=(\d+)$/i)?.[1]
+  const get = async (key: string) => (await http<ZCase>(`${z.api}/testcases/${encodeURIComponent(key)}`, { auth: z.auth })).data
+  const out: TestCase[] = []
+  if (cycle) {
+    const project = cycle.includes("-R") ? cycle.slice(0, cycle.lastIndexOf("-R")) : z.projectKey
+    const executions = await paged<{ testCase?: { self?: string } }>(
+      `${z.api}/testexecutions?testCycle=${encodeURIComponent(cycle)}${project ? `&projectKey=${encodeURIComponent(project)}` : ""}`,
+      z.auth,
+    )
+    const keys = [...new Set(executions.map((e) => keyFromSelf(e.testCase?.self)).filter((k): k is string => Boolean(k)))]
+    for (const key of keys) out.push(await toCase(await get(key), z.api, z.auth, cycle))
+    if (!out.length) throw new Error(`No test cases in Zephyr Scale cycle ${cycle}.`)
+    return out
+  }
+  if (folder) {
+    if (!z.projectKey) throw new Error("Zephyr Scale folders need sources.zephyr.project_key in forgeqe.yaml.")
+    for (const c of await paged<ZCase>(`${z.api}/testcases?projectKey=${encodeURIComponent(z.projectKey)}&folderId=${folder}`, z.auth)) out.push(await toCase(c, z.api, z.auth))
+    if (!out.length) throw new Error(`No test cases in Zephyr Scale folder ${folder}.`)
+    return out
+  }
+  const keys = ref.split(/[,\s]+/).map((k) => k.trim().toUpperCase()).filter(Boolean)
+  if (!keys.length || keys.some((k) => !k.includes("-T"))) throw new Error(`Zephyr Scale reference "${ref}": use zephyr:SHOP-T1,SHOP-T2, zephyr:cycle=SHOP-R5, or zephyr:folder=123.`)
+  for (const key of keys) out.push(await toCase(await get(key), z.api, z.auth))
+  return out
+}
+
+const STATUS = { passed: "Pass", failed: "Fail", error: "Blocked" } as const
+const STEP_STATUS = { passed: "Pass", failed: "Fail", not_run: "Not Executed" } as const
+
+/** One test execution per case, in the cycle the cases came from or in a new cycle per project. */
+export async function zephyrWriteBack(results: CaseResult[], cfg: SourcesConfig, runName: string): Promise<WriteBack[]> {
+  const z = zephyrApi(cfg)
+  const out: WriteBack[] = []
+  const newCycles = new Map<string, string>()
+  const recorded = new Map<string, number>()
+  for (const r of results) {
+    const key = String(r.case.ref?.testCase || r.case.id)
+    const projectKey = zephyrProject(key)
+    try {
+      let cycle = r.case.ref?.cycle ? String(r.case.ref.cycle) : newCycles.get(projectKey)
+      if (!cycle) {
+        const { data } = await http<{ key: string }>(`${z.api}/testcycles`, { auth: z.auth, body: { projectKey, name: runName } })
+        cycle = data.key
+        newCycles.set(projectKey, cycle)
+      }
+      const verdicts = new Map((r.stepResults || []).map((v) => [v.step, v]))
+      const body: Record<string, unknown> = {
+        projectKey,
+        testCaseKey: key,
+        testCycleKey: cycle,
+        statusName: STATUS[r.status as keyof typeof STATUS] ?? "Blocked",
+        executionTime: r.ms,
+        actualEndDate: r.finishedAt,
+        comment: resultText(r).replace(/\n/g, "<br>"),
+      }
+      const scripted = verdicts.size
+        ? {
+            ...body,
+            testScriptResults: r.case.steps.map((_, i) => {
+              const v = verdicts.get(i + 1)
+              return { statusName: v ? STEP_STATUS[v.status] : "Not Executed", actualEndDate: r.finishedAt, actualResult: v?.actual || "" }
+            }),
+          }
+        : body
+      await http(`${z.api}/testexecutions`, { auth: z.auth, body: scripted }).catch((err) =>
+        scripted === body ? Promise.reject(err) : http(`${z.api}/testexecutions`, { auth: z.auth, body }),
+      )
+      recorded.set(cycle, (recorded.get(cycle) || 0) + 1)
+    } catch (err) {
+      out.push({ source: "zephyr", caseId: r.case.id, text: `${key}: result not recorded`, error: (err as Error).message })
+    }
+  }
+  for (const [cycle, n] of recorded) {
+    out.push({ source: "zephyr", text: `Zephyr Scale cycle ${cycle}${[...newCycles.values()].includes(cycle) ? " (new)" : ""}: ${n} execution${n === 1 ? "" : "s"}` })
+  }
+  return out
+}

package/src/childEnv.ts

@@ -0,0 +1,86 @@
+import { savedSecrets } from "./auth/store.ts"
+import type { AppConfig } from "./config.ts"
+import { NO_TELEMETRY_ENV, withoutTelemetry } from "./privacy.ts"
+
+/**
+ * What each process ForgeQE starts may see of its environment. The engine gets an allow-list (system settings, its own
+ * tuning, the active model key, and saved-login variables); the user's test commands and the agent runtime get everything
+ * except the secrets ForgeQE itself holds that their job does not need.
+ */
+
+type Env = Record<string, string | undefined>
+
+/** System settings a browser, Python, or a package manager needs: locale, display, temp folders, proxies, certificates. */
+const SYSTEM_NAMES = new Set([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE", "TZ", "TERM", "COLORTERM",
+  "DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS",
+  "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY",
+  "SSL_CERT_FILE", "SSL_CERT_DIR", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE", "NODE_EXTRA_CA_CERTS",
+  "VIRTUAL_ENV", "FORGEQE_HOME", "FORGEQE_PYTHON",
+  // Windows
+  "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT", "APPDATA", "LOCALAPPDATA", "PROGRAMDATA", "PROGRAMFILES",
+  "PROGRAMFILES(X86)", "PROGRAMW6432", "COMMONPROGRAMFILES", "USERPROFILE", "USERNAME", "USERDOMAIN", "HOMEDRIVE", "HOMEPATH",
+  "NUMBER_OF_PROCESSORS", "PROCESSOR_ARCHITECTURE", "OS",
+])
+const SYSTEM_PREFIXES = ["LC_", "XDG_", "BROWSER_USE_", "FORGEQE_ENGINE_", "UV_", "PIP_", "PYTHON", "PYENV", "CONDA", "CHROME", "PLAYWRIGHT_"]
+
+function isSystem(name: string): boolean {
+  const n = name.toUpperCase()
+  return SYSTEM_NAMES.has(n) || SYSTEM_PREFIXES.some((p) => n.startsWith(p))
+}
+
+/** `env` with telemetry off, keeping only system settings and `names`. */
+export function allowListEnv(env: Env, names: Iterable<string>): Record<string, string> {
+  const keep = new Set([...names].filter(Boolean))
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(withoutTelemetry(env))) if (isSystem(k) || keep.has(k)) out[k] = v
+  return { ...out, ...NO_TELEMETRY_ENV }
+}
+
+/** `env` with telemetry off and `names` removed. */
+export function withoutNames(env: Env, names: Iterable<string>): Record<string, string> {
+  const drop = new Set(names)
+  const out = withoutTelemetry(env)
+  for (const k of Object.keys(out)) if (drop.has(k)) delete out[k]
+  return out
+}
+
+const ENV_REF = /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/** The variable names `{env:NAME}` references in `value` (any JSON-like value). */
+export function envRefs(value: unknown): string[] {
+  return [...new Set([...JSON.stringify(value ?? null).matchAll(ENV_REF)].map((m) => m[1]!))]
+}
+
+/** Login variables (usernameEnv, passwordEnv, totpEnv): test credentials that the tests themselves read. */
+const LOGIN_KEYS = new Set(["usernameEnv", "passwordEnv", "totpEnv"])
+
+function collectEnvNames(value: unknown, out: Set<string>, inLogins: boolean): void {
+  if (Array.isArray(value)) {
+    for (const v of value) collectEnvNames(v, out, inLogins)
+    return
+  }
+  if (!value || typeof value !== "object") return
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "string" && /Env$/.test(k) && v && !(inLogins && LOGIN_KEYS.has(k))) out.add(v)
+    else collectEnvNames(v, out, inLogins || k === "logins")
+  }
+}
+
+/**
+ * Secrets ForgeQE holds for itself: every model profile's key variable, test case system and alert credentials
+ * (`*Env` settings), and variables `mcp:` servers reference. Saved-login variables are left out: tests read them.
+ */
+export function privateEnvNames(cfg: AppConfig, extra: Iterable<string> = []): string[] {
+  const out = new Set<string>(extra)
+  collectEnvNames({ ...cfg, logins: undefined }, out, false)
+  for (const name of envRefs(cfg.mcp)) out.add(name)
+  // Secrets a saved sign-in put into the environment, including those saved by name (forgeqe auth login NAME).
+  for (const name of savedSecrets) out.add(name)
+  return [...out]
+}
+
+/** Variables the saved logins read: the engine needs them to sign in, tests to log in. */
+export function loginEnvNames(logins: { usernameEnv?: string; passwordEnv?: string; totpEnv?: string }[]): string[] {
+  return logins.flatMap((l) => [l.usernameEnv, l.passwordEnv, l.totpEnv]).filter((n): n is string => Boolean(n))
+}

package/src/cli/args.ts

@@ -0,0 +1,114 @@
+import path from "node:path"
+
+import { replayMode } from "../config.ts"
+
+/** Command-line arguments: flags, switches, and the values commands read from them. */
+
+export type Flags = Map<string, string | boolean>
+
+/** Flags that never take the next word as their value, so `run --direct "<goal>"` keeps the goal. `--headed=false` still works. */
+export const SWITCHES = new Set([
+  "all", "check", "debug", "direct", "force", "global", "guide", "headed", "help", "locators", "no-code", "no-memory", "no-write-back",
+  "once", "open", "plain", "shots", "steps", "test-alerts", "user", "verbose", "yes",
+])
+
+export function parseArgs(argv: string[]): { positionals: string[]; flags: Flags } {
+  const positionals: string[] = []
+  const flags: Flags = new Map()
+  const alias: Record<string, string> = {
+    p: "profile",
+    u: "url",
+    g: "goal",
+    o: "out",
+    d: "dir",
+    c: "config",
+    h: "help",
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]
+    if (token === "--") {
+      positionals.push(...argv.slice(i + 1))
+      break
+    }
+    if (token.startsWith("--")) {
+      const body = token.slice(2)
+      const eq = body.indexOf("=")
+      // --skill repeats: each value is added to the list.
+      const set = (key: string, value: string | boolean) => {
+        const before = flags.get(key)
+        flags.set(key, key === "skill" && typeof before === "string" && typeof value === "string" ? `${before},${value}` : value)
+      }
+      if (eq >= 0) {
+        set(body.slice(0, eq), body.slice(eq + 1))
+        continue
+      }
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith("-") || SWITCHES.has(body)) set(body, true)
+      else {
+        set(body, next)
+        i++
+      }
+      continue
+    }
+    if (token.startsWith("-") && token.length === 2) {
+      const key = alias[token.slice(1)] || token.slice(1)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith("-") || SWITCHES.has(key)) flags.set(key, true)
+      else {
+        flags.set(key, next)
+        i++
+      }
+      continue
+    }
+    positionals.push(token)
+  }
+  return { positionals, flags }
+}
+
+export function strFlag(flags: Flags, name: string): string | undefined {
+  const value = flags.get(name)
+  return typeof value === "string" ? value : undefined
+}
+
+export function boolFlag(flags: Flags, name: string): boolean {
+  const value = flags.get(name)
+  if (value === undefined || value === false) return false
+  if (value === true) return true
+  return !/^(0|false|no|off)$/i.test(value)
+}
+
+/** --skill NAME (repeatable, or comma-separated): browser skills for every run; `--skill none` runs without any. Unset: the engine picks. */
+export function skillFlags(flags: Flags): string[] | undefined {
+  const raw = strFlag(flags, "skill")
+  if (raw === undefined) return undefined
+  const names = raw.split(",").map((n) => n.trim()).filter(Boolean)
+  return names.includes("none") ? [] : names
+}
+
+export function configOpts(flags: Flags) {
+  return {
+    configPath: strFlag(flags, "config"),
+    profile: strFlag(flags, "profile"),
+  }
+}
+
+export function memoryFlags(flags: Flags) {
+  const replay = strFlag(flags, "replay")
+  return {
+    replay: replay ? replayMode(replay) : undefined,
+    memory: boolFlag(flags, "no-memory") ? false : undefined,
+  }
+}
+
+export function maxStepsFlag(flags: Flags): number | undefined {
+  const raw = strFlag(flags, "max-steps")
+  if (raw && !(Number(raw) >= 1)) throw new Error("--max-steps must be a positive number")
+  return raw ? Number(raw) : undefined
+}
+
+/** --repo DIR, null for --no-code, undefined for code.repo from forgeqe.yaml. */
+export function repoFlag(flags: Flags): string | null | undefined {
+  if (boolFlag(flags, "no-code")) return null
+  const dir = strFlag(flags, "repo")
+  return dir ? path.resolve(dir) : undefined
+}

package/src/cli/help.ts

@@ -0,0 +1,167 @@
+import { HELP } from "../commands.ts"
+
+/** `forgeqe --help`. */
+
+export const HELP_TEXT = `ForgeQE — browser agent CLI
+
+Live runs use the ForgeQE engine (Python) with an OpenTUI shell. Tests are written by Scribe, the coding agent.
+No FastAPI or database. LLM profiles live in llms.json, settings in forgeqe.yaml.
+
+Usage:
+  forgeqe init [--dir .] [--global] [--force] [--profile name]
+  forgeqe setup [--force]
+  forgeqe models [--config forgeqe.yaml]
+  forgeqe features [--config forgeqe.yaml]   what ForgeQE can do, and what each capability still needs here
+  forgeqe docs [--guide|--open] [--copy DIR]  the guides and the architecture page (--guide: the user guide in the browser; --open: the architecture page)
+  forgeqe start [--profile name] [--url URL] [--goal TEXT] [--headed] [--replay MODE] [--no-memory]
+                 [--repo DIR] [--no-code]
+  forgeqe run "<request>" [--profile name] [--url URL] [--headed] [--plain] [--max-steps N]
+               [--repo DIR] [--no-code] [--replay MODE] [--no-memory] [--attempts N] [--code-model provider/model]
+                                               ForgeQE's agent works out what the request needs: a browser goal,
+                                               test cases from Jira, Azure DevOps, Xray or files, a test, a pipeline
+  forgeqe run --direct "<goal>" [--out DIR] [--skill NAME] ...  one browser goal, no agent
+  forgeqe suite <source...> [--parallel N] [--repo DIR] [--no-code] [--no-write-back] [--out DIR]
+                 [--profile name] [--url URL] [--headed] [--plain] [--attempts N] [--skill NAME]
+                                               run test cases the same way every time (what pipelines call)
+  forgeqe cases <source...> [--goal]          list the test cases a source gives (--goal: the goal each runs)
+  forgeqe code [run-dir] [--repo DIR] [--attempts N] [--code-model provider/model]
+                                               write a test for a run (default: the latest) with Scribe
+  forgeqe heal ["<test command>"] [--repo DIR] [--attempts N] [--code-model provider/model] [--headed] [--plain]
+                                               run the repo's tests and heal the ones the app has outgrown
+  forgeqe monitor [source...] [--every 15m] [--once] [--replay MODE] [--parallel N] [--out DIR] [--verbose] [--skill NAME]
+                                               check flows on a schedule and alert Teams or email when one breaks
+  forgeqe monitor --test-alerts               send a sample alert to check the Teams and email settings
+  forgeqe mcp [--repo DIR] [--profile name] [--url URL] [--headed]
+                                               ForgeQE's tools as an MCP server on stdio, for other agents
+  forgeqe mcp list                            the Azure DevOps, Jira and other MCP servers ForgeQE's agent gets
+  forgeqe pr-tests [pr] [--base BRANCH] [--agent] [--run] [--post]
+                                               the tests a pull request (or the commits since BRANCH) can break; --run runs
+                                               them and exits 1 when one fails (a CI gate), --post puts the results on the PR
+  forgeqe quality [run-dir]                   a run's WCAG rules passed and failed, Core Web Vitals, and budgets
+  forgeqe quality trends [page]               accessibility and timings per page over time: what got worse or better
+  forgeqe notify test [channel]                  send a test card to the Teams and email notification channels
+  forgeqe eval domain [--only id,id] [--min 0.8]  does the agent apply domain and regulatory knowledge? (with the domain declared and without)
+  forgeqe prompts [list]                      every agent prompt and where it comes from (ForgeQE's or your edited copy)
+  forgeqe prompts show|diff|reset <name>      read one, see how yours differs from ForgeQE's, or go back to ForgeQE's
+  forgeqe visual [run-dir]                    each page of a run against its approved screenshot: same, changed (with a diff), new
+  forgeqe visual approve [run-dir] [--page a,b] [--yes]
+                                               make the run's screenshots the new baselines (an intended change)
+  forgeqe explore <story> [--url URL] [--charters N] [--roles a,b] [--focus TEXT] [--yes] [--file-bugs]
+                                               exploratory testing of a story (ado:123, SHOP-12, a link, or its text):
+                                               charters beyond the scripted cases, defects confirmed by a second run,
+                                               proposed test cases, bugs for confirmed defects; exits 1 on a defect
+  forgeqe api contracts --spec <link|file>    API contracts from OpenAPI/Swagger, WSDL, GraphQL, .proto, or grpc://host:port
+  forgeqe api contracts --run [RUN]           API contracts from the calls a browser run saw the app make (latest run)
+  forgeqe api run [SET] [--base-url URL] [--only a,b] [--allow-writes]
+                                               run contracts against the API (no browser); exits 1 when one fails
+  forgeqe api tests [SET] [--repo DIR] [--include-writes]
+                                               the coding agent writes them as API tests in the repository's framework
+  forgeqe api scenarios --run [RUN]           an end-to-end API scenario from a browser run: values chained call to call
+  forgeqe api scenarios [SET] [--spec <link|file>] [--no-negative]
+                                               lifecycle, browse, linked, and negative scenarios from an API description
+  forgeqe api scenarios --cases <ado:2238,...> | --text "<scenario>" [--spec <link|file>]
+                                               scenarios planned from test cases or plain English
+  forgeqe api run-scenarios [SET] [--allow-writes] [--base-url URL]
+                                               run them against the API; exits 1 when one fails
+  forgeqe api tests [SET] --scenarios[=a,b] --repo DIR
+                                               scenario tests on the repository's existing API helpers
+  forgeqe api list                            saved contract sets
+  forgeqe auth login [system] [--no-browser]  sign in to azure_devops, github, jira, confluence, testrail, zephyr, qtest
+                                               or xray in the browser, and save the token in the system's credential store
+  forgeqe auth login <ENV_NAME>               save one secret (an LLM API key, a webhook URL) in the credential store
+  forgeqe auth [status]                       which systems are signed in, and how
+  forgeqe auth logout <system|ENV_NAME>       forget a saved sign-in
+  forgeqe login <name> [--url URL]            sign in once by hand in a browser; runs reuse the saved session
+  forgeqe logins [clear <name>|--all]         saved logins (logins: in forgeqe.yaml) and their sessions
+  forgeqe memory [list]                       hosts, pages, elements and flows in page memory
+  forgeqe memory show <host|url> [--locators] [--all]
+  forgeqe memory flows [--steps]
+  forgeqe memory clear [host] --yes
+  forgeqe skills [list|check]                 the skills each agent can use, where they come from, and problems
+  forgeqe skills show <name>                  one skill's instructions
+  forgeqe skills new <name> [--user] [--agent browser|scribe|forgeqe] [--description TEXT]
+                                               a new skill in .forgeqe/skills (--user: ~/.forgeqe/skills)
+  forgeqe skills enable|disable <name>        turn a skill on or off for this project (skills.disable)
+  forgeqe logs                                recent session logs (one per forgeqe session, in .forgeqe/logs)
+  forgeqe logs bundle [log] [--shots]         one archive to share for debugging: the session log, its run
+                                               folders (--shots: with screenshots), settings without secrets
+  forgeqe update [version] [--check] [--wait MIN]
+                                               update every forgeqe on PATH (bun, npm and pip installs) to the
+                                               latest release, waiting while the registries catch up (default 20)
+  forgeqe --version
+  --debug (or FORGEQE_DEBUG=1) on any command  also log the browser engine's debug output and keep long values whole
+  --verbose (or FORGEQE_VERBOSE=1)             show everything the agents do while they work: the browser agent's
+                                               reasoning, page memory, engine logs, every file the coding agent reads
+                                               (default: progress, step results, files written, test results, problems)
+
+Page memory (memory: in forgeqe.yaml; default .forgeqe/memory next to it, or ~/.forgeqe/memory) keeps every element seen on each
+page with ranked locators and a confidence %, plus the steps of each goal's last successful run.
+--replay verify   replay a known goal without the LLM, then one LLM step checks the result (default)
+--replay trust    replay and finish without the LLM when every step works
+--replay off      never replay; still record pages
+
+ForgeQE's agent (forgeqe start, forgeqe run) runs on the agent runtime with the active profile's model (or code.model) and
+calls ForgeQE's tools: browser runs, reading and running test cases, writing tests and running them, page memory, pushing
+a branch, and storing CI secrets. It reads the request and decides; there are no commands to pick a source.
+  forgeqe run "Search hotels in Mumbai on booking.com for next weekend"
+  forgeqe run "Run SHOP-12 and SHOP-14"            (Jira keys, Azure DevOps ids, Xray tests, files, or pasted cases)
+  forgeqe run "Add an Azure DevOps pipeline that runs test plan 12 every night"
+Pipelines: the agent writes or updates the workflow, validates it, pushes it to a new branch (never the default
+branch; git push itself is blocked), stores the keys it needs as secrets without seeing them, triggers it with gh or
+az, watches it, and fixes it until it passes. The pipeline itself calls forgeqe suite.
+It needs the agent runtime (downloaded automatically) and a live profile. Without them the request runs as one browser goal.
+Exit codes for run: 0 done, 1 failed, 2 stopped, 3 the agent needs more information.
+
+Tests (code: in forgeqe.yaml, or --repo): after a run passes, the agent gets the run's steps and page memory,
+studies the repo's existing tests, page objects and fixtures, and writes a test. ForgeQE runs that test itself;
+the test counts only when it passes, within --attempts (default 5) runs.
+
+Test case sources for forgeqe suite and cases (sources: in forgeqe.yaml): a file (.txt/.md split on --- lines,
+.csv, .yaml, .json, .feature), ado:123,456  ado:plan=12/suite=34  jira:SHOP-1  jira:jql=<query>  xray:SHOP-1
+xray:plan=SHOP-100  testrail:C12,C13  testrail:run=45  testrail:plan=7  zephyr:SHOP-T1  zephyr:cycle=SHOP-R5
+qtest:1234  qtest:cycle=88, or quoted text. Each case runs as one goal; its expected results are the checks, and
+the agent gives a verdict for every step. Results go back to Azure DevOps (test run or comment), Jira (comment),
+Xray (Test Execution), TestRail (run), Zephyr Scale (test cycle) or qTest (test run logs), with step results.
+With sources.bugs, each failed case files a bug in Jira or Azure DevOps, or comments on the open one.
+The report is report.html (step verdicts, timeline with screenshots, timings, environment) + junit.xml in
+out/suites/<time>/; every run folder also has its own report.html.
+
+Healing (forgeqe heal): ForgeQE runs the tests (the command given, code.test_command, or one the agent finds).
+For each failing test, Scribe re-runs its flow in the real browser: when the flow still works, the test is out
+of date and it updates the steps and locators from page memory; when the browser fails at the same step, it is an
+app bug and the test is left alone. ForgeQE re-runs every healed test and then the whole command; only those runs
+count. Quote the command, or put it after --:  forgeqe heal -- npx playwright test --project=chromium
+The report is heal.md in out/heal/<time>/, next to the browser runs.
+
+Monitoring (monitor: in forgeqe.yaml): each round runs the checks (any source forgeqe suite takes) replaying page
+memory, so a known flow costs one model call to confirm the outcome (or none with --replay trust). A check alerts
+after monitor.fail_after failing rounds, again every monitor.remind_every while it fails, and once when it recovers,
+through a Teams webhook and email (SMTP). --once runs one round for cron or a scheduled pipeline (keep
+out/monitor/state.json between runs so alerts fire on changes only). Rounds and their reports are in out/monitor/.
+
+Skills (skills: in forgeqe.yaml): folders with a SKILL.md (name, description, optional agents: [forgeqe, scribe,
+browser]) that teach the agents a repo's conventions, a framework or an app. ForgeQE ships some; yours go in
+.forgeqe/skills next to forgeqe.yaml (or the repo's) and ~/.forgeqe/skills, and a project skill replaces a built-in
+one with the same name. ForgeQE's agent and Scribe load the ones that fit the job; for browser runs the agent passes
+them, or the engine picks them from the goal. --skill NAME (repeatable) fixes the browser skills; --skill none uses none.
+
+Saved logins (logins: in forgeqe.yaml): the browser agent signs in with credentials from the environment (it only
+sees placeholders), fills authenticator codes from a TOTP secret, and keeps the session for the next run.
+Generated specs read the same variables. forgeqe login <name> saves a session you sign in to by hand (SSO).
+
+Shell (forgeqe start):
+${HELP.split("\n").map((l) => `  ${l}`).join("\n")}
+
+MCP servers for ForgeQE's agent come from forgeqe.yaml: Microsoft's Azure DevOps server (npx @azure-devops/mcp)
+for sources.azure_devops, mcp-atlassian (uvx) or Atlassian's hosted server for sources.jira and sources.confluence,
+and anything under mcp:.
+Org, project, site URL and token names come from the same settings; tokens stay in the environment. A system
+without a connected server (Xray has none) goes through ForgeQE's own API tools, including query_api.
+
+MCP (forgeqe mcp): ForgeQE's tools for Claude Code, Cursor, Codex or any MCP client, e.g.
+  {"mcpServers": {"forgeqe": {"command": "forgeqe", "args": ["mcp"]}}}
+
+OpenTUI needs Bun 1.3+ (Node 22 cannot load the native renderer).
+The first live run installs the engine into ~/.forgeqe (uv or Python 3.11+); forgeqe setup does it up front.
+Each run gets its own folder under .forgeqe/reports/<run-id>/ (report, steps, screenshots).
+`