AI-readable Index
Fast file and document index for AI agents. **Do not duplicate** AGENTS.md rules or full essays from [core-architecture-thinking.md](./core-architecture-thinkin
Purpose
Fast file and document index for AI agents. Do not duplicate AGENTS.md rules or full essays from core-architecture-thinking.md. Use context-pack.md for read order.
Start Here
| Priority | Document | Use when |
|---|---|---|
| 1 | AGENTS.md | Strong rules, checks, package boundaries |
| 2 | docs/ai/context-pack.md | Task-specific doc routing |
| 3 | docs/architecture/core-architecture-thinking.md | Build, state, tokens, UI layers, anti-patterns |
| 4 | docs/architecture/project-brief.md | Product summary |
| 5 | docs/architecture/monorepo-workspace-guide.md | Which app/package to open, dev commands |
AI Execution Governance
For large AI-assisted changes, agents must follow Cost Gate, RFC workflow, and task splitting before modifying implementation files.
Read first:
docs/ai/ai-execution-protocol.mddocs/ai/cost-gate.mddocs/ai/task-splitting-protocol.mddocs/rfcs/README.mddocs/adr/README.md
Architecture Docs (by topic)
| Topic | Document |
|---|---|
| Monorepo apps & packages | monorepo-workspace-guide.md, package-graph.md |
| Cloudflare deploy & Access | cloudflare-deploy-and-access.md, ../operations/deployment.md |
| Build / Rsbuild / React 18 | build-and-rendering.md |
| Shell boot & login | ../ai/os-startup-flow.md |
| App registry & routes | app-registry.md, app-contract-view.md |
| Windows & Spaces | window-manager.md |
| State boundaries | state-model.md |
| Data flow & API | data-flow.md, api-map.md, runtime-view.md |
| OS apps package | os-apps.md |
| Generated graphs | arch-observability.md |
| Refactor / lint rules | refactor-guardrails.md |
| ADRs | decisions/ |
| App URLs / domains (roadmap) | ../roadmap/app-namespace-and-domain-strategy.md |
| MCP catalog & safety | ../ai/mcp-catalog.md |
Roadmap (identity & routing)
| Topic | Document |
|---|---|
Creator-owned paths, appId, subdomains | ../roadmap/app-namespace-and-domain-strategy.md |
| Roadmap index | ../roadmap/README.md |
Design Docs
| Topic | Document |
|---|---|
| Design entry | ../design/DESIGN.md |
| Tokens & Tailwind | ../design/tokens.md |
os-ui layering | ../design/component-layering.md |
| Shell chrome | ../design/os-shell-design-language.md |
| App interiors | ../design/app-design-language.md |
| Agent design discipline | ../design/ai-design-workflow.md |
Key Source Paths
| Area | Path |
|---|---|
| Shell entry | apps/os-shell/src/index.tsx |
| Registry | apps/os-shell/src/apps/registry.ts |
| Cmd+K apps | apps/os-shell/src/shell/command/commandPaletteApps.ts |
| Window + Spaces store | apps/os-shell/src/window-manager/store.ts |
| Shell controller | apps/os-shell/src/shell/useDesktopShellController.ts |
| Hola welcome app | packages/os-apps/src/apps/hola/ |
| Managed link resolver | apps/os-shell/src/shell/links/resolveManagedLink.ts |
| Platform host map | packages/app-registry/src/platformHosts.ts |
| Global shortcuts | apps/os-shell/src/shell/GlobalShortcuts.tsx |
| Mission Control | apps/os-shell/src/shell/spaces/MissionControlOverlay.tsx |
| Tokens CSS | packages/design-tokens/css/prox.css |
| UI package | packages/os-ui/src/index.ts |
| App contract | packages/app-contract/src/index.ts |
| API worker | apps/api-worker/src/index.ts |
| Docs sync | scripts/sync-docs-content.mjs, pnpm docs:sync |
Common Tasks
Add shell app (registry + Cmd+K)
Read: app-registry.md, .agents/skills/prox-os-shell-workflows/SKILL.md
Modify: types.ts, registry.ts, localAppComponents.tsx, packages/os-ui ShellAppIcon.tsx, optional packages/os-apps
Add UI primitive
Read: ../design/component-layering.md, ../design/tokens.md
Modify: packages/os-ui/src/primitives/* or packages/os-ui/src/shell/*
Verify: pnpm dev:ui, pnpm --filter @prox-os/os-shell dev
Change window or Space behavior
Read: window-manager.md, state-model.md
Modify: apps/os-shell/src/window-manager/store.ts, shell/window-manager/*, shell/spaces/*
Add API route
Read: api-map.md, decisions/0003-msw-hono-openapi.md
Modify: apps/api-worker/src/*
Publish docs to site
Edit root docs/**, then:
pnpm docs:sync
pnpm build:docs