business-os-app-module-development

name	business-os-app-module-development
description	Use whenever CTOX, Business OS, App Creator, App Store, chat, CLI, or an inbound Business OS workflow asks an agent to build, modify, repair, review, or install a CTOX Business OS app/module. The agent builds the app itself as no-build vanilla HTML/CSS/browser ESM, persists through the shell-provided CTOX Sync Engine/RxDB handle, sends automation through commandBus, studies shipped Business OS app examples, and validates the result with CTOX app validation.
metadata	{"short-description":"Build runnable CTOX Business OS app modules with vanilla ESM, CTOX Sync Engine persistence, and command-bus automation."}

Business OS App Module Development

This file is a resource index. Use the linked contracts and checklists as the working source of truth.

Non-negotiable preflight (before writing ANY app surface)

1. Open references/design-guide.md and re-read "Canonical Column Grammar" and the anti-patterns — in THIS session, not from memory. A rebuilt or new pane without the grammar (header row → search + collapsed filter tray with reset + active-dot → counted view band (>= 2 views) → shard/list toggle in the filterbar → recessed well → one-line footer) is a regression, not a draft.
2. Put a reference app beside your work and diff structurally before calling it done: threads (hub/inbox columns) and knowledge (content columns) are the binding reference implementations.
3. Run scripts/module_static_check.mjs <module-id> — it enforces tokens, kit usage, and the mechanical grammar rules (e.g. no single-tab view bands). A red check is a finding, never an inconvenience.

Tool Boundary

• Remote MCP agents read advertised business-os-skill://… resources with business_os.read_app_skill_resource; local filesystem access is not assumed.

• Product entry points may use ctox business-os app create --instruction <text> or ctox business-os app modify <module-id> --instruction <text> to enqueue a real Business OS app task.

• These tools route the request to the Business OS command/queue/policy path; they do not generate app files, derive schemas, choose layouts, or write templates.

• App workers build or modify the app themselves, using the resources below and the three chosen reference apps.

• Use the agent's structured file-edit tool for app files. In CTOX Codex runs this is apply_patch; keep shell commands for inspection, validation, and tests.

• During app creation or modification, do not run ctox stop, ctox start, ctox upgrade, launchctl, systemctl, or service lifecycle commands. The running CTOX service is the required runtime for validation and browser proof.

Resource Index

• references/module-contract.md: file layout, manifest, schema, mount contract, persistence contract, automation contract, agent right-click context.
• references/design-guide.md: Business OS token contract, custom branding rules, UX patterns, and anti-patterns.
• references/impeccable-preflight.md: mandatory frontend preflight for operational density, signature automation, windows, panes, and mobile.
• references/standalone-porting.md: how to keep standalone vanilla apps portable into Business OS with mount(ctx) and mock context boundaries.
• references/dos-and-donts.md: short rules for correct Business OS app implementation.
• references/green-checklist.md: finalization checklist before a task can be considered done.
• references/architecture-translation.md: mapping from familiar web app patterns to CTOX Business OS app patterns.
• assets/standalone/business-os-tokens.css: lightweight default token CSS for standalone previews only.
• assets/standalone/mock-business-os-context.mjs: lightweight mock ctx for standalone demos/tests before porting.

Required Agent Context (Right-Click)

Mandatory for every app and every record -- not optional, not deferrable. The shell, not the app, owns the right-click menu; the app's job is to label its records so the agent knows what was clicked.

• Put data-context-record-id, data-context-record-type, and data-context-label on the outermost element of every record (list row, card, table row, tree node). The shell's global "Chat to CTOX" right-click menu reads them and tells the agent which record the user clicked. Without them the agent gets only loose text and cannot act on the record.
• Always set the explicit trio. The shell will also resolve a bare data-*-id as a safety net (deriving the type from the attribute name and guessing a label), but that is NOT a substitute -- do not skip the trio just because a data-*-id already exists on the element.
• Mark side panes with a *-left / *-right / *-sidebar class or data-left-content / data-right-content so the agent learns the column.
• Do not build a per-app context menu or app-owned right-click event bridge for this; the shell handles it. Full contract and shell internals: references/module-contract.md ("Agent Context (Right-Click)").

Required Context

• Before frontend design or CSS changes, run the contract in references/impeccable-preflight.md. Treat root PRODUCT.md, DESIGN.md, and .impeccable/design.json as the CTOX-specific input to IMPECCABLE_PREFLIGHT; emit its exact pass line before implementation.

• Inspect three existing shipped Business OS apps selected for similar workflow, data model, and UI shape.

• Use ctox business-os app references --query "<workflow data keywords>" --json --limit 8 when a local reference catalog is needed.

• Runtime-created apps live in runtime/business-os/installed-modules/<module-id>/.

• Source apps live in src/apps/business-os/modules/<module-id>/ only when the task explicitly targets checked-in source.

• Runtime-created business apps must own the visible work surface inside ctx.host and launch as responsive desktop windows. Set module.json root launch_kind to desktop-app, and the canonical root presentation contract. layout.shell: windowed remains a temporary compatibility hint; do not duplicate launch_kind below layout. Do not rely on generic shell Kontext/Themen side panes. Use the shared responsive workspace/pane patterns inside the window instead.

• The Business OS shell already shows app identity, navigation, version/source controls, account state, and global chat. A normal business app may have at most one compact app-level command/header row for its own filters and primary actions. Do not stack a hero/title block, version bar, day strip, metrics row, and filter bar before the work surface.

• Design the primary workflow around the user's common action. For booking, scheduling, shift, parking, availability, or other date/slot domains, provide a calendar/date-strip view and one-click actions for claim/release/book flows; do not force a modal or form unless the user must supply extra data.

• Encode the domain invariant behind the one-click path. For physical-resource apps such as parking, rooms, desks, devices, or shifts, prevent impossible duplicate claims such as the same person, vehicle, or asset being booked into two slots at the same time.

• Do not add generic "Report to CTOX", "An CTOX melden", queue, AI, or command-bus buttons by default. Add visible automation only when the user asks for it or the workflow clearly needs it, and only when it dispatches a real command and shows a trackable result.

Validation

• Runtime app: ctox business-os app validate <module-id> --installed
• Source app: ctox business-os app validate <module-id> --source
• Browser proof: ctox business-os app smoke <module-id> --installed
• Visual proof: inspect the mounted app in the real Business OS shell at a desktop viewport, a resized 640×480 window, and a 360px mobile sheet, in light and dark theme. The app must use the central workspace, avoid useless side columns, keep text readable, and complete the primary workflow without clipped controls.

Validation failures are app defects or contract defects. Fix the app or the contract; do not hide failures by weakening validation.

References

Load only the files needed for the current task from references/.