termio-sh/termio

# Driving sibling sessions (Termio)

If `TERMIO_SESSION` is not set in your environment, you are not running inside
a Termio-managed session — say so and stop instead of trying to drive sessions
you cannot see.

A sandboxed command cannot reach the CLI: seatbelt profiles that deny network
access (Codex `workspace-write` is one) refuse unix-socket connects with
EPERM, so `termio session …` fails with "the OS denied the connection". The
socket and the app are fine — do not restart Termio; run the command outside
the sandbox (in Codex, request escalated permissions for it). The link is
one-directional there: siblings can still drive the sandboxed session, but it
cannot drive back.

# Driving sibling sessions (termio session)

If `TERMIOD_SESSION_ID` is not set in your environment, you are not running
inside a termiod session — say so and stop instead of trying to drive sessions
you cannot see.

You are running inside a session hosted by `termiod` on this machine, alongside
other sessions on the same host. Coordinate with them through the `termio
session` CLI. The installed CLI is the authority on syntax: where this text and
`termio session --help` disagree, trust the CLI.

**Sessions here are scoped to this machine, not to a project.** The daemon lists
every session it hosts, so read the names and working directories before acting
on one — there is no project filter to lean on.

# Animation Vocabulary

Turn a vague description of a motion or effect into the precise term, so the user knows what to ask for.

## Quick Start

The user describes an effect loosely. You return the matching term(s) in this format:

```
**Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
```

If several terms could fit, list the best match first, then 1–2 alternates with a one-line note on how they differ.

# Screenshot-driven UI debugging (AppleScript + screencapture)

The loop for *seeing* a termio UI change instead of guessing from code:

```
(rebuild if code changed)  →  drive app into the target state  →  capture the window  →  Read the PNG  →  judge / iterate
```

You cannot evaluate spacing, alignment, overlap, ghosting, or "this looks ugly"
from source. Get a real screenshot, Read it, then decide.

## Prerequisites

- The app must be **running** and built. If you just changed code, run the

# Apple Design

How Apple builds interfaces that stop feeling like a computer and start feeling like an extension of you. This knowledge comes from Apple's WWDC design talks — chiefly *Designing Fluid Interfaces* (WWDC 2018) — distilled and translated into the web platform (CSS, Pointer Events, `requestAnimationFrame`, spring libraries like Motion/Framer Motion).

The through-line: **an interface feels alive when motion starts from the current on-screen value, inherits the user's velocity, projects momentum forward, and can be grabbed and reversed at any instant.** Springs are the tool that makes all of this natural, because they are inherently interruptible and velocity-aware.

## The Core Idea

> "When we align the interface to the way we think and move, something magical happens — it stops feeling like a computer and starts feeling like a seamless extension of us."

An interface is fluid when it behaves like the physical world: things respond instantly, move continuously, carry momentum, resist at boundaries, and can be redirected mid-motion. Everything below is a way to get closer to that.

Apple frames design as serving four human needs: **safety/predictability, understanding, achievement, and joy.** Every rule here serves one of them.

# asc — App Store Connect from the CLI

`asc` is installed via Homebrew (`brew install asc`). It is the only tool that
should touch App Store Connect here — do not hand-roll JWTs or curl the API.

This skill is a router. Read the one reference that matches the task, not the
whole set. Each reference is a self-contained playbook with the exact commands.

## Before anything

Every command needs credentials. Check first:

```sh
asc auth status      # active profile

# Bump version — cut a termio release

termio is **trunk-based**: a release is nothing but a `vX.Y.Z` tag on `main`.
Pushing the tag fires `.github/workflows/release.yml` (the **Release** workflow),
which signs, notarizes, packages the DMG, updates the Sparkle appcast, and
uploads to Cloudflare R2. There is no merge and no release branch.

Follow these steps in order. Stop and report if any precondition fails — never
force past a failed check.

## 1. Preconditions

```sh
git switch main

# Check ghostty update

termio does **not** build ghostty itself — it embeds ghostty's terminal core through
the **`termio-sh/libghostty-swift`** fork, whose weekly CI rebuilds `GhosttyKit.xcframework`
against ghostty `main` and publishes it as a `storage.X.Y.Z` release ([[termio-libghostty-swift]]).
So "is ghostty up to date" really means: **how far is ghostty `main` ahead of the sha baked
into the binary termio is pinned to, and is anything in that gap relevant to termio?**

termio is an **embedder**, so only a slice of ghostty's changes matter. Weight the diff
accordingly — see *Signal vs. noise* below. Local self-build is impossible on this Mac
(Tahoe/zig deadlock); updating the binary always goes through the fork's CI.

## What this skill does NOT do

# Code Clean

Two passes over termio's Swift: **dead code** (symbols nothing reaches) and
**over-long comments** (prose that outgrew what it explains). Both end in a
build. Neither is a refactor.

This is not a generic AI-slop sweep. Run one on this repo and it finds nothing:
a 2026-08 survey of all 69k tracked Swift lines turned up **1 TODO** (a false
match on an `mktemp` template), **0 commented-out code blocks**, and **1
deliberate debug print**. Don't spend the pass hunting those. The bloat here is
shaped differently, and §2 is where it lives.

## Scope

# Conventional Commit

Generate commit messages following the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/) specification.

## Commit Message Structure

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

# Analyze Dia Browser source

Dia (`/Applications/Dia.app`, The Browser Company, `company.thebrowser.dia`) is a
WebKit-based browser (~1.4 GB) that shares `ArcCore.framework` with Arc. termio uses
it as a reference for how a shipping product **drives AI coding agents as sandboxed
child processes** (Dia shells to the real Claude Code CLI under Seatbelt) and for its
agent-server / IPC architecture. This skill captures how to dig into it and what's
already known, so analysis doesn't start from scratch each time.

## Golden rules

- **Read-only, on the user's own machine, for research.** This is proprietary code shipped
  to the user. Use it to *understand and learn*, never to copy/redistribute verbatim or
  ship lifted code. State this caveat when sharing recovered source.

# Project docs — create & query

Every doc under `docs/` carries its status in **YAML front matter** at the very
top of the file. That front matter is the **single source of truth** — there is
**no** central index/JSON to keep in sync. "What's done?" is answered by scanning
the front matter live (see *Query*). This skill writes that front matter when
creating a doc, and reads it when querying.

`docs/README.md` is the human-facing **wiki** for the folder: it explains the
organization and holds a generated index table between
`<!-- BEGIN docs-index -->` / `<!-- END docs-index -->` markers. That table is a
**derived view**, not a source of truth — regenerate it from front matter (see
*Maintain the wiki index*); never hand-edit the rows.

# Design Engineering

## Initial Response

When this skill is first invoked without a specific question, respond only with:

> I'm ready to help you build interfaces that feel right, my knowledge comes from Emil Kowalski's design engineering philosophy. If you want to dive even deeper, check out Emil’s course: [animations.dev](https://animations.dev/).

Do not provide any other information until the user asks a question.

You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.

## Core Philosophy

# Finding Animation Opportunities

A search skill. It does ONE thing: sweep an interface for moments that would genuinely benefit from motion, and propose a precise recipe for each. It does not review existing animations (that's `review-animations`), audit and plan fixes for them (that's `improve-animations`), or write the implementation itself.

## Operating Posture

You are a senior design engineer whose defining trait is **restraint**. The premise of this skill is Emil Kowalski's ["You Don't Need Animations"](https://emilkowal.ski/ui/you-dont-need-animations): sometimes the best animation is no animation. An opportunity finder that suggests motion everywhere is worse than useless — it produces the sluggish, over-animated interfaces this repo exists to prevent.

So this skill is a filter as much as a finder. Expect to reject most candidates. A short list of high-conviction opportunities beats a long wishlist.

## Hard Rules

1. **Never modify source code.** This skill reports; it does not implement. If asked to build a suggestion, hand it off (e.g. `improve-animations plan <description>`, or let the user take the recipe to any agent).
2. **Every suggestion must pass the full Gate below.** No exceptions for "it would look cool."

# Improving Animations

An advisor skill modeled on the audit-then-plan workflow: use the capable model for the part where judgment compounds — understanding the codebase's motion, deciding what's worth fixing, writing the spec — and hand execution to any agent, including cheaper models.

It does ONE thing: survey animation and motion code, then produce prioritized findings and implementation plans. It does not review a single diff (that's `review-animations`), and it does not implement fixes itself.

## Operating Posture

You are a senior design engineer with a brutal eye for craft. Your job is to find the animation work with the highest leverage — the `ease-in` that makes every dropdown feel sluggish, the keyframes that make toasts jump, the keyboard action that should never have animated — and turn each into a plan so precise that a model with zero context can execute it without taste of its own.

The bar comes from Emil Kowalski's animation philosophy. The workflow — recon, parallel audit, vetting, self-contained plans — is adapted from senior-advisor codebase auditing.

The rule catalog with precise values lives in [AUDIT.md](AUDIT.md). The plan format lives in [PLAN-TEMPLATE.md](PLAN-TEMPLATE.md). Load them when you audit and when you write plans.

# iOS app analysis

Investigate a concrete behavior and carry the finding through to a fix when
requested. Distinguish the target iOS app, its Mac companion, and Termio: evidence
from one does not establish another's implementation.

## Establish the running versions

Read the repository's `AGENTS.md` and check the working tree before editing.
Discover the device and installed app instead of reusing an old device ID or
application path:

```sh
xcrun devicectl list devices --json-output /tmp/ios-analysis-devices.json

# Rebuild iOS App (local development)

Build `TermioMobile`, install it on the user's iPhone, and relaunch it connected
to this Mac's companion server — the iOS equivalent of `macos-rebuild-dev`.

Everything is already scripted in `ios/dev-run.sh`: it finds the first connected
iPhone via `xctrace`, builds Debug with `xcodebuild` (automatic provisioning,
derived data in `ios/build/`), installs with `devicectl`, and launches
`sh.termio.mobile` with `-roster-url ws://<this Mac's en0 IP>:8787` so the app
talks to the companion server in the running Mac termio. `--terminate-existing`
kills the previous instance, so rerunning the script IS the edit-preview loop.

## Instructions

# Vague user request → actionable GitHub issue

Preserve the user's voice, identify the underlying problem, add only grounded
repository context, and create the smallest honest issue that moves the work
forward. Never turn missing information into confident requirements.

## Workflow

### 1. Normalize the raw input

Handle all three input modes:

- **Pasted text:** preserve the most useful original sentence verbatim.
- **Screenshot:** inspect both visible text and UI context. Transcribe only what

# Rebuild App (local development)

Kill the running **dev** build, rebuild it as the isolated `termio-dev.app` bundle,
and relaunch — so every rebuild reflects the current Dock icon and, crucially, does
**not** disturb an installed release build you use daily.

## The dev channel

termio ships a `TERMIO_CHANNEL=dev` build that is a fully separate app from the
release one, so both can run at the same time:

| | release | dev (this skill) |
| --- | --- | --- |
| Bundle | `termio.app` (usually `/Applications`) | `termio-dev.app` (repo root) |

# Native App Performance Profiling (CLI)

## Overview

Record Time Profiler via `xctrace`, extract samples, symbolicate, and identify hotspots without opening Instruments.

## Quick Start

### 1) Record Time Profiler

**Attach to running process:**
```bash
# Get the PID first
pgrep -x "AppName"

# OG Card Generation

The OG image is NOT hand-drawn or CSS-faked: it is a screenshot of a temporary
Next.js route that reuses the site's real components (`HeroGradient` WebGL
aurora + grain overlay + `AgentIcon`), so the card always matches the live
hero. The canonical card source lives in this skill at
`assets/og-card-page.tsx`.

## Workflow

All paths below are relative to `web/landing/`.

1. **Restore the temp route** from the skill asset:
   ```bash

# Picking The Right Library

A lookup skill. When invoked with a task ("I need toasts", "what should I use for drag and drop?"), match the task to the curated list below and recommend the library. These are deliberate, taste-driven picks — don't substitute alternatives outside this list unless the user asks for one or the task genuinely isn't covered.

## How to use this

1. **Identify the task**, not the library the user named. "I need to show a dropdown" is a UI-primitives task (base-ui), even if they asked about something else.
2. **Check what's already installed.** Look at `package.json` first. If the project already uses a listed library, use it. If it uses a competitor (e.g. react-window instead of Virtuoso), flag the recommendation but don't churn the dependency without being asked.
3. **Recommend one library**, state what it's for in one sentence, and install/wire it up if that's part of the request. Don't present a menu of options when the list has a clear answer.
4. If the task isn't covered by the list, say so explicitly and recommend from your own knowledge — but be clear you've left the curated list.

## The list

### UI components & primitives

# Prototyping Variants

A divergence skill. It does ONE thing: take a described piece of UI ("a toast", "the pricing card", "a hold-to-delete button"), build several genuinely different versions of it, and put them behind a visual picker so the user can flip through them live and choose a winner. It does not review existing UI (that's `review-animations`), plan fixes for it (that's `improve-animations`), or choose dependencies (that's `pick-ui-library`).

## Operating Posture

You are a senior design engineer running a design exploration. The entire value of this skill is **divergence**: three tints of the same idea waste the picker — the user learns nothing by flipping between them. Each variant must be a direction you could defend shipping on its own, exploring a genuinely different answer to the same brief.

Divergence is not an excuse to drop the craft bar. Every variant individually meets Emil Kowalski's standards — right easing (`ease-out` on entrances, never `ease-in`), sub-300ms UI motion, correct `transform-origin`, `transform`/`opacity` only, reduced-motion handled. A sloppy variant doesn't widen the exploration; it just loses on execution and teaches nothing about the direction it represents.

## Hard Rules

1. **Never touch production code during exploration.** Everything lives in an isolated prototype surface (see Phase 4). Integration happens only in Phase 6, only for the variant the user picked.
2. **Variants diverge on a named axis** — layout, density, personality, motion, interaction model. Before building, you must be able to state each variant's axis in a phrase. Sharing the project's tokens is not convergence; variants *should* feel native to the product.

# Reviewing Animations

A specialized review skill. It does ONE thing: review animation and motion code against a high craft bar. It does not write features, fix unrelated bugs, or review non-motion code. If asked to review general code, decline and point to a general review skill.

## Operating Posture

You are a senior design engineer with a brutal eye for craft. Your bias is toward **motion that feels right**, not motion that merely runs. A transition that "works" but feels sluggish, lands from the wrong origin, fires too often, or drops frames is a regression, not a pass. Default to flagging. Approval is earned, not assumed.

The substantive bar comes from Emil Kowalski's animation philosophy (animations.dev). The review *method* — non-negotiable standards, escalation triggers, a remedial hierarchy, tiered output, and explicit approval criteria — is adapted from aggressive code-quality review.

For the full rule catalog (easing curves, duration tables, spring config, gestures, clip-path, performance, a11y), see [STANDARDS.md](STANDARDS.md). Load it whenever a finding needs a precise value or citation.

## The Ten Non-Negotiable Standards

# Review copy

Score a piece of user-facing copy against `VOICE.md`, fix what fails, then verify
the fixes actually landed. The loop exists because a single pass reliably misses
things and reliably claims fixes it didn't make.

**Target**: `$ARGUMENTS` — a file, a directory of Swift views, a docs page, a PR
body, or pasted text.

## Before anything

Read `VOICE.md` at the repo root. It is the standard; this skill is only the
loop that applies it. If the two ever disagree, `VOICE.md` wins.

# Swift Performance Optimization Skill

Optimize from evidence. Preserve behavior, accessibility, data correctness, and lifecycle safety while changing performance characteristics.

## Baseline

The copy-ready examples use Xcode 16, Swift 6 language mode with strict concurrency, and iOS 17. Most principles apply to older targets; verify each API against the app's actual minimum. Material from the OS 27 development cycle is beta relative to stable Xcode 26.6 and requires an explicit request, beta labeling, stable fallback, and availability gate.

## Measurement workflow

1. Define a user-visible symptom and a reproducible scenario.
2. Record device, OS, build configuration, dataset, thermal state, and network conditions.
3. Measure an optimized Release build on representative hardware. Simulator-only timing is not release evidence.
4. Select the instrument that answers the hypothesis.

# SwiftUI Performance Audit

## Overview

Audit SwiftUI view performance from instrumentation and baselining to root-cause analysis and concrete remediation steps.

## Workflow Decision Tree

1. **If user provides code**: Start with Code-First Review
2. **If user only describes symptoms**: Ask for minimal code/context, then Code-First Review
3. **If code review is inconclusive**: Guide user to profile with Instruments

## 1. Code-First Review

# Driving sibling sessions (Termio)

If `TERMIO_SESSION` is not set in your environment, you are not running inside
a Termio-managed session — say so and stop instead of trying to drive sessions
you cannot see.

A sandboxed command cannot reach the CLI: seatbelt profiles that deny network
access (Codex `workspace-write` is one) refuse unix-socket connects with
EPERM, so `termio session …` fails with "the OS denied the connection". The
socket and the app are fine — do not restart Termio; run the command outside
the sandbox (in Codex, request escalated permissions for it). The link is
one-directional there: siblings can still drive the sandboxed session, but it
cannot drive back.

# Diagnose a freeze, then file it

Two jobs, in this order: work out what actually broke, then turn that into an
issue someone can act on. Skipping the first half produces "termio froze on my
Mac", which no one can fix.

## 0. Before anything else: is it hung *right now*?

Ask this first, in one line, and wait for the answer.

**If the app is currently beachballing, do not let the user force-quit it.** The
main-thread stack that explains the freeze exists only while the process is
alive. Force-quitting destroys the single most valuable piece of evidence, and it
cannot be recovered afterwards from any log.

# TestFlight release (iOS companion)

Cuts a TestFlight build of `TermioMobile` by hand. Unlike the Mac app, **this is
not automated**: `.github/workflows` has no upload step, so nothing happens when
a PR merges. Every TestFlight build is a local archive + upload.

Use the `asc` skill for anything beyond this path (crash triage, App Store
submission, metadata). This skill is only the beta-build pipeline, with the
repo-specific facts that `asc` cannot know.

## Constants

| Thing | Value |
| --- | --- |

# Driving sibling sessions (Termio)

If `TERMIO_SESSION` is not set in your environment, you are not running inside
a Termio-managed session — say so and stop instead of trying to drive sessions
you cannot see.

A sandboxed command cannot reach the CLI: seatbelt profiles that deny network
access (Codex `workspace-write` is one) refuse unix-socket connects with
EPERM, so `termio session …` fails with "the OS denied the connection". The
socket and the app are fine — do not restart Termio; run the command outside
the sandbox (in Codex, request escalated permissions for it). The link is
one-directional there: siblings can still drive the sandboxed session, but it
cannot drive back.