flakiness 0.218.0 → 0.219.0

package/lib/cli/cli.js

@@ -1028,7 +1028,7 @@ import path7 from "path";
 // ../package.json
 var package_default = {
   name: "@flakiness/monorepo",
-  version: "0.218.0",
+  version: "0.219.0",
   type: "module",
   private: true,
   scripts: {
@@ -1964,6 +1964,41 @@ function durationTrendScale(currentMs, baseMs) {
 }
 
 // src/cli/cmd-list-tests.ts
+function buildTimelineSplit(filters) {
+  const systemFilters = [];
+  if (filters.envName?.length)
+    systemFilters.push({ name: "name", values: filters.envName });
+  if (filters.envPath?.length)
+    systemFilters.push({ name: "path", values: filters.envPath });
+  if (filters.envCategory?.length)
+    systemFilters.push({ name: "category", values: filters.envCategory });
+  if (filters.envOs?.length)
+    systemFilters.push({ name: "osname", values: filters.envOs });
+  if (filters.envArch?.length)
+    systemFilters.push({ name: "osarch", values: filters.envArch });
+  const userFilters = /* @__PURE__ */ new Map();
+  for (const entry of filters.envMetadata ?? []) {
+    const eqIndex = entry.indexOf("=");
+    const key = entry.slice(0, eqIndex);
+    const value = entry.slice(eqIndex + 1);
+    let values = userFilters.get(key);
+    if (!values) {
+      values = [];
+      userFilters.set(key, values);
+    }
+    values.push(value);
+  }
+  if (!systemFilters.length && !userFilters.size)
+    return void 0;
+  return {
+    splitByDefault: true,
+    filters: {
+      system: systemFilters.length ? systemFilters : void 0,
+      user: userFilters.size ? Array.from(userFilters, ([name, values]) => ({ name, values })) : void 0
+    },
+    inverse: {}
+  };
+}
 async function cmdListTests(options) {
   const [orgSlug, projectSlug] = options.flakinessProject.split("/");
   if (!orgSlug || !projectSlug)
@@ -1992,7 +2027,8 @@ async function cmdListTests(options) {
       direction: options.sortDir
     },
     historyBuckets: 10,
-    fql: options.fql
+    fql: options.fql,
+    timelineSplit: buildTimelineSplit(options)
   });
   let scope = "default branch";
   if (options.pr !== void 0)
@@ -2020,9 +2056,12 @@ async function cmdListTests(options) {
     const trend = formatDurationTrend(testStats.durationChangeMs, testStats.durationMs);
     const flipRate = formatFlipRate(testStats.flipRate);
     const env = formatEnv(testStats.env);
+    const metadata = formatEnvMetadata(testStats.env);
     lines.push(`### ${index + 1}. ${fullName}`);
     lines.push(`- Location: ${asInlineCode(location)}`);
     lines.push(`- Env: ${asInlineCode(env)}`);
+    if (metadata)
+      lines.push(`- Env Metadata: ${asInlineCode(metadata)}`);
     lines.push(`- Status: ${asInlineCode(status)}`);
     lines.push(`- Duration: ${asInlineCode(duration)} (${asInlineCode(trend)})`);
     lines.push(`- Flip Rate: ${asInlineCode(flipRate)}`);
@@ -2053,18 +2092,25 @@ function outcomeToStatus(outcome) {
 }
 function formatEnv(env) {
   const parts = [];
-  const { systemData } = env;
-  if (systemData.osName)
-    parts.push(`os=${systemData.osName}`);
-  if (systemData.osVersion)
-    parts.push(`osVersion=${systemData.osVersion}`);
-  if (systemData.osArch)
-    parts.push(`arch=${systemData.osArch}`);
-  if (env.userSuppliedData) {
-    for (const [key, value] of Object.entries(env.userSuppliedData))
-      parts.push(`${key}=${value}`);
-  }
-  return parts.join(", ") || env.name || "unknown";
+  if (env.category)
+    parts.push(`category=${env.category}`);
+  if (env.name)
+    parts.push(`name=${env.name}`);
+  if (env.configPath)
+    parts.push(`path=${env.configPath}`);
+  if (env.systemData.osName) {
+    const os4 = [env.systemData.osName, env.systemData.osVersion].filter(Boolean).join(" ");
+    parts.push(`os=${os4}`);
+  }
+  if (env.systemData.osArch)
+    parts.push(`arch=${env.systemData.osArch}`);
+  return parts.join(", ") || "unknown";
+}
+function formatEnvMetadata(env) {
+  if (!env.userSuppliedData)
+    return void 0;
+  const parts = Object.entries(env.userSuppliedData).map(([key, value]) => `${key}=${value}`);
+  return parts.length ? parts.join(", ") : void 0;
 }
 function formatDurationTrend(changeMs, currentMs) {
   const baseMs = currentMs - changeMs;
@@ -2087,17 +2133,18 @@ function asInlineCode(text) {
 import { execSync } from "child_process";
 import chalk3 from "chalk";
 import fs5 from "fs";
+import os3 from "os";
 import path5 from "path";
 
 // src/generated/bundledSkillsData.ts
 var BUNDLED_SKILLS = [
   {
     "name": "flakiness-investigation",
-    "description": "Use when querying Flakiness.io test data, writing FQL filters, finding flaky or failed tests, investigating regressions, analyzing test health, or fixing PR test failures with the flakiness CLI.",
+    "description": "TRIGGER when: CI fails, tests fail, PR checks fail, user asks about test results, regressions, flakiness, or test health. Always use this INSTEAD OF `gh` CLI for investigating test failures \u2014 it distinguishes regressions (caused by the PR) from pre-existing failures and flakes. DO NOT TRIGGER when: the user is asking about non-test CI issues (e.g. build failures, deployment problems).",
     "files": [
       {
         "path": "SKILL.md",
-        "content": "---\nname: flakiness-investigation\ndescription: Use when querying Flakiness.io test data, writing FQL filters, finding flaky or failed tests, investigating regressions, analyzing test health, or fixing PR test failures with the flakiness CLI.\n---\n\n# Flakiness Investigation\n\nUse the `flakiness` CLI to query and analyze test data from Flakiness.io.\n\n## Prerequisites\n\n- The `flakiness` CLI must be available in PATH (installed via `npm install -g flakiness` or `npx flakiness`).\n- A project must be specified: `--project <org/project>` or set `FLAKINESS_PROJECT` env var.\n- Authentication: run `flakiness auth login` first, or set `FLAKINESS_ACCESS_TOKEN`.\n\n## Core command\n\n```bash\nflakiness list tests --project <org/project> [--pr <number>] [--branch <name>] [--fql <query>] [--sort <axis>] [--sort-dir asc|desc] [--page <n>] [--page-size <n>]\n```\n\n### Scope options\n\n| Flag | Effect |\n|------|--------|\n| *(none)* | Default branch \u2014 tests from the day of its head commit (in the project's timezone) |\n| `--pr <number>` | Pull request \u2014 tests from the merge-commit of the PR branch into the target branch |\n| `--branch <name>` | Named branch \u2014 tests from the day of its head commit (in the project's timezone) |\n\n`--pr` and `--branch` are mutually exclusive.\n\n### Status semantics with `--pr`\n\nWhen querying a PR, the status values have specific meaning:\n\n| Status | Meaning |\n|--------|---------|\n| `regressed` | Test was passing on the target branch but fails in this PR \u2014 **caused by the PR** |\n| `failed` | Test also fails on the target branch \u2014 **pre-existing failure, not caused by the PR** |\n| `flaked` | Test failed but passed on retry \u2014 flaky, not a real failure |\n| `passed` | Test passes |\n| `skipped` | Test was skipped |\n\n### Sort axes\n\n- `outcome` \u2014 sort by test outcome severity (default)\n- `flip_rate` \u2014 sort by flip rate (how often a test flips between pass/fail)\n- `duration` \u2014 sort by test duration\n- `duration_trend` \u2014 sort by duration trend\n- `name` \u2014 sort alphabetically\n\n### Common queries\n\n| Goal | FQL + flags |\n|------|-------------|\n| Flaky tests | `--fql 'flip>0%' --sort flip_rate --sort-dir desc` |\n| Very flaky (>50%) | `--fql 'flip>50%' --sort flip_rate --sort-dir desc` |\n| Failed tests | `--fql 's:failed' --sort outcome --sort-dir desc` |\n| Regressions | `--fql 's:regressed'` |\n| All broken tests | `--fql 'status:(failed, regressed)'` |\n| Slow tests | `--fql 'd>5s' --sort duration --sort-dir desc` |\n| Tests matching error | `--fql '$timeout'` |\n| Tests in file | `--fql 'f:login.spec.ts'` |\n\n## FQL (Filter Query Language)\n\nFull reference: [references/fql.md](references/fql.md)\n\nKey rules:\n- Multiple tokens combine with AND: `s:failed f:e2e` means \"failed AND in e2e files\"\n- Prefix with `-` to exclude: `-#smoke` excludes smoke-tagged tests\n- Same filter type uses OR: `status:(failed, regressed)` means \"failed OR regressed\"\n- Quote values with spaces: `f:'tests/e2e checkout'`\n\n### Filter types\n\n| Filter | Syntax | Example |\n|--------|--------|---------|\n| Text search | `<text>` | `login` |\n| Status | `s:<status>` | `s:failed`, `status:(failed, regressed)` |\n| File | `f:<path>` | `f:login.spec.ts` |\n| Error | `$<text>` | `$timeout` |\n| Tag | `#<tag>` | `#smoke` |\n| Duration | `d><time>` | `d>2s`, `d<=500ms` |\n| Flip rate | `flip><pct>` | `flip>0%`, `fr>50%` |\n| Annotation | `@<type>` | `@skip` |\n\n### Status values\n\n`passed`, `failed`, `flaked`, `skipped`, `regressed`\n\n## Workflow: Fix My PR Tests\n\nWhen a user asks to fix failing tests in a PR, follow these steps:\n\n1. **Fetch regressions from the PR:**\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:regressed' --page-size 50\n   ```\n   Tests with status `regressed` were passing on the target branch but fail in this PR \u2014 these are **caused by the PR** and must be fixed.\n\n2. **Analyze the output:** Look at the error messages, file paths, and test names to understand what the PR broke.\n\n3. **Fix the regressions** by reading the reported file paths and error messages, then making targeted code changes.\n\n4. **Optionally check pre-existing failures:** Tests with status `failed` also fail on the target branch and are not caused by the PR. You can list them with:\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:failed' --page-size 50\n   ```\n   These are informational \u2014 fixing them is a bonus, not a requirement.\n\n5. **Ignore flakes:** Tests with status `flaked` failed but passed on retry \u2014 they are flaky and not actionable in the context of a PR fix.\n\n## Workflow tips\n\n1. Start broad: `flakiness list tests --project <org/project> --page-size 20`\n2. Filter down with FQL based on what you're investigating\n3. Use `--page-size 50` or higher to see more results at once\n4. Combine filters: `--fql 's:failed $timeout f:e2e -#smoke'`\n\nMore recipes: [references/recipes.md](references/recipes.md)\n"
+        "content": "---\nname: flakiness-investigation\ndescription: >-\n  TRIGGER when: CI fails, tests fail, PR checks fail, user asks about test results, regressions, flakiness, or test health.\n  Always use this INSTEAD OF `gh` CLI for investigating test failures \u2014 it distinguishes regressions (caused by the PR) from pre-existing failures and flakes.\n  DO NOT TRIGGER when: the user is asking about non-test CI issues (e.g. build failures, deployment problems).\n---\n\n# Flakiness Investigation\n\nUse the `flakiness` CLI to query and analyze test data from Flakiness.io.\n\n## Prerequisites\n\n- The `flakiness` CLI must be available in PATH (installed via `npm install -g flakiness` or `npx flakiness`).\n- A project must be specified: `--project <org/project>` or set `FLAKINESS_PROJECT` env var.\n- Authentication: run `flakiness auth login` first, or set `FLAKINESS_ACCESS_TOKEN`.\n\n## Core command\n\n```bash\nflakiness list tests --project <org/project> [--pr <number>] [--branch <name>] [--fql <query>] [--sort <axis>] [--sort-dir asc|desc] [--page <n>] [--page-size <n>] [--env-name <value>] [--env-path <value>] [--env-category <value>] [--env-os <value>] [--env-arch <value>] [--env-metadata <key=value>]\n```\n\n### Scope options\n\n| Flag | Effect |\n|------|--------|\n| *(none)* | Default branch \u2014 tests from the day of its head commit (in the project's timezone) |\n| `--pr <number>` | Pull request \u2014 tests from the merge-commit of the PR branch into the target branch |\n| `--branch <name>` | Named branch \u2014 tests from the day of its head commit (in the project's timezone) |\n\n`--pr` and `--branch` are mutually exclusive.\n\n### Environment filter options\n\nFilter results by environment. All flags are repeatable. Multiple values for the same flag are OR'd; different flags are AND'd.\n\n| Flag | Filters by | Example |\n|------|-----------|---------|\n| `--env-name <value>` | Environment name | `--env-name chromium` |\n| `--env-path <value>` | Config file path | `--env-path playwright.config.ts` |\n| `--env-category <value>` | Test category | `--env-category playwright` |\n| `--env-os <value>` | OS name + version | `--env-os \"Ubuntu 22.04\"` |\n| `--env-arch <value>` | CPU architecture | `--env-arch x86_64` |\n| `--env-metadata <key=value>` | User-supplied metadata | `--env-metadata browser=chromium` |\n\nThe output for each test shows environment info in the same `key=value` format:\n- **Env** line: system-collected data with keys matching the `--env-*` flag suffixes (`category=`, `name=`, `path=`, `os=`, `arch=`)\n- **Env Metadata** line (if any): user-supplied key=value pairs\n\nThis makes it easy to copy a value from the output and use it as a filter flag.\n\n### Status semantics with `--pr`\n\nWhen querying a PR, the status values have specific meaning:\n\n| Status | Meaning |\n|--------|---------|\n| `regressed` | Test was passing on the target branch but fails in this PR \u2014 **caused by the PR** |\n| `failed` | Test also fails on the target branch \u2014 **pre-existing failure, not caused by the PR** |\n| `flaked` | Test failed but passed on retry \u2014 flaky, not a real failure |\n| `passed` | Test passes |\n| `skipped` | Test was skipped |\n\n### Sort axes\n\n- `outcome` \u2014 sort by test outcome severity (default)\n- `flip_rate` \u2014 sort by flip rate (how often a test flips between pass/fail)\n- `duration` \u2014 sort by test duration\n- `duration_trend` \u2014 sort by duration trend\n- `name` \u2014 sort alphabetically\n\n### Common queries\n\n| Goal | FQL + flags |\n|------|-------------|\n| Flaky tests | `--fql 'flip>0%' --sort flip_rate --sort-dir desc` |\n| Very flaky (>50%) | `--fql 'flip>50%' --sort flip_rate --sort-dir desc` |\n| Failed tests | `--fql 's:failed' --sort outcome --sort-dir desc` |\n| Regressions | `--fql 's:regressed'` |\n| All broken tests | `--fql 'status:(failed, regressed)'` |\n| Slow tests | `--fql 'd>5s' --sort duration --sort-dir desc` |\n| Tests matching error | `--fql '$timeout'` |\n| Tests in file | `--fql 'f:login.spec.ts'` |\n| Tests on Linux | `--env-os \"Ubuntu 22.04\"` |\n| Tests for chromium project | `--env-name chromium` |\n| Tests with specific metadata | `--env-metadata browser=firefox` |\n| Linux or macOS failures | `--env-os \"Ubuntu 22.04\" --env-os \"Darwin 24.0\" --fql 's:failed'` |\n\n## FQL (Filter Query Language)\n\nFull reference: [references/fql.md](references/fql.md)\n\nKey rules:\n- Multiple tokens combine with AND: `s:failed f:e2e` means \"failed AND in e2e files\"\n- Prefix with `-` to exclude: `-#smoke` excludes smoke-tagged tests\n- Same filter type uses OR: `status:(failed, regressed)` means \"failed OR regressed\"\n- Quote values with spaces: `f:'tests/e2e checkout'`\n\n### Filter types\n\n| Filter | Syntax | Example |\n|--------|--------|---------|\n| Text search | `<text>` | `login` |\n| Status | `s:<status>` | `s:failed`, `status:(failed, regressed)` |\n| File | `f:<path>` | `f:login.spec.ts` |\n| Error | `$<text>` | `$timeout` |\n| Tag | `#<tag>` | `#smoke` |\n| Duration | `d><time>` | `d>2s`, `d<=500ms` |\n| Flip rate | `flip><pct>` | `flip>0%`, `fr>50%` |\n| Annotation | `@<type>` | `@skip` |\n\n### Status values\n\n`passed`, `failed`, `flaked`, `skipped`, `regressed`\n\n## Workflow: Fix My PR Tests\n\nWhen a user asks to fix failing tests in a PR, follow these steps:\n\n1. **Find the project slug:** Search the codebase for `flakinessProject` to find the `--project` value. It is typically configured in a test reporter config (e.g. `playwright.config.ts`, `jest.config.ts`) as `flakinessProject: 'org/project'`.\n\n2. **Fetch regressions from the PR:**\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:regressed' --page-size 50\n   ```\n   Tests with status `regressed` were passing on the target branch but fail in this PR \u2014 these are **caused by the PR** and must be fixed.\n\n3. **Analyze the output:** Look at the error messages, file paths, and test names to understand what the PR broke.\n\n4. **Fix the regressions** by reading the reported file paths and error messages, then making targeted code changes.\n\n5. **Optionally check pre-existing failures:** Tests with status `failed` also fail on the target branch and are not caused by the PR. You can list them with:\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:failed' --page-size 50\n   ```\n   These are informational \u2014 fixing them is a bonus, not a requirement.\n\n6. **Ignore flakes:** Tests with status `flaked` failed but passed on retry \u2014 they are flaky and not actionable in the context of a PR fix.\n\n## Workflow tips\n\n1. Start broad: `flakiness list tests --project <org/project> --page-size 20`\n2. Filter down with FQL based on what you're investigating\n3. Use `--page-size 50` or higher to see more results at once\n4. Combine filters: `--fql 's:failed $timeout f:e2e -#smoke'`\n\nMore recipes: [references/recipes.md](references/recipes.md)\n"
       },
       {
         "path": "references/fql.md",
@@ -2105,7 +2152,7 @@ var BUNDLED_SKILLS = [
       },
       {
         "path": "references/recipes.md",
-        "content": "# Investigation Recipes\n\nReplace `myorg/myproject` with the target project slug, or set `FLAKINESS_PROJECT`.\n\n## Query a pull request\n\nShows tests from the merge-commit of the PR branch into the target branch.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42\n```\n\n## Find PR regressions (caused by the PR)\n\nTests marked `regressed` were passing on the target branch but fail in this PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:regressed'\n```\n\n## Find pre-existing failures in a PR\n\nTests marked `failed` also fail on the target branch \u2014 not caused by the PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:failed'\n```\n\n## Find all broken tests in a PR\n\nIncludes both PR-caused regressions and pre-existing failures.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 'status:(failed, regressed)' --page-size 50\n```\n\n## Query a specific branch\n\nShows tests from the day of the branch's head commit, in the project's timezone.\n\n```bash\nflakiness list tests --project myorg/myproject --branch feature/login\n```\n\n## Find all flaky tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>0%' --sort flip_rate --sort-dir desc\n```\n\n## Find the most flaky tests (>50% flip rate)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>50%' --sort flip_rate --sort-dir desc\n```\n\n## Show failed tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed' --sort outcome --sort-dir desc\n```\n\n## Show regressions\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:regressed'\n```\n\n## Show all currently broken tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'status:(failed, regressed)' --sort outcome --sort-dir desc\n```\n\n## Show flaked tests (passed on retry)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:flaked' --sort flip_rate --sort-dir desc\n```\n\n## Find slow tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'd>5s' --sort duration --sort-dir desc\n```\n\n## Find tests by error text\n\n```bash\nflakiness list tests --project myorg/myproject --fql '$timeout'\nflakiness list tests --project myorg/myproject --fql '$\"network error\"'\n```\n\n## Combine filters\n\nFailed tests in e2e files, excluding smoke-tagged tests:\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed f:e2e -#smoke'\n```\n\n## Narrow to a specific file\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'f:login.spec.ts'\n```\n\n## Find tests with a specific annotation\n\n```bash\nflakiness list tests --project myorg/myproject --fql '@skip'\nflakiness list tests --project myorg/myproject --fql '@fixme'\n```\n"
+        "content": "# Investigation Recipes\n\nReplace `myorg/myproject` with the target project slug, or set `FLAKINESS_PROJECT`.\n\n## Query a pull request\n\nShows tests from the merge-commit of the PR branch into the target branch.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42\n```\n\n## Find PR regressions (caused by the PR)\n\nTests marked `regressed` were passing on the target branch but fail in this PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:regressed'\n```\n\n## Find pre-existing failures in a PR\n\nTests marked `failed` also fail on the target branch \u2014 not caused by the PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:failed'\n```\n\n## Find all broken tests in a PR\n\nIncludes both PR-caused regressions and pre-existing failures.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 'status:(failed, regressed)' --page-size 50\n```\n\n## Query a specific branch\n\nShows tests from the day of the branch's head commit, in the project's timezone.\n\n```bash\nflakiness list tests --project myorg/myproject --branch feature/login\n```\n\n## Find all flaky tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>0%' --sort flip_rate --sort-dir desc\n```\n\n## Find the most flaky tests (>50% flip rate)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>50%' --sort flip_rate --sort-dir desc\n```\n\n## Show failed tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed' --sort outcome --sort-dir desc\n```\n\n## Show regressions\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:regressed'\n```\n\n## Show all currently broken tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'status:(failed, regressed)' --sort outcome --sort-dir desc\n```\n\n## Show flaked tests (passed on retry)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:flaked' --sort flip_rate --sort-dir desc\n```\n\n## Find slow tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'd>5s' --sort duration --sort-dir desc\n```\n\n## Find tests by error text\n\n```bash\nflakiness list tests --project myorg/myproject --fql '$timeout'\nflakiness list tests --project myorg/myproject --fql '$\"network error\"'\n```\n\n## Combine filters\n\nFailed tests in e2e files, excluding smoke-tagged tests:\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed f:e2e -#smoke'\n```\n\n## Narrow to a specific file\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'f:login.spec.ts'\n```\n\n## Find tests with a specific annotation\n\n```bash\nflakiness list tests --project myorg/myproject --fql '@skip'\nflakiness list tests --project myorg/myproject --fql '@fixme'\n```\n\n## Filter by environment\n\n### Show tests for a specific OS\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\"\n```\n\n### Show tests for a specific environment name\n\n```bash\nflakiness list tests --project myorg/myproject --env-name chromium\n```\n\n### Show tests for a specific architecture\n\n```bash\nflakiness list tests --project myorg/myproject --env-arch arm64\n```\n\n### Show tests for multiple OSes (OR)\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --env-os \"Darwin 24.0\"\n```\n\n### Combine env filter with FQL\n\nFailed tests on Linux only:\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --fql 's:failed'\n```\n\n### Filter by user-supplied metadata\n\n```bash\nflakiness list tests --project myorg/myproject --env-metadata browser=firefox\n```\n\n### Combine multiple env filters (AND)\n\nTests on Linux with arm64 architecture:\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --env-arch arm64\n```\n"
       }
     ]
   }
@@ -2121,8 +2168,9 @@ function projectRoot() {
   }
 }
 async function cmdSkillsInstall(options) {
+  const root = options.project ? projectRoot() : os3.homedir();
   for (const skill of BUNDLED_SKILLS) {
-    const dest = path5.join(projectRoot(), `.${options.agent}`, "skills", skill.name);
+    const dest = path5.join(root, `.${options.agent}`, "skills", skill.name);
     await fs5.promises.rm(dest, { recursive: true, force: true });
     for (const file of skill.files) {
       const filePath = path5.join(dest, file.path);
@@ -2235,7 +2283,20 @@ var optTestsPR = new Option("--pr <number>", "Show tests from a specific pull re
   return parsed;
 }).conflicts("branch");
 var optTestsBranch = new Option("--branch <name>", "Show tests from a specific branch").conflicts("pr");
-list.command("tests").description("Query tests data. Defaults to the default branch (day of head commit in project timezone). Use --pr for PR merge-commit tests, or --branch for a named branch.").addOption(optTestsPage).addOption(optTestsPageSize).addOption(optTestsSort).addOption(optTestsSortDir).addOption(optTestsFQL).addOption(optTestsPR).addOption(optTestsBranch).addOption(mustFlakinessProject).addOption(optEndpoint).addOption(optAccessToken).action(async (options) => runCommand(async () => {
+function collectValues(value, prev) {
+  return [...prev ?? [], value];
+}
+var optTestsEnvName = new Option("--env-name <value>", "Filter by environment name (repeatable)").argParser(collectValues);
+var optTestsEnvPath = new Option("--env-path <value>", "Filter by config path (repeatable)").argParser(collectValues);
+var optTestsEnvCategory = new Option("--env-category <value>", "Filter by category (repeatable)").argParser(collectValues);
+var optTestsEnvOs = new Option("--env-os <value>", "Filter by OS name + version (repeatable)").argParser(collectValues);
+var optTestsEnvArch = new Option("--env-arch <value>", "Filter by CPU architecture (repeatable)").argParser(collectValues);
+var optTestsEnvMetadata = new Option("--env-metadata <key=value>", "Filter by user-supplied environment metadata (repeatable)").argParser((value, prev) => {
+  if (!value.includes("="))
+    throw new Error(`Invalid env-metadata format '${value}'; expected key=value`);
+  return [...prev ?? [], value];
+});
+list.command("tests").description("Query tests data. Defaults to the default branch (day of head commit in project timezone). Use --pr for PR merge-commit tests, or --branch for a named branch.").addOption(optTestsPage).addOption(optTestsPageSize).addOption(optTestsSort).addOption(optTestsSortDir).addOption(optTestsFQL).addOption(optTestsPR).addOption(optTestsBranch).addOption(optTestsEnvName).addOption(optTestsEnvPath).addOption(optTestsEnvCategory).addOption(optTestsEnvOs).addOption(optTestsEnvArch).addOption(optTestsEnvMetadata).addOption(mustFlakinessProject).addOption(optEndpoint).addOption(optAccessToken).action(async (options) => runCommand(async () => {
   await cmdListTests({
     page: options.page,
     pageSize: options.pageSize,
@@ -2244,6 +2305,12 @@ list.command("tests").description("Query tests data. Defaults to the default bra
     fql: options.fql,
     pr: options.pr,
     branch: options.branch,
+    envName: options.envName,
+    envPath: options.envPath,
+    envCategory: options.envCategory,
+    envOs: options.envOs,
+    envArch: options.envArch,
+    envMetadata: options.envMetadata,
     endpoint: options.endpoint,
     accessToken: options.accessToken,
     flakinessProject: options.project
@@ -2261,8 +2328,8 @@ auth.command("whoami").description("Show current logged in user information").ac
 }));
 var skills = program.command("skills").description("Manage agent skills");
 var optAgent = new Option("--agent <agent>", "Target agent").choices(AGENTS).makeOptionMandatory();
-skills.command("install").description("Install bundled skills into the project").addOption(optAgent).action(async (options) => runCommand(async () => {
-  await cmdSkillsInstall({ agent: options.agent });
+skills.command("install").description("Install bundled skills into the user home directory (use --project for project-local install)").addOption(optAgent).option("--project", "Install into the project directory instead of the user home directory").action(async (options) => runCommand(async () => {
+  await cmdSkillsInstall({ agent: options.agent, project: options.project });
 }));
 program.command("access").description("Check access to a Flakiness.io project").addOption(mustFlakinessProject).addOption(optAccessToken).addOption(optEndpoint).option("--json", "Output result as JSON").option("-q, --quiet", "Suppress output, only set exit code").action(async (options) => runCommand(async () => {
   await cmdAccess({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flakiness",
-  "version": "0.218.0",
+  "version": "0.219.0",
   "private": false,
   "bin": {
     "flakiness": "./lib/cli/cli.js"
@@ -22,8 +22,9 @@
     "@playwright/test": "^1.57.0",
     "@types/debug": "^4.1.12",
     "@types/express": "^4.17.20",
-    "@flakiness/shared": "0.218.0",
-    "@flakiness/server": "0.218.0"
+    "gray-matter": "^4.0.3",
+    "@flakiness/shared": "0.219.0",
+    "@flakiness/server": "0.219.0"
   },
   "dependencies": {
     "@flakiness/flakiness-report": "^0.28.0",