docs: sync clice

en/clice/cli/analyze.md

@@ -4,32 +4,32 @@
 
 `clice analyze` reads the persisted index and reports facts a coding agent turns into refactoring decisions. It never builds or times anything: it describes the code, and the agent — with the code at hand — decides what to change. Like `clice query`, it reads the index `clice index` builds and prints JSON on stdout.
 
-**Usage**: `clice analyze <analysis> [--workspace <dir>] [--configuration <tag>] [options]`
+**Usage**: `clice analyze <analysis> [<view> [<target>...]] [--workspace <dir>] [--configuration <tag>] [options]`
 
 ## Modules
 
 `clice analyze modules` describes how the directories of a program depend on each other, as the input for partitioning it into C++20 named modules: which cycles stand in the way, which few entities each cycle hangs on, which headers belong elsewhere, and which constructs a mechanical rewrite into modules cannot carry over.
 
 Every file in the scope belongs to a module, by default its directory. A module depends on another when one of its files names an entity a file of the other provides: a spelled name, a name a macro expansion produces in that file, or the template an explicit specialization specializes. The file providing an entity is a header defining it, else a header declaring it, else the source defining it. A dependency from a header is an interface edge, which would become an import of the module's interface; one only from sources is an implementation edge, which never closes a cycle because an implementation unit may import a module above it. Textual fragments such as `.inc` and `.def` files count as part of the files including them. A header only its own module's sources use, directly or through other such headers, is an internal partition: it adds nothing to the module's interface, and none of its dependencies are interface edges.
 
-- `--scope <glob,...>` analyzes only the files the globs match, as workspace-relative paths; by default every indexed file under the workspace outside a dot directory.
-- `--depth <n>` names a file's default module by the first `n` segments of its directory instead of all of them.
+- `--scope <glob>` analyzes only the files the glob matches, as a workspace-relative path; repeat it for several. By default every indexed file under the workspace outside a dot directory.
+- `--dir-depth <n>` names a file's default module by the first `n` segments of its directory instead of all of them.
 - `--partition <file>` assigns modules by globs, first match wins: `{"modules": [{"name": "core", "files": ["src/support/**", "src/vfs/**"]}]}`. Files no glob claims keep their directory module. For the `interface` view and [modularize](./modularize.md), `"textual": true` keeps a module headers, `"external": true` marks one an existing module stands for (the standard library), and `"provides": "std.compat"` names the module exporting a module's names, read from the libc++ module sources `--std <dir>` names.
-- `--move <path>=<module>,...` and `--merge <module>+<module>[+...],...` evaluate a hypothetical change without making it.
+- `--move <path>=<module>` and `--merge <module>+<module>[+...]` evaluate a hypothetical change without making it; repeat them for several.
 - `--move-entity <locator>=<header>` evaluates moving a declaration, with its members and what their definitions name, to another header, existing or new; repeat it for several moves. The [locator](./query.md#locators) names the declaration by its whole name: a function's overloads in one scope move together, the locator the `edge` view prints picks one of them, and a name several scopes spell is an error listing the candidates.
-- `--annotation <file>,...` and `--churn-since <date>` weigh the results; see [annotations](#annotations).
-- `--view <view>` chooses the answer, `overview` by default.
-
-| View                                 | Answers                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `overview`                           | the modules by layer, the edges with sample entities, the cycles with the lightest set of edges whose removal breaks each, header cycles inside a module, the number of internal partitions, the deepest import chain, rebuild totals, hotspots, move and split candidates, and obstacle counts                                                                                                |
-| `edge --from <module> --to <module>` | every entity the edge carries, with its locator, owner and the `file:line` of each use                                                                                                                                                                                                                                                                                                         |
-| `module --module <module>`           | each file's dependencies and dependents by module, the module's internal partitions, and its other headers grouped by the modules using them — the lines a directory splits along                                                                                                                                                                                                              |
-| `file --file <path>`                 | what the file names by module, who names its entities, and its annotations                                                                                                                                                                                                                                                                                                                     |
-| `obstacles`                          | every construct listed below                                                                                                                                                                                                                                                                                                                                                                   |
-| `macros`                             | macros used outside the file defining them, by module: imports carry no macros, so each reaches its users through a textual header                                                                                                                                                                                                                                                             |
-| `impact`                             | per header, the units an edit to it rebuilds today and under the partition, and whether it is an internal partition                                                                                                                                                                                                                                                                            |
-| `interface [--module <module>]`      | per module, what a wrapper module over its headers needs: the modules it imports, its entries with the name other modules include them by, its namespace-scope names with their headers, its namespace aliases, the headers that stay textual, the TU-local entities its headers share with other wrapped modules, the macros importers need, and the macros of other modules its headers read |
+- `--annotation <file>` and `--churn-since <date>` weigh the results of the views that rank by them; see [annotations](#annotations).
+- The view, a word after `modules`, chooses the answer, the overview when there is none.
+
+| View                   | Answers                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (no view)              | the modules by layer, the edges with sample entities, the cycles with the lightest set of edges whose removal breaks each, header cycles inside a module, the number of internal partitions, the deepest import chain, rebuild totals, hotspots, move and split candidates, and obstacle counts                                                                                                |
+| `edge <from> <to>`     | every entity the edge carries, with its locator, owner and the `file:line` of each use                                                                                                                                                                                                                                                                                                         |
+| `module <module>`      | each file's dependencies and dependents by module, the module's internal partitions, and its other headers grouped by the modules using them — the lines a directory splits along                                                                                                                                                                                                              |
+| `file <path>`          | what the file names by module, who names its entities, and its annotations                                                                                                                                                                                                                                                                                                                     |
+| `obstacles`            | every construct listed below                                                                                                                                                                                                                                                                                                                                                                   |
+| `macros`               | macros used outside the file defining them, by module: imports carry no macros, so each reaches its users through a textual header                                                                                                                                                                                                                                                             |
+| `impact`               | per header, the units an edit to it rebuilds today and under the partition, and whether it is an internal partition                                                                                                                                                                                                                                                                            |
+| `interface [<module>]` | per module, what a wrapper module over its headers needs: the modules it imports, its entries with the name other modules include them by, its namespace-scope names with their headers, its namespace aliases, the headers that stay textual, the TU-local entities its headers share with other wrapped modules, the macros importers need, and the macros of other modules its headers read |
 
 The overview's hotspots, move candidates and split candidates are capped by `--limit` (20 by default); modules, edges and cycles are always complete.
 

en/clice/cli/format.md

@@ -8,7 +8,7 @@ into clice, as the editor does, several files at a time, with the
 settings of its own: the style comes from clang-format's own discovery, the
 nearest `.clang-format` above each file.
 
-**Usage**: `clice format [--workspace <dir>] [--configuration <tag>] [--check] [--jobs <n>] [<path>...]`
+**Usage**: `clice format [<path>...] [--workspace <dir>] [--configuration <tag>] [--check] [--jobs <n>]`
 
 Without paths it formats the build's own files: every translation unit of the
 compilation database and every file with a C-family suffix they include that

en/clice/cli/index.md

@@ -4,20 +4,20 @@
 
 `clice index` builds the persistent symbol index of a workspace ahead of time, so an editor session starts warm instead of indexing in the background while you work. It runs the same indexing pipeline as the server with a worker pool, and the two share one index per build configuration under `cache_dir`.
 
-**Usage**: `clice index [--workspace <dir>] [--configuration <tag>] [--workers <n>]`
+**Usage**: `clice index [--workspace <dir>] [--configuration <tag>] [--jobs <n>]`
 
 One process writes the index of a workspace at a time. While an editor session has the workspace open, its server holds that role, so `clice index` asks the server to run the sweep and waits for the result instead of starting a worker pool of its own; the summary says so. A lock held by a process that cannot be asked (another `clice index`, a server of a different clice build, or one whose configuration keeps background indexing off) makes the command fail with the holder named — rerun it when that process is done.
 
 The run is resumable: interrupting it with Ctrl-C or SIGTERM (what `timeout` and CI job limits send) saves the progress made so far, and the next invocation continues where it left off; only a second Ctrl-C quits at once without saving. Progress is also saved every five minutes, so a crash loses at most that much work. While it runs, a progress line goes to stderr every ten seconds whatever the log level; the final summary on stdout counts the indexed units, the file shards and symbols produced, lists every unit that failed to index, and names the session log directory. The exit code is 0 for a complete index, 1 when some units failed or part of the index could not be persisted, 2 when the arguments do not parse, and 130 when interrupted.
 
 ## Inspecting the index
 
-The same command reads the persisted index without touching it. Every mode prints plain lines meant for a terminal or `grep`, and works while an editor session holds the index open.
+The same command's operations read the persisted index without touching it. Each prints plain lines meant for a terminal or `grep`, and works while an editor session holds the index open.
 
-- `clice index --stats [--top <n>]` prints what the index contains: the translation units and file shards, the byte split of the shard columns and of the global symbol table, how symbols distribute by reference-file count and name length, how file shards distribute by variant count, and the largest shards. `--variants` appends one tab-separated line per file shard with its variant count, for comparing two runs.
-- `clice index --show-symbol <name>` prints what the index records about a symbol: its kind, name and flags, the parent chain that spells its qualified name, the file holding its canonical declaration, and per file how many definitions, declarations and references it has. The name is matched as displayed (`Box<int>`) or qualified (`ns::Box<int>`); `#<hash>` names a symbol by its identity, which is how file-local symbols are reached.
-- `clice index --show-file <path>` prints a file's persisted rows: the content generation the rows were built from, every variant with the translation units that contributed it, the row counts by relation kind, and the file-local symbols whose identities live only in this file.
-- `clice index --show-tu <path>` prints a translation unit's manifest: when it was indexed, the files it contributed rows to, and its include tree.
+- `clice index stats [--limit <n>]` prints what the index contains: the translation units and file shards, the byte split of the shard columns and of the global symbol table, how symbols distribute by reference-file count and name length, how file shards distribute by variant count, and the largest shards. `--variants` appends one tab-separated line per file shard with its variant count, for comparing two runs.
+- `clice index symbol <locator>` prints what the index records about the symbols a [locator](./query.md#locators) names: their kind, name and flags, the parent chain that spells the qualified name, the file holding the canonical declaration, and per file how many definitions, declarations and references each has. A name names every symbol spelling it whole (`Box<int>`, `ns::Box<int>`) that `clice query` finds; an id names its symbol even when no file declares it, as with a macro defined on the command line.
+- `clice index file <path>` prints a file's persisted rows: the content generation the rows were built from, every variant with the translation units that contributed it, the row counts by relation kind, and the file-local symbols whose identities live only in this file.
+- `clice index unit <path>` prints a translation unit's manifest: when it was indexed, the files it contributed rows to, and its include tree.
 
 ## Examples
 

en/clice/cli/lint.md

@@ -6,7 +6,7 @@ clice integrates clang-tidy as a built-in linting engine. `clice lint` runs
 the checks of your `.clang-tidy` over the workspace's translation units with a
 resident worker pool and prints one merged report.
 
-**Usage**: `clice lint [--workspace <dir>] [--configuration <tag>] [--workers <n>] [--index]`
+**Usage**: `clice lint [--workspace <dir>] [--configuration <tag>] [--jobs <n>] [--index]`
 
 Runs clang-tidy over every translation unit of the compilation database that
 the lint set below admits, prints the merged findings, and exits non-zero when