@tangle-network/starter-foundry 0.5.4 → 0.7.0

package/registry/layers/framework/k12-edtech/files/gradebook.ts

@@ -0,0 +1,161 @@
+// Gradebook API. Every grade read writes a FERPA audit row BEFORE the grade
+// is returned. Grade writes are not destructive: amendments are new rows
+// that reference the prior grade via amendmentOfGradeId.
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { and, desc, eq } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import {
+  assignments,
+  gradeAccessLogs,
+  grades,
+  parentStudents,
+  submissions,
+} from '../db/schema.ts'
+
+interface Actor {
+  id: string
+  role: 'teacher' | 'admin' | 'parent' | 'student'
+}
+
+function resolveActor(request: IncomingMessage): Actor | null {
+  const id = request.headers['x-actor-id']
+  const role = request.headers['x-actor-role']
+  if (typeof id !== 'string' || typeof role !== 'string') return null
+  if (!['teacher', 'admin', 'parent', 'student'].includes(role)) return null
+  return { id, role: role as Actor['role'] }
+}
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  for await (const chunk of request) chunks.push(chunk as Buffer)
+  const raw = Buffer.concat(chunks).toString('utf8')
+  return raw ? JSON.parse(raw) : null
+}
+
+async function logGradeAccess(params: {
+  actor: Actor
+  studentId: string
+  assignmentId: string | null
+  reason: string | undefined
+  ipAddress: string | null
+}): Promise<void> {
+  await db.insert(gradeAccessLogs).values({
+    actorId: params.actor.id,
+    actorRole: params.actor.role,
+    studentId: params.studentId,
+    assignmentId: params.assignmentId ?? null,
+    reason: params.reason ?? null,
+    ipAddress: params.ipAddress,
+  })
+}
+
+/** Gate parent access to a student's grades via canAccessGrades AND custodial_rights. */
+async function parentCanAccess(parentId: string, studentId: string): Promise<boolean> {
+  const rows = await db
+    .select()
+    .from(parentStudents)
+    .where(and(eq(parentStudents.parentId, parentId), eq(parentStudents.studentId, studentId)))
+    .limit(1)
+  const link = rows[0]
+  return !!link && link.canAccessGrades && link.custodialRights
+}
+
+export async function gradeSubmission(
+  request: IncomingMessage,
+  response: ServerResponse,
+  submissionId: string,
+) {
+  const actor = resolveActor(request)
+  if (!actor || (actor.role !== 'teacher' && actor.role !== 'admin')) {
+    response.writeHead(403, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'only teachers or admins can grade' }))
+    return
+  }
+  const body = (await readJsonBody(request)) as {
+    pointsEarned?: number
+    letter?: 'A' | 'B' | 'C' | 'D' | 'F' | 'I' | 'P' | 'NP'
+    comment?: string
+    amendmentOfGradeId?: string
+  } | null
+  if (typeof body?.pointsEarned !== 'number') {
+    response.writeHead(422, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'pointsEarned required' }))
+    return
+  }
+  const [sub] = await db.select().from(submissions).where(eq(submissions.id, submissionId)).limit(1)
+  if (!sub) {
+    response.writeHead(404, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'submission not found' }))
+    return
+  }
+  const [row] = await db
+    .insert(grades)
+    .values({
+      submissionId,
+      pointsEarned: body.pointsEarned,
+      letter: body.letter ?? null,
+      gradedByTeacherId: actor.id,
+      comment: body.comment ?? null,
+      amendmentOfGradeId: body.amendmentOfGradeId ?? null,
+    })
+    .returning()
+  response.writeHead(201, { 'content-type': 'application/json' })
+  response.end(JSON.stringify(row))
+}
+
+export async function studentGrades(
+  request: IncomingMessage,
+  response: ServerResponse,
+  studentId: string,
+) {
+  const actor = resolveActor(request)
+  if (!actor) {
+    response.writeHead(401, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'unauthenticated' }))
+    return
+  }
+
+  if (actor.role === 'parent') {
+    const allowed = await parentCanAccess(actor.id, studentId)
+    if (!allowed) {
+      response.writeHead(403, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ error: 'parent lacks access to this student (canAccessGrades/custodialRights gate)' }))
+      return
+    }
+  } else if (actor.role === 'student' && actor.id !== studentId) {
+    // Students may only see their own grades.
+    response.writeHead(403, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'students can only view their own grades' }))
+    return
+  }
+
+  // FERPA audit entry BEFORE returning grades.
+  await logGradeAccess({
+    actor,
+    studentId,
+    assignmentId: null,
+    reason: (request.headers['x-access-reason'] as string | undefined) ?? undefined,
+    ipAddress: (request.socket.remoteAddress ?? '').slice(0, 45) || null,
+  })
+
+  const rows = await db
+    .select({
+      gradeId: grades.id,
+      submissionId: grades.submissionId,
+      pointsEarned: grades.pointsEarned,
+      letter: grades.letter,
+      gradedAt: grades.gradedAt,
+      comment: grades.comment,
+      assignmentId: assignments.id,
+      assignmentTitle: assignments.title,
+      totalPoints: assignments.totalPoints,
+    })
+    .from(grades)
+    .innerJoin(submissions, eq(grades.submissionId, submissions.id))
+    .innerJoin(assignments, eq(submissions.assignmentId, assignments.id))
+    .where(eq(submissions.studentId, studentId))
+    .orderBy(desc(grades.gradedAt))
+
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ studentId, grades: rows }))
+}

package/registry/layers/framework/k12-edtech/files/schema.ts

@@ -0,0 +1,171 @@
+// K-12 SIS / gradebook schema. FERPA-aligned: grade access is logged; parent
+// access to a child's grades is explicitly flagged (canAccessGrades).
+import { pgTable, uuid, varchar, timestamp, integer, text, boolean, jsonb, index, uniqueIndex, pgEnum } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+
+export const teacherRoleEnum = pgEnum('teacher_role', ['teacher', 'admin', 'counselor'])
+export const parentRelationshipEnum = pgEnum('parent_relationship', ['mother', 'father', 'guardian', 'other'])
+export const gradeLetterEnum = pgEnum('grade_letter', ['A', 'B', 'C', 'D', 'F', 'I', 'P', 'NP'])
+
+export const students = pgTable(
+  'students',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    districtStudentId: varchar('district_student_id', { length: 64 }).notNull(),
+    firstName: varchar('first_name', { length: 100 }).notNull(),
+    lastName: varchar('last_name', { length: 100 }).notNull(),
+    grade: integer('grade').notNull(), // K=0, 1-12
+    birthDate: timestamp('birth_date', { withTimezone: false }),
+    enrolledAt: timestamp('enrolled_at', { withTimezone: true }).notNull().defaultNow(),
+    sisExternalId: varchar('sis_external_id', { length: 128 }),
+  },
+  (t) => ({ districtUniq: uniqueIndex('students_district_uniq').on(t.districtStudentId) }),
+)
+
+export const teachers = pgTable(
+  'teachers',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    districtStaffId: varchar('district_staff_id', { length: 64 }).notNull(),
+    firstName: varchar('first_name', { length: 100 }).notNull(),
+    lastName: varchar('last_name', { length: 100 }).notNull(),
+    email: varchar('email', { length: 254 }).notNull(),
+    role: teacherRoleEnum('role').notNull().default('teacher'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({ emailUniq: uniqueIndex('teachers_email_uniq').on(t.email) }),
+)
+
+export const classes = pgTable(
+  'classes',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    code: varchar('code', { length: 32 }).notNull(),
+    title: varchar('title', { length: 200 }).notNull(),
+    subject: varchar('subject', { length: 64 }).notNull(), // Math, ELA, Science, etc.
+    academicYear: varchar('academic_year', { length: 9 }).notNull(), // "2025-2026"
+    term: varchar('term', { length: 16 }).notNull(), // "Fall", "Spring", "Q1"
+    teacherId: uuid('teacher_id').notNull().references(() => teachers.id, { onDelete: 'restrict' }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    codeYearUniq: uniqueIndex('classes_code_year_uniq').on(t.code, t.academicYear, t.term),
+  }),
+)
+
+export const enrollments = pgTable(
+  'enrollments',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    classId: uuid('class_id').notNull().references(() => classes.id, { onDelete: 'cascade' }),
+    studentId: uuid('student_id').notNull().references(() => students.id, { onDelete: 'restrict' }),
+    enrolledAt: timestamp('enrolled_at', { withTimezone: true }).notNull().defaultNow(),
+    droppedAt: timestamp('dropped_at', { withTimezone: true }),
+  },
+  (t) => ({
+    classStudentUniq: uniqueIndex('enrollments_class_student_uniq').on(t.classId, t.studentId),
+  }),
+)
+
+export const assignments = pgTable(
+  'assignments',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    classId: uuid('class_id').notNull().references(() => classes.id, { onDelete: 'cascade' }),
+    title: varchar('title', { length: 200 }).notNull(),
+    description: text('description'),
+    totalPoints: integer('total_points').notNull(),
+    dueAt: timestamp('due_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({ classIdx: index('assignments_class_idx').on(t.classId) }),
+)
+
+export const submissions = pgTable(
+  'submissions',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    assignmentId: uuid('assignment_id').notNull().references(() => assignments.id, { onDelete: 'cascade' }),
+    studentId: uuid('student_id').notNull().references(() => students.id, { onDelete: 'restrict' }),
+    submittedAt: timestamp('submitted_at', { withTimezone: true }).notNull().defaultNow(),
+    content: text('content'),
+    attachments: jsonb('attachments').$type<Array<{ uri: string; filename: string }>>().default([]),
+  },
+  (t) => ({
+    assignmentStudentUniq: uniqueIndex('submissions_assignment_student_uniq').on(t.assignmentId, t.studentId),
+  }),
+)
+
+export const grades = pgTable(
+  'grades',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    submissionId: uuid('submission_id').notNull().references(() => submissions.id, { onDelete: 'cascade' }),
+    pointsEarned: integer('points_earned').notNull(),
+    letter: gradeLetterEnum('letter'),
+    gradedByTeacherId: uuid('graded_by_teacher_id').notNull().references(() => teachers.id),
+    gradedAt: timestamp('graded_at', { withTimezone: true }).notNull().defaultNow(),
+    // Grade amendments are new rows referencing the prior row — never UPDATE an existing grade.
+    amendmentOfGradeId: uuid('amendment_of_grade_id'),
+    comment: text('comment'),
+  },
+  (t) => ({ submissionIdx: index('grades_submission_idx').on(t.submissionId) }),
+)
+
+export const parents = pgTable('parents', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  firstName: varchar('first_name', { length: 100 }).notNull(),
+  lastName: varchar('last_name', { length: 100 }).notNull(),
+  email: varchar('email', { length: 254 }).notNull(),
+  phone: varchar('phone', { length: 32 }),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+})
+
+export const parentStudents = pgTable(
+  'parent_students',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    parentId: uuid('parent_id').notNull().references(() => parents.id, { onDelete: 'cascade' }),
+    studentId: uuid('student_id').notNull().references(() => students.id, { onDelete: 'cascade' }),
+    relationship: parentRelationshipEnum('relationship').notNull(),
+    canAccessGrades: boolean('can_access_grades').notNull().default(true),
+    // Set to false when a court order restricts the parent's access (non-custodial).
+    custodialRights: boolean('custodial_rights').notNull().default(true),
+  },
+  (t) => ({
+    parentStudentUniq: uniqueIndex('parent_students_uniq').on(t.parentId, t.studentId),
+  }),
+)
+
+/** FERPA-aligned audit log: one row per grade/record disclosure. */
+export const gradeAccessLogs = pgTable('grade_access_logs', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  actorId: varchar('actor_id', { length: 128 }).notNull(),
+  actorRole: varchar('actor_role', { length: 32 }).notNull(), // 'teacher' | 'admin' | 'parent' | 'student'
+  studentId: uuid('student_id').notNull().references(() => students.id, { onDelete: 'restrict' }),
+  assignmentId: uuid('assignment_id').references(() => assignments.id, { onDelete: 'set null' }),
+  accessedAt: timestamp('accessed_at', { withTimezone: true }).notNull().defaultNow(),
+  reason: text('reason'),
+  ipAddress: varchar('ip_address', { length: 45 }),
+})
+
+export const classesRelations = relations(classes, ({ one, many }) => ({
+  teacher: one(teachers, { fields: [classes.teacherId], references: [teachers.id] }),
+  enrollments: many(enrollments),
+  assignments: many(assignments),
+}))
+
+export const studentsRelations = relations(students, ({ many }) => ({
+  enrollments: many(enrollments),
+  submissions: many(submissions),
+  parentLinks: many(parentStudents),
+}))
+
+export type Student = typeof students.$inferSelect
+export type Teacher = typeof teachers.$inferSelect
+export type Class = typeof classes.$inferSelect
+export type Assignment = typeof assignments.$inferSelect
+export type Submission = typeof submissions.$inferSelect
+export type Grade = typeof grades.$inferSelect
+export type Parent = typeof parents.$inferSelect
+export type ParentStudent = typeof parentStudents.$inferSelect

package/registry/layers/framework/k12-edtech/files/server.ts

@@ -0,0 +1,58 @@
+import http from 'node:http'
+import {
+  classRoster,
+  createAssignment,
+  createClass,
+  submitAssignment,
+} from './api/classroom.ts'
+import { gradeSubmission, studentGrades } from './api/gradebook.ts'
+
+const port = Number.parseInt(process.env.PORT ?? '{{port}}', 10)
+
+const server = http.createServer(async (request, response) => {
+  const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`)
+
+  if (url.pathname === '/health') {
+    response.writeHead(200, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ status: 'ok', service: '{{serviceName}}' }))
+    return
+  }
+
+  if (url.pathname === '/api/classes' && request.method === 'POST') {
+    await createClass(request, response)
+    return
+  }
+  const rosterMatch = /^\/api\/classes\/([^/]+)\/roster$/.exec(url.pathname)
+  if (rosterMatch && request.method === 'GET') {
+    await classRoster(request, response, rosterMatch[1] ?? '')
+    return
+  }
+  const assignMatch = /^\/api\/classes\/([^/]+)\/assignments$/.exec(url.pathname)
+  if (assignMatch && request.method === 'POST') {
+    await createAssignment(request, response, assignMatch[1] ?? '')
+    return
+  }
+  const submitMatch = /^\/api\/assignments\/([^/]+)\/submissions$/.exec(url.pathname)
+  if (submitMatch && request.method === 'POST') {
+    await submitAssignment(request, response, submitMatch[1] ?? '')
+    return
+  }
+  const gradeMatch = /^\/api\/submissions\/([^/]+)\/grade$/.exec(url.pathname)
+  if (gradeMatch && request.method === 'POST') {
+    await gradeSubmission(request, response, gradeMatch[1] ?? '')
+    return
+  }
+  const studentGradesMatch = /^\/api\/students\/([^/]+)\/grades$/.exec(url.pathname)
+  if (studentGradesMatch && request.method === 'GET') {
+    await studentGrades(request, response, studentGradesMatch[1] ?? '')
+    return
+  }
+
+  response.writeHead(404, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ error: 'not found' }))
+})
+
+server.listen(port, '0.0.0.0', () => {
+  // eslint-disable-next-line no-console
+  console.log(`{{serviceName}} listening on ${port}`)
+})

package/registry/layers/framework/k12-edtech/files/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/registry/layers/framework/k12-edtech/manifest.json

@@ -0,0 +1,105 @@
+{
+  "id": "k12-edtech",
+  "description": "K-12 edtech framework layer — SIS/gradebook schema (students, teachers, classes, assignments, submissions, grades, parent-student links), FERPA-aligned grade-read audit trail.",
+  "appliesTo": ["k12-edtech"],
+  "files": [
+    { "source": "files/README.md", "target": "README.md" },
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/drizzle.config.ts", "target": "drizzle.config.ts" },
+    { "source": "files/db.ts", "target": "src/db/client.ts" },
+    { "source": "files/schema.ts", "target": "src/db/schema.ts" },
+    { "source": "files/classroom.ts", "target": "src/api/classroom.ts" },
+    { "source": "files/gradebook.ts", "target": "src/api/gradebook.ts" },
+    { "source": "files/server.ts", "target": "src/server.ts" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "drizzle-orm": "^0.36.0",
+      "postgres": "^3.4.5"
+    },
+    "devDependencies": {
+      "drizzle-kit": "^0.30.0",
+      "typescript": "^5.9.0",
+      "@types/node": "^20.17.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "K-12 school software: gradebooks, student information systems (SIS), roster management, assignment submission portals, or any product that stores student education records and must comply with FERPA.",
+    "firstSteps": [
+      "Set DATABASE_URL to a Postgres connection string, then run `pnpm install && pnpm db:generate && pnpm db:migrate` to create all tables.",
+      "Start the server with `pnpm dev` — it listens on PORT (default 8103) and responds to GET /health immediately.",
+      "Seed a teacher row directly in Postgres, then POST /api/classes with the teacher's UUID as `teacherId`. All other routes flow from there.",
+      "Every call to GET /api/students/:id/grades writes a GradeAccessLog row before returning data — this is the FERPA audit trail. Do not remove or async-detach this write.",
+      "Run `pnpm validate` to verify the scaffold is wired correctly (checks schema tables, FERPA audit hook, /health route, valid package.json).",
+      "Run `npx tsc --noEmit` to typecheck — requires only `pnpm install` first, no build step needed."
+    ],
+    "apiRoutes": [
+      "GET /health",
+      "POST /api/classes (create class)",
+      "GET /api/classes/:id/roster",
+      "POST /api/classes/:id/assignments",
+      "POST /api/assignments/:id/submissions",
+      "POST /api/submissions/:id/grade (teacher grades a submission — audit-logged)",
+      "GET /api/students/:id/grades (audit-logged per FERPA)"
+    ],
+    "dataModels": [
+      "Student (districtStudentId, firstName, lastName, grade, enrolledAt, sisExternalId)",
+      "Teacher (districtStaffId, firstName, lastName, email, role: teacher|admin)",
+      "Class (code, title, subject, academicYear, term, teacherId)",
+      "Enrollment (classId, studentId, enrolledAt, droppedAt nullable)",
+      "Assignment (classId, title, description, totalPoints, dueAt)",
+      "Submission (assignmentId, studentId, submittedAt, content, attachments)",
+      "Grade (submissionId, pointsEarned, letter, gradedByTeacherId, gradedAt)",
+      "Parent (firstName, lastName, email, phone)",
+      "ParentStudent (parentId, studentId, relationship: mother|father|guardian, canAccessGrades)",
+      "GradeAccessLog (actorId, actorRole, studentId, assignmentId, accessedAt, reason)"
+    ],
+    "integrations": [
+      "Drizzle ORM with Postgres",
+      "SIS import adapter (OneRoster CSV / ClassLink / Clever — wire in src/sis/)"
+    ],
+    "placeholders": [
+      {
+        "path": "src/server.ts",
+        "description": "{{port}} is replaced with the family default (8103) at compose time; falls back to the PORT env var at runtime. {{serviceName}} is replaced with the project slug (default: starter-foundry-k12)."
+      }
+    ],
+    "architectureNotes": [
+      "FERPA-aligned: every read of a grade writes a GradeAccessLog row before returning the grade",
+      "Parent access to a child's grades is gated by ParentStudent.canAccessGrades AND custodial-rights flag (not shipped; add before production)",
+      "Enrollments are soft-delete via droppedAt — historical grade lookups need the student on the roster at the time of assignment"
+    ],
+    "gotchas": [
+      "FERPA: student education records are protected. Every disclosure needs either parent consent (<18) or student consent (18+ / post-secondary). This scaffold does NOT implement consent tracking — add before production.",
+      "Directory information vs. education records: directory info (name, grade level, enrollment dates) CAN be disclosed without consent IF parents haven't opted out. Check district's annual directory-info policy.",
+      "Parent access is NOT automatic. Divorced / separated parents may have restricted custody — check custodial_rights before exposing a child's grades to a parent account. Missing this is a district lawsuit.",
+      "COPPA (under 13): collecting PII from students under 13 requires verifiable parental consent. Student accounts for K-7 need the parent consent flow, not direct signup.",
+      "State-level laws (e.g. California SOPIPA, New York 2-d) add requirements beyond FERPA. Check state before storing biometric data, location data, or behavioral tracking.",
+      "Don't log student names or grades into stdout/APM/error-tracking by default — redact in the logging middleware. A Sentry screenshot of a grade is a FERPA violation.",
+      "Grades are immutable once final; amendments are new rows with an `amendment_of_grade_id` FK, not UPDATEs. Preserves audit trail.",
+      "SIS imports are destructive: when OneRoster CSVs arrive, reconciliation must be idempotent and MUST NOT delete students silently — orphan detection should alert, not drop."
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm dev",
+      "pnpm validate",
+      "npx tsc --noEmit",
+      "pnpm db:generate",
+      "pnpm db:migrate"
+    ],
+    "entrypoints": [
+      "src/server.ts",
+      "src/db/schema.ts",
+      "src/api/classroom.ts",
+      "src/api/gradebook.ts"
+    ],
+    "preview": { "path": "/health" },
+    "extensionPoints": [
+      "src/db/schema.ts",
+      "src/api/",
+      "src/sis/"
+    ]
+  }
+}

package/registry/layers/framework/kotlin-multiplatform/files/AGENTS.md

@@ -0,0 +1,67 @@
+# Kotlin Multiplatform Starter — Agent Guide
+
+## What this scaffold is
+
+One Kotlin codebase targeting Android and iOS with shared UI via Compose Multiplatform. The `shared/` module compiles to an Android library and a Kotlin/Native iOS framework; platform apps in `androidApp/` and `iosApp/` host it.
+
+## Project layout
+
+```
+shared/
+  src/
+    commonMain/kotlin/App.kt          ← shared @Composable root (start here)
+    androidMain/kotlin/Platform.android.kt   ← actual for Android
+    iosMain/kotlin/Platform.ios.kt           ← actual for iOS
+  build.gradle.kts                    ← KMP + Compose plugin config
+settings.gradle.kts                   ← declares :shared module
+build.gradle.kts                      ← root — plugins apply false
+gradle.properties                     ← JVM args, Kotlin flags
+validate-kmp.mjs                      ← structural validator (node)
+```
+
+## Key commands
+
+| Task | Command |
+|------|---------|
+| Build shared module | `bash gradlew :shared:build` |
+| Run iOS simulator tests | `bash gradlew :shared:iosSimulatorArm64Test` |
+| Install Android debug APK | `bash gradlew :androidApp:installDebug` |
+| Structural validation (no Gradle needed) | `node validate-kmp.mjs` |
+
+## Extending this scaffold
+
+### Add shared UI
+Create new `@Composable` functions in `shared/src/commonMain/kotlin/` and call them from `App()` in `App.kt`.
+
+### Add platform-specific behavior (expect/actual pattern)
+1. Declare `expect fun myFn(): ReturnType` in `commonMain`.
+2. Implement `actual fun myFn()` in `androidMain/kotlin/` using Android APIs.
+3. Implement `actual fun myFn()` in `iosMain/kotlin/` using platform.* Kotlin/Native APIs.
+4. Call `myFn()` from any composable in `commonMain`.
+
+### Add a dependency
+Gradle dependencies go in `shared/build.gradle.kts`:
+- Shared (all targets): in the `commonMain` source set.
+- Android-only: in the `androidMain` source set.
+- iOS-only: in the `iosMain` source set.
+
+## Package name
+
+All three Kotlin files declare `package com.example.starter`. When renaming, update:
+1. The `package` declaration in all three source files.
+2. `namespace` in `shared/build.gradle.kts`.
+3. `applicationId` in `androidApp/build.gradle.kts` (if present).
+
+## Placeholders that must be replaced
+
+| File | Token | What it becomes |
+|------|-------|-----------------|
+| `settings.gradle.kts` | `{{packageName}}` | kebab-case project slug (e.g. `my-app`) |
+| `shared/build.gradle.kts` | `{{packageName}}` | same slug; namespace becomes `com.starterfoundry.<slug>.shared` |
+| `App.kt` + actuals | `com.example.starter` | your reverse-domain package base |
+
+## What NOT to do
+
+- Do not mix Groovy `.gradle` and Kotlin `.gradle.kts` build files — it breaks IDE navigation.
+- Do not re-enable `kotlin.native.binary.memoryModel=strict` — incompatible with coroutines and Compose.
+- iOS targets require macOS + Xcode 15+; do not attempt iOS compilation on Linux/Windows CI.

package/registry/layers/framework/kotlin-multiplatform/files/App.kt

@@ -0,0 +1,46 @@
+package com.example.starter
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Button
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+
+/**
+ * Root Compose Multiplatform composable. Shared across Android + iOS + Desktop.
+ * Platform-specific wiring lives in `androidMain/`, `iosMain/`, `jvmMain/` —
+ * they provide `Platform.name` via expect/actual.
+ */
+@Composable
+fun App() {
+    MaterialTheme {
+        var count by remember { mutableStateOf(0) }
+        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+            Column(
+                verticalArrangement = Arrangement.spacedBy(16.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+                modifier = Modifier.padding(24.dp),
+            ) {
+                Text("Starter Foundry — Kotlin Multiplatform", style = MaterialTheme.typography.titleLarge)
+                Text("Running on ${platformName()}", style = MaterialTheme.typography.bodyMedium)
+                Button(onClick = { count++ }) {
+                    Text("Tapped $count times")
+                }
+            }
+        }
+    }
+}
+
+/** expect/actual — each platform supplies its own value. */
+expect fun platformName(): String

package/registry/layers/framework/kotlin-multiplatform/files/Platform.android.kt

@@ -0,0 +1,5 @@
+package com.example.starter
+
+import android.os.Build
+
+actual fun platformName(): String = "Android ${Build.VERSION.RELEASE} (SDK ${Build.VERSION.SDK_INT})"

package/registry/layers/framework/kotlin-multiplatform/files/Platform.ios.kt

@@ -0,0 +1,6 @@
+package com.example.starter
+
+import platform.UIKit.UIDevice
+
+actual fun platformName(): String =
+    "${UIDevice.currentDevice.systemName()} ${UIDevice.currentDevice.systemVersion}"

package/registry/layers/framework/kotlin-multiplatform/files/build.gradle.kts

@@ -0,0 +1,3 @@
+plugins {
+    kotlin("multiplatform") version "1.9.22" apply false
+}