create-coline-app 2.3.0 → 2.5.1

package/templates/backendless/.agents/skills/coline-ui-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: coline-ui-review
+description: Review and finish a Coline App UI with local browser previews, screenshots, keyboard interaction, and light/dark/mobile states. Use after UI changes or when fixing clipping, generic layouts, broken styling, or inaccessible controls.
+---
+
+# Coline UI review — experimental
+
+1. Run `npm test` and `npm run check`. Fix new failures before visual review.
+2. Run `npm run preview`. Exercise the main action, search/filter, open/close,
+   save/discard, and recovery. Tab through the UI; confirm visible focus and
+   labelled fields. A screenshot does not prove an action works.
+3. Install Chromium if needed: `npx playwright install chromium`. Then run
+   `npm run screenshots`. For a reference pattern append `-- --pattern triage`
+   (or board/settings). Read `.coline/screenshots/report.json`.
+4. View at least ready desktop light/dark and mobile, plus affected empty/error
+   states. Check title/action hierarchy, awkward wrapping, clipped content,
+   cramped controls, contrast, and whether repeated cards should be rows.
+   Compare against the selected example or the user's visual reference.
+5. Fix the largest concrete problem, recapture the affected view, and inspect
+   again. Keep local scrolling intentional. Long content must not push actions
+   off screen. Respect reduced motion; don't animate routine data refreshes.
+6. Report what was actually tested and any limitation. The screenshot command
+   catches browser errors, whole-page overflow, and unlabelled form fields;
+   it does not grade beauty, certify accessibility, or prove hosted behavior.
+
+The preview's data resets on reload. Its state selector injects capability faults;
+if your page bypasses capabilities or swallows errors, that state may expose a
+bug rather than a useful screen. Example layouts handle state locally to make
+reference states inspectable. Test permissions/persistence on the real host
+separately when that work is in scope.
+
+Do not claim visual review if you cannot view the images. Give the image paths
+and explain what remains for someone with vision/browser tools to check.
+
+
+Keep preview cleanup scoped. The screenshot command closes its own server. For
+interactive QA, retain the terminal session or exact child-process PID you started
+and stop only that process. Never use broad `pkill -f` or `killall` commands: other
+apps may be running previews at the same time.
+
+Check dialog buttons in both themes: page-scoped CSS variables do not inherit
+into portals. Exercise form submission, Escape/close, tab keyboard navigation,
+and filter menu selection. Capture every actual app view, not only the default
+preview tab. Inspect motion and reduced-motion behavior as well as still images.
+Keep the number of attached images within the model/provider's request limit;
+review a small representative set, compact context before accumulating more,
+and record provider failures separately from app failures.

package/templates/backendless/AGENTS.md

@@ -1,169 +1,81 @@
-# AGENTS.md — building __APP_NAME__ (a Coline App)
+# Building __APP_NAME__
 
-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.
+Use the installed public packages, this project, and its examples. Do not inspect
+the private Coline product repository to discover app APIs. User instructions
+and the product's existing design take precedence over starter preferences.
 
-## Project model
+## Start here
 
-Coline hosts the app logic. There is no server, database, auth flow, or deploy
-step in this project:
+- `app.config.ts`: hosted manifest, permissions, tools, file types, tree fallbacks.
+- `main.tsx`: sandboxed React home/editor inside `ColineAppProvider`.
+- `app.css`: app styling. Tailwind v4 and ordinary CSS compile automatically.
+- `preview.seed.ts`: disposable local fixtures; never imported by production entries.
+- `examples/`: working UI references with local state, not persistent business data.
+- `app.test.ts`: logic tests using the public in-memory 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.
+For UI work, read `.agents/skills/coline-ui-design/SKILL.md`, choose the closest
+example, then use `.agents/skills/coline-ui-review/SKILL.md` to finish. These
+experimental skills are plain Markdown: follow them even if your agent has no
+skill loader. Development details: `.agents/skills/coline-app-development/SKILL.md`.
 
-## Commands
+## Working loop
 
 ```sh
 npm install
-npm run typecheck
 npm test
-
-# after local checks pass and the user has supplied these variables:
-npx coline-app dev --internal
-npx coline-app push --internal
-```
-
-`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`.
-
-## Public package contract
-
-Use only these app-facing entry points:
-
-```ts
-import { z } from "zod/v4";
-import { defineApp, defineFileType, defineTool, ui } from "@colineapp/sdk/v2";
-import { createTestWorkspace } from "@colineapp/sdk/testing";
-```
-
-For React:
-
-```tsx
-import { createRoot } from "react-dom/client";
-import { ColineAppProvider, useColine, useColineQuery } from "@colineapp/ui";
-import "@colineapp/ui/styles.css";
-```
-
-The scaffold installs the SDK, UI, React, ReactDOM, and their type packages.
-Do not replace them with private workspace paths or a second bridge.
-
-## Manifest and permissions
-
-Keep permissions minimal. Common permissions include:
-
-| 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 |
-
-Tool effects are enforced ceilings, not labels:
-
-- `read` for reads only
-- `write` for ordinary mutations
-- `destructive` for irreversible or deletion-like actions
-- `external` for outbound side effects
-
-Every tool input is a Zod schema and every tool name is prefixed with the app
-key (`__APP_KEY__.operation`).
-
-## Capability patterns
-
-```ts
-interface Decision {
-  title: string;
-  status: "proposed" | "decided";
-}
-
-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,
-});
-```
-
-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.
-
-File capabilities include `list`, `get`, `create`, `update`, `trash`,
-`getDocument`, and `updateDocument`. Navigation includes `openFile`,
-`openAppHome`, `navigate`, and `openReference`.
-
-## UI tiers
-
-Tree UI is native and works in previews, inline surfaces, mobile, and Kairo
-cards:
-
-```ts
-return ui.stack([
-  ui.heading("Decisions", { level: 1 }),
-  ui.text("No decisions yet.", { tone: "muted" }),
-]);
-```
-
-The starter home is React with a tree fallback for mobile:
-
-```ts
-surfaces: {
-  home: {
-    tier: "react",
-    entry: "main.tsx",
-    mobile: { tier: "tree" },
-  },
-}
+npm run check
+npm run preview
+# Other working screen references:
+npm run preview -- --pattern triage
+npm run preview -- --pattern board
+npm run preview -- --pattern settings
+# Install Chromium once for captures:
+npx playwright install chromium
+npm run screenshots
 ```
 
-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.
-
-## 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();
-```
-
-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.
+Preview uses simulated data, requires no credentials, resets on reload, and
+reloads when source changes. Theme and state selectors expose ready, empty,
+error, loading, and permission-denied states. Screenshots and a mechanical
+browser report go in `.coline/screenshots`. Inspect the pictures and exercise
+controls: passing checks cannot prove that a UI looks good.
+Stop only the preview terminal session/PID you started; never kill processes by
+a shared name. The screenshot command cleans up its own server.
+
+`npm run dev -- --internal` and `npm run push -- --internal` upload to Coline.
+They need `COLINE_API_KEY` with `apps.write`; `COLINE_BASE_URL` selects the host.
+Use these when publishing is in the user's scope. Local preview is not proof of
+hosted authorization, persistence, multiplayer, delivery, or performance.
+
+## Build with the public contract
+
+Use `@colineapp/sdk/v2`, `@colineapp/sdk/testing`, and `@colineapp/ui`.
+Import UI styles, then `./app.css`. Use complete utility class strings;
+`bg-${tone}` cannot be discovered by Tailwind. Use a fixed class map instead.
+The CLI bundles installed browser-compatible dependencies, CSS, and inline
+assets; there is no separate CSS command. Do not import preview fixtures into
+`main.tsx` or `app.config.ts`.
+
+Use `useColine()` for capabilities. `useColineQuery(loader, deps)` provides
+bounded loading/error/refetch for files and other reads. For collaborative
+records use `useLiveCollection`; it owns optimistic updates, version checks,
+reconciliation, and subscriptions. Catch mutation rejections, show recovery,
+and never retry a conflicting write blindly. Check installed declarations for
+query operators and method arguments; do not guess APIs.
+
+Store documents as files and structured app data in install-private collections.
+Use `expectedVersion` when saving a document. Record access policies enforce
+workspace/readers/writers on the server; hiding a button is not authorization.
+Native tasks/calendar/messages/references and shared files require explicit
+permissions and retain the invoking user's access. Render handlers/previews are
+read-only; interactive home/editor capabilities can write within grants.
+
+Prefix tools with the app key, validate input with `zod/v4`, and declare honest
+effects. UI can call `coline.tools.invoke` to share a tool with Kairo. Tree
+handlers use `ui.*`; chat cards use the restricted chat subset. Use tree mobile
+fallbacks where declared; a narrow browser preview does not prove native mobile.
+
+No direct API routes, credentials, cookies, or localStorage in the sandbox.
+External calls use `coline.net.fetch` and declared allowlists. Keep React state
+for transient UI, not as a substitute for saved records. Do not imply CRDT text
+editing, durable offline queues, presence, or public hosting from live records.

package/templates/backendless/CLAUDE.md

@@ -1,6 +1 @@
-# Claude Instructions
-
-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. For app-authoring tasks, also read
-[`.agents/skills/coline-app-development/SKILL.md`](.agents/skills/coline-app-development/SKILL.md).
+Read AGENTS.md before working. It contains the public SDK contract, local preview commands, and links to the bundled experimental UI skills.

package/templates/backendless/README.md

@@ -1,40 +1,33 @@
 # __APP_NAME__
 
-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
+A Coline App with a working notes home, editor, tool, and tree fallback.
 
 ```sh
 npm install
-npm test          # runs against the in-memory test workspace
-npm run typecheck  # checks app.config.ts and main.tsx
+npm test
+npm run check
+npm run preview
 ```
 
-## Push to Coline
-
-Create a workspace API key with the `apps.write` scope in
-**Workspace Settings → API**, then:
+Preview runs locally with disposable fixtures, no account or API key. Try its
+light/dark themes and ready/empty/error/loading/permission states. Source edits
+reload the preview. `preview.seed.ts` defines local fixtures.
 
-```sh
-export COLINE_API_KEY=col_ws_...
-npm run push
-```
+For other layouts, run `npm run preview -- --pattern triage`, `board`, or
+`settings`. Copy and adapt the examples to your product, then connect their local
+state to SDK data. `app.css` supports ordinary CSS and automatically compiled
+Tailwind utilities.
 
-Versions land in your developer console in draft state. Use
-`npm run dev` to watch the project and push on every change.
+For browser captures, install Chromium once with `npx playwright install chromium`,
+then run `npm run screenshots`. Inspect `.coline/screenshots` and its report.
+This catches browser errors, overflow, and missing form labels; visual quality
+and interactions still need review.
 
-## Grow the app
+Read [AGENTS.md](AGENTS.md) for the SDK contract and bundled experimental design,
+development, and review skills. They work as plain instructions with any agent;
+models with limited visual or tool abilities may need human review.
 
-- Add Kairo tools with `defineTool` — declare the honest `effect`
-  (`read` / `write` / `destructive` / `external`); the runtime enforces
-  it as a capability ceiling.
-- Add file types with `defineFileType` — tree previews render everywhere
-  Coline shows files, including mobile and Kairo chat.
-- 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
-  `network.external` hosts in the manifest.
+To upload, set `COLINE_API_KEY` (workspace key with `apps.write`) and optionally
+`COLINE_BASE_URL`, then run `npm run push -- --internal`. `npm run dev -- --internal`
+watches and updates a development version. Local preview does not test production
+persistence, authorization, multiplayer, or deployment.

package/templates/backendless/app.config.ts

@@ -11,16 +11,14 @@ const noteFileType = defineFileType({
     name: "__APP_NAME__ Note",
     indexable: true,
     surfaces: {
+      editor: { tier: "react", entry: "main.tsx" },
       preview: { tier: "tree" },
       inline: { tier: "tree" },
     },
   },
   runtime: {
     renderPreview: (context) =>
-      ui.stack([
-        ui.heading(context.file.name),
-        ui.text(String(context.document.body ?? "")),
-      ]),
+      ui.stack([ui.heading(context.file.name), ui.text(String(context.document.body ?? ""))]),
     renderInline: (context) => ui.text(context.file.name),
     index: {
       title: (document) => String(document.title ?? "Untitled note"),
@@ -41,7 +39,7 @@ const createNote = defineTool({
     const file = await context.coline.files.create({
       typeKey: "__APP_KEY__.note",
       name: input.title,
-      document: { body: input.body },
+      document: { title: input.title, body: input.body },
     });
     return {
       output: { fileId: file.fileId },
@@ -57,7 +55,7 @@ export default defineApp({
   key: "__APP_KEY__",
   name: "__APP_NAME__",
   description: "A starter Coline App.",
-  permissions: ["files.read", "files.write", "storage.app", "ai.tools"],
+  permissions: ["files.read", "files.write", "storage.app", "ai.tools", "drives.app"],
   hosting: { default: "coline" },
   surfaces: {
     home: {
@@ -77,9 +75,15 @@ export default defineApp({
       return ui.stack(
         [
           ui.heading("__APP_NAME__ is running", { level: 1 }),
-          ui.text("Edit app.config.ts and save — dev mode hot-swaps this screen instantly.", {
-            tone: "muted",
+          ui.button("New note", {
+            action: actions.invokeTool("__APP_KEY__.create_note", { title: "Untitled note" }),
           }),
+          ui.text(
+            "Edit app.config.ts and save — dev mode updates this app; reload to see changes.",
+            {
+              tone: "muted",
+            },
+          ),
           ui.card({
             title: "Try the example tool",
             description:

package/templates/backendless/app.css

@@ -0,0 +1,84 @@
+/* Compiled automatically by check, preview, dev, and push. Use complete class names. */
+@import "tailwindcss";
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+}
+
+body {
+  margin: 0;
+}
+.note-editor {
+  display: grid;
+  gap: 24px;
+}
+.note-editor label {
+  display: grid;
+  gap: 8px;
+  font-size: 13px;
+  font-weight: 500;
+}
+.note-editor textarea {
+  min-height: 340px;
+  line-height: 1.7;
+}
+.example-meta {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--muted-foreground);
+  font-size: 12px;
+}
+.example-select {
+  border: 1px solid var(--border);
+  background: var(--background);
+  color: var(--foreground);
+  border-radius: 6px;
+  padding: 7px 9px;
+  font: inherit;
+  max-width: 100%;
+}
+.example-field {
+  display: grid;
+  gap: 8px;
+  font-size: 13px;
+}
+.example-description {
+  font-size: 13px;
+  line-height: 1.7;
+  color: var(--muted-foreground);
+}
+
+.coline-settings-fields .example-toggle {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.example-description {
+  margin: 12px 0 18px;
+}