# AGENTS.md — ffind

Cross-shell fuzzy file search (filename matching) for any shell and any Linux
distribution. ffind is an external executable, so there are no shell-specific
functions or wrappers to load.

## Structure

| Path | Purpose |
|------|---------|
| `ffind` | Main executable (bash). Args: `[dir]` (default `.`), `--md`, `--version`, `-h/--help`. Requires fzf + ripgrep; opens selection via `xdg-open`. |
| `ffind-preview` | Preview helper. Default: render file. `--copy`: copy first colon field (the path) to clipboard via wl-copy/xclip/xsel/pbcopy. |
| `completions/` | Completion snippets: `ffind.bash`, `_ffind.zsh`, `ffind.fish`. |
| `VERSION` | Current version (`0.1.0`). |
| `LICENSE` | AGPL-3.0-or-later. |
| `install.sh` | Installer: prefers OBS-built package (apt/zypper/dnf), falls back to script copy; macOS via brew. |
| `.forgejo/workflows/release.yml` | On tag `v*`: build source tarball, create release, poll OBS, attach rpm/deb artifacts. |
| `.forgejo/workflows/ci.yml` | shellcheck on push (dev, main) + PR. |

## Distribution pipeline

- Forgejo release (tag `vX.Y.Z`) triggers: (1) release.yml Job A creates the
  source tarball `ffind-$VER.tar.xz` and the release; (2) a webhook triggers
  the OBS watchdog (`watchdog.sh --once --project ffind` on the VPS), which
  downloads the tarball into OBS package `home:Baalthasar:ffind/ffind`,
  bumps spec/debian versions, and opens a submit request to
  `home:Baalthasar`; (3) release.yml Job B polls OBS (Tumbleweed x86_64,
  Debian_13 x86_64 + aarch64) and attaches the built rpm/deb to the release.
- ffind has **no vendor tarball** (no Rust deps) — the watchdog's
  `vendor_asset` is unset for this project.

## Workflow

1. Work on branch `dev`; commit and push there.
2. Merge to `main` when finished and regression-tested.
3. Tag `vX.Y.Z` on `main` and push to trigger the release pipeline.
