--- name: TZGyn-skill description: Use proactively for ANY development task in TZGyn's working directories — starting a new project in any language (Go, Rust, TypeScript, not just Swift), cloning/studying/porting a third-party repo (reference material goes in .reference/, never the working root), working in an existing TZGyn repo, creating Gitea repos, publishing to the TZGyn Homebrew tap (casks for GUI apps, formulae for CLIs), signing and notarizing macOS builds, cutting releases, or extending this skill. Load it at the start of any dev session on this machine even when the task doesn't mention Gitea, Homebrew, or macOS. --- # TZGyn dev skill Personal conventions for TZGyn projects. Source of truth is the Git repo `https://gitea.tzgyn.dev/TZGyn/TZGyn-skill`; it is installed as a global Crush skill at `~/.agents/skills/TZGyn-skill` (a symlink to the checkout, so editing the repo updates the live skill). The reference implementations to copy from are `~/Git/kapture` and `~/Git/konference` (macOS menu-bar apps); for iOS, `~/Git/koins/apps/ios`. ## Ground rules - **Applies from the first command of any session**, in any TZGyn working directory — before any clone, scaffold, or build. Third-party repos cloned to study, port, or compare against go straight into `.reference/` (section 2); waiting until the project is a git repo is too late. - **Host**: Gitea at `https://gitea.tzgyn.dev`, owner `TZGyn`, `tea` login name `gitea.tzgyn.dev`. SSH: `git@gitea.tzgyn.dev:TZGyn/.git`. - **Always print the upgrade script** (the `brew` commands below) in the final answer after any release or version bump. The user wants it every time. - **Every macOS GUI release must be notarized and stapled.** An unnotarized build is not a release: never publish one, and never paper over Gatekeeper with `xattr -dr com.apple.quarantine` or `brew install --cask --no-quarantine`. If notarization fails, fix the cause (see [Troubleshooting](#notarization-troubleshooting)) before publishing. (iOS apps are not notarized — Apple has no such step; see section 6.) - Never commit build artifacts. `.gitignore` covers `.build/`, `*.app/`, `dist/`, `.swiftpm/`, `xcuserdata/`, `DerivedData/`, `.DS_Store`. (`go build ./...` drops a binary next to the source — ignore it explicitly.) - Never commit secrets (`.p8`, API keys) or push to a remote unless asked. - **Reference material goes in `.reference/`, never in the repo.** Every project that is modelled on another app or repo gets a `.reference/` folder with a `.gitignore` containing `*` — see [Reference material](#2-reference-material-reference) for the exact shape and what to put in it. - Commit messages: concise, why-focused, first line < 72 chars; add a body only when it helps a future reader. - Prefer SwiftPM (Swift/SwiftUI) for macOS apps; no external dependencies. ## 1. New project on Gitea ```bash # 1. Create the repo (as the authenticated user). tea repos create --name --desc "" --login gitea.tzgyn.dev # Do NOT pass --owner TZGyn: that hits /orgs/TZGyn/repos and 404s for a user. # 2. Initialise and push. cd ~/Git/ git init -b main git add -A && git commit -m "" git remote add origin https://gitea.tzgyn.dev/TZGyn/.git git push -u origin main ``` Scaffold every repo with `README.md`, `AGENTS.md` (architecture + commands + gotchas), `.gitignore`, and `.reference/` (see below). See `~/Git/simpletopbar` for the minimal shape: `Package.swift`, `Sources//*.swift`, `build-app.sh`, `release.sh`, `scripts/`. ## 2. Reference material (`.reference/`) Apps and repos that a project is modelled on are research input, not source code. Keep them in an untracked `.reference/` folder at the repo root so they are available to every session without ever entering the repository: ```bash mkdir -p ~/Git//.reference printf '*\n' > ~/Git//.reference/.gitignore ``` - The `.gitignore` **inside** `.reference/` contains a single `*`. Ignore the whole folder there, not in the repo's root `.gitignore`: the folder is then self-contained and stays untracked even if the root ignore file is rewritten. - **Any repo cloned to study, port, or compare against is reference material.** When asked to "check out this repo" (e.g. to reimplement it in another language), create `.reference/` and its `.gitignore` as the very first step and clone straight into it — never into the working root, even when the project is not a git repo yet. - Clone reference repos inside it: `git clone --depth 1 .reference/`. Do not vendor them into `Sources/` or `vendor/`. - Write one short note per reference (`tangerine.md`, `filee.md`) covering: what the app does, its interaction model, the formats/features worth matching, and what we deliberately skip. Notes are untracked too — that is fine; they are for the next session, not for the public repo. - Check licences before reusing code. MIT/Apache-2.0 code can be adapted with attribution; never copy assets, icons, or code from a closed app. - `.reference/` is never committed, never released, and never required to build. ## 3. Homebrew tap - The tap clone lives at **`~/.cache/homebrew-tap`** (origin `https://gitea.tzgyn.dev/TZGyn/homebrew-tap.git`). - Layout: **GUI apps → `Casks/.rb`**; **CLI tools → `Formula/.rb`**. - After pushing, sync Homebrew's own clone: ```bash git -C ~/.cache/homebrew-tap add -A git -C ~/.cache/homebrew-tap commit -m "Add cask" git -C ~/.cache/homebrew-tap push git -C /opt/homebrew/Library/Taps/tzgyn/homebrew-tap pull --ff-only brew audit --cask tzgyn/tap/ # or: brew audit --formula tzgyn/tap/ ``` - Users tap once (non-GitHub taps need the full URL): ```bash brew tap TZGyn/tap https://gitea.tzgyn.dev/TZGyn/homebrew-tap.git brew trust TZGyn/tap ``` ### Cask (GUI app) ```ruby cask "" do version "X.Y.Z" sha256 "" url "https://gitea.tzgyn.dev/TZGyn//releases/download/v#{version}/.zip" name "" desc "" homepage "https://gitea.tzgyn.dev/TZGyn/" app ".app" end ``` ### Formula (CLI) ```ruby class < Formula desc "" homepage "https://gitea.tzgyn.dev/TZGyn/" url "https://gitea.tzgyn.dev/TZGyn//releases/download/v0.1.0/-0.1.0-darwin-arm64.tar.gz" sha256 "" version "0.1.0" def install bin.install "" end end ``` ## 4. Releasing a macOS GUI app Two scripts per repo: `build-app.sh ` and `release.sh `. 1. **Build + sign** (`build-app.sh`): `swift build -c release` → handwritten `Info.plist` (NOT generated from `Package.swift`) → `make-icon.sh` → sign with the Developer ID identity resolved from the login keychain (`security find-identity -v -p codesigning | awk '/Developer ID Application:/{print $2;exit}'`), falling back to ad-hoc (`-`). GUI apps set `LSUIElement = true` and `CFBundleIdentifier = dev.tzgyn.`. 2. **Notarize + staple + zip** (`release.sh`): build → `ditto -c -k --keepParent .app dist/.zip` → submit to Apple → staple → re-zip → print sha256. See [Notarization](#5-notarization) for the credentials. 3. **Publish the release** and attach the zip: ```bash tea releases create --tag v --title " " \ --note "" --asset dist/.zip \ --repo TZGyn/ --login gitea.tzgyn.dev ``` Push `main` **before** this: `tea` tags the remote default branch, so an unpushed commit means the tag points at source that is not what shipped (the binary would contain changes absent from the tag). If it already happened, re-point the tag: `git push origin :refs/tags/v` then `git tag -f v && git push origin v`. 4. **Bump the cask** (`version` + `sha256`), push the tap, pull Homebrew's clone, `brew audit`. Verify by downloading the asset back and comparing the sha256, and `spctl -a -vv .app` → `accepted` / `source=Notarized Developer ID`. If `spctl` does not say `source=Notarized Developer ID`, stop and fix notarization first — do not publish the release or the cask. 5. **Print the upgrade script**: ```bash brew update brew upgrade --cask ``` ## 5. Notarization Signing identity: `Developer ID Application: Teh Zi Gyn (RX6767S6BW)`. App Store Connect API key (shared with Kapture): | Value | Where | | --------- | ------------------------------------------------------------ | | Key file | `~/.config/kapture/AuthKey_K5KXMMSB28.p8` | | Key ID | `K5KXMMSB28` | | Issuer ID | `3e25e5dc-8b75-453f-a71c-c7f3feaac628` (not secret) | | Team ID | `RX6767S6BW` | Signing must use a hardened runtime and a secure timestamp: ```bash codesign --force --options runtime --timestamp --sign "$IDENT" ".app" ``` Submit and verify: ```bash xcrun notarytool submit dist/.zip \ --key "$HOME/.config/kapture/AuthKey_K5KXMMSB28.p8" \ --key-id K5KXMMSB28 --issuer 3e25e5dc-8b75-453f-a71c-c7f3feaac628 \ --wait --output-format json xcrun stapler staple .app && xcrun stapler validate .app spctl -a -vv .app # want: accepted, source=Notarized Developer ID ``` `release.sh` **must** notarize. Treat any skip or failure as a failed release: do not publish the tag, the release, or the cask, and do not suggest quarantine workarounds (`xattr -dr com.apple.quarantine`, `brew install --cask --no-quarantine`) — those hand the user a build macOS rejects. Only publish once `spctl -a -vv .app` reports `accepted` with `source=Notarized Developer ID`. ### Notarization troubleshooting | Symptom | Cause / fix | | --- | --- | | `HTTP status code: 403. A required agreement is missing or has expired.` | The **Apple Developer Program License Agreement** for the team is unsigned or expired. The Account Holder must accept it in App Store Connect → **Business → Agreements** *and* at `developer.apple.com/account` → **Agreements**. Account-wide: every call fails, including read-only `notarytool history`, until it is accepted; allow a few minutes to propagate. | | The same 403 *after* accepting | The wrong agreement was accepted (App Store Connect "Paid Apps" instead of the Program License Agreement) or it was accepted under a different team's account. | | `401 Authentication credentials are incorrect` | Wrong key id / issuer, or the key belongs to another team. | Confirm the team before blaming the credentials — do not "fix" this by switching teams or re-signing: ```bash security find-identity -v -p codesigning # the Developer ID team must match the key's team spctl -a -vv /Applications/.app # an already-notarized app proves the team/key pair works xcrun notarytool history --key ... --key-id ... --issuer ... # 403 here = account agreement, not the app ``` `notarytool history` failing the same way as the submit is the tell: the problem is the account, not the bundle, so there is nothing to change in the app or the scripts. ## 6. iOS apps Native SwiftUI iOS apps are built with **XcodeGen** — no CocoaPods, no SwiftPM packages. `project.yml` is the source of truth; the generated `.xcodeproj/` is gitignored and regenerated after any file is added or removed. Working reference: `~/Git/koins/apps/ios`. One-time tool install: `brew install xcodegen`. ### Layout and project file ``` apps/ios/ project.yml XcodeGen project (committed) / Swift sources, assets, Info.plist /Bridge/ optional ObjC/ObjC++ bridge + bridging header /Libs/ optional prebuilt static archives (not bundled) .gitignore .xcodeproj/, build/, DerivedData/, xcuserdata/ ``` Minimal `project.yml`: ```yaml name: options: bundleIdPrefix: dev.tzgyn deploymentTarget: iOS: "16.0" xcodeVersion: "16.0" settings: base: SWIFT_VERSION: "5.0" ENABLE_USER_SCRIPT_SANDBOXING: NO targets: : type: application platform: iOS sources: - path: excludes: - "Libs" # static archives are linked, never bundled settings: base: PRODUCT_BUNDLE_IDENTIFIER: dev.tzgyn. CODE_SIGN_STYLE: Automatic DEVELOPMENT_TEAM: RX6767S6BW CODE_SIGNING_ALLOWED[sdk=iphonesimulator*]: NO SWIFT_OBJC_BRIDGING_HEADER: /Bridge/-Bridging-Header.h LIBRARY_SEARCH_PATHS: - "$(SRCROOT)//Libs" OTHER_LDFLAGS[sdk=iphoneos*]: - "$(inherited)" - "-l_device" OTHER_LDFLAGS[sdk=iphonesimulator*]: - "$(inherited)" - "-l_merged" info: path: /Info.plist properties: UILaunchScreen: {} UISupportedInterfaceOrientations: - UIInterfaceOrientationPortrait UIUserInterfaceStyle: Dark NSCameraUsageDescription: Scan a QR code. NSFaceIDUsageDescription: Unlock the app and approve payments. ``` - Bundle id convention: `dev.tzgyn.` (Koins predates it and uses `com.koins.app`; keep an existing id rather than migrating). - Privacy usage strings are mandatory. A missing `NSCameraUsageDescription`, `NSPhotoLibraryUsageDescription`, or `NSFaceIDUsageDescription` crashes the app the first time that API is used. - Prebuilt static archives need separate device and simulator builds; select them with `OTHER_LDFLAGS[sdk=…]` as above. If ObjC categories fail to load, link with `-Wl,-force_load,$(SRCROOT)//Libs/lib.a` instead. - The simulator target uses `CODE_SIGNING_ALLOWED[sdk=iphonesimulator*] = NO`; device builds use automatic signing with the TZGyn team. After adding/removing files or changing `project.yml`: ```bash cd apps/ios && xcodegen generate ``` ### Build ```bash cd apps/ios xcodegen generate # Simulator (Apple Silicon) xcodebuild -project .xcodeproj -scheme -configuration Debug \ -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \ ARCHS=arm64 ONLY_ACTIVE_ARCH=NO -derivedDataPath /tmp/-dd build # Device xcodebuild -project .xcodeproj -scheme -configuration Debug \ -sdk iphoneos -destination 'generic/platform=iOS' \ -allowProvisioningUpdates -derivedDataPath /tmp/-dd-device build ``` `-allowProvisioningUpdates` creates/refreshes the development profile automatically; no manual profile management is needed with the paid team. Derived data under `/tmp` is lost on reboot — rebuild rather than chasing a missing `.app`. ### Install on a physical iPhone (over the network, no cable) This is the normal way to update a TZGyn iPhone app: build the `iphoneos` slice, then install over Wi-Fi with `devicectl`. `simctl` only works with simulators. One-time setup: 1. Connect the iPhone once with a cable, open Xcode → **Window → Devices and Simulators**, select the phone, and tick **Connect via network**. 2. On the phone: **Settings → Privacy & Security → Developer Mode → On** (requires a reboot), then trust the Mac when prompted. Wireless install and launch: ```bash # 1. Find the paired phone (UDID, ECID, name and DNS name are all accepted). xcrun devicectl list devices # want: .coredevice.local available (paired) # 2. Install the device build. This replaces the app in place and keeps its data. xcrun devicectl device install app --device --timeout 180 \ /tmp/-dd-device/Build/Products/Debug-iphoneos/.app # 3. Launch it (the phone must be unlocked). xcrun devicectl device process launch --device ``` - Use the **device** build path (`-dd-device/.../Debug-iphoneos`), not the simulator build; installing the wrong slice fails. - `--timeout 180` is deliberate: the app bundle transfer over Wi-Fi can take a while, and the default timeout is easy to hit. - Installing over the network **does not delete app data**. Wallet files, seeds and preferences survive updates (seeds live in the Keychain). - If the device shows `unavailable`, or install fails with `Network.NWError error 60 - Operation timed out`, the phone is asleep, locked, or off Wi-Fi. Wake/unlock it, keep it on the same network, retry. A timed-out install leaves the previous build installed. - Launch errors with `BSErrorCodeDescription = Locked` mean exactly that: the phone must be unlocked for the launch. - `devicectl` is for physical devices only; use `simctl` for simulators. ### Simulator workflow ```bash xcrun simctl list devices available xcrun simctl boot open -a Simulator xcrun simctl install /tmp/-dd/Build/Products/Debug-iphonesimulator/.app xcrun simctl launch xcrun simctl io screenshot /tmp/screen.png xcrun simctl get_app_container data ``` - Files the app writes (self-test reports, exported data) can be read from the data container printed by `get_app_container`. - Simulator preferences are cached by `cfprefsd`; `xcrun simctl spawn defaults delete …` often does not stick. To reset a preference: terminate the app, `xcrun simctl spawn launchctl stop com.apple.cfprefsd.xpc.daemon`, then edit or delete the key in the plist directly. ### Local self-tests Gate verification code behind launch arguments, write the report into the app's Documents folder, and read it back from the container (console output is not always reachable): ```bash xcrun simctl launch -SelfTest DATA=$(xcrun simctl get_app_container data) cat "$DATA/Documents/-selftest.txt" ``` For unified-log checks: ```bash xcrun simctl spawn log show --last 1m \ --predicate 'subsystem == ""' --style compact ``` Keep network tests explicit (`-SelfTestNetwork`) so the default launch is offline and fast. ### Signing and distribution - **Team: `RX6767S6BW` for every TZGyn app, macOS and iOS.** iOS device builds use automatic signing (`CODE_SIGN_STYLE: Automatic`, `DEVELOPMENT_TEAM: RX6767S6BW`) and `-allowProvisioningUpdates`; no manual profiles. - **iOS apps are not notarized.** Apple has no notarization step for iOS — device installs are gated by code signing + Developer Mode. Do not add a `notarytool`/`stapler` step to an iOS build, and do not `spctl` an `iphoneos` app. - **macOS GUI releases are always notarized and stapled** (section 5), with the shared App Store Connect key: `~/.config/kapture/AuthKey_K5KXMMSB28.p8`, key ID `K5KXMMSB28`, issuer `3e25e5dc-8b75-453f-a71c-c7f3feaac628`, team `RX6767S6BW`. Never publish a macOS release until `spctl -a -vv` reports `accepted` / `source=Notarized Developer ID`. - **App Store Connect** (only if TestFlight/App Store is ever used) reuses the same key; koins does not use it yet. - Android is not codified yet; ask which stack (native, Compose, RN, EAS) before assuming. ## 7. Extending this skill (self-improvement) This skill is meant to grow. When the user asks for a new behaviour, preference, or convention: 1. Edit the relevant section of `SKILL.md` (add a new section if it is a new topic). Keep it concrete: exact commands, paths, and templates. 2. Keep it truthful — only document what has actually worked; delete steps that became stale (e.g. a changed path or flag). 3. Commit and push: ```bash cd ~/Git/TZGyn-skill git add -A && git commit -m "" git push ``` 4. The installed copy is a symlink, so it updates immediately; a new Crush session picks it up. Confirm with `crush_info` (the skill should appear under `[skills]`). Prefer updating this skill over repeating ad-hoc instructions in a project: if a convention applies to more than one repo, it belongs here.