genlayerlabs · MuncleUscles · May 20, 2026 · May 20, 2026
diff --git a/pages/developers/intelligent-contracts/_meta.json b/pages/developers/intelligent-contracts/_meta.json
@@ -1,5 +1,6 @@
 {
   "introduction": "Introduction to Intelligent Contracts",
+  "when-to-use-genlayer": "When to Use GenLayer",
   "features": "Feature List",
   "tooling-setup": "Development Setup",
   "first-contract": "Your First Contract",

diff --git a/pages/developers/intelligent-contracts/equivalence-principle.mdx b/pages/developers/intelligent-contracts/equivalence-principle.mdx
@@ -45,6 +45,10 @@ def validator_fn(leader_result) -> bool:
 
 The leader's result is only accepted if a majority of validators agree. If the majority rejects, the network rotates to a different leader and retries. If consensus still can't be reached, the transaction goes **undetermined** — it does not modify contract state.
 
+<Callout type="info">
+  **What gets stored?** The accepted leader result is the value your contract receives and can store. Validators verify or reject that leader result; their independent intermediate answers are not automatically persisted on-chain. If your application needs to expose multiple perspectives, make those perspectives explicit fields in the leader result and write validator logic that checks them.
+</Callout>
+
 ```mermaid
 graph TD
     subgraph "Step 1: Leader"

diff --git a/pages/developers/intelligent-contracts/examples/fetch-web-content.mdx b/pages/developers/intelligent-contracts/examples/fetch-web-content.mdx
@@ -104,6 +104,8 @@ You can monitor the contract's behavior through transaction logs, which will sho
 
 The `gl.nondet.web.get()` function supports different modes for retrieving web content. While the default mode returns the plain text content, `gl.nondet.web.render()` with `mode="html"` allows you to retrieve the complete HTML `<body>` of the webpage.
 
+Use `render` instead of `get` when the page needs a browser to execute JavaScript, load dynamic content, or render the DOM before your contract extracts data.
+
 Here's an example of using HTML mode:
 
 ```python
@@ -141,4 +143,26 @@ class FetchHTMLContent(gl.Contract):
 3. When analyzing page structure or links
 4. If you need to process structured data like tables or forms
 
+### Waiting for Dynamic Pages
+
+Some pages finish the initial load before the data you need appears. For JavaScript-heavy sites, pass `wait_after_loaded` so the browser waits briefly after the page load event before returning content:
+
+```python
+def fetch_rendered_text() -> str:
+    return gl.nondet.web.render(
+        "https://example.com/dynamic-page",
+        mode="text",
+        wait_after_loaded="5s",
+    )
+```
+
+Use this sparingly:
+
+- Prefer `gl.nondet.web.get()` for stable APIs and static pages.
+- Use `render(..., mode="text")` when you only need readable page text.
+- Use `render(..., mode="html")` when you need DOM structure, attributes, links, or tables.
+- Keep waits short and extract stable structured fields before returning data from the non-deterministic block.
+
+Dynamic pages can still vary between validators. If the raw page content is unstable, extract the specific facts you need and validate only those fields in your equivalence logic.
+
 This addition provides users with a clear understanding of the HTML mode option and its specific use cases, complementing the existing text mode example.
diff --git a/pages/developers/intelligent-contracts/when-to-use-genlayer.mdx b/pages/developers/intelligent-contracts/when-to-use-genlayer.mdx
@@ -0,0 +1,118 @@
+# When to Use GenLayer
+
+GenLayer is most useful when your application needs a **shared, on-chain decision** about something a normal deterministic smart contract cannot evaluate by itself.
+
+Use GenLayer when the decision depends on evidence, language, or judgment — and when different parties need to trust the result without relying on a single backend, oracle, or operator.
+
+## Quick Fit Checklist
+
+A feature is usually a good fit for GenLayer if most of these are true:
+
+- **There is a real on-chain consequence**: payout, escrow release, market resolution, reputation update, rule enforcement, or another state change.
+- **The outcome requires judgment**: interpreting evidence, applying natural-language rules, evaluating quality, or resolving ambiguity.
+- **The evidence can be independently checked**: validators can fetch the same source material or enough comparable evidence to verify the leader's result.
+- **The decision benefits from neutral consensus**: counterparties should not have to trust your centralized backend or one AI provider.
+- **The result can be made explicit**: your contract can return a structured decision such as `accepted`, `winner`, `score`, `amount`, or `reason`.
+
+If your feature is mostly personalization, summarization, chat, analytics, routing, or UX assistance with no consensus-critical state change, it is usually better handled by a normal backend or frontend LLM.
+
+## Architecture Pattern
+
+A common GenLayer app has three layers:
+
+1. **Frontend or backend**: collects user intent, displays data, handles indexing, and may prepare URLs or evidence.
+2. **Intelligent Contract**: owns the consensus-critical decision and any on-chain state transition.
+3. **GenLayer validators**: independently verify the leader's result using the evidence and equivalence principle you define.
+
+The key question is:
+
+> What decision must not depend on my server alone?
+
+That decision is the part that belongs in the Intelligent Contract.
+
+## Good Fits
+
+### Prediction or resolution markets
+
+Good fit when the contract resolves a market by checking source evidence and applying listing or resolution rules.
+
+- Frontend: shows the market, lets users trade, links evidence.
+- Intelligent Contract: determines the outcome from trusted sources and settles the market.
+- Validators: verify that the outcome follows the evidence and rules.
+
+### Dispute or milestone workflows
+
+Good fit when parties agree up front that a contract should evaluate whether a deliverable, task, or condition was satisfied.
+
+- Frontend/backend: stores submissions, attachments, and communication context.
+- Intelligent Contract: evaluates the evidence against agreed criteria and releases funds or updates status.
+- Validators: verify that the accepted result is reasonable given the evidence.
+
+### Rule or policy verification
+
+Good fit when a decision depends on natural-language criteria.
+
+Examples:
+
+- Does a proposal comply with a DAO constitution?
+- Does a submitted work item meet bounty rules?
+- Does a listing meet market guidelines?
+- Does a claim satisfy policy conditions?
+
+## Weak Fits and Anti-Patterns
+
+### Frontend computes the answer, GenLayer only stores it
+
+If your frontend fetches data, asks an LLM for the answer, and sends the finished result to GenLayer for storage, GenLayer is not adding much trust.
+
+Better pattern: send the contract stable evidence references or inputs, then let the Intelligent Contract perform the consensus-critical evaluation.
+
+### Generic AI brain
+
+If GenLayer is only being used as an AI assistant, recommender, chatbot, or analytics engine, a normal backend is usually simpler and cheaper.
+
+Better pattern: use off-chain AI for UX and exploration, then use GenLayer only for the part where users need neutral settlement or verifiable judgment.
+
+### Private data that validators cannot verify
+
+If validators cannot access enough evidence to independently check the leader result, consensus becomes weak or impossible.
+
+Better pattern: commit to public evidence, signed attestations, hashes, URLs, or other verifiable inputs that validators can inspect.
+
+### Unbounded subjective output
+
+If the contract asks for open-ended text with no structured decision fields, validators may disagree even when they are all reasonable.
+
+Better pattern: return structured fields and compare only the parts that matter. See the [Equivalence Principle](/developers/intelligent-contracts/equivalence-principle).
+
+## What Belongs Where
+
+- **Frontend**: UX, forms, wallets, previews, charts, indexing, user guidance.
+- **Backend**: caching, notifications, search, off-chain analytics, non-critical LLM assistance.
+- **Intelligent Contract**: the decision that moves money, resolves a market, updates reputation, enforces rules, or creates another shared state transition.
+- **Evidence sources**: stable URLs, APIs, signed data, user submissions, or other material validators can fetch or evaluate.
+
+## Dispute Resolution Is Not a Court
+
+GenLayer can support agreed dispute-resolution workflows, but it does not automatically make a decision legally binding or replace a court.
+
+Use safer framing such as:
+
+- evidence-based settlement workflow
+- agreed arbitration primitive
+- contractual dispute-resolution mechanism
+- milestone or deliverable adjudication
+
+Avoid implying that an Intelligent Contract is a legal judge unless your application has the legal agreements, jurisdiction, and review process to support that claim.
+
+## Design Prompt
+
+Before building, answer these questions:
+
+1. What exact decision should GenLayer make?
+2. What state changes if the decision is accepted?
+3. What evidence will validators use to verify it?
+4. Which fields must validators agree on exactly, and which can vary?
+5. What happens if validators reject the leader result or the transaction becomes undetermined?
+
+If the answers are clear, the feature is probably a good candidate for GenLayer. If not, start by moving more logic off-chain or narrowing the on-chain decision.
diff --git a/pages/understand-genlayer-protocol/typical-use-cases.mdx b/pages/understand-genlayer-protocol/typical-use-cases.mdx
@@ -2,6 +2,8 @@
 
 GenLayer is built for commitments where outcomes depend on judgment — evaluating evidence, interpreting language, or assessing quality — and where a deterministic smart contract alone cannot resolve them.
 
+If you are deciding whether a feature belongs on GenLayer or in a normal backend, start with the [builder fit checklist](/developers/intelligent-contracts/when-to-use-genlayer).
+
 The use cases below are grouped by where the need for adjudication is most acute today.
 
 ## 1. Performance & Milestone Adjudication
@@ -17,6 +19,8 @@ Payments, rewards, or recognition that depend on whether some obligation was act
 - **Freelance and gig work** — was the deliverable satisfactory? AI consensus replaces subjective back-and-forth
 - **Chargebacks** — buyer/seller disputes resolved by analyzing shipping records, communication logs, and transaction history
 
+GenLayer can support agreed dispute-resolution workflows, but it is not a court and does not automatically make a result legally binding. For legal or contractual use cases, parties still need the appropriate agreements, jurisdiction, and escalation process around the Intelligent Contract.
+
 ## 2. Adjudication Inside the Agentic-Commerce Stack
 
 GenLayer plugs into the infrastructure the industry is building right now: payment rails ([x402](https://www.x402.org/)), agent identity and reputation ([ERC-8004](https://eips.ethereum.org/EIPS/eip-8004)), agent-to-agent task exchange ([A2A](https://a2a-protocol.org)), plus Stripe/OpenAI's ACP, Visa's Trusted Agent Protocol, Google's AP2, and Mastercard's Agent Pay. Each standard ships the happy path and carves the moment of disagreement out as someone else's problem. GenLayer is that someone else.