agentbrush 0.1.0__tar.gz

agentbrush-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+*.so
+.DS_Store

agentbrush-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.1.1 (2026-03-11)
+
+### CLI
+- Added `paste-centered` subcommand to `agentbrush composite` — center artwork on a new canvas with `--canvas WxH`, `--fit`, `--bg-color` options
+- Fixed README composite syntax: removed spurious `overlay` subcommand prefix
+
+### Docs
+- Fixed `text` CLI examples in SKILL.md and README — removed nonexistent `add`/`render` subcommands, correct syntax is `agentbrush text <input> <output> <text>` (use `new:WxH` as input for blank canvas)
+- Fixed `--font mono-bold` → `--font mono --bold` (CLI uses separate flag)
+- Fixed README standalone requirements: Python >= 3.10 + Pillow >= 12.1 (was "pip install Pillow")
+
+### Tests
+- 126 tests (up from 122)
+
+## 0.1.0 (2026-03-11)
+
+Initial release.
+
+### Core Library
+- `agentbrush.core`: flood fill, color matching, alpha ops, geometry, connectivity, fonts, Result dataclass
+- Edge-based flood fill (BFS from edges only) — never threshold-based removal
+- Cross-platform font discovery with bundled Space Mono, JetBrains Mono, DejaVu Sans Mono
+
+### Modules
+- `background`: Solid-color background removal via edge-based flood fill
+- `greenscreen`: Multi-pass green screen pipeline (flood fill + color sweep + post-upscale sweep)
+- `border`: White border erosion + green halo cleanup + alpha edge smoothing
+- `text`: Pillow text rendering with textbbox y-offset correction and getmetrics() line height
+- `composite`: Alpha compositing with overlay positioning and centered paste
+- `resize`: Scale, fit, pad modes with LANCZOS resampling
+- `validate`: Design QA — dimensions, aspect ratio, transparency, sticker layout/complexity detection
+- `convert`: Format conversion (PNG, JPEG, WEBP, BMP, TIFF) with RGBA->RGB alpha flattening
+- `generate`: AI image generation via OpenAI GPT Image and Pollinations (optional dependency)
+
+### CLI
+- `agentbrush <command>` dispatcher with 9 subcommands
+- Uniform exit codes: 0=success, 1=validation fail, 2=input error
+
+### Agent Skills Package
+- `skill/agent-brush/SKILL.md` — Agent Skills standard entrypoint
+- `skill/agent-brush/references/` — product specs, troubleshooting guide
+- `skill/agent-brush/scripts/` — standalone wrappers (work without pip install)
+
+### Documentation
+- Pipeline guides: sticker, t-shirt, mug
+- 122 tests (all synthetic fixtures)

agentbrush-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ultrathink.art
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentbrush-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: agentbrush
+Version: 0.1.0
+Summary: Image editing toolkit for AI agents. Photoshop for Claude Code, Codex, Cursor, and friends.
+Project-URL: Homepage, https://github.com/ultrathink-art/agentbrush
+Project-URL: Repository, https://github.com/ultrathink-art/agentbrush
+Project-URL: Issues, https://github.com/ultrathink-art/agentbrush/issues
+Author-email: Ultrathink <ceo@ultrathink.art>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,background-removal,greenscreen,image-editing,pillow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: pillow>=12.1
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: generate
+Requires-Dist: openai>=1.0; extra == 'generate'
+Description-Content-Type: text/markdown
+
+# AgentBrush
+
+[![PyPI version](https://img.shields.io/pypi/v/agentbrush.svg)](https://pypi.org/project/agentbrush/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Agent Skills](https://img.shields.io/badge/agent--skills-compatible-purple.svg)](https://agentskills.io)
+[![Tests](https://img.shields.io/badge/tests-126%20passed-brightgreen.svg)](#testing)
+
+Image editing toolkit for AI agents. Photoshop for Claude Code, Codex, Cursor, and friends.
+
+Built from 134 production sessions of print-on-demand image processing. Battle-tested algorithms for background removal, green screen processing, border cleanup, text rendering, compositing, validation, and more.
+
+## Install
+
+```bash
+pip install agentbrush
+```
+
+With AI image generation support:
+
+```bash
+pip install agentbrush[generate]
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from agentbrush import remove_background, remove_greenscreen, cleanup_border
+
+# Remove black background (edge-based flood fill, safe for artwork)
+result = remove_background("input.png", "output.png", color="black", threshold=25)
+print(result.summary())
+# [OK] output.png
+#   Size: 1024x1024px
+#   Transparent: 72.3%  Opaque: 27.7%
+#   pixels_removed: 758432
+
+# Remove green screen (multi-pass: flood fill + color sweep)
+result = remove_greenscreen("input.png", "output.png", halo_passes=20)
+
+# Clean up white sticker border from AI-generated art
+result = cleanup_border("input.png", "output.png", passes=15, threshold=185)
+```
+
+Every function returns a `Result` object:
+
+```python
+result.success         # True if no errors
+result.width           # Output width in px
+result.height          # Output height in px
+result.transparent_pct # Percentage of transparent pixels
+result.warnings        # Non-fatal issues
+result.errors          # Fatal issues
+result.metadata        # Operation-specific data
+result.summary()       # Human-readable string
+```
+
+### CLI
+
+```bash
+# Background removal
+agentbrush remove-bg input.png output.png --color black --threshold 25 --smooth
+
+# Green screen removal
+agentbrush greenscreen input.png output.png --upscale 3 --halo-passes 20
+
+# Border cleanup
+agentbrush border-cleanup input.png output.png --passes 15 --green-halo-passes 20
+
+# Text rendering
+agentbrush text input.png output.png "HELLO" --font mono --bold --size 72
+agentbrush text new:1664x1664 output.png "BUG\nFEATURE" --bold --center
+
+# Compositing
+agentbrush composite base.png art.png output.png --position 100,200
+agentbrush composite paste-centered output.png --overlay art.png --canvas 4500x5400 --fit
+
+# Resize
+agentbrush resize input.png output.png --width 4500 --height 5400
+agentbrush resize input.png output.png --scale 3.0
+agentbrush resize input.png output.png --width 2700 --height 1050 --fit --pad
+
+# Validate design against product specs
+agentbrush validate check design.png --type sticker
+agentbrush validate compare source.png processed.png --max-loss 10
+
+# Format conversion
+agentbrush convert input.png output.jpg --quality 95
+
+# AI image generation (requires openai package)
+agentbrush generate --provider openai --prompt "cat coding" --output cat.png
+```
+
+Exit codes: `0` = success, `1` = validation failure, `2` = input error.
+
+## Agent Skills
+
+AgentBrush ships as an [Agent Skills](https://agentskills.io) package. Copy `skill/agent-brush/` into your project's `.claude/skills/` directory:
+
+```bash
+cp -r skill/agent-brush/ .claude/skills/agent-brush/
+```
+
+Claude Code (and other compatible tools) will automatically discover the skill and use it when processing images. The skill includes:
+
+- **SKILL.md** — instructions and quick reference for the agent
+- **references/** — product specs, troubleshooting guides
+- **scripts/** — standalone wrappers that work without `pip install`
+
+## Usage Without Install
+
+The standalone scripts work directly from a git clone — no `pip install` needed:
+
+```bash
+git clone https://github.com/ultrathink-art/agentbrush.git
+cd agentbrush
+
+# Run scripts directly (auto-detects src/ directory)
+python skill/agent-brush/scripts/remove_bg.py input.png output.png --color black
+python skill/agent-brush/scripts/validate.py check design.png --type sticker
+python skill/agent-brush/scripts/greenscreen.py input.png output.png --upscale 3
+```
+
+Requirements: **Python >= 3.10** and **Pillow >= 12.1** (`pip install 'Pillow>=12.1'`). Older versions fail at runtime (`get_flattened_data` API requires Pillow 12.1+, type union syntax requires Python 3.10+).
+
+## Modules
+
+| Module | Description | Key function |
+|--------|-------------|-------------|
+| `background` | Edge-based flood fill bg removal | `remove_background()` |
+| `greenscreen` | Multi-pass green screen pipeline | `remove_greenscreen()` |
+| `border` | White border erosion + green halo | `cleanup_border()` |
+| `text` | Pillow text rendering (accurate) | `add_text()`, `render_text()` |
+| `composite` | Image layering + centering | `composite()`, `paste_centered()` |
+| `resize` | Resize with fit/pad/scale modes | `resize_image()` |
+| `validate` | Design QA against product specs | `validate_design()`, `compare_images()` |
+| `convert` | Format conversion (PNG/JPEG/WEBP) | `convert_image()` |
+| `generate` | AI image generation (optional) | `generate_image()` |
+
+## Core Primitives
+
+Low-level functions available for custom pipelines:
+
+```python
+from agentbrush.core import (
+    flood_fill_from_edges,   # BFS flood fill (4-conn or 8-conn)
+    is_near_color,           # Color distance matching
+    parse_color,             # Parse "black", "white", "R,G,B" strings
+    smooth_edges,            # 1px edge feathering
+    smooth_alpha_edges,      # Gaussian alpha blur (edges only)
+    find_artwork_bounds,     # Opaque pixel bounding box
+    crop_to_content,         # Crop to content with padding
+    find_opaque_centroid,    # Center of mass for opaque region
+    ensure_single_shape,     # Remove floating elements (8-connected BFS)
+    count_components,        # Connected component count
+    find_font,               # Cross-platform font discovery
+)
+```
+
+## Product Presets
+
+Built-in dimensions for print-on-demand products:
+
+| Product | Width | Height | Transparent | Notes |
+|---------|-------|--------|-------------|-------|
+| T-shirt | 4500 | 5400 | Required | Apparel |
+| Hoodie | 4500 | 5400 | Required | Apparel |
+| Hat | 1890 | 765 | Required | Wide horizontal |
+| Mug (11oz) | 2700 | 1050 | Recommended | Wrap-around |
+| Sticker | 1664 | 1664 | Required | Die-cut, single shape |
+| Desk mat | 9200 | 4500 | No | Large format |
+| Poster | 5400 | 7200 | No | Portrait |
+
+## Why Edge-Based Flood Fill?
+
+Threshold-based removal (`magick -fuzz -transparent black`) scans every pixel and removes anything "close enough" to the target color — including internal outlines, dark shadows, and fine details inside the artwork.
+
+AgentBrush starts flood fill from image edges only. Interior pixels that happen to match the background color are never touched because flood fill can't reach them without crossing through the artwork.
+
+```
+Threshold-based:              Edge-based flood fill:
+removes ALL dark pixels       removes ONLY edge-connected dark pixels
++-----------------+           +-----------------+
+|                 |           |                 |
+|    #########    |           |    #########    |
+|   #         #   | <- loses  |   #*********#   | <- preserved!
+|   #         #   |   detail  |   #*********#   |
+|    #########    |           |    #########    |
+|                 |           |                 |
++-----------------+           +-----------------+
+```
+
+## Examples
+
+Full pipeline guides with code:
+
+- [Sticker Pipeline](docs/examples/sticker_pipeline.md) — AI art -> green screen -> border cleanup -> validate die-cut
+- [T-Shirt Pipeline](docs/examples/tshirt_pipeline.md) — artwork -> transparent bg -> resize to 4500x5400
+- [Mug Pipeline](docs/examples/mug_pipeline.md) — sticker adaptation -> wrap format -> multi-sticker composition
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+All tests use synthetic Pillow-generated fixtures (no production images). 126 tests covering all modules.
+
+## Dependencies
+
+- **Required**: `Pillow >= 12.1`
+- **Optional**: `openai >= 1.0` (for `generate` command)
+- **Dev**: `pytest >= 7.0`, `pytest-cov`
+
+## License
+
+MIT

agentbrush-0.1.0/README.md

@@ -0,0 +1,220 @@
+# AgentBrush
+
+[![PyPI version](https://img.shields.io/pypi/v/agentbrush.svg)](https://pypi.org/project/agentbrush/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Agent Skills](https://img.shields.io/badge/agent--skills-compatible-purple.svg)](https://agentskills.io)
+[![Tests](https://img.shields.io/badge/tests-126%20passed-brightgreen.svg)](#testing)
+
+Image editing toolkit for AI agents. Photoshop for Claude Code, Codex, Cursor, and friends.
+
+Built from 134 production sessions of print-on-demand image processing. Battle-tested algorithms for background removal, green screen processing, border cleanup, text rendering, compositing, validation, and more.
+
+## Install
+
+```bash
+pip install agentbrush
+```
+
+With AI image generation support:
+
+```bash
+pip install agentbrush[generate]
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from agentbrush import remove_background, remove_greenscreen, cleanup_border
+
+# Remove black background (edge-based flood fill, safe for artwork)
+result = remove_background("input.png", "output.png", color="black", threshold=25)
+print(result.summary())
+# [OK] output.png
+#   Size: 1024x1024px
+#   Transparent: 72.3%  Opaque: 27.7%
+#   pixels_removed: 758432
+
+# Remove green screen (multi-pass: flood fill + color sweep)
+result = remove_greenscreen("input.png", "output.png", halo_passes=20)
+
+# Clean up white sticker border from AI-generated art
+result = cleanup_border("input.png", "output.png", passes=15, threshold=185)
+```
+
+Every function returns a `Result` object:
+
+```python
+result.success         # True if no errors
+result.width           # Output width in px
+result.height          # Output height in px
+result.transparent_pct # Percentage of transparent pixels
+result.warnings        # Non-fatal issues
+result.errors          # Fatal issues
+result.metadata        # Operation-specific data
+result.summary()       # Human-readable string
+```
+
+### CLI
+
+```bash
+# Background removal
+agentbrush remove-bg input.png output.png --color black --threshold 25 --smooth
+
+# Green screen removal
+agentbrush greenscreen input.png output.png --upscale 3 --halo-passes 20
+
+# Border cleanup
+agentbrush border-cleanup input.png output.png --passes 15 --green-halo-passes 20
+
+# Text rendering
+agentbrush text input.png output.png "HELLO" --font mono --bold --size 72
+agentbrush text new:1664x1664 output.png "BUG\nFEATURE" --bold --center
+
+# Compositing
+agentbrush composite base.png art.png output.png --position 100,200
+agentbrush composite paste-centered output.png --overlay art.png --canvas 4500x5400 --fit
+
+# Resize
+agentbrush resize input.png output.png --width 4500 --height 5400
+agentbrush resize input.png output.png --scale 3.0
+agentbrush resize input.png output.png --width 2700 --height 1050 --fit --pad
+
+# Validate design against product specs
+agentbrush validate check design.png --type sticker
+agentbrush validate compare source.png processed.png --max-loss 10
+
+# Format conversion
+agentbrush convert input.png output.jpg --quality 95
+
+# AI image generation (requires openai package)
+agentbrush generate --provider openai --prompt "cat coding" --output cat.png
+```
+
+Exit codes: `0` = success, `1` = validation failure, `2` = input error.
+
+## Agent Skills
+
+AgentBrush ships as an [Agent Skills](https://agentskills.io) package. Copy `skill/agent-brush/` into your project's `.claude/skills/` directory:
+
+```bash
+cp -r skill/agent-brush/ .claude/skills/agent-brush/
+```
+
+Claude Code (and other compatible tools) will automatically discover the skill and use it when processing images. The skill includes:
+
+- **SKILL.md** — instructions and quick reference for the agent
+- **references/** — product specs, troubleshooting guides
+- **scripts/** — standalone wrappers that work without `pip install`
+
+## Usage Without Install
+
+The standalone scripts work directly from a git clone — no `pip install` needed:
+
+```bash
+git clone https://github.com/ultrathink-art/agentbrush.git
+cd agentbrush
+
+# Run scripts directly (auto-detects src/ directory)
+python skill/agent-brush/scripts/remove_bg.py input.png output.png --color black
+python skill/agent-brush/scripts/validate.py check design.png --type sticker
+python skill/agent-brush/scripts/greenscreen.py input.png output.png --upscale 3
+```
+
+Requirements: **Python >= 3.10** and **Pillow >= 12.1** (`pip install 'Pillow>=12.1'`). Older versions fail at runtime (`get_flattened_data` API requires Pillow 12.1+, type union syntax requires Python 3.10+).
+
+## Modules
+
+| Module | Description | Key function |
+|--------|-------------|-------------|
+| `background` | Edge-based flood fill bg removal | `remove_background()` |
+| `greenscreen` | Multi-pass green screen pipeline | `remove_greenscreen()` |
+| `border` | White border erosion + green halo | `cleanup_border()` |
+| `text` | Pillow text rendering (accurate) | `add_text()`, `render_text()` |
+| `composite` | Image layering + centering | `composite()`, `paste_centered()` |
+| `resize` | Resize with fit/pad/scale modes | `resize_image()` |
+| `validate` | Design QA against product specs | `validate_design()`, `compare_images()` |
+| `convert` | Format conversion (PNG/JPEG/WEBP) | `convert_image()` |
+| `generate` | AI image generation (optional) | `generate_image()` |
+
+## Core Primitives
+
+Low-level functions available for custom pipelines:
+
+```python
+from agentbrush.core import (
+    flood_fill_from_edges,   # BFS flood fill (4-conn or 8-conn)
+    is_near_color,           # Color distance matching
+    parse_color,             # Parse "black", "white", "R,G,B" strings
+    smooth_edges,            # 1px edge feathering
+    smooth_alpha_edges,      # Gaussian alpha blur (edges only)
+    find_artwork_bounds,     # Opaque pixel bounding box
+    crop_to_content,         # Crop to content with padding
+    find_opaque_centroid,    # Center of mass for opaque region
+    ensure_single_shape,     # Remove floating elements (8-connected BFS)
+    count_components,        # Connected component count
+    find_font,               # Cross-platform font discovery
+)
+```
+
+## Product Presets
+
+Built-in dimensions for print-on-demand products:
+
+| Product | Width | Height | Transparent | Notes |
+|---------|-------|--------|-------------|-------|
+| T-shirt | 4500 | 5400 | Required | Apparel |
+| Hoodie | 4500 | 5400 | Required | Apparel |
+| Hat | 1890 | 765 | Required | Wide horizontal |
+| Mug (11oz) | 2700 | 1050 | Recommended | Wrap-around |
+| Sticker | 1664 | 1664 | Required | Die-cut, single shape |
+| Desk mat | 9200 | 4500 | No | Large format |
+| Poster | 5400 | 7200 | No | Portrait |
+
+## Why Edge-Based Flood Fill?
+
+Threshold-based removal (`magick -fuzz -transparent black`) scans every pixel and removes anything "close enough" to the target color — including internal outlines, dark shadows, and fine details inside the artwork.
+
+AgentBrush starts flood fill from image edges only. Interior pixels that happen to match the background color are never touched because flood fill can't reach them without crossing through the artwork.
+
+```
+Threshold-based:              Edge-based flood fill:
+removes ALL dark pixels       removes ONLY edge-connected dark pixels
++-----------------+           +-----------------+
+|                 |           |                 |
+|    #########    |           |    #########    |
+|   #         #   | <- loses  |   #*********#   | <- preserved!
+|   #         #   |   detail  |   #*********#   |
+|    #########    |           |    #########    |
+|                 |           |                 |
++-----------------+           +-----------------+
+```
+
+## Examples
+
+Full pipeline guides with code:
+
+- [Sticker Pipeline](docs/examples/sticker_pipeline.md) — AI art -> green screen -> border cleanup -> validate die-cut
+- [T-Shirt Pipeline](docs/examples/tshirt_pipeline.md) — artwork -> transparent bg -> resize to 4500x5400
+- [Mug Pipeline](docs/examples/mug_pipeline.md) — sticker adaptation -> wrap format -> multi-sticker composition
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+All tests use synthetic Pillow-generated fixtures (no production images). 126 tests covering all modules.
+
+## Dependencies
+
+- **Required**: `Pillow >= 12.1`
+- **Optional**: `openai >= 1.0` (for `generate` command)
+- **Dev**: `pytest >= 7.0`, `pytest-cov`
+
+## License
+
+MIT

agentbrush-0.1.0/docs/architecture.md

@@ -0,0 +1,119 @@
+# Architecture
+
+## Design Principles
+
+1. **Edge-based flood fill only** — never threshold-based pixel removal
+2. **Uniform Result type** — every operation returns `Result` with the same fields
+3. **CLI mirrors API** — every Python function has a CLI subcommand
+4. **Cross-platform** — no hardcoded OS paths; bundled fonts as fallback
+5. **Minimal dependencies** — only Pillow required; OpenAI optional
+6. **Standalone scripts** — work from git clone without pip install
+
+## Directory Layout
+
+```
+agentbrush/
+├── src/agentbrush/          # Python package (pip installable)
+│   ├── __init__.py          # Public API re-exports
+│   ├── __main__.py          # python -m agentbrush
+│   ├── cli.py               # Top-level argparse dispatcher
+│   ├── core/                # Shared primitives
+│   │   ├── flood_fill.py    # BFS flood fill (4/8-connectivity)
+│   │   ├── color.py         # Color matching, parsing
+│   │   ├── alpha.py         # Alpha channel ops, edge smoothing
+│   │   ├── geometry.py      # Bounds, crop, centroid
+│   │   ├── connectivity.py  # Die-cut single shape (8-connected BFS)
+│   │   ├── fonts.py         # Cross-platform font discovery
+│   │   └── result.py        # Uniform Result dataclass
+│   └── <module>/            # Each module has:
+│       ├── __init__.py      #   Re-export from ops
+│       ├── cli.py           #   argparse subcommand registration
+│       └── ops.py           #   Core logic + public function
+├── skill/agent-brush/       # Agent Skills package
+│   ├── SKILL.md             # Agent instructions + quick reference
+│   ├── references/          # Product specs, troubleshooting
+│   └── scripts/             # Standalone wrappers
+├── fonts/                   # Bundled OFL fonts
+├── tests/                   # pytest suite (synthetic fixtures)
+└── docs/examples/           # Pipeline guides
+```
+
+## Module Pattern
+
+Every operation module follows the same structure:
+
+```
+module/
+├── __init__.py    # from .ops import main_function
+├── cli.py         # add_parser(subparsers) + run(args) -> exit_code
+└── ops.py         # main_function(...) -> Result
+```
+
+**ops.py** contains the core logic. It:
+- Accepts `Union[str, Path]` for file paths
+- Returns `Result` with stats
+- Sets `Result.errors` on failure (never raises exceptions to callers)
+- Prints nothing (caller prints `result.summary()`)
+
+**cli.py** registers an argparse subparser and converts CLI args to function calls.
+
+**__init__.py** re-exports the main function for `from agentbrush.module import func`.
+
+## Result Dataclass
+
+All operations return `Result`:
+
+```python
+@dataclass
+class Result:
+    output_path: Optional[Path]
+    width: int
+    height: int
+    transparent_pct: float     # 0-100
+    opaque_pct: float          # 0-100
+    warnings: list[str]        # Non-fatal issues
+    errors: list[str]          # Fatal issues
+    metadata: dict[str, Any]   # Operation-specific data
+
+    @property
+    def success(self) -> bool:
+        return len(self.errors) == 0
+
+    def summary(self) -> str:
+        """Human-readable string for stdout."""
+```
+
+## Flood Fill Algorithm
+
+The core differentiator. BFS from all 4 edges simultaneously:
+
+1. Seed queue with all border pixels matching target color
+2. BFS expands to adjacent matching pixels (4-connectivity default)
+3. Set matched pixels to transparent (alpha=0)
+4. Interior pixels matching the color are never reached
+
+This preserves internal outlines and details that threshold-based removal destroys.
+
+## Font Discovery
+
+Search order:
+1. Bundled fonts in `fonts/` directory (Space Mono, JetBrains Mono, DejaVu)
+2. System directories (macOS, Linux, Windows platform-specific paths)
+3. Pillow default fallback
+
+Name aliases map friendly names to filenames: `mono` -> `SpaceMono-Regular.ttf`, `jetbrains-bold` -> `JetBrainsMono-Bold.ttf`, etc.
+
+## Standalone Script Pattern
+
+Each script in `skill/agent-brush/scripts/` uses this auto-detection:
+
+```python
+_script_dir = os.path.dirname(os.path.abspath(__file__))
+_src_dir = os.path.join(_script_dir, "..", "..", "..", "src")
+if os.path.isdir(_src_dir):
+    sys.path.insert(0, _src_dir)
+```
+
+This makes scripts work both:
+- **Standalone**: `python scripts/remove_bg.py` (finds `src/` relative to script)
+- **Installed**: `python scripts/remove_bg.py` (imports from site-packages)