Pioneer Onboarding

Welcome to the Vreko Pioneer program. This guide will help you install Vreko, start your first session, and troubleshoot any issues you encounter.

Install + First Session

Step 1: Install Vreko

# Install Vreko CLI
npm install -g @vreko/cli

# Initialize Vreko in your project
vreko init

The vreko init command will:

• Create a .vreko/ directory in your project
• Set up the configuration file
• Start the Vreko service in the background

Step 2: Start Your First Session

With the service running, start a session:

# Start a session
vreko session start

# Do some AI-assisted work with your AI assistant

# End the session
vreko session end

After ending the session, Vreko will generate a closing ceremony showing:

• How many fragile files were detected
• Patterns learned from your work
• Any risks avoided during the session

Step 3: Install the Pre-Commit Hook (Optional)

To get real-time feedback on fragile files:

vreko hook install

This installs a git pre-commit hook that will warn you before editing fragile files.

Troubleshooting

Service Won’t Start

Problem: Running vreko service status shows the service is not running.

Solutions:

1. Check if another process is using the service socket:

   lsof -i :3000  # or the port configured in .vrekorc

2. Kill any existing service processes:

   pkill -f vreko-service

3. Restart the service:

   vreko service restart

Session Not Recording

Problem: You started a session but no learnings or snapshots were captured.

Solutions:

1. Verify the service is running:

   vreko service status

2. Check your .vrekorc configuration file to ensure the workspace is properly configured
3. Try ending the session manually:

   vreko session end

Hook Not Triggering

Problem: The pre-commit hook isn’t warning you about fragile files.

Solutions:

1. Verify the hook is installed:

   ls -la .git/hooks/pre-commit

2. Reinstall the hook:

   vreko hook install --force

3. Check that you have fragile files in your workspace:

   vreko session list --last 1

Ceremony Not Appearing

Problem: After ending a session, the closing ceremony doesn’t appear.

Solutions:

1. In VS Code: Open the Command Palette (Cmd+Shift+P) and run vreko.showCeremony
2. In CLI: Run vreko session list --last 1 to view the ceremony in the terminal
3. Check that the service is healthy:

   vreko service status

What to Expect / Feedback Loop

What to Expect

During Your First Week:

• Vreko will learn your coding patterns
• You’ll see the closing ceremony after each session
• The hook will warn you about fragile files (advisory mode)
• You may notice suggestions for refactoring based on fragility

After 14 Days:

• The hook will switch to block mode (exits non-zero on fragile files)
• You’ll have accumulated enough data for meaningful pattern learning
• Invariant suggestions will become more accurate

Ongoing:

• Each session builds on previous learnings
• Vreko adapts to your coding style
• The closing ceremony provides actionable insights

Feedback Loop

We need your feedback to improve Vreko. Here’s how to help:

Report Bugs:

• Open an issue on GitHub: GitHub Issues
• Include your OS, Node version, and steps to reproduce

Share Learnings:

• What patterns did Vreko learn correctly?
• What suggestions were helpful or unhelpful?
• Are there false positives in fragility detection?

Join the Community:

• Discord - Chat with other Pioneers and the Vreko team
• Share your closing ceremonies and learnings
• Help shape the future of Vreko

Need More Help?

• Documentation: Full documentation
• Discord: Join our Discord
• GitHub: View source code