Eagle Intake Shelf

A small, always-on-top Windows intake shelf for Eagle App users who want a safer, faster way to stage visual assets before import.

Drop files or folders onto the shelf, optionally type a short instruction, click Create Proposal, review a plain-language summary, then validate the import plan. The app is built for people who collect screenshots, references, thumbnails, renders, marketing graphics, PDFs, source media, and other creative assets in Eagle.

The Shelf is a thin PySide6 UI over a safety-hardened import runner. It keeps staging, SHA-256 hashing, duplicate detection, JSON proposals, controlled tags, count-invariant checks, and audit logs out of your normal workflow.

Safety first. This app never touches your Eagle .library internals, only ever adds metadata (never removes), and in v1 the Approve & Import button runs in dry-run mode only. No real items are written to Eagle until live writes are enabled in a separate, explicitly approved step. See Safety.

---

Highlights

• Floating Windows shelf with drag-and-drop intake.
• System tray app with global hotkey support.
• Proposal-first workflow: inspect the import plan before writes.
• Dry-run default for safe testing.
• Saved shelves for parking a working set and resuming later.
• Controlled taxonomy hints from short natural-language instructions.
• Audit-oriented design: count checks, duplicate handling, and local logs.
• Strict .library guard: Eagle-managed library internals are never read or modified.

---

Public release status

This is a public v0.1.0 release of a working Windows utility that was built inside a larger Eagle automation project. The Shelf source is published here as a standalone app, but it currently expects a companion Eagle Import Runner with the same callable interface used by this project.

For community users, the current best fit is:

• Windows developers and automation users comfortable editing config/shelf_config.json.
• Eagle power users who want a safer staged import workflow.
• Contributors interested in helping package the runner dependency, generalize paths, or create a one-click installer.

The app is intentionally conservative. Live import remains separately gated.

License

Eagle Intake Shelf is released under the MIT License.

The 6-step flow

1. Open the shelf — it floats on top of your other windows. Toggle it any time with the global hotkey (default Ctrl+Alt+E) or the tray icon.
2. Drop files or folders onto the drop zone. A badge shows how many files were collected.
3. (Optional) Type an instruction — e.g. "selfies into Personal/Selfies, approved". This is a hint; the app still maps everything to the controlled taxonomy.
4. Click Create Proposal. The app safely copies your files into staging and runs the Import Runner in proposal mode.
5. Review the summary — how many files will be imported, how many were skipped as duplicates, what tags and folders they'll get, anything unsupported.
6. Click Approve & Import. In v1 this runs a dry-run and shows you exactly what would happen, plus an audit summary. (Live importing is enabled separately.)

---

First-run setup

Requirements:

• Windows 10/11.
• Python 3.10+.
• Eagle App installed.
• Eagle Web API / MCP available when validating real library state.
• A compatible Eagle Import Runner configured in config/shelf_config.json.

git clone https://github.com/DonovanDeHart/eagle-intake-shelf.git
cd eagle-intake-shelf
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# copy and edit the config
copy config\shelf_config.example.json config\shelf_config.json

# launch once
.\scripts\run_shelf.ps1

The shelf starts in the system tray. Left-click the tray icon (or press the hotkey) to show/hide it. The × on the shelf hides it to the tray; use Quit in the tray menu to exit fully.

Normal launch

After first install, launch with either script:

.\scripts\run_shelf.ps1

or double-click scripts\run_shelf.cmd.

Both scripts set PYTHONPATH to the local src folder and prefer .venv\Scripts\pythonw.exe, so the Shelf opens like a Windows utility without leaving a console window behind. If the venv is missing, they fall back to pythonw.exe on PATH.

Desktop / Start Menu shortcuts

Create a Desktop shortcut:

.\scripts\create_shortcuts.ps1 -Desktop

Create a Start Menu shortcut:

.\scripts\create_shortcuts.ps1 -StartMenu

You can combine locations:

.\scripts\create_shortcuts.ps1 -Desktop -StartMenu

Run at startup

Toggle Run at startup in Settings (it manages a small, transparent .cmd launcher in your Windows Startup folder), or create a Startup shortcut manually:

.\scripts\create_shortcuts.ps1 -Startup

Troubleshooting launch

• If nothing appears, check the tray overflow area first; the shelf may already be running in the system tray.
• If duplicate tray icons appear after repeated launches, quit the shelf from the tray menu. If stale icons remain, kill stale pythonw.exe processes for this app's .venv\Scripts\pythonw.exe, then relaunch.
• If the shortcut does nothing, rerun first install from the repository root and confirm .venv\Scripts\pythonw.exe exists.
• If PowerShell blocks run_shelf.ps1, double-click scripts\run_shelf.cmd or run: powershell -ExecutionPolicy Bypass -File .\scripts\run_shelf.ps1.
• If imports fail, confirm config\shelf_config.json still has "live_writes_enabled": false and that Eagle's Web API is enabled. The launcher does not enable live writes.

---

Interface

Themes

Three built-in visual skins are available:

• Solid Modern — default; translucent teal glass with a restrained premium shell.
• Dark Fire Ice — optional high-contrast orange/blue accent skin inspired by the fire/ice mockup.
• Swirls Fantasy — optional purple fantasy accent skin inspired by the swirl mockup.

Pick a theme in Settings (⚙ in the title bar, or the tray menu); it applies instantly. The window is a rounded, frameless, always-on-top glass card you can drag by its body.

Collapsed vs expanded

• ▾ Collapse shrinks the shelf to a compact stack — overlapping thumbnails of your dropped assets with a count badge, like a small pile of files. Click the stack (or ▴) to expand again.
• Expanded shows your items in a grid or list (toggle with ▦ / ☰). Each item shows a thumbnail (real preview for images), name, size, and type. Select items to Open, Show in Explorer, or Remove from the shelf. Dropping more files adds to the shelf rather than replacing it. None of these actions import anything — the only path to Eagle remains Create Proposal → review → Validate Dry Run.

Settings

Open with the ⚙ button or the tray's Settings…:

• Theme and Default view (grid/list)
• Run at startup, Always on top
• Close shelf when empty, Save shelf when closed with items
• Show developer paths
• Import mode is shown read-only as Dry-run only; the "Enable live import" control is permanently disabled in v1 and gated behind a separate approval.

Saved shelves

A saved shelf is a parked working set: the files you dropped, your instruction text, the shelf's name and status, and pointers to any proposal/audit it generated. It lets you close a work-in-progress and pick it up later without re-dropping files.

What's saved: shelf id, display name, created/updated timestamps, status, original source paths, staged file references (if a proposal was generated), instruction text, proposal path, audit-log path, item count, and a per-type file summary. Binaries are never copied into the store — only referenced by path.

Statuses: draft (items, no proposal) → proposed (proposal generated) → validated (dry-run validated). imported is reserved for the future, separately-gated live-import path and is unreachable in v1; archived hides a shelf from the recent list.

Save: click the ✕ (close) button or close the window. If the shelf has items you get a Save / Discard / Cancel prompt — or, if Save shelf when closed with items is enabled in Settings, it saves automatically. The quick show/hide hotkey just peeks; it never discards. Rename the shelf any time with the ✎ button; the status badge sits at the top-right.

Restore: open the tray menu → Saved Shelves and pick a recent shelf to reopen it (files, instruction, name, and status are restored). Manage saved shelves… lets you reopen, rename, archive, or delete (delete asks for confirmation and only removes the shelf record — your files and any staged copies are untouched).

Where they live: data\shelves\*.json under the repository root (local, git-ignored). Use Open saved shelves folder in the tray to browse them.

How this differs from importing into Eagle: saving a shelf is purely local bookkeeping — it makes no Eagle calls and writes nothing to your library. Importing into Eagle only ever happens through Create Proposal → review → Validate Dry Run, and even that is dry-run only in v1 (no writes until the separately-approved go-live).

Architecture details: docs/SAVED_SHELVES_DESIGN.md.

---

Examples

1. Importing a folder of selfies

Drag your Selfies 2026\ folder onto the shelf. Type: selfies into Personal/Selfies, approved. Click Create Proposal. The summary shows the images mapped to type:image, source:camera/source:manual, and the Personal/Selfies folder suggestion with status:approved. Review and approve.

2. Importing mixed screenshots / references

Drop a folder containing screenshots and reference images. The app auto-detects screenshot in filenames and tags those source:screenshot → Research/Screenshots, while the rest map to Creative/Creative References. No instruction needed; add one to override.

3. Importing audio / video source files

Drop .mp3 and .mp4 files. They import natively as type:audio / type:video and are suggested for Audio/Source Audio and Video/Source Clips. Other formats not on the supported list are listed under "Unsupported" and skipped.

4. Handling duplicate files

If you drop a file already in the library (same name) or two byte-identical copies, they appear under Skipped (duplicates) in the review summary and are never imported twice. Eagle's own silent de-duplication is also caught by the count invariant.

5. Adding a natural-language instruction before proposal generation

Before clicking Create Proposal, type something like reference art for the GFL project, illustration style. The app extracts only controlled hints (project:gfl, style:illustration) — it never invents new tag values. Unrecognized words are ignored and the files default to status:needs-review.

---

Safety

• Never touches .library internals. Every path is checked by the Import Runner's path guard; anything under an Eagle *.library folder is rejected.
• Additive only. The app can only add items, tags, and folder assignments. It cannot delete, untag, move out of folders, or overwrite metadata.
• Proposal before apply. You always see a summary before anything is imported.
• Live writes are gated. In v1, Approve & Import runs dry-run only. Enabling real imports is a separate, explicitly approved change.
• Baseline check. Before any apply, the app verifies the live item count matches the expected baseline; a mismatch blocks the import.

---

How it fits together

You ──drop──> Intake Shelf (PySide6 UI)
                  │ safe copy
                  ▼
        configured staging inbox\intake_<timestamp>\
                  │ runner_bridge
                  ▼
        Eagle Import Runner  (proposal → apply → audit)
                  │ official Web API / MCP only
                  ▼
              Eagle library

See ARCHITECTURE.md for details and SPEC.md for the full product spec.