Decisions

Why lnk is installed, split and updated the way it is.

The command line is "Link", but /bin/link already exists on macOS and Linux, and package names are hard to change, so the command, its modules (lnk-<name>) and most environment variables (LNK_*) say lnk.

Why are modules separate programs and not Cargo features?

Separate programs let a person install one capability without linking every other module into its executable. Each module has its own installation and process boundary. Calls between modules use their documented commands, so callers still depend on those interfaces.

Why do the core and every module share one version?

The core and every first-party module are built and signed in the same release, one archive per program (lnk-core-<target>, lnk-<module>-<target>). So lnk module add always matches the core, and lnk upgrade updates them together. A lnk built from source never installs a release's modules, which may be another's code under its version. It records the checkout it was built from, and lnk module add builds its modules there, as lnk up --source does.

Where does a source build put its modules?

Where that lnk is, so it finds them beside it and no second install mixes another version in. A lnk run from a Cargo target folder, such as target/debug, builds them into that folder with its profile. One in a Cargo installation's bin installs them into that installation. Anywhere else, it changes nothing and says where it is, since a module put elsewhere would be one lnk might not find or might find stale.

How a module Link doesn't build is trusted and checked before installation.

By its own key, asked about once and pinned after. A harness Link doesn't come with is released and signed by its own repository, as anyone's adapter would be: Link's key signs only what Link's release builds (its modules, and its harness adapters), so a fix to an outside adapter ships when its repository releases, without Link vouching for code it didn't build.

Pinned, never listed

lnk keeps no list of trusted outside keys. The first add shows the key and asks, and every upgrade must be signed by the same key, so a repository taken over later can't push a release to the machines that added it.

Its program must answer the generic component protocol through --link-describe, using its own ID and lnk-<id> executable name. A standalone program and an ID belonging to Link are refused. A harness adapter also implements the harness contract used by the Agent program, while other module kinds implement their own subject's interface.

Where Link keeps what's yours and what's this machine's, and what an uninstall takes.

Why two folders, not the XDG ones, and why ask where one went?

An owner should be able to put their Link folder in Documents, or on the Desktop, and have everything still work. So Link keeps what is theirs, their agents and files, in one folder, and what is this machine's (its programs, settings, caches, sockets) in ~/.lnk. Every path Link stores is relative to its folder, so either can move or be copied.

Not the XDG folders

The XDG folders spread one install over three places and leave the owner's agents among other programs' settings. Only the machine folder's settings name where the Link folder is, and only once it has moved: the places of everything else are one spec that comes with Link.

Link asks where a moved Link folder went rather than search. A search of the disk is slow, may open folders the owner keeps private, and may find a copy rather than the folder they use. The folder's marker holds an ID that this machine records the first time it sees it, so a moved, renamed or replaced folder is told apart from a fresh start and asked about once.

What does lnk uninstall delete?

The programs, and only the parts you pick. Removing a tool and deleting what it kept are different wishes: an agent's memory, your files and encrypted buckets' passwords can't be made again, so each is its own answer, and none is the default.

Why does each module say what it keeps?

So the core knows no module's files: it asks each installed module (lnk-<module> uninstall --parts --json) what it keeps, by part, and has it stop its services and delete what was picked (uninstall --delete <part>) before its program goes. A module from outside Link is only told to stop, once you've said yes: its parts are never offered, so what it keeps in ~/.lnk or ~/Link is rest.

How parts merge

Parts of one name merge (the cloud adapters each keep some of clouds), and rest is what no installed module claims, which the core deletes itself: a module removed before keeps its files there. lnk module remove takes what needs a module with it, the reverse of what lnk module add brings.

Why does a published installer carry a version floor?

latest in the releases repo has no version to compare with, so someone with that repo could point it at an older signed release with a known hole. A published installer can carry its build's minimum version and refuse an older latest. The source script leaves that floor unset. Signatures authenticate downloaded release files, while the first script fetched still relies on its host's HTTPS and trusted build.

How does lnk say a newer release is out?

lnk up and lnk agent show, the commands a person runs to see where things stand, show ordinary update notices at most once a day on stderr. They never wait on the network. Ordinary notices are quiet with --json, off a terminal, and with LNK_UPDATE_NOTICE=off. Critical security advisories remain visible under those settings (Security Update Notices).

What the notice tells

So it tells only what the last lnk upgrade --check found, and starts the next in the background a day after the last, for the next command to tell. The version comes from the release's signed VERSION, as lnk upgrade reads it, so nobody but Link's signer can make every lnk say "upgrade".

Why is lnk --help the groups alone?

Every command and every module made it 122 lines, which no one reads past the first screen. It lists the groups, each in its own help's words, and the core's commands; lnk help <group> lists a group's commands, which are its module's own help, and lnk module list the modules and which are installed. A word that is no group gets the one it most likely meant: a plural or a module's name (agents), a command of one group alone (login), or a group a typo or two away (agnet).

What a module needs

Where what a module needs, or goes with, is declared, and when lnk asks before it installs one.

Where is what a module needs declared?

The owning module.toml declares dependencies and required commands, including conditions for a feature or platform. The core's registry derives installation order from those declarations. Repository checks compare cross-owner calls with their declared requirements, so a new call updates its owner's declaration rather than a core table.

Why does a missing module install without a terminal?

Because the command typed named the feature: lnk agent move gcp in a script is a yes to the box and cloud modules it needs. It installs from Link's signed release, as lnk module add would, and says what it installs, on stderr. Only a module's own lnk underneath (it carries LNK_EXE) installs nothing and names the command instead: a check a module makes, such as whether you have any cloud accounts, never installs one.

Why one question, and sometimes none?

In a terminal, a missing module is asked about once, naming everything it will install with what that needs (Install cloud, accounts and box?), after the command's arguments are read. lnk <group> whose own module is missing asks before: only that module can read its arguments. A command that names the module itself (lnk agent connect slack, lnk agent harness set hermes, lnk agent tool add web) asks nothing: naming it was the yes.

Why doesn't the storage module need the cloud module?

A bucket in a folder uses no cloud. So the cloud module is installed when a bucket names a cloud account, the way a box's cloud adapter is, not with every storage module.

Where is what goes with a module declared?

Beside what it needs, as recommends in its module.toml, which the core's goes_with() reads: a box goes with sandbox, Link Harness with memory-tool, web-tool and measure. lnk up takes a use's modules and what they need, never what goes with them, so a choice installs only what it names. The first command of a module whose companions aren't here offers them once, each on its own line with what it is. Link Harness's scheduler, run, file and code tools are in the agents choice beside it, so lnk up agents installs them with it.

How is a refusal remembered?

Where it was made: the tools an agent is offered, in that agent's settings; anything else, on this machine, in ~/.lnk/safe/modules/offers.toml. Neither is asked again; only the command that adds it (lnk agent tool add, lnk module add) does. A line said without a terminal isn't a refusal: a later start in a terminal still asks. Memory's embedding model is offered once, when memory is picked, and memory says it searches by words only without it.

Why is a harness's runtime asked about every time?

It's a large download (DeepSeek Harness's is about 800 MB), so even lnk agent harness set deepseek, which names it, asks first, saying what it downloads; without a terminal it downloads only with --yes.