@intent-systems/nexus 2026.1.5-3

package/skills/telegram/docs/setup.md

@@ -0,0 +1,41 @@
+# Telegram Setup
+
+## Create a bot
+
+1. Message @BotFather on Telegram.
+2. Run `/newbot`.
+3. Choose a name and username.
+4. Copy the token.
+
+## Store the token
+
+```bash
+export TELEGRAM_BOT_TOKEN="your-token-here"
+```
+
+1Password example:
+
+```bash
+op item create --category login \
+  --title "Telegram Bot Token" \
+  --vault Personal \
+  credential="YOUR_BOT_TOKEN_HERE"
+```
+
+## Enable Telegram in Nexus
+
+Add to `~/nexus/state/nexus.json`:
+
+```json5
+{
+  telegram: {
+    enabled: true
+  }
+}
+```
+
+The gateway reads `TELEGRAM_BOT_TOKEN` from env or `telegram.botToken` in config.
+
+## Verify
+
+Start the gateway and send a DM to the bot.

package/skills/telegram/docs/webhook.md

@@ -0,0 +1,17 @@
+# Telegram Webhook Mode
+
+Polling is the default. For production, you can enable webhooks.
+
+Set in `~/nexus/state/nexus.json`:
+
+```json5
+{
+  telegram: {
+    enabled: true,
+    webhookUrl: "https://your.domain/telegram-webhook",
+    webhookPath: "/telegram-webhook"
+  }
+}
+```
+
+See `docs/telegram.md` for full details and proxy settings.

package/skills/things-mac/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: things-mac
+description: Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database). Use when a user asks Nexus to add a task to Things, list inbox/today/upcoming, search tasks, or inspect projects/areas/tags.
+homepage: https://github.com/ossianhempel/things3-cli
+metadata: {"nexus":{"emoji":"✅","os":["darwin"],"requires":{"bins":["things"]},"install":[{"id":"go","kind":"go","module":"github.com/ossianhempel/things3-cli/cmd/things@latest","bins":["things"],"label":"Install things3-cli (go)"}]}}
+---
+
+# Things 3 CLI
+
+Use `things` to read your local Things database (inbox/today/search/projects/areas/tags) and to add/update todos via the Things URL scheme.
+
+Setup
+- Install (recommended, Apple Silicon): `GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`
+- If DB reads fail: grant **Full Disk Access** to the calling app (Terminal for manual runs; `Nexus.app` for gateway runs).
+- Optional: set `THINGSDB` (or pass `--db`) to point at your `ThingsData-*` folder.
+- Optional: set `THINGS_AUTH_TOKEN` to avoid passing `--auth-token` for update ops.
+
+Read-only (DB)
+- `things inbox --limit 50`
+- `things today`
+- `things upcoming`
+- `things search "query"`
+- `things projects` / `things areas` / `things tags`
+
+Write (URL scheme)
+- Prefer safe preview: `things --dry-run add "Title"`
+- Add: `things add "Title" --notes "..." --when today --deadline 2026-01-02`
+- Bring Things to front: `things --foreground add "Title"`
+
+Examples: add a todo
+- Basic: `things add "Buy milk"`
+- With notes: `things add "Buy milk" --notes "2% + bananas"`
+- Into a project/area: `things add "Book flights" --list "Travel"`
+- Into a project heading: `things add "Pack charger" --list "Travel" --heading "Before"`
+- With tags: `things add "Call dentist" --tags "health,phone"`
+- Checklist: `things add "Trip prep" --checklist-item "Passport" --checklist-item "Tickets"`
+- From STDIN (multi-line => title + notes):
+  - `cat <<'EOF' | things add -`
+  - `Title line`
+  - `Notes line 1`
+  - `Notes line 2`
+  - `EOF`
+
+Examples: modify a todo (needs auth token)
+- First: get the ID (UUID column): `things search "milk" --limit 5`
+- Auth: set `THINGS_AUTH_TOKEN` or pass `--auth-token <TOKEN>`
+- Title: `things update --id <UUID> --auth-token <TOKEN> "New title"`
+- Notes replace: `things update --id <UUID> --auth-token <TOKEN> --notes "New notes"`
+- Notes append/prepend: `things update --id <UUID> --auth-token <TOKEN> --append-notes "..."` / `--prepend-notes "..."`
+- Move lists: `things update --id <UUID> --auth-token <TOKEN> --list "Travel" --heading "Before"`
+- Tags replace/add: `things update --id <UUID> --auth-token <TOKEN> --tags "a,b"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags "a,b"`
+- Complete/cancel (soft-delete-ish): `things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`
+- Safe preview: `things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`
+
+Delete a todo?
+- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).
+- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.
+
+Notes
+- macOS-only.
+- `--dry-run` prints the URL and does not open Things.

package/skills/tmux/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: tmux
+description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
+metadata: {"nexus":{"emoji":"🧵","os":["darwin","linux"],"requires":{"bins":["tmux"]}}}
+---
+
+# tmux Skill (Nexus)
+
+Use tmux only when you need an interactive TTY. Prefer bash background mode for long-running, non-interactive tasks.
+
+## Quickstart (isolated socket, bash tool)
+
+```bash
+SOCKET_DIR="${NEXUS_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nexus-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nexus.sock"
+SESSION=nexus-python
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+After starting a session, always print monitor commands:
+
+```
+To monitor:
+  tmux -S "$SOCKET" attach -t "$SESSION"
+  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+## Socket convention
+
+- Use `NEXUS_TMUX_SOCKET_DIR` (default `${TMPDIR:-/tmp}/nexus-tmux-sockets`).
+- Default socket path: `"$NEXUS_TMUX_SOCKET_DIR/nexus.sock"`.
+
+## Targeting panes and naming
+
+- Target format: `session:window.pane` (defaults to `:0.0`).
+- Keep names short; avoid spaces.
+- Inspect: `tmux -S "$SOCKET" list-sessions`, `tmux -S "$SOCKET" list-panes -a`.
+
+## Finding sessions
+
+- List sessions on your socket: `{baseDir}/scripts/find-sessions.sh -S "$SOCKET"`.
+- Scan all sockets: `{baseDir}/scripts/find-sessions.sh --all` (uses `NEXUS_TMUX_SOCKET_DIR`).
+
+## Sending input safely
+
+- Prefer literal sends: `tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"`.
+- Control keys: `tmux -S "$SOCKET" send-keys -t target C-c`.
+
+## Watching output
+
+- Capture recent history: `tmux -S "$SOCKET" capture-pane -p -J -t target -S -200`.
+- Wait for prompts: `{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern'`.
+- Attaching is OK; detach with `Ctrl+b d`.
+
+## Spawning processes
+
+- For python REPLs, set `PYTHON_BASIC_REPL=1` (non-basic REPL breaks send-keys flows).
+
+## Windows / WSL
+
+- tmux is supported on macOS/Linux. On Windows, use WSL and install tmux inside WSL.
+- This skill is gated to `darwin`/`linux` and requires `tmux` on PATH.
+
+## Orchestrating Coding Agents (Codex, Claude Code)
+
+tmux excels at running multiple coding agents in parallel:
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/codex-army.sock"
+
+# Create multiple sessions
+for i in 1 2 3 4 5; do
+  tmux -S "$SOCKET" new-session -d -s "agent-$i"
+done
+
+# Launch agents in different workdirs
+tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
+tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter
+
+# Poll for completion (check if prompt returned)
+for sess in agent-1 agent-2; do
+  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
+    echo "$sess: DONE"
+  else
+    echo "$sess: Running..."
+  fi
+done
+
+# Get full output from completed session
+tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -500
+```
+
+**Tips:**
+- Use separate git worktrees for parallel fixes (no branch conflicts)
+- `pnpm install` first before running codex in fresh clones
+- Check for shell prompt (`❯` or `$`) to detect completion
+- Codex needs `--yolo` or `--full-auto` for non-interactive fixes
+
+## Cleanup
+
+- Kill a session: `tmux -S "$SOCKET" kill-session -t "$SESSION"`.
+- Kill all sessions on a socket: `tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t`.
+- Remove everything on the private socket: `tmux -S "$SOCKET" kill-server`.
+
+## Helper: wait-for-text.sh
+
+`{baseDir}/scripts/wait-for-text.sh` polls a pane for a regex (or fixed string) with a timeout.
+
+```bash
+{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
+```
+
+- `-t`/`--target` pane target (required)
+- `-p`/`--pattern` regex to match (required); add `-F` for fixed string
+- `-T` timeout seconds (integer, default 15)
+- `-i` poll interval seconds (default 0.5)
+- `-l` history lines to search (integer, default 1000)

package/skills/tmux/scripts/find-sessions.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]
+
+List tmux sessions on a socket (default tmux socket if none provided).
+
+Options:
+  -L, --socket       tmux socket name (passed to tmux -L)
+  -S, --socket-path  tmux socket path (passed to tmux -S)
+  -A, --all          scan all sockets under NEXUS_TMUX_SOCKET_DIR
+  -q, --query        case-insensitive substring to filter session names
+  -h, --help         show this help
+USAGE
+}
+
+socket_name=""
+socket_path=""
+query=""
+scan_all=false
+socket_dir="${NEXUS_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nexus-tmux-sockets}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -L|--socket)      socket_name="${2-}"; shift 2 ;;
+    -S|--socket-path) socket_path="${2-}"; shift 2 ;;
+    -A|--all)         scan_all=true; shift ;;
+    -q|--query)       query="${2-}"; shift 2 ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
+  echo "Cannot combine --all with -L or -S" >&2
+  exit 1
+fi
+
+if [[ -n "$socket_name" && -n "$socket_path" ]]; then
+  echo "Use either -L or -S, not both" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+list_sessions() {
+  local label="$1"; shift
+  local tmux_cmd=(tmux "$@")
+
+  if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
+    echo "No tmux server found on $label" >&2
+    return 1
+  fi
+
+  if [[ -n "$query" ]]; then
+    sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
+  fi
+
+  if [[ -z "$sessions" ]]; then
+    echo "No sessions found on $label"
+    return 0
+  fi
+
+  echo "Sessions on $label:"
+  printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
+    attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
+    printf '  - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
+  done
+}
+
+if [[ "$scan_all" == true ]]; then
+  if [[ ! -d "$socket_dir" ]]; then
+    echo "Socket directory not found: $socket_dir" >&2
+    exit 1
+  fi
+
+  shopt -s nullglob
+  sockets=("$socket_dir"/*)
+  shopt -u nullglob
+
+  if [[ "${#sockets[@]}" -eq 0 ]]; then
+    echo "No sockets found under $socket_dir" >&2
+    exit 1
+  fi
+
+  exit_code=0
+  for sock in "${sockets[@]}"; do
+    if [[ ! -S "$sock" ]]; then
+      continue
+    fi
+    list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
+  done
+  exit "$exit_code"
+fi
+
+tmux_cmd=(tmux)
+socket_label="default socket"
+
+if [[ -n "$socket_name" ]]; then
+  tmux_cmd+=(-L "$socket_name")
+  socket_label="socket name '$socket_name'"
+elif [[ -n "$socket_path" ]]; then
+  tmux_cmd+=(-S "$socket_path")
+  socket_label="socket path '$socket_path'"
+fi
+
+list_sessions "$socket_label" "${tmux_cmd[@]:1}"

package/skills/tmux/scripts/wait-for-text.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: wait-for-text.sh -t target -p pattern [options]
+
+Poll a tmux pane for text and exit when found.
+
+Options:
+  -t, --target    tmux target (session:window.pane), required
+  -p, --pattern   regex pattern to look for, required
+  -F, --fixed     treat pattern as a fixed string (grep -F)
+  -T, --timeout   seconds to wait (integer, default: 15)
+  -i, --interval  poll interval in seconds (default: 0.5)
+  -l, --lines     number of history lines to inspect (integer, default: 1000)
+  -h, --help      show this help
+USAGE
+}
+
+target=""
+pattern=""
+grep_flag="-E"
+timeout=15
+interval=0.5
+lines=1000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--target)   target="${2-}"; shift 2 ;;
+    -p|--pattern)  pattern="${2-}"; shift 2 ;;
+    -F|--fixed)    grep_flag="-F"; shift ;;
+    -T|--timeout)  timeout="${2-}"; shift 2 ;;
+    -i|--interval) interval="${2-}"; shift 2 ;;
+    -l|--lines)    lines="${2-}"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$target" || -z "$pattern" ]]; then
+  echo "target and pattern are required" >&2
+  usage
+  exit 1
+fi
+
+if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+  echo "timeout must be an integer number of seconds" >&2
+  exit 1
+fi
+
+if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+  echo "lines must be an integer" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+# End time in epoch seconds (integer, good enough for polling)
+start_epoch=$(date +%s)
+deadline=$((start_epoch + timeout))
+
+while true; do
+  # -J joins wrapped lines, -S uses negative index to read last N lines
+  pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
+
+  if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
+    exit 0
+  fi
+
+  now=$(date +%s)
+  if (( now >= deadline )); then
+    echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
+    echo "Last ${lines} lines from $target:" >&2
+    printf '%s\n' "$pane_text" >&2
+    exit 1
+  fi
+
+  sleep "$interval"
+done

package/skills/trello/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: trello
+description: Manage Trello boards, lists, and cards via the Trello REST API.
+homepage: https://developer.atlassian.com/cloud/trello/rest/
+metadata: {"nexus":{"emoji":"📋","requires":{"bins":["jq"],"env":["TRELLO_API_KEY","TRELLO_TOKEN"]}}}
+---
+
+# Trello Skill
+
+Manage Trello boards, lists, and cards directly from Nexus.
+
+## Setup
+
+1. Get your API key: https://trello.com/app-key
+2. Generate a token (click "Token" link on that page)
+3. Set environment variables:
+   ```bash
+   export TRELLO_API_KEY="your-api-key"
+   export TRELLO_TOKEN="your-token"
+   ```
+
+## Usage
+
+All commands use curl to hit the Trello REST API.
+
+### List boards
+```bash
+curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id}'
+```
+
+### List lists in a board
+```bash
+curl -s "https://api.trello.com/1/boards/{boardId}/lists?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id}'
+```
+
+### List cards in a list
+```bash
+curl -s "https://api.trello.com/1/lists/{listId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id, desc}'
+```
+
+### Create a card
+```bash
+curl -s -X POST "https://api.trello.com/1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "idList={listId}" \
+  -d "name=Card Title" \
+  -d "desc=Card description"
+```
+
+### Move a card to another list
+```bash
+curl -s -X PUT "https://api.trello.com/1/cards/{cardId}?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "idList={newListId}"
+```
+
+### Add a comment to a card
+```bash
+curl -s -X POST "https://api.trello.com/1/cards/{cardId}/actions/comments?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "text=Your comment here"
+```
+
+### Archive a card
+```bash
+curl -s -X PUT "https://api.trello.com/1/cards/{cardId}?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "closed=true"
+```
+
+## Notes
+
+- Board/List/Card IDs can be found in the Trello URL or via the list commands
+- The API key and token provide full access to your Trello account - keep them secret!
+- Rate limits: 300 requests per 10 seconds per API key; 100 requests per 10 seconds per token; `/1/members` endpoints are limited to 100 requests per 900 seconds
+
+## Examples
+
+```bash
+# Get all boards
+curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&fields=name,id" | jq
+
+# Find a specific board by name
+curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | select(.name | contains("Work"))'
+
+# Get all cards on a board
+curl -s "https://api.trello.com/1/boards/{boardId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, list: .idList}'
+```

package/skills/upstream-sync/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: upstream-sync
+description: Monitor and auto-port changes from upstream to nexus
+metadata: {"nexus":{"emoji":"🔄","requires":{"bins":["git","npm"]}}}
+---
+
+# Upstream Sync Skill
+
+Monitor and automatically port changes from upstream to nexus.
+
+Nexus is a fork of the upstream project. This skill helps track upstream changes and automatically ports conflict-free commits to stay in sync with community improvements.
+
+## Quick Start
+
+```bash
+# Check what's new in nexus
+./skills/upstream-sync/scripts/check-nexus.sh --since "1 week ago"
+
+# Auto-port conflict-free commits (dry run first!)
+./skills/upstream-sync/scripts/auto-port.sh --dry-run
+
+# Actually port them
+./skills/upstream-sync/scripts/auto-port.sh
+```
+
+## Commands
+
+### Check upstream for new commits
+
+```bash
+./skills/upstream-sync/scripts/check-nexus.sh [options]
+```
+
+Shows new commits in upstream since the fork point.
+
+**Environment variables:**
+- `CLAWDBOT_PATH`: Path to clawdbot repo (default: `/Users/tyler/Desktop/projects/clawdbot`)
+- `NEXUS_PATH`: Path to nexus repo (default: current directory or `/Users/tyler/Desktop/projects/nexus`)
+
+**Example:**
+```bash
+# Check auth-related commits in last 2 weeks
+./skills/upstream-sync/scripts/check-nexus.sh --since "2 weeks ago" --grep "auth"
+```
+
+### Auto-port Conflict-Free Commits
+
+```bash
+./skills/upstream-sync/scripts/auto-port.sh [options]
+```
+
+Automatically cherry-picks and ports commits that apply cleanly without conflicts.
+
+**Options:**
+- `--dry-run` - Show what would be ported without making changes
+- `--since DATE` - Only consider commits since date (default: "1 week ago")
+- `--max-commits N` - Maximum commits to port (default: 10)
+- `--skip-tests` - Skip build verification (faster but riskier)
+- `--skip-docs` - Skip documentation commits (default: true)
+
+**What it does:**
+1. Fetches latest from nexus
+2. Finds commits since your fork point
+3. Filters out docs/test/chore commits
+4. Attempts to cherry-pick each commit
+5. Runs build to verify
+6. Commits successful ports with reference to original
+7. Logs results to `~/.nexus/state/upstream-sync/port-log.jsonl`
+
+**Example:**
+```bash
+# See what would be ported
+./skills/upstream-sync/scripts/auto-port.sh --dry-run --since "3 days ago"
+
+# Port everything from last week
+./skills/upstream-sync/scripts/auto-port.sh --since "1 week ago"
+```
+
+### Check Pi-AI Package Versions
+
+```bash
+./skills/upstream-sync/scripts/check-pi-ai.sh
+```
+
+Checks npm for new versions of:
+- `@mariozechner/pi-agent-core`
+- `@mariozechner/pi-coding-agent`
+
+Compares against the versions installed in nexus.
+
+**Output:** Current vs latest versions for each pi-ai package
+
+### Check all upstreams
+
+```bash
+./skills/upstream-sync/scripts/check-all.sh
+```
+
+Runs both nexus and pi-ai checks.
+
+## Usage
+
+Run this skill daily (manually or via cron) to stay informed about upstream changes:
+
+```bash
+# Check daily at 9am
+nexus cron add "0 9 * * *" --skill upstream-sync --message "Check for new nexus commits and show me the summary"
+
+# Check specific upstream
+nexus agent --message "Check clawdbot for new commits"
+```
+
+## Notes
+
+- `NEXUS_PATH` - Path to nexus repo (default: auto-detected)
+
+**Pi-AI package tracking:**
+- Pi-AI provides OAuth support used by nexus for Claude authentication
+- Check `@mariozechner/pi-agent-core` for auth/oauth changes
+- Check `@mariozechner/pi-coding-agent` for agent runtime improvements
+- Update frequency: Check weekly or before major nexus releases
+
+Successful and failed port attempts are logged to:
+```
+~/.nexus/state/upstream-sync/port-log.jsonl
+```
+
+Each entry contains:
+- `ts` - Timestamp
+- `hash` - Commit hash
+- `subject` - Commit message
+- `status` - "ported", "skipped", or "failed"
+- `reason` - Failure reason if applicable
+
+## Porting Guidelines
+
+**Focus on porting:**
+- Bug fixes (especially auth, gateway, sessions)
+- Security improvements
+- Performance optimizations
+- New utility functions
+
+**Usually skip:**
+- Branding/naming changes (legacy branding → Nexus)
+- Feature changes that conflict with nexus direction
+- Tests for features we don't have
+
+**After porting:**
+1. Run full test suite: `npm test`
+2. Review changes: `git diff HEAD~N`
+3. Push when satisfied: `git push`