diff --git a/hledger/Hledger/Cli/Commands/Close.md b/hledger/Hledger/Cli/Commands/Close.md
index 311fbe2ab..4be0c4e11 100644
--- a/hledger/Hledger/Cli/Commands/Close.md
+++ b/hledger/Hledger/Cli/Commands/Close.md
@@ -2,90 +2,104 @@
 
 (equity)
 
-A transaction-generating command which generates several kinds of "closing"
-and/or "opening" transactions useful in certain situations.
-It prints one or two transactions to stdout, but does not write them to the journal file;
-you can append or copy them there when you are happy with the output.
+`close` generates several kinds of "closing" and/or "opening" transactions, useful in certain situations, including
+migrating balances to a new journal file, retaining earnings into equity, consolidating balances, or viewing lots.
+Like `print`, it prints valid journal entries.
+You can append or copy these to your journal file(s) when you are happy with how they look.
 
 _FLAGS
 
 <!-- related:  -->
 
-This command is most often used when migrating balances to a new journal file, at the start of a new financial year. 
-It can also be used to "retain earnings" (transfer revenues and expenses to equity),
-or as a sort of generic mover of balances from any group of accounts to some other account.
-So it currently has six modes, selected by a mode flag. Use only one of these flags at a time:
+`close` currently has six modes, selected by a single mode flag:
 
-1. With `--close` (or no mode flag) it prints a "closing balances" transaction
-that zeroes out all the asset and liability account balances, by default
-(this requires [account types](hledger.md#account-types) to be detected or declared.).
-All of the balances are transferred to a special "opening/closing balances" equity account.
-Or, if it will zero out the accounts matched by query arguments you provide.
-Eg you could include assets, liabilities, and equity with `hledger close type:ALE`.
-The "opening/closing balances" equity account is always excluded.
+### `close --migrate`
 
-2. With `--open`, it prints an opposite "opening balances" transaction that
-restores the same account balances, starting from zero.
-<!-- This mode is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command). -->
+This is the most common mode.
+It prints a "closing balances" transaction that zeroes out all asset and liability balances (by default),
+and an opposite "opening balances" transaction that restores them again.
+The balancing account will be `equity:opening/closing balances` (or another specified by `--close-acct` and/or `--open-acct`).
 
-3. With `--migrate`, it prints both the closing and opening transactions above.
-This is a common way to migrate balances to a new file at year end;
-run `hledger close --migrate -e NEWYEAR` (-e influences the transaction date)
-and add the closing transaction at the end of the old file,
-and the opening transaction at the start of the new file.
-Doing this means you can include past year files in your reports at any time
-without disturbing asset/liability/equity balances,
-because the closing balances transaction cancels out the following opening balances transaction.
-You will sometimes need to exclude these transactions from reports, eg to see an end of year balance sheet;
-a `not:opening/closing` query argument should do.
-You should probably also use this query when `close`-ing, to exclude the "opening/closing balances" account
-which might otherwise [cause problems](https://www.reddit.com/r/plaintextaccounting/comments/18zxlbn/hledger_year_closing/).
-Or you can just migrate assets and liabilities: `hledger close type:AL`.
-Most people don't need to migrate equity.
-And revenues and expenses usually should not be migrated.
+This is useful when migrating balances to a new journal file at the start of a new year.
+Essentially, you run `hledger close --migrate -e NEWYEAR`
+and then copy the closing transaction to the end of the old file
+and the opening transaction to the start of the new file.
+The opening transaction sets correct starting balances in the new file when it is used alone,
+and the closing transaction keeps balances correct when you use both old and new files together,
+by cancelling out the following opening transaction and preventing buildup of duplicated opening balances.
+Think of the closing/opening pair as "moving the balances into the next file".
 
-4. With `--assert` it prints a "closing balances" transaction that
-just asserts the current balances, without changing them.
-This can be useful as documention and to guard against errors and changes.
+You can close a different set of accounts by providing a query.
+Most people don't need to migrate equity (?)
+but you can include it by adding a `type:ALE` argument (except `equity:opening/closing balances`, which is always excluded).
+Revenues and expenses usually are not migrated to a new file directly; see `--retain` below.
 
-5. With `--assign` it prints an "opening balances" transaction that
+### `close --close`
+
+This prints just the closing balances transaction of `--migrate`.
+It is the default behaviour if you specify no mode flag.
+Using the customisation options below, you can move balances from any set of accounts to a different account.
+
+### `close --open`
+
+This prints just the opening balances transaction of `--migrate`.
+It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command).
+
+### `close --assert`
+
+This prints a "closing balances" transaction that just declares [balance assertions](#balance-assertions)
+for the current balances without changing them.
+It could be useful as documention and to guard against changes.
+
+### `close --assign`
+
+This prints an "opening balances" transaction that
 restores the account balances using [balance assignments](#balance-assignments).
 Balance assignments work regardless of any previous balance, so a preceding closing balances transaction is not needed.
-This is an alternative to `--close` and `--open`: at year end,
-`hledger close --assert -e NEWYEAR` in the old file (optional, but useful for error checking),
-and `hledger close --assign -e NEWYEAR` in the new file.
-This might be more convenient, eg if you are often doing cleanups or fixes which would break closing/opening transactions.
 
-6. With `--retain`, it prints a "retain earnings" transaction that transfers
-revenue and expense balances to `equity:retained earnings`.
-This is a traditional end-of-period bookkeeping operation also called "closing the books";
-in personal accounting you probably will not need this but it could be useful
-if you want to see the accounting equation (A=L+E) balanced.
+However, omitting the closing balances transaction would unbalance equity.
+This is relatively harmless for personal reports, but it disturbs the accounting equation, removing a source of error detection.
+So `--migrate` is generally the best way to set to set balances in new files, [for now](https://github.com/simonmichael/hledger/issues/2151).
+
+### `close --retain`
+
+This is like `--close` with different defaults:
+it prints a "retain earnings" transaction that transfers revenue and expense balances to `equity:retained earnings`.
+
+This is a different kind of closing, called "retaining earnings" or "closing the books";
+it is traditionally performed by businesses at the end of each accounting period,
+to consolidate revenues and expenses into the main equity balance.
+("Revenues" and "expenses" are actually equity by another name, kept separate temporarily for reporting purposes.)
+
+In personal accounting you generally don't need to do this,
+unless you want the `balancesheetequity` report to show a zero total, demonstrating that the accounting equation (A-L=E) is satisfied.
+
+### `close` customisation
 
 In all modes, the following things can be overridden:
 
-- the transaction descriptions can be changed with `--close-desc=DESC` and `--open-desc=DESC`
-- the account to transfer to and from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT`
-- the accounts to be closed/opened can be changed with `ACCTQUERY` (account query arguments).
-- the closing/opening dates can be changed with `-e DATE` (a report end date)
+- the accounts to be closed/opened, with account query arguments
+- the balancing account, with `--close-acct=ACCT` and/or `--open-acct=ACCT`
+- the transaction descriptions, with `--close-desc=DESC` and `--open-desc=DESC`
+- the closing/opening dates, with `-e OPENDATE`
 
-By default just one destination/source posting will be used, with its amount left implicit.
-With `--x/--explicit`, the amount will be shown explicitly,
+By default, the closing date is yesterday, or the journal's end date, whichever is later;
+and the opening date is always one day after the closing date.
+You can change these by specifying a [report end date](#report-start--end-date);
+the closing date will be the last day of the report period.
+Eg `-e 2024` means "close on 2023-12-31, open on 2024-01-01".
+
+With `--x/--explicit`, the balancing amount will be shown explicitly,
 and if it involves multiple commodities, a separate posting will be generated for each of them
 (similar to `print -x`).
 
-With `--show-costs`, any amount costs are shown, with separate postings for each cost.
-This is currently the best way to view investment lots.
-If you have many currency conversion or investment transactions, it can generate very large journal entries.
+With `--interleaved`, each individual transfer is shown with source and destination postings next to each other
+(perhaps useful for troubleshooting).
 
-With `--interleaved`, each individual transfer is shown with source
-and destination postings next to each other.
-This could be useful for troubleshooting.
-
-The default closing date is yesterday, or the journal's end date, whichever is later.
-You can change this by specifying a [report end date](#report-start--end-date) with `-e`.
-The last day of the report period will be the closing date, eg `-e 2024` means "close on 2023-12-31".
-The opening date is always the day after the closing date.
+With `--show-costs`, balances' costs are also shown, with different costs kept separate.
+This may generate very large journal entries, if you have many currency conversions or investment transactions.
+`close --show-costs` is currently the best way to view investment lots with hledger.
+(To move or dispose of lots, see the more capable [`hledger-move`](scripts.md#hledger-move) script.)
 
 ### close and balance assertions
 
@@ -122,7 +136,9 @@ in effect splitting the multi-day transaction into two single-day transactions:
     assets:bank:checking  -5
 ```
 
-### Example: retain earnings
+### close examples
+
+#### Retain earnings
 
 <!-- XXX update -->
 
@@ -133,16 +149,16 @@ appending the generated transaction to the journal:
 $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
 ```
 
-Note 2022's income statement will now show only zeroes,
+2022's income statement will now show only zeroes,
 because revenues and expenses have been moved entirely to equity.
-To see them again, you could exclude the retain transaction:
+To see their end balances, you could exclude the retain transaction:
 ```cli
 $ hledger -f 2022.journal is not:desc:'retain earnings'
 ```
 
-### Example: migrate balances to a new file
+#### Migrate balances to a new file
 
-Close assets/liabilities/equity on 2022-12-31 and re-open them on 2023-01-01:
+Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
 
 ```cli
 $ hledger close --migrate -f 2022.journal -p 2022
@@ -159,63 +175,51 @@ $ hledger close --open  -f 2022.journal -p 2022 >> 2022.journal
 ```
 -->
 
-Now 2022's balance sheet will show only zeroes, indicating a balanced accounting equation.
+2022's balance sheet will now show only zeroes, indicating a balanced accounting equation.
 ([Unless](/investments.html#a-more-correct-entry) you are using @/@@ notation - in that case, try adding --infer-equity.)
-To see the end-of-year balances again, you could exclude the closing transaction:
+(Do we need to close equity also ? retest)
+To see the end-of-year balances, you could exclude the closing transaction:
 ```cli
 $ hledger -f 2022.journal bs not:desc:'closing balances'
 ```
 
-### Example: excluding closing/opening transactions
+#### Exclude opening/closing transactions
 
-When combining many files for multi-year reports, 
-the closing/opening transactions cause some noise in transaction-oriented reports like `print` and `register`.
-You can exclude them as shown above, but `not:desc:...` is not ideal
-as it depends on consistent descriptions; also you will want to avoid excluding
-the very first opening transaction, which could be awkward. 
-Here is one alternative, using tags:
-
-Add `clopen:` tags to all opening/closing balances transactions except the first,
-like this:
+When combining files for multi-year reports, for some reports (eg a yearly balance sheet)
+you may need to suppress all opening/closing transactions except the first.
+This is a bit awkward if you also want to be able to choose any range of year files,
+but here is a way, using tags:
 
 ```journal
 ; 2021.journal
-2021-06-01 first opening balances
+2021-06-01 opening balances  ; start:2021
 ...
-2021-12-31 closing balances  ; clopen:2022
+2021-12-31 closing balances  ; start:2022
 ...
 ```
 
 ```journal
 ; 2022.journal
-2022-01-01 opening balances  ; clopen:2022
+2022-01-01 opening balances  ; start:2022
 ...
-2022-12-31 closing balances  ; clopen:2023
+2022-12-31 closing balances  ; start:2023
 ...
 ```
+
 ```journal
 ; 2023.journal
-2023-01-01 opening balances  ; clopen:2023
+2023-01-01 opening balances  ; start:2023
 ...
 ```
 
-Now, assuming a combined journal like:
+All of these will show the year-end balances correctly:
 
-```journal
-; all.journal
-include 2021.journal
-include 2022.journal
-include 2023.journal
-```
-
-The `clopen:` tag can exclude all but the first opening transaction.
-To show a clean multi-year checking register:
 ```cli
-$ hledger -f all.journal areg checking not:tag:clopen
+$ hledger bs -Y -f 2021.journal -f 2022.journal -f 2023.journal expr:'tag:start=2021 or not tag:start'
+$ hledger bs -Y -f 2021.journal -f 2022.journal                 expr:'tag:start=2021 or not tag:start'
+$ hledger bs -Y -f 2022.journal -f 2023.journal                 expr:'tag:start=2022 or not tag:start'
+$ hledger bs -Y -f 2021.journal                                 expr:'tag:start=2021 or not tag:start'
+$ hledger bs -Y -f 2022.journal                                 expr:'tag:start=2022 or not tag:start'
+$ hledger bs -Y -f 2023.journal                                 # unclosed file, no query needed
 ```
 
-And the year values allow more precision.
-To show 2022's year-end balance sheet:
-```cli
-$ hledger -f all.journal bs -e2023 not:tag:clopen=2023
-```