hamedmp/matrix-os/app-builder

Matrix App Builder

When to Use

Use this when the user asks to build, create, fix, redesign, or publish a Matrix OS app.

Non-Negotiables

• Build user-facing apps in ~/apps/<slug>/.
• Default to Vite, React 19, TypeScript, and runtime: "vite".
• CRM, roadmap, dashboard, admin, and data-heavy apps are still Vite React SPAs by default. Use Matrix/Postgres bridge APIs for data instead of creating Next.js API routes.
• Do not create Next.js, .next/, app/ router files, runtime: "node", serve.start, or npm start unless the user explicitly requests a server runtime or Next.js.
• Do not create plain HTML apps unless the user explicitly asks for a plain HTML app.
• Always create or update matrix.json. For apps built for the owner, include listingTrust: "first_party" and scope: "personal"; missing trust blocks launch even if the build succeeds. Never relabel downloaded/store/community apps to bypass policy.
• Always run pnpm install when dependencies changed and pnpm build before saying the app works.
• Verify dist/index.html exists.
• Use injected Matrix theme variables and iframe-safe sizing. Choose a coherent product style from the brief, mood and references; use app-local semantic tokens for its palette/materials, with inherited Matrix tokens as the baseline when no direction is chosen.
• For UI, read matrix-design-system, matrix-app-ui-patterns, and App craft. Discover relevant installed skills through the active harness catalog (or load_skill in kernel routes). Read emil-design-eng for polish, apple-design for direct manipulation, and animate for specific motion work; load supporting references only for the chosen task. Preserve Matrix integration/runtime rules and choose typography, shapes, borders, layout, materials, color and motion for the app’s actual purpose.
• Store structured app data through Matrix/Postgres bridge APIs, not ad hoc local databases.
• Never put provider secrets, API keys, or OAuth tokens inside the app directory.
• Do not use browser localStorage as app persistence in the Matrix shell. Sandboxed iframes can throw SecurityError; use window.MatrixOS.db and keep local fallback paths test-only/no-op.
• For default or first-party apps under home/apps/**, keep manifests deterministic: runtime: "vite", build.output: "dist", schema columns declared in storage.tables, and icon pointing to a committed asset in home/system/icons/.

Design workflow

1. Read Visual references and style intake, the craft reference, and the user’s images/links or existing DESIGN.md. Invite a style or inspiration screenshot when the direction is unclear. When available, delegate bounded similar-app screenshot research to one or two subagents, inspect the actual images, and select a task-appropriate direction. Offer annotated alternatives when useful or requested; continue independent work and use the user’s delegated default without a mandatory approval checkpoint.
2. Save a short app DESIGN.md: primary task, visual family and palette, layout and density, semantic tokens, typography/spacing, true data and state behavior, and one useful motion recipe with a reduced-motion variant. Keep it updated as the implementation changes.
3. Build one complete vertical slice against the owner's real Postgres through window.MatrixOS.db: read → create/edit → confirm or restore on failure → reopen. Verify it before expanding secondary screens. Never use convincing fake records to conceal a missing data path.
4. Inspect the running app in the available Matrix surfaces, refine the largest hierarchy or interaction problem, and inspect again. Check keyboard and reduced motion, not just the default screenshot. Record skills loaded, surface, viewport, theme, states, persistence result, and screenshot/recording evidence; report unavailable evidence explicitly.

For apps and matching landing pages, read Responsive layout and verification. Compose for actual app container width across varied Matrix windows and mobile screens; verify the listed widths and retain all meaningful fields/actions.

Avoid a generic welcome hero, decorative statistic cards, repeated glass containers, and automatic staggered entrances. The usable primary flow owns the first screen.

For requested shadcn UI, read the installed shadcn skill, preset guidance and charts. Use real current components with the project’s actual config, approved package policy and semantic tokens. Choose one fresh coherent style for a new app when the user delegates direction; sample preset links are examples. Preserve existing local components/design during refinements.

Standard Structure

~/apps/<slug>/
  matrix.json
  package.json
  vite.config.ts
  tsconfig.json
  index.html
  src/
    main.tsx
    App.tsx
    App.css
  dist/
    index.html

Manifest

Use this baseline and adjust the app name, description, category, icon, and storage tables:

{
  "name": "My App",
  "description": "A concise app description",
  "slug": "my-app",
  "version": "1.0.0",
  "runtime": "vite",
  "runtimeVersion": "^1.0.0",
  "listingTrust": "first_party",
  "scope": "personal",
  "icon": "my-app",
  "category": "productivity",
  "build": {
    "command": "pnpm build",
    "output": "dist"
  },
  "storage": {
    "tables": {}
  }
}

Valid storage column types include text, boolean, integer, float, timestamptz, jsonb, and uuid.

Presenting apps and charts in Chat

After verifying the app, link its owner-relative directory, for example [AI Adoption](~/apps/ai-adoption). Electron Desktop resolves installed app directories against the app catalog and opens them through the normal launcher behavior. Do not claim an arbitrary folder is an installed app.

Display saved charts or screenshots with Markdown images and full owner-relative paths, for example ![AI adoption chart](~/apps/ai-adoption/chart-light.png). Electron Desktop can display these images and open them in File Preview; do not tell the user images can only appear in the agent's terminal. Use Markdown links for other saved files. Static HTML previews are sandboxed without scripts; link the installed app for an interactive chart rather than promising active HTML execution inside Chat. Report missing files or preview failures truthfully.

Naming

• name is the human, Title-Case label shown in the launcher, dock, and title bar — e.g.

"Calorie Tracker", "Habit Garden". Make it short and real; never show the slug to users.

• slug is the lowercase, hyphenated id used in paths/URLs (^[a-z0-9][a-z0-9-]{0,63}$). Derive it

from the name (calorie-tracker). It is internal — do not use it as a display string anywhere.

Icon (required — or the app shows a broken tile)

The launcher loads each app's icon from ~/system/icons/<icon>.svg (or .png) matching the manifest icon field. If you don't ship that file, `/icons/<icon>` 404s and the app gets a broken/placeholder icon. So always:

1. Set "icon": "<slug>" in matrix.json (use the app slug unless you have a better concept name).
2. Create ~/system/icons/<slug>.png using the Matrix desktop icon style:

a distinct app-specific silhouette on a transparent background, rich color and controlled depth. Read App icon recipe for the palette, scale, prompt template and semantic mappings. Keep a distinct object for each game's identity. Preserve user-provided icons and icon styles when refining an existing app.

For first-party/default apps, prefer committed PNG icons from home/system/icons/. Exact supplied Supplied Figma SVGs may be packaged directly or rasterized for PNG-compatible launcher paths; keep their geometry and colours unchanged. Do not substitute a recreated outline for supplied artwork.

Data (Postgres via the MatrixOS bridge)

Public website deployments

When the user wants a public app, build a production React/Vite app with base: "./", no source maps, and a separate dist/. Declare only visitor-safe content in matrix.json publishing.data and named form schemas in publishing.forms. Public apps use window.MatrixOS.site.data and window.MatrixOS.site.submit(formId, fields, { idempotencyKey }); reuse a key for retries of one submission. Private Matrix bridges (db, services, AI) are unavailable to anonymous visitors. Do not copy private records, credentials, or environment values into public configuration or compiled code.

Information-only guides publish as ordinary Matrix apps without forms or a publishing declaration. Include the requested guidance, support/post/channel links and discount codes; do not add forms unless requested. Outbound HTTP(S) links open a new tab without an opener/referrer, and fragment links stay in the guide.

Optional visitor form example (only when requested)

This is a matrix.json fragment for a separate form-enabled app, not a requirement for the launch guide:

{
  "publishing": {
    "data": { "event_title": "Community meetup" },
    "forms": [{
      "id": "rsvp",
      "title": "Reserve a place",
      "fields": {
        "name": { "type": "text", "required": true, "maxLength": 80 },
        "email": { "type": "email", "required": true, "maxLength": 254 },
        "guests": { "type": "number", "required": true, "min": 1, "max": 20 },
        "updates": { "type": "boolean", "required": false }
      }
    }]
  }
}

forms is an array, each fields value is a declaration keyed by the submitted field name, and undeclared fields are rejected. Use up to 10 forms and 30 fields per form; apply maxLength only to text/email and min/max only to numbers. Submit with MatrixOS.site.submit("rsvp", fields, { idempotencyKey }) after checking that bridge availability and handling failure.

Owner controls are in Publish app on Web Canvas, Web Desktop, Electron Desktop and Web Mobile. Review the exact public declaration before deployment. The headless owner API is /api/apps/:slug/site: GET current publication, POST checked build/deploy with metadata plus reviewedConfig matching the current publishing declaration, PATCH metadata, DELETE with baseRevision, and POST /rollback with versionId/baseRevision. This REST API requires a genuine verified owner client; never put a token in app source or invent a login. Scoped Chat runs cannot publish or manage sites with their integration-only tokens in V1. After preparing the app, direct the owner to Publish app for review and deployment. Visitor submissions use owner-only /submissions, /submissions/export (paginated), and DELETE /submissions/:id. Publishing fails safely when hosting is unconfigured; do not claim a public deployment from a local build alone.

Addresses are https://matrix.page/<permanent-id> or an optional friendly path. Visitors need no login. Pages remain readable with the owner runtime offline; form saves require it online. Unpublish closes new public access but retains owner records. Native Mobile has no owner publishing controls in this release; custom domains/server processes are deferred. See public app sites.

Apps run in a sandboxed, null-origin iframe (CSP connect-src 'self'), so a direct fetch() to /api/bridge/* is blocked and localStorage throws SecurityError. Persist ONLY through the injected bridge: