Special tools

The basic tools cover what every repository needs. A repository with a workflow of its own can switch on more: its special tools.

Engines

A special tool is backed by an engine: tested code built into Major Vault for one kind of work. A repository does not bring code. It picks an engine and configures it, in one file per tool.

A tool file

Each special tool is a Markdown file in .vault/tools/: the engine and its settings above, the description the model reads below. Acme’s .vault/tools/create_decision.md makes a create tool for one note type:

---
engine: create
type: decision
title: Record a decision
---
Records one decision of a project: what was decided, by whom, and when.
Refuses to overwrite a decision that already exists under the same title.

• The file name is the tool’s name, here create_decision.
• title and the body are the tool’s title and description, written by the repository for its own workflow.
• fields may replace the description of an input field, where the repository’s words fit better than the engine’s.

How special tools are listed

• With the repository in front of their name: projects__create_decision. Two repositories may switch on the same engine, and their tools never clash.
• Only for people who can read the repository. Everyone else does not see the tool, or the repository’s name.
• Only in their own repository. A special tool takes no repo: it is bound to its repository already, and refuses a path in another.
• Not twice. A tool file that does what a basic tool already does is not listed again.

Guards

Some engines protect what they own. Switched on, such an engine changes the basic tools for that repository’s paths only: edit_note and move_note then refuse a change that only the engine’s own tools may make. A repository that does not switch the engine on keeps the basic tools as they are.