1
+# LLM Guardrails
2
+
3
+## Decision
4
+
5
+Inject invisible guardrail instructions into every `.md` response so AI code generators use the correct Composio SDK patterns. Guardrails are scoped per-page via frontmatter — different pages can get different instruction sets.
6
+
7
+## Problem
8
+
9
+LLMs that crawl or receive Composio docs generate code using the old direct tool execution pattern (`composio.tools.get()`, `composio.provider.handle_tool_calls()`) instead of the current session-based pattern (`composio.create()`, `session.tools()`).
10
+
11
+## Architecture
12
+
13
+```
14
+lib/llm-guardrails/
15
+├── index.ts ← getGuardrails(type), module-private GuardrailType
16
+├── session.ts ← SESSION_GUARDRAILS constant (default)
17
+└── direct-execution.ts ← DIRECT_EXECUTION_GUARDRAILS constant
18
+```
19
+
20
+### How it flows
21
+
22
+1. `getLLMText()` in `lib/source.ts` reads `page.data.llmGuardrails` from frontmatter
23
+2. Passes it to `getGuardrails(type)` which returns the right guardrail string
24
+3. Appends it to the markdown output
25
+
26
+### Scoping via frontmatter
27
+
28
+Pages control which guardrails they get:
29
+
30
+| Frontmatter value | What gets appended |
31
+|---|---|
32
+| *(omitted — default)* | `SESSION_GUARDRAILS` — full "use composio.create() + session.tools()" instructions, ALWAYS/NEVER rules, deprecated patterns, verification checklist |
33
+| `llmGuardrails: "direct-execution"` | `DIRECT_EXECUTION_GUARDRAILS` — acknowledges direct execution is valid, but strongly recommends sessions unless user explicitly asks for it |
34
+| `llmGuardrails: "none"` | Nothing |
35
+
36
+The Zod schema in `source.config.ts` validates the field at build time — typos cause build failures.
37
+
38
+### Tagged pages (12 total)
39
+
40
+`tools-direct/` (8):
41
+- executing-tools, fetching-tools, authenticating-tools, custom-tools
42
+- toolkit-versioning
43
+- modify-tool-behavior/schema-modifiers, before-execution-modifiers, after-execution-modifiers
44
+
45
+`auth-configuration/` (4):
46
+- connected-accounts, custom-auth-configs, custom-auth-params, programmatic-auth-configs
47
+
48
+### Endpoint behavior
49
+
50
+| Endpoint | Guardrails behavior |
51
+|---|---|
52
+| `/:path*.md` (per-page) | Appended per page based on frontmatter |
53
+| `llms.txt` (index) | One-liner note at top pointing to session pattern |
54
+| `llms-full.txt` (all pages) | `SESSION_GUARDRAILS` once at the top, per-page guardrails disabled (`includeGuardrails: false`) to avoid 1148x repetition |
55
+| Copy Page button | Fetches `.md` endpoint, so guardrails are included automatically |
56
+
57
+### getLLMText options
58
+
59
+```typescript
60
+getLLMText(page, {
61
+ includeFooter?: boolean; // default true — nav links at bottom
62
+ includeGuardrails?: boolean; // default true — guardrail block
63
+})
64
+```
65
+
66
+`llms-full.txt` passes both as `false` and handles them at the route level instead.
67
+
68
+## Why this approach
69
+
70
+| Alternative | Why not |
71
+|---|---|
72
+| Per-page component/accordion | Requires adding to every page, new pages miss it |
73
+| URL-path matching in code | Implicit — moving a file breaks it silently |
74
+| Separate "Copy Prompt" button (Clerk-style) | Clashes with existing "Copy Page" button |
75
+| Guardrails in frontmatter content | Visible to humans on the site |
76
+
77
+Frontmatter tag + pipeline injection = zero visual impact, zero per-page maintenance, explicit opt-in for different behavior, build-time validation.
78
+
79
+## Adding a new guardrail set
80
+
81
+1. Create `lib/llm-guardrails/your-set.ts` exporting a string constant
82
+2. Add the enum value to `llmGuardrails` in `source.config.ts`
83
+3. Add a case to `getGuardrails()` in `lib/llm-guardrails/index.ts`
84
+4. Tag pages with `llmGuardrails: "your-set"` in frontmatter
85
+
86
+## Session guardrails content
87
+
88
+The default guardrails include:
89
+- Correct pattern code (Python + TypeScript)
90
+- Provider packages table (9 providers)
91
+- ALWAYS rules (4)
92
+- NEVER rules (4)
93
+- Deprecated patterns with markers
94
+- Verification checklist (5 items)
95
+
96
+## Direct execution guardrails content
97
+
98
+The softer guardrails include:
99
+- Note that this page documents the low-level API
100
+- Recommended session pattern code (Python + TypeScript)
101
+- "When to use direct execution" — only when user explicitly asks for it