Document Ghost error field usage

[ErisDS]

Summary

• Document how to use GhostError fields for human-readable context, machine-readable codes, and structured metadata.
• Add JSDoc comments to GhostErrorOptions so generated types make the field semantics clearer.

Testing

• pnpm --filter @tryghost/errors test
• pnpm exec oxfmt -c .oxfmtrc.json --check \"packages/errors/**/*.{js,ts,json,md}\"

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1596f408-73df-4c73-b8b6-fcfc79aae402

📥 Commits

Reviewing files that changed from the base of the PR and between 6fe1679 and 25d1659.

📒 Files selected for processing (2)

• packages/errors/README.md
• packages/errors/src/GhostError.ts

✅ Files skipped from review due to trivial changes (2)

• packages/errors/src/GhostError.ts
• packages/errors/README.md

---

Walkthrough

This PR adds comprehensive documentation to the Ghost error handling system without modifying any code logic or type definitions. The README is expanded with a concrete usage example showing how to throw a typed error, a field guide table describing each supported error property and its intended use, and a section highlighting common mistakes with before/after examples. The GhostError.ts source file receives matching JSDoc comments on the GhostErrorOptions interface fields to document their purposes at the definition site.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• Add details to zip safety errors #636: Expands JSDoc/documentation for GhostErrorOptions fields like context, code, and errorDetails, closely related to the README usage example for thrown typed errors.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and directly summarizes the main change: documenting Ghost error field usage through README updates and JSDoc comments.
Description check	✅ Passed	The description accurately describes the changeset: documenting GhostError field usage with JSDoc comments and a comprehensive README guide with examples and best practices.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/ghost-error-usage

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.92%. Comparing base (4c827db) to head (25d1659).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #635      +/-   ##
==========================================
- Coverage   98.12%   97.92%   -0.20%     
==========================================
  Files          84       49      -35     
  Lines        2771     1975     -796     
  Branches      510      395     -115     
==========================================
- Hits         2719     1934     -785     
+ Misses         11        7       -4     
+ Partials       41       34       -7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.