AI Context Pack

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). User chat may be any language; committed artifacts stay English. AI replies may match the user’s chat language. 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:

AGENTS.md
docs/architecture/project-brief.md
docs/architecture/core-architecture-thinking.md when the task touches build, state, tokens, UI boundaries, or cross-cutting runtime design
One domain document from the sections below

AI Execution Governance (Cost Gate)

Read before large or ambiguous implementation work:

docs/ai/ai-execution-protocol.md — Triage, RFC, Plan, Patch, Verify, Docs Sync modes
docs/ai/cost-gate.md — S / M / L / XL and trigger words
docs/ai/task-splitting-protocol.md — slice rules and scope-stop
docs/ai/prompt-templates.md — copy-paste prompts for maintainers
docs/rfcs/README.md — when an RFC is required
docs/adr/README.md — single decisions; existing ADRs under docs/architecture/decisions/

Rule: For L / XL tasks, output Triage (or RFC/Plan) and wait for explicit confirmation before editing implementation files.

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:

docs/architecture/core-architecture-thinking.md (hub — links to topic docs)
docs/architecture/build-and-rendering.md
docs/architecture/state-model.md
docs/design/tokens.md
docs/design/component-layering.md
docs/architecture/monorepo-workspace-guide.md for app/package locations and dev commands

OS Shell

Read when changing shell chrome, desktop, windows, routing, shortcuts, Display options, Developer Tools, Architecture App, app registry, or local shell apps:

Design entry: docs/design/DESIGN.md, then docs/design/os-shell-design-language.md for spatial/chrome visuals (includes Spaces / Mission Control).
.agents/skills/prox-os-shell-workflows/SKILL.md
docs/ai/os-startup-flow.md when changing boot loading, session gates, Hola auto-open, or persisted shell appearance
docs/architecture/app-registry.md
docs/architecture/window-manager.md
docs/architecture/state-model.md

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.

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:

docs/roadmap/README.md
docs/roadmap/product-roadmap.md
docs/roadmap/platform-roadmap.md
docs/roadmap/growth-roadmap.md
docs/roadmap/prox-os-roadmap.md for legacy combined context and High-leverage OS affordances
docs/roadmap/app-namespace-and-domain-strategy.md when designing app registry, public URLs, subdomains, API explorer access, Moments-style data apps, or creator namespaces (candidate direction — not a final contract)
docs/architecture/project-brief.md

Expected AI flow:

Summarize the most relevant current roadmap phase.
Recommend 1-3 small next tasks with priority and rationale.
Ask which task to start, unless the user already picked one.
When the user confirms (e.g. "go ahead" or "proceed"), read the relevant domain docs and implement only that selected task.

OS Apps

Read when adding or moving apps under /app, /app-user, /app-shell, /app-dev, /app-iframe, /app-os, or preparing extraction to packages/os-apps. For future public paths, custom domains, or per-app DNS, read docs/roadmap/app-namespace-and-domain-strategy.md first — do not add subdomains or backend registry without RFC.

docs/design/DESIGN.md and docs/design/app-design-language.md for app UI posture and embed rules
docs/product/app-store-collections.md when changing the App Store catalog, collection model, Space templates, or incubating app direction
packages/app-registry/README.md when adding or changing platform iframe registry entries (esmadrider-me, dev localhost apps)
docs/deployment/esmadrider-me.md when changing the founder site, iframe URL, or Pages deploy assumptions
docs/architecture/os-apps.md
docs/architecture/app-registry.md
docs/architecture/decisions/0001-local-module-apps.md

Package Boundaries

Read when changing imports, packages, workspace scripts, dependency rules, or build graph behavior:

docs/architecture/arch-observability.md — pnpm arch:* observability pipeline and docs/architecture/generated/ outputs
docs/architecture/package-graph.md
docs/architecture/refactor-guardrails.md
.dependency-cruiser.js

Deployment, Cloudflare, And MCP

Read before changing Cloudflare deployment scripts, custom domains, Wrangler configuration, API docs exposure, Access boundaries, or AI/MCP integration assumptions:

docs/architecture/cloudflare-deploy-and-access.md
docs/operations/deployment.md
docs/ai/mcp-catalog.md
docs/roadmap/app-namespace-and-domain-strategy.md for long-term app URL and domain strategy

API

Read when changing apps/api-worker, API clients, OpenAPI, MSW, Scalar, or server data flow:

docs/architecture/runtime-view.md
docs/architecture/api-map.md
docs/architecture/data-flow.md
docs/architecture/decisions/0003-msw-hono-openapi.md

App Contract

Read when changing app manifests, window contracts, permissions, data scopes, or future app runtime boundaries:

docs/architecture/app-contract-view.md
packages/app-contract/src/index.ts

Data And Database

Read when changing schema, migrations, data model, storage, or production database assumptions:

docs/architecture/data-view.md
docs/data/data-model.md
docs/data/schema-decisions.md
docs/db/roles.md
packages/db/src/schema.ts

UI Primitives And Workshop

Read when changing reusable UI primitives, Storybook, or apps/ui-workshop:

docs/design/DESIGN.md
docs/design/component-layering.md
packages/os-ui/src/index.ts
docs/design/os-shell-design-language.md when visuals must match shell chrome
docs/design/tokens.md when changing color, radius, shadow, or density variables
apps/ui-workshop/README.md if present

Rsbuild

Read when changing build config, dev server, assets, or bundle diagnostics:

.agents/skills/rsbuild-best-practices/SKILL.md
apps/os-shell/rsbuild.config.ts

Product Facts

Próx OS is a cloud-first personal intelligence OS for developers, creators, and AI-native workers, not a marketing website.
Use Próx OS for brand display, Prox OS for ASCII-only prose, and prox-os / @prox-os/* for code.
The current product route is cloud-first, GitHub-first, RSS-first, and AI Context-first.
The App Store is an incubation entry for apps, templates, Spaces, data sources, and AI workflows; the runtime registry is still the source of truth for what can actually open.
Shell route groups are registry-driven:
- /app/*: personal work, data, and creative apps.
- /app-user/*: user/profile/visitor/preference surfaces.
- /app-shell/*: shell-coupled system apps that remain inside apps/os-shell.
- /app-dev/*: developer-only local tools, docs, project graphs, and API explorers.
- /app-iframe/*: external and standalone iframe apps hosted inside managed shell windows.
- /app-os/*: reusable OS, official team, community, developer, and platform operations apps.
Website mode uses /website route suffixes; true fullscreen app Spaces use /spaces/:spaceId.
True fullscreen apps are dedicated Spaces routed as /spaces/:spaceId; do not reuse website-mode route semantics for OS fullscreen behavior.
Current priority: prove Awesome GitHub Radar, then RSS Knowledge Inbox, then AI Context Builder.

Do Not Assume

Do not assume all architecture docs need to be read for every task.
Do not assume the OS Shell should copy macOS or Windows.
Do not assume shadcn/ui is required for shell chrome.
Do not assume NocoDB is the runtime data API.
Do not assume future apps all stay in the shell bundle.

AI Context Pack

On this page