docs: document the monorepo scan layout trade-off

The mechanics of --sub-path and --workspace-name were documented, but not the
choice they force. One combined scan gives a single dashboard entry and no
per-component attribution; one scan per component gives attribution, baselines
and per-component policy, but adds a repository entry per component, which grows
the dashboard's repository list. There is no layout that provides both today.

Customers hit this at a dozen-plus components and reasonably assume they have
configured something wrong. Naming the trade-off, and adding rules of thumb for
picking a side, is cheaper than each of them discovering it.

Cross-referenced from the CI/CD guide's independent-workspace pattern, which is
the layout that grows the list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: lelia

docs/ci-cd.md

@@ -79,6 +79,12 @@ to start a small selector job on every PR update, then create one scan job per
 affected logical workspace. This also avoids a required check remaining pending
 when GitHub skips the entire workflow because of a top-level path filter.
 
+This pattern produces one dashboard entry per logical workspace, which is what
+gives each component its own alerts, baseline, and policy. It is also the layout
+that grows the dashboard's repository list. See
+[Choosing a scan layout](cli-reference.md#choosing-a-scan-layout) for when that
+trade-off is worth making.
+
 Define a repository variable named `SOCKET_MONOREPO_WORKSPACES_JSON`. Its value is
 an array with one stable workspace name, one or more scan roots, and the path globs
 that should select that workspace. Fill these placeholders with the repository's

docs/cli-reference.md

@@ -70,6 +70,47 @@ Normal scan logs include the effective repository and Socket workspace context,
 repository-relative discovery roots, aggregate manifest count, and selected baseline.
 Individual manifest paths remain opt-in through `--save-submitted-files-list`.
 
+### Choosing a scan layout
+
+`--sub-path` and `--workspace-name` support two layouts, and picking between them
+is a trade-off rather than a preference. There is no third option today.
+
+**One combined scan** — a single invocation, no `--workspace-name`, with
+`--target-path` at the repository root or several repeated `--sub-path` values
+sharing one workspace name:
+
+- One dashboard entry for the repository, named after the repository
+- One server-side dependency graph covering everything that was uploaded
+- Alerts are **not** broken out by component, so a finding does not tell you which
+  part of the monorepo introduced it
+- Transitive findings can surface without a clear owning component, because the
+  combined graph has no component boundaries to attribute them to
+
+**One scan per component** — a separate invocation per component, each with its
+own `--sub-path` and a distinct `--workspace-name`:
+
+- Per-component alerts, baselines, and policy
+- Each component gets its own dependency graph, which is also the faster option
+  (see the performance note above)
+- But `--workspace-name` suffixes the repository slug, so *N* components produce
+  *N* separate entries in the dashboard's repository list
+
+The second point is what makes this a real choice: a monorepo with a dozen or more
+independently scanned components produces a dozen or more repository entries, which
+gets hard to navigate as the list grows. A single consolidated entry that still
+preserves per-component attribution is a known request and is not available today.
+
+Rules of thumb:
+
+- **Few components, or components that share a release cycle** — use one combined
+  scan and accept coarser attribution.
+- **Many components, or components with different owners or policies** — use
+  per-component scans and accept the extra dashboard entries. Per-component policy
+  is only possible in this layout.
+- **Components that are genuinely one application** — group them under a single
+  `--workspace-name`, as in the first example below. Grouping is per logical
+  application, not per directory.
+
 ### Usage Examples
 
 **Scan several directories that belong to one logical application:**