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 -- --write

A 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 by link-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' layers rule and the repository checks' layer_words rule.
  • 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 by link-actions-build, and link-component, embedded by link-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 by link-actions-build.
  • A harness's variables (1 file): Every variable Link knows in a harness's .env, and what lnk agent migrate makes of it. Read by link-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-build embeds 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-check and link-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.

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.