The Browser

eidos browser                       # http://127.0.0.1:6180, this machine only
eidos browser --port 7000 --no-open

The workbench

The frame is VS Code’s. A command center across the top opens the palette: empty, it lists what you opened recently and matches blueprints, docs, drafts, tasks, canvases, and asset files by title, id, and path as you type (T-A7GJ finds the task, B-5KFM the blueprint), and what you pick opens on its own page, not in the reader over a table; > lists every command the host and each plugin registered, with its key. ⌘P or / opens it, ⇧⌘P opens it on the commands (the keys are a preference: VS Code’s, /, or ⌘K). Back and forward arrows sit beside it. A Go to command shows the activity that holds where it goes (the Root view for a collection or a top-level doc, a plugin’s activity for its pages), opening the sidebar if it is hidden. Every activity has a Focus command (Focus Root, Focus Backlog) that shows its view wherever you put it and moves the cursor into it, and every activity with settings an Open … Settings command that goes where its right-click menu’s settings item goes; any of them takes a key under Hot keys.

/ opens on the Home: the health check’s findings first, errors before warnings; what the plugins put there (the tasks assigned to you and the board by column, from the Backlog); then the root’s blueprints by collection, with its documents and drafts counted. The Home’s head is the root’s name: the product it defines (eidos setup --product, or the pencil beside it), else the repository it sits in. The browser’s tab carries the same name.

An Activity Bar at the left edge holds a house for the Home first, then one icon per view in the Primary Sidebar: the Root view first (the top-level docs, the drafts, one entry per collection, each plugin’s group), then each plugin’s activity in the order you set (Canvas, Comments, Backlog, Source control, Assets, Settings); the person you act as and a gear sit at its foot. An Auxiliary Sidebar at the right edge and a Panel under the main area are rows of tabs a plugin fills (a blueprint’s history, its attached tasks and assets, the Chat, the Terminal), hidden until shown. Every sector shows, hides, and resizes as VS Code’s do (⌘B, ⌥⌘B, ⌘J, a drag on its edge), and all of it is remembered per person in local.yaml. Where a plugin puts a view is only where it starts: drag its icon or its tab onto another sector (the Chat into the Panel, the Terminal into the Primary Sidebar), or right-click it for Move to, and it stays there on every root until you move it back or run Reset View Locations. Right-click the title bar (Back and Forward, the search, the sector buttons) for the Activity Bar, the Primary Sidebar, the Panel, and the Auxiliary Sidebar, each ticked while it shows, so a hidden Activity Bar, with the person you act as and the gear at its foot, comes back with one pick. The rows of a sidebar list take your own order: drag one where you want it, a line marking where it lands, right-click it (or use its ⋯) for Move up and Move down, or press ⌥↑ and ⌥↓ while it has focus. That holds for the Root view’s top-level docs, collections (each collection’s saved views follow it), and drafts; the pages of the Backlog, Decisions, and Comments activities; a page’s saved views; the canvases; the Assets activity’s folders; and the Activity Bar’s icons. The activities’ pages are in your order on every root, in preferences.yaml; the order of a root’s own rows (its docs, collections, and drafts, its views, shared ones included, its canvases, its folders) stays with that root, in its local.yaml, and is never written into the files the root shares. The statuses and the types keep the order the root’s settings give them, since that order is shared.

Search, first among the activities until you drag it elsewhere, is the command center’s search kept open in the Primary Sidebar (⇧⌘F): what matches by title first, then every mention in the text with the match marked. Tabs, in the desktop app (a browser has tabs of its own): pages open as tabs above the main area. A page opens in the tab showing, ⌘-click a link or press + for a tab of its own, pin a tab to keep its page, and close one with its ×, a middle click, or its menu; close the last and the main area stays empty until you open a page. The tabs open are remembered for each root. A middle click on a link, a sidebar entry, a search result, a row of a table, or a card on the board opens its page in a new tab, a tab of the app’s own in the desktop app and a new browser tab in a browser, and leaves the page you are on as it is. A reader shown in a modal (a blueprint, a draft, a task, a decision, a Registry package, a comment thread) has Open in new tab and Open in this tab before its ×. Focus mode, under Preferences → Workbench, draws one page at a time instead. Find in File (⌘F) finds text in the page or file open, every match marked, with Enter and ⇧Enter to step through them.

Collections as tables

Each collection is a table: one row per blueprint, the properties that apply to it as columns, sortable from the header, with a search box, a column picker, and a filter per property flagged as one; a property also switched to Only show actively used in filters offers only the values a blueprint in the collection holds. A filter holding a value says so, on every page that has filters: its button names the filter and the value in the accent, and its × puts it back. A dropdown of ten options or more, a filter’s or a field’s, opens on a search: type part of a value to narrow the list, then pick it with the arrows and Enter. A grouped collection nests rows under their groups. A dot at a row’s end marks a blueprint the check has something to say about. N starts a new blueprint; every table the page ships sorts the same way, with its filters on the left. On the Backlog’s table and the Decisions list, the title’s head holds a second target, ID, that sorts by id: in natural order under the sequential id scheme (T-2 before T-10, T-F36.2 before T-F36.10), and by the day each was made under a random one, whose ids carry no order. Every table has the same search box first among its filters (a collection’s, the Backlog’s table, board, drafts, and milestones, the blueprint drafts, the assets, the hot keys, Vocabulary, Versions): it keeps the rows holding every word you type, in any case and any order, in the id, the title, or a value the row shows, and its × empties it. On the Backlog’s board, table, and drafts, a collection’s table, and the assets, the filters (the search among them as q) are in the page’s address, so a filtered table can be bookmarked, shared, reloaded, and reached again with back and forward; changing one adds no step to the history. The other tables hold theirs while the page is open. A refresh beside the search reads the table’s rows again, for a change that has not reached the table on its own; a change made in a modal over the table (a task’s status set in its reader, say) reaches it without one.

Saved views

Once the Backlog’s board, table, or drafts, or a collection’s table, is filtered, Save as view in the ⋮ beside its search keeps the page’s filters and its sort under a name: Local, on this machine in local.yaml and never committed, or Shared, in .eidos/plugins/eidosmd/views.yaml and committed with the root, so the whole team sees it. The view is listed at once in the Primary Sidebar in a group of its page’s views (Board views, Task views, and Draft views in the Backlog, a collection’s after the Collections), a local one with the laptop, and opens that page as it was saved; its address is the page’s with view=<id> (/p/backlog?view=V-7K2M&assignee=agent), and the sort sits beside the filters as sort=<column>, - before the column for the other way. Change the filters or the sort of a view you opened and the ⋮ offers Update view for it or Save as new view; right-click a view, or its ⋯, to rename it, Make local or Make shared it (it keeps its id, so a page open on it stays on it), or delete it. The Backlog’s My work, By status, and By type are the views every root starts with. eidos views →

Click a row for the reader over the table: properties on the left, holding still while the body on the right scrolls with its contents rail, findings and comments underneath, set apart by a rule. Esc returns to the table; Expand opens the blueprint as its own page. A top-level doc, a draft, a task, and an asset open in the same shape. Right-click a row, here or in any table that lists things (the drafts, the Backlog’s tasks and milestones, the assets), for its actions: the ways in first, its id or path to copy, the ways out to the file, and the one that removes it last, asked once.

Reading, Editor, Source

A reader’s page opens on a bar that stays put as you scroll: the way back and the blueprint’s id (specs / B-5KFM; a task’s parent and its own id, each with its type’s icon, Backlog / T-PARENT / T-TASK, the parent alone and never the chain above it), with nothing to save or revert on it (Delete, Find in file, and Move blueprint to…, which moves the file to another group of its collection with every link following, are in the ⋮); the title under it with the path below, the id and the path each copied from a link that shows on hover.

The reader has Obsidian’s three modes, picked in the ⋮ beside the title (the one in use ticked) and carried from page to page for the session (a Default view preference says which it starts in). Reading shows the rendered page. Editor is a markdown editor with the page rendered as you write: the block under the caret shows its syntax in place, at the height it was drawn and marked by the accent along its edge, and every other block is drawn; a + on an empty block, or / at its head, opens a menu of blocks (headings, lists, a task list, a quote, code, a table, a rule, and what the plugins offer: an image or a file from Assets, a task from Backlog); a written block shows its kind’s icon instead (¶, H1, a list’s), which turns it into another kind; a pasted image lands in the asset folder and in the text. Source is the file as text. A line break you type is a line break when the page is read, as Obsidian reads a note, and a blank line starts a new paragraph. A right-click in a field, the editor’s blocks included, shows the browser’s own menu, with its spelling suggestions.

In every mode the properties edit in place as typed fields the way Obsidian shows them: a dropdown where a property has options, pills for a list (a long title cut with an ellipsis, whole on hover), each added from a select that says what it adds (Add blueprint, Add assignee) and is searched once it offers ten or more, a checkbox, a calendar for a date; a declared property the file lacks is one click away, listed by its name (never the id a file carries, which the bar shows), and one a tool owns is shown locked. Save writes the file in the house style, applies the Linter’s on-save rules, and runs the check on it. The same menu opens the file in each external editor you listed under Preferences, one Open in per editor by its name (Open in VS Code), or shows it in Finder; the palette also has Open root in Finder and Open root in each editor, for the root’s whole folder.

Saving, as in VS Code

An edit is held in the page until it is saved, as VS Code holds an editor’s changes: by Auto Save, a second after you stop typing unless you choose otherwise, or by File’s Save (⌘S, or Ctrl+S off a Mac, for the editor in front) and Save All (⌥⌘S, or Ctrl+Alt+S). No editor shows a Save or a Revert button: in a browser, File’s Save, Save All, and Revert File head the menu a right-click on the bar across the top opens, and every one is in the palette; the desktop app has them in its File menu. While an item holds changes its title and its tab wear a dot, and Revert File (or Revert changes in the ⋮) puts back what the file holds. Undo and redo (⌘Z, ⇧⌘Z, and Ctrl+Y off a Mac) step through what you did since the item was opened, across saves.

A held edit stays with its tab: go elsewhere and the item stays in its own tab, the page you went to opening beside it, and coming back finds the edit where you left it. Closing its tab or its modal, switching to another mode, or reloading asks Save, Don’t save, or Cancel, once for everything held. A save that fails keeps the edit and says why. When the file changes on disk while it is open (git, a command, another editor), an item you have not edited takes the change in place and nothing is written. An item holding an edit says the file changed, and Auto Save waits for you: Refresh takes the file, Keep mine writes yours over it on the next save, and a save you make before choosing is refused.

Auto Save is a preference (Preferences → General), with VS Code’s four settings:

Setting	What it does
After delay (the default)	Saved after the Auto Save delay (1000 milliseconds unless you set another) since the last change.
Off	An editor with changes is saved only by Save or Save All; its tab keeps its dot, and closing it asks.
On focus change	Saved when the editor loses focus: you click another part of the page, open another item, switch tabs, or leave the window.
On window change	Saved when the window loses focus.

With Auto Save on, closing a tab or quitting saves what is held instead of asking. A save that renames the file (a task’s new title) takes the reader to the new name, and leaving at once never loses it or brings you back. A save never makes the page read the file again: the page knows its own save when the change comes back from the disk, while a change anyone else makes still shows at once.

A code block fenced with a language (```ts, ```yaml, ```bash, and the rest of Shiki’s grammars) is coloured in the theme’s colours in Reading, in the editor’s drawn blocks, and wherever else the page shows markdown; an untagged block stays plain. A block fenced as mermaid is drawn as its diagram in the page’s colours and font, and redrawn when the theme or the light and dark side changes. The file keeps the text: in the editor a click on the diagram opens it, Diagram in the block menu puts one in, and a block that does not parse shows its text with Mermaid’s error under it. Export to PDF…, in the ⋮ of a blueprint, a document, a draft, or a task, writes the one file open as a PDF, with or without its title and properties, at the page size, orientation, margin, and scale you pick; the desktop app asks where to save it, and a browser opens the print dialog on it.

Drafts

A blueprint can be started before it belongs to a collection: the Draft button on the New form (New spec, New video: named for the collection picked), Shared or Local from its menu, keeps the file with the CLI, shared with the root or local, in no index or check until Publish moves it into its collection under new’s rules. Drafts have a group in the Root view and a page of their own; started from there (the group’s +, the page’s New) the form is New draft, whose Create draft and Enter keep the file as a draft, never a blueprint. eidos draft →

Growing the framework as you work

Organization is earned, not set up first. A framework editor (in a root that marks nobody, everyone is one) adds what the work needs where the work is, and the framework follows:

New collection, the + on the Collections group: a name, the word for one of its things read from it, and a starter template of one required Intent section. Each collection’s row shows New and that word on hover.
New group… in the New form’s group select, even for a collection with no grouping yet: the grouping starts labelled Group, its property declared, and the blueprints at the collection’s top move into the group.
Promote to framework, the + beside a property the framework does not declare: the property form opens filled in, its type read from the value. A property of your own is never a warning unless the Health Check’s Settings turn on Warn on unknown properties.
A section the template offers and a blueprint lacks is drawn greyed in its place with a + that adds it. Templates mark their Required sections in the builder, and a new blueprint starts with those alone.

Settings

The gear opens Settings as a sidebar view, its groups named as VS Code names its scopes: User (Preferences, Appearance, Hot keys, yours on every root) and Workspace (this root’s: Framework, Health Check with the check’s findings and their fixes, Fix all supported issues at the top running every fix at once, after listing them, holding a re-id, a renamed file, or a dropped value until you tick it, and counting the fixes on a bar as they run, and a Settings tab for strictness and the section rules; Users, Core plugins, Community plugins, Registry). Framework opens the framework document as forms (Root, Folders, Templates, Properties, Vocabulary, Roles, Me, each page a draft until Save to Framework), and while one of its pages is open Settings becomes the framework’s own sidebar, its pages under a way back to the page you came from. On Users, New role… at the foot of a person’s Role opens Roles. A plugin’s settings open from the gear at the foot of its own sidebar view or the cog on Plugins, and Settings then lists that plugin’s sections alone, under a way back to the page you opened them from, which holds as you go on to another plugin’s settings; its page in these docs is the Docs button in the head of the plugin’s settings. A setting changed on any of these pages shows its new value at once and keeps it while it saves; it goes back only if the save fails, and a toast says why.

The framework’s pages, Users, and every plugin’s shared settings are changed by a framework editor. To anyone else they stay readable but read-only, and Edit in the page’s head asks to make the user you act as an editor; once you are one, the page edits directly. A root that marks nobody an editor leaves everyone one. A setting kept on this machine (local) is never held.

Users: the people who work in the root (name, @alias, role, email, an Access select of None, Editor, or Owner, and an Agent switch for an AI agent that comments as itself), kept in settings.yaml; eidos users lists them, eidos users add adds one, and eidos users set sets the access. An owner is always an editor, only an owner grants or removes Owner, and an owner’s avatar and @mentions carry a star. The user you act as is marked wherever they are named: their avatar is ringed in the accent color, and their name, their assignee pills, the @mentions of them, and their row here are set in it. A plugin’s own user, the AI Agent’s @agent, is listed as the plugin’s: its name, alias, and role are read-only, it has no email or access, and it stays while the plugin is on. Acting as picks who this machine signs comments as, from the people only: an agent acts from the shell with --as, so it is not offered there. Attribution, not authentication.
Plugins: every plugin with its switch, its description, and its settings as a form; a setting marked local is kept on this machine. Plugins →
Preferences: the look, laid out as Obsidian’s Appearance: the base color scheme (Adapt to system, Light, or Dark), an accent color, a theme (Default, one included with Eidos such as Catppuccin, AnuPpuccin, Nord, Gruvbox, Tokyo Night, or Ledger, or your own, made in the theme editor with the light side beside the dark, imported from a CSS file or an Obsidian vault, and exported as one CSS file), the interface, text, and monospace fonts, the size of the reading and editing text, and Ctrl and the scroll wheel to change it; then the language (English, Spanish, or Portuguese, or the one your browser asks for), the default view, the page width (Fixed or Fluid, also Change default page width to in the palette), the palette’s keys, the corner notifications appear in (top right by default), the external editors (as many as you like, each a name and a command, picked from the common ones such as VS Code, Cursor, Zed, or Sublime Text, or typed), whether release notes show after an update, whether the Backlog’s board draws each subtask as a card (Show subtasks on the board, off by default), whether each person’s picture comes from Gravatar where their initials are drawn (Show Gravatar pictures, on by default: the page sends gravatar.com a SHA-256 hash of each user’s email, never the email, and keeps the initials for anyone with no picture, no email, or no network; an agent is never looked up and wears the agent’s mark, a spark on the accent color; off, nothing is sent), and the order of the sidebar’s groups and activities. Me holds who you are on every root (your name, email, technical capacity, and how you like to be helped), copied into each root’s me.md; Ask your AI fills it from the AI Agent for you to review, and Copy prompt puts the same question to any AI.
What’s new: every release with its headline and a one-sentence summary, and a page for each one, its entries grouped as New, Improved, Changed, and Fixed, from the Releases page. After an update the page opens the new release’s page once, listing any releases you skipped; What’s New in the palette lists them all, Show Release Notes opens the one you are on, and the Home ends on it.

Everything the browser remembers is YAML in .eidos/plugins/eidosmd/: settings.yaml and the shared views’ views.yaml travel with the root, local.yaml is yours and gitignored (as is a local/ folder beside it). Nothing is kept in the browser or a database.

The Registry

Registry, under Workspace in Settings and in the palette, is the Registry inside the page: every framework published there, as a table of name and description, category, collections, and installs in the last 30 days, with a category filter and a search on the left. A row opens the framework over the table (Expand for its own page, /registry/@owner/name): its collections with each variant’s template as the file it is, its roles, top-level documents, properties, and README, each piece marked as this root has it: not at all, the same, or differently.

Include in this root is eidos install for the root you are in. What the root lacks is checked, a piece it holds differently is yours to pick, and a property comes with its collection or with Everything this root lacks (--all). The plan shows what is written and what is already here, and each conflict asks Keep current or Accept incoming before anything is written; the button names how many pieces it includes. What lands is exactly what eidos install <package> --collection … --on-conflict … --yes writes: the index rewritten, the check run, the provenance recorded, and the one install-count request sent. Each piece the root lacks also has an Include of its own, which opens the same plan with only that piece ticked, as eidos install <package> --variant … takes one. eidos install →

When the Registry cannot be reached, nothing is listed and nothing can be included; Try again asks it afresh. A README is shown with its HTML as text and its images as links, so the page still loads nothing from outside.

Canvas

An activity of its own, listing every canvas with its pages. A canvas is a whiteboard of pages where a node is a sketch (an idea that is not a blueprint yet), a blueprint (drawn live from its file), a sticky, or free text, with flows between them, frames around regions, and comment threads pinned to anything. A sketch is promoted into a blueprint through the same scaffold as eidos new and keeps its place. Nodes are styled by the framework’s own properties. A page exports as PNG, SVG, or JSON Canvas for Obsidian.

Navigating the canvas → is the manual: every tool, gesture, shortcut, and the file on disk.

How it is built

A Preact app shipped in the package as static files, served by Node’s own http module with a JSON API under /api/ (a plugin’s routes under /api/plugins/<name>/), bound to the loopback interface only. No external resources, so it works offline. Search uses SQLite full text on Node 22.16 or newer and Node 24 (node:sqlite with its FTS5 module, nothing to compile) and an in-memory scan on an older Node, whose node:sqlite is missing or lacks FTS5.