@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/capabilities/registry.ts

@@ -0,0 +1,343 @@
+/**
+ * What ForgeQE can do: the one source its agent, the shell's /features, `forgeqe features`, and the Agent map in
+ * HOW_TO_USE.md are built from. Every tool belongs to exactly one capability, and every docs reference names a real
+ * heading; tests/capabilities.test.ts fails when either drifts, so a new tool cannot ship without saying what it is for.
+ */
+
+/** A system ForgeQE reads from or writes to, as configured in forgeqe.yaml (or signed in with /auth). */
+export type System = "azure_devops" | "jira" | "xray" | "testrail" | "zephyr" | "qtest" | "confluence"
+
+/**
+ * What a capability needs before it works. Each kind is checked against the loaded config and this machine by
+ * src/capabilities/status.ts; `optional` ones only widen what it does (a capability without them still works).
+ */
+export type Requirement =
+  /** A live llms.json profile for the browser agent (not none or the offline mock). */
+  | { kind: "live_model"; optional?: boolean }
+  /** ForgeQE's coding agent, Scribe: a live profile (or code.model) and the agent runtime. */
+  | { kind: "coding_agent"; optional?: boolean }
+  /** At least one of these systems is set up. */
+  | { kind: "system"; anyOf: System[]; optional?: boolean; why?: string }
+  /** sources.bugs in forgeqe.yaml. */
+  | { kind: "bugs"; optional?: boolean }
+  /** monitor.alerts (Teams or email) in forgeqe.yaml. */
+  | { kind: "monitor_alerts"; optional?: boolean }
+  /** domain: (industry and regulations) in forgeqe.yaml. */
+  | { kind: "domain"; optional?: boolean }
+  /** notify.channels (Teams or email) in forgeqe.yaml. */
+  | { kind: "notify_channels"; optional?: boolean }
+  /** A command-line tool on PATH. */
+  | { kind: "command"; command: "gh" | "az" | "git" | "npx"; optional?: boolean; why?: string }
+  /** Something only the request can supply (a repository, a pull request); stated, never checked. */
+  | { kind: "input"; what: string }
+  /** Alternatives: met when any one of them is (GitHub through gh, or Azure DevOps). */
+  | { kind: "either"; of: Requirement[]; optional?: boolean }
+
+/** A heading in README.md or HOW_TO_USE.md, by its exact text (### headings without their parent). */
+export type DocRef = { doc: "README.md" | "HOW_TO_USE.md"; heading: string }
+
+export type Area = "Browser" | "Test cases" | "Automated tests" | "Pull requests" | "API" | "Quality" | "Release" | "Operations" | "Systems" | "Setup"
+
+export type Capability = {
+  /** Stable id the agent asks for details by. */
+  id: string
+  area: Area
+  title: string
+  /** What it does, for a user who has never seen ForgeQE: one or two sentences. */
+  summary: string
+  /** The tools that carry it out (forgeqe_ prefix left off). */
+  tools: string[]
+  /** How a user might ask for it, in their words. */
+  examples: string[]
+  requires: Requirement[]
+  /** What it does not do, so the agent never promises it. */
+  limits?: string[]
+  docs: DocRef[]
+}
+
+export const CAPABILITIES: Capability[] = [
+  {
+    id: "browser-goals",
+    area: "Browser",
+    title: "Run any goal in a real browser",
+    summary:
+      "Carries out a plain-language goal in Chrome one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper.",
+    tools: ["browser_run", "run_details", "page_memory"],
+    examples: ["Go to booking.com and search hotels in Mumbai for next weekend", "What does ForgeQE know about the checkout page?"],
+    requires: [{ kind: "live_model" }],
+    limits: ["Web applications in Chrome or Chromium only: not native mobile or desktop applications."],
+    docs: [
+      { doc: "HOW_TO_USE.md", heading: "4. Without the shell" },
+      { doc: "HOW_TO_USE.md", heading: "5. Page memory" },
+    ],
+  },
+  {
+    id: "logins",
+    area: "Browser",
+    title: "Saved logins for the application under test",
+    summary: "Signs the browser agent in with saved credentials (including TOTP) and reuses the session; a user can also sign in by hand once in a browser.",
+    tools: ["logins"],
+    examples: ["Sign in to the admin site and keep the session", "Forget the saved session for shop.example.com"],
+    requires: [],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Signing in" }],
+  },
+  {
+    id: "run-test-cases",
+    area: "Test cases",
+    title: "Run manual test cases in browsers",
+    summary:
+      "Reads test cases from Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, qTest, a file, or pasted text, runs each in a real browser with a verdict per step, writes report.html and junit.xml, posts results back, and files or updates bugs for failures.",
+    tools: ["find_test_cases", "run_test_cases"],
+    examples: ["Run SHOP-12 and SHOP-14 from Jira, two browsers at once", "Run test plan 12 suite 34 from Azure DevOps and don't post results"],
+    requires: [
+      { kind: "live_model" },
+      { kind: "system", anyOf: ["azure_devops", "jira", "xray", "testrail", "zephyr", "qtest"], optional: true, why: "to read cases from a test management system and post results back (files and pasted text work without one)" },
+      { kind: "bugs", optional: true },
+    ],
+    docs: [
+      { doc: "HOW_TO_USE.md", heading: "7. Test cases and suites" },
+      { doc: "HOW_TO_USE.md", heading: "Where cases come from" },
+      { doc: "HOW_TO_USE.md", heading: "Running" },
+      { doc: "HOW_TO_USE.md", heading: "Results back in the source" },
+      { doc: "HOW_TO_USE.md", heading: "Bugs for failures" },
+    ],
+  },
+  {
+    id: "test-case-quality",
+    area: "Test cases",
+    title: "Check and improve test cases",
+    summary:
+      "Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps cases once the user agrees.",
+    tools: ["check_test_cases", "update_test_case"],
+    examples: ["Are the cases in test plan 12 good enough to run?", "Fix the expected results of case 4512"],
+    requires: [{ kind: "system", anyOf: ["azure_devops"], optional: true, why: "to rewrite cases in place" }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Checking test cases before they run" }],
+  },
+  {
+    id: "write-test-cases",
+    area: "Test cases",
+    title: "Write test cases from a story",
+    summary: "Writes test cases from a story's acceptance criteria and saves them in Azure DevOps or Jira, linked to the story.",
+    tools: ["save_test_cases"],
+    examples: ["Write test cases for story 1234 and save them"],
+    requires: [{ kind: "system", anyOf: ["azure_devops", "jira"] }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Where cases come from" }],
+  },
+  {
+    id: "domain-compliance",
+    area: "Test cases",
+    title: "Domain and regulatory test design",
+    summary:
+      "Every agent works as an expert in the product's industry would, automatically: the risks the industry is known for and the obligations of its regulations and standards (for example DORA, PSD2, GDPR, ISO 27001), declared in forgeqe.yaml or worked out from the story and the application. It applies to analysing requirements, writing and checking test cases, exploration, writing, reviewing, and healing test code, API tests, finding tests, and pull request reviews, labelled so coverage can be traced and citing only the control ids in the team's compliance file. forgeqe eval domain measures how well the agent does it.",
+    tools: [],
+    examples: ["Write test cases for story 1234, covering our DORA and PSD2 obligations", "Which GDPR obligations do these cases miss?"],
+    requires: [{ kind: "domain", optional: true }],
+    limits: ["Designs and checks tests for regulatory obligations; it does not certify compliance or replace an audit.", "Cites control or article ids only from the team's compliance file, never from memory."],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "16. Domain and regulations" }],
+  },
+  {
+    id: "exploratory-testing",
+    area: "Test cases",
+    title: "Exploratory testing of a story",
+    summary:
+      "Explores a story in real browsers beyond its scripted cases (edge cases, invalid input, boundaries, roles, state), confirms each defect by reproducing it, proposes test cases, and files bugs once the user agrees.",
+    tools: ["explore_story"],
+    examples: ["Explore story 1234 and find bugs", "Test this feature beyond the test cases"],
+    requires: [{ kind: "live_model" }, { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to read the story and file bugs" }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Exploratory testing from a story" }],
+  },
+  {
+    id: "write-tests",
+    area: "Automated tests",
+    title: "Turn a passed run into an automated test",
+    summary:
+      "Scribe, the coding agent, writes a test for a passed browser run in the repository's own framework, page objects, and helpers; ForgeQE runs it until it passes and a reviewer approves it.",
+    tools: ["write_test", "run_test"],
+    examples: ["Write a Playwright test for that run in ../app"],
+    requires: [{ kind: "coding_agent" }, { kind: "input", what: "a repository to write the test in (default: the working directory)" }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "6. Tests" }],
+  },
+  {
+    id: "heal-tests",
+    area: "Automated tests",
+    title: "Heal failing tests",
+    summary: "Runs a repository's tests and updates the ones the application has outgrown against the live app, or reports a real application bug instead.",
+    tools: ["heal_tests"],
+    examples: ["Heal the failing tests in ../app"],
+    requires: [{ kind: "coding_agent" }, { kind: "input", what: "a repository with tests" }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Fixing broken tests" }],
+  },
+  {
+    id: "find-run-tests",
+    area: "Automated tests",
+    title: "Find and run existing tests",
+    summary: "Finds the automated tests that match a feature, tags, ids, a folder, or a sprint, confirms the selection, and runs it once the user agrees, with a verdict per test.",
+    tools: ["find_tests", "run_tests", "list_sprints"],
+    examples: ["Run the checkout tests", "Run the tests added in sprint 12"],
+    requires: [
+      { kind: "coding_agent" },
+      { kind: "input", what: "a repository with tests" },
+      { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to pick tests by sprint" },
+    ],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Finding and running existing tests" }],
+  },
+  {
+    id: "flaky-tests",
+    area: "Automated tests",
+    title: "Flaky test detection and quarantine",
+    summary: "Finds tests that flip between passing and failing in the repository's run history, with their likely cause, and quarantines them once the user agrees.",
+    tools: ["flaky_tests", "quarantine_tests"],
+    examples: ["Which tests are flaky?", "Quarantine the flaky login test"],
+    requires: [{ kind: "input", what: "a repository whose tests ForgeQE has run" }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Flaky tests" }],
+  },
+  {
+    id: "pr-review",
+    area: "Pull requests",
+    title: "Review pull requests",
+    summary: "Reviews an Azure DevOps or GitHub pull request from the local clone for bugs, security, requirements, and tests, and posts the review once the user agrees.",
+    tools: ["review_pull_request", "post_pr_review"],
+    examples: ["Review PR 42 and focus on error handling"],
+    requires: [
+      { kind: "coding_agent" },
+      { kind: "input", what: "a local clone of the repository" },
+      { kind: "either", of: [{ kind: "system", anyOf: ["azure_devops"], why: "for Azure DevOps pull requests" }, { kind: "command", command: "gh", why: "for GitHub pull requests" }] },
+    ],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Reviewing pull requests" }],
+  },
+  {
+    id: "pr-impact",
+    area: "Pull requests",
+    title: "Pull request impact and test selection",
+    summary:
+      "Works out which product areas, pages, requirements, and tests a pull request touches, picks the tests it can break, runs them, and posts the impact or results on the pull request once the user agrees.",
+    tools: ["analyze_pr_impact", "select_pr_tests", "post_pr_test_results", "comment_on_pr"],
+    examples: ["What does PR 42 impact?", "Run the tests PR 42 can break"],
+    requires: [
+      { kind: "input", what: "a local clone of the repository" },
+      { kind: "either", of: [{ kind: "system", anyOf: ["azure_devops"], why: "for Azure DevOps pull requests and their linked work items" }, { kind: "command", command: "gh", why: "for GitHub pull requests" }] },
+    ],
+    docs: [
+      { doc: "HOW_TO_USE.md", heading: "What a pull request impacts in the product" },
+      { doc: "HOW_TO_USE.md", heading: "Tests for a pull request" },
+    ],
+  },
+  {
+    id: "api-testing",
+    area: "API",
+    title: "API and contract testing",
+    summary:
+      "Builds API contracts (status, schema, key fields) from the calls a browser run saw or from an API description (OpenAPI, Swagger, WSDL, GraphQL, .proto, gRPC reflection), and end-to-end API scenarios from runs, descriptions, test cases, or plain English. Runs them straight against the API without a browser, or writes them as tests in the repository. REST, GraphQL, SOAP, and gRPC.",
+    tools: ["api_contracts", "run_api_contracts", "api_scenarios", "run_api_scenarios", "write_api_tests"],
+    examples: ["Turn the last run's API calls into tests", "Test the API in openapi.yaml", "Write API scenario tests for the order lifecycle"],
+    requires: [{ kind: "coding_agent", optional: true }],
+    limits: ["Functional API testing, not load or stress testing."],
+    docs: [
+      { doc: "HOW_TO_USE.md", heading: "API and contract tests" },
+      { doc: "HOW_TO_USE.md", heading: "End-to-end API scenarios" },
+    ],
+  },
+  {
+    id: "accessibility-performance",
+    area: "Quality",
+    title: "Accessibility and page performance",
+    summary: "Checks every page a run visits against WCAG rules (axe-core) and measures its Core Web Vitals, against budgets, with trends over time per page.",
+    tools: ["quality_report", "quality_trends"],
+    examples: ["Is the checkout page accessible?", "Did page performance get worse this week?"],
+    requires: [{ kind: "input", what: "a browser run (from browser_run or run_test_cases); new runs need a live model" }],
+    limits: ["Per-page Core Web Vitals, not load testing under many users."],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Accessibility and performance budgets" }],
+  },
+  {
+    id: "visual-comparison",
+    area: "Quality",
+    title: "Visual comparison with baselines",
+    summary: "Compares each page a run captures with its approved baseline and shows what changed; intended changes become the new baseline once the user agrees.",
+    tools: ["visual_compare", "visual_approve"],
+    examples: ["What changed visually since the last run?", "Approve the new header"],
+    requires: [{ kind: "input", what: "a browser run (from browser_run or run_test_cases); new runs need a live model" }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Visual comparison" }],
+  },
+  {
+    id: "release-readiness",
+    area: "Release",
+    title: "Requirement coverage and release readiness",
+    summary: "Gives requirement coverage and a GO / GO WITH RISKS / NO-GO verdict for a sprint, area, epic, or stories, from test cases, results, bugs, and flaky tests; can publish it to the wiki.",
+    tools: ["release_readiness"],
+    examples: ["Are we ready to release?", "Coverage of sprint 12"],
+    requires: [{ kind: "system", anyOf: ["azure_devops", "jira"] }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Requirement coverage and release readiness" }],
+  },
+  {
+    id: "monitoring",
+    area: "Operations",
+    title: "Scheduled monitoring with alerts",
+    summary: "Runs checks on a schedule and alerts Teams or email when one keeps failing, and again when it recovers.",
+    tools: ["monitor"],
+    examples: ["Check the login flow every 15 minutes and alert Teams"],
+    requires: [{ kind: "live_model" }, { kind: "monitor_alerts", optional: true }],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "9. Monitoring" }],
+  },
+  {
+    id: "notifications",
+    area: "Operations",
+    title: "Teams and email notifications",
+    summary:
+      "Tells the team in Microsoft Teams channels or by email when a suite fails or passes, when a release readiness verdict is in, and when the domain evaluation falls below its gate, with the failing cases, their bugs, and links to the report and the CI build. Each channel picks its events; the agent also posts a summary to a channel when asked.",
+    tools: ["notify"],
+    examples: ["Post the results to the QA channel", "Tell the release channel the verdict is NO-GO"],
+    requires: [{ kind: "notify_channels" }],
+    limits: ["Automatic notifications come from runs nobody is watching (forgeqe suite, forgeqe run, pipelines, the MCP server), not from the interactive shell, where the agent posts only when asked."],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "17. Notifications" }],
+  },
+  {
+    id: "pipelines",
+    area: "Operations",
+    title: "CI pipelines",
+    summary: "Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green.",
+    tools: ["push_branch", "set_ci_secret"],
+    examples: ["Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green"],
+    requires: [
+      { kind: "command", command: "git" },
+      { kind: "either", of: [{ kind: "command", command: "gh", why: "for GitHub Actions" }, { kind: "command", command: "az", why: "for Azure Pipelines" }] },
+    ],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "8. Pipelines" }],
+  },
+  {
+    id: "systems",
+    area: "Systems",
+    title: "Work with Azure DevOps, Jira, and Confluence",
+    summary: "Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, and builds Azure DevOps dashboards and wiki pages.",
+    tools: ["query_api", "read_confluence", "create_ado_dashboard", "write_ado_wiki_page"],
+    examples: ["Show the open bugs in this sprint", "Read the checkout requirements from Confluence", "Make a dashboard of this sprint's test results"],
+    requires: [{ kind: "system", anyOf: ["azure_devops", "jira", "xray", "confluence"] }],
+    docs: [{ doc: "README.md", heading: "Azure DevOps, Jira, and other systems" }],
+  },
+  {
+    id: "setup-help",
+    area: "Setup",
+    title: "Setup, skills, and documentation",
+    summary: "Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list.",
+    tools: ["forgeqe_setup", "capabilities"],
+    examples: ["What can you do?", "Which model am I using?", "How do I set up email alerts?"],
+    requires: [],
+    docs: [
+      { doc: "HOW_TO_USE.md", heading: "2. Scaffold config" },
+      { doc: "HOW_TO_USE.md", heading: "11. Skills" },
+    ],
+  },
+]
+
+/**
+ * What ForgeQE does not do, so a "can you…?" gets a plain no with the nearest thing it does, instead of a guess.
+ * Only add what is certain.
+ */
+export const OUT_OF_SCOPE: { what: string; instead?: string }[] = [
+  { what: "Native mobile apps (iOS, Android) and desktop applications", instead: "web applications in Chrome or Chromium" },
+  { what: "Load, stress, or soak testing with many simultaneous users", instead: "per-page Core Web Vitals with budgets" },
+  { what: "Penetration testing or dynamic security scanning", instead: "security findings in pull request reviews" },
+]
+
+export function capability(id: string): Capability | undefined {
+  return CAPABILITIES.find((c) => c.id === id)
+}

package/src/capabilities/render.ts

@@ -0,0 +1,106 @@
+import type { AppConfig } from "../config.ts"
+import { anchor, resolveDoc } from "./docs.ts"
+import { CAPABILITIES, OUT_OF_SCOPE, type Area, type Capability } from "./registry.ts"
+import { allStatuses, capabilityStatus, MACHINE, type CapabilityStatus, type Probes } from "./status.ts"
+
+const STATE: Record<CapabilityStatus["state"], string> = { ready: "ready", partial: "ready, some parts need setup", needs_setup: "needs setup" }
+
+function byArea(): [Area, Capability[]][] {
+  const areas = new Map<Area, Capability[]>()
+  for (const c of CAPABILITIES) areas.set(c.area, [...(areas.get(c.area) || []), c])
+  return [...areas]
+}
+
+/** For the agent's session notes: every capability on one line, with its state in this setup. */
+export function capabilityIndex(cfg: AppConfig, probes: Probes = MACHINE): string {
+  const status = allStatuses(cfg, probes)
+  return [
+    "What ForgeQE can do (the capabilities tool has each one's details, setup, and docs; anything not listed here or under its out-of-scope list, ForgeQE does not do):",
+    ...CAPABILITIES.map((c) => {
+      const s = status.get(c.id)!
+      const missing = s.gaps.filter((g) => !g.optional).map((g) => g.missing)
+      return `- ${c.id}: ${c.title} [${STATE[s.state]}${missing.length ? `: needs ${missing.join("; ")}` : ""}]`
+    }),
+    `Out of scope: ${OUT_OF_SCOPE.map((o) => o.what).join("; ")}.`,
+  ].join("\n")
+}
+
+/** The capabilities tool's list: areas with each capability's summary and state. */
+export function capabilityList(cfg: AppConfig, probes: Probes = MACHINE) {
+  const status = allStatuses(cfg, probes)
+  return {
+    areas: byArea().map(([area, caps]) => ({
+      area,
+      capabilities: caps.map((c) => ({ id: c.id, title: c.title, summary: c.summary, state: status.get(c.id)!.state })),
+    })),
+    out_of_scope: OUT_OF_SCOPE,
+  }
+}
+
+/** The capabilities tool's details for one capability: what it does, how to ask, what it needs here, and its docs. */
+export function capabilityDetail(c: Capability, cfg: AppConfig, probes: Probes = MACHINE) {
+  const s = capabilityStatus(c, cfg, probes)
+  return {
+    id: c.id,
+    title: c.title,
+    summary: c.summary,
+    state: s.state,
+    tools: c.tools,
+    examples: c.examples,
+    ...(s.gaps.length ? { setup_needed: s.gaps.map((g) => ({ missing: g.missing, optional: g.optional, fix: g.fix })) } : {}),
+    ...(s.inputs.length ? { needs_from_request: s.inputs } : {}),
+    ...(c.limits?.length ? { limits: c.limits } : {}),
+    docs: c.docs.map((d) => {
+      const section = resolveDoc(d)
+      return { id: section?.id || `${d.doc}#${anchor(d.heading)}`, heading: d.heading, text: section?.text || "" }
+    }),
+  }
+}
+
+/** /features and `forgeqe features`: what ForgeQE can do here, by area. */
+export function featuresText(cfg: AppConfig, probes: Probes = MACHINE): string {
+  const status = allStatuses(cfg, probes)
+  const mark = { ready: "✓", partial: "◐", needs_setup: "○" } as const
+  const lines: string[] = ["What ForgeQE can do  (✓ ready  ◐ works, some parts need setup  ○ needs setup)", ""]
+  for (const [area, caps] of byArea()) {
+    lines.push(area)
+    for (const c of caps) {
+      const s = status.get(c.id)!
+      lines.push(`  ${mark[s.state]} ${c.title}`)
+      lines.push(`      e.g. ${c.examples[0]}`)
+      for (const g of s.gaps.filter((g) => !g.optional)) lines.push(`      needs ${g.missing}: ${g.fix}`)
+    }
+    lines.push("")
+  }
+  lines.push(`Not supported: ${OUT_OF_SCOPE.map((o) => o.what).join("; ")}.`)
+  lines.push("Ask in the shell for details about any of these, e.g. \"how do I set up API testing?\"")
+  return lines.join("\n")
+}
+
+export const AGENT_MAP_START = "<!-- capabilities:start (generated from src/capabilities/registry.ts by bun scripts/gen-capabilities.ts; do not edit) -->"
+export const AGENT_MAP_END = "<!-- capabilities:end -->"
+
+/** The Capabilities part of HOW_TO_USE.md's Agent map: every capability with its tools and a link to its docs. */
+export function agentMapMarkdown(): string {
+  const link = (c: Capability) => {
+    const d = c.docs[0]!
+    return d.doc === "HOW_TO_USE.md" ? `[docs](#${anchor(d.heading)})` : `[docs](${d.doc}#${anchor(d.heading)})`
+  }
+  return [
+    AGENT_MAP_START,
+    "| Area | Capability | Tools | |",
+    "|------|------------|-------|-|",
+    ...CAPABILITIES.map((c) => `| ${c.area} | **${c.title}**: ${c.summary} | ${c.tools.map((t) => `\`${t}\``).join(", ")} | ${link(c)} |`),
+    "",
+    `Not supported: ${OUT_OF_SCOPE.map((o) => `${o.what}${o.instead ? ` (instead: ${o.instead})` : ""}`).join("; ")}.`,
+    AGENT_MAP_END,
+  ].join("\n")
+}
+
+/** HOW_TO_USE.md with its generated block (from its start marker, whatever follows the marker's name, to its end marker) replaced by the current one. */
+export function withAgentMap(markdown: string): string {
+  const start = markdown.indexOf("<!-- capabilities:start")
+  const end = markdown.indexOf(AGENT_MAP_END)
+  if (start === -1 || end < start) throw new Error("HOW_TO_USE.md has no capabilities block (its start and end markers).")
+  return markdown.slice(0, start) + agentMapMarkdown() + markdown.slice(end + AGENT_MAP_END.length)
+}

package/src/capabilities/status.ts

@@ -0,0 +1,137 @@
+import type { AppConfig } from "../config.ts"
+import { findOpencode } from "../code/runtime.ts"
+import { noAgentModel } from "../llm.ts"
+import { CAPABILITIES, type Capability, type Requirement, type System } from "./registry.ts"
+
+/**
+ * Whether each capability works in this setup, and what is missing when it does not: every requirement kind is
+ * checked against the loaded config and this machine, never guessed from text.
+ */
+
+export type Probes = {
+  /** A command on PATH. */
+  which(command: string): boolean
+  /** The agent runtime Scribe runs on is installed. */
+  runtime(cfg: AppConfig): boolean
+}
+
+export const MACHINE: Probes = {
+  which: (command) => Boolean(Bun.which(command)),
+  runtime: (cfg) => Boolean(findOpencode(cfg.code.opencode)),
+}
+
+export const SYSTEM_LABEL: Record<System, string> = {
+  azure_devops: "Azure DevOps",
+  jira: "Jira",
+  xray: "Xray",
+  testrail: "TestRail",
+  zephyr: "Zephyr Scale",
+  qtest: "qTest",
+  confluence: "Confluence",
+}
+
+/** The systems forgeqe.yaml (or a sign-in) sets up. */
+export function configuredSystems(cfg: AppConfig): Set<System> {
+  const s = cfg.sources
+  const on: [System, unknown][] = [
+    ["azure_devops", s.ado],
+    ["jira", s.jira],
+    ["xray", (s.xray.url && process.env[s.xray.clientIdEnv]) || (s.jira && !s.jira.cloud)],
+    ["testrail", s.testrail],
+    ["zephyr", s.zephyr],
+    ["qtest", s.qtest],
+    ["confluence", s.confluence],
+  ]
+  return new Set(on.filter(([, v]) => Boolean(v)).map(([k]) => k))
+}
+
+export type Gap = { requirement: Requirement; optional: boolean; missing: string; fix: string }
+
+export type CapabilityStatus = {
+  id: string
+  /** ready: everything is set up. partial: it works, but something optional is missing. needs_setup: it does not work yet. */
+  state: "ready" | "partial" | "needs_setup"
+  gaps: Gap[]
+  /** What only the request can supply (a repository, a pull request). */
+  inputs: string[]
+}
+
+function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "requirement" | "optional"> | null {
+  switch (r.kind) {
+    case "live_model":
+      return cfg.llm.provider === "none" || cfg.llm.provider === "mock"
+        ? { missing: "a live model profile", fix: "add a profile with your provider to llms.json (forgeqe init writes one), then pick it with llm.active or Tab" }
+        : null
+    case "coding_agent": {
+      const why = noAgentModel(cfg.llm, cfg.code.model, "Scribe")
+      if (why) return { missing: "a live model for the coding agent", fix: "pick a live llms.json profile, or set code.model" }
+      return probes.runtime(cfg) ? null : { missing: "the agent runtime the coding agent runs on", fix: "run forgeqe setup, or set code.runtime to its binary" }
+    }
+    case "system": {
+      const have = configuredSystems(cfg)
+      if (r.anyOf.some((s) => have.has(s))) return null
+      const names = r.anyOf.map((s) => SYSTEM_LABEL[s])
+      return {
+        missing: `${names.length > 1 ? `one of ${names.join(", ")}` : names[0]}${r.why ? ` (${r.why})` : ""}`,
+        fix: `set it up under sources: in forgeqe.yaml, or sign in with /auth ${r.anyOf[0]}`,
+      }
+    }
+    case "bugs":
+      return cfg.sources.bugs ? null : { missing: "bug filing for failures", fix: "set sources.bugs in forgeqe.yaml (Jira or Azure DevOps)" }
+    case "monitor_alerts":
+      return cfg.monitor.alerts.teams || cfg.monitor.alerts.email ? null : { missing: "alert channels", fix: "set monitor.alerts.teams or monitor.alerts.email in forgeqe.yaml" }
+    case "notify_channels":
+      return cfg.notify?.channels.length ? null : { missing: "a notification channel", fix: "add notify.channels to forgeqe.yaml: a Teams Workflows webhook (webhook_env) or email for each" }
+    case "domain":
+      return cfg.domain ? null : { missing: "the product's industry and regulations", fix: "set domain: in forgeqe.yaml, and list your applicable controls in .forgeqe/knowledge/compliance.md" }
+    case "command":
+      return probes.which(r.command) ? null : { missing: `${r.command} on PATH${r.why ? ` (${r.why})` : ""}`, fix: `install ${r.command}` }
+    case "input":
+      return null
+    case "either": {
+      const gaps = r.of.map((alt) => gap(alt, cfg, probes))
+      if (gaps.some((g) => !g)) return null
+      return { missing: gaps.map((g) => g!.missing).join(", or "), fix: gaps.map((g) => g!.fix).join("; or ") }
+    }
+  }
+}
+
+export function capabilityStatus(c: Capability, cfg: AppConfig, probes: Probes = MACHINE): CapabilityStatus {
+  const gaps: Gap[] = []
+  for (const r of c.requires) {
+    const g = gap(r, cfg, probes)
+    if (g) gaps.push({ requirement: r, optional: Boolean("optional" in r && r.optional), ...g })
+  }
+  const state = gaps.some((g) => !g.optional) ? "needs_setup" : gaps.length ? "partial" : "ready"
+  return { id: c.id, state, gaps, inputs: c.requires.flatMap((r) => (r.kind === "input" ? [r.what] : [])) }
+}
+
+export function allStatuses(cfg: AppConfig, probes: Probes = MACHINE): Map<string, CapabilityStatus> {
+  return new Map(CAPABILITIES.map((c) => [c.id, capabilityStatus(c, cfg, probes)]))
+}
+
+/** A requirement in words, for documentation: what it is and where it is set up (not whether this machine has it). */
+export function describeRequirement(r: Requirement): string {
+  switch (r.kind) {
+    case "live_model":
+      return "A live model profile in llms.json (an API key or Microsoft Entra ID sign-in)"
+    case "coding_agent":
+      return "The coding agent, Scribe: a live model profile (or code.model) and the agent runtime, which forgeqe setup installs"
+    case "system":
+      return `${r.anyOf.map((s) => SYSTEM_LABEL[s]).join(" or ")}${r.why ? `, ${r.why}` : ""}: set up under sources: in forgeqe.yaml, or sign in with /auth`
+    case "bugs":
+      return "Bug filing: sources.bugs in forgeqe.yaml (Jira or Azure DevOps)"
+    case "monitor_alerts":
+      return "Alert channels: monitor.alerts.teams or monitor.alerts.email in forgeqe.yaml"
+    case "notify_channels":
+      return "A notification channel: notify.channels in forgeqe.yaml, each a Teams Workflows webhook (in an environment variable) or email"
+    case "domain":
+      return "The product's industry and regulations: domain: in forgeqe.yaml, with your applicable controls in .forgeqe/knowledge/compliance.md"
+    case "command":
+      return `${r.command} on PATH${r.why ? `, ${r.why}` : ""}`
+    case "input":
+      return `From your request: ${r.what}`
+    case "either":
+      return r.of.map(describeRequirement).join("; or ")
+  }
+}

package/src/card.ts

@@ -0,0 +1,11 @@
+/** A tool's result as a card: the shell renders it as a panel, plain output prints it as text. */
+export type CardStatus = "ok" | "fail" | "stopped" | "info"
+
+export type Card = { status: CardStatus; title: string; stats?: string; body: string[] }
+
+export const CARD_MARK: Record<CardStatus, string> = { ok: "✓", fail: "✗", stopped: "■", info: "▸" }
+
+export function cardText(c: Card): string {
+  const head = `${CARD_MARK[c.status]} ${c.title}${c.stats ? ` · ${c.stats}` : ""}`
+  return c.body.length ? [head, "", ...c.body].join("\n") : head
+}