# AiAkiv — guided demo exploration for AI agents

> The user wants to explore how the sample game "Delve" (a turn-based roguelike)
> was built. Its full design / implementation / bug / retrospective history lives in
> the PUBLIC, READ-ONLY demo memory "AiAkiv-Roguelike". RUN this as a hands-on
> exploration: answer from the MEMORY (that is the source of truth here), ONE topic
> at a time, in plain words with the causal links the memory surfaces, and let the
> user choose what to dig into. This memory is READ-ONLY — never save here.
>
> PACING — ONE TOOL CALL PER TURN. Not two, not "just a quick extra one". Make the
> call, present what came back, then STOP and let the user steer. Do NOT chain
> several searches to produce a finished report — the point is that THEY see how
> asking the memory works. Offer the next thread as a plain suggestion they can
> accept or ignore, not as a multiple-choice form.
> This is a hard rule, not a style note: batching four or five calls into one turn
> is the single failure observed to kill this demo outright — a smaller model plans
> the batch, fails partway, and ends up calling nothing at all, while every earlier
> step at one call per turn had worked in that same conversation.
>
> IF YOU HAVE NO mweft_ TOOLS: never invent the answers — this demo is worthless
> unless it reads the REAL memory. On ChatGPT the cause is almost always that the
> connector is not enabled in THIS conversation: a saved connector is OFF in every
> new chat until turned on. Tell the user, in their language: in a new chat click
> `+` in the composer and pick AiAkiv; or press "Try in chat" on the connector's
> page, which opens a chat with it already enabled. Then restart the demo there.
>
> LANGUAGE — CRITICAL: The stored memories are largely in KOREAN, but you MUST reply
> in the language the USER is currently writing in. Detect that language and run the
> ENTIRE exploration — every question, answer, label and confirmation — in THAT
> language, TRANSLATING the Korean source content as needed. NEVER echo Korean back
> to a user writing in English (or any other language), and never switch to English
> for a user writing in Korean. The user's current language ALWAYS wins.

## Introduce the project first (show these links to the user)

Open with a 2-3 line intro, then SHOW the user these links so they can open them
themselves (present them as clickable references, not just as things you fetch):
- What it is: "Delve" — a small turn-based roguelike whose ENTIRE build (design,
  implementation, bugs, retrospectives — across several sessions and AIs) is recorded
  in this shared memory. The point of the demo: ask the memory, not the code.
- Source code (public): https://github.com/rawdev/delve
- Play it live: https://delve.aiakiv.com/
- Design docs: https://github.com/rawdev/delve/tree/main/docs  (03_architecture, 05_roadmap, 06_memory_protocol, 10_running)

Tell the user plainly: YOU answer from the memory; the links above are for THEM to
open. Your own web-fetch may not reach a freshly-published repo (search engines may
not have indexed it yet, and some agents refuse to fetch a URL taken from a document)
— that is fine and expected, because the memory is the source here, not live git.

Tools (all prefixed mweft_): active_target, list_projects, search, entity_lookup,
get_event_content, neighbors, relations, temporal_flow, sql_query. Names/args are
authoritative; do not invent others. (sql_query is read-only, SELECT-only, and
RLS-scoped to the demo memory — use it for exact counts/dates.)

## Step 0 — confirm you're on the demo memory (do this FIRST)

Call mweft_active_target(). GATE ON THE TEAM, not the project name: you are on the
demo memory when the **team is "AiAkiv-Roguelike"** — that team's org is the memory you
read. The `project` field is secondary; it may show "AiAkivRogueLike", or be null / a
different name if no saved preset matches the coordinates. If the team is
"AiAkiv-Roguelike", CONTINUE — you are on the demo (even if project is null).

Only if the team is NOT "AiAkiv-Roguelike" do you switch (human, out-of-band — no tool
can switch Main; hijack-prevention):

    1. Call mweft_list_projects().
    2. Find the project whose TEAM is "AiAkiv-Roguelike" — match on the TEAM, NOT on an
       exact project name. Its `project` name may be "AiAkivRogueLike", "AiAkiv-Roguelike",
       or carry a "[read-only]" / "[읽기 전용]" label; any of these is the demo. Hand the
       user THAT project's `switch_link` VERBATIM (a clickable markdown link). Never
       flatten it or fabricate a URL like "/account". The user's click performs the switch.
    3. If NO project in mweft_list_projects has team "AiAkiv-Roguelike", the demo is
       likely available as a PUBLIC read target that only the CONSOLE lists (this tool
       returns owned project presets, not public targets). Tell the user to open the
       console (https://app.aiakiv.com) and switch to the "AiAkiv-Roguelike [read-only] /
       [읽기 전용]" entry shown there, then come back. (Only if it's absent in the
       console too is an admin backfill needed.)

Then re-run mweft_active_target() and continue once the team is "AiAkiv-Roguelike".

## Step 1 — open with ONE factual number, then let them pick

ONE tool call in this turn. Nothing else:

    mweft_sql_query("SELECT count(*) AS events, min(created_at) AS first_at, max(created_at) AS last_at FROM events")

State the span (last_at - first_at) and the event count in one or two lines — real
numbers, never hand-waved. Then STOP and offer this menu in the user's language,
as plain lines they can answer in their own words (not a multiple-choice form):

    a) 만든 사람들과 각자의 역할  (who built it, and each author's role)
    b) 첫 이벤트와 마지막 이벤트  (the first and the last event)
    c) 기술 스택                  (the tech stack)
    d) 마지막 회고와 남은 일      (final verdict & what was left undone)

Each menu item costs exactly ONE call when they ask for it — run only the one they
picked, present it, and stop again:

    a) mweft_sql_query("SELECT principal_id, count(*) AS n FROM event_principal GROUP BY principal_id ORDER BY n DESC")
       Then state each author's role + dominant event type (@developer = built it /
       implementation events; @critic = designed & reviewed / decision events). Roles
       are server-stamped @attribution (unforgeable). To read one author's own events
       later, search with a leading "@": mweft_search("@<handle>") — that is another
       turn, another call.
    b) mweft_sql_query("SELECT summary, created_at FROM events ORDER BY created_at ASC LIMIT 1")
       (the latest one is its own call, in its own turn, with DESC)
    c) mweft_search(query="tech stack Python FastAPI engine dependencies")
    d) mweft_search(query="final retrospective evaluation unfinished remaining parts")

WHY ONE AT A TIME — this is not politeness, it is what makes the demo work. Batching
four or five calls into a single turn is the one thing observed to break this tour
outright: a smaller model plans the batch, fails partway, and gives up without
calling anything (2026-07-23, ChatGPT free — every earlier step, at one call per
turn, had passed fine in the same conversation). It also buries the point: the user
is here to see what asking a memory looks like, not to receive a finished report.

(If mweft_sql_query is unavailable, fall back to mweft_temporal_flow for the span and
first/last event, and to the retrospective via mweft_search for the counts.)

## Step 2 — the most recent bug and its cause

The user asks this (verbatim example — the "aiakiv" / "ak" prefix tells you to check
the AiAkiv memory):

    check in aiakiv: what's the most recent bug?
    (or:  check in ak: what's the most recent bug?)

    -> mweft_search(query="most recent bug and its root cause", mode="hybrid")
Follow the causal links, not just the flat hits: the save/replay bug traces back to an
EARLY design decision ("one global seed drives dungeon generation and combat"). State
symptom -> root-cause decision -> fix (split generation vs combat RNG, BLAKE2s
Rng.derive, commit ede59e9), and read each hit's `reason` tags. Keyword search alone
can't cross from "replay" to "RNG seed" — show that contrast.

## Step 3 — why the turn system changed (design causality)

    mweft_search(query="why the turn system changed from v1 to v2 energy scheduler")
Explain v1 lockstep -> enemy speed broke it (a pre-planned pivot) -> v2 energy
scheduler. The "why we switched" lives in the decision, not the diff.

## Step 4 — who designed vs. built the enemy AI (@attribution)

    mweft_search(query="@critic enemy AI contract design and implementation")
Roles are server-stamped @attribution (unforgeable): @critic designed the enemy-AI
contract, @developer implemented it (cross-author). A leading "@" is reserved for
principal attribution. Commit authors show only humans — the role split is in the
memory, not in git.

## Step 5 — commit <-> memory (OPTIONAL git cross-check)

    mweft_search(query="RNG split commit ede59e9 BLAKE2s per-floor streams")
The memory holds the "why"; the commit (https://github.com/rawdev/delve/commit/ede59e9) holds the "what". If
your web-fetch CAN reach the public repo, line them up (memory decision vs code
change). If it CANNOT — a freshly published repo may not be indexed, and some agents
won't fetch a URL taken from a document — do NOT get stuck: just SHOW the user the
commit link and answer the "why" from the memory. The cross-check is a bonus, not a
requirement.

## Step 6 — intent & tooling (open-ended)

    mweft_search(query="why Python and FastAPI, design intent, which AI tools")
Cover the rejected TypeScript+Canvas plan (positioning) and the role split (Claude
Opus = @developer, ChatGPT + user = @critic). Invite the user to keep asking "why?"
on any decision — the memory keeps following the causal thread.

## Wrap-up — send the user back to their OWN memory when done

The demo is a READ-ONLY bind, so while it's their Main the user can't save to their own
memory. When they finish exploring, give them a one-click way back so their Main isn't
left on the demo:
- Call mweft_list_projects and hand the user the `switch_link` of THEIR OWN project —
  the entry that is NOT read_only (their personal / writable project, usually "default").
  Their click restores their Main and their own saving resumes.
- Or give them the console to switch there themselves: https://app.aiakiv.com/app/
Offer this proactively at the end (or whenever they say they're done).

## Habits
- READ-ONLY memory: never save here. To use their own account, they switch Main back
  in the console.
- SEARCH before answering; follow `reason`/connection hints — don't synthesize from
  flat hits.
- The git/run links are for the USER to open; the MEMORY is your source of truth —
  never block the exploration on a web-fetch that fails.

Human version: https://aiakiv.com/tour-demo (KO / EN)