docs(cso): explain the capacity refusals and file the follow-ups

docs/troubleshooting.md#cso-capacity covers the snapshot-list cap, the 64 MiB
source cap and the tracked-symlink refusal. TODOS.md records the symlink
design call, the #2993 aggregate cap, the full-manifest inspect output and
repair-bundle transformations.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

TODOS.md

@@ -2,6 +2,31 @@
 
 ## NEXT PRIORITY
 
+### P1/P2: /cso capacity follow-ups (filed 2026-10-08)
+
+Left open by v1.91.37.0, which lifted the snapshot file-count ceiling.
+
+- **Tracked symlinks refuse the whole /cso run** — `capture()` fails closed on
+  any tracked symlink ("Symlink or special source file"). 5 of 8 mid-size OSS
+  repos measured for v1.91.37.0 stop there (django, rails, terraform, grafana,
+  vscode; 1-10 symlinks each, mostly test fixtures). Recording them as unread
+  exclusions in the manifest, like dependency trees, is a security design call
+  for Garry. **Effort:** M. **Priority:** P1.
+- **64 MiB aggregate source cap (#2993)** — files over 1 MiB are withheld from
+  the audit but still read and counted. Stream-hash them without counting
+  toward the cap, report them as unread coverage, and add an admission estimate
+  to `doctor`. grafana (211 MiB) and vscode (540 MiB) hit it once symlinks are
+  out of the way. A `GSTACK_CSO_SNAPSHOT_MAX_BYTES` knob was deferred with it.
+  **Effort:** L. **Priority:** P2.
+- **`inspect` prints the whole public manifest** — about 2.8 MB of stdout for
+  5,000 files, more than an agent's tool output keeps. The skill reads paths
+  from it, so trimming it is a skill-contract change with evals.
+  **Effort:** M. **Priority:** P2.
+- **Repair bundles carry every transformation** — `lib/cso/verification.ts`
+  binds the full transformation list into a 1 MiB immutable bundle. Only
+  runtime verification writes bundles, and no qualified runtime catalog exists
+  yet. **Effort:** M. **Priority:** P3.
+
 ### P2/P3: Oct 7 fix-wave follow-ups (filed 2026-10-07)
 
 Left open by the Oct 7 wave (docs/designs/FOLLOWUP_WAVE_2026_10_07.md), each with its reason.

docs/troubleshooting.md

@@ -674,6 +674,24 @@ Linux) with a local Docker socket. On Windows, static assessment is the
 supported mode; if the refusal named a user directory, install Docker Desktop
 under Program Files.
 
+<a id="cso-capacity"></a>
+### `Snapshot manifest cap exceeded: ...` / `64 MiB source cap exceeded: ...` / `Symlink or special source file: <path>`
+
+**Meaning.** /cso copies the repository into a private snapshot before any
+audit starts, and refuses the whole run when the snapshot would be incomplete
+or too large. Each message names the cap that applied:
+
+- **Snapshot manifest cap (16 MiB).** One entry per tracked or nonignored
+  untracked file; about 50,000 files fit.
+- **64 MiB source cap.** The full size of every such file outside dependency
+  and VCS directories counts, including files over 1 MiB whose contents are
+  withheld from the audit.
+- **Symlinks.** A tracked symlink anywhere in the repository stops the run.
+
+**Fix.** No setting raises these caps. Run /cso on a smaller checkout that
+holds the code you want audited and no symlinks. Add your file count or size to
+[#2993](https://github.com/garrytan/gstack/issues/2993).
+
 <a id="conductor-auq-hook-removed"></a>
 ### `removed the AskUserQuestion preference hook: it breaks Conductor's native AskUserQuestion (#2207). ...`