agent-orchestrator/MAINTENANCE.md

Maintenance Guide

Operational procedures for the commercial edition of Agent Orchestrator.

PAT Rotation

The COMMUNITY_PAT personal access token is used by CI to sync with the community repository. Rotate it every 90 days.

Rotation Procedure

1. Generate a new fine-grained PAT on GitHub with scope:
   • Repository: DexterFromLab/agent-orchestrator
   • Permissions: Contents: Read-only
2. Update the secret in this repo's GitHub Settings > Secrets > Actions:
   • Name: COMMUNITY_PAT
   • Value: the new token
3. Run the sync workflow manually to verify: Actions > Community Sync > Run workflow.
4. Record the rotation date. Next rotation due in 90 days.

Token Audit

Check token expiry dates monthly. Set a calendar reminder.

Community Sync

Automated

make sync

This fetches community/main, merges it into origin/main, and runs the test suite. Conflicts must be resolved manually.

Manual

git remote add community https://github.com/DexterFromLab/agent-orchestrator.git 2>/dev/null
git fetch community main
git checkout main
git merge community/main --no-edit
npm run test:all

If tests fail after sync, fix before pushing.

Pre-Release Checklist: Community Edition

Before publishing a community release from main:

• git diff main..commercial/main -- agor-pro/ src/lib/commercial/ shows no commercial code on main
• Run grep -r "LicenseRef-Commercial" --include="*.ts" --include="*.rs" --include="*.svelte" src/ src-tauri/ on main returns nothing
• Run npm run test:all passes
• Run cargo test --workspace passes
• CHANGELOG.md updated with release notes
• Tag follows semver: v{major}.{minor}.{patch}
• No secrets, API keys, or internal URLs in the diff since last release

Pre-Release Checklist: Commercial Edition

Before publishing a commercial release:

• All commercial branches merged into the release branch
• npm run test:all:commercial passes
• cargo test --workspace passes
• License headers present on all commercial files (grep -rL "SPDX-License-Identifier" agor-pro/ src/lib/commercial/ returns nothing)
• No hardcoded credentials or internal endpoints
• Database migrations tested against fresh install and upgrade from previous version
• Release notes written for commercial changelog

Database Migration Notes

The commercial edition uses a separate data directory to avoid conflicts:

Edition	Data Directory
Community	~/.local/share/bterminal/
Commercial	~/.local/share/agor/

Migration Rules

• Schema migrations run automatically on startup (WAL mode SQLite).
• Never modify existing migration SQL. Add new migrations with incrementing version numbers.
• Test migrations against: (a) fresh install, (b) upgrade from N-1, (c) upgrade from N-2.
• Back up ~/.local/share/agor/ before testing destructive migrations locally.

Edition Switching in Development

When switching between community and commercial editions locally:

make clean

This clears build artifacts and resets configuration to avoid cross-contamination. The two editions use separate data directories, so user data is not affected. Rebuild after switching:

npm install && npm run tauri dev

Quarterly Maintenance

Perform these tasks every quarter:

Security

• Rotate COMMUNITY_PAT (if due within the quarter)
• Run npm audit and cargo audit on both editions
• Review GitHub Dependabot alerts
• Verify no secrets in git history: git log --all --diff-filter=A -- '*.env' '*.pem' '*.key'

Dependencies

• Update Rust toolchain (rustup update)
• Update Node.js to latest LTS if applicable
• Review and update pinned dependency versions
• Run full test suite after updates

Repository Health

• Prune stale branches (git branch --merged main | grep -v main)
• Verify CI workflows are green on main
• Review and close stale issues/PRs
• Sync community changes if not done recently
• Verify backup procedures for commercial data