🌟 COSMOS: Your Complete Welcome Guide v5.2

🎯 What You're Going to Do

You'll complete your first complete workflow:

1. Create a GitHub account (if needed)
2. Get repository access
3. Open your terminal
4. Download the codebase
5. Install COSMOS with membrane generation 🆕
6. Set up cloud infrastructure (optional) 🆕
7. Configure issue tracking (optional) 🆕
8. Make a change and commit it
9. Create and manage issues
10. Preview and execute a release

Time needed: 45-60 minutes for complete setup

What you'll learn: The full professional development workflow

📝 Step 0: Create Your GitHub Account

Before anything else, you need a GitHub account. GitHub is where all our code lives online.

If you already have a GitHub account:

Skip to Step 1! 🎉

If you need to create an account:

1. Open your web browser and go to: https://github.com/signup
2. Enter your email address
3. Create a password (make it strong!)
4. Choose a username (pick something professional—your team will see it)
5. Verify you're human (solve the puzzle)
6. Check your email for a verification code and enter it
7. Complete the setup (you can skip optional questions)

✅ You now have a GitHub account!

🚨 Important: Request Repository Access

💻 Step 1: Open Your Terminal

The terminal is how you talk to your computer using text commands instead of clicking.

On Mac:

1. Press Command + Space (opens Spotlight)
2. Type: terminal
3. Press Enter

On Windows:

Use Git Bash (not Command Prompt or PowerShell):

1. Go to: https://git-scm.com/downloads
2. Download "Git for Windows"
3. Run the installer (defaults are fine)
4. Search for "Git Bash" in the Start menu and open it

What you'll see:

A window with text ending in a $ or > symbol. This is your prompt—where you type commands.

💻 Step 1.5: Choose Your Editor (Recommended)

COSMOS works in any editor. But for your first mission, we recommend Visual Studio Code because:

• 🐛 Debugging – When validation fails, Code shows you exactly why
• 🧠 Intelligence – Language servers understand 6 languages, give real-time hints
• 🔗 Integration – Git, terminals, extensions all built-in
• 📚 Learning – Tons of tutorials, extensions, community help

Using Sublime, Vim, or another editor? That works too. COSMOS validates outside the editor, so your choice doesn't matter. But we recommend Code for the best first experience.

🔐 Step 2: Connect to GitHub

You need to authenticate with GitHub before you can download code.

Type this command:

Press Enter

Answer the prompts:

1. "What account do you want to log into?"
→ Type 1 and press Enter (GitHub.com)

2. "What is your preferred protocol?"
→ Type 1 and press Enter (HTTPS)

3. "Authenticate Git with your GitHub credentials?"
→ Type y and press Enter

4. "How would you like to authenticate?"
→ Type 1 and press Enter

In your browser:

1. Copy the code shown (looks like: ABCD-1234)
2. Paste it in the browser window
3. Log in and authorize

✅ Success! Terminal shows: "✓ Logged in as [your username]"

📥 Step 3: Download COSMOS

Now we're getting the actual code to your computer.

Create a Code folder:

Press Enter

Download COSMOS:

✅ Replace with your actual repository URL!

Press Enter

Move into the folder:

Press Enter

Verify you're in the right place:

Press Enter

You should see: install.sh, various .sh files, and directories.

✅ Perfect! You're in the repository.

⚡ Step 4: Install COSMOS (With Intelligent Features)

The installer now includes membrane generation, cloud setup, and issue tracking.

Run the installer:

Press Enter

What the installer does:

1. ✅ Checks Git and Bash are installed
2. ✅ Detects optional tools (Rust, Go, Node, Java, Python, fzf)
3. ✅ Makes all scripts executable with verification
4. ✅ Creates command shortcuts (c-pulse, c-commit, etc.)
5. ✅ Offers membrane generation 🆕
6. ✅ Offers cloud infrastructure setup 🆕
7. ✅ Offers issue tracking configuration 🆕
8. ✅ Tests everything works

🧠 Step 4.1: Membrane Generation (Recommended)

The installer will ask: "Generate .cosmos-membrane.json?"

When prompted, type y to generate:

✅ Membrane created! This powers all intelligent features.

☁️ Step 4.2: Cloud Infrastructure Setup (Optional)

The installer will ask: "Configure cloud infrastructure?"

Supported Providers:

When prompted, type y to configure:

📋 Step 4.3: Issue Tracking Setup (Optional)

The installer will ask: "Configure issue tracking?"

Supported Platforms:

When prompted, type y to configure:

✅ Issue templates created in .cosmos/issue-templates/

🎉 Installation Complete!

Verify installation:

Press Enter

You should see: A formatted table showing the status of all services with language badges, versions, and sync status.

📋 Your Complete COSMOS Toolkit

🔧 Supported Languages & Detection

COSMOS automatically detects and validates multiple programming languages plus documentation:

✏️ Step 6: Make Your First Change

Let's practice the daily workflow. You'll edit a file and use COSMOS to save it properly.

Navigate to the repository:

Press Enter

Create or edit a file:

For this example, create a simple text file:

Press Enter

Verify your change:

Press Enter

✅ You've modified a real file!

💾 Step 7: Commit with COSMOS

This is where COSMOS makes your life easier. It validates, formats, and saves your changes properly.

Run the commit tool:

Press Enter

The --no-verify flag: Skips validation since we're changing documentation, not code.

Answer COSMOS's questions:

1. "Selection:"
→ Type 4 and press Enter (documentation change)

2. "Message:"
→ Type: add myself to newcomers registry
→ Press Enter

3. "Scope:"
→ Just press Enter (auto-fills)

4. "Finalize?"
→ You'll see your formatted message
→ Type y and press Enter

✅ Success! You'll see: "✓ Commit successful!"

What COSMOS did automatically:

1. Staged your changes
2. Formatted your message in team standard: docs(scope): your message
3. Saved it using git

🚀 Step 8: Share With the Team

Upload your change to GitHub so everyone can see it.

Set upstream branch (first time only):

Press Enter

Upload your change:

Press Enter

✅ Your change is now on GitHub!

See your change online:

1. Open the repository on GitHub
2. Click "Commits" near the top
3. Your commit should appear at the very top!

🏆 You Did It!

You just completed your first real workflow:

• Created a GitHub account
• Requested repository access
• Opened a terminal
• Connected to GitHub
• Downloaded a real monorepo
• Installed COSMOS with verification
• Made a change
• Committed with COSMOS
• Shared with the team

That's genuinely impressive!

📖 Your Daily Workflow

Now you know the four-step workflow you'll use every day:

1. Navigate to your code:

2. Make changes (use your editor)

Edit files however you normally would

3. Commit with validation:

This time without --no-verify. COSMOS will validate your code before saving. For code changes, it will run language-specific checks (cargo check, npm lint, etc.).

4. Share with team:

That's it! Four simple steps instead of remembering all the git commands.

🚀 Ready for More?

Once you're comfortable with the basics, you can explore:

Check overall status:

Shows all services, their versions, and release status

Preview a release:

See what version and changelog would be created (no changes made)

Create a release:

Release a service version with automatic constraint checking and GitHub Actions coordination. Then push with git push --follow-tags

Deep analysis:

See detailed history and version information

❓ Common Questions

Q: What if I make a mistake?
A: Don't panic! Everything is tracked and reversible. You can't break anything permanently.

Q: What if I see an error?
A: Read it carefully—most errors tell you exactly what's wrong. Common fixes:

• Wrong folder? Use cd ~/Code/roxy-systems
• Permissions issue? Re-run ./install.sh
• Script won't run? Scripts are made executable with defensive verification during install

Q: Can I practice the commit workflow again?
A: Absolutely! Make more changes and repeat the c-commit → git push flow.

Q: What does c-linker do?
A: It coordinates releases with GitHub Actions. It checks that security scans pass, validates dependencies, and creates release tags. Your workflow triggers the AP (Application Plane) workflow to build Docker images and sign them.

Q: What is cosmos.json?
A: An optional manifest file for documenting projects and custom types. Create it later with cosmos-init.sh when you're ready.

Q: Who do I ask for help?
A: Your team lead or team chat. Everyone was new once—asking questions is normal!

💭 Remember

Take your time: No rush. Go at your own pace.

You can't break anything: Seriously. Worst case is an error message and you try again.

Every expert started here: Every great developer was once typing their first terminal command.

You're doing great: If you made it this far, you're already learning!

🎓 What's Next?

1. Practice the c-commit → git push workflow several times
2. Explore c-pulse to see the full project status
3. Try making a code change (with validation enabled)
4. Learn about c-test for previewing releases
5. When ready, ask your team lead about using c-linker
6. Create a cosmos.json manifest with cosmos-init.sh

You've got this! 🌟