# Limits

> The engine's hard caps, what goflag deliberately does not check, and the failure modes worth knowing about before you trust a green run.

A tool that only documents what it catches is not honest about what it misses.

## Engine caps

These are compiled in, not configurable. They exist so a run on a large site
finishes rather than melting somebody's laptop or somebody's origin. The
values are listed in the [CLI reference](/docs/cli#engine-limits).

The user-facing caps you _can_ move are `--max-pages` (default `200`) and
`--depth` (default `2`). When any cap cuts a crawl short, `diagnostics.truncated`
is `true` and the terminal prints `note: results truncated by a page/link cap`.
**A truncated report is a report about part of your site**, and a green verdict on
one means very little.

## What goflag does not check

These are decisions, not oversights:

- **Performance.** No Core Web Vitals, no Lighthouse score, no bundle analysis.
  Different tools, different failure modes, and both already well served.
- **Accessibility.** Nothing here is an a11y audit. `axe` and friends do that
  properly.
- **Content quality.** No keyword analysis, no readability score, no rank
  tracking, no competitor comparison.
- **Structured data validity.** JSON-LD presence is used as a signal that a page's
  head is not empty. Its _correctness_ is not judged.
- **Images.** No `alt` audit, no weight checks, no format advice.
- **JavaScript errors.** The headless path renders a page; it does not report what
  the console said while doing it.
- **Anything requiring authentication.** goflag sends no credentials and has
  nowhere to put them. It audits what an anonymous crawler sees, which is also the
  point.

## Failure modes worth knowing

**Rate limiting looks like breakage.** A site that answers `429` under a crawl
produces link findings that say more about the crawl than about the links.
`--timeout` and a smaller `--max-pages` help; auditing your own origin from CI
usually avoids it entirely.

**Anti-bot filters return 403.** These are triaged apart from real breakage: the
verdict is `blocked`, not `broken`, and it appears in `warnings`. A heavily
protected third party can still produce noise. This is one reason `--no-external`
belongs in a CI gate.

**Soft 404s are detected heuristically.** A page that returns `200` while saying
"not found" is caught by pattern, not by proof. False negatives exist.

**The length thresholds are conventions, not specifications.** `title.length` and
`description.length` cite no standard, because there is none to cite. They are
labelled as heuristics in the [catalogue](/docs/rules).

**Client-rendered metadata needs the browser path.** By default, a page with an
empty-looking head is re-rendered in Chromium. With `--static`, it is judged as
served, which is correct for a crawler, and misleading if you expected the
runtime result. See [Install](/docs/install#chromium) before opting in.

**A baseline can hide a lot.** `--regressions-only` passes builds on sites with
known defects. That is what it is for. The output never says `clean` and always
prints how many findings are being let through and how old the baseline is, but
if nobody reads it, the number does not help. See
[baseline gating](/docs/ci/baseline).

## Known false positives, and why they are documented

Capturing the first baselines on four production sites surfaced five ways goflag
was wrong. Two are worth reading because they shaped the design:

- The path segment `/cv` was read as a locale, the mistake that ended locale
  guessing. The full story is in
  [Translations](/docs/i18n#the-bug-that-started-this).
- A trailing slash was stripped before probing, which declared 159 working
  citation links dead and sent somebody to fix content that was already correct.

All five are fixed. They are published rather than buried because a tool that
reports defects has to be auditable itself, and because the second one cost
somebody an afternoon.

## Reporting a wrong finding

A finding you believe is wrong is worth an issue: include the URL, the rule id,
and the `--json` output for that page. `id` is stable, so a report from three
weeks ago still identifies the same finding today.