docs: improve jwt-auth package documentation

[gustavomarques00]

Summary

This PR improves the public documentation of @devflow-modules/jwt-auth as a reusable authentication package case for the DevFlow Labs portfolio.

Changes

• Clarifies that the package currently ships as CommonJS.
• Adds a recruiter-focused summary.
• Adds a public API reference table based on the namespace exports.
• Updates examples to use the current namespace-based API shape.
• Adds a complete Express refresh-auth example under examples/express-refresh-auth/server.cjs.
• Clarifies that native ESM compatibility is still roadmap work.
• Notes that protectWithRoles exists in source/tests but should be verified/exported before documenting it as public package API.

Validation

Documentation-only change plus example file. Runtime code was not modified.

Recommended local checks:

npm test
npm run test:coverage

Related Portfolio Issue

Related to devflow-modules/devflow#34.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[gustavomarques00]

Local validation exposed a real Node runtime issue in the example: src/index.js imported CommonJS files without the .cjs extension, so node examples/express-refresh-auth/server.cjs failed with MODULE_NOT_FOUND.

Fixed in commit 2b7af77 by updating src/index.js to require .cjs files explicitly and exporting protectWithRoles through the public middleware namespace.

Please pull the branch again and rerun:

git pull origin docs/jwt-auth-portfolio-polish
npm test
npm run test:coverage
node examples/express-refresh-auth/server.cjs

[gustavomarques00]

Local validation passed after the CommonJS runtime import fixes.

Validated commands:

npm test
npm run test:coverage
node examples/express-refresh-auth/server.cjs

Results:

• Jest: 10 test suites passed, 34 tests passed.
• Coverage: 90.51% statements, 86.76% branches, 100% functions, 90.35% lines.
• Example server started successfully with: Example API running at http://localhost:3000.

GitHub Actions CI also completed successfully for the PR head commit.

Merge is currently blocked only by required code owner review from devflowbotbr.