Quickstart upgrade guide

[miles-kt-inkeep]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Ready	Preview	Comment	Oct 7, 2025 2:28pm
agents-manage-api	Ready	Preview	Comment	Oct 7, 2025 2:28pm
agents-manage-ui	Ready	Preview	Comment	Oct 7, 2025 2:28pm
agents-run-api	Ready	Preview	Comment	Oct 7, 2025 2:28pm

[claude]

Claude finished @miles-kt-inkeep's task —— View job

---

PR Review: Quickstart Upgrade Guide

Review Checklist:

• Analyze upgrade guide documentation content and structure
• Review navigation integration changes
• Examine utility function modifications
• Evaluate system architecture and design decisions
• Assess customer impact and user experience
• Provide actionable feedback and recommendations

Staff Engineer Review

🔍 Documentation Analysis

Strengths:

• Clear structure with Overview → Quickstart Template → Agent CLI sections
• Good use of package links to npm registry for reference
• Proper MDX frontmatter with title, description, and icon

Critical Issues:

1. Missing upgrade-agents Command Implementation ⚠️ HIGH PRIORITY

The documentation instructs users to run pnpm upgrade-agents but this command doesn't exist anywhere in the codebase:

• Not found in root package.json scripts
• Not found in packages/create-agents/package.json
• No implementation in the create-agents codebase

Impact: Users will get command not found errors, making the upgrade guide unusable.

Recommendation: Either:

• Implement the upgrade-agents script in the root package.json
• Update documentation to use existing commands
• Create the missing functionality

2. Incomplete Upgrade Instructions ⚠️ MEDIUM PRIORITY

• No guidance for upgrading individual packages
• Missing database migration considerations
• No rollback or troubleshooting instructions
• No version compatibility matrix

3. Incorrect CLI Global Update Command ⚠️ MEDIUM PRIORITY

Line 34: npm update -g @inkeep/agents-cli --latest

• The --latest flag doesn't exist for npm update
• Should be: npm update -g @inkeep/agents-cli or npm install -g @inkeep/agents-cli@latest

📁 Navigation Integration ✅

• Properly integrated into "Get Started" group
• Consistent with existing navigation patterns
• Good placement after credentials setup

🔧 Utility Function Changes

Reviewing changes in packages/create-agents/src/utils.ts:

Issues Found:

1. Line 424: The push command will fail silently but documentation assumes it works:

await execAsync(
  `pnpm inkeep push --project src/${config.projectId} --config src/inkeep.config.ts`
);

The documentation references upgrade-agents which would need similar error handling.

2. Process Management Complexity: Lines 430-449 show complex process cleanup logic that could be error-prone during upgrades.

🏗️ System Architecture Considerations

Missing Upgrade Strategy:

• No consideration for breaking changes across versions
• No database schema migration handling for upgrades
• No configuration migration patterns
• No validation that existing projects are compatible

Customer Experience Issues:

1. Breaking User Flow: The main upgrade command doesn't exist
2. No Version Validation: Users could upgrade incompatible versions
3. Missing Error Recovery: No guidance when upgrades fail
4. Incomplete Coverage: Only covers template upgrades, not manual installations

📋 Recommendations

Immediate Actions Required:

1. Implement upgrade-agents command or update documentation to use existing commands
2. Fix CLI update command syntax - remove --latest flag
3. Add error handling examples
4. Test the documented upgrade flow end-to-end

Enhancement Suggestions:

1. Add version compatibility section
2. Include database migration steps
3. Provide troubleshooting section
4. Add upgrade validation checks
5. Include rollback instructions

Code Quality:

• Consider adding integration tests for upgrade scenarios
• Implement upgrade command with proper error handling and rollback capabilities
• Add version checking logic before attempting upgrades

💡 Architectural Improvements

Consider implementing a proper upgrade system that:

• Validates current installation before upgrading
• Handles database migrations automatically
• Provides rollback capabilities
• Shows progress and status updates
• Validates successful upgrade completion

The current approach is documentation-only without corresponding implementation, which will lead to poor user experience and support issues.

---

Summary

This PR introduces upgrade documentation but has a critical flaw: the main upgrade command pnpm upgrade-agents doesn't exist. This needs to be resolved before merging to avoid breaking user workflows. The documentation structure is good but needs implementation backing and more comprehensive coverage of upgrade scenarios.