Adding Celestra to Demos

.claude/docs/README.md

@@ -120,6 +120,73 @@ This directory contains Apple's official documentation for CloudKit Web Services
 
 ---
 
+### cktool.md / cktool-full.md
+**Source**: https://developer.apple.com/icloud/ck-tool/
+
+**Primary Use**: CloudKit command-line tool for schema and data management
+
+**Files**:
+- `cktool.md` - Curated summary with command examples
+- `cktool-full.md` - Complete Apple documentation
+
+**Key Topics**:
+- **Authentication**: Management tokens, user tokens, Keychain storage
+- **Schema Management**:
+  - Reset development schema to production
+  - Export schema to `.ckdb` files
+  - Import schema from files to development
+- **Data Commands**:
+  - Query records with filters
+  - Create records with JSON field definitions
+- **Automation**: CI/CD integration, test data seeding
+- **Token Management**: Saving and managing CloudKit tokens
+
+**When to Consult**:
+- Setting up development environments with CloudKit schemas
+- Exporting/importing schemas for version control
+- Automating schema deployment in CI/CD pipelines
+- Seeding test data for MistKit integration tests
+- Resetting development databases
+- Understanding CloudKit Management API workflows
+
+---
+
+### cktooljs.md / cktooljs-full.md
+**Source**: https://developer.apple.com/documentation/cktooljs/
+**Version**: CKTool JS 1.2.15+
+
+**Primary Use**: JavaScript library for CloudKit management operations
+
+**Files**:
+- `cktooljs.md` - Curated summary with key information
+- `cktooljs-full.md` - Complete Apple documentation (41 pages)
+
+**Key Topics**:
+- **Core Modules**:
+  - `@apple/cktool.database` - CloudKit types and operations
+  - `@apple/cktool.target.nodejs` - Node.js configuration
+  - `@apple/cktool.target.browser` - Browser configuration
+- **Capabilities**:
+  - Deploy schemas to Sandbox databases
+  - Seed databases with test data
+  - Restore Sandbox to production settings
+  - Create automated integration test scripts
+- **API Components**:
+  - PromisesApi and CancellablePromise
+  - Configuration for server communication
+  - Container and ContainersResponse structures
+  - Error handling framework
+
+**When to Consult**:
+- Building JavaScript-based CloudKit automation tools
+- Creating CI/CD pipelines with Node.js
+- Understanding CloudKit Management API from JS perspective
+- Automating schema deployment programmatically
+- Building developer tooling for CloudKit workflows
+- Comparing management API patterns across platforms
+
+---
+
 ## Quick Reference: When to Use Each Doc
 
 ### Implementing Core API Functionality
@@ -134,6 +201,10 @@ This directory contains Apple's official documentation for CloudKit Web Services
 ### Writing Tests
 → **testing-enablinganddisabling.md**: Modern Swift Testing patterns
 
+### Schema Management & Automation
+→ **cktool.md**: Native command-line tool for schema and data operations
+→ **cktooljs.md**: JavaScript library for programmatic management
+
 ---
 
 ## Integration with MistKit Development
@@ -162,24 +233,58 @@ When designing MistKit's API surface:
 ### Authentication Flow
 1. **webservices.md** → Request signing, token formats
 2. **cloudkitjs.md** → Authentication state management
+3. **cktool.md** → Management token setup and storage
 
 ### Record Operations
 1. **webservices.md** → `/records/modify` endpoint structure
 2. **cloudkitjs.md** → `Database.saveRecords()` operation flow
+3. **cktool.md** → Creating test records via CLI
 
 ### Query Operations
 1. **webservices.md** → `/records/query` request format
 2. **cloudkitjs.md** → Query filters, sort descriptors, pagination
+3. **cktool.md** → Query filters via command-line
 
 ### Error Handling
 1. **webservices.md** → HTTP status codes, error response format
 2. **cloudkitjs.md** → `CKError` codes and retry logic
+3. **cktooljs.md** → Error handling in management operations
+
+### Development Workflows
+1. **cktool.md** → Export/import schemas for version control
+2. **cktooljs.md** → Programmatic schema deployment and automation
+3. **webservices.md** → Understanding underlying API operations
 
 ---
 
+## Documentation Ecosystem Map
+
+```
+CloudKit Development & Operations
+├── Runtime APIs (Application Level)
+│   ├── webservices.md ────────── REST API reference
+│   ├── cloudkitjs.md ─────────── JS SDK for web apps
+│   └── MistKit ───────────────── Swift implementation
+│
+├── Management APIs (Development Level)
+│   ├── cktool.md ─────────────── Native CLI tool (Xcode)
+│   └── cktooljs.md ───────────── JS library for automation
+│
+├── Code Generation
+│   └── swift-openapi-generator.md ─ Generate Swift from OpenAPI
+│
+└── Testing
+    └── testing-enablinganddisabling.md ─ Swift Testing framework
+```
+
 ## Notes
 
-- These docs are from Apple's official documentation, downloaded via llm.codes
-- Content is filtered for relevant information (URLs filtered, deduplicated)
-- Last updated: October 20, 2025
-- Corresponds to CloudKit Web Services (archived), CloudKit JS 1.0+, Swift Testing (Swift 6.0+)
+- These docs are from Apple's official documentation and community sources
+- Most content downloaded via llm.codes and filtered for relevance
+- Last updated: November 4, 2025
+- Corresponds to:
+  - CloudKit Web Services (archived)
+  - CloudKit JS 1.0+
+  - Swift Testing (Swift 6.0+)
+  - cktool (Xcode 13+)
+  - CKTool JS (latest)

.claude/docs/cktool-full.md

@@ -0,0 +1,113 @@
+<!--
+Downloaded via https://llm.codes by @steipete on November 4, 2025 at 03:26 PM
+Source URL: https://developer.apple.com/icloud/ck-tool/
+Total pages processed: 1
+URLs filtered: Yes
+Content de-duplicated: Yes
+Availability strings filtered: Yes
+Code blocks only: No
+-->
+
+# https://developer.apple.com/icloud/ck-tool/
+
+View in English
+
+# Using cktool
+
+### Before you begin
+
+- You'll need to be a current member of the Apple Developer Program or the Apple Developer Enterprise Program in order to use `cktool`.
+- Understand the concepts of Authentication, as described in Automating CloudKit Development.
+- Generate a CloudKit Management Token from the CloudKit Console by choosing the Settings section for your user account. Save this token, as it will not be visible again.
+
+### Installing the application
+
+By default, `cktool` is distributed with Xcode starting with Xcode 13, which is available on the Mac App Store.
+
+### General usage
+
+`cktool` is stateless and passes all operations to the CloudKit Management API in single operations. A full list of supported operations is available from the `help` command or the `man` pages:
+
+xcrun cktool --help
+OVERVIEW: CloudKit Command Line Tool
+
+-h, --help				Show help information.
+
+SUBCOMMANDS: ...
+
+### Authenticating `cktool` to CloudKit
+
+`cktool` supports both management and user tokens, and will store them securely in Mac Keychain. You can add a token using the `save-token` command, which will launch CloudKit Console for copying of the appropriate token after prompting for information from the user:
+
+xcrun cktool save-token			\
+--type [management | user]
+
+#### Issuing Schema Management commands
+
+Schema Management commands require the Management Token to be provided. Once provided, `cktool` can perform the following commands:
+
+**Reset development schema.** This allows you to revert the development database to the current production definition.
+
+xcrun cktool reset-schema	\
+--team-id [TEAM-ID]		\
+--container-id [CONTAINER]
+
+**Export schema file.** This allows you to save an existing CloudKit Database schema definition to a file, which can be kept alongside the related source code:
+
+xcrun cktool export-schema 		\
+--team-id [TEAM-ID]			\
+--container-id [CONTAINER]	\
+--environment [development | production]	\
+[--output-file schema.ckdb]
+
+**Import schema file.** This applies a file-based schema definition against the development database for testing.
+
+xcrun cktool import-schema 		\
+--team-id [TEAM-ID]			\
+--container-id [CONTAINER]	\
+--environment development 	\
+--file schema.ckdb
+
+### Issuing data commands
+
+When a user token is available, `cktool` can access public and private databases on behalf of the user. This can be used for fetching data and inserting new records prior to integration tests. Note that due to the short lifespan of the user token, frequent interactive authentication may be required.
+
+Querying records can be performed with the `query-records` command. Note that queries without filters require the `___recordID` to have a `Queryable` index applied, as do fields specified in the optional `--filters` argument:
+
+xcrun cktool query-records		\
+--team-id [TEAMID] 			\
+--container-id [CONTAINER] 	\
+--zone-name [ZONE_NAME] 		\
+--database-type [public | private] 	\
+--environment [development | production]	\
+--record-type [RECORD_TYPE]	\
+[--filters [FILTER_1] [FILTER_2]]
+
+Where `FILTER_1` is in the form `"[FIELD_NAME] [OPERATOR] [VALUE]"`, for example `"lastname == Appleseed"`.
+
+Inserting data is accomplished with the `create-record` command:
+
+xcrun cktool create-record		\
+--team-id [TEAM_ID]			\
+--container-id [CONTAINER]	\
+--zone-name [ZONE_NAME] 		\
+--database-type [public | private] 	\
+--environment [development | production]	\
+--record-type [RECORD_TYPE]	\
+[--fields-json [FIELDS_JSON]]
+
+Where `FIELDS_JSON` is a JSON representation of the fields to set in the record. For example:
+
+'{
+"firstName": {
+"type": "stringType",
+"value": "Johnny"
+},
+"lastName": {
+"type": "stringType",
+"value": "Appleseed"
+}
+}'
+
+---
+