Assets

The Assets plugin manages the files in a project that are not markdown: a PDF, a diagram, a screenshot, a data file. They live in every folder the framework declares as the plugin’s (assets/ by default), and the plugin lists them, links each to the blueprints and tasks it belongs to, finds the places that reference it, and moves or removes it through the host so history and links follow. On by default in a new project; a project made before that keeps it off until eidos plugin enable assets switches it on and declares the folder.

Links and references

A link is declared: this file belongs to these blueprints (by their permanent id), these tasks (by name), and these URLs. Links live in the plugin’s index, never beside the file and never inside a blueprint. A reference is found: a blueprint’s or a task’s body that carries the file’s path. References are computed on every read and written nowhere. A file with no record and no reference is still listed.

A bundle is a folder directly inside an asset folder, handled as one asset: a clickable prototype with its scripts and styles, or a design delivery. It is one row, one record (title, description, links, comments), and one page, and a rename or a removal takes the folder, its record, its references, and its threads as one. Link the bundle, not each of its files.

In the app

• Assets, an activity in the Activity Bar: All files, Clean up, your saved views, and a filter per folder and per kind (Bundles among them), each with its count, and an upload in its head. The files and bundles are a table under /p/assets showing each one’s title and description, with a column cog, New bundle, Add a file, and open, rename, and remove on a row; its search, filters, and sort sit in the page’s address, so the ⋮ saves them as a view.
• A page per file, leading with its name (renamed where it stands), its title and description edited in place, its links (the blueprints and tasks offered as you type), and its references linked to their place. Below them, the preview at the page’s width: an image shown as an image, a PDF in the browser’s own viewer, an HTML mockup in a sandbox whose scripts never reach the project, any other file as its name, type, and size with Open in the external editor and Reveal in the file manager. Comment threads sit at the foot, listed in the Comments table with a way back.
• A page per bundle: it previews its entry (index.html, else its only HTML file, else its first image, or the file picked under Opens on) and lists its files. Add files and Add a folder fill it.
• Full preview, on an HTML file’s or a bundle’s page, shows the mockup alone across the window: Desktop at the window’s width, Mobile in a 390 × 844 frame, and Responsive in a frame you size by dragging its handles, the size shown. It runs in the same sandbox, Reload reloads it, and Escape closes it.
• Attached assets, a view in the Auxiliary Sidebar: the files linked to or referencing the open blueprint, the count on its tab, and a way to link another.
• In the editor, the block menu offers Image and File from a picker: ![…](…) embeds an image, […](…) links a file, as markdown has it. A pasted image lands in the asset folder and in the text, scaled to max_image_size on its way in. Quick Open answers files by name.
• Clean up lists every file and bundle nothing links to, no body references, and no file of the project names, and removes the ones you choose after asking once.
• An image nothing links to any more goes: delete the blueprint, task, or doc that drew it, or take its last link out of a blueprint or a doc, and an image in the asset folder that nothing else in the project names or links to is flagged. An image pasted or uploaded from the page that is still named nowhere once the interval has passed is flagged too, so a paste you undid does not stay for good; a file added from the shell or put in the folder by hand is never flagged for this. A sweep removes a flagged image once it has stayed unlinked for the interval (auto_remove, 5 minutes by default), through the host (with Git on, a git rm you can get back from history), with a toast naming it. Clean up shows when each flagged image goes, with Keep; an image linked again is kept. The sweep runs while the project is open in the app. Remove images nothing links to in the Assets settings (remove_unlinked, on by default) turns it off.

On disk

• assets/ (or any folder declared owned_by: "@assets/files"): the files themselves, nested, dotfiles ignored. The project →
• .eidos/plugins/assets/index.yaml: one record per file or bundle that has one, keyed by its path from the project: title, description, links, and a bundle’s picked entry.
• .eidos/plugins/assets/settings.yaml, shared: max_file_size (megabytes, 6 by default), the largest file the page takes and add writes; max_image_size (pixels, 2000 by default, 0 for no limit), the longest side an image keeps; remove_unlinked (on by default), whether unlinked images are removed. The settings page shows the first two under Uploads as Largest file and Longest image side.
• .eidos/plugins/assets/local.yaml, local: auto_remove, the interval in minutes (1, 5, 15, 30, or 60). .eidos/plugins/assets/local/pending.yaml, local: the images flagged on this machine.

From the shell

eidos assets                                    # every file per folder, with its links and reference count
eidos assets --for login                        # the files linked to one blueprint; --folder, --json
eidos assets show assets/login-flow.png         # its links (missing where the target is gone) and references
eidos assets add ~/Desktop/login-flow.png --to @login   # copied in; --folder, --name
eidos assets bundle checkout-prototype --title "Checkout prototype"   # a bundle; --folder, --description
eidos assets add ~/Desktop/proto/index.html --bundle checkout-prototype   # into a bundle, made if it is not there
eidos assets link assets/login-flow.png --to task:rate-limit-the-login-form --drop https://…
eidos assets set assets/login-flow.png --title "Login flow" --name login-flow-v2.png
eidos assets set assets/checkout-prototype --entry checkout.html   # the file a bundle opens on; "" for the one found
eidos assets remove assets/login-flow.png

A link is @<blueprint-id>, task:<name>, canvas:<id>, or a URL. set --name moves the file through the host (git mv where Git is on) and rewrites every blueprint and task body that named the old path, and every canvas image node that showed it; remove removes it through the host and drops its record. A bundle takes the same show, link, set, and remove, its folder, record, references, and threads moving or going as one. eidos assets --json lists bundles and gives each file the bundle it sits in. Never rename or delete a file in an asset folder by hand.

To attach a diagram to a blueprint: add the file, link it (--to @<id>), and link to it from the blueprint’s body as a relative link where it is discussed.

What the check reports

assets/link-missing (a link to a blueprint or a task the project does not have) and assets/record-orphaned (a record for a file that is gone; Drop record fixes it). With the plugin off, the folders stay declared and untouched, no file is read, and no route answers.