create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/plans/02-pocketbase-setup.md

@@ -0,0 +1,1374 @@
+# PocketBase Setup
+
+> **For AI:** Complete all tasks in order. This sets up the entire backend with multitenancy, RBAC, and seed data.
+
+**Goal:** Install PocketBase, create all collections with API rules for multi-tenancy, implement migration system, and add seed data.
+
+**Architecture:** PocketBase as backend with proper API rules ensuring each organization's data is isolated. Collections: users, organizations, roles, permissions, user_roles, audit_logs, todos.
+
+**Tech Stack:** PocketBase v0.22+, JavaScript migrations, admin API for programmatic collection creation
+
+---
+
+## Task 1: Download and Setup PocketBase
+
+**Files:**
+- Create: `pocketbase/`
+- Download: PocketBase binary
+
+**Step 1: Create pocketbase directory and download binary**
+
+```bash
+# Create directory
+mkdir -p pocketbase
+cd pocketbase
+
+# Download PocketBase v0.22.0 for your platform
+# Linux (adjust URL for Mac/Windows if needed)
+wget https://github.com/pocketbase/pocketbase/releases/download/v0.22.0/pocketbase_0.22.0_linux_amd64.zip
+
+# Extract
+unzip pocketbase_0.22.0_linux_amd64.zip
+
+# Make executable
+chmod +x pocketbase
+
+# Verify
+./pocketbase --version
+```
+
+Expected: Output shows version 0.22.0
+
+**Step 2: Create .gitignore for pocketbase**
+
+Create `pocketbase/.gitignore`:
+
+```
+# Ignore data directory
+pb_data/
+
+# Ignore public uploads
+pb_public/
+
+# Keep binary and migrations
+!pocketbase
+!pb_migrations/
+```
+
+**Step 3: Create migrations directory**
+
+```bash
+mkdir -p pb_migrations
+```
+
+**Step 4: Commit**
+
+```bash
+git add pocketbase/
+git commit -m "chore: add PocketBase binary and migrations structure"
+```
+
+---
+
+## Task 2: Create Migration Types
+
+**Files:**
+- Create: `host/src/lib/pocketbase/types.ts`
+- Create: `host/src/lib/pocketbase/migrations.ts`
+
+**Step 1: Create PocketBase types**
+
+Create `host/src/lib/pocketbase/types.ts`:
+
+```typescript
+// PocketBase field types
+export interface BoolField {
+  name: string;
+  type: 'bool';
+  required?: boolean;
+  default?: boolean;
+}
+
+export interface NumberField {
+  name: string;
+  type: 'number';
+  required?: boolean;
+  min?: number;
+  max?: number;
+  default?: number;
+}
+
+export interface TextField {
+  name: string;
+  type: 'text';
+  required?: boolean;
+  min?: number;
+  max?: number;
+  default?: string;
+  pattern?: string;
+}
+
+export interface EmailField {
+  name: string;
+  type: 'email';
+  required?: boolean;
+}
+
+export interface UrlField {
+  name: string;
+  type: 'url';
+  required?: boolean;
+}
+
+export interface DateField {
+  name: string;
+  type: 'date';
+  required?: boolean;
+}
+
+export interface AutodateField {
+  name: string;
+  type: 'autodate';
+  required?: boolean;
+}
+
+export interface SelectField {
+  name: string;
+  type: 'select';
+  required?: boolean;
+  values: string[];
+  default?: string;
+}
+
+export interface JsonField {
+  name: string;
+  type: 'json';
+  required?: boolean;
+}
+
+export interface RelationField {
+  name: string;
+  type: 'relation';
+  required?: boolean;
+  maxSelect?: number;
+  collectionId: string;
+  cascadeDelete?: boolean;
+}
+
+export type Field = BoolField | NumberField | TextField | EmailField | UrlField | DateField | AutodateField | SelectField | JsonField | RelationField;
+
+// Collection definition
+export interface Collection {
+  type: 'base' | 'auth' | 'view';
+  name: string;
+  listRule?: string | null;
+  viewRule?: string | null;
+  createRule?: string | null;
+  updateRule?: string | null;
+  deleteRule?: string | null;
+  fields: Field[];
+  indexes?: string[];
+}
+
+// Migration function type
+export type Migration = () => Collection | Collection[];
+```
+
+**Step 2: Create migration utilities**
+
+Create `host/src/lib/pocketbase/migrations.ts`:
+
+```typescript
+import PocketBase from 'pocketbase';
+import type { Collection, Migration } from './types';
+
+export async function runMigrations(pb: PocketBase, migrations: Migration[]) {
+  console.log('[Migrations] Starting PocketBase migrations...');
+
+  for (const migration of migrations) {
+    const collections = Array.isArray(migration()) ? migration() : [migration()];
+
+    for (const collection of collections) {
+      await ensureCollection(pb, collection);
+    }
+  }
+
+  console.log('[Migrations] ✅ All migrations complete');
+}
+
+async function ensureCollection(pb: PocketBase, collection: Collection) {
+  const existing = await pb.collections.getList(1, 50, {
+    filter: `name = "${collection.name}"`,
+  });
+
+  if (existing.totalItems > 0) {
+    console.log(`[Migrations] ✓ Collection exists: ${collection.name}`);
+    return;
+  }
+
+  console.log(`[Migrations] → Creating collection: ${collection.name}`);
+
+  const result = await pb.collections.create({
+    type: collection.type,
+    name: collection.name,
+    listRule: collection.listRule,
+    viewRule: collection.viewRule,
+    createRule: collection.createRule,
+    updateRule: collection.updateRule,
+    deleteRule: collection.deleteRule,
+    fields: collection.fields,
+    indexes: collection.indexes,
+  });
+
+  console.log(`[Migrations]   ✅ Created: ${result.name} (${result.id})`);
+}
+```
+
+**Step 3: Commit**
+
+```bash
+git add host/src/lib/pocketbase/
+git commit -m "feat: add PocketBase migration utilities"
+```
+
+---
+
+## Task 3: Define All Collection Migrations
+
+**Files:**
+- Create: `host/src/lib/pocketbase/collections/index.ts`
+- Create: `host/src/lib/pocketbase/collections/users.ts`
+- Create: `host/src/lib/pocketbase/collections/organizations.ts`
+- Create: `host/src/lib/pocketbase/collections/roles.ts`
+- Create: `host/src/lib/pocketbase/collections/permissions.ts`
+- Create: `host/src/lib/pocketbase/collections/user_roles.ts`
+- Create: `host/src/lib/pocketbase/collections/audit_logs.ts`
+- Create: `host/src/lib/pocketbase/collections/todos.ts`
+
+**Step 1: Create collections index**
+
+Create `host/src/lib/pocketbase/collections/index.ts`:
+
+```typescript
+import { users } from './users';
+import { organizations } from './organizations';
+import { roles } from './roles';
+import { permissions } from './permissions';
+import { userRoles } from './user_roles';
+import { auditLogs } from './audit_logs';
+import { todos } from './todos';
+
+export const collections = [
+  users,
+  organizations,
+  roles,
+  permissions,
+  userRoles,
+  auditLogs,
+  todos,
+];
+```
+
+**Step 2: Create users collection**
+
+Create `host/src/lib/pocketbase/collections/users.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const users: Collection = {
+  type: 'auth',
+  name: 'users',
+  // Users can view their own profile
+  viewRule: 'id = @request.auth.id',
+  // Users can update their own profile
+  updateRule: 'id = @request.auth.id',
+  // No public list/create/delete - must be done by org admin
+  listRule: null,
+  createRule: null,
+  deleteRule: null,
+  fields: [
+    {
+      name: 'name',
+      type: 'text',
+      required: true,
+      min: 1,
+      max: 100,
+    },
+    {
+      name: 'avatar',
+      type: 'url',
+      required: false,
+    },
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'organizations',
+      cascadeDelete: false, // Don't delete user when org deleted
+    },
+    {
+      name: 'isActive',
+      type: 'bool',
+      required: true,
+      default: true,
+    },
+  ],
+  indexes: ['CREATE INDEX idx_users_org ON users (organizationId)'],
+};
+```
+
+**Step 3: Create organizations collection**
+
+Create `host/src/lib/pocketbase/collections/organizations.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const organizations: Collection = {
+  type: 'base',
+  name: 'organizations',
+  // Multi-tenancy: Users can only see their organization
+  listRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // Only org owners/admins can create/update/delete
+  createRule: '@request.auth.id != "" && @request.auth.roles.role.name = "Owner"',
+  updateRule: '@request.auth.id != "" && @request.auth.roles.role.name = "Owner"',
+  deleteRule: '@request.auth.id != "" && @request.auth.roles.role.name = "Owner"',
+  fields: [
+    {
+      name: 'name',
+      type: 'text',
+      required: true,
+      min: 1,
+      max: 100,
+    },
+    {
+      name: 'slug',
+      type: 'text',
+      required: true,
+      unique: true,
+      pattern: '^[a-z0-9-]+$',
+    },
+    {
+      name: 'logo',
+      type: 'url',
+      required: false,
+    },
+    {
+      name: 'ownerId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'users',
+      cascadeDelete: true,
+    },
+    {
+      name: 'settings',
+      type: 'json',
+      required: false,
+    },
+    {
+      name: 'maxUsers',
+      type: 'number',
+      required: true,
+      default: 10,
+      min: 1,
+    },
+  ],
+  indexes: [
+    'CREATE UNIQUE INDEX idx_organizations_slug ON organizations (slug)',
+    'CREATE INDEX idx_organizations_owner ON organizations (ownerId)',
+  ],
+};
+```
+
+**Step 4: Create roles collection**
+
+Create `host/src/lib/pocketbase/collections/roles.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const roles: Collection = {
+  type: 'base',
+  name: 'roles',
+  // Users can see roles in their organization
+  listRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // Only org owners/admins can manage roles
+  createRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  updateRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  deleteRule: '@request.auth.id != "" && @request.auth.roles.role.name = "Owner"',
+  fields: [
+    {
+      name: 'name',
+      type: 'text',
+      required: true,
+      min: 1,
+      max: 50,
+    },
+    {
+      name: 'slug',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'description',
+      type: 'text',
+      required: false,
+    },
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'organizations',
+      cascadeDelete: true,
+    },
+    {
+      name: 'isSystem',
+      type: 'bool',
+      required: true,
+      default: false, // System roles (Owner, Admin, Member, Guest) cannot be deleted
+    },
+  ],
+  indexes: [
+    'CREATE UNIQUE INDEX idx_roles_org_slug ON roles (organizationId, slug)',
+    'CREATE INDEX idx_roles_org ON roles (organizationId)',
+  ],
+};
+```
+
+**Step 5: Create permissions collection**
+
+Create `host/src/lib/pocketbase/collections/permissions.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const permissions: Collection = {
+  type: 'base',
+  name: 'permissions',
+  // Users can see permissions for their organization
+  listRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // Only org owners/admins can manage permissions
+  createRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  updateRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  deleteRule: '@request.auth.id != "" && @request.auth.roles.role.name = "Owner"',
+  fields: [
+    {
+      name: 'name',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'slug',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'description',
+      type: 'text',
+      required: false,
+    },
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'organizations',
+      cascadeDelete: true,
+    },
+    {
+      name: 'resource',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'action',
+      type: 'text',
+      required: true,
+    },
+  ],
+  indexes: [
+    'CREATE UNIQUE INDEX idx_permissions_org_slug ON permissions (organizationId, slug)',
+    'CREATE INDEX idx_permissions_resource_action ON permissions (resource, action)',
+  ],
+};
+```
+
+**Step 6: Create user_roles junction collection**
+
+Create `host/src/lib/pocketbase/collections/user_roles.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const userRoles: Collection = {
+  type: 'base',
+  name: 'user_roles',
+  // Users can see who has roles in their org
+  listRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // Only org owners/admins can assign roles
+  createRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  updateRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  deleteRule: '@request.auth.id != "" && (@request.auth.roles.role.name = "Owner" || @request.auth.roles.role.name = "Admin")',
+  fields: [
+    {
+      name: 'userId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'users',
+      cascadeDelete: true,
+    },
+    {
+      name: 'roleId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'roles',
+      cascadeDelete: true,
+    },
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'organizations',
+      cascadeDelete: false,
+    },
+    {
+      name: 'assignedBy',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'users',
+      cascadeDelete: true,
+    },
+  ],
+  indexes: [
+    'CREATE UNIQUE INDEX idx_user_roles_user_role ON user_roles (userId, roleId)',
+    'CREATE INDEX idx_user_roles_org ON user_roles (organizationId)',
+    'CREATE INDEX idx_user_roles_user ON user_roles (userId)',
+  ],
+};
+```
+
+**Step 7: Create audit_logs collection**
+
+Create `host/src/lib/pocketbase/collections/audit_logs.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const auditLogs: Collection = {
+  type: 'base',
+  name: 'audit_logs',
+  // Users can see audit logs for their organization
+  listRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // System creates audit logs, users cannot manually create
+  createRule: null,
+  updateRule: null,
+  deleteRule: null,
+  fields: [
+    {
+      name: 'action',
+      type: 'select',
+      required: true,
+      values: ['create', 'update', 'delete', 'login', 'logout', 'invite_user', 'remove_user', 'assign_role', 'revoke_role'],
+    },
+    {
+      name: 'entityType',
+      type: 'select',
+      required: true,
+      values: ['user', 'organization', 'role', 'permission', 'plugin'],
+    },
+    {
+      name: 'entityId',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'entityName',
+      type: 'text',
+      required: false,
+    },
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'organizations',
+      cascadeDelete: true,
+    },
+    {
+      name: 'userId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'users',
+      cascadeDelete: true,
+    },
+    {
+      name: 'ipAddress',
+      type: 'text',
+      required: false,
+    },
+    {
+      name: 'userAgent',
+      type: 'text',
+      required: false,
+    },
+    {
+      name: 'metadata',
+      type: 'json',
+      required: false,
+    },
+  ],
+  indexes: [
+    'CREATE INDEX idx_audit_logs_org ON audit_logs (organizationId)',
+    'CREATE INDEX idx_audit_logs_user ON audit_logs (userId)',
+    'CREATE INDEX idx_audit_logs_entity ON audit_logs (entityType, entityId)',
+    'CREATE INDEX idx_audit_logs_action ON audit_logs (action)',
+    'CREATE INDEX idx_audit_logs_created ON audit_logs (created DESC)',
+  ],
+};
+```
+
+**Step 8: Create todos collection**
+
+Create `host/src/lib/pocketbase/collections/todos.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const todos: Collection = {
+  type: 'base',
+  name: 'todos',
+  // Multi-tenancy: Users can only see todos in their organization
+  listRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  viewRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // Authenticated users can create todos
+  createRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations',
+  // Users can update their own todos
+  updateRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations && owner = @request.auth.id',
+  // Users can delete their own todos
+  deleteRule: '@request.auth.id != "" && organization = @request.auth.membership.organizations && owner = @request.auth.id',
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+      required: true,
+      min: 1,
+      max: 200,
+    },
+    {
+      name: 'description',
+      type: 'text',
+      required: false,
+    },
+    {
+      name: 'completed',
+      type: 'bool',
+      required: true,
+      default: false,
+    },
+    {
+      name: 'priority',
+      type: 'select',
+      required: true,
+      values: ['low', 'medium', 'high'],
+      default: 'medium',
+    },
+    {
+      name: 'dueDate',
+      type: 'date',
+      required: false,
+    },
+    {
+      name: 'owner',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'users',
+      cascadeDelete: true,
+    },
+    {
+      name: 'organizationId',
+      type: 'relation',
+      required: true,
+      maxSelect: 1,
+      collectionId: 'organizations',
+      cascadeDelete: true,
+    },
+  ],
+  indexes: [
+    'CREATE INDEX idx_todos_org ON todos (organizationId)',
+    'CREATE INDEX idx_todos_owner ON todos (owner)',
+    'CREATE INDEX idx_todos_completed ON todos (completed)',
+    'CREATE INDEX idx_todos_priority ON todos (priority)',
+  ],
+};
+```
+
+**Step 9: Commit**
+
+```bash
+git add host/src/lib/pocketbase/
+git commit -m "feat: add all PocketBase collection definitions with multi-tenancy API rules"
+```
+
+---
+
+## Task 4: Create Seed Data System
+
+**Files:**
+- Create: `host/src/lib/pocketbase/seed.ts`
+- Create: `host/src/lib/pocketbase/seed/roles.ts`
+- Create: `host/src/lib/pocketbase/seed/permissions.ts`
+
+**Step 1: Create seed roles**
+
+Create `host/src/lib/pocketbase/seed/roles.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+// System roles that exist for every organization
+export const systemRoles: Omit<Collection, 'type' | 'indexes'>[] = [
+  {
+    name: 'roles_owner',
+    slug: 'owner',
+    description: 'Full access to all resources',
+    isSystem: true,
+    fields: [] as any,
+  },
+  {
+    name: 'roles_admin',
+    slug: 'admin',
+    description: 'Can manage users, roles, and most settings',
+    isSystem: true,
+    fields: [] as any,
+  },
+  {
+    name: 'roles_member',
+    slug: 'member',
+    description: 'Standard user with basic access',
+    isSystem: true,
+    fields: [] as any,
+  },
+  {
+    name: 'roles_guest',
+    slug: 'guest',
+    description: 'Limited access, read-only',
+    isSystem: true,
+    fields: [] as any,
+  },
+];
+```
+
+**Step 2: Create seed permissions**
+
+Create `host/src/lib/pocketbase/seed/permissions.ts`:
+
+```typescript
+import type { Collection } from '../types';
+
+export const systemPermissions: Omit<Collection, 'type' | 'indexes'>[] = [
+  // User management
+  {
+    name: 'permissions_users_view',
+    slug: 'users.view',
+    description: 'View users in organization',
+    resource: 'users',
+    action: 'view',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_users_create',
+    slug: 'users.create',
+    description: 'Invite users to organization',
+    resource: 'users',
+    action: 'create',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_users_update',
+    slug: 'users.update',
+    description: 'Update user information',
+    resource: 'users',
+    action: 'update',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_users_delete',
+    slug: 'users.delete',
+    description: 'Remove users from organization',
+    resource: 'users',
+    action: 'delete',
+    fields: [] as any,
+  },
+
+  // Role management
+  {
+    name: 'permissions_roles_view',
+    slug: 'roles.view',
+    description: 'View roles in organization',
+    resource: 'roles',
+    action: 'view',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_roles_create',
+    slug: 'roles.create',
+    description: 'Create new roles',
+    resource: 'roles',
+    action: 'create',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_roles_update',
+    slug: 'roles.update',
+    description: 'Update roles',
+    resource: 'roles',
+    action: 'update',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_roles_delete',
+    slug: 'roles.delete',
+    description: 'Delete roles',
+    resource: 'roles',
+    action: 'delete',
+    fields: [] as any,
+  },
+
+  // Permission management
+  {
+    name: 'permissions_permissions_view',
+    slug: 'permissions.view',
+    description: 'View permissions',
+    resource: 'permissions',
+    action: 'view',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_permissions_create',
+    slug: 'permissions.create',
+    description: 'Create permissions',
+    resource: 'permissions',
+    action: 'create',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_permissions_delete',
+    slug: 'permissions.delete',
+    description: 'Delete permissions',
+    resource: 'permissions',
+    action: 'delete',
+    fields: [] as any,
+  },
+
+  // Organization management
+  {
+    name: 'permissions_org_update',
+    slug: 'org.update',
+    description: 'Update organization settings',
+    resource: 'organization',
+    action: 'update',
+    fields: [] as any,
+  },
+
+  // Audit logs
+  {
+    name: 'permissions_audit_view',
+    slug: 'audit.view',
+    description: 'View audit logs',
+    resource: 'audit_logs',
+    action: 'view',
+    fields: [] as any,
+  },
+
+  // Todo management
+  {
+    name: 'permissions_todos_view',
+    slug: 'todos.view',
+    description: 'View todos',
+    resource: 'todos',
+    action: 'view',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_todos_manage',
+    slug: 'todos.manage',
+    description: 'Manage all todos (create, update, delete any)',
+    resource: 'todos',
+    action: 'manage',
+    fields: [] as any,
+  },
+
+  // Plugin management
+  {
+    name: 'permissions_plugins_view',
+    slug: 'plugins.view',
+    description: 'View enabled plugins',
+    resource: 'plugins',
+    action: 'view',
+    fields: [] as any,
+  },
+  {
+    name: 'permissions_plugins_manage',
+    slug: 'plugins.manage',
+    description: 'Enable/disable plugins',
+    resource: 'plugins',
+    action: 'manage',
+    fields: [] as any,
+  },
+];
+```
+
+**Step 3: Create seed function**
+
+Create `host/src/lib/pocketbase/seed.ts`:
+
+```typescript
+import PocketBase from 'pocketbase';
+import { env } from '../../env/env.schema';
+import { systemRoles } from './seed/roles';
+import { systemPermissions } from './seed/permissions';
+
+interface SeedData {
+  adminEmail: string;
+  adminPassword: string;
+  adminName: string;
+  orgName: string;
+}
+
+export async function seedDatabase(pb: PocketBase, seedData: SeedData) {
+  console.log('[Seed] Starting database seeding...');
+
+  // Check if already seeded
+  const orgs = await pb.collections.getList(1, 1, {
+    filter: 'name = "organizations"',
+  });
+
+  if (orgs.totalItems > 0) {
+    const existingOrgs = await pb.records.getList('organizations', 1, 1);
+    if (existingOrgs.totalItems > 0) {
+      console.log('[Seed] ℹ Database already seeded, skipping...');
+      return;
+    }
+  }
+
+  console.log('[Seed] → Creating admin user...');
+
+  // Create admin user
+  const admin = await pb.users.create({
+    email: seedData.adminEmail,
+    password: seedData.adminPassword,
+    passwordConfirm: seedData.adminPassword,
+    name: seedData.adminName,
+  });
+
+  console.log('[Seed] → Creating organization...');
+
+  // Create organization
+  const organization = await pb.records.create('organizations', {
+    name: seedData.orgName,
+    slug: seedData.orgName.toLowerCase().replace(/\s+/g, '-'),
+    ownerId: admin.id,
+    maxUsers: 10,
+  });
+
+  // Update admin with organization
+  await pb.users.update(admin.id, {
+    organizationId: organization.id,
+  });
+
+  console.log('[Seed] → Creating system roles...');
+
+  // Create system roles
+  const roleMap = new Map<string, string>();
+
+  for (const roleData of systemRoles) {
+    const role = await pb.records.create('roles', {
+      name: roleData.name,
+      slug: roleData.slug,
+      description: roleData.description,
+      organizationId: organization.id,
+      isSystem: roleData.isSystem,
+    });
+    roleMap.set(roleData.slug, role.id);
+  }
+
+  console.log('[Seed] → Creating system permissions...');
+
+  // Create system permissions
+  for (const permData of systemPermissions) {
+    await pb.records.create('permissions', {
+      name: permData.name,
+      slug: permData.slug,
+      description: permData.description,
+      organizationId: organization.id,
+      resource: permData.resource,
+      action: permData.action,
+    });
+  }
+
+  console.log('[Seed] → Assigning Owner role to admin...');
+
+  // Assign Owner role to admin
+  await pb.records.create('user_roles', {
+    userId: admin.id,
+    roleId: roleMap.get('owner')!,
+    organizationId: organization.id,
+    assignedBy: admin.id,
+  });
+
+  console.log('[Seed] → Creating sample todos...');
+
+  // Create sample todos
+  await pb.records.create('todos', {
+    title: 'Welcome to Lego-One! 👋',
+    description: 'This is your first todo item. Try editing or completing it!',
+    completed: false,
+    priority: 'medium',
+    owner: admin.id,
+    organizationId: organization.id,
+  });
+
+  await pb.records.create('todos', {
+    title: 'Explore the Dashboard',
+    description: 'Check out the Dashboard plugin to see your stats and activity.',
+    completed: false,
+    priority: 'low',
+    owner: admin.id,
+    organizationId: organization.id,
+  });
+
+  await pb.records.create('todos', {
+    title: 'Manage your Organization',
+    description: 'Go to Settings to invite team members and configure roles.',
+    completed: false,
+    priority: 'high',
+    owner: admin.id,
+    organizationId: organization.id,
+  });
+
+  console.log('[Seed] ✅ Database seeded successfully!');
+  console.log('');
+  console.log('📧 Login credentials:');
+  console.log(`   Email: ${seedData.adminEmail}`);
+  console.log(`   Password: ${seedData.adminPassword}`);
+}
+```
+
+**Step 4: Commit**
+
+```bash
+git add host/src/lib/pocketbase/seed/
+git commit -m "feat: add database seeding system with roles, permissions, and sample data"
+```
+
+---
+
+## Task 5: Create PocketBase Client Initialization
+
+**Files:**
+- Create: `host/src/lib/pocketbase/client.ts`
+- Create: `host/src/lib/pocketbase/index.ts`
+
+**Step 1: Create PocketBase client**
+
+Create `host/src/lib/pocketbase/client.ts`:
+
+```typescript
+import PocketBase from 'pocketbase';
+import { env } from '../../env/env.schema';
+
+let pbInstance: PocketBase | null = null;
+
+export function getPocketBase(): PocketBase {
+  if (pbInstance) {
+    return pbInstance;
+  }
+
+  const pb = new PocketBase(env.VITE_POCKETBASE_URL);
+
+  // Auto-authenticate as admin for server-side operations
+  if (typeof window === 'undefined') {
+    pb.admins.authViaPassword(
+      env.VITE_POCKETBASE_ADMIN_EMAIL,
+      env.VITE_POCKETBASE_ADMIN_PASSWORD
+    ).catch((err) => {
+      console.error('Failed to authenticate with PocketBase:', err);
+    });
+  }
+
+  pbInstance = pb;
+  return pb;
+}
+
+export function getPocketBaseAdmin(): PocketBase {
+  const pb = new PocketBase(env.VITE_POCKETBASE_URL);
+
+  // This must be called with admin credentials
+  return pb;
+}
+
+// Reset singleton (useful for testing)
+export function resetPocketBase(): void {
+  pbInstance = null;
+}
+```
+
+**Step 2: Create barrel export**
+
+Create `host/src/lib/pocketbase/index.ts`:
+
+```typescript
+export * from './client';
+export * from './types';
+export * from './migrations';
+export * from './collections';
+export * from './seed';
+```
+
+**Step 3: Commit**
+
+```bash
+git add host/src/lib/pocketbase/
+git commit -m "feat: add PocketBase client initialization and exports"
+```
+
+---
+
+## Task 6: Create Startup Migration Hook
+
+**Files:**
+- Create: `host/src/kernel/use-migrations.ts`
+
+**Step 1: Create migration hook**
+
+Create `host/src/kernel/use-migrations.ts`:
+
+```typescript
+import { useEffect, useState } from 'react';
+import { getPocketBaseAdmin } from '@lib/pocketbase';
+import { runMigrations } from '@lib/pocketbase/migrations';
+import { collections } from '@lib/pocketbase/collections';
+import { seedDatabase } from '@lib/pocketbase/seed';
+import { env } from '@env/env.schema';
+
+interface MigrationState {
+  status: 'pending' | 'running' | 'success' | 'error';
+  message: string | null;
+}
+
+export function useMigrations() {
+  const [state, setState] = useState<MigrationState>({
+    status: 'pending',
+    message: null,
+  });
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function run() {
+      if (cancelled) return;
+
+      setState({ status: 'running', message: 'Running database migrations...' });
+
+      try {
+        const pb = getPocketBaseAdmin();
+
+        // Authenticate as admin
+        await pb.admins.authWithPassword(
+          env.VITE_POCKETBASE_ADMIN_EMAIL,
+          env.VITE_POCKETBASE_ADMIN_PASSWORD
+        );
+
+        if (cancelled) return;
+
+        // Run migrations
+        await runMigrations(pb, collections);
+
+        if (cancelled) return;
+
+        // Seed database (only if in development or explicitly requested)
+        if (env.VITE_SEED_ADMIN_EMAIL) {
+          setState({ status: 'running', message: 'Seeding database...' });
+
+          await seedDatabase(pb, {
+            adminEmail: env.VITE_SEED_ADMIN_EMAIL,
+            adminPassword: env.VITE_SEED_ADMIN_PASSWORD || 'admin123',
+            adminName: env.VITE_SEED_ADMIN_NAME || 'Super Admin',
+            orgName: env.VITE_SEED_ORG_NAME || 'Demo Organization',
+          });
+        }
+
+        if (cancelled) return;
+
+        setState({ status: 'success', message: 'Database ready!' });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        setState({ status: 'error', message });
+        console.error('[Migrations] Error:', error);
+      }
+    }
+
+    run();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return state;
+}
+```
+
+**Step 2: Commit**
+
+```bash
+git add host/src/kernel/use-migrations.ts
+git commit -m "feat: add database migration hook for startup"
+```
+
+---
+
+## Task 7: Create PocketBase Provider
+
+**Files:**
+- Create: `host/src/providers/PocketBaseProvider.tsx`
+
+**Step 1: Create PocketBase context provider**
+
+Create `host/src/providers/PocketBaseProvider.tsx`:
+
+```typescript
+import { createContext, useContext, ReactNode } from 'react';
+import { getPocketBase, resetPocketBase } from '@lib/pocketbase';
+import type { PocketBase } from 'pocketbase';
+
+const PocketBaseContext = createContext<PocketBase | null>(null);
+
+export function PocketBaseProvider({ children }: { children: ReactNode }) {
+  const pb = getPocketBase();
+
+  return (
+    <PocketBaseContext.Provider value={pb}>
+      {children}
+    </PocketBaseContext.Provider>
+  );
+}
+
+export function usePocketBase(): PocketBase {
+  const pb = useContext(PocketBaseContext);
+
+  if (!pb) {
+    throw new Error('usePocketBase must be used within PocketBaseProvider');
+  }
+
+  return pb;
+}
+
+export function usePocketBaseAdmin() {
+  return getPocketBaseAdmin();
+}
+
+// For testing
+export { resetPocketBase as resetPocketBaseForTesting };
+```
+
+**Step 2: Commit**
+
+```bash
+git add host/src/providers/
+git commit -m "feat: add PocketBase context provider"
+```
+
+---
+
+## Task 8: Create Initial saas.config.ts
+
+**Files:**
+- Create: `saas.config.ts`
+
+**Step 1: Create SaaS configuration**
+
+Create `saas.config.ts`:
+
+```typescript
+import { defineConfig } from '@lego/kernel/config';
+
+export default defineConfig({
+  plugins: [
+    {
+      name: '@lego/plugin-dashboard',
+      enabled: true,
+    },
+    {
+      name: '@lego/plugin-todo',
+      enabled: true,
+    },
+  ],
+});
+```
+
+**Step 2: Commit**
+
+```bash
+git add saas.config.ts
+git commit -m "chore: add initial SaaS plugin configuration"
+```
+
+---
+
+## Verification
+
+After completing all tasks:
+
+**Step 1: Verify file structure**
+
+Run:
+```bash
+ls -la host/src/lib/pocketbase/
+```
+
+Expected: `types.ts`, `migrations.ts`, `collections/index.ts`, `seed.ts`, `client.ts`, `seed/` folder
+
+**Step 2: Verify imports compile**
+
+Run:
+```bash
+cd host && pnpm install && pnpm typecheck
+```
+
+Expected: Will fail because workspace doesn't exist yet, but should not have TypeScript errors in created files.
+
+**Step 3: Verify migrations compile**
+
+No errors in TypeScript files created.
+
+---
+
+## Summary
+
+After completing this document, you have:
+
+✅ PocketBase downloaded and configured
+✅ All 7 collections defined (users, organizations, roles, permissions, user_roles, audit_logs, todos)
+✅ Multi-tenancy API rules on all collections
+✅ Migration system to create collections on startup
+✅ Seed data system with admin + org + roles + permissions + sample todos
+✅ PocketBase client with singleton pattern
+✅ PocketBase context provider for React
+
+**Next:** → [`03-host-kernel.md`](./03-host-kernel.md)