# Edictum Docs Style & Terminology Guide

This is the binding reference for all documentation writers. Every page must use these terms consistently.

## Canonical Terms (USE THESE, NOT THE ALTERNATIVES)

| Concept | Canonical Term | DO NOT USE |
|---------|---------------|------------|
| The YAML constructs that define rules | **contract** / **contracts** | policies, rules, guards, checks |
| What Edictum does to tool calls | **enforces contracts** | governs, guards, protects, secures |
| When a contract blocks a call | **denied** / **deny** | blocked, rejected, prevented, stopped |
| When a contract allows a call | **allowed** / **allow** | passed, approved, permitted |
| The runtime check sequence | **pipeline** | engine, evaluator, processor, middleware |
| The sequence: preconditions -> execute -> postconditions -> audit | **pipeline** (describe the steps, don't rename them) | workflow, chain, flow |
| What agents do that Edictum checks | **tool call** / **tool calls** | function call, action, operation, invocation |
| The thin framework-specific integration layer | **adapter** / **adapters** | integration, plugin, connector, driver |
| Shadow-testing without blocking | **observe mode** | shadow mode, dry run, passive mode, monitor mode |
| The identity context on a tool call | **principal** | user, identity, caller, actor |
| The structured output from postconditions | **finding** / **findings** | result, detection, alert, violation |
| The YAML file containing contracts | **contract bundle** | policy file, rule file, config |
| What Edictum IS | **runtime contract enforcement for agent tool calls** | governance framework, safety library, guardrails |

## The One-Liner

Use this exact framing (or close paraphrase) when describing what Edictum is:

> Edictum enforces contracts on AI agent tool calls -- preconditions before execution, postconditions after, session limits across turns, and a full audit trail. Contracts are YAML. Enforcement is deterministic. The agent cannot bypass it.

## The Core Metaphor

Edictum sits at the **decision-to-action seam**. The agent decides to call a tool. Before that call executes, Edictum checks it against contracts. This is a hard boundary, not a suggestion.

DO NOT use metaphors like: gatekeeper, guardian, shield, firewall, sentinel, watchdog.
DO use: "hard boundary," "enforcement point," "the check between decision and action."

## Writing Rules

1. **Lead with the problem, then the solution.** Not "Edictum has X" but "Agents do Y bad thing. Edictum prevents this by..."
2. **Show, don't describe.** Every concept page: working example within the first screen.
3. **No marketing language.** No "powerful," "seamless," "revolutionary," "robust," "elegant." Just say what it does.
4. **Short paragraphs.** 2-3 sentences max.
5. **Code examples must be copy-pasteable.** If it doesn't work when pasted, delete it.
6. **Deterministic, not probabilistic.** Emphasize that contracts are code, not suggestions. The LLM cannot talk its way past a contract.

## Pipeline Description (USE THIS CONSISTENTLY)

When describing what happens on every tool call:

1. Agent decides to call a tool
2. Edictum evaluates **preconditions** against the call's arguments and principal
3. If any precondition fails: **deny** (call never executes)
4. If all pass: tool executes
5. Edictum evaluates **postconditions** against the tool's output
6. Postcondition failures produce **findings**. With `effect: warn`, the tool result is unchanged. With `effect: redact` or `effect: deny`, the pipeline modifies the output for READ/PURE tools (WRITE/IRREVERSIBLE tools fall back to warn)
7. **Audit event** is emitted for every evaluation (allowed, denied, or observed)

Session limits (max calls, per-tool caps, attempt limits) are checked as part of step 2.

## What Edictum is NOT (be honest about these)

- NOT prompt engineering or input guardrails (those filter what goes INTO the LLM)
- NOT output content filtering (that filters what comes OUT of the LLM)
- NOT an authentication/authorization system (it accepts a Principal but doesn't authenticate)
- NOT ML-based detection (contracts are deterministic pattern matching)
- NOT a proxy or network-level tool (it's an in-process library)

## Page Structure Pattern

Every page should follow:

1. **Opening**: 1-2 sentences stating the problem this page addresses
2. **Example**: Working code/YAML within the first visible screen
3. **Explanation**: How it works, why it matters
4. **Reference**: Full details, edge cases, configuration
5. **Next steps**: Links to related pages

## Cross-Reference Conventions

- Link to concepts pages for explanations: `[contracts](../concepts/contracts.md)`
- Link to reference pages for syntax: `[YAML reference](../contracts/yaml-reference.md)`
- Link to adapter pages by name: `[LangChain adapter](../adapters/langchain.md)`
- Always use relative paths for internal links
