create-coline-app 2.2.0 → 2.3.0

package/AGENTS.md

@@ -0,0 +1,62 @@
+# create-coline-app package agent guide
+
+This package owns the external developer experience: the `create-coline-app`
+scaffold and the `coline-app push/dev` CLI. The template is a tested public
+contract, not illustrative pseudocode.
+
+## Source of truth
+
+- `src/scaffold.ts` copies `templates/backendless` and replaces app
+  placeholders.
+- `src/push.ts` bundles `app.config.ts`, extracts the manifest, and collects
+  `main.tsx` plus app `.ts`, `.tsx`, and `.css` source for React surfaces.
+- `templates/backendless/AGENTS.md` is the primary guidance delivered to
+  every generated app.
+- `templates/backendless/.agents/skills/` contains the reusable task skill
+  discovered by OpenCode/Codex-style agents.
+
+## Non-negotiable scaffold contract
+
+After a clean `npx create-coline-app app && cd app && npm install`, the project
+must have a working backend example, a working React starter, accurate agent
+guidance, and tests that do not need the Coline product repository or a running
+Coline server.
+
+Keep these versions aligned in one release:
+
+- `@colineapp/sdk` — logic, manifest, capabilities, tree UI, test workspace
+- `@colineapp/ui` — React provider, hooks, components, stylesheet
+- `@colineapp/app-runtime` — transitive guest/host bridge dependency
+- `create-coline-app` — scaffold and push/dev CLI
+
+When any public API changes, update the package README, package `AGENTS.md`,
+template `AGENTS.md`, template skill, template dependencies, and the focused
+smoke test together.
+
+## Agent-safety rules
+
+- A generated app must be self-describing. Agents should not need to inspect
+  `/Users/radin/coline-app`, a worktree, or private first-party apps.
+- Do not make the template point at local workspace packages or private URLs.
+- Do not claim a dependency is “already wired” unless it is in the generated
+  `package.json` and exercised by the template.
+- Do not add a React example without the `main.tsx` entry, React peer packages,
+  CSS export, and a manifest surface that references it.
+- Keep external hosting, network, auth, and database claims explicit. The
+  default app is hosted and backendless.
+
+## Verification
+
+- Run `pnpm --filter create-coline-app typecheck` and
+  `pnpm --filter create-coline-app test`.
+- The CLI tests must assert placeholder replacement, exact package dependency
+  wiring, the React starter's presence, and that the app config bundles against
+  the real SDK source.
+- Never use a checked-in private app as the only proof that a public scaffold
+  works. Add the smallest self-contained fixture instead.
+
+## Release hygiene
+
+The package publishes `bin`, `src`, `templates`, `README.md`, `AGENTS.md`, and
+`LICENSE`. Bump the CLI version when the template contract changes. Publish
+the three runtime libraries first, then publish this CLI with matching ranges.

package/README.md

@@ -9,9 +9,10 @@ cd my-app && npm install && npm test
 
 Two binaries ship from this package:
 
-- **`create-coline-app <dir>`** — scaffolds a backendless app: a
-  `defineApp` config with a Kairo tool, a file type with tree surfaces,
-  a hosted home surface, and tests against `@colineapp/sdk/testing`.
+- **`create-coline-app <dir>`** — scaffolds a self-contained backendless app:
+  a `defineApp` config with a Kairo tool, a file type with tree surfaces, a
+  working React home using `@colineapp/ui`, mobile/tree fallback rendering,
+  agent guidance, and tests against `@colineapp/sdk/testing`.
 - **`coline-app push | dev`** — builds the logic bundle with esbuild,
   extracts the manifest through the two-artifact model (plan §6.2),
   collects client source when the manifest declares react surfaces, and
@@ -20,3 +21,8 @@ Two binaries ship from this package:
 
 The CLI never builds tier-2 client bundles itself — it ships source and
 Coline's reviewed build pipeline produces the bundle.
+
+The generated project includes `AGENTS.md` and
+`.agents/skills/coline-app-development/SKILL.md`. Those files are deliberately
+specific to the installed public packages so coding agents can work without
+reading Coline's private product repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-coline-app",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Scaffold, push, and iterate on Coline Apps.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "src",
     "templates",
     "README.md",
+    "AGENTS.md",
     "LICENSE"
   ],
   "dependencies": {

package/src/cli.test.ts

@@ -48,8 +48,21 @@ describe("runCreate", () => {
     expect(config).not.toContain("__APP_KEY__");
     const packageJson = JSON.parse(await readFile(join(dir, "package.json"), "utf8")) as {
       name: string;
+      dependencies: Record<string, string>;
+      devDependencies: Record<string, string>;
     };
     expect(packageJson.name).toBe("team-crm");
+    expect(packageJson.dependencies["@colineapp/sdk"]).toBe("^0.3.1");
+    expect(packageJson.dependencies["@colineapp/ui"]).toBe("^0.3.1");
+    expect(packageJson.dependencies.react).toBe("^19.0.0");
+    expect(packageJson.dependencies["react-dom"]).toBe("^19.0.0");
+    expect(packageJson.devDependencies["create-coline-app"]).toBe("^2.3.0");
+    await expect(readFile(join(dir, "main.tsx"), "utf8")).resolves.toContain(
+      "ColineAppProvider",
+    );
+    await expect(
+      readFile(join(dir, ".agents/skills/coline-app-development/SKILL.md"), "utf8"),
+    ).resolves.toContain("Do not inspect");
     await expect(readFile(join(dir, ".gitignore"), "utf8")).resolves.toContain("node_modules");
   });
 
@@ -97,4 +110,39 @@ describe("runCreate", () => {
     expect(imported.default.manifest.key).toBe("smoke-app");
     expect(imported.default.manifest.tools[0]?.name).toBe("smoke-app.create_note");
   });
+
+  it("contains a React starter that bundles against the public UI packages", async () => {
+    const dir = await scaffoldTemp("react-smoke");
+    const packagesRoot = resolve(__dirname, "..", "..");
+    const sdkRoot = join(packagesRoot, "sdk");
+    const runtimeRoot = join(packagesRoot, "app-runtime");
+    const uiRoot = join(packagesRoot, "coline-ui");
+    const sdkRequire = createRequire(join(sdkRoot, "package.json"));
+    const uiRequire = createRequire(join(uiRoot, "package.json"));
+    const result = await build({
+      entryPoints: [join(dir, "main.tsx")],
+      bundle: true,
+      write: false,
+      format: "iife",
+      platform: "browser",
+      target: "es2022",
+      jsx: "automatic",
+      logLevel: "silent",
+      absWorkingDir: packagesRoot,
+      nodePaths: [resolve(packagesRoot, "..", "node_modules")],
+      alias: {
+        "@colineapp/sdk/v2": join(sdkRoot, "src", "v2.ts"),
+        "@colineapp/app-runtime": join(runtimeRoot, "src", "index.ts"),
+        "@colineapp/ui": join(uiRoot, "src", "index.ts"),
+        "@colineapp/ui/styles.css": join(uiRoot, "src", "styles", "base.css"),
+        react: uiRequire.resolve("react"),
+        "react-dom": uiRequire.resolve("react-dom"),
+        "react-dom/client": uiRequire.resolve("react-dom/client"),
+        "react/jsx-runtime": uiRequire.resolve("react/jsx-runtime"),
+        "zod/v4": sdkRequire.resolve("zod/v4"),
+      },
+      loader: { ".css": "empty" },
+    });
+    expect(result.outputFiles?.[0]?.text).toBeTruthy();
+  });
 });

package/templates/backendless/.agents/skills/coline-app-development/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: coline-app-development
+description: Build and debug a Coline App using the public SDK, hosted capabilities, tree UI, and sandboxed React UI.
+---
+
+# Coline App development
+
+Use this skill for any task that changes a generated Coline App.
+
+## Start from the shipped contract
+
+Read the repository `AGENTS.md`, `app.config.ts`, `main.tsx`, `app.test.ts`,
+and `package.json`. The generated project is intentionally self-contained.
+Do not inspect `/Users/radin/coline-app`, private worktrees, first-party apps,
+or product internals to learn an app-authoring API. Use the installed package
+types, README files, and this skill.
+
+The project has two halves:
+
+- `app.config.ts` is the hosted logic bundle: manifest, permissions, tools,
+  file types, tree handlers, and capability calls.
+- `main.tsx` is the React client entry. The starter includes `@colineapp/ui`,
+  React, ReactDOM, and the CSS export; do not add a second bridge or fetch
+  data from a Coline API route.
+
+## Choose the right surface
+
+- Use `ui.*` tree nodes for previews, inline surfaces, mobile fallbacks, and
+  simple Kairo cards.
+- Use a React surface when the app needs local interaction, filtering, forms,
+  or an editor. Declare `{ tier: "react", entry: "main.tsx" }` and keep the
+  root wrapped in `<ColineAppProvider>`.
+- Use `useColine()` for capability calls and `useColineQuery()` for a bounded
+  loading/error/refetch loop. Never use `fetch`, localStorage, cookies, or
+  credentials in the sandbox.
+
+## Public SDK rules
+
+- Import logic from `@colineapp/sdk/v2` and tests from `@colineapp/sdk/testing`.
+- Prefix every tool name with the app key.
+- Validate inputs with `zod/v4` and declare honest effects (`read`, `write`,
+  `destructive`, or `external`).
+- Ask for the minimum permissions. Capability calls still require both the
+  declared permission and the tool effect ceiling.
+- Collections are typed record envelopes. `where` is exact-match on top-level
+  fields; query bounded pages and filter more complex predicates in memory.
+- Use `ui.*` for hosted handlers. Chat tool cards must stay within the
+  validated chat subset and remain small.
+
+## UI rules
+
+- Import components from `@colineapp/ui` and `@colineapp/ui/styles.css`.
+- Use the host theme tokens (`bg-background`, `text-foreground`,
+  `text-muted-foreground`, and related tokens); dark mode is supplied by the
+  host.
+- Render explicit loading, empty, and error states.
+- Keep components accessible and use the provided controls before writing
+  custom primitives.
+- Do not add a state library or network client for the first implementation.
+
+## Verify before pushing
+
+```sh
+npm run typecheck
+npm test
+```
+
+Then push with `npx coline-app dev --internal` or `npx coline-app push --internal`
+when the user has supplied `COLINE_BASE_URL` and `COLINE_API_KEY`. The local
+test workspace is the first proof; the hosted app is the second.

package/templates/backendless/AGENTS.md

@@ -1,196 +1,169 @@
 # AGENTS.md — building __APP_NAME__ (a Coline App)
 
-You are working on a Coline App. Everything an agent needs is in this file —
-no URLs required. The scaffold compiles, tests, and runs as-is; evolve it
-rather than starting from a blank page.
+This is a self-contained Coline App project. Read this file before changing
+code. The public SDK, UI package, tests, and this guide are the contract; do
+not inspect the Coline product repository or private worktrees to discover how
+to build an app.
 
-## What a Coline App is
+## Project model
 
-A Coline App runs INSIDE a Coline workspace on Coline's hosted runtime.
-There are no servers, no database, no auth, no deploys — the platform
-provides all of it through the `coline.*` capability API:
+Coline hosts the app logic. There is no server, database, auth flow, or deploy
+step in this project:
 
-- `app.config.ts` — the ENTIRE backend: manifest + tools + file types +
-  UI handlers, bundled and executed server-side by Coline.
-- `main.tsx` (optional) — a React UI running in a locked sandbox iframe.
-  Create it only if the manifest declares a `react` tier surface.
-- `app.test.ts` — tests against an in-memory fake workspace.
+- `app.config.ts` is the hosted logic bundle: manifest, permissions, tools,
+  file types, tree handlers, and capability calls.
+- `main.tsx` is the React client entry for the starter home surface. It runs in
+  a locked sandbox iframe and uses `@colineapp/ui`.
+- `app.test.ts` runs the logic against `createTestWorkspace`, an in-memory
+  capability fake. It does not need a Coline server.
+- `.agents/skills/coline-app-development/SKILL.md` is the detailed task
+  workflow for agents that support skills.
 
 ## Commands
 
-- `npm test` — run tests (in-memory workspace; no Coline instance needed)
-- `npm run typecheck` — strict TS; keep it clean
-- `npx coline-app dev --internal` — watch mode; every save pushes a
-  `0.0.0-dev` version that hot-swaps the live app (reload the app page)
-- `npx coline-app push --internal` — one-off push as a workspace-internal
-  app (auto-approved, private to the workspace)
-- Needs `COLINE_API_KEY` (workspace API key with `apps.write` scope) and
-  `COLINE_BASE_URL` (the Coline instance) in the environment.
+```sh
+npm install
+npm run typecheck
+npm test
 
-## The manifest (`defineApp`)
-
-```ts
-export default defineApp({
-  key: "__APP_KEY__",           // immutable, lowercase, hyphens
-  name: "__APP_NAME__",
-  description: "…",
-  permissions: [...],            // ONLY what you use — users see this list
-  hosting: { default: "coline" },// hosted runtime (no external server)
-  surfaces: { home: { tier: "tree" } }, // or { tier: "react" } with main.tsx
-  files: [...],                  // custom file types (optional)
-  tools: [...],                  // Kairo tools (optional)
-  handlers: { renderHome: async (context) => uiNode },
-});
+# after local checks pass and the user has supplied these variables:
+npx coline-app dev --internal
+npx coline-app push --internal
 ```
 
-### Permissions (request the minimum)
-
-| key | grants |
-| --- | --- |
-| `storage.app` | app key-value + record collections |
-| `files.read` / `files.write` | read / create workspace files |
-| `drives.app` | a private drive owned by the app |
-| `members.read` | list workspace members |
-| `search.index` / `search.query` | add to / query workspace search |
-| `notifications.write` | send notifications |
-| `ai.generate` | call Coline's AI model (200/day) |
-| `ai.tools` | expose tools to Kairo (the workspace AI) |
-| `events.emit` | publish app events |
-| `commands.register` | add command-palette commands |
-| `realtime.subscribe` | live updates in the UI |
-| `network.external` | HTTPS fetch to allowlisted hosts only |
-
-## Tools (`defineTool`) — how Kairo operates your app
+`COLINE_BASE_URL` selects the Coline instance and `COLINE_API_KEY` must be a
+workspace API key with `apps.write`. The CLI uploads `app.config.ts` as a
+logic bundle and submits `main.tsx` plus app `.ts`, `.tsx`, and `.css` source
+when the manifest declares a React surface. It never uploads `node_modules`.
 
-```ts
-const logDecision = defineTool({
-  name: "__APP_KEY__.log_decision",   // MUST be prefixed with the app key
-  description: "…",                    // what Kairo reads to pick the tool
-  input: z.object({ title: z.string().min(1) }),  // zod schema
-  effect: "write",                     // read | write | destructive | external
-  execute: async (input, context) => {
-    // context.coline — the capability client
-    // context.workspace — { id, slug, name }
-    // context.actor — who invoked it
-    return {
-      output: { id: "…" },            // structured result for the model
-      card: ui.stack([...]),           // optional rich card shown in chat
-    };
-  },
-});
-```
+## Public package contract
 
-`effect` is ENFORCED by the runtime, not a hint: a `read` tool cannot
-write. Reads auto-approve; `write` follows the session's permission mode;
-`destructive`/`external` always prompt the user. Be honest.
-
-## Storage — `coline.storage`
+Use only these app-facing entry points:
 
 ```ts
-// Key-value
-await context.coline.storage.kv.set("settings", { theme: "auto" });
-const settings = await context.coline.storage.kv.get("settings");
+import { z } from "zod/v4";
+import { defineApp, defineFileType, defineTool, ui } from "@colineapp/sdk/v2";
+import { createTestWorkspace } from "@colineapp/sdk/testing";
+```
 
-// Typed record collections (the main data store)
-interface Decision { title: string; status: "proposed" | "decided"; tags: string[] }
-const decisions = context.coline.storage.collection<Decision>("decisions");
+For React:
 
-const rec = await decisions.insert({ title: "Use Postgres", status: "decided", tags: ["infra"] });
-await decisions.update(rec.id, { status: "proposed" });
-await decisions.get(rec.id);            // envelope | null
-await decisions.delete(rec.id);
-const { records, nextCursor } = await decisions.query({
-  where: { status: "decided" },          // exact-match on top-level fields
-  orderBy: "title", order: "asc",       // or omit for newest-first
-  limit: 50, cursor: undefined,
-});
-// Every record comes wrapped: { id, createdBy, createdAt, updatedAt, data }
+```tsx
+import { createRoot } from "react-dom/client";
+import { ColineAppProvider, useColine, useColineQuery } from "@colineapp/ui";
+import "@colineapp/ui/styles.css";
 ```
 
-Limits: 5,000 kv keys · 200,000 records per collection · 200 kB per value.
-`query.where` is exact-match only — filter/search in memory after querying
-when you need contains/ranges (keep result sets bounded with `limit`).
+The scaffold installs the SDK, UI, React, ReactDOM, and their type packages.
+Do not replace them with private workspace paths or a second bridge.
 
-## UI — two tiers
+## Manifest and permissions
 
-### Tree tier (`ui.*` builders) — renders everywhere incl. mobile & chat cards
+Keep permissions minimal. Common permissions include:
 
-`ui.stack(children, { direction?, gap? })` · `ui.row(children)` ·
-`ui.heading(text, { level? 1-4 })` · `ui.text(text, { tone? })` ·
-`ui.badge(text, { tone? })` · `ui.card({ title?, description?, children?, footer? })` ·
-`ui.button({ label, action, variant? })` · `ui.divider()` ·
-`ui.emptyState({ title, description? })` · `ui.fileCard({ title, fileId, action? })` ·
-`ui.table({ columns, rows })` · `ui.link({ label, href })` · `ui.image({ src, alt })`
+| Permission | Use |
+| --- | --- |
+| `storage.app` | App-private key/value and typed record collections |
+| `files.read` / `files.write` | Read or create workspace files |
+| `ai.tools` | Expose app tools to Kairo |
+| `members.read` | Read workspace member summaries |
+| `search.index` / `search.query` | Index or query workspace search |
+| `network.external` | Use `coline.net.fetch` for allowlisted hosts |
 
-Tones: `default | muted | positive | warning | danger`.
-Actions: `actions.openFile(fileId)`, `actions.openAppHome()`,
-`actions.navigate(path)`, `actions.createFile(...)`, `actions.custom(name, payload)`.
-Chat cards (tool results) allow a validated subset — keep them simple
-(stack/heading/text/badge/table/fileCard are all safe). Max 120 nodes.
+Tool effects are enforced ceilings, not labels:
 
-### React tier (`main.tsx` + `@colineapp/ui`) — full React in a sandbox
+- `read` for reads only
+- `write` for ordinary mutations
+- `destructive` for irreversible or deletion-like actions
+- `external` for outbound side effects
 
-Set `surfaces: { home: { tier: "react" } }` and create `main.tsx`:
+Every tool input is a Zod schema and every tool name is prefixed with the app
+key (`__APP_KEY__.operation`).
 
-```tsx
-import { createRoot } from "react-dom/client";
-import { ColineAppProvider, useColine, useColineQuery, useColineContext } from "@colineapp/ui";
+## Capability patterns
 
-function Home() {
-  const coline = useColine();                       // capability client
-  const { data, isLoading, error, refetch } =      // simple async hook
-    useColineQuery(() => coline.storage.collection("decisions").query({ limit: 100 }), []);
-  // …render
+```ts
+interface Decision {
+  title: string;
+  status: "proposed" | "decided";
 }
 
-const root = document.getElementById("root");
-if (root) createRoot(root).render(<ColineAppProvider><Home /></ColineAppProvider>);
+const decisions = context.coline.storage.collection<Decision>("decisions");
+const created = await decisions.insert({ title: "Use Postgres", status: "decided" });
+const page = await decisions.query({
+  where: { status: "decided" },
+  orderBy: "title",
+  order: "asc",
+  limit: 50,
+});
 ```
 
-Sandbox rules (enforced, not conventions):
-- NO network (`fetch` is blocked by CSP), no localStorage, no cookies.
-  ALL data flows through the `coline.*` client over the capability bridge.
-- Theme tokens follow the host automatically (dark mode included) — use
-  the CSS variables / `@colineapp/ui` components, never hardcoded colors.
-- One bundle per app: switch on `useColineContext().surface` if you have
-  multiple react surfaces.
+Collection `where` is exact-match on top-level fields. Records are envelopes
+with the user data under `.data`. Keep pages bounded and filter contains,
+search, or range conditions in app code.
 
-## Rate limits & budgets
+File capabilities include `list`, `get`, `create`, `update`, `trash`,
+`getDocument`, and `updateDocument`. Navigation includes `openFile`,
+`openAppHome`, `navigate`, and `openReference`.
 
-120 capability calls burst / 20 per second per install · `net.fetch`
-20 burst / 2 per second · `ai.generate` 200/day · 10,000 executions/day.
-Exceeding any returns a named error visible in the execution log.
+## UI tiers
 
-## Testing (`app.test.ts` pattern)
+Tree UI is native and works in previews, inline surfaces, mobile, and Kairo
+cards:
 
 ```ts
-import { describe, expect, it } from "vitest";
-import { createTestWorkspace } from "@colineapp/sdk/testing";
-import app from "./app.config";
-
-it("logs a decision", async () => {
-  const workspace = createTestWorkspace(app);
-  const result = await workspace.invokeTool("__APP_KEY__.log_decision", {
-    title: "Use Postgres",
-  });
-  expect(result.card).not.toBeNull();       // result: { output, card }
-  // Also available: workspace.renderHome(), workspace.files.byType(...),
-  // workspace.renderFileSurface(...), workspace.fireSchedule(...)
-});
+return ui.stack([
+  ui.heading("Decisions", { level: 1 }),
+  ui.text("No decisions yet.", { tone: "muted" }),
+]);
 ```
 
-## Debugging
+The starter home is React with a tree fallback for mobile:
 
-- Tool throws → the error lands in the app's execution log (developer
-  console → your app → Executions) with the message redacted of secrets.
-- Permission denied → the manifest doesn't declare it, the user didn't
-  grant it, or the tool's `effect` is too low for the operation.
-- UI blank → check the browser console for the sandbox frame; the
-  capability bridge logs denials with reason codes.
+```ts
+surfaces: {
+  home: {
+    tier: "react",
+    entry: "main.tsx",
+    mobile: { tier: "tree" },
+  },
+}
+```
+
+In `main.tsx`, put the app under `ColineAppProvider`. Call capabilities only
+through `useColine()`, and use `useColineQuery(loader, deps)` for bounded
+loading/error/refetch state. The host supplies theme tokens and dark mode.
+Use classes such as `bg-background`, `text-foreground`,
+`text-muted-foreground`, and the exported UI components.
+
+Sandbox restrictions are real: no `fetch`, localStorage, cookies, credentials,
+or direct Coline API routes. External access goes through `coline.net.fetch`
+and a manifest allowlist.
 
-## Style rules for the UI
+## Testing workflow
+
+```ts
+const workspace = createTestWorkspace(app);
+const result = await workspace.invokeTool("__APP_KEY__.create_note", {
+  title: "Hello",
+});
+expect(result.card).not.toBeNull();
+expect(workspace.files.byType("__APP_KEY__.note")).toHaveLength(1);
+const tree = await workspace.renderHome();
+```
 
-- No eyebrow labels / kicker pills above headings. No monospace accent
-  fonts. Solid font weights (500–600).
-- Explicit loading, empty, and error states for every async view.
-- Dark mode must work — it's automatic if you use theme tokens.
+Test tools and tree handlers without a server. React client behavior is
+covered by the typecheck and the hosted dev loop after the logic tests pass.
+Keep explicit loading, empty, and error states in every async React view.
+
+## Agent boundaries
+
+- Do not read `/Users/radin/coline-app`, any `*.worktrees` directory, or
+  first-party app code to understand this public API.
+- Do not add dependencies until checking whether the installed SDK/UI already
+  provides the capability or component.
+- Do not invent signatures from a README snippet: use the installed package
+  declarations when a detail is unclear, then update this guide if the public
+  contract is missing.
+- Keep changes inside this generated app. Ask the user before changing the
+  platform or publishing packages.

package/templates/backendless/CLAUDE.md

@@ -2,4 +2,5 @@
 
 Read and follow [`AGENTS.md`](./AGENTS.md) — it contains the complete
 Coline App contract: capabilities, tools, storage, UI builders, sandbox
-rules, limits, and testing patterns.
+rules, limits, and testing patterns. For app-authoring tasks, also read
+[`.agents/skills/coline-app-development/SKILL.md`](.agents/skills/coline-app-development/SKILL.md).

package/templates/backendless/README.md

@@ -1,13 +1,15 @@
 # __APP_NAME__
 
-A backendless Coline App. The logic in `app.config.ts` runs on Coline's
-hosted runtime — no servers to deploy.
+A hosted, backendless Coline App. The logic in `app.config.ts` runs on
+Coline's hosted runtime — no servers to deploy. The starter also includes a
+working React home in `main.tsx` using `@colineapp/ui`.
 
 ## Develop
 
 ```sh
 npm install
 npm test          # runs against the in-memory test workspace
+npm run typecheck  # checks app.config.ts and main.tsx
 ```
 
 ## Push to Coline
@@ -30,8 +32,8 @@ Versions land in your developer console in draft state. Use
   it as a capability ceiling.
 - Add file types with `defineFileType` — tree previews render everywhere
   Coline shows files, including mobile and Kairo chat.
-- Add a React editor by setting a file surface to
-  `{ tier: "react", entry: "main.tsx" }` and creating `main.tsx`.
+- The starter home is already a React surface. Keep `main.tsx` as the single
+  client entry and use `@colineapp/ui` for components, provider, and hooks.
 - Store app-private data with `coline.storage.kv` and
   `coline.storage.collection(name)`.
 - Call external APIs with `coline.net.fetch` after declaring

package/templates/backendless/app.config.ts

@@ -1,7 +1,7 @@
 import { z } from "zod/v4";
 import { actions, defineApp, defineFileType, defineTool, ui } from "@colineapp/sdk/v2";
 
-// __APP_NAME__ — a backendless Coline App. Everything here runs on
+// __APP_NAME__ — a hosted, backendless Coline App. Everything here runs on
 // Coline's hosted runtime: no servers, no deploys. `coline-app push`
 // uploads this file as the logic bundle and main.tsx as client source.
 
@@ -60,12 +60,16 @@ export default defineApp({
   permissions: ["files.read", "files.write", "storage.app", "ai.tools"],
   hosting: { default: "coline" },
   surfaces: {
-    home: { tier: "tree" },
+    home: {
+      tier: "react",
+      entry: "main.tsx",
+      mobile: { tier: "tree" },
+    },
   },
   files: [noteFileType],
   tools: [createNote],
   handlers: {
-    // The starter home screen — replace this with your app's real UI.
+    // The mobile/tree fallback. The React home lives in main.tsx.
     renderHome: async (context) => {
       const { files } = await context.coline.files.list({
         typeKey: "__APP_KEY__.note",

package/templates/backendless/main.tsx

@@ -0,0 +1,100 @@
+import { createRoot } from "react-dom/client";
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  ColineAppProvider,
+  Skeleton,
+  useColine,
+  useColineQuery,
+} from "@colineapp/ui";
+import type { ColineFileSummaryV2 } from "@colineapp/sdk/v2";
+import "@colineapp/ui/styles.css";
+
+function StarterHome() {
+  const coline = useColine();
+  const files = useColineQuery(
+    (capabilities) =>
+      capabilities.files.list({ typeKey: "__APP_KEY__.note", limit: 50 }),
+    [],
+  );
+  const notes = files.data?.files ?? [];
+
+  async function createNote(): Promise<void> {
+    const file = await coline.files.create({
+      typeKey: "__APP_KEY__.note",
+      name: "Untitled note",
+      document: { title: "Untitled note", body: "" },
+    });
+    await coline.navigation.openFile(file.fileId);
+  }
+
+  return (
+    <main className="mx-auto flex min-h-screen w-full max-w-3xl flex-col gap-6 bg-background p-6 text-foreground">
+      <header className="flex items-center justify-between gap-4">
+        <div>
+          <h1 className="text-xl font-semibold">__APP_NAME__ is running</h1>
+          <p className="mt-1 text-sm text-muted-foreground">
+            Edit app.config.ts or main.tsx and save to hot-swap this app.
+          </p>
+        </div>
+        <Button onClick={() => void createNote()}>New note</Button>
+      </header>
+
+      {files.isLoading ? (
+        <div className="flex flex-col gap-2">
+          <Skeleton className="h-16 w-full" />
+          <Skeleton className="h-16 w-full" />
+        </div>
+      ) : files.error ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>Couldn&apos;t load notes</CardTitle>
+            <CardDescription>{files.error}</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Button variant="outline" onClick={files.refetch}>
+              Retry
+            </Button>
+          </CardContent>
+        </Card>
+      ) : notes.length === 0 ? (
+        <Card>
+          <CardHeader>
+            <CardTitle>Edit me</CardTitle>
+            <CardDescription>
+              This is a real React surface. Replace this starter with your app,
+              then ask Kairo to create a note called Hello.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+      ) : (
+        <div className="flex flex-col gap-2">
+          {notes.map((file: ColineFileSummaryV2) => (
+            <button
+              key={file.fileId}
+              type="button"
+              onClick={() => void coline.navigation.openFile(file.fileId)}
+              className="rounded-xl border border-border bg-card px-4 py-3 text-left hover:bg-muted/50"
+            >
+              <p className="text-sm font-medium">{file.name}</p>
+              <p className="mt-1 text-xs text-muted-foreground">Open note</p>
+            </button>
+          ))}
+        </div>
+      )}
+    </main>
+  );
+}
+
+const root = document.getElementById("root");
+if (root) {
+  createRoot(root).render(
+    <ColineAppProvider>
+      <StarterHome />
+    </ColineAppProvider>,
+  );
+}

package/templates/backendless/package.json

@@ -10,12 +10,17 @@
     "dev": "coline-app dev"
   },
   "dependencies": {
-    "@colineapp/sdk": "^0.3.0",
-    "zod": "^4.0.0"
+    "@colineapp/sdk": "^0.3.1",
+    "@colineapp/ui": "^0.3.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "create-coline-app": "^2.0.0",
-    "typescript": "^5.7.2",
-    "vitest": "^3.0.5"
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "create-coline-app": "^2.3.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
   }
 }