# Vancetope

> A personal project: a server (the "Brain") on which LLM agents work assignments over hours and days — shaped almost entirely from its own documents. Not a product; source-available, not classic open source.

Almost everything in Vancetope is a document in MongoDB — recipes, prompts, schedulers, hooks, settings, manuals — so the system can be reshaped from its own data, by humans and by agents. Engines are Java algorithms with a lifecycle; code drives the flow, not the LLM. Recipes (YAML configs) bind engines to default params, prompt prefixes and tool adjustments — many recipes per engine, no Java change required.

The authoritative specs are written in German under `specification/public/*.md` in the source repository. The English Markdown linked below is auto-translated via Gemini and may lag behind the German originals. Inter-spec links in the raw markdown use relative `.md` paths and resolve within `/llm/specification/`.

## Documentation

- [Get started](https://www.vancetope.com/getting-started): install and run Vancetope locally with Docker.
- [Concepts](https://www.vancetope.com/concepts): engines, recipes, scopes, think-processes, kits.
- [Architecture](https://www.vancetope.com/architecture): brain + clients, data model, triggers.
- [How-tos](https://www.vancetope.com/howtos/): task-oriented guides for common workflows.
- [Source repository](https://github.com/mhus/vance): Java/TypeScript implementation, BSL 1.1.
- [Install script](https://www.vancetope.com/install.sh): one-command local install (curl … | bash), no git needed.

## Specifications

- [addon-system](https://www.vancetope.com/llm/specification/addon-system.md): Status: v1 in production since 2026-06-03 (slideshow as reference Addon).
- [agrajag-engine](https://www.vancetope.com/llm/specification/agrajag-engine.md): Agrajag checks tools, classifies their errors, and writes their health state. In the Adams universe, Agrajag is one half of the diagnostic duo "Agrajag…
- [anus-setup-wizard](https://www.vancetope.com/llm/specification/anus-setup-wizard.md): Interactive bootstrap mode of the Anus Admin Shell for initial provisioning of a fresh Vancetope deployment: creates Tenant + User, configures AI Provider (API…
- [app-calendar](https://www.vancetope.com/llm/specification/app-calendar.md): Specifies the calendar-suite application — the first reference implementation of the `kind: application` pattern. A folder with `_app.yaml` (`$meta.app: calendar`) becomes a project planning…
- [app-canvasbook](https://www.vancetope.com/llm/specification/app-canvasbook.md): Folder container for multiple `kind: canvas` pages — a "book" of Canvases,
- [app-gtd](https://www.vancetope.com/llm/specification/app-gtd.md): Getting-Things-Done container via `kind: action` pages, in the Things paradigm
- [app-issues](https://www.vancetope.com/llm/specification/app-issues.md): A lightweight GitHub-Issues-style issue tracker, built on the
- [app-journal](https://www.vancetope.com/llm/specification/app-journal.md): Journal container via `kind: journal-entry` pages, built on the
- [app-kanban](https://www.vancetope.com/llm/specification/app-kanban.md): Self-contained Kanban-board pattern built on the `kind: application` foundation (see `doc-kind-application.md`). One folder = one board. Sub-folders = columns. One `kind: card` file per…
- [app-wiki](https://www.vancetope.com/llm/specification/app-wiki.md): Name-addressed link-graph wiki over `kind: workpage` pages, built
- [app-workbook](https://www.vancetope.com/llm/specification/app-workbook.md): Notion-style Workbook built on the `kind: application` foundation (see
- [architektur-scopes-clients](https://www.vancetope.com/llm/specification/architektur-scopes-clients.md): Defines the hierarchy of Scopes, the Client model, and the Session concept.
- [arthur-engine](https://www.vancetope.com/llm/specification/arthur-engine.md): Arthur is the reactive Session Chat Think Engine — the default engine of the Chat Think Process, which is automatically created when an Interactive…
- [audit-system](https://www.vancetope.com/llm/specification/audit-system.md): Central audit pipeline for Vancetope Server (Brain + Anus). Producers emit typed audit events; an `AuditService` normalizes, buffers, and fans them out to a…
- [client-protokoll-erweiterbarkeit](https://www.vancetope.com/llm/specification/client-protokoll-erweiterbarkeit.md): Defines the WebSocket protocol, how external systems connect as clients, and how Vancetope thereby becomes an open platform.
- [cortex](https://www.vancetope.com/llm/specification/cortex.md): Status: v1. Binding product spec for the unified Chat + Document + Execute work environment of the web UI. Implementation resides in `client_web/packages/vance-face/src/cortex/` plus…
- [damogran-system](https://www.vancetope.com/llm/specification/damogran-system.md): A lightweight, linear batch runner over a named Workspace:
- [doc-kind-application](https://www.vancetope.com/llm/specification/doc-kind-application.md): Specifies the `application` payload for documents named `_app.yaml` — the manifest at the root of a Vancetope "application folder". The folder + manifest convention…
- [doc-kind-calendar](https://www.vancetope.com/llm/specification/doc-kind-calendar.md): Specifies the `calendar` payload for documents that carry a flat list of events — meetings, deadlines, holidays, recurring activities. The renderer is a Vancetope-internal…
- [doc-kind-canvas](https://www.vancetope.com/llm/specification/doc-kind-canvas.md): First 2D spatial surface in Vancetope: an area where notes, referenced
- [doc-kind-chart](https://www.vancetope.com/llm/specification/doc-kind-chart.md): Specifies the `chart` payload for documents that carry one or more data series with chart-rendering metadata. One kind for all chart types — the…
- [doc-kind-checklist](https://www.vancetope.com/llm/specification/doc-kind-checklist.md): Specifies the `checklist` payload for documents that carry a flat list of actionable items with per-item status — todos, action items from meetings, review…
- [doc-kind-data](https://www.vancetope.com/llm/specification/doc-kind-data.md): Specifies the `data` payload for documents that carry an arbitrary, free-form data tree — objects, arrays, and primitive types. Designed as a container that…
- [doc-kind-diagram](https://www.vancetope.com/llm/specification/doc-kind-diagram.md): Specifies the `diagram` payload for documents that carry a single, text-defined diagram (flowchart, sequence, state, ER, gantt, gitGraph, …) rendered to SVG. The renderer…
- [doc-kind-finance-tree](https://www.vancetope.com/llm/specification/doc-kind-finance-tree.md): Hierarchical financial modeling tool: a tree of income/expense nodes,
- [doc-kind-graph](https://www.vancetope.com/llm/specification/doc-kind-graph.md): Specifies the `graph` payload for documents that carry a (typically directed) graph: top-level `nodes` and `edges` arrays where edges are first-class entities with their…
- [doc-kind-items](https://www.vancetope.com/llm/specification/doc-kind-items.md): Specifies the `items` payload for documents that carry an ordered list of small records — currently the privileged `kind: list`. Defines a single canonical…
- [doc-kind-map](https://www.vancetope.com/llm/specification/doc-kind-map.md): Specifies the `map` payload for documents that carry geospatial features — markers (points), areas (polygons) and routes (polylines). Rendered in the Web-UI with Leaflet…
- [doc-kind-mindmap](https://www.vancetope.com/llm/specification/doc-kind-mindmap.md): Specifies the `mindmap` payload for documents that carry a hierarchical, ordered set of items rendered as a radial mindmap. Reuses the `tree` schema 1:1…
- [doc-kind-records](https://www.vancetope.com/llm/specification/doc-kind-records.md): Specifies the `records` payload for documents that carry a flat, ordered table — a fixed schema in the metadata plus one record per item,…
- [doc-kind-sheet](https://www.vancetope.com/llm/specification/doc-kind-sheet.md): Specifies the `sheet` payload for documents that carry a 2D table with A1 cell addresses — a table with named columns and numbered rows,…
- [doc-kind-slides](https://www.vancetope.com/llm/specification/doc-kind-slides.md): Specifies the `slides` payload for documents that carry a sequence of presentation slides, written as Markdown sections separated by CommonMark thematic breaks (`---`). Renderer…
- [doc-kind-tree](https://www.vancetope.com/llm/specification/doc-kind-tree.md): Specifies the `tree` payload for documents that carry a hierarchical, ordered set of items. Builds directly on the `list` schema — same per-item shape,…
- [doc-kind-workpage](https://www.vancetope.com/llm/specification/doc-kind-workpage.md): Notion-like linear block document. One file = one WorkPage. Markdown superset
- [document-lock](https://www.vancetope.com/llm/specification/document-lock.md): A soft, voluntary edit protection mechanism per document. Each document carries a `lockedFor: Set<WriterRole>` with the blocked Writer classes (`AI`, `USER`, `KIT`); a write…
- [document-templates](https://www.vancetope.com/llm/specification/document-templates.md): A Document Template is a named template from which the web UI generates finished file content when creating a new document. Unlike the previous…
- [document-versioning](https://www.vancetope.com/llm/specification/document-versioning.md): Every overwritten document leaves an archived version. Versions reside in their own Mongo collection, are linked to the active document by a stable `lineageId`,…
- [documents-channel](https://www.vancetope.com/llm/specification/documents-channel.md): Live WS channel `documents`: subscribe/unsubscribe per path, viewer roster
- [eddie-engine](https://www.vancetope.com/llm/specification/eddie-engine.md): Eddie is the Hub Engine — the personal Jarvis-like conversational partner from which the user creates, observes, and controls Projects. Eddie is a regular…
- [events](https://www.vancetope.com/llm/specification/events.md): An Event is an externally triggerable, REST-accessible trigger that starts a workflow run. Events are stored as YAML documents under `_vance/events/<name>.yaml` in the Document…
- [execution-modes-trigger](https://www.vancetope.com/llm/specification/execution-modes-trigger.md): Defines how Think Processes are triggered and how the unified client session model works.
- [fenchurch-service](https://www.vancetope.com/llm/specification/fenchurch-service.md): Vancetope's sole path for newly generated images. Persona: Fenchurch (Arthur Dent's great love, *So Long, and Thanks for All the Fish*) — intuition, creative…
- [file-transfer](https://www.vancetope.com/llm/specification/file-transfer.md): Defines the protocol for transferring files between Foot client and Brain server in both directions. Data lands on the respective receiver's disk (Brain: Workspace-RootDir,…
- [follow-up](https://www.vancetope.com/llm/specification/follow-up.md): REST endpoint that generates context-aware follow-up suggestions from a text fragment plus cursor position. Single-shot, no Process-Spawn — built on the [LightLlmService](light-llm-service.md) with Recipe…
- [fook-service](https://www.vancetope.com/llm/specification/fook-service.md): Built-in bug/feature triage system: a reporter (LLM or User) sends
- [fook-upstream](https://www.vancetope.com/llm/specification/fook-upstream.md): Locally triaged Fook tickets are forwarded to an external ticket system
- [foot-sandbox](https://www.vancetope.com/llm/specification/foot-sandbox.md): Permission gate for the Brain-driven File and Exec Tools of the Foot-CLI. Every incoming `client-tool-invoke` is checked against a central rule policy: `deny` →…
- [ford-engine](https://www.vancetope.com/llm/specification/ford-engine.md): Ford is the full-fledged single-LLM engine — the Guide's field researcher. Quick response, no frills, knows where its towel is: It receives a user…
- [frankie-engine](https://www.vancetope.com/llm/specification/frankie-engine.md): Frankie is the generic Pi-style Executor Engine. It
- [hactar-engine](https://www.vancetope.com/llm/specification/hactar-engine.md): Status: production (v2.0). Hactar is the pure script-execution
- [help-system](https://www.vancetope.com/llm/specification/help-system.md): A generic help subsystem delivers Markdown/text help content from the Brain to the Web UI (and potentially other clients). Content resides as static resources…
- [how-do-i](https://www.vancetope.com/llm/specification/how-do-i.md): A Discovery Tool that allows Engines, when uncertain about the correct procedure, to provide a natural language intent description to an internal `DiscoveryService`. The…
- [identity-credentials](https://www.vancetope.com/llm/specification/identity-credentials.md): Defines the unified account model, how credentials work, and why everything is tied to an account.
- [image-manipulation](https://www.vancetope.com/llm/specification/image-manipulation.md): Pure-Java image processing on existing Document assets. Complements [Fenchurch](fenchurch-service.md): where Fenchurch creates a new image, these tools manipulate an existing one. Implemented as `ImageManipulationService`…
- [inline-and-embedded-content](https://www.vancetope.com/llm/specification/inline-and-embedded-content.md): Defines how structured content (tables, mindmaps, graphs, code, images, PDFs, ...) is displayed in chat messages and document bodies. Two delivery channels, one common…
- [integrationen-externe-systeme](https://www.vancetope.com/llm/specification/integrationen-externe-systeme.md): Defines what Vancetope itself does, what external tools do, and how the connection looks.
- [jeltz-engine](https://www.vancetope.com/llm/specification/jeltz-engine.md): Jeltz is the structured single-shot engine of the Vancetope engine set — the Vogon Constructor Captain who does nothing without a form. It takes…
- [kits](https://www.vancetope.com/llm/specification/kits.md): A Kit is a bundle of Skills, Recipes, Documents, Settings, and Server Tools, imported into a Project from a Git repo. Kits are the…
- [knowledge-graph](https://www.vancetope.com/llm/specification/knowledge-graph.md): How Vancetope not only stores knowledge but maps relationships and actively finds connections from a perspective.
- [light-llm-service](https://www.vancetope.com/llm/specification/light-llm-service.md): A central helper service for single-shot LLM calls using Recipes as configuration profiles. No Process spawn, no Lane lock, no dedicated chat audit trail.…
- [live-ws](https://www.vancetope.com/llm/specification/live-ws.md): Multi-channel envelope protocol for external Vancetope clients (Web, Foot, Mobile)
- [llm-resource-management](https://www.vancetope.com/llm/specification/llm-resource-management.md): Defines how LLM access is managed: providers, keys, quotas, routing.
- [marvin-engine](https://www.vancetope.com/llm/specification/marvin-engine.md): Marvin is the deep-think Engine. It builds a
- [mcp-tool-routing](https://www.vancetope.com/llm/specification/mcp-tool-routing.md): Defines where MCP tools reside (server vs. client), how routing works, and what happens when no client is present.
- [memory-compaction](https://www.vancetope.com/llm/specification/memory-compaction.md): Long Sessions accumulate more chat history than any model's context window can hold. Memory Compaction folds older turns into an `ARCHIVED_CHAT` summary and replays…
- [memory-knowledge-management](https://www.vancetope.com/llm/specification/memory-knowledge-management.md): Defines how knowledge in Vancetope is structured, stored, tagged, and made searchable.
- [mobile-ui](https://www.vancetope.com/llm/specification/mobile-ui.md): Status: v1 Initial Draft. Binding for the development of the mobile app under `repos/vance/client/packages/vance-fingers/`.
- [multi-user-collaboration](https://www.vancetope.com/llm/specification/multi-user-collaboration.md): Defines how Tenants, Teams, Users, and Project Sharing work.
- [permission-system](https://www.vancetope.com/llm/specification/permission-system.md): Vancetope authorizes every access via a narrow, abstract interface
- [plan-mode](https://www.vancetope.com/llm/specification/plan-mode.md): Plan-Mode is Vancetope's mechanism for *exploration-before-execution*
- [pointers-channel](https://www.vancetope.com/llm/specification/pointers-channel.md): Live WS channel `pointers`: subscribe per document path, send your own
- [process-delegate](https://www.vancetope.com/llm/specification/process-delegate.md): A tool that starts a new Think Process without the caller needing to know the Recipe name. Instead, the caller describes the task in…
- [project-kits-catalog](https://www.vancetope.com/llm/specification/project-kits-catalog.md): A tenant-wide catalog of pre-configured Kits, serving as a selection list
- [project-lifecycle](https://www.vancetope.com/llm/specification/project-lifecycle.md): Defines the status set of a Project, Pod ownership, the `bring` / `suspend` / `close` transitions, and the relationship to the Workspace. Complements [workspace-management.md](workspace-management.md)…
- [prompt-caching](https://www.vancetope.com/llm/specification/prompt-caching.md): Anthropic prompt caching for the `vance-brain` LLM layer. Goal: 60–85% token cost reduction for medium to long Sessions, without Engines (Eddie, Arthur, Ford, Marvin,…
- [prompts-and-manuals](https://www.vancetope.com/llm/specification/prompts-and-manuals.md): How Engine and Recipe Prompts stay compact: Capabilities, How-Tos, and domain knowledge reside in Manuals, which the LLM loads on demand via `manual_read('name')`. The…
- [rag](https://www.vancetope.com/llm/specification/rag.md): How Vancetope places documents into a vector index, how the index is synchronized with the Project lifecycle, and how LLM engines query hits from…
- [recipe-routing](https://www.vancetope.com/llm/specification/recipe-routing.md): How a Spawn call reaches a specific Recipe. The standard trio eddie / arthur / ford handles the default path without LLM dispatch; all…
- [recipes](https://www.vancetope.com/llm/specification/recipes.md): A Recipe is a named, reusable blueprint for a worker process: Engine + Default-Params + Prompt-Prefix + Tool-Adjustments. Upon spawn (e.g., by Arthur via…
- [responsive-focus-layout](https://www.vancetope.com/llm/specification/responsive-focus-layout.md): Layout pattern for multi-zone editors with fluid resizing based on user attention. Implemented in `<EditorShell>` (`specification/web-ui.md` §7.2.1) and validated in the pilot in `chat.html`…
- [scheduler](https://www.vancetope.com/llm/specification/scheduler.md): A Scheduler is a time-based trigger definition that spawns a Think Process via a Recipe. Schedulers are stored as YAML documents under `_vance/scheduler/<name>.yaml` in…
- [script-document-api](https://www.vancetope.com/llm/specification/script-document-api.md): Status: v1. Binding product spec for running Cortex scripts to access
- [script-engine](https://www.vancetope.com/llm/specification/script-engine.md): A Script Engine is the JVM-internal runtime for inline code executed by Tools, Engines, or Recipes. v1 provides GraalJS as a Library (JavaScript), encapsulated…
- [server-tools](https://www.vancetope.com/llm/specification/server-tools.md): A Server Tool is a configurable instance of a Tool Type, addressed by Engines/Recipes via its `name`. Server Tool configurations live as YAML documents…
- [session-compact](https://www.vancetope.com/llm/specification/session-compact.md): "Compact" manually triggers the memory compaction of a Session: older chat turns are folded into an `ARCHIVED_CHAT` summary to reduce the context window —…
- [session-crop](https://www.vancetope.com/llm/specification/session-crop.md): "Crop" removes messages from a Session's memory without deleting them.
- [session-duplicate](https://www.vancetope.com/llm/specification/session-duplicate.md): "Duplicate" creates an independent, continuable copy from an existing Session—including the Chat Memory (Chat Process, complete message history, and associated Memory entries such as…
- [session-lifecycle](https://www.vancetope.com/llm/specification/session-lifecycle.md): Defines the status set for Sessions and Engines (Think Processes), the typed lifecycle properties of a Session, the suspend/archive/close behavior depending on the trigger,…
- [setting-forms](https://www.vancetope.com/llm/specification/setting-forms.md): A Setting Form is a named form that configures Settings in a structured way — analogous to [Wizards](wizards.md), but instead of generating a prompt…
- [settings-system](https://www.vancetope.com/llm/specification/settings-system.md): Unified, typed settings system for all configurations.
- [signals-channel](https://www.vancetope.com/llm/specification/signals-channel.md): Live WS channel `signals`: subscribe per document path and receive **ephemeral,
- [skills](https://www.vancetope.com/llm/specification/skills.md): A Skill is a reusable capability bundle focused on a single LLM turn: description + auto-trigger + prompt extension + tool whitelist + reference…
- [slartibartfast-engine](https://www.vancetope.com/llm/specification/slartibartfast-engine.md): Status: Implemented (M0–M6). This spec describes the
- [structure-tool](https://www.vancetope.com/llm/specification/structure-tool.md): The `structure` tool converts unstructured content into a schema-compliant JSON object. Input is a free-text prompt plus a target structure; output is validated JSON.…
- [structured-engine-output](https://www.vancetope.com/llm/specification/structured-engine-output.md): An Engine ends each turn with a mandatory `respond` tool call. This tool call contains the user-facing message plus a boolean flag that explicitly…
- [think-engines](https://www.vancetope.com/llm/specification/think-engines.md): A Think Engine is an interchangeable algorithm. A Think Process is a running instance that operates according to the algorithm of a Think Engine.…
- [tool-availability](https://www.vancetope.com/llm/specification/tool-availability.md): Model for the health status of tools at runtime: when a tool is usable, when it is not, for how long, and why. This…
- [trigger-actions](https://www.vancetope.com/llm/specification/trigger-actions.md): Binding schema for all spawn actions triggered from outside the
- [trillian-engine](https://www.vancetope.com/llm/specification/trillian-engine.md): Trillian is Vancetope's Agentic User Loop — a layer above
- [ursahooks](https://www.vancetope.com/llm/specification/ursahooks.md): Ursahooks are project-specific, lifecycle-event-driven triggers.
- [user-interaction](https://www.vancetope.com/llm/specification/user-interaction.md): How the system communicates with humans when non-chat mechanisms are needed — decision templates, free-text feedback, ordering inputs, structured outputs (texts, images, documents). Plus:…
- [user-notification-channel](https://www.vancetope.com/llm/specification/user-notification-channel.md): Short, attention-grabbing user pings — "BEEP, finished XXX". Separate
- [user-progress-channel](https://www.vancetope.com/llm/specification/user-progress-channel.md): Live status for the user while Engines are working. One message class `PROCESS_PROGRESS` with three payload variants, separate from the authoritative chat stream. Ephemeral,…
- [vance-facelift](https://www.vancetope.com/llm/specification/vance-facelift.md): Status: v1. This spec is binding for the Capacitor shell
- [vision](https://www.vancetope.com/llm/specification/vision.md): What Vancetope is, why it exists, and how it is structured.
- [vogon-engine](https://www.vancetope.com/llm/specification/vogon-engine.md): Vogon is the Think Engine for deterministic multi-phase orchestration. While Arthur reacts and converses with the user, and Ford, as a generalist worker, solves…
- [voice-mode](https://www.vancetope.com/llm/specification/voice-mode.md): Dynamic per-turn toggle that signals Engines (Arthur, Eddie, later Foot-with-TTS): *"User is hearing this response and/or speaking the next input."* Output becomes shorter, long/structured…
- [web-ui](https://www.vancetope.com/llm/specification/web-ui.md): Status: v1 Initial Draft. This spec is binding for the development of the Web-UI under `repos/vance/client/` (symlink `client_web/`).
- [webdav](https://www.vancetope.com/llm/specification/webdav.md): Access to Project documents via WebDAV at `/brain/{tenant}/webdav/{project}/{path...}`. The target is standard clients like macOS Finder (mounted volume) and Obsidian (WebDAV Sync plugin). WebDAV…
- [websocket-protokoll](https://www.vancetope.com/llm/specification/websocket-protokoll.md): Chat-Frame Wire-Format (`WebSocketEnvelope`) between local clients (CLI, Desktop, Mobile) and the Vancetope Brain. This document describes only the inner frame — the outer multi-channel…
- [wizards](https://www.vancetope.com/llm/specification/wizards.md): A Wizard is a named form that guides the user step-by-step through the input parameters of a complex Prompt and, at the end, injects…
- [work-target](https://www.vancetope.com/llm/specification/work-target.md): A WorkTarget describes, per `ThinkProcess`, which backend the
- [workbook-forms](https://www.vancetope.com/llm/specification/workbook-forms.md): Editable, typed forms over a data document plus a server-side executed
- [workflows](https://www.vancetope.com/llm/specification/workflows.md): A Workflow is a project-scoped automation: a state-machine plan of typed tasks (Agent / Shell / Script / Tool / Gate / Timer /…
- [workspace-access](https://www.vancetope.com/llm/specification/workspace-access.md): Defines how the Web-UI accesses a Project's Workspace. Workspaces are pod-sticky (Folder + Snapshots live on a specific Brain process — the Project's Home…
- [workspace-management](https://www.vancetope.com/llm/specification/workspace-management.md): Defines the Workspace of a Project: a container for temporary working files (Git checkouts, temp files, later persistent data) that are *not* persisted as…
- [zaphod-engine](https://www.vancetope.com/llm/specification/zaphod-engine.md): Zaphod is the Multi-Head engine: several independent agents ("heads") work on the same question, and Zaphod synthesizes their views into one answer. While Marvin…
- [zarniwoop-service](https://www.vancetope.com/llm/specification/zarniwoop-service.md): Persona: Zarniwoop (*The Hitchhiker's Guide to the Galaxy*) — the Imperial employee who has an electronic model of the universe in his office. If…

## Optional

- [Specification index](https://www.vancetope.com/llm/specification/index.txt): plain-text URL list of every English spec, for simple crawlers.