docs: explain syncProcessCwd async contexts

[KirtiRamchandani]

Problem

Issue #876 notes that the current docs mention cd() and syncProcessCwd(), but do not explain the async-context mismatch that can happen when cd() changes the global process directory while within() restores only zx's internal $ context.

Root cause

The syncProcessCwd() section only states what the hook does. It does not show how process.cwd() can drift from $ in separate callbacks, or when users should prefer $.cwd instead.

Solution

Add examples showing the mismatch without the hook and the restored behavior with syncProcessCwd() enabled, plus guidance to use $.cwd for zx-only directory changes.

Tests run

• npm exec --yes prettier -- --check docs/api.md
• git diff --check

Fixes #876

[antonmedv]

@antongolub looks right and explanatory to me. ptal

[KirtiRamchandani]

I checked the failing jobs on this PR. The diff only touches docs/api.md, and the failures look unrelated to this docs change:

• checks fails in
  pm run test:audit on GHSA-jxxr-4gwj-5jf2 via zx@8.9.0 -> c8@11.0.0 -> test-exclude@8.0.0 -> minimatch@10.2.4 -> brace-expansion@5.0.5.
• smoke-windows-2022-node16 fails in est/smoke/win32.test.js on ps detects self process / kill works; the same smoke job on Windows 2025 passed.

I do not see a docs-side change to make for this PR. Happy to rebase or rerun if you prefer that path.

[KirtiRamchandani]

Thanks @antonmedv — appreciate the review.

The change clarifies that $/syncProcessCwd() behavior differs between top-level scripts and dynamically imported modules, with a short example showing why cd() inside an imported file does not mutate the parent process cwd unless explicitly synced.

Ready for merge when you are.