Add the docs-site troubleshooting page

[wallstop]

The site documented the happy paths; the behaviors that look like bugs but are designed lived only in issues and progress notes. The T11 roadmap item asked for a troubleshooting page. Refs #114.

Behavior

• docs/troubleshooting.md: async loading and the Loading In Progress refusal, Building search index…, busy-database refresh deferral and postprocessor auto-refresh, missing-script and exact-type listing rules, idle-time selection normalization, the 860x480 and per-pane minimums with preferred-vs-clamped sizes, user-state and settings-asset recovery, and capture regeneration (CLI, output-dir argument/env var, project-root path resolution, meta-free staging, the macOS 6000.4 render-gap limit, container workflow). Every claim traced to main.
• mkdocs.yml nav gains Troubleshooting after Extending; the index links it under Where to go next.

Validation

• mkdocs build --strict green; site/troubleshooting/ published with all ten sections, the five PNGs present, zero .meta files; cross-page links resolve.
• npm run lint:llm green; npm pack payload unchanged (172 files, no docs/ paths). Docs-only change: Unity suites not exercised (precedent Add the documentation site foundation (T11) #130, Document search, filtering, asset operations, and extension points #134, Publish the capture-pipeline imagery on the docs site #144).

Risk / Rollback

• Docs-only: risk is stale guidance; capture-limits wording leans on the chore: Documentation OverHaul + Auto-Captured Images/webp #114 record. Revert the single commit to remove the page and nav entry.

---

Note

Low Risk
Documentation-only; no runtime or package code changes. Risk is outdated or incorrect user guidance, including capture-limit wording tied to #114.

Overview
Adds a Troubleshooting page to the MkDocs site (docs/troubleshooting.md) so “looks broken but is by design” behavior is documented in one place instead of issues/notes. Sections cover gradual async object loading and processor refusal while loading, first-search index build, deferred refresh when the AssetDatabase is busy or Play Mode is active, exact-type and missing-script listing rules, post-recompile selection cleanup, window/pane minimum sizes, corrupt or empty persistence recovery, and how to regenerate docs/images/ via DocsImageCapture (CLI, env var, staging paths, validation, and the macOS 6000.4 capture gap tied to #114), plus a short container/host edit workflow note.

Navigation: mkdocs.yml and Where to go next in docs/index.md link the new page. The diff currently registers Troubleshooting twice in both places (two nav items and two index bullets with slightly different blurbs)—likely an accidental duplicate worth collapsing to a single entry. A Unity .meta companion for the markdown file is also added.

^{Reviewed by Cursor Bugbot for commit 3be6036. Bugbot is set up for automated code reviews on this repo. Configure here.}