1 files changed, 73 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f7af7d2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# is_required
+
+List which Slackware SBo packages depend on a given package, and whether each is installed.
+
+Given a package name, `is_required` searches the SlackBuilds.org (SBo) git tree for `.info` files whose `REQUIRES=` field names that package (whole-word match), then marks each dependent as installed or missing by checking `/var/log/packages`.
+
+## Usage
+
+```
+is_required [OPTIONS] <package>
+```
+
+### Options
+
+| Flag | Effect |
+|------|--------|
+| `-i` | show only installed dependents |
+| `-u` | show only uninstalled dependents |
+| `-r` | recursive: also show packages that require those dependents (one level up) |
+| `-h` | help |
+
+### Example
+
+```
+$ is_required ffmpeg
+Packages requiring 'ffmpeg':
+────────────────────────────────────────────────────
+[I] mpv                                       (multimedia)
+[ ] obs-studio                                (multimedia)
+```
+
+### Output legend
+
+- `[I]` — installed (present in `/var/log/packages`), bold green
+- `[ ]` — not installed, yellow
+- `<package>` — queried package name in the header, bold cyan
+- `(category)` — SBo category of the dependent, dim white
+
+Color is auto-disabled when stdout is not a terminal (piped or redirected).
+
+## Configuration
+
+Both paths are overridable via environment variables:
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `SBO_REPO` | `/var/lib/sbopkg/SBo-git` | SBo git tree to search |
+| `PKG_LOG` | `/var/log/packages` | installed-package log |
+
+Package names are derived from `/var/log/packages` filenames by stripping the trailing version, arch, and build-tag fields (e.g. `ffmpeg-7.1.4-x86_64-1` → `ffmpeg`).
+
+> **Note:** `/var/log/packages` is a symlink to `/var/lib/pkgtools/packages`, so `find` is run with `-follow`.
+
+## Bash completion
+
+`is_required.bash` completes option flags and installed package names (read from `$PKG_LOG`).
+
+Install system-wide:
+
+```bash
+sudo cp is_required.bash /etc/bash_completion.d/is_required
+```
+
+Or per-user (requires `~/.bash_completion.d/` sourced in `~/.bashrc`):
+
+```bash
+cp is_required.bash ~/.bash_completion.d/is_required
+```
+
+## Requirements
+
+- Bash 4+ (uses associative arrays)
+- Standard SlackBuilds tooling layout (`sbopkg` SBo-git tree, `pkgtools` package log)