@xiaotianxt/skills 0.1.0

package/skills/ship-ai-native-cli/references/case-notes.md

@@ -0,0 +1,83 @@
+# Case Notes From tg, cx, mon
+
+## Shared Project Shape
+
+All three converge on:
+
+- short binary name and repo under `~/dev/<name>`;
+- Rust CLI with `clap` and small modules;
+- `README.md` for humans;
+- `SKILL.md` for Codex operation;
+- `docs/architecture.md` or workflow design notes for maintainers;
+- `Makefile`;
+- `scripts/install.sh`;
+- `scripts/release.sh`;
+- GitHub CI and tag-triggered release workflow;
+- Homebrew tap formula that installs prebuilt arm64 binaries;
+- real installed-binary verification after release.
+
+## tg Lessons
+
+`tg` started from a fragile local-data problem and became usable by hiding
+low-level recovery steps behind task-level commands.
+
+Useful patterns:
+
+- default command maps to the primary user job;
+- `refresh` and `doctor` separate maintenance from diagnosis;
+- `sessions` provides discovery before exact reads;
+- exports support `txt`, `csv`, and `json`;
+- sensitive local data stays local;
+- `SKILL.md` tells agents how to operate the tool, not how internals work.
+
+Product lesson: users want a chat-history tool, not a database-decryption
+toolkit. Low-level commands can exist, but they should not dominate the product
+frame.
+
+## cx Lessons
+
+`cx` wrapped an everyday manual workflow into one fast command.
+
+Useful patterns:
+
+- direct default action: `cx` launches through the best slot;
+- management commands are explicit: `status`, `select`, `add`, `login`, `doctor`;
+- stdin wrapping is part of the product contract;
+- status output needed iteration to become human-readable;
+- transient network failure gets a conservative fallback;
+- release automation came early because the tool is used constantly.
+
+Product lesson: for a workflow tool, optimize the default path first. Users
+should not have to remember the implementation model on every run.
+
+## mon Lessons
+
+`mon` is the boundary-discipline case.
+
+Useful patterns:
+
+- expose the remote service as a general, structured, agent-native API surface;
+- provide `auth`, `accounts`, `transactions`, `gql`, `doctor`;
+- test against real credentials and real API responses;
+- treat rate limits, MFA, redirects, and CAPTCHA as product behavior;
+- reuse sessions before attempting password login;
+- keep domain-specific reconciliation outside the generic API tool.
+
+Product lesson: the first concrete use case can reveal the tool, but should not
+own the tool. Put one-off settlement or reconciliation logic in a separate
+project folder or downstream skill.
+
+## Conversation-Derived Method
+
+The successful sessions followed this rhythm:
+
+1. User states a concrete pain.
+2. Codex inspects existing local evidence before designing.
+3. First version ships a narrow but real vertical slice.
+4. User tries it immediately.
+5. Failures become product requirements, not just bug fixes.
+6. The repo gains release/Homebrew automation once the loop proves useful.
+7. Scope mistakes are corrected by moving domain-specific logic out of the core.
+
+Use this loop intentionally. Do not wait for perfect architecture before the
+first real smoke test.

package/skills/ship-ai-native-cli/references/product-method.md

@@ -0,0 +1,82 @@
+# Product Method
+
+## The Pattern
+
+The repeated shape across `tg`, `cx`, and `mon` is:
+
+1. Find a repeated local job that is painful enough to deserve a command.
+2. Collapse the job into a small command taxonomy.
+3. Implement a direct, local, deterministic vertical slice.
+4. Add diagnostics and recovery paths before broadening features.
+5. Make the tool agent-native with JSON output and stable error behavior.
+6. Ship it like a real product: docs, CI, release assets, Homebrew, installed smoke test.
+
+## Product Frame Template
+
+Use this before writing code:
+
+```text
+<name> is a <platform/domain> CLI for <user job>.
+It should let a user/agent do <primary outcome> without manually doing <old workflow>.
+The first shipped slice is <smallest real command set>.
+It is not <non-goals>.
+```
+
+Examples:
+
+- `tg`: read/search/export local chat history without manually opening databases.
+- `cx`: launch Codex through the best available auth slot without manual account rotation.
+- `mon`: query Monarch data through a stable local CLI without browser scraping.
+
+## Command Taxonomy
+
+Prefer this order:
+
+1. Primary task command: the thing users actually came for.
+2. Discovery command: list/find/select available targets.
+3. Data command: stable JSON for agents and scripts.
+4. Maintenance command: refresh/cache/auth/install.
+5. Diagnostic command: `doctor`, with read-only checks by default.
+6. Escape hatch: raw API/query command for future needs.
+
+Avoid exposing implementation chores as the first screen unless the domain
+requires setup. If setup is required, make it explicit and diagnoseable.
+
+## AI-Native Contract
+
+AI-native means an agent can operate the tool without screen scraping or hidden
+state guesses:
+
+- `--json` for data-bearing commands.
+- Machine-readable rows with stable field names.
+- Human tables for quick terminal use.
+- Secrets never printed by default.
+- Errors include the failing subsystem and next useful action.
+- Commands can be composed in shell pipelines.
+- Local state paths can be overridden by env vars or flags.
+
+## Boundary Discipline
+
+When a user asks for a specific workflow while building a general tool, separate
+the layers:
+
+- Put **generic access** in the CLI.
+- Put **domain-specific reconciliation or analysis** in a project folder,
+  downstream script, or separate skill.
+- Promote a domain workflow into the CLI only after it proves general and stable.
+
+The `mon` rent detour is the cautionary case: payment reconciliation belonged in
+the rent tracking folder, while `mon` should stay a general Monarch API surface.
+
+## First Slice
+
+For a new CLI, ship the smallest version that can be used immediately:
+
+- `auth/status` or equivalent local setup if needed.
+- One read-only command that returns real useful data.
+- `--json`.
+- `doctor`.
+- README install/usage.
+- CI and release path.
+
+Only add mutation commands after read-only behavior is verified.

package/skills/ship-ai-native-cli/references/release-checklist.md

@@ -0,0 +1,147 @@
+# Release Checklist
+
+## Local Verification
+
+Run before committing:
+
+```bash
+cargo fmt --all -- --check
+cargo check
+cargo test
+cargo build --release
+cargo run -- --help
+```
+
+Also run the most important real-world smoke test:
+
+- local app/database access for local tools;
+- authenticated read-only API call for API tools;
+- installed binary behavior after Homebrew install.
+
+## Makefile
+
+Include:
+
+```makefile
+.PHONY: build check fmt test install-local install release clean
+
+build:
+	cargo build --release
+
+check:
+	cargo check
+
+fmt:
+	cargo fmt --all
+
+test:
+	cargo test
+
+install-local: build
+	mkdir -p ~/.local/bin
+	cp target/release/<bin> ~/.local/bin/
+
+install: build
+	sudo cp target/release/<bin> /usr/local/bin/
+
+release:
+	scripts/release.sh
+
+clean:
+	cargo clean
+	rm -f ~/.local/bin/<bin> 2>/dev/null || true
+```
+
+## CI
+
+Use macOS arm64 when the product is macOS-specific or distributed as
+`darwin-arm64`:
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+env:
+  CARGO_TERM_COLOR: always
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+      - name: Verify arm64 runner
+        run: test "$(uname -m)" = "arm64"
+      - name: Format
+        run: cargo fmt --all -- --check
+      - name: Build
+        run: cargo build --release
+      - name: Test
+        run: cargo test
+      - name: Verify CLI
+        run: cargo run --release -- --help
+```
+
+## Release Workflow
+
+On tag `v*`:
+
+1. Build release binary on `macos-latest`.
+2. Archive `target/release/<bin>` into `<bin>-${{ github.ref_name }}-darwin-arm64.tar.gz`.
+3. Upload artifact.
+4. Create GitHub release with `softprops/action-gh-release@v2`.
+
+## Homebrew Formula Rules
+
+Prefer prebuilt release assets:
+
+```ruby
+class Tool < Formula
+  desc "..."
+  homepage "https://github.com/<owner>/<repo>"
+  url "https://github.com/<owner>/<repo>/releases/download/vX.Y.Z/tool-vX.Y.Z-darwin-arm64.tar.gz"
+  sha256 "..."
+  license "MIT"
+
+  depends_on arch: :arm64
+
+  head do
+    url "https://github.com/<owner>/<repo>.git", branch: "main"
+    depends_on "rust" => :build
+  end
+
+  def install
+    if build.head?
+      system "cargo", "install", "--bin", "tool", "--root", prefix, "."
+    else
+      bin.install "tool"
+    end
+  end
+
+  test do
+    system bin/"tool", "--help"
+  end
+end
+```
+
+Avoid requiring Rust for normal `brew install`; only `--HEAD` should build from
+source.
+
+## Release Script Behavior
+
+The release script should:
+
+1. Refuse dirty source and dirty tap checkouts.
+2. Pull tap and fetch source tags.
+3. Bump `Cargo.toml` and `Cargo.lock` when requested.
+4. Run tests.
+5. Push main and tag.
+6. Wait for GitHub Actions release.
+7. Read or compute asset sha256.
+8. Update `Formula/<bin>.rb` in the tap and push it.
+9. Run `brew update`, `brew upgrade/reinstall`, and `brew test`.
+
+Do not call the release complete until `brew test` passes.

package/skills/ship-ai-native-cli/references/rust-cli-shape.md

@@ -0,0 +1,111 @@
+# Rust CLI Shape
+
+## Default File Tree
+
+Use this shape unless the repo already has a stronger local convention:
+
+```text
+project/
+  .github/workflows/ci.yml
+  .github/workflows/release.yml
+  .gitignore
+  Cargo.toml
+  Cargo.lock
+  LICENSE
+  Makefile
+  README.md
+  SKILL.md
+  docs/architecture.md
+  scripts/install.sh
+  scripts/release.sh
+  src/
+    main.rs
+    cli.rs
+    client.rs        # API or local app boundary, if applicable
+    output.rs        # human tables + JSON
+    paths.rs         # local state paths
+    session.rs       # auth/session state, if applicable
+    install.rs
+```
+
+Add modules only when the domain forces them. Keep names boring and explicit.
+
+## Cargo Defaults
+
+Use `edition = "2021"` for compatibility unless there is a reason to move.
+
+Common dependencies:
+
+```toml
+anyhow = "1"
+clap = { version = "4", features = ["derive"] }
+reqwest = { version = "0.12", default-features = false, features = ["blocking", "json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+```
+
+Use `rusqlite`, `toml`, `chrono`, `rpassword`, etc. only when the product needs
+them. Avoid async runtimes unless concurrency is central to the tool.
+
+## CLI Design
+
+In `src/main.rs`:
+
+- Keep `main()` as a thin `ExitCode` wrapper.
+- Put command parsing in `cli.rs`.
+- Dispatch commands explicitly.
+- Print errors as `name: {err:#}`.
+
+In `src/cli.rs`:
+
+- Use `clap::{Parser, Subcommand, Args}`.
+- Prefer typed args over stringly parsing.
+- Add `--json` to agent-consumed data commands.
+- Add `--session-file`, `--config-dir`, or env overrides where local state matters.
+
+## Output
+
+Split output from logic:
+
+- Human tables should be compact and terminal-friendly.
+- JSON should be uncontaminated stdout.
+- Progress/warnings should go to stderr when stdout is data.
+- Avoid long wrapped lines in status output; use short columns or sections.
+
+## Local State
+
+Use predictable paths:
+
+```text
+~/.<tool>/session.json
+~/.<tool>/cache/
+```
+
+Support env overrides:
+
+```text
+TOOL_SESSION_FILE
+TOOL_CONFIG_DIR
+```
+
+Secrets:
+
+- chmod token/session files to `0600` on Unix.
+- Never commit generated local state.
+- Never print tokens in status output.
+
+## Core Commands To Consider
+
+```text
+tool                 # default primary action, if unambiguous
+tool status          # quick state, if status matters
+tool auth ...        # login/token/logout, if remote API
+tool list/find       # discovery
+tool get/search      # data access
+tool gql/query/raw   # escape hatch for APIs
+tool refresh         # maintenance
+tool doctor          # diagnostics
+tool install         # local install into ~/.local/bin
+```
+
+Do not add every command. Pick the smallest taxonomy that matches the product.

package/skills/telegram-mtproto-session/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: telegram-mtproto-session
+description: Create, verify, and use local Telegram MTProto user sessions with Telethon, including fast date-bounded chat history sync into local SQLite/FTS and local history queries. Use when Codex needs to log in to Telegram with a phone account, validate an existing .session file, read Telegram channel/group/chat history, search or inspect Telegram chats through the user API, or recover from broken/unauthorized sessions while keeping Telegram app credentials in macOS Keychain.
+---
+
+# Telegram MTProto Session
+
+Use this skill for Telegram user-account access through MTProto/Telethon. This is separate from bot-token workflows and separate from the `tg` skill, which is for local WeChat history on this machine.
+
+## Rules
+
+- Read Telegram app credentials from macOS Keychain; do not paste API IDs, hashes, phone numbers, login codes, or 2FA passwords into files or final responses.
+- Prefer these Keychain entries:
+  - `keychain-secret get codex.telegram api_id`
+  - `keychain-secret get codex.telegram api_hash`
+  - `keychain-secret get codex.telegram phone`
+- One-time migration from 1Password, when needed:
+  - `keychain-secret import-op codex.telegram api_id 'op://Private/Telegram Apps/api_id'`
+  - `keychain-secret import-op codex.telegram api_hash 'op://Private/Telegram Apps/api_hash'`
+  - `keychain-secret import-op codex.telegram phone 'op://Private/Telegram Apps/telegram_phone'`
+- Use a dedicated session path under `~/.local/share/codex-telegram/` unless the user asks for another location.
+- Use the bundled SQLite history store for high-volume reads:
+  `~/.local/share/codex-telegram/history.sqlite3`.
+- Treat `.session` files as sensitive account credentials. Do not commit, upload, or print their raw contents.
+- If Keychain reads, Telethon network calls, or SQLite opens under `~/.local/share`
+  fail under sandboxing, rerun the same scoped command with approval.
+- Respect Telegram rate limits. If a command reports `FloodWaitError`, stop and report the wait duration.
+
+## Script
+
+Use `scripts/telegram_session.py` from this skill directory. It requires Telethon and reads credentials from environment variables:
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+TELEGRAM_PHONE="$(keychain-secret get codex.telegram phone)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram login
+```
+
+When login sends a Telegram code, ask the user for the code in chat or have them type it into the running command. If Telegram asks for 2FA, prefer prompting interactively with `getpass`; do not ask the user to paste a long-lived password into chat unless they explicitly choose that path.
+
+## Workflows
+
+### Verify A Session
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram verify
+```
+
+Expected successful output includes `authorized=True`, the session path, and the Telegram user id/username. If `authorized=False`, run `login`.
+
+### Search Public Telegram Chats
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram search 'linux.do'
+```
+
+Use this for public channel/group discovery. It prints title, username, kind, participants, and id.
+
+### Inspect A Channel Or Group
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram inspect linux_do --limit 5
+```
+
+Use `inspect` to resolve a known username, print channel metadata, and summarize recent messages. Message summaries include reply/comment metadata when Telegram exposes it.
+
+### Fast History Sync And Local Query
+
+For date-bounded history, prefer `today` or `sync` so messages are cached in
+local SQLite with WAL and FTS5 indexes. `today` syncs one local day and prints
+the resulting rows:
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram \
+  today @linux_do_channel --day 2026-05-08 --timezone America/Los_Angeles
+```
+
+Use `sync` when you want to warm the local cache without printing messages:
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram \
+  sync @linux_do_channel --since 2026-05-01 --until 2026-05-08 --timezone America/Los_Angeles
+```
+
+Use `query` for local-only reads after sync:
+
+```bash
+python3 scripts/telegram_session.py query @linux_do_channel \
+  --since 2026-05-08 --until 2026-05-08 --timezone America/Los_Angeles
+```
+
+Add `--match '<fts expression>'` to search message text through SQLite FTS5.
+Add `--format jsonl` when downstream tooling should parse rows.
+
+### List Joined Dialogs
+
+```bash
+TELEGRAM_API_ID="$(keychain-secret get codex.telegram api_id)" \
+TELEGRAM_API_HASH="$(keychain-secret get codex.telegram api_hash)" \
+python3 scripts/telegram_session.py --session ~/.local/share/codex-telegram/telegram dialogs --match linux
+```
+
+Use this when the user says the session is already joined to a group/channel but the public username is unknown.
+
+## Common Fixes
+
+- `missing required env`: load credentials through the exact `keychain-secret get` commands above.
+- `authorized=False`: the session file is missing, expired, or was created for another account; run `login`.
+- `SessionPasswordNeededError`: Telegram account has 2FA enabled; let the script prompt via `getpass`.
+- `FloodWaitError`: stop and report the wait duration; do not retry aggressively.
+- Public search finds candidates but `inspect` fails: the channel may require joining, may be private, or may be blocked by account restrictions.
+- `query` returns no rows: run `sync` or `today` for that chat/date first, or check that the local date and `--timezone` match the intended day.
+- `sqlite3.OperationalError: unable to open database file` in Codex sandbox:
+  run the same query with approval, or point `--db` at a writable/readable task-local path.

package/skills/telegram-mtproto-session/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Telegram MTProto Session"
+  short_description: "Read Telegram via local MTProto sessions and SQLite history."
+  default_prompt: "Use the local Telegram MTProto session to verify access, sync date-bounded chat history into SQLite, or query cached Telegram messages."