Cinatra Concepts and Glossary
Cinatra introduces several first-class concepts. They are well-defined inside the platform and recur across every doc; if you are landing here for the first time, this page is the quickest way to orient yourself.
For a deeper architectural picture, see Architecture. For the open standards that meet at the platform’s edges, see Open standards in Cinatra.
Core entities
Section titled “Core entities”A unit of capability with its own inputs, system prompt, tool references, control flow, output schema, and optional human-in-the-loop gates. A Cinatra agent is declared as an OAS Flow file at agents/<vendor>/<slug>/cinatra/oas.json. The OAS compiler derives the runtime fields (input/output schemas, approval policy, compiled plan) from the node graph; the WayFlow runtime executes the compiled flow. Agents are first-class citizens of the platform — they show up in the sidebar, can be installed from the marketplace, can be composed (an orchestrator agent calls sub-agents), and can be reached over A2A by anything outside Cinatra.
Assistant
Section titled “Assistant”A long-lived persona that appears in /chat. Assistants are not the same as agents: an agent runs a specific declared flow and exits; an assistant is a conversational identity (@chatgpt, future @gemini, @claude via the testing daemon) that lives across threads and can invoke agents as tools. Assistant configuration is managed under /administration/assistants.
A SKILL.md file (plus optional supporting scripts or references) that the platform delivers to an LLM as runtime guidance. Skills are curated, versioned, matched to agents through a declarative match engine, and synced into the active skills store. The skills surface in the sidebar (/skills) covers the installed catalog, packages, and matches.
Personal skill
Section titled “Personal skill”A skill scoped to one user × one agent, captured automatically by the skill autosave hook from the HITL prompt edits made during a run. A personal skill carries a based_on: frontmatter list of the prompt IDs that informed it, is updated in place on subsequent runs, and is matched into the agent’s prompt context the next time the same user runs that agent. Autosave is off by default and admin-gated under /administration/skills. See Continuous learning and personal skills.
Extension
Section titled “Extension”A self-contained domain capability packaged for Cinatra. Today the extension registry recognises two installable kinds: agents (OAS Flow packages) and skill packages (curated SKILL.md bundles). Extensions own their own persistence (Drizzle schema), background jobs (BullMQ), UI screens, MCP primitives, and a deterministic in-process client. Extension lifecycle (install, archive, restore, force-delete, public/private visibility) is dispatched through a central extensionRegistry. The marketplace at /administration/marketplace is where you find, install, and manage extensions. See Marketplace for the end-user view and Extensions for the engineering reference.
Object
Section titled “Object”Any persistent record in the typed object store — accounts, contacts, campaigns, recipients, blog posts, blog ideas, saved media, agent templates, lists, generic objects produced by agent runs. Every object has a namespaced type ID (@cinatra/<package>:<local-id>), a parent/child relationship, soft-delete, provenance, and is dual-written to a Graphiti-backed graph index for retrieval. See Objects layer.
A typed grouping of object references — for example, a list of contacts to receive an outreach campaign. Lists are themselves objects (@cinatra/lists:list), can be created and edited in the Information area of the sidebar, and are designed so agents can read from and write to them as first-class inputs and outputs.
Project
Section titled “Project”A bounded execution and context space that scopes a set of related runs and outputs. A project can sit at any of the four ownership levels (User, Team, Organization, Workspace) and ratchets upward irreversibly. Outputs created inside a project inherit the project’s scope; outputs created outside a project are owned directly at the triggering level.
A single execution of an agent. A run has an id, a status (queued, running, pending_approval, completed, failed, stopped), a stream of typed AG-UI events, optional HITL surfaces published over A2UI, and a final outputs payload. Runs are durable: they survive page reloads and disconnects, and a client reconnecting with a Last-Event-ID header resumes exactly where it left off.
Trigger
Section titled “Trigger”A configured way to start an agent run without a user clicking Run. Triggers include scheduled runs, webhook-driven runs, and event-driven runs. Each agent template can have a trigger config that fires its execution under specific conditions.
Dashboard
Section titled “Dashboard”A user-configurable layout of analytics widgets backed by a shared semantic-layer engine. The /agents route hosts the default agents-activity dashboard out of the box; users can create additional dashboards, drag widgets around, and persist their layout through a single mutation service with a draft → published → archived lifecycle. Each mutation also writes an audit_events row inside the same transaction. Dashboards are reachable as MCP primitives (dashboards_create, dashboards_update, dashboards_publish, dashboards_archive, dashboards_get, dashboards_list). See Dashboards.
Notification
Section titled “Notification”A typed record in cinatra.notifications describing an event a user (or team, organisation, project, or admins recipient set) should see. Notifications are written by the platform — for example, on BullMQ job completion or failure, on long-running agent run state transitions, or by extensions through the explicit createNotificationForRecipient API — and surfaced through the Notifications sidebar area plus a realtime SSE push driven by Postgres LISTEN/NOTIFY. Toasts handle in-page transient feedback; the notifications feed is durable.
Permission
Section titled “Permission”The access control on an extension. Cinatra’s permissions surface is generic across four kinds — agent_template, agent_run, skill_package, and skill — with a co-owner grant (a boolean entry, paired with a per-resource access policy that governs read / execute / share for users outside the co-owner set). Skill-level entries can carry a tighter or wider policy than the parent skill package. Every privileged read or write goes through one of the kernel’s authorization helpers, and every grant, revoke, and policy change writes an audit_events row.
Ownership and scope
Section titled “Ownership and scope”The signed-in human. Every actor in the system resolves to a user identity (or a delegated service identity).
A collaboration unit inside an organization. Teams own resources that the team’s members can use together.
Organization
Section titled “Organization”A workspace tenant. Better Auth manages organizations, memberships, roles, and invitations. Most administrative controls (LLM keys, connector credentials, extensions installed) operate at the organization level.
Workspace
Section titled “Workspace”The platform-instance level above organization — currently implicit per deployment. The Workspace level is the ownership tier where platform-wide resources (instance namespace, registry credentials, base configuration) live.
Instance namespace
Section titled “Instance namespace”A globally-unique identifier each Cinatra instance picks during setup. It doubles as the npm scope under which the instance publishes its extensions to the shared registry — @<instance-namespace>/<extension-name>. Setting up an instance fixes the namespace; renaming it is intentional and limited.
Protocols and surfaces
Section titled “Protocols and surfaces”OAS (Open Agent Specification / agentspec)
Section titled “OAS (Open Agent Specification / agentspec)”The declarative file format Cinatra agents are authored in. Cinatra implements agentspec_version: "26.1.0". See Open standards in Cinatra.
A2A (Agent-to-Agent Protocol)
Section titled “A2A (Agent-to-Agent Protocol)”The HTTP/JSON-RPC protocol Cinatra exposes for external systems to call its agents, and the protocol Cinatra uses to call remote agents.
AG-UI (Agent-User Interaction Protocol)
Section titled “AG-UI (Agent-User Interaction Protocol)”The SSE event protocol Cinatra streams from every agent run — RUN_STARTED, TEXT_MESSAGE_CONTENT, INTERRUPT, etc.
A2UI (Agent-to-User Interface)
Section titled “A2UI (Agent-to-User Interface)”The declarative payload format Cinatra publishes for HITL surfaces — setup forms before a run starts, mid-run review panels, confirmation surfaces.
MCP (Model Context Protocol)
Section titled “MCP (Model Context Protocol)”The capability surface every extension exposes. Internally, packages call each other through MCP primitives via the deterministic client; externally, MCP clients (Claude Code, ChatGPT connector, custom agents) reach the same primitives via the MCP server endpoint.
Runtime and infrastructure
Section titled “Runtime and infrastructure”WayFlow
Section titled “WayFlow”The OAS-compliant Python agent runtime, running as a Docker sidecar. Cinatra invokes it over A2A; in principle any OAS-compliant runtime could be swapped in without changing the rest of the platform.
BullMQ
Section titled “BullMQ”The Redis-backed job queue handling all long-running work (agent runs, content generation, email sends, etc.). The Next.js app enqueues, the worker process picks up and executes. Default queue name: cinatra-background-jobs.
Graphiti
Section titled “Graphiti”A typed object graph indexer used by the Objects layer. Persisted objects are shadow-written into Graphiti for embedding-backed retrieval; the OpenAI API key is required because Graphiti uses it for embeddings.
The OAuth gateway for third-party connector authentication. Connectors (Gmail, Apollo, LinkedIn, etc.) authenticate via Nango; the user-side flow is in the Connectors sidebar area.
Better Auth
Section titled “Better Auth”The authentication library powering sessions, multi-factor auth, passkeys, organization membership, and the OAuth provider plugin that issues tokens for MCP and A2A access.
Where to go next
Section titled “Where to go next”- See how the pieces fit: Architecture
- Author your first agent: Developing agents
- Install and run an agent: Quickstart
- The open standards behind the surfaces: Open standards in Cinatra
- Extension lifecycle: Extensions