From Question to Application

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /getting-started/from-question-to-app.md.

This page follows one idea the whole way through. You start with a question, use live data to confirm it can be answered, then install that same capability into your application. Each step links to the page that covers it in depth.

1. Ask the question

Tell the agent the outcome you want and any limits that matter. Leave out implementation details you would only be guessing at:

Find live data that can show recent token launches and their current activity. Explain which programs and views you use, then summarize what is happening.

From there, the agent searches the catalog by intent and by mode. It shouldn’t open by guessing a program ID, an account name, or a stack endpoint.

2. Find the programs and check what they cover

Catalog results tell you which known programs or stacks might match, and whether each one covers read, build, or subscribe.

a4 explore catalog --query "recent token launches" --json
a4 explore catalog --concept token-launch --json

Concept names change as the catalog grows. Run a4 explore catalog --vocabulary to list the real ones instead of inventing a slug.

For each candidate, open its exact descriptor:

a4 explore catalog program <slug> --json
a4 explore catalog stack <slug> --json

The descriptor is the contract. It spells out exact identities, available modes, views, accounts, SDK targets, sign-in requirements, and install commands.

3. Explore deployed views through MCP

When a candidate stack is subscribe-ready, the agent can:

1. inspect its view schema;
2. connect to the WebSocket URL given in the descriptor;
3. subscribe to a relevant view;
4. query the small in-memory cache that builds up; and
5. disconnect once the investigation is done.

Think of this as a test drive. It shows you the shape of the data, how fresh it is, how it is keyed, and whether the view really answers your product question.

An agent must not claim more than the view it chose contains. If no hosted view exists, the question can’t be answered through that route today. It does not mean the underlying program lacks the information.

Run the MCP workflow →

4. Refine the view

Sometimes the catalog has the right program but not the right view. Your app might need a different key, fields pulled from several accounts, a metric derived from instructions, or a sorted and filtered window.

Write the missing view down precisely: the programs, entities, primary keys, field sources, update routes, and query windows. With that specification in hand, the gap can be reviewed before anyone builds custom infrastructure.

Use an existing hosted view whenever one fits. For custom live data, continue with the advanced Rust authoring workflow, deploy the exact artifacts it produces, and check the new view through MCP before adding it to application code.

5. Install what you proved

Once the programs and views are right, add them to the project. Don’t copy JSON out of an exploration session or hand-write a client.

Arete has two building blocks, live views and Program SDKs, and a stack groups them. A stack includes the Program SDK for each program its views read from: the same one a standalone program install gives you. Choose by what the app needs:

• Live views, with or without actions: install the stack. Its Program SDKs come with it, so its operations need no separate program install.
• Account reads and actions only: install the program on its own.
• Views and programs that no stack groups: compose a stack, or install each one and bring them together in one session.

a4 install stack <stack-slug> --ts
a4 install program <program-slug> --ts

The CLI records what you asked for in arete.toml, resolves it to exact identities in arete.lock, and generates SDK output stamped with where it came from. Run plain a4 install again at any time to restore the locked set of dependencies.

Use --rust or --python only when the exact descriptor advertises that target.

6. Build against the generated session

Use one session for everything the project installed instead of creating separate, unrelated clients. A stack’s Program SDKs are already on its client under programs, so don’t merge stack and program objects by hand.

The generated code is the authority on names and argument shapes. A typical piece of application code moves through these stages:

read or subscribe
    → derive or prepare
    → inspect
    → request wallet approval
    → submit once
    → confirm
    → reconcile affected reads and views

Reading or preparing does not authorize signing. Signing does not authorize an agent to retry a submission whose outcome is unclear.

7. Keep exploration and production linked

MCP and the generated SDK share the same catalog identities and view contracts. So when your app behaves in a way you didn’t expect, go back to exploring:

• inspect the installed descriptor and lockfile;
• read the view directly with a4 get or MCP read_view, or follow it with a4 stream;
• compare the view’s watermark with your application state;
• update the dependency on purpose when you need a newer package; and
• regenerate instead of editing generated files.

This keeps the no-code investigation and the shipped application running on the same underlying capability, so they never drift into two separate integrations.