AI application blueprints

An application blueprint is the reviewable contract between a human request, an AI planner, generated source, and deployment resources.

The default file is clank.app.ts. It must export one data literal:

export default {
  name: "Orbit Tasks",
  description: "A live, authenticated task planner.",
  auth: {
    required: true,
    organizations: true,
    roles: {
      owner: {
        description: "Workspace administrator.",
        permissions: ["tasks.*", "members.*"],
      },
      member: {
        description: "Workspace member.",
        permissions: ["tasks.read", "tasks.write"],
      },
    },
  },
  entities: {
    tasks: {
      description: "Actionable work.",
      ownership: "workspace",
      realtime: true,
      displayField: "title",
      completionField: "done",
      fields: {
        title: { type: "string", min: 1, max: 200 },
        done: { type: "boolean", default: false },
      },
    },
  },
  routes: [
    { path: "/", view: "TaskList", entity: "tasks" },
  ],
  services: {
    reminders: {
      kind: "jobs",
      description: "Schedule durable reminders.",
      required: true,
    },
  },
  deployment: {
    database: "sqlite",
    scale: "single",
    isolation: "container",
  },
} satisfies import("@clank.run/framework/blueprint").AppBlueprintInput;

#Commands

clank explain
clank plan
clank plan --output .clank/reviewed-plan.json
clank generate .
clank generate ./new-app --blueprint ./clank.app.ts
clank generate ./new-app --blueprint ./clank.app.ts --framework=local

explain summarizes identity, data, routes, operations, services, and unresolved production requirements.

plan normalizes the contract and prints clank-plan/1, including every generated path, byte length, SHA-256 checksum, aggregate digest, and warning. Identical blueprints on the same Clank version produce identical plans.

generate writes the authenticated full-stack application, human and agent operating guides, and .clank/plan.json. It refuses to replace a changed file unless --force is supplied. The source blueprint is preserved when generating into its own directory. --framework=local makes a generated app install directly from the current Clank checkout without requiring a published registry version.

#Static safety

Clank does not import or execute clank.app.ts. A dedicated parser accepts an exported JSON-like literal with comments, trailing commas, and an optional satisfies or as const clause. Function calls, computed properties, template expressions, environment reads, imports with runtime behavior, and arbitrary statements are rejected.

This means an AI can prepare a TypeScript-assisted contract without gaining implicit local-code execution during review or generation. Generated application source is still code and must pass normal review, authorization, conformance, and deployment controls.

#Contract surface

A blueprint declares:

• entities, field constraints, ownership, indexes, display/completion semantics, and live behavior;
• relationships and deletion expectations;
• authentication, organizations, roles, and permissions;
• routes, views, access requirements, and user-visible actions;
• immutable SQL migrations;
• files, images, email, jobs, cron, search, and webhook service requirements; and
• database, scaling, isolation, health, region, custom-domain, and public environment requirements.

Generated applications currently include built-in authentication by construction. auth.required may be omitted or set to true; unauthenticated generation is rejected rather than silently producing a client/backend mismatch.

The generator creates a deterministic baseline, not domain truth. Payment, legal, medical, tax, retention, or other domain-specific behavior still needs explicit contracts and review.

See examples/blueprint-todo/clank.app.ts for a Todoist-style specification.