Surfaces

link-actions-surfaces writes every surface Link offers beside its command line from the catalog of every module's declarations, so the API, its typed client, agents' tools, and the references can never disagree about a command or a shape.

Generators

A module declares its commands in actions.toml, its shapes in types.toml and its environment variables in variables.toml. link-actions reads every module's files into one checked catalog, and each generator here reads that catalog and nothing else. A generator adds no behavior, so what a surface offers is what the declarations say.

Where an Action Is Offered

An action's surfaces field says where it is offered. A plumbing action is offered on the command line alone, so no generator here writes it. Core's --json flag shapes only what the command line prints, so the API, its client, and agents' tools leave it out. Core's --yes answers for a person what a command would ask, so agents' tools leave it out, and a model never says yes for the person. surfaces.toml lists both kinds.

One Module a Surface

Each generator is one module of this package.

  • openapi: the OpenAPI document.
  • typescript: TypeScript types and a typed client.
  • pages: a web page per action.
  • tools: agents' tool schemas.
  • reference: the command reference, spec references, and variable index.
  • completion: lnk's shell completion for bash and zsh.

OpenAPI Document

OpenAPI is the standard description of an HTTP API, read by client generators, documentation sites and test tools. Version 3.1 describes its shapes in JSON Schema 2020-12, the dialect the catalog renders, so the one translation the document needs is where its references point.

Paths and Components

Each action is a POST to /_link/<namespace>/<resource>/<verb>, and its operation ID is its action ID. Its runtime arguments are query parameters, its spec is the request body, and its output is the 200 response. Every shape is a component named <module>.<name>. An operation's x-link-command and x-link-role give its command and where help lists it, and each parameter's x-link-cli says how the command line takes it.

TypeScript

types.ts declares a type for every shape, named in PascalCase from its qualified name, so env.stage is EnvStage. It also declares each action's Args and Output. Two names that would read alike are refused, never renamed.

Typed Client

client.ts exports client(send), whose methods follow the action IDs, as client(send).env.approval.add(args). Each method passes its call to send, a transport its caller gives it, and holds no behavior of its own.

Action Pages

The page per action is a route at <namespace>/<resource>/<verb>.tsx. Each renders one component, which the caller names, with its action ID, so the page holds nothing else. The component finds everything about the action in its operation in the OpenAPI document.

Agents' Tools

A tool is an action a model may call. Its name is the action ID with _ between the words, as env_approval_add, since tool names allow no dot. Its description is the action's, and its input is one JSON Schema object holding the runtime arguments and, under spec, the spec. Every shape the input reaches is under the input's $defs, so each tool stands alone. No x-link-* keyword is left in an input, so a model's provider never sees one. tools.json holds every such tool.

Refused Tools

A name longer than surfaces.toml's limit of 64 characters is refused, and so is an action with a runtime argument named spec, since its tool holds the spec under that name.

Tool Programs

A module whose program serves its own MCP calls, an agent's tool, gives each a tool table, whose name a model calls in place of the joined ID. Only its program offers those calls, so tools.json leaves them out: tools::template renders them, each input as a tool's, and the program gives them, so one source names each call. Each call carries the arguments its title shows, the choices and text its program fills, and the condition it's offered on, for link_actions::tools::offer to fill at runtime and give as tools/list with the title's arguments in _meta link.local/summary.

References

Each module's command reference is at docs/more/reference/modules/<domain>/<module>.md in its own folder, its domain the folder after modules or adapters, as tooling for modules/tooling/bundle. It lists every command the module offers, in order of its resource, with its usage, its runtime arguments, the spec it reads, and what it answers. An argument kept out of help (hidden) is kept out of its usage and arguments too.

Hubs

The workspace's hub, docs/more/reference/modules.md, links a page for each domain, docs/more/reference/modules/<domain>.md, which links that domain's modules. The hub's pages stay few as modules grow, within the docs' limit on pages under one page. A domain with fewer modules than the docs allow a group, three, has no hub of its own: the workspace's hub links its modules directly.

Spec Pages

Each spec kind's page is at docs/config/specs/<kind>.md, beside its JSON Schema. It opens with the commands a person gives the spec to: those on the command line, never plumbing, of the page's own workspace. The page lists every field by its key path, with its field flag where it has one. Each flag is the one the command line's parser, link-spec, derives from the same JSON Schema, so the page and the command line can't disagree. A table has no flag of its own, but each value inside it does, as --server.port, and a map's values do by their key, as --variables.<name>.

Variable Index

The workspace's variable index lists every variable a module defines, with its type, its default, and its meaning. A runtime flag that reads one when it is absent says so in its command's reference.

One Page Each

Each reference is one page, however long: a module's commands, a spec kind's fields, and the variable index. A reader looks an entry up by its heading, on the website or in GitHub's outline, so a page is never split to fit a length. The docs' limits on lines and headings hold every page a person writes, and tests/docs/limits.toml exempts these. A module whose commands act on several resources has a heading for each resource and its commands beneath, so the page's outline is the module's resources.

Shell Completion

The completion generator writes lnk's bash and zsh scripts into the workspace's scripts/completion/, for the workspace holding core. Each script holds a table of the words a person may type after each command so far, from every action offered on the command line but plumbing, and a function the shell runs on Tab that walks it. A command's runtime flags come from its arguments, an enumerated one completing its values, and its field flags from its bound spec through link_spec::fields, the list its help prints. Where to put each is on Shell Completion.

Freshness

A generated file, such as the OpenAPI document or a page of the docs, is written by its generator and checked in. Every generated file carries the line surfaces.toml names as the marker. Files::problems reports a file that is absent, stale, or edited by hand. It also reports a file a person wrote where a generated one goes, and a generated file in a generator's folder that nothing writes any more. Files::write writes the absent and stale files, removes the orphans, and refuses to overwrite a file a person wrote.

Generated Files

A file is generated only if it carries the marker on its first line, or as its top-level x-link-generator in JSON, so a person's page quoting the marker is never removed. Each module's command and spec folders are the generators' own, so a page whose kind was renamed or whose commands are gone is found and removed.

Modules Read

modules::discover finds the modules a workspace's checks generate from: each member of its Cargo workspace whose folder holds a module.toml, except the members a held list names. The public docs check holds the references fresh, and lnk-docs-inventories --write writes them.