shimpz.toml — Shimpz docs

Complete example

Two required tables and optional link and Integration tables

shimpz.toml toml

[shimpz]
spec = 1
id = "shimpz-cloudflare"
version = "0.5.2"
name = "Cloudflare"
summary = "Set up your domains' DNS without opening a dashboard or memorizing records."
description = "Look up your Cloudflare domains and their DNS records, and create, replace, or delete A, AAAA, CNAME, and TXT records without opening the Cloudflare dashboard. Every change waits for your password before anything reaches Cloudflare."
creators = ["@shimpz"]
github = "https://github.com/TheShimpz/shimpz-cloudflare"
genesis = """
Use this Assistant to inspect Cloudflare zones and to manage reviewed A, AAAA, CNAME, and TXT DNS records.

Call list-zones to discover available zones and get-zone for exact zone details. Call DNS-record Actions only with
a zone_id returned by list-zones, and get-dns-record only with a record_id returned by list-dns-records. Start with
page 1 and a small per_page. Use ensure-dns-record to converge on one exact state, replace-dns-record for a complete
replacement, and delete-dns-record for one exact record. Every mutation must complete its declared auth:password
authorization before observing an access token or contacting Cloudflare. Never claim success beyond the returned
provider result, silently retry an uncertain write, mutate a zone, or ask the user to paste OAuth credentials.
"""

[shimpz.links]
site = "https://shimpz.com/"
github = "https://github.com/TheShimpz"

[network]
allowed_hosts = ["api.cloudflare.com"]

[integrations.cloudflare]
scopes = ["zone.read", "dns.read", "dns.write", "offline_access"]

Identity

Describe one Assistant under [shimpz]

[shimpz]: The required parent table for identity, publication disclosure, and Genesis.
spec: The integer 1. No other Assistant Spec version is supported.
id: A stable identifier of 1 to 40 characters: lowercase letters and digits in hyphen-separated segments, starting with a letter. It is independent of repository and Python project names. postgres, assistant-egress, and shimpz-assistant-egress are reserved.
version: A stable semantic version such as 0.1.0.
name: A display name from 1 to 80 characters, without surrounding whitespace or line breaks.
summary: A short, single-line outcome description from 1 to 80 characters, shown in full under the Assistant's name. With SDK 0.6.0, it joins the message catalog and is translated with it, so it must be NFC-normalized English without braces, and every translation must fit 80 characters too.
description: A plain-language paragraph from 1 to 400 characters, shown under the summary on the Assistant's page. Write it on one line, without surrounding whitespace. Like the summary, it joins the message catalog and is translated into every interface language, so it must be NFC-normalized English without braces; every translation must fit 500 characters.
creators: One to 16 unique Account-owned Creator handles, each beginning with @.
github: The exact HTTPS URL of the public GitHub repository.
[shimpz.links]: An optional table of the Creator's public pages, shown as the Creator's links on the Assistant's page. Its keys are site, github, x, youtube, linkedin, and instagram, each at most once, and the table needs at least one when it is present. Each value is an https URL of at most 256 characters in the form required for help_url, on the kind's own host: github.com for github, x.com for x, youtube.com or www.youtube.com for youtube, linkedin.com or www.linkedin.com for linkedin, instagram.com or www.instagram.com for instagram, and any public host for site. Nothing verifies these links, and they are separate from the repository named by github above.
genesis: Bounded behavior and Action-composition guidance loaded by the Brain. Genesis never grants authority. help.md is not part of Assistant Spec v1 and is not loaded as Brain guidance.

Access intent

Request only what the code needs

[network]: The required parent table for Assistant outbound network intent.
allowed_hosts: A unique list of exact public DNS hostnames. Use [] for no network access. Schemes, ports, paths, wildcards, IP literals, and private or reserved names are invalid.
[integrations.<provider>]: An optional table keyed by a registered provider id. Its only key is a unique, non-empty scopes list from that provider's supported catalog. Both the provider and every scope must exist in the current published catalog. Provider endpoints and OAuth client configuration remain Controller-owned.
[stored_inputs.<id>]: An optional table for a token-like third-party value that Team keeps encrypted for the Team once a person enters it, at most eight per manifest. It holds kind = "password", a label of 1 to 80 characters, a help-text description of 1 to 400 characters, and a required help_url. The description is what a person reads wherever the value is asked for: in plain language, what the secret is and the steps to get it, written for someone who has never made one. The label and the description join the message catalog and are translated like the summary, so both must be NFC-normalized English without braces, and every translation must fit 120 and 500 characters. A provider permission name such as ads_read is kept by translation intent, not guaranteed, so the linked page stays the authority. It also declares where Team places the value in provider calls: one host from allowed_hosts, exactly one header (with an optional scheme such as "Bearer") or query parameter, and an optional hmac naming another Stored Input of the same host, which places the lowercase hexadecimal HMAC-SHA256 keyed by this value over that one, as Meta's appsecret_proof. Team-owned headers such as Host or Content-Length and a field another Stored Input uses on the same host are refused. The required routes list names the only endpoints on that host that ever receive the value. Each Action names the ids it uses, any number of them, and only its calls carry them; several Actions may share one. See password input.
help_url: A required key of a [stored_inputs.<id>] table: the closest official page where a person creates or finds the value, such as an API key page, or the provider's documentation when making it takes several steps. Admin shows it after the description as one "How to get it" link that opens in a new tab. It must be one canonical https URL of at most 2,048 characters on a public DNS host, with a path and an optional query, and without a port, credentials, a fragment, or a . or .. segment, written exactly as a browser prints it: for example https://dashboard.exa.ai/api-keys, not https://dashboard.exa.ai.

Stored Input routes

Name every endpoint that receives the value

A Stored Input reaches its host only on the calls its routes admit. List each method and path your Actions send it on, and nothing more: a key that only searches must never travel to an endpoint that changes billing or reads other credentials.

shimpz.toml toml

[stored_inputs.exa-api-key]
kind = "password"
label = "Exa API key"
description = "Lets this Assistant search the web. Create it in the Exa dashboard."
help_url = "https://dashboard.exa.ai/api-keys"
host = "api.exa.ai"
header = "x-api-key"
routes = [{ method = "POST", path = "/search" }, { method = "POST", path = "/contents" }]

routes: A required key of a [stored_inputs.<id>] table: 1 to 32 inline tables { method, path, query }, with no two sharing the same method and path. query is optional.
method: One of GET, HEAD, POST, PUT, PATCH, or DELETE.
path: At most 512 characters of /-prefixed segments. A segment is either a literal of 1 to 64 unreserved characters (A-Z, a-z, 0-9, -, ., _, ~) other than . and .., or *, which matches exactly one segment of 1 to 256 of those characters, such as a numeric object id. There is no root path, empty or trailing segment, partial wildcard such as v*, or wildcard spanning several segments: /v23.0/*/messages matches /v23.0/1234567890/messages but not /v23.0/1/2/messages.
query: Optional selectors for a provider parameter that changes what an endpoint returns or acts on, such as Meta's fields on an object that can also return a token. Each is { name, values }: a name of 1 to 64 unreserved characters, unique without regard to case, and 1 to 16 unique values of at most 256 characters. Write each value exactly as your Action's query encoder sends it, with reserved characters percent-encoded in uppercase hexadecimal: Python's urlencode sends id,name as id%2Cname. A call on that route must carry each selector exactly once, under that exact name, with one listed value; other parameters stay free. At most 8 selectors per route.

A route may never name an endpoint that issues, lists, or exchanges credentials. A literal segment is refused when, lowercased and without -, _, ., and ~, it contains apikey, authoriz, credential, oauth, password, secret, or token, so /v1/api-keys and /oauth/access_token fail validation. Team applies the same test to every segment of each call, so a * never reaches such an endpoint either.

Team places a credential only when every Stored Input the Action declares for the call's host admits the call. When two Stored Inputs share a host, such as Meta's access token and its app secret, give them the same routes; otherwise a call outside either list is refused before any credential is placed. See how Team matches each call.