docs: enhance readme in order to be compliance with our oss repos

[peppescg]

🎉 Make repository open source

This PR prepares the repository for open source release by adding all necessary documentation, legal files, and developer guidelines.

📄 New Files Added

Legal & Community Files

• LICENSE - Apache 2.0 license (© 2025 Stacklok, Inc.)
• SECURITY.md - Security policy and vulnerability reporting process
• CODE_OF_CONDUCT.md - Contributor Covenant v1.4
• CONTRIBUTING.md - Contribution guidelines
• .env.example - Environment variables template with detailed comments

📝 Updated Files

README.md - Major Enhancements

• ✅ Updated project description (removed "managing", added "visualizing with easy URL copying")
• ✅ Added reference to backend API (toolhive-registry-server)
• ✅ New: Developer Guide section with:
  • Complete command reference (all pnpm scripts explained)
  • Make commands aligned with pnpm scripts
  • 4 development modes (Full Stack, Mock OIDC + Real API, Mock API + Real OIDC, Real Services Only)
  • Development workflow (setup, running, code quality, API updates)
  • Testing guide
  • Mock server documentation
• ✅ New: Environment Variables section with:
  • Required production variables table
  • Optional variables table
  • Development auto-configured variables
• ✅ New: Related Projects section (toolhive-registry-server)
• ✅ Added Contributing and License sections at the end

Makefile

• ✅ Added new development targets aligned with pnpm scripts:
  • make install, make lint, make format, make test, make type-check
  • make dev-mock-server, make dev-mock-oidc (new development modes)
  • make generate-client
• ✅ Updated help text with all available commands organized by category

package.json

• ✅ Added dev:mock-oidc script - runs Next.js + OIDC mock (requires real backend API)

.gitignore

• ✅ Added exception to allow .env.example in repository (!.env.example)

🔗 References

• Follows the same structure as toolhive-studio
• Backend API: toolhive-registry-server
• Implements official MCP Registry API format

✅ Checklist

• Apache 2.0 license added
• Security policy
• Code of Conduct (Contributor Covenant v1.4)
• Contributing guide with DCO requirement
• Comprehensive README with developer guide
• Environment variables template and documentation
• Make commands aligned with pnpm scripts

---

Ready for open source release! 🚀

[peppescg]

@claude could you review this PR

[claude]

Claude finished @peppescg's task —— View job

---

Code Review for PR #91 - Open Source Compliance Documentation

I've completed a thorough review of this PR. Overall, this is excellent work that properly prepares the repository for open source release! The documentation is comprehensive, well-structured, and follows industry best practices. Below are my detailed findings.

---

✅ Strengths

1. Comprehensive Legal & Community Files

• ✅ Apache 2.0 LICENSE properly formatted with correct copyright (© 2025 Stacklok, Inc.)
• ✅ SECURITY.md follows responsible disclosure best practices
• ✅ CODE_OF_CONDUCT.md uses Contributor Covenant v1.4 (industry standard)
• ✅ CONTRIBUTING.md includes DCO requirement and clear PR process

2. Outstanding README Enhancement

• ✅ Clear project description with backend API reference
• ✅ Comprehensive Developer Guide with 4 development modes
• ✅ Well-organized command reference (pnpm + Make)
• ✅ Environment variables documentation (Required/Optional/Dev)
• ✅ Professional structure suitable for open source

3. Developer Experience

• ✅ .env.example with detailed inline comments
• ✅ New dev:mock-oidc script fills a real workflow gap
• ✅ Makefile aligned with all pnpm scripts
• ✅ .gitignore properly allows .env.example

4. Consistency & Standards

• ✅ Aligned with toolhive-studio repository standards
• ✅ References to related projects (registry-server, studio)
• ✅ Consistent terminology throughout

---

🔍 Issues Found

Critical Issue: Makefile Target Name Inconsistency

Location: Makefile line 18

Problem: The Makefile defines dev-mock-server but the README references dev-mock:

# Makefile line 18
make dev-mock-server # Run Next.js with MSW (requires real OIDC)

# README.md line 82
make dev-mock        # Run with MSW only (pnpm dev:mock-server)

Impact: Users following the README will encounter "No rule to make target 'dev-mock'" error.

Solution: Choose one of:

1. Rename Makefile target to dev-mock (shorter, matches README)
2. Update README to use dev-mock-server (matches existing pattern)

I recommend option 1 for brevity, but either works.

---

Minor Issues

1. Missing Makefile Target Definition

Location: Makefile line 1

The .PHONY declaration includes dev-mock-server and dev-mock-oidc, but the README mentions dev-mock. Update the .PHONY line to match whatever naming you choose.

2. Documentation Typo - "compliance" vs "compliant"

Location: Commit message

doc: enhance readme in order to be compliance with our oss repos

Should be either:

• "to be compliant with" (adjective)
• "to be in compliance with" (noun phrase)

Note: This is in the commit message, which will be squashed, so not critical.

3. NEXT_PUBLIC_OIDC_PROVIDER_ID Explanation

Location: .env.example lines 18-20

The comment is excellent, but you might want to add a note explaining why this variable needs the NEXT_PUBLIC_ prefix:

# OIDC Provider identifier (e.g., "okta", "auth0", "oidc")
# Must use NEXT_PUBLIC_ prefix because it's needed on both server and client
# This is not sensitive data - it's just an identifier for the auth provider type
NEXT_PUBLIC_OIDC_PROVIDER_ID=

This matches the explanation in CLAUDE.md (line 309) and helps developers understand the reasoning.

---

📋 Verification Checklist

I verified the following against CLAUDE.md and project standards:

• ✅ All new scripts align with project conventions
• ✅ Documentation mentions Server Components First (implicit via tech stack)
• ✅ References to hey-api for API calls
• ✅ TypeScript strict mode mentioned
• ✅ No any type policy referenced in CONTRIBUTING.md (line 76)
• ✅ Async/await over promises mentioned in guidelines
• ✅ Testing strategy documented
• ✅ Make commands properly forward to pnpm
• ✅ Environment variables correctly categorized

---

🎯 Recommendations

Must Fix Before Merge

1. ❗ Fix Makefile/README inconsistency (dev-mock vs dev-mock-server)

Nice to Have

2. Enhance .env.example NEXT_PUBLIC_OIDC_PROVIDER_ID comment (explain why NEXT_PUBLIC_)
3. Fix commit message grammar (will be squashed anyway, so low priority)

---

📊 Summary

Overall Assessment: ⭐⭐⭐⭐⭐ (Excellent)

This PR successfully prepares the repository for open source release with:

• ✅ Complete legal compliance (Apache 2.0, DCO, CoC)
• ✅ Professional documentation standards
• ✅ Comprehensive developer onboarding
• ✅ Clear contribution guidelines
• ✅ Multiple development workflow options

Only blocking issue: Makefile target naming inconsistency that will cause runtime errors.

Once the Makefile/README naming is aligned, this PR is ready to merge! 🚀

---

Job Run: View workflow run
Branch: issues/90

[Copilot]

Pull request overview

This PR prepares the repository for open source release by adding comprehensive documentation, legal files, and developer guidelines following the same standards as toolhive-studio.

Key changes:

• Added Apache 2.0 license and standard OSS governance files (SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md)
• Enhanced README with detailed developer guide covering 4 development modes, environment variables, and complete command reference
• Added new dev:mock-oidc npm script and corresponding Makefile targets for flexible development workflows

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
LICENSE	Apache 2.0 license (© 2025 Stacklok, Inc.)
SECURITY.md	Security policy and vulnerability reporting process aligned with toolhive-studio
CODE_OF_CONDUCT.md	Contributor Covenant v1.4 code of conduct
CONTRIBUTING.md	Contribution guidelines with DCO requirement and development best practices
.env.example	Environment variables template with detailed comments for all required and optional variables
README.md	Major enhancement with comprehensive developer guide, environment variables section, and related projects
Makefile	Added new development targets (install, lint, format, test, type-check, dev-mock-oidc, dev-mock-server, generate-client) aligned with pnpm scripts
package.json	Added dev:mock-oidc script for running Next.js with OIDC mock (requires real backend API)
.gitignore	Added exception to allow .env.example in repository while ignoring other .env files

[kantord]

💯