AI Context Pack
This file is a lightweight routing index for AI agents.
Purpose
This file is a lightweight routing index for AI agents.
Do not treat it as a second rulebook. AGENTS.md owns strong rules. Open only the documents relevant to the task so routine AI runs do not spend tokens reading the full architecture docs tree.
Language: Follow AGENTS.md → Repository Language (English, except i18n assets). Chat with the project owner in Chinese when requested, but commit repository content in English. Chinese user-facing copy must only live in the formal i18n locale files. Prox OS is English-first for v0.1; exposed language switchers and locale routing stay paused until product, privacy, legal, and payment surfaces are stable enough for multilingual rollout. Do not write Chinese/CJK placeholders into docs, mock data, app copy, or AI guidance; run pnpm check:cjk when touching text-heavy artifacts.
Baseline Read
For most tasks, read:
| Order | Document | Read when |
|---|---|---|
| 1 | AGENTS.md | Always use as the strong rule source. |
| 2 | docs/start-here/project-brief.md | Re-anchor product vocabulary and current platform direction. |
| 3 | docs/platform/architecture/overview/core-architecture-thinking.md | The task touches build, state, tokens, UI boundaries, or cross-cutting runtime design. |
| 4 | One domain document from the sections below | The task has a clear architecture, product, design, or operations domain. |
Execution Modes
Default mode is Direct Implementation Mode. Large task size alone is not enough to trigger Slicing Mode. Do not read or apply RFC, ADR, slicing, phase planning, or proceed-gated workflows during normal development unless the user explicitly asks for them.
For UI incubation, docs, app cards, route surfaces, Storybook, copywriting, mock data, app registry display updates, and lightweight roadmap sync, read only the minimum relevant context and implement in the same run.
Read these only when Opt-in Slicing Mode, RFC Mode, ADR Mode, phase planning, or proceed-gated work is explicitly requested:
| Need | Document | Notes |
|---|---|---|
| Execution mode definitions | docs/development/ai/protocols/ai-execution-protocol.md | Direct implementation and opt-in governance modes. |
| Risk hints | docs/development/ai/protocols/cost-gate.md | Recommend slicing when useful; do not auto-enter it. |
| Slice rules | docs/development/ai/protocols/task-splitting-protocol.md | Opt-in scope-stop and slice planning. |
| Maintainer prompts | docs/development/ai/prompts/prompt-templates.md | Copy-paste prompt patterns. |
| Multi-agent control plane | docs/development/ai-control-plane/README.md | Architect AI, agent scopes, dated task graphs, worker prompts, run logs, integration reports, and release plans. |
| Multi-agent assignment | docs/development/ai-control-plane/architect-ai.md | Read before assigning cross-domain or cross-repo work. |
| RFC workflow | docs/development/rfcs/README.md | Opt-in RFC workflow. |
| ADR workflow | docs/development/adr/README.md | Opt-in ADR workflow; accepted ADRs live under docs/platform/architecture/decisions/. |
| Governance | docs/business/governance/index.md | Governance objects, knowledge-base strategy, contribution lifecycle, and asset ownership. |
| Roles | docs/business/roles/index.md | Human roles and AI agent roles; keep them semantically separate. |
If a task looks high-risk, recommend Opt-in Slicing Mode and explain why, but do not enter it unless the user explicitly confirms. When Opt-in Slicing Mode is activated, announce it at the start so the user can interrupt early.
Collaborative Development
Read when coordinating branches, git worktrees, several Codex/Cursor/local agents, prompt batches, GitHub Issues, PR requirements, merge order, or development quality gates:
| Need | Document | Read when |
|---|---|---|
| Collaborative development overview | docs/development/README.md | Multi-agent or multi-worktree work starts. |
| Worktree and agent model | docs/development/os-collaborative-development-model.md | Coordinating several local agents. |
| Branch and merge rules | docs/development/branch-and-merge-rules.md | Planning PR order or merge safety. |
| Quality gates | docs/development/quality-gates.md | Choosing checks and validation scope. |
| Nx governance | docs/development/nx-first-monorepo.md | Changing root scripts, Nx targets, affected workflows, or project graph governance. |
| Nx validation | docs/development/ai/integrations/nx-agent-workflow.md | Validating multi-project changes through Nx. |
| Prompt batching | docs/development/ai/prompts/codex-prompt-batching.md | Splitting large prompts into serial or parallel tasks. |
| GitHub issue and PR automation | docs/development/ai/integrations/github-issues-prs-agent-workflow.md | Issue-to-agent or PR automation is relevant. |
| AI Control Plane records | docs/development/ai-control-plane/README.md | The user requests opt-in task graphs, run logs, integration reports, or multi-agent orchestration records. |
Domain Routing
Core Architecture (build, state, design system)
Read when changing Rsbuild config, Zustand/Query boundaries, design tokens, os-ui primitives, or explaining where code must live:
| Need | Document | Notes |
|---|---|---|
| Engineering hub | docs/platform/architecture/overview/core-architecture-thinking.md | Links to topic docs and consolidates cross-cutting thinking. |
| Build and render pipeline | docs/platform/architecture/repo/build-and-rendering.md | Rsbuild, Rspack, and shell rendering. |
| State ownership | docs/platform/architecture/data/state-model.md | Zustand, TanStack Query, localStorage, and React local state. |
| Tokens | docs/product/design/tokens.md | CSS variables, Tailwind bridge, and theme changes. |
| Component layering | docs/product/design/component-layering.md | UI primitive boundaries and composition rules. |
| Workspace guide | docs/platform/architecture/repo/monorepo-workspace-guide.md | App/package locations and dev commands. |
Public Shell, SEO, And AI Readability
Read when changing apps/os-shell, public landing pages, prox-os.com route
handoffs, crawler metadata, robots.txt, sitemap.xml, llms.txt, or
search/AI retrieval policy:
| Need | Document |
|---|---|
| Public Shell layer and route handoffs | docs/platform/architecture/runtime/public-website-layer.md |
| Search and AI crawler posture | docs/operations/seo/ai-crawler-policy.md |
| Cloudflare deploy and access boundaries | docs/platform/architecture/operations/cloudflare-deploy-and-access.md |
| Public app and page design language | docs/product/design/app-design-language.md |
Data Surface Packages
Read when changing structured dataset contracts, table/grid primitives, chart primitives, Storybook data surface examples, or Grist/Baserow/Teable/NocoDB/ Univer integration policy:
| Need | Document |
|---|---|
| Data surface contracts | docs/platform/architecture/data/data-surface.md |
| Chart primitives | docs/platform/architecture/media/charting.md |
| Structured data integrations | docs/platform/architecture/data/structured-data-integrations.md |
| Package graph | docs/platform/architecture/repo/package-graph.md |
| App design language | docs/product/design/app-design-language.md |
Media Resource Packages
Read when changing image components, avatars, covers, screenshots, galleries, external link previews, embeds, YouTube wrappers, media allowlists, image transforms, Cloudflare media adapters, or the future OS Media Library:
| Need | Document |
|---|---|
| Image primitives and transforms | docs/platform/architecture/media/media-and-images.md |
| Media resources and embeds | docs/platform/architecture/media/media-resources.md |
| Package graph | docs/platform/architecture/repo/package-graph.md |
| App design language | docs/product/design/app-design-language.md |
Maps And Geospatial Packages
Read when changing map contracts, MapLibre previews, markers, layers, tile provider policy, attribution, map context action intent, PMTiles/R2 planning, Places/geocoding direction, routing/tracks direction, or Spatial Data OS notes:
| Need | Document |
|---|---|
| Map architecture | docs/platform/architecture/media/maps.md |
| Frontend map package | docs/platform/packages/frontend/data/maps.md |
| Package graph | docs/platform/architecture/repo/package-graph.md |
| App design language | docs/product/design/app-design-language.md |
Actions And Interaction Packages
Read when changing shared action contracts, action targets, action context, common actions, action menus, toolbar actions, resource card actions, command contracts, command palette primitives, command providers, keyboard action intent, form contracts, field primitives, validation adapters, schema forms, editor contracts, rich text/markdown/code/prompt adapters, collaboration contracts, presence, threads, mentions, sharing, reviews, notification contracts, badges, toasts, notification center, preferences, search contracts, local search adapters, filters, facets, previews, file contracts, file picker primitives, storage provider boundaries, preview/transfer state, AI UI contracts, AI sessions, messages, tool calls, approvals, artifacts, context sources, citations, model selectors, agent status, security UI contracts, principals, permissions, risk notices, audit rows, sessions, tokens, access reviews, workspace UI contracts, spaces, members, roles, resources, projects, milestones, settings, onboarding, integrations, workspace-aware adapters, activity contracts, actors, targets, objects, events, feeds, timelines, groups, digests, redaction, related resources, or future permission/audit/AI/workspace/ activity runtime integration:
| Domain | Architecture doc | Package or support doc |
|---|---|---|
| Actions | docs/platform/architecture/capabilities/actions.md | docs/platform/packages/frontend/interaction/actions.md |
| Command | docs/platform/architecture/shell/command-system.md | docs/platform/packages/frontend/interaction/command.md |
| Forms | docs/platform/architecture/capabilities/forms.md | docs/platform/packages/frontend/interaction/forms.md |
| Editor | docs/platform/architecture/capabilities/editor-system.md | docs/platform/packages/frontend/interaction/editor.md |
| Collaboration | docs/platform/architecture/capabilities/collaboration-system.md | docs/platform/packages/frontend/interaction/collaboration.md |
| Notifications | docs/platform/architecture/capabilities/notification-system.md | docs/platform/packages/frontend/interaction/notifications.md |
| Search | docs/platform/architecture/capabilities/search-system.md | docs/platform/packages/frontend/interaction/search.md |
| Files | docs/platform/architecture/capabilities/file-system.md | docs/platform/packages/frontend/interaction/files.md |
| AI UI | docs/platform/architecture/ai/ai-ui-system.md | docs/platform/packages/frontend/system/ai-ui.md |
| Security UI | docs/platform/architecture/capabilities/security-ui-system.md | docs/platform/packages/frontend/system/security-ui.md |
| Workspace UI | docs/platform/architecture/spaces/workspace-ui-system.md | docs/platform/packages/frontend/system/workspace-ui.md |
| Activity | docs/platform/architecture/capabilities/activity-system.md | docs/platform/packages/frontend/system/activity.md |
| Package graph | docs/platform/architecture/repo/package-graph.md | Read with any cross-package change. |
| App design language | docs/product/design/app-design-language.md | Read when changing visible app UI. |
OS Shell
Read when changing shell chrome, Desktop Runtime, Studio Engines, windows, routing, shortcuts, Display options, Developer Tools, Architecture App, app registry, or local shell apps:
| Need | Document | Notes |
|---|---|---|
| Platform runtime architecture | docs/platform/architecture/overview/platform-runtime-architecture.md | Global Platform Navigation, Alma, Left Panel, Center Runtime, Inspector, Runtime Command Strip, Runtime Canvas, and new package ownership. |
| Shell visuals | docs/product/design/DESIGN.md, then docs/product/design/os-shell-design-language.md | Spatial/chrome visuals, Scenes, Mission Control, and runtime chrome visuals. |
| Shell workflow skill | .agents/skills/prox-os-shell-workflows/SKILL.md | Use alongside architecture docs for shell behavior changes. |
| Desktop Runtime | docs/platform/architecture/runtime/desktop-runtime.md | /@user/runtime/:runtimeSlug, runtime overlays, app launch/window behavior, Runtime versus Studio terminology, and Universe route boundaries. |
| Studio system | docs/platform/architecture/ai/prox-studio-system.md | /studio, /@user/studios/*, Studio Engines, Studio Surfaces, AI Entry, Projection Contract, and terminology migration. |
| Community shell | docs/platform/architecture/apps/community-shell-entry.md | Community workspace, public discovery, Builder detail drawer, Visitor Mode, and Moments boundary. |
| Desktop spaces | docs/platform/architecture/spaces/desktop-spaces.md | Studio Engine workspace scopes, virtual desktop scope, workspace routes, and engine-switching shortcuts. |
| Alma control plane | docs/platform/architecture/ai/alma-control-plane.md | Platform-level AI control plane, permission chips, Alma modes, workspace overlay boundary, and Community/Visitor context. |
| Alma side panel | docs/platform/architecture/ai/alma-sidecar.md | Alma panel behavior, side panel model, and action contract direction. |
| Cmd+K spatial summoning | docs/platform/architecture/shell/command-palette.md | Summon, Generate, Open, Connect, and Execute posture for the global command surface. |
| Workspace geometry | docs/platform/architecture/spaces/workspace-and-alma.md | Alma layout, resizing, Center Runtime contraction, and workspace geometry. |
| Shortcuts | docs/platform/architecture/shell/shortcut-priority.md | Host, workspace, app, and iframe shortcut ownership. |
| AI actions | docs/development/ai/protocols/os-action-contract.md | Alma Workflow Cards, Action Plan, Operation Log, artifacts, and permissions. |
| Startup flow | docs/development/ai/protocols/os-startup-flow.md | Boot loading, session gates, Hola auto-open, and persisted shell appearance. |
| App registry | docs/platform/architecture/apps/app-registry.md | Registry, launch metadata, app route groups, and runtime app facts. |
| Studio/window sessions | docs/platform/architecture/spaces/space-desktop-window-session.md | Studio sessions, Scenes, workspace naming, owner-scoped URLs, and window session boundaries. |
| Desktop grid | docs/platform/architecture/spaces/desktop-grid-model.md | Desktop item layout, workspace resize behavior, safe areas, and window geometry restore rules. |
| Layout presets | docs/platform/architecture/spaces/window-group-layout-presets.md | Snap presets, selected-window layouts, and Studio-level layout memory. |
| Window manager | docs/platform/architecture/shell/window-manager.md | Window state and window runtime behavior. |
| Shell state | docs/platform/architecture/data/state-model.md | Zustand, TanStack Query, localStorage, and local state. |
| App docs taxonomy | docs/product/apps/README.md | /app-user, /app-track, /app-connectors, /app-sports, /app-os, and /app-hub app documentation. |
Browser persistence: React code in apps/os-shell should use useLocalStorage (usehooks-ts) or the shared browserLocalStore helper for non-React writers; keys are centralized in apps/os-shell/src/browser-local/proxOsLocalStorageKeys.ts.
Trust, Safety, Compliance, And Region Profiles
Read when changing Trust Center, public UGC boundaries, abuse reporting, Prox Cloud hosted-content responsibility, self-hosting responsibility, regional availability profiles, CN Lite constraints, payments abuse posture, or feature availability gates:
| Need | Document |
|---|---|
| Trust and safety overview | docs/trust/trust-safety/overview.md |
| Content policy | docs/trust/trust-safety/content-policy.md |
| UGC launch gate | docs/trust/trust-safety/ugc-launch-gate.md |
| Self-hosting responsibility | docs/trust/trust-safety/self-hosting-responsibility.md |
| Prox Cloud responsibility | docs/trust/trust-safety/prox-cloud-responsibility.md |
| Compliance overview | docs/trust/compliance/overview.md |
| EU GDPR baseline | docs/trust/compliance/eu-gdpr-baseline.md |
| EU privacy readiness | docs/trust/readiness/eu/privacy-policy-readiness.md |
| Global product boundaries | docs/trust/compliance/global-product-boundaries.md |
| CN Lite strategy | docs/trust/compliance/regions/china-lite-strategy.md |
| Regional feature profiles | docs/platform/architecture/regional/region-and-feature-profiles.md |
Product Planning And Roadmap
Read when the user asks what to build next, asks for priorities, says "roadmap", wants to start from the roadmap, or discusses shareable OS Home, public profiles, command palette vs global search, virtual desktops / remix, or admin consoles:
| Need | Document | Notes |
|---|---|---|
| Platform north star | docs/product/strategy/prox-os-platform-vision.md | GitHub -> Hugging Face -> Prox OS analogy, Studio object model, competitor landscape, and platform direction. |
| Competitive landscape | docs/product/strategy/competitive-landscape.md | Overall and module-by-module competitors, references, learning targets, and anti-copy boundaries. |
| Commercial model | docs/product/commerce/pricing-and-commercialization.md | Tiers, first $10K experiments, Studio launch packages, and self-serve versus concierge routes. |
| User archetypes | docs/product/strategy/user-archetypes.md | Early adopters, mid-stage users, later users, and market-entry sequencing. |
| Roadmap index | docs/product/roadmap/README.md | Start here for current roadmap routing. |
| Studio roadmap | docs/product/roadmap/platform/prox-studio-roadmap.md | Studio-specific direction. |
| Product roadmap | docs/product/roadmap/product/product-roadmap.md | Product surface priorities. |
| Platform roadmap | docs/product/roadmap/platform/platform-roadmap.md | Platform foundation priorities. |
| Growth roadmap | docs/product/roadmap/growth/growth-roadmap.md | Growth, launch, and awareness priorities. |
| Combined roadmap snapshot | docs/product/roadmap/product/prox-os-roadmap.md | Continuity context and high-leverage OS affordances. |
| Namespace and domain strategy | docs/product/roadmap/platform/app-namespace-and-domain-strategy.md | App registry, public URLs, subdomains, API explorer access, Moments-style data apps, and creator namespaces. |
| URL and surface model | docs/platform/architecture/routing/url-and-surface-model.md | SurfaceType, Hub versus App versus Folder versus Collection, owner-scoped Store URLs, creator canonical paths, and revenue split ownership. |
| Session and window model | docs/platform/architecture/spaces/space-desktop-window-session.md | StudioSession, Scene, WindowSession, active Studio context, owner-scoped Studio URLs, and app data persistence boundaries. |
| Desktop grid model | docs/platform/architecture/spaces/desktop-grid-model.md | Responsive desktop grids, safe areas, or normalized window geometry. |
| Window group presets | docs/platform/architecture/spaces/window-group-layout-presets.md | Studio/window group layout presets or app-agnostic slot rules. |
| Hub app model | docs/platform/hub-app-model.md | Founder Suite Hub, first-party Hub candidates, Hub bundle packaging, or Hub versus Folder boundaries. |
| Backend object planning | docs/platform/db/os-shell-backend-model.md | User, Organization, Membership, Studio, Surface, InstalledSurface, WindowSession, and first business loop persistence. |
| Future shell appearance | docs/product/roadmap/platform/future-shell-appearance.md | Desktop wallpaper, visual language/chrome presets, or Theme API scope; long-term only. |
| Platform incubation | docs/product/roadmap/platform/platform-incubation-roadmap.md | Design operations, Join Us roles, Storybook expansion, deck-as-code, or future platform tracks. |
| Project brief | docs/start-here/project-brief.md | Product vocabulary and current platform summary. |
For Governance Console, Join Us, Roadmap app, role system, or operating model work, also read:
| Need | Document |
|---|---|
| Internal operating context | docs/business/internal/index.md |
| Team culture | docs/business/internal/team-culture.md |
| Governance model | docs/business/governance/index.md |
| Human and AI roles | docs/business/roles/index.md |
| Readiness index | docs/trust/readiness/index.md |
| Payments readiness | docs/business/payments/index.md |
| Performance posture | docs/operations/performance/index.md |
| Security posture | docs/trust/security/index.md |
| Operations | docs/operations/index.md |
| Business context | docs/business/index.md |
| Contributors | docs/business/contributors/index.md |
| Platform index | docs/platform/index.md |
| Platform vision beyond SaaS | docs/platform/platform-visions-beyond-saas.md |
| Proxied apps | docs/platform/proxied-apps.md |
| Anti-patterns | docs/business/bad-ideas/index.md |
| Decks | docs/go-to-market/decks/index.md |
| Tools | docs/development/tooling/index.md |
Default AI flow:
| Step | Action |
|---|---|
| 1 | Summarize the most relevant current roadmap phase. |
| 2 | Recommend 1-3 small next tasks with priority and rationale. |
| 3 | If the user already picked a concrete task, implement it directly in the same run. |
| 4 | Ask the user to choose only when the task is genuinely open-ended. |
OS Apps
Read when adding or moving apps under /app, /app-user, /app-shell,
/app-admin, /app-dev, /app-iframe, /app-os, or choosing an app category
package under packages/apps/*-apps. packages/apps/system-apps is only for
OS-level apps; personal, connector, developer, admin, game, founder,
community, and hub apps should use their category package. For future
public paths, custom domains, or per-app DNS, read
docs/product/roadmap/platform/app-namespace-and-domain-strategy.md first — do not add
subdomains or backend registry without explicit Opt-in Slicing Mode, RFC Mode,
or an accepted plan.
| Need | Document |
|---|---|
| App UI posture and embed rules | docs/product/design/DESIGN.md and docs/product/design/app-design-language.md |
| Join Us, public app narratives, design tooling doctrine, or text-first design operations | docs/product/design/design-operating-system.md |
| Storybook stories, screenshots, or visual review expectations | docs/product/design/workflow/visual-regression-baseline.md |
| Prox Studio, Studio Gallery, Profile, Developer Console, Connectors Hub, Launcher Hub, Design System Hub, Live Center, Permission Center, MCP Gateway, or commercial OS apps | docs/product/strategy/prox-os-platform-vision.md |
/app-hub/*, /app-os/spaces, /app-os/profile, /app-os/permissions, /app-os/mcp, /app-admin/*, /app-dev/*, /app/awesome-radar, or /app/rss-inbox prototype apps | docs/product/strategy/platform-core-app-prototypes.md |
| Live Center, Visitor App, presence, rooms, multiplayer, collaboration, or Visitor Log concepts | docs/platform/architecture/runtime/live-runtime.md, docs/platform/architecture/media/presence-and-collaboration.md, and docs/trust/privacy/visitor-log.md |
/app-os/governance, /app-os/join-us, or /app-os/roadmap | docs/business/governance/governance-console.md |
| App Store catalog, collection model, Studio templates, or incubating app direction | docs/product/commerce/app-store-collections.md |
| Current UI app competitors and references | docs/product/apps/matrix/ui-app-competitive-matrix.md |
| App, Hub, or Collection surface labels, Store listing doctrine, owner-scoped listing notes, or first-party Hub concept cards | docs/platform/app-store-surfaces.md |
| Platform iframe registry entries | packages/runtime/app-registry/README.md |
| Founder site, iframe URL, or Pages deploy assumptions | docs/operations/deployment/esmadrider-me.md |
| OS app inventory | docs/platform/architecture/apps/os-apps.md |
| App registry | docs/platform/architecture/apps/app-registry.md |
| Package boundaries | docs/platform/architecture/repo/package-boundaries.md |
| Package taxonomy | docs/platform/architecture/repo/package-taxonomy.md |
| Local Module App decision | docs/platform/architecture/decisions/0001-local-module-apps.md |
Package Boundaries
Read when changing imports, packages, workspace scripts, dependency rules, or build graph behavior:
| Need | Document |
|---|---|
| Architecture observability pipeline and generated outputs | docs/platform/architecture/repo/arch-observability.md |
| Package placement | docs/platform/architecture/repo/package-taxonomy.md |
| Dependency boundaries | docs/platform/architecture/repo/package-boundaries.md |
| Package graph | docs/platform/architecture/repo/package-graph.md |
| Refactor guardrails | docs/platform/architecture/repo/refactor-guardrails.md |
| Dependency-cruiser rules | .dependency-cruiser.js |
Backend Package Planning
Read when planning future API contracts, Hono runtime helpers, database packages, auth, permissions, storage, media services, search, jobs, webhooks, agents runtime, audit, billing, observability, or AI-generated backend gates:
| Need | Document |
|---|---|
| Backend foundation | docs/platform/architecture/data/backend-foundation-v0.md |
| Backend package index | docs/platform/packages/backend/index.md |
| Backend package graph | docs/platform/packages/backend/package-graph.md |
| Backend package radar | docs/platform/packages/backend/package-radar.md |
| Backend package boundaries | docs/platform/packages/backend/package-boundaries.md |
| AI-generated backend gates | docs/platform/packages/backend/ai-generated-backend.md |
| Testing strategy | docs/platform/packages/backend/testing-strategy.md |
| API map | docs/platform/architecture/data/api-map.md |
| Data flow | docs/platform/architecture/data/data-flow.md |
Deployment, Cloudflare, And MCP
Read before changing Cloudflare deployment scripts, custom domains, Wrangler configuration, API docs exposure, Access boundaries, or AI/MCP integration assumptions:
| Need | Document |
|---|---|
| Cloudflare deployment and Access | docs/platform/architecture/operations/cloudflare-deploy-and-access.md |
| Operations deployment | docs/operations/deployment.md |
| MCP catalog | docs/development/ai/integrations/mcp-catalog.md |
| Long-term app URL and domain strategy | docs/product/roadmap/platform/app-namespace-and-domain-strategy.md |
API
Read when changing apps/api-worker, API clients, OpenAPI, MSW, Scalar, or server data flow:
| Need | Document |
|---|---|
| Runtime view | docs/platform/architecture/runtime/runtime-view.md |
| API map | docs/platform/architecture/data/api-map.md |
| Data flow | docs/platform/architecture/data/data-flow.md |
| MSW, Hono, OpenAPI, and Scalar decision | docs/platform/architecture/decisions/0003-msw-hono-openapi.md |
App Contract
Read when changing app manifests, window contracts, permissions, data scopes, or future app runtime boundaries:
| Need | Document |
|---|---|
| App contract architecture | docs/platform/architecture/apps/app-contract-view.md |
| Contract source | packages/contracts/app-contract/src/index.ts |
Data And Database
Read when changing schema, migrations, data model, storage, or production database assumptions:
| Need | Document |
|---|---|
| Data view | docs/platform/architecture/data/data-view.md |
| Data model | docs/platform/data/data-model.md |
| Schema decisions | docs/platform/data/schema-decisions.md |
| Database roles | docs/platform/db/roles.md |
| OS Shell backend model | docs/platform/db/os-shell-backend-model.md |
| Desktop surface roadmap | docs/platform/db/space-desktop-surface-roadmap.md |
| Schema source | packages/data/db/src/schema.ts |
UI Primitives And Workshop
Read when changing reusable UI primitives, Storybook, or apps/ui-workshop:
| Need | Document |
|---|---|
| Design entry | docs/product/design/DESIGN.md |
| Component layering | docs/product/design/component-layering.md |
| UI primitive exports | packages/ui/os-ui/src/index.ts |
| Shell chrome visuals | docs/product/design/os-shell-design-language.md |
| Color, radius, shadow, or density variables | docs/product/design/tokens.md |
| UI workshop | apps/ui-workshop/README.md if present |
Rsbuild
Read when changing build config, dev server, assets, or bundle diagnostics:
| Need | Document |
|---|---|
| Rsbuild best practices | .agents/skills/rsbuild-best-practices/SKILL.md |
| Shell build config | apps/os-shell/rsbuild.config.ts |
Product Facts
| Fact | Guidance |
|---|---|
| Product identity | Próx OS is a cloud-first, AI-native Studio platform for developers, creators, teams, and communities, not a marketing website. |
| Brand spelling | Use Próx OS for brand display, Prox OS for ASCII-only prose, and prox-os / @prox-os/* for code. |
| Current route to value | The current product route is cloud-first, GitHub-first, RSS-first, and AI Context-first. |
| Strategic analogy | GitHub is where code lives; Hugging Face is where models, datasets, and demos live; Prox OS explores where personal AI-native workspaces, OS apps, data sources, and AI contexts live. |
| Long-term object model | The object model is Studio, App, Dataset, Source, AI Context, and Workflow; do not treat it as a current database schema or API contract. |
| App Store boundary | The App Store is an incubation entry for apps, templates, Studios, data sources, and AI workflows; the runtime registry is still the source of truth for what can actually open. |
| Commercial core | The commercial core is Studio + Connector + Permission + MCP Gateway. Do not reduce Pricing to a generic SaaS plan page or imply live billing before it exists. |
| Website mode | Website mode uses /website route suffixes. |
| Fullscreen app sessions | Fullscreen app sessions still use the historical /spaces/:spaceId runtime route until the backend Studio route model replaces it. |
| Spaces route boundary | Treat /spaces/:spaceId as a current runtime route, not the product model for new Studio resources. |
| Current priority | Prove Awesome GitHub Radar, then RSS Knowledge Inbox, then AI Context Builder. |
| Early narrative | Paste an awesome GitHub repo. Get a living Studio. |
| Core platform prototypes | Core /app-os platform prototype routes are documented in docs/product/strategy/platform-core-app-prototypes.md; they are static UI prototypes until later MVP slices replace the mock flows. |
| Runtime route preservation | /app-os/* runtime routes should be preserved. Future published app canonical paths such as /@prox-os/apps/hola and App Store listings such as /apps/@prox-os/hola should be metadata bindings, not runtime route replacements. |
| Store listing URLs | App Store listing URLs for concrete apps, hubs, and collections should be owner-scoped under /apps/@owner/:slug; published app canonical URLs should use /@owner/apps/:slug. Do not default to global ownerless aliases. |
Shell route groups are registry-driven:
| Route group | Purpose |
|---|---|
/app/* | Personal work, data, and creative apps. |
/app-user/* | User/profile/visitor/preference surfaces. |
/app-track/* | Personal tracking primitives such as People, Places, Devices, Money, Sources, and AI Context. /app-data/* is a deprecated compatibility alias. |
/app-connectors/* | External connector apps for imports, sync readiness, permission previews, source status, and future MCP tool surfaces. |
/app-shell/* | Shell-coupled system apps that remain inside apps/os-shell. |
/app-admin/* | Internal admin operating cockpit for real OS administration, operations, users, waitlist, feedback, audit, permissions, jobs, storage, and billing readiness. |
/app-dev/* | Local development tools, API docs, contracts, mock scenarios, Storybook, Scalar, architecture graphs, route maps, and debugging surfaces. |
/app-iframe/* | External and standalone Proxied Apps hosted inside managed shell windows; iframe is the current implementation detail. |
/app-os/* | Reusable OS, official team, community, developer, and platform operations apps. |
/app-hub/* | Productized vertical Hub surfaces and OS-native cockpit workspaces. |
Do Not Assume
| Assumption to avoid | Correct posture |
|---|---|
| All architecture docs need to be read for every task. | Read the smallest relevant doc set. |
| The OS Shell should copy macOS or Windows. | Follow Prox OS design docs and current shell constraints. |
| shadcn/ui is required for shell chrome. | Use existing shell primitives and tokens unless a task calls for otherwise. |
| NocoDB is the runtime data API. | Treat structured data integrations as references until architecture says otherwise. |
| Future apps all stay in the shell bundle. | App extraction and runtime hosting should follow package boundary docs. |