Repository Files
What each recurring file in the repository is, who reads it and who edits it, so a contributor can tell a declaration from generated data.
Reading a File's Header
Component declarations (module.toml) and layer declarations
(layer.toml) open with a generated header. It says what the file is,
its author, its copyright and license as SPDX tags, and the section of
this page that explains it. Everything below the header is authored by
hand, and the header never changes it.
# Local Link repository metadata: declares this component and its requirements.
# Author: Local Link Company
# SPDX-FileCopyrightText: 2026 Local Link Company
# SPDX-License-Identifier: MIT OR Apache-2.0
# Reference: ../../../docs/more/developing/repository-files.md#component
# Header maintained by lnk-docs-inventories; the declaration below is authored here.Writing the Headers
The headers and the lists on this page come from one catalogue of file
kinds, tests/docs/code/files.toml. After adding a file or changing the
catalogue, write them again, then let the docs checks confirm nothing
is stale.
cargo run -p link-docs-check-code --bin lnk-docs-inventories -- --writeA second write changes nothing. A missing or stale header, and a TOML
file no kind in the catalogue matches, fail the docs checks' files
rule. The license comes from the Cargo package that owns the file, or
the workspace's for a layer.
Authorship and License
Every package names Local Link Company as its author by inheriting the
workspace's authors, with authors.workspace = true. Its license is
MIT OR Apache-2.0, declared once in [workspace.package] and inherited
the same way, and the full texts are LICENSE-MIT and LICENSE-APACHE.
The copyright holder and years every header carries are
[workspace.metadata.link.copyright] in the workspace's Cargo.toml.
Third-Party Material
Dependencies keep their own licenses, which the dependency checks
review: Rust crates through Cargo.lock and the website's packages
through its lock file. A header is never added to a third-party file,
and an existing notice is never replaced.
File Kinds
Each kind below is one entry of the catalogue, with how many files of it the workspace holds. A file is of the first kind that matches it.
- Cargo.toml (121 files): A package's or the workspace's Cargo metadata: its name, author, license, dependencies and Link's own
[package.metadata.link]. Read by Cargo, and the repository and docs checks. - Cargo.lock (1 file): The workspace's locked dependency versions, written by Cargo. Read by Cargo, and the dependency checks.
- module.toml (62 files): A module's component declaration: its id, kind, menu, removal, dependencies and requirements. Read by
link-component, embedded bylink-component-build. - layer.toml (11 files): A group folder's layer: the group folders it is built on, and the words it introduces. Read by the docs checks'
layersrule and the repository checks'layer_wordsrule. - actions.toml (54 files): A program's commands: each action keyed by its ID, its runtime arguments, bound spec and output. Read by
link-actions, generated bylink-actions-build, andlink-component, embedded bylink-component-build. - types.toml (44 files): A module's shapes, its spec kinds and outputs among them, each named once in JSON Schema's terms. Read by
link-actions, generated into Rust bylink-actions-build. - A harness's variables (1 file): Every variable Link knows in a harness's
.env, and whatlnk agent migratemakes of it. Read bylink-agent. - variables.toml (60 files): The environment variables a crate defines, each once, and every one it reads, sets, removes, or hands a child, with its namespaces and reader functions. Read by
link-actions;link-component-buildembeds a module's definitions as its program's inputs. - rust-toolchain.toml (1 file): The compiler and components the workspace builds with. Read by rustup.
- .cargo/config.toml (1 file): Cargo's settings for this workspace, such as the test threads. Read by Cargo.
- clippy.toml (1 file): Clippy's settings, such as the methods a test may not call. Read by Clippy.
- Spec cases (179 files): One case of a spec each: the spec as a user writes it and what must come of it. Read by each spec's owning crate's tests, and the docs code checks.
- Repository policy (22 files): The repository and docs checks' lists and limits: approved exceptions, which may only shrink. Read by
link-docs-checkandlink-repository-check. - Test inputs (26 files): What a package's tests read: cases, fixtures and expected results. Read by the owning package's tests.
- Release inputs (1 file): What sealing a release reads, such as accepted advisories. Read by
link-bundle. - Owned values (247 files): A package's own values, defaults, schemas and pins, read once into a type and checked by a test. Read by the owning package.
Component
A module.toml beside a module's Cargo.toml declares the module: its
id under [module], whose program is lnk-<id>, its kind, menu,
removal, dependencies and requirements, and whether its commands read
control (reads-control, true unless it says otherwise, as File
Security
explains). Adding a
module walks through one, and
link-component-build embeds it in the module's program.
Layer
A layer.toml in a group folder (packages/, core/, each domain's
modules/ and interop/) lists the group folders it is built on.
A crate depends only on its own group's crates or a listed group's, and
the docs checks' layers rule refuses a cycle.
Its optional words are the concepts its layer introduces, which no
file of a layer it is built on says, as the repository checks'
Layer words
rule holds.
Commands
An actions.toml beside a program declares its commands, each action
by its ID with its help, runtime arguments, bound spec and output, and
types.toml declares the shapes they take. The program's parser is
generated from them, and Modules explains
both.
Owned Values
A value someone may want to read or change, such as a default, a limit,
a pin or a schema, is a TOML file beside the code that reads it. The
code reads it once into a type, and a test checks it. A file named
defaults.toml or schema.toml means only what its own package says.
Build Scripts
A build.rs at a package's root is the package's Cargo build script,
which Cargo runs before compiling it. Most embed the module's component
declaration and owned pages through
Component Build,
writing component.json to OUT_DIR. The CLI's also builds the module
registry, the manual's collects the shared docs, and the API's generates
Rust types from its schema.
Which Packages Have One
Cargo finds a build script as package.build names it, else as
build.rs at the package's root, unless build = false. This list
follows that rule. A build.rs anywhere else, such as a VM fixture's
src/fixture/build.rs, is an ordinary module.
core/cliinterop/agents/connections/discordinterop/agents/connections/signalinterop/agents/connections/slackinterop/agents/connections/telegraminterop/agents/harnesses/deepseekinterop/agents/harnesses/hermesinterop/agents/harnesses/openclawinterop/cloud/awsinterop/cloud/gcpmodules/agents/agentmodules/agents/agent/contract/placemodules/agents/agent/contract/specmodules/agents/connections/contractmodules/agents/connections/contract/policymodules/agents/connections/webhookmodules/agents/harnesses/linkmodules/agents/harnesses/minimodules/agents/harnesses/portability/agent-state-protocolmodules/agents/harnesses/portability/contractmodules/agents/harnesses/portability/contract/wiremodules/agents/modelmodules/agents/model/contractmodules/agents/stores/bucket-storemodules/agents/stores/contractmodules/agents/stores/file-storemodules/agents/stores/sqlite-storemodules/agents/tools/browser-toolmodules/agents/tools/browser-tool/contractmodules/agents/tools/code-toolmodules/agents/tools/code-tool/contractmodules/agents/tools/desktop-toolmodules/agents/tools/desktop-tool/contractmodules/agents/tools/file-toolmodules/agents/tools/file-tool/contractmodules/agents/tools/memory-toolmodules/agents/tools/memory-tool/contractmodules/agents/tools/memory-tool/document-convertermodules/agents/tools/memory-tool/document-converter/contractmodules/agents/tools/run-toolmodules/agents/tools/run-tool/contractmodules/agents/tools/scheduler-toolmodules/agents/tools/scheduler-tool/contractmodules/agents/tools/web-toolmodules/agents/tools/web-tool/contractmodules/cloud/cloudmodules/cloud/cloud/contractmodules/compute/boxmodules/compute/envmodules/compute/env/contractmodules/security/sandboxmodules/security/sandbox/contractmodules/security/sandbox/contract/clientmodules/security/secretmodules/storage/storagemodules/tooling/archivemodules/tooling/bundlemodules/tooling/manmodules/tooling/mcpmodules/tooling/measuremodules/tooling/specpackages/apipackages/interactions/contractpackages/policypackages/typestests/fixtures/agent-placetests/fixtures/connectiontests/fixtures/declarations
Lowercase Names
Link's own declarations are module.toml and layer.toml, lowercase,
while Cargo.toml keeps the spelling Cargo requires. No reader accepts
another case, so a file named otherwise is not read.