# `jadpo suggest`

Hint where a standard type or operation fits.

Formats, then scans the project for code that could use a standard type or operation: hand-rolled money, durations, quantities, points, validation patterns and loops, found by the signals each standard type's entry holds. It never edits: each finding is numbered (S1, S2...) for the agent to act on, and the report ends with the routine to follow. `ignore` keeps a finding quiet until its code changes, in the committed ignored_suggestions.jadpo_record. `found` records something the scan missed, before the code changes, and teaches it so the next scan finds the same pattern, in the committed taught_suggestions.jadpo_record. `share` sends the hashes of what was learned to Jadpo HQ at once, shows exactly what it would send of the snippets HQ asks for, and sends them only with `--approve`, after a person said yes; `suggestions { share: false }` in app.jadpo or JADPO_SUGGEST_SHARE=off turns sharing off. `--catalogue` lists every signal.

```text
jadpo suggest [action] [subject] [what] [why]
```

## Arguments

- `action` (optional): What to do besides scanning: ignore, found or share
- `subject` (optional): For ignore, the suggestion's number; for found, <file>:<line>
- `what` (optional): For ignore, the reason; for found, the type or operation
- `why` (optional): For found, the reason

## Flags

- `--catalogue`: List every signal the scan looks for
- `--approve`: Send what HQ asked for, after a person's yes
- `--decline`: Drop the snippets HQ asked for, sending none
- `--new-token`: Replace the project token, then share
- `--unattended`: Send only hashes; also when CI is set

## On every command

- `--json`: Print data for tools instead of text
- `--help`: Show every flag, with examples
- `--color <when>`: Choose when to use colour

`jadpo suggest --json` writes one JSON document to standard output instead of text, with the same exit code. The document has `schemaVersion`, `command` (`"suggest"`), `ok`, `data` (what the command produced, `null` when it failed) and `diagnostics` (each error with its `rule`, `reason`, `next` and `help`). A command that needs a terminal refuses `--json` and names the flags that do the same job.

## Examples

```text
# Find where the code could use a standard type
jadpo suggest
# Keep the first suggestion quiet, with the reason
jadpo suggest ignore S1 "Basis points, not money"
# Record a miss before fixing it
jadpo suggest found domains/shop/actions/pence_of.jadpo:5 Money "Pence held as Int"
# See every signal it looks for
jadpo suggest --catalogue
# Send what was learned to Jadpo HQ
jadpo suggest share
# Send the snippets HQ asked for, after the person said yes
jadpo suggest share --approve
```

## Errors

- [`cli.suggest_arguments`](../errors/cli.suggest_arguments.md): Suggest command has invalid arguments
- [`suggest.record_invalid`](../errors/suggest.record_invalid.md): Suggestions record can't be read
- [`suggest.share_failed`](../errors/suggest.share_failed.md): Jadpo HQ couldn't be reached or refused what was shared
- [`toolchain.artifact_write_failed`](../errors/toolchain.artifact_write_failed.md): Generated file could not be written
- [`toolchain.project_not_found`](../errors/toolchain.project_not_found.md): Project could not be found