Agent Rules

https://github.com/steipete/agent-rules
Admin
A collection of reusable rules and knowledge documents for AI coding assistants like Claude Code and...
Tokens:1,345,746
Snippets:13,105
Trust Score:10
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### init(starting:ending:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Initializes a gradient with two colors.

```APIDOC
## [init] convenience init?(starting: NSColor, ending: NSColor)

### Description
Initializes a newly allocated gradient object with two colors.

### Method
init

### Parameters
#### Parameters
- **starting** (NSColor) - Required - The starting color of the gradient.
- **ending** (NSColor) - Required - The ending color of the gradient.

### Return Value
An initialized gradient object, or nil if initialization fails.

```

--------------------------------

### run()

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Documentation for the NSApplication.run() instance method that starts the main event loop.

```APIDOC
## run()

### Description
Starts the main event loop for the application. The loop continues until a `stop(_:)` or `terminate(_:)` message is received. Upon each iteration, the next available event from the window server is stored and dispatched by sending it to `NSApp` using `sendEvent(_:)`.

### Method
Instance Method

### Signature
@MainActor
func run()

### Parameters
None

### Return Value
None

### Discussion
After creating the `NSApplication` object, the `main` function should load your app’s main nib file and then start the event loop by sending the `NSApplication` object a `run()` message. If you create a Cocoa app project in Xcode, this `main` function is implemented for you.

### See Also
- `beginModalSession(for:)` - Runs a given modal session, as defined in a previous invocation of `beginModalSession(for:)`.
- `runModal(for:)` - Starts a modal event loop for the specified window.
- `applicationDidFinishLaunching(Notification)` - Tells the delegate that the app’s initialization is complete but it hasn’t received its first event.
- `nextEvent(matching:until:inMode:dequeue:)` - Returns the next event matching a given mask, or `nil` if no such event is found before a specified expiration date.
- `discardEvents(matching:before:)` - Removes all events matching the given mask and generated before the specified event.
- `currentEvent` - The last event object that the app retrieved from the event queue.
- `isRunning` - A Boolean value indicating whether the main event loop is running.
- `finishLaunching()` - Activates the app, opens any files specified by the `NSOpen` user default, and unhighlights the app’s icon.
- `stop(Any?)` - Stops the main event loop.
- `sendEvent(NSEvent)` - Dispatches an event to other objects.
- `postEvent(NSEvent, atStart: Bool)` - Adds a given event to the receiver’s event queue.
```

--------------------------------

### var layoutMarginsGuide: UILayoutGuide

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

A layout guide representing the view’s margins.

```APIDOC
## Property: layoutMarginsGuide

### Description
A layout guide representing the view’s margins.

### Declaration
`var layoutMarginsGuide: UILayoutGuide`

### Parameters
None

### Return Value
`UILayoutGuide` - The layout margins guide.
```

--------------------------------

### showHelp(_:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

If your project is properly registered, and the necessary keys have been set in the property list, this method launches Help Viewer and displays the first page of your app’s help book.

```APIDOC
## showHelp(_:)

### Description
If your project is properly registered, and the necessary keys have been set in the property list, this method launches Help Viewer and displays the first page of your app’s help book.

### Method
showHelp(_:)

### Parameters
- **sender** (Any?) - Required - The object that sent the command.

### Discussion
For information on how to set up your project to take advantage of having Help Viewer display your help book, see Specifying the Comprehensive Help File.
```

--------------------------------

### Get item replacement directory and generate output filename

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Gets a temporary directory for writing output files using the itemReplacementDirectory constantasi and constructs a filename for a thumbnail by appending " Thumbnail.png" to the source file name. This snippet is a setup step for Action Extensions that need to write files.

```swift
let itemReplacementDirectory = try FileManager.default.url(
for: .itemReplacementDirectory, in: .userDomainMask,
appropriateFor: URL(fileURLWithPath: NSHomeDirectory()), create: true)
let thumbnailFilename = sourceUrl.deletingPathExtension().lastPathComponent + " Thumbnail.png"
```

--------------------------------

### Update suggestions dynamically with ForEach

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Updates search suggestions dynamically by iterating over a model array of suggested searches. If the array starts empty, no suggestions are shown initially; you can update it later, for example to include previous searches.

```swift
ProductList(departmentId: departmentId, productId: $productId)
.searchable(text: $model.searchText)
.searchSuggestions {
    ForEach(model.suggestedSearches) { suggestion in
        Label(suggestion.title, image: suggestion.image)
            .searchCompletion(suggestion.text)
    }
}
```

--------------------------------

### init()

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a key command.

```APIDOC
## init()

### Description
Creates a key command.

### Method
Initializer

### Parameters
None.

### Response
No return value.
```

--------------------------------

### convenience init()

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Initializes a window with default settings. Deprecated.

```APIDOC
## convenience init()

### Description
Initializes a window with default settings. Deprecated.

### Method
init

### Parameters
None

```

--------------------------------

### Start Live Activity for order preparation in SwiftUI

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Shows the setup and request of a Live Activity for tracking order preparation time. It creates the activity attributes, content state with a 60-second timer range, and requests the activity. Includes error handling and a notification after a successful request.

```swift
let timerSeconds = 60
let activityAttributes = TruckActivityAttributes(
orderID: String(order.id.dropFirst(6)),
order: order.donuts.map(\.id),
sales: order.sales,
activityName: "Order preparation activity."
)

let future = Date(timeIntervalSinceNow: Double(timerSeconds))

let initialContentState = TruckActivityAttributes.ContentState(timerRange: Date.now...future)

let activityContent = ActivityContent(state: initialContentState, staleDate: Calendar.current.date(byAdding: .minute, value: 2, to: Date())!)

do {

pushType: nil)
print(" Requested MyActivity live activity. ID: \(myActivity.id)")
postNotification()
} catch let error {
print("Error requesting live activity: \(error.localizedDescription)")
}
```

--------------------------------

### finishLaunching()

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Documentation for the NSApplication.finishLaunching() instance method, including its signature, behavior, and related methods.

```APIDOC
## finishLaunching()

### Description
Activates the app, opens any files specified by the `NSOpen` user default, and unhighlights the app’s icon. The `run()` method calls this method before it starts the event loop. When this method begins, it posts a `willFinishLaunchingNotification` to the default notification center. If you override `finishLaunching()`, the subclass method should invoke the superclass method.

### Method
Instance Method

### Signature
@MainActor
func finishLaunching()

### Parameters
None

### Return Value
None

### Discussion
- The `run()` method calls this method before it starts the event loop.
- When this method begins, it posts a `willFinishLaunchingNotification` to the default notification center.
- If you override `finishLaunching()`, the subclass method should invoke the superclass method.

### See Also
- `func applicationWillFinishLaunching(Notification)` - Tells the delegate that the app’s initialization is about to complete.
- `func applicationDidFinishLaunching(Notification)` - Tells the delegate that the app’s initialization is complete but it hasn’t received its first event.
- `func discardEvents(matching: NSEvent.EventTypeMask, before: NSEvent?)` - Removes all events matching the given mask and generated before the specified event.
- `var currentEvent: NSEvent?` - The last event object that the app retrieved from the event queue.
- `var isRunning: Bool` - A Boolean value indicating whether the main event loop is running.
- `func run()` - Starts the main event loop.
- `func stop(Any?)` - Stops the main event loop.
- `func sendEvent(NSEvent)` - Dispatches an event to other objects.
- `func postEvent(NSEvent, atStart: Bool)` - Adds a given event to the receiver’s event queue.
```

--------------------------------

### Getting Document Metadata

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Properties for getting document metadata.

```APIDOC
## var fileURL: URL?

### Description
The location of the document’s on-disk representation.

### Method
fileURL

### Parameters
None

### Response
Returns the URL of the document's file.
```

```APIDOC
## var isEntireFileLoaded: Bool

### Description
A Boolean value that indicates whether the document’s file is completely loaded into memory.

### Method
isEntireFileLoaded

### Parameters
None

### Response
Returns a Boolean value.
```

```APIDOC
## var fileModificationDate: Date?

### Description
The last-known modification date of the document’s on-disk representation.

### Method
fileModificationDate

### Parameters
None

### Response
Returns the modification date.
```

```APIDOC
## var keepBackupFile: Bool

### Description
A Boolean value that indicates whether the document archives previously saved versions of the document.

### Method
keepBackupFile

### Parameters
None

### Response
Returns a Boolean value.
```

```APIDOC
## var isDraft: Bool

### Description
A Boolean value that indicates whether the document is a draft that the user has not yet saved.

### Method
isDraft

### Parameters
None

### Response
Returns a Boolean value.
```

```APIDOC
## var fileType: String?

### Description
The name of the document type, as specified in the app’s information property-list file.

### Method
fileType

### Parameters
None

### Response
Returns the document type.
```

```APIDOC
## var isDocumentEdited: Bool

### Description
A Boolean value that indicates whether the document has unsaved changes.

### Method
isDocumentEdited

### Parameters
None

### Response
Returns a Boolean value.
```

```APIDOC
## var isInViewingMode: Bool

### Description
A Boolean value that indicates whether the document is in read-only mode.

### Method
isInViewingMode

### Parameters
None

### Response
Returns a Boolean value.
```

--------------------------------

### convenience init(title:image:target:action:menu:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a plain-style item using the specified title, image, target, action, and context menu.

```APIDOC
## convenience init(title: String?, image: UIImage?, target: AnyObject?, action: Selector?, menu: UIMenu?)

### Description
Creates a plain-style item using the specified title, image, target, action, and context menu.

### Method
Initializer

### Parameters
- **title** (String?) - Optional. The title of the item.
- **image** (UIImage?) - Optional. The image of the item.
- **target** (AnyObject?) - Optional. The object that receives the action.
- **action** (Selector?) - Optional. The selector defining the action message.
- **menu** (UIMenu?) - Optional. The context menu for the item.
```

--------------------------------

### Getting Nib and Storyboard Information

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Properties for getting nib and storyboard information.

```APIDOC
## var owner: AnyObject?

### Description
The owner of the nib file containing the window managed by the receiver.

### Type
AnyObject?
```

```APIDOC
## var storyboard: NSStoryboard?

### Description
The storyboard file from which the window controller was loaded.

### Type
NSStoryboard?
```

```APIDOC
## var windowNibName: NSNib.Name?

### Description
The name of the nib file that stores the window associated with the receiver.

### Type
NSNib.Name?
```

```APIDOC
## var windowNibPath: String?

### Description
The full path of the nib file that stores the window associated with the receiver.

### Type
String?
```

--------------------------------

### Assigning an NSImage to a CALayer with recommended scale

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Use this method to assign an NSImage to a CALayer's contents with the correct scale factor. Start by obtaining the window's backing scale factorchen, then recommend the actual scale for the image, then get the layer contents and set both contents and scale on the layer. This ensures the image adheres to the layer's gravity modes, whereas direct assignment only supports resize, resizeAspect, and resizeAspectFill.

```objective-c
static void updateLayerWithImageInWindow1(NSImage *image, CALayer *layer, NSWindow *window) {
CGFloat desiredScaleFactor = [window backingScaleFactor];
CGFloat actualScaleFactor = [image recommendedLayerContentsScale:desiredScaleFactor];

id layerContents = [image layerContentsForContentsScale:actualScaleFactor];

[layer setContents:layerContents];
[layer setContentsScale:actualScaleFactor];
}
```

--------------------------------

### applicationWillFinishLaunching(_:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Documentation for the NSApplicationDelegate method applicationWillFinishLaunching(_:).

```APIDOC
## applicationWillFinishLaunching(_:)

### Description
Tells the delegate that the app's initialization is about to complete.

### Method
Instance Method

### Signature
@MainActor optional func applicationWillFinishLaunching(_ notification: Notification)

### Parameters
- **notification** (Notification) - A notification named `willFinishLaunchingNotification`. Calling the `object` method of this notification returns the `NSApplication` object itself.

### Mentioned in
Supporting Continuity Camera in Your Mac App

### See Also
- `func applicationWillBecomeActive(Notification)` - Tells the delegate that the app is about to become active.
- `func finishLaunching()` - Activates the app, opens any files specified by the `NSOpen` user default, and unhighlights the app's icon.
- `func applicationDidFinishLaunching(Notification)` - Tells the delegate that the app's initialization is complete but it hasn't received its first event.
```

--------------------------------

### convenience init(title:style:target:action:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates an item using the specified title, style, target, and action.

```APIDOC
## convenience init(title: String?, style: UIBarButtonItem.Style, target: Any?, action: Selector?)

### Description
Creates an item using the specified title, style, target, and action.

### Method
Initializer

### Parameters
- **title** (String?) - Optional. The title of the item.
- **style** (UIBarButtonItem.Style) - Required. The style of the item.
- **target** (Any?) - Optional. The object that receives the action.
- **action** (Selector?) - Optional. The selector defining the action message.
```

--------------------------------

### Define Equal Spacing with NSLayoutGuide (Swift and Objective-C)

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Creates two layout guides to define equal spacing between three views. The guides are added to the view and constrained to have equal widths, then the save, cancel, and clear buttons are pinned to the guides' leading/trailing anchors.

```Swift
let space1 = NSLayoutGuide()
view.addLayoutGuide(space1)

let space2 = NSLayoutGuide()
view.addLayoutGuide(space2)

space1.widthAnchor.constraintEqualToAnchor(space2.widthAnchor).active = true
saveButton.trailingAnchor.constraintEqualToAnchor(space1.leadingAnchor).active = true
cancelButton.leadingAnchor.constraintEqualToAnchor(space1.trailingAnchor).active = true
cancelButton.trailingAnchor.constraintEqualToAnchor(space2.leadingAnchor).active = true
clearButton.leadingAnchor.constraintEqualToAnchor(space2.trailingAnchor).active = true
```

```Objective-C
NSLayoutGuide *space1 = [[NSLayoutGuide alloc]init];
[self.view addLayoutGuide:space1];

NSLayoutGuide *space2 = [[NSLayoutGuide alloc] init];
[self.view addLayoutGuide:space2];

[space1.widthAnchor constraintEqualToAnchor:space2.widthAnchor].active = YES;
[self.saveButton.trailingAnchor constraintEqualToAnchor:space1.leadingAnchor].active = YES;
[self.cancelButton.leadingAnchor constraintEqualToAnchor:space1.trailingAnchor].active = YES;
[self.cancelButton.trailingAnchor constraintEqualToAnchor:space2.leadingAnchor].active = YES;
[self.clearButton.leadingAnchor constraintEqualToAnchor:space2.trailingAnchor].active = YES;
```

--------------------------------

### convenience init(image:style:target:action:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates an item using the specified image, style, target, and action.

```APIDOC
## convenience init(image: UIImage?, style: UIBarButtonItem.Style, target: Any?, action: Selector?)

### Description
Creates an item using the specified image, style, target, and action.

### Method
Initializer

### Parameters
- **image** (UIImage?) - Optional. The image of the item.
- **style** (UIBarButtonItem.Style) - Required. The style of the item.
- **target** (Any?) - Optional. The object that receives the action.
- **action** (Selector?) - Optional. The selector defining the action message.
```

--------------------------------

### scaledToFill3D() Example

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Use this SwiftUI example to scale a 3D model to fill its parent while maintaining its 3D aspect ratio. The `scaledToFill3D()` method is equivalent to `aspectRatio3D(nil, contentMode: .fill)`. The example uses a `Model3D` with a placeholder `ProgressView` and applies frame and border modifiers.

```swift
Model3D(named: "Sphere") { resolved in
    resolved
        .resizable()
        .scaledToFill3D()
} placeholder: {
    ProgressView()
}
.frame(width: 300, height: 100)
.frame(depth: 300)
.border(Color(white: 0.75))
```

--------------------------------

### scaledToFit3D() Example

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Use this SwiftUI example to scale a 3D model to fit within its parent while maintaining its 3D aspect ratio. The `scaledToFit3D()` method is equivalent to `aspectRatio3D(nil, contentMode: .fit)`. The example uses a `Model3D` with a placeholder `ProgressView` and applies frame and border modifiers.

```swift
Model3D(named: "Plane") { resolved in
    resolved
        .resizable()
        .scaledToFit3D()
} placeholder: {
    ProgressView()
}
.frame(width: 400, height: 400)
.frame(depth: 200)
.border(Color(white: 0.75))
```

--------------------------------

### convenience init(for: any PersistentModel.Type..., migrationPlan: (any SchemaMigrationPlan.Type)?, configurations: ModelConfiguration...) throws

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftdata.md

Convenience initializer that creates a model container using model types, a migration plan, and configurations.

```APIDOC
## convenience init(for: any PersistentModel.Type..., migrationPlan: (any SchemaMigrationPlan.Type)?, configurations: ModelConfiguration...) throws

### Description
Creates a model container using the specified model types, migration plan, and zero or more configurations.

### Method
Initializer

### Parameters
- **modelTypes** (any PersistentModel.Type...) - Required - The model types to include in the container.
- **migrationPlan** ((any SchemaMigrationPlan.Type)?) - Required - The plan that describes the evolution of your app's schema and how to migrate between specific versions.
- **configurations** (ModelConfiguration...) - Required - Zero or more configurations that describe how to manage the persisted data for specific groups of models.

### Return Value
A model container instance.
```

--------------------------------

### convenience init(for: Schema, migrationPlan: (any SchemaMigrationPlan.Type)?, configurations: ModelConfiguration...) throws

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftdata.md

Convenience initializer that creates a model container using a schema, migration plan, and configurations.

```APIDOC
## convenience init(for: Schema, migrationPlan: (any SchemaMigrationPlan.Type)?, configurations: ModelConfiguration...) throws

### Description
Creates a model container using the specified schema, migration plan, and zero or more configurations.

### Method
Initializer

### Parameters
- **schema** (Schema) - Required - The schema that maps your app's model classes to the associated data in the app's persistent storage.
- **migrationPlan** ((any SchemaMigrationPlan.Type)?) - Required - The plan that describes the evolution of your app's schema and how to migrate between specific versions.
- **configurations** (ModelConfiguration...) - Required - Zero or more configurations that describe how to manage the persisted data for specific groups of models.

### Return Value
A model container instance.
```

--------------------------------

### addLayoutGuide(_:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Adds the specified layout guide to the view. This method adds the guide to the view's layoutGuides array and sets its owningView property.

```APIDOC
## [Instance Method] addLayoutGuide(_:)

### Description
Adds the specified layout guide to the view. This method adds the guide to the end of the view's `layoutGuides` array and assigns the view to the guide's `owningView` property.

### Method
Instance Method

### Declaration
@MainActor
func addLayoutGuide(_ layoutGuide: UILayoutGuide)

### Parameters
- **layoutGuide** (UILayoutGuide) - Required - The layout guide to be added.

### Discussion
This method adds the specified layout guide to the end of the view's `layoutGuides` array. It also assigns the view to the guide's `owningView` property. Each guide can have only one owning view. After the guide has been added to a view, it can participate in Auto Layout constraints with that view's hierarchy.

### See Also
- `var layoutGuides: [UILayoutGuide]` - The array of layout guide objects owned by this view.
- `var layoutMarginsGuide: UILayoutGuide` - A layout guide representing the view's margins.
- `var readableContentGuide: UILayoutGuide` - A layout guide representing an area with a readable width within the view.
- `func removeLayoutGuide(UILayoutGuide)` - Removes the specified layout guide from the view.
```

--------------------------------

### convenience init(image:landscapeImagePhone:style:target:action:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates an item using the specified images, style, target, and action.

```APIDOC
## convenience init(image: UIImage?, landscapeImagePhone: UIImage?, style: UIBarButtonItem.Style, target: Any?, action: Selector?)

### Description
Creates an item using the specified images, style, target, and action.

### Method
Initializer

### Parameters
- **image** (UIImage?) - Optional. The image of the item.
- **landscapeImagePhone** (UIImage?) - Optional. The landscape image for iPhone.
- **style** (UIBarButtonItem.Style) - Required. The style of the item.
- **target** (Any?) - Optional. The object that receives the action.
- **action** (Selector?) - Optional. The selector defining the action message.
```

--------------------------------

### presentationBackground(_:) example

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Sets the presentation background of the enclosing sheet using a shape style. The example uses the `thick` material as the sheet background.

```swift
struct ContentView: View {
    @State private var showSettings = false

    var body: some View {
        Button("View Settings") {
            showSettings = true
        }
        .sheet(isPresented: $showSettings) {
            SettingsView()
                .presentationBackground(.thickMaterial)
        }
    }
}
```

--------------------------------

### convenience init(systemItem:primaryAction:menu:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates an item using the specified system item, primary action, and context menu.

```APIDOC
## convenience init(systemItem: UIBarButtonItem.SystemItem, primaryAction: UIAction?, menu: UIMenu?)

### Description
Creates an item using the specified system item, primary action, and context menu.

### Method
Initializer

### Parameters
- **systemItem** (UIBarButtonItem.SystemItem) - Required. The system item to use.
- **primaryAction** (UIAction?) - Optional. The primary action associated with the item.
- **menu** (UIMenu?) - Optional. The context menu for the item.
```

--------------------------------

### presentationCornerRadius(_:) example

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Use this modifier to change the corner radius of a presentation. The example shows a sheet with medium and large detents and a corner radius of 21.

```swift
struct ContentView: View {
    @State private var showSettings = false

    var body: some View {
        Button("View Settings") {
            showSettings = true
        }
        .sheet(isPresented: $showSettings) {
            SettingsView()
                .presentationDetents([.medium, .large])
                .presentationCornerRadius(21)
        }
    }
}
```

--------------------------------

### Simple State Example with @State

Source: https://github.com/steipete/agent-rules/blob/main/docs/modern-swift.md

Use @State for local, ephemeral view state. This example shows a counter view with a button that increments the count.

```swift
struct CounterView: View {
    @State private var count = 0
    
    var body: some View {
        VStack {
            Text("Count: \(count)")
            Button("Increment") { 
                count += 1 
            }
        }
    }
}
```

--------------------------------

### openApplication(at:configuration:completionHandler:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Launches the app at the specified URL and asynchronously reports back on the app’s status.

```APIDOC
## openApplication(at:configuration:completionHandler:)

### Description
Launches the app at the specified URL and asynchronously reports back on the app’s status.

### Method
Instance Method

### Endpoint
`openApplication(at applicationURL: URL, configuration: NSWorkspace.OpenConfiguration, completionHandler: ((NSRunningApplication?, Error?) -> Void)? = nil)`

### Parameters
- **applicationURL** (URL) - Required - A URL specifying the location of the app in the file system.
- **configuration** (NSWorkspace.OpenConfiguration) - Required - The options that indicate how you want to launch the app.
- **completionHandler** (closure) - Optional - The completion handler block to call asynchronously with the results. AppKit executes the completion handler on a concurrent queue. The handler block has no return value and takes the following parameters:
  - **app** (NSRunningApplication?) - On success, this parameter contains a reference to the launched app. If the app wasn’t launched, this parameter is `nil`.
  - **error** (Error?) - On failure, this parameter contains an `NSError` object indicating the reason for the failure. If the app launched successfully, this parameter is `nil`.
```

--------------------------------

### DefaultStore.init(ModelConfiguration:migrationPlan:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftdata.md

Initializes a DefaultStore instance with a model configuration and an optional migration plan.

```APIDOC
## [INIT] DefaultStore.init(ModelConfiguration, migrationPlan:)

### Description
Creates a data store with the given model configuration and an optional migration plan.

### Method
Initializer

### Signature
`convenience init(_ configuration: ModelConfiguration, migrationPlan: (any SchemaMigrationPlan.Type)?) throws`

### Parameters
- **configuration** (ModelConfiguration) - Required - The model configuration for the store.
- **migrationPlan** ((any SchemaMigrationPlan.Type)?) - Optional - The migration plan to use for the store.

### Throws
An error if the store cannot be created.

### Example
```swift
let store = try DefaultStore(ModelConfiguration(schema: schema), migrationPlan: MyMigrationPlan.self)
```
```

--------------------------------

### Install agent-rules slash commands

Source: https://github.com/steipete/agent-rules/blob/main/global-rules/steipete-mcps.md

Clones the agent-rules repository and runs the installation script to set up 20+ development slash commands for Claude Code.

```bash
git clone https://github.com/steipete/agent-rules.git
cd agent-rules
bash install-project-rules.sh
```

--------------------------------

### Configure and start NSMetadataQuery for iCloud document discovery

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Configure and start an NSMetadataQuery to watch for document metadata changes in an iCloud container. The query searches both ubiquitous data and documents scopes, filters for files with the .sicd extension, and sorts by file name. After starting, the query posts NSMetadataQueryDidFinishGathering and NSMetadataQueryDidUpdate notifications.

```swift
metadataQuery.notificationBatchingInterval = 1
metadataQuery.searchScopes = [NSMetadataQueryUbiquitousDataScope, NSMetadataQueryUbiquitousDocumentsScope]
metadataQuery.predicate = NSPredicate(format: "%K LIKE %@", NSMetadataItemFSNameKey, "*." + Document.extensionName)
metadataQuery.sortDescriptors = [NSSortDescriptor(key: NSMetadataItemFSNameKey, ascending: true)]
metadataQuery.start()
```

--------------------------------

### convenience init(title:style:actions:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a peek quick action group using a specified title, style, and array of peek quick actions.

```APIDOC
## Initializer

### Description
Creates a peek quick action group using a specified title, style, and array of peek quick actions.

### Declaration
```swift
convenience init(title: String, style: UIPreviewAction.Style, actions: [UIPreviewAction])
```

### Parameters
- **title** (String) - The title of the group.
- **style** (UIPreviewAction.Style) - The style of the group.
- **actions** ([UIPreviewAction]) - An array of UIPreviewAction instances to include in the group.

### Discussion
Use this initializer to create a group of preview actions. The group appears as a single option in a peek quick action sheet, and selecting it opens a submenu with the child actions.

### Availability
- iOS 9.0–13.0 Deprecated
- iPadOS 9.0–13.0 Deprecated
- Mac Catalyst 13.1–13.1 Deprecated
- tvOS 9.0–13.0 Deprecated
```

--------------------------------

### readableContentGuide

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

A layout guide representing an area with a readable width within the view. Use this guide to lay out a single column of text or determine optimal column width.

```APIDOC
## [Instance Property] readableContentGuide

### Description
A layout guide representing an area with a readable width within the view. This guide defines an area that can easily be read without forcing users to move their head to track the lines.

### Declaration
@MainActor
var readableContentGuide: UILayoutGuide { get }

### Discussion
The readable content area follows these rules:
1. The readable content guide never extends beyond the view's layout margin guide.
2. The readable content guide is vertically centered inside the layout margin guide.
3. The readable content guide's width is equal to or less than the readable width defined for the current dynamic text size.

Use the readable content guide to lay out a single column of text. If you are laying out multiple columns, you can use the guide's width to determine the optimal width for your columns.

### See Also
- `func addLayoutGuide(UILayoutGuide)` - Adds the specified layout guide to the view.
- `var layoutGuides: [UILayoutGuide]` - The array of layout guide objects owned by this view.
- `var layoutMarginsGuide: UILayoutGuide` - A layout guide representing the view's margins.
- `func removeLayoutGuide(UILayoutGuide)` - Removes the specified layout guide from the view.
```

--------------------------------

### showHelp(_:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Launches Help Viewer and displays the first page of your app's help book.

```APIDOC
## showHelp(_:)

### Description
If your project is properly registered, and the necessary keys have been set in the property list, this method launches Help Viewer and displays the first page of your app’s help book.

### Method
showHelp(_:)
```

--------------------------------

### convenience init(title:image:primaryAction:menu:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a plain-style item using the specified title, image, primary action, and context menu.

```APIDOC
## convenience init(title: String?, image: UIImage?, primaryAction: UIAction?, menu: UIMenu?)

### Description
Creates a plain-style item using the specified title, image, primary action, and context menu.

### Method
Initializer

### Parameters
- **title** (String?) - Optional. The title of the item.
- **image** (UIImage?) - Optional. The image of the item.
- **primaryAction** (UIAction?) - Optional. The primary action associated with the item.
- **menu** (UIMenu?) - Optional. The context menu for the item.
```

--------------------------------

### CustomDebugStringConvertible Example for debugDescription

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftdata.md

Shows how to use the debugDescription property by conforming to CustomDebugStringConvertible. The example defines a Point struct and prints its debug description using String(reflecting:).

```swift
struct Point: CustomDebugStringConvertible {
let x: Int, y: Int

var debugDescription: String {
return "(\(x), \(y))"
}
}

let p = Point(x: 21, y: 30)
let s = String(reflecting: p)
print(s)
// Prints "(21, 30)"
```

--------------------------------

### SwiftUI navigationTransition(_:) example

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Add this modifier to a view that appears within a NavigationStack or a sheet, outside of any containers such as VStack. The example shows a NavigationLink with a zoom transition and a matched transition source.

```swift
struct ContentView: View {
    @Namespace private var namespace
    var body: some View {
        NavigationStack {
            NavigationLink {
                DetailView()
                    .navigationTransition(.zoom(sourceID: "world", in: namespace))
            } label: {
                Image(systemName: "globe")
                    .matchedTransitionSource(id: "world", in: namespace)
            }
        }
    }
}
```

--------------------------------

### layoutGuide(for:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Instance method that returns a layout guide for the specified layout region. The method is marked as @MainActor @preconcurrency and is available in Mac Catalyst.

```APIDOC
## [Instance Method] layoutGuide(for:)

### Description
Returns a layout guide for the specified layout region.

### Method
Instance Method

### Declaration
@MainActor @preconcurrency func layoutGuide(for region: UILayoutGuide)

### Parameters
- **region** (UILayoutGuide) - The layout region for which to return a layout guide.

### Return Value
A layout guide for the specified region.

### Discussion
This method is used to access layout guides for specific regions of the view. The exact behavior and usage are not detailed in the provided documentation.

### See Also
- `struct LayoutRegion` - A structure that defines a layout region.

### Availability
Mac Catalyst
```

--------------------------------

### Align Feedback Filter: Instantiate NSAlignmentFeedbackFilter in Swift and Objective-C

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Creates an instance of NSAlignmentFeedbackFilter for providing alignment feedback. The Swift example uses with a constant declaration, the Objective-C example uses with an instance variable assignment.

```swift
let self.feedbackFilter = NSAlignmentFeedbackFilter()
```

```objectivec
self.feedbackFilter = [NSAlignmentFeedbackFilter new];
```

--------------------------------

### init(for: Schema, migrationPlan: (any SchemaMigrationPlan.Type)?, configurations: [ModelConfiguration]) throws

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftdata.md

Initializer that creates a model container with a schema, migration plan, and configurations.

```APIDOC
## init(for: Schema, migrationPlan: (any SchemaMigrationPlan.Type)?, configurations: [ModelConfiguration]) throws

### Description
Creates a model container using the specified schema, migration plan, and configurations.

### Method
Initializer

### Parameters
- **schema** (Schema) - Required - The schema that maps your app's model classes to the associated data in the app's persistent storage.
- **migrationPlan** ((any SchemaMigrationPlan.Type)?) - Required - The plan that describes the evolution of your app's schema and how to migrate between specific versions.
- **configurations** ([ModelConfiguration]) - Required - The configurations that describe how to manage the persisted data for specific groups of models.

### Return Value
A model container instance.
```

--------------------------------

### init(placeholderItem: Any)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Initializes and returns a provider object with the specified placeholder data.

```APIDOC
## [INIT] init(placeholderItem: Any)

### Description
Initializes and returns a provider object with the specified placeholder data.

### Method
INIT

### Parameters
#### Parameters
- **placeholderItem** (Any) - Required - The placeholder data to use.

### Response
#### Success Response
- **UIActivityItemProvider** - The initialized provider object.

```

--------------------------------

### occlusionState

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Property to get the occlusion state.

```APIDOC
## [Property] occlusionState

### Description
The occlusion state of the app.

### Property
`var occlusionState: NSApplication.OcclusionState`

### Return Value
- **NSApplication.OcclusionState** - The occlusion state of the app.
```

--------------------------------

### context

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Property to get the graphics context.

```APIDOC
## [Property] context

### Description
The graphics context associated with the app.

### Property
`var context: NSGraphicsContext?`

### Return Value
- **NSGraphicsContext?** - The graphics context associated with the app, or `nil` if none.
```

--------------------------------

### convenience init(input:modifierFlags:action:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a key command that matches the specified input.

```APIDOC
## convenience init(input:modifierFlags:action:)

### Description
Creates a key command that matches the specified input.

### Method
Initializer

### Parameters
- **input** (String) - Required - The string of characters corresponding to the keys that must be pressed.
- **modifierFlags** (UIKeyModifierFlags) - Required - The bit mask of modifier flags that must be pressed.
- **action** (Selector) - Required - The action method to be called when the key command is triggered.

### Response
No return value.
```

--------------------------------

### init(name:bundle:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates and returns a storyboard object for the specified resource file.

```APIDOC
## init(name:bundle:)

### Description
Creates and returns a storyboard object for the specified resource file.

### Method
init

### Parameters
- **name** (String) - Required - The name of the storyboard resource file without the .storyboard extension.
- **bundle** (Bundle?) - Optional - The bundle containing the storyboard file, or nil to use the main bundle.

### Return Value
A new UIStoryboard object.

### Example
```swift
let storyboard = UIStoryboard(name: "Main", bundle: nil)
```
```

--------------------------------

### startAnimating()

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Starts the animation of the progress indicator.

```APIDOC
## startAnimating()

### Description
Starts the animation of the progress indicator.

### Method
func

### Parameters
None

### Return Value
Void

### Example
```swift
activityIndicator.startAnimating()
```
```

--------------------------------

### init(nibName:bundle:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a view controller with the nib file in the specified bundle.

```APIDOC
## init(nibName:bundle:)

### Description
Creates a view controller with the nib file in the specified bundle.

### Method
init

### Parameters
- **nibName** (String?) - Optional - The name of the nib file.
- **bundle** (Bundle?) - Optional - The bundle containing the nib file.

### Return Value
A newly initialized view controller.
```

--------------------------------

### currentDirectory

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

The starting directory for the Open panel.

```APIDOC
## [property] currentDirectory

### Description
The directory path to be used as the starting point in the Open panel.

### Declaration
`var currentDirectory: String?`
```

--------------------------------

### init()

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Creates an environment values instance.

```APIDOC
## init()

### Description
Creates an environment values instance.

### Declaration
`init()`

```

--------------------------------

### Check prerequisites and API keys

Source: https://github.com/steipete/agent-rules/blob/main/global-rules/steipete-mcps.md

Check that jq, Node.js 20+, and ollama are installed, installing jq and ollama via Homebrew if missing. Also verify that required API keys (OPENAI_API_KEY, GITHUB_PERSONAL_ACCESS_TOKEN, FIRECRAWL_API_KEY) are present in ~/.zshrc.

```bash
command -v jq || brew install jq
command -v node || echo "Need Node.js 20+"
command -v ollama || brew install ollama

grep "OPENAI_API_KEY\|GITHUB_PERSONAL_ACCESS_TOKEN\|FIRECRAWL_API_KEY" ~/.zshrc
```

--------------------------------

### init(_:systemImage:content:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Creates a menu bar extra with a system image label and accessibility title.

```APIDOC
## init(_:systemImage:content:)

### Description
Creates a menu bar extra with a system image to use as the item's label. The provided title will be used by the accessibility system.

### Method
`init(_:systemImage:content:)`

### Parameters
- **title** (Text) - Required - The title to use for accessibility.
- **systemImage** (String) - Required - The name of the system image to use as the label.
- **content** (() -> Content) - Required - The content of the menu bar extra.

### Example
```swift
MenuBarExtra("Utility App", systemImage: "hammer") {
    AppMenu()
}
```
```

--------------------------------

### dragContainer(for:id:in:_:) example with draggable sections

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Example from the dragContainer(for:id:in:_:) documentation. Shows a container with three draggable sections, each with a custom payload computed from the current selection. The code includes the view body, the dragContainer closure, and supporting types (Fruit, FruitSection, BerriesSectionView). Note that the example is incomplete: it references undefined properties and methods (e.g., sectionIDsToDrag, sections(identifiers:), selectedFruits, sectionIdentifiersOfSelectedFruits, uniqueSections(from:), BerryView) and the dragContainer closure is not fully shown.

```swift
var berries: [Fruit]
var citruses: [Fruit]
var tropical: [Fruit]

@State var selectedSections: [UUID]
@State var selectedFruits: [UUID]

var body: some View {
ScrollView {
VStack {
BerriesSectionView(FruitSection(berries))
.draggable(containerItemID: FruitSection.berries)
CitrusSectionView(FruitSection(citruses))
.draggable(containerItemID: FruitSection.citruses)
TropicalSectionView(FruitSection(tropical))
.draggable(containerItemID: FruitSection.tropical)
}
}
.dragContainer { draggedSectionID in
let identifiers = sectionIDsToDrag(for: draggedSectionID)
return sections(identifiers: identifiers)
}
}

// an unselected section is dragged
if !selectedSections.contains(draggedID) { return [draggedID] }

// a selected section is dragged
let payloadIDs = selectedSections + sectionIdentifiersOfSelectedFruits()
return uniqueSections(from: payloadIDs)
}

struct Fruit {
let id: UUID
}

struct FruitSection: Transferable {
static let berries: UUID
static let citruses: UUID
static let tropical: UUID

let id: UUID
var fruits: [Fruit]
}

struct BerriesSectionView: View {
var section: FruitSection

var body: some View {
HStack {
ForEach(section.fruit) { berry in
BerryView(berry)
}
}
}
}
```

--------------------------------

### init?(coder:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/uikit.md

Creates a key command from data in an unarchiver.

```APIDOC
## init?(coder:)

### Description
Creates a key command from data in an unarchiver.

### Method
Initializer

### Parameters
- **coder** (NSCoder) - Required - The unarchiver object that contains the data.

### Response
An optional UIKeyCommand instance.
```

--------------------------------

### GET /NSApplication.ActivationPolicy

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Describes the NSApplication.ActivationPolicy enumeration and its cases.

```APIDOC
## [GET] /NSApplication.ActivationPolicy

### Description
Enumeration of activation policies that control whether and how an app may be activated.

### Method
GET

### Endpoint
/NSApplication.ActivationPolicy

### Parameters
#### Path Parameters
- **none** - This is an enumeration type.

### Response
#### Success Response (200)
- **regular** (case) - The application is an ordinary app that appears in the Dock and may have a user interface.
- **accessory** (case) - The application doesn’t appear in the Dock and doesn’t have a menu bar, but it may be activated programmatically or by clicking on one of its windows.
- **prohibited** (case) - The application doesn’t appear in the Dock and may not create windows or be activated.

#### Response Example
```json
{
  "cases": ["regular", "accessory", "prohibited"]
}
```
```

--------------------------------

### init(_:value:formatter:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Create an instance which binds over an arbitrary type, `V`.

```APIDOC
## init(_:value:formatter:)

### Description
Create an instance which binds over an arbitrary type, `V`.

### Method
Initializer

### Parameters
- **titleKey** (LocalizedStringKey) - Required - The key for the localized title of the text field.
- **value** (Binding<V>) - Required - The value to display and edit.
- **formatter** (Formatter) - Required - The formatter to use for converting the value to a string.

### Return Value
A text field view.

```

--------------------------------

### openGLVersion

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Gets the OpenGL version supported by the system.

```APIDOC
## openGLVersion

### Description
The version of OpenGL.

### Method
Static Property

### Signature
`static var openGLVersion: (major: GLint, minor: GLint)`

### Return Value
A tuple containing the major and minor version numbers.
```

--------------------------------

### pixelFormat

Source: https://github.com/steipete/agent-rules/blob/main/docs/appkit.md

Gets the pixel format of the OpenGL context.

```APIDOC
## pixelFormat

### Description
The pixel format of the OpenGL context.

### Method
Instance Property

### Signature
`var pixelFormat: NSOpenGLPixelFormat`

### Return Value
The pixel format of the context.
```

--------------------------------

### init(_:content:)

Source: https://github.com/steipete/agent-rules/blob/main/docs/swiftui.md

Creates a menu bar extra with a localized string label and content.

```APIDOC
## init(_:content:)

### Description
Creates a menu bar extra with a key for a localized string to use as the label. The extra defines the primary scene of an `App`.

### Method
`init(_:content:)`

### Parameters
- **titleKey** (LocalizedStringKey) - Required - The key for a localized string to use as the label.
- **content** (() -> Content) - Required - The content of the menu bar extra.

### Example
```swift
MenuBarExtra("App Menu Bar Extra", systemImage: "star") {
    StatusMenu()
}
```
```
Tokens:
Raw