Glossary

Terms and concepts used throughout the Pilot codebase.

Package Naming

Directory vs. npm Name

Directory Path	npm Package Name	Description
`@core/ai`	`@repo/ai`	AI CLI commands
`@core/base`	`@repo/base`	Domain modeling
`@core/query`	`@repo/query`	Query builder
`@core/lint`	`@repo/lint`	ESLint config
`@core/typescript`	`@repo/typescript`	tsconfig presets
`@core/ui`	`@repo/ui`	Core UI components
`@packages/chamber-ui`	`@repo/chamber-ui`	OpenChamber UI
`@packages/frontend`	`@repo/frontend`	RuntimeAPIs adapters
`@packages/backend`	`@repo/backend`	Hono app factory
`@packages/domain`	`@repo/domain`	Domain models
`@packages/shared`	`@repo/shared`	Shared contracts
`@services/app`	`@pilot/app`	Main web app
`@services/gateway`	`@pilot/gateway`	API gateway
`@services/chamber`	`@pilot/chamber`	Chamber frontend
`@services/runtime`	`@pilot/runtime`	Runtime orchestrator

Naming Convention

@core/* and @packages/* use @repo/ npm scope (internal packages)
@services/* and @demos/* use @pilot/ npm scope (deployable artifacts)

Architecture Terms

Planes

Term	Definition
Control Plane	`@pilot/gateway` - handles auth, session, routing decisions
Runtime Plane	`@pilot/runtime` - executes workloads, manages instances
App Plane	`@pilot/app` - hosts browser application

Canonical Package

A package that is the authoritative owner of a specific domain. Other packages should not duplicate its functionality.

Example: @repo/backend is the canonical owner of RuntimeAdapter interface.

Adapter

An implementation that bridges two interfaces. Used for:

RuntimeAdapter: Bridges backend to runtime (LocalAdapter, MockAdapter)
RuntimeAPIs: Bridges frontend to backend (terminal, files, git adapters)

Tier-1 / Tier-2 Endpoints

Tier	Definition	Examples
Tier-1	Critical endpoints required for core functionality	terminal, fs, git, session, health
Tier-2	Supporting endpoints, can be added incrementally	github, push, skills, quota, tts

Tier-1 parity gates migration decisions.

Upstream Terms

Upstream

The external source repository that Pilot packages derive from.

Upstream	Repository	Our packages
OpenChamber	github.com/btriapitsyn/openchamber	chamber-ui, frontend, backend
OpenCode	@opencode-ai/sdk	Used as dependency

Baseline

The specific upstream version we're tracking. Currently: v1.6.8

Divergence

Any change from upstream. Categories:

Integration glue: New files for Pilot integration
Bug fix: Fixes that could be upstreamed
Feature addition: Pilot-specific features
Intentional removal: Upstream features we don't use

Manifest

A document recording a sync event with upstream. Located in @plan/sync/openchamber/manifests/.

Code Annotations

@pilot:divergence

// @pilot:divergence embedded prop for app integration
export function App({ embedded = false }: AppProps) {

Marks code that intentionally differs from upstream. Include reason.

@pilot:note

// @pilot:note this may conflict with upstream 1.6.9 ContextPanel feature

Marks code that needs attention or has context not obvious from code alone.

Service Status Terms

Status	Definition
Active	In production or active development
New	Recently created, being built out
Deprecated	Scheduled for removal, should not add features
Decommissioned	Removed, no longer exists

Plan Terms

Term	Definition
Plan	An execution plan for a specific goal
Task	A unit of work within a plan
Phase	A group of related tasks
P0/P1/P2	Priority levels (P0 = immediate, P2 = can wait)
Superseded	Plan replaced by a newer plan

Runtime Terms

RuntimeAPIs

The interface that chamber-ui uses to communicate with the backend. Defined in @repo/frontend.

interface RuntimeAPIs {
  runtime: RuntimeDescriptor
  terminal: TerminalAPI
  git: GitAPI
  files: FilesAPI
  settings: SettingsAPI
  permissions: PermissionsAPI
  notifications: NotificationsAPI
  github?: GitHubAPI
  push?: PushAPI
  tools: ToolsAPI
}

RuntimeAdapter

The interface that backend uses to communicate with runtime instances. Defined in @repo/backend.

interface RuntimeAdapter {
  identity: RuntimeIdentity
  capabilities(): Promise<RuntimeCapabilities>
  health(): Promise<RuntimeHealth>
  proxy(request: Request, targetPath: string): Promise<Response>
}

Instance

A running OpenCode process in an isolated environment (container, worker, etc.).

Orchestrator

The component that manages instance lifecycle (create, destroy, health check).

Build Terms

Catalog

Centralized dependency versions in pnpm-workspace.yaml. Use catalog:<name> in package.json.

Workspace Reference

Use workspace:* to reference local packages in package.json.

Abbreviations

Abbrev	Full	Context
FE	Frontend	`@repo/frontend`, browser code
BE	Backend	`@repo/backend`, server code
CF	Cloudflare	Cloudflare Workers deployment
SSE	Server-Sent Events	Real-time streaming
SDK	Software Development Kit	@opencode-ai/sdk
ADR	Architecture Decision Record	Documented decision
POC	Proof of Concept	Demo/experiment