arka-deck concepts
This document explains product terms in logical order: from the most concrete (your machine, your files) to the most abstract (multi-agent orchestration).
Project
Section titled “Project”A project is a local folder on your machine. You point arka-deck at it, and arka-deck creates a .arka-deck/ subfolder inside it to store its working data (memory, sessions, logs, configuration).
Your files don’t move. arka-deck only reads what it needs.
Workspace
Section titled “Workspace”A workspace is a logical container that groups several projects. It does not exist on disk — it’s an organization label internal to arka-deck.
Example: a workspace “Client A” can contain the projects “audit-2026” and “api-rewrite”.
Provider
Section titled “Provider”A provider is the LLM engine you configure to run the agents. arka-deck supports several providers:
| Provider | Status | Notes |
|---|---|---|
| Claude Code (Anthropic) | beta | Official @anthropic-ai/claude-agent-sdk SDK |
| Google Gemini | beta | Generative Language API |
| Codex CLI (OpenAI) | beta | Codex CLI runtime |
Each provider keeps its native capabilities. arka-deck does not erase specifics — it adds an orchestration layer on top.
Profile (HYOS)
Section titled “Profile (HYOS)”A profile is a specialized agent: a set of rules, capabilities, flowmaps and atoms that define how the agent should work in a given domain.
The public Cortex offers several dozen ready-to-use profiles (architect, lawyer, QA, data scientist, etc.). You install a profile on a project to recruit that agent.
A profile is not a hand-written system prompt. It’s a versioned entity, fetched from the Cortex and injected into the context at the right moment.
An atom is an atomic unit of knowledge: a rule, a pattern, a constraint or an isolated capability, identified by a stable identifier.
Atoms compose profiles and blocs.
A bloc is an executable rule or capability — a structured instruction that the agent can receive to frame its behavior: method, expertise, allowed tool, scope, constraint.
Blocs are organized into several types (skill, expertise, tool, methode, scope).
The cortex-actions addon lets you select a bloc before a chat turn to inject it into the agent’s context.
Flowmap
Section titled “Flowmap”A flowmap is an agentic execution sequence: a chain of steps, decisions and transitions that the agent follows to handle a structured mission.
Flowmaps come from the Cortex. They give the agent an explicit progression frame rather than free improvisation.
Session
Section titled “Session”A session is a chat exchange with an agent on a project. It contains the complete timeline: messages, thinking blocks, tool calls, results. Everything stays local.
A session has a lifecycle: started → ended (normal), or aborted, or error.
A turn is a single exchange within a session: a user message followed by the agent’s response. The events chat.turn.started and chat.turn.ended bound each turn.
Memory
Section titled “Memory”Memory is an active per-project persistence system. After a session, important elements (decisions, learnings, methods) can be captured as memory entries and reinjected into subsequent sessions.
Entries have an importance level from L1 (short note) to L5 (elaborated synthesis). Stored locally in <project>/.arka-deck/memory/.
Memory is not a chat history. It’s a semantic extraction of what is worth reusing.
An addon is a self-contained module that extends arka-deck’s capabilities. It subscribes to the event bus and can augment a turn’s context, write logs, or expose its own functionality.
Pre-installed (first-party) addons:
| Addon | Role | Status |
|---|---|---|
cortex-actions | Cortex artifact panel in chat | beta |
cortex-lite | Local Cortex runtime sidecar | stable |
memory-local | Per-project agentic memory | beta |
mission-guardian | Mission Control, guardian packs, leader and QA gates, evidence | beta |
squad-leader | Squad composition and coordination | beta |
squad-orchestration | Multi-agent LangGraph orchestration | beta |
notion-connect | Notion connector | beta |
gmail | User-managed Gmail connector | beta |
google-drive | User-managed Google Drive connector | beta |
@arkalabs/addon-expert-panel | Expert Panel infrastructure for future Expert Packs | not exposed in release |
Gmail and Google Drive are user-managed connectors: arka-deck does not provide a global Google OAuth app. The user brings the API token/gateway and may attach a user-managed MCP endpoint to the same connector installation.
The addon contract is stabilized to eventually allow external extensions. For now, all addons are wired explicitly in arka-deck.
Project MCP
Section titled “Project MCP”A project MCP is an external MCP server made available only to agents of a specific project. It is configured from External sources → Project MCP.
There are two paths:
- attach an existing connector installation that exposes an MCP endpoint, for example Gmail, Google Drive or Notion when the installation carries one;
- add a custom HTTP/SSE endpoint with a stable
connector_*runtime name.
arka-deck does not copy secrets into the project MCP configuration. Credentials remain in the connector installation or in a dedicated secret policy. Remote endpoints must use HTTPS; HTTP is accepted only on loopback for a local server.
When a project MCP is configured and tested, project agents receive it in their provider runtime. Another project does not receive it.
Worker
Section titled “Worker”A worker is a single-shot headless LLM process. It receives JSON as input, produces JSON as output, and exits. No chat, no multi-turn.
Workers are declared in a manifest.json and tied to a parent addon. Examples:
squad-creator— proposes a squad composition for a missioncortex-favorites-suggester— proposes Cortex artifacts relevant to the projectmemory-note-writer— drafts a memory note from a session
A squad is a team of specialized agents recruited to work together on a mission. Each agent has its profile and role. A leader coordinates.
The squad-leader addon manages squad composition and activation on a project. The squad-orchestration addon manages multi-agent mission execution with a LangGraph state graph.
Mission
Section titled “Mission”A mission is a unit of work entrusted to a squad. It includes a goal, phases, expected evidence and a QA verdict.
The mission-guardian addon tracks the mission state (phases, gates crossed, evidence captured) and prevents an agent from moving to the next step until the gates are validated. Mission Control is the runtime view of the same flow: active flowmap, current mode, blockers and expected next documents.
Mission Control
Section titled “Mission Control”Mission Control is the set of rules, permissions and traces that frame the agents’ work. In arka-deck, these runtime rules are carried by the active guardian pack and materialized through Cortex Lite for the project.
Guardian Pack
Section titled “Guardian Pack”A guardian pack is a governance pack applied to a project. It contains modes, transitions, rules, mini rules, mode-specific rules, flowmap, event policy, tool policy, UI card templates, prompt layers and required documents.
The active pack is materialized in Cortex Lite. Mission Guardian administers it and the runtime executes it; the core must not choose governance in its place.
Deck Guardian is the default first-party guardian pack for a standard arka-deck project. A future Expert Pack must bring its own dedicated guardian pack before it is published.
Cortex
Section titled “Cortex”The Cortex is a structured knowledge repository. It stores profiles, atoms, blocs, flowmaps and documents as a graph.
- Public Cortex (
public.arkalabs.app) — read-only, no authentication. Provides the starter catalogue. Your projects are never sent there. - Dedicated Cortex — private instance for a team or organization. Allows storing internal profiles, decisions, traces and operational memory (upcoming offer).
Cortex Lite
Section titled “Cortex Lite”Cortex Lite is arka-deck’s local Cortex runtime. It is backed by SurrealDB and a local graph model.
Its role is not to store files. Cortex Lite materializes the relationships the runtime needs: project, ArkaDoc documents, memory, profiles, methods, rules, events and module artifacts. Agents do not read a raw folder; they resolve a structured context scoped to the project through HTTP routes and the arka_runtime MCP server.
When a future validated Expert Pack is enabled on a project, Cortex Lite will link that pack to the project in the local graph. The pack’s methods, rules and eventmaps will become available only in that project context. No first-party Expert Pack ships in this release.
ArkaDoc
Section titled “ArkaDoc”An ArkaDoc is a business document attached to a project: report, brief, spec, task, decision, QA verdict. It persists on disk under <project>/.arka-deck/arkadoc/ and is consultable from the UI (list, timeline, kanban, tree).
For dispatch, the ArkaDoc document id is the stable runtime id. Agents may see a business task_id inside the document payload, but dispatch commands must use the ArkaDoc id exposed as dispatch_task_id.
Project Documentation
Section titled “Project Documentation”Project Documentation is the readable view over ArkaDoc deliverables: reports, specs, decisions, QA verdicts, briefs and business documents. It is no longer a UI mock: it reads the project’s real documents through documentation routes.
Each document is exposed with a consultation index: summary, tags, token estimate, blocks and relations. Agents can navigate by index, read a precise block, explore document neighbors or open the full content when needed. The goal is to avoid raw full-document reads by default and keep a deliverable graph Cortex Lite can use.