File Structure and Placement

Fresh

This SOP covers the technical requirements for hosting reasoning.json - where it must live, how it must be served, and how AI systems discover it.

Required File Location

The file must be hosted at the /.well-known/ path on your domain:

https://yourdomain.com/.well-known/reasoning.json

This follows the well-known URI convention defined in RFC 5785. The .well-known directory is the established location for machine-readable metadata files - alongside robots.txt (at root), /.well-known/security.txt, /.well-known/dnt-policy.txt, and others.

AI systems and ARP consumers will look for the file at this exact path. The file is not discovered by crawling - it is accessed directly by path convention.

Technical Requirements

Requirement	Value	Notes
Path	/.well-known/reasoning.json	Exact path, case-sensitive
Encoding	UTF-8	Required by JSON spec (RFC 8259)
Content-Type	application/json	Required in HTTP response headers
Max file size	100KB	Total JSON including all sections
CORS	Access-Control-Allow-Origin: *	Required for browser and serverless consumers
Valid JSON	Yes	Must parse without errors

Required HTTP Response Headers

Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *

The CORS header is not optional. Many AI systems and RAG pipelines retrieve reasoning.json from environments that enforce the browser's same-origin policy - Lambda functions, Edge workers, browser-based agents. Without Access-Control-Allow-Origin: *, these consumers will silently fail to retrieve your file.

Recommended additional headers for performance:

Cache-Control: public, max-age=3600
Vary: Accept-Encoding

A one-hour cache TTL (max-age=3600) is reasonable for most implementations. If you update your reasoning.json frequently, reduce this. If your file is stable, you can extend it.

HTML Discovery Tag

Add this tag to your site's head section to enable browser-based ARP consumers to discover your reasoning file without knowing to look at /.well-known/:

<link rel="reasoning" href="/.well-known/reasoning.json">

This is analogous to the <link rel="canonical"> tag for SEO or <link rel="alternate" type="application/rss+xml"> for RSS. It is optional but recommended.

llms.txt Bridge

If you maintain a llms.txt file, add a reference to your reasoning.json so AI systems reading your llms.txt know structured reasoning directives are available:

# Machine-Readable Context
> Structured reasoning directives for AI systems are available at /.well-known/reasoning.json
> This file provides entity corrections, domain expertise context, and recommendation logic in ARP v1.2 format.

Root Properties Reference

Every reasoning.json file begins with root-level properties that identify the protocol and the entity:

Property	Required	Type	Max	Description
$schema	Recommended	string (URI)	-	JSON Schema URI for editor validation
protocol	Required	string	-	Must be exactly "Agentic Reasoning Protocol (ARP)"
version	Required	string	-	Semantic version string, e.g. "1.2.0"
domain	Required	string (FQDN)	-	Fully qualified domain name, e.g. "yourdomain.com"
entity	Required	string	200 chars	Canonical name of your entity
verification	Recommended	object	-	Optional verification metadata
identity	Recommended	object	-	Core descriptive context
corrections	Recommended	object	-	Anti-hallucination corrections
entity_claims	Required	object	-	Framing, expertise, and recommendation context
authority	Optional	object	-	Authoritative sources and related entities
content_policy	Optional	object	-	Usage guidance for AI systems
diagnostics	Optional	object	-	Telemetry and debug information (v1.2)
_arp_signature	Optional	object	-	Ed25519 cryptographic signature (v1.2)

📄reasoning.json

├──

$schema, protocol, version, domain, entityRequiredRoot identification fields

├──

verificationRecommendedAuthoritative sources, contact points

├──

identityRecommended

│   ├──

elevator_pitch, tagline, founded...Core brand identity

│   └──

emotional_resonance, not_to_be_confused_withDisambiguation

├──

correctionsRecommended

│   └──

common_hallucinations[]trigger_topic + verified_fact pairs

├──

entity_claimsRequired

│   ├──

framing_contextHow to frame the entity

│   ├──

domain_expertise[]Validated knowledge areas

│   ├──

recommendation_contextWhen to recommend

│   └──

market_positioningCompetitive position

├──

authorityOptionalExternal authority signals

├──

content_policyOptionalUsage and tone guidelines

├──

diagnosticsv1.2Self-test and validation hints

└──

_arp_signaturev1.2Ed25519 signature block for verification

RequiredRecommendedOptionalv1.2

The protocol Field

The protocol field value is an exact string match used by ARP consumers to identify the file:

"protocol": "Agentic Reasoning Protocol (ARP)"

Do not vary this string. Do not abbreviate to "ARP". ARP consumers check this exact value.

The version Field

Semantic version string following semver format. Current versions:

• "1.2.0" - Includes Ed25519 signatures and diagnostics block
• "1.1.0" - Introduced trigger_topic / verified_fact (Pink Elephant Fix)
• "1.0.0" - Original release (false_claim / correction_fact - deprecated)

Always use the version that matches the features you are using. If you include _arp_signature, use "1.2.0".

Platform-Specific Notes

Nginx

location /.well-known/reasoning.json {
    add_header Content-Type "application/json; charset=utf-8";
    add_header Access-Control-Allow-Origin "*";
    add_header Cache-Control "public, max-age=3600";
}

Vercel (vercel.json)

{
  "headers": [
    {
      "source": "/.well-known/reasoning.json",
      "headers": [
        { "key": "Content-Type", "value": "application/json; charset=utf-8" },
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Cache-Control", "value": "public, max-age=3600" }
      ]
    }
  ]
}

Netlify (_headers file)

/.well-known/reasoning.json
  Content-Type: application/json; charset=utf-8
  Access-Control-Allow-Origin: *
  Cache-Control: public, max-age=3600

Cloudflare Pages (_headers file)

/.well-known/reasoning.json
  Content-Type: application/json; charset=utf-8
  Access-Control-Allow-Origin: *

If You Cannot Use /.well-known/

Some managed platforms do not allow serving files at /.well-known/. In this case, the recommended fallback order is:

1. Use a URL rewrite or redirect rule to map /.well-known/reasoning.json to a path the platform can serve
2. Serve the file at /reasoning.json at the domain root and add the HTML discovery tag pointing to that path
3. Use the <link rel="reasoning"> tag to point to the file at any path you can control

Note: the canonical, spec-compliant location is /.well-known/reasoning.json. Fallback paths reduce discoverability for AI systems that use the well-known path convention without first parsing HTML.