Improve SDK and docs-site developer documentation.

Add comprehensive Swift API doc comments across VeltoKit and app modules, expand docs with Triki UI integration guidance, and reorganize documentation navigation with dedicated Cursor/Claude skill hubs and downloadable skill files for faster contributor onboarding.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: koderhack

Package.swift

@@ -1,6 +1,7 @@
 // swift-tools-version: 5.9
 import PackageDescription
 
+/// Stores `package` used by this scope.
 let package = Package(
   name: "veltokit",
   platforms: [

VeltoKit/BLE/BLEByteProbe.swift

@@ -2,33 +2,50 @@ import Foundation
 
 /// Pomocnik do znalezienia bajtu/bitów przycisku — porównuje kolejne pakiety RX.
 @MainActor
+/// Represents blebyte probe.
 public final class BLEByteProbe {
+  /// Zmiana pojedynczego bajtu między kolejnymi pakietami.
   public struct ByteChange: Equatable, Sendable {
+    /// Indeks bajtu w pakiecie.
     public let index: Int
+    /// Poprzednia wartość bajtu.
     public let from: UInt8
+    /// Nowa wartość bajtu.
     public let to: UInt8
 
+    /// Zwraca maskę, jeśli zmienił się dokładnie jeden bit.
     public var singleBitMask: UInt8? {
       let xor = from ^ to
       guard xor != 0, xor & (xor - 1) == 0 else { return nil }
       return xor
     }
   }
 
+  /// Zdarzenie zmiany stanu bajtu.
   public struct EdgeEvent: Identifiable, Sendable {
+    /// Unikalny identyfikator zdarzenia.
     public let id = UUID()
+    /// Indeks bajtu w pakiecie.
     public let index: Int
+    /// Poprzednia wartość bajtu.
     public let from: UInt8
+    /// Nowa wartość bajtu.
     public let to: UInt8
+    /// Czas wykrycia zmiany.
     public let at: Date
   }
 
+  /// Ostatnio zarejestrowany pakiet bajtów.
   private(set) public var lastBytes: [UInt8] = []
   private var lastValuesByIndex: [Int: UInt8] = [:]
 
+  /// Ostatni pakiet w formacie HEX.
   public private(set) var lastPacketHex = "—"
+  /// Lista zmian wykrytych dla ostatniego pakietu.
   public private(set) var lastChanges: [ByteChange] = []
+  /// Ostatnie zdarzenia krawędzi 0→1 i 1→0.
   public private(set) var edgeEvents: [EdgeEvent] = []
+  /// Ostatnie linie logu diagnostycznego.
   public private(set) var recentLines: [String] = []
 
   private let maxLines = 80
@@ -41,8 +58,10 @@ public final class BLEByteProbe {
     ).sorted()
   }
 
+  /// Tworzy nowy analizator zmian pakietów BLE.
   public init() {}
 
+  /// Czyści stan analizatora i historię.
   public func reset() {
     lastBytes = []
     lastValuesByIndex = [:]
@@ -52,7 +71,16 @@ public final class BLEByteProbe {
     recentLines = []
   }
 
+  /// Zasila analizator kolejnym pakietem bajtów.
+  ///
+  /// - Parameter bytes: Pakiet bajtów RX.
+  /// - Returns: Lista wykrytych zmian bajtów względem poprzedniego pakietu.
   @discardableResult
+  /// Handles `ingest`.
+  ///
+  /// - Parameters:
+  ///   - bytes: Input used by this operation.
+  /// - Returns: Result produced by this operation.
   public func ingest(_ bytes: [UInt8]) -> [ByteChange] {
     guard !bytes.isEmpty else { return [] }
 

VeltoKit/BLE/BLEManager.swift

@@ -4,7 +4,9 @@ import Combine
 import os
 
 @MainActor
+/// Represents blemanager.
 final class BLEManager: NSObject, ObservableObject {
+  /// Represents status.
   enum Status: String {
     case idle
     case bluetoothOff
@@ -30,6 +32,7 @@ final class BLEManager: NSObject, ObservableObject {
   /// Pełny hex + diff bajtów w konsoli Xcode i w devRawLog (szukaj przycisku).
   @Published public var debugRXBytes = false
 
+  /// Stores `byteProbe` used by this scope.
   public let byteProbe = BLEByteProbe()
 
   /// Domyślnie wyłączone — flow jak w Żappce: user wybiera urządzenie z listy.
@@ -42,6 +45,7 @@ final class BLEManager: NSObject, ObservableObject {
   private var didAutoConnectThisScan = false
 
   private let rxBytesSubject = PassthroughSubject<[UInt8], Never>()
+  /// Stores `rxBytes` used by this scope.
   var rxBytes: AnyPublisher<[UInt8], Never> { rxBytesSubject.eraseToAnyPublisher() }
 
   private let log = Logger(subsystem: "com.koderteam.gametriki", category: "BLE")
@@ -51,12 +55,18 @@ final class BLEManager: NSObject, ObservableObject {
     central = CBCentralManager(delegate: self, queue: nil)
   }
 
+  /// Stores `isScanning` used by this scope.
   var isScanning: Bool { status == .scanning }
 
+  /// Stores `centralStateLabel` used by this scope.
   var centralStateLabel: String {
     "\(centralState.rawValue) (\(stateLabel(centralState)))"
   }
 
+  /// Handles `startScan`.
+  ///
+  /// - Parameters:
+  ///   - clearList: Input used by this operation.
   func startScan(clearList: Bool = true) {
     guard isBluetoothReady else {
       status = .bluetoothOff
@@ -77,12 +87,17 @@ final class BLEManager: NSObject, ObservableObject {
     log.info("BLE scan started (no service filter, allow duplicates)")
   }
 
+  /// Handles `stopScan`.
   func stopScan() {
     central.stopScan()
     if status == .scanning { status = .idle }
     addDevLog("SCAN ■ stop")
   }
 
+  /// Handles `connect`.
+  ///
+  /// - Parameters:
+  ///   - item: Input used by this operation.
   func connect(_ item: DiscoveredPeripheral) {
     stopScan()
     status = .connecting
@@ -92,18 +107,25 @@ final class BLEManager: NSObject, ObservableObject {
     addDevLog("CONN ▶ \(item.name)")
   }
 
+  /// Handles `disconnect`.
   func disconnect() {
     guard let p = activePeripheral else { return }
     central.cancelPeripheralConnection(p)
   }
 
+  /// Handles `sendInitAndStartIfReady`.
   func sendInitAndStartIfReady() {
     guard activePeripheral != nil, let rx = rxChar else { return }
     write([0x01, 0x00], to: rx, type: .withResponse)
     write([0x20, 0x10, 0x00, 0xD0, 0x07, 0x34, 0x00, 0x03], to: rx, type: .withoutResponse)
     addDevLog("TX ▶ INIT + START")
   }
 
+  /// Handles `writeHex`.
+  ///
+  /// - Parameters:
+  ///   - hex: Input used by this operation.
+  ///   - withResponse: Input used by this operation.
   func writeHex(_ hex: String, withResponse: Bool) {
     guard let rx = rxChar else { return }
     let bytes = Hex.parse(hex)
@@ -187,14 +209,21 @@ final class BLEManager: NSObject, ObservableObject {
   }
 }
 
+/// Represents discovered peripheral.
 struct DiscoveredPeripheral: Identifiable, Equatable {
+  /// Stores `id` used by this scope.
   let id: UUID
+  /// Stores `peripheral` used by this scope.
   let peripheral: CBPeripheral
+  /// Stores `name` used by this scope.
   var name: String
+  /// Stores `rssi` used by this scope.
   var rssi: Int
+  /// Stores `isLikelyController` used by this scope.
   var isLikelyController: Bool
 }
 
+/// Adds focused blemanager helpers.
 extension BLEManager: CBCentralManagerDelegate {
   nonisolated func centralManagerDidUpdateState(_ central: CBCentralManager) {
     Task { @MainActor in
@@ -255,6 +284,7 @@ extension BLEManager: CBCentralManagerDelegate {
   }
 }
 
+/// Adds focused blemanager helpers.
 extension BLEManager: CBPeripheralDelegate {
   nonisolated func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
     Task { @MainActor in
@@ -353,6 +383,7 @@ extension BLEManager: CBPeripheralDelegate {
   }
 }
 
+/// Represents hex.
 enum Hex {
   static func format(_ bytes: [UInt8]) -> String {
     bytes.map { String(format: "%02X", $0) }.joined(separator: " ")

VeltoKit/BLEButtonDecoder.swift

@@ -2,9 +2,12 @@ import Foundation
 
 /// Przycisk Triki w pakiecie NUS: `22` na [0], przycisk **0/1 na [1]** (edge 0→1).
 public enum BLEButtonDecoder {
+  /// Oczekiwany nagłówek pakietu BLE.
   public static let packetHeader: UInt8 = 0x22
+  /// Indeks bajtu przycisku w pakiecie.
   public static let buttonIndex = 1
 
+  /// Sprawdza, czy bajt reprezentuje stan wciśnięty.
   public static func isPressed(_ byte: UInt8) -> Bool {
     byte == 1
   }

VeltoKit/BLEGyroParser.swift

@@ -3,15 +3,24 @@ import Foundation
 /// Parser BLE: bloki 0x22 0x00, 3× int16 LE, normalizacja / 2000.
 /// Drugi blok w pakiecie = żyroskop (pierwszy = akcelerometr, ignorowany).
 public enum BLEGyroParser {
+  /// Sygnatura nagłówka bloku BLE Triki.
   public static let header: [UInt8] = [0x22, 0x00]
+  /// Rozmiar pojedynczego bloku osi w bajtach.
   public static let blockByteCount = 8
+  /// Domyślny dzielnik normalizacji danych gyro.
   public static let gyroDivisor = 2000.0
+  /// Dzielnik dla danych tilt.
   public static let tiltDivisor = 80.0
+  /// Alias dzielnika używanego do normalizacji.
   public static let normalizeDivisor = gyroDivisor
 
+  /// Znormalizowana próbka osi 3D.
   public struct GyroTriple: Equatable, Sendable {
+    /// Oś X.
     public var x: Double
+    /// Oś Y.
     public var y: Double
+    /// Oś Z.
     public var z: Double
   }
 
@@ -24,6 +33,7 @@ public enum BLEGyroParser {
     return Double(value)
   }
 
+  /// Alias kompatybilności do odczytu surowej osi Y.
   public static func gyroRawYFromPacket(_ data: [UInt8]) -> Double? {
     gyroRawFromPacket(data)
   }
@@ -148,10 +158,12 @@ public enum BLEGyroParser {
     return Int16(bitPattern: lo | (hi << 8))
   }
 
+  /// Normalizuje surową wartość int16 do zakresu roboczego.
   public static func normalize(_ v: Int16, divisor: Double = gyroDivisor) -> Double {
     MotionMath.clamp(Double(v) / divisor)
   }
 
+  /// Skaluje blok tilt do jednostek używanych przez żyroskop.
   public static func scaledTiltBlock(_ block: GyroTriple) -> GyroTriple {
     let scale = gyroDivisor / tiltDivisor
     return GyroTriple(x: block.x * scale, y: block.y * scale, z: block.z * scale)

VeltoKit/ButtonDetector.swift

@@ -2,13 +2,17 @@ import Foundation
 
 /// Wykrywanie kliknięcia z BLE (`0x22`, bajt [1], zbocze 0→1).
 @MainActor
+/// Wykrywa zbocze narastające przycisku w strumieniu BLE.
 final class ButtonDetector {
+  /// Ostatnia wartość bajtu przycisku odebrana z pakietu.
   private(set) var lastSeenButtonByte: UInt8 = 0
   private var lastButton: UInt8 = 0
   private var pendingClick = false
 
+  /// Informuje, czy oczekuje nieodebrany impuls kliknięcia.
   var didClick: Bool { pendingClick }
 
+  /// Przetwarza pojedynczy pakiet BLE i wykrywa zbocze 0→1.
   func process(_ data: [UInt8]) {
     guard !data.isEmpty else { return }
     if data.count > BLEButtonDecoder.buttonIndex, data[0] == BLEButtonDecoder.packetHeader {
@@ -25,6 +29,7 @@ final class ButtonDetector {
     return edge
   }
 
+  /// Resetuje stan detektora kliknięć.
   func reset() {
     lastButton = 0
     lastSeenButtonByte = 0