johnwatso · johnwatso · May 11, 2026 · May 5, 2026 · May 6, 2026 · May 6, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,85 @@
+# SwiftBot Agent Notes
+
+Read `AI_CONTEXT.md` first. It is the main architecture and workflow reference for AI agents working in this repo.
+
+This file exists to capture the practical guardrails that agents are most likely to miss: build system boundaries, project generation, versioning, and release metadata discipline.
+
+## Project Shape
+
+- SwiftBot is a native macOS Xcode app built with SwiftUI.
+- The app project is generated from `project.yml` using XcodeGen.
+- This repo also contains one nested Swift package at `Sources/UpdateEngine`.
+- Do not convert the main app into a Swift package.
+- Do not introduce a repo-root `Package.swift`.
+- Do not move app files into a package-style layout.
+
+## Build and Test
+
+For the main app, use Xcode tooling:
+
+```sh
+xcodebuild -project SwiftBot.xcodeproj -scheme SwiftBot -configuration Debug build
+xcodebuild -project SwiftBot.xcodeproj -scheme SwiftBot -configuration Debug test
+```
+
+Run `xcodegen` after editing `project.yml`:
+
+```sh
+xcodegen
+```
+
+For the nested UpdateEngine package only, SwiftPM commands are valid inside `Sources/UpdateEngine` when that package is the thing being changed:
+
+```sh
+cd Sources/UpdateEngine
+swift test
+```
+
+Do not use `swift build` or `swift test` as a substitute for validating the app target.
+
+## Scope Discipline
+
+- Keep changes scoped to the user’s request.
+- Prefer modifying the relevant SwiftUI view, model, or service directly instead of refactoring unrelated systems.
+- Do not introduce new modules, packages, or architectural layers unless the user explicitly asks for that level of change.
+- Follow existing Apple-platform patterns in this repo. Avoid web-style UI abstractions and avoid external UI frameworks.
+
+## Versioning
+
+- `MARKETING_VERSION` is user-directed. Do not bump it unless the user explicitly asks.
+- `CURRENT_PROJECT_VERSION` is timestamp-based. Update it whenever release/version/build preparation is part of the requested work. Use the local project time at the moment of the change, formatted as `yyyyMMddHH` (example: `2026050813` means 2026 May 8 at 1pm).
+- When version metadata changes, keep `project.yml` and `SwiftBot.xcodeproj/project.pbxproj` aligned.
+- If release metadata is touched, also verify related Sparkle/appcast files under `docs/`:
+  - `sparkle:shortVersionString` should match `MARKETING_VERSION`.
+  - `sparkle:version` should match the generated `CURRENT_PROJECT_VERSION` timestamp.
+  - Any visible build references in release notes should match the generated build number.
+
+## Sparkle and Release Metadata
+
+Treat these as release-critical whenever touched:
+
+- `project.yml`
+- `SwiftBot.xcodeproj/project.pbxproj`
+- `docs/appcast.xml`
+- `docs/release-notes/*`
+
+Do not break:
+
+- `SUFeedURL`
+- `SUPublicEDKey`
+- `MARKETING_VERSION`
+- `CURRENT_PROJECT_VERSION`
+- appcast version/release-note links
+
+If you edit release metadata, build the app and verify the resulting Info.plist values before calling the work done.
+
+## Project Generation Rules
+
+- `project.yml` is the source of truth for generated Xcode settings.
+- If you change build settings in the generated project, mirror them in `project.yml` unless there is a very specific reason not to.
+- Avoid committing unrelated XcodeGen drift.
+
+## Coordination
+
+- Use `AI_CONTEXT.md` for architecture, file ownership, cluster safety rules, and UI rules.
+- If guidance in this file and `AI_CONTEXT.md` ever appear to conflict, follow the repo reality and preserve existing behavior, then document the inconsistency in your final note.
diff --git a/AI_CONTEXT.md b/AI_CONTEXT.md
@@ -11,12 +11,12 @@ SwiftBot is a **native macOS Discord bot manager** built entirely with Swift and
 
 | Property | Value |
 |----------|-------|
-| Platform | macOS 13+ |
+| Platform | macOS 26+ |
 | Language | Swift with Concurrency (async/await, actors) |
 | Framework | SwiftUI — Apple-platform-first, no web frameworks |
 | Design Language | Apple Human Interface Guidelines — Liquid Glass / modern macOS |
 | Architecture | MVVM + actor isolation + EventBus pub/sub |
-| Build System | Xcode + Swift Package Manager |
+| Build System | Xcode + XcodeGen for the app, SwiftPM only for `Sources/UpdateEngine` |
 
 **What it does:** Connects to Discord via WebSocket gateway, monitors server events, and executes automated rules when events match. Also supports AI replies, wiki lookups, update monitoring (Patchy), multi-node cluster failover (SwiftMesh), and a web-based admin UI.
 
@@ -99,7 +99,7 @@ struct PipelineContext {
 | File | Purpose |
 |------|---------|
 | `AppModel.swift` | Primary app state `@MainActor ObservableObject`. Bot lifecycle, settings, gateway coordination, rule engine orchestration, Patchy scheduler, plugin management. |
-| `AppModel+Commands.swift` | Slash and prefix command handlers |
+| `AppModel+Commands.swift` | Slash command handlers |
 | `AppModel+Gateway.swift` | Gateway event parsing and dispatch |
 | `AppModel+AI.swift` | AI provider routing and response generation |
 | `DiscordService.swift` | Discord WebSocket gateway + REST API actor. Rule action execution. AI replies. Wiki lookup. |
@@ -163,7 +163,7 @@ All UI in SwiftBot **must** follow:
 
 1. **Apple Human Interface Guidelines** — always, without exception
 2. **SwiftUI only** — no AppKit views unless unavoidable (use `NSViewRepresentable`)
-3. **System Settings layout style** — sidebar navigation, HSplitView, material backgrounds
+3. **System Settings layout style** — sidebar navigation, split-pane layouts where appropriate, material backgrounds
 4. **Liquid Glass / modern macOS design language** — `.ultraThinMaterial`, `.thinMaterial`, semantic system colors
 5. **No web-style patterns** — no CSS-like layouts, no custom scrollbars, no card grids
 6. **No external UI frameworks** — zero SwiftPM UI dependencies
@@ -179,7 +179,7 @@ All UI in SwiftBot **must** follow:
 ### 3-Pane View Architecture
 
 ```
-VoiceWorkspaceView (HSplitView)
+VoiceWorkspaceView (split-pane layout)
 ├── RuleListView (220–320px)             — VoiceRuleListView.swift
 │   ├── isLoading → ProgressView()
 │   ├── rules.isEmpty → RuleListEmptyStateView ("No Rules Yet")
@@ -233,7 +233,8 @@ var processedActions: [RuleAction]   // runtime migration: legacy booleans → m
 
 - ✅ Swift Concurrency (`async/await`, `actor`, `@MainActor`, `Task`)
 - ✅ Keychain for ALL secrets — never write to disk
-- ✅ Add new `.swift` files to `project.pbxproj` (4 entries: PBXFileReference, PBXBuildFile, PBXGroup, PBXSourcesBuildPhase)
+- ✅ Treat `project.yml` as the source of truth for app project settings
+- ✅ Run `xcodegen` after editing `project.yml`
 - ✅ `.id(selectionID)` on all list-detail views to prevent SwiftUI state leakage
 - ✅ Look up current selection INSIDE binding closures — never capture IDs at creation time
 - ✅ `await MainActor.run {}` when updating `@Published` from background actors
@@ -245,7 +246,8 @@ var processedActions: [RuleAction]   // runtime migration: legacy booleans → m
 - ❌ Pre-populate new rules with default trigger or actions
 - ❌ Change `Models.swift` structure without cross-agent approval
 - ❌ Add new SwiftPM dependencies without explicit justification
-- ❌ Break existing UI layouts or SplitView behaviors
+- ❌ Convert the main app target into a Swift package or add a repo-root `Package.swift`
+- ❌ Break existing UI layouts or split-pane behaviors
 - ❌ Send Discord output from Standby or Worker nodes
 - ❌ Use `#if DEBUG` to gate production logic
 - ❌ Call `test*` methods from production code paths
@@ -255,20 +257,11 @@ var processedActions: [RuleAction]   // runtime migration: legacy booleans → m
 
 ---
 
-## 8. Multi-Agent File Ownership
+## 8. Agent Coordination
 
-When multiple agents work on SwiftBot simultaneously, respect file ownership:
+If multiple agents are working in parallel, coordinate before editing the same files and prefer clear ownership by area for the duration of the task.
 
-| File | Owner |
-|------|-------|
-| `VoiceActionsView.swift` | **claude** |
-| `VoiceRuleListView.swift` | **claude** |
-| `EmptyRuleOnboardingView.swift` | **claude** |
-| `Models.swift` | **kimi** |
-| `AppModel.swift` | **gemini** |
-| `DiscordService.swift` | **gemini** |
-
-**Rule:** Post in `#swiftbotdev` before editing another agent's file. Coordinate task splits before starting any work.
+This file does not assign permanent file owners. Treat any historical ownership notes elsewhere as advisory, not authoritative.
 
 ---
 
@@ -306,11 +299,10 @@ static func empty() -> Rule { Rule(trigger: nil, actions: []) }
 - [ ] Build succeeds — 0 errors, 0 new warnings
 - [ ] Modified feature works as expected
 - [ ] No regressions in unrelated features
-- [ ] `CHANGELOG.md` updated
-- [ ] Any new `.swift` files added to `project.pbxproj`
-- [ ] Posted results in `#swiftbotdev`
+- [ ] If `project.yml` changed, regenerate with `xcodegen`
+- [ ] If versioning or release metadata changed, verify `project.yml`, `SwiftBot.xcodeproj/project.pbxproj`, and `docs/` stay aligned
 
 ---
 
-*Last updated: 2026-03-11*
+*Last updated: 2026-05-07*
 *See `ARCHITECTURE.md` for full technical detail · `AI_GUIDE.md` for common task recipes*
diff --git a/AI_GUIDE.md b/AI_GUIDE.md
@@ -342,7 +342,6 @@ Binding(
 
 When modifying this project, update these files:
 
-- [ ] **CHANGELOG.md** - Document what changed and why
 - [ ] **This file** - If you discover new patterns or gotchas
 - [ ] **ARCHITECTURE.md** - If you change core architecture
 
@@ -435,7 +434,6 @@ Before marking changes complete:
 - [ ] Modified features work as expected
 - [ ] Existing features still work (no regressions)
 - [ ] Settings persist across restart
-- [ ] CHANGELOG.md updated
 - [ ] No console errors or warnings
 
 ## Resources