Assets

The Assets plugin manages the files in a root 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. Off by default; 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.

In the browser

• Assets, an activity in the Activity Bar: the folders and their files, with an upload per folder and filters. The files are a table under /p/assets, with open, rename, and remove on a row.
• A page per file: an image shown as an image, a PDF read in the page with a link out, any other file as its name, type, and size with Open in the external editor and Reveal in the file manager; its title, description, and links (the blueprints and tasks offered as you type), and its references linked to their place.
• 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.

On disk

• assets/ (or any folder declared owned_by: "@assets/files"): the files themselves, nested, dotfiles ignored. The root →
• .eidos/plugins/assets/index.yaml: one record per file that has one, keyed by its path from the root: title, description, and links.
• .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.

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 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 remove assets/login-flow.png

A link is @<blueprint-id>, task:<name>, 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; remove removes it through the host and drops its record. 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 root 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.