brightdigit · leogdion · May 18, 2026 · May 18, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -426,6 +426,16 @@ For detailed schema workflows and integration:
 - **AI Schema Workflow** (`Examples/CelestraCloud/.claude/AI_SCHEMA_WORKFLOW.md`) - Comprehensive guide for understanding, designing, modifying, and validating CloudKit schemas with text-based tools
 - **Quick Reference** (`Examples/SCHEMA_QUICK_REFERENCE.md`) - One-page cheat sheet with syntax, patterns, cktool commands, and troubleshooting
 
+## Import Conventions
+
+Every `import` statement must carry an explicit access modifier — `internal import X` or `public import X`. Bare `import X` is forbidden. Default to `internal`; use `public import` only when the module's types appear in this file's `public` API (e.g. `public import HTTPTypes` where `HTTPRequest` is part of a `public` signature).
+
+Exceptions:
+- `@testable import …` is its own modifier — no `internal`/`public` prefix.
+- `Sources/MistKitOpenAPI/` is generated by swift-openapi-generator and currently emits a single bare `import HTTPTypes` in `Client.swift`. The generator doesn't expose an `accessModifierOnImports` setting yet, so that one line is a documented carve-out (SwiftLint already excludes this directory).
+
+The convention is not lint-enforced (SwiftLint has no rule for import visibility), so it's a reviewer responsibility plus the precedent set by the codebase after #159.
+
 ## Additional Notes
 - We are using explicit ACLs in the Swift code
 - type order is based on the default in swiftlint: https://realm.github.io/SwiftLint/type_contents_order.html

diff --git a/Examples/BushelCloud/Sources/BushelCloudCLI/BushelCloudCLI.swift b/Examples/BushelCloud/Sources/BushelCloudCLI/BushelCloudCLI.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 @main
 internal struct BushelCloudCLI {

diff --git a/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/ClearCommand.swift b/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/ClearCommand.swift
@@ -27,10 +27,10 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelCloudKit
-import BushelFoundation
-import BushelUtilities
-import Foundation
+internal import BushelCloudKit
+internal import BushelFoundation
+internal import BushelUtilities
+internal import Foundation
 
 internal enum ClearCommand {
   internal static func run(_ args: [String]) async throws {

diff --git a/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/ExportCommand.swift b/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/ExportCommand.swift
@@ -27,10 +27,10 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelCloudKit
-import BushelFoundation
-import Foundation
-import MistKit
+internal import BushelCloudKit
+internal import BushelFoundation
+internal import Foundation
+internal import MistKit
 
 internal enum ExportCommand {
   // MARK: - Export Types

diff --git a/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/ListCommand.swift b/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/ListCommand.swift
@@ -27,10 +27,10 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelCloudKit
-import BushelFoundation
-import Foundation
-import MistKit
+internal import BushelCloudKit
+internal import BushelFoundation
+internal import Foundation
+internal import MistKit
 
 internal enum ListCommand {
   internal static func run(_ args: [String]) async throws {

diff --git a/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/StatusCommand.swift b/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/StatusCommand.swift
@@ -27,9 +27,9 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelCloudKit
-import BushelFoundation
-import Foundation
+internal import BushelCloudKit
+internal import BushelFoundation
+internal import Foundation
 internal import MistKit
 
 internal enum StatusCommand {

diff --git a/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/SyncCommand.swift b/Examples/BushelCloud/Sources/BushelCloudCLI/Commands/SyncCommand.swift
@@ -27,10 +27,10 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelCloudKit
-import BushelFoundation
-import BushelUtilities
-import Foundation
+internal import BushelCloudKit
+internal import BushelFoundation
+internal import BushelUtilities
+internal import Foundation
 
 internal enum SyncCommand {
   internal static func run(_ args: [String]) async throws {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/BushelCloudKitService.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/BushelCloudKitService.swift
@@ -30,11 +30,11 @@
 public import BushelFoundation
 public import BushelLogging
 public import Foundation
-import Logging
+internal import Logging
 public import MistKit
 
 #if canImport(FelinePineSwift)
-  import FelinePineSwift
+  internal import FelinePineSwift
 #endif
 
 /// CloudKit service wrapper for Bushel demo operations

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/CloudKitAuthMethod.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/CloudKitAuthMethod.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Authentication method for CloudKit Server-to-Server
 ///

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/KeyIDValidator.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/KeyIDValidator.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Validates CloudKit Server-to-Server Key ID format
 internal enum KeyIDValidator {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/OperationClassification.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/OperationClassification.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Classifies CloudKit operations as creates or updates
 ///

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/PEMValidator.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/PEMValidator.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Validates PEM format for CloudKit Server-to-Server private keys
 internal enum PEMValidator {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/SyncEngine+Export.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/SyncEngine+Export.swift
@@ -27,13 +27,13 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelLogging
-import BushelUtilities
-import Logging
+internal import BushelLogging
+internal import BushelUtilities
+internal import Logging
 public import MistKit
 
 #if canImport(FelinePineSwift)
-  import FelinePineSwift
+  internal import FelinePineSwift
 #endif
 
 // MARK: - Export Operations

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/SyncEngine.swift b/Examples/BushelCloud/Sources/BushelCloudKit/CloudKit/SyncEngine.swift
@@ -31,11 +31,11 @@ public import BushelFoundation
 public import BushelLogging
 public import BushelUtilities
 public import Foundation
-import Logging
+internal import Logging
 public import MistKit
 
 #if canImport(FelinePineSwift)
-  import FelinePineSwift
+  internal import FelinePineSwift
 #endif
 
 /// Orchestrates the complete sync process from data sources to CloudKit

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/BushelConfiguration.swift b/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/BushelConfiguration.swift
@@ -28,8 +28,8 @@
 //
 
 public import BushelFoundation
-import Foundation
-import MistKit
+internal import Foundation
+internal import MistKit
 
 // MARK: - Configuration Error
 

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/CloudKitConfiguration.swift b/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/CloudKitConfiguration.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 public import MistKit
 
 // MARK: - CloudKit Configuration

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/CommandConfigurations.swift b/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/CommandConfigurations.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 // MARK: - Sync Configuration
 

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/ConfigurationKeys.swift b/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/ConfigurationKeys.swift
@@ -27,8 +27,8 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import ConfigKeyKit
-import Foundation
+internal import ConfigKeyKit
+internal import Foundation
 
 /// Configuration keys for reading from providers
 internal enum ConfigurationKeys {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/ConfigurationLoader+Loading.swift b/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/ConfigurationLoader+Loading.swift
@@ -27,8 +27,8 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelFoundation
-import Foundation
+internal import BushelFoundation
+internal import Foundation
 
 // MARK: - Configuration Loading
 

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/ConfigurationLoader.swift b/Examples/BushelCloud/Sources/BushelCloudKit/Configuration/ConfigurationLoader.swift
@@ -27,9 +27,9 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import ConfigKeyKit
-import Configuration
-import Foundation
+internal import ConfigKeyKit
+internal import Configuration
+internal import Foundation
 
 /// Actor responsible for loading configuration from CLI arguments and environment variables
 public actor ConfigurationLoader {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBEntry.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBEntry.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents a single macOS build entry from AppleDB
 internal struct AppleDBEntry: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBFetcher.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBFetcher.swift
@@ -29,16 +29,16 @@
 
 public import BushelFoundation
 public import BushelLogging
-import BushelUtilities
-import Foundation
-import Logging
+internal import BushelUtilities
+internal import Foundation
+internal import Logging
 
 #if canImport(FelinePineSwift)
-  import FelinePineSwift
+  internal import FelinePineSwift
 #endif
 
 #if canImport(FoundationNetworking)
-  import FoundationNetworking
+  internal import FoundationNetworking
 #endif
 
 /// Fetcher for macOS restore images using AppleDB API

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBHashes.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBHashes.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents file hashes for verification
 internal struct AppleDBHashes: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBLink.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBLink.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents a download link for a source
 internal struct AppleDBLink: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBSource.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/AppleDBSource.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents an installation source (IPSW, OTA, or IA)
 internal struct AppleDBSource: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/GitHubCommit.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/GitHubCommit.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents a commit in GitHub API response
 internal struct GitHubCommit: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/GitHubCommitsResponse.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/GitHubCommitsResponse.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Response from GitHub API for commits
 internal struct GitHubCommitsResponse: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/GitHubCommitter.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/GitHubCommitter.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents a committer in GitHub API response
 internal struct GitHubCommitter: Codable {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/SignedStatus.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/AppleDB/SignedStatus.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import Foundation
+internal import Foundation
 
 /// Represents the signing status for a build
 /// Can be: array of device IDs, boolean true (all signed), or empty array (none signed)

diff --git a/...les/BushelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline+Deduplication.swift b/...les/BushelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline+Deduplication.swift
@@ -27,8 +27,8 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelFoundation
-import Foundation
+internal import BushelFoundation
+internal import Foundation
 
 // MARK: - Deduplication
 extension DataSourcePipeline {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline+Fetchers.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline+Fetchers.swift
@@ -27,8 +27,8 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelFoundation
-import Foundation
+internal import BushelFoundation
+internal import Foundation
 
 // MARK: - Private Fetching Methods
 extension DataSourcePipeline {

diff --git a/...shelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline+ReferenceResolution.swift b/...shelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline+ReferenceResolution.swift
@@ -27,7 +27,7 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-import BushelFoundation
+internal import BushelFoundation
 
 // MARK: - Reference Resolution
 extension DataSourcePipeline {

diff --git a/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline.swift b/Examples/BushelCloud/Sources/BushelCloudKit/DataSources/DataSourcePipeline.swift
@@ -28,8 +28,8 @@
 //
 
 public import BushelFoundation
-import BushelLogging
-import Foundation
+internal import BushelLogging
+internal import Foundation
 
 /// Orchestrates fetching data from all sources with deduplication and relationship resolution
 public struct DataSourcePipeline: Sendable {