Kosmos OS primitives for the HolyC native apps
Recon for the planned native apps on our TempleOS desktop (desk3/): email, spreadsheets, slides, maps, applications folder, font manager,
weather, music, contacts and an AI IDE. Written 2026-10-27 from a read-only pass over the Kosmos OS repo.
Source repos (read only):
- Kosmos OS:
/Users/paulbloch/kosmos-os-frame(GitHub Kosmos-computer/Kosmos, branchfeat/kosmos-engine-window). The README title is "Arco OS". The product is called Kosmos or Arco in different places; code usesarco-*for shell internals and brand-freeos.*,core.*,x-app-token,--os-*at the platform boundary. - Marketing site:
/Users/paulbloch/Documents/github/kosmos-www(its brief indocs/CONTENT-BRIEF.mdstill says "Longformer"; treat it as stale copy). - Five desk styles:
/Users/paulbloch/Documents/github/kosmos-engine/apps/os-styles.
Verification tags: [V] read in the source; [I] inferred from names, comments or memory, not run.
1. What Kosmos OS is, and how an app is defined#
Kosmos OS is a browser-based desktop shell (Vite + React on the client, a Hono/Node server with SQLite) where an agent can build apps. It has a window
manager, dock, menu bar, command palette, a chat agent, generated OpenUI apps, system services and a bridge that all app calls pass through. [V]
README.md, src/os/Desktop.tsx, src/os/Dock.tsx, src/os/MenuBar.tsx, src/os/WindowFrame.tsx.
1.1 The platform rules (from docs/app-platform-plan.md)#
- Contracts over implementations: apps implement versioned contracts (
os.calendar@1); callers never bind to an app. [V] - One choke point: every privileged call goes through
dispatchAppBridgewith a caller identity. [V]server/platform/bridge.ts - Tier decides the container, not the surface. Same manifest, identity, grants and bus for every app. [V] (plan)
- The OS owns PIM and file data; apps are clients. [V] (plan,
shared/capabilities/files.ts) - No private shell APIs: core apps use the same SDK and manifest as third-party apps. [V] (plan)
- Typed intents on the wire, not natural language, between components. [V] (plan)
- Brand-free platform boundary:
os.*contracts,core.*app ids,x-app-token,/app-sdk.js,--os-*theme tokens. [V]
1.2 Manifest#
Type: AppManifest in shared/manifest.ts; validated by Zod in server/platform/manifestSchema.ts. [V]
| Field | Shape | Notes |
|---|---|---|
id |
reverse-dns, ^[a-z0-9]+(\.[a-z0-9-]+)+$ |
core apps use core.* |
name, version, description |
strings, semver | |
icon |
Lucide kebab name, e.g. calendar-days, file-text |
|
tier |
declarative or code |
all bundled apps are code [V] |
entry |
url / bundle (path under apps/) / openui (StoredApp id) |
bundle paths are validated as lowercase segments |
implements |
contract ids, e.g. ["os.docs@1"] |
|
permissions |
intent, contract (read or write), storage: own, shell (notify, windows, clipboard, agent) |
grant keys like contract:os.files@1:write |
tools |
up to 20 agent tools; binding is intent or storage-query (SELECT only) |
JSON Schema parameters |
events |
emits and subscribes topic lists |
bridge checks emits |
chrome |
{ toolbar: false } hides the version strip |
Example (apps/docs/manifest.json, [V]): core.docs, tier: code, entry: { kind: bundle, path: docs/dist }, implements: [os.docs@1],
permissions for os.files@1 and os.docs@1 read and write, events.subscribes: [files.changed].
1.3 Lifecycle#
- Seeds:
ensureSeeds()readsapps/*/manifest.jsonon boot and installs them assource: seed; they are served at/apps/<folder>/. [V] (server/platform/installedAppStore.ts,docs/office-suite-plan.md) - Install paths: seed folder, URL, raw JSON (all through
parseManifest). [V]shared/manifest.tsAppSource - Grants:
granted | denied | ask, keyed per permission (grantStore.ts). Install grants every requested key by default. [V] - Launch: the shell mints a 24-byte per-window token (
POST /api/installed-apps/:id/token, 12 h TTL) and the AppHost attaches it. The app cannot claim its own identity. [V]bridge.ts - Window:
{ type: "installed", appId }inwindowStore; installed apps sit in the Dock, not the NavRail. [V] (office-suite plan)
1.4 SDK and bridge#
- SDK:
packages/app-sdk/sdk.js(324 lines, zero dependencies, served at/app-sdk.js); types inindex.d.ts. [V] createAppClient()exposesintents.invoke(intent, params),storage.query/execute(own SQLite namespace, needsstorage:own),shell.notify,shell.askAgent,shell.setWindowGeometry(aspect lock),shell.toolbar.set/onInput,events.on(topic),theme.current/onChange. [V]- Wire:
window.parent.postMessage({ appBridge: true, type: "request", id, method, params }); host replies withui.result; ready istype: "ready". [V] - Also handles host
ui.commandmessages, so the agent cursor can click inside the app (data-arco-cidids). [V] - Bridge methods (
dispatchAppBridge):intent.invoke(grant check, audit, theninvokeIntent),storage.query,storage.execute,events.emit. Unknown method is an error. Every call writesappendAudit. [V] - HTTP:
POST /api/bridge(server/index.ts), audit read at the audit route. [V]
1.5 Contracts (the intent vocabulary)#
Registry: shared/capabilities/index.ts CONTRACTS map, routed by server/capabilities/registry.ts (invokeIntent). [V]
| Contract | Intents (access) | Backing store | Used by |
|---|---|---|---|
os.calculator@1 |
calculator.evaluate, history.list | SQLite history table |
core.calculator |
os.calendar@1 |
events.list, event.get (r); event.create/update/delete (w) | SQLite events |
core.calendar |
os.files@1 |
list, get, search, content.read (r); create, rename, move, star, trash, restore, delete, content.write (w) | SQLite files + blobs in data/files/ |
Drive, docs, sheets, slides |
os.docs@1 |
docs.create, open, export, import | files (application/x-os-doc+json) |
core.docs |
os.sheets@1 |
sheets.create, open, query, write_range, export, import | files (application/x-os-sheet+json) |
Sheets |
os.slides@1 |
slides.create, open, write, export, import | files (application/x-os-slides+json) |
core.slides |
os.tasks@1 |
tasks.list, get, create, update, complete, archive, delete | SQLite tasks |
Tasks app, menubar, agent |
os.music@1 |
music intents (imports, scan, tracks) | data/music-library/ |
Music |
os.downloads@1, os.shares@1, os.board@1, os.memory@1, os.voice@1, os.engine@1 |
present, schemas in shared/capabilities/ |
services | various |
No contract exists for mail, contacts, maps, weather, fonts or a code editor (see section 7).
Intent schemas are JSON Schema 2020-12 objects and are reusable as tool definitions. [V]
1.6 Data stores#
- System stores are owned by the server:
filesService(data/db/system-files.sqliteplusdata/files/<id>blobs), calendar, tasks, calculator, music library, mail (server/mail/mailStore.ts, secret-safe JSON viasecureFs, not SQLite). [V] - Per-app private namespace:
app_<appId>viastorageNamespace(), gated bystorage:own. [V] - Client-only stubs: contacts vault (
localStoragekeyarco-contacts-vault, zustand persist); timer history (localStorage). [V]
1.7 Agent tools#
- System tools live in
server/agent/tools.ts(agentTools[], e.g.tasks_list,tasks_create,sheets_query,docs_export). [V] (README,docs/office-format-interop.md) - App tools compile from manifests:
server/platform/appTools.ts(74 lines) turnstools[]into LLM tool defs, namespacedapp__<id>__<name>. [V] (shared/manifest.tscomment) - Dispatch is deterministic code; the app's grant sheet is enforced on every call. [V]
- Per-tool agent policy
auto | confirm | denyis planned (Phase 3), not confirmed built. [I]
1.8 Intents, events and confirmation#
files.changed,calendar.changed,calculator.changedare the subscribed topics;server/bus.tsrepublishes app events asapp-event:<topic>. [V]- Confirmation:
confirm_requiredSSE flow is reused for first-use prompts (plan). [V] (plan)
2. Design tokens, icons, chrome and components#
2.1 Shell tokens (src/styles/tokens.css, src/os/themeTokens.ts) [V]#
Light and dark palettes on html[data-theme]. Every value is a CSS custom property. Apps get them as --os-* through the AppHost.
- Colour (dark / light): desktop bg
#0d0d0f/#dfe4ec; surfacergba(26,26,28,.92)/rgba(252,253,255,.92); solid surface#1a1a1c/#fcfdff; elevatedrgba(40,40,44,.95)/ white 98%; hover 6% / 5%; active 10% / 9%; chromergba(18,18,20,.78)/rgba(248,250,253,.8). Text primary#ececee/#171b23; secondary#a8a8ae/#4e5665; tertiary#717178/#8a92a3. Accent#7c9dff/#3b64e0(strong#5b82ff/#2b51c7); success#58c98b/#23985e; warning#e5b567/#b57f24; danger#e5737d/#cc4450. Borderrgba(255,255,255,.09)/rgba(15,20,30,.1). - Accent presets: blue, violet, green, amber, rose, cyan, monochrome (
themeTokens.ts). Font presets: system, inter, ibm-plex, source-serif, space-grotesk. - Type scale: xs 11, sm 12.5, md 14, lg 16, xl 20 px. UI font stack:
-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, .... Mono: SF Mono / Menlo. - Spacing: 2, 4, 8, 12, 16, 24, 32 px (2xs to 2xl).
- Radii: s 6, m 10, l 14, window 12 px.
- Shadows:
--arco-shadow-window(0 24/64 px, two layers) and--arco-shadow-chrome(0 8/32 px). Backdropsaturate(160%) blur(22px). - Motion: ease
cubic-bezier(0.32, 0.72, 0, 1); fast 140 ms; med 240 ms; full-screen crossfade 600 ms. - Z layers: windows 10, chrome 1000, overlay 2000, modal 2100.
- Wallpapers: aurora, dusk, graphite, forest gradients (
tokens.css).
2.2 Five styles in apps/os-styles [V]#
apps/os-styles/styles.css (generated by scripts/gen-styles.py, WCAG AAA 7:1 text) defines nine data-style values: longformer-light,
longformer-dark, temple, kosmica, platinum, paper, macos, windows, brutalist. Each sets --lf-* tokens (accent, surfaces 1 to 3, text,
border, focus ring, radii, font family, durations) and --s-* shell tokens (desk, bar, shadow, lift, title style). Targets: 44 px hit area, 16 px body,
1.6 line height. [V]
Our desk3 implements five (desk3/01-core.HC lines 40 to 48, README): Longformer light, Longformer dark, macOS, Windows 11, Kosmica glass. The
temple, platinum, paper and brutalist styles are not in desk3 [V]. The user brief said "five styles"; this matches.
2.3 Desk3 mapping [V]#
desk3/01-core.HC:
- 16 colour slots, in order: ink, accent, ok, teal, bad, purple, warn, surface, muted, accent2, card, border, shadow, dock, amber, page
(
ks_pn). Each style has its own 16 values inks_pal[NS*16]. - Per-style:
ks_kind(window chrome kind 0 rounded card, 1 traffic lights, 2 caption buttons),ks_rad(12, 12, 14, 8, 16),ks_glass(true only for Kosmica). - Corner radius adjust
ks_radadj, accent overrideks_accov, animation and magnification toggles, dock size 52.
Token mapping (proposed; [I] unless noted):
| Kosmos token | desk3 slot |
|---|---|
--arco-text-primary |
ink (0) |
--arco-accent |
accent (1) |
--arco-success |
ok (2) |
--arco-danger |
bad (4) |
--arco-warning |
warn (6) |
--arco-text-secondary / tertiary |
muted (8) |
--arco-bg-surface-solid |
surface (7) and card (10) |
--arco-border |
border (11) |
--arco-shadow-chrome |
shadow (12) |
--arco-bg-chrome |
dock (13) |
--arco-bg-desktop |
page (15) |
--arco-accent-soft |
no slot: compute by alpha blend at paint time |
Radii: --arco-radius-window 12 px matches ks_rad for Longformer. Spacing and type scale are not in desk3; desk3 uses pixel constants in code. [I]
2.4 Icons [V]#
- Client: Lucide (
lucide-react^0.575.0 in the root package, ISC licence). Manifests name icons in Lucide kebab case. - Vendored subset:
apps/os-styles/kamiji-ui/targets/lit/icons.js(generated; Lucide ISC plus some Feather-derived MIT icons; seeICONS-LICENSE.md). - Desk3: an enum of 21 icon indices (
L_GRID0 toL_GLOBE20, in01-core.HC) and an ASCII cursor (ks_cur). How each icon is drawn was not checked. - Mapping task: each manifest icon name maps to an
L_*index or a new vector path. Lucide paths need rasterising or a stroke renderer in HolyC.
2.5 Window chrome [V]#
- Kosmos:
src/os/WindowFrame.tsx,WindowControls.tsx. Control looks aretraffic | glyph | circles | outline | capsules, aligned left or right (themeTokens.ts). The 44 px title bar is in the os-styles prototype (apps/os-styles/index.html), not confirmed in Kosmos code. [V] - desk3: chrome kinds 0, 1, 2, plus glass. Title bar
TBAR44, menu barMBAR32, dock height 76 (DOCK_H). [V]desk3/01-core.HC
2.6 Component inventory#
Kosmos src/components/ui/ [V]: Avatar, Badge, Button (variant default, primary, danger, ghost; size default or icon), Chip, EmptyState,
Input, PasswordInput, Switch. Also src/components/patterns/, Menu.tsx, useDismiss.ts, richmarkdown/, composer/, chat/.
Shell: CommandPalette, Dock, HoverDock, MenuBar, NavRail, WindowFrame, SwipeRevealTray, FloatingKeyboard.
desk3 widgets [V] (desk3/02-ui.HC, 04-main.HC): Button(kind), Toggle, Radio, Slider, Check, Icon, Frame, Menubar, KMenu, Dock,
Cursor, Input (a basic keyboard handler in 04-main.HC).
Missing in desk3 and needed by every native app: text field with caret, selection and clipboard; scroll view; list and table with rows and
columns; tabs; menus with submenus; dialogs and sheets; toolbar; split view; tree view. This matches the widget kit v2 gate in
docs/holyc-native-apps-plan.md.
2.7 Layout patterns [V]#
- Sidebar plus main plus optional right panel (Drive, Tasks, Sheets, Mail):
FilesWorkspace,TaskDrawer,EmailSidebar/EmailThreadList. - Toolbar on top with search (
--arco-search-*tokens); status line; empty states viaEmptyState. - Adaptive:
ResizeObserverplusdata-arco-sizeand CSS container queries (os-stylesuses@container); mobile shell below a width threshold. [V]
3. Existing apps: data model, features, and what can become spec#
| App | Source | Data model | Features (verified) | What to take as spec |
|---|---|---|---|---|
| Calendar | apps/calendar/ (app.js 243 lines, styles 257), contract shared/capabilities/calendar.ts, service server/services/calendarService.ts |
events(id, title, start, end, allDay, location, notes, createdAt, updatedAt), ISO 8601, indexed by start |
list by range, create, update, delete via intents; no tools in manifest | Event shape and intent set. View modes (day, week, month) were not checked in the source. iCal bridge is planned, not built. |
| Tasks | src/apps/tasks/ (TasksApp, TaskDrawer, TaskList, AddTaskModal, MiniCalendar, AssignToPicker), shared/capabilities/tasks.ts, server/services/tasksService.ts |
tasks(id, title, description, status, priority, assigneeJson, dueDateISO, archived, createdAt, updatedAt); status pending, in_progress, completed, cancelled |
list with filters, drawer editing, due dates, assignees (self, agent, contact, custom), history, archive | Full spec for a HolyC Tasks app. Also the menubar capture contract. |
| Docs | apps/docs/ (src App.tsx), packages/editor-kit/, shared/capabilities/docs.ts, files.ts |
TipTap JSON in application/x-os-doc+json; images as sibling files |
headings, lists, bold, italic, code, links, tables, images (v1 scope per plan) | Document JSON schema and v1 feature list. Editor engine is TipTap and cannot port. |
| Sheets | src/apps/sheets/ (SheetsApp 141 lines, SheetGridView, SheetsSidebar, SheetsToolbar, workbookFormat), shared/sheetFormula.ts, shared/capabilities/sheets.ts |
workbook JSON {version, title, sheets:[{id,name,cells}]}; cells keyed by A1 address; mime application/x-os-sheet+json |
multi-sheet, A1 parsing, ranges, formulas via evaluateFormula, recalculateSheet; query and write-range intents; CSV, XLSX export via doc-interop |
Formula grammar and A1 rules (sheetFormula.ts is pure TS and testable). Grid UI must be built natively. |
| Slides | apps/slides/ (src App.tsx, styles), shared/capabilities/slides.ts |
DeckDoc: {version:1,width:960,height:540,slides:[{id,boxes:[]}]}; boxes text | shape | image with x, y, w, h |
DOM canvas, drag and resize, shapes (rect, ellipse, triangle, line, diamond), text boxes in TipTap | DeckDoc schema and box rules; present mode is planned but not verified in source. |
| Calculator | apps/calculator/ (app.js 946 lines, skins Datamath, Omron, Scientific), server/services/calculatorService.ts, shared/capabilities/calculator.ts |
history(id, expression, result, createdAt) |
arithmetic and scientific expressions, DEG or RAD, history list | Expression grammar; skins are a visual spec for desk3 styles. |
| Timer | apps/timer/ (app.js 449 lines) |
localStorage entries; no contract; alerts through shell.notify |
countdowns and clock-time alarms, optional beep | Behaviour only; small enough to rewrite. |
| Files (Drive) | src/apps/files/ (FilesApp, FilesWorkspace, FileRow, FileCard, PdfViewer, ShareLinkModal, DriveMoveModal), server/services/filesService.ts (595 lines), shared/capabilities/files.ts, shares.ts |
files table with id, name, parentId, mimeType, size, starred, trashed; blobs on disk | list and grid, breadcrumbs, rename, move, star, trash and restore, search, share links, PDF preview | Core spec for a HolyC Applications and file browser. The file contract is the same one editor apps use. |
| Terminal | src/apps/terminal/TerminalApp.tsx (108 lines) |
in-memory history only | one-shot commands against the workspace exec; not a pty |
Little to take. Native terminal is better built from scratch. |
| Studio (AI IDE) | src/apps/studio/ (StudioApp 577 lines, sidebar, board panel, browser preview, editor, diff comments, worktree picker, conversation groups), server/agent, server/git.ts, Monaco in deps |
conversations, worktrees, diff comments in client stores; project files on disk | multi-conversation chat, git worktrees, diffs with comments, live browser preview, model picker, status dots, board | The approval flow and conversation model. A HolyC IDE needs a text engine first. |
Other apps for the brief (not in your list, but relevant):
- Email:
src/apps/email/(useEmail 240 lines, EmailHtmlBody, EmailThreadList) withserver/mail/(adapters/gmail.ts,adapters/imap.ts,googleOAuth.ts,mailGateway.ts,tools.ts). Tokens stay server side. - Contacts:
src/apps/contacts/(ContactsApp, DialPad, ContactImport, ContactDetail). The store is a localStorage stub with a comment saying it is waiting foros.contacts@1. - Maps:
src/apps/maps/(MapCanvas with Leaflet, MapsApp, useMaps) andserver/services/mapsService.ts, which proxies Nominatim and OSRM with a user agent. - Music:
src/apps/music/(MusicApp, musicStore 718 lines, catalogs) andserver/services/musicLibraryService.ts(595 lines),musicRssService.ts. - Weather: no app. A bento widget (
src/os/bento/bentoCatalog.ts,templateId: "weather") shows live data from Open-Meteo (src/styles/bento.css). [V]
4. Packages: reuse as spec or as host service#
| Package | What it is | HolyC use |
|---|---|---|
packages/doc-interop (@arco/doc-interop, private) |
Import and export for ODT, DOCX, ODS, XLSX, ODP, PPTX, Markdown, HTML, CSV, TSV. Deps: docx, exceljs, jszip, mammoth, pptxgenjs. FIDELITY.md documents the matrix. src/roundtrip.test.ts holds golden tests. [V] |
Host service for XLSX, DOCX, PPTX and ODF import and export. The guest sends bytes over the channel and receives canonical JSON (workbook, DeckDoc, doc JSON). Keep FIDELITY.md as the spec. Do not port the parsers into HolyC. |
packages/editor-kit (@arco/editor-kit) |
TipTap React editor with toolbar, bubble menu, slash menu, widget node views. [V] | Spec only: document schema and command list. The engine is React and cannot run in TempleOS. |
packages/app-sdk |
Zero-dependency postMessage client and types. [V] | Spec for the HolyC app API (method names, ui.result, toolbar slots, events.on). Could be the host-side message format for an embedded browser later. |
packages/platform-bridge |
Runtime detection and shell bridges for Electron, Tauri, Capacitor, web. [V] | Not needed. Shell-specific. |
packages/cli |
kosmos / arco CLI for worktrees and sessions. [V] |
Not needed. |
Services that could run behind the channel (host side, not inside the guest): doc-interop; mail (IMAP and Gmail adapters, OAuth stays on the host);
maps proxy (Nominatim and OSRM); weather (Open-Meteo); music library and RSS; the file store (filesService); tasks and calendar stores; the agent.
5. Reusable for the native apps#
Licence status: the Kosmos OS repo has no LICENSE file at the root, no license field in any package.json (root, packages/*, apps/*), and the
kosmos-www repo has no LICENSE file either [V]. Treat all Kosmos OS code and docs as unlicensed, all rights reserved until the owner says otherwise.
Ask before copying code. The only explicit licence statements are in apps/os-styles/kamiji-ui (see row 2). Dependency licences below are [I] (from
memory), to verify in node_modules.
Effort: S under a day, M a few days, L one or more weeks, measured on the HolyC side.
| Item | Source path | Licence | What to take | Effort |
| --- | --- | --- | --- |
| 1. Shell design tokens | src/styles/tokens.css, src/os/themeTokens.ts | Unclear (no repo licence) | Values only (colour, type, radius, spacing, motion) as desk3 palette and constants | S |
| 2. Five styles and --lf-* tokens | apps/os-styles/styles.css, apps/os-styles/kamiji-ui/dist/tokens.css | Kamiji UI: "provisional MIT, IP clearance open" (PROVENANCE.md); not for publishing | Values for the desk3 palettes (already partly done in desk3) | S |
| 3. Icon paths | apps/os-styles/kamiji-ui/targets/lit/icons.js, ICONS-LICENSE.md | Lucide ISC; Feather-derived MIT. Licence text is in the file | Path data for the 20 or so icons we need | S to M (rasterising) |
| 4. Manifest and permission model | shared/manifest.ts, server/platform/manifestSchema.ts, server/platform/grantStore.ts | Unclear | Spec: fields, grant keys, plain-language permission text | S (spec); M (port the grant store) |
| 5. Bridge protocol | server/platform/bridge.ts, packages/app-sdk/sdk.js, index.d.ts | Unclear (SDK has no licence header) | Methods, audit model, token rules; spec for the HolyC call API | M |
| 6. Calendar contract and app | shared/capabilities/calendar.ts, apps/calendar/app.js, calendarService.ts | Unclear | Event shape, intent set, range view behaviour | S (spec); M (app) |
| 7. Tasks contract and app | shared/capabilities/tasks.ts, src/apps/tasks/, tasksService.ts | Unclear | Full behaviour and schema for the Tasks app | M |
| 8. Files contract and store | shared/capabilities/files.ts, server/services/filesService.ts | Unclear | Entry shape, mime conventions, trash and restore rules; host store for the Applications folder and Drive | M |
| 9. Formula engine | shared/sheetFormula.ts (+ sheetFormula.test.ts) | Unclear | Port to HolyC, or run as host service; grammar is the spec | M |
| 10. Sheets workbook schema | shared/capabilities/sheets.ts, src/apps/sheets/workbookFormat.ts | Unclear | JSON schema, parse and serialize rules | S |
| 11. Slides DeckDoc schema | shared/capabilities/slides.ts, apps/slides/src/App.tsx | Unclear | DeckDoc JSON, box rules, layout tips, shape list | S (spec); M (editor) |
| 12. Docs schema | shared/capabilities/docs.ts, packages/editor-kit/src/ | Unclear; TipTap deps MIT [I] | Document JSON and v1 feature list | S |
| 13. doc-interop | packages/doc-interop/ (+ FIDELITY.md, roundtrip test) | Unclear; deps docx MIT, exceljs MIT, mammoth BSD-2, pptxgenjs MIT, jszip MIT or GPL (dual) [I] | Host service plus fidelity matrix; golden tests | M (service) |
| 14. Calculator logic | server/services/calculatorService.ts, apps/calculator/app.js | Unclear | Grammar, DEG or RAD rules, history model; skins as visual spec | S to M |
| 15. Timer behaviour | apps/timer/app.js | Unclear | Countdown and alarm rules | S |
| 16. Maps proxy | server/services/mapsService.ts, shared/maps/format.js | Unclear; Leaflet BSD-2 [I]; OSM data ODbL and Nominatim and OSRM usage policies [I] | Host service only (User-Agent, rate limits, attribution) | S (service) |
| 17. Mail | server/mail/ (adapters/imap.ts, adapters/gmail.ts, mailStore.ts), src/apps/email/ | Unclear; imapflow, mailparser, nodemailer MIT [I] | Host service; the approval rule for send. The UI is React and not portable. | L |
| 18. Music library | server/services/musicLibraryService.ts, musicRssService.ts, shared/musicFeeds.ts | Unclear | Host service for library and feeds; playback needs an audio path on TempleOS (none yet) | M (service); L (playback) |
| 19. Weather | Bento weather in src/os/bento/bentoCatalog.ts; Open-Meteo | Unclear; Open-Meteo terms [I] | Host fetch of forecast JSON; layout only | S |
| 20. Studio approval and conversation model | src/apps/studio/, server/agent/ | Unclear | Approval-before-write and command rules, conversation model | M (spec); L (IDE) |
| 21. Desk3 widgets and styles | apps/templeos-holyc/desk3/ | Ours | Already ours | n/a |
6. App model for the Applications folder#
Goal: a HolyC app and a Kosmos app share one manifest shape, one permission vocabulary and one call API, so the same app id and grants work in both.
Proposed (for discussion; no code changed):
- Folder:
apps/templeos-holyc/apps/<name>/manifest.jsonplus the HolyC source (<name>.HC). The desk3ks_an,ks_aw,ks_ah,ks_fx,ks_fyandks_dordarrays become a scanned list, which matches the framework step inholyc-native-apps-plan.md. - Manifest: the
AppManifestfields from section 1.2, unchanged. Add one entry kind,{ kind: "holyc", path: "<name>.HC" }, to bothshared/manifest.tsandmanifestSchema.ts. This is a schema change on the Kosmos side; decide with the owner first. [I] - Icon: manifest
iconis a Lucide name; the desk3 loader maps it to anL_*icon or a vector path (section 2.4). - Permissions: the same grant keys (
contract:os.files@1:write,shell:notify). The Settings Apps panel reads one grants file shared by both shells. - One call gate: a single HolyC function (
KsCall(appId, method, params)) that checks grants, writes an audit line, then calls either a local HolyC service or a host service over the channel. Nothing calls a service directly. MirrorsdispatchAppBridge. - Contracts: HolyC apps implement and consume the same
os.*@1ids. The HolyC Tasks app readsos.tasks@1the same way the Kosmos Tasks app does. - Tools:
tools[]in the manifest stays data-only; the agent calls it through the same gate. - Store: the file contract (
os.files@1) is the shared document store. A HolyC Applications folder lists installed manifests. Documents keep their mime types so HolyC editors can open Kosmos documents and the reverse.
Open decisions for the owner: whether the HolyC app ids are core.* (preinstalled) or holyc.*; whether the HolyC channel is a new entry kind or
reuses url; whether an app that needs the network must always go through the host fetch service.
7. What is missing in Kosmos OS today#
| App | Present | Missing |
|---|---|---|
UI (src/apps/email/), Gmail and IMAP adapters, OAuth setup, mail store, agent tools |
os.mail@1 contract (planned as Phase 4 in app-platform-plan.md); a bundled core.mail app; a headless sync process; approval rules for send |
|
| Contacts | UI (src/apps/contacts/), import, dial pad |
Server store (today a localStorage stub); os.contacts@1; sync; a contact picker for tasks and mail |
| Maps | Leaflet UI, Nominatim and OSRM proxy, history | os.maps@1; offline tiles; a bundled core.maps app; attribution review |
| Weather | A bento widget with Open-Meteo | Weather app; os.weather@1; location permission (shell feature set has no location) |
| Music | UI, library import, RSS and live feeds, os.music@1 contract |
Playback path for TempleOS (no audio driver); bundled app manifest for the Applications folder |
| Fonts | Shell font presets only (themeTokens.ts) |
Font manager of any kind: no font files store, no install, no preview; no os.fonts@1 |
| Spreadsheets | os.sheets@1, formula engine, doc-interop export |
Native grid engine (custom, no Fortune-sheet in deps); charts; a bundled core.sheets manifest; formula coverage is partial |
| Slides | os.slides@1, apps/slides editor, PPTX export |
Present mode not verified; no presenter view; no PPTX import verified end to end |
| AI IDE | Studio app (worktrees, diffs, Monaco, browser preview, agent) | Not an app contract (os.code@1 or similar); bundled manifest; editor engine for TempleOS; the approval rule for every write and command is the spec to copy |
Cross-cutting gaps: no shared file-open routing for a MIME type (planned in office-suite-plan.md Stage 1, not confirmed built); no installed-app
windows for the agent cursor (opaque DOM, per the office plan); no audit viewer in the shell (the audit route exists).
8. Verified versus inferred#
Verified by reading: repo layout; shared/manifest.ts; manifestSchema.ts; bridge.ts (methods and token flow); packages/app-sdk (surface and wire
messages); the contract registry and per-contract intent lists; the SQLite schemas of calendar, tasks, files and calculator; the five desk3 styles and
their palette slots; tokens.css values; the os-styles data-style list; the existence and size of each app folder; the missing contracts for mail,
contacts, maps, weather, fonts and code; the absence of any LICENSE file; the bento weather widget.
Inferred or not run: dependency licences (from memory); Open-Meteo, Nominatim, OSRM and OSM usage terms; whether present mode works in Slides; whether per-tool agent policy is built; whether the file-open routing by MIME type exists; whether sheet formula coverage matches the plan; the effort estimates in section 5; the desk3 token mapping in section 2.3.
Not checked: the contents of docs/ files other than the ones named; server/agent/tools.ts; the Studio conversation store; running any app.
Also not read: apps/templeos-holyc/docs/core-apps-plan.md and os-foundation-plan.md in depth (they overlap with this document).