arete

Discover and Install Arete Capabilities

Use this skill to turn an application intent into an exact, installed Arete dependency. Do not guess protocols, stack names, program surfaces, view names, or generated APIs.

Platform Model

Arete has two building blocks:

• Live views: entities and views that a hosted runtime maintains. Query them at a point in time or subscribe to their updates.
• Program SDKs: one program's typed accounts, reads, PDAs, raw instruction builders, and semantic instructions, transactions, and flows.

A protocol builds on both: it composes existing programs into a hosted multi-step flow (instances, roles, guards, deadlines, steps that prepare transactions for the user's wallet to sign) with its own generated stack.

A stack is a named group of live views and program SDKs. A default stack includes the program SDKs for the programs its views index. A composed stack groups views and program SDKs that you choose.

Catalog results describe coverage in three modes:

• subscribe: typed point-in-time and live views from a hosted stack.
• read: typed program-account and chain reads.
• build: typed program instructions, transactions, and flows.

An exact stack descriptor binds selected views, programs, authentication policies, endpoints, and SDK targets. A program descriptor binds a normalized IDL, ProgramSpec, Program Release, Program Read service, and supported SDK targets.

Health Gate

When environment setup is relevant, run:

a4 doctor --json

Follow the reported fix commands when a required check is not ready. If a4 is missing and setup is within scope, use the current bootstrap instructions at https://docs.arete.run/agent.md; do not substitute a Cargo installation from memory.

Do not run setup on every Arete task. A healthy project, a usable generated dependency, or a task that only asks for explanation does not need repeated onboarding.

Discovery Workflow

Start from the user's intent, not from a remembered public stack:

a4 explore catalog --query "<intent>" --json
a4 explore catalog --vocabulary --json

Use --concept or --category only with slugs returned by the vocabulary. Narrow by --kind program|stack, --mode read|build|subscribe, and --target typescript|rust|python when the request already determines those constraints.

Search results and the vocabulary are brief by default, and brief JSON names the next step in a top-level hint. Add --full for every field or, on search only, --fields a,b for specific keys, and pass a page's nextCursor back as --cursor with the same filters. a4 explore catalog --json with no filters returns an overview of the first programs and stacks. The MCP search_catalog, list_catalog_vocabulary, explore_stacks, and explore_programs tools are brief the same way; pass full: true for more, or fields on every tool except list_catalog_vocabulary, which only takes full.

Read each result's coverage modes, then route by what the application needs:

• Live views, with or without operations: a stack. Its program SDKs come with it (see Stacks include their program SDKs). Use arete-streams for view code and arete-programs for the stack's operations.
• Reads and operations only: a program SDK. Use arete-programs.
• Views and program SDKs that no stack groups: compose a stack from them (see Compose a stack), or install each one and hold them in one session.
• A stack result without subscribe coverage (live: false) is definition-only. It installs as a typed SDK and a pinned StackManifest, but nothing is hosted. The user can deploy their own copy after installing it (see arete-deploy); do not present it as a live stream until then.
• An app flow or transaction workflow over several steps or programs (open, contribute, close, refund; roles, deadlines, approvals): a protocol. Install an existing one with a4 install protocol <protocol-ref> --ts, or author one; use arete-protocols for both. A single program call stays with arete-programs.
• An agent acting on a protocol with a wallet (what can this wallet do now, prepare a step, check and sign it, submit; the MCP protocol_* tools and an optional signer policy): a4 protocol actions <protocol-ref> --wallet <pubkey>, covered by arete-protocols. The agent signs with the wallet it was given; never configure a signer or move funds unless the user asks.
• Local development of a protocol (a cloud fork, local RPC and UI, steps, clock controls, and a generated dev client): a4 dev up, covered by arete-protocols. Start a new protocol project with a4 protocol init. Streaming its stack locally (a4 stream --dev) is in arete-streams.
• No suitable hosted capability and the user wants a custom feed: specify the missing read model, then use arete-stack-authoring.
• Publication or hosted lifecycle work, including a4 protocol deploy: use arete-deploy.

Program, stack and protocol slugs often differ for the same protocol, so results link them. live is a stack property: whether it streams now. Building transactions and reading accounts is a program property; a stack whose modes include build or read has them because it ships its programs' SDKs, so a protocol with a stack can be built against through either slug. A stack's programs lists the programs it composes as {slug, programId}; a program's stacks lists the stacks composing it as {slug, live}; a program whose install name differs from its slug carries installName, and either name installs it. The page-level protocols lists every stack and program of each result's protocol, including ones on other pages or excluded by --kind. To stream, install a stacks[].slug with live: true; to build without streaming, install a programs[].slug. When asked which protocols can stream or build, answer per protocol from protocols, not per catalog entry, and count only the stacks and programs that match the question: on a narrowed search the rollup marks them matched: true and lists the protocol's others (an exchange's AMM stacks on a launchpad search) with matched: false. A protocol streams for the question only when a matching stack is live. Do not guess one kind's slug from another's. A page continued with --cursor that carries catalogChanged: true may skip or repeat entries; search again without --cursor when you need the full list.

Inspect the selected catalog result as an exact install descriptor:

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

If the user or project already supplies a direct reference, inspect it directly. These print a compact summary; add --full for the complete descriptor contract:

a4 explore stack <stack-ref> --json
a4 explore program <program-ref> --json

a4 explore stacks and a4 explore programs list the installable stacks and standalone programs.

Keep exploration output small when you only need part of a descriptor:

a4 explore stack <stack-ref> --views <Entity>/<view> --json
a4 explore stack <stack-ref> --operation <operation> --json
a4 explore program <program-ref> --operation <operation> --json
a4 explore program <program-ref> --section instructions --json

The default stack summary gives live, entities with their view ids, token-amount fields with units, the stack's read.* helpers, program SDKs, stream endpoints, brief auth, and the install command; --full adds identities, hashes, per-surface auth and every endpoint. The default program summary lists instructions, accounts and PDAs; --full prints the IDL-level descriptor. --views takes several views, comma-separated. --operation takes a semantic path such as transactions.<group>.<name>, an operation id, or a raw instruction name. On a stack it searches the stack's program SDKs. Semantic paths need an API key; without one, only raw instruction names resolve.

Catalog contents and capability delivery can change. Do not maintain a static list of public programs or stacks, infer an endpoint, or treat a search result as proof that an unreported mode is available.

For reviewed protocol context and callable operation semantics, use the knowledge layer when available. a4 know search and a4 know concepts (MCP search_knowledge and list_concepts) are brief by default; add --full (full: true) for every field, or --fields (fields) on search:

a4 know search --query "<intent>" --json
a4 know program <program-slug> --section surface --json
a4 know program <program-slug> --section instructions --json
a4 know program <program-slug> --section accounts --json

Return to the exact catalog descriptor before installation. Treat a descriptor refusal as “not currently installable.” Do not fall back to an arbitrary latest IDL, AST, deployment, or release.

Install the Exact Dependency

Prefer the installCommand returned by the exact descriptor. In a project, a saved dependency updates arete.toml, resolves arete.lock, and generates provenance-owned output:

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

Choose --ts, --rust, or --python from the existing project language and the descriptor's sdkTargets. Standalone program packaging may support fewer targets than a program bundled in a stack; trust the descriptor and command output.

For TypeScript in a directory with no package.json, add --setup (for example a4 install stack <stack-ref> --ts --setup): it creates an ES module package.json and tsconfig.json and installs the runtime and dev dependencies. Without it, a4 still writes the generated SDK, arete.lock, and any arete.toml change, but leaves package.json and tsconfig.json alone and lists what is missing; follow the user's preferred setup if they have one. The install summary points to each SDK's reference: a4 sdk describe <alias> --read <name> or --view <Entity>/<view> (or MCP describe_sdk) prints one part, and README.md in its generated folder indexes every part at the top. Server-side SDKs need no auth option: they pick up ARETE_API_KEY or the active a4 login.

Use --no-save only for a genuinely disposable, one-package generation. Do not hand-edit generated SDKs.

A definition-only stack's generated SDK has empty endpoints until the project records a deployment of it. Deploying it with a4 up <alias> (an external mutation; see arete-deploy) records the deployment in arete.toml and regenerates the SDK.

For project dependency configuration, locked installs, updates, removals, and output ownership, read references/project-dependencies.md.

Stacks include their program SDKs

A default stack includes the program SDKs for the programs its views index. Installing the stack gives you each one at arete.programs.<name> (session.programs.<name> in a session), using the stack's auth and transaction transport. These are the same SDKs a standalone a4 install program produces, from the same program package release, so you do not need a separate program install to get a stack's operations. Take <name> from the generated types.

• Install a program on its own when you only need reads and transactions.
• If no stack groups the views and program SDKs you need, compose one.
• Installing a stack and the same program standalone is still valid. When both come from the same program package release, the install output lists the program under Shared, and at runtime they are one program.
• Never merge stack and program objects by hand, for example by spreading them into one object. Pass stacks and programs to one session, or use the stack's own programs.

To confirm that a stack provides an operation before adding another package for it, run a4 explore stack <stack-ref> --operation <operation> --json.

Report the requirements before writing code that sends transactions. The install output lists the stack's auth requirements, and authRequirements in a4 explore stack <stack-ref> --full --json gives the same. Browser apps need a publishable key bound to the app's origin. When transactions need an account entitlement, a4 doctor --json reports the account's account.transactions readiness.

Compose a stack

When no stack groups the live views and program SDKs you need, compose one from published parts:

a4 stack compose --name <name> --live <stack-ref> --program <program-ref> --install --ts

This writes [authoring.stacks.<name>] in arete.toml, declares the stack as a dependency with the SDK target you pass (--ts, --rust, or --python, as for a4 install), and installs it. The programs the views index come with them, as their stack's program SDKs. A composed stack does not carry a source stack's stack extension, such as its read functions. For view selection, local files, deployment, and limits, use arete-stack-authoring.

Source-of-Truth Order

When sources differ, use this precedence:

1. Generated types and the installed descriptor identity.
2. Current a4 <command> --help and --json output.
3. Current Arete documentation.
4. These workflow instructions.

Never preserve a stale example merely because it appears in an existing application. Identify the mismatch and migrate it to the installed surface.