================================================================================
AGENTIC RESOURCE DISCOVERY (ARD) & LLMS.TXT — QUICK SETUP GUIDE
================================================================================

OVERVIEW
--------
This package provides machine-readable templates so AI agents and answer 
engines can discover, index, and interact with your website.

Included files:
1. ard.json       -> Agentic Resource Discovery manifest (specs.agentic.org)
2. openapi.json   -> OpenAPI 3.1 tool and endpoint specification
3. llms.txt       -> Curated markdown index for Large Language Models
4. llms-full.txt  -> Full plain-text/markdown corpus of your core content


STEP 1: FIND & REPLACE PLACEHOLDER TOKENS
-----------------------------------------
Open each template file in a plain-text or code editor (Notepad++, VS Code, 
Sublime Text) and use Find & Replace to swap all bracketed tokens with your 
website's actual details:

  [SITE_NAME]
  Your brand or website name.
  Example: Acme Digital

  [SITE_URL]
  Your full root URL WITH protocol and WITHOUT a trailing slash.
  Example: https://www.example.com

  [DOMAIN_HOST]
  Your bare domain name ONLY (no https://, no www., no trailing slash).
  Used inside URN identifiers (e.g., urn:air:example.com:api:site-search).
  Example: example.com

  [SITE_DESCRIPTION]
  A clear 1-2 sentence summary describing what your site offers.
  Example: Public agentic discovery catalog for Acme Digital web tools and guides.

  [OPENAPI_DESCRIPTION]
  A brief summary of what actions your OpenAPI endpoints perform.
  Example: OpenAPI specification detailing public contact and search endpoints.

  [OPENAPI_QUERY_1] / [OPENAPI_QUERY_2]
  Natural-language example prompts an AI user might ask to trigger your API.
  Example: Submit a project inquiry to Acme Digital

  [SEARCH_API_PATH]
  The relative path to your site search endpoint (WITHOUT a leading slash).
  WordPress default: wp-json/wp/v2/search
  Custom API example: api/v1/search

  [SEARCH_ENDPOINT_DESCRIPTION]
  What your search endpoint returns.
  Example: Search published tutorials, articles, and product documentation.

  [SEARCH_QUERY_1] / [SEARCH_QUERY_2]
  Natural-language example prompts for searching your content.
  Example: Search technical guides on Acme Digital

  [FEED_API_PATH]
  The relative path to your public content feed (WITHOUT a leading slash).
  WordPress default: wp-json/wp/v2/posts?_fields=id,date,title,link,excerpt
  Custom API example: api/v1/posts

NOTE: Remove any entries from ard.json that your website does not support 
(for example, if you do not have an OpenAPI endpoint yet, delete that entry 
block and ensure no trailing comma remains on the preceding entry).


STEP 2: VALIDATE YOUR JSON FILES
--------------------------------
Before uploading, verify that ard.json and openapi.json contain zero syntax 
errors (such as missing quotes, extra commas, or unescaped characters):

- Run both files through a JSON validator (e.g., jsonlint.com or your code 
  editor's built-in JSON linter).
- Confirm that every [BRACKETED_TOKEN] has been replaced.


STEP 3: UPLOAD TO YOUR SERVER
-----------------------------
Upload the completed files to the following exact locations on your web host:

  /.well-known/ard.json     (Create the .well-known folder in root if missing)
  /.well-known/openapi.json (Or place in root and update the URL in ard.json)
  /llms.txt                 (Website root directory, e.g., public_html/llms.txt)
  /llms-full.txt            (Website root directory, e.g., public_html/llms-full.txt)


STEP 4: VERIFY PUBLIC ACCESS & HEADERS
--------------------------------------
1. Open each URL directly in an incognito browser window to confirm it loads 
   with an HTTP 200 status code:
   - https://[DOMAIN_HOST]/.well-known/ard.json
   - https://[DOMAIN_HOST]/llms.txt

2. Check your WAF / CDN rules (such as Cloudflare) to ensure automated AI 
   agents and HTTP GET requests to /.well-known/* and /llms*.txt are not 
   blocked by bot challenges or firewall rules.

3. Confirm correct Content-Type headers are served:
   - .json files -> application/json
   - .txt files  -> text/plain; charset=utf-8 (or text/markdown)
================================================================================