### Run Release Generation Script

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Execute the script to generate release JSON files. This is typically part of the CI pipeline.

```bash
bun ./generate-releases-json.ts
```

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

### GitHub Actions CI/CD - Release Pipeline

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Details the GitHub Actions workflow for the release pipeline, triggered by a `repository_dispatch` event. It outlines the build process for different platforms, the generation of release metadata, and key environment variables.

```APIDOC
## GitHub Actions CI/CD — Release Pipeline (`release.yml`)

### Description
The release workflow is triggered by a `repository_dispatch` event of type `release`. It checks out the private `egoist/chatwise` source repo at a specific SHA, builds the Electron app for macOS (with Apple code-signing), Windows, and Linux in parallel, then runs `generate-releases-json.ts` to publish the structured release metadata to R2.

### Trigger
- `repository_dispatch` event with `event_type: "release"`.

### Triggering the Workflow
```bash
# POST https://api.github.com/repos/egoist/chatwise-releases/dispatches
# {
#   "event_type": "release",
#   "client_payload": { "sha": "abc123def456" }
# }
```

### Jobs
- `release`: Builds the application on `ubuntu-latest`, `macos-latest`, and `windows-latest`.
- `generate-releases-json`: Runs after all build jobs succeed, publishing release metadata.

### Key Environment Variables
Injected per platform:
- macOS Notarization: `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`
- macOS Code Signing: `CSC_LINK`, `CSC_KEY_PASSWORD`
- R2 Upload: `R2_ACCOUNT_ID`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
- Analytics: `POSTHOG_CLI_ENV_ID`, `POSTHOG_CLI_TOKEN`

### Version Extraction
After builds complete, the version is extracted from `desktop/package.json` and passed as the `VERSION` environment variable to `generate-releases-json.ts`.
```bash
VERSION=$(cat _chatwise-src/desktop/package.json | bun -e '...')
```
```

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

### Sync GitHub Release Assets to S3

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Fetches the latest GitHub release, downloads all assets, and uploads them to S3/R2. Also publishes `latest.json` and `all.json` metadata files. Requires GitHub token and S3 credentials.

```typescript
// sync-release.ts
// Required environment variables:
//   GITHUB_TOKEN        - GitHub personal access token
//   GITHUB_REPO         - defaults to "egoist/chatwise-releases"
//   S3_BUCKET           - defaults to "gh-releases"
//   S3_ENDPOINT         - S3-compatible endpoint URL (e.g. Cloudflare R2)
//   AWS_ACCESS_KEY_ID
//   AWS_SECRET_ACCESS_KEY

// Run with Bun:
//   bun ./sync-release.ts

// Internally calls:
//   1. fetchReleases()       → GET https://api.github.com/repos/{repo}/releases
//   2. downloadAsset(url)    → authenticated GET of each asset binary
//   3. uploadToS3(buf, key)  → Bun.S3Client.write() to {repo}/{tag}/{asset.name}
//   4. syncReleaseJSON(type) → uploads latest.json and all.json to S3

// Example S3 key layout after a successful run:
//   egoist/chatwise-releases/v1.2.3/ChatWise-1.2.3.dmg
//   egoist/chatwise-releases/v1.2.3/ChatWise-Setup-1.2.3.exe
//   egoist/chatwise-releases/latest.json   ← single release object
//   egoist/chatwise-releases/all.json      ← array of all releases

// Console output:
// Fetching latest release...
// Found release: v1.2.3 with 6 assets
// Downloading ChatWise-1.2.3.dmg (98304000 bytes)...
// Uploading to S3: egoist/chatwise-releases/v1.2.3/ChatWise-1.2.3.dmg...
// ✓ Synced ChatWise-1.2.3.dmg
// Successfully synced 6 assets from v1.2.3

```

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

### Assistant YAML Format

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Defines the structure for custom AI assistant personas, which are stored as YAML files. Each persona includes a display name, timestamps, and a system instruction prompt.

```APIDOC
## Assistant YAML Format

### Description
ChatWise supports importing reusable AI assistant personas defined as YAML files. Each file specifies a display name, creation/update timestamps, and a full `systemInstruction` prompt. These files live in `assistants/` and can be shared or imported directly into the app.

### File Structure
Files should be named following a pattern like `assistants/{persona-name}.{locale}.yml`.

### Fields
- `name` (string): The display name of the assistant persona.
- `createdAt` (string): The creation timestamp of the persona.
- `updatedAt` (string): The last update timestamp of the persona.
- `systemInstruction` (string): The detailed prompt that guides the AI assistant's behavior.

### Example (`assistants/web-designer.en.yml`)
```yaml
name: Web designer
createdAt: 2024-12-20
updatedAt: 2024-12-20
systemInstruction: |
  You are an experienced designer and developer. Your goal is to design a
  landing page for a client. They give you a brief description of their
  service, and you design and implement a beautiful landing page.

  Always format your reply using markdown with these sections:
  1. Design direction
  2. HTML output  (Tailwind CSS, <body> only, 4 sections, responsive)
  3. How to use

  Use images from: https://enzostvs-cached-generation.hf.space/generate/{prompt}?format={square|portrait-9_16|landscape-16_9}
```

### Example (Chinese persona `assistants/zanghua.zh.yml`)
```yaml
title: 脏话学习助手
createdAt: 2024-12-19
updatedAt: 2024-12-19
systemInstruction: |
  你现在是一个语言学习辅助助手 ...
```
```

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

### Generate release.json from Update Manifests

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Reads Electron update manifests from R2, parses them, deduplicates assets, and writes a structured `release.json` file. Requires version and S3/R2 credentials.

```typescript
// generate-releases-json.ts
// Required environment variables:
//   VERSION             - release version string, e.g. "1.2.3"
//   R2_ACCOUNT_ID       - Cloudflare R2 account ID
//   AWS_ACCESS_KEY_ID
//   AWS_SECRET_ACCESS_KEY
//   S3_BUCKET           - defaults to "chatwise-releases2"
//   BUCKET_ORIGIN       - defaults to "https://releases.chatwise.app"

// Run with Bun:
//   VERSION=1.2.3 bun ./generate-releases-json.ts

// Reads from R2:
//   1.2.3/latest-mac.yml
//   1.2.3/latest.yml
//   1.2.3/latest-linux.yml

// Produces R2 object:
//   1.2.3/release.json

// Example output shape of release.json:
// {
//   "version": "1.2.3",
//   "changelog": "- Fixed crash on startup\n- Added dark mode",
//   "date": "2025-01-15",
//   "assets": [
//     {
//       "name": "ChatWise-1.2.3-arm64.dmg",
//       "url": "https://releases.chatwise.app/1.2.3/ChatWise-1.2.3-arm64.dmg",
//       "sha512": "abc123..."
//     },
//     {
//       "name": "ChatWise-Setup-1.2.3.exe",
//       "url": "https://releases.chatwise.app/1.2.3/ChatWise-Setup-1.2.3.exe",
//       "sha512": "def456..."
//     }
//   ]
// }

// Note: update manifest filenames (latest-mac.yml, latest.yml, latest-linux.yml)
// are excluded from the assets list automatically via UPDATE_MANIFESTS set.

```

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

### Assistant YAML Persona Definition

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Defines custom AI assistant personas using YAML format. Includes display name, timestamps, and a system instruction prompt for the AI. Supports multiple languages.

```yaml
# assistants/web-designer.en.yml
name: Web designer
createdAt: 2024-12-20
updatedAt: 2024-12-20
systemInstruction: |
  You are an experienced designer and developer. Your goal is to design a
  landing page for a client. They give you a brief description of their
  service, and you design and implement a beautiful landing page.

  Always format your reply using markdown with these sections:
  1. Design direction
  2. HTML output  (Tailwind CSS, <body> only, 4 sections, responsive)
  3. How to use

  Use images from: https://enzostvs-cached-generation.hf.space/generate/{prompt}?format={square|portrait-9_16|landscape-16_9}
```

```yaml
# assistants/zanghua.zh.yml  (example of a Chinese-language persona)
title: 脏话学习助手
createdAt: 2024-12-19
updatedAt: 2024-12-19
systemInstruction: |
  你现在是一个语言学习辅助助手 ...
```

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

### Fetch GitHub Releases

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Fetches all GitHub releases for a configured repository using the GitHub REST API. Requires Bearer token authentication. Throws an error on non-2xx HTTP status.

```typescript
// Internal helper used by syncReleaseAssets()
// GET https://api.github.com/repos/egoist/chatwise-releases/releases
// Headers: { Authorization: "Bearer <GITHUB_TOKEN>", User-Agent: "sync-release" }

// Returned shape (array):
// [
//   {
//     "tag_name": "v1.2.3",
//     "assets": [
//       {
//         "name": "ChatWise-1.2.3.dmg",
//         "browser_download_url": "https://github.com/.../ChatWise-1.2.3.dmg",
//         "size": 98304000
//       }
//     ]
//   }
// ]

// Error handling: throws on non-2xx HTTP status
// try {
//   const releases = await fetchReleases();
//   console.log(releases[0].tag_name); // "v1.2.3"
// } catch (err) {
//   // "GitHub API error: 401 Unauthorized"
// }
```

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

### Safely Read Text File from S3/R2

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Fetches text content from S3/R2, returning null if the object doesn't exist or an error occurs. Useful for reading configuration files like Electron update manifests.

```typescript
// Signature:
// async function getS3Text(key: string): Promise<string | null>

// Example:
const macYaml = await getS3Text("1.2.3/latest-mac.yml");
if (macYaml) {
  const manifest = YAML.parse(macYaml);
  // { releaseNotes: "...", releaseDate: "2025-01-15", files: [...] }
} else {
  console.warn("latest-mac.yml not found for this version");
}
```

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

### Upload Buffer to S3/R2

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Uploads an ArrayBuffer to S3/R2 using Bun.S3Client.write. Defaults to 'application/octet-stream' content type if not specified. Handles both JSON metadata and binary assets.

```typescript
// Signature:
// async function uploadToS3(
//   buffer: ArrayBufferLike,
//   key: string,
//   contentType?: string
// ): Promise<void>

// Example — uploading a JSON metadata file:
const payload = new TextEncoder().encode(JSON.stringify({ version: "1.2.3" }));
await uploadToS3(payload.buffer, "egoist/chatwise-releases/latest.json", "application/json");

// Example — uploading a binary asset:
const response = await fetch("https://example.com/ChatWise-1.2.3.dmg");
const buffer = await response.arrayBuffer();
await uploadToS3(buffer, "egoist/chatwise-releases/v1.2.3/ChatWise-1.2.3.dmg");
// → writes to S3 with content-type "application/octet-stream"
```

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

### fetchReleases()

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Fetches all GitHub releases for the configured repository using the GitHub REST API. It requires Bearer token authentication and returns a list of release objects, each containing details like tag name and assets.

```APIDOC
## fetchReleases()

### Description
Fetches the full list of GitHub releases for the configured repo using the GitHub REST API with Bearer token authentication.

### Method
GET

### Endpoint
`https://api.github.com/repos/egoist/chatwise-releases/releases`

### Headers
- `Authorization` (string) - Required - Bearer token
- `User-Agent` (string) - Required - `sync-release`

### Response
#### Success Response (200)
- `tag_name` (string) - The tag name of the release.
- `assets` (array) - A list of assets associated with the release.
  - `name` (string) - The name of the asset.
  - `browser_download_url` (string) - The URL to download the asset.
  - `size` (number) - The size of the asset in bytes.

### Request Example
```typescript
try {
  const releases = await fetchReleases();
  console.log(releases[0].tag_name); // "v1.2.3"
} catch (err) {
  // Handle error
}
```

### Error Handling
Throws an error on non-2xx HTTP status codes.
```

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

### GitHub Actions CI/CD Release Pipeline Trigger

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Configuration for a GitHub Actions release workflow triggered by a repository_dispatch event. Includes details on job execution, environment variables, and version extraction.

```yaml
# Trigger from another workflow or external system:
# POST https://api.github.com/repos/egoist/chatwise-releases/dispatches
# {
#   "event_type": "release",
#   "client_payload": { "sha": "abc123def456" }
# }

# Jobs:
#   release              → builds on ubuntu-latest, macos-latest, windows-latest
#   generate-releases-json → runs after all build jobs succeed (needs: release)

# Key environment variables injected per platform:
#   APPLE_ID / APPLE_APP_SPECIFIC_PASSWORD / APPLE_TEAM_ID  ← macOS notarization
#   CSC_LINK / CSC_KEY_PASSWORD                             ← macOS code signing cert
#   R2_ACCOUNT_ID / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY ← R2 upload
#   POSTHOG_CLI_ENV_ID / POSTHOG_CLI_TOKEN                  ← analytics

# After builds complete, version is extracted from desktop/package.json and
# passed as VERSION env var to generate-releases-json.ts:
#   VERSION=$(cat _chatwise-src/desktop/package.json | bun -e '...')

```

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

### uploadToS3()

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Uploads a given ArrayBuffer to an S3/R2 storage key. It allows specifying a content type, which defaults to 'application/octet-stream' if not provided.

```APIDOC
## uploadToS3(buffer, key, contentType?)

### Description
Wraps `Bun.S3Client.write()` to upload an `ArrayBuffer` (or `ArrayBufferLike`) to a given S3 key with an optional content type, defaulting to `application/octet-stream`.

### Signature
`async function uploadToS3(
  buffer: ArrayBufferLike,
  key: string,
  contentType?: string
): Promise<void>`

### Parameters
#### Path Parameters
- `buffer` (ArrayBufferLike) - Required - The data buffer to upload.
- `key` (string) - Required - The S3 key (path) where the file will be stored.
- `contentType` (string) - Optional - The MIME type of the content.

### Request Example
```typescript
// Example — uploading a JSON metadata file:
const payload = new TextEncoder().encode(JSON.stringify({ version: "1.2.3" }));
await uploadToS3(payload.buffer, "egoist/chatwise-releases/latest.json", "application/json");

// Example — uploading a binary asset:
const response = await fetch("https://example.com/ChatWise-1.2.3.dmg");
const buffer = await response.arrayBuffer();
await uploadToS3(buffer, "egoist/chatwise-releases/v1.2.3/ChatWise-1.2.3.dmg");
// → writes to S3 with content-type "application/octet-stream"
```
```

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

### getS3Text()

Source: https://context7.com/egoist/chatwise-releases/llms.txt

Safely reads the text content of a specified key from S3/R2. It returns the content as a string or null if the object does not exist or an error occurs.

```APIDOC
## getS3Text(key)

### Description
Fetches the text content of a key from S3/R2, returning `null` if the object does not exist or any error occurs (silently swallowed). Used to read Electron update manifest YAMLs.

### Signature
`async function getS3Text(key: string): Promise<string | null>`

### Parameters
#### Path Parameters
- `key` (string) - Required - The S3 key (path) of the text file to read.

### Request Example
```typescript
const macYaml = await getS3Text("1.2.3/latest-mac.yml");
if (macYaml) {
  const manifest = YAML.parse(macYaml);
  // { releaseNotes: "...", releaseDate: "2025-01-15", files: [...] }
} else {
  console.warn("latest-mac.yml not found for this version");
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.