# DollarLint installation instructions for agents

Install DollarLint, add project config, validate the repository, tune noisy behavior, and summarize only the remaining real findings.

## 1. Install the CLI

Pick the first method that fits the environment.

1. Homebrew available:

       brew install --cask dollarlint/tap/dollarlint

2. npm available and lifecycle scripts are allowed:

       npm install -g dollarlint

3. Go available:

       go install github.com/dollarlint/dollarlint/cmd/dollarlint@latest

   Ensure $(go env GOPATH)/bin is on PATH.

4. Otherwise, download a release archive from:

       https://github.com/dollarlint/dollarlint/releases/latest

   Verify checksums when practical, and put dollarlint on PATH.

Verify the install:

    dollarlint version

## 2. Create or update config

Work from the repository root.

Do not run interactive dollarlint init.

If .dollarlint.toml already exists, read it and preserve intentional settings.

If no config exists, generate a fully default config non-interactively:

    dollarlint init --defaults

Use that generated config as the starting point, then edit it for this repository.

## 3. Test and iterate

1. Inspect discovery and schema association first:

       dollarlint inspect . --format json

   Prefer JSON output while analyzing. Use it to read every discovered file, whether it has a schema, why that schema was chosen or skipped, and any suggested config snippets.

2. Run:

       dollarlint validate . --format json --locations --show-skipped

   Use JSON fields such as schemaMatch, schemaGap, suggestedAssociation, suggestedCatalogIgnore, warnings, skipReason, skipClass, category, line, and column. Do not write JSON output artifacts into the repository unless the user asks; use stdout or a temporary file.

3. When inspect shows a correct catalog match for an important first-party config file, make it explicit in .dollarlint.toml with [[schemas.associations]]. Prefer explicit associations for project-owned configs that should keep being validated even if catalog behavior changes.

4. If important first-party files are skipped, add [[schemas.associations]] entries or add in-file schema declarations. Leave unimportant skipped files alone.

5. Exclude generated files, dependency folders, snapshots, baselines, and intentionally invalid fixtures with narrow discovery.exclude patterns only when they produce parse errors, validation noise, or excessive discovery volume. Do not exclude a file solely because it is skipped.

6. Use [[ignore]] only for known accepted validation issues. Do not hide unknown failures with broad excludes or ignores.

7. Re-run inspect and validate until discovered, associated, validated, skipped, warning, and issue counts look reasonable for this repository. A nonzero skipped count is acceptable when the skipped files do not need schema coverage.

8. Before reporting that setup is complete, minimize .dollarlint.toml. Treat the generated default config as temporary scaffolding, not the desired final file.

   Remove every unchanged default key and every generated section that contains only unchanged defaults. Do not keep defaults just because dollarlint init wrote them.

   The final config should contain project-specific choices only, such as:

   - discovery.exclude entries for this repository
   - [[schemas.associations]] entries for important first-party files
   - [[schemas.catalogs.ignore]] entries for catalog matches that should stay skipped
   - [[ignore]] rules for known accepted validation issues
   - non-default policy choices, such as enabling catalog matching, requiring schema coverage, changing nested config behavior, or opting into output locations

   Remove unchanged generated values such as configs.mode = "single", parsing.json.mode = "auto", default schema depth/concurrency, default fetch/cache settings, default catalog source definitions, and default output settings unless you intentionally changed or need to document that policy for this repo.

   A good final config is usually much shorter than the generated starter. If a value matches DollarLint's normal behavior and does not explain a repo-specific decision, delete it.

## 4. Report to the user

Include:

- the installer chosen and dollarlint version output
- the config file created or changed
- the final validation command and summary counts
- remaining active findings grouped by file with line/column when available
- which active findings were ignored or excluded and why
- which skipped files still need schema coverage, if any

Write the final report for the user in concise human-readable prose, not as raw JSON.

Separate parse errors, schema-fetch warnings, coverage gaps, and skipped files from user-actionable validation findings. Do not summarize skipped files as failures, and do not tune them away unless they are causing real parse, validation, or discovery noise.

Human docs:

- Installation: https://dollarlint.dev/guides/installation/
- Configuration: https://dollarlint.dev/reference/configuration/