fix: revise language; add mintlify broken-links npm script

Author: Really Him

CONTRIBUTING.md

@@ -32,9 +32,9 @@ npm install  # install dependencies
 
 ## Making Changes
 
-Note that schema changes are made to `schema.ts`. `schema.json` is generated from
-`schema.ts` using `npm run generate:json`. You should validate your `schema.ts` changes
-by running `npm run validate:schema`.
+Note that schema changes are made to `schema.ts`, and `schema.json` is generated from
+`schema.ts`. You should validate your `schema.ts` changes first and then generate the
+`schema.json`.
 
 1. Create a new branch:
 
@@ -47,16 +47,21 @@ git checkout -b feature/your-feature-name
 
 ```bash
 npm run validate:schema    # validate schema
-npm run generate:json     # generate JSON schema
 ```
 
-4. Run docs locally (optional):
+4. Generate the `schema.json`:
+
+```bash
+npm run generate:json      # generate JSON schema
+```
+
+5. Run docs locally (optional):
 
 ```bash
 npm run serve:docs
 ```
 
-5. Format/lint your changes:
+6. Format/lint your changes:
 
 ```bash
 npm run format:check   # check formatting
@@ -72,10 +77,11 @@ When contributing to the documentation:
 - Include code examples where appropriate
 - Use proper MDX formatting and components
 - Test all links and code samples
+  - You may run `npm run check-links` to look for broken internal links.
 - Use appropriate headings: "When to use", "Steps", and "Tips" for tutorials
 - Place new pages in appropriate sections (concepts, tutorials, etc.)
-- Update docs.json when adding new pages
-- Follow existing file naming conventions (kebab-case.mdx)
+- Update `docs.json` when adding new pages
+- Follow existing file naming conventions (`kebab-case.mdx`)
 - Include proper frontmatter in MDX files
 
 ### Specification Proposal Guidelines

package.json

@@ -26,7 +26,8 @@
     "generate:json": "for f in schema/*/schema.ts; do typescript-json-schema --defaultNumberType integer --required --skipLibCheck \"$f\" \"*\" -o \"${f%ts}json\"; done",
     "serve:docs": "cd docs && mintlify dev",
     "format": "prettier --write \"**/*.md\"",
-    "format:check": "prettier --check \"**/*.md\""
+    "format:check": "prettier --check \"**/*.md\"",
+    "check-links": "cd docs && mintlify broken-links"
   },
   "devDependencies": {
     "ajv": "^8.17.1",