Components
A component is a program lnk installs and runs on its own: a module,
a harness program, a connection, a tool, a store driver or a standalone
program. link-component is the one typed description of a component
that its build, the installed program and lnk all share.
What a component is
A component is one Cargo package with one program, lnk-<id>, and a
module.toml beside it. Its kind says which interface it answers:
module, harness, connection, tool, store or program. A
library or a contract isn't a component, since programs link it and
nothing installs it.
Where its description comes from
Cargo gives a component its identity: its id, Cargo name, version,
license, description and program, the Component type. Its
module.toml gives its kind, what it requires and recommends, its
place in lnk up's menu, how it's removed, and its documentation, read
into Source. Its actions.toml gives its actions, each an Action
keyed by its command line: its help, its arguments, whether it's
hidden, plumbing between programs a person never runs, and where it's
offered (Surface), on the CLI, as an agent's command, a route or a
tool. A field either type doesn't know is refused.
What a hidden command is
A hidden command, or a command under a hidden group, is Link's and not a
person's. Link runs it, such as a backend's typed request on standard
input, and never offers it. The registry carries it as Command.hidden,
so lnk --help does not list its group and Next's graph does not count
it. Routing still dispatches it.
Command Importance
Each action declares its role: primary gives the module its function,
secondary supports a primary command, and plumbing is hidden work
between programs. Primary commands have an owning documentation section;
plumbing is documented only under the owner's More references. Command
depth groups subcommands, dispatch assigns a command prefix to a module,
and surfaces selects where it is offered.
What each command leads to
An action's next and fail are the Nexts its command can give on
success and on failure, each a command as cmd! writes it (lnk agent connect <connection>), retry for itself again: Next's graph, read by
format's check.
What each command diagnoses
An action's diagnoses is the kind of name (agent, box) its command
diagnoses: given one, <command> <name> --json answers that name's
state as typed blocks, the same a person sees, and lnk issue create puts it
in an issue scrubbed. Each kind has one; an end-to-end test holds the
contract, with the kinds no command diagnoses yet on a list that may
shrink, never grow.
What an installed program answers
At build, link-component-build joins the two into Resolved, the
self-contained answer embedded in the program. When lnk asks a
program what it is, this is what it gets back, so help, routing and the
install menu work without installing anything the program needs.
What an operation needs
requirements works out what one command needs installed, from the
requires of every component it reaches: a module it runs, with the
command and options it runs it with, or a capability of the machine.
The machine's OS, architecture and libc, and the operation's options,
decide which apply. A recommendation installs nothing until it's
chosen, and a cycle of required commands is refused.
Values the module refuses
An option given a value its type or listed values refuse, on the
command line or through its environment variable, binds nothing
(Values::Refused). Then lnk installs and offers nothing for the
command, and the module's own parser refuses it with its usage code.
Documentation
A component's [documentation] names its topic, where lnk man and
the website find its pages, and says with quickstart = false that its
first page has no quickstart, for a program only Link runs. An
installed module carries its own pages, and one that isn't installed
shows where to get it.
Build-Time Embedding
Build-Time Embedding explains the build-script entry points, embedded pages, registry generation, and the inputs refused before a component is packaged.
What a release ships
Every workspace member ships. The release checks use Cargo's
program inventory for archives and documentation. Each component declared
with module.toml also appears in the registry.
Optional release exclusions
The component format supports holding a member back with
released = false under [package.metadata.link]. A held member
stays in the code and is built and tested, and dev, staging and source
builds keep it. Only a production build's registry and archives, and the
website, leave it out. No member sets it today. Any other value of released, true among them, is refused.
The registry of a production build
A production build's lnk, Link's public release among them, is built
with LNK_BUILD=prod, and
link_component_build::registry then embeds only the released
components (link_component::release::registry). A released one's
recommendations of a held one are dropped, but a requirement of one,
or an upgrade that adds one, fails the build.
Its other parts
lnk bundle packages and seals the same selection,
and the website leaves out each folder scripts/documentation-index.json
marks "released": false. A repository check refuses a normal or build
dependency of a released crate on a held one, and holds the index's
marks to the crates'.
Question answers
A module's answers lists the questions of modules below it that it
answers, each by its name (<module>.<what>, check_question):
# module.toml
schema = 1
answers = ["storage.folders", "storage.owner"]
[module]
id = "example"
kind = "module"It answers them all through one hidden flag at its program's root,
lnk-<module> --link-answer <question>, which its generated parser
has. A name that isn't a question's, or a question listed twice, is
refused. How a
question is asked and answered is the
framework's.
Account setup
account_services names exact HTTPS origins whose successful sign-in
sets up this component and its required modules. Only declarations
embedded in the trusted core registry select components. A service
cannot supply a program, download URL or capability. A component with
account setup declares the questions it answers in answers; discovery
then reads the cached login through that existing typed question.
Action routes
An action offered as a route or tool names its callers and bridge,
exactly one of answer and carries, and positive limits.bytes and
limits.time_ms. The registry refuses incomplete definitions.
Caller discovery
The bridge establishes owner, agent, program or trigger from its
trusted context. Registry discovery filters actions by caller and surface;
request arguments cannot change the caller. Canonical routes use
/_link/<namespace>/<action>; encoded and relative paths do not match.
Answer budgets
A bridge applies each action's byte and time budgets before returning a
typed answer. streams distinguishes a stream from a single answer;
carries names a protocol relayed without a Link answer type.
Command Tools
An action can expose its existing command through MCP by listing the tool surface and the agent caller, setting bridge to command, and declaring answer as Json or Text. It declares positive limits.bytes and limits.time_ms values. JSON commands must declare --json. A hidden, streaming or protocol-carrying action cannot use this bridge.
Read Classification
read_only = true marks a command whose calls need no change approval. Omission means a change. This classification controls the Link agent's sandbox allowlist, so a command with a mutating option must be treated as a change. The installed descriptor retains this policy with its generated tool metadata.
Tool Inputs
Tool names and schemas are projected from declared commands and their typed arguments. Transport and approval flags are caller-owned, and an agent-bound server withholds the agent selector. A value-taking flag with optional_value = true accepts JSON null for its bare spelling and a typed value otherwise. Other command validation stays with the owning parser, so commands and tools share the same implementation.