thatfactory · backslash-f · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1 @@
+AgentGuidelines/Configurations/Swift/.editorconfig
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,2 @@
+# Synced from thatfactory/agent-guidelines; keep tracked but collapse GitHub diffs.
+AgentGuidelines/** linguist-generated
diff --git a/.github/workflows/ci-pr.yml b/.github/workflows/ci-pr.yml
@@ -0,0 +1,33 @@
+---
+name: Pull Request CI
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  format:
+    name: Swift Format
+    runs-on: [self-hosted, macOS]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      - name: Lint Swift Sources
+        run: AgentGuidelines/Scripts/swift_format.sh lint-strict Sources Tests
+
+  test:
+    name: Test
+    runs-on: [self-hosted, macOS]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+        with:
+          clean: true
+
+      - name: Run Tests
+        run: swift test -v
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,34 @@
+---
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  format:
+    name: Swift Format
+    runs-on: [self-hosted, macOS]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+
+      - name: Lint Swift Sources
+        run: AgentGuidelines/Scripts/swift_format.sh lint-strict Sources Tests
+
+  test:
+    name: Test
+    runs-on: [self-hosted, macOS]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+        with:
+          clean: true
+
+      - name: Run Tests
+        run: swift test -v
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
@@ -0,0 +1,23 @@
+---
+name: Nightly Tests
+
+on:
+  schedule:
+    - cron: '0 4 * * *'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nightly_tests:
+    name: Nightly Tests
+    runs-on: [self-hosted, macOS]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+        with:
+          clean: true
+
+      - name: Run Tests
+        run: swift test -v
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,102 @@
+---
+name: Release
+run-name: Release ${{ github.event.release.tag_name }}
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  actions: read
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test Release
+    runs-on: [self-hosted, macOS]
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+        with:
+          clean: true
+
+      - name: Run Tests
+        run: swift test -v
+
+  build_docs:
+    name: Build DocC
+    runs-on: [self-hosted, macOS]
+    needs: test
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+        with:
+          clean: true
+
+      - name: Generate DocC
+        run: |
+          set -euo pipefail
+          swift package --allow-writing-to-directory ./public generate-documentation \
+            --target CloudSaveKit \
+            --disable-indexing \
+            --output-path ./public \
+            --transform-for-static-hosting \
+            --hosting-base-path cloudsavekit
+
+          cat > ./public/index.html <<'INDEX'
+          <!doctype html>
+          <meta http-equiv="refresh" content="0; url=/cloudsavekit/documentation/cloudsavekit/" />
+          <title>CloudSaveKit Documentation</title>
+          INDEX
+
+      - name: Upload Pages Artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: ./public
+          name: github-pages
+
+  deploy_docs:
+    name: Deploy DocC
+    needs: build_docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  notify_package_collection:
+    name: Notify Package Collection
+    runs-on: ubuntu-latest
+    needs: deploy_docs
+    steps:
+      - name: Trigger Swift Package Collection Rebuild
+        env:
+          COLLECTION_REPO: thatfactory/swift-package-collection
+          WORKFLOW_FILE: publish.yml
+          REF: main
+          GH_TOKEN: ${{ secrets.COLLECTION_TRIGGER_TOKEN }}
+          SOURCE_REPO: ${{ github.repository }}
+          SOURCE_VERSION: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${GH_TOKEN:-}" ]; then
+            echo "Missing COLLECTION_TRIGGER_TOKEN secret"
+            exit 1
+          fi
+
+          curl --fail-with-body -sS -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer $GH_TOKEN" \
+            "https://api.github.com/repos/$COLLECTION_REPO/actions/workflows/$WORKFLOW_FILE/dispatches" \
+            -d "{\"ref\":\"$REF\",\"inputs\":{\"source_repo\":\"$SOURCE_REPO\",\"source_version\":\"$SOURCE_VERSION\"}}"
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,11 @@
+.DS_Store
+/.build
+/Packages
+/*.xcodeproj
+*.xcworkspace
+xcuserdata/
+Package.resolved
+DerivedData/
+.swiftpm/configuration/registries.json
+.netrc
+/public-check
diff --git a/.swift-format b/.swift-format
@@ -0,0 +1 @@
+AgentGuidelines/Configurations/Swift/.swift-format
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,47 @@
+# CloudSaveKit
+
+## Context
+
+CloudSaveKit is a pure Swift package that coordinates a host application's durable local store with a private CloudKit database through `CKSyncEngine`. Read [README.md](README.md) and the DocC catalog before changing public behavior.
+
+The package is persistence-, UI-, and application-architecture agnostic. Host applications own their local database, record schemas, merge semantics, and user-facing recovery policy.
+
+## Shared guidelines
+
+Read only the guides relevant to the task:
+
+- [Swift](AgentGuidelines/Guidelines/Swift/Swift.md)
+- [Swift style](AgentGuidelines/Guidelines/Swift/SwiftStyle.md)
+- [Swift format](AgentGuidelines/Guidelines/Swift/SwiftFormat.md)
+- [Unit and integration testing](AgentGuidelines/Guidelines/Testing/UnitTesting.md)
+- [Documentation](AgentGuidelines/Guidelines/Documentation.md)
+- [Logging](AgentGuidelines/Guidelines/Logging.md)
+- [Packages](AgentGuidelines/Guidelines/Packages.md)
+- [CI/CD](AgentGuidelines/Guidelines/CICD.md)
+- [Git repositories and SSH-first cloning](AgentGuidelines/Guidelines/Git/Repositories.md)
+- [GitHub pull requests](AgentGuidelines/Guidelines/GitHub/PullRequests.md)
+- [Xcode MCP](AgentGuidelines/Guidelines/Xcode/MCP.md)
+- [Xcode security audits](AgentGuidelines/Guidelines/Xcode/Security.md)
+
+Redux, SwiftData, SwiftUI, and application-localization guidance do not apply to the package target.
+
+## Physical folder map
+
+| Role | Physical folder |
+|---|---|
+| Package sources | `Sources/CloudSaveKit/` |
+| DocC catalog | `Sources/CloudSaveKit/CloudSaveKit.docc/` |
+| Unit tests | `Tests/CloudSaveKitTests/` |
+
+## Package specialization
+
+- Use `CKSyncEngine` rather than duplicating its scheduling, batching, state tracking, or transient retry behavior.
+- Do not add a local database, Redux, UI, product record schema, or game-specific conflict policy.
+- Persist every engine state update through the host-provided client boundary.
+- Keep status and errors privacy-safe; never log record contents or identifiers.
+- Update tests, DocC, README examples, and release notes when public behavior changes.
+- Use logging subsystem `com.thatfactory.cloudsavekit`, category `sync`, and canonical package emoji `☁️`.
+
+## Codex review scope
+
+For consumer pull requests, do not substantively review `AgentGuidelines/**` after exact tagged-tree provenance has been verified. Verify its `VERSION`, compare its tree with the matching central tag, and verify the required `.gitattributes` rule. If provenance does not match exactly, review the subtree contents and stop the merge. Report substantive guideline feedback against the central `agent-guidelines` pull request.
diff --git a/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md b/AgentGuidelines/.agents/skills/agent-guidelines-audit/SKILL.md
diff --git a/AgentGuidelines/.agents/skills/agent-guidelines-audit/agents/openai.yaml b/AgentGuidelines/.agents/skills/agent-guidelines-audit/agents/openai.yaml
diff --git a/AgentGuidelines/.github/workflows/ci.yml b/AgentGuidelines/.github/workflows/ci.yml
diff --git a/AgentGuidelines/.github/workflows/release.yml b/AgentGuidelines/.github/workflows/release.yml
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		AgentGuidelines/Configurations/Swift/.editorconfig
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Synced from thatfactory/agent-guidelines; keep tracked but collapse GitHub diffs.
		AgentGuidelines/** linguist-generated
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		AgentGuidelines/Configurations/Swift/.swift-format