Ascend Flow Coach

Ascend Flow is an open-source iOS conversation companion. During a session that the user explicitly starts, the iPhone microphone is transcribed on-device, the app keeps a rolling conversation context, and it suggests a useful next move.

The suggestion can appear in the iPhone app and, when a compatible Meta display is connected, as a short glanceable card. The goal is to help someone stay present while navigating a conversation—not to replace the conversation with a chatbot.

What the app does

Ascend is built for active, real-world conversations:

• Conversation guidance: suggest a follow-up question, transition, concise response, or respectful exit.
• Conversation modes: Casual, One-on-one, Networking, Sales pitch, Door-to-door sales, Work meeting, Doctor visit, Social confidence, and Vibe Check.
• Human AI: detect the current topic on-device, request a quick OpenAI web-backed research pull, and present several factual cards with sources, context, and natural conversation bridges.
• Vibe Check: during an active session, periodically return a rubric-based signal using observable transcript facts, one next suggestion, and grounded encouragement.
• Conversation history: save an in-progress draft locally as the session runs, then finalize the transcript, summary, topics, analysis, matched knowledge references, and cards shown when the session ends.
• Knowledge base: add personal reference text—talking points, product facts, objections, stories, or transition topics—and use it to shape suggestions for general, networking, or sales goals.
• Export: share a conversation as Markdown through the iOS share sheet, including Apple Notes when available.
• Wearable display: send compact suggestion, Rapid Node, listening-status, and Vibe Check cards through Meta's Device Access Toolkit (DAT).

Ascend does not create contacts, send follow-ups, schedule reminders, create CRM records, or initiate outreach. It is a personal, in-the-moment tool.

The important boundary: phone input, wearable output

The iPhone is the input and processing device. The connected glasses are an optional display and audio-output endpoint.

flowchart LR
    MIC["iPhone microphone"] --> STT["Apple Speech\non-device recognition"]
    STT --> SESSION["Active conversation\nrolling transcript"]
    SESSION --> LOCAL["Local engine\nFoundation Models + Natural Language"]
    SESSION --> OPENAI["Optional OpenAI\nstructured guidance"]
    SESSION --> HUMAN["Human AI\nOpenAI web research"]
    LOCAL --> PHONE["iPhone UI"]
    OPENAI --> PHONE
    HUMAN --> PHONE
    PHONE --> DISPLAY["Meta DAT\nglanceable cards"]
    SESSION --> STORE["SwiftData\nlocal history + knowledge base"]

Loading

The audio capture code explicitly selects the iPhone microphone. It does not depend on an unsupported continuous ambient microphone stream from the glasses. Audio buffers are used for the temporary speech-recognition session; the app does not write microphone audio files. When the user ends a session with detected speech, the transcript and analysis are saved locally; sessions with no speech are not saved.

The iPhone owns long text, scrolling, and swipe navigation. Display cards are intentionally short so they can be read at a glance. The app shows microphone and transcription status on the phone and sends listening-state cards such as MIC ON to the display. The phone-side card preview can be swiped left or right, and display cards include a visible Dismiss action; the public Meta DAT 0.9.0 API does not expose a general swipe callback for custom cards.

Human AI checks the rolling transcript every ten seconds. Topic extraction happens on-device first; a changed topic starts one bounded OpenAI web-search request. The phone presents the returned cards in a horizontal pager, with a vertical scroll view for long facts and clickable cited sources. When glasses output is enabled, the selected card is sent to DAT with Previous, Next, and Dismiss controls. Every generated Human AI card is included in the active conversation's local card history with the topic, reason, and transcript snapshot.

AI engines and secure access

The shipped Ascend experience uses OpenAI for richer live guidance and Vibe Check when secure device access is ready. Apple Speech, Apple's Natural Language sentence embedding, and the weak-linked iOS 26 Foundation Models text engine remain on-device paths; deterministic suggestions remain available when Apple Intelligence is unavailable. The app explains the active engines in Output & AI settings; it does not expose a server URL, gateway token, or API-key field to users.

On-device fallback: no OpenAI key required

The local suggestion engine, optional Apple Foundation Models text generation, local Vibe Check rubric, Apple Speech recognition, topic extraction, and local sentence embedding path do not require an OpenAI account, server, or API key. They remain available when the device is offline or secure OpenAI access is unavailable. Human AI does not invent replacement facts on-device when web research is unavailable; it clearly reports that research is waiting or unavailable while the transcript continues to be captured locally.

Speech recognition also requests Apple's on-device recognition path. Availability depends on the iPhone, language, permissions, and current Apple speech-recognition support.

OpenAI mode: automatic hosted setup

The app contacts the configured HTTPS service when it opens and uses Apple App Attest to request a short-lived device session. Railway keeps the provider key; the iPhone receives only the session credential needed for that device. If setup cannot complete, Ascend continues with on-device guidance. Microphone audio is never sent to OpenAI.

An open-source fork should deploy its own copy of gateway/, set its own server-side OpenAI key, and change the signed app's gateway configuration. Do not add provider keys to the iOS target, source code, screenshots, or a committed .env file.

Release builds and the HTTPS gateway

The release path keeps the provider key on a server. The iPhone sends transcript text—not microphone audio—to /v1/responses or /v1/embeddings. The gateway forwards structured requests to OpenAI, applies authentication and request limits, and does not persist request bodies.

The current project contains a default Ascend gateway URL and attempts automatic App Attest provisioning when OpenAI mode is selected. A public fork should not assume it can use that service: App Attest is tied to the signed bundle identifier and Apple Developer Team, and the gateway's policy may reject a different fork.

For your own release gateway:

1. Deploy gateway/ to a private HTTPS service.
2. Set OPENAI_API_KEY only in the service's environment.
3. Set a long random ASCEND_GATEWAY_TOKEN and ASCEND_SESSION_SECRET.
4. Set APP_ATTEST_BUNDLE_ID and APP_ATTEST_TEAM_ID to your signed app's values.
5. Update the app's gateway base URL in ConversationHelper/App/AppBrand.swift or an equivalent release configuration.
6. Keep all tokens, provider keys, and Meta client tokens out of Git.

For local gateway development, copy gateway/.env.example to the ignored gateway/.env, fill it with your own values, then follow gateway/README.md. Point the fork's AppBrand.gatewayBaseURL at its HTTPS /v1 URL. A phone cannot reach a gateway running at its own localhost; use an HTTPS development endpoint or a LAN address with the appropriate iOS transport configuration.

Requirements

iOS app

• macOS with Xcode and an Apple development team.
• iOS 17.2 or later; the project is Swift 6 with strict concurrency enabled.
• The shipped target is iPhone-only (TARGETED_DEVICE_FAMILY=1). iPad layouts, screenshots, and distribution are intentionally out of scope because Meta display pairing is phone-based.
• A physical iPhone for microphone, on-device speech recognition, App Attest, and DAT testing. The simulator cannot validate the glasses workflow.
• A compatible Meta wearable display and the Meta AI app if you want to test display cards.
• An OpenAI key or your own gateway only if you choose a network-backed OpenAI path.

Gateway

• Node.js 20 or later.
• An HTTPS deployment for device testing and release use.
• Your own OpenAI API key stored as a server environment variable.
• A durable/shared challenge and session store before operating more than one gateway instance. The current service uses short-lived in-memory state and is intentionally a small development gateway.

Build the iOS app

Clone the repository and open the checked-in Xcode project:

git clone https://github.com/mbishopfx/bishoptech-ascendflow.git
cd bishoptech-ascendflow
open ConversationHelper.xcodeproj

The project already contains the Swift Package Manager resolution for Meta DAT 0.9.0. Install XcodeGen only if you need to regenerate the project after editing project.yml:

brew install xcodegen
xcodegen generate --spec project.yml --project .

In Xcode:

1. Select the ConversationHelper application target.
2. Select your Apple development team under Signing & Capabilities.
3. Use your own bundle identifier for a fork, and keep it consistent with your App Attest and Meta configuration.
4. Build to a physical iPhone.

The existing com.bishoptech.conversationhelper identifier, conversationhelper:// callback, and Apple team value are the maintainer's development configuration. They are not credentials you can reuse for an independently signed fork.

Connect Meta display hardware

The complete hardware checklist is in META_SETUP.md. The short version is:

1. Install or update Meta AI and pair the glasses with the iPhone.
2. Update the glasses firmware and Meta AI app.
3. Turn on Developer Mode for the paired glasses in Meta AI.
4. Run Ascend on the physical iPhone.
5. Register through Meta AI, connect the display, and send the demo card.
6. Grant microphone and speech-recognition permissions.
7. Start an explicitly consented session, speak near the iPhone, confirm the phone shows audio/transcription activity, and end the session when finished.

For distribution outside Meta Developer Mode, create your own Wearables Developer Center project, release channel, iOS bundle registration, application ID, and client token. Keep the client token in local Xcode settings or an ignored .xcconfig; do not commit it.

Use the app correctly

1. Choose a conversation mode before starting. Sales and networking modes use different knowledge goals and suggestion rules.
2. Add knowledge-base references before a session when you want the app to use product facts, objections, stories, or transition topics.
3. Select the retrieval provider that matches the privacy and latency you want. Re-index references after switching embedding providers.
4. Start the session only after the people involved understand that the phone microphone is active. Ascend requires explicit session consent and exposes microphone/transcription indicators.
5. Keep the iPhone close enough to hear the room. The glasses are not the assumed microphone.
6. Treat suggestions as prompts, not instructions. Stay natural and use your own judgment.
7. End the session when the conversation is over. Review, export, share, or delete the saved local record from the app.

Vibe Check is an active-session feature. It does not run in the background or continue listening after the session is paused or ended. Its rubric is limited to observable transcript signals; it is not a diagnosis of emotion, personality, identity, consent, or intent. Doctor Visit mode organizes questions and observations but does not provide medical advice.

Knowledge base behavior

Knowledge entries are stored locally as raw text plus a semantic vector. Each entry has a goal—General, Networking, or Sales pitch—and a category such as Transition topics, Product or service, Personal context, or General reference.

During a live session, Ascend compares the current transcript and mode to those references. A relevant match can become a transition, an adapted product talking point, or a question. In Sales pitch and Door-to-door sales modes, matched product and objection-handling references receive more weight. The AI prompt treats reference text as untrusted material and does not allow it to create external actions.

Gateway API

The Node service exposes:

Route	Purpose
GET /health	Deployment health check
GET /v1/device/challenge	Create an App Attest challenge
POST /v1/device/attest	Verify the device and issue a short-lived session
POST /v1/responses	Authenticated structured guidance, analysis, Vibe Check, and Human AI web-research proxy
POST /v1/embeddings	Authenticated embedding proxy for semantic retrieval

The client contract and current operational limitations are documented in ASCEND_AI_GATEWAY.md. The product audit in ASCEND_PRODUCT_AUDIT.md covers product hardening, while ASCEND_APP_STORE_READINESS.md is the release gate for Apple policy, App Store Connect metadata, privacy labels, and reviewer instructions.

Repository map

ConversationHelper/
  App/             app state, settings, and branding
  Models/          SwiftData and conversation domain models
  Services/        audio, transcription, AI, gateway, knowledge, and DAT logic
  Views/           SwiftUI interface and display-facing controls
gateway/            Node HTTPS proxy and App Attest provisioning routes
ConversationHelperTests/
META_SETUP.md       Meta DAT, signing, and physical-device setup
ASCEND_AI_GATEWAY.md
ASCEND_PRODUCT_AUDIT.md
project.yml         XcodeGen project definition

Testing and contribution notes

The unit tests are in ConversationHelperTests/. Run them from Xcode against an installed iOS Simulator, or use a destination available on your machine:

xcodebuild -project ConversationHelper.xcodeproj \
  -scheme ConversationHelper \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  test

That test path does not prove microphone or Meta display behavior. Physical-device testing is required for permissions, on-device speech recognition, App Attest, Meta AI registration, display cards, and audio routing.

Before opening a pull request:

• Do not include keys, tokens, transcripts, device identifiers, or screenshots containing personal data.
• Do not weaken the active-session consent or visible microphone state.
• Keep local AI fallback behavior intact when a network request fails.
• Preserve the boundary between transcript text and microphone audio.
• Run git diff --check and the relevant Xcode tests.

Privacy and license

Ascend is a personal, local-first project. When OpenAI is selected, transcript and matched reference text can leave the device; microphone audio is not sent to the gateway. Read ASCEND_APP_STORE_READINESS.md and the live Ascend privacy section before distributing a build. The older ASCEND_PRIVACY_ADDENDUM_DRAFT.md remains a design reference, not a substitute for the published policy. Review SECURITY.md before reporting a vulnerability.

The source code and documentation are licensed under the MIT License. Ascend is an independent project and is not affiliated with Meta Platforms, Inc. Meta and related product names are trademarks of their respective owners.