Docs: error handling, configuration, records, and limits articles

[leogdion]

Summary

Adds four DocC articles to close out the open documentation gaps tracked by parent #361:

• HandlingErrors.md — three-layer error model (construction, token, request) with retry/recovery guidance. Covers CloudKitError, TokenManagerError, TokenStorageError, CredentialsValidationError, and the four *Reason enums.
• ConfiguringMistKit.md — container, environment, transport, and logging inputs. Explicitly defers credential construction to AuthenticationAndDatabases.md to avoid duplication. Notes there is no MistKitConfiguration type (issue Add comprehensive configuration documentation #116's terminology) — configuration is what you pass to CloudKitService.init.
• WorkingWithRecords.md — CRUD, batched modifyRecords, lookup, and sync-via-change-token walks.
• CloudKitLimitsAndPerformance.md — pagination guard (maxPages: 1_000 + stuck-marker detection), batch sizing, asset upload transport split (URLSession.shared vs configured ClientTransport, with the 421 Misdirected Request rationale), CloudKit rate limits.

Also adds inline # Example blocks to createRecord, updateRecord (CloudKitService+WriteOperations.swift) and lookupRecords (CloudKitService+LookupOperations.swift) to match the existing example style on queryRecords. modifyRecords and deleteRecord examples live in the article rather than inline to keep the write-operations file under the file_length cap.

Updates Documentation.md Topics:

• Adds the three new article links plus <doc:HandlingErrors> under Getting Started / Error Handling.
• Adds a new ### Error Handling group covering the typed error and reason enums.

Base branch note

This PR targets v1.0.0-beta.2 — the v1.0.0-beta.1 branch you mentioned no longer exists upstream (it was replaced by v1.0.0-beta.1-backup and the active v1.0.0-beta.2). Retarget if you want it against a different base.

A parallel PR (#362) targets main with the same content. Pick whichever base is right and close the other.

Out of scope (deliberate)

• Migration guide mentioned in Documentation: Add API examples, migration guide, and performance characteristics #160 — deferred. MistKit is at 1.0.0-beta.x with no stable predecessor to migrate from; that article should land alongside a future release transition.
• MistKitConfiguration type referenced in Add comprehensive configuration documentation #116 — does not exist; the new article documents the actual init-driven configuration model.
• Pre-existing type_contents_order warning on CloudKitService+WriteOperations.swift — already present on the v1.0.0-beta.2 base; out of scope for a docs PR.

Test plan

• swift build — DocC catalog parses, articles compile against beta.2
• swift test — 449 tests pass; no regressions from inline doc edits
• ./Scripts/lint.sh — swift-format, swiftlint, periphery clean (only pre-existing type_contents_order warning remains)
• CI DocC build step verifies <doc:> cross-links and Type references resolve

Closes #115
Closes #116
Closes #160

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bc342c93-ede0-4a71-9463-91839f65e69f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 361-docs-error-config-records-beta

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Code Review — PR 364: Docs articles (error handling, configuration, records, limits)

Overview

Adds four DocC articles (HandlingErrors.md, ConfiguringMistKit.md, WorkingWithRecords.md, CloudKitLimitsAndPerformance.md) plus inline examples on createRecord, updateRecord, lookupRecords. Closes #115, #116, #160.

Strengths

• The four articles are well-structured and cover the most common developer questions about MistKit.
• The transport-separation warning in CloudKitLimitsAndPerformance.md is prominent, accurate, and directly references the 421 Misdirected Request root cause.
• The stuck-marker detection note is accurate and not obvious from the method signatures alone.
• ConfiguringMistKit.md correctly notes there is no MistKitConfiguration type, avoiding a naming confusion from issue Add comprehensive configuration documentation #116.
• Inline code examples on createRecord and updateRecord are clean and compile-correct.
• Environment.init(caseInsensitive:) referenced in ConfiguringMistKit.md exists at Sources/MistKit/Models/Environment.swift:40 — good.

Issues Found

1. Incorrect DocC symbol path for fetchAllRecordChanges (WorkingWithRecords.md)

In the Topics section of WorkingWithRecords.md, the link is:

- ``CloudKitService/fetchAllRecordChanges(recordType:syncToken:)``

But the actual method signature (CloudKitService+SyncOperations.swift:156) is:

public func fetchAllRecordChanges(
  zoneID: ZoneID? = nil,
  syncToken: String? = nil,
  resultsLimit: Int? = nil,
  maxPages: Int = 1_000,
  database: Database
)

The correct DocC path should be:

- ``CloudKitService/fetchAllRecordChanges(zoneID:syncToken:resultsLimit:maxPages:database:)``

DocC will emit an unresolved-symbol warning for the incorrect path and the link won't render. This also means the CI DocC build step (unchecked in the test plan) needs to pass before merging to catch this.

2. Two parallel PRs (#362 and #364) for the same content

The description acknowledges this — one targets main, one targets v1.0.0-beta.2. Close whichever is not the intended target before merging.

3. CI DocC build step unchecked

The "CI DocC build step verifies cross-links" item is unchecked. Issue #1 above will surface as a broken link in that step. Worth resolving before merging.

Minor Observations

• The sync code example in WorkingWithRecords.md uses fetchRecordChanges(syncToken:database:) without zoneID — this is valid since zoneID has a default. Clean.
• The batching guidance (200 ops cap, chunk example) in CloudKitLimitsAndPerformance.md is useful and correct.
• The rate-limit section is intentionally vague ("exact thresholds vary"), which is appropriate since Apple does not publish exact numbers.

Summary

The articles are high quality and fill real documentation gaps. One actionable fix before merging: correct the fetchAllRecordChanges symbol path in WorkingWithRecords.md Topics section. The CI DocC build step will catch it if left in.

Review generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (v1.0.0-beta.2@b0c65d8). Learn more about missing BASE report.

Additional details and impacted files

@@               Coverage Diff                @@
##             v1.0.0-beta.2     #364   +/-   ##
================================================
  Coverage                 ?   69.35%           
================================================
  Files                    ?      113           
  Lines                    ?     2630           
  Branches                 ?        0           
================================================
  Hits                     ?     1824           
  Misses                   ?      806           
  Partials                 ?        0           

Flag	Coverage Δ
mistdemo-spm-macos	12.12% <ø> (?)
mistdemo-swift-6.2-jammy	11.93% <ø> (?)
mistdemo-swift-6.2-noble	11.93% <ø> (?)
mistdemo-swift-6.3-jammy	11.93% <ø> (?)
mistdemo-swift-6.3-noble	11.93% <ø> (?)
spm	67.98% <ø> (?)
swift-6.1-jammy	67.56% <ø> (?)
swift-6.1-noble	67.52% <ø> (?)
swift-6.2-jammy	67.60% <ø> (?)
swift-6.2-noble	67.56% <ø> (?)
swift-6.3-jammy	67.56% <ø> (?)
swift-6.3-noble	67.49% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.