The mental model

PocketPi becomes simpler when you follow ownership instead of implementation files. The Agent owns intent and its workspace; an App owns domain behavior and durable product state; PocketJS executes bounded JavaScript and renders the fixed View; the native host owns trusted mechanisms.

Start with actors, not layers

Then learn the three App parts

Data
  durable App-owned SQLite/files

Actions
  named behavior shared by Agent Tools, UI events and schedules

View
  fixed PocketJS interface projected from bounded Data

Projection is the Data-to-View binding. It has no independent durable state, so it is not a fourth App concept. A View may keep small in-memory presentation state, but SQLite remains the durable product truth.

Follow one Action through the system

1. Admission: a Tool route, UI event or App schedule selects a local Action name.
2. Execution: the Action Guest validates arguments and may call allowed native services.
3. Persistence: PocketPi.data.transaction() writes App-owned SQLite.
4. Invalidation: a successful commit increments an in-memory App revision.
5. Projection: only a visible stale View re-runs its bounded queries at a frame boundary.
6. Rendering: PocketJS reconciles the fixed View and the host displays its DrawList.

The Agent never calls an update_view Tool. It changes product state through an Action; the View follows the App revision and projects the resulting Data.

What “resident” changes

Pi Agent's Agent loop and Root View share one System Guest created at boot. Opening an ordinary App changes which View owns the display and input; it does not destroy the Agent, its pending model request or its Tool registry. Ordinary View and Action Guests are bounded and may be evicted, so durable state cannot live only in JavaScript objects.

What runs where

Device hardware
└── target OS / RTOS and native host
    ├── credentials, transport, storage enforcement, lifecycle
    ├── AppSupervisor, routing, schedules and recovery
    └── PocketJS / QuickJS platform
        ├── resident Pi Agent System Guest
        ├── ordinary View Guests
        └── ordinary Action Guests

This is where the RTOS boundary belongs: as one implementation layer beneath the product runtime. App developers normally work above it. Host developers use it when providing the native composition for a target.

Current versus target

Deep implementation detail lives in docs/agentos-architecture.md ↗.