Skip to content

Documentation Conventions

Reference: The canon every documentation page follows — vocabulary, story spine, and the AI-discovery contract.

At a glance

  • What — the rules that keep Mercury's docs consistent: canonical terminology, the narrative spine, and the machine-readable contract that lets an AI agent discover context without reading source.
  • Why it matters — the docs serve two readers at once: a human reading a story, and an AI agent resolving context fast and deterministically. One canon keeps both coherent as the docs evolve.
  • For anyone — human or AI — editing these docs. A CI drift check (scripts/check-doc-canon.py) enforces the mechanical parts.

Two readers, one canon

Every page is written for two audiences at once:

  1. Humans — the docs tell a story: why before how, a clear arc, engagement over exhaustiveness.
  2. AI agents — the docs are a context surface: structured metadata and deterministic specs let an agent find the right page and generate correct artifacts without drilling into engine source.

Canonical vocabulary

"Layers" means the three paradigm layers — nothing else

Mercury ascends three layers. Reserve the word layer for these:

Layer Express behavior as… You write
1 · Event-driven (Platform Core) decoupled functions reacting to events Java functions, addressed by route name
2 · Composable (Event Script) YAML flows that choreograph functions ~50% config, 50% code
3 · Semantic (Active Knowledge Graph) a graph whose nodes execute during traversal a model — little or no code

Describe the path a request takes from the caller through to the functions (see the Architecture Overview) as a pipeline; use layer only for the three paradigm layers above. (Don't frame the pipeline as a contrast with the layers — it just confuses a first-time reader.)

Layer-3 names

  • Active Knowledge Graph (AKG) — the thing (the model / the artifact).
  • Knowledge Graph as Application — the paradigm (the tagline for the idea).
  • MiniGraph — the engine (graph.executor, the in-memory property graph, the Playground).
  • semantic — an adjective only ("the semantic layer"); never a standalone noun for the thing.

One atom, four roles

There is one building block: the function — a @PreLoad class implementing LambdaFunction / TypedLambdaFunction, addressed only by its route name, with Map-or-PoJo I/O. What we call it depends on how it is wired:

Term A function that…
Function the atom — used at every layer
Service is mapped straight to an HTTP endpoint via service: in rest.yaml
Task is a step in an Event Script flow (carrying an execution type)
Skill is attached to an Active Knowledge Graph node via the node's skill: property

"Function" is the general atom; "service" is only the narrow REST role.

The story spine

Every page reinforces one arc:

  1. Origin (the why). The event-driven core descends from the Scala/Akka actor model, runs on the Eclipse Vert.x event bus, and uses Java 21 virtual threads so synchronous code performs like reactive — which is why functions are decoupled actors addressed by name.
  2. The ascent: code → configuration → knowledge. Each layer pushes more "how" out of imperative code: decouple functions → move orchestration into YAML flows → move behavior into a model you traverse.
  3. Cross-cutting: human–AI collaboration. Agent-ready DSL specs and the companion endpoint let humans and AI co-author across all three layers — a capability, not a fourth layer.

Voice: product narrative, present tense, why before how. Avoid analyst/whitepaper framing.

The AI-discovery contract

  • Every page carries YAML frontmatter (title, summary, layer, audience, keywords, optional related), an "At a glance" block, consistent headings with stable anchors, and a "See also" footer. URLs are lowercase-kebab semantic slugs. This is a clean rewrite — old URLs are intentionally not preserved (no redirects); the navigation is the source of truth.
  • llms.txt is the machine-readable site map, organized by layer, and is kept current — every guide page and DSL catalog carries an entry, enforced in CI (a page with no entry is unreachable by an agent following the map, which sends it into engine source instead).
  • The three DSLs (MiniGraph, Event Script, REST automation) each ship a deterministic spec kit: a grammar reference, a machine-readable catalog, an AI-agent guide, and a CI drift test. A claim that an agent can generate correct artifacts "from this page alone" belongs only to those agent guides, never to a concept page.

Enforcement

The mechanical rules are checked in CI by scripts/check-doc-canon.py — slugs, frontmatter, At-a-glance, no UTF-8 BOM, retired terminology, and llms.txt coverage — alongside the three DSL grammar drift checks.

See also