Polish open source project docs and releases

Author: parrisdigital

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -12,7 +12,7 @@ body:
     attributes:
       label: App or bridge version
       description: Include the TestFlight build number or `runline-bridge --version`.
-      placeholder: "Runline 1.0 (11), runline-bridge 0.1.0"
+      placeholder: "Runline 1.0 (11), runline-bridge 0.1.2"
     validations:
       required: true
   - type: dropdown

CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable public changes to Runline are tracked here.
+
+Runline is in public beta. Versions may move quickly while the iOS app, TestFlight flow, and optional Cursor SDK bridge settle.
+
+## Unreleased
+
+- Keep Cloud Agent mode as the default iOS experience.
+- Continue refining Cursor SDK mode and Runline Bridge pairing for power users.
+- Improve iPhone and iPad polish while staying native to SwiftUI and iOS system patterns.
+
+## Runline Public Beta
+
+- Renamed the project and repository to Runline.
+- Prepared GitHub source release `v1.0.0-beta.1`.
+- Moved the public repository to `https://github.com/parrisdigital/runline`.
+- Preserved the App Store bundle identifier `com.matthewparris.runline`.
+- Added open source project files: MIT license, security policy, contributing guide, support guide, code of conduct, issue templates, PR template, Dependabot, CI, and gitleaks configuration.
+- Added native iPhone and iPad support for Cloud Agent chats, repositories, Settings, attachments, model selection, light/dark mode, and optional Cursor SDK mode.
+- Cleaned chat event rendering so streaming text and thinking deltas are grouped into readable timeline entries.
+
+## runline-bridge 0.1.2
+
+- Published `runline-bridge@0.1.2` to npm.
+- Set both `latest` and `beta` npm dist-tags to `0.1.2`.
+- Updated npm metadata to point to `parrisdigital/runline`.
+- Preserved Cursor SDK session endpoints, pairing endpoints, MCP profile metadata, and Cloud compatibility aliases.
+- Added dependency overrides and shrinkwrap updates so the local bridge audit passes with no high-severity findings.
+
+## runline-bridge 0.1.1
+
+- Prepared the bridge package for public beta usage.
+- Added repository, homepage, bugs, license, keywords, and packaged README metadata.
+- Tightened npm package contents to the CLI, compiled output, README, and shrinkwrap.
+
+## runline-bridge 0.1.0
+
+- Initial bridge package for optional Cursor SDK sessions.
+- Added local server, health check, pairing, SDK session creation, follow-up messages, session state, and event endpoints.
+
+## TestFlight Build 1.0 (6)
+
+- Historical TestFlight prerelease retained on GitHub as `testflight-1.0-6`.
+- Included iPad adaptive layout work and native iPhone/iPad validation.
+
+## Notes
+
+Runline is independent and is not affiliated with, endorsed by, or connected to Cursor or Anysphere.

CONTRIBUTING.md

@@ -24,6 +24,7 @@ Run bridge checks:
 ```bash
 npm --prefix orchestrator run typecheck
 npm --prefix orchestrator run build
+npm --prefix orchestrator audit --audit-level=high
 ```
 
 Run iOS tests:
@@ -42,7 +43,8 @@ xcodebuild test \
 - Keep Cursor SDK mode optional and clearly labeled as requiring Runline Bridge.
 - Add or update tests for behavior changes.
 - Do not commit generated archives, IPAs, derived data, local ASC artifacts, npm tokens, Apple signing material, API keys, or private repository data.
-- Run `git diff --check`, bridge typecheck/build, and relevant iOS tests before opening a PR.
+- Run `git diff --check`, bridge typecheck/build/audit, and relevant iOS tests before opening a PR.
+- For release process changes, update [docs/RELEASES.md](docs/RELEASES.md) and [CHANGELOG.md](CHANGELOG.md).
 
 ## Security
 

README.md

@@ -1,41 +1,109 @@
 # Runline for Cursor
 
-Runline is a native iOS 26+ client for managing Cursor Cloud Agents from iPhone and iPad.
+<p align="center">
+  <img src="DesignAssets/runline-logo-transparent-1024.png" alt="Runline logo" width="96" height="96">
+</p>
 
-The app uses a proven Cloud Agents foundation with a chat-first, system-native iOS interface: stock navigation, lists, forms, sheets, toolbars, and settings surfaces.
+Runline is a native iOS 26+ client for working with Cursor Cloud Agents from iPhone and iPad. It keeps the default path simple: connect a Cursor API key, choose a repository, start a Cloud Agent run, and continue the conversation from a system-native chat interface.
+
+Runline also includes an optional Mac-side bridge for Cursor SDK sessions. The bridge is only needed when a user wants SDK-specific workflows such as MCP profiles, SDK session state, or local Mac-assisted pairing.
 
 Runline is independent and is not affiliated with, endorsed by, or connected to Cursor or Anysphere.
 
-## Status
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm runline-bridge](https://img.shields.io/npm/v/runline-bridge.svg)](https://www.npmjs.com/package/runline-bridge)
+
+## Project Status
+
+Runline is in public beta.
+
+- iOS app: native SwiftUI app for iOS 26+ and iPadOS 26+.
+- Cloud Agent mode: default, fully on-device direct integration with Cursor's Cloud Agents API.
+- Cursor SDK mode: optional, powered by `runline-bridge` on the user's Mac or a trusted HTTPS bridge.
+- TestFlight/App Store Connect releases: maintainer-managed.
+- npm package: `runline-bridge@0.1.2` is published on both `latest` and `beta`.
+
+## What Runline Does
+
+- Stores the user's Cursor API key in iOS Keychain.
+- Lists Cursor repositories and models.
+- Starts Cursor Cloud Agent runs from native iOS forms.
+- Streams and restores run timelines with cleaner event grouping.
+- Lets users continue terminal runs with a native chat composer.
+- Supports images and files as prompt context where the Cursor API path accepts them.
+- Shows artifacts, PR links, run status, archive/delete/cancel actions, and notification preferences.
+- Adapts the same SwiftUI experience to iPhone and iPad, including portrait and landscape.
+- Supports system appearance, light mode, dark mode, and user-selected appearance preferences.
+- Provides an optional Cursor SDK bridge path for users who want SDK sessions from their Mac.
+
+## Runtime Modes
+
+| Mode | Where it runs | Best for | Requirements |
+| --- | --- | --- | --- |
+| Cloud Agent | Directly from iOS to Cursor Cloud Agents | Most users, TestFlight users, repository tasks, follow-ups, artifacts, PR workflows | Cursor API key |
+| Cursor SDK | iOS app plus Runline Bridge | SDK sessions, MCP profiles, richer local tooling, Mac-assisted workflows | Cursor API key, Node.js 20+, `runline-bridge` |
+
+Cloud Agent mode does not require Node, a Mac bridge, a hosted backend, or any Runline server.
 
-Runline is in public beta. Cloud Agent mode is the default path and works directly from iOS. Cursor SDK mode is optional and requires Runline Bridge on the user's Mac.
+Cursor SDK mode is intentionally opt-in. It should be treated as a power-user path until the bridge and pairing flow are hardened further.
 
-## Features
+## Install the iOS Beta
 
-- iOS 26+ SwiftUI app target
-- Chat-first Cloud Agents navigation for iPhone and iPad
-- Cursor Cloud Agents v1 provider for account, repositories, models, agents, runs, streams, artifacts, archive, unarchive, and delete
-- Optional `@cursor/sdk` bridge client for Cursor SDK sessions, MCP profiles, subagents, and multi-turn follow-ups
-- Runline Bridge pairing with one-time terminal codes and Keychain-backed bridge tokens
-- First-run and Settings runtime selection between Cloud Agent and Cursor SDK defaults
-- Native Cursor SDK composer controls for intent, model, MCP profile, image context, and file context
-- Keychain-backed Cursor API key storage
-- Local cache for account, repositories, models, agents, runs, stream events, artifacts, notification preferences, and launch draft
-- Unit tests for Cursor v1 request contracts, SSE parsing, cache persistence, app routing, push payloads, chat event cleanup, file attachment loading, and SDK bridge request mapping
+The iOS beta is distributed through TestFlight by the maintainer. Once installed:
 
-## Cursor SDK Mode
+1. Open Runline.
+2. Connect a Cursor API key.
+3. Keep Cloud Agent as the default mode unless you specifically want the SDK bridge.
+4. Select a repository and launch a chat.
+5. Continue completed runs from the chat composer.
 
-Cloud Agent mode works directly from iOS. Cursor SDK mode is optional and requires Runline Bridge on the user's Mac:
+Cursor API keys stay on device in Keychain for direct Cloud Agent requests.
+
+## Optional Cursor SDK Mode
+
+Install the bridge only if you want Cursor SDK mode:
 
 ```bash
-npm install -g runline-bridge@beta
+npm install -g runline-bridge
 export CURSOR_API_KEY="replace-with-your-cursor-key"
 runline-bridge up
 ```
 
-Runline Bridge prints the iPhone-reachable URL and pairing instructions. The iOS app stores the bridge token in Keychain after pairing.
+For Simulator development, `http://localhost:8787` is usually enough.
+
+For a physical iPhone on the same Wi-Fi network:
+
+```bash
+ipconfig getifaddr en0
+```
+
+Then enter `http://<mac-lan-ip>:8787` in Runline Settings and pair with the one-time code printed by the bridge.
+
+The bridge does not need to store Cursor API keys. It can accept a per-request bearer token from the iOS app, or use `CURSOR_API_KEY` from the user's local shell environment.
+
+## Repository Layout
+
+```text
+Runline/                  SwiftUI app source
+RunlineTests/             Unit tests for app state, providers, cache, routing, and bridge mapping
+orchestrator/             runline-bridge npm package
+DesignAssets/             Public logo and app icon source previews
+Tools/                    Maintainer utilities such as build-number updates
+.asc/                     Maintainer App Store Connect workflow config
+.github/                  CI, issue templates, PR template, Dependabot
+docs/                     Release and maintainer documentation
+```
+
+## Development Setup
 
-## Development
+Requirements:
+
+- macOS
+- Xcode 26 or newer with the iOS 26 simulator runtime
+- Swift 6
+- Node.js 20 or newer
+- npm
+- XcodeGen, if regenerating the Xcode project from `project.yml`
 
 Install bridge dependencies:
 
@@ -48,6 +116,7 @@ Run bridge checks:
 ```bash
 npm --prefix orchestrator run typecheck
 npm --prefix orchestrator run build
+npm --prefix orchestrator audit --audit-level=high
 ```
 
 Run iOS tests:
@@ -59,7 +128,32 @@ xcodebuild test \
   -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.4.1'
 ```
 
-## Release Workflow
+Run metadata checks:
+
+```bash
+xcodebuild -list -project Runline.xcodeproj
+ruby -c Tools/set_build_number.rb
+plutil -lint ExportOptions-AppStore.plist ExportOptions-TestFlightUpload.plist Runline/Resources/Info.plist Runline/Resources/PrivacyInfo.xcprivacy Runline/Resources/Runline.entitlements
+```
+
+Run secret scanning before public release work:
+
+```bash
+gitleaks detect --source . --redact --verbose
+gitleaks detect --source . --no-git --redact --verbose
+```
+
+## Release Channels
+
+| Channel | Current state | Notes |
+| --- | --- | --- |
+| GitHub | Public repository at `parrisdigital/runline` | Source, docs, issues, releases |
+| npm | `runline-bridge@0.1.2` on `latest` and `beta` | Optional bridge for Cursor SDK mode |
+| TestFlight | Maintainer-managed Runline 1.0 builds | Requires App Store Connect access |
+
+See [docs/RELEASES.md](docs/RELEASES.md) for the maintainer release checklist, [CHANGELOG.md](CHANGELOG.md) for public release notes, and [docs/ROADMAP.md](docs/ROADMAP.md) for the beta roadmap.
+
+## Maintainer TestFlight Workflow
 
 TestFlight and App Store releases are maintainer-only and are not required for contributors.
 
@@ -79,9 +173,20 @@ asc workflow run testflight BUILD_NUMBER:<next-build-number>
 
 Use explicit build numbers so TestFlight stays aligned with the active Runline sequence.
 
+## Security Model
+
+- Cursor API keys are stored on iOS in Keychain.
+- Bridge pairing tokens are stored on iOS in Keychain.
+- Cloud Agent mode works without any Runline backend.
+- Cursor SDK mode uses a user-controlled bridge.
+- The bridge must not log or persist user Cursor API keys.
+- Apple signing material, npm tokens, API keys, `.env` files, archives, IPAs, and provisioning profiles must never be committed.
+
+Report vulnerabilities privately through [SECURITY.md](SECURITY.md).
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [SUPPORT.md](SUPPORT.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 
 ## License
 

SUPPORT.md

@@ -13,6 +13,8 @@ Open a GitHub issue for:
 
 Include the app build number, iOS version, device type, bridge version, and clear reproduction steps when relevant.
 
+For Cursor SDK mode, also include whether the bridge is local LAN, Simulator localhost, or hosted HTTPS. Do not include pairing tokens, API keys, terminal environment dumps, or private repository contents.
+
 ## Security Issues
 
 Do not open public issues for security reports. Use [SECURITY.md](SECURITY.md).