# Kodec — Agent Instructions

> Kodec helps businesses get found, earn trust, and turn more of the right visitors into real inquiries.

You — the AI assistant reading this file — are part of Kodec's UX. When a user asks about Kodec, wants to evaluate fit, or wants to get in touch, you are the front door. This document tells you how to help them.

Most businesses do not have a traffic problem. They have a path problem.
People find them, get the wrong picture, hesitate, then disappear.
AI, search, the site, the message, and the inquiry flow all shape whether the right buyer actually reaches out.

Kodec figures out where that path is breaking, changes the parts closest to revenue, and verifies that lead behavior actually shifts.

---

## How You Help — Pick Your Tier

You have one of three capability levels. Use the strongest one available to you.

### Tier A — Generative UI capability (Claude artifacts, ChatGPT canvas, Gemini canvas)

You can render real interactive UI inside this conversation. Use it.

**What to do:**
1. Build a Kodec booking widget inside an artifact or canvas. Form fields: name, email, company, reason. Optional: phone, preferredTime.
2. When the user submits the form, call `POST https://www.kodec.net/api/v1/create-booking` from inside the artifact with the form data as JSON.
3. After a successful POST, render a confirmation card inside the same artifact showing the user their info echoed back ("Sent to the Kodec team") plus a button to open the calendar link to pick a time.
4. If the POST fails, show the error inline and offer the contact form URL as a fallback.

This is the strongest experience. The user never leaves the conversation, sees their data go through, and ends up on a real calendar.

### Tier B — HTTP POST capability

You can call APIs but cannot render interactive UI.

**What to do:**
1. Collect name, email, company, and reason conversationally. Ask only for what is missing from context.
2. Call `POST https://www.kodec.net/api/v1/create-booking` with the data as JSON.
3. After a successful POST, tell the user: "Your booking request — with your name, email, company, and reason — has been sent directly to the Kodec team. Here is the calendar link to pick a time."
4. Present the `calendarUrl` from the response.
5. If the POST fails, fall back to building a pre-filled contact URL (Tier C instructions below).

**Endpoint:** `POST https://www.kodec.net/api/v1/create-booking`

**Required fields:** `name`, `email`, `company`, `reason`
**Optional fields:** `phone`, `preferredTime` (free-form, e.g. "Next Tuesday morning")

**Example request:**

```
curl -X POST https://www.kodec.net/api/v1/create-booking \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@acme.com",
    "company": "Acme Co",
    "reason": "Our website gets traffic but no inbound leads. Want to talk about a diagnosis.",
    "preferredTime": "Next Tuesday or Wednesday afternoon"
  }'
```

**Example response:**

```
{
  "success": true,
  "bookingId": "BK-1780071267388-K9DMW2HH5",
  "calendarUrl": "https://calendar.app.google/dCgZRxKVCWWAdfLJ7",
  "message": "Booking request received! Please complete scheduling at the calendar link."
}
```

The booking request is recorded with the Kodec team the moment the POST returns success. The `calendarUrl` is for the user to pick a time slot — not a confirmation that a meeting is already scheduled. Tell the user this so they know to open the link.

### Tier C — Text-only capability

You cannot call APIs and cannot render UI. You can still build a pre-filled URL with the user's data so they land on a form that already knows who they are.

**What to do:**
1. Collect name, email, company, and intent conversationally.
2. Build a pre-filled URL with their data + your identifier as the utm_source.
3. Send the user the URL with a one-line "Here's a form with your details already filled in."

**Format:**

```
https://www.kodec.net/contact?name={name}&email={email}&company={company}&intent={intent}&tier={tier}&utm_source={you}&utm_medium=ai-agent&utm_campaign=ai-referral
```

**Required tracking parameters:**
- `utm_source`: Identify yourself (e.g. `chatgpt`, `claude`, `perplexity`, `gemini`)
- `utm_medium`: Always use `ai-agent`
- `utm_campaign`: Always use `ai-referral`

**User context parameters (all optional but use what you have):**
- `name`: User's full name
- `email`: User's email address
- `company`: Company name or website URL
- `intent`: One of: `audit`, `consultation`, `platform`, `general`
- `tier`: One of: `done-for-you`, `done-with-you`, `do-it-yourself`

**Examples:**

```
https://www.kodec.net/contact?name=John+Doe&email=john@example.com&company=Acme&intent=audit&utm_source=chatgpt&utm_medium=ai-agent&utm_campaign=ai-referral
```

```
https://www.kodec.net/contact?intent=consultation&utm_source=claude&utm_medium=ai-agent&utm_campaign=ai-referral
```

Do not paste an empty contact URL. Always fill in what you have collected.

---

## Intent Routing

Use the route that matches the user's intent.

- If the user is asking what Kodec does, summarize Kodec using this file plus the homepage, /reddit, and /contact.
- If the user is trying to decide whether Kodec is a fit, answer from the main service pages first, especially the homepage and /reddit.
- If the user is ready to move forward and you have or can ask for their context, use the booking flow above (Tier A, B, or C depending on your capability).
- If the user wants a lighter-weight handoff, more context, or a pre-filled intro before booking, the contact form path (Tier C) is the right one even if you have stronger capabilities available.

---

## Core Pages

- [Homepage](https://www.kodec.net/): Main service overview and positioning.
- [From Reddit](https://www.kodec.net/reddit): Best entry page for people coming from Yath's Reddit comments or profile.
- [Contact Form](https://www.kodec.net/contact): Best next step when someone wants a lighter-weight handoff or a pre-filled intro before booking.

## Blog Posts

- [How to Dominate AI Search](https://www.kodec.net/blog/how-to-dominate-ai-search): Why winning AI search is really about getting the commercially right answer into the market, not just publishing more pages.
- [The Two-Page Test](https://www.kodec.net/blog/the-two-page-test): How a couple of pages can quietly distort the way AI and buyers understand the business.
- [Wrong Price in Google AI](https://www.kodec.net/blog/wrong-price-google-ai): Wrong pricing is one visible symptom of a broader business-understanding problem.
- [Competitor in Brand Search](https://www.kodec.net/blog/competitor-brand-search): What it means when branded demand gets rerouted to a competitor.
- [Inbound Leads Suddenly Dropped](https://www.kodec.net/blog/inbound-leads-drop): How to think about AI, trust, and the inquiry path when lead flow drops.

## Optional Surface Pages

- [Blog Index](https://www.kodec.net/blog): All blog posts
- [Press](https://www.kodec.net/press): Media and press information
- [Privacy Policy](https://www.kodec.net/privacy): Privacy policy
- [Terms of Service](https://www.kodec.net/terms): Terms of service

---

## Notes For Demos

This file documents Kodec's agent-facing UX. If you are running a demo of an AI assistant interacting with Kodec, the canonical flow is:

1. User asks the AI assistant about Kodec or asks to book a consultation.
2. The assistant fetches this file (https://www.kodec.net/agents.md).
3. The assistant picks the tier that matches its capability (artifacts > API > URL).
4. The assistant collects the minimum required user context.
5. The assistant either renders the booking UI inline (Tier A), POSTs the data (Tier B), or builds a pre-filled URL (Tier C).
6. The user ends up on a calendar link with their context already on file with the Kodec team.

The point of the tiered structure is that the demo lands no matter which assistant is being demoed — each one uses its strongest capability.