# 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 checks | **rule** / **rules** | contracts, policies, guards, checks |
| What Edictum does to tool calls | **enforces rules** | governs, guards, protects, secures, enforces contracts |
| When a rule blocks a call | **blocked** / **block** | denied, rejected, prevented, stopped |
| When a rule allows a call | **allowed** / **allow** | passed, approved, permitted |
| The runtime check sequence | **pipeline** | engine, evaluator, processor, middleware |
| The sequence: check -> execute -> check_output -> 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 check_output rules | **violation** / **violations** | findings, result, detection, alert |
| The YAML file containing rules | **ruleset** | contract bundle, policy file, rule file, config |
| What Edictum IS | **runtime rule enforcement for agent tool calls** | governance framework, safety library, guardrails |

Note: `Finding` (the class name) and `findings.py` (the module name) are valid code symbols in the Python SDK. The ban on finding/findings applies to prose and user-facing terminology, not existing code identifiers.

## Terminology Migration Reference

These terms were renamed in M1 (v2 schema). This is a clean break — old terms are rejected, not deprecated.

| Old Term (deprecated) | New Term |
|----------------------|----------|
| `contracts:` | `rules:` |
| `effect:` | `action:` |
| `timeout_effect` | `timeout_action` |
| `deny` (as action value) | `block` |
| `approve` (as action value) | `ask` |
| `preconditions:` | `check:` |
| `postconditions:` | `check_output:` |
| `kind: ContractBundle` | `kind: Ruleset` |
| `ToolEnvelope` (class) | `ToolCall` |
| `Verdict` (class) | `Decision` |
| `ContractResult` (class) | `RuleResult` |
| `GovernancePipeline` (class) | `CheckPipeline` |
| `findings` | `violations` |
| `contract bundle` (prose) | `ruleset` |

## The One-Liner

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

> Edictum enforces rules on AI agent tool calls — checks before execution, sandbox allowlists for file paths and commands, output checks after, session limits across turns, and a full audit trail. Rules 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 rules. 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 rules are code, not suggestions. The LLM cannot talk its way past a rule.

## Pipeline Description (USE THIS CONSISTENTLY)

When describing what happens on every tool call:

1. Agent decides to call a tool
2. Edictum evaluates **checks** against the call's arguments and principal
3. If any check fails: **block** (call never executes)
4. Edictum evaluates **sandbox rules** against allowlist boundaries (file paths, commands, domains)
5. If the call falls outside any sandbox boundary: **block** or **pending_approval** (depending on `outside` setting)
6. If all pass: tool executes
7. Edictum evaluates **output checks** against the tool's output
8. Output check failures produce **violations**. With `action: warn`, the tool result is unchanged. With `action: redact` or `action: block`, the pipeline modifies the output for READ/PURE tools (WRITE/IRREVERSIBLE tools fall back to warn)
9. **Audit event** is emitted for every evaluation (allowed, blocked, or observed)

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

## 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 (rules 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. **When to use this**: Concrete scenarios where this feature applies — real situations a user would recognize (e.g., "Your fintech agent needs to limit daily transaction approvals" not "This feature provides configurable limits"). Include:
   - 2-4 concrete scenarios with brief descriptions
   - Which user persona benefits (developer debugging vs. platform team in production)
   - How this relates to other Edictum features (e.g., "Use callbacks for immediate reactions, OTel for historical dashboards")
4. **Explanation**: How it works, why it matters
5. **Reference**: Full details, edge cases, configuration
6. **Next steps**: Links to related pages

## Cross-Reference Conventions

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