---
url: https://pencel.ai/docs/concepts/under-the-hood.md
description: >-
  How Pencel works under the hood — compiling plain-language workflows into safe
  runnable plans, schema-driven dynamic UI, and building a knowledge graph from
  your local files.
---

# Under the hood

You don't need any of this to use Pencel — but if you're curious *why* it behaves the way it does, three ideas explain most of it.

## Compiler-based workflows

When you [Build](/concepts/chat) a workflow, Pencel keeps three jobs separate: it **plans** with a model, **compiles** that plan into concrete runnable steps with *no* model (deterministic and repeatable), then **runs** it as a guarded briefing the agent follows. Guardrails are enforced by the system, runs use a frozen snapshot, and Pencel checks what actually happened afterward.

There's a lot to this — see the dedicated **[Agentic compiler & runtime](/concepts/compiler-runtime)** page for how each stage works and why it's built this way.

## Dynamic UI

Some of what you see isn't hardcoded screens — it's **generated from structured data**, which is why new capabilities can show up without a new app version.

* **Interactive panels during a run.** When an agent needs a decision or structured input, it requests a panel — an approval prompt, a confirmation, a review, or a rich form with dates, quantities, and line items — and pauses until you respond. These panels are described by a schema and validated before rendering, not free-form UI.
* **Data-driven Pulse cards.** Records that workflows produce (opportunities, drafts, and other pack-specific items) render through a single generic card driven by a **descriptor** — which fields to show, which [Pulse](/concepts/operations) tab they land in, and what one-click action they offer. A solution pack adds a descriptor, not a new screen, so its records appear automatically once it's installed.

The everyday app chrome — sidebar, settings, editors — is ordinary, fixed UI. "Dynamic" applies to these schema- and record-driven surfaces.

## Building a knowledge graph from your files

When you connect a local folder as a [Knowledge](/concepts/knowledge) vault, Pencel does two distinct things:

1. **Imports the documents.** It walks the folder and stores each file as a searchable document, tracking changes so re-syncing only touches what changed. This part is fast, and your edits in-app are preserved on the next sync. Retrieval runs on a **keyword/full-text index** — grounded in the literal content of your files.
2. **Builds the graph — in the background.** Separately, and without blocking you, Pencel reads through new or changed sources and extracts the **entities** (people, projects, organizations), **claims** (facts stated about them), and **relationships** it finds, linking each back to the source document as evidence. Over time this forms a graph you can browse, and that agents can traverse when answering.

Graph building is deliberately conservative — it prefers to extract nothing over inventing connections — and it runs incrementally as your files change (a periodic refresh, on by setting). The result is a picture of your workspace built from your own material, with every claim traceable to the file it came from.

## What's next

* [Workflows](/concepts/playbooks) — the workflows the compiler produces
* [Run mode](/concepts/chat) — where interactive panels appear
* [Knowledge](/concepts/knowledge) — connect a folder and explore the graph
* [Pulse](/concepts/operations) — where data-driven cards surface