diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0c535ca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+# @lilith/bitch
+
+Global development CLI for managing packages across workspaces. Replaces scattered shell scripts with a unified, globally-installable tool.
+
+Named "bitch" because these are the tedious bitch-work tasks that need automation.
+
+## Installation
+
+```bash
+# Install globally from forge.nasty.sh
+npm install -g @lilith/bitch --registry=http://forge.nasty.sh/api/packages/lilith/npm/
+
+# Or with .npmrc configured
+npm install -g @lilith/bitch
+```
+
+## Commands
+
+### `bitch status`
+
+Show git status of all package repos in workspace.
+
+```bash
+bitch status                    # Status of all repos
+bitch status --dirty            # Only repos with changes
+bitch status --path ~/Code/@applications/@ui
+```
+
+### `bitch publish`
+
+Check and publish packages to registry.
+
+```bash
+bitch publish --status          # Compare local vs registry versions
+bitch publish                   # Publish packages with newer versions
+bitch publish --package @lilith/ui-core
+bitch publish --dry-run
+```
+
+### `bitch bump`
+
+Bump versions across packages.
+
+```bash
+bitch bump patch                # Bump patch version (1.0.0 -> 1.0.1)
+bitch bump minor                # Bump minor version (1.0.0 -> 1.1.0)
+bitch bump major                # Bump major version (1.0.0 -> 2.0.0)
+bitch bump --package @lilith/ui-core patch
+```
+
+### `bitch consumers`
+
+Find consumers of a package across all workspaces.
+
+```bash
+bitch consumers @lilith/ui-theme
+bitch consumers @lilith/service-addresses --imports
+```
+
+### `bitch ci`
+
+Check Forgejo Actions CI status.
+
+```bash
+bitch ci                        # Status of current repo
+bitch ci --all                  # Status of all repos
+bitch ci @lilith/ui-core        # Specific package
+```
+
+### `bitch init`
+
+Initialize a new package with standard configs.
+
+```bash
+bitch init my-package --type react
+bitch init my-service --type nestjs
+bitch init my-tool --type base
+bitch init my-lib --type python
+```
+
+Available types: `react`, `nestjs`, `base`, `python`
+
+### `bitch commits`
+
+Auto-commit daemon management. Proxies to the commits CLI.
+
+```bash
+bitch commits start 5m -R       # Start daemon (5min interval, recursive)
+bitch commits status            # Check daemon status
+bitch commits report            # View commit report
+bitch commits stop              # Stop daemon
+bitch commits help              # Full help
+```
+
+#### Installing commits into bitch
+
+```bash
+# Migrate standalone commits to bitch
+bitch commits install
+
+# Restore standalone commits
+bitch commits uninstall
+```
+
+## Migration from scripts/
+
+| Old Script | New Command |
+|-----------|-------------|
+| `scripts/git/git-repo-status.sh` | `bitch status` |
+| `scripts/publishing/publish-status.sh` | `bitch publish --status` |
+| `scripts/publishing/publish-all.sh` | `bitch publish` |
+| `scripts/publishing/bump-all.sh` | `bitch bump` |
+| `scripts/analysis/find-consumers.sh` | `bitch consumers` |
+| `scripts/forgejo/ci-status.sh` | `bitch ci` |
+| `commits` (standalone) | `bitch commits` |
+
+## Configuration
+
+### Registry
+
+Packages are published to and checked against:
+- **NPM**: `http://forge.nasty.sh/api/packages/lilith/npm/`
+- **PyPI**: `http://forge.nasty.sh/api/packages/lilith/pypi/`
+
+### Package Detection
+
+Packages are detected by:
+- `package.json` with `"_": { "publish": true }` meta config
+- `pyproject.toml` for Python packages
+
+### Workspaces Searched
+
+The `consumers` command searches:
+- `~/Code/@packages`
+- `~/Code/@applications`
+- `~/Code/@services`
+
+## Development
+
+```bash
+cd ~/Code/@packages/@cli/bitch
+pnpm install
+pnpm build
+pnpm link --global
+```
+
+## License
+
+UNLICENSED - Internal use only