Surfaces

PROMPT 1 of 2 — learn what the Surfaces page teaches: the three classes, why a status code is evidence rather than a state, and the three rules that keep a hostname table honest. You read and explain. You write one checklist file and nothing else.

I run my own agents and public surfaces. Skip basics.

FIRST — WRITE YOUR CHECKLIST TO A FILE

Write ~/SURFACES-LEARN-CHECKLIST.md and work from it:

  # Surfaces — learn
  - [ ] 1. Fetch the page
  - [ ] 2. The three classes, and NEVER-EXISTED
  - [ ] 3. The rows where a bare code lies
  - [ ] 4. The three rules
  - [ ] 5. Quiz me, then tell me to paste prompt 2

  ## Rules
  - Read only. The checklist is the one file I write.
  - Every claim quotes the page sentence it came from.

1 — FETCH

    curl -s https://docs.utopiamodels.ai/docs/structure/surfaces.md

If that fails, say what came back and stop.

2 — THE CLASSES

Define LIVE, RETIRED-BY-DECISION and BROKEN, and why BROKEN is the only one that is a bug. Then tell the story the RETIRED-BY-DECISION class was born from: an auto-loaded doc still described a retired host as live, a master was dispatched to "restore" it, and the P0 was self-inflicted. Explain why "unclassified is broken" — the row with a plausible explanation and no decision record.

Add NEVER-EXISTED: a name cited in docs that never resolved. A citation is not a surface.

3 — WHERE A BARE CODE LIES

Walk through the rows the page uses to prove a status code is not a state:
  - the docs host that read 307, then 301, then 200 while its class changed twice — a check reading only the first code calls it healthy, broken and healthy again
  - the object-storage host: `/` is 404, a real object is 200, and there is no index — not a fault
  - the admin UI that answers `200` with `redirects=0` and is completely gated, because it renders its login in page

4 — THE THREE RULES

  1. No registry row means no check, and no check means nobody notices the day it breaks.
  2. Neither a 200 nor redirects=0 proves a page is public. Report redirects and the final URL, and read the body.
  3. Which edge served it matters: `cf-ray` = Cloudflare, `x-vercel-id` = Vercel, both = Cloudflare in front of a Vercel origin.

5 — QUIZ AND FINISH

Ask me three questions with the `AskUserQuestion` tool, one at a time, four options each, exactly one correct. At least one must present a status line and ask what class it supports. Quote the settling sentence after each.

If `AskUserQuestion` is unavailable in this session, ask the same questions as plain numbered text in one message instead.

Then say exactly this:

  "Surfaces learned. Paste prompt 2 and I will classify every hostname you own."

Then stop.

PROMPT 2 of 2 — build a classified surfaces table for MY hostnames: every name I own or cite, each with a class (LIVE · RETIRED-BY-DECISION · BROKEN · NEVER-EXISTED) and the evidence behind it. Probing is read-only; the table file is written only after I confirm where it goes.

HOW LONG THIS TAKES: a multi-step audit (5 steps, about 6 questions, one probe per hostname, writes only what you approve) — expect roughly 10–25 minutes across several turns. Running headless with a timeout? Budget for that, or start with a shorter prompt first. Cut off partway? Paste this prompt again — it resumes from its checklist rather than starting over.

    curl -s https://docs.utopiamodels.ai/docs/structure/surfaces.md

Read it first if prompt 1 did not run in this session.

ASK EVERY QUESTION WITH the `AskUserQuestion` tool, with a RECOMMENDED option first and one line of why.

FIRST — WRITE YOUR CHECKLIST TO A FILE

RESUMING? Before you write anything, check whether ~/SURFACES-INTEGRATE-CHECKLIST.md already exists. If it does, this prompt was interrupted: read it, tell me which steps are already ticked, and continue from the first unchecked step. Do not overwrite it, do not redo a ticked step, and do not re-ask a question whose answer it already records — the scope answer under ## Rules included, if it's there. If ## Rules has no Scope field, this checklist predates the scope question: say so plainly in your first output line and ask it now, before anything else. Only if the file does not exist, write it fresh as below.

Write ~/SURFACES-INTEGRATE-CHECKLIST.md and work from it:

  # Surfaces — integrate
  - [ ] 1. Collect every hostname I own or cite
  - [ ] 2. Probe each one properly
  - [ ] 3. Classify, and find the decisions that are missing
  - [ ] 4. Write the table where I choose
  - [ ] 5. Propose the re-measure

  ## Rules
  - Only GET/HEAD requests. No logins, no form posts, no changes to DNS or deploy config.
  - Every row carries the date it was measured.
  - A host I cannot reach from here is UNREACHABLE-FROM-HERE, never BROKEN.

SCOPE — ASK ME BEFORE YOU SURVEY ANYTHING OF MINE

Before step 1, ask me this with the `AskUserQuestion` tool, with both options exactly as written:

  "Should I treat any path as off-limits, or do you want me to have full access to survey and propose changes anywhere in this environment?"

  A — Exclude .env*, credentials and CI/deploy config (.github/workflows/, deploy keys) from anything I read or propose touching.   [RECOMMENDED for most readers]
  B — No exclusions. Full access to survey and propose anywhere, including secrets and CI files.

This is my preference, not a policy: some people want their agent to reach everything, some do not, and neither answer is the correct one. Never assume it and never pick for me. My answer governs every read and every proposal for the rest of this prompt. Write my answer under ## Rules in the checklist as "Scope: A" or "Scope: B", so it survives compaction. It governs the SURVEY and PROPOSE steps only — nothing gets written until step 4 (the table, where I choose) and step 5 (the script, if I choose it).

Before you ask, decide whether an answer can reach me at all. It cannot in a one-shot non-interactive run — `claude -p`, `codex exec`, `gemini -p`, a scripted or CI invocation — and you can tell without guessing: the `AskUserQuestion` tool is missing from your tool list there, while an interactive session has it. It also cannot if the question comes back immediately with no real answer. In either case do not ask, do not wait and do not re-ask: a question asked as plain text in a one-shot run ends the run with nothing done. This is the one case where you pick for me: treat A as my answer, record and hold it exactly as above, and make the first line of your output exactly: "No interactive scope answer available — defaulted to A (excluded .env*, credentials and CI/deploy config). To choose B, re-run this prompt in an interactive session and answer the scope question."

Only if the `AskUserQuestion` tool is in your tool list but fails when you call it, ask the same question as plain numbered text in one message instead.

1 — COLLECT

Hostnames come from three places, and the third is where NEVER-EXISTED rows come from:
  - what I own: ask me for my domains with the `AskUserQuestion` tool (RECOMMENDED option: "read them from my DNS/registrar config if it is in a repo here"), or read them from deploy configs (vercel.json, wrangler.toml, cloudflared config, Caddyfile, nginx)
  - what my infrastructure publishes: tunnel ingress rules, reverse-proxy configs
  - what my own docs and agent instructions CITE:
      grep -rhoE '[a-z0-9.-]+\.(com|ai|io|dev|app|shop|net|org)' --include='*.md' . | sort -u

2 — PROBE, PROPERLY

For each name, record all of this, not just a code:

    dig +short <host>
    curl -sS -o /dev/null -m 15 -L -w '%{http_code} redirects=%{num_redirects} final=%{url_effective}\n' https://<host>/
    curl -sSI -m 15 https://<host>/ | grep -iE '^(server|cf-ray|x-vercel-id|location):'

And for any 200, read the first part of the body: is it the real page, or a login form rendered in page? A 200 with redirects=0 that renders a sign-in is GATED, not public.

For object storage, a 404 at `/` is not evidence of anything — probe one real object path if one is cited anywhere.

3 — CLASSIFY

  LIVE                  intended to serve, and serving
  RETIRED-BY-DECISION   not serving, AND a decision says so — name where that decision is written
  BROKEN                not serving, and nothing says it was intended
  NEVER-EXISTED         cited somewhere, never resolved (NXDOMAIN, or delegated with no record)

The rule that does the work: if a host is not serving and you cannot point to a written decision, it is BROKEN, however plausible the explanation. List every row that would be RETIRED if someone wrote the decision down — that list is the finding.

Also list every LIVE host that nothing monitors. No row means no check.

4 — WRITE THE TABLE

Ask with the `AskUserQuestion` tool where it goes (RECOMMENDED: beside my other infrastructure docs, as SURFACES.md). Columns: hostname · class · what it is · evidence with date · edge (Cloudflare / Vercel / both / origin). Do not publish internal addresses in it if the file is public — use placeholders for anything that identifies private infrastructure.

5 — PROPOSE THE RE-MEASURE

A dated table decays. Propose ONE way to re-measure it — a script that re-runs step 2 and diffs the classes, run by hand or on a schedule I already have. Ask with the `AskUserQuestion` tool: write the script (RECOMMENDED) / just the table. Write only what I choose, then run it once and paste the real output.

When the writes are done, tell me in one line, filled in with the real paths:

  "To undo, delete `~/SURFACES-INTEGRATE-CHECKLIST.md`, `<the folder I chose>/SURFACES.md` and <the re-measure script, if you wrote one> — nothing else on your system was touched."

Finish with: counts per class, every BROKEN row, every would-be-RETIRED row missing its decision, and every unmonitored LIVE host.