docs: streamline README getting started

.github/renovate-tracked-deps.json

@@ -93,13 +93,6 @@
         "mise"
       ]
     },
-    "README.md": {
-      "regex": [
-        "actionlint",
-        "shellcheck",
-        "shfmt"
-      ]
-    },
     "mise.toml": {
       "mise": [
         "actionlint",

.github/renovate.json5

@@ -16,46 +16,6 @@
   // Kept inline (not via "local>.") because renovate-deps.py runs with
   // --platform=local which cannot resolve local presets.
   customManagers: [
-    {
-      customType: "regex",
-      description: "Update SHA-pinned raw.githubusercontent.com URLs in README.md",
-      managerFilePatterns: ["/^README\\.md$/"],
-      matchStrings: ["https://raw\\.githubusercontent\\.com/(?<depName>[^/]+/[^/]+)/(?<currentDigest>[a-f0-9]{40})/.*#\\s*(?<currentValue>v\\S+)"],
-      datasourceTemplate: "github-tags",
-    },
-    {
-      customType: "regex",
-      description: "Update shellcheck version in README quickstart example",
-      managerFilePatterns: ["/^README\\.md$/"],
-      matchStrings: [
-        "# Add whichever linters apply to your repo:\\n[\\s\\S]*?shellcheck\\s*=\\s*\"(?<currentValue>[^\"]+)\"[\\s\\S]*?\\n```",
-      ],
-      datasourceTemplate: "github-releases",
-      depNameTemplate: "shellcheck",
-      packageNameTemplate: "koalaman/shellcheck",
-    },
-    {
-      customType: "regex",
-      description: "Update shfmt version in README quickstart example",
-      managerFilePatterns: ["/^README\\.md$/"],
-      matchStrings: [
-        "# Add whichever linters apply to your repo:\\n[\\s\\S]*?shfmt\\s*=\\s*\"(?<currentValue>[^\"]+)\"[\\s\\S]*?\\n```",
-      ],
-      datasourceTemplate: "github-releases",
-      depNameTemplate: "shfmt",
-      packageNameTemplate: "mvdan/sh",
-    },
-    {
-      customType: "regex",
-      description: "Update actionlint version in README quickstart example",
-      managerFilePatterns: ["/^README\\.md$/"],
-      matchStrings: [
-        "# Add whichever linters apply to your repo:\\n[\\s\\S]*?actionlint\\s*=\\s*\"(?<currentValue>[^\"]+)\"[\\s\\S]*?\\n```",
-      ],
-      datasourceTemplate: "github-releases",
-      depNameTemplate: "actionlint",
-      packageNameTemplate: "rhysd/actionlint",
-    },
     {
       customType: "regex",
       description: "Update mise version in GitHub Actions workflows",
@@ -126,11 +86,5 @@
       description: "Only update mise once a week",
       schedule: ["before 4am on Monday"],
     },
-    {
-      matchPackageNames: ["ghcr.io/super-linter/super-linter"],
-      matchCurrentValue: "/^slim-/",
-      description: "Use regex versioning for slim Super-Linter tags (slim-v8.4.0)",
-      versioning: "regex:^slim-v(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)$",
-    },
   ],
 }

AGENTS.md

@@ -95,9 +95,13 @@ vars control its behaviour:
   e.g. `FLINT_CASES=shellcheck` or
   `FLINT_CASES=shellcheck/clean`.
 - `UPDATE_SNAPSHOTS=1` — regenerate golden stdout/stderr/exit
-  in `test.toml` instead of asserting. Always review the diff
+  in `test.toml` instead of asserting (run via
+  `mise run generate:snapshots`). Always review the diff
   before committing.
 
+To regenerate README + docs tables from the registry/CLI, run
+`mise run generate`.
+
 On failure the test prints a rerun hint, e.g.:
 `FLINT_CASES=shellcheck/clean cargo test cases`
 

default.json

@@ -72,12 +72,6 @@
       "groupName": "flint",
       "description": "Only update flint once a week",
       "schedule": ["before 4am on Monday"]
-    },
-    {
-      "matchPackageNames": ["ghcr.io/super-linter/super-linter"],
-      "matchCurrentValue": "/^slim-/",
-      "description": "Use regex versioning for slim Super-Linter tags (slim-v8.4.0)",
-      "versioning": "regex:^slim-v(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)$"
     }
   ]
 }

docs/cli.md

@@ -14,17 +14,23 @@ it do not need to re-learn the interface.
 
 ## `flint run` flags
 
-| Flag                 | Description                                                                                                          |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `--fix`              | Fix what's fixable, report `clean` / `fixed` / `partial` / `review` outcomes; exit non-zero if anything needs action |
-| `--full`             | Lint all files instead of only changed files                                                                         |
-| `--short`            | Compact summary output, no per-check noise                                                                           |
-| `--verbose`          | Show all linter output, not just failures                                                                            |
-| `--new-from-rev REV` | Diff base (default: merge base with base branch)                                                                     |
-| `--to-ref REF`       | Diff head (default: HEAD)                                                                                            |
-
-Every flag has an env var equivalent: `FLINT_FIX`, `FLINT_FULL`,
-`FLINT_VERBOSE`, `FLINT_SHORT`, `FLINT_NEW_FROM_REV`, `FLINT_TO_REF`.
+<!-- run-flags-start -->
+<!-- Generated. Run `mise run generate` to regenerate. -->
+
+| Flag                 | Env var              | Description                                                                                                                                                                |
+| -------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--fix`              | `FLINT_FIX`          | Fix what's fixable, report what still needs review. Exits 1 if anything was fixed (uncommitted) or needs review; 0 if already clean. Only 0 vs non-0 is stable for callers |
+| `--allow-fixed`      | `FLINT_ALLOW_FIXED`  | In --fix mode, exit 0 when all reported issues were fixed successfully. Still exits non-zero when any check is partial or needs review                                     |
+| `--full`             | `FLINT_FULL`         | Lint all files instead of only changed files                                                                                                                               |
+| `--verbose`          | `FLINT_VERBOSE`      | Show all linter output, not just failures                                                                                                                                  |
+| `--short`            | `FLINT_SHORT`        | Compact summary output — no per-check noise (human) or read-only AI review                                                                                                 |
+| `--new-from-rev` REV | `FLINT_NEW_FROM_REV` | Show only new issues created after git revision REV (default: merge base with base branch)                                                                                 |
+| `--to-ref` REF       | `FLINT_TO_REF`       | Compare changed files to this ref (default: HEAD)                                                                                                                          |
+| `--time`             | `FLINT_TIME`         | Show how long each linter took to run                                                                                                                                      |
+
+<!-- run-flags-end -->
+
+All `flint run` flags above have env var equivalents.
 
 ## Intended use by context
 
@@ -67,12 +73,37 @@ have changed. Config-file triggers are detected from the raw git change list, so
 they still apply when the config path itself is excluded from ordinary lint file
 selection.
 
-Flint intentionally supports one canonical config filename per linter when it
-passes config paths explicitly. If an active linter has a known alternate
-upstream config file, Flint fails before running the linter instead of silently
-ignoring or partially auto-discovering that config. Move the config to the
-Flint-managed filename under `FLINT_CONFIG_DIR`, or remove the alternate file.
-Biome is the exception: its canonical config is root `biome.jsonc`.
+## Adaptive runs
+
+Some linters are expensive enough that running them on every local
+`flint run` would slow the inner loop. For those, `flint run` skips the
+linter when none of the changed files could plausibly affect its result.
+CI is unaffected — it always runs the full set.
+
+Affected linters:
+
+| Linter                                                              | Skipped locally when…                                           |
+| ------------------------------------------------------------------- | --------------------------------------------------------------- |
+| [`renovate-deps`](linters/renovate-deps.md#when-does-this-run)      | No change to Renovate config, the snapshot, or any tracked file |
+
+To force a local run of a skipped linter:
+
+- `flint run --full` — runs every active linter
+- `flint run <linter>` — runs just that one
+
+### Canonical config filenames
+
+When Flint passes config paths explicitly, it supports one canonical config
+filename per linter. If an active linter has a known alternate upstream config
+file, Flint fails before running the linter instead of silently ignoring or
+partially auto-discovering that config.
+
+Move the config to the Flint-managed filename under `FLINT_CONFIG_DIR`, or
+remove the alternate file.
+
+> [!NOTE]
+> Biome is the exception: its canonical config is root `biome.jsonc`, not a
+> file under `FLINT_CONFIG_DIR`.
 
 **`--short` output** — failed checks partitioned by fixability, fixable ones
 expressed as the exact command to run: