Connect recipe conventions

Connect recipe conventions

Every recipe in the Connect cookbook follows the same contract. This page records that contract so you know what to expect as a reader and what a recipe must satisfy as an author. It is descriptive: it records the convention. Enforcement lives in the nextpdf/server repository tooling and the documentation style override sheet, not here.

Authors write Connect recipes in the nextpdf/server repository under docs/public/, and the aggregator pulls them into this site. The conventions below apply wherever a Connect recipe lives.

1. Tool calls are transport-independent

A Connect recipe uses the same tool invocation across every transport.

• The recipe shows the tool call once. The same call drives the tool over the Model Context Protocol (tools/call), the Representational State Transfer (REST) tool endpoint, and the gRPC service, because all three share one tool executor.
• The authoritative argument schema for a tool is the one the running deployment returns from tools/list (MCP) or the service descriptor (gRPC). A recipe’s sample arguments show the call shape; they are not a frozen schema that the recipe redefines.
• A recipe never asserts a fixed total tool count. The catalog of record is the server’s own tool catalog, which the recipe links.

2. Tier-conditional tools are stated, not assumed

The server’s tool registry always registers core tools. It then probes for the Pro and Enterprise providers with class_exists() and registers their tools only when nextpdf/premium is installed alongside the server.

• A recipe that depends on a Pro or Enterprise tool states that tier dependency explicitly and tells you how to confirm that the tool is present on your deployment with a tools/list call.
• On a deployment where the tool does not resolve, the call returns an unknown-tool error. A recipe presents that result as the intended tier boundary, not a degradation, and never implies that a tier-gated tool is always available.

3. The risk model and the confirmation gate

Every tool declares one of four risk levels. The highest level, approval_required, does not run on the first call.

• A recipe whose tool can be approval_required (by design or by an operator override) documents the ConfirmationGate: the gate returns a single-use challenge token bound to the tool name, a nonce, and a 300-second time to live (TTL), not to the arguments. The caller re-invokes the same tool once with arguments._confirmation_token.
• A recipe states that a configuration override may only raise a tool’s risk level; it can never lower a tool that is approval_required by design. The gate behaves identically across transports.

4. Error handling separates transport from status

For a recipe that reaches a remote service over Hypertext Transfer Protocol (HTTP), a transport failure and a non-success HTTP status are distinct cases. A PSR-18 client raises a typed client exception only when it cannot send the request at all — PSR-18 §4; a 4xx or 5xx response is a normal return value that the recipe inspects, not an exception it catches. A production-ready Connect recipe handles both cases distinctly, with no empty catch block.

5. The conformance and certification boundary

A Connect recipe treats support for a standard as support, never as conformance or certification.

• The engine produces output intended to conform to a standard (PDF/UA-2, PDF/A-4, a PAdES level); conformance is determined against the standard’s requirements by an independent validator, not asserted by the producing software — PDF/A-4 §6.7.3.
• A readiness assessment is a readiness signal, not a certification. An attestation is not a legal guarantee. Long-term-validation material present in a document is a capability the document carries, not a guarantee of indefinite signature validity. It is an Enterprise-only capability distinct from the lower PAdES levels.
• Absolute conformance words are not used as engine claims. The lexical blocklist a recipe is checked against is, verbatim, the tokens “certified”, then “guaranteed”, then the two-word phrase “fully” + “compliant”, then “tamper-proof”, then “legally valid”: none may stand as an asserted property of NextPDF output, because conformance is decided by an independent validator against the standard’s requirements, not by the producing software — PDF/A-4 §6.7.3. A recipe that softens an upstream claim records the softening in its co-located downgraded-claims sidecar.

6. The publish gate

Every Connect recipe carries publish: false until it clears the Writing Gate. The default is deny: merging a page does not publish it; only an explicit gate decision recorded in front-matter does. A recipe whose normative citations could not be pinned because of a genuine compliance-engine outage also carries an unresolved-citation marker and stays publish: false until the citation re-pins. The repository’s Retrieval-Augmented Generation (RAG) infra-outage fallback protocol governs that marker; an author follows it rather than inventing a citation or dropping the claim.

7. The aggregator writes the provenance fields

A Connect recipe author does not hand-write the four source-provenance fields that the aggregator owns: source_repo, source_ref, source_hash, and manifest_hash. The aggregator fills them in when it pulls the recipe from nextpdf/server, so the published page records the exact revision that produced it. This index and this conventions page are docs-native, so their provenance fields are zero-filled by design and the aggregator does not overwrite them.

Summary

A Connect recipe has transport-independent tool calls, an explicitly stated tier dependency, the documented risk model and confirmation gate, error handling that separates transport from status, an honest conformance boundary, and a publish: false default until the Writing Gate. A page that meets all six is a recipe; a page that meets fewer is a draft.

See also

• Connect cookbook — the recipe slug map and the tier and transport boundary.
• Integration cookbook recipe conventions — the ecosystem-wide recipe contract this one specialises for Connect.