{
  "markdown": "# .dotfiles\n\nPublic dotfiles for [fish](https://fishshell.com/), [git](https://git-scm.com/),\n[jed](https://www.jedsoft.org/jed/), and\n[VS Code](https://code.visualstudio.com/) — plus a large collection of\n[agent skills](#agent-skills) and command-line tools for AI-assisted development\nwith agents such as Claude Code, Codex, and Gemini CLI.\n\n## Repository layout\n\n```text\n.dotfiles/\n├── bin/                 # Shell scripts added directly to $PATH\n├── fish/\n│   ├── config.fish      # Main fish config; loads .private overlay if present\n│   ├── conf.d/          # Fish startup snippets\n│   ├── completions/     # Fish completions\n│   └── functions/       # Fish functions (autoloaded)\n├── home/                # Dotfiles symlinked into $HOME by install.sh\n├── etc/                 # Tool-specific config (git templates, VS Code, etc.)\n├── skills/              # Agent skills (see Agent skills below)\n├── config/              # Plugins for the skill and permission tools\n├── docker/              # Dockerfile + notes for building an image from this repo\n├── tests/               # TAP tests for bin/ scripts\n└── install.sh           # Idempotent install/update script\n```\n\n`install.sh` symlinks `home/.*` into `$HOME`, installs packages, and wires up\ntool-specific config. It is safe to run multiple times, and doubles as the\nupdater: an existing checkout is fast-forwarded before applying. It can be run\nlocally (`./install.sh`) or piped straight from the network (see\n[Installation](#installation)).\n\n## Agent skills\n\nThe [`skills/`](skills/) directory contains\n[Agent Skills](https://agentskills.io): folders with a `SKILL.md` (metadata and\ninstructions) plus supporting scripts and references that teach AI coding agents\nhow to perform specific tasks — driving Android devices over adb, inspecting\nAPKs, managing emulators, looking up current AndroidX library facts, enforcing\ncoding standards, planning award flights, and more.\n\n### Key skills\n\n| Skill                                          | Description                                                                                          |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| [`adb`](skills/adb/)                           | ADB device automation with a Wear OS focus: screenshots, screen recording, tiles, dumpsys, logcat    |\n| [`agent-tools`](skills/agent-tools/)           | CLI tools delegating analysis to AI models: image description, screenshot diffing, deep research     |\n| [`apk`](skills/apk/)                           | Offline APK binary analysis: manifests, resources, launcher icons, split APKs                        |\n| [`coding-standards`](skills/coding-standards/) | This repo's coding standards: shell/Python/Markdown formatting, CLI design, commit message style     |\n| [`emumanager`](skills/emumanager/)             | Android SDK bootstrap plus AVD/emulator management (mobile, Wear OS, TV, Automotive)                 |\n| [`jetpack`](skills/jetpack/)                   | Current AndroidX/Jetpack facts that are wrong from memory: versions, Maven coordinates, dependencies |\n\nMore specialised skills: [`android-testing`](skills/android-testing/) (system\nstate and connectivity testing on phone and Wear OS),\n[`wear-widget`](skills/wear-widget/) (reverse-engineering widgets), and\n[`workspace-config`](skills/workspace-config/) (skill selection and agent tool\npermissions). Personal-workflow skills live here too:\n[`agent-review`](skills/agent-review/), [`taskgo`](skills/taskgo/),\n[`technical-writing`](skills/technical-writing/), and\n[`travel`](skills/travel/).\n\n### Installing skills into a workspace\n\nSkills are intentionally **not** installed globally — every project seeing every\nskill would be noise. Instead, the bundled `skill` command manages them per\nworkspace as untracked symlinks in `.claude/skills/` or `.agents/skills/`,\nauto-detecting which agent is installed:\n\n```sh\nskill apply       # sync workspace symlinks with AGENT_REQUIRED_SKILLS\nskill add jetpack # add one skill by name\nskill list        # what's active in this workspace\n```\n\nSkill names resolve against `skills/` in this repo and its `.private`/`.corp`\noverlays (later layers shadow by name); plugins in `config/skill/plugins/`\nregister additional remote skills from third-party catalogs. Projects declare\nthe skills they require via direnv (`skills NAME …` in `.envrc`, maintained by\n`envrc add skills NAME`), and `skill preflight` verifies them before an agent is\nlaunched.\n\n## Overlays\n\n**SECURITY NOTE:** The `.dotfiles` repository is public. To prevent the leakage\nof sensitive information (such as API keys, corporate tool configurations, or\ninternal pathnames), two private companion repositories can optionally be\ncloned: `~/.private` and `~/.corp`.\n\nThis architecture is specifically designed to help both humans and AI agents\nunderstand what goes where and ensures private information remains strictly out\nof the public repository. This repository works fine without them.\n\n### Purpose of each layer\n\n| Repo          | Intended for                                |\n| ------------- | ------------------------------------------- |\n| `~/.dotfiles` | Public config, tools, and scripts           |\n| `~/.private`  | Personal secrets, API keys, private tooling |\n| `~/.corp`     | Work machine config, internal tooling       |\n\n### Precedence\n\n`install.sh` processes overlays in this order: `.dotfiles` → `.private` →\n`.corp`. Later layers win on conflict. A file in `~/.corp` always beats the same\npath in `~/.private` or `~/.dotfiles`.\n\n### How files are applied\n\nTwo functions handle overlay merging, with different semantics:\n\n- **`link_overlay_path rel dst`** — symlinks `dst` to the single\n  highest-priority source that provides `rel`. Used for whole-file configs where\n  only one version makes sense (e.g. `etc/starship/starship.toml`).\n\n- **`link_overlay_files rel dst`** — iterates every overlay in order and\n  symlinks each file it finds under `rel/` into `dst/`. All overlays contribute;\n  later layers win on filename collision. Used when multiple overlays may each\n  add files to a directory (e.g. `etc/code/`).\n\n`home/` dotfiles are linked by iterating all overlays in order with `ln -sf`, so\nthe last overlay to provide a given filename wins.\n\n### Overlay-aware paths\n\n| Path                         | Mechanism                           | Notes                                                                                                      |\n| ---------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| `home/.*`                    | `link_home_dotfiles` (all overlays) | Last overlay wins per filename                                                                             |\n| `etc/agents/AGENTS.md`       | `overlay_path` (highest wins)       | Symlinked to `~/.codex/`, `~/.gemini/`, `~/.claude/` (gated on their respective binaries)                  |\n| `etc/shpool/config.toml`     | `link_overlay_path`                 |                                                                                                            |\n| `etc/starship/starship.toml` | `link_overlay_path`                 |                                                                                                            |\n| `etc/ghostty/config`         | `link_overlay_path`                 |                                                                                                            |\n| `etc/bat/config`             | `link_overlay_path`                 |                                                                                                            |\n| `etc/code/`                  | `link_overlay_files`                | VS Code `settings.json`, `keybindings.json`, etc.                                                          |\n| `etc/macos/KeyBindings`      | `overlay_path`                      | rsync'd (not symlinked) due to macOS bug                                                                   |\n| `etc/macos/Solarized.clr`    | `overlay_path`                      | Copied to `~/Library/Colors/`                                                                              |\n| `skills/*/`                  | `skill` catalog source              | Not linked globally; added per workspace via `skill add`/`skill apply` (see [Agent skills](#agent-skills)) |\n\n### Per-overlay `update` hooks\n\nAfter the main install, `install.sh` runs `~/.private/update` and\n`~/.corp/update` if they exist and are executable. These hooks handle\noverlay-specific setup that cannot be expressed as file overlays (package\ninstalls, auth setup, etc.).\n\n### Expected layout\n\n```text\n.private/               # same structure for .corp\n├── fish/\n│   ├── conf.d/         # Startup snippets sourced by config.fish\n│   ├── completions/    # Completions prepended to fish_complete_path\n│   ├── functions/      # Functions prepended to fish_function_path\n│   └── secrets.fish    # API keys and tokens (chmod 600)\n├── home/               # Dotfiles symlinked into $HOME (e.g. .gitconfig.local)\n├── etc/                # Tool-specific config (see overlay-aware paths above)\n├── skills/             # Agent skills that shadow ~/.dotfiles/skills/ by name\n└── update              # Optional hook run at end of ./install.sh\n```\n\n`fish/config.fish` prepends `~/.private/fish/functions` (and `.corp`\nequivalents) and `~/.private/fish/completions` to the fish search paths, and\nsources any `~/.private/fish/conf.d/*.fish` snippets at shell startup.\n\nTo install: clone your private repos to `~/.private` and/or `~/.corp`, then run\n`./install.sh` again.\n\n## Secret management\n\nSecrets (API keys, tokens) live in `~/.private/fish/secrets.fish` and are not\nsourced in full at shell startup. Three fish functions provide on-demand access:\n\n<!-- markdownlint-disable MD013 -->\n\n| Function    | Usage                           | Description                                  |\n| ----------- | ------------------------------- | -------------------------------------------- |\n| `setsecret` | `setsecret NAME [NAME...]`      | Load secret(s) into the current shell        |\n| `getsecret` | `getsecret NAME`                | Print secret value(s) to stdout (array-safe) |\n| `envsecret` | `envsecret NAME [...] [--] CMD` | Run a command with secret(s) injected        |\n\n<!-- markdownlint-restore MD013 -->\n\n`envsecret` is the safest option for scripts: secrets are injected into the\nchild process and never leak into the calling shell.\n\nA `~/.private/fish/conf.d/` snippet uses `setsecret --if-unset` to auto-load a\nsmall set of everyday secrets at shell startup.\n\nRun `setsecret --help`, `getsecret --help`, or `envsecret --help` for details.\n\n## Environment management\n\n[direnv](https://direnv.net/) handles per-project environment switching,\nconfigured via `~/.direnvrc` (symlinked from `home/.direnvrc`). To activate it\nin a project, create an `.envrc` file in the project root.\n\n### Node.js\n\nNode.js versions are managed by `bin/node-install` and direnv.\n\n```sh\nnode-install 22        # installs latest 22.x into ~/.local/share/node/versions\n```\n\nAdd to `.envrc`:\n\n```sh\nuse node 22\nlayout node            # adds node_modules/.bin to PATH\n```\n\n### Ruby\n\nRuby versions are managed by `bin/ruby-install` and direnv. Versions are\ncompiled from source via [ruby-build](https://github.com/rbenv/ruby-build) (the\ntoolchain and its build dependencies install with\n`install.sh --install-optional`), so the first install of a version takes a few\nminutes.\n\n```sh\nruby-install 3.4       # compiles latest 3.4.x into ~/.local/share/ruby/versions\n```\n\nAdd to `.envrc`:\n\n```sh\nuse ruby 3.4\nlayout ruby            # project-local gems in .direnv/ruby\n```\n\n`layout ruby` keeps gems inside the project, so `gem install kamal` makes\n`kamal` available on `PATH` without touching the system Ruby.\n\nBecause each version is compiled against the system libraries present at build\ntime, an installed Ruby can later fail to start with a library load error (for\nexample after a Homebrew `openssl` upgrade removes a library it was linked\nagainst). The fix is to rebuild that version: `ruby-install 3.4`.\n\n### Python\n\nPython environments use [uv](https://github.com/astral-sh/uv). Add to `.envrc`:\n\n```sh\nlayout uv              # creates .venv if absent, activates it\n```\n\n## Installation\n\nThe same `install.sh` script both installs and updates, and runs in two ways.\n`git` must already be installed either way (see\n[Prerequisites](#prerequisites)).\n\n### Option 1: Straight from the network\n\nClones the repo to `~/.dotfiles` (if absent), points the push remote at SSH,\nthen installs — and on later runs, updates (it fast-forwards `~/.dotfiles`\nbefore applying):\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/ithinkihaveacat/dotfiles/master/install.sh | bash\n```\n\nIt must be piped to `bash`, not `sh` — the script is bash and refuses to run\nunder other shells. Pass flags after `-s --`, e.g. `… | bash -s -- --force`. To\ndownload the whole script before running anything (rather than streaming it into\nthe interpreter), use the equivalent:\n\n```sh\nbash -c \"$(curl -fsSL https://raw.githubusercontent.com/ithinkihaveacat/dotfiles/master/install.sh)\"\n```\n\n### Option 2: From a local checkout\n\n```sh\ncd $HOME\ngit clone https://github.com/ithinkihaveacat/dotfiles.git .dotfiles\ncd .dotfiles\ngit remote set-url origin --push git@github.com:ithinkihaveacat/dotfiles.git\n./install.sh\n```\n\nAfter cloning `~/.private` and/or `~/.corp` (if available), run `./install.sh`\nagain so the overlay is applied.\n\n> **Note:** `install.sh` may overwrite unmanaged files in locations such as\n> `~/Library/KeyBindings`. It is otherwise safe to run multiple times.\n\n## Prerequisites\n\n### git\n\n- **Ubuntu/Debian**: `sudo apt-get install git`\n- **macOS**: `xcode-select --install`\n\n### fish\n\nOn **Debian 13** and **macOS**, `install.sh` installs fish for you, so you can\nskip this step. Debian's packaged fish is out of date, so on Debian 13 it pulls\nfish 4 from the OpenSUSE Build Service; on macOS it uses Homebrew. If fish is\nalready installed at a version older than 4.2, `install.sh` warns rather than\nreplacing it. On other systems, install it first:\n\n- **Ubuntu/other Debian**: `sudo apt-get install fish`\n- **Other**: <https://fishshell.com/>\n\n<!-- markdownlint-disable MD013 -->\n\n> Standard apt packages lag significantly (Ubuntu 24.04: 3.7.0, Debian\n> bookworm/Raspberry Pi OS: 3.6.0, Debian trixie: 4.0.2). For fish 4.2+, install\n> from the OpenSUSE Build Service:\n>\n> ```bash\n> curl -fsSL https://download.opensuse.org/repositories/shells:fish:release:4/Debian_Unstable/Release.key | \\\n>   gpg --dearmor | sudo tee /usr/share/keyrings/fish-shell.gpg > /dev/null\n> echo 'deb [signed-by=/usr/share/keyrings/fish-shell.gpg] https://download.opensuse.org/repositories/shells:/fish:/release:/4/Debian_Unstable/ /' | \\\n>   sudo tee /etc/apt/sources.list.d/fish-shell.list\n> sudo apt update && sudo apt install -y fish\n> ```\n\n<!-- markdownlint-restore MD013 -->\n\n## Platform-specific setup\n\n### macOS\n\n- **Terminal:** Import `etc/macos/Solarized Dark.terminal` and set it as the\n  default profile.\n- **Keyboard:** System Preferences > Keyboard > Shortcuts > Services > File and\n  Folders: enable \"New Terminal at Folder\".\n- **Text Replacements:** If not shared via iCloud, restore from\n  `etc/macos/Text Replacements.plist` — see\n  [Back up and share text replacements on Mac](https://support.apple.com/en-gb/guide/mac-help/mchl2a7bd795/mac).\n- **Lock Screen:** Add to Menu Bar via Keychain Access preferences.\n- **Volume:** Add to Menu Bar via Control Center > Sound > Always Show in Menu\n  Bar.\n- **Time Machine:** Disable local snapshots: `sudo tmutil disablelocal`\n- **Hot Corners:** Disable via System Preferences.\n- **Fonts:** See <https://typography.guru/journal/awesome-catalina-fonts/>.\n- **iA Writer theme:** <https://ia.net/writer/templates/>\n- **Network Link Conditioner** (for simulating degraded network conditions):\n  <https://developer.apple.com/download/more/?q=Additional%20Tools>\n\n### Ubuntu\n\n```sh\n# Emacs keybindings across GTK apps\ngsettings set org.gnome.desktop.interface gtk-key-theme \"Emacs\"\n```\n\n**Compose key:** Set to Caps Lock via Settings > Keyboard. Enables e.g. Caps\nLock + `---` → em dash.\n\n### Raspberry Pi\n\nComplete setup sequence for a fresh Raspberry Pi OS install.\n\n1. Use the [Raspberry Pi Imager](https://www.raspberrypi.com/software/) to write\n   the OS to an SD card or SSD.\n\n   - For a headless install: Raspberry Pi OS (other) > Raspberry Pi OS Lite.\n   - In OS customisation: enable SSH (Remote access section).\n   - (Optional) Configure Wi-Fi.\n\n1. SSH in: `ssh mjs@lil.local` (substitute your username and hostname).\n\n   - (Optional) If using Ghostty, copy the terminfo from your local machine:\n     `infocmp -x xterm-ghostty | ssh mjs@lil.local -- tic -x -`\n\n1. Update the OS:\n\n   ```sh\n   sudo apt-get update && sudo apt-get upgrade -y\n   ```\n\n   Reboot if `/var/run/reboot-required` exists: `sudo reboot`\n\n1. Install fish (see [Prerequisites](#fish) for the OpenSUSE Build Service\n   instructions to get fish 4.2+, or use the older distro version):\n\n   ```sh\n   sudo apt-get install fish\n   ```\n\n1. Install git: `sudo apt-get install git`\n\n1. Install Tailscale: `curl -fsSL https://tailscale.com/install.sh | sh` then\n   `sudo tailscale up`\n\n1. (Optional) Install Node.js and npm: `sudo apt-get install nodejs npm` (for\n   newer versions see [Node.js](#nodejs)).\n\n1. (Optional) Disable WiFi and Bluetooth: add these lines under `[all]` in\n   `/boot/firmware/config.txt`:\n\n   ```text\n   dtoverlay=disable-wifi\n   dtoverlay=disable-bt\n   ```\n\n1. (Optional) Change hostname: edit `/etc/hostname` and `/etc/hosts`.\n\n1. Reboot after any optional steps above: `sudo reboot`\n\nOnce complete, proceed to [Installation](#installation).\n\n> **Tip:** Use VS Code's\n> [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)\n> extension to edit files on the Pi.\n\n## Local binaries\n\nPut manually installed binaries in `~/.local/bin`.\n\n## Testing and CI\n\nScripts are tested with TAP-format tests run via `prove`. Tests are co-located\nwith the code they cover: `tests/test-*` for `bin/` scripts and\n`skills/*/tests/test-*` for skill scripts. Run them with:\n\n```sh\nprove -j 9 tests/test-* skills/*/tests/test-*\n```\n\nSee [tests/README.md](tests/README.md) for details, including how to run tests\noffline and in isolated environments.\n\nA GitHub Actions workflow (`.github/workflows/lint.yml`) runs on every push:\n`shellcheck` and `shfmt` over all Bash scripts (`bin/`, `skills/*/scripts/`,\n`install.sh`), `ruff` via `skills/coding-standards/scripts/python-format` over\nall Python scripts, plus the full test suite.\n\n## Author\n\n<mjs@beebo.org>\n",
  "bytes": 18900,
  "sha": "18a7f989e54f6677f4f005518afb5b1335a02d3e43748ad9c2a4e4508795bbad",
  "repo_slug": "ithinkihaveacat/dotfiles",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_ithinkihaveacat_dotfiles_etc_prompts_jet_429beede/readme"
}