@construct-space/cli 1.5.0 → 1.6.0

package/README.md

@@ -23,6 +23,25 @@ construct check                # Type-check + lint
 construct clean                # Remove build artifacts
 ```
 
+### Built-in libraries
+
+Scaffolded spaces ship with the full Construct stack pre-wired — import freely, the host resolves them at runtime (never bundled):
+
+| Package | Purpose |
+|---------|---------|
+| `@construct-space/ui` | Vue 3 components — `Button`, `Card`, `Modal`, `Table`, `Badge`, `Avatar`, `ToggleGroup`, `ConfirmationModal`, ... |
+| `@construct-space/sdk` | Host composables — `useOrg`, `useOrgMembers`, `useToast`, `useAuth` |
+| `@construct-space/graph` | Multi-tenant data layer — `defineModel`, `useGraph`, scopes, access rules |
+| `lucide-vue-next` | Icon set |
+
+```ts
+import { Button, Card, Modal } from '@construct-space/ui'
+import { useOrg, useOrgMembers } from '@construct-space/sdk'
+import { defineModel, field, useGraph } from '@construct-space/graph'
+```
+
+The scaffolded `src/pages/index.vue` and `src/actions.ts` show the recommended patterns. Use `construct check` (typecheck + ESLint flat config) before commit.
+
 ### Graph (Data Models)
 
 ```bash

package/dist/index.js

@@ -2887,14 +2887,47 @@ function store(creds) {
 }
 function load2() {
   const path = credentialsPath();
-  if (!existsSync10(path)) {
-    throw new Error("not logged in \u2014 run 'construct login' first");
+  if (existsSync10(path)) {
+    const data = JSON.parse(readFileSync7(path, "utf-8"));
+    if (data.token)
+      return data;
   }
-  const data = JSON.parse(readFileSync7(path, "utf-8"));
-  if (!data.token) {
-    throw new Error("not logged in \u2014 run 'construct login' first");
+  const fromProfile = loadFromActiveProfile();
+  if (fromProfile)
+    return fromProfile;
+  throw new Error("not logged in \u2014 run 'construct login' first");
+}
+function loadFromActiveProfile() {
+  try {
+    const regPath = join12(dataDir(), "profiles.json");
+    if (!existsSync10(regPath))
+      return null;
+    const reg = JSON.parse(readFileSync7(regPath, "utf-8"));
+    const activeId = reg.active_profile;
+    if (!activeId)
+      return null;
+    const authPath = join12(profilesDir(), activeId, "auth.json");
+    if (!existsSync10(authPath))
+      return null;
+    const a = JSON.parse(readFileSync7(authPath, "utf-8"));
+    if (!a.token)
+      return null;
+    if (a.authenticated === false)
+      return null;
+    const u = a.user || {};
+    return {
+      token: a.token,
+      portal: DEFAULT_PORTAL,
+      profileId: activeId,
+      user: {
+        id: u.id || u.uuid || activeId,
+        name: u.name || u.username || activeId,
+        email: u.email || ""
+      }
+    };
+  } catch {
+    return null;
   }
-  return data;
 }
 function isAuthenticated() {
   try {
@@ -5280,8 +5313,10 @@ async function scaffold(nameArg, options) {
     "safety.json.tmpl": join2(name, "agent", "hooks", "safety.json"),
     "build.yml.tmpl": join2(name, ".github", "workflows", "build.yml"),
     "tsconfig.json.tmpl": join2(name, "tsconfig.json"),
+    "eslint.config.js.tmpl": join2(name, "eslint.config.js"),
     "gitignore.tmpl": join2(name, ".gitignore"),
     "readme.md.tmpl": join2(name, "README.md"),
+    "construct.md.tmpl": join2(name, "CONSTRUCT.md"),
     "widgets/2x1.vue.tmpl": join2(name, "widgets", "summary", "2x1.vue"),
     "widgets/4x1.vue.tmpl": join2(name, "widgets", "summary", "4x1.vue"),
     "actions.ts.tmpl": join2(name, "src", "actions.ts")
@@ -7956,6 +7991,7 @@ function ora(options) {
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync3 } from "fs";
 import { join as join3 } from "path";
 var MANIFEST_FILE = "space.manifest.json";
+var HOST_API_VERSION = "0.5.0";
 var idRegex = /^[a-z][a-z0-9-]*$/;
 var versionRegex = /^\d+\.\d+\.\d+/;
 function validate2(m) {
@@ -8301,7 +8337,7 @@ async function build(options) {
   writeWithBuild(distDir, raw, {
     checksum,
     size: bundleData.length,
-    hostApiVersion: "0.2.0",
+    hostApiVersion: HOST_API_VERSION,
     builtAt: new Date().toISOString()
   });
   console.log(source_default.green(`Built ${m.name} v${m.version}`));
@@ -9983,7 +10019,7 @@ async function dev() {
     writeWithBuild(distDir, raw, {
       checksum,
       size: bundleData.length,
-      hostApiVersion: "0.2.0",
+      hostApiVersion: HOST_API_VERSION,
       builtAt: new Date().toISOString()
     });
     console.log(source_default.green(`Built \u2192 dist/ (${(bundleData.length / 1024).toFixed(1)} KB)`));
@@ -10966,9 +11002,17 @@ function parseModelFile(content, fileName) {
     const [, op, level] = accessMatch;
     accessRules[op] = level;
   }
+  let scope;
+  const scopeMatch = content.match(/scope\s*:\s*['"](app|project|org)['"]/);
+  if (scopeMatch)
+    scope = scopeMatch[1];
   const result = { name: modelName, fields };
-  if (Object.keys(accessRules).length > 0) {
-    result.options = { access: accessRules };
+  if (Object.keys(accessRules).length > 0 || scope) {
+    result.options = {};
+    if (Object.keys(accessRules).length > 0)
+      result.options.access = accessRules;
+    if (scope)
+      result.options.scope = scope;
   }
   return result;
 }
@@ -11121,7 +11165,7 @@ function parseModelFields(content, fileName) {
 // package.json
 var package_default = {
   name: "@construct-space/cli",
-  version: "1.5.0",
+  version: "1.6.0",
   description: "Construct CLI \u2014 scaffold, build, develop, and publish spaces",
   type: "module",
   bin: {

package/dist/templates/space/actions.ts.tmpl

@@ -1,35 +1,26 @@
 /**
- * Space Actions — exposed to the AI agent via space_run_action
+ * Space Actions — exposed to the AI agent via space_run_action.
  *
- * Define actions here and they'll be automatically available as agent tools.
- * The agent calls: space_run_action(action: "action_id", payload: {...})
+ * Each action: { description, params, run }.
+ *  - `params` describe agent-callable inputs (type, description, required).
+ *  - `run` receives the payload and returns any JSON-serialisable value.
+ *
+ * Pair with @construct-space/graph for typed multi-tenant data:
+ *   import { useGraph } from '@construct-space/graph'
+ *   import { Item } from './models'
+ *   const items = useGraph(Item)
+ *
+ *   listItems: {
+ *     description: 'List items',
+ *     params: { limit: { type: 'number', required: false } },
+ *     run: async (p: any) => ({ items: await items.find({ limit: p.limit ?? 50 }) }),
+ *   }
  */
 
-// --- Graph SDK (data layer) ---
-// Uncomment after running `construct graph init` and defining models:
-//
-// import { useGraph } from '@construct-space/graph'
-// const graph = useGraph()
-//
-// Example action using Graph:
-// fetchItems: {
-//   description: 'Fetch items from the graph',
-//   params: {
-//     limit: { type: 'number', description: 'Max items to return', required: false },
-//   },
-//   run: async (p: any) => {
-//     const items = await graph.query('Item').limit(p.limit ?? 10).exec()
-//     return { items }
-//   },
-// },
-
 export const actions = {
-  // Example action:
-  // hello: {
-  //   description: 'Say hello',
-  //   params: {
-  //     name: { type: 'string', description: 'Name to greet', required: true },
-  //   },
-  //   run: (p: any) => ({ message: `Hello ${p.name}!` }),
-  // },
+  ping: {
+    description: 'Health check — returns pong with the space id.',
+    params: {},
+    run: () => ({ pong: true, space: '{{.ID}}' }),
+  },
 }

package/dist/templates/space/construct.md.tmpl

@@ -0,0 +1,238 @@
+---
+id: construct-stack
+name: Construct Stack Guide
+description: How to build and extend a Construct space — CLI, UI, SDK, Graph, manifest, agent actions
+trigger: construct|space|graph|ui|sdk|manifest|action
+category: skill
+tools: [read_file, list_dir, glob, grep, write_file, edit_file]
+---
+
+# Construct.md — agent guide for `{{.DisplayName}}`
+
+This file briefs an AI coding agent on the Construct stack so it can build, extend, and ship this space without external lookups.
+
+---
+
+## Stack at a glance
+
+| Layer | Package | Purpose |
+|-------|---------|---------|
+| UI | `@construct-space/ui` | Vue 3 component library |
+| Host | `@construct-space/sdk` | App composables (org, members, toast, auth) |
+| Data | `@construct-space/graph` | Multi-tenant typed data layer |
+| Icons | `lucide-vue-next` | Icon set |
+| Tooling | `@construct-space/cli` | Build / dev / publish |
+
+All four are **host-provided externals** — import normally, never bundle. Vite externalises them via `vite.config.ts`.
+
+---
+
+## Layout
+
+```
+{{.Name}}/
+  space.manifest.json     scope, pages, toolbar, agent, widgets, actions
+  src/
+    entry.ts              auto-generated; do not hand-edit
+    actions.ts            agent-callable actions (space_run_action)
+    pages/                filesystem routing (e.g. settings.vue → /settings)
+    components/           local Vue components
+    composables/          local composables (use* convention)
+    models/               graph models (defineModel)
+  agent/
+    config.md             agent system prompt, tool whitelist, max iterations
+    skills/               scoped skills loaded with the agent
+    hooks/safety.json     tool-call interception rules
+  widgets/                home-screen widgets (run inside Shadow DOM sandbox)
+```
+
+---
+
+## CLI
+
+```bash
+construct dev                  hot-reload dev (regenerates entry.ts on change)
+construct build                production build → dist/
+construct check                manifest + typecheck + lint
+construct install              install to active profile
+construct publish              publish to registry (requires auth)
+construct graph push           register models with graph backend
+construct graph install <id>   install a published space for current org
+```
+
+---
+
+## Manifest essentials
+
+```jsonc
+{
+  "id": "{{.ID}}",
+  "scope": "app | project | org",   // org = multi-tenant per organization
+  "minConstructVersion": "0.7.0",
+  "pages": [{ "path": "", "label": "Home", "default": true }],
+  "toolbar": [{ "id": "...", "icon": "...", "action": "createX" }],
+  "agent": "agent/config.md",
+  "skills": ["agent/skills/default.md"],
+  "actions": "src/actions.ts",
+  "widgets": [{ "id": "summary", "defaultSize": "4x1", "sizes": {...} }]
+}
+```
+
+`scope: 'org'` makes everything multi-tenant — graph schemas auto-partition per org. Use `useOrg()` to read current org context.
+
+---
+
+## `@construct-space/ui` — component cheatsheet
+
+All exported from the package root:
+
+**Layout**: `Card` (slots: header/accessory/default/footer/footer-end; variants: default/outline/muted; modifiers: hoverable/interactive), `SplitPane`, `ScrollArea`, `Separator`, `PanelSection`, `DashboardPanel`
+
+**Inputs**: `Input`, `Textarea`, `Select` (options: `{label, value}[]`), `MultiSelect`, `Checkbox`, `Switch`, `RadioGroup`, `DatePicker`, `ColorPicker`, `FileInput`, `Slider`, `Autocomplete`, `FormField` (label/hint wrapper)
+
+**Display**: `Badge` (color: primary|neutral|success|warning|error|info; variant: solid|soft|subtle|outline), `Chip`, `Avatar` (`fallback` shows text — pass initials), `Empty`, `Skeleton`, `Progress`, `Tooltip`, `Kbd`, `Alert`, `Notification`/`Toast`
+
+**Actions**: `Button` (variant: solid|ghost|outline; color: primary|neutral|error|...; size: xs|sm|md|lg), `Dropdown`, `DropdownMenu`, `ContextMenu`, `Popover`, `ToggleGroup` (segmented control)
+
+**Overlays**: `Modal` (`v-model:open`, slots: header/body/footer), `Slideover`, `Drawer`, `ConfirmationModal` (`@confirm`, `@cancel`), `Pagination`
+
+**Data**: `Table` (`columns: TableColumn[]`, `rows`, `selectable`, `striped`, `stickyHeader`, slots: `cell-{key}`, `header-{key}`, `empty`), `Tree`, `Timeline`, `Tabs`, `Tab`, `Accordion`, `Calendar`, `Breadcrumbs`
+
+**Composables**: `useNotification`, `notify`, `useAuth`, `useTheme`, `useClipboard`, `useMediaQuery`, `useFormValidation`, `useKeyboard`/`useHotkey`, `useClickOutside`, `useEscapeKey`, `useLocalStorage`, `useAsync`, `useDebounce`/`useThrottle`, `useToggle`, `useSearch`, `useIntersectionObserver`
+
+```vue
+<script setup lang="ts">
+import { Card, Button, Modal, Badge } from '@construct-space/ui'
+const open = ref(false)
+</script>
+<template>
+  <Card title="Hello" hoverable>
+    <Badge color="success" variant="subtle" label="Live" />
+    <template #footer-end>
+      <Button variant="solid" size="sm" @click="open = true">Open</Button>
+    </template>
+  </Card>
+  <Modal v-model:open="open" title="Demo">…</Modal>
+</template>
+```
+
+---
+
+## `@construct-space/sdk` — host composables
+
+```ts
+import { useOrg, useOrgMembers, useToast, useAuth } from '@construct-space/sdk'
+
+const { orgId, isOrg, org } = useOrg()           // current org context (reactive)
+const { members } = useOrgMembers()              // [{ user_id, name, email, role }, ...]
+const toast = useToast()                         // toast.success(...), toast.error(...)
+const { user, isAuthenticated, logout } = useAuth()
+```
+
+Use these for org-aware UX (assignee pickers, "shared with N" badges, avatars, member lookups).
+
+---
+
+## `@construct-space/graph` — data layer
+
+Define typed models, get a typed reactive client, multi-tenant by default.
+
+```ts
+// src/models/Task.ts
+import { defineModel, field, access } from '@construct-space/graph'
+
+export const Task = defineModel('task', {
+  title:       field.string().required(),
+  description: field.string(),
+  priority:    field.string(),
+  due_date:    field.date(),
+  position:    field.int(),
+  labels:      field.json(),
+  assignee_id: field.string().index(),
+}, {
+  scope: 'org',                          // partitions schema per organization
+  access: {
+    read:   access.authenticated(),
+    create: access.authenticated(),
+    update: access.authenticated(),
+    delete: access.owner(),
+  },
+})
+```
+
+```ts
+// src/composables/useTasks.ts
+import { useGraph } from '@construct-space/graph'
+import { Task } from '../models'
+
+const tasks = useGraph(Task)
+await tasks.find({ where: { priority: 'high' }, orderBy: { position: 'asc' }, limit: 50 })
+await tasks.create({ title: 'Ship', position: 0 })
+await tasks.update(id, { position: 1 })
+await tasks.remove(id)
+```
+
+**Field types**: `string`, `int`, `number`, `boolean`, `date`, `json`, `enum([...])`. Chain `.required()`, `.index()`, `.unique()`, `.default(v)`.
+
+**Access helpers**: `authenticated()`, `owner()`, `admin()`, `member()`. `member()` requires org context — use `authenticated()` for org-scoped models that allow any logged-in member.
+
+**Scopes**:
+- `app` — single shared schema (rare)
+- `org` — partitioned by organization (most product spaces)
+- `project` — partitioned by project (dev-tooling spaces)
+
+**Push models to backend after editing**: `construct graph push`.
+
+### Pitfalls
+
+- **`field.json()` columns** must receive a JSON-stringified value on write: `labels: JSON.stringify(arr)`. On read, parse back if it returns a string. Sending a JS array directly triggers `column is of type jsonb but expression is of type record`.
+- **Topological sort on push**: avoid `relation.belongsTo()` if push fails — use a `field.string()` foreign-key column instead and join manually in composables.
+- **Lazy provisioning**: first query for a new tenant auto-creates the schema; expect a one-time slower request.
+
+---
+
+## Actions (agent surface)
+
+`src/actions.ts` exports an `actions` object — each entry becomes an agent-callable tool via `space_run_action`.
+
+```ts
+export const actions = {
+  createTask: {
+    description: 'Create a task',
+    params: {
+      title: { type: 'string', required: true },
+      priority: { type: 'string', required: false },
+    },
+    run: async (p: any) => ({ task: await tasks.create(p) }),
+  },
+}
+```
+
+The agent (configured in `agent/config.md`) calls `space_list_actions` then `space_run_action`. Keep descriptions tight and specific — they're the only docstring the agent sees.
+
+---
+
+## Drag and drop (HTML5)
+
+Tauri intercepts native drag-drop by default. The Construct host sets `dragDropEnabled: false` so HTML5 events fire normally — use `draggable="true"`, `@dragstart`, `@dragover.prevent`, `@drop`. No extra deps required; reach for `vuedraggable` only if reordering needs auto-scroll/animation.
+
+---
+
+## Conventions
+
+- **Imports**: `@construct-space/*` packages always external. Local imports use relative paths (no `@/` alias unless you add one).
+- **Composables**: `use*` prefix, keep in `src/composables/`.
+- **Pages**: filename = route path. `index.vue` → `/`, `settings.vue` → `/settings`, `[id].vue` → param.
+- **Styling**: Tailwind utilities + CSS vars `--app-foreground`, `--app-background`, `--app-muted`, `--app-border`, `--app-accent`. Don't hard-code colors; the host themes via these variables.
+- **Comments**: explain *why*, not *what*. Skip TODOs in committed code.
+- **No emojis** in source unless the user requests them.
+
+---
+
+## Build pipeline reminder
+
+`construct build` writes:
+- `dist/space-{{.ID}}.iife.js` — the bundled space
+- `dist/manifest.json` — manifest + `build` block (checksum, size, **`hostApiVersion`**, builtAt)
+
+The runtime SpaceLoader compares `hostApiVersion` to its own; mismatches log a warning. Bump the CLI to keep them aligned.

package/dist/templates/space/eslint.config.js.tmpl

@@ -0,0 +1,26 @@
+import js from '@eslint/js'
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        console: 'readonly',
+        window: 'readonly',
+        document: 'readonly',
+        globalThis: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        history: 'readonly',
+      },
+    },
+    rules: {
+      'no-unused-vars': 'off',
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/', '*.d.ts'],
+  },
+]

package/dist/templates/space/index.vue.tmpl

@@ -2,19 +2,34 @@
 /**
  * {{.DisplayName}} — Home page
  *
- * Host-provided packages (vue, pinia, @vueuse/core, @construct/sdk, etc.)
- * are available as imports — they resolve to the host at runtime.
+ * Built-in libraries available at runtime (do not bundle):
+ *   @construct-space/ui     — Vue 3 components (Button, Card, Modal, Table, Badge, ...)
+ *   @construct-space/sdk    — useOrg, useOrgMembers, useToast, useAuth
+ *   @construct-space/graph  — defineModel, useGraph (multi-tenant data layer)
+ *   lucide-vue-next         — icons
  */
 import { ref } from 'vue'
+import { Button, Card, Empty } from '@construct-space/ui'
+import { Sparkles } from 'lucide-vue-next'
 
 const greeting = ref('Your space is ready. Start building!')
 </script>
 
 <template>
-  <div class="h-full flex items-center justify-center">
-    <div class="text-center">
-      <h1 class="text-2xl font-bold text-[var(--app-foreground)] mb-2">{{.DisplayName}}</h1>
-      <p class="text-sm text-[var(--app-muted)]">{{ greeting }}</p>
-    </div>
+  <div class="h-full flex items-center justify-center p-6">
+    <Card variant="default" class="max-w-md w-full text-center">
+      <template #header>
+        <div class="flex items-center justify-center gap-2 w-full">
+          <Sparkles class="size-5 text-[var(--app-accent)]" />
+          <h1 class="text-lg font-semibold text-[var(--app-foreground)]">{{.DisplayName}}</h1>
+        </div>
+      </template>
+
+      <Empty :description="greeting" size="sm" />
+
+      <template #footer-end>
+        <Button variant="solid" size="sm" label="Get Started" />
+      </template>
+    </Card>
   </div>
 </template>

package/dist/templates/space/package.json.tmpl

@@ -8,6 +8,7 @@
     "build": "construct build",
     "dev": "construct dev",
     "check": "construct check",
+    "lint": "eslint .",
     "validate": "construct validate"
   },
   "peerDependencies": {
@@ -18,10 +19,18 @@
   "devDependencies": {
     "@construct-space/cli": "latest",
     "@construct-space/sdk": "latest",
+    "@eslint/js": "^10.0.1",
     "@vitejs/plugin-vue": "^5.2.3",
+    "eslint": "^10.2.1",
+    "eslint-plugin-vue": "^10.0.0",
     "lucide-vue-next": "^1.0.0",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^9.0.0",
     "vite": "^6.3.5",
     "vue-tsc": "^3.2.5"
+  },
+  "dependencies": {
+    "@construct-space/graph": "^0.5.0",
+    "@construct-space/ui": "^0.5.2"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@construct-space/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Construct CLI — scaffold, build, develop, and publish spaces",
   "type": "module",
   "bin": {

package/templates/space/actions.ts.tmpl

@@ -1,35 +1,26 @@
 /**
- * Space Actions — exposed to the AI agent via space_run_action
+ * Space Actions — exposed to the AI agent via space_run_action.
  *
- * Define actions here and they'll be automatically available as agent tools.
- * The agent calls: space_run_action(action: "action_id", payload: {...})
+ * Each action: { description, params, run }.
+ *  - `params` describe agent-callable inputs (type, description, required).
+ *  - `run` receives the payload and returns any JSON-serialisable value.
+ *
+ * Pair with @construct-space/graph for typed multi-tenant data:
+ *   import { useGraph } from '@construct-space/graph'
+ *   import { Item } from './models'
+ *   const items = useGraph(Item)
+ *
+ *   listItems: {
+ *     description: 'List items',
+ *     params: { limit: { type: 'number', required: false } },
+ *     run: async (p: any) => ({ items: await items.find({ limit: p.limit ?? 50 }) }),
+ *   }
  */
 
-// --- Graph SDK (data layer) ---
-// Uncomment after running `construct graph init` and defining models:
-//
-// import { useGraph } from '@construct-space/graph'
-// const graph = useGraph()
-//
-// Example action using Graph:
-// fetchItems: {
-//   description: 'Fetch items from the graph',
-//   params: {
-//     limit: { type: 'number', description: 'Max items to return', required: false },
-//   },
-//   run: async (p: any) => {
-//     const items = await graph.query('Item').limit(p.limit ?? 10).exec()
-//     return { items }
-//   },
-// },
-
 export const actions = {
-  // Example action:
-  // hello: {
-  //   description: 'Say hello',
-  //   params: {
-  //     name: { type: 'string', description: 'Name to greet', required: true },
-  //   },
-  //   run: (p: any) => ({ message: `Hello ${p.name}!` }),
-  // },
+  ping: {
+    description: 'Health check — returns pong with the space id.',
+    params: {},
+    run: () => ({ pong: true, space: '{{.ID}}' }),
+  },
 }

package/templates/space/construct.md.tmpl

@@ -0,0 +1,238 @@
+---
+id: construct-stack
+name: Construct Stack Guide
+description: How to build and extend a Construct space — CLI, UI, SDK, Graph, manifest, agent actions
+trigger: construct|space|graph|ui|sdk|manifest|action
+category: skill
+tools: [read_file, list_dir, glob, grep, write_file, edit_file]
+---
+
+# Construct.md — agent guide for `{{.DisplayName}}`
+
+This file briefs an AI coding agent on the Construct stack so it can build, extend, and ship this space without external lookups.
+
+---
+
+## Stack at a glance
+
+| Layer | Package | Purpose |
+|-------|---------|---------|
+| UI | `@construct-space/ui` | Vue 3 component library |
+| Host | `@construct-space/sdk` | App composables (org, members, toast, auth) |
+| Data | `@construct-space/graph` | Multi-tenant typed data layer |
+| Icons | `lucide-vue-next` | Icon set |
+| Tooling | `@construct-space/cli` | Build / dev / publish |
+
+All four are **host-provided externals** — import normally, never bundle. Vite externalises them via `vite.config.ts`.
+
+---
+
+## Layout
+
+```
+{{.Name}}/
+  space.manifest.json     scope, pages, toolbar, agent, widgets, actions
+  src/
+    entry.ts              auto-generated; do not hand-edit
+    actions.ts            agent-callable actions (space_run_action)
+    pages/                filesystem routing (e.g. settings.vue → /settings)
+    components/           local Vue components
+    composables/          local composables (use* convention)
+    models/               graph models (defineModel)
+  agent/
+    config.md             agent system prompt, tool whitelist, max iterations
+    skills/               scoped skills loaded with the agent
+    hooks/safety.json     tool-call interception rules
+  widgets/                home-screen widgets (run inside Shadow DOM sandbox)
+```
+
+---
+
+## CLI
+
+```bash
+construct dev                  hot-reload dev (regenerates entry.ts on change)
+construct build                production build → dist/
+construct check                manifest + typecheck + lint
+construct install              install to active profile
+construct publish              publish to registry (requires auth)
+construct graph push           register models with graph backend
+construct graph install <id>   install a published space for current org
+```
+
+---
+
+## Manifest essentials
+
+```jsonc
+{
+  "id": "{{.ID}}",
+  "scope": "app | project | org",   // org = multi-tenant per organization
+  "minConstructVersion": "0.7.0",
+  "pages": [{ "path": "", "label": "Home", "default": true }],
+  "toolbar": [{ "id": "...", "icon": "...", "action": "createX" }],
+  "agent": "agent/config.md",
+  "skills": ["agent/skills/default.md"],
+  "actions": "src/actions.ts",
+  "widgets": [{ "id": "summary", "defaultSize": "4x1", "sizes": {...} }]
+}
+```
+
+`scope: 'org'` makes everything multi-tenant — graph schemas auto-partition per org. Use `useOrg()` to read current org context.
+
+---
+
+## `@construct-space/ui` — component cheatsheet
+
+All exported from the package root:
+
+**Layout**: `Card` (slots: header/accessory/default/footer/footer-end; variants: default/outline/muted; modifiers: hoverable/interactive), `SplitPane`, `ScrollArea`, `Separator`, `PanelSection`, `DashboardPanel`
+
+**Inputs**: `Input`, `Textarea`, `Select` (options: `{label, value}[]`), `MultiSelect`, `Checkbox`, `Switch`, `RadioGroup`, `DatePicker`, `ColorPicker`, `FileInput`, `Slider`, `Autocomplete`, `FormField` (label/hint wrapper)
+
+**Display**: `Badge` (color: primary|neutral|success|warning|error|info; variant: solid|soft|subtle|outline), `Chip`, `Avatar` (`fallback` shows text — pass initials), `Empty`, `Skeleton`, `Progress`, `Tooltip`, `Kbd`, `Alert`, `Notification`/`Toast`
+
+**Actions**: `Button` (variant: solid|ghost|outline; color: primary|neutral|error|...; size: xs|sm|md|lg), `Dropdown`, `DropdownMenu`, `ContextMenu`, `Popover`, `ToggleGroup` (segmented control)
+
+**Overlays**: `Modal` (`v-model:open`, slots: header/body/footer), `Slideover`, `Drawer`, `ConfirmationModal` (`@confirm`, `@cancel`), `Pagination`
+
+**Data**: `Table` (`columns: TableColumn[]`, `rows`, `selectable`, `striped`, `stickyHeader`, slots: `cell-{key}`, `header-{key}`, `empty`), `Tree`, `Timeline`, `Tabs`, `Tab`, `Accordion`, `Calendar`, `Breadcrumbs`
+
+**Composables**: `useNotification`, `notify`, `useAuth`, `useTheme`, `useClipboard`, `useMediaQuery`, `useFormValidation`, `useKeyboard`/`useHotkey`, `useClickOutside`, `useEscapeKey`, `useLocalStorage`, `useAsync`, `useDebounce`/`useThrottle`, `useToggle`, `useSearch`, `useIntersectionObserver`
+
+```vue
+<script setup lang="ts">
+import { Card, Button, Modal, Badge } from '@construct-space/ui'
+const open = ref(false)
+</script>
+<template>
+  <Card title="Hello" hoverable>
+    <Badge color="success" variant="subtle" label="Live" />
+    <template #footer-end>
+      <Button variant="solid" size="sm" @click="open = true">Open</Button>
+    </template>
+  </Card>
+  <Modal v-model:open="open" title="Demo">…</Modal>
+</template>
+```
+
+---
+
+## `@construct-space/sdk` — host composables
+
+```ts
+import { useOrg, useOrgMembers, useToast, useAuth } from '@construct-space/sdk'
+
+const { orgId, isOrg, org } = useOrg()           // current org context (reactive)
+const { members } = useOrgMembers()              // [{ user_id, name, email, role }, ...]
+const toast = useToast()                         // toast.success(...), toast.error(...)
+const { user, isAuthenticated, logout } = useAuth()
+```
+
+Use these for org-aware UX (assignee pickers, "shared with N" badges, avatars, member lookups).
+
+---
+
+## `@construct-space/graph` — data layer
+
+Define typed models, get a typed reactive client, multi-tenant by default.
+
+```ts
+// src/models/Task.ts
+import { defineModel, field, access } from '@construct-space/graph'
+
+export const Task = defineModel('task', {
+  title:       field.string().required(),
+  description: field.string(),
+  priority:    field.string(),
+  due_date:    field.date(),
+  position:    field.int(),
+  labels:      field.json(),
+  assignee_id: field.string().index(),
+}, {
+  scope: 'org',                          // partitions schema per organization
+  access: {
+    read:   access.authenticated(),
+    create: access.authenticated(),
+    update: access.authenticated(),
+    delete: access.owner(),
+  },
+})
+```
+
+```ts
+// src/composables/useTasks.ts
+import { useGraph } from '@construct-space/graph'
+import { Task } from '../models'
+
+const tasks = useGraph(Task)
+await tasks.find({ where: { priority: 'high' }, orderBy: { position: 'asc' }, limit: 50 })
+await tasks.create({ title: 'Ship', position: 0 })
+await tasks.update(id, { position: 1 })
+await tasks.remove(id)
+```
+
+**Field types**: `string`, `int`, `number`, `boolean`, `date`, `json`, `enum([...])`. Chain `.required()`, `.index()`, `.unique()`, `.default(v)`.
+
+**Access helpers**: `authenticated()`, `owner()`, `admin()`, `member()`. `member()` requires org context — use `authenticated()` for org-scoped models that allow any logged-in member.
+
+**Scopes**:
+- `app` — single shared schema (rare)
+- `org` — partitioned by organization (most product spaces)
+- `project` — partitioned by project (dev-tooling spaces)
+
+**Push models to backend after editing**: `construct graph push`.
+
+### Pitfalls
+
+- **`field.json()` columns** must receive a JSON-stringified value on write: `labels: JSON.stringify(arr)`. On read, parse back if it returns a string. Sending a JS array directly triggers `column is of type jsonb but expression is of type record`.
+- **Topological sort on push**: avoid `relation.belongsTo()` if push fails — use a `field.string()` foreign-key column instead and join manually in composables.
+- **Lazy provisioning**: first query for a new tenant auto-creates the schema; expect a one-time slower request.
+
+---
+
+## Actions (agent surface)
+
+`src/actions.ts` exports an `actions` object — each entry becomes an agent-callable tool via `space_run_action`.
+
+```ts
+export const actions = {
+  createTask: {
+    description: 'Create a task',
+    params: {
+      title: { type: 'string', required: true },
+      priority: { type: 'string', required: false },
+    },
+    run: async (p: any) => ({ task: await tasks.create(p) }),
+  },
+}
+```
+
+The agent (configured in `agent/config.md`) calls `space_list_actions` then `space_run_action`. Keep descriptions tight and specific — they're the only docstring the agent sees.
+
+---
+
+## Drag and drop (HTML5)
+
+Tauri intercepts native drag-drop by default. The Construct host sets `dragDropEnabled: false` so HTML5 events fire normally — use `draggable="true"`, `@dragstart`, `@dragover.prevent`, `@drop`. No extra deps required; reach for `vuedraggable` only if reordering needs auto-scroll/animation.
+
+---
+
+## Conventions
+
+- **Imports**: `@construct-space/*` packages always external. Local imports use relative paths (no `@/` alias unless you add one).
+- **Composables**: `use*` prefix, keep in `src/composables/`.
+- **Pages**: filename = route path. `index.vue` → `/`, `settings.vue` → `/settings`, `[id].vue` → param.
+- **Styling**: Tailwind utilities + CSS vars `--app-foreground`, `--app-background`, `--app-muted`, `--app-border`, `--app-accent`. Don't hard-code colors; the host themes via these variables.
+- **Comments**: explain *why*, not *what*. Skip TODOs in committed code.
+- **No emojis** in source unless the user requests them.
+
+---
+
+## Build pipeline reminder
+
+`construct build` writes:
+- `dist/space-{{.ID}}.iife.js` — the bundled space
+- `dist/manifest.json` — manifest + `build` block (checksum, size, **`hostApiVersion`**, builtAt)
+
+The runtime SpaceLoader compares `hostApiVersion` to its own; mismatches log a warning. Bump the CLI to keep them aligned.

package/templates/space/eslint.config.js.tmpl

@@ -0,0 +1,26 @@
+import js from '@eslint/js'
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        console: 'readonly',
+        window: 'readonly',
+        document: 'readonly',
+        globalThis: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        history: 'readonly',
+      },
+    },
+    rules: {
+      'no-unused-vars': 'off',
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/', '*.d.ts'],
+  },
+]

package/templates/space/index.vue.tmpl

@@ -2,19 +2,34 @@
 /**
  * {{.DisplayName}} — Home page
  *
- * Host-provided packages (vue, pinia, @vueuse/core, @construct/sdk, etc.)
- * are available as imports — they resolve to the host at runtime.
+ * Built-in libraries available at runtime (do not bundle):
+ *   @construct-space/ui     — Vue 3 components (Button, Card, Modal, Table, Badge, ...)
+ *   @construct-space/sdk    — useOrg, useOrgMembers, useToast, useAuth
+ *   @construct-space/graph  — defineModel, useGraph (multi-tenant data layer)
+ *   lucide-vue-next         — icons
  */
 import { ref } from 'vue'
+import { Button, Card, Empty } from '@construct-space/ui'
+import { Sparkles } from 'lucide-vue-next'
 
 const greeting = ref('Your space is ready. Start building!')
 </script>
 
 <template>
-  <div class="h-full flex items-center justify-center">
-    <div class="text-center">
-      <h1 class="text-2xl font-bold text-[var(--app-foreground)] mb-2">{{.DisplayName}}</h1>
-      <p class="text-sm text-[var(--app-muted)]">{{ greeting }}</p>
-    </div>
+  <div class="h-full flex items-center justify-center p-6">
+    <Card variant="default" class="max-w-md w-full text-center">
+      <template #header>
+        <div class="flex items-center justify-center gap-2 w-full">
+          <Sparkles class="size-5 text-[var(--app-accent)]" />
+          <h1 class="text-lg font-semibold text-[var(--app-foreground)]">{{.DisplayName}}</h1>
+        </div>
+      </template>
+
+      <Empty :description="greeting" size="sm" />
+
+      <template #footer-end>
+        <Button variant="solid" size="sm" label="Get Started" />
+      </template>
+    </Card>
   </div>
 </template>

package/templates/space/package.json.tmpl

@@ -8,6 +8,7 @@
     "build": "construct build",
     "dev": "construct dev",
     "check": "construct check",
+    "lint": "eslint .",
     "validate": "construct validate"
   },
   "peerDependencies": {
@@ -18,10 +19,18 @@
   "devDependencies": {
     "@construct-space/cli": "latest",
     "@construct-space/sdk": "latest",
+    "@eslint/js": "^10.0.1",
     "@vitejs/plugin-vue": "^5.2.3",
+    "eslint": "^10.2.1",
+    "eslint-plugin-vue": "^10.0.0",
     "lucide-vue-next": "^1.0.0",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^9.0.0",
     "vite": "^6.3.5",
     "vue-tsc": "^3.2.5"
+  },
+  "dependencies": {
+    "@construct-space/graph": "^0.5.0",
+    "@construct-space/ui": "^0.5.2"
   }
 }