@rom-weaver/cli 0.15.1 → 0.16.1

package/docs/man/rom-weaver-identify.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-identify \- Identify a ROM title from its checksums
 .SH SYNOPSIS
-\fBrom\-weaver identify\fR [\fB\-i\fR|\fB\-\-input\fR] [\fB\-\-json\fR] [\fB\-\-hash\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-size\fR] [\fB\-d\fR|\fB\-\-database\fR] [\fB\-\-log\-level\fR] [\fB\-\-system\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-offline\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-database\-dir\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-exhaustive\-database\-search\fR] [\fB\-\-no\-color\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-filter\fR] [\fB\-\-no\-extract\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-trim\-fix\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIsubcommands\fR]
+\fBrom\-weaver identify\fR [\fB\-i\fR|\fB\-\-input\fR] [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-hash\fR] [\fB\-\-json\fR] [\fB\-\-jsonl\fR] [\fB\-\-size\fR] [\fB\-d\fR|\fB\-\-database\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-system\fR] [\fB\-\-log\-level\fR] [\fB\-\-name\fR] [\fB\-\-title\-index\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-debug\fR] [\fB\-\-limit\fR] [\fB\-\-offline\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-database\-dir\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-exhaustive\-database\-search\fR] [\fB\-\-no\-color\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-filter\fR] [\fB\-\-no\-extract\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-trim\-fix\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIFILE\fR] [\fIsubcommands\fR]
 .SH DESCRIPTION
 Identify a ROM title from its checksums and local RWFP1 database packs.
 .PP
@@ -29,6 +29,15 @@ RWFP1 identify pack, raw or Brotli, to search instead of the built\-in data (rep
 \fB\-\-system\fR \fI<SYSTEM>\fR
 Search only this system\*(Aqs pack. Takes a canonical platform name or a common alias (e.g. `snes`, `psx`)
 .TP
+\fB\-\-name\fR \fI<QUERY>\fR
+Search the database for games whose name matches QUERY, instead of identifying a file or checksum
+.TP
+\fB\-\-title\-index\fR \fI<JSON>\fR
+Search a cross\-platform title index with \-\-name instead of database packs
+.TP
+\fB\-\-limit\fR \fI<N>\fR
+Maximum number of matches \-\-name returns [default: 50]
+.TP
 \fB\-\-offline\fR
 Assert that identify performs no network access (it never does natively; this flag records the guarantee)
 .TP
@@ -68,19 +77,28 @@ How many threads to use at most. auto uses every core; a format may still use fe
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+[\fIFILE\fR]
+File input; an alternative to \-i, \-\-input
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -101,10 +119,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-man.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-man \- Print or install the generated CLI man pages
 .SH SYNOPSIS
-\fBrom\-weaver man\fR [\fB\-\-install\fR] [\fB\-\-json\fR] [\fB\-\-man\-dir\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fICOMMAND\fR]
+\fBrom\-weaver man\fR [\fB\-\-install\fR] [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-man\-dir\fR] [\fB\-\-jsonl\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-debug\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fICOMMAND\fR]
 .SH DESCRIPTION
 Print one generated CLI man page, or install generated pages in a user manpath.
 .PP
@@ -29,17 +29,23 @@ Print help (see a summary with \*(Aq\-h\*(Aq)
 Command path to print
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -60,10 +66,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-patch-apply.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-patch\-apply \- Apply one or more patches to a ROM, in order
 .SH SYNOPSIS
-\fBrom\-weaver patch apply\fR [\fB\-\-json\fR] [\fB\-\-progress\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-\-no\-progress\fR] [\fB\-\-target\fR] [\fB\-\-filter\fR] [\fB\-\-log\-level\fR] [\fB\-\-no\-extract\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-no\-ignore\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-patch\fR] [\fB\-\-color\fR] [\fB\-\-patch\-select\fR] [\fB\-\-no\-color\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-bundle\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-with\fR] [\fB\-\-without\fR] [\fB\-\-no\-compress\fR] [\fB\-\-compress\-format\fR] [\fB\-\-compress\-codec\fR] [\fB\-\-compress\-level\fR] [\fB\-\-assume\-in\fR] [\fB\-\-expect\-in\fR] [\fB\-\-patch\-header\fR] [\fB\-\-patch\-basis\fR] [\fB\-\-output\-header\fR] [\fB\-\-repair\-checksum\fR] [\fB\-\-n64\-byte\-order\fR] [\fB\-\-ignore\-checksum\-validation\fR] [\fB\-\-expect\-out\fR] [\fB\-\-code\fR] [\fB\-\-code\-system\fR] [\fB\-\-code\-kind\fR] [\fB\-\-emit\-bundle\fR] [\fB\-\-tui\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-\-force\fR] [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-i\fR|\fB\-\-input\fR>
+\fBrom\-weaver patch apply\fR [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-\-jsonl\fR] [\fB\-\-target\fR] [\fB\-\-filter\fR] [\fB\-\-progress\fR] [\fB\-\-no\-extract\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-patch\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-debug\fR] [\fB\-\-patch\-select\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-bundle\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-with\fR] [\fB\-\-no\-color\fR] [\fB\-\-without\fR] [\fB\-\-without\-cheats\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-no\-compress\fR] [\fB\-\-compress\-format\fR] [\fB\-\-compress\-codec\fR] [\fB\-\-compress\-level\fR] [\fB\-\-assume\-in\fR] [\fB\-\-expect\-in\fR] [\fB\-\-patch\-header\fR] [\fB\-\-patch\-basis\fR] [\fB\-\-patch\-input\-check\fR] [\fB\-\-patch\-output\-check\fR] [\fB\-\-default\-patch\-basis\fR] [\fB\-\-output\-header\fR] [\fB\-\-repair\-checksum\fR] [\fB\-\-n64\-byte\-order\fR] [\fB\-\-ignore\-checksum\-validation\fR] [\fB\-\-expect\-out\fR] [\fB\-\-code\fR] [\fB\-\-code\-system\fR] [\fB\-\-code\-kind\fR] [\fB\-\-cheat\fR] [\fB\-\-cheat\-database\fR] [\fB\-\-cheat\-system\fR] [\fB\-\-game\fR] [\fB\-\-allow\-cheat\-conflicts\fR] [\fB\-\-emit\-bundle\fR] [\fB\-\-tui\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-\-force\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-i\fR|\fB\-\-input\fR>
 .SH DESCRIPTION
 Apply one or more patches to a ROM, in order.
 .PP
@@ -38,9 +38,6 @@ cannot be combined with other patches or with the header and checksum options.
 \fB\-\-force\fR
 Overwrite the output if it already exists (without this, the command stops instead)
 .TP
-\fB\-n\fR, \fB\-\-dry\-run\fR
-Print the plan (inputs, patches, output, format, codec, level, threads) and stop without writing
-.TP
 \fB\-h\fR, \fB\-\-help\fR
 Print help (see a summary with \*(Aq\-h\*(Aq)
 .SH BASIC
@@ -56,7 +53,7 @@ Leave it out and rom\-weaver looks for RetroArch\-style patches sitting next to
 the ROM inside the input archive.
 .TP
 \fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
-Where to write the patched ROM. Optional when a bundle already names the output
+Output path; \- writes one completed binary file to stdout
 .TP
 \fB\-\-no\-compress\fR
 Write a plain ROM instead of compressing the result
@@ -192,6 +189,9 @@ Turn on a bundle patch the bundle leaves off by default, matched by name or file
 .TP
 \fB\-\-without\fR \fI<GLOB>\fR
 Turn off a bundle patch, matched by name or file name (repeatable)
+.TP
+\fB\-\-without\-cheats\fR
+Ignore every cheat the bundle records and run only its patch chain
 .SH COMPATIBILITY
 .TP
 \fB\-\-assume\-in\fR \fI<ALGO=HEX>\fR
@@ -253,7 +253,7 @@ auto
 Which ROM the preceding \-\-patch was built against, and so which one its
 checksums describe.
 
-  auto      Work it out from the checksums (the default).
+  auto      Clear the shared rule and work it out from the checksums.
   base      The original ROM. It is verified once up front, and the patch\*(Aqs own
             checks are skipped when it runs later in the chain.
   previous  The output of the patch before it.
@@ -261,9 +261,27 @@ checksums describe.
 Reach for this when several patches in a chain were each written against the
 unmodified ROM rather than against each other.
 
-This flag must follow the \-\-patch it describes; it binds to the most recent
-\-\-patch and carries forward until the next occurrence. An occurrence before any
-\-\-patch applies to every patch.
+This flag must follow the \-\-patch it describes and applies only to that patch.
+Use \-\-default\-patch\-basis to set one rule for every patch.
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+auto
+.IP \(bu 2
+base
+.IP \(bu 2
+previous
+.RE
+.TP
+\fB\-\-default\-patch\-basis\fR \fI<DEFAULT_PATCH_BASIS>\fR
+Set one input ROM rule for every patch. An individual \-\-patch\-basis can override it.
+
+  base      Every patch was made from the original ROM.
+  previous  Each later patch was made from the previous result.
+  auto      Infer the input ROM from checksums (the default).
 .br
 
 .br
@@ -345,6 +363,12 @@ byte\-swapped
 Apply the patch even when its own checksums do not match. Can produce a broken ROM
 .SH DIAGNOSTICS/AUTHORING
 .TP
+\fB\-\-patch\-input\-check\fR \fI<ALGO=HEX>\fR
+Expected input checks for the preceding patch (repeatable, comma\-separable)
+.TP
+\fB\-\-patch\-output\-check\fR \fI<ALGO=HEX>\fR
+Expected output checks for the preceding patch (repeatable, comma\-separable)
+.TP
 \fB\-\-expect\-out\fR \fI<ALGO=HEX>\fR
 Fail unless the patched ROM has this checksum, as in sha1=abc... (repeatable, comma\-separable)
 .TP
@@ -352,7 +376,7 @@ Fail unless the patched ROM has this checksum, as in sha1=abc... (repeatable, co
 Game Genie or GameShark/Pro Action Replay code to bake into the ROM. Repeat for each code
 .TP
 \fB\-\-code\-system\fR \fI<CODE_SYSTEM>\fR
-Console the \-\-code values are for (nes, snes, genesis, gameboy, gba, psx), when the ROM header does not say
+Console the \-\-code values are for (nes, snes, genesis, 32x, sms, gamegear, sg1000, gameboy, gba, psx), when the ROM header does not say
 .TP
 \fB\-\-code\-kind\fR \fI<CODE_KIND>\fR [default: auto]
 Which cheat scheme the \-\-code values use: auto, game\-genie, gameshark/par, or xploder
@@ -362,23 +386,45 @@ Also write a rom\-weaver\-bundle.json recording this run, so someone else can re
 .TP
 \fB\-\-tui\fR
 Ask for each patch\*(Aqs name, version, and author, then apply and write a bundle. Needs a terminal
+.SH CHEATS
+.TP
+\fB\-\-cheat\fR \fI<ID_OR_DESCRIPTION>\fR
+Database cheat to use, by record ID or exact description. Repeat for each cheat
+.TP
+\fB\-\-cheat\-database\fR \fI<DIR>\fR
+Directory holding manifest.json and the <system>.json cheat shards. Defaults to $ROM_WEAVER_CHEAT_DATABASE, then the per\-user data directory
+.TP
+\fB\-\-cheat\-system\fR \fI<SYS>\fR
+Console the cheat shard is for (nes, snes, genesis, gameboy, gameboy\-color, gba), when the ROM header does not say
+.TP
+\fB\-\-game\fR \fI<ID>\fR
+Use this database game ID instead of matching the ROM by checksum or title
+.TP
+\fB\-\-allow\-cheat\-conflicts\fR
+Let a later cheat overwrite an earlier one at the same offset instead of failing
 .SH PERFORMANCE
 .TP
 \fB\-j\fR, \fB\-\-threads\fR \fI<auto|N>\fR [default: auto]
 How many threads to use at most. auto uses every core; a format may still use fewer
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -399,10 +445,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-patch-create.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-patch\-create \- Build a patch from an original ROM and a changed one
 .SH SYNOPSIS
-\fBrom\-weaver patch create\fR [\fB\-\-json\fR] [\fB\-\-modified\fR] [\fB\-\-progress\fR] [\fB\-f\fR|\fB\-\-format\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-plan\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-ignore\-checksum\-validation\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-checksum\-name\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-assume\-in\fR] [\fB\-\-color\fR] [\fB\-\-code\fR] [\fB\-\-no\-color\fR] [\fB\-\-code\-system\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-code\-kind\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-\-solid\-system\fR] [\fB\-\-solid\-game\fR] [\fB\-\-solid\-hack\fR] [\fB\-\-solid\-version\fR] [\fB\-\-solid\-author\fR] [\fB\-\-solid\-contact\fR] [\fB\-\-solid\-comment\fR] [\fB\-\-solid\-extended\fR] [\fB\-\-xdelta\-secondary\fR] [\fB\-\-force\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-\-original\fR>
+\fBrom\-weaver patch create\fR [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-modified\fR] [\fB\-f\fR|\fB\-\-format\fR] [\fB\-\-jsonl\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-plan\fR] [\fB\-\-ignore\-checksum\-validation\fR] [\fB\-\-log\-level\fR] [\fB\-\-checksum\-name\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-assume\-in\fR] [\fB\-\-debug\fR] [\fB\-\-code\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-code\-system\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-code\-kind\fR] [\fB\-\-color\fR] [\fB\-\-cheat\fR] [\fB\-\-no\-color\fR] [\fB\-\-cheat\-database\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-cheat\-system\fR] [\fB\-\-game\fR] [\fB\-\-allow\-cheat\-conflicts\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-\-solid\-system\fR] [\fB\-\-solid\-game\fR] [\fB\-\-solid\-hack\fR] [\fB\-\-solid\-version\fR] [\fB\-\-solid\-author\fR] [\fB\-\-solid\-contact\fR] [\fB\-\-solid\-comment\fR] [\fB\-\-solid\-extended\fR] [\fB\-\-xdelta\-secondary\fR] [\fB\-\-force\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-\-original\fR>
 .SH DESCRIPTION
 Build a patch from an original ROM and a changed one, so you can share the
 change without sharing the ROM.
@@ -34,7 +34,7 @@ Common alternate spellings are accepted, so `xdelta3` works as well as `xdelta`
 and `bsdiff` as well as `bdf`. The CLI guide lists every alias.
 .TP
 \fB\-o\fR, \fB\-\-output\fR \fI<PATH>\fR
-Where to write the patch. Required unless \-\-plan is used
+Output path; \- writes one completed binary file to stdout
 .TP
 \fB\-\-plan\fR
 Only report which formats suit these two ROMs; write nothing
@@ -56,7 +56,7 @@ Take the original ROM\*(Aqs checksum on trust rather than reading the file, as i
 Build the patch from a Game Genie or GameShark/Pro Action Replay code instead of a second ROM. Repeat for each code; cannot be used with \-\-modified
 .TP
 \fB\-\-code\-system\fR \fI<CODE_SYSTEM>\fR
-Console the \-\-code values are for (nes, snes, genesis, gameboy, gba, psx), when the ROM header does not say
+Console the \-\-code values are for (nes, snes, genesis, 32x, sms, gamegear, sg1000, gameboy, gba, psx), when the ROM header does not say
 .TP
 \fB\-\-code\-kind\fR \fI<CODE_KIND>\fR [default: auto]
 Which cheat scheme the \-\-code values use: auto, game\-genie, gameshark/par, or xploder
@@ -121,19 +121,41 @@ Overwrite the output if it already exists (without this, the command stops inste
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 Print help (see a summary with \*(Aq\-h\*(Aq)
+.SH CHEATS
+.TP
+\fB\-\-cheat\fR \fI<ID_OR_DESCRIPTION>\fR
+Database cheat to use, by record ID or exact description. Repeat for each cheat
+.TP
+\fB\-\-cheat\-database\fR \fI<DIR>\fR
+Directory holding manifest.json and the <system>.json cheat shards. Defaults to $ROM_WEAVER_CHEAT_DATABASE, then the per\-user data directory
+.TP
+\fB\-\-cheat\-system\fR \fI<SYS>\fR
+Console the cheat shard is for (nes, snes, genesis, gameboy, gameboy\-color, gba), when the ROM header does not say
+.TP
+\fB\-\-game\fR \fI<ID>\fR
+Use this database game ID instead of matching the ROM by checksum or title
+.TP
+\fB\-\-allow\-cheat\-conflicts\fR
+Let a later cheat overwrite an earlier one at the same offset instead of failing
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -154,10 +176,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-patch-validate.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-patch\-validate \- Check that patches would apply cleanly, without writing anything
 .SH SYNOPSIS
-\fBrom\-weaver patch validate\fR [\fB\-\-json\fR] [\fB\-\-progress\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-\-filter\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-\-no\-extract\fR] [\fB\-\-no\-ignore\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-patch\-select\fR] [\fB\-\-assume\-in\fR] [\fB\-\-color\fR] [\fB\-\-expect\-in\fR] [\fB\-\-no\-color\fR] [\fB\-\-strip\-header\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-n64\-byte\-order\fR] [\fB\-\-ignore\-checksum\-validation\fR] [\fB\-\-independent\fR] [\fB\-\-plan\fR] [\fB\-\-patch\-basis\fR] [\fB\-\-patch\-input\-check\fR] [\fB\-\-patch\-output\-check\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-i\fR|\fB\-\-input\fR> <\fB\-\-patch\fR>
+\fBrom\-weaver patch validate\fR [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-\-filter\fR] [\fB\-\-jsonl\fR] [\fB\-\-no\-extract\fR] [\fB\-\-progress\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-\-patch\-select\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-assume\-in\fR] [\fB\-\-debug\fR] [\fB\-\-expect\-in\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-strip\-header\fR] [\fB\-\-color\fR] [\fB\-\-n64\-byte\-order\fR] [\fB\-\-ignore\-checksum\-validation\fR] [\fB\-\-no\-color\fR] [\fB\-\-independent\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-\-plan\fR] [\fB\-\-patch\-basis\fR] [\fB\-\-default\-patch\-basis\fR] [\fB\-\-patch\-input\-check\fR] [\fB\-\-patch\-output\-check\fR] [\fB\-j\fR|\fB\-\-threads\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-i\fR|\fB\-\-input\fR> <\fB\-\-patch\fR>
 .SH DESCRIPTION
 Check that patches would apply cleanly to a ROM, without writing anything.
 .PP
@@ -88,7 +88,26 @@ Check every patch against the original ROM rather than as a chain, and report a
 Report the order the patches would run in and what each would be checked against, without reading the ROM more than needed
 .TP
 \fB\-\-patch\-basis\fR \fI<PATCH_BASIS>\fR
-Which ROM the preceding \-\-patch was built against: auto, base, or previous [default: auto]
+Override the preceding \-\-patch input rule: auto, base, or previous
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+auto
+.IP \(bu 2
+base
+.IP \(bu 2
+previous
+.RE
+.TP
+\fB\-\-default\-patch\-basis\fR \fI<DEFAULT_PATCH_BASIS>\fR
+Set one input ROM rule for every patch. An individual \-\-patch\-basis can override it.
+
+  base      Every patch was made from the original ROM.
+  previous  Each later patch was made from the previous result.
+  auto      Infer the input ROM from checksums (the default).
 .br
 
 .br
@@ -119,17 +138,23 @@ Print help (see a summary with \*(Aq\-h\*(Aq)
 Pick which file to use inside the \-\-patch archive before it. Repeatable, one per \-\-patch; falls back to \-\-select
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -150,10 +175,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-patch.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-patch \- Apply, create, or check ROM patches
 .SH SYNOPSIS
-\fBrom\-weaver patch\fR [\fB\-\-json\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+\fBrom\-weaver patch\fR [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-jsonl\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-debug\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
 .SH DESCRIPTION
 Apply, create, or check ROM patches
 .SH OPTIONS
@@ -13,17 +13,23 @@ Apply, create, or check ROM patches
 Print help
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -44,10 +50,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-probe.1

@@ -4,7 +4,7 @@
 .SH NAME
 rom\-weaver\-probe \- Identify a file: its format, its platform, and any header it carries
 .SH SYNOPSIS
-\fBrom\-weaver probe\fR [\fB\-\-json\fR] [\fB\-\-progress\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-\-filter\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-\-no\-extract\fR] [\fB\-\-no\-ignore\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fB\-i\fR|\fB\-\-input\fR>
+\fBrom\-weaver probe\fR [\fB\-i\fR|\fB\-\-input\fR] [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-s\fR|\fB\-\-select\fR] [\fB\-\-filter\fR] [\fB\-\-jsonl\fR] [\fB\-\-no\-extract\fR] [\fB\-\-progress\fR] [\fB\-\-no\-ignore\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-debug\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fIFILE\fR]
 .SH DESCRIPTION
 Identify a file. Reports what format it is, which console it is for, whether it
 carries a copier header, and what is inside it if it is an archive.
@@ -45,19 +45,28 @@ Also consider files normally skipped inside archives: readmes, images, checksum
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+[\fIFILE\fR]
+File input; an alternative to \-i, \-\-input
 .SH "GLOBAL OPTIONS"
 .TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
 \fB\-\-json\fR
-Print one JSON object per line instead of human\-readable output
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
 .TP
 \fB\-\-progress\fR
-Show progress even when output is piped to a file or another program
+Show progress on stderr (off by default; JSONL includes progress)
 .TP
 \fB\-\-no\-progress\fR
 Hide progress
 .TP
 \fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
-How much rom\-weaver logs to stderr. Separate from the normal output [default: off]
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
 .br
 
 .br
@@ -78,10 +87,13 @@ trace
 .RE
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
-Log more: \-v for info, \-vv for debug, \-vvv for trace
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
-Log errors only
+Hide optional diagnostics and progress; keep results, warnings, and errors
 .TP
 \fB\-\-dep\-trace\fR
 Also log trace output from bundled libraries (for bug reports)

package/docs/man/rom-weaver-save-export-schema.1

@@ -0,0 +1,80 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH rom-weaver-save-export-schema 1  "rom-weaver-save-export-schema "
+.SH NAME
+rom\-weaver\-save\-export\-schema \- Print the generic field schema for a supported game save
+.SH SYNOPSIS
+\fBrom\-weaver save export\-schema\fR [\fB\-\-game\fR] [\fB\-n\fR|\fB\-\-dry\-run\fR] [\fB\-\-json\fR] [\fB\-\-rom\-sha1\fR] [\fB\-\-jsonl\fR] [\fB\-\-progress\fR] [\fB\-\-no\-progress\fR] [\fB\-\-log\-level\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-\-debug\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-\-dep\-trace\fR] [\fB\-\-color\fR] [\fB\-\-no\-color\fR] [\fB\-y\fR|\fB\-\-yes\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fISAVE\fR]
+.SH DESCRIPTION
+Print the generic field schema for a supported game save
+.SH OPTIONS
+.TP
+\fB\-\-game\fR \fI<GAME_ID>\fR
+Force a game id instead of detecting one
+.TP
+\fB\-\-rom\-sha1\fR \fI<SHA1>\fR
+SHA\-1 of the matching ROM, used to pick a game
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+[\fISAVE\fR]
+Save file to read. Omit it and pass \-\-game instead
+.SH "GLOBAL OPTIONS"
+.TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
+Plan the command without changing files or downloading data
+.TP
+\fB\-\-json\fR
+Print one complete JSON report; progress and diagnostics use stderr
+.TP
+\fB\-\-jsonl\fR
+Stream JSON events, including progress, one object per line
+.TP
+\fB\-\-progress\fR
+Show progress on stderr (off by default; JSONL includes progress)
+.TP
+\fB\-\-no\-progress\fR
+Hide progress
+.TP
+\fB\-\-log\-level\fR \fI<LOG_LEVEL>\fR
+How much rom\-weaver logs to stderr. Separate from the normal output [default: warn]
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+off
+.IP \(bu 2
+error
+.IP \(bu 2
+warn
+.IP \(bu 2
+info
+.IP \(bu 2
+debug
+.IP \(bu 2
+trace
+.RE
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Show user diagnostics on stderr; repeat for developer detail (\-vv debug, \-vvv trace)
+.TP
+\fB\-\-debug\fR
+Show developer diagnostics and trace events on stderr (same as \-vvv)
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
+Hide optional diagnostics and progress; keep results, warnings, and errors
+.TP
+\fB\-\-dep\-trace\fR
+Also log trace output from bundled libraries (for bug reports)
+.TP
+\fB\-\-color\fR
+Keep colors even when output is piped
+.TP
+\fB\-\-no\-color\fR
+Turn colors off
+.TP
+\fB\-y\fR, \fB\-\-yes\fR
+Answer yes to every confirmation instead of asking. Does not choose between candidates