docs: add TROUBLESHOOTING.md troubleshooting manual

[Rish-2006]

Description

Introduces a comprehensive troubleshooting guide for common local environment setup, viewport scaling, and permission constraints to streamline onboarding.

Related Issue

Closes #3240

Which package(s)?

docs

Summary by CodeRabbit

• Documentation
  • Added a troubleshooting guide for common local setup issues.
  • Included steps for resolving dependency version mismatches, terminal sizing problems, and script execution permissions.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds TROUBLESHOOTING.md with guidance for resolving Node module mismatches, terminal sizing issues, and missing script execution permissions.

Changes

TermUI troubleshooting

Layer / File(s)	Summary
Troubleshooting guidance TROUBLESHOOTING.md	Adds npm reinstall steps, minimum terminal dimensions, and commands for restoring local script execution permissions.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: karanjot786

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the new troubleshooting docs.
Description check	✅ Passed	The description includes the required summary, linked issue, and package, with no major template gaps.
Linked Issues check	✅ Passed	The changes match #3240 by adding a structured troubleshooting guide for common setup and build problems.
Out of Scope Changes check	✅ Passed	The PR stays focused on docs for troubleshooting and adds no obvious unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@TROUBLESHOOTING.md`:
- Around line 7-10: Update the clean reinstall command in the Resolution section
of TROUBLESHOOTING.md to remove only node_modules and use npm ci, preserving
package-lock.json. Do not regenerate the lockfile unless explicitly addressing a
stale or invalid lockfile.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c3c3e0b-39a7-42e8-bc4f-7fcfa0671830

📥 Commits

Reviewing files that changed from the base of the PR and between 48f63a1 and 992d430.

📒 Files selected for processing (1)

• TROUBLESHOOTING.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== files =="
git ls-files | sed -n '1,120p'
echo "== TROUBLESHOOTING =="
if [ -f TROUBLESHOOTING.md ]; then
  nl -ba TROUBLESHOOTING.md | sed -n '1,80p'
fi

echo "== package manager files =="
for f in package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock; do
  echo "--- $f"
  [ -f "$f" ] && wc -l "$f"
done

echo "== lockfile/package scripts relevant =="
if [ -f package.json ]; then
  python3 - <<'PY'
import json
with open('package.json') as f: data=json.load(f)
print(json.dumps({"name": data.get("name"), "scripts": data.get("scripts"), "dependencies": data.get("dependencies"), "devDependencies": data.get("devDependencies")}, indent=2, sort_keys=True))
PY
fi

Repository: Karanjot786/TermUI

Length of output: 5756

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== TROUBLESHOOTING lines 1-30 =="
awk '{printf "%6d\t%s\n",NR,$0} NR<=30' TROUBLESHOOTING.md 2>/dev/null || cat -n TROUBLESHOOTING.md 2>/dev/null | sed -n '1,30p'

echo "== lockfile/package scripts relevant =="
for f in package-lock.json npm-shrinkwrap.json pnpm-lock.yaml yarn.lock package.json; do
  echo "--- $f"
  [ -f "$f" ] && wc -l "$f"
done

if [ -f package.json ]; then
  python3 - <<'PY'
import json
with open('package.json') as f: data=json.load(f)
print(json.dumps({"name": data.get("name"), "scripts": data.get("scripts"), "dependencies": data.get("dependencies"), "devDependencies": data.get("devDependencies")}, indent=2, sort_keys=True))
PY
fi

Repository: Karanjot786/TermUI

Length of output: 3012

---

Preserve the lockfile during a clean reinstall.

Removing package-lock.json makes npm install resolve a new dependency tree, which can hide the original mismatch and leave local builds unreproducible. Prefer rm -rf node_modules && npm ci; only regenerate the lockfile intentionally when it is stale or invalid.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@TROUBLESHOOTING.md` around lines 7 - 10, Update the clean reinstall command
in the Resolution section of TROUBLESHOOTING.md to remove only node_modules and
use npm ci, preserving package-lock.json. Do not regenerate the lockfile unless
explicitly addressing a stale or invalid lockfile.

Source: MCP tools