# 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

```bash
make sync
```

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

### Manual

```bash
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:

```bash
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:

```bash
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