Pilot Concept

Status: Draft Last Updated: 2026-02-17

This document describes the high-level concept and vision for Pilot.

Vision

Pilot is an AI-native workspace platform that brings AI capabilities to organizations while keeping users in control of their data.

Core belief: AI interactions should produce files you own, not data locked in a SaaS.

Analogies

Obsidian for AI - Local-first, file-based, extensible, but with AI superpowers and organizational controls.

What we're not:

• Not ChatGPT (conversations locked in a platform)
• Not Cursor (developer-only, code-focused)
• Not a chatbot widget (AI is the primary interface, not an add-on)

Core Principles

1. File-Based

Everything is files:

• Knowledge bases are folders of markdown, JSON, YAML
• AI artifacts are saved as files (reports, summaries, code)
• Sessions can be exported as markdown
• Configuration is files (rules, skills, settings)

Formats: Markdown, Mermaid, JSON, YAML, tldraw, and others with good viewer/editor UX.

2. Layered Control

Three levels with inheritance:

Organization
└── Workspace
    └── User

3. Storage-Runtime Separation

Storage: Persistent, survives sessions

• Primary: Pilot's R2 storage or organization's S3
• Sync: Bidirectional with Google Drive (selected folders)
• Future: Local device (desktop app)

Runtime: Ephemeral, spins up on demand

• Container with AI execution capabilities
• Mounts persistent storage
• Dies after session (or idle timeout)
• No state in runtime - all state in storage

4. Use-Case Driven

Workspace types control complexity:

Non-technical users see a simple interface. Complexity is opt-in via workspace type.

5. Extensible via Skills

Skills are CLI tools that extend AI capabilities:

• Organization IT/AI teams author custom skills
• Pilot provides a marketplace of default skills (hosted on GitHub)
• Skills install to workspace (downloaded, with org/workspace/user hierarchy)

Example: Jira skill with jira-cli - user says "create a ticket for this bug" and AI uses the skill.

Hierarchy Model

Organization

• Multi-tenant SaaS entity
• Owns: API keys (Anthropic, OpenAI, etc.), billing, members
• Configures: Global rules, global skills, workspace defaults
• Storage: R2 (default) or custom S3

Every user has an implicit personal organization for individual use.

Workspace

• Owned by an organization
• Collection of folders and files (replacing abstract "project" concept)
• Has a type (document, knowledge, development)
• Access levels: private, shared (specific members), public (org-wide)
• Edit permissions: manage, edit, view

Structure (system layer - hidden or toggleable):

.pilot/
├── config.json       # Workspace settings
├── rules/            # System prompts, constraints
├── skills/           # Installed skills
└── cache/            # Temporary data

Structure (user layer - visible):

workspace/
├── sessions/         # Saved chat sessions (markdown)
├── sync/             # Folders synced to Google Drive
└── [user folders]/   # Whatever user creates

User

• Single account across organizations
• Profile per organization
• Belongs to 1+ organizations
• Personal preferences (theme, etc.)
• Personal rules (additive only)

Data Model

Sessions

• Stored in database (not files) for:
  • Query performance (search across sessions)
  • Real-time sync (multiple devices)
  • Structured metadata
  • Integration (notifications, etc.)
• Exportable as markdown files
• Can be saved to workspace sessions/ folder

Knowledge

• Files the AI can reference to answer questions
• Lives in organization or workspace level
• Integration layer for external sources:
  • One-way sync from Google Drive
  • Summarize website/YouTube as markdown

Rules/Prompts

• Instructions for how AI should behave
• Organization sets global + per-workspace rules
• Users can add personal rules (cannot override org rules)
• Examples: tone, constraints, coding style

Skills

• CLI tools that extend AI capabilities
• Distribution: Pilot marketplace (GitHub), org private, git repos
• Merged across layers, deduplicated by name
• Downloaded to workspace on install

Collaboration Model

Real-Time by Default

For edit access, collaboration is real-time:

• Users see the same live state (like Google Docs)
• Git is infrastructure, not user-facing (for non-dev workspaces)
• "Sarah is editing" / "Last edited by John 2 hours ago"

Technical consideration: Real-time requires reliable sync infrastructure:

• rclone/rsync for storage sync
• WebSocket or Cloudflare Durable Objects for live presence
• Conflict resolution strategy

Sharing

• Workspaces: private, shared, or organization-wide
• Access levels: manage, edit, view
• Within org only (no external sharing in v1)

Storage & Sync

Source of Truth by Use Case

Sync Strategy

Priority: Pilot ↔ Google Drive (bidirectional)

• Selected folders sync bidirectionally
• Not for active editing (sync, not real-time collab)
• Enables sharing with non-Pilot users

Future: Pilot ↔ Local device (desktop app)

AI Provider Model

Organization-Level Keys

• API keys always belong to organization
• Organization can have multiple providers (Anthropic, OpenAI, etc.)
• Model preferences: org configures available models per workspace
• User selects from available models

Layered AI Setup

User Experience Abstraction

Non-technical users shouldn't see infrastructure:

Open Questions

1. Workspace visibility toggle - Should system layer (.pilot/) be hidden+accessible or fully invisible?
2. Skill hierarchy - Exact override/merge semantics for org → workspace → user skills
3. Ephemeral storage use cases - When (if ever) should storage be ephemeral? (Currently: only sandboxed code execution)
4. Desktop app timeline - When does local device sync become priority?

Related Documents

• Architecture: @plan/ARCHITECTURE.md
• Roadmap: @plan/ROADMAP.md (to be created)
• Product Personas: @plan/product/PERSONAS.md
• Product Features: @plan/product/FEATURES.md