Prox OS Roadmap

This is the legacy combined roadmap. For new planning, prefer:

• docs/roadmap/README.md
• docs/roadmap/product-roadmap.md
• docs/roadmap/platform-roadmap.md
• docs/roadmap/growth-roadmap.md
• docs/product/prox-os-positioning.md
• docs/product/app-store-collections.md
• docs/product/platform-capabilities.md

Use this file for continuity, historical context, and high-leverage OS affordances that have not yet moved into a focused roadmap.

Prox OS is not a generic website, a Notion clone, a Puter clone, an n8n clone, or a Dify clone.

It is an OS Home and Space Layer for builders, creators, and communities. Its purpose is to organize scattered apps, data, workflows, and AI context into a browsable, runnable, shareable, permission-aware operating space.

This roadmap is both a product document and an AI-readable guidance document. It should help human maintainers and AI coding agents understand where the project is going without turning every future idea into an immediate implementation task.

Roadmap Maintenance Rules

Roadmap items should not be deleted after implementation.

Use this lifecycle:

Planned -> In Progress -> Done -> Archived Notes / Release History

Rules:

• Keep completed roadmap items visible under the relevant version.
• Mark completed items with checkboxes.
• Add completion notes when useful.
• Do not keep old finished items inside the active work queue forever.
• Move detailed implementation notes into architecture docs when the feature becomes stable.
• Keep the roadmap strategic, not a task dump.

AI Planning Workflow

This file is the primary source for product priority prompts.

When a user asks an AI agent "what should we build next", "roadmap priority", or a similar planning question, the agent should:

1. Read this roadmap before recommending work.
2. Identify the current phase and the smallest useful next step.
3. Prefer work that strengthens the OS Shell, app contract, developer workflow, and data-aware foundation before adding broad product surface area.
4. Recommend 1-3 prioritized tasks with a short rationale, expected files or domains, and quality checks.
5. Wait for explicit user confirmation (e.g. "go ahead", "proceed", or "implement that") before editing code.
6. After confirmation, read the relevant architecture docs from docs/ai/context-pack.md, then implement only the selected task.

The default answer should not be a long backlog. It should be a practical next move that can be reviewed as a small diff.

Recommended public roadmap versioning:

v0.1, v0.2, v0.3, ...

Recommended package / npm versioning:

0.0.x while APIs are unstable
0.1.0 for the first usable alpha package line
1.0.0 only after public compatibility guarantees exist

Recommended release tag style:

v0.1.0, v0.2.0, v0.3.0

Do not use v0.100 style numbering. Use v0.10 or v0.10.0 when the roadmap naturally reaches that stage.

Product Thesis

People already use many tools:

• Vercel / Netlify for deployed apps
• GitHub for code and projects
• Notion / Obsidian for knowledge
• NocoDB / Airtable / Postgres for structured data
• n8n / Dify for workflows and agents
• Puter and other Web OS projects for cloud apps
• Cloudflare for domains, edge runtime, storage, security, and observability
• PostHog for product analytics, events, funnels, and user behavior analysis

Prox OS does not force users to migrate everything into one closed platform.

Instead, Prox OS provides:

• an entry layer
• a space layer
• a data relationship layer
• a community curation layer
• a permission protocol
• an AI context layer
• an observability layer for both product usage and system health

The early product should help users create an OS Home that can collect, present, launch, and gradually operate their existing digital assets.

Core Positioning

Prox OS turns scattered apps, links, datasets, dashboards, and workflows into an AI-operable OS Home.

It should be able to answer:

• What apps does this user or community use?
• What datasets are available?
• Which spaces are public or private?
• Which apps can access which data?
• Which dashboards summarize which datasets?
• Which workflows or AI actions are allowed?
• What should be embedded, launched externally, or shown as a preview card?
• Which product events indicate activation, retention, or monetization?

Non-Goals

Prox OS should not try to replace every existing tool.

Early non-goals:

• Do not build a full cloud drive.
• Do not build a full Notion replacement.
• Do not build a full n8n or Dify replacement.
• Do not build a full code hosting platform.
• Do not run arbitrary user code in containers at the beginning.
• Do not assume every external app can be embedded in an iframe.
• Do not expose a public API gateway before app permissions and tenant boundaries are stable.
• Do not rebuild PostHog, Cloudflare Analytics, Sentry, or GitHub Actions inside Monitor App too early.

App Integration Modes

External and community apps must support multiple integration modes.

1. Embed in Window

The app can be rendered inside a Prox OS window, usually through iframe or a local system app module.

Use this for:

• local dev tools
• self-owned apps
• apps with compatible CSP / frame settings
• docs
• dashboards
• static spaces

Requirements:

• lazy load by default
• sandbox iframe where possible
• do not preload every app on desktop startup
• unload or freeze closed windows
• handle load failure visibly

2. Open in New Tab

Some apps cannot or should not be embedded.

Use this for:

• apps that block iframe embedding
• apps with complex login flows
• external SaaS dashboards
• sensitive admin panels
• apps with strict CSP or X-Frame-Options

The OS window may show a launch screen with metadata, status, and a button to open externally.

3. Preview Card + External Launch

When embedding is not available, Prox OS should still provide a useful card.

A preview card may include:

• title
• description
• favicon
• screenshot
• owner
• tags
• last opened time
• health status
• external URL
• related space
• related dataset
• related workflow

This allows Prox OS to act as a high-quality launcher and public OS Home even when deep integration is not possible.

Browser Homepage Roadmap

Prox OS may become a browser start page in the future, but this is not an early requirement.

Stages:

1. Public OS Home as a normal website
2. PWA installable app
3. Bookmarkable daily launcher
4. Browser new tab extension
5. Full daily OS homepage

Performance rules for homepage mode:

• load shell and metadata first
• do not eagerly load all iframes
• restore previous workspace lazily
• preload only pinned apps
• freeze background windows
• keep startup path small

Observability and PostHog

PostHog should be introduced early as a lightweight product analytics layer, but Monitor App should not try to clone the PostHog dashboard at the beginning.

Recommended install command:

pnpm add posthog-js @posthog/react

Recommended environment variables:

VITE_POSTHOG_KEY=
VITE_POSTHOG_HOST=

Rules:

• Public frontend project tokens may be exposed through Vite env variables.
• Personal API keys must never be exposed to the browser.
• Any future PostHog Query API usage must go through apps/api-worker or another trusted backend worker.
• Monitor App v0 should link out to PostHog, Cloudflare, GitHub Actions, Sentry, and other external dashboards.
• Monitor App v1 should show first-party Prox OS events collected by the platform itself.
• Monitor App v2 may proxy selected PostHog analytics through a backend API.

Early events:

app_opened
app_closed
iframe_loaded
iframe_load_failed
external_app_launched
preview_card_clicked
space_created
space_published
dataset_created
dashboard_opened
roadmap_doc_opened

Product activation events:

create_first_space
add_first_external_app
add_first_preview_card
add_first_dataset
publish_first_space
share_first_space

Retention events:

open_os_home_again
launch_external_app_again
revisit_space
edit_space
open_monitor_app

Conversion events:

connect_custom_domain
create_private_space
use_ai_context_pack
invite_member
upgrade_plan_clicked

Nx Adoption

Prox OS started with a pnpm workspace and Turborepo-style task orchestration. As the project grows into multiple apps, packages, OS apps, docs, API worker, CLI, SDK, and architecture tools, Nx should be adopted incrementally for project graph visibility, affected tasks, dependency boundaries, and long-term AI-readable monorepo governance.

Recommended init command for an existing pnpm workspace:

pnpm dlx nx@latest init

Adoption principles:

• Do not rewrite the whole repo just to adopt Nx.
• Keep pnpm workspace as the package linking foundation.
• Keep Turborepo only if it still provides value; otherwise gradually let Nx become the main task runner.
• Add Nx first for task running, caching, and project graph.
• Add stricter boundary rules only after the app and package structure is stable.
• Use Nx graph as a system app candidate inside Prox OS.

Expected future usage:

pnpm nx graph
pnpm nx affected -t build
pnpm nx affected -t test
pnpm nx run os-shell:dev

AI coding agents should use Nx graph and affected tasks to understand the blast radius of changes before performing large refactors.

Prox.js

Prox.js is the runtime SDK for apps running inside or alongside Prox OS.

Package:

packages/prox-js

Package name:

@prox-os/prox-js

Primary goal:

Prox.js should let apps communicate with Prox OS without importing shell internals.

It should provide access to:

• OS context
• current space
• current user permission scope
• window actions
• data query actions
• AI context actions
• app-to-shell messaging
• iframe bridge
• permission requests

Example future usage:

import { connectProx } from '@prox-os/prox-js'

const prox = await connectProx()

await prox.window.open('dataset.viewer', {
  datasetId: 'bookmarks',
})

const rows = await prox.data.query('bookmarks', {
  limit: 50,
})

const summary = await prox.ai.summarize({
  dataset: 'bookmarks',
  scope: 'current-space',
})

Development stages:

Stage 0: No public SDK

System apps can use internal shell APIs while the app contract is unstable.

Stage 1: Internal runtime

Create a runtime abstraction used by official OS apps.

Stage 2: Iframe bridge

Allow iframe apps to communicate with the shell through a controlled message bridge.

Stage 3: Public Prox.js alpha

Expose a small SDK for app developers.

Stage 4: Prox.js v1

Stabilize APIs after multiple official and community apps use the SDK.

Prox CLI

The Prox CLI is the developer tool for initializing, validating, inspecting, and publishing Prox-compatible apps and spaces.

Package:

packages/prox-cli

Package name:

@prox-os/cli

Binary:

prox

Root script during local development:

{
  "scripts": {
    "prox": "tsx packages/prox-cli/src/index.ts"
  }
}

Recommended command priority:

pnpm prox init
pnpm prox validate manifest
pnpm prox inspect permissions
pnpm prox mock api
pnpm prox dev app
pnpm prox build app
pnpm prox publish space
pnpm prox create app

The CLI does not replace Vite, Rsbuild, Next.js, Turborepo, or Nx.

Instead, it wraps existing app templates and injects Prox OS requirements:

• app manifest
• permission declaration
• iframe bridge
• Prox.js starter
• preview card metadata
• AI-readable README
• local dev URL
• app validation
• publishing metadata

The first public CLI feature should probably be prox init, not prox create app.

Reason:

Most developers already have projects. Prox OS should be able to make existing Vite, Rsbuild, Next.js, Astro, or static apps compatible with Prox OS instead of forcing everyone to start from a Prox-specific template.

Template examples:

templates/app-iframe-vite
templates/app-iframe-rsbuild
templates/app-static-space
templates/app-system

dev.prox-os.com

dev.prox-os.com should become the developer home for Prox-compatible apps, spaces, SDKs, and validation tools.

It should not start as a separate large product. Early versions can be docs-first and link-driven:

• app contract documentation
• Prox.js examples
• CLI installation and prox init flow
• app manifest examples
• iframe bridge guidance
• permission model guidance
• local development URLs and templates
• API explorer and Scalar links
• compatibility checklist for embedding, external launch, and preview cards

Recommended early shape:

dev.prox-os.com
-> docs for app developers
-> app contract reference
-> Prox.js / CLI quickstart
-> manifest validator direction
-> examples and templates

Do not make dev.prox-os.com depend on unstable private shell internals. It should document and exercise the public app contract, CLI, Prox.js, iframe bridge, and validation flow.

Future examples:

pnpm prox init
pnpm prox init --from ./existing-app
pnpm prox init --template vite
pnpm prox init --template rsbuild
pnpm prox create app --template vite
pnpm prox create app --template rsbuild
pnpm prox create app --template next

AI Context Layer

AI should not understand Prox OS through long prompts alone.

AI should read structured context packs.

Core objects:

• Dataset
• Table
• Card
• Dashboard
• Space
• App
• Workflow
• PermissionGrant
• AuditLog

Each Space should eventually produce an AI Context Pack.

Example:

{
  "space": {
    "id": "builder-os-home",
    "title": "Builder OS Home",
    "visibility": "public"
  },
  "datasets": [],
  "cards": [],
  "dashboards": [],
  "apps": [],
  "allowed_ai_actions": ["summarize", "classify", "suggest-dashboard", "generate-space-readme"],
  "forbidden_ai_actions": [
    "publish-private-data",
    "call-external-api-without-permission",
    "send-message-without-confirmation"
  ]
}

AI coding agents should preserve these boundaries:

• do not bypass app contract
• do not deep-import shell internals from OS apps
• do not mix remote server data into local OS UI state
• do not preload all apps
• do not assume iframe embedding always works
• do not create hidden permissions
• do not expose private data in public spaces

Core Growth Mechanisms

Prox OS should grow through visible user-created spaces, not through a vague platform pitch.

Growth loops:

1. Public OS Home Loop

user creates OS Home
-> user adds apps, links, datasets, dashboards, workflows
-> user shares public OS Home
-> visitors discover Prox OS
-> visitors create their own OS Home

2. Space Template Loop

creator builds a useful space
-> Prox OS turns it into a reusable template
-> other users fork / remix the template
-> original creator gets visibility
-> more creators publish templates

3. Featured Curation Loop

community creates spaces
-> Prox OS curates featured spaces, apps, datasets, dashboards, and workflows
-> featured creators get traffic
-> more creators want to publish on Prox OS

4. Made with Prox OS Loop

public space shows subtle badge
-> visitors click badge
-> Prox OS landing page explains OS Home
-> visitor creates or forks a space

Early growth assets:

• Featured Spaces
• Featured Apps
• Featured Datasets
• Featured Dashboards
• Featured Workflows
• Creator OS Homes
• Fork / Remix
• Space Templates
• Custom Domains
• Embeddable Preview Cards
• Made with Prox OS badge

High-leverage OS affordances

This section is AI- and maintainer-facing: a durable place to extend “what users will play with” without inflating Platform Phases tick lists. Implementations still land in normal versions (mostly v0.3 shell + API, v0.5 identity, v0.7–v0.9 hosted + social).

Command palette (e.g. Cmd+K) vs global search

Keep these distinct products:

Rule: Extend Cmd+K with more commands and better grouping; add global search as a separate mode or parallel entry (e.g. Cmd+Shift+K / dedicated panel) once indexes + ACL exist. Do not collapse “search the world” into the command list without a real retrieval layer.

Shareable OS Home (public profile + rich space)

North star: Every user’s OS Home has a stable URL (like a GitHub profile) but feels composable and app-rich (like Hugging Face Spaces — many surfaces, deep customization).

View modes (conceptual, enforce server-side):

1. Anonymous / signed-out visitor — sees only published apps and public data cards; no private datasets; iframe apps obey manifest visibility flags.
2. Owner signed in — sees full private + public layout, all windows, all linked data, edit/publish controls.
3. Signed-in guest (“friend”) — sees published shell plus assets shared explicitly to that identity (per-viewer ACL): not “everyone’s public,” but their slice of your home (unique shared data per relationship).

Implications for architecture (do not implement all at once):

• URL routing must distinguish public home vs private edit vs impersonated read-only preview.
• Data plane (Neon from v0.3 onward) needs space_id, asset ACLs, share tokens or relationship rows before this is real — preview UI can ship earlier with static or mock ACLs.
• “GitHub-like” = identity URL, README/bio strip, follower-ready public layer.
• “Spaces-like” = multiple pinned apps, demos, and curated layouts that still run in browser (iframe + local).

Virtual desktops, “tour others’ desks,” fork to mine

• Virtual desktops — multiple workspace layers each with its own window set (see v0.3 shell personalization in Platform Phases).
• View another user’s public desk — read-only replay of published layout + allowed apps (no private window state). Ties to shareable OS Home and Monitor/telemetry for abuse.
• Clone / remix — copy a published workspace template (layout + app manifest references, not private data) into the viewer’s home; aligns with Space Template growth loops and v0.9 community flows. Exact legal/quotas TBD.

High-leverage checklist (prioritize for “feels like an OS”)

Use this list in planning chats; tick items into Platform Phases when committing work.

• Notifications center that clears, deep-links to windows, surfaces iframe/API failures.
• Global search (once index + ACL) separate from command palette (see above).
• Theme / density presets on top of design tokens (dark, compact, contrast).
• Layout persistence — folders, icon positions, workspace snapshots; Neon sync when prefs API exists.
• Unified clipboard / drag-in story (start with links + text across windows).
• Workspace snapshot export (image or shareable layout JSON) for social proof.
• Permissions / privacy surface — “what this home exposes” visible to owner and visitors.
• Shareable URL + per-viewer data — core product differentiator (requires v0.5+ identity and ACL model).

Admin and “management system” for builders of Prox OS

Do you need it now? Not as a full product. Today, Developer Tools, Architecture App, Monitor links, pnpm arch:*, and Cloudflare dashboards cover builder diagnostics. A unified admin console becomes worth it when you have paid tenants, abuse, support impersonation, or RBAC across many spaces — roughly late v0.7+ for platform ops, with small space-level admin earlier.

When to start (suggested):

• v0.4 — operational hooks only: CI, deploy visibility, health (already roadmap).
• v0.5 — user-facing “account & security” and space publish/ACL primitives — can live in /app-user / Profile flows, not a separate giant admin app at first.
• v0.7+ — platform admin (moderation, billing overrides, feature flags per tenant) if you operate multi-tenant hosted homes.

Ship as a sub-app? Yes. Register a local-module or os-package app (e.g. under /app-os for Platform Admin, /app-dev for internal-only builds). It should not duplicate:

• Feature flags / kill switches — one store (env + DB), one reader API.
• User / session model — single api-worker + Neon schema; admin only calls privileged routes.
• Analytics — link PostHog / first-party events; don’t rebuild charts in v0.
• Registry and manifest truth — Architecture App stays the read-mostly registry explorer; admin adds mutations (approve app, suspend space) only if product requires.

Reuse: OpenAPI-defined admin routes on api-worker, TanStack Query for server state, app-contract for any admin-facing permission enums, same shell window + keyboard patterns as other OS apps.

Platform Phases

v0.1 — Local OS Shell Foundation

Summary: v0.1 delivers a credible local Próx OS desktop inside the monorepo: windowing, shell chrome, an early app catalog, shortcuts and commands, and shared UI primitives—plus repo hygiene so the codebase stays navigable as surface area grows.

Status: mostly done (ongoing polish is normal).

Monorepo and quality gates

• pnpm workspace + Turborepo tasks as the default script path.
• apps/os-shell — React + Rsbuild browser “OS” runtime.
• ESLint / TypeScript baselines; refactor guardrails and dependency policy.
• Dependency Cruiser (.dependency-cruiser.js) + pnpm arch:check for package-boundary discipline.
• Large-file awareness (pnpm check:file-size / Nx-oriented reporting).
• Nx workspace (graphs, affected tasks, Nx Cloud hookup).

Shell UX and window model

• Desktop scene, dock, top bar / shell bar, context menus, loading screen.
• Window manager: open / close / minimize / maximize, desktop icon grid, window overview transforms.
• Global shortcuts — command surface, app switcher, “close other apps”, platform-appropriate labels.
• View mode toggle and related shortcuts.
• Display options — backgrounds, screensaver, overlay placement, notification corner, panel preferences.
• Mobile mode presets and floating menus tied to shell layout.

First apps (mostly shell-era before deeper package extraction)

• Early registry-driven apps: e.g. Notifications, Deploy (registration story), Visitor, Resume, Assets, ChatOS, Keyboard Shortcuts, Architecture (later evolved with graphs — see v0.2).
• Shell affordances: Personal button, AI assistant entry, active apps / command navigation.

Shared UI and data-hygiene direction

• packages/os-ui — reusable shell primitives; no Zustand / app i18n in package code.
• TanStack Query wired for remote data; React Query Devtools in dev; local OS state stays in Zustand.
• Storybook / UI Workshop (apps/ui-workshop) for component work outside shell runtime.

Documentation and AI workflow

• Docs tree, Fumadocs app (pnpm dev:docs), product/architecture entry points.
• AGENTS.md + docs/ai/context-pack.md as the default agent routing contract.
• React Scan and other diagnostics hooks where useful for shell performance work.

Still allowed in v0.1 (small diffs, no new platform pillars):

• Shell / desktop polish without changing package boundaries.
• Tighten lint rules and dependency graphs after refactors.
• Roadmap and architecture doc maintenance.

Deferred out of v0.1 (moved to later phases): MSW mock system (v0.3), iframe guest protocols and extracted OS apps (v0.2).

v0.2 — Local System Apps and Iframe Integration

Summary: v0.2 turns the shell into an integration-ready platform: neutral app-contract, reusable os-apps, a registry-driven routing model, a production-grade iframe host, supporting packages (app-registry, design-tokens), and a real guest app (esmadrider-me)—including the same managed link menu (new tab / open in Prox OS) for links inside iframes as on the desktop surface.

Status: foundation shipped; preview-card integration mode and deeper telemetry remain incremental.

Contract, packages, and registry

• packages/app-contract — implementation-neutral manifests (local-module, os-package, iframe, route-app, etc.), runtime context types, window/settings/keyboard/dialog surfaces (no client router imports).
• packages/os-apps — official apps moved out of shell internals; manifests + shared primitives; no imports from apps/os-shell/src/shell/** or private window-manager paths.
• Shell app registry — registry.ts, ShellAppId, local render maps, route groups /app, /app-user, /app-shell, /app-dev, /app-iframe, /app-os, plus fullscreen behavior.
• @prox-os/app-registry — iframe-oriented manifest templates and helpers so external-ish apps can be described consistently (e.g. dev localhost URLs, naming).
• @prox-os/design-tokens — shared tokens consumed by UI surfaces; typecheck/lint integrated like other packages.

Iframe runtime and guest app

• IframeAppHost — sandboxed iframe, load/health/fetch path, offline fallback, fallbackCommand / toolbar actions for dev recovery.
• apps/esmadrider-me — Vite guest site, embedded in Prox OS via registry; production vs dev base URL handling and companion pnpm dev:os-with-esmadrider-me (or equivalent) workflow.
• Iframe ↔ shell managed links — guest postMessage PROX_OS_IFRAME_GUEST_LINK / prox-os:guest-link (contract types + validation), shell maps pointer position and opens openManagedLinkMenuAt (same UX as desktop); guests opt out with data-prox-os-skip-managed-link where navigation must stay in-guest or _top.

Developer experience and observability

• Developer Tools and Developer Route Map system apps; AppRuntime diagnostics improvements.
• Architecture App — package/app registry/window observability for maintainers.
• pnpm arch:* pipeline + docs/architecture/generated/ (see arch-observability.md); project graph from Nx/lockfile-style workflows.
• API boundary docs — apps/api-worker with OpenAPI/Scalar exposure; docs app mirrors product API direction.

Shell hardening adjacent to integration

• Routing and navigation context refinements for OS apps (memory routing where appropriate).
• Local storage discipline — logout, reset managed local storage, floating menu behavior tied to shell settings.

Partial / next increment (still v0.2 themes):

• Preview card + external launch — generalized product UI for non-embeddable apps (not only iframe fallback screens).
• Three integration modes as first-class UX — embed is strong (local + iframe + os-package); managed link menu covers “open in new tab” vs “open in Prox OS” for many links; remaining work is consistent entry points from every manifest/flavor and card-first flows.
• Iframe load failure — visible fallbacks exist; broaden telemetry, copy, and optional Monitor App surfacing.
• Dev-only commands — extend fallbackCommand and devtoolbar consistency across all iframe/dev manifests.

v0.3 — Serverless Data Plane, Mock Parity, and Observability

Summary: Make remote data and product observability first-class without a fake “local-only database forever” story: apps/api-worker uses Neon Postgres via packages/db + Drizzle as the default serverless DB for real routes. MSW remains for browser dev / tests and shape parity with OpenAPI — it does not replace Postgres for wrangler dev or deployed Workers. Add TanStack Query discipline, optional shell personalization (folders, virtual desktops) that can sync once prefs APIs exist, plus PostHog-class analytics and Monitor surfaces.

Baseline already in the tree (v0.3 builds on this, does not re-litigate it):

• apps/api-worker — Hono + @hono/zod-openapi + Scalar reference; deploy via Wrangler (pnpm deploy:api).
• packages/db — Drizzle + Neon PostgreSQL direction (see repo conventions).
• TanStack Query in shell with dev-only React Query Devtools; Zustand reserved for local OS/window state (see AGENTS.md).
• msw present under apps/os-shell — handlers and dev bootstrap still need to be canonical (see below).

Neon / serverless Postgres (platform persistence v0)

• api-worker → Neon — Worker-safe driver (e.g. Hyperdrive + pooled Postgres, or Neon serverless driver); no deferred “turn on DB in v0.5” for new platform APIs.
• Migrations — Drizzle migrations in-repo; apply to dev/staging/prod Neon branches/projects (document environments).
• First tables — whatever v0.3 endpoints need (e.g. user prefs / layout snapshots, feature flags, registry hints); full auth/user rows arrive in v0.5 on the same Neon project.
• Dev ergonomics — documented switch: MSW-only shell vs real Worker + Neon (avoid silent divergence).

API contract and mock parity

• Treat OpenAPI / Zod route definitions in api-worker as the authoritative contract for v0.3-era endpoints (expand routes incrementally; document versioning assumptions).
• MSW handler set (dev and optional test/e2e) generated or hand-maintained to match that contract — same shapes as production responses; avoid one-off mock JSON drift.
• Shell dev experience: one clear switch — e.g. “mock API” vs “real wrangler dev API” — documented in docs/ai/context-pack.md or deployment docs.
• Optional: thin typed client or shared request/response types pulled from the same source as OpenAPI (codegen or manual re-export) to reduce stringly-typed fetch.

Client data layer discipline

• Query key conventions and mutation invalidation rules for shell-owned queries (naming, scope per app, no giant blobs in cache).
• Error and loading UX at shell boundaries (toasts, inline retry, “API unavailable” tied to iframe/API health where relevant).
• No Zustand for server data — audit or lint guidance for new features (document anti-pattern in architecture notes).

Shell personalization (incremental; local-first, then Neon sync)

• Custom desktop layout — user-created folders, icon grouping, placement; persist locally first, then optional sync via api-worker once Neon-backed prefs endpoints exist.
• Virtual desktops (workspaces) — several desktop contexts, each with its own window set; Ctrl+Shift+Up (and companion chords, e.g. Down or Arrow cycle) switches workspace; ship together with Keyboard Shortcuts app entries and window-manager state design (document in docs/architecture/window-manager.md when stabilized).

Product analytics (PostHog or equivalent)

• Event catalog — lifecycle (session_start), navigation (app_open, route_change), iframe (iframe_load_success / iframe_load_error), managed links (managed_link_open_external / managed_link_open_shell), errors (client_error).
• Environments — dev/staging/prod keys; sampling; no PII in event properties by default; document in privacy-facing docs when public.
• Wire PostHog (or chosen vendor) in apps/os-shell first; keep package boundaries (no analytics imports inside packages/os-ui).

Monitor App v0 and operator visibility

• Monitor / Observability system app (or extend Architecture App) with curated external links — PostHog project, Cloudflare dashboards, Worker logs, error tracking — plus read-only summaries where API allows (e.g. last deploy, health).
• Correlation IDs or request ids from api-worker for debugging (header convention + docs).

Telemetry targets called out in earlier roadmap

• Iframe load failures — structured client events + optional breadcrumb to IframeAppHost state (already user-visible; make measurable).
• App launches — count by ShellAppId / manifest kind; distinguish local vs iframe vs os-package.

v0.4 — CI/CD, Cloudflare Deploy, and Nx-Aware Governance

Summary: Nx + pnpm workspace baseline already landed in v0.1–v0.2 (graphs, affected tasks, Nx Cloud). v0.4 focuses on automation: every meaningful push runs verify + build in GitHub Actions, then publishes the right Cloudflare surfaces (Pages / Workers) so staging or production updates without manual wrangler runs from a laptop.

GitHub Actions → build many projects → Cloudflare refresh

• Workflows on pull_request and push (protected branches): install pnpm, cache store, pnpm install --frozen-lockfile, pnpm lint, pnpm typecheck, pnpm build (or nx affected for lint, typecheck, build once targets are aligned).
• Multi-target Cloudflare deploy (secrets via GitHub Actions secrets / environments):
  • Workers — apps/api-worker via wrangler deploy (existing pnpm deploy:api).
  • Pages — e.g. apps/os-shell (existing deploy:os pattern: pnpm --filter @prox-os/os-shell build + wrangler pages deploy …), apps/esmadrider-me, apps/docs if/when each has a production Pages project.
• Branch previews where product needs them (Pages preview deployments per PR, or a single staging project).
• Idempotency and failure semantics — failed job does not partial-publish; document rollback (Cloudflare dashboard / previous deployment pin).
• Optional: Nx Cloud in CI for distributed cache and flaky-task insight (already optional locally).

Ongoing governance (original v0.4 themes)

• Nx affected as the default path for large refactors (full build on main merges; affected on PRs when safe).
• Tighten dependency boundary rules as new packages stabilize (depcruise / ESLint boundaries; align with AGENTS.md).
• Expose Nx Graph in Architecture App or devtools only if it still pulls its weight next to existing pnpm arch:* reports.

Planning lens: v0.5–v1.0 (questions → release themes)

Each v0.x here is a theme spanning many PRs (weeks–months), not a single feature flag. Avoid planning one microscopic v0.x.0 per ticket; also avoid stuffing auth + payments + MF + proxy into one release.

Phase intentions (single-screen)

• v0.5 = who is the user + space protocol — auth product and multi-account chrome on top of Neon already live from v0.3; Space/Dataset protocol v0, shell aligned with account.
• v0.6 = how builders ship — Prox.js, CLI, templates, one integration handbook; not the large marketplace yet.
• v0.7 = hosted product + money — public/private spaces, sharing, real payments and entitlements, backup and subdomains deliverable in slices. For app identity vs DNS, prefer app-namespace-and-domain-strategy.md (creator-owned paths; infra subdomains only) before defaulting to per-app *.prox-os.com.
• v0.8 = deep integration — Module Federation, API forward/proxy, enterprise-style trust boundaries.
• v0.9 = ecosystem surface — featured content, community catalog, experimental marketplace and creator flows.
• v1.0 = commitments + migration — contract semver, upgrade guide.

v0.5 — Identity, Multi-Account, and Space Protocol v0

Summary: First product-level auth and multi-account Prox OS on the Neon data plane introduced in v0.3: signup/login, session and account switcher in shell chrome (Profile / account menu — switch anytime without treating it as a rare edge case), plus Space/Dataset/App manifest v0 and permission sketches. v0.5 does not introduce Postgres for the first time — it adds user/tenant tables and auth flows on the existing Worker + Neon path.

Typical scope (chunked inside the release, not one PR):

• Auth: email magic link and/or OAuth providers; session model; secure httpOnly patterns where applicable; CSRF/CORS discipline documented.
• Data: extend v0.3 migrations with user / workspace / space (and multi-session if product requires); dev/staging/prod policy unchanged in spirit; align with future SpaceManifest fields.
• Shell: account-aware profile entry, multi-account list + switch, preference sync boundaries, logout vs “reset local” semantics; Visitor vs signed-in flows clarified; update Keyboard Shortcuts if global account actions are added.
• AI / privacy: context pack shape v0 (what is allowed in prompts vs forbidden); no wholesale ingestion of private space data without permission hooks.
• App/Dataset/Card/Dashboard manifests: define JSON shapes + validation even if not all subtypes live in UI yet.

v0.6 — Prox.js, CLI, and the Integration Handbook

Summary: Turn v0.2 integration reality into repeatable builder UX: @prox-os/prox-js alpha, prox CLI (init, validate, maybe dev helpers), scaffolds (iframe guest + os-package starters), and published integration docs — one place for “how to ship an app that runs in Prox OS”.

Does not duplicate v0.2: contract types and iframe guest-link remain defined in v0.2; v0.6 packages, documents, and generates from that truth.

Typical scope:

• prox init / prox validate against manifest + permission declarations.
• Developer portal stub (dev.prox-os.com or docs section): quickstarts, troubleshooting, CSP/iframe checklist.
• Templates maintained in-repo and tested in CI (v0.4) so they don’t rot.

v0.7 — Hosted OS Home, Sharing, and Paid Surface

Summary: Internet-facing OS Home: public/private spaces, sharing links, backups/export basics, subdomains (optional early), and real payments — checkout, webhooks, entitlements (e.g. paid templates, seat/space limits, premium AI pack) — staged so first SKU can ship before full domain/branding depth.

Typical scope:

• Profile / public home, external app cards, analytics hooks from v0.3 operationalized for product not only ops.
• Billing provider integration; feature flags keyed off subscription/entitlement; admin/Developer Tools never bypass billing in prod.
• Custom domains / team spaces / deeper branding can follow first revenue path in the same phase without blocking a smaller initial launch.

v0.8 — Federated UI and API Mesh (Proxy)

Summary: Advanced app loading and controlled outbound API: Module Federation (or equivalent remote module loading) for trusted apps; api-worker as forward/proxy to third-party APIs with scoped credentials, rate limits, audit logs, and allowlists — so sub-apps do not hold third-party secrets in the browser.

Typical scope:

• MF: remote entry discovery, version pins, fallback when remote fails, security review checklist.
• Proxy: signed app_id + user/session context on Worker; OAuth token vault pattern on server; abuse prevention.

Guardrail: public open relay to arbitrary URLs is a non-goal until permission and quota models are mature.

v0.9 — Community Catalog and Ecosystem Scale

Summary: Discovery and social proof: featured spaces/apps/datasets/workflows, fork/remix, early marketplace experiments, creator visibility — after v0.7 can onboard and charge safely.

Typical scope:

• Curated lists, badges, “Made with Prox OS”, submission/review workflow (manual first).
• Scale integration docs from v0.6 with live examples and templates maintained by community (moderation policy documented).

v1.0 — Stable Public Contract

Summary: Semver-ish promises across app-contract, Space/permission models, Prox.js, and CLI; migration guide from v0.x; compatibility policy for hosted homes and billing.

Typical scope:

• Freeze or intentionally version breaking surfaces; deprecation windows.
• Security review of v0.8 proxy and MF patterns before stamping 1.0.

Commercial Direction

Early paid features should be simple:

• custom domain
• private spaces
• premium templates
• AI context pack generation
• analytics
• team spaces
• hosted space backup

Avoid selling a vague “Web OS platform” too early.

The first sellable product should be:

Builder OS Home: a beautiful, shareable home for a builder’s apps, links, datasets, dashboards, docs, and workflows.

Public vs Private Roadmap

This document can be committed to the repository because it describes product and architecture direction.

Do not put sensitive founder-only details here, such as:

• private revenue targets
• tax planning
• immigration strategy
• personal financial runway
• unreleased competitive tactics
• private investor notes
• confidential customer information

Use a separate private note or private repository for founder-only planning.